Skip to content
Source
Sign inSign up
TanStack/db
Open History to see the last commit

oracle-coverage.md

901 lines308.7 KB

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 states its contract, model, history grammar, production driver, and refinement check—including its public observations and checkpoint—in the executable file. Focused regressions outside that inventory may remain short, but a file named oracle or property cannot use that allowance to omit the literate structure.

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.

SurfaceStatusCompleted or next owner
Ordered relations and BTreeCompleteThe signed top-K relation, BTree/Map refinement model, and DBSP incrementalization laws are literate.
D2 operator workpackages/db-ivm/tests/d2-work-oracle.test.tsA finalized 65-branch graph receives one direct input at the first, middle, or last branch, then a second input on a different branch. The oracle compares exact forwarded messages and operator invocations after each run(): branches without queued input perform no operator work. A connected reversed-registration pair must drain in the same run, and an empty unfinalized graph rejects. The old unconditional loop fails with 64 idle calls per turn. This bounded work check does not establish elapsed latency, fused operators, arbitrary graph topologies, or provider-level live-query work.
Includes and publicationCompleteThe central recomputation model plus cross-formulation, temporal demand, layered publication, Collection facade lifecycle and space bounds, route-context transport, functional projection, query-shape, optimistic, and source-work owners are literate. They keep the architecture document as their contract source.
Collection lifecycleCompleteThe shared logical-owner/acquisition-attempt/sync-run grammar plus mutation admission, lifecycle trace, publication, replay, disposal, and transaction-refinement boundaries are literate.
Paced mutationsPartialThe virtual-clock owner checks queue order, bounded admission, cleanup draining in FIFO/LIFO order at the configured wait, admitted writes after separate Collection cleanup, post-cleanup queue rejection with a disposal reason, pending debounce drain at the last call's quiet edge, pending trailing throttle drain at its regular edge, debounce and throttle edge options including omitted options, immediate rejection of dropped leading-only calls and both-disabled calls, caller-option immutability, and settlement. New debounce/throttle admission after cleanup, failed persistence, and broader generated schedules remain open.
Optimistic stateCompleteThe independent base/intent/source-queue graph plus outcome, transaction-payload, and publication drivers are literate.
Drafts and native valuesCompleteNative differential behavior, draft change tracking, detachment and its class-instance exception, hostile keys, aliases, cycles, and Map/Set live iteration are literate.
Query DB and observerCompleteQuery-scope row ownership, subset identity and cancellation, failure and recovery, and the per-listener eligibility ledger are literate.
Query DB SSR dehydrationFixed QueryClient/Seroval boundarySuccessful on-demand entries with a compound predicate, a request signal, and an ordered cursor with a custom comparator retain their row and user metadata through Seroval's reconstructed stream payload and Query Core hydration; request options are absent from the stream, while query functions retain the original values. The TanStack Start router and browser Collection resume path still need a host witness.
Ordered acquisitionCompleteExact demand identity, applied settlement, independent pagination recomputation, request work, lifecycle products, replay authority, source-generation readiness, and transaction-refinement abort boundaries are literate.
Indexed predicate filteringComplete for bounded dotted-path collisionAn independent row filter checks direct predicates and public callback predicates for a dotted scalar field beside a nested path, with and without an index. Selected-field ordering checks the same distinction through $selected.
WHERE predicate publicationComplete for bounded predicate and sync-transaction grammarThe contract, Kleene reference evaluator, snapshot and change-history grammar, three subscriber consumers plus direct snapshot, and per-commit key-set refinement check are literate. A fixed same-key update checks live-row and direct-subscriber payloads; a focused descriptor boundary checks stored-row prefilter safety. Generated cleanup and restart histories for filtered subscribers remain open.
Joined result keysComplete for bounded two-source key grammarThe contract, nested-loop pair model, delimiter-, number-like, infinite, and NaN key grammar, public join driver, and per-checkpoint pair and key-count check are literate. Joins over subqueries, more than two sources, custom getKey, and optimistic mutations remain outside this owner.
D2 Index storageComplete for bounded prefix grammarThe contract, plain-Map multiset model, prefixed and unprefixed value grammar, Index driver, and per-addition get/has check are literate. Compaction, presence tracking, and structural payloads remain outside this owner.
Pooled live queriesComplete for bounded eq-filter grammarThe contract, independent eq model, live-query Collection second formulation, sync/optimistic/mount/cleanup-restart grammar, observer driver, and per-step refinement check are literate. On-demand and persisted sources, DbClient, Suspense, and every clause beyond eq conjuncts keep the live-query Collection.
Flat-row change trackingComplete for bounded flat-row grammarFlat and proxy trackers and an independent change model run the same generated callbacks. Nested values fall back to the proxy, which its own oracles own.
Lazy target path identityFocused compiler boundaryA same-source union/coalesce witness keeps dotted and nested demand paths distinct during target deduplication.
Correlated include path identityFocused public route-context witnessesOne-level and nested includes keep dotted and nested parent paths, including ancestor aliases, distinct. Conditional result paths receive separate routes. Fixed fixtures cover initial reads and selected source updates; other recursive source forms and arbitrary path segments remain outside this witness.
Alias scope identityGenerated cross-scope alpha-renaming with an independent modelOptimizer copies, wraps, and collapses keep SourceId; compilation binds inputs by SourceId only; includes cannot shadow a parent subquery alias. Unreached forms and channels are listed in the owner row.
Join equality and cold acquisitionCompleteIndependent cold relational recomputation, acquisition evidence, established equality domains, replacements, and scan/index routes are literate.
Opaque backend paginationCompleteThe full-relation value model plus opaque token, cache generation, publication, browser acquisition, and live-window integration owners are literate.
Electric and TrailBaseCompleteElectric replica and recovery models, installed-SDK HTTP delivery, PostgreSQL serialization, and TrailBase's controlled RecordApi/native-stream lifecycle are literate with their real-provider limits intact.
PowerSyncCompletePatch conservation, effective-update receipts, metadata and falsey changes, declared-view keys, transformed schema output, logging, cleanup, and native SQLite reach are literate.
SQLite persistence and native hostsCompletePersisted hydration/replay and ownership, shared-handle driver transaction laws, OPFS page and diagnostic state machines, and the 113-law native conformance manifest are literate. Native execution remains distinct from registration and shim evidence.
Offline executionCompleteFIFO retry, scheduler eligibility, leadership replay, transaction settlement, and typed wire serialization are literate.
FrameworksCompleteShared live-query and infinite-query models are literate. Each framework keeps its own realm, ownership, and scheduling driver.
Structural values and ordered primitivesCompleteStructural hashing, deep equality, comparison, cursor denotation, index refinement, and query-identity output equivalence are literate.
Boundary refinementsCompleteCleanup/restart admission, metadata publication, retained state, acquisition cells, D2 source reconciliation, top-K support windows, and nested Query work bounds are literate.
Small structures and test mechanicsCompleteSortedMap, cleanup appointments, and guarded replay are literate.

Guide-audit boundary handoffs

The includes-space owner (packages/db/tests/query/includes-space-oracle.test.ts) now varies leaves per twig across 0, 1, and 10. Public leaf rows change from 0 to 10 to 100 while 13 Collection facades remain. This protects facade ownership for the fixture's fixed root/branch/twig topology; route churn, D2 demand retention, and a heap bound need separate witnesses in the includes owners.

The virtual-row-fields owner (packages/db/tests/query/virtual-row-fields-oracle.test.ts) checks presence of all four public virtual fields directly after implicit, expression, and functional root publication. Its fixed controlled-Collection cases do not establish every nested projection shape or framework receiving boundary.

Three type-only owners check compile-time boundaries: packages/db-sqlite-persistence-core/tests/persisted-options-type-oracle.test-d.ts checks local and synced persisted option input/output and key types; packages/db/tests/mutation-handler-type-oracle.test-d.ts checks sibling Collection/key/utilities in mutation handlers; and packages/db/tests/query/virtual-row-fields-oracle.test-d.ts checks all four published virtual fields against an independently written public shape. Their passing type assertions do not prove runtime parsing, I/O, or publication.

The shared-driver fairness owner now distinguishes K=1 from K=2 at the second hydrate and checks full logical persist FIFO order in its Node seam. The Chromium OPFS receiving spec checks a cold SQL read, the K=1 hydrate bound, public rows, the pending persist backlog at the second hydrate, and all five logical persist completion IDs in FIFO order during one held-BEGIN storm through the real worker. This closes the bounded real-OPFS handoff at logical adapter completion for that history. It does not establish durable write order after reopen, naturally occurring contention, a browser matrix, multi-context coordination, elapsed-time latency, or unbounded eventuality.

The D2 source reconciliation owner checks its helper and controlled Effect and live-query consumers. Fixed truncate/replay and cleanup→preload graph-restart cuts run on both eager-index and scan-fallback routes. Its generated histories still do not cover arbitrary graph shapes or real provider event delivery; the Electric real-provider E2E owner must supply that external premise before a cross-boundary claim.

PowerSync's correctness owner reaches native local SQLite and records an SDK-delivered watcher callback after a metadata-bearing Collection.update; registration is wrapped for observation while delivery uses the SDK callback. The oracle checks the public and SQLite rows and the exact queued CRUD patch. Its held watcher callbacks are a controlled delivery premise, and its trailing no-op and tracked metadata-only cases enter through the public transactor with synthetic mutations rather than Collection.update. Neither path establishes remote backend upload or that Collection updates can construct those zero-field mutations.

The Query DB nested-shape work owner checks both an all-reachable finite tree and an on-demand irrelevant-branch variant. At preload, one or three disconnected branches leave the public tree and delivered rows unchanged and cause exactly one acquisition attempt and one Query provider call per child level. Provider scans, internal index traversal, facade allocations, and elapsed time remain outside this owner; DB includes-work counts source Collection reads and delivered changes, not internal index traversal.

