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

oracle-coverage.md

540 lines68.5 KB

Oracle coverage and closeout

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

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

Scope of the oracle repair project

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

Literate model audit

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

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

The command includes tracked and untracked package files so an in-progress audit cannot hide a new owner. A surface is complete only when each primary owner states its contract, model, history grammar, production driver, and refinement check—including its public observations and checkpoint—in the executable file. Focused regressions outside that inventory may remain short, but a file named oracle or property cannot use that allowance to omit the literate structure.

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

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

SurfaceStatusCompleted or next owner
Ordered relations and BTreeCompleteThe signed top-K relation, BTree/Map refinement model, and DBSP incrementalization laws are literate.
Includes and publicationCompleteThe central recomputation model plus cross-formulation, temporal demand, layered publication, Collection facade lifecycle and space bounds, route-context transport, functional projection, query-shape, optimistic, and source-work owners are literate. They keep the architecture document as their contract source.
Collection lifecycleCompleteThe shared logical-owner/acquisition-attempt/sync-run grammar plus mutation admission, lifecycle trace, publication, replay, disposal, and transaction-refinement boundaries are literate.
Paced mutationsPartialThe virtual-clock owner checks queue order, bounded admission, cleanup draining in FIFO/LIFO order at the configured wait, admitted writes after separate Collection cleanup, post-cleanup queue rejection with a disposal reason, pending debounce drain at the last call's quiet edge, pending trailing throttle drain at its regular edge, debounce and throttle edge options including omitted options, immediate rejection of dropped leading-only calls and both-disabled calls, caller-option immutability, and settlement. New debounce/throttle admission after cleanup, failed persistence, and broader generated schedules remain open.
Optimistic stateCompleteThe independent base/intent/source-queue graph plus outcome, transaction-payload, and publication drivers are literate.
Drafts and native valuesCompleteNative differential behavior, draft change tracking, detachment and its class-instance exception, hostile keys, aliases, cycles, and Map/Set live iteration are literate.
Query DB and observerCompleteQuery-scope row ownership, subset identity and cancellation, failure and recovery, and the per-listener eligibility ledger are literate.
Ordered acquisitionCompleteExact demand identity, applied settlement, independent pagination recomputation, request work, lifecycle products, replay authority, source-generation readiness, and transaction-refinement abort boundaries are literate.
Indexed predicate filteringComplete for bounded dotted-path collisionAn independent row filter checks direct predicates and public callback predicates for a dotted scalar field beside a nested path, with and without an index. Selected-field ordering checks the same distinction through $selected.
Lazy target path identityFocused compiler boundaryA same-source union/coalesce witness keeps dotted and nested demand paths distinct during target deduplication.
Correlated include path identityFocused public route-context witnessesOne-level and nested includes keep dotted and nested parent paths, including ancestor aliases, distinct. Conditional result paths receive separate routes. Fixed fixtures cover initial reads and selected source updates; other recursive source forms and arbitrary path segments remain outside this witness.
Join equality and cold acquisitionCompleteIndependent cold relational recomputation, acquisition evidence, established equality domains, replacements, and scan/index routes are literate.
Opaque backend paginationCompleteThe full-relation value model plus opaque token, cache generation, publication, browser acquisition, and live-window integration owners are literate.
Electric and TrailBaseCompleteElectric replica and recovery models, installed-SDK HTTP delivery, PostgreSQL serialization, and TrailBase's controlled RecordApi/native-stream lifecycle are literate with their real-provider limits intact.
PowerSyncCompletePatch conservation, effective-update receipts, metadata and falsey changes, declared-view keys, transformed schema output, logging, cleanup, and native SQLite reach are literate.
SQLite persistence and native hostsCompletePersisted hydration/replay and ownership, shared-handle driver transaction laws, OPFS page and diagnostic state machines, and the 113-law native conformance manifest are literate. Native execution remains distinct from registration and shim evidence.
Offline executionCompleteFIFO retry, scheduler eligibility, leadership replay, transaction settlement, and typed wire serialization are literate.
FrameworksCompleteShared live-query and infinite-query models are literate. Each framework keeps its own realm, ownership, and scheduling driver.
Structural values and ordered primitivesCompleteStructural hashing, deep equality, comparison, cursor denotation, index refinement, and query-identity output equivalence are literate.
Boundary refinementsCompleteCleanup/restart admission, metadata publication, retained state, acquisition cells, D2 source reconciliation, top-K support windows, and nested Query work bounds are literate.
Small structures and test mechanicsCompleteSortedMap, cleanup appointments, and guarded replay are literate.

