Oracle coverage and closeout#

Use Writing reliable oracle tests when adding or reviewing a law. This map identifies existing owners, their judgment, and their limits. It is not a claim that every state or every test has been audited.

The project glossary owns terms shared by these executable models and their production subsystems. A coverage owner may define narrower local terms, but it must not silently rename a production concept.

Scope of the oracle repair project#

Issue #1808 commissioned a bounded portfolio audit and repair. The September 11 inventory contained 329 tracked paths: 132 selected/support entries and 197 discovery-tier files. The latter received routing recommendations, not 197 full semantic reviews. Focused examples, type tests, and host-wiring tests remain useful; converting them all to generated tests is not a completion criterion.

Literate model audit#

The literate-model pass audits every primary executable owner in Find an owner and every repository file explicitly named oracle or property. Derive that strict inventory from the repository rather than copying a count into this document:

git ls-files -co --exclude-standard packages \
  | rg '/[^/]*(oracle|property)[^/]*$' \
  | sort -u

The command includes tracked and untracked package files so an in-progress audit cannot hide a new owner. A surface is complete only when each primary owner does one of these things:

• states its contract, model, history grammar, production path, and observations in the executable file, or
• records why that structure would add no useful information to a focused test.

The pass must not change product behavior. If clearer prose exposes a missing model rule or assertion, strengthen the oracle and run it against unchanged production first. Track any production failure as separate follow-up work.

The same pass audits vocabulary. Shared concepts use the production names in the project glossary. The audit corrected model prose that collapsed a physical acquisition into a request or called an acquisition lease merely a lease. Model-only terms such as an appointment ledger or fault tape remain local and say what production facts they abstract. This is a semantic review, not a rule that test identifiers must copy production's private data structures.

Recent fix-wave authority inventory#

This inventory records the permanent authority for the September 17 fix wave. It distinguishes an executable oracle from a specialized real-provider authority and does not award oracle credit for a filename alone.

PR #1816 preserves existing witnesses, repairs false-green assertions and drivers, adds missing histories, and includes narrow runtime fixes reproduced by the stronger tests. The later ten-area audit found 59 actionable findings or optional suggestions: 46 repaired, one partly repaired storage item, nine contract decisions, and three deferred suggestions. These are not counts of production bugs. The earlier 13-item review is a separate ledger, not another 13 unique defects.

Find an owner#

Paths below are relative to the repository root. Follow each suite's domain comment and the current API/architecture contract before extending its model.

Acceptance map#

The post-merge review added three missing domains to existing owners:

• Top-K batch contracts cross sparse-array length/holes and RegExp source/flags/position with equal controls, replacement order, hash consolidation, and actual retained graph output. Ordinary replacements also run without the global File constructor.
• Leadership replay holds real storage-read delivery across successful and permanently rejected durable removals, with bounded scans, concurrent loads, and unfinished peers. This is distinct from exactly-once execution across independent owners.
• Accepted-snapshot retention varies truncate before/during/after an optimistic delete, rejection versus rollback, post-capture direct insertion, and later ordinary sync/key reuse. A hidden accepted insert returns after rollback; an uncaptured insert retires, and neither snapshot is rebased onto synced fields.

Running and replaying#

Build workspace dependencies before testing consumers of package exports. Use the package's checked-in config; source aliases and native shims must be named when they replace that path.

pnpm --filter @tanstack/db-ivm build
pnpm --filter @tanstack/db build
pnpm --filter @tanstack/db test:oracles
pnpm --filter @tanstack/powersync-db-collection test:oracles
# Service-dependent: requires Electric and PostgreSQL to be running.
pnpm --filter @tanstack/electric-db-collection test:e2e
pnpm run typecheck:tests
pnpm exec tsc --noEmit -p packages/db/tsconfig.json
pnpm --dir packages/db exec vitest run --coverage.enabled=false --maxWorkers=2
pnpm --dir packages/db-ivm exec vitest run --coverage.enabled=false --maxWorkers=2
pnpm --dir packages/offline-transactions exec vitest run --maxWorkers=2

Core guarded replay is run from packages/db, for example:

TANSTACK_DB_ORACLE_SEED=1813 TANSTACK_DB_ORACLE_PATH=0 \
TANSTACK_DB_ORACLE_PROPERTY=live-query-observer.granular-history \
node --import tsx tests/oracle-replay.ts \
  tests/live-query-observer-history.property.test.ts \
  -t 'granular listeners follow the eligibility ledger with a random or replayed seed' \
  --coverage.enabled=false --typecheck.enabled=false

Use the failure's actual seed/path for a reproduction. The example establishes target execution, not reproduction of a particular bug. Local IVM and offline properties have separate environment variables; inspect their test headers. Do not assume the core multiplier reaches them.

Stress runs need an explicit file list, run budget, seed policy, runtime, exit status and cost. For long synchronous campaigns, yield between complete histories, never between an action and its synchronous observation. In this project, worker progress RPC starvation produced passing assertions with a nonzero process exit. Such a run is not green. Raising a test timeout alone does not let the worker process its progress messages.

Deferred contracts and evidence#

The maintainer assigned offline policy work to RFC #1659. It is not a merge blocker for this oracle repair. Keep these scenarios and decisions with that owner:

• A10 R7/R13: provider succeeds, outbox deletion fails, then restart can replay the retained work. IndexedDB transaction-completion settlement is fixed here; LocalStorage's failure/read policy and post-success acknowledgment remain open.
• A10 R4/R5/R9: loss before durable admission, terminal waiter/removal/clear and restored optimistic lifetimes, and retry-hook failures.
• A10 R11/R12 and earlier R8: metadata/native-value domain, old readers of new wire records, and unreadable/unknown-version outbox recovery. New readers accepting old records does not prove reverse compatibility. Do not delete unreadable work silently or invent exactly-once guarantees.

Other explicit follow-up boundaries are owned by issue #1820, not silently claimed green:

• Effect disposal: the existing external-disposal wait and synchronous in-handler cancellation are tested. Waiting for independent work returned by the initiating handler conflicts with supporting a handler that awaits its own disposal. The candidate implementation was removed pending a contract.
• Proxy native mutators and symbol writes: retain supported standard Map/Set behavior. Decide additional support versus a clear error before generalizing expectations; do not silently drop native edits.
• Progressive/native execution: eight progressive registrations lack valid phase/capability evidence. Electric's ready gate is after application, not a pre-swap source gate; TrailBase does not supply that capability. The 24 move cases and actual native hosts need separate execution receipts. A green registration helper or package job does not prove these cells ran.
• Optional mechanics/performance: separating the expensive replay-process campaign, sharing native runner code only with both host builds verified, optional cancellation calibration and proxy construction-work budgets. An earlier suggestion to merge unnamed cleanup helpers still lacks exact targets; do not perform a blind consolidation.

Final evidence record#

Verification receipts and follow-up issue links are recorded in the PR and the issue closeout comment. Keep their exact revision/runtime boundaries; historical counts in research notes do not certify later commits. Closing the bounded repair means the acceptance map has evidence and each remaining question has an owner—not that there can be no more bugs.