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 --`.