Three Ordered acquisition companions own distinct controlled cuts: packages/db/tests/query/load-subset-replay-refinement-oracle.test.ts checks held replay authority and public snapshots; packages/db/tests/query/load-subset-source-readiness-refinement-oracle.test.ts checks source-generation readiness, progressive old-child retention, and retired-route publication; and packages/db/tests/query/load-subset-transaction-refinement-oracle.test.ts checks before, during, and after-commit abort boundaries with applied receipts. These fixtures do not establish real-provider cancellation or framework timing. The core load-subset-oracle.property.test.ts now distinguishes each exact demand-key option through one-axis pairs; its derived-sync expected-failure guard and controlled-adapter scope remain explicit limits.

The QueryRef owner checks DISTINCT support through source deletions, last-support removal, reinsertion, and person enable/disable. It checks nested and flat aggregate joins through source updates, and ordered joined findOne() through initial, singleton, empty, restored, and changed-join-key cuts. An unordered findOne() QueryRef used on either side of a join keeps one default-key row through deletion and reinsertion. The optimizer aggregate owner checks the initial public inner join of a global aggregate with accepting, rejecting, and absent outer predicates; a materialized-Collection formulation supplies matching and nonmatching controls. Other singleResult forms, join forms, and scheduling cuts remain outside these owners.

The offline scheduler owner (packages/offline-transactions/tests/KeyScheduler-oracle.property.test.ts) checks FIFO eligibility and retry order at the scheduler boundary. It does not observe the executor's awaited outbox update between updateTransaction and markFailed, or public caller settlement. Those receiving cuts belong with packages/offline-transactions/tests/transaction-settlement-oracle.property.test.ts. The transaction serializer owner uses controlled Temporal constructors and fake storage; a claim about native Temporal or browser storage needs a receiving witness in those runtimes. The offline settlement owner follows the README's success boundary: the configured mutationFn has returned and the storage adapter has acknowledged outbox deletion. Its controlled storage histories hold and fail deletion, stop the executor and queued peers on a storage failure, reject new admission, and restart after a persisted deletion-pending phase. A marked row skips provider replay even when beforeRetry filters all ordinary pending work; an old unmarked row still replays. Adapter tests prove that IndexedDB transaction failure and localStorage removeItem failure reject rather than masquerade as deletion. When a caller removes an active row with removeFromOutbox or clearOutbox while its provider is held, the caller remains pending until that provider returns. The controlled witness then checks provider calls, public settlement, and the empty outbox. The leadership owner checks that an earlier deletion-pending row with the same persisted timestamp is deleted before its later peer reaches the provider. This restart witness uses storage insertion order to distinguish creation order; independent storage writers and native browser hosts remain outside its claim. These witnesses do not establish physical power-loss durability, a real provider's idempotency, or the crash window between provider completion and the phase write. The provider must honor the supplied idempotency key in that window. Older application versions that do not understand the phase can also replay a marked row. Native browser restart and multi-owner handoff of the marked phase remain receiving witnesses for this owner.

The same owner also needs a captured failing seed-and-shrink-path replay for its generated settlement property. The deletion-settlement review record preserves its earlier executable revision. The fail-stop follow-up records the revised storage-failure law, RED/GREEN witnesses, and limits. The guarded replay owner (packages/db/tests/oracle-replay.test.ts) now checks that named pagination and index campaigns execute only the requested replay lane. An unrelated failing fixed campaign no longer runs first. The prep-PR review record records these four review repairs at their exact executable revision.

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.

PRClassificationPermanent authority and campaign
#1831Explicit oraclePowerSync's packages/powersync-db-collection/tests/correctness-oracle.test.ts crosses real PowerSync receipts and native SQLite behavior. It runs in the package test campaign and the focused test:oracles campaign; portable declarations retain compiler authority.
#1832Equivalent specialized authoritypackages/electric-db-collection/e2e/sql-predicate-semantics-oracle.e2e.test.ts and packages/electric-db-collection/e2e/subset-sql-acceptance.e2e.test.ts run through the package's real-provider test:e2e campaign. Compiler unit tests are collateral, not substitutes for either service boundary.
#1833Explicit oraclepackages/db/tests/query/pagination-oracle.property.test.ts owns inherited collection collation, actual item2/item10 order, exact request options, hostile lexical/numeric controls, and both scan and auto-index paths. It runs in @tanstack/db's test:oracles campaign.
#1834Explicit oraclepackages/db/tests/query/cold-join-reconciliation-oracle.test.ts owns join/predicate equality equivalence across the established value domains, binary/string and nullish controls, replacement histories, raw lazy demand, and scan/auto-index paths. It runs in @tanstack/db's test:oracles campaign.
#1835Explicit oracleThe existing packages/db/tests/collection-state-retention-oracle.property.test.ts and packages/db/tests/optimistic-transaction-oracle.property.test.ts owners cover separate collection-state and transaction-history laws. Both were already registered in @tanstack/db's test:oracles campaign; focused storage/local-only tests remain collateral.
#1837Explicit oracleThe offline scheduler, leadership replay, and serializer owners cover selective replay retirement, durable per-ID settlement, stale-read fencing, lifecycle recovery, native scalar encoding, and prior wire compatibility. They run in the package test campaign; generated owners expose OFFLINE_ORACLE_{SEED,PATH,RUNS} or the scheduler's TANSTACK_DB_OFFLINE_ORACLE_* replay interface.
#1842No shipped-law caseThe PR changed only focused observer tests and introduced no production behavior. packages/db/tests/live-query-observer.test.ts remains the correct evidence; no synthetic oracle or campaign claim is added.

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.

