test(db): add loadSubset refinement oracle foundation

[KyleAMathews]

Adds a compositional refinement oracle for the remaining loadSubset lifecycle work. It changes no runtime behavior; it gives later RFC fixes a small independent model, real Collection boundary drivers, and adapter conformance checks.

Approach

• Extend the shared event vocabulary with independent projections for demand ownership, physical acquisition sharing, applied settlement, source readiness, transaction receipts, replay replacement, and retained rows.
• Compare shared and separate exact acquisitions through real Collections, downstream live-query rows, event batches, callback-time reads, and physical start counts.
• Exercise replay failure and overlap, cross-source readiness, and abort timing at their public Collection boundaries.
• Replay the same final-owner release/remount history through Electric and PowerSync.
• Run every generated refinement law with both a committed fixed seed and a random or replayed seed. The documented test:oracles command now includes the full 20-suite oracle hierarchy.

Key invariants

• Sharing exact physical work may reduce starts, but cannot change per-owner settlement or visible rows.
• A demand becomes reusable only after authoritative rows are applied; evidence-free settlement must permit a later retry.
• Receipts settle only after coherent publication, including callback-time reads.
• Failed replay preserves the last complete publication; overlapping replay publishes only the newest complete success.
• Initial readiness waits for every reachable source and does not expose partial joined output.
• Final-owner release invalidates adapter evidence, so a later remount reloads the same semantic rows.

Non-goals and trade-offs

• No runtime or adapter behavior changes.
• The oracle is compositional rather than a monolithic simulator. Small projections remain easy to inspect; generated component models and real boundary drivers cover the points where planes meet.
• No changeset: internal tests and architecture notes do not change a published package.

Verification

cd packages/db
pnpm test:oracles --silent=passed-only --pool-options.threads.maxThreads=2

TANSTACK_DB_ORACLE_RUNS_MULTIPLIER=100 pnpm vitest run \
  tests/query/load-subset-refinement-model.property.test.ts \
  tests/query/load-subset-replay-refinement-oracle.property.test.ts \
  tests/query/load-subset-source-readiness-refinement-oracle.property.test.ts \
  tests/query/load-subset-transaction-refinement-oracle.property.test.ts \
  --silent=passed-only --pool-options.threads.maxThreads=2

• DB oracle command: 20 files, 546 tests passed; no type errors.
• 100× refinement campaign: 4 files, 26 tests passed; no type errors.
• Electric and PowerSync remount conformance tests passed; no type errors.
• ESLint, Prettier, and git diff --check passed.

Files changed

• packages/db/tests/load-subset-full-flow-model.ts: independent refinement projections.
• packages/db/tests/query/load-subset-*-refinement-*.test.ts: model laws and real Collection drivers.
• Electric and PowerSync on-demand suites: adapter remount conformance.
• packages/db/src/query/live/ARCHITECTURE.md and packages/db/package.json: executable-contract map and complete oracle command.

---

Stacked on #1778.
Related to #1657.

[coderabbitai]

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: 1e95fe09-b71a-4613-9896-2d852d26dd9b

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

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[pkg-pr-new]

More templates

• todos
• offline-first-electron
• @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
• offline-transactions-react-native
• shopping-list-react-native
• @tanstack/db-example-solid-todo

@tanstack/angular-db

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

@tanstack/browser-db-sqlite-persistence

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

@tanstack/capacitor-db-sqlite-persistence

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

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

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

@tanstack/db

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

@tanstack/db-ivm

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

@tanstack/db-sqlite-persistence-core

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

@tanstack/electric-db-collection

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

@tanstack/electron-db-sqlite-persistence

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

@tanstack/expo-db-sqlite-persistence

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

@tanstack/node-db-sqlite-persistence

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

@tanstack/offline-transactions

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

@tanstack/powersync-db-collection

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

@tanstack/query-db-collection

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

@tanstack/react-db

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

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

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

@tanstack/react-router-with-db

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

@tanstack/rxdb-db-collection

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

@tanstack/solid-db

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

@tanstack/svelte-db

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

@tanstack/tauri-db-sqlite-persistence

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

@tanstack/trailbase-db-collection

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

@tanstack/vue-db

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

commit: b5fc012

[github-actions]

Size Change: 0 B

Total Size: 173 kB

ℹ️ View Unchanged

