LocalStorage oracle follow-up review, 2026-10-08#

Reviewed PR #2074 at 347e28207815e4a64a7a495e07e6b45bc2c97f12. This record reconciles four independent oracle reviews: receipt ownership, peer synchronization, queue liveness, and parser recovery. The append-only intake with the original claims and execution notes is /private/tmp/pr2074-final-review-ledger.md in the review workspace.

Reviewer assessment#

The reviewers found eight actionable product or oracle defects and separated three approved limits from defects. Their strongest observations used public persistence receipts, method-return cuts, fresh restore, and a deliberately hostile transaction-work mutant. The reports identified the missing history dimension or assertion for each confirmed bug. One proposed custom Storage return-value concern was correctly rejected because StorageApi.getItem returns string | null. The default-JSON Date observation was real, but its suggested normalization would change an established writer contract. Overall: high technical accuracy, high analytical depth, strong signal-to-noise and prioritization, and mostly precise repairs. Hire recommendation: yes.

Lossless finding ledger#

No item is deferred, and no design decision remains open. The original twelve items equal eight fixed, three accepted designs and one refutation.

Laws, gaps and enforcement#

Manual receipt and owner law (R1, R5). The guide requires acceptMutations() called inside mutationFn to join the actual Collection's ordered write queue, and persistence receipts to wait for the durable write. The order oracle previously omitted direct-owner lifecycle states and invoked acceptance outside mutationFn. Its independent authored-row fold now reaches idle, ready and cleaned-up direct owners with a DbClient materialization. The driver compares durable bytes, active Collection rows and fresh restore after the manual receipt. A separate held-predecessor cut observes the receipt after work registration; disabling registerTransactionCommitWork makes that exact assertion fail (fulfilled instead of pending). The original production fails the ready and cleaned-up histories with empty durable Storage. These assertions enforce the law for single-owner acceptance through the tested direct and materialized paths. Multi-owner acceptance in one utility call is outside this grammar; the API rejects mixing recognized owners.

Peer agreement law (R2, R3). The guide promises that active Collections sharing one Storage object and key see an accepted same-tab write without a browser event. The peer oracle's independent authored-row fold does not use the adapter mirror. It now admits a peer write from nonempty restore publication, then checks readiness, nested receipt, a later update, durable bytes and both public snapshots. It also normalizes an authored row using a custom parser while holding the version token fixed; insert and update receipts compare writer, peer, durable and fresh restore. The original code fails the receiver and writer comparisons respectively; the repaired code passes. Default JSON rich values are an explicit exception: the writer retains the authored native value until restore, and the Date witness checks that limit. The finite histories do not prove arbitrary subscriber reentry or simultaneous cross-tab writes.

Direct-write and valid-snapshot laws (R4, R6–R8). The guide promises a handler-free write before method return when no earlier write can still use Storage. The order oracle now places a synchronous failed handler immediately before a handler-free insert and compares durable bytes at the return cut; the old queue fails that assertion and the repair passes. The neighboring settled cut and ordinary no-predecessor cases protect the conditional premise. For restore and event delivery, only a valid whole snapshot can advance the mirror or readiness. The peer oracle's absent/valid/malformed classifier now includes null data, null token and key/row disagreement, while the driver checks startup error, intact bytes, zero sync begin, invalid-event retention and same-token repair. The old implementation accepts or advances these malformed cases; the repair passes. This is shape and identity validation, not arbitrary application-schema validation. Invalid writer key extractors and direct raw same-tab edits remain outside this adapter's guarantees.

RED and GREEN evidence#

Oracle changes preceded production changes. On the original production, the expanded order and peer owners ran 83 tests: 73 passed and nine intended new comparisons failed. One additional default-Storage setup error came from running the root Vitest invocation without the package's jsdom environment; it is not counted as a product failure. The failing checkpoints were the ready/cleaned manual durable receipts, restore-time peer receipt, parser- normalized writer receipt, direct-write method return, malformed key and token startup cases, invalid-event repair and null-row startup begin count. The R5 hostile mutant was removed after it failed the repaired held-receipt comparison; transaction-commit-work.ts has no diff.

With production repaired, the package-configured LocalStorage run passed four files and 142 tests with no type errors. This includes the existing CRUD and persistence-failure tests, plus the two primary oracles. Full-suite and build results are separate from the RED evidence above. The full package runtime suite passed 270 files and 11,665 tests. Standalone TypeScript checks for both the package and test project, package build, changed-file lint, formatting, generated error docs, and ESM/CommonJS production error checks passed. Vitest's integrated type-check phase still reports an overload diagnostic in unchanged src/collection/index.ts:961 and exits nonzero. Its type-check-only path reports the same diagnostic in a clean pre-fix review copy, while both standalone TypeScript checks pass. This is an existing tool discrepancy, not a green integrated gate. The docs link checker reports nine existing links that point outside /docs; this record adds none.