You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
fix(db): preserve observer row sharing and freshness - #2346
Status and health updates replace the observer's row containers even when no rows change. Consumers that compare those containers by reference can repeat row work after each metadata update.
Capture each row revision once and share its data array and lazy state Map across metadata snapshots. Metadata changes still produce a fresh full snapshot with current status and health. Value writes replace the row containers, and retained snapshots keep their captured rows. Membership and ordering changes remain visible through layoutRevision. Actions that change no public fact retain the full snapshot identity.
The cache trusts Collection's row and layout clocks. Equal-content writes can create fresh virtual wrappers without changing those clocks, so snapshots keep their existing capture. This PR also fixes three freshness hazards at that boundary:
Discarding deferred delivery keeps committed row revisions monotonic. Restoring a discarded layout clock also advances row invalidation, so a detached observer cannot retain an obsolete capture when clock numbers repeat.
Replacing a nested plain record with a class or null-prototype record publishes an update, even when its enumerable fields match. This follows the maintainer's approved prototype policy. Draft reconstruction keeps its separate class/plain equivalence.
Replacing an array hole with a defined value publishes the update. Previously, a hole-skipping comparison could change Collection reads without advancing its clock, leaving observers stale. A hole still compares equal to undefined.
Supported inputs are Collections and pooled views from this DB instance. Reject absent or non-finite revision clocks before client binding, row reads, or sync activation. Pooled views use their ordinary change stream for layout updates, so the separate layout channel stays optional. Remove the unsupported clockless compatibility branch and check clocks before enumerating unchanged rows. Apply client hydration captures once through the publication queue. The cache keeps references to the live capture and last materialized visible capture, which can differ between publication and a read.
Review also found factorial Set comparison and a quadratic common-case regression in its first fix. First compare corresponding members, which establishes equality in linear work for paired equal inputs. Otherwise, build candidates and find a one-to-one assignment, preferring free candidates before reassignment. The utility oracle checks large equal inputs, multiplicity deficits, and a case that requires reassignment. Generic deepEquals retains its established keyed-class/plain/null/cross-realm record policy. Only Collection row equality gains the approved prototype distinction.
This preserves @benjavicente's original commit from #2328 and adds the oracle, freshness, and size improvements. The source PR disables maintainer edits, so this PR contains the follow-up changes. Production changes affect the shared observer, Collection invalidation, and equality utility in @tanstack/db. Framework adapter sources stay unchanged. The Angular adapter's separate row-state projection belongs to #2327. The latest combined tree with that PR remains unverified.
The size comparison uses current main 1443dc92e, identical production defines, and identical compression:
Measurement
Delta
Observer module, minified
−408 bytes
Collection changes, minified
−7 bytes
Equality utility, minified
+186 bytes
Net production, minified
−229 bytes
DB export bundle, gzip
−97 bytes
DB export bundle, brotli
+50 bytes
All eight app scenarios shrink by 49–83 gzip bytes. Brotli changes range from −161 to +55 bytes. The DB export and group-by scenario grow under brotli compression. A deterministic unchanged granular-attachment probe reduces row enumerations from two to one. The remaining enumeration is Collection subscription bootstrap. A real hydration handoff applies the observer cache once instead of twice. The prototype check adds no traversal and uses prototypes the comparison already reads.
🔬 Oracle Coverage
The primary snapshot owner is packages/db/tests/live-query-observer-snapshot-oracle.property.test.ts. Its sharing, capture-path, and record-shape properties check independent row/rank and shape/number models.
Law: Metadata changes preserve row containers, writes and layout changes remain visible, retained snapshots keep their rows, and no-op actions preserve snapshot identity. Collection invalidation stays monotonic across discarded delivery. Record prototypes publish under the 2026-11-03 maintainer decision. The observer and Collection contracts supply the other laws.
Reach: Sharing runs 24 examples plus 40 generated histories per campaign, with 17 states. Capture paths run 16 examples plus 40 generated histories, with 27 states. Record shape runs 16 examples plus 40 generated histories, with 12 states. Every shape history exercises direct Collection and projected-query receivers. Both fixed and random campaigns meet all declared minima. No run budget decreases.
RED: The merge-base observer fails metadata sharing. Head e02e09c70 fails equal-refresh attachment sharing. Unchanged 71bb4c659 fails eight intended assertions in the extended five-owner gate. These include discarded value/layout captures and prototype replacements through both receivers. Clock seed 2346, path 0, retains version 2 instead of 3. Shape seed 234602, path 0:1:0:2:2, retains plain shape after a class replacement.
GREEN: The final audit gate passes 508 tests in eleven focused suites. These cover utilities, snapshots, observer delivery, pooled views, draft tracking, production errors, and generated docs. Angular ordinary and conformance tests also pass: 109 tests plus one todo, with no type errors. TypeScript, ESLint, changed-file lint, minified API, error erasure, and mangle checks pass. The earlier merged-main gate passed 1,868 tests in 16 suites. The gate includes the Effect metadata/callback owner. Focused TypeScript, ESLint, changed-file oracle lint, mangle validation, minified build, and public API checks pass. The merged gate repeats all three hostile mutants and guarded replays. Guarded direct replay passes each requested clock and shape witness.
Mutant: Restoring row-clock rollback fails value freshness. Omitting only the discarded-layout fence fails ordering after the value case passes. Restoring class/plain equality fails both shape receivers. Earlier wrapper-comparison, no-op identity, layout, cardinality, and health mutants remain documented.
Set work and pooled views: The small utility lane runs 100 fixed and 100 random histories with thirteen states, each reached 200 times. Independent counts and capacity judge each comparison domain. The large paired lane adds ten histories per campaign and eight states, each reached 20 times. Its widths span 1,024–3,072. Scalar-read and scoped native-operation ceilings are linear for this paired family. The original matcher and precheck-only mutant exceed the cubic scalar-read ceiling. Candidate reuse fails equality. The pooled owner compares wholesale, granular and detached readers in all 160 generated histories. Before the fix, subscription throws on the absent channel. A silent fallback fails the granular mirror assertion. The final source gate passes 190 tests, the built-dist gate passes 357, Preact conformance passes 136, and pooled GC passes 21.
CI counter overhead: Both Set campaigns exceeded the five-second timeout in the database shard. The scalar-read counter now allocates diagnostics only when its unchanged ceiling fails. All 87 utility tests and the combined 100-test utility/pooled gate pass locally. Every Set reach still records 200 histories. The original matcher still fails at read 2,049 against ceiling 2,048. Inputs, run counts, work limits, and timeouts remain unchanged.
Third review calibration: Before fix, paired Set work exceeds 4,096 reads and generic equal-record comparison fails. Ten invalid-clock witnesses also fail before the constructor fix. Removing the paired fast path, restoring strict generic prototypes, using greedy-only matching, and restoring factorial search each fail intended direct-replay observations. Paired Set linearity does not extend to arbitrary unordered inputs or nested-value traversal.
Four-agent audit: The sparse-array grammar now distinguishes holes from defined neighbors through both equality APIs, records, and singleton Sets. Seven utility states each reach 200 histories. Fourteen real publication states each reach 20 histories per campaign, including each direct/projected, mode, and attachment path. Unchanged production fails both owners before the indexed fix. Restoring hole skipping fails both guarded replays. Scoped native Map/Set counters reject a cached factorial matcher that scalar reads accepted. The draft model now preserves signed zero and rejects lost writes through root, nested, and Float64 paths. The observer checker comment now states value/order agreement without an unsupported row-reference identity promise. The fixes address all four audit findings. Existing budgets remain unchanged.
Limits: These comparisons observe direct core actions and queued query reads. They establish no framework scheduling, provider timing, arbitrary concurrency, cleanup/reset sharing, caller-mutation isolation, or infinite-page-array identity promise. The shape grammar covers sync replacements with keyed record prototypes through records, arrays, Map values, and Set members. Exotic built-in subclasses, descriptors, cycles, and optimistic assignment policy remain outside that grammar.
From packages/db, run the snapshot owner with:
pnpm exec vitest run tests/live-query-observer-snapshot-oracle.property.test.ts --coverage.enabled=false --maxWorkers=2
The versioned evidence record contains the laws, reach counts, replay inputs, mutants, measurements, and the external and four-agent review audits. The first review records five fixed findings, three refutations, and two accepted design choices. The second records seven fixed findings, one refutation, and one accepted design choice. The supplement records both CodeRabbit reviews, the Set work fix, and CI corrections. The third external review records five fixes, one accepted readonly-sharing design, and the explicitly separate draft bug #2349. Editing a nested sibling can temporarily strip an untouched class/null-prototype leaf. The maintainer identified that bug and kept its fix outside this PR. No known counterexample remains in the metadata-sharing and discarded-publication scope. The separate cleanup/restart issue #2334 remains open. Its shared-model trace also fails after readiness in both modes on 162eebf39. The coverage map records its owner and next witness. This PR does not establish general observer lifecycle correctness. The coverage map records the owners and their limits.
✅ Checklist
I have tested this code locally with pnpm test.
The full workspace suite did not run locally. The focused gates above pass. CI for 22da3b06e completed with 25 successful checks and one skipped CodeRabbit check. CI for 779466c62 found the missing generated error page and an Angular test mock without a layout clock. The fixes address both mechanical omissions. CI for 5911d5e00 found five source-type errors in the new sparse-array driver and a separate ordered-loader oracle failure. The driver correction passes both sparse campaigns, the full DB TypeScript source check, ESLint, and changed-file lint. The original sparse-array mutant still fails all receiving paths. The loader failure reproduces identically on exact main 1443dc92e; its seed, shrink path, full trace, owner, and next experiment are preserved in the coverage map. Its repair location remains unresolved. The independently replayed trace is tracked in #2296. The maintainer approved merging this scoped observer fix with that investigation tracked separately. No test, budget, or seed was changed to bypass it. CI for corrected head acdfb6f14 completed successfully: 25 successful checks and one skipped CodeRabbit check. Production remains at ba336f4b2. CodeRabbit is paused and its latest covered production commit remains 162eebf39; it has not reviewed the later semantic changes. This green random campaign does not close the recorded loader counterexample, the separate #2334 cleanup/restart defect, or the unverified combined #2327 integration. General readiness remains unproven. The separate Electric sampling reach issue remains tracked in #2347.
Live-query snapshots preserve row data and state containers when only status or health metadata changes. Row value and ordering changes appear in new snapshots, while earlier snapshots retain their point-in-time data.
Discarded publication deferrals now invalidate detached observer snapshots when needed, ensuring subsequent reads reflect current collection data.
Record comparisons now distinguish plain, class, and null-prototype records, while same-shape equal writes remain equal.
Documentation
Clarified snapshot-sharing behavior, record-shape equality, and the limits of observer coverage.
Cache row materialization separately from full observer snapshots. Keep lazy
state Maps and data arrays stable across status/health changes while preserving
value-only updates, layout changes, and retained point-in-time reads.
Law: metadata-only snapshots retain their row containers (maintainer decision
2026-11-01; LiveQuerySnapshot contract).
Reach: 52 fixed and 52 random histories cross both observer modes, attached and
detached reads, empty/nonempty rows, read order, readiness, health, and writes.
RED: unchanged production fails metadata reference equality; seed 1101,
path 0:0:0:0, in live-query-observer.row-container-sharing.
GREEN: 100 observer tests, 89 existing Angular tests (one TODO), focused types,
ESLint, oracle lint, mangle validation, package build, and docs snippets pass on
Node 24.8.0. The patch Changeset releases this independently of Angular fixes.
Mutant: same-cardinality reuse fails a same-key value write; seed 1101,
path 0:0:1:2. The final implementation is restored.
Limits: the new lane uses synchronous direct Collections with 0..3 string keys;
existing ordered/findOne/hydration suites cover neighboring laws. No new host
scheduling or external-provider guarantee.
Exercise subscribe/unsubscribe transitions, require genuine health-only
reach, and register the sharing lane with guarded replay. Reuse captured
entries for layout comparison and materialize the shared Map directly.
Law: same-row-revision metadata changes share containers; values and retained
snapshots remain correct. Authority: LiveQuerySnapshot and maintainer decision.
Reach: 24 examples plus 40 generated histories per fixed/random campaign;
nonempty attach/detach/reattach reached in both modes.
RED: original implementation fails metadata identity, seed 1101 path 0:0:0:0.
GREEN: 112 observer tests, guarded replay, TypeScript, lint, mangle, and minified
API checks pass.
Mutant: unconditional entry replacement fails guarded replay at seed 1101,
path 2:3:1:6:4:3; cardinality-only reuse and false health reach also fail.
Limits: synchronous direct Collection path; no new host/provider or reset
sharing claim. Full evidence is in the observer row-container review record.
Production observer is 75 minified bytes smaller than the original merge-base;
DB package delta is -34 gzip and -111 brotli bytes.
It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.
No actionable comments were generated in the recent review.
Walkthrough
Live-query observers retain captured data and state containers across metadata-only updates and refresh captures from collection revisions. Discarded layout publications advance the state revision. Deep equality distinguishes record prototypes and uses bounded matching for object-valued Sets.
Discarded layout epochs advance the state revision without rewinding it. The observer refreshes captures when either collection revision changes and reuses data and state containers when row contents remain unchanged. Tests cover metadata updates, capture paths, publication deferrals, and retained snapshots.
Record shape and Set equality packages/db/src/utils.ts, packages/db/tests/utils-oracle.property.test.ts, packages/db/tests/utils.test.ts, packages/db/tests/live-query-observer-snapshot-oracle.property.test.ts, docs/contributing/glossary.md, docs/contributing/oracle-coverage.md, docs/contributing/oracle-reviews/2026-11-01-observer-row-containers.md
Deep equality distinguishes plain, class, and null-prototype records, with a draft-comparison exception when prototypes differ and at least one is plain. Object-valued Sets use candidate matching with augmenting paths. Tests cover record prototypes, nested payloads, and bounded Set comparisons.
sequenceDiagram
participant Collection
participant LiveQueryObserver
participant Snapshot
Collection->>LiveQueryObserver: state and layout revisions
LiveQueryObserver->>Collection: read entries when either revision changes
LiveQueryObserver->>Snapshot: provide captured data and state containers
No concrete issue requiring a fix before merge was identified. Normal validation and pending CI should still complete.
Pre-merge checks: 4 · 1
Failed checks: 1 warning
Check name
Status
Explanation
Resolution
Docstring Coverage
Docstring coverage is 11.11% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documenta…
Write docstrings for the functions missing them to satisfy the coverage threshold.
Passed checks: 4 passed
Check name
Status
Explanation
Title check
The title clearly identifies the main change: preserving observer row sharing and freshness in the database package.
Linked Issues check
Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check
Check skipped because no linked issues were found for this pull request.
Description check
The description follows the repository template and provides substantive content. It has a detailed Changes section covering the row-container sharing, the freshness fixes, the Set matching change, an…
Full details: Description check
Explanation
The description follows the repository template and provides substantive content. It has a detailed Changes section covering the row-container sharing, the freshness fixes, the Set matching change, and the size measurements. It also has an Oracle Coverage section naming the owner file, laws, reach counts, RED/GREEN results, mutants, and limits. The checklist and release impact sections are present. The release impact box is checked for a changeset, which matches the raw summary. The description is very long and dense, and the Oracle Coverage section is hard to parse in places. It also contains unresolved items: a known loader counterexample tracked in #2296, a separate draft bug #2349, cleanup/restart issue #2334, and an unverified combined #2327 integration. These are disclosed, not hidden. The checklist item for local tests is unchecked, but the author states focused gates pass and the full workspace suite did not run. The template asks for RED/GREEN evidence for bug fixes, which the description provides. The description is mostly complete and satisfies the template's required information.
Full details: Docstring Coverage
Explanation
Docstring coverage is 11.11% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 9 functions across 12 files. (3 skipped: 3 unsupported.)
Resolution
Write docstrings for the functions missing them to satisfy the coverage threshold.
Finishing Touches
Generate docstrings
Commit to this branch
Create a new PR
Generate unit tests (beta)
Commit to this branch
Create a new PR
Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
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.
Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 3 remain after this review.
Comparing 65c6d2b5d (this PR) against 1443dc92e (base). Write times are per-write medians over 100 iterations (20 warmup writes). Cold hydrate is one timed first load of each query.
Overall median write time vs base: 0.96× · cold hydrate time: 1.03× (geometric mean of per-case ratios; lower is faster).
Writes: 0 regression(s), 3 improvement(s) (threshold: ±20% and >0.05ms).
Cold hydrate: 3 regression(s), 1 improvement(s) (threshold: ±50% and >5ms).
Per-case flags are noisy on shared runners. Read the geometric means first.
Writes
Query
Δ median write time (geomean)
Best case
Worst case
Flags
list: newest 50 open
+0.2%
-40.2%
+49.5%
—
list + author
+2.1%
-10.7%
+49.2%
—
list + comment count
-3.6%
-39.2%
+14.2%
1 🟢
list + 3 recent comments
-7.1%
-56.3%
+33.8%
1 🟢
issue detail + comments
-14.1%
-60.4%
+10.7%
1 🟢
Cold hydrate
Query
Δ cold hydrate time (geomean)
Best case
Worst case
Flags
list: newest 50 open
-2.3%
-46.8%
+40.5%
—
list + author
+8.9%
-20.9%
+256.1%
1 🔴
list + comment count
-10.3%
-63.7%
+41.5%
1 🟢
list + 3 recent comments
+7.5%
-44.8%
+115.1%
1 🔴
issue detail + comments
+20.2%
-5.3%
+193.2%
1 🔴
Each row aggregates the 14.4 scale/index/write-mode configurations of that query; per-configuration tables below.
Runner: node v24.8.0, linux 7.0.0-1017-azure, AMD EPYC 9V45 96-Core Processor. Timings on shared CI runners are noisy; treat small deltas as indicative only.
Law: LiveQuerySnapshot and the 2026-11-01 maintainer decision require
unchanged rows to retain containers, while values and ordered keys stay fresh.
No-op actions also preserve full-snapshot identity.
Reach: 17 sharing and 16 real-query capture states have fixed witnesses;
fixed/random campaigns use 24+40 and 16+40 histories respectively.
All measured counts are in the versioned evidence record.
RED: Parent e02e09c fails metadata keeps data after refresh, subscribe,
report. Seed 1101, path 2:4:5:6:8:5. New receiving paths passed before edits.
GREEN: 118 observer tests and 41 replay tests pass, plus TypeScript, ESLint,
oracle lint, minified build/API and mangle checks. Observer -99 minified
bytes; DB -40 gzip and -97 brotli bytes against the original merge-base.
Mutant: Original wrapper comparison fails guarded replay. Ignoring layout
clocks fails ordered rows at seed 2346, path 0:2:0:1:1:0. Snapshot cloning
survives the old lane and fails the added no-op assertion.
Limits: Core direct/query snapshot cuts, bounded rows/actions, no arbitrary
concurrency, framework/provider timing, cleanup sharing, caller-mutation
isolation or infinite-page-array identity promise. No budget decreased.
Keep committed row revisions monotonic and fence discarded layout clocks.
Publish nested record prototype changes under the maintainer decision.
Remove unsupported clockless compatibility and redundant observer capture work.
Law: committed reads remain fresh, retained snapshots keep capture-time rows,
and metadata-only updates share containers. Record prototype changes publish
under the maintainer decision of 2026-11-03. Draft equality remains separate.
Reach: capture histories reach all 27 declared states, with nested discarded
value/layout writes, both modes, ordered/findOne, hydration and reattachment.
Record-shape histories reach all 12 states through source and query receivers.
RED: unchanged 71bb4c6 fails 8 intended assertions in the extended five-owner
gate; clock seed2346/path0 and shape seed234602/path0:1:0:2:2 fail publicly.
GREEN: 1423 tests in15 suites pass; latest utility reach rerun83/83 passes.
Focused types, lint, minified API/build, mangle validation and guarded replay pass.
Mutant: original row rollback, layout-fence omission and old record equality
all fail the intended comparisons. All production files restored afterward.
Limits: bounded core sync histories and queued-query reads; no host/provider
timing, exotic built-in subclasses, cleanup sharing or infinite page identity.
Full evidence and nine-finding dispositions are in
docs/contributing/oracle-reviews/2026-11-01-observer-row-containers.md.
Shipped minified bytes are net -339 versus the original merge base.
KyleAMathews
changed the title
perf(db): preserve observer row containers with stronger oracle coverage
fix(db): preserve observer row sharing and freshness
Nov 3, 2026
Resolve the record-equality conflict while retaining upstream signed-zero,
comparison-mode and Effect publication policies.
Law: retain fresh committed captures, metadata sharing and record prototypes,
under the established contracts and maintainer decision of 2026-11-03.
Reach: all sharing, capture and shape states reached on the merged tree.
RED: row rollback, layout-fence omission and old prototype equality each fail
the merged oracle at the intended public comparison.
GREEN: 1868 tests in16 suites, focused types, lint, minified API and mangle pass.
Mutant: all three repeated against merged main and rejected; guarded replay
passes after restoring production.
Limits: bounded core/query cuts; combined Angular tree and full local workspace
suite unverified. Exact pushed-head CI is separate.
Production remains net -339 minified bytes against current main1443dc92e.
Full evidence: docs/contributing/oracle-reviews/2026-11-01-observer-row-containers.md.
Law: unordered structural Sets require a bijection; AGENTS.md excludes
combinatorial comparison work. Supported pooled observers publish the same
rows, status and deltas as their live-query Collection. Prototype publication
follows the maintainer decision of 2026-11-03.
Reach: utils.42 runs 100 fixed + 100 random histories; all 12 declared states
reach 200. Pooled wholesale/granular/detached receivers each reach 160.
RED: extended utility owner on f66d684 fails scalar read 2049 > 2048
(seed 20260911, path 0:0:0). Extended pooled owner fails subscription before
repair (seed 44502001, path 0:0:0:0:0:0).
GREEN: final focused source gate 190 tests; prior broader gate 786 tests;
built-dist 357 tests; real Preact conformance 136 tests; pooled GC 21 tests.
Types, ESLint, changed-file oracle lint, minified API and mangle checks pass.
Mutant: factorial matcher and precheck-only matcher fail work assertions;
candidate reuse fails bag equality. Silent pooled attach fallback fails the
granular mirror (seed 44502001, path 1:0:0:0:3:2:2). All mutants restored.
Limits: bounded scalar Set work, corresponding parent cycles, core pooled
histories and real Preact receiving witness. No global nested-value cost or
latest combined Angular tree claim. Production is -285 minified bytes against
main1443dc92e. See the versioned row-container review report for the audits.
Restore generic record equality while retaining prototype-sensitive Collection
publication. Reuse Set cycle bookkeeping, prefer free candidates, and enforce
observer revision clocks before resource acquisition. Simplify capture callers.
Law: generic and row equality retain their distinct approved domains; paired
equal Sets need bounded work; invalid Collection clocks reject before mutation.
Reach: small Set 13 states x 200 histories; paired Set 8 states x 20 histories.
RED: extended pre-fix utility gate fails paired work (4097 > 4096) and generic
record equality; ten constructor invariant witnesses fail before that repair.
GREEN: seven focused suites pass 381 tests; types, ESLint, changed-file lint,
minified API, production error erasure, and mangle checks pass.
Mutant: no paired fast path, strict generic prototypes, greedy-only assignment,
and original factorial matching all fail intended observations in direct replay.
Limits: arbitrary Set reorder/nested cost and graph topology are unbounded;
#2349 draft prototype loss is explicitly outside this PR. #2334 stays open.
Production: -262 minified bytes vs exact origin/main 1443dc9.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
KyleAMathews
changed the title
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
🎯 Changes
Status and health updates replace the observer's row containers even when no rows change. Consumers that compare those containers by reference can repeat row work after each metadata update.
Capture each row revision once and share its data array and lazy state Map across metadata snapshots. Metadata changes still produce a fresh full snapshot with current status and health. Value writes replace the row containers, and retained snapshots keep their captured rows. Membership and ordering changes remain visible through
layoutRevision. Actions that change no public fact retain the full snapshot identity.The cache trusts Collection's row and layout clocks. Equal-content writes can create fresh virtual wrappers without changing those clocks, so snapshots keep their existing capture. This PR also fixes three freshness hazards at that boundary:
Supported inputs are Collections and pooled views from this DB instance. Reject absent or non-finite revision clocks before client binding, row reads, or sync activation. Pooled views use their ordinary change stream for layout updates, so the separate layout channel stays optional. Remove the unsupported clockless compatibility branch and check clocks before enumerating unchanged rows. Apply client hydration captures once through the publication queue. The cache keeps references to the live capture and last materialized visible capture, which can differ between publication and a read.
Review also found factorial Set comparison and a quadratic common-case regression in its first fix. First compare corresponding members, which establishes equality in linear work for paired equal inputs. Otherwise, build candidates and find a one-to-one assignment, preferring free candidates before reassignment. The utility oracle checks large equal inputs, multiplicity deficits, and a case that requires reassignment. Generic
deepEqualsretains its established keyed-class/plain/null/cross-realm record policy. Only Collection row equality gains the approved prototype distinction.This preserves @benjavicente's original commit from #2328 and adds the oracle, freshness, and size improvements. The source PR disables maintainer edits, so this PR contains the follow-up changes. Production changes affect the shared observer, Collection invalidation, and equality utility in
@tanstack/db. Framework adapter sources stay unchanged. The Angular adapter's separate row-state projection belongs to #2327. The latest combined tree with that PR remains unverified.The size comparison uses current main
1443dc92e, identical production defines, and identical compression:All eight app scenarios shrink by 49–83 gzip bytes. Brotli changes range from −161 to +55 bytes. The DB export and group-by scenario grow under brotli compression. A deterministic unchanged granular-attachment probe reduces row enumerations from two to one. The remaining enumeration is Collection subscription bootstrap. A real hydration handoff applies the observer cache once instead of twice. The prototype check adds no traversal and uses prototypes the comparison already reads.
🔬 Oracle Coverage
The primary snapshot owner is
packages/db/tests/live-query-observer-snapshot-oracle.property.test.ts. Its sharing, capture-path, and record-shape properties check independent row/rank and shape/number models.e02e09c70fails equal-refresh attachment sharing. Unchanged71bb4c659fails eight intended assertions in the extended five-owner gate. These include discarded value/layout captures and prototype replacements through both receivers. Clock seed2346, path0, retains version 2 instead of 3. Shape seed234602, path0:1:0:2:2, retains plain shape after a class replacement.From
packages/db, run the snapshot owner with:pnpm exec vitest run tests/live-query-observer-snapshot-oracle.property.test.ts --coverage.enabled=false --maxWorkers=2The versioned evidence record contains the laws, reach counts, replay inputs, mutants, measurements, and the external and four-agent review audits. The first review records five fixed findings, three refutations, and two accepted design choices. The second records seven fixed findings, one refutation, and one accepted design choice. The supplement records both CodeRabbit reviews, the Set work fix, and CI corrections. The third external review records five fixes, one accepted readonly-sharing design, and the explicitly separate draft bug #2349. Editing a nested sibling can temporarily strip an untouched class/null-prototype leaf. The maintainer identified that bug and kept its fix outside this PR. No known counterexample remains in the metadata-sharing and discarded-publication scope. The separate cleanup/restart issue #2334 remains open. Its shared-model trace also fails after readiness in both modes on
162eebf39. The coverage map records its owner and next witness. This PR does not establish general observer lifecycle correctness. The coverage map records the owners and their limits.✅ Checklist
pnpm test.The full workspace suite did not run locally. The focused gates above pass. CI for
22da3b06ecompleted with 25 successful checks and one skipped CodeRabbit check. CI for779466c62found the missing generated error page and an Angular test mock without a layout clock. The fixes address both mechanical omissions. CI for5911d5e00found five source-type errors in the new sparse-array driver and a separate ordered-loader oracle failure. The driver correction passes both sparse campaigns, the full DB TypeScript source check, ESLint, and changed-file lint. The original sparse-array mutant still fails all receiving paths. The loader failure reproduces identically on exact main1443dc92e; its seed, shrink path, full trace, owner, and next experiment are preserved in the coverage map. Its repair location remains unresolved. The independently replayed trace is tracked in #2296. The maintainer approved merging this scoped observer fix with that investigation tracked separately. No test, budget, or seed was changed to bypass it. CI for corrected headacdfb6f14completed successfully: 25 successful checks and one skipped CodeRabbit check. Production remains atba336f4b2. CodeRabbit is paused and its latest covered production commit remains162eebf39; it has not reviewed the later semantic changes. This green random campaign does not close the recorded loader counterexample, the separate #2334 cleanup/restart defect, or the unverified combined #2327 integration. General readiness remains unproven. The separate Electric sampling reach issue remains tracked in #2347.🚀 Release Impact
observer-row-container-sharing.md, preserved from perf(db): preserve row references across metadata snapshots #2328).Summary by CodeRabbit