Issue #2071: refused insert in a persisted Collection

Source: TanStack/db issue #2071, including its closure comment, reread 2026-10-07. The report names @tanstack/db 0.12.1 and @tanstack/db-sqlite-persistence-core 0.4.5. The release probe used 3825ac3cb1db1fb145cafcc202dc05424b74dc56, whose package versions match. This review began from origin/main at ea51b67b06f2ef86d3a891a577dcc74e558454d7, then merged origin/main at 2c98b4992. Its executable tests and contract corrections are commits 14fc66d99c852dff9e0046c3ed32e92c4da6f51f and 3e33fec8d073811e0c4c08e10cfd5db14268e596. At those commits, the checkout had no production behavior change. The later PR #2078 review records subsequent oracle and production changes.

The reporter's bridge test and callback/write sequence are unavailable. The direct probes below reproduce the stated public setup, but they cannot establish that the private bridge reaches the same scheduling path. The issue is closed; the author's comment says it is probably a real problem, and does not retract the technical claim.

Reviewer assessment

The report identifies the wrapper, real SQLite adapter, rejected outbound insert, transaction state, durable-versus-live divergence, and same-key source delete. Those are useful signals and a plausible high-impact failure if reproduced. It gives no minimal bridge fixture or exact sync callback and mutation-handler order, so its root-cause theory and proposed repairs cannot be verified. The scope is focused and the signal-to-noise ratio is good; the proposed overlay/reconciliation alternatives are outcomes to test, not approved mechanisms. Hire recommendation: insufficient evidence to recommend hiring as a reviewer from this single report.

Lossless finding ledger

The issue supplied no file/line or severity labels. “High if true” below reflects the live/durable divergence, not a confirmed defect. Dispositions apply to the reviewed commit.

ID	Original claim or proposal	Technical verdict and evidence	Disposition / PR action	Durable value and destination
R01	A failed local insert remains visible until restart.	Unverified on the private bridge; no ghost at refusal settlement or fresh-adapter reopen in the controlled current and release probes. High if true.	confirmed-open; obtain the bridge schedule before a production fix.	Refusal and reopen law in the persisted wrapper and real SQLite owners; bridge gap in the coverage map.
R02	In sync-present persistence, outbound insert rejects and the transaction fails, while applyCommittedTx never stores the failed row and reopen omits it.	The focused real SQLite receiver observes exactly this in its refusal history. An independently accepted source insert is a separate durable write.	accepted-design; retain the durability and rollback assertions.	Fresh Collection, adapter, and driver witness in persisted-real-adapter-lifecycle.test.ts.
R03	Version 0.12 folds the failed optimistic insert into syncedData.	No such promotion in four controlled histories on either commit. A hostile promotion mutant fails the new exposed-base comparison at refusal settlement. The private path is unknown. High if true.	confirmed-open; do not alter core state from an unverified causal theory.	Core optimistic owner and persisted wrapper owner; exact bridge history needed.
R04	Same-key post-failure sync writes are silently ignored in memory although a delete reaches applyCommittedTx.	No omission in controlled insert/delete orders or the real SQLite continuation. Omitting source-delete forwarding fails two controlled row comparisons and one real receiver. The private path remains unknown. High if true.	confirmed-open; request the exact source transaction sequence.	Persisted wrapper source-order law and real adapter receiving witness.
R05	Without the wrapper, core rolls the failed optimistic row back.	Confirmed by the core optimistic-history model and its failure path; no conflicting controlled result.	accepted-design; no production change.	optimistic-history-oracle.ts and outcome/publication drivers.
R06	Supported APIs could not repair the bridge; completed overlays survived persistence in 0.9, while the current bridge acknowledges success through sync.	The 0.9 behavior is the reporter's historical account, not retested; the current settlement-drop contract does not retain completed overlays. Whether supported APIs leave a current bridge gap cannot be judged without its sequence.	confirmed-open for the current API/path question; retain the retired 0.9 detail as context, not a restoration request.	Current core contract and the bridge evidence gap in oracle-coverage.md.
R07	A failed mutation must leave live and stored rows consistent; keep it overlay-only until acknowledgement or reconcile through later source writes.	The outcome law is accepted. Both controlled and real adapter witnesses satisfy it. The two implementation suggestions are unproved alternatives.	accepted-design for the outcome; no speculative state machine or retry.	Refusal matrix, durable adapter comparison, and reopen receiver.
R08	The reporter closed the issue with an apology while saying it was probably real.	Closure and comment confirmed. They add no execution evidence and do not technically retract R01/R03/R04.	stale as an issue-status signal; no closure-based refutation.	This record preserves the unresolved claims and exact evidence request.

