Skip to content
Source
Sign inSign up
TanStack/db

test(db): close state-stack gaps found by a mutation round #1996

MergedKyleAMathews(GitHub profile, opens in a new tab)merged 3 commits intomain fromrefs/pull/1996/headmerged by KyleAMathews(GitHub profile, opens in a new tab)

This PR adds tests for five state-subsystem mistakes that passed the whole db suite. It changes no production code. The tests are in place before a planned code-weight refactor of state.ts, sync.ts, and lifecycle.ts, so a bad port of that refactor fails.

How the gaps were found

The refactor exists as nine prototype commits. Before porting them, I applied 22 plausible porting mistakes to unchanged main and ran the suite. For each survivor I wrote a probe that passes on main and fails on the mistake, or I showed that the mistake changes no public observation.

Two survivors exposed bugs on main, which have their own PRs: #1986 (merged) and #1995. This PR closes the five survivors that were test gaps:

Mistake that passed the suiteNew test
A sync insert keeps the key's pending local layers. After a confirmed insert, the next remote update reports $origin: 'local'.Source rows in the optimistic-history oracle are written as insert for a key the source lacks.
A sync delete keeps the key's pending local layers. A later source reinsert reports $origin: 'local'.Source batches in that oracle can delete keys, and a pinned replay keeps the counterexample.
A sync write() after commit() joins the queued batch while that batch waits for persistence.The retention oracle expects SyncTransactionAlreadyCommittedWriteError.
Cleanup during a pending subset load emits a loading-subset start transition.The cleanup/restart oracle expects one end transition.
A returning subscriber cannot cancel idle cleanup that rescheduled itself, so the Collection cleans up early.The new collection-idle-cleanup.test.ts uses a controllable browser idle scheduler.

Why the oracle missed the first two

Every optimistic-history source batch wrote update messages, and an update acts as an upsert. So the production insert and delete apply paths never ran in those histories. The driver now tracks which keys the source holds, including queued batches. A row for an absent key is written as insert, and a delete applies only to a key the source holds. The model receives the same resolved batch. A runtime witness requires the fixed campaign to write both kinds.

Results

All new tests pass on main, and each one fails when its mistake is applied:

MistakeOwnerFailures
Sync insert keeps pending layersretention oracle3 of 97
Sync delete keeps pending layersretention oraclepinned replay
Write after commitretention oracle1 of 97
Cleanup start transitioncleanup/restart oracle1 of 41
Idle reschedule not canceledidle-cleanup test1 of 1

The idle-cleanup case needs its own file. The idle scheduler is chosen when browser-polyfills.ts loads, and the Node polyfill always reports a timed-out deadline, so no other test can make cleanup reschedule.

The review record lists the survivors that change no observation. Two of them sit in dead code that the refactor can delete.

Verification

On f1a40e58d: packages/db Vitest passes 201 files and 7,862 tests.

This pull request and its description were written by Isaac.

