Issue 2046: source commits inside shared hydration scopes#

Current status: PR #2049 contains the committed production repair and strengthened oracles. See the latest receipt for current results and content hashes. The historical RED-stage ledger below is retained for provenance; its open verdicts and unchanged-production statements are not the PR's current status.

The initial entry below records the frozen 24-core/12-browser candidate. The follow-up loss audit supersedes its oracle enforcement claims and results. In particular, the original aggregate receipt check and browser cleanup capture were weaker than described here; the follow-up preserves those losses and strengthens the executable checks.

Historical scope and verdict: initial RED stage#

Issue 2046 reports one P1 persistence deadlock, expressed through nine claims below. The report is an issue, not a pull request. Checked source: 65992aacda530fde89f4c8ffa803b60cd708c425 (origin/main, fetched 2026-10-06). The worktree branch is codex/issue-2046-red-oracles.

The defect on the initial main baseline was confirmed through both the controlled persisted history owner and real Chromium OPFS. The requested deliverable at that stage was red reproductions. Production was unchanged; a temporary repair was calibrated and then restored byte-for-byte. No issue comment, PR, push, or release had been made at that stage.

Reviewer assessment#

The reporter accurately identified the default coordinator, the lost scoped adapter, both hydration entry points, the effect on a peer Collection, and two working controls. The report has high technical depth and signal, appropriate urgency, and a narrow implied repair: honor the supplied scoped adapter while retaining the registered adapter for ordinary commits. The calibration supports that repair within the tested bounds.

The release cutoff needs qualification. The repository changelogs list #1868 under core 0.3.0/browser 0.2.24, earlier than the report's core 0.4.0/browser 0.2.25 cutoff. This evaluation did not execute historical published packages, so it does not establish the earliest affected release or pre-0.4.0 success.

Finding ledger#

The task-local append-only ledger was created from the complete issue body before test edits. There were no issue comments. IDs preserve source order; related observations are not treated as additional independent product defects. All nine remain confirmed-open against unchanged production. For verified control claims, that disposition refers to the associated open defect; those controls need no behavior change.

Law coverage and enforcement#

Authority. PersistenceAdapter.runInHydrationScope requires nested work to use the supplied unscheduled adapter and forbids retaining it past the callback. PersistedCollectionCoordinator.requestApplyCommittedTx explicitly accepts that adapter. The persisted-history contract promises durable or observably failed source work. The applied-receipt and Collection-readiness contracts make unreported self-deadlock unacceptable. No new recovery or product policy is introduced.

Original gap. The primary persisted-oracle.test.ts recording adapter had no shared hydration scope by default. It could flush buffered commits without exposing coordinator reentry. shared-logical-scheduling-oracle.test.ts exercised core-adapter scopes directly, without a wrapped source commit through the default coordinator. The browser fairness grammar scheduled independent persists and cold hydrations, not a persist awaited inside its owning hydrate. Each separate test could be green while this composition was broken.

Primary owner. The appended hydration source durability routing matrix in packages/db-sqlite-persistence-core/tests/persisted-oracle.test.ts adds 24 bounded histories: phase {startup, subscription, after-ready} × adapter {scoped, unscheduled} × baseline {0,1} × source transaction count {1,2}. Both source transactions insert distinct keys. The independent snapshot rule is baseline plus source inserts; the independent routing rule forbids reacquisition of an already-owned hydration scope. The model does not simulate the production scheduler.

At the held-read cut, receipts remain pending and source inserts are absent from public rows. At the durability-admission cut, an event records any public-adapter call under the owning scope. That event competes against successful completion; the original fails an assertion, not a test timeout. On success, the oracle compares public rows, recording-adapter durable rows, ordered mutation-key batches, receipt completion, and Collection readiness. The fixture releases its diagnostic reentry gate in finally, allowing all work and Collection cleanup to settle without replacing the original failure.

Real-provider receiver. packages/browser-db-sqlite-persistence/e2e/hydration-commit-oracle.opfs.spec.ts and its directly named page driver run 12 histories: the same three phases × {default, BrowserCollectionCoordinator} × {empty, one stored row}. The driver uses createBrowserWASQLitePersistence, its real shared scheduler, actual BrowserWASQLiteDriver, and Chromium OPFSCoopSyncVFS workers. Startup commits inside sync(), matching the report. Subscription commits occur after a real row SELECT completes but before its result returns to hydration. All wrapped adapter calls forward to production unchanged. Source/peer readiness and receipt settlement are observed; successful histories also read durable rows. The subscription history awaits completion of the actual hydration scope, since a ready subscription status alone does not establish load settlement.