Recent fix-wave authority inventory

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

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

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

Find an owner

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

SurfacePrimary executable ownersIndependent judgment and important limit
Ordered relations and BTreetop-K relation oracle, fractional-index window moves, BTree/Map, incrementalization lawsIndependent ordered relations and cumulative signed output. Top-K consolidation compares same-key values without hashing, including cyclic replacements and fresh transient cancellation. The fractional-index test checks an empty output message for a window move after all rows retract; it does not prove downstream lazy acquisition. Other hash-based operators retain hashing's declared domain. Algebra does not specify client readiness.
Includes and publicationcross-formulation, temporal, Collection includes, architecture and complete suite mapPer-parent/flat-join/partition relations, callback-time rows, nested values, and route histories. Fragmented lazy-demand consolidation covers delta growth and successful, rejected/retried, and obsolete replacements at the Collection request boundary; it observes exact key unions and abort checkpoints. A compiled-includes fixture makes adapter unload evict owned child rows and proves a rejected union cannot remove established public child rows. Retry after that terminal live-query failure remains covered at the acquisition boundary; no automatic in-place recovery is claimed. Observe raw promised order; fresh queries do not establish continuous publication safety.
Collection lifecyclemutation startup, change-event history, history, publication, replay, effect disposal, PR #1902 review, batch-order decision reviewCore Collection insert/update/delete admission while startSync:false is idle; complete public-row/change-message agreement across bounded one- and two-key histories plus replayable four-key campaigns; a two-key deferred sync history checks each key's causal insert/update/delete trace while allowing any cross-key interleaving. Reversing all deferred messages fails that check; reversing each sync transaction's distinct-key messages passes. Queued duplicate admission and cancellation, ownership and phase histories, exact caller/error/publication evidence, and late completion and restart have separate witnesses. Generated deferred histories with cancellation or reentrant callbacks need a witness in the change-event history owner before claiming general batch-shape coverage. Query write utilities and effect self-dependent disposal remain separate contracts.
Paced mutationsvirtual-clock oraclecreatePacedMutations with queue front/back options, bounded waiting capacity at zero and one, cleanup draining in FIFO/LIFO order after a held write, cleanup timing at the configured wait for immediate writes, admitted writes after separate Collection cleanup, debounce and throttle schedules with explicit and omitted options, and first-leading throttle execution at epoch zero. Finite histories compare optimistic rows, returned transaction identity and receipt outcome, execution order and virtual-clock time. Held writes verify queue serialization. Leading-only throttle and debounce witnesses reject skipped calls immediately with their named dropped-call errors, including omitted edges, both edges disabled, and same-row rollback while a prior write is held. Capacity witnesses cover overflow rejection, distinct-key optimistic rollback, same-key admitted-write survival, and in-flight versus waiting admission. Cleanup witnesses check repeated queue cleanup, eventual admitted receipt settlement, direct queue strategy rejection of new callbacks, public post-cleanup rollback with QueueDisposedError, pending debounce transactions that wait until the last call's quiet edge after separate Collection cleanup, and a trailing throttle timer that runs at its regular edge after separate Collection cleanup. Deferred custom queue and batch callbacks check compatibility with void and false execute results, respectively. Frozen options verify factory non-mutation; a mutable option witness checks that debounce uses its construction-time trailing setting. New debounce/throttle admission after cleanup, failed persistence, broader capacities and schedules remain outside this owner.
Optimistic statehistory model, generated histories, truncate capture ownership, outcomes, publicationIndependent whole-row snapshots, rollback dependencies, captured truncate ownership, metadata and prior-value events. Never rebase a pending snapshot merely to simplify the model.
Drafts and native valuesproxy, detachment, iterationNative-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.
Query DB and observerownership, load lifecycle, observer historiesReal QueryClient boundary, applied-settlement barriers for existing and cached demand, mutation-handler Collection identity, terminal fetch-record lifecycle, and a per-listener eligibility ledger, not a duplicate dispatch queue. The bounded handler grammar crosses insert, update, delete, parameter and mutation-alias access, refetch, and clearError. A held clearError retry retains the prior public error through initial, background, and Collection application failures; success clears it, failure advances the count, including a repeated error at clock time zero. An intermediate Query retry attempt does not recount the previous background error; a held final attempt can succeed or fail. A held application after successful Query fetch keeps the error visible until the applied result. A mocked persisted-baseline scan holds an older success while a newer terminal Query failure arrives; the newer public error and count survive application, including when the Error object and clock tick repeat. Native SQLite persistence, concurrent retries across multiple tracked Queries, mutation-handler fetch-boundary settlement, and deferred result application remain outside this witness. The mutation overlap grammar crosses both start orders. Check reentry, peer survival, FIFO and disposal independently of final rows.
Ordered acquisitionpagination, ordered work, ordered lifecycle, ordered loader state, graph scheduler, issue #1880 ordered-repair review, issue #1882 custom local collation review, issue #1898 relation-filter review, PR #1909 external reviewComplete finite provider results, inherited locale and bounded/unbounded custom collation with exact request options, query-level inheritance across source aliases, real lexical/numeric disagreement, custom comparator ties, scan/index paths, pending windows, ties/nulls, lease ownership, Effect callback gates, including an indexed source update during Effect startup, and documented repair timing. Direct LEFT-joined filters cover local finite prefixes, pending child demand, child removal, and anti-join publication with custom full-source and unindexed fallback loading; unrelated include demand cannot stall the root continuation, and an empty joined replay wakes held Effect callbacks; remote relation hints remain outside this owner. Graph scheduler checks coalescing, dependency order, synchronous loader input, and repeated-alias failure ownership. The ordered-work oracle checks that a synchronous root refill reaches D2 before joined publication; a mutant that omitted the post-loader graph step failed at the second child demand. Custom collation proves local full-source acquisition only; it does not establish provider cursor capability or backend collation fidelity. Sibling-source input during a synchronous ordered continuation returns to graph work before another ordered acquisition. Request completion is not proof of unrequested source extent. A window move during existing joined demand waits for its root continuation, including an independently held root request; current demand failure rejects the move, while retirement and an obsolete rejection do not. A bounded ordered repair resumes its refill after joined demand settles. The ordered-source-loader state test checks that an explicit failed-request retry blocked by joined demand retains its generation until it can issue a request. Multiple simultaneously pending joined plans during a window move and a public-query failed-retry overlap still need dedicated witnesses.
Indexed predicate filteringpackages/db/tests/query/index-path-collision-oracle.test.tsA bounded cross product of numeric values checks exact public keys before and after adding a nested-field BTree index. Direct predicates vary argument order, bound inclusivity, reversed operands, and bound field. Public Collection subscription and live-query callbacks run with and without the index. Selected-field ordering compares a direct JavaScript sort with a public $selected callback; restoring the dotted-key proxy cache made that comparison fail. The original compound grouping failed four indexed cases while scan controls passed. The original callback proxy caches also failed both unindexed public routes. A hostile cleanup control preserves the primary mismatch and secondary release error. Arbitrary path segments, nullish values, custom collation, and incremental publication need separate witnesses if claimed.
Lazy target path identitypackages/db/tests/query/compiler/lazy-targets.test.tsA focused same-source UnionFrom/coalesce witness requires both [a.b] and [a, b] demand targets. Restoring dotted-string deduplication drops the second target at the compiler boundary. A public on-demand adapter and row-publication history still need a separate witness.
Correlated include path identitypackages/db/tests/query/includes-context-transport-oracle.test.tsA flat parent field and nested parent field reach one-level and nested toArray results independently; dotted ancestor aliases remain distinct through a grandchild route. Initial results and parent updates have exact public-value checks. A conditional projection gives [a.b] and [a, b] different include results and checks parent-key changes plus later child inserts. Removing the compiler's unique route-key allocator loses a public child result; restoring dotted-string deduplication at either builder site loses a distinct parent value. These fixed witnesses do not establish arbitrary path segments, every recursive source form, or every materialization form.
Join equality and cold acquisitionpackages/db/tests/query/cold-join-reconciliation-oracle.test.tsIndependent recomputation for cold acquisition plus direct join/predicate equivalence across established equality domains. Binary/string and nullish classes, replacement histories, raw on-demand values, and both scan/auto-index paths are explicit; compound join syntax is not claimed.
Optimizer aggregate pushdownpackages/db/tests/query/optimizer-semantics-oracle.test.ts, review recordIndependent 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. The owner does not cover every predicate, wrapper, join type, or incremental update. An inner join with a global aggregate returned no row even without a WHERE clause in the initial probe; that separate path still needs a public witness and owner before claiming optimizer coverage there.
QueryRef operators and user-value boundariespackages/db/tests/query/subquery-user-value-oracle.test.ts, packages/db/tests/transactions.test.tsA 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; they do not establish singleResult subqueries, other join forms, source-update histories, or cross-copy value handling outside that guard.
Opaque backend paginationwindow oracle, cache histories, cache publication, browser acquisition boundaries, QueryCollection integrationFull filter/sort/slice reference, opaque token transport, actual Query cache expiry/invalidation/GC, forced refresh during growth, protocol failure publication/recovery, bounded slice work, nested cancellation/replacement, reader abort, browser retry defaults, manual-write cache isolation, and production window publications. Stable backend sequences; not snapshot guarantees for changing endpoints. Peek-ahead remains enabled.
Electric and TrailBaseElectric histories, recovery histories, held resume snapshots, PostgreSQL semantics, TrailBase contractInstalled SDK delivery/framing, independent predicates, exact subscription arguments, restart/reset lineage, held certification and durability races, source-order publication before durability, and late errors. The queued-presence property runs identical fixed/random generators plus isolated seed-and-path replay across insert, update, delete, and truncate callbacks. The recovery fixtures use a mocked ShapeStream; they do not establish live Electric-service framing or native persistence-host behavior.
PowerSynctests, tests/correctness-oracle.test.tsApplied receipt positions crossed with held peers, native SQLite/SDK and cleanup evidence. Run the focused owner with the package's test:oracles command. A timeout mutant proves a progress failure, not every value assertion.
SQLite persistence and native hostspersisted histories, reset/resume histories, dual-adapter resume snapshots, Browser composed-owner histories, Browser coordinator RPC, shared-driver fairness, driver contracts, Node shared-handle scheduling, OP-SQLite shared-handle scheduling, browser OPFS lifecycle, worker diagnostics, Electron IPC and composed owner, 113-law manifestCore cache/remote rejection/peer/reopen histories, atomic reset/resume lineage, key-set evidence, dual-adapter races, queued coordinator reload/gap notifications during startup, unscheduled startup/reset overlap, and exact driver results. The shared core-adapter contract checks custom local comparator dispatch for ascending, descending, and comparator-equal public-key ordering at loadSubset completion. Host packages register this contract, but the local sqlite3 CLI run does not prove native host execution. Browser composes public source commits with per-collection elected-owner routing and covers the complete committed-transaction wire partition through deterministic Node transport seams. Remote-subset histories distinguish logical demand, physical acquisitions, exact acquisition leases, and released replay tombstones. Electron composes source commits with a per-collection renderer owner, IPC adapter, real SQLite, and reopen checks. The shared-driver fairness owner checks K=1 complete-logical-hydrate scheduling with identical fixed, random, and seed-plus-path campaigns. It records public rows, raw dequeue reach, and a persist-first FIFO hostile control. Its Chromium OPFS fixture refines the provider boundary but does not establish a browser matrix, elapsed-time latency, unbounded eventuality, or multi-process coordination. Same-handle Node and OP-SQLite tests cover transaction admission. Controlled OPFS page/worker histories cover ownership and diagnostic-cause retention. The reset/resume owners use sqlite3 CLI and in-memory node:sqlite seams; they do not prove multi-process WAL, mobile/Tauri, or other native-device execution. Distinct database handles rely on SQLite lock admission rather than one in-process queue. React Native hosts without async-context propagation must use the transaction driver supplied to the callback for nested work. Fake workers and synthetic page events do not prove native handle release or real bfcache admission. The Browser composed seams are not real multi-context/OPFS-worker execution; the Electron harness is not an actual Electron process unless its explicit runtime-bridge mode runs. An ownerless elected node suppresses core routing, while a follower may route demand to the elected owner; host coordinators retry only classified transport or admission failures while demand remains retained. The manifest excludes progressive and move suites; registration and shim runs are not device execution.
SQLite expression-index planningNode expression-index oracleRFC #1659 invariant 8 owns identical persisted-index and runtime-expression shapes. Independent expected keys are checked against direct captured SQL, adapter results, and named-index plans. Generated BigInts use SQLite's signed range; one fixed case checks legacy oversized-value reads. Other limits: bounded unqualified JSON paths/scalars, Node BetterSQLite, and no null, arbitrary raw SQL, or native-host planning. Run the package's test:oracles campaign.
Offline executionscheduler, leadership, settlement, serializationDeclarative FIFO eligibility, per-transaction outcomes, durable state and typed wire trees. Issued work may finish after ownership loss, but new work must not start. Exactly-once network execution is not promised.
FrameworksReact conformance, React pagination, shared suitesExact exposed rows/pages and each framework's own lifecycle cuts. A React witness does not prove Vue/Solid/Angular/Svelte scheduling. Preserve their receiving registrations.
Window-controller overlapshared infinite-query conformance, React driver, Vue driver, Svelte driver, review recordFour or five ordered source rows, two window-settlement orders, and public snapshots after each settlement, a subscribed observer update, a detached controller read, and explicit recovery. Insertion and removal of the fifth row distinguish both continuation directions while an earlier error remains visible. The detached read follows a source change with no controller subscriber; its preloaded Collection retains the five-row window. The exact overlap uses the exported DB controller in each package realm. Framework hooks expose no controller preload, so this cell does not establish a hook scheduling path; direct hook paging remains in the adjacent shared scenarios. An unsubscribed controller has no notification claim.
Structural values and ordered primitiveshash values, hash graphs, mixed hash graphs, hash retry, comparison, deep equality, cursor, indexes, query identity, LIKE semanticsIndependent flat values, graph topology, algebraic laws, Map/group/sort recomputation, expression denotation, custom comparator dispatch/reference identity/index compatibility, LIKE wildcard refinement, compiled output bags, declared value-pair agreement between D2 equality keys and IR equality operands, and Collection collation with exact public scan/index order and one-index reuse across repeated reads. The auto-index cells cross BasicIndex and BTreeIndex; scan cells omit indexes. Both paths cover lexical and numeric en-US locale defaults plus an explicit ordinary locale override of a numeric default. An unindexed six-row work cell bounds Collection collation resolution to at most two reads per ordered scan: one index-path check and one scan clause. Other locales and ordered histories are outside this owner. The identity pair grammar covers primitives, signed zero, NaN/invalid Date, valid Date/timestamp, binary/Buffer, Temporal, nested references, symbols, and functions; fixed and sampled pairs do not prove every JavaScript value or hash collision freedom. Ref proxies are expressions rather than literal values in this lane. The 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. 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.
Minified DB public APIconsumer bundle checkCI bundles the public @tanstack/db entry with db-ivm inlined through esbuild minify: true. It checks every exported error class's current public name, the built-in BasicIndex resolver name in index metadata and its event, complete query rows (after removing the four documented virtual fields) against an independent array filter/sort/projection, and one live update. The new.target.name, public-member mangle, and extra-output-field calibration modes fail at the intended observations. This fixed slice does not replace the unminified generated oracles, exercise framework adapters, or establish stable names for custom index resolvers.
Boundary refinementscleanup/restart, issue #1891 async-cleanup review, issue #1891 cleanup-start follow-up, metadata publication, state retention, acquisition cells, D2 source reconciliation, top-K support windows, nested Query workExplicit lifecycle products, independent source maps and weighted relations, exact publication cuts, support/multiplicity, and value-plus-work observations. These refine the larger subsystem models; they do not replace them.
Small structures and test mechanicsSortedMap, cleanup queue, guarded replayMap/full-sort and appointment-list models with executed target/seed/path checks. Callback-reentrant scheduling is outside the initial cleanup-queue domain.

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.

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. The DEC-02 review record retains the RED and mutant evidence. This owner does not cover a held reorder inside a Collection-valued child facade. The receiving owner is packages/db/tests/query/includes-collection-oracle.property.test.ts; it needs a child-row A→B→A update during a held child repair and a facade subscriber observation. Concurrent optimistic changes to the same root row during a held repair also need a public snapshot and event witness in packages/db/tests/query/includes-optimistic-oracle.property.test.ts.

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 replacement test applies 25-, 26-, and 205-row full replacements through the actual Cloudflare driver. A storage seam enforces Cloudflare's documented 100-bound-parameter query limit and checks the durable keys after each transaction. This Node SQLite seam does not execute in Workers.

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.test.ts checks scheduler entry before the writer-lock request; the old bypass fails at that order assertion. The live recovery histories also guard the resulting progress. These bounded histories do not prove Firefox/Zen, React rendering, React Native, arbitrary large datasets, or an exclusive-OPFS ownership topology. Their review record preserves the RED and GREEN host observations.

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

