test(db): cover includes query-shape bugs

[KyleAMathews]

This adds three independent recompute-oracle drivers for includes query shapes: join multiplicity, correlation through a joined alias, and nullable findOne() materialization. Each driver pins a known failure while nearby control cases remain green; this PR changes tests only.

Approach

Each case uses the shared trace runner with a small driver for live state and a separate projection that recomputes the expected result from plain model state.

• Join multiplicity (innerJoin drops a live-query result when one of many children is deleted #1703): generate two to five matching children, delete one contributor, and assert the parent remains visible. The known mismatch occurs at checkpoint 1; deleting the sole contributor is the green control.
• Joined-alias correlation (materialize() subquery resolves to [] when its correlation predicate targets a joined alias #1704): materialize a subquery whose predicate targets an alias introduced by an inner join. The known mismatch occurs at checkpoint 0; correlation through the source alias is the green control.
• Nullable findOne() correlation (materialize(q…findOne()) resolves to null, not undefined, when the correlation key is itself null #1706): start with a null correlation key and expect undefined. The known mismatch occurs at checkpoint 0 because the live result contains null. An unmatched non-null key and a matched key updated to null both remain green, which narrows the defect to rows that start null.

The property cases use fixed seeds, 12 runs, and bounded integer or child-count ranges. The nullable driver also gives collection ingestion and the recompute model separate row objects so a live-side mutation cannot alter the expected state.

Key invariants

• Expected rows come from independent model state, not from query-engine output.
• Each expected failure is bound to the exact checkpoint where the oracle first diverges.
• Green controls vary one relevant condition around each failure boundary.
• Generated values stay small and deterministic enough to reproduce from CI output.

Non-goals

• Fixing the three runtime defects or closing their issues.
• Expanding into publication timing, work-count, or longer transition-history drivers.
• Refactoring the shared trace-runner framework from test(db): fuzz visible includes relationship transitions #1722.

This PR is intentionally stacked on #1722 (codex/includes-state-aware-transitions) so reviewers see only the query-shape oracle work.

Trade-offs

The three drivers remain local and independent instead of introducing a broader query-shape abstraction. That keeps the failure boundaries readable and this stacked PR small, while the bounded fast-check variants still test that each classification is not tied to one fixture value.

Verification

pnpm exec vitest run packages/db/tests/query/includes-oracle.property.test.ts packages/db/tests/query/includes-temporal-oracle.test.ts packages/db/tests/query/includes-query-shape-oracle.test.ts
pnpm exec tsc --noEmit -p packages/db/tsconfig.json
pnpm exec eslint packages/db/tests/query/includes-query-shape-oracle.test.ts
pnpm exec prettier --check packages/db/tests/query/includes-query-shape-oracle.test.ts
git diff --check fa63e888dce4ff0bc01b922e4622a8283d641d38..HEAD

The combined oracle run passes 52 tests, including the expected-failure classifications.

Files changed

• packages/db/tests/query/includes-query-shape-oracle.test.ts — adds the three drivers, their recompute projections, bounded generated variants, and green controls.

---

Refs #1658, #1703, #1704, #1706

[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: 204caf10-bfce-4e07-a0e7-9bcc3c0ed555

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-start-example-basic
• @tanstack/db-example-paced-mutations-demo
• tanstack-start-db-projects-example
• @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@1725

@tanstack/browser-db-sqlite-persistence

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

@tanstack/capacitor-db-sqlite-persistence

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

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

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

@tanstack/db

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

@tanstack/db-ivm

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

@tanstack/db-sqlite-persistence-core

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

@tanstack/electric-db-collection

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

@tanstack/electron-db-sqlite-persistence

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

@tanstack/expo-db-sqlite-persistence

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

@tanstack/node-db-sqlite-persistence

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

@tanstack/offline-transactions

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

@tanstack/powersync-db-collection

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

@tanstack/query-db-collection

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

@tanstack/react-db

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

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

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

@tanstack/rxdb-db-collection

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

@tanstack/solid-db

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

@tanstack/svelte-db

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

@tanstack/tauri-db-sqlite-persistence

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

@tanstack/trailbase-db-collection

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

@tanstack/vue-db

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

commit: c60ff3d

[github-actions]

Size Change: 0 B

Total Size: 132 kB

ℹ️ View Unchanged

Filename	Size
packages/db/dist/esm/collection/change-events.js	1.44 kB
packages/db/dist/esm/collection/changes.js	1.51 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.86 kB
packages/db/dist/esm/collection/indexes.js	1.99 kB
packages/db/dist/esm/collection/lifecycle.js	1.7 kB
packages/db/dist/esm/collection/mutations.js	2.47 kB
packages/db/dist/esm/collection/state.js	5.51 kB
packages/db/dist/esm/collection/subscription.js	3.77 kB
packages/db/dist/esm/collection/sync.js	3.05 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.16 kB
packages/db/dist/esm/event-emitter.js	748 B
packages/db/dist/esm/index.js	3.26 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	2.35 kB
packages/db/dist/esm/live-query-window-controller.js	3.04 kB
packages/db/dist/esm/local-only.js	916 B
packages/db/dist/esm/local-storage.js	2.12 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/index.js	5.84 kB
packages/db/dist/esm/query/builder/ref-proxy.js	1.24 kB
packages/db/dist/esm/query/compiler/evaluators.js	1.89 kB
packages/db/dist/esm/query/compiler/expressions.js	430 B
packages/db/dist/esm/query/compiler/group-by.js	3.56 kB
packages/db/dist/esm/query/compiler/index.js	6.67 kB
packages/db/dist/esm/query/compiler/joins.js	2.5 kB
packages/db/dist/esm/query/compiler/lazy-targets.js	923 B
packages/db/dist/esm/query/compiler/order-by.js	1.74 kB
packages/db/dist/esm/query/compiler/select.js	1.53 kB
packages/db/dist/esm/query/effect.js	4.77 kB
packages/db/dist/esm/query/expression-helpers.js	1.43 kB
packages/db/dist/esm/query/ir.js	1.25 kB
packages/db/dist/esm/query/live-query-collection.js	360 B
packages/db/dist/esm/query/live/collection-config-builder.js	9.32 kB
packages/db/dist/esm/query/live/collection-registry.js	264 B
packages/db/dist/esm/query/live/collection-subscriber.js	1.95 kB
packages/db/dist/esm/query/live/internal.js	145 B
packages/db/dist/esm/query/live/utils.js	1.81 kB
packages/db/dist/esm/query/optimizer.js	2.92 kB
packages/db/dist/esm/query/predicate-utils.js	2.97 kB
packages/db/dist/esm/query/query-once.js	359 B
packages/db/dist/esm/query/subset-dedupe.js	960 B
packages/db/dist/esm/scheduler.js	1.3 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.04 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.15 kB
packages/db/dist/esm/utils/cursor.js	457 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: 3.79 kB

ℹ️ View Unchanged

Filename	Size
packages/react-db/dist/esm/index.js	249 B
packages/react-db/dist/esm/useLiveInfiniteQuery.js	1.29 kB
packages/react-db/dist/esm/useLiveQuery.js	920 B
packages/react-db/dist/esm/useLiveQueryEffect.js	355 B
packages/react-db/dist/esm/useLiveSuspenseQuery.js	567 B
packages/react-db/dist/esm/usePacedMutations.js	401 B

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