SurfacePrimary executable ownersIndependent judgment and important limit
Ordered relations and BTreetop-K relation oracle, fractional-index window moves, BTree/Map, incrementalization lawsIndependent ordered relations and cumulative signed output. Top-K consolidation compares same-key values without hashing, including cyclic replacements and fresh transient cancellation. The fractional-index test checks an empty output message for a window move after all rows retract; it does not prove downstream lazy acquisition. Other hash-based operators retain hashing's declared domain. Algebra does not specify client readiness. The BTree/Map oracle checks point operations, neighbor pairs, and full, partial, boundary, exclusive-high, and empty range scans for integer keys and node sizes 4–8. It does not check balance or space, and it assumes consistent comparators (code-weight BTree review).
Includes and publicationcross-formulation, temporal, Collection includes, architecture and complete suite mapPer-parent/flat-join/partition relations, callback-time rows, nested values, and route histories. Fragmented lazy-demand consolidation covers delta growth and successful, rejected/retried, and obsolete replacements at the Collection request boundary; it observes exact key unions and abort checkpoints. A compiled-includes fixture makes adapter unload evict owned child rows and proves a rejected union cannot remove established public child rows. Retry after that terminal live-query failure remains covered at the acquisition boundary; no automatic in-place recovery is claimed. Observe raw promised order; fresh queries do not establish continuous publication safety.
Collection lifecyclemutation startup, change-event history, history, publication, replay, effect disposal, PR #1902 review, batch-order decision review, absent-key insert reviewCore Collection insert/update/delete admission while startSync:false is idle; complete public-row/change-message agreement across bounded one- and two-key histories plus replayable four-key campaigns, where every message must be valid for a strict consumer (insert only for an absent key, update or delete only for a present one; absent-key insert review); a two-key deferred sync history checks each key's causal insert/update/delete trace while allowing any cross-key interleaving. Reversing all deferred messages fails that check; reversing each sync transaction's distinct-key messages passes. Queued duplicate admission and cancellation, ownership and phase histories, exact caller/error/publication evidence, and late completion and restart have separate witnesses. Generated deferred histories with cancellation or reentrant callbacks need a witness in the change-event history owner before claiming general batch-shape coverage. Query write utilities and effect self-dependent disposal remain separate contracts.
Paced mutationsvirtual-clock oraclecreatePacedMutations with queue front/back options, bounded waiting capacity at zero and one, cleanup draining in FIFO/LIFO order after a held write, cleanup timing at the configured wait for immediate writes, admitted writes after separate Collection cleanup, debounce and throttle schedules with explicit and omitted options, and first-leading throttle execution at epoch zero. Finite histories compare optimistic rows, returned transaction identity and receipt outcome, execution order and virtual-clock time. Held writes verify queue serialization. Leading-only throttle and debounce witnesses reject skipped calls immediately with their named dropped-call errors, including omitted edges, both edges disabled, and same-row rollback while a prior write is held. Capacity witnesses cover overflow rejection, distinct-key optimistic rollback, same-key admitted-write survival, and in-flight versus waiting admission. Cleanup witnesses check repeated queue cleanup, eventual admitted receipt settlement, direct queue strategy rejection of new callbacks, public post-cleanup rollback with QueueDisposedError, pending debounce transactions that wait until the last call's quiet edge after separate Collection cleanup, and a trailing throttle timer that runs at its regular edge after separate Collection cleanup. Deferred custom queue and batch callbacks check compatibility with void and false execute results, respectively. Frozen options verify factory non-mutation; a mutable option witness checks that debounce uses its construction-time trailing setting. New debounce/throttle admission after cleanup, failed persistence, broader capacities and schedules remain outside this owner.
Optimistic statehistory model, generated histories, truncate capture ownership, outcomes, publicationIndependent whole-row snapshots, rollback dependencies, captured truncate ownership, metadata and prior-value events. A raw subscriber without initial state checks that each truncate batch inserts a key once (2026-10-02 review). Never rebase a pending snapshot merely to simplify the model. Generated histories also write source batches inside mutation handlers, before they return; the Collection must own the request by then (handler source batch review). The same-key transaction lane also authors a delete followed by a reinsert, which must be visible optimistically and net to the truth-table request (state mutation round 2). Source rows are written as insert for a key the source lacks, and batches may delete keys the source holds (state-stack mutation gaps). Batches may also delete a key the source never held. That delete retires an accepted snapshot of the key, as any ordinary source publication does, and leaves an active request in place (absent-key source delete review).
Drafts and native valuesproxy, detachment, iteration, revert, native methodsNative-operation controls, exact patches and actual stored rows; alias/cycle/adversarial-key histories. Set and Map reorder histories check draft patches and stored iteration order after replacement and clear-and-readd; RegExp replacement/reversion histories check lastIndex. General native-mutator and symbol-write support is not established by a plain-object oracle. The revert owner generates assignment, revert, delete, nested, symbol-key, and for...of histories and checks getChanges() and the draft against an independent draft-equality model: ordered Map and Set contents (including Sets inside Map values), RegExp lastIndex, array holes, and symbol keys inside nested values. Mutator methods (push, set, add) and top-level symbol writes are outside its grammar. The proxy owner's stored-function law checks, against a native row, that a function stored as data reads back as stored by every read path and that a stored method sees the draft as this, so its writes are tracked. The detachment owner pins which key classes a draft copies: enumerable string keys and every symbol key. The revert owner also generates typed arrays (including a subclass that does not forward its constructor argument), URLs, and a class with only private state as written values, with a property that writes two of them over one field. The native-methods owner generates rows (holes, undefined, duplicates, nested arrays, empty rows, typed -0 and NaN) and calls every method of Array.prototype and TypedArray.prototype, in fixed and random campaigns with replay; it compares the result, whether the method returned the array itself, the identity of each original object, and the published row with native values, and a new built-in method fails until it has arguments. The proxy owner's defineProperty, stored-function, and frozen-draft laws are bounded tables against native rows. Its defineProperty law compares result, value, descriptor, and changes, for values and accessors. The iteration owner checks that array iterators see a push, removal, index write, or length cut made while they are open. Open: a draft reads a class instance of the original row as a plain object, so private-field getters read undefined, and a built-in method called through this on a nested Map or Set draft rejects the Proxy receiver; a mutator that changes nothing publishes an equal value; reading an object under a frozen draft key counts that key as changed, writing back a keyless class instance of the original row is a change, and DataView setters are untracked (draft proxy review).
Query DB and observerownership, load lifecycle, observer historiesReal QueryClient boundary, applied-settlement barriers for existing and cached demand, mutation-handler Collection identity, terminal fetch-record lifecycle, and a per-listener eligibility ledger, not a duplicate dispatch queue. The bounded handler grammar crosses insert, update, delete, parameter and mutation-alias access, refetch, and clearError. A held clearError retry retains the prior public error through initial, background, and Collection application failures; success clears it, failure advances the count, including a repeated error at clock time zero. An intermediate Query retry attempt does not recount the previous background error; a held final attempt can succeed or fail. A held application after successful Query fetch keeps the error visible until the applied result. A mocked persisted-baseline scan holds an older success while a newer terminal Query failure arrives; the newer public error and count survive application, including when the Error object and clock tick repeat. Native SQLite persistence, concurrent retries across multiple tracked Queries, mutation-handler fetch-boundary settlement, and deferred result application remain outside this witness. The mutation overlap grammar crosses both start orders. Check reentry, peer survival, FIFO and disposal independently of final rows.
Query DB SSR dehydrationpackages/query-db-collection/tests/ssr-dehydration-oracle.test.ts, review recordA plain Query cache control, a live on-demand compound predicate, a signal-only request, and an ordered cursor with a custom comparator all retain their row through QueryClient dehydration, reconstruction of Seroval's emitted stream payload, and Query Core hydration from that payload. The on-demand query functions still receive the original IR, comparator, and signal; serialized metadata retains enumerable user metadata but excludes request options. The original implementation fails the compound and signal cases at the stream checkpoint. A serializable stream-only request-options leak passes the former chunk-count check but fails the current payload assertion. This owner covers successful Query cache entries at the installed Query Core 5.90.20 and Seroval 1.5.0 versions. A TanStack Start integration owner still needs the reporter's Router 1.171.33 and Seroval 1.6.8 path, browser Collection resume/refetch, and request cancellation across SSR. Query subset and pagination oracles remain owners of predicate/order/cursor meaning and supported value types. The issue's shouldDehydrateQuery workaround replaces Query Core's success-only default and admits pending/error queries; any documented workaround must preserve that default filter.
Ordered acquisitionpagination, ordered work, ordered lifecycle, ordered loader state, graph scheduler, issue #1880 ordered-repair review, issue #1882 custom local collation review, issue #1898 relation-filter review, PR #1909 external reviewComplete finite provider results, inherited locale and bounded/unbounded custom collation with exact request options, query-level inheritance across source aliases, real lexical/numeric disagreement, custom comparator ties, scan/index paths, pending windows, ties/nulls, lease ownership, Effect callback gates, including an indexed source update during Effect startup, and documented repair timing. Direct LEFT-joined filters cover local finite prefixes, pending child demand, child removal, and anti-join publication with custom full-source and unindexed fallback loading; unrelated include demand cannot stall the root continuation, and an empty joined replay wakes held Effect callbacks; remote relation hints remain outside this owner. Graph scheduler checks coalescing, dependency order, synchronous loader input, and repeated-alias failure ownership. The ordered-work oracle checks that a synchronous root refill reaches D2 before joined publication; a mutant that omitted the post-loader graph step failed at the second child demand. Custom collation proves local full-source acquisition only; it does not establish provider cursor capability or backend collation fidelity. Sibling-source input during a synchronous ordered continuation returns to graph work before another ordered acquisition. Request completion is not proof of unrequested source extent. A window move during existing joined demand waits for its root continuation, including an independently held root request; current demand failure rejects the move, while retirement and an obsolete rejection do not. A bounded ordered repair resumes its refill after joined demand settles. The ordered-source-loader state test checks that an explicit failed-request retry blocked by joined demand retains its generation until it can issue a request. Multiple simultaneously pending joined plans during a window move and a public-query failed-retry overlap still need dedicated witnesses.
Indexed predicate filteringpackages/db/tests/query/index-path-collision-oracle.test.tsA bounded cross product of numeric values checks exact public keys before and after adding a nested-field BTree index. Direct predicates vary argument order, bound inclusivity, reversed operands, and bound field. Public Collection subscription and live-query callbacks run with and without the index. Selected-field ordering compares a direct JavaScript sort with a public $selected callback; restoring the dotted-key proxy cache made that comparison fail. The original compound grouping failed four indexed cases while scan controls passed. The original callback proxy caches also failed both unindexed public routes. A hostile cleanup control preserves the primary mismatch and secondary release error. Arbitrary path segments, nullish values, custom collation, and incremental publication need separate witnesses if claimed.
Lazy target path identitypackages/db/tests/query/compiler/lazy-targets.test.tsA focused same-source UnionFrom/coalesce witness requires both [a.b] and [a, b] demand targets. Restoring dotted-string deduplication drops the second target at the compiler boundary. A public on-demand adapter and row-publication history still need a separate witness.
Correlated include path identitypackages/db/tests/query/includes-context-transport-oracle.test.tsA flat parent field and nested parent field reach one-level and nested toArray results independently; dotted ancestor aliases remain distinct through a grandchild route. Initial results and parent updates have exact public-value checks. A conditional projection gives [a.b] and [a, b] different include results and checks parent-key changes plus later child inserts. Removing the compiler's unique route-key allocator loses a public child result; restoring dotted-string deduplication at either builder site loses a distinct parent value. These fixed witnesses do not establish arbitrary path segments, every recursive source form, or every materialization form.
Alias scope identitypackages/db/tests/query/includes-oracle.property.test.ts (includes alpha-renaming across sibling scopes), packages/db/tests/query/includes-scope-identity-oracle.ts, packages/db/tests/query/validate-aliases.test.ts, issue #1975 reviewFour topologies place a source beside a same-named sibling source: a from() subquery with an include, a joined unionAll() branch with an include, a collapsed top-level pure wrapper with a join subquery, and an include directly on a joined unionAll(), which may reuse a branch alias. The grammar crosses zero to two joins, LEFT or INNER, zero to two predicates, plain, ordered-and-limited, or DISTINCT bodies, include forms, and eager or on-demand finite providers, after preload and after source writes. Includes read their source directly, through a join, through a unionAll() with an anchor join, or through a from() subquery that reads the parent row. One in four scenarios draws any naming and requires illegal ones to be rejected. Each checkpoint compares the canonical naming with plain recomputation, the generated naming with the canonical naming, and per-Collection loadSubset WHERE clauses. Every pinned witness and both campaigns fail on 18abceee4; each of the four optimizer re-mint sites fails a witness when reverted. Nested includes, include-inside-subquery forms, join subqueries outside the wrapper topology, groupBy/having, outer RIGHT/FULL joins, publication events, unload, ordered windows and lazy join loading through the alias-merged aliasRemapping, and temporal demand remain outside this owner; they need witnesses before an alias-scope closure claim covers them.
Join equality and cold acquisitionpackages/db/tests/query/cold-join-reconciliation-oracle.test.tsIndependent recomputation for cold acquisition plus direct join/predicate equivalence across established equality domains. Binary/string and nullish classes, replacement histories, raw on-demand values, and both scan/auto-index paths are explicit; compound join syntax is not claimed.
Query optimizer semanticspackages/db/tests/query/optimizer-semantics-oracle.test.ts, aggregate review, QueryRef repair, residual reviewIndependent sum recomputation and a materialized-Collection formulation check the first public snapshot of a nested aggregate under a left join. Direct, arithmetic-wrapped, and conditional aggregates distinguish safe from unsafe pushdown; a grouped-key control covers the grouped boundary. Matching and nonmatching global aggregates also cross a nested QueryRef inner join with absent, accepting, and rejecting outer predicates. The matching initial cases fail on the pre-repair revision and pass after the computed-projection lookup repair. A separate fixed residual-convergence grammar checks exact predicate and outer WHERE clause counts at optimizeQuery return and after re-optimization: LEFT, RIGHT, INNER, and FULL joins; equality, greater-than, nullable-field isUndefined, same-source OR, cross-source equality, clause order, separate/AND form, two active predicates, two residual sources, and an existing residual marker. Plain-array LEFT/RIGHT and three-source join models check first public rows, including unmatched rows. Arbitrary expressions, more complex join chains, and incremental optimizer/publication histories remain outside this owner.
QueryRef operators and user-value boundariespackages/db/tests/query/subquery-user-value-oracle.test.ts, packages/db/tests/transactions.test.ts, repair recordA finite array/Set model checks the compiled output bag for a joined DISTINCT subquery with an outer WHERE. Live-query drivers check selected containers, no-select, functional, and predicate-literal user objects with IR-like fields, top-level and aggregate-subquery proxy-shaped fields, arrays of selected references, outer virtual-field filters on joined DISTINCT and nested aggregate QueryRefs, and a renamed no-select source. The transaction suite documents the existing development-browser duplicate-load guard. The bounded cases run in test:oracles or the full DB suite. Joined DISTINCT, nested and flat aggregate source-update histories pass. Ordered joined findOne() checks initial, singleton, empty, restored, and changed-join-key cuts; an unordered findOne() QueryRef on either side of a join checks default-key candidate deletion and reinsertion. A materialized joined findOne() supplies a separate receiving formulation. Other singleResult forms, join forms, schedules, and cross-copy value handling outside the duplicate-load guard remain unproved.
Opaque backend paginationwindow oracle, cache histories, cache publication, browser acquisition boundaries, QueryCollection integrationFull filter/sort/slice reference, opaque token transport, actual Query cache expiry/invalidation/GC, forced refresh during growth, protocol failure publication/recovery, bounded slice work, nested cancellation/replacement, reader abort, browser retry defaults, manual-write cache isolation, and production window publications. Stable backend sequences; not snapshot guarantees for changing endpoints. Peek-ahead remains enabled.
Electric and TrailBaseElectric histories, recovery histories, held resume snapshots, PostgreSQL semantics, TrailBase contractInstalled SDK delivery/framing, independent predicates, exact subscription arguments, restart/reset lineage, held certification and durability races, source-order publication before durability, and late errors. The queued-presence property runs identical fixed/random generators plus isolated seed-and-path replay across insert, update, delete, and truncate callbacks. The recovery fixtures use a mocked ShapeStream; they do not establish live Electric-service framing or native persistence-host behavior.
PowerSynctests, tests/correctness-oracle.test.tsApplied receipt positions crossed with held peers, native SQLite/SDK and cleanup evidence. A metadata-bearing Collection.update passes through an observed SDK watcher callback to the public and SQLite rows and an exact queued CRUD patch. Held callback ordering and synthetic zero-field cases remain controlled-only, and remote upload has no receiving fixture here. Run the focused owner with the package's test:oracles command. A timeout mutant proves a progress failure, not every value assertion.
SQLite persistence and native hostspersisted histories, reset/resume histories, dual-adapter resume snapshots, Browser composed-owner histories, Browser coordinator RPC, shared-driver fairness, driver contracts, Node shared-handle scheduling, OP-SQLite shared-handle scheduling, browser OPFS lifecycle, worker diagnostics, Electron IPC and composed owner, 113-law manifestCore cache/remote rejection/peer/reopen histories, atomic reset/resume lineage, key-set evidence, dual-adapter races, queued coordinator reload/gap notifications during startup, unscheduled startup/reset overlap, and exact driver results. The shared core-adapter contract checks custom local comparator dispatch for ascending, descending, and comparator-equal public-key ordering at loadSubset completion. Host packages register this contract, but the local sqlite3 CLI run does not prove native host execution. Browser composes public source commits with per-collection elected-owner routing and covers the complete committed-transaction wire partition through deterministic Node transport seams. Remote-subset histories distinguish logical demand, physical acquisitions, exact acquisition leases, and released replay tombstones. Electron composes source commits with a per-collection renderer owner, IPC adapter, real SQLite, and reopen checks. The shared-driver fairness owner checks K=1 complete-logical-hydrate scheduling with identical fixed, random, and seed-plus-path campaigns. It records public rows, raw dequeue reach, and a persist-first FIFO hostile control. Its Chromium OPFS fixture refines the provider boundary but does not establish a browser matrix, elapsed-time latency, unbounded eventuality, or multi-process coordination. Same-handle Node and OP-SQLite tests cover transaction admission. Controlled OPFS page/worker histories cover ownership and diagnostic-cause retention. The reset/resume owners use sqlite3 CLI and in-memory node:sqlite seams; they do not prove multi-process WAL, mobile/Tauri, or other native-device execution. Distinct database handles rely on SQLite lock admission rather than one in-process queue. React Native hosts without async-context propagation must use the transaction driver supplied to the callback for nested work. Fake workers and synthetic page events do not prove native handle release or real bfcache admission. The Browser composed seams are not real multi-context/OPFS-worker execution; the Electron harness is not an actual Electron process unless its explicit runtime-bridge mode runs. An ownerless elected node suppresses core routing, while a follower may route demand to the elected owner; host coordinators retry only classified transport or admission failures while demand remains retained. The manifest excludes progressive and move suites; registration and shim runs are not device execution.
SQLite expression-index planningNode expression-index oracleRFC #1659 invariant 8 owns identical persisted-index and runtime-expression shapes. Independent expected keys are checked against direct captured SQL, adapter results, and named-index plans. Generated BigInts use SQLite's signed range; one fixed case checks legacy oversized-value reads. Other limits: bounded unqualified JSON paths/scalars, Node BetterSQLite, and no null, arbitrary raw SQL, or native-host planning. Run the package's test:oracles campaign.
Offline executionscheduler, leadership, settlement, serialization, web connectivity replay, review recordDeclarative FIFO eligibility, per-transaction outcomes, durable state and typed wire trees. The web connectivity owner checks a persisted write under a false browser online hint, then visible replay by event or explicit retry, at provider-call, outbox, and caller-settlement cuts. It uses controlled browser globals and fake storage; it does not prove actual browser network detection, genuine offline retry timing, multi-tab leadership transfer, or React Native behavior. Issued work may finish after ownership loss, but new work must not start. Exactly-once network execution is not promised.
FrameworksReact conformance, React pagination, shared suites, Vue synchronous publicationExact exposed rows/pages and each framework's own lifecycle cuts. Vue's synchronous watcher checks insert, update, and nonterminal delete through supplied Collection and identity query inputs; it does not cover an empty final result, multiple changes in one transaction, or query recompilation. A React witness does not prove Vue/Solid/Angular/Svelte scheduling. Preserve their receiving registrations.
Window-controller overlapshared infinite-query conformance, React driver, Vue driver, Svelte driver, review recordFour or five ordered source rows, two window-settlement orders, and public snapshots after each settlement, a subscribed observer update, a detached controller read, and explicit recovery. Insertion and removal of the fifth row distinguish both continuation directions while an earlier error remains visible. The detached read follows a source change with no controller subscriber; its preloaded Collection retains the five-row window. The exact overlap uses the exported DB controller in each package realm. Framework hooks expose no controller preload, so this cell does not establish a hook scheduling path; direct hook paging remains in the adjacent shared scenarios. An unsubscribed controller has no notification claim.
Structural values and ordered primitiveshash values, hash identity, MultiSet consolidation, hash graphs, mixed hash graphs, hash retry, comparison, deep equality, cursor, indexes, BTree Map, query identity, LIKE semanticsIndependent flat values, graph topology, algebraic laws, Map/group/sort recomputation, expression denotation, custom comparator dispatch/reference identity/index compatibility, LIKE wildcard refinement, compiled output bags, declared value-pair agreement between D2 equality keys and IR equality operands, and Collection collation with exact public scan/index order and one-index reuse across repeated reads. The auto-index cells cross BasicIndex and BTreeIndex; scan cells omit indexes. Both paths cover lexical and numeric en-US locale defaults plus an explicit ordinary locale override of a numeric default. An unindexed six-row work cell bounds Collection collation resolution to at most two reads per ordered scan: one index-path check and one scan clause. Other locales and ordered histories are outside this owner. The identity pair grammar covers primitives, signed zero, NaN/invalid Date, valid Date/timestamp, binary/Buffer, Temporal, nested references, symbols, and functions; fixed and sampled pairs do not prove every JavaScript value or hash collision freedom. Ref proxies are expressions rather than literal values in this lane. The deep-equality owner also pins that deepEquals ignores Map and Set insertion order, RegExp lastIndex, array holes, and typed-array class, the rules draft equality keeps. It also pins that objects of another class differ, that plain and null-prototype objects are one class, that a class instance without enumerable keys equals only itself, that URLs compare by href, and that typed-array elements compare like numbers. The hash-values owner samples Set/object and Map/object type-marker distinctions in fixed and random campaigns with seed-and-path replay; collision freedom is not promised. The hash-identity owner checks hash and equalHashValues against one spec-level identity model: primitives with signed zero, NaN, and bigint; reference leaves (functions, registered handles, File, binary over 128 bytes); Date, binary, Temporal, and RegExp headers; array length and holes; Map and Set insertion order; and object keys in any order, for acyclic values and for cycles through arrays, Map values, Sets, and plain objects. Map/Set order sensitivity is pinned current behavior, not a promise. Arrays from another realm, RegExps with a NaN lastIndex, getters, proxies, other cycle carriers, and pairs that differ only in a back-edge target are outside its grammar; pinned cases keep equality's cross-realm length check and strict RegExp field comparison. hash-work.test.ts pins how visited values and array/RegExp headers count toward the structural work cap, and that equality copies a shared Map's entries once per distinct pair (code-weight hash dispatch review). Custom string indexes do not optimize ordinary ranges, and custom cursors remain unsupported. The LIKE owner covers boolean string matching and bounded work, not nullish three-valued logic or a general Unicode collation contract. Unsupported composite cursors reject. The MultiSet consolidation owner checks keyed, single-type, and structural identity, signed zero and NaN in keyed and single-number data, the retained first record, zero-sum removal, and input record contents. It does not assert output order. Its keyed grammar includes cross-type key and value collisions, non-finite numeric keys, the | delimiter, symbol and function identity, and a direct-object/object-tuple delimiter control from #1948. Eight named collision witnesses and both generated campaigns are RED on c879ba6d and GREEN with the repair (#1948 review record); the code-weight consolidation review records the earlier exclusion. The keyed reference uses direct value/reference equality, including SameValueZero for numeric keys. The unkeyed fallback keeps its original key and value domains. The direct MultiSet owner does not prove which @tanstack/db query shapes produce primitive keyed values or mixed-type source keys; that needs a live-query production witness. The index owner enforces one invalid-comparator law across both BasicIndex and BTreeIndex: for each comparator, accepted numeric prefix (including the empty prefix), and probe operation (add, update, eq/range lookup, take, build), the operation throws exactly when it receives a NaN or non-number result and never when every comparison is valid. A signed infinity comparator is the valid control, and a custom collation compare supplied through compareOptions is checked the same way. Two BTree Map split histories check inserted-key reads, exact whole-range payloads/order, size, and extrema, proving split placement follows the insertion index without a post-mutation comparison. A rejected index add or remove leaves the index refining its accepted rows; update and build are not atomic. At the Collection boundary, both index types and both write paths (optimistic insert, sync commit) crash the collection: status becomes error and the next mutation throws, so a usable collection never holds rows its subscribers were not told about. Open: a sync source can still commit writes on a collection in error state, which stores unpublished rows; this is existing markError behavior and needs a lifecycle-owner witness. Comparator transitivity is outside this evidence.
WHERE predicate publicationWHERE predicate publication oracleAn independent Kleene evaluator judges eq/not/and/or predicates over strings, a normalization-prefixed string, booleans, numbers, NaN, a valid Date, null, a missing field, and virtual fields. Snapshot histories with pending optimistic inserts compare a live query, direct subscribers with and without initial state, and currentStateAsChanges; change histories apply multi-key sync transactions, including reinsertion of a key deleted earlier, and compare every consumer's key set after each commit, on scan and BasicIndex paths. Peer subscribers share one field with different literals, plus one on a virtual field, so every published change must reach exactly the subscribers whose predicate it can satisfy; routing mutants that ignored the previous value, ignored the field, delivered a change twice, or routed while stale published rows awaited reconciliation fail here. Fixed witnesses cover a layout-only publication reaching a filtered subscriber as one empty batch, a filtered subscriber's empty Collection-readiness batch, retraction of a vanished row after eager cleanup and restart, and the new row plus exact subscriber update payload when a same-key row stays TRUE. A stale-live-value mutant survives the generated membership checks but fails the payload witness. A focused property-visibility test compares the public unindexed snapshot with the enriched-row contract for inherited, non-enumerable, enumerable-own, and nested getter paths; the pre-fix stored-row shortcut failed three of its four controls. Other property-descriptor and stateful-getter histories remain outside those fixed controls. Hostile mutants for FALSE-for-UNKNOWN eq, or or number-literal subscription prefilters, a prefilter that ignores the previous value, a skipped readiness batch, a skip while stale published rows await reconciliation, and an unindexed snapshot scan that reads only synced rows while an optimistic insert or delete changes visibility passed the prior @tanstack/db suite and fail here. Change routing withholds a dropped row from an eq subscription before its sent key could be recorded, so a mutant that records dropped rows as sent is equivalent for routed predicates in this oracle. A focused collection-subscription.test.ts witness checks that a dropped insert or update, alone or beside a matching change, cannot advance a limited subscription's page offset under a routed eq and an unrouted or predicate; the unrouted cases beside a matching change kill that mutant, and the unrouted alone case does not. A loose-equality prefilter is an equivalent mutant: it only skips less. Skipping during truncate replay also survives; the replay's baseline diff re-derives the same retraction, so the guard keeps the prior dataflow without its own witness. Generated cleanup and restart histories for filtered subscribers remain open for the lifecycle publication owner. No-op updates, other comparison operators, Temporal and binary operands, joins, ordering, optimistic updates, and truncate are outside this owner. It runs in @tanstack/db's test:oracles campaign. The 2026-09-30 review records each ORC outcome. Change routing was later removed in favor of pooled live queries; the routing mutants above are historical, and the same peer laws now check plain subscription dispatch. The unindexed snapshot prefilter was restored for compiled queries as one stored-row eq test on a string or boolean literal. Its property-visibility test also covers the reverse direction: a stored row with an inherited or non-enumerable field must still match isUndefined on that field, which a scan that evaluated the full predicate on stored rows fails.
Joined result keysJoined result key oracleA nested-loop model recomputes the pair set of an inner, left, or full join over source keys drawn from plain, comma-bearing, bracket-bearing, and quoted strings, numbers beside the strings that print the same, both infinities, and NaN. After preload and each synced group change, the published rows must equal the model's pairs and the result key count must equal the row count. The comma-joined key encoding fails its two pinned histories and both campaigns; plain JSON.stringify, which prints infinities as the missing-side null, fails the pinned infinity history and both campaigns. A pinned history in which a NaN-keyed pair leaves and re-forms fails when the join index compares source-key prefixes with ===. Joins over subqueries, more than two sources, custom getKey, and optimistic mutations are outside this owner. It runs in @tanstack/db's test:oracles campaign. The 2026-09-30 review records each ORC outcome.
D2 Index storageIndex refinement oracleA plain-Map model sums multiplicities under a type-and-value identity in which NaN equals NaN and -0 equals 0. Histories of up to twelve additions to two keys mix prefixed arrays with NaN, 0, -0, 1, '1', 1n, and 'a' prefixes and unprefixed values, with cancellation and reappearance. After each addition, get and has must equal the model. Comparing prefixes with ===, which disagrees with the Map that holds them, fails three pinned histories and both campaigns; the -0 control passes under both. Compaction, presence tracking, and structural payloads are outside this owner; the join operator tests and incrementalization law own operator behavior.
Pooled live queriespooled live query oracleAn independent eq model (nullish UNKNOWN, Date as timestamp, NaN equal to NaN, -0 equal to 0) gives membership; a live-query Collection compiled for the same query gives order, values, and status. Histories mix sync transactions, optimistic writes confirmed or rolled back, peer mounts and unmounts, and source cleanup and restart, including cleanup while a write is pending and a mount between cleanup and restart. Wholesale observers must match after every step, granular changes must match a reference observer by type, key, value, and previous value and replay to the model's rows, the layout revision must advance when keys reorder, and observing must never build the live-query Collection. Peers may add a residual not(eq(...)) conjunct, which the model evaluates itself; a view that ignores it, reports an unfiltered entries(), or delivers a row entering or leaving it as an update fails it. Other residual operators use the same compiler evaluator but are not generated. Peers may also order their rows by id or by a g that can be null, with explicit nulls; order comes from the reference. A comparator that ignores direction or nulls, an order left out of the partition key, and key order instead of the query's order each fail the pinned reorder history and both campaigns. A partition that ignores a row's previous group, orders by arrival, skips normalization, skips the initial snapshot, follows the source's status after cleanup, or never terminates fails it. Two shared conformance scenarios (eq-filter-rows, eq-filter-peers) run the pooled path under React, Vue, Solid, Svelte, and Angular; a partition that ignores a row's previous group fails both under every adapter, and eq-filter-peers checks through subscriberCount that each adapter shares one source subscription per partition. A focused release-timing test compares when a pooled query and a live-query Collection release their sources across gcTime 1, 100, 0, and Infinity, with and without a subscriber, and with no gcTime, where both use the live-query Collection default, checks that a partition waits for its views' longest gcTime, checks that a view resubscribed after its partition released follows later source writes as its live-query Collection does, including a view with a residual conjunct, and checks that a partition that subscribes again still serves new mounts from one source subscription. Further focused witnesses check that a partition keeps groups only for values that have rows or watchers, that a detached reader never sees a dropped group's revision reused, keep a pooled query's public Collection live while the view is observed, accept it as a query source, and check that a pooled query turns terminal when source cleanup starts while the adapter's cleanup is still pending, as a live-query Collection does. A pinned oracle witness checks that an eq path whose getter throws excludes the row on both paths; a pooled path that rethrows fails it. The pooled oracle's grammar never releases a partition, so release and resubscribe histories rely on these fixed witnesses; a fixed delay, a missing unsubscribed floor, a last-gcTime-wins rule, and releasing at gcTime 0 each fail it. The 2026-10-01 review records each ORC outcome.
Flat-row change trackingflat change tracking oracleGenerated callbacks over flat rows, frozen or not and with or without a non-enumerable field (assignments of 0, -0, NaN, undefined, functions, and fresh objects; reverts; deletions; added fields; data and accessor defineProperty; stored drafts; throws), run through the flat tracker, the draft proxy, and an independent model, which must report the same change sets with 0 and -0 equal, or throw the same error and leave the rows unchanged. Defining a field acts as assigning it, and a non-enumerable field is row data only once written; the proxy broke three of those laws on main and the flat tracker one. Diffs using !==, Object.is alone, or no deletions fail it. It found that the proxy dropped a field added as undefined when another field reverted; the pinned history and both campaigns fail without that fix. Non-flat rows must fall back. The 2026-10-01 review records each ORC outcome.
Virtual props cachecache lawsFocused laws for the per-key cache of rows read with virtual props: a change's published value is the row later get and toArray reads return, for every subscriber, after sync and local writes, and a key that is deleted or rolled back leaves the cache. Enriching the value before the previous value fails the first two; skipping the drop on delete events fails the third. Rows read with virtual props through other paths, such as joins, are outside these laws.
Local-only direct writesdirect write witnessesFocused witnesses pin when a local-only direct write skips the optimistic stage: a completed transaction and one publication per write, and the fallbacks for a pending, persisting, or ambient transaction and a user handler, for insert, update, and delete. Each history also runs on a local-only Collection whose handlers resolve, which must match its rows, change batches, errors, and transaction states, across mixed multi-key batches, a batch that fails midway, schema rejection, and handler rollback. Mutants that drop each guard, write only the first mutation, or never complete the transaction fail them. The change-event history oracle drives the direct path through generated histories (about two thousand writes per run); removing the guard, or guarding only persisting transactions, fails these witnesses.
Reused sync row objectsreused row witnessFocused witnesses for a sync source that changes a stored row object in place: in development, writing it again as an update without previousValue throws, while the same write with previousValue, or with a new object, moves the row out of an eq live query. Production skips the check. The check compares a shallow snapshot taken when the object was written, so it misses changes to nested fields; a write that names previousValue and a row whose fields throw on read are not checked.
Index suggestionscollection-size suggestion oracleA public filtered live-query Collection checks manual/default, eager, threshold, matching-index, and unrelated-index cases against the documented collection-size suggestion policy. The original manual-silence/eager-noise implementation failed two expected observations. The owner does not judge repeated-query warning volume, slow-query timing, query work, production-build suppression, or every query shape. It runs in @tanstack/db's test:oracles campaign.
Minified DB public APIconsumer bundle checkCI builds @tanstack/db, then bundles its built dist entry with db-ivm inlined through esbuild minify: true. The build renames TypeScript-private members from packages/db/mangle-cache.json, so this lane runs against the renamed output that consumers install. It rejects a dist that is older than src, the cache, or the package's build configuration. pnpm --filter @tanstack/db test:dist also runs five db test files against the built dist, chosen for coverage of the modules with the most renamed members. pnpm check:mangle fails when a cached name is used other than as a private member in db src, is read by another package, appears as a string, or has a short name that collides with a source identifier (private-member mangling review). It checks every exported error class's current public name, the built-in BasicIndex resolver name in index metadata and its event, complete query rows (after removing the four documented virtual fields) against an independent array filter/sort/projection, and one live update. The new.target.name, public-member mangle, and extra-output-field calibration modes fail at the intended observations. This fixed slice does not replace the unminified generated oracles, exercise framework adapters, or establish stable names for custom index resolvers.
Boundary refinementscleanup/restart, idle cleanup, issue #1891 async-cleanup review, issue #1891 cleanup-start follow-up, metadata publication, state retention, acquisition cells, D2 source reconciliation, top-K support windows, nested Query workExplicit lifecycle products, independent source maps and weighted relations, exact publication cuts, support/multiplicity, and value-plus-work observations. These refine the larger subsystem models; they do not replace them.
Small structures and test mechanicsSortedMap, cleanup queue, live-query GC clock, guarded replayMap/full-sort and elapsed appointment-list models with executed target/seed/path checks. SortedMap also checks deferred bulk writes, array-movement work, scan reuse, live iterators, runtime undefined keys, and public single-transaction and queued-transaction Collection sync paths. It does not settle the contract for comparator-observed values mutated after publication or every legal iterator/mutation interleaving. Wall-clock steps do not move due times, and a focused public witness checks source subscription release. Callback-reentrant scheduling, OS suspend/resume, environments without performance.now(), and fake/real Performance clock replacement while GC is pending remain outside this coverage. Tests must drain or reset pending GC before switching timer providers.

