Skip to content
Source
Sign inSign up
TanStack/db

test(db): cover source deletes for keys the source never held #2008

MergedKyleAMathews(GitHub profile, opens in a new tab)merged 6 commits intomain fromrefs/pull/2008/headmerged 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.

GrammarOptimistic-history campaignsPinned histories
before this PRpassnot present
this PRfail3 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/db suite: 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. ⚠️ 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

    2. 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: 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.md
      • docs/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.ts
      The oracle documents absent-key source deletes. resolveSourceBatch retains those deletes, and writeSourceBatch counts 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 06bca

      This 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 06bca

      The change affects 2 systems.

      Changed systems: docs, packages/db

      Architecture 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 SourceBatch comment to state that source deletes may name keys the source does not hold.
      • observed — Modified behavior in packages/db/tests/optimistic-history-oracle.ts: resolveSourceBatch now 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: writeSourceBatch increments absentSourceDeletes when a batch delete targets a key recorded as absent by resolveSourceBatch.
      🚥 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 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 nameStatusExplanation
      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.
      Title check✅ PassedThe title clearly describes the main change: adding database test coverage for source deletes of keys the source never held.
      Description check✅ PassedThe 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.

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

      @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@2008

      commit: 06bcab8

    4. Size Change: 0 B

      Total Size: 180 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.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
      compressed-size-action::db-package-size
    5. Size Change: 0 B

      Total Size: 8.66 kB

      ℹ️ View Unchanged
      FilenameSize
      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
      compressed-size-action::react-db-package-size

Sign in to join this conversation.