PR #2313 external review evaluation

Reviewed head: ef6316a910c24e60cbcfe8e3e613b0bddc821958. Source: the maintainer's ten-item external review, in source order below. The repeated source numbers receive stable IDs P1–P3, O1–O6, and D1. This follow-up changes tests and documentation. Production remains byte-for-byte identical to the reviewed head. No product-law change is required.

Laws, experiments, and inferences

Law and authority	Existing enforcement	Decisive experiment	Inference and repair
A successful direct on-demand restart publishes restored rows, deletes omitted rows, suppresses equal public updates, and keeps partial or failed replacements private. Authority: subscription.ts's public change-message boundary, the lifecycle grammar, and ARCHITECTURE's cleanup/restart and replay sections.	The publication model independently accumulates source and subscriber rows and compares exact per-command batches. Its old reach labels did not establish restored equality independently of fixture numbering.	On reviewed production, prepend one request/resolve/release of the other demand to the old grammar. The old fixed acquisition campaign passes, but a labeled equal case retains {id:'a',value:1} and actually restores {id:'a',value:2}. Restoring the original equality-suppression defect makes all 12 expanded restart campaigns fail at the shared publication comparison.	The production fix remains correct. Explicit input row values, observed retained/delivered values, actual settlements, owner lifetimes, and acquisition counts now establish the premises.
An eager restart's next public batch reconciles retained subscriber rows with installed state. An empty ready batch reconciles an empty replacement. Authority: ARCHITECTURE, “Cleanup, restart, and detached waiters.”	The existing restart fixture marks an empty eager run ready immediately. It does not promise whole-run atomicity for a source that streams several commits.	The new ordinary boundary test starts with a/b/c, cleans up, restarts, commits a while loading, then commits b/c and marks ready. It observes delete b/c in the first batch and insert b/c in the second.	P1's observation is real and is accepted design under the existing contract. Waiting until ready would change that contract and delay streamed eager updates. This PR does not make that change.
Cleanup ends a dependent graph. Public cleanup rejects active live queries, dependent cleanup ends them first, and internal cleanup crashes them. Source-only restart does not revive a crashed graph. Authority: public cleanup() documentation, glossary, ARCHITECTURE laws 14/16 and its explicit direct-restart limitation.	The cleanup oracle already exercises admission and dependent invalidation. The publication owner explicitly excludes compiled includes.	Six real compiled-query witnesses cross eager/on-demand with public, dependent, and internal cleanup. Public cleanup rejects. Internal cleanup keeps b/d in a crashed query after source-only restart. Cleaning up and preloading the query again publishes only b.	P2 conflates retained terminal rows with a live replacement. A supported query restart removes d. No delegated-publication production repair is justified by this trace.
Ordinary subscription admission is closed during active cleanup. Initial listener registration owns no demand, replay, or public rows. Authority: glossary's admission rule and AGENTS.md's distinction between valid operations and contradictory collaborators.	The cleanup oracle has 18 admission cells. Actual Collection.on only registers a callback. The only synchronous cleanup-start callback during construction has no user-visible work to retire.	An executable registration probe calls the real public subscription boundary while adapter cleanup is held. It throws before either listener-registration method runs. Ordinary registration and repeated unsubscribe succeed. The unchanged 18-cell admission owner passes.	P3's arbitrary throwing-registration conditional can leak resources, but the proposed throwing/reentrant collaborator does not occur at this constructor boundary. Do not add defensive recovery for substituted internal methods.

A whole-run eager atomicity law would be a product proposal. Its rival is the accepted first-public-batch rule above. Atomicity would keep older rows visible until readiness, while the existing rule exposes each committed eager batch. The review supplies no authority to replace the accepted rule. No decision is needed to complete this enforcement repair.

Oracle repair and measured reach

The governing row model and exact comparisons are unchanged. Settle commands can now supply explicit row data, independently of the fixture's attempt ID. Generated values range from -100,000 to 100,000. Zero to three preliminary retired acquisitions perturb numbering before the tested restart.

The single scenario grammar supplies both history construction and declared reach. A separate observer classifies executed owner operations, adapter acquisition counts, actual settlement, and callback-applied versus written rows. Rejected acquisitions establish no rows. Their successful retry supplies the row-relation witness, after the actual rejection is observed. A canceled or absent acquisition claims neither restored equality nor a rejection.

Acquisition delivery: 24 cases, each measured 12 times per campaign.
Independent source delivery: 27 cases, each measured 12 times per campaign.
Direct, filtered, ordered-snapshot, and snapshot-before-source-events receivers: three row relations each, measured 12 times per campaign and receiving path.
Fixed and random campaigns share the generator, budget, recorder and comparison. Together these campaigns execute 1,512 restart histories at multiplier 1.