Acceptance map

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

  • Top-K batch contracts cross sparse-array length/holes and RegExp source/flags/position with equal controls, replacement order, hash consolidation, and actual retained graph output. Ordinary replacements also run without the global File constructor.
  • Leadership replay holds real storage-read delivery across successful and permanently rejected durable removals, with bounded scans, concurrent loads, and unfinished peers. This is distinct from exactly-once execution across independent owners.
  • Accepted-snapshot retention is owned by state retention and its focused truncate-capture ownership refinement. They vary truncate before/during/after an optimistic delete, rejection versus rollback, post-capture direct insertion, and later ordinary sync/key reuse. A hidden accepted insert returns after rollback; an uncaptured insert retires, and neither snapshot is rebased onto synced fields. The state-retention owner also crosses both accepted-delete/dependent-edit settlement orders with reinsert success or failure, with and without truncate. Its public row and change-message checks run after every step. These eight histories do not establish every ordering of the insert outcome relative to sibling settlement or an arbitrary later source acknowledgement. The PR #1907 review record preserves the exact RED/GREEN evidence and reviewed commits.
Issue obligationImplemented evidenceLimit
Metamorphic lawsIncludes cross-formulation/partition, D2 independent-key commutation, DBSP incremental/full recomputation, pagination provider/UI boundaries, optimistic snapshot stabilityEquivalence premises are explicit; not arbitrary query rewrites.
Public observationsReads, exact event payloads and reconstructed state, observer eligibility, downstream includes, lifecycle and ownership checksCount/work budgets are separate from row truth and only pin established promises.
Meaningful async historiesApplied receipts, truncate/replay, cleanup/restart, pending optimistic work, held provider completion, leadership lossControl real causes; unsupported SDK traces receive no coverage credit.
Checker sensitivityFaulty output controls, missing/duplicate events, stale completion/ownership controls, forced collisions and pre-fix runtime witnessesSetup failures and timeouts are recorded separately from assertion kills.
Executed reach and replayNamed manifest with guarded replay, finite boundary products, pinned examples, fixed/random lanes and explicit stress runsRoot test:oracles is a selected core/Query DB campaign, not all repository oracles.
Contract and scope recordsGuide, companion case notes, this map, suite-local law/domain comments and architectureThis is an executable testing method, not a completeness proof or new product specification.

