test(db): close state-stack gaps found by a mutation round #1996
main fromrefs/pull/1996/head·merged 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 suite | New 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:
| Mistake | Owner | Failures |
|---|---|---|
| Sync insert keeps pending layers | retention oracle | 3 of 97 |
| Sync delete keeps pending layers | retention oracle | pinned replay |
| Write after commit | retention oracle | 1 of 97 |
| Cleanup start transition | cleanup/restart oracle | 1 of 41 |
| Idle reschedule not canceled | idle-cleanup test | 1 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
More templates
- offline-first-electron
- todos
- @tanstack/db-example-react-next-ssr-e2e
- tanstack-start-example-basic
- @tanstack/db-example-paced-mutations-demo
- tanstack-start-db-projects-example
- @tanstack/db-example-react-start-ssr-e2e
- @tanstack/db-example-react-todo
- offline-transactions-react-native
- shopping-list-react-native
- @tanstack/db-example-solid-todo
@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@1996commit:
3706dcdSize Change: 0 B
Total Size: 174 kB
compressed-size-action::db-package-sizeℹ️ View Unchanged
Filename Size 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 Size Change: 0 B
Total Size: 8.51 kB
compressed-size-action::react-db-package-sizeℹ️ View Unchanged
Filename Size 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 KyleAMathews(GitHub profile, opens in a new tab) closed this
Sign in to join this conversation.
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.mddocs/contributing/oracle-reviews/2026-10-02-state-stack-mutant-gaps.mdpackages/db/tests/collection-cleanup-restart-oracle.test.tspackages/db/tests/collection-idle-cleanup.test.ts🚧 Files skipped from review as they are similar to previous changes (2)
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
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.mdpackages/db/tests/collection-cleanup-restart-oracle.test.tsisLoadingSubsetbecomes false.packages/db/tests/collection-idle-cleanup.test.ts,docs/contributing/oracle-coverage.mdPriority: ⬇️ Low
Estimated code review effort: 3 (Moderate) | ~20 minutes
Change: Other
Merge Risk: ⚪ Minimal · up to
3706dThe added tests and oracle changes have no identified issue that needs resolution before merging.
🚥 Pre-merge checks | ✅ 4 | ❌ 1
❌ Failed checks (1 warning)#
✅ Passed checks (4 passed)
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.)
✨ Finishing Touches 💡 1
📝 Generate docstrings 💡
🧪 Generate unit tests (beta)
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