Skip to content
Source
Sign inSign up
TanStack/db

feat(db): track applied loadSubset coverage #1774

ClosedKyleAMathews(GitHub profile, opens in a new tab)wants to merge 48 commits intocodex/loadsubset-outcome-plumbing fromcodex/loadsubset-coverage-registryopened

This adds a source-side coverage registry that publishes only exact, authoritative loadSubset facts backed by rows that have reached the collection. It also keeps cleanup retry-safe and restores Query DB's eager observer after TanStack Query removes its cache entry.

Root cause

Request intent and a resolved adapter Promise do not prove that a source has established reusable coverage. Coverage also cannot own adapter resources or rows implicitly: compaction, stale results, failed release, and cache removal each have different lifetimes.

Approach

  • Track demand leases, physical acquisitions, applied coverage, and row provenance as separate records.
  • Bind publication tokens to the exact collection, source, demand, and current generation.
  • Publish finite-prefix coverage only from applied row keys: either at least the requested limit, or fewer rows plus exact exhaustion.
  • Integrate publication and release with _sync.loadSubset and _sync.unloadSubset.
  • Keep release atomic. A throwing adapter callback leaves ownership intact, surfaces the original error, and can be retried without repeating callbacks that already succeeded.
  • Recreate Query DB's eager lifetime observer after cache removal without retiring its owned rows.

Key invariants

  • Requests and unknown extents establish no coverage.
  • Stale or mismatched outcomes establish neither rows nor coverage.
  • Public coverage facts are defensive immutable snapshots.
  • Coverage compaction never erases leases, acquisitions, or row ownership.
  • Logical retirement and GC happen only after every required release callback succeeds.
  • Query cache removal does not release eager collection ownership.

Non-goals

  • This PR does not yet use coverage to suppress or combine future load requests.
  • It does not change adapter query planning or public query syntax.

Verification

pnpm vitest run packages/db/tests/load-subset-outcome.test.ts packages/db/tests/query/coverage-registry-oracle.property.test.ts packages/db/tests/query/load-subset-oracle.property.test.ts packages/query-db-collection/tests/ownership-lifecycle.oracle.test.ts packages/query-db-collection/tests/query.test.ts --maxWorkers=1
pnpm --filter @tanstack/db test
pnpm --filter @tanstack/query-db-collection test
pnpm --filter @tanstack/db build
pnpm --filter @tanstack/query-db-collection build
pnpm --filter @tanstack/db lint
pnpm --filter @tanstack/query-db-collection lint

The coverage-registry command model also passes a 100× campaign of 10,000 generated histories.

Files changed

  • packages/db/src/query/coverage-registry.ts: coverage, ownership, generation, and retry-safe release state.
  • packages/db/src/collection/sync.ts: production load/unload integration.
  • packages/db/src/query/load-subset-outcome.ts and types: exact applied-row evidence.
  • packages/db/tests/query/coverage-registry-oracle.property.test.ts: command/state-machine oracle and focused laws.
  • packages/query-db-collection/src/query.ts: eager lifetime observer repair.
  • packages/db/src/query/live/ARCHITECTURE.md: source coverage and release contracts.