The React source ID reuse oracle (review) checks that a mounted derived-identity hook rejects a different same-ID source Collection directly, after an intervening ID and predicate, within one query, and after source cleanup. Stable sources, new IDs, a fresh hook after cleanup, and independent client scopes remain usable. Returning to a prior client scope retains that scope's binding, including through DbProvider. A suspended render that starts a source query also claims the ID until unmount. Separate client-scoped Suspense hooks and an initial suspended retry keep their same-ID sources distinct. A rejected collision render releases sync-start deferral for a different shared client descriptor; a later direct reader reaches ready and observes its row. The public rerender error, status, or row is the observation cut. A second controlled history makes two deferred sync starts throw and checks that a later shared source still starts and publishes its row. This distinguishes releasing every pending source from stopping at the first startup error. The first thrown error still reaches React's error boundary. This owner does not constrain explicit queryKey, direct Collection input, or legacy dependency-array identity, and it does not install a process-wide ID registry. Real persisted SQLite sources and DbClient SSR preload/streaming remain outside this controlled React driver. A space policy for a mounted hook that visits unbounded distinct source IDs remains open; this owner needs a bounded-navigation counter witness once that policy is chosen.

The SQLite core binding-capacity oracle in packages/db-sqlite-persistence-core/tests/sqlite-core-adapter-oracle.test.ts is a bounded owner for issue #1993. The review record gives the exact executable revision and guide audit. It failed on the original 900-item chunking and passes with one JSON table binding per runtime IN list and a statement-total fallback. It compares independently filtered rows and typed values with loadSubset on real Node prepared SQLite statements. Node versions that expose the configured 999-parameter limit use that native cap. Older versions use a controlled driver that rejects over-cap bindings before SQLite preparation; the oracle tests that guard separately. Fixed and generated cases cover empty lists, 998/999/1000 single lists, 499+500 and 500+500 statement totals, mixed scalar/list and nested predicates, root and distinct transaction-driver routes (including an omitted transaction cap at the 100/101 driver boundary), signed-64-bit BigInt edges, escaped strings, an ordered two-hit list across the old 900-item chunk, both cursor SELECTs, and a 1,000-scalar fallback. Both index-definition IN contexts must remain literal SQL. The existing CLI large-list test substitutes values into SQL and cannot witness parameter capacity. This new owner does not establish behavior for null, nonfinite, container, or structured values; 50,582-ID stress; JSON-function availability; the cost of a full-table fallback; concurrent writers; or browser, mobile, Tauri, and native-host execution. The core owner needs typed equivalence and row-read work witnesses before claiming class closure. Each host driver owns a receiving capacity witness for its real SQLite engine.