Running and replaying

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

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

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

TANSTACK_DB_ORACLE_SEED=1813 TANSTACK_DB_ORACLE_PATH=0 \
TANSTACK_DB_ORACLE_PROPERTY=live-query-observer.granular-history \
node --import tsx tests/oracle-replay.ts \
  tests/live-query-observer-history.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.

  • Real-provider conformance fixtures. Frozen 15.2.7 React Native and Node receipts cover the supported peer version; 18.2.1 React Native, Node, and browser receipts cover the known forward shapes. Exact-row checks and a row-dropping hostile control prove the shim accepts those envelopes without mutating them. Owner: packages/react-native-db-sqlite-persistence/tests/fixtures/op-sqlite-provider-results.ts and packages/react-native-db-sqlite-persistence/tests/op-sqlite-driver.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.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.test.ts and the shared SQLite driver contract.

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

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

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

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

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

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

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

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

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

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

  • Joined aggregate and singleResult subquery histories. Extend packages/db/tests/query/subquery-user-value-oracle.test.ts with source changes after initial publication and joined findOne() subqueries. Recompute complete result bags or public singleton values at each checkpoint; the current fixed DISTINCT and nested aggregate witnesses do not establish those neighboring paths.

Deferred contracts and evidence

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

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

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

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

Final evidence record

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