Totals: 8 raw items = 4 confirmed-open + 3 accepted-design + 1 stale. There are no fixed-now behavioral bugs, refutations, duplicates, deferrals, or design-decision items. Documentation was corrected separately under the attribution law below.

Laws, histories, paths, and enforcement

L1. A rejected local mutation cannot become authoritative

Authority: the optimistic-state and accepted-sync-transaction contracts in docs/contributing/glossary.md and optimistic-history-oracle.ts. A local insert overlays the applied source rows while its handler runs. On rejection its optimistic state drops. Only an accepted source transaction can change the applied base or durable adapter. This is an outcome law; it does not choose the reporter's proposed repair mechanism. It covers R01–R03, R05, and R07.

The old portfolio exercised core rollback but did not cross a rejecting onInsert through the sync-present persisted wrapper with source work on the same key, nor receive that controlled event with a fresh real SQLite adapter. The new independent single-row source reference state starts empty. Four legal histories cross first source insert/delete with acceptance before/after refusal, then apply the opposite turn. A source insert before refusal is an accepted independent source row, so it may survive; a refused local intent alone may not. The production path is collection.insert → wrapped onInsert → SyncConfig → real Collection and recording adapter. The driver compares the live row, exposed collection.base, durable adapter row, and origin while optimistic, after source acceptance, at isPersisted rejection, and after each source receipt. A held receipt must remain pending until the mutation settles.

The real receiving path uses createSQLiteCorePersistenceAdapter with a SQLite CLI driver. It observes the absent durable row, accepted same-key source delete, live/base absence after rejection, later insert/delete/replacement, and reopening the same SQLite file with a new Collection, adapter, and driver. It does not restart an OS process. Its two histories cover reopen before later writes and reopen after the continuation. They receive the controlled delete-before-refusal premise, but do not receive every insert/timing cell.

Encoding and enforcement are complete for these bounded histories and checkpoints: the independent source reference state predicts the row, and the production comparison reaches each named cut. They are not complete for the reporter's bridge, other mutation kinds, on-demand sync, other SQLite hosts, or a process restart. A reachable bridge-specific counterexample would keep the product class open; the current evidence does not establish its absence.

L2. Accepted source writes apply in order and receipts wait for visibility

Authority: the accepted-sync-transaction glossary entry and the persisted wrapper contract. An accepted source transaction becomes durable and then visible in order. A same-key delete can remove an absent source key and still must reach core. If publication waits behind a persisting mutation, its commit receipt waits too. This covers R04 and the source portion of R02/R07.

The refusal matrix checks source insert/delete in both orders and at settlement and each receipt. The real receiver confirms that a delete reaches the adapter and core and that subsequent source writes replace the row in live, base, storage, and reopened Collection. The original gap was the absence of a refused-insert wrapper history with a direct same-key source continuation. The model can represent absent keys, later replacement, and independent source writes; the recorder does not collapse them to a final snapshot. The exact private bridge sequencing remains uncovered.

L3. $origin is key-and-timing attribution, not causal authorship

The old public API text said a local source row originated from this client. SyncConfig.write carries no source-client identity. Two temporary RED probes disproved that wording on the reviewed core: an independent peer write accepted on the same key during a successful local mutation was labeled local, and a second queued same-key source transaction was labeled remote even though it too was accepted before settlement. We chose the observed attribution contract, as directed in this review, and corrected API comments, guide, generated reference pages, production comments, glossary, and oracle prose. No production branch was changed.

For one local mutation without truncate, a successful settlement grants local attribution to the first queued same-key source transaction. Every same-key write inside that atomic transaction keeps it; an absent-key delete consumes it without leaving a row. Later queued same-key transactions are remote without another local owner. A rejected mutation grants those queued writes none. A truncate is a distinct legal cut: it can publish a same-key source row while the mutation still persists, leaving that row labeled local after the mutation later fails. Local-only Collections always label rows local. These are attribution rules, not evidence of the writer's identity.

The core HistoryModel independently tracks applied rows, local mutations, and accepted source batches. Its existing driver compares virtual properties, live rows, event replicas, downstream rows, request outcomes, and publication cuts after each step. New fixed witnesses reach one and two queued transactions, two different same-key writes inside the first atomic transaction, an absent-key delete followed by insert, and truncate before failed settlement. The persisted wrapper receives the one/two queued pair. The new truncate witness also prevents the revised public prose from overclaiming that every failed mutation leaves remote origin. This law is encoded and asserted for these histories. At 3e33fec8d, the source-batch grammar wrote rows before deletes, so it could not express delete then reinsert within one batch. The later PR #2078 review added ordered operations and a witness for that history. Overlapping same-key mutations and all truncate/source combinations are not claimed as exhausted; causal authorship would require a new source signal, model, and real-provider receiver.

The prep-PR review exposed a model flaw, not a production defect. The old model deleted a key's attribution after its first write inside a batch. Adding a legal first batch with two different same-key writes made the oracle fail at isPersisted settlement: it expected the final row's $origin to be remote, while production returned local. HistoryModel.drain() now snapshots attributed keys once per atomic batch, then consumes them for later batches. The extra batch-local set is derived from existing state; it preserves a distinction that the next legal same-key write inside the batch can observe. The adjacent two-transaction witness ensures attribution does not persist into the next batch. A temporary production mutant that discarded within-batch attribution failed the new settlement assertion; restored production passed.

Hostile controls and GREEN results

All mutants were temporary and restored before commit. Each failure below reached the intended production path; none was committed.

Control	Wrong design	Result at the relevant checkpoint
M1	Omit clearing pending local changes.	Two refused-insert origin assertions failed.
M2	Drop durable source-delete forwarding to core.	Two controlled row assertions and one real SQLite receiver failed.
M3	Settle a wrapped receipt at durability.	Two held-receipt pending assertions failed.
M4	Keep local attribution after the first same-key source transaction.	The two-transaction origin assertion failed.
M5	Ignore the first same-key local attribution.	The one-transaction origin assertion failed.
M6	Keep attribution after an absent-key source delete.	The delete-then-insert origin assertion failed.
M7	Clear the pending-local snapshot in truncate replacement.	The truncate history failed on rows visible when isPersisted settled.
M8	Keep a failed mutation in the optimistic overlay.	All four refused-insert histories failed at the refusal-settlement live-row comparison.
M9	Promote a failed local insert into applied synced data.	The two histories with no prior source write failed at the refusal-settlement live/base comparison.
M10	Clear local attribution after the first same-key write inside one atomic source transaction.	The new two-write history failed at the isPersisted settlement origin comparison.

A narrower attempt that removed only the direct pendingLocalChanges check survived the truncate witness because the retained truncate snapshot enforced the same rule. That survival does not weaken M7's separate assertion failure and is not counted as a kill. The old model's false RED and M10's production assertion failure are distinct controls. M8 and M9 directly challenge the reported ghost-row class; M2 and M3 challenge the neighboring source and timing laws.

On executable commit 3e33fec8d, the two core optimistic-history suites passed 37/37, with no type errors. The affected persistence suites passed 869, with 2 existing todos and no type errors. Prettier and git diff --check passed. The docs link check still exits 1 on two links in unchanged docs/contributing/oracle-tests.md that point outside the docs tree; it reports no new link from this review. The @tanstack/db build passed earlier in this review, before the final test and documentation edits. The reported release's scratch controlled matrix passed five selected probes, and its fresh-adapter SQLite probe passed three selected tests. The release probes are uncommitted diagnostic files in a separate checkout; only the current-head witnesses are in the executable commits.

Oracle guide audit (ORC-001–014)

Rule	Outcome
ORC-001 authority/limits	L1/L2 use the existing settlement and accepted-source contracts; L3 was corrected to the observed, approved timing contract. The bridge and host limits are explicit.
ORC-002 independent judgment	The persisted expected row comes from a single-row source reference state, not wrapper caches. The core HistoryModel remains structurally separate from Collection state.
ORC-003 literate responsibilities	Opening prose states each law and limit; nearby comments identify the fixed history grammar, model rule, real driver, observations, and settlement/receipt/reopen cuts.
ORC-004 generated grammar	No generator changed. The new fixed matrix reconstructs all four declared timing/write cells; each axis changes a reachable cut or expected row. The core owner's existing generated grammar and exclusions are not revalidated by these fixed cases. The fixed two-write source batch reaches repeated same-key rows; at 3e33fec8d, delete then reinsert within one batch remained unrepresented. PR #2078 later added an ordered-batch witness.
ORC-005 production/observations	collection.insert, wrapped sync, Collection, real adapter, and fresh reopen all run. Live/base/durable rows, origin, receipt state, and publication cuts are asserted.
ORC-006 calibration	M1–M10 classify wrong answers at intended assertions; the redundant-check survivor and old model's false RED are reported separately.
ORC-007 fixed/random parity	Not triggered by these fixed witnesses; no generated property or replay interface was edited. Existing campaigns ran as part of the persistence suite, not as proof of the private bridge.
ORC-008 state minimality	The core model added only a derived batch-local attribution set. A second same-key write in the same batch distinguishes retaining it from consuming attribution per write; a later batch distinguishes it from retaining attribution indefinitely. The persisted reference state has one expected row and source-order turns.
ORC-009 vocabulary mapping	“optimistic state,” “accepted sync transaction,” “applied base,” and “held optimistic row” use the glossary. base/queue model fields are mapped in the core owner opening.
ORC-010 failure fidelity/cleanup	Controlled and real witnesses preserve primary assertion errors, await/reject outstanding work, and report secondary cleanup failures before releasing collections and SQLite files.
ORC-011 second formulation	The single-row source reference state and core event-history model differ from wrapper state; real SQLite supplies a separate durability receiver. A causal-origin formulation cannot be derived without a client-ID signal, so causal authorship is not claimed.
ORC-012 review evidence	This record is tied to exact executable commits 14fc66d99 and 3e33fec8d and names the open contract × history × path × observation cells. No bug-class closure is claimed.
ORC-013 distinguishing boundary	Two same-key writes in one transaction versus two queued transactions distinguish per-batch attribution from per-write consumption or indefinite retention at settlement. Delete-then-insert and truncate-before-failure distinguish other plausible wrong origin rules. M4–M7 and M10 reach their premises.
ORC-014 controlled handoff	The real SQLite receiver supplies the controlled delete-before-refusal premise and same-key continuation. Other controlled cells and the private bridge have no real-provider receiver and remain bounded.

Refutations, stale context, and remaining work

There is no refutation of the reported bridge failure. The negative probes reach the public setup but not the exact private callback schedule. The reporter's 0.9 completed-overlay account was not retested and does not describe the current settlement-drop contract. Issue closure is not a technical answer. The former causal $origin wording was disproved by controlled counterexamples and corrected as documentation and contract prose, not by changing runtime attribution.

No authorized repair is deferred: no reproducible current product defect was found to fix. R01/R03/R04/R06 remain confirmed-open evidence gaps. The persisted wrapper owner in oracle-coverage.md needs the reporter's smallest bridge callback and source-write sequence, including which sync transaction commits before the refused handler settles. If supplied, replay it first against 3e33fec8d and the reported release, extend the primary oracle with nearby legal histories, require a hostile control at the violated checkpoint, and only then change production. At 3e33fec8d, remaining in-scope paths included other mutation kinds, on-demand sync, host-specific SQLite behavior, overlapping same-key mutations for attribution, delete then reinsert within one atomic source transaction, and an actual OS process restart. PR #2078 later added an atomic delete/reinsert witness and bounded same-key overlap histories. The other paths remain unestablished.

Final accounting: 8 = 4 confirmed-open + 3 accepted-design + 1 stale. The bounded oracle and documentation work requested for this restart is complete; the issue's private bridge claim remains unresolved.

Prep-PR review reconciliation

The code reviewer found one test-integrity flaw and no other actionable finding. The claim was accurate, reached a legal history, and identified a narrow model fix, so its technical depth and signal-to-noise were strong. P2 is proportionate because the oracle falsely rejected correct behavior, while no production defect was shown. This single review supports a recommendation for focused oracle review; it does not establish broader reviewer performance. The simplifier made no edits and proposed three useful cleanups, plus preservation of existing distinct witnesses and API text.

ID	Original review item	Evidence and verdict	Disposition and durable result
P01	The model consumes $origin attribution per write, while production retains it through an atomic source transaction; preserve it through the batch and add a witness.	Old model RED at isPersisted settlement for two same-key writes; corrected model GREEN; M10 fails at that cut.	fixed-now in 3e33fec8d; primary oracle model, witness, glossary, and coverage map. Mixed delete/reinsert was outside the grammar at that commit; PR #2078 later added it.
S01	Consolidate duplicated SQLite reopen setup while preserving both checkpoints.	Both branches repeated the same Collection, adapter, and driver construction; the shared tail now reopens after each branch's distinct source history. Both real SQLite histories pass.	fixed-now in 3e33fec8d; real adapter lifecycle test.
S02	Describe scalar expectedSource as independent reference state, rather than an “edit log.”	The model holds one expected row after each source turn, so “edit log” implied a history it does not store.	fixed-now in this record; L1 and ORC-002/008/011 descriptions.
S03	Separate the two #2071 coverage entries from the earlier three-domain list.	The prior layout included those entries under an unrelated count.	fixed-now in 3e33fec8d; acceptance map.
S04	Retain distinct oracle histories, checkpoints, and full descriptions on both generated API reference pages.	The histories compare different publication cuts, and both public pages describe their own API surface. No deletion was proposed or made.	already-fixed; preserve the witnesses and API text.

Prep-PR loss audit: 5 raw items = 4 fixed-now + 1 already-fixed. The final executable diff matches each disposition. P01's per-batch law is encoded and enforced for repeated row writes in the first batch and distinguished from a later batch. At 3e33fec8d, the grammar could not express delete then reinsert within one batch; PR #2078 added that witness. The private bridge is still unavailable, so this record does not claim the reported issue is closed.