lib

Core libraries for Radroots
git clone https://radroots.dev/git/lib.git
Log | Files | Refs | README

README.md (13330B)


      1 # radroots_storage_indexeddb
      2 
      3 An explicit per-connection IndexedDB host for bounded opaque records. Namespace
      4 identity comes from a supplied source generation. Creating a namespace and
      5 opening an existing namespace are distinct operations; missing data never
      6 silently creates a replacement. Importing the package performs no host work.
      7 
      8 Atomic compare/exchange checks every original value and writes the complete
      9 batch in one real transaction. Dependent requests are issued from active
     10 IndexedDB callbacks. Success is returned only after `complete`; request success
     11 alone never acknowledges a commit. Accepted work remains owned after its
     12 observer is dropped. Closing stops admission and waits for accepted work.
     13 
     14 The default private host stores opaque bytes. The opt-in `workspace` feature
     15 adds `workspace::BrowserWorkspace`: authenticated protected local buyer and seller
     16 outboxes using the shared storage enrollment/grant rules and an explicitly
     17 selected nonvolatile provider. It creates only a fresh unrelated outbox;
     18 opening existing data requires its retained selection and protected proof.
     19 It implements the shared `OperationJournal` for these protected local outboxes.
     20 Participant custody, general storage SPI and stock authority remain
     21 separate.
     22 
     23 Initial public listings use the same shared command, plan, claim, obtained
     24 evidence, installation and delivery models. T0 atomically reserves the initial
     25 author/listing coordinate in an independently protected index. Reads verify its
     26 exact original decision, and later writes compare it inside the real transaction.
     27 A second initial publication cannot replace that decision. Private record bytes
     28 and positions stay unchanged; public issuance uses its own protection domain and
     29 target position, and public installation/work use distinct fixed 76-byte metadata.
     30 Direct public delivery retains the original signed event, policy, target ordinals
     31 and observations without a private recipient or temporary wrapping key.
     32 
     33 The workspace also executes immutable buyer operation admission and lookup.
     34 It retains the original command, transaction identity and first-issue window;
     35 an exact replay returns that preparation before acquiring entropy or applying
     36 a fresh command deadline. A different command under the same ID refuses.
     37 Preparation uses the shared native codec, split into at most four 16 KiB clear
     38 parts and an authenticated manifest. Each part binds its workspace, operation,
     39 position and full preparation digest. The grant comparison and all record slots
     40 commit atomically, with current access, writer and fresh deadline checks inside
     41 active callbacks. Unknown completion retains the original attempt and stops
     42 admission until exact reopening. Queries compare the complete witnessed operation record set;
     43 missing, orphaned or damaged parts never trigger replacement. These methods
     44 provide T0; they do not issue signatures, install messages or deliver them.
     45 
     46 The owner also binds and queries the original complete T1 signing plan, using
     47 the shared native v1 manifest codec. The 384 KiB plan uses at most twenty-four
     48 16 KiB clear parts. Every part binds the workspace, operation, position and
     49 plan digest. One real 31-record private transaction compares the grant, all five
     50 T0 slots and all twenty-five T1 slots. Public binding also compares the original
     51 coordinate, using the unchanged 32-record maximum. Fresh binding rechecks the original issue
     52 window after asynchronous protection; exact retained replay keeps the original
     53 transaction and observation without fresh entropy. Missing, orphaned, foreign
     54 or damaged state refuses, including T0 absence with retained plan records.
     55 Unknown completion retains the original attempt and stops admission. T1 stores
     56 complete captured signing data; participant issuance remains a separate phase.
     57 
     58 The v2 owner claims original per-recipient signing attempts and appends already
     59 obtained, verified signed seals. A retained claim authorizes no redispatch.
     60 Each claim binds its original preparation, plan, intent, recipient, deadline and
     61 transaction. Captured output retains its exact bytes and optional original
     62 observation in at most four 16 KiB parts plus an authenticated manifest. Actual
     63 signing happens outside storage. Capture requires retained proof and the actual
     64 original claim; expiry, revocation or an unavailable clock cannot discard already
     65 obtained output. Explicit capture-only opening permits this append and closure,
     66 and denies current authentication and fresh work. `capture_evidence` borrows
     67 the original proof and output; accepted work retains its bounded owned copy
     68 through caller cancellation. `obtained_evidence` reads original exact output.
     69 
     70 The owner installs an original logical chat once from actual obtained evidence,
     71 then appends distinct publication work for later obtained recipients. Exact
     72 replay preserves the message, basis and transaction before new entropy. The
     73 original first-issue deadline limits signing, while installation of already
     74 obtained bytes requires current grant/proof, lease and clock. Shared checked
     75 installation/publication models validate relationships; host-private v2 metadata
     76 is a closed 468-byte record under independent protection contexts. Bodies stay
     77 in the original command. `operation_snapshot` verifies the complete retained
     78 T0/T1/S/T2/D graph and reconstructs its original message through the shared model.
     79 All facts are witnessed and compared in the actual transaction before results
     80 are returned. Missing predecessors with retained descendants refuse false
     81 absence and new issuance.
     82 
     83 `prepare_delivery_attempt` retains exact obtained outer bytes and selected target
     84 intent before a potential transport invocation. It independently verifies the
     85 temporary wrapping key, distinct author, signature, original contained seal,
     86 actual publication work and captured signed relay routes. The complete original
     87 target set and publication policy remain fixed. Selected endpoints spend at most
     88 twelve contiguous invocation ordinals each. Retained attempts authorize no
     89 redispatch; a new explicit attempt can reuse original exact bytes without another
     90 participant signature. Replay preserves the original transaction and deadline.
     91 Fresh writes recheck current grant/proof, lease, monotonic time and the original
     92 delivery deadline after crypto, inside the actual transaction callback.
     93 
     94 A private frame contains at most 393,216 bytes in at most twenty-four 16 KiB
     95 parts, a 200-byte manifest and an independent 100-byte request index. Both rows
     96 must agree under separately expected contexts. At most twenty-six new records
     97 plus the existing six grant/preparation comparisons fit the 32-record atomic
     98 limit. The complete witnessed operation prefix fences every write. A coherent
     99 snapshot and `delivery_attempt` read original retained data without dispatch.
    100 Partial or missing predecessors, manifest, index and parts refuse replacement
    101 and false absence. Actual uncertain completion preserves the original operation,
    102 request and optional transaction anchor. Borrowed candidates remain caller-owned;
    103 accepted work retains its bounded copy through observer loss and cancelled close.
    104 `record_delivery_observation` appends an already obtained normalized target
    105 fact against the actual original attempt and retained proof. Each of six classes
    106 has one immutable first observation per selected target and attempt, including
    107 absent time and normalized details. Later classes append without erasing earlier
    108 facts. Relay acceptance does not imply recipient delivery. Expiry, revocation
    109 and an unavailable clock do not discard obtained evidence; capture-only opening
    110 allows retention while denying current queries and fresh work. Independent v2
    111 contexts bind the original work, request, outer representation, transaction,
    112 target and class. Each clear record is at most 16 KiB, with at most 2,304 reports
    113 per operation. Reports decode while the original attempt frame is available,
    114 without retaining every raw outer body. The complete prefix and original grant
    115 are compared in the actual retention transaction. Uncertain completion returns
    116 the original observation and stops admission. `delivery_observations` and coherent
    117 snapshots require current access and do not dispatch. Browser transport and the
    118 ordinary client remain separate phases.
    119 
    120 All shared journal ports delegate to this actual owner. Uncertainty stops
    121 ordinary admission while retaining the original namespace and writer lease.
    122 Already obtained original seals and target observations may reconcile under
    123 the retained proof. Recovery authenticates the actual grant before connection
    124 disposal, confirms closure, opens only the same existing namespace/schema and
    125 rechecks the current grant and actual original claim or attempt. Cached original
    126 grant authorization survives a failed reopen without retaining raw proof in the
    127 handle. Fresh connection-bound witnesses are acquired after reopening; no old
    128 witness or `RefCell` borrow crosses the asynchronous replacement boundary.
    129 
    130 Only confirmation matching the original uncertain capture identity clears
    131 admission. Confirming an unrelated older fact does not resolve another pending
    132 operation. General or multiple unrelated uncertainty requires explicit closure
    133 and reopening. Recovery grants no fresh command, grant, clock, signing, network
    134 or redispatch permission and never initializes, migrates or repairs a namespace.
    135 Accepted recovery stays owned through lost observation; final close drains it
    136 before releasing the writer.
    137 
    138 An owner-bound read snapshot witnesses at most 16,384 ordered opaque keys,
    139 lengths and SHA-256 digests, using a conservative 2 MiB scan reservation. Every
    140 decoded value must match its witness. The complete set is checked again in the
    141 same real transaction as bounded mutations, detecting insertion, deletion and
    142 replacement. Only synchronous bounded comparisons run in transaction callbacks;
    143 providers and signing stay outside. The 32-mutation and 4 MiB live-input limits
    144 remain unchanged. Exact-key cursor lookup distinguishes absent keys from foreign
    145 stored `undefined` values. Readwrite transactions request and check `strict`
    146 durability, which is a browser hint rather than a physical power-loss guarantee.
    147 Observed asynchronous request errors remain failures even if their default abort
    148 is prevented and the browser subsequently completes the transaction.
    149 
    150 The workspace holds an actual exclusive origin Web Lock. Unavailable or
    151 contended acquisition refuses; no in-memory substitute is selected. Accepted
    152 jobs remain Rust-owned and serial through cancelled observation. Closing stops
    153 admission, drains the jobs, closes IndexedDB, then observes actual lock release.
    154 Its workspace queue reserves a conservative 4 MiB for one accepted job,
    155 including a complete T1 plan and atomic comparisons. Grant-only setup remains
    156 separately bounded to eight jobs at 512 KiB each; close retains at most 32 weak
    157 observations.
    158 These limits cover owned inputs, not browser-internal or whole-process memory.
    159 Clear grants are bounded to 16 KiB and their protected representation to 32 KiB.
    160 
    161 `compare_exchange_checked` runs a trusted host's synchronous eligibility check
    162 in active write callbacks, after asynchronous crypto completes. Refusal aborts
    163 the whole transaction. The workspace uses it to recheck current expiry/clock
    164 and writer ownership before grant writes. Browser workspace v2 has its own
    165 namespace and independently expected grant context. Earlier namespaces are
    166 preserved and refused without migration or replacement. Native grant wire and
    167 context, shared private codecs and generic authenticated envelope v2 remain
    168 unchanged.
    169 No JavaScript object or key handle is exposed by the workspace API. The Web
    170 Lock follows the [standard holding and released promise lifecycle](https://www.w3.org/TR/web-locks/#locks).
    171 Browser storage can be evicted; opening an absent namespace reports its absence.
    172 No SQL global, memory fallback, network, implicit migration or automatic replay
    173 is used. The transaction behavior follows the
    174 [IndexedDB transaction lifecycle](https://w3c.github.io/IndexedDB/#transaction-lifecycle).
    175 
    176 The standalone fixture at `tests/browser/Cargo.toml` builds the real host to
    177 WASM. Generate its web bindings with the `wasm-bindgen` version matching that
    178 fixture's lockfile, using an external output directory and the output name
    179 `fixture`. Run `tests/browser/run.mjs` with an installed Playwright package
    180 directory, that output directory, `chromium`, `firefox`, or `webkit`, and the
    181 preserved v1 fixture package directory for actual cross-version refusal checks.
    182 The optional final argument selects `delivery`, `delivery_limits`,
    183 `delivery_corruption`, `delivery_faults`, `observations`, `observation_faults`,
    184 `observation_corruption`, `journal`, `journal_observations`, or `journal_reopen`;
    185 omission runs the existing base
    186 regressions. Additional profiles preserve that base's bounded deadline.
    187 Synthetic normalized observation inputs prove concrete storage and linkage
    188 behavior; they do not establish remote relay execution or acceptance.
    189 Both the page and dedicated worker import those generated bytes. The runner
    190 uses isolated loopback origins and bounds each expanded run to 180 seconds.
    191 This harness ceiling is not a product deadline or performance acceptance. Route
    192 builds, generation and runner execution through `cargo extbuild run --`.