Skip to content
Source
Sign inSign up
TanStack/db

fix(query-db): compose accepted ownership before publication #2198

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

Why this matters

An ordered refetch could retain a backend-absent row after another Query observed that row. The failure required an optimistic mutation to delay publication.

PR #2030 introduced the accepted-before-publication interval. PR #2154 exposed the regression through its ordered-prefix oracle.

The failing CI replay showed the concrete result. The ordered window disagreed with the backend after publication resumed.

Cause

The Query ownership indexes accepted newer results before the Collection published their metadata. Cleanup could then rebuild ownership from older published metadata.

That stale metadata could restore an owner that an accepted result retired. An older cleanup could also invalidate ownership from a later reacquisition.

The same authority problem made cold restore depend on row order. Processing one row could make a partially rebuilt Query appear fully resolved.

Repair

Resolved Query ownership now takes precedence over persisted ownership. Persisted metadata seeds only Queries that do not yet have a resolved ownership result.

Each accepted result installs a new ownership generation. Cleanup removes its accepted edges immediately and keeps an empty tombstone until publication completes.

The tombstone retires only when it still belongs to that cleanup. Therefore, an older cleanup cannot invalidate a later acquisition.

Cold persisted and hydrated rows project their owners before they update the ownership indexes. This makes reconstruction independent of row order.

This repair reuses the existing ownership indexes. Production source changes by 54 additions and 60 deletions.

Excluding comments and blank lines, production code changes by 49 additions and 53 deletions.

Oracle model

The ownership oracle does not copy the production maps or cleanup algorithm. Its model stores each active Query's latest complete result.

The expected public Collection is the union of those results. The histories compare that model with public rows and durable effects at defined checkpoints.

New histories cover these cases:

  • Three overlapping owners accept two empty results while an optimistic mutation delays publication.
  • A Query releases and reacquires before its older cleanup publishes.
  • A cold two-row result restores in both persisted scan orders.
  • A hydrated two-row result restores in both hydration orders.
  • The original ordered-refetch history excludes a backend-absent row after publication resumes.

The oracle documentation records the covered histories and the remaining limits.

Verification

  • pnpm vitest run packages/query-db-collection/tests/ownership-lifecycle.oracle.test.ts packages/query-db-collection/tests/refetch-ordered-prefix-oracle.test.ts --pool-options.threads.maxThreads=2 passed 379 tests.
  • The exact query-db.refetch-ordered-prefix CI replay passed with seed -1338032236 and its recorded path.
  • pnpm --filter @tanstack/query-db-collection build passed.
  • The Prettier check and git diff --check passed.