Filename	Size
packages/db/dist/esm/client.js	3.66 kB
packages/db/dist/esm/collection-options.js	236 B
packages/db/dist/esm/collection/change-events.js	1.47 kB
packages/db/dist/esm/collection/changes.js	1.95 kB
packages/db/dist/esm/collection/cleanup-queue.js	810 B
packages/db/dist/esm/collection/events.js	434 B
packages/db/dist/esm/collection/index.js	3.99 kB
packages/db/dist/esm/collection/indexes.js	1.99 kB
packages/db/dist/esm/collection/lifecycle.js	1.86 kB
packages/db/dist/esm/collection/mutations.js	2.54 kB
packages/db/dist/esm/collection/state.js	6.08 kB
packages/db/dist/esm/collection/subscription.js	6.69 kB
packages/db/dist/esm/collection/sync.js	7.12 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.3 kB
packages/db/dist/esm/event-emitter.js	748 B
packages/db/dist/esm/index.js	3.79 kB
packages/db/dist/esm/indexes/auto-index.js	829 B
packages/db/dist/esm/indexes/base-index.js	784 B
packages/db/dist/esm/indexes/basic-index.js	2.17 kB
packages/db/dist/esm/indexes/btree-index.js	2.29 kB
packages/db/dist/esm/indexes/index-registry.js	820 B
packages/db/dist/esm/indexes/reverse-index.js	557 B
packages/db/dist/esm/live-query-adapter.js	318 B
packages/db/dist/esm/live-query-observer.js	3.65 kB
packages/db/dist/esm/live-query-options.js	702 B
packages/db/dist/esm/live-query-window-controller.js	4.43 kB
packages/db/dist/esm/local-only.js	975 B
packages/db/dist/esm/local-storage.js	2.18 kB
packages/db/dist/esm/optimistic-action.js	359 B
packages/db/dist/esm/paced-mutations.js	496 B
packages/db/dist/esm/proxy.js	3.75 kB
packages/db/dist/esm/query/builder/functions.js	1.47 kB
packages/db/dist/esm/query/builder/get-query-ir.js	121 B
packages/db/dist/esm/query/builder/index.js	6.6 kB
packages/db/dist/esm/query/builder/ref-proxy.js	1.24 kB
packages/db/dist/esm/query/compiler/evaluators.js	1.9 kB
packages/db/dist/esm/query/compiler/expressions.js	430 B
packages/db/dist/esm/query/compiler/group-by.js	3.69 kB
packages/db/dist/esm/query/compiler/index.js	8.71 kB
packages/db/dist/esm/query/compiler/joins.js	2.95 kB
packages/db/dist/esm/query/compiler/lazy-targets.js	1.11 kB
packages/db/dist/esm/query/compiler/order-by.js	1.81 kB
packages/db/dist/esm/query/compiler/parent-routes.js	319 B
packages/db/dist/esm/query/compiler/route-metadata.js	419 B
packages/db/dist/esm/query/compiler/select.js	1.58 kB
packages/db/dist/esm/query/coverage-registry.js	3.49 kB
packages/db/dist/esm/query/effect.js	5.31 kB
packages/db/dist/esm/query/expression-helpers.js	1.43 kB
packages/db/dist/esm/query/ir-stable-identity.js	4.17 kB
packages/db/dist/esm/query/ir.js	1.59 kB
packages/db/dist/esm/query/live-query-collection.js	391 B
packages/db/dist/esm/query/live/bucket-facade-adapter.js	2.76 kB
packages/db/dist/esm/query/live/collection-config-builder.js	7.32 kB
packages/db/dist/esm/query/live/collection-registry.js	264 B
packages/db/dist/esm/query/live/collection-subscriber.js	2.63 kB
packages/db/dist/esm/query/live/internal.js	145 B
packages/db/dist/esm/query/live/materialized-pipeline.js	2.47 kB
packages/db/dist/esm/query/live/subset-demand-controller.js	1.23 kB
packages/db/dist/esm/query/live/utils.js	1.36 kB
packages/db/dist/esm/query/live/window-state.js	1.77 kB
packages/db/dist/esm/query/load-subset-options.js	1.08 kB
packages/db/dist/esm/query/load-subset-outcome.js	557 B
packages/db/dist/esm/query/optimizer.js	2.92 kB
packages/db/dist/esm/query/predicate-utils.js	3.38 kB
packages/db/dist/esm/query/query-once.js	359 B
packages/db/dist/esm/query/runtime-reference-identity.js	446 B
packages/db/dist/esm/query/subset-dedupe.js	1.54 kB
packages/db/dist/esm/query/total-order.js	604 B
packages/db/dist/esm/scheduler.js	1.43 kB
packages/db/dist/esm/SortedMap.js	1.3 kB
packages/db/dist/esm/strategies/debounceStrategy.js	247 B
packages/db/dist/esm/strategies/queueStrategy.js	428 B
packages/db/dist/esm/strategies/throttleStrategy.js	246 B
packages/db/dist/esm/transactions.js	3.5 kB
packages/db/dist/esm/utils.js	927 B
packages/db/dist/esm/utils/array-utils.js	273 B
packages/db/dist/esm/utils/browser-polyfills.js	304 B
packages/db/dist/esm/utils/btree.js	5.61 kB
packages/db/dist/esm/utils/comparison.js	1.39 kB
packages/db/dist/esm/utils/cursor.js	699 B
packages/db/dist/esm/utils/index-optimization.js	2.39 kB
packages/db/dist/esm/utils/type-guards.js	157 B
packages/db/dist/esm/utils/uuid.js	449 B
packages/db/dist/esm/virtual-props.js	360 B

_{compressed-size-action::db-package-size}

[github-actions]

Size Change: 0 B

Total Size: 7.25 kB

ℹ️ View Unchanged

Filename	Size
packages/react-db/dist/esm/DbProvider.js	317 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.81 kB
packages/react-db/dist/esm/useLiveQuery.js	2.68 kB
packages/react-db/dist/esm/useLiveQueryEffect.js	355 B
packages/react-db/dist/esm/useLiveSuspenseQuery.js	812 B
packages/react-db/dist/esm/usePacedMutations.js	401 B

_{compressed-size-action::react-db-package-size}