test(db): fuzz visible includes relationship transitions #1722
main fromrefs/pull/1722/head·merged by tannerlinsley This adds state-aware property scenarios for visible includes relationship transitions across query depths and target levels. It expands recompute-oracle coverage and pins known divergences; it does not change runtime behavior or fix the bugs it exposes.
Approach#
- Build two fully connected, visible branches with generated, disjoint ID and relationship-key ranges.
- Select an existing visible row at each target level, then either reparent it to the other branch or change its relationship key.
- Add connected scalar updates before the transition and on the stable branch afterward so the generated traces exercise real query state instead of disconnected noise.
- Enumerate depth and target-level pairs in the test matrix, while fuzzing source branch, row identities, relationship keys, scalar values, positions, and operation order.
- Assert that the recomputed result changes at the forced transition before comparing incremental output with the oracle.
Known divergence boundaries#
- A visible rekey is an exact expected failure only when at least two descendant levels remain:
targetLevel + 2 <= depth. - A deterministic depth-4 trace records a newly found bug: after a level-1 subtree is reparented, later scalar updates at levels 2 and 3 leave incremental output stale at checkpoint 8.
Each expected failure is pinned to the exact checkpoint. If the implementation stops failing there, the test fails and prompts us to turn the trace into a passing regression.
Key invariants#
- Every forced relationship transition targets a row that exists and is visible immediately before the transition.
- Generated ID and relationship-key ranges cannot collide across branches or with rekey values.
- Recomputation must observe a changed result at the forced transition.
- The generated green corpus must match recomputation at every checkpoint.
Non-goals#
- Fix any relationship-routing or moved-subtree propagation bug.
- Treat known divergences as passing behavior.
- Randomize post-transition updates on the moved branch in the green corpus. That path exposes the separately pinned moved-subtree bug and can join the corpus after the runtime fix.
Trade-offs#
The matrix enumerates all depth/target-level combinations and uses a small deterministic fuzz sample within each pair. This gives structural coverage without making the suite slow or leaving rare target levels to chance.
Verification#
pnpm --filter @tanstack/db exec vitest run tests/query/includes-oracle.property.test.ts --maxWorkers=2 --coverage.enabled=false
pnpm --filter @tanstack/db test
pnpm exec eslint packages/db/tests/query/includes-oracle.property.test.ts
pnpm exec tsc --noEmit -p packages/db/tsconfig.json
Focused oracle tests: 40 passed. Package suite: 2,620 passed and 5 skipped.
Files changed#
packages/db/tests/query/includes-oracle.property.test.ts— adds the state-aware relationship scenario builder, generated depth/level matrix, exact expected-failure boundaries, and the newly found moved-subtree trace.
Refs #1658
Summary by CodeRabbit#
- Bug Fixes
- Improved handling of nested relationships when records are reparented, reorganized, or reassigned.
- Preserved existing child relationships during full-row updates.
- Improved consistency for relationship changes across different nesting levels and branches.
- Added safeguards for reparented subtrees, key changes, and complex relationship transitions.
- Improved validation for conflicting relationship keys and other invalid transitions.
- 1
🧹 Nitpick comments (2)
packages/db/tests/query/includes-oracle.property.test.ts (2)
1272-1281: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winGenerate the empty-noise case.
noiseusesminLength: 1, so the scenario with no scalar updates around the transition is never generated. That case is the simplest and most valuable shrink target. SetminLength: 0.Based on the retrieved learning "Test corner cases including: empty arrays/sets, single-element collections, undefined vs null values, resolved promises, async race conditions, and limit/offset edge cases".
♻️ Proposed change
- { minLength: 1, maxLength: 10 }, + { minLength: 0, maxLength: 10 },🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/db/tests/query/includes-oracle.property.test.ts` around lines 1272 - 1281, Update the noise array arbitrary in the property test to use minLength: 0 instead of minLength: 1, while preserving its existing maxLength and record generation so empty-noise transition cases are generated and shrinkable.Source: Learnings
1857-1897: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winMake seeds unique per combination and document the failure heuristic.
Two problems in this loop:
seed: 1721 + depth + targetLevelcollides across combinations.reparentandrekeyshare the same seed for the same(depth, targetLevel), and different pairs with equal sums collide too (depth 2 / level 2 and depth 3 / level 1 both give 1725). WithnumRuns: 4, the generated corpus repeats instead of widening coverage. Derive the seed from all three inputs.expectsFailure = transition === 'rekey' && targetLevel + 2 <= depthencodes a known defect without stating why. Add a short comment that a rekey disconnects descendants two or more levels below the changed row, so a reader knows what to delete when the defect is fixed.
♻️ Proposed change
for (let targetLevel = 1; targetLevel <= depth; targetLevel++) { + // A rekey changes the parent key of the target row only. Descendants + // two or more levels below keep the stale `parentGroup`, which the + // incremental path currently fails to detach. const expectsFailure = transition === `rekey` && targetLevel + 2 <= depth fcTest.prop( @@ { numRuns: 4, - seed: 1721 + depth + targetLevel, + seed: + 1721 + + depth * 100 + + targetLevel * 10 + + (transition === `rekey` ? 1 : 0), },🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/db/tests/query/includes-oracle.property.test.ts` around lines 1857 - 1897, Update the property-test loop around expectsFailure so the seed incorporates transition, depth, and targetLevel, producing distinct seeds for every combination rather than relying only on numeric inputs. Add a brief comment beside the expectsFailure heuristic explaining that rekey disconnects descendants two or more levels below the changed row, and retain the existing failure behavior until that defect is fixed.🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. Nitpick comments: In `@packages/db/tests/query/includes-oracle.property.test.ts`: - Around line 1272-1281: Update the noise array arbitrary in the property test to use minLength: 0 instead of minLength: 1, while preserving its existing maxLength and record generation so empty-noise transition cases are generated and shrinkable. - Around line 1857-1897: Update the property-test loop around expectsFailure so the seed incorporates transition, depth, and targetLevel, producing distinct seeds for every combination rather than relying only on numeric inputs. Add a brief comment beside the expectsFailure heuristic explaining that rekey disconnects descendants two or more levels below the changed row, and retain the existing failure behavior until that defect is fixed.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID:
6077b4b5-a714-4fbd-b510-cab141cfa9ff📥 Commits
Reviewing files that changed from the base of the PR and between dc53f0ecbc38e173af68d829ff2de97531494722 and 8cb28cb787fe0ec062af3ef0bea091795802d044.
📒 Files selected for processing (1)
packages/db/tests/query/includes-oracle.property.test.ts
More templates
@tanstack/angular-db
npm i https://pkg.pr.new/@tanstack/angular-db@1722@tanstack/browser-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/browser-db-sqlite-persistence@1722@tanstack/capacitor-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/capacitor-db-sqlite-persistence@1722@tanstack/cloudflare-durable-objects-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/cloudflare-durable-objects-db-sqlite-persistence@1722@tanstack/db
npm i https://pkg.pr.new/@tanstack/db@1722@tanstack/db-ivm
npm i https://pkg.pr.new/@tanstack/db-ivm@1722@tanstack/db-sqlite-persistence-core
npm i https://pkg.pr.new/@tanstack/db-sqlite-persistence-core@1722@tanstack/electric-db-collection
npm i https://pkg.pr.new/@tanstack/electric-db-collection@1722@tanstack/electron-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/electron-db-sqlite-persistence@1722@tanstack/expo-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/expo-db-sqlite-persistence@1722@tanstack/node-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/node-db-sqlite-persistence@1722@tanstack/offline-transactions
npm i https://pkg.pr.new/@tanstack/offline-transactions@1722@tanstack/powersync-db-collection
npm i https://pkg.pr.new/@tanstack/powersync-db-collection@1722@tanstack/query-db-collection
npm i https://pkg.pr.new/@tanstack/query-db-collection@1722@tanstack/react-db
npm i https://pkg.pr.new/@tanstack/react-db@1722@tanstack/react-native-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/react-native-db-sqlite-persistence@1722@tanstack/rxdb-db-collection
npm i https://pkg.pr.new/@tanstack/rxdb-db-collection@1722@tanstack/solid-db
npm i https://pkg.pr.new/@tanstack/solid-db@1722@tanstack/svelte-db
npm i https://pkg.pr.new/@tanstack/svelte-db@1722@tanstack/tauri-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/tauri-db-sqlite-persistence@1722@tanstack/trailbase-db-collection
npm i https://pkg.pr.new/@tanstack/trailbase-db-collection@1722@tanstack/vue-db
npm i https://pkg.pr.new/@tanstack/vue-db@1722commit:
fa63e88Size Change: 0 B
Total Size: 132 kB
compressed-size-action::db-package-sizeℹ️ View Unchanged
Filename Size packages/db/dist/esm/collection/change-events.js1.44 kB packages/db/dist/esm/collection/changes.js1.51 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.86 kB packages/db/dist/esm/collection/indexes.js1.99 kB packages/db/dist/esm/collection/lifecycle.js1.7 kB packages/db/dist/esm/collection/mutations.js2.47 kB packages/db/dist/esm/collection/state.js5.51 kB packages/db/dist/esm/collection/subscription.js3.77 kB packages/db/dist/esm/collection/sync.js3.05 kB packages/db/dist/esm/collection/transaction-metadata.js144 B packages/db/dist/esm/deferred.js207 B packages/db/dist/esm/errors.js5.16 kB packages/db/dist/esm/event-emitter.js748 B packages/db/dist/esm/index.js3.26 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.js2.35 kB packages/db/dist/esm/live-query-window-controller.js3.04 kB packages/db/dist/esm/local-only.js916 B packages/db/dist/esm/local-storage.js2.12 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/index.js5.84 kB packages/db/dist/esm/query/builder/ref-proxy.js1.24 kB packages/db/dist/esm/query/compiler/evaluators.js1.89 kB packages/db/dist/esm/query/compiler/expressions.js430 B packages/db/dist/esm/query/compiler/group-by.js3.56 kB packages/db/dist/esm/query/compiler/index.js6.67 kB packages/db/dist/esm/query/compiler/joins.js2.5 kB packages/db/dist/esm/query/compiler/lazy-targets.js923 B packages/db/dist/esm/query/compiler/order-by.js1.74 kB packages/db/dist/esm/query/compiler/select.js1.53 kB packages/db/dist/esm/query/effect.js4.77 kB packages/db/dist/esm/query/expression-helpers.js1.43 kB packages/db/dist/esm/query/ir.js1.25 kB packages/db/dist/esm/query/live-query-collection.js360 B packages/db/dist/esm/query/live/collection-config-builder.js9.32 kB packages/db/dist/esm/query/live/collection-registry.js264 B packages/db/dist/esm/query/live/collection-subscriber.js1.95 kB packages/db/dist/esm/query/live/internal.js145 B packages/db/dist/esm/query/live/utils.js1.81 kB packages/db/dist/esm/query/optimizer.js2.92 kB packages/db/dist/esm/query/predicate-utils.js2.97 kB packages/db/dist/esm/query/query-once.js359 B packages/db/dist/esm/query/subset-dedupe.js960 B packages/db/dist/esm/scheduler.js1.3 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.04 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.15 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: 3.79 kB
compressed-size-action::react-db-package-sizeℹ️ View Unchanged
Filename Size packages/react-db/dist/esm/index.js249 B packages/react-db/dist/esm/useLiveInfiniteQuery.js1.29 kB packages/react-db/dist/esm/useLiveQuery.js920 B packages/react-db/dist/esm/useLiveQueryEffect.js355 B packages/react-db/dist/esm/useLiveSuspenseQuery.js567 B packages/react-db/dist/esm/usePacedMutations.js401 B Actionable comments posted: 1
🧹 Nitpick comments (1)
packages/db/tests/query/includes-oracle.property.test.ts (1)
1304-1314: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueAdd an explicit return type.
scalarNoiseArbitraryhas no return type annotation. Add: fc.Arbitrary<VisibleScalarNoise>.As per coding guidelines, “Always provide the most precise return type annotation.”
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/db/tests/query/includes-oracle.property.test.ts` around lines 1304 - 1314, Update the scalarNoiseArbitrary helper’s declaration to explicitly return fc.Arbitrary<VisibleScalarNoise>, while preserving its existing parameters and generated record behavior.Source: Coding guidelines
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. Inline comments: In `@packages/db/tests/query/includes-oracle.property.test.ts`: - Around line 1897-1911: Update the rejects-overlapping-visible-relationship-keys fixture in fcTest to use disjoint idBase values while retaining colliding groupBase values, so it specifically exercises relationship-group overlap. Add a separate case where only rekeyGroup collides with an existing group, ensuring ID keys remain disjoint. --- Nitpick comments: In `@packages/db/tests/query/includes-oracle.property.test.ts`: - Around line 1304-1314: Update the scalarNoiseArbitrary helper’s declaration to explicitly return fc.Arbitrary<VisibleScalarNoise>, while preserving its existing parameters and generated record behavior.🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID:
8b01d34a-d5b2-4289-a867-45d7bc077cdb📥 Commits
Reviewing files that changed from the base of the PR and between 77539d223f8ad33c922c9f6c964930d466b11b35 and 789718f1c40135c272c0c59dfb62e07016a8eeb0.
📒 Files selected for processing (1)
packages/db/tests/query/includes-oracle.property.test.ts
@@ -1674,0 +1891,21 @@1891+ ],1892+ rekeyGroup: 2_100,1893+ noise: [],1894+})1895+1896+describe(`includes recompute oracle`, () => {1897+ fcTest(`rejects overlapping visible relationship keys`, () => {1898+ expect(() =>1899+ createVisibleRelationshipScenario({1900+ depth: 4,1901+ transition: `rekey`,1902+ targetLevel: 1,1903+ sourceBranch: 0,1904+ branches: [1905+ { idBase: 100, groupBase: 600 },1906+ { idBase: 102, groupBase: 602 },1907+ ],1908+ rekeyGroup: 603,1909+ noise: [],1910+ }),1911+ ).toThrow(/overlap/)🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Isolate relationship-group overlap from ID overlap.
This fixture overlaps IDs before it checks groups. The
||inassertDisjointRelationshipKeysthen short-circuits, so this test passes if group collision validation is removed. Use disjoint ID bases with colliding group bases. Add a separate case where onlyrekeyGroupcollides with an existing group.Proposed fixture adjustment
- { idBase: 102, groupBase: 602 }, + { idBase: 1_100, groupBase: 602 }, - rekeyGroup: 603, + rekeyGroup: 2_100,🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/db/tests/query/includes-oracle.property.test.ts` around lines 1897 - 1911, Update the rejects-overlapping-visible-relationship-keys fixture in fcTest to use disjoint idBase values while retaining colliding groupBase values, so it specifically exercises relationship-group overlap. Add a separate case where only rekeyGroup collides with an existing group, ensuring ID keys remain disjoint.✅ Addressed in commit fa63e88
tannerlinsley merged this1b42802
tannerlinsley closed this
Sign in to join this conversation.
No actionable comments were generated in the recent review. 🎉
ℹ️ Recent review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID:
b50fb558-e19f-4c88-844a-60c0fb6de563📥 Commits
Reviewing files that changed from the base of the PR and between 789718f1c40135c272c0c59dfb62e07016a8eeb0 and fa63e888dce4ff0bc01b922e4622a8283d641d38.
📒 Files selected for processing (1)
packages/db/tests/query/includes-oracle.property.test.ts🚧 Files skipped from review as they are similar to previous changes (1)
📝 Walkthrough
Walkthrough#
The includes-oracle property tests now model configurable branches and relationship transitions at arbitrary depths. Full-row normalization preserves existing child relationships. Deterministic and property-based cases cover reparenting, rekeying, scalar updates, and expected deep-transition failures.
Changes#
Nested relationship tests
packages/db/tests/query/includes-oracle.property.test.tspackages/db/tests/query/includes-oracle.property.test.tspackages/db/tests/query/includes-oracle.property.test.tsEstimated code review effort: 4 (Complex) | ~45 minutes
Mergeability Score: ⚪ Minimal · up to
fa63eThis test-only change does not alter runtime behavior, and no actionable merge-blocking risk remains after normal checks and review.
Possibly related PRs
🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
✨ Finishing Touches 💡 1
🛠️ Fix failing CI checks 💡
📝 Generate docstrings
🧪 Generate unit tests (beta)
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