Summary by CodeRabbit

  • Bug Fixes
    • Improved query cleanup during overlapping refetches and observer changes, helping prevent outdated results from removing data that is still needed.
    • Updated complete query results more reliably when replacing persisted or hydrated data, including removing rows omitted from the latest result.
    • Preserved refreshed results when an invalidation and refetch overlap with an optimistic update.
    1. 🦋 Changeset detected

      Latest commit: de1ea0d38c27d2ebe5fd37208f7ef84fced97fbc

      The changes in this PR will be included in the next version bump.

      This PR includes changesets to release 1 package
      NameType
      @tanstack/query-db-collectionPatch

      Not sure what this means? Click here to learn what changesets are.

      Click here if you're a maintainer who wants to add another changeset to this PR

    2. Review in Change Stack →

      No actionable comments were generated in the recent review. 🎉

      ℹ️ Recent review info
      ⚙️ Run configuration
      • Configuration used: defaults
      • Review profile: CHILL
      • Plan: Advanced
      • Run ID: 9291fda4-f97b-474c-937f-8b47a9657e58
      📥 Commits

      Reviewing files that changed from the base of the PR and between 7d60818831806dc1a64ad61872533886ce875dbf and de1ea0d38c27d2ebe5fd37208f7ef84fced97fbc.

      📒 Files selected for processing: 5
      • .changeset/fix-refetch-query-ownership.md
      • docs/contributing/oracle-coverage.md
      • packages/query-db-collection/src/query.ts
      • packages/query-db-collection/tests/ownership-lifecycle.oracle.test.ts
      • packages/query-db-collection/tests/refetch-ordered-prefix-oracle.test.ts

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

      📝 Walkthrough

      Query ownership resolution and cleanup now account for persisted ownership, complete query results, and overlapping refetch and observer lifecycles. Added oracle tests cover ownership reconstruction, delayed publication, reacquisition, and refetch ordering.

      Changes: Query ownership lifecycle

      Layer / File(s)Summary
      Resolve and reconstruct query ownership
      packages/query-db-collection/src/query.ts, packages/query-db-collection/tests/ownership-lifecycle.oracle.test.ts, docs/contributing/oracle-coverage.md
      Ownership resolution combines persisted and in-memory claims. Persisted owner sets are snapshotted before reconstruction. Successful query results initialize the ownership baseline from previously owned rows. Tests cover cold scans and hydration in both row orders.
      Retire ownership across query lifecycles
      packages/query-db-collection/src/query.ts, packages/query-db-collection/tests/ownership-lifecycle.oracle.test.ts, packages/query-db-collection/tests/refetch-ordered-prefix-oracle.test.ts, docs/contributing/oracle-coverage.md, .changeset/fix-refetch-query-ownership.md
      Cleanup updates ownership maps and retires ownership after transaction application. Tests cover delayed releases, reacquisition, accepted empty results, and refetch ordering. The changeset describes the ownership cleanup fix.

      Priority: ➖ Normal

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

      Change: Bug fix

      Suggested reviewers: samwillis

      Merge Risk: ⚪ Minimal · up to de1ea

      No change-specific issue remains identified before merge; normal checks still apply.

      Pre-merge checks: Passed 4 · Failed 1
      Failed Failed checks: 1 warning
      Check nameStatusExplanationResolution
      Docstring CoverageWarningDocstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 3 files. (2 skipped: 2 …Write docstrings for the functions missing them to satisfy the coverage threshold.
      Passed Passed checks: 4 passed
      Check nameStatusExplanation
      Title checkPassedThe title is concise, specific, and accurately describes the main ownership-composition fix.
      Description checkPassedThe description provides detailed motivation, cause, repair, oracle coverage, and verification results. It does not use the template headings or include the required Checklist and Release Impact secti…
      Linked Issues checkPassedCheck skipped because no linked issues were found for this pull request.
      Out of Scope Changes checkPassedCheck skipped because no linked issues were found for this pull request.
      Full details: Description check

      Explanation

      The description provides detailed motivation, cause, repair, oracle coverage, and verification results. It does not use the template headings or include the required Checklist and Release Impact sections, but the substantive information is mostly complete.

      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 1 functions across 3 files. (2 skipped: 2 unsupported.)

      Resolution

      Write docstrings for the functions missing them to satisfy the coverage threshold.

      • 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
      • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

      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. Size Change: 0 B

      Total Size: 218 kB

      ℹ️ View Unchanged
      FilenameSize
      packages/db/dist/esm/client.js4.22 kB
      packages/db/dist/esm/collection-options-brand.js219 B
      packages/db/dist/esm/collection-options.js258 B
      packages/db/dist/esm/collection/change-events.js1.76 kB
      packages/db/dist/esm/collection/changes.js2.96 kB
      packages/db/dist/esm/collection/cleanup-queue.js901 B
      packages/db/dist/esm/collection/config-errors.js547 B
      packages/db/dist/esm/collection/events.js481 B
      packages/db/dist/esm/collection/index.js5.27 kB
      packages/db/dist/esm/collection/indexes.js2.3 kB
      packages/db/dist/esm/collection/lifecycle.js2.94 kB
      packages/db/dist/esm/collection/mutations.js2.99 kB
      packages/db/dist/esm/collection/state.js7.16 kB
      packages/db/dist/esm/collection/subscription.js8.9 kB
      packages/db/dist/esm/collection/sync.js5.4 kB
      packages/db/dist/esm/collection/validate-config.js1.17 kB
      packages/db/dist/esm/deferred.js207 B
      packages/db/dist/esm/error-message.js642 B
      packages/db/dist/esm/errors.js6.53 kB
      packages/db/dist/esm/event-emitter.js1.06 kB
      packages/db/dist/esm/index.js4.52 kB
      packages/db/dist/esm/indexed-db-wrapper.js1.91 kB
      packages/db/dist/esm/indexed-db.js3.7 kB
      packages/db/dist/esm/indexes/auto-index.js924 B
      packages/db/dist/esm/indexes/base-index.js1.92 kB
      packages/db/dist/esm/indexes/basic-index.js1.93 kB
      packages/db/dist/esm/indexes/btree-index.js1.62 kB
      packages/db/dist/esm/indexes/index-registry.js916 B
      packages/db/dist/esm/indexes/reverse-index.js1.01 kB
      packages/db/dist/esm/live-query-adapter.js338 B
      packages/db/dist/esm/live-query-observer.js4.8 kB
      packages/db/dist/esm/live-query-options.js1.41 kB
      packages/db/dist/esm/live-query-window-controller.js4.27 kB
      packages/db/dist/esm/local-only.js1.08 kB
      packages/db/dist/esm/local-storage.js3.93 kB
      packages/db/dist/esm/optimistic-action.js359 B
      packages/db/dist/esm/paced-mutations.js1.11 kB
      packages/db/dist/esm/persisted-readiness.js195 B
      packages/db/dist/esm/proxy.js3.51 kB
      packages/db/dist/esm/query/builder/clone-query.js849 B
      packages/db/dist/esm/query/builder/functions.js1.56 kB
      packages/db/dist/esm/query/builder/index.js7.48 kB
      packages/db/dist/esm/query/builder/query-ir.js312 B
      packages/db/dist/esm/query/builder/ref-proxy-identity.js292 B
      packages/db/dist/esm/query/builder/ref-proxy.js1.67 kB
      packages/db/dist/esm/query/builder/wrapper-identity.js221 B
      packages/db/dist/esm/query/compiler/evaluators.js2.51 kB
      packages/db/dist/esm/query/compiler/expressions.js603 B
      packages/db/dist/esm/query/compiler/group-by.js4.48 kB
      packages/db/dist/esm/query/compiler/index.js10.3 kB
      packages/db/dist/esm/query/compiler/joins.js3.42 kB
      packages/db/dist/esm/query/compiler/lazy-targets.js1.11 kB
      packages/db/dist/esm/query/compiler/order-by.js2.8 kB
      packages/db/dist/esm/query/compiler/parent-routes.js319 B
      packages/db/dist/esm/query/compiler/query-equivalence.js568 B
      packages/db/dist/esm/query/compiler/route-metadata.js1.24 kB
      packages/db/dist/esm/query/compiler/select.js1.5 kB
      packages/db/dist/esm/query/effect.js5.36 kB
      packages/db/dist/esm/query/equality-conjunct.js486 B
      packages/db/dist/esm/query/equality-value-identity.js735 B
      packages/db/dist/esm/query/expression-helpers.js1.61 kB
      packages/db/dist/esm/query/ir-stable-identity.js4.2 kB
      packages/db/dist/esm/query/ir.js2.2 kB
      packages/db/dist/esm/query/join-conditions.js257 B
      packages/db/dist/esm/query/live-query-collection.js391 B
      packages/db/dist/esm/query/live/bucket-facade-adapter.js3.17 kB
      packages/db/dist/esm/query/live/collection-config-builder.js6.84 kB
      packages/db/dist/esm/query/live/collection-registry.js264 B
      packages/db/dist/esm/query/live/collection-subscriber.js2.28 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.39 kB
      packages/db/dist/esm/query/live/ordered-source-loader.js5.35 kB
      packages/db/dist/esm/query/live/subset-demand-controller.js1.73 kB
      packages/db/dist/esm/query/live/utils.js1.35 kB
      packages/db/dist/esm/query/optimizer.js2.95 kB
      packages/db/dist/esm/query/pooled-live-query.js4.13 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.23 kB
      packages/db/dist/esm/SortedMap.js1.6 kB
      packages/db/dist/esm/strategies/commit-completion.js156 B
      packages/db/dist/esm/strategies/debounceStrategy.js658 B
      packages/db/dist/esm/strategies/queueStrategy.js523 B
      packages/db/dist/esm/strategies/serial-pacer.js486 B
      packages/db/dist/esm/strategies/throttleStrategy.js738 B
      packages/db/dist/esm/sync-persistence.js626 B
      packages/db/dist/esm/sync-receipt.js211 B
      packages/db/dist/esm/transaction-commit-work.js351 B
      packages/db/dist/esm/transactions.js4.61 kB
      packages/db/dist/esm/utils.js1.67 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.94 kB
      packages/db/dist/esm/utils/cursor.js753 B
      packages/db/dist/esm/utils/error.js262 B
      packages/db/dist/esm/utils/get-or-create.js155 B
      packages/db/dist/esm/utils/index-optimization.js2.58 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.js530 B
      packages/db/dist/esm/virtual-props.js413 B
      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/source-id-bindings.js746 B
      packages/react-db/dist/esm/useLiveInfiniteQuery.js2.15 kB
      packages/react-db/dist/esm/useLiveQuery.js3.34 kB
      packages/react-db/dist/esm/useLiveQueryEffect.js504 B
      packages/react-db/dist/esm/useLiveSuspenseQuery.js1.33 kB
      packages/react-db/dist/esm/usePacedMutations.js429 B
      compressed-size-action::db-and-react-package-size
    4. More templates

      @tanstack/angular-db

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

      @tanstack/browser-db-sqlite-persistence

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

      @tanstack/capacitor-db-sqlite-persistence

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

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

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

      @tanstack/db

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

      @tanstack/db-ivm

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

      @tanstack/db-sqlite-persistence-core

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

      @tanstack/electric-db-collection

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

      @tanstack/electron-db-sqlite-persistence

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

      @tanstack/expo-db-sqlite-persistence

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

      @tanstack/node-db-sqlite-persistence

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

      @tanstack/offline-transactions

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

      @tanstack/powersync-db-collection

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

      @tanstack/query-db-collection

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

      @tanstack/react-db

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

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

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

      @tanstack/react-router-with-db

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

      @tanstack/rxdb-db-collection

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

      @tanstack/solid-db

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

      @tanstack/svelte-db

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

      @tanstack/tauri-db-sqlite-persistence

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

      @tanstack/trailbase-db-collection

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

      @tanstack/vue-db

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

      commit: de1ea0d

    5. 🎉 This PR has been released!

      Thank you for your contribution!

Sign in to join this conversation.