The Query ownership oracle checks that a direct-write promise stays pending while a controlled persisted adapter holds its sync commit and settles after the adapter stores the row. It also checks that all five direct-write methods reject after cleanup starts and that a restarted sync run can persist a new write. Focused Query tests check a synchronous batch callback returning another Collection's write without losing either write, while an async callback still rejects. They also check two serialized updates: after each awaited response write and mutation settlement, the public row shows the server revision. These witnesses cover an eager Query Collection after initial load with a controlled adapter, not a direct write already in flight when cleanup starts, native SQLite, or overlapping Query revalidation. The Query ownership and optimistic-history owners still need a joint generated witness for competing source writes around mutation settlement.

The hash-identity owner also runs every law in a second module copy whose initialization draws are all equal, so every type marker has the same hash number in any declaration order. There it checks equality verdicts, equal hashes for equal identities, cycle rejection, and a topKBatch Map-to-Set replacement; only the sampled distinct-hash control is skipped. This closes the equality type-separation witness for every generated carrier. It does not prove hash collision freedom. Generated Map keys include numbers, symbols, references, and containers, and the model merges keys under SameValueZero.

The NaN ranked-window review records an eager direct-source refinement in the pagination owner. It covers initial ascending and descending windows, two NaN tie values, an offset move, and equal, changed, and deleted source ranks. On-demand NaN rank acquisition, joined queries, and null/NaN order combinations still need public witnesses in the pagination owner before they support a broader claim.