The original reaches a real scheduled applyCommittedTx while hydration awaits that call. The observation is frozen at that cycle, then the worker is closed. Playwright closes each isolated page/context even on assertion failure. Success also checks Collection cleanup and provider-close diagnostics. This is a causal finite cycle witness, not a claim of proving unbounded eventuality by waiting a chosen number of milliseconds.

Encoding/enforcement answers. The stated finite grammar is fully reachable and its routing, held-read, and successful-result obligations are asserted at the cuts above. Original main is the hostile subject: eight core routing assertions and four real OPFS cycle assertions reject it. The temporary narrow repair passes those same histories. No expected-failure marker, waiver, classifier, timeout acceptance, or skipped failing case was introduced. Successful durable-row checks prevent a coordinator from satisfying the law merely by returning without storing the insert.

Limits/open cells. This reproduces one scheduler/coordinator bug class; it does not close production repair. The bounded grammar does not establish update/delete/truncate, metadata-only commits, failures, abort/cleanup races, multiple scoped peers, distinct schema adapters, restarts, arbitrary payloads, or other browsers/hosts. The persisted-history owner retains those source and lifecycle dimensions as future witnesses; the OPFS owner retains the receiving host cases. Exact release attribution needs historical package execution. These limits are recorded in the coverage map, rather than erased by a green calibration. No general claim of class closure is made.

Calibration and exact verification#

Temporary change, not retained:

 public async requestApplyCommittedTx(
   collectionId: string,
   tx: PersistedTx,
+  scopedAdapter?: HydrationPersistenceAdapter,
 ): Promise<ApplyCommittedTxResponse> {
-  const adapter = this.collectionAdapters.get(collectionId)
+  const adapter = scopedAdapter ?? this.collectionAdapters.get(collectionId)

Runs used Node 24.19.0, Vitest 3.2.4, Vite 7.3.6, TypeScript 5.9.3, Playwright 1.60.0, Chrome 154.0.8037.98, and wa-sqlite 1.5.0. Full frozen installation failed on the configured registry and the public-registry fallback. Cached tools were reused; source aliases target this worktree's db, db-ivm, and persistence-core source, not another checkout's builds. The lockfile remains unchanged.

Historical session-only commands, from the worktree root, are retained below as execution provenance. They depend on untracked cache/temporary files and are not runnable from a fresh checkout. Use the fresh-checkout instructions for the current repository configurations.

node node_modules/vitest/vitest.mjs run --config node_modules/.cache/issue-2046/vitest.config.ts --reporter=dot
node node_modules/typescript/bin/tsc --noEmit -p packages/db-sqlite-persistence-core/tsconfig.json
node node_modules/typescript/bin/tsc --noEmit -p /private/tmp/issue-2046-audit/browser-types.json

From packages/browser-db-sqlite-persistence:

PATH="$PWD/../../node_modules/.bin:$PATH" node node_modules/@playwright/test/cli.js test --config playwright.opfs.config.ts hydration-commit-oracle.opfs.spec.ts --reporter=line --timeout=15000

The ordinary package test glob includes the appended core matrix; the existing Playwright OPFS configuration now registers the browser spec. The local source alias runner and append-only working ledger remain ignored/task-local. Raw source and logs were stored in the session-only, untracked directory /private/tmp/issue-2046-audit/. That path is not a repository prerequisite or a durable source for reproducing these checks.

Oracle guide audit#

Loss audit and remaining work#

Returned to the complete raw body, including its cause chain, condition list, example, table, release assertions, database-reset note, and workarounds. Nine items remain accounted for: 9 confirmed-open; 0 fixed-now; 0 stale; 0 refuted; 0 accepted-design; 0 deferred; 0 design-decision; 0 duplicate. There is one underlying P1 defect, not nine separate bugs. No permission to defer an in-scope repair was inferred: this request explicitly asks for red reproduction.

The evaluation/reproduction work is complete on unchanged main. Production repair is intentionally open. There is no blocking product-policy choice. The historical release cutoff is an evidence gap, not a refutation or a validated pre-0.4.0 compatibility claim. Worktree changes add tests, runner registration, and contract evidence only; production line delta is zero.

Weight: production +0/-0; tests, fixtures, and runner registration +522/-0; contract/review documentation +241/-0.