feat(db): track applied loadSubset coverage #1774
codex/loadsubset-outcome-plumbing fromcodex/loadsubset-coverage-registry·opened 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.loadSubsetand_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.tsand 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.
- 1
More templates
- todos
- offline-first-electron
- offline-transactions-react-native
- shopping-list-react-native
- @tanstack/db-example-solid-todo
- @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@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@1774commit:
ea6fb69Size Change: +8.54 kB (+5.26%) 🔍
Total Size: 171 kB
📦 View Changed
Filename Size Change 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%) compressed-size-action::db-package-sizeℹ️ View Unchanged
Filename Size 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 Size Change: 0 B
Total Size: 7.25 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/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 KyleAMathews(GitHub profile, opens in a new tab) closed this
Sign in to join this conversation.
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.yamlfile in this repository. To trigger a single review, invoke the@coderabbitai reviewcommand.⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID:
5e0d607b-f9d2-485e-b429-b11353dafcb7You can disable this status message by setting the
reviews.review_statustofalsein the CodeRabbit configuration file.Use the checkbox below for a quick retry:
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