PR 2096 persistence oracle law review#

The executable baseline for this review is 8b3debb3a9d5c6ab6d4da15e5d9c597559bf32b6. The failing histories below were RED on that production revision or the first repair, and pass with the final repair reviewed here. Their primary owner is packages/db-sqlite-persistence-core/tests/persisted-oracle.test.ts; packages/db/tests/local-storage-peer-oracle.test.ts owns the LocalStorage constructor and host boundary. The claims below are bounded to controlled adapter and host histories; the open cells remain open.

Law structure and distinguishing histories#

A complete durable row replaces the value of a previously public persisted row, including field absence. An ordinary source partial update instead retains omitted fields. These are different kinds of evidence. A targeted tx:committed notice carries the source patch, not a complete durable row. Its receiver cannot treat that patch as either a complete row or a predicate decision. The independent model authors complete durable rows and selects keys by active demand, previously public keys after demand retirement, and protected DbClient hydration seeds. It does not call the wrapper's row comparator, predicate compiler, or notification classifier.

This distinction resolves a concrete tension: keeping omitted fields is required for a source patch, while keeping them after a complete durable read leaves stale public data. The same row shape appears under complete demand, retired-demand full-reload notice, retired-demand reset, and targeted notice. Each route has a separate production entry point and public snapshot checkpoint. The model preserves source partial-update semantics rather than changing the Collection's global update mode.

Eighteen exact-shape histories cross three complete-read routes with removal, removal with metadata, addition, removal/addition of an own undefined field, and scalar change. Nine removal cases fail at expectExactSnapshot on the baseline; nine neighboring controls pass. Callback-time snapshots, event values, public keys, row metadata, and the later settled public snapshot distinguish a coherent replacement from a delete followed by an observable partial state. The undefined cases are generic-adapter checks; SQLite's object encoding omits such fields.

The targeted histories use legal source patches and an authored durable relation. Six predicate-scope cases cross active title = Keep demand and retired demand with stay, enter, and leave transitions: five fail and the leaving-active control passes at exact public-row comparison. Nine hydration-seed cases cross active complete, active filtered, and retired demand with durable replacement, partial update, and deletion of a source-owned seed while an ordinary row changes; all nine fail. The filtered cases keep a hydrated title = Keep seed while its older durable row leaves that predicate. Six same-key operation-order cases cross active/retired demand with delete-then-update, update-then-delete, and two partial updates; three fail and three pass. The first two sequences have the same separated changedRows and deletedKeys arrays but opposite durable outcomes. The fixture verifies the adapter's durable result before delivering the notice. A receiver that merely changes loop order cannot satisfy both; it needs authoritative final-row evidence or an ordered protocol.

Two active-demand union controls keep a row that leaves title = Keep and enters title = Other, with both acquisition orders. Both pass on the baseline. Temporary first-only and last-only evaluator mutants each fail one control at the public snapshot comparison; each mutant changed only the subset-evaluator selection and was restored before further runs. A shortcut that handles only a complete second demand would also fail because both demands are constrained. These are assertion failures at expectExactSnapshot, not timeouts or setup failures.

An active filtered demand does not acquire authority over a previously public row outside its predicate. The maintainer explicitly chose to keep that row visible and refresh it from storage. Six mixed-demand histories first load and retire a broad demand, acquire title = Keep, then deliver a peer notice. The previously visible Other row is unchanged, updated, or deleted in durable storage while the Keep row changes. Targeted and full-reload routes must agree on public rows at the change callback and settled checkpoint. On the first repaired revision, three cases failed at expectExactSnapshot: targeted update deleted the Other row, while full reload deleted it even when durable storage retained it. The current implementation validates those outside-scope keys from a complete durable snapshot. The fixture applies an adapter transaction before emitting a matching term/sequence/version notice; the full-reload envelope omits delta fields, as the protocol requires.

Hydration-seed protection ends when an applied source transaction confirms its key. Ten histories cross source insert, update, and delete with later peer update, delete, or insert under targeted and full-reload notices. An ordinary sibling changes in every peer transaction, so a wrapper that protects the seed forever reaches the strict public-row comparison. A temporary targeted-path mutant that skipped the confirmed seed failed there with the stale source row; it did not time out. The fixture first checks the source receipt, public row, and durable row, then applies a separate versioned peer transaction and compares every callback snapshot with the authored final relation.

Four captured-read source histories and eighteen additional complete-demand source-precedence histories pass. They protect the distinct accepted-source obligation at settlement after a held persisted read. They do not assert acceptance before that read releases. A hostile comparison control rejects a missing key, a stale defined field, and a stale own-undefined field.

The one-owner law consumes an options descriptor only after successful Collection construction. Pre-bind invalid configuration, failed coordinator subscription during persisted sync startup, failed LocalStorage listener registration, and a post-acquisition missing loadSubset handler are distinct constructor cuts. The corrected descriptor must be reusable after each failure; a third construction must reject after success. A successful LocalStorage owner retains its claim after cleanup and can restart and persist. The baseline fails two persisted post-bind retry cases and four LocalStorage retry/resource cases. Four LocalStorage post-cleanup direct/spread histories pass. The late-failure host retains both a browser listener and an active same-tab refresh; a paired-host write makes three Storage reads after the failure versus two without it. Counts are captured inside the host's original getItem, after preload and before assertion reads.