Depends on #1772. Part of #1657.

    1. Important

      Review skipped

      Auto reviews are disabled on base/target branches other than the default branch.

      Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

      ⚙️ Run configuration

      Configuration used: defaults

      Review profile: CHILL

      Plan: Pro Plus

      Run ID: 5e0d607b-f9d2-485e-b429-b11353dafcb7

      You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

      Use the checkbox below for a quick retry:

      • 🔍 Trigger review

      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.
    2. More templates

      @tanstack/angular-db

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

      @tanstack/browser-db-sqlite-persistence

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

      @tanstack/capacitor-db-sqlite-persistence

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

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

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

      @tanstack/db

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

      @tanstack/db-ivm

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

      @tanstack/db-sqlite-persistence-core

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

      @tanstack/electric-db-collection

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

      @tanstack/electron-db-sqlite-persistence

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

      @tanstack/expo-db-sqlite-persistence

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

      @tanstack/node-db-sqlite-persistence

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

      @tanstack/offline-transactions

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

      @tanstack/powersync-db-collection

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

      @tanstack/query-db-collection

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

      @tanstack/react-db

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

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

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

      @tanstack/react-router-with-db

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

      @tanstack/rxdb-db-collection

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

      @tanstack/solid-db

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

      @tanstack/svelte-db

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

      @tanstack/tauri-db-sqlite-persistence

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

      @tanstack/trailbase-db-collection

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

      @tanstack/vue-db

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

      commit: ea6fb69

    3. Size Change: +8.54 kB (+5.26%) 🔍

      Total Size: 171 kB

      📦 View Changed
      FilenameSizeChange
      packages/db/dist/esm/collection/state.js6.19 kB+421 B (+7.29%)🔍
      packages/db/dist/esm/collection/subscription.js6.32 kB+318 B (+5.3%)🔍
      packages/db/dist/esm/collection/sync.js7.48 kB+2.52 kB (+50.95%)🆘
      packages/db/dist/esm/query/builder/get-query-ir.js121 B+121 B (new file)🆕
      packages/db/dist/esm/query/builder/index.js6.6 kB+9 B (+0.14%)
      packages/db/dist/esm/query/coverage-registry.js4.75 kB+4.75 kB (new file)🆕
      packages/db/dist/esm/query/ir-stable-identity.js4.17 kB+96 B (+2.36%)
      packages/db/dist/esm/query/live/collection-config-builder.js7.32 kB+121 B (+1.68%)
      packages/db/dist/esm/query/live/collection-subscriber.js2.48 kB+64 B (+2.65%)
      packages/db/dist/esm/query/live/utils.js1.36 kB+10 B (+0.74%)
      packages/db/dist/esm/query/load-subset-outcome.js557 B+50 B (+9.86%)⚠️
      packages/db/dist/esm/query/runtime-reference-identity.js463 B+54 B (+13.2%)⚠️
      packages/db/dist/esm/query/subset-dedupe.js1.54 kB+11 B (+0.72%)
      ℹ️ View Unchanged
      FilenameSize
      packages/db/dist/esm/client.js3.66 kB
      packages/db/dist/esm/collection-options.js236 B
      packages/db/dist/esm/collection/change-events.js1.44 kB
      packages/db/dist/esm/collection/changes.js1.95 kB
      packages/db/dist/esm/collection/cleanup-queue.js810 B
      packages/db/dist/esm/collection/events.js434 B
      packages/db/dist/esm/collection/index.js3.99 kB
      packages/db/dist/esm/collection/indexes.js1.99 kB
      packages/db/dist/esm/collection/lifecycle.js1.86 kB
      packages/db/dist/esm/collection/mutations.js2.54 kB
      packages/db/dist/esm/collection/transaction-metadata.js144 B
      packages/db/dist/esm/deferred.js207 B
      packages/db/dist/esm/errors.js5.3 kB
      packages/db/dist/esm/event-emitter.js748 B
      packages/db/dist/esm/index.js3.79 kB
      packages/db/dist/esm/indexes/auto-index.js829 B
      packages/db/dist/esm/indexes/base-index.js784 B
      packages/db/dist/esm/indexes/basic-index.js2.17 kB
      packages/db/dist/esm/indexes/btree-index.js2.29 kB
      packages/db/dist/esm/indexes/index-registry.js820 B
      packages/db/dist/esm/indexes/reverse-index.js557 B
      packages/db/dist/esm/live-query-adapter.js318 B
      packages/db/dist/esm/live-query-observer.js3.65 kB
      packages/db/dist/esm/live-query-options.js702 B
      packages/db/dist/esm/live-query-window-controller.js4.43 kB
      packages/db/dist/esm/local-only.js975 B
      packages/db/dist/esm/local-storage.js2.18 kB
      packages/db/dist/esm/optimistic-action.js359 B
      packages/db/dist/esm/paced-mutations.js496 B
      packages/db/dist/esm/proxy.js3.75 kB
      packages/db/dist/esm/query/builder/functions.js1.47 kB
      packages/db/dist/esm/query/builder/ref-proxy.js1.24 kB
      packages/db/dist/esm/query/compiler/evaluators.js1.9 kB
      packages/db/dist/esm/query/compiler/expressions.js430 B
      packages/db/dist/esm/query/compiler/group-by.js3.69 kB
      packages/db/dist/esm/query/compiler/index.js8.71 kB
      packages/db/dist/esm/query/compiler/joins.js2.95 kB
      packages/db/dist/esm/query/compiler/lazy-targets.js1.11 kB
      packages/db/dist/esm/query/compiler/order-by.js1.8 kB
      packages/db/dist/esm/query/compiler/parent-routes.js319 B
      packages/db/dist/esm/query/compiler/route-metadata.js419 B
      packages/db/dist/esm/query/compiler/select.js1.58 kB
      packages/db/dist/esm/query/effect.js5.19 kB
      packages/db/dist/esm/query/expression-helpers.js1.43 kB
      packages/db/dist/esm/query/ir.js1.59 kB
      packages/db/dist/esm/query/live-query-collection.js391 B
      packages/db/dist/esm/query/live/bucket-facade-adapter.js2.76 kB
      packages/db/dist/esm/query/live/collection-registry.js264 B
      packages/db/dist/esm/query/live/internal.js145 B
      packages/db/dist/esm/query/live/materialized-pipeline.js2.47 kB
      packages/db/dist/esm/query/live/subset-demand-controller.js1.23 kB
      packages/db/dist/esm/query/load-subset-options.js1.08 kB
      packages/db/dist/esm/query/optimizer.js2.92 kB
      packages/db/dist/esm/query/predicate-utils.js3.38 kB
      packages/db/dist/esm/query/query-once.js359 B
      packages/db/dist/esm/scheduler.js1.43 kB
      packages/db/dist/esm/SortedMap.js1.3 kB
      packages/db/dist/esm/strategies/debounceStrategy.js247 B
      packages/db/dist/esm/strategies/queueStrategy.js428 B
      packages/db/dist/esm/strategies/throttleStrategy.js246 B
      packages/db/dist/esm/transactions.js3.5 kB
      packages/db/dist/esm/utils.js927 B
      packages/db/dist/esm/utils/array-utils.js273 B
      packages/db/dist/esm/utils/browser-polyfills.js304 B
      packages/db/dist/esm/utils/btree.js5.61 kB
      packages/db/dist/esm/utils/comparison.js1.34 kB
      packages/db/dist/esm/utils/cursor.js457 B
      packages/db/dist/esm/utils/index-optimization.js2.39 kB
      packages/db/dist/esm/utils/type-guards.js157 B
      packages/db/dist/esm/utils/uuid.js449 B
      packages/db/dist/esm/virtual-props.js360 B
      compressed-size-action::db-package-size
    4. Size Change: 0 B

      Total Size: 7.25 kB

      ℹ️ View Unchanged
      FilenameSize
      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.81 kB
      packages/react-db/dist/esm/useLiveQuery.js2.68 kB
      packages/react-db/dist/esm/useLiveQueryEffect.js355 B
      packages/react-db/dist/esm/useLiveSuspenseQuery.js812 B
      packages/react-db/dist/esm/usePacedMutations.js401 B
      compressed-size-action::react-db-package-size
    5. Closing as superseded by merged #1797. The general coverage-registry design was deliberately not shipped; the consolidated implementation uses exact-request deduplication and authoritative recovery. Remaining RFC #1657 requirements are not all complete.

Sign in to join this conversation.