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. |
| 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. |
| 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. |
| 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. |
| 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. |
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.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. |
| 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 | 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; 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. Never rebase a pending snapshot merely to simplify the model. |
| Drafts and native values | proxy, detachment, iteration | 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. |
| 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. |
| 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. |
| 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. |
| Optimizer aggregate pushdown | packages/db/tests/query/optimizer-semantics-oracle.test.ts, review record | 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. 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 boundaries | packages/db/tests/query/subquery-user-value-oracle.test.ts, packages/db/tests/transactions.test.ts | 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; they do not establish singleResult subqueries, other join forms, source-update histories, or cross-copy value handling outside that guard. |
| 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. 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 | Declarative 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. |
| Frameworks | React conformance, React pagination, shared suites | Exact 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 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 graphs, mixed hash graphs, hash retry, comparison, deep equality, cursor, indexes, 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 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 API | consumer bundle check | CI 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 refinements | cleanup/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 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, guarded replay | Map/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
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.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.tsandpackages/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.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.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.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.test.tsunder R5-007.Joined aggregate and
singleResultsubquery histories. Extendpackages/db/tests/query/subquery-user-value-oracle.test.tswith source changes after initial publication and joinedfindOne()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.