Summary by CodeRabbit

  • Tests
    • Added coverage confirming that cleanup ends an in-progress subset load exactly once and leaves loading inactive.
    • Added checks that a returning subscriber cancels scheduled idle cleanup.
    • Expanded state-retention tests for writes to committed batches and source inserts and deletes, including generated histories.
  • Documentation
    • Updated state inventories and added a report covering test findings, observed behavior, and verification results.
    1. Review in Change Stack →

      Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

      No actionable comments were generated in the recent review. 🎉

      ℹ️ Recent review info
      ⚙️ Run configuration

      Configuration used: defaults

      Review profile: CHILL

      Plan: Advanced

      Run ID: 5435a01b-d57d-4f26-bb11-e48275172f19

      📥 Commits

      Reviewing files that changed from the base of the PR and between cada02a67fbf6777d2c9b589be391fc8949ff6d7 and 3706dcd083716cd66b45de8b4b3903bc41f6d4f5.

      📒 Files selected for processing (4)
      • docs/contributing/oracle-coverage.md
      • docs/contributing/oracle-reviews/2026-10-02-state-stack-mutant-gaps.md
      • packages/db/tests/collection-cleanup-restart-oracle.test.ts
      • packages/db/tests/collection-idle-cleanup.test.ts
      🚧 Files skipped from review as they are similar to previous changes (2)
      • docs/contributing/oracle-coverage.md
      • docs/contributing/oracle-reviews/2026-10-02-state-stack-mutant-gaps.md

      Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 5 remain after this review.


      📝 Walkthrough

      Walkthrough

      The changes extend optimistic-history tests to model source inserts and deletes. They add tests for committed sync-batch writes, pending subset-load cleanup, and idle-cleanup cancellation. Contributor documentation records the test scope and results.

      Changes

      Collection state oracles

      Layer / File(s)Summary
      Optimistic source-batch modeling and tests
      packages/db/tests/optimistic-history-oracle.ts, packages/db/tests/collection-state-retention-oracle.property.test.ts, docs/contributing/oracle-coverage.md, docs/contributing/oracle-reviews/2026-10-02-state-stack-mutant-gaps.md
      The history model and driver classify source rows as inserts or updates and process source deletes. Tests cover source-delete accounting, fixed-seed insert/delete histories, and writes to committed sync batches. The documents describe the updated coverage and mutant results.
      Cleanup ends pending subset loads
      packages/db/tests/collection-cleanup-restart-oracle.test.ts
      A new test checks that cleanup ends a pending subset load with one start transition and one end transition, and that isLoadingSubset becomes false.
      Returning subscribers cancel idle cleanup
      packages/db/tests/collection-idle-cleanup.test.ts, docs/contributing/oracle-coverage.md
      A new test controls idle callbacks and checks that a returning subscriber prevents cleanup after it leaves again. The coverage inventory adds this test to its evidence links.

      Priority: ⬇️ Low

      Estimated code review effort: 3 (Moderate) | ~20 minutes

      Change: Other

      Merge Risk: ⚪ Minimal · up to 3706d

      The added tests and oracle changes have no identified issue that needs resolution before merging.

      🚥 Pre-merge checks | ✅ 4 | ❌ 1

      ❌ Failed checks (1 warning)

      Check nameStatusExplanationResolution
      Docstring Coverage⚠️ WarningDocstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 4 files. (2 skipped: 2 …Write docstrings for the functions missing them to satisfy the coverage threshold.
      ✅ Passed checks (4 passed)
      Check nameStatusExplanation
      Title check✅ PassedThe title clearly identifies a database test change that closes state-stack gaps found through mutation testing.
      Description check✅ PassedThe description explains the motivation, covered test gaps, verification results, and lack of production-code changes. It omits the template headings and explicit checklist and release-impact items, b…
      Linked Issues check✅ PassedCheck skipped because no linked issues were found for this pull request.
      Out of Scope Changes check✅ PassedCheck skipped because no linked issues were found for this pull request.
      Full details: Docstring Coverage

      Explanation

      Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 4 files. (2 skipped: 2 unsupported.)

      • Fix all pre-merge checks with AI
      ✨ Finishing Touches 💡 1
      📝 Generate docstrings 💡
      • Commit to this branch
      • Create a new PR
      🧪 Generate unit tests (beta)
      • Commit to this branch
      • Create a new PR
      • Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

      Autopilot is currently an internal CodeRabbit preview.


      Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

      ❤️ Share
      Comment `@coderabbitai help` to get the list of available commands.
    2. More templates

      @tanstack/angular-db

      npm i https://pkg.pr.new/@tanstack/angular-db@1996

      @tanstack/browser-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/browser-db-sqlite-persistence@1996

      @tanstack/capacitor-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/capacitor-db-sqlite-persistence@1996

      @tanstack/cloudflare-durable-objects-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/cloudflare-durable-objects-db-sqlite-persistence@1996

      @tanstack/db

      npm i https://pkg.pr.new/@tanstack/db@1996

      @tanstack/db-ivm

      npm i https://pkg.pr.new/@tanstack/db-ivm@1996

      @tanstack/db-sqlite-persistence-core

      npm i https://pkg.pr.new/@tanstack/db-sqlite-persistence-core@1996

      @tanstack/electric-db-collection

      npm i https://pkg.pr.new/@tanstack/electric-db-collection@1996

      @tanstack/electron-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/electron-db-sqlite-persistence@1996

      @tanstack/expo-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/expo-db-sqlite-persistence@1996

      @tanstack/node-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/node-db-sqlite-persistence@1996

      @tanstack/offline-transactions

      npm i https://pkg.pr.new/@tanstack/offline-transactions@1996

      @tanstack/powersync-db-collection

      npm i https://pkg.pr.new/@tanstack/powersync-db-collection@1996

      @tanstack/query-db-collection

      npm i https://pkg.pr.new/@tanstack/query-db-collection@1996

      @tanstack/react-db

      npm i https://pkg.pr.new/@tanstack/react-db@1996

      @tanstack/react-native-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/react-native-db-sqlite-persistence@1996

      @tanstack/react-router-with-db

      npm i https://pkg.pr.new/@tanstack/react-router-with-db@1996

      @tanstack/rxdb-db-collection

      npm i https://pkg.pr.new/@tanstack/rxdb-db-collection@1996

      @tanstack/solid-db

      npm i https://pkg.pr.new/@tanstack/solid-db@1996

      @tanstack/svelte-db

      npm i https://pkg.pr.new/@tanstack/svelte-db@1996

      @tanstack/tauri-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/tauri-db-sqlite-persistence@1996

      @tanstack/trailbase-db-collection

      npm i https://pkg.pr.new/@tanstack/trailbase-db-collection@1996

      @tanstack/vue-db

      npm i https://pkg.pr.new/@tanstack/vue-db@1996

      commit: 3706dcd

    3. Size Change: 0 B

      Total Size: 174 kB

      ℹ️ View Unchanged
      FilenameSize
      packages/db/dist/esm/client.js3.61 kB
      packages/db/dist/esm/collection-options.js236 B
      packages/db/dist/esm/collection/change-events.js2.07 kB
      packages/db/dist/esm/collection/changes.js2.72 kB
      packages/db/dist/esm/collection/cleanup-queue.js808 B
      packages/db/dist/esm/collection/events.js481 B
      packages/db/dist/esm/collection/index.js4.57 kB
      packages/db/dist/esm/collection/indexes.js2.06 kB
      packages/db/dist/esm/collection/lifecycle.js2.63 kB
      packages/db/dist/esm/collection/mutations.js2.59 kB
      packages/db/dist/esm/collection/state.js8.32 kB
      packages/db/dist/esm/collection/subscription.js8.63 kB
      packages/db/dist/esm/collection/sync.js4.96 kB
      packages/db/dist/esm/collection/transaction-metadata.js144 B
      packages/db/dist/esm/deferred.js207 B
      packages/db/dist/esm/errors.js5.49 kB
      packages/db/dist/esm/event-emitter.js961 B
      packages/db/dist/esm/index.js3.94 kB
      packages/db/dist/esm/indexes/auto-index.js841 B
      packages/db/dist/esm/indexes/base-index.js1.25 kB
      packages/db/dist/esm/indexes/basic-index.js2.01 kB
      packages/db/dist/esm/indexes/btree-index.js2.3 kB
      packages/db/dist/esm/indexes/index-registry.js820 B
      packages/db/dist/esm/indexes/reverse-index.js370 B
      packages/db/dist/esm/live-query-adapter.js318 B
      packages/db/dist/esm/live-query-observer.js4.53 kB
      packages/db/dist/esm/live-query-options.js731 B
      packages/db/dist/esm/live-query-window-controller.js4.12 kB
      packages/db/dist/esm/local-only.js989 B
      packages/db/dist/esm/local-storage.js2.17 kB
      packages/db/dist/esm/optimistic-action.js359 B
      packages/db/dist/esm/paced-mutations.js702 B
      packages/db/dist/esm/persisted-readiness.js195 B
      packages/db/dist/esm/proxy.js2.77 kB
      packages/db/dist/esm/query/builder/clone-query.js766 B
      packages/db/dist/esm/query/builder/functions.js1.45 kB
      packages/db/dist/esm/query/builder/index.js6.79 kB
      packages/db/dist/esm/query/builder/query-ir.js116 B
      packages/db/dist/esm/query/builder/ref-proxy-identity.js198 B
      packages/db/dist/esm/query/builder/ref-proxy.js1.35 kB
      packages/db/dist/esm/query/builder/wrapper-identity.js221 B
      packages/db/dist/esm/query/compiler/evaluators.js2.1 kB
      packages/db/dist/esm/query/compiler/expressions.js603 B
      packages/db/dist/esm/query/compiler/group-by.js4.2 kB
      packages/db/dist/esm/query/compiler/index.js9.39 kB
      packages/db/dist/esm/query/compiler/joins.js3.06 kB
      packages/db/dist/esm/query/compiler/lazy-targets.js1.14 kB
      packages/db/dist/esm/query/compiler/order-by.js2 kB
      packages/db/dist/esm/query/compiler/parent-routes.js319 B
      packages/db/dist/esm/query/compiler/query-equivalence.js455 B
      packages/db/dist/esm/query/compiler/route-metadata.js1.24 kB
      packages/db/dist/esm/query/compiler/select.js1.59 kB
      packages/db/dist/esm/query/effect.js4.86 kB
      packages/db/dist/esm/query/equality-value-identity.js591 B
      packages/db/dist/esm/query/expression-helpers.js1.45 kB
      packages/db/dist/esm/query/ir-stable-identity.js4.22 kB
      packages/db/dist/esm/query/ir.js1.69 kB
      packages/db/dist/esm/query/live-query-collection.js391 B
      packages/db/dist/esm/query/live/bucket-facade-adapter.js2.67 kB
      packages/db/dist/esm/query/live/collection-config-builder.js6.47 kB
      packages/db/dist/esm/query/live/collection-registry.js264 B
      packages/db/dist/esm/query/live/collection-subscriber.js2.05 kB
      packages/db/dist/esm/query/live/graph-scheduler.js303 B
      packages/db/dist/esm/query/live/internal.js145 B
      packages/db/dist/esm/query/live/materialized-pipeline.js2.32 kB
      packages/db/dist/esm/query/live/ordered-source-loader.js4.14 kB
      packages/db/dist/esm/query/live/subset-demand-controller.js1.65 kB
      packages/db/dist/esm/query/live/utils.js1.2 kB
      packages/db/dist/esm/query/optimizer.js2.92 kB
      packages/db/dist/esm/query/query-once.js359 B
      packages/db/dist/esm/query/runtime-reference-identity.js630 B
      packages/db/dist/esm/query/subset-dedupe.js493 B
      packages/db/dist/esm/scheduler.js1.13 kB
      packages/db/dist/esm/SortedMap.js1.58 kB
      packages/db/dist/esm/strategies/debounceStrategy.js331 B
      packages/db/dist/esm/strategies/queueStrategy.js488 B
      packages/db/dist/esm/strategies/throttleStrategy.js386 B
      packages/db/dist/esm/sync-persistence.js530 B
      packages/db/dist/esm/transactions.js3.89 kB
      packages/db/dist/esm/utils.js1.43 kB
      packages/db/dist/esm/utils/array-utils.js270 B
      packages/db/dist/esm/utils/browser-polyfills.js304 B
      packages/db/dist/esm/utils/btree.js3.02 kB
      packages/db/dist/esm/utils/callbacks.js174 B
      packages/db/dist/esm/utils/comparison.js1.59 kB
      packages/db/dist/esm/utils/cursor.js677 B
      packages/db/dist/esm/utils/error.js167 B
      packages/db/dist/esm/utils/get-or-create.js155 B
      packages/db/dist/esm/utils/index-optimization.js2.42 kB
      packages/db/dist/esm/utils/source-record.js140 B
      packages/db/dist/esm/utils/type-guards.js230 B
      packages/db/dist/esm/utils/uuid.js449 B
      packages/db/dist/esm/virtual-props.js413 B
      compressed-size-action::db-package-size
    4. Size Change: 0 B

      Total Size: 8.51 kB

      ℹ️ View Unchanged
      FilenameSize
      packages/react-db/dist/esm/DbProvider.js317 B
      packages/react-db/dist/esm/HydrationBoundary.js263 B
      packages/react-db/dist/esm/index.js330 B
      packages/react-db/dist/esm/live-query-internals.js282 B
      packages/react-db/dist/esm/useLiveInfiniteQuery.js1.93 kB
      packages/react-db/dist/esm/useLiveQuery.js3.3 kB
      packages/react-db/dist/esm/useLiveQueryEffect.js355 B
      packages/react-db/dist/esm/useLiveSuspenseQuery.js1.33 kB
      packages/react-db/dist/esm/usePacedMutations.js401 B
      compressed-size-action::react-db-package-size

Sign in to join this conversation.