The Angular conformance driver checks a required signal input on a real TestBed component. Angular assigns the input after field initialization, then the driver checks rendered data and exact selected IDs after initial change detection and one input change. The driver supplies the AOT-equivalent signal-input flag because this suite uses Angular's JIT test environment. It does not exercise Angular's AOT compiler, older Angular runtimes, or every scheduler cut. The same driver checks that an explicitly disabled query reports disabled and ready before effects run.

The query identity owner generates both equal and unequal primitive string pairs. Its fixed pairs also check public groupBy rows after initial publication. End-to-end subset-demand reuse is still unproven: the demand-key check observes internal identity only. The identity owner needs a subscription witness that compares public rows and acquisition counts after equivalent and distinct predicate demands settle.

The subscription callback-reentry companion kills eleven guard-deletion mutants at the named request, resource, status, replay, or retention checkpoint on the reviewed production head. It also checks that releasing a direct snapshot during an unoptimized callback or snapshot evaluation prevents publication. A combined-predicate loader case checks release by the original request predicate before the loader returns. Three guards remain for a separate code-weight review (SUBS-09): M1's generation check after loadSubset is followed by demand-membership and generation checks after cleanup removes a starting demand; M6's replaced-state check before restart setup is followed by detached-demand and replay-state checks; M8's releaseAttempted true branch was unreached in 538 focused tests and its callers remove or detach ownership before invoking adapter unload. These are bounded equivalence arguments, not permission to delete the guards without a separate review. The companion does not establish arbitrary provider callback behavior.

Row canonicalization before the result boundary now runs only for DISTINCT, which tracks visibility by selected value; removing it fails the functional projection oracle. Ordering already consolidates each key's batch before top-K state changes, and materialized relations reduce by public key. Removing the former parent-route, non-Collection source, join, grouping, ordering, and includes conditions passed the whole @tanstack/db suite and a TANSTACK_DB_ORACLE_RUNS_MULTIPLIER=10 oracle campaign. Without the keyed reduction, live-query-result-multiplicity.test.ts witnesses the output boundary rejecting a flush that changes one key by more than one row.

The Collection lifecycle publication owner checks 32 bounded histories in which cleanup interrupts nested publication deferrals and a restarted sync run later publishes or discards one or two source rows. It compares the next subscriber's exact batch when the new deferral closes, including an old handle closed before or during that deferral. The includes publication owner still needs a compiled includes witness for cleanup during a discarded source deferral, followed by a parent or child publication at its callback boundary.

The Temporal group-key oracle owns the db-ivm groupBy value boundary for the eight Temporal kinds recognized by structural hashing. It compares public group counts with fixture-defined identity classes after one input batch, including distinct and matching fresh values and a plain object with its own spoofed Temporal tag. Nested serialization controls cover records, arrays, Maps, and Sets. Incremental retractions and unsupported symbols, cycles, and mutable RegExp state are outside this owner's bounded domain. The owner uses db-ivm's established kind-and-string Temporal key domain. Alternate representations remain separate: Durations such as PT1H and PT60M form different groups even when they compare equal. The supported inputs are ordinary native Temporal values or values from one polyfill copy. A custom prototype that impersonates Temporal can still merge a plain object with a genuine value. A genuine value with a replaced prototype can split from an equal value. Both altered-prototype cases and separately loaded polyfill copies are outside this contract. The oracle still protects a plain object's own spoofed tag without a custom prototype.