Independent challenge and guide audit#

Independent oracle-review agents challenged the SQLite, ownership, and combined laws, then reviewed revisions prompted by their findings. They exposed missing post-cleanup admission, late listener acquisition, filtered-seed authority, two-constrained-demand union, source-confirmation exit, and mixed active/retired demand. A final reviewer found that the first mixed-demand and seed-exit fixtures fabricated a peer version and put delta fields on a full-reload envelope. Both now use real recording-adapter transactions and protocol-shaped notices. The reviewer then found that targeted mixed-demand changedRows omitted the ID carried by the actual mutation; the corrected envelope copies each committed patch verbatim, and all six histories and package TypeScript pass. The ownership reviewer found no further incorrect expectation in the bounded constructor histories. A proposed rule that would suppress metadata for an unseen targeted row was withdrawn: core explicitly permits row metadata for absent rows, so that demand-scoping change needs a separate product decision.

CI exposed one conflicting Electric recovery oracle assumption. Its generated publication history required zero subset reads after every targeted notice, including a new key whose patch has no completeness certificate. That work count was not a public-row law. The revised oracle retains its exact public/durable row and metadata-marker checks and permits a targeted read. For a full reload with active demand, it counts both adapter row-read routes and requires one authoritative durable read. Its fixture now omits delta fields from a full-reload envelope, matching the coordinator protocol. The 60 Electric recovery tests and all 681 Electric package tests pass after the initial correction. An independent reviewer then challenged the specific-subset-read assertion and the coverage map's accidental implication of real SQLite peer delivery; both are corrected in this follow-up.

ORC-001: the durable snapshot, source partial-update, hydration-seed, demand-scope, and one-owner contracts are stated beside their tests and in the coverage map. Their host and value limits are explicit. ORC-002: authored rows, Map selection, admission state, and paired-host relation do not import production semantic decisions. ORC-003: comments beside the model and each history name the law, driver, observation, and checkpoint. ORC-004 and ORC-007 do not apply to these bounded enumerations; existing generated campaigns are unchanged. ORC-005: the tests exercise public Collection construction, subset loads, coordinator delivery, Storage writes, public rows, events, and receipts; the REDs reach the named comparisons. ORC-006: the reviewed production revision supplies wrong-result controls, the exact-snapshot helper has explicit hostile outputs, and two temporary subset-selection mutants fail at the intended public comparison. ORC-008 does not apply to the stateless snapshot recomputation; the two admission states are distinguished by the corrected retry and third-construction histories. ORC-009: model durable rows, previously public keys, and protected hydration seeds map directly to the glossary's durable/public/source concepts; active demand and retired demand stay distinct. ORC-010: controlled histories use primary-failure-preserving cleanup; setup failures and timeouts are not counted as product RED. ORC-011: authored durable state versus actual adapter state, paired same-envelope/opposite-outcome order histories, and paired-host Storage work provide independent second formulations for the named shared-fault risks. ORC-012 is this exact-head record and the owner limits in the coverage map. ORC-013: removal versus addition/scalar controls, active versus retired demand, delete/update order reversal, filtered seed versus durable predicate, two constrained demand orders, failed versus successful construction, and pre/post-cleanup admission are neighboring distinguishing witnesses. ORC-014: the controlled adapter and host establish these premises only at their boundaries; real SQLite delta creation and browser/Electron delivery still require receiving witnesses.

Open cells#

The repaired implementation passes these controlled histories. Targeted delivery concurrent with an accepted same-key source transaction still needs an acceptance-order history in the persisted owner. Real SQLite mutation-delta construction and browser/Electron notification delivery need receiving witnesses in their existing adapter and host owners before the controlled targeted result can be generalized. Paginated mixed demand and a peer write between full and filtered reads also remain outside the new histories. A private closure or inert same-tab callback could retain a failed LocalStorage Collection without extra work; a lifecycle/GC witness remains outside this controlled host. The full-table read used for zero-demand visible-key validation still has no O(visible) work budget or keyed atomic adapter contract. These are tracked in docs/contributing/oracle-coverage.md.

The focused RED runs used direct repository Vitest binaries with existing dependencies. After the final fixture correction, the persistence oracle passed 842 tests with one existing todo, the LocalStorage peer oracle passed 55 tests, and the 11 persistence-core executable suites passed 1,085 tests with one todo. The full database runtime suite passed 11,749 tests across 242 files with Vitest's integrated typecheck disabled; standalone DB source/test and persistence-core TypeScript passed. The Electric recovery oracle passed 60 tests, and all 13 Electric package suites passed 681 tests. Standalone Electric TypeScript, both package builds, changed-file lint with zero errors, formatting, and whitespace checks passed. On an earlier revision, Vitest's integrated typecheck exited nonzero while trying to write a temporary build-info file through a dependency symlink outside the writable sandbox.