test(db): cover source deletes for keys the source never held #2008
main fromrefs/pull/2008/head·merged by KyleAMathews(GitHub profile, opens in a new tab) This PR adds oracle coverage for a source delete of a key that the source never held. It changes no production code. main already follows the contract below, and the new histories now check it.
The case#
A backend can accept an optimistic insert and then delete the row before the source streams it. The source then sends a delete for a key that it never held:
collection.insert({ id: 1, a: 1, b: 0, c: 0 }) // the handler succeeds
// The backend deleted row 1 before the source streamed it.
sync.begin()
sync.write({ type: `delete`, key: 1 })
sync.commit()
// The accepted row 1 disappears, and subscribers get `delete 1`.
Contract#
- The delete retires an accepted optimistic snapshot of the key, as any ordinary source publication does.
- The delete leaves an active request in place. It changes no base row and acknowledges no request.
The oracle's opening prose now states this contract.
Why no test covered it#
The optimistic-history driver dropped each delete for a key the source did not hold. Neither the model nor the Collection saw such a delete. The coverage map recorded the case as open after #1996.
What changes#
- The driver writes these deletes and counts them. The fixed campaign must write at least one, beside deletes of held keys.
- Three pinned histories accept an optimistic insert and then delete its key from a source that never held it. They cover a queued delete, an immediate delete, and a delete inside the insert handler.
- A fourth pinned history writes an immediate delete while the insert is still active. The row stays visible through settlement.
- The coverage map row for optimistic state now names the contract and the new review record.
Evidence#
A hostile mutant rejects a sync delete for a key absent from the source projection.
| Grammar | Optimistic-history campaigns | Pinned histories |
|---|---|---|
| before this PR | pass | not present |
| this PR | fail | 3 of 3 fail |
A broader mutant drops any delete for a key absent from syncedData. It does not distinguish this change: the old grammar already kills it through queued deletes of held keys.
Limits#
An immediate delete can arrive while the insert is still active. The accepted row then stays until the next source publication, because a source delete acknowledges no request. A separate change drops immediate sync batches, so this PR does not revisit that rule.
Verification#
@tanstack/dbsuite: 244 files, 8,269 tests pass.- The review record accounts for every ORC requirement against tested revision
74e5b80d6. - ESLint, Prettier, and
tsc: clean on the changed files.
This pull request and its description were written by Isaac.
Summary by CodeRabbit#
- Documentation
- Clarified that a source delete for a key it does not contain retires an accepted optimistic snapshot without removing a base row or acknowledging an active request.
- Documented that an active insert may remain visible after an absent-key delete.
- Tests
- Added coverage for absent-key deletes before and during settlement, and for active inserts that remain unacknowledged.
- Strengthened fixed test campaigns to verify that absent-key deletes occur alongside deletes of existing keys.
- 1
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:
41bef2e4-f964-4385-952f-8acd9667a0dc
📥 Commits
Reviewing files that changed from the base of the PR and between fc18d51e56ddd84de67ea3a88be829b576f24cb6 and 06bcab8cccb4aeff55082ec44ed4a0685860ab3a.
📒 Files selected for processing (2)
docs/contributing/oracle-coverage.mddocs/contributing/oracle-reviews/2026-10-02-truncate-raw-subscriber.md
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/contributing/oracle-coverage.md
Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 6 remain after this review.
📝 Walkthrough
Walkthrough#
The history oracle now retains and counts source deletes for keys absent from source state. Property tests cover absent-key deletes after accepted optimistic inserts and during active inserts. Documentation records the behavior, test histories, campaign results, and limits.
Changes#
Absent-Key Source Delete Coverage
Layer / File(s) Summary Preserve deletes in the history oracle
packages/db/tests/optimistic-history-oracle.tsThe oracle documents absent-key source deletes. resolveSourceBatchretains those deletes, andwriteSourceBatchcounts them.Exercise and document absent-key delete histories
packages/db/tests/collection-state-retention-oracle.property.test.ts,docs/contributing/oracle-coverage.md,docs/contributing/oracle-reviews/*The fixed campaign requires an absent-key delete. New cases cover deletes after accepted optimistic inserts and an immediate delete during an active insert. The documentation records the histories, campaign results, active-insert limit, and corrected pinned replay reference. Priority: ⬇️ Low
Estimated code review effort: 2 (Simple) | ~10 minutes
Change: Other
Merge Risk: ⚪ Minimal · up to
06bcaThis PR changes oracle tests and documentation, not production behavior. The campaign and pinned histories cover the stated absent-key delete behavior; no actionable merge risk remains.
Architecture Summary#
Architecture risk: 🔵 Low · up to
06bcaThe change affects 2 systems.
Changed systems:
docs,packages/dbArchitecture concerns No architecture-level concerns identified.
Review details
Systems and components
- observed — docs (service) was modified; 3 changed files map to changed impact.
- observed — packages/db (library) was modified; 2 changed files map to changed impact.
Before / after behavior
- observed — Modified behavior in packages/db/tests/optimistic-history-oracle.ts: Added documentation describing absent-key source deletes: they retire accepted snapshots but remove no base row and acknowledge no active request.
- observed — Modified behavior in packages/db/tests/optimistic-history-oracle.ts: Updated the
SourceBatchcomment to state that source deletes may name keys the source does not hold. - observed — Modified behavior in packages/db/tests/optimistic-history-oracle.ts:
resolveSourceBatchnow records keys absent from the source after processing batch rows and deletes, rather than filtering those deletes out. It returns the original batch, preserving all deletes for the model and driver. - observed — Modified behavior in packages/db/tests/optimistic-history-oracle.ts:
writeSourceBatchincrementsabsentSourceDeleteswhen a batch delete targets a key recorded as absent byresolveSourceBatch.
🚥 Pre-merge checks | ✅ 4 | ❌ 1
❌ Failed checks (1 warning)#
Check name Status Explanation Resolution Docstring Coverage ⚠️ Warning 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 3 functions across 2 files. (2 skipped: 2 … Write docstrings for the functions missing them to satisfy the coverage threshold. ✅ Passed checks (4 passed)
Check name Status Explanation Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request. Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request. Title check ✅ Passed The title clearly describes the main change: adding database test coverage for source deletes of keys the source never held. Description check ✅ Passed The description explains the changes, motivation, contract, test coverage, verification, and lack of production-code changes. It does not use the template headings or mark the checklist and release-im… 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 3 functions across 2 files. (2 skipped: 2 unsupported.)
- Fix all pre-merge checks with AI
✨ Finishing Touches
🧪 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.
Comment `@coderabbitai help` to get the list of available commands.More templates
- todos
- offline-first-electron
- @tanstack/db-example-solid-todo
- offline-transactions-react-native
- shopping-list-react-native
- @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
@tanstack/angular-db
npm i https://pkg.pr.new/@tanstack/angular-db@2008@tanstack/browser-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/browser-db-sqlite-persistence@2008@tanstack/capacitor-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/capacitor-db-sqlite-persistence@2008@tanstack/cloudflare-durable-objects-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/cloudflare-durable-objects-db-sqlite-persistence@2008@tanstack/db
npm i https://pkg.pr.new/@tanstack/db@2008@tanstack/db-ivm
npm i https://pkg.pr.new/@tanstack/db-ivm@2008@tanstack/db-sqlite-persistence-core
npm i https://pkg.pr.new/@tanstack/db-sqlite-persistence-core@2008@tanstack/electric-db-collection
npm i https://pkg.pr.new/@tanstack/electric-db-collection@2008@tanstack/electron-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/electron-db-sqlite-persistence@2008@tanstack/expo-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/expo-db-sqlite-persistence@2008@tanstack/node-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/node-db-sqlite-persistence@2008@tanstack/offline-transactions
npm i https://pkg.pr.new/@tanstack/offline-transactions@2008@tanstack/powersync-db-collection
npm i https://pkg.pr.new/@tanstack/powersync-db-collection@2008@tanstack/query-db-collection
npm i https://pkg.pr.new/@tanstack/query-db-collection@2008@tanstack/react-db
npm i https://pkg.pr.new/@tanstack/react-db@2008@tanstack/react-native-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/react-native-db-sqlite-persistence@2008@tanstack/react-router-with-db
npm i https://pkg.pr.new/@tanstack/react-router-with-db@2008@tanstack/rxdb-db-collection
npm i https://pkg.pr.new/@tanstack/rxdb-db-collection@2008@tanstack/solid-db
npm i https://pkg.pr.new/@tanstack/solid-db@2008@tanstack/svelte-db
npm i https://pkg.pr.new/@tanstack/svelte-db@2008@tanstack/tauri-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/tauri-db-sqlite-persistence@2008@tanstack/trailbase-db-collection
npm i https://pkg.pr.new/@tanstack/trailbase-db-collection@2008@tanstack/vue-db
npm i https://pkg.pr.new/@tanstack/vue-db@2008commit:
06bcab8Size Change: 0 B
Total Size: 180 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.js1.64 kB packages/db/dist/esm/collection/changes.js2.38 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.64 kB packages/db/dist/esm/collection/mutations.js3.03 kB packages/db/dist/esm/collection/state.js7.87 kB packages/db/dist/esm/collection/subscription.js8.44 kB packages/db/dist/esm/collection/sync.js5.31 kB packages/db/dist/esm/collection/transaction-metadata.js144 B packages/db/dist/esm/deferred.js207 B packages/db/dist/esm/errors.js5.61 kB packages/db/dist/esm/event-emitter.js961 B packages/db/dist/esm/index.js4.01 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.js338 B packages/db/dist/esm/live-query-observer.js4.59 kB packages/db/dist/esm/live-query-options.js1.06 kB packages/db/dist/esm/live-query-window-controller.js4.12 kB packages/db/dist/esm/local-only.js1.08 kB 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.js3.17 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.81 kB packages/db/dist/esm/query/builder/query-ir.js116 B packages/db/dist/esm/query/builder/ref-proxy-identity.js292 B packages/db/dist/esm/query/builder/ref-proxy.js1.48 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.js604 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-conjunct.js486 B 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.7 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.js305 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/pooled-live-query.js4.06 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.6 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.49 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.66 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/development.js190 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.27 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.
⚠️ No Changeset found#
Latest commit: 06bcab8cccb4aeff55082ec44ed4a0685860ab3a
Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.
This PR includes no changesets
When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types
Click here to learn what changesets are, and how to add one.
Click here if you're a maintainer who wants to add a changeset to this PR