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.
| Surface | Status | Completed or next owner |
|---|---|---|
| Ordered relations and BTree | Complete | The signed top-K relation, BTree/Map refinement model, and DBSP incrementalization laws are literate. |
| D2 operator work | packages/db-ivm/tests/d2-work-oracle.test.ts | A 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 publication | Complete | The 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 lifecycle | Complete | The shared logical-owner/acquisition-attempt/sync-run grammar plus mutation admission, lifecycle trace, publication, replay, disposal, and transaction-refinement boundaries are literate. |
| Paced mutations | Partial | The 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 state | Complete | The independent base/intent/source-queue graph plus outcome, transaction-payload, and publication drivers are literate. |
| Drafts and native values | Complete | Native 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 observer | Complete | Query-scope row ownership, subset identity and cancellation, failure and recovery, and the per-listener eligibility ledger are literate. |
| Query DB SSR dehydration | Fixed QueryClient/Seroval boundary | Successful 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 acquisition | Complete | Exact 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 filtering | Complete for bounded dotted-path collision | An 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 publication | Complete for bounded predicate and sync-transaction grammar | The 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 keys | Complete for bounded two-source key grammar | The 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 storage | Complete for bounded prefix grammar | The 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 queries | Complete for bounded eq-filter grammar | The 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 tracking | Complete for bounded flat-row grammar | Flat 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 identity | Focused compiler boundary | A same-source union/coalesce witness keeps dotted and nested demand paths distinct during target deduplication. |
| Correlated include path identity | Focused public route-context witnesses | One-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 identity | Generated cross-scope alpha-renaming with an independent model | Optimizer 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 acquisition | Complete | Independent cold relational recomputation, acquisition evidence, established equality domains, replacements, and scan/index routes are literate. |
| Opaque backend pagination | Complete | The full-relation value model plus opaque token, cache generation, publication, browser acquisition, and live-window integration owners are literate. |
| Electric and TrailBase | Complete | Electric 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. |
| PowerSync | Complete | Patch 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 hosts | Complete | Persisted 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 execution | Complete | FIFO retry, scheduler eligibility, leadership replay, transaction settlement, and typed wire serialization are literate. |
| Frameworks | Complete | Shared live-query and infinite-query models are literate. Each framework keeps its own realm, ownership, and scheduling driver. |
| Structural values and ordered primitives | Complete | Structural hashing, deep equality, comparison, cursor denotation, index refinement, and query-identity output equivalence are literate. |
| Boundary refinements | Complete | Cleanup/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 mechanics | Complete | SortedMap, 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.
| PR | Classification | Permanent authority and campaign |
|---|---|---|
| #1831 | Explicit oracle | PowerSync'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. |
| #1832 | Equivalent specialized authority | packages/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. |
| #1833 | Explicit oracle | packages/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. |
| #1834 | Explicit oracle | packages/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. |
| #1835 | Explicit oracle | The 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. |
| #1837 | Explicit oracle | The 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. |
| #1842 | No shipped-law case | The 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.
| Surface | Primary executable owners | Independent judgment and important limit |
|---|---|---|
| Ordered relations and BTree | top-K relation oracle, fractional-index window moves, BTree/Map, incrementalization laws | Independent 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 publication | cross-formulation, temporal, Collection includes, architecture and complete suite map | Per-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 lifecycle | mutation startup, change-event history, history, publication, replay, effect disposal, PR #1902 review, batch-order decision review, absent-key insert review | Core 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 mutations | virtual-clock oracle | createPacedMutations 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 state | history model, generated histories, truncate capture ownership, outcomes, publication | Independent 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 values | proxy, detachment, iteration, revert, native methods | Native-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 observer | ownership, load lifecycle, observer histories | Real 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 dehydration | packages/query-db-collection/tests/ssr-dehydration-oracle.test.ts, review record | A 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 acquisition | pagination, 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 review | Complete 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 filtering | packages/db/tests/query/index-path-collision-oracle.test.ts | A 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 identity | packages/db/tests/query/compiler/lazy-targets.test.ts | A 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 identity | packages/db/tests/query/includes-context-transport-oracle.test.ts | A 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 identity | packages/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 review | Four 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 acquisition | packages/db/tests/query/cold-join-reconciliation-oracle.test.ts | Independent 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 semantics | packages/db/tests/query/optimizer-semantics-oracle.test.ts, aggregate review, QueryRef repair, residual review | Independent 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 boundaries | packages/db/tests/query/subquery-user-value-oracle.test.ts, packages/db/tests/transactions.test.ts, repair record | A 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 pagination | window oracle, cache histories, cache publication, browser acquisition boundaries, QueryCollection integration | Full 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 TrailBase | Electric histories, recovery histories, held resume snapshots, PostgreSQL semantics, TrailBase contract | Installed 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. |
| PowerSync | tests, tests/correctness-oracle.test.ts | Applied 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 hosts | persisted 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 manifest | Core 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 planning | Node expression-index oracle | RFC #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 execution | scheduler, leadership, settlement, serialization, web connectivity replay, review record | Declarative 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. |
| Frameworks | React conformance, React pagination, shared suites, Vue synchronous publication | Exact 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 overlap | shared infinite-query conformance, React driver, Vue driver, Svelte driver, review record | Four 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 primitives | hash values, hash identity, MultiSet consolidation, hash graphs, mixed hash graphs, hash retry, comparison, deep equality, cursor, indexes, BTree Map, query identity, LIKE semantics | Independent 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 publication | WHERE predicate publication oracle | An 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 keys | Joined result key oracle | A 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 storage | Index refinement oracle | A 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 queries | pooled live query oracle | An 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 tracking | flat change tracking oracle | Generated 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 cache | cache laws | Focused 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 writes | direct write witnesses | Focused 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 objects | reused row witness | Focused 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 suggestions | collection-size suggestion oracle | A 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 API | consumer bundle check | CI 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 refinements | cleanup/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 work | Explicit 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 mechanics | SortedMap, cleanup queue, live-query GC clock, guarded replay | Map/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 Query ownership oracle enumerates five controlled persisted-refetch
overlaps after initial load: a committed metadata-only transaction before
Collection publication followed by a newer refetch, direct writeUpsert, or
mutation-handler writeUpsert; and a row transaction before durability
followed by a newer refetch or direct writeUpsert. It checks the latest
public receipt, public and stored rows, and the Query Collection error ledger.
Adjacent controls cover precommit cancellation and cleanup fencing. With the
Query result controller's post-commit supersession guard, refetch and direct
write successors pass before publication and durability. Both before-publication
mutation-handler schedules now settle: an immediate write queued before the
older normal source reaches core and one queued after it begins waiting both
release the older publication without overtaking its durable write. They
require fulfilled awaited handler receipts and durable revisions in
one, two, three order. The controlled adapter records distinct durable revisions,
collapsing adjacent duplicate writes of the same value.
Two additional before-publication refetch histories replace the held result's
row key with either the same key and a new value or a different key. They
require the latest public and durable row set at the successor receipt. These
witnesses exposed stale ownership when a superseded committed row was absent
from syncedData; preserving its staged ownership and deleting by key makes
both pass.
An on-demand subset-release witness supersedes a persisted source commit while
publication is held, then retires its logical demand. It checks rejection of
the older applied receipt and absence of public and durable rows. The same
request object drives load and release. Multiple logical owners for the same
query key and native SQLite cancellation remain outside this witness.
The persistence owner holds an earlier source publication until a later
immediate source write is queued, on both sides of the wrapper's publication
wait. A listener failure on the earlier batch must not reject the later write;
a faulting index before receipt settlement still rejects the dependent write.
The index-fault history crosses both drain orders. It checks that the earlier
claimed source receipt rejects with the same fault instead of remaining pending,
that the dependent mutation rejects, and that its row is absent from Collection
and durable storage. It does not prove rollback of partially applied core state
after an arbitrary index implementation throws.
A two-handler Query history holds the first durable write, then starts a second
mutation on the same row. It checks four pending receipts, durable revisions in
accepted one, two, three order, the latest Query cache and Collection row
after settlement, and the row after an explicit refetch. The wrong-order
one, three, two control fails its order check. This controlled adapter
does not establish Expo SQLite scheduling or every multi-action interleaving.
It also does not establish cache and Collection reconciliation after a durability
rejection that follows publication, repeated writes, and lifecycle restart;
the persistence and Query ownership owners need that recovery witness.
Precommit cancellation and cleanup controls pass. Each history has its own Collection identity and an exact
adapter commit-count check at the hold. The controlled adapter
establishes these cuts; it does not establish native SQLite or Expo scheduling.
The Node persistence owner now checks an awaited immediate source write behind
a pending normal source write with real better-sqlite3 and exact public and
durable rows. The reported two-refetch schedule still needs a Node receiving
witness; Expo's asynchronous SQLite host also needs one. The Query result-settlement owner
models an accepted refetch result retired before publication by cleanup and
compares the public promise at source-commit and cleanup checkpoints. This
corrected control passes: the row-2 source receipt and throwing refetch both
reject with AbortError, cleanup fulfills, and durable row 1 remains. An
earlier diagnostic was falsely red because it captured adapter commit #2,
which writes metadata only, before the row-2 source commit was accepted; the
new reach check requires the pending commit to contain row 2.
The row-durability mutation-handler cell has a separate bounded two-case Query notification model. Holding observer notifications through mutation settlement leaves the accepted optimistic snapshot public while both handler receipts fulfill and durable row 3 is stored. Delivering a new row-3 Query result during the handler retires the predecessor result controller while its accepted source commit continues; queued publication retires the snapshot, so public and durable rows are 3 after the receipts settle. An explicit refetch restores row 3 after held notifications are released; the intermediate replay of those notifications is not modeled. These two controlled schedules pass the optimistic-history settlement law. The adapter's commit #3 alone did not distinguish them. Other handler schedules and native SQLite receiving witnesses remain unproven.
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.
SQLite boolean predicate arity and row work#
packages/db-sqlite-persistence-core/tests/sqlite-boolean-arity-oracle.test.ts
is the primary executable owner for bounded and/or predicate arity at
SQLiteCorePersistenceAdapter.loadSubset return. Its independent three-valued
model compares public keys while a node:sqlite driver records SQL and raw row
work. The 960-case matrix and paired fixed and unseeded campaigns cover root
arity 0–3, one nested operator, boolean and nonboolean operands, safe selective
predicates, and sound candidate supersets for unsafe predicates. Eight direct cases challenge Unicode ilike
and like patterns, tagged NaN comparison, lone-surrogate equality, and
null-vs-missing under not. Paired- and lone-surrogate equality controls
retain SQL row-work reduction.
An empty-IN control and two-SELECT cursor composition check zero-row work.
The original compiler was RED for unary and empty boolean work and multioperand
under-selection. The first repair was RED for unsafe SQL prefilters: Unicode
case folding, an emoji spanning two JavaScript code units, tagged NaN, and
null-vs-missing under negation. A later lone-surrogate equality witness was RED
for public rows and SQL work. The compiler now applies SQLite JSON extraction
to the matching binding; paired and lone surrogates both keep indexed equality.
The current compiler passes the bounded oracle.
A removed-WHERE mutant fails the raw-row work law and a blind-unary mutant
fails public rows. For this grammar, SQL pushdown admits every row that the
in-memory evaluator could retain; a statically false AND may read zero rows
even with an unsafe sibling.
Mixed-AND witnesses retain a certified equality while an unsafe range, NOT,
or OR sibling stays with the row evaluator. They cover child order and one
nested AND, measure one raw row instead of twenty, and reject a removed-WHERE
mutant. The unsafe OR mutant loses a public row.
A fixed 80-level nested AND witness bounds compiler argument reads to linear
work. It was RED on the prior quadratic compiler and is GREEN after removing
the repeated subtree compilation; elapsed latency and arbitrary depth remain
outside this owner.
TimFL's 50,582-string-ID AND(OR(IN, IN)) scope was RED for SQL row work:
the adapter returned the right public row but read all 20 stored rows. A fixed
real-SQLite witness now checks the public result, exact candidate count, two
bound JSON arrays, and use of both named expression indexes. It includes
lone-surrogate, NUL, and paired-surrogate string members. Mixed-type lists,
other SQLite hosts, and elapsed-time gains remain outside this witness.
The Node expression-index oracle checks the receiving SQLite query, raw
candidate keys, public keys, and named-index plan. Its generated indexed
grammar uses string equality, BigInt membership, numeric range, and string
conjunction. Focused Date-epoch witnesses keep numeric equality and numeric
membership on the JavaScript fallback path: a stored Date(1) matches numeric
1 in the row evaluator but is ISO text in the SQLite expression index. Fixed
lower-wrapped BigInt membership and lone-surrogate coalesce witnesses also
retain fallback: SQLite converts the former to text and encodes the latter's
inline fallback differently from a JSON-extracted binding. Integer-bound
range cases include adjacent fractional values and tagged or mixed scalars;
this is bounded evidence, not a proof over every persisted representation.
Large Number versus BigInt range cases check both operand directions, four
inequalities, and unary boolean wrappers. Unsafe BigInt bounds admit a wider
candidate range over the indexed expression for potentially rounded Numbers; JavaScript still
decides the public result. Numeric-key object and array cases check public
rows and named-index use through three digit segments, including mixed
carriers. Deeper numeric paths use an unbounded candidate read. Unicode
lowercase cases place NUL before and after a fold and keep the matching row
through either equality direction and unary wrapper.
The receiving Node plan uses the named index for the selective BigInt range
orientation in both operand orders. The opposite orientation can scan because
its candidate union also admits text and rounded Numbers; this oracle makes no
constant-index-use claim for that branch.
Fixed strftime, add, and Date-range witnesses also use full reads for mixed
stored types; direct SQL would exclude a matching numeric timestamp or string
concatenation. A typed-field contract or a separate indexed representation is
needed before those forms can gain a generally sound selective candidate.
The owner does not establish arbitrary depth or arity, every equality or LIKE pattern, limit/offset after filtering, all cursor shapes, order or value/metadata semantics, index-expression compilation, native hosts, OPFS, or multi-process execution. The existing SQLite owners above retain their separate reset/resume, order, driver, and host contracts. Broader class closure needs witnesses at those remaining paths.
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
Fileconstructor. - 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 obligation | Implemented evidence | Limit |
|---|---|---|
| Metamorphic laws | Includes cross-formulation/partition, D2 independent-key commutation, DBSP incremental/full recomputation, pagination provider/UI boundaries, optimistic snapshot stability | Equivalence premises are explicit; not arbitrary query rewrites. |
| Public observations | Reads, exact event payloads and reconstructed state, observer eligibility, downstream includes, lifecycle and ownership checks | Count/work budgets are separate from row truth and only pin established promises. |
| Meaningful async histories | Applied receipts, truncate/replay, cleanup/restart, pending optimistic work, held provider completion, leadership loss | Control real causes; unsupported SDK traces receive no coverage credit. |
| Checker sensitivity | Faulty output controls, missing/duplicate events, stale completion/ownership controls, forced collisions and pre-fix runtime witnesses | Setup failures and timeouts are recorded separately from assertion kills. |
| Executed reach and replay | Named manifest with guarded replay, finite boundary products, pinned examples, fixed/random lanes and explicit stress runs | Root test:oracles is a selected core/Query DB campaign, not all repository oracles. |
| Contract and scope records | Guide, companion case notes, this map, suite-local law/domain comments and architecture | This 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.tsand 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.tsandpackages/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.tsand 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.tsandpackages/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
signalandsubscriptionreferences 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.
loadSubsetchecks baseline visibility and on-demand rows; the sync-absentforceReloadSubsetroute 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 omissionssection 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.tsunder R5-007.Joined aggregate and
singleResultsubquery histories.packages/db/tests/query/subquery-user-value-oracle.test.tschecks flat and nested aggregate source changes and joinedfindOne()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-pendingphase 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
onMutateafter offline selection; a manual transaction loses leadership after its optimistic mutation and beforecommit(). 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.