The includes publication oracle now checks one held ordered repair with two public parent rows and one inline child. Its bounded history crosses a single-step row move, a private value change that returns to the prior value, and a final value change. It compares root Collection reads and subscriber callbacks with an independent sorted source Map, and checks Effect callbacks against the last callback-visible row. Its optimistic rollback histories also require the callback to be reached and compare the restored public rows and callback trace after rejection. This rejects a final-row-only check that misses a torn callback publication. The DEC-02 review record retains the RED and mutant evidence. The receiving Collection-valued owner (packages/db/tests/query/includes-collection-oracle.property.test.ts) now checks a held finite ordered child repair request with A→A, A→B→A, and B→C histories, facade identity, silence during the hold, final child order, and subscriber delivery. The optimistic owner (packages/db/tests/query/includes-optimistic-oracle.property.test.ts) checks a same-root-row optimistic update during held ordered repair, comparing exact public snapshots and change events before release, after release, and after rollback. Both use controlled provider timing; real-provider ordering remains a separate receiving handoff.

The ordinary committed-transaction companion in the SQLite resume-snapshot owner checks durable rows, row and collection metadata, expected-key evidence, tombstones, applied position, idempotent reapply, and replay threshold behavior for bounded insert, partial-update, delete, metadata-only, and repeated-key histories. Its fixed and random generated campaigns cover a two-row seed, ordered action prefixes, seven required action/metadata suffixes, optional dependent updates, and late-bookkeeping rollback, comparing durable state after each settlement. The generated grammar is bounded to two writable string keys, one absent metadata key, up to 60 prefix mutations sampled in short, middle, and long bands, three row-metadata and two collection-metadata prefix actions, and up to three committed positions; it does not claim arbitrary histories or concurrent owners. Every generated seed, candidate, dependent update, and late rollback must enter exactly one SQLite transaction; counters are captured before durable snapshot reads. A separate fixed/random generated work grammar covers 0–60 distinct keys, six insert/update/delete/row and collection metadata shapes, and 100/999 parameter caps. It checks durable values before applying the same proposed chunk-bound work law; all repeated-key histories now check a distinct-key work bound after both committed and rolled-back candidates. A fixed 205-update single-key case drops from 824 to 8 query/run calls against a bound of 18. Truncate cases require overwritten invalid row and metadata values, including unbindable undefined collection metadata, to reject and roll back. Fixed 25/26 and 10,000-row cases separately witness the independent-key work boundary. Both fixed and generated independent-key work laws were RED on ef1e6a4 and are GREEN with ordinary batching: the 10,000-row insert plus metadata takes 505 query/run calls instead of 50,005. A later 125-row-ceiling follow-up checks 124/125/126 rows under a 500-parameter host cap; the 10,000-row case now takes 405 calls. A temporary repeated-key classifier mutation fails the generated oracle at the candidate durable checkpoint, seed 1992, path 2:0:0:2:2:2:2. A temporary chunk-limit mutation passes the Cloudflare 25-row case but fails at 26 rows under the 100-parameter guard. A collection-metadata classifier mutation that ignores repeated keys fails at the durable checkpoint for a set/delete history. All mutations were restored. The Cloudflare receiving driver also persists ordinary writes with row and collection metadata at 25, 26, and 205 rows within that guard. Its Node SQLite storage seam does not establish Cloudflare Worker execution. The synthetic node:sqlite seam does not establish OPFS worker scheduling, browser latency, or native-device performance. Tagged-value serialization, unavailable key evidence after raw loss, concurrent schema migration, WAL across processes, and arbitrary longer transaction histories remain with their existing owners or need explicit future witnesses.

The SQLite resume-snapshot owner also checks a cold, unique-key, non-delete full replacement with 205 rows. It compares exact durable rows, row metadata, key-set evidence, resume metadata, and applied position at transaction return; the driver query/run count is bounded, and a later-batch fault rolls back the whole transaction. Duplicate-key and delete histories keep their sequential semantics. This in-memory driver-call law does not measure Chromium OPFS latency, worker scheduling, or an end-to-end Electric snapshot.

The Cloudflare Durable Object test applies 25-, 26-, and 205-row full replacements and ordinary writes with row and collection metadata through the actual Cloudflare driver. A storage seam enforces Cloudflare's documented 100-bound-parameter query limit and checks durable keys and metadata after each transaction. Its subset receiving witness compares exact rows for 100 and 101 equality or one-item IN clauses through both savepoint and native transaction drivers; the same seam rejects a statement above 100 bindings. The original transaction driver exceeded the cap at 101. This Node SQLite seam does not execute in Workers or prove native JSON-function support.

The browser OPFS lifecycle owner also checks that a silent initialization rejects at the default or overridden open deadline, terminates its worker, ignores a late response, and releases the deadline and abort listener after a successful open. It also checks an abort during synchronous option evaluation, after the initial signal check but before listener registration. A Chromium fixture holds the VFS database Web Lock while a second tab times out. It checks that the queued request disappears, then reopens the database after releasing the lock. This controlled lock holder does not reproduce a frozen tab or establish behavior in other browsers. The issue #1883 review record preserves the exact-head unit and Chromium evidence and the queued-lock mutant.

The ordered-work owner also checks that an Effect with skipInitial waits for joined demand before ending initial callback suppression. A deterministic work counter rejects an extra joined-filter graph schedule on root readiness while preserving the joined-source wake-up. Nonterminal per-demand failure recovery is outside this owner: failDemand enters terminal live-query error while its plan record remains unsettled until sync teardown. A future recovery contract must reconcile plan and subscription pending state before reopening publication. Its startup witness covers one synchronous rank update after an indexed page load and before the last source subscription returns. It does not cover every source ordering, multiple buffered mutations, or asynchronous startup changes. The ordered Effect startup review records its baseline and hostile-mutant observations.

The Collection lifecycle change-event history owner also checks eager auto-index equality buckets and fresh indexed eq live queries against its independent row Map. Its required same-turn delete/reinsert prefix reaches an already-built index for both BasicIndex and BTreeIndex. In the batched lane, public rows and equality buckets are checked after each mutation returns, before any transaction is awaited; the batched final state and each sequential settled prefix are also checked. Fresh indexed queries are checked at the final checkpoint. Fixed and random tails check nearby legal histories. One temporary mutant that skipped index updates failed the fixed batched final count: one indexed key versus two model rows. Another fault that preserved the final keys failed the new returned-mutation check. The direct index refinement owner does not prove this Collection mutation path. Callback-time index agreement, the reported insert-seeded string-key setup, adapter cancellation, and non-local-only persistence remain outside this lane. The issue #1912 review record records the grammar controls, exact reviewed commit, and ORC audit.

The live Electric immediate-reload witness checks one Chromium/OPFS history: an onInsert handler receives PostgreSQL transaction evidence, awaitTxId and the optimistic transaction settle while the source row's adapter write is held, and a hard page close is followed by an empty raw OPFS snapshot before the recovering Collection or Electric starts. After release, the witness checks the exact public and durable row from live Electric and records that the reopened page sent no user-insert request. Public rows are polled before durable snapshots to avoid a full OPFS read on every pre-publication tick. This bounded history does not prove Windows/Edge behavior, offline recovery, arbitrary later re-inserts, or a durable-acknowledgment contract for awaitTxId.

The PR #1914 follow-up review record preserves the held-checkpoint and extra-POST mutant results at the exact reviewed executable commit.

The PR #1902 review record also covers one-pass queued-sync cancellation, partial-update dependencies on queued source rows, and focused late-hydration cases in packages/db/tests/db-client.test.ts. Those cases cross queued adapter insert and delete with a held local mutation. The DbClient hydration authority oracle crosses applied adapter insert, update, delete, and truncate with hydration before and after the applied receipt. It includes delete/reinsert and truncate/reinsert controls. These owners do not establish arbitrary hydration stream order, a later authoritative hydration epoch, or unbounded retention.

The two-tab OPFS remote-subset oracle now exercises a real Chromium follower with a QueryClient-backed, filtered on-demand live query. It checks the function-bearing local request, clone-safe follower post, public row, and rejection of an invalid nested wire value before transport. A raw-options mutant fails with browser DataCloneError. The review record names the exact reviewed commit. The test does not run React, Firefox/Zen, or a live backend, and it does not settle exclusive OPFS ownership during leadership transfer.

The two-tab live Electric OPFS oracle crosses real Chromium tabs, Web Locks, OPFS workers, PostgreSQL, and the installed Electric SDK. It checks distinct per-Collection schema versions, unchanged public and durable rows when a follower opens, leadership transfer with later source rows, and recovery of partial-row loss or a fully empty pre-key-ledger baseline with a stale resume marker. A wrapped source-commit test in packages/browser-db-sqlite-persistence/tests/browser-coordinator-oracle.test.ts checks scheduler entry before the writer-lock request; the old bypass fails at that order assertion. The live recovery histories also guard the resulting progress. These bounded histories do not prove Firefox/Zen, React rendering, React Native, arbitrary large datasets, or an exclusive-OPFS ownership topology. Their review record preserves the RED and GREEN host observations.

The live Electric hydration-straddle oracle owns one #1754 host history: an on-demand Collection has an initial durable row; an OPFS subset hydration is held after its local read; a PostgreSQL update begins an Electric source transaction during that hold; and the row-bearing commit is released only after the hydration scope exits. It checks the old row before release and the exact new public and durable row afterward, then after follower takeover and reopen. A late-buffer mutant leaves the old row in both observations. The core persistence tests own the adjacent during/straddling/after settlement, FIFO, abort, and failure histories. The live oracle does not prove eager-startup overlap, other mutation shapes, arbitrary Electric fetch schedules, Firefox/Zen, React rendering, or exclusive OPFS ownership. The review record preserves the live-host and mutant evidence.

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 is owned by state retention and its focused truncate-capture ownership refinement. They vary 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. The state-retention owner also crosses both accepted-delete/dependent-edit settlement orders with reinsert success or failure, with and without truncate. Its public row and change-message checks run after every step. These eight histories do not establish every ordering of the insert outcome relative to sibling settlement or an arbitrary later source acknowledgement. The PR #1907 review record preserves the exact RED/GREEN evidence and reviewed commits.
Issue obligationImplemented evidenceLimit
Metamorphic lawsIncludes cross-formulation/partition, D2 independent-key commutation, DBSP incremental/full recomputation, pagination provider/UI boundaries, optimistic snapshot stabilityEquivalence premises are explicit; not arbitrary query rewrites.
Public observationsReads, exact event payloads and reconstructed state, observer eligibility, downstream includes, lifecycle and ownership checksCount/work budgets are separate from row truth and only pin established promises.
Meaningful async historiesApplied receipts, truncate/replay, cleanup/restart, pending optimistic work, held provider completion, leadership lossControl real causes; unsupported SDK traces receive no coverage credit.
Checker sensitivityFaulty output controls, missing/duplicate events, stale completion/ownership controls, forced collisions and pre-fix runtime witnessesSetup failures and timeouts are recorded separately from assertion kills.
Executed reach and replayNamed manifest with guarded replay, finite boundary products, pinned examples, fixed/random lanes and explicit stress runsRoot test:oracles is a selected core/Query DB campaign, not all repository oracles.
Contract and scope recordsGuide, companion case notes, this map, suite-local law/domain comments and architectureThis is an executable testing method, not a completeness proof or new product specification.

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
pnpm --filter @tanstack/db-sqlite-persistence-core build
pnpm --filter @tanstack/node-db-sqlite-persistence 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-oracle.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.

The Node expression-index oracle runs matching fixed-seed and seedless-random campaigns by default. Supplying both replay values selects only the requested seed and shrink path:

TANSTACK_DB_WS5A_SEED=1659005 TANSTACK_DB_WS5A_PATH=0 \
pnpm --filter @tanstack/node-db-sqlite-persistence test:oracles

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.

Reusable-law backlog

RFC #1659 reviews found several green oracles whose stated laws remained valid but whose fixtures, grammars, or observations did not cover a neighboring boundary. Track the generalized repairs here instead of accumulating isolated regressions. Completion requires an executable owner, a production-path witness, a hostile wrong-answer control, and an explicit statement of remaining limits.

  • Optimizer residual convergence beyond the checked paths. The optimizer-semantics owner now checks sourceWhereClauses, source-free predicates, namespace-only predicates, later RIGHT/FULL join nullability, and an ordered QueryRef refusal at structural checkpoints. It still needs public-row witnesses for later RIGHT/FULL chains, residual checks for aggregate, functional, and projection-remapped QueryRef refusals, a separate UNION branch model, and incremental source/publication histories. Owner: packages/db/tests/query/optimizer-semantics-oracle.test.ts and its production compiler driver. Each extension needs a distinguishing wrong-plan control at the relevant checkpoint.

  • Real-provider conformance fixtures. Frozen 15.2.7 React Native and Node receipts cover the supported peer version; 18.2.1 React Native, Node, and browser receipts cover the known forward shapes. Exact-row checks and a row-dropping hostile control prove the shim accepts those envelopes without mutating them. Owner: packages/react-native-db-sqlite-persistence/tests/fixtures/op-sqlite-provider-results.ts and packages/react-native-db-sqlite-persistence/tests/op-sqlite-driver-oracle.test.ts. Native device/host execution remains a separate runtime receipt.

  • Minimal ambiguity and name invariance. Generate one-field and otherwise minimally distinguishable results. Renaming a selected column to a structural-looking alias must not turn a data row into a write envelope. Owner: packages/react-native-db-sqlite-persistence/tests/op-sqlite-driver-oracle.test.ts.

  • Carrier coexistence and representation symmetry. Cross rows, rawRows, columnNames, and supported result containers, including legal coexistence. Equivalent array and object forms must agree on rows or on the documented rejection. Owner: packages/react-native-db-sqlite-persistence/tests/op-sqlite-driver-oracle.test.ts and the shared SQLite driver contract.

  • Shared-handle transaction admission. Concurrent driver wrappers for one provider database handle serialize root transactions. Nested work must use the transaction driver supplied to the callback on hosts without async context propagation. Owners: packages/node-db-sqlite-persistence/tests/node-driver.test.ts and packages/react-native-db-sqlite-persistence/tests/op-sqlite-driver-oracle.test.ts.

  • Transitions at every relevant await. Hold each coordination boundary, then change leadership, remote-subset ownership, abort state, cleanup, or restart generation before release. Owners: browser/electron coordinator, persisted-history, and collection cleanup/restart oracles.

  • Local-versus-transport refinement. Compare local-leader and transported remote-subset behavior for immutable values. Separately prove that local signal and subscription references survive delivery and reach matching unload cleanup. Owners: browser/electron coordinator and persisted-history suites.

  • Partial-construction cleanup. Fail database, driver, worker, and subscription construction after each acquired resource. Preserve the primary failure while proving all acquired resources are released exactly once. Owners: OP-SQLite driver-contract construction and OPFS page/worker lifecycle suites.

  • On-demand persistence after evidence changes. Cross baseline versus on-demand hydration with consistent, unknown, and incompatible key-set evidence. A baseline certification failure must not silently erase valid on-demand rows. loadSubset checks baseline visibility and on-demand rows; the sync-absent forceReloadSubset route crosses the same startup evidence states but records baseline visibility as unobserved because that API does not expose baseline hydration. Owner: packages/db-sqlite-persistence-core/tests/persisted-oracle.test.ts.

  • Deterministic value-and-work laws. Pair row correctness with stable statement, scan, trigger, or queue-cardinality observations where the subsystem promises bounded work. Owners: SQLite resume snapshots, Electric acquisition work, shared-driver scheduling suites, and the Node same-database-handle admission law.

  • Startup generation interleavings. Hold persisted startup between its metadata and hydration snapshots, then cross no write, a managed mutation, and hostile raw loss. Compare public rows with the atomic durable snapshot, and require mutation persistence to wait until the prior stream position is known. Owners: SQLite resume snapshots and Electric resume snapshot races.

  • Schema-generation fences on cached adapters. Cross a newer-schema reset with snapshot, row, metadata, delta, position, and index-lifecycle operations from the cached older adapter. Every stale operation rejects; the current adapter remains readable and its index registry remains intact. Owners: SQLite resume snapshots plus browser/electron coordinator routing.

  • Explicit omission records. Add a short Known omissions section to each primary executable owner touched above and keep this map synchronized as laws land. An omission record narrows evidence; it does not waive a product obligation.

  • Atomic active-subset full reload. Load collection metadata and every active subset from one adapter generation, including filtered and paginated on-demand subsets. A sound implementation needs an atomic multi-subset API; loading all rows or accepting a metadata/row torn pair is not equivalent. RED evidence and the deferred executable placeholder live in packages/db-sqlite-persistence-core/tests/persisted-oracle.test.ts under R5-007.

  • Joined aggregate and singleResult subquery histories. packages/db/tests/query/subquery-user-value-oracle.test.ts checks flat and nested aggregate source changes and joined findOne() QueryRefs at initial and later public checkpoints. The bounded histories and remaining forms are recorded in the QueryRef owner row above.

Persisted readiness and network-first initial rendering

The persisted-readiness oracle in packages/db-sqlite-persistence-core/tests/persisted-readiness-oracle.test.ts owns the opted-in eager restore boundary through the persisted wrapper, Collection, live query, and observer. A finite two-source model checks all 36 opt-in/outcome combinations independently of the observer classifier. Its controlled persistence histories check nonempty and empty restore while upstream remains pending, all-source conjunction, mixed opt-out, nested live-query sources, exact failure, SSR seed handoff, stale cleanup/restart work, an already-restored source, a network-first deadline, early network success and failure, network failure before nonempty restore, client query stream failure before or after empty and nonempty restore or before observer construction, joined-source deadline composition, and a derived-query error alone or alongside a failed client stream that must not be mistaken for network failure. It checks a separate initial-render wait that leaves network preload() unchanged. The framework conformance suite checks the projected signals in React, Vue, Svelte, Solid, and Angular, including exact identity for a plain-object restore error after notification. The window-controller test checks infinite-query projection, and focused React and Solid tests check Suspense gating. The React tests check client-stream failure before and after completed empty and nonempty restore, including a failed record already present before mount. They also check error-boundary handling for derived-query failures with and without a failed client stream. A replacement client record arriving during an initial-render wait has no persisted-fallback witness yet. This owner uses a controlled persistence adapter, not native SQLite or a real network provider; it does not prove browser scheduling or arbitrary histories. The framework identity scenario does not cover every possible rejection value or an error already present before a hook mounts.

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: the executor holds caller success until deletion is acknowledged, and a persisted deletion-pending phase prevents provider replay after a known deletion failure. Controlled restart and adapter-failure witnesses cover that boundary. A crash before the phase write, old readers of marked rows, physical power loss after adapter acknowledgement, and native browser restart or multi-owner handoff remain open. Provider idempotency is required to avoid a repeated effect in the first two cases.
  • A10 R4: Issue #1939 is owned by the leadership replay oracle. The action grammar crosses retained leadership, loss before invocation, and loss during or just after onMutate after offline selection; a manual transaction loses leadership after its optimistic mutation and before commit(). The original action path fulfilled with no outbox record or provider call. The repaired paths reject and roll back; retained-leader and before-invocation controls still fulfill. Later leadership changes and a held outbox write crossed with loss or regain remain for this leadership oracle, using controlled write settlement and caller checkpoints. The IndexedDB write-settlement owner still needs a browser-host composition with leadership loss across a write. These paths are outside this bounded repair. The review record preserves the RED/GREEN and checker-calibration evidence.
  • A10 R5/R9: manual removal/clear outside the active-provider witnesses, restored optimistic lifetimes, and retry-hook failures remain open. The settlement owner checks terminal provider rejection with failed deletion, a halted executor with queued peers held, and restart without a second provider call or optimistic restore. The executor does not automatically retry a failed phase write or deletion. A failed terminal marker write followed by a crash remains an unmarked replay window. Broader offline retry and recovery policy remains with RFC #1659.
  • 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.