The old 72-label count included observationally redundant canceled acquisition relationships and no-op outcomes. Removing those duplicate categories does not remove a valid publication distinction. Every generated-input budget remains 12. The original broad fixed/random budgets remain 60 each. O5's recommended 24-input enumeration would itself run 24 × 72 = 1,728 histories, the old total. It would improve finite input enumeration, but would not reduce that work. The revised grammar spends its budget on distinct structural cases and a much larger payload domain. This is no elapsed-performance claim.

The receiving driver uses the existing independent Map diff. A real predicate excludes b. An ordered snapshot selects the whole bounded two-row replacement. A held source publication installs rows before requestSnapshot() reads them, then releases its source events before acquisition settlement. The held-cut comparison checks unchanged subscriber rows and no callbacks. The settled-cut comparison checks exact batches, values, omitted-row deletion and readiness. No test discards installed source events to invent an unsupported public path.

Lossless item ledger

ID / original location	Claim	Evidence and technical verdict	PR action	Durable value
P1 / production 1, subscription.ts:1921	Eager a/b/c restart deletes b/c after an early a-only batch, before readiness. Older behavior, traced but not run.	Observation confirmed by same-path execution. Its claimed defect contradicts the explicit eager first-batch contract.	accepted-design	Ordinary eager boundary witness and the law distinction above.
P2 / production 2, subscription.ts:787	Delegated restart restores b from b/d but leaves d visible because there is no privateRows buffer. Older behavior, traced but not run.	Refuted as an active-query restart failure by real compiled paths. Internal cleanup deliberately leaves terminal rows in a crashed graph. Public cleanup rejects it, or dependent cleanup ends it. Supported query restart yields b.	refuted	Six compiled receiving witnesses and explicit terminal-versus-live scope.
P3 / production 3, subscription.ts:300	A later registration throw leaks earlier listeners. Reentrant unsubscribe spreads an unassigned array.	The conditional about substituted throwing methods is true, but current registrations cannot expose or unsubscribe the partly constructed subscription. Active-cleanup admission fails before registration. No reachable production counterexample was found at the stated seam.	refuted as a current product defect	Keep construction assumptions explicit. Existing admission oracle and the executable probe establish the supported boundary. Future fallible collaborators would require a new construction contract and witness.
O1 / oracle 3, :2606	Reach records grammar labels, and inactive equal/changed acquisition histories count indistinguishable states.	Confirmed in part. Other model comparisons and restart/no-op assertions were real, so the old test was not vacuous. Its row-relation reach claim was unsupported. The fixture perturbation stays green with false equal labels.	fixed-now	Observed reach classifier and 51 distinct structural cases replace the 72-label claim.
O2 / oracle 4, :637	Equality depends on hard-coded fixture acquisition IDs, so reordered or added attempts silently change the premise.	Confirmed by the green perturbed old campaign and retained 1/restored 2 trace.	fixed-now	Explicit generated values and preliminary retired-acquisition dimension.
O3 / oracle 5, :2585	Default-only campaign omits eager, filtered, ordered, and snapshot delivery, which hides P1.	The path omissions are real. P1 is a different accepted law, and snapshots have their own delivery branch, so the blanket implication of a defect is too broad.	fixed-now for the coverage gap	Four shared-model receiving paths, eager and compiled ordinary witnesses, and precise coverage limits.
O4 / oracle 6, :2568	Issue seed 2310 appears in the test name.	Confirmed naming-policy violation in the interpolated runtime name.	fixed-now	Names now say fixed seed or random/replayed seed. Seed data and replay stay unchanged.
O5 / oracle 7, :2565	The 1,728 histories repeat 24 inputs. Enumerating those inputs once gives equal coverage faster.	Finite payload sampling was wasteful. The work conclusion is incorrect: each input drives 72 histories, so enumerating 24 still costs 1,728. Fixed/random parity is also required.	fixed-now for the useful grammar improvement	Broader payloads, numbering churn and removal of redundant structural cases. No run budget is lowered.
O6 / oracle 8, :587	Reach product, repeated outcome arrays and duplicated input type can drift.	Confirmed source-maintenance issue.	fixed-now	One scenario grammar, one outcomes constant and an inferred arbitrary input type. Observed reach remains separate.
D1 / docs 6, :5/:184/:223	Current-head and uncommitted/no-PR claims are stale, raw evidence needs inaccessible scratch, and hiring prose is misplaced.	Confirmed misleading presentation. Later entries already recorded publication, but the opening still claimed current status.	fixed-now	Historical checkpoints are explicit, this versioned record preserves decisive evidence, and hiring recommendations remain conversation output.

No raw item is dropped or merged. No sibling production violation was confirmed. The initial receiver experiments had setup failures (an invalid IR function name and an unnormalized expected batch), which are not production RED results. The final valid receiving paths pass unchanged production. A discarded-event experiment was removed because it did not establish a supported public history.

Verification and calibration

The nine-suite command below passes 661 tests. TypeScript, formatting, ESLint, pnpm lint:changed, and git diff --check pass.

shell

pnpm --filter @tanstack/db exec vitest run \
  tests/collection-subscription-lifecycle-publication-oracle.property.test.ts \
  tests/collection-subscription-lifecycle-history-oracle.property.test.ts \
  tests/collection-subscription-lifecycle-oracle.test.ts \
  tests/collection-subscription-replay-oracle.property.test.ts \
  tests/collection-subscription-lifecycle.test.ts \
  tests/collection-subscription-lifecycle-publication.test.ts \
  tests/collection-subscription-reentrancy-oracle.test.ts \
  tests/collection-cleanup-restart-oracle.test.ts \
  tests/collection-restart-publication-boundaries.test.ts \
  --maxWorkers=2 --coverage.enabled=false

Calibration commands use the same owner with -t 'matches restarted row publication'. The original-defect mutant removes only this.truncateReplayState?.privateRows || from stale-row reconciliation. It fails all 12 campaigns at the publication comparison, rather than timeout or setup. Restoring the exact reviewed production file restores GREEN. The old-fixture perturbation uses git show ef6316a91:<owner-path>, prepends request/resolve/release of the other demand to each restart history, and runs -t 'matches restarted row publication acquisition \(2310\)'. It passes while an actual write of 2 replaces retained 1 in a labeled equal history. These results directly calibrate O1/O2 without treating a temporary mutant's GREEN result as a repaired branch result.

Direct replay remains:

shell

TANSTACK_DB_ORACLE_SEED=2310 TANSTACK_DB_ORACLE_PATH=0:0:0 \
TANSTACK_DB_ORACLE_PROPERTY=subscription-lifecycle.restart-publication \
pnpm --filter @tanstack/db exec node --import tsx tests/oracle-replay.ts \
  tests/collection-subscription-lifecycle-publication-oracle.property.test.ts \
  -t 'matches restarted row publication' --maxWorkers=2 --coverage.enabled=false

The guarded replay passes six campaigns and reports six successful witnesses with property, seed, and path.

The evidence block is: Law, direct replacement membership and existing neighboring lifecycle rules above. Reach, 51 structural cases plus 12 receiver relations, each 12 times in each normal campaign. RED, the old oracle accepts a false equality premise, and the original-defect mutant fails all expanded campaigns. GREEN, the same comparisons on restored reviewed production. Mutant, original equality suppression. Limits, finite integer rows, a controlled sync boundary, bounded ordered snapshot selection, and the receiving paths above. These checks establish no new external-provider, framework, arbitrary ordered-window, or delegated-includes promise.

Oracle rubric audit and loss audit

ORC-001/002: existing authority and independent Map diff are unchanged. ORC-003: executable prose describes the law, grammar, receiving seams and cuts. ORC-004: the exact issue replay remains. Equality, omission, delivery and live outcomes distinguish suppression, keep-all and acquisition-only designs. Numbering churn is a marginal case. Inactive acquisitions cannot claim restored rows. Transactions remain well formed. ORC-005/006: actual receiving writes, held/settled public observations and the original-defect assertion failures establish path and checker sensitivity. ORC-007: fixed/random parity and direct seed/path replay remain. ORC-008: removing duplicate inactive labels changes no model state or legal next action. ORC-009: row relation and owner reach labels are observations, not new production states. ORC-010: failures and secondary cleanup errors remain ordered, with the primary as cause. ORC-011 does not require another formulation: no shared semantic fault in the Map diff was identified. ORC-012: this record links the reviewed head to every raw item and its evidence. ORC-013: absent/equal/changed and omitted rows discriminate nearby wrong membership rules. ORC-014: claims remain at the controlled core boundary. Compiled cleanup is exercised in its real core receiving path, with no external provider claim. ORC-015: each path asserts measured reach with minimum 12. ORC-016: ordinary boundary examples stay outside the oracle file, and all oracle histories use the shared judgment.

10 raw items = 7 fixed-now + 1 accepted-design + 2 refuted. No item is confirmed-open, deferred, stale, duplicate, or awaiting a product decision. Item accounting, local validation, and bounded enforcement repairs are complete. CI status and PR readiness require separate final-head evidence.

The reviewed production SHA-256 remains f2ee13496359611fa5fe22066df96d80dec88a77fa18693af2fcfeff4ce29bc4. The repaired publication-owner SHA-256 is ff91a783388ceee1d3189f0b105cdfdae555e2ac5b15f5a50937ecd5aaa51112. These identify the exact source and oracle used for the final local checks.