Skip to content

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

Open
KyleAMathews wants to merge 1 commit into
mainfrom
test/absent-key-source-delete
Open

KyleAMathews wants to merge 1 commit into
mainfrom
test/absent-key-source-delete

Conversation

@KyleAMathews

@KyleAMathews KyleAMathews commented Oct 2, 2026 •

Copy link
Copy Markdown
Collaborator

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.
  • 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/db suite: 244 files, 8,269 tests pass.
  • 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 acknowledging an active request.
    • Documented that deleting during an active insert may leave the accepted row visible until a later source update.
  • Tests
    • Added coverage for absent-key deletes across different synchronization and delivery scenarios, and strengthened checks that these deletes occur in fixed test campaigns.

A source may delete a key it does not hold, for example after its
backend accepted an optimistic insert and deleted the row before the
source streamed it. The optimistic-history driver dropped those deletes
before the model or the Collection saw them, so the coverage map listed
the case as open.

The driver now writes them and counts them. The contract: the delete
retires an accepted snapshot of the key, as any ordinary source
publication does, and leaves an active request in place. main already
behaves this way. Three pinned histories cover a queued, an immediate,
and an in-handler delete after an accepted insert.

A mutant that rejects a delete for a key absent from the source
projection passes the old optimistic-history campaigns and fails the
new ones and the pinned histories.

Co-authored-by: Isaac <no-reply@databricks.com>
@changeset-bot

changeset-bot Bot commented Oct 2, 2026

Copy link
Copy Markdown

⚠️ No Changeset found

Latest commit: af0b864

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

@coderabbitai

coderabbitai Bot commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

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: 083013f2-1c38-44ee-b871-357a4a1b68e6
📥 Commits

Reviewing files that changed from the base of the PR and between 95c3f9e and af0b864.

📒 Files selected for processing (4)
  • docs/contributing/oracle-coverage.md
  • docs/contributing/oracle-reviews/2026-10-02-absent-key-source-delete.md
  • packages/db/tests/collection-state-retention-oracle.property.test.ts
  • packages/db/tests/optimistic-history-oracle.ts

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


📝 Walkthrough

Walkthrough

The optimistic-history oracle now retains source deletes for keys absent from source state and counts them. Property tests cover absent-key deletes after accepted optimistic inserts. Documentation records the behavior, test histories, campaign results, and a limit involving active inserts.

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 documentation now describes 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 across sync modes and handler delivery. The documentation records the histories, test outcomes, and the active-insert limit.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Other

Merge Risk: ⚪ Minimal · up to af0b8

The added histories cover the intended delete behavior. No issue requiring a fix before merge was identified.

🚥 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 identifies the main change: adding database test coverage for source deletes targeting keys that the source never held.
Description check ✅ Passed The description clearly explains the change, motivation, contract, test coverage, evidence, limits, and verification results. It does not use the required Changes, Checklist, and Release Impact headin…
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 💡 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.

@pkg-pr-new

pkg-pr-new Bot commented Oct 2, 2026

Copy link
Copy Markdown
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: af0b864

@github-actions

github-actions Bot commented Oct 2, 2026

Copy link
Copy Markdown
Contributor

Size Change: 0 B

Total Size: 180 kB

ℹ️ View Unchanged
Filename Size
packages/db/dist/esm/client.js 3.61 kB
packages/db/dist/esm/collection-options.js 236 B
packages/db/dist/esm/collection/change-events.js 1.64 kB
packages/db/dist/esm/collection/changes.js 2.38 kB
packages/db/dist/esm/collection/cleanup-queue.js 808 B
packages/db/dist/esm/collection/events.js 481 B
packages/db/dist/esm/collection/index.js 4.57 kB
packages/db/dist/esm/collection/indexes.js 2.06 kB
packages/db/dist/esm/collection/lifecycle.js 2.66 kB
packages/db/dist/esm/collection/mutations.js 3.07 kB
packages/db/dist/esm/collection/state.js 8.27 kB
packages/db/dist/esm/collection/subscription.js 8.44 kB
packages/db/dist/esm/collection/sync.js 5.37 kB
packages/db/dist/esm/collection/transaction-metadata.js 144 B
packages/db/dist/esm/deferred.js 207 B
packages/db/dist/esm/errors.js 5.61 kB
packages/db/dist/esm/event-emitter.js 961 B
packages/db/dist/esm/index.js 4 kB
packages/db/dist/esm/indexes/auto-index.js 841 B
packages/db/dist/esm/indexes/base-index.js 1.25 kB
packages/db/dist/esm/indexes/basic-index.js 2.01 kB
packages/db/dist/esm/indexes/btree-index.js 2.3 kB
packages/db/dist/esm/indexes/index-registry.js 820 B
packages/db/dist/esm/indexes/reverse-index.js 370 B
packages/db/dist/esm/live-query-adapter.js 338 B
packages/db/dist/esm/live-query-observer.js 4.59 kB
packages/db/dist/esm/live-query-options.js 1.06 kB
packages/db/dist/esm/live-query-window-controller.js 4.12 kB
packages/db/dist/esm/local-only.js 1.08 kB
packages/db/dist/esm/local-storage.js 2.17 kB
packages/db/dist/esm/optimistic-action.js 359 B
packages/db/dist/esm/paced-mutations.js 702 B
packages/db/dist/esm/persisted-readiness.js 195 B
packages/db/dist/esm/proxy.js 3.17 kB
packages/db/dist/esm/query/builder/clone-query.js 766 B
packages/db/dist/esm/query/builder/functions.js 1.45 kB
packages/db/dist/esm/query/builder/index.js 6.81 kB
packages/db/dist/esm/query/builder/query-ir.js 116 B
packages/db/dist/esm/query/builder/ref-proxy-identity.js 292 B
packages/db/dist/esm/query/builder/ref-proxy.js 1.48 kB
packages/db/dist/esm/query/builder/wrapper-identity.js 221 B
packages/db/dist/esm/query/compiler/evaluators.js 2.1 kB
packages/db/dist/esm/query/compiler/expressions.js 603 B
packages/db/dist/esm/query/compiler/group-by.js 4.2 kB
packages/db/dist/esm/query/compiler/index.js 9.39 kB
packages/db/dist/esm/query/compiler/joins.js 3.06 kB
packages/db/dist/esm/query/compiler/lazy-targets.js 1.14 kB
packages/db/dist/esm/query/compiler/order-by.js 2 kB
packages/db/dist/esm/query/compiler/parent-routes.js 319 B
packages/db/dist/esm/query/compiler/query-equivalence.js 455 B
packages/db/dist/esm/query/compiler/route-metadata.js 1.24 kB
packages/db/dist/esm/query/compiler/select.js 1.59 kB
packages/db/dist/esm/query/effect.js 4.86 kB
packages/db/dist/esm/query/equality-conjunct.js 486 B
packages/db/dist/esm/query/equality-value-identity.js 591 B
packages/db/dist/esm/query/expression-helpers.js 1.45 kB
packages/db/dist/esm/query/ir-stable-identity.js 4.22 kB
packages/db/dist/esm/query/ir.js 1.7 kB
packages/db/dist/esm/query/live-query-collection.js 391 B
packages/db/dist/esm/query/live/bucket-facade-adapter.js 2.67 kB
packages/db/dist/esm/query/live/collection-config-builder.js 6.47 kB
packages/db/dist/esm/query/live/collection-registry.js 264 B
packages/db/dist/esm/query/live/collection-subscriber.js 2.05 kB
packages/db/dist/esm/query/live/graph-scheduler.js 303 B
packages/db/dist/esm/query/live/internal.js 145 B
packages/db/dist/esm/query/live/materialized-pipeline.js 2.32 kB
packages/db/dist/esm/query/live/ordered-source-loader.js 4.14 kB
packages/db/dist/esm/query/live/subset-demand-controller.js 1.65 kB
packages/db/dist/esm/query/live/utils.js 1.2 kB
packages/db/dist/esm/query/optimizer.js 2.92 kB
packages/db/dist/esm/query/pooled-live-query.js 4.06 kB
packages/db/dist/esm/query/query-once.js 359 B
packages/db/dist/esm/query/runtime-reference-identity.js 630 B
packages/db/dist/esm/query/subset-dedupe.js 493 B
packages/db/dist/esm/scheduler.js 1.13 kB
packages/db/dist/esm/SortedMap.js 1.6 kB
packages/db/dist/esm/strategies/debounceStrategy.js 331 B
packages/db/dist/esm/strategies/queueStrategy.js 488 B
packages/db/dist/esm/strategies/throttleStrategy.js 386 B
packages/db/dist/esm/sync-persistence.js 530 B
packages/db/dist/esm/transactions.js 3.89 kB
packages/db/dist/esm/utils.js 1.49 kB
packages/db/dist/esm/utils/array-utils.js 270 B
packages/db/dist/esm/utils/browser-polyfills.js 304 B
packages/db/dist/esm/utils/btree.js 3.02 kB
packages/db/dist/esm/utils/callbacks.js 174 B
packages/db/dist/esm/utils/comparison.js 1.59 kB
packages/db/dist/esm/utils/cursor.js 677 B
packages/db/dist/esm/utils/error.js 167 B
packages/db/dist/esm/utils/get-or-create.js 155 B
packages/db/dist/esm/utils/index-optimization.js 2.42 kB
packages/db/dist/esm/utils/source-record.js 140 B
packages/db/dist/esm/utils/type-guards.js 230 B
packages/db/dist/esm/utils/uuid.js 449 B
packages/db/dist/esm/virtual-props.js 413 B

compressed-size-action::db-package-size

@github-actions

github-actions Bot commented Oct 2, 2026

Copy link
Copy Markdown
Contributor

Size Change: 0 B

Total Size: 8.66 kB

ℹ️ View Unchanged
Filename Size
packages/react-db/dist/esm/DbProvider.js 317 B
packages/react-db/dist/esm/development.js 190 B
packages/react-db/dist/esm/HydrationBoundary.js 263 B
packages/react-db/dist/esm/index.js 330 B
packages/react-db/dist/esm/live-query-internals.js 282 B
packages/react-db/dist/esm/useLiveInfiniteQuery.js 1.93 kB
packages/react-db/dist/esm/useLiveQuery.js 3.27 kB
packages/react-db/dist/esm/useLiveQueryEffect.js 355 B
packages/react-db/dist/esm/useLiveSuspenseQuery.js 1.33 kB
packages/react-db/dist/esm/usePacedMutations.js 401 B

compressed-size-action::react-db-package-size

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant