Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
docs(ok): fix two stale replay-outbox rationales in provider-pool (PRD-8314) (#3950)
Andrew Mikofalvy747829e30c04
diff --git a/packages/app/src/editor/provider-pool.ts b/packages/app/src/editor/provider-pool.tsindex de33d13f3..58342e5c1 100644--- a/packages/app/src/editor/provider-pool.ts+++ b/packages/app/src/editor/provider-pool.ts@@ -55,9 +55,17 @@ interface BufferedReplayUpdate {readonly delta: Uint8Array;readonly fullState: Uint8Array | null;/**- * The branch this buffer was captured under — the outbox key's first- * component. Captured rather than re-read at use time because the discard- * paths run AFTER a branch switch has already moved the observed branch.+ * The branch this buffer was captured under — one component of the outbox+ * key, alongside the project namespace and the docName. Deliberately not+ * stated as an ordinal: `outboxDbName` composes those into a name whose+ * project segment is absent for a null namespace, so the branch's position+ * there moves by host.+ *+ * Captured rather than re-read at use time because a discard CAN run after+ * a branch switch has already moved the observed branch — and+ * `discardBufferedUpdate` keys its detached consume off this field for that+ * reason. See its docblock for which discards those are, and for what the+ * captured branch does and does not protect.*/readonly branch: string;/**@@ -2464,12 +2472,17 @@ export class ProviderPool {//// The consume is also the CROSS-TAB claim: tabs resolving the SAME// namespace share one `(namespace, branch, docName)` record, so losing- // the claim means another such tab has already CLAIMED this edit and- // owns whatever happens to it (consume-first, so that tab may still- // bail) — either way this one must stand down rather than apply on top.- // A window of a DIFFERENT project never contends for it. That covers- // both orders — the other tab consuming before we read (we never see a- // record) and after (we see one but cannot claim it).+ // the claim usually means another such tab has already CLAIMED this+ // edit and owns whatever happens to it (consume-first, so that tab may+ // still bail). It can also mean a stale detached consume took the key+ // and nobody owns the edit — `discardBufferedUpdate` documents that+ // race. Stand down regardless: this caller cannot distinguish them, and+ // applying against a real winner splices this tab's stale pre-recycle+ // bytes back over the content just recovered — a silent revert, not a+ // duplicate. A window of a+ // DIFFERENT project never contends for it. That covers both orders —+ // the other tab consuming before we read (we never see a record) and+ // after (we see one but cannot claim it).//// Only attempt it when a durable record actually backs this replay. An// unconditional consume would, on a RAM-only buffer, throw its way into@@ -3382,16 +3395,43 @@ export class ProviderPool {}/**- * Drop one doc's pending replay buffer on an INTENTIONAL discard (explicit- * close, LRU eviction, cross-branch invalidation) — RAM copy and durable- * mirror together.+ * Drop one doc's pending replay buffer on an INTENTIONAL discard — RAM copy+ * and durable mirror together. Two families of trigger, and the split is+ * what the race note below turns on: those that follow a BRANCH MOVE (the+ * cross-branch invalidation, and the replay path's own provenance fence when+ * a buffer turns out to belong to another branch), and those on the branch+ * still current (everything reaching here through `close()` — an explicit+ * close, LRU eviction, the rename flow's close-and-clear).** Dropping only the RAM copy would leave the outbox record behind as an* immortal orphan: a later open of the same doc reads it back and replays an* arbitrarily old edit, which is exactly the surprise `close()` and the- * cross-branch invalidation were each written to prevent. Fire-and-forget —- * both call sites are synchronous and the record is idempotent to consume —- * but a failure is reported, since it leaves a resurrectable edit behind.+ * cross-branch invalidation were each written to prevent. The consume is+ * detached (`void`) for every caller — none needs the result — and it always+ * keys on `buffered.branch`, the branch captured WITH the buffer, never the+ * branch now current. So a discard triggered by a branch move cannot reach a+ * post-switch record: that record lives under a different key.+ *+ * The still-current-branch family has no such disjointness, and+ * `consumeReplayOutboxEntry` claims the KEY rather than the record — so if+ * the same doc is recaptured before a pending consume lands, that consume+ * takes the NEW record, and the replay behind it then finds its claim gone+ * and stands down, having ALREADY dropped its RAM copy. No tab owns the+ * edit at that point, so it is lost, and reported as+ * `claimed-by-another-tab`, which misnames both the cause and the outcome.+ * Accepted on likelihood: the consume is three IDB hops even nominally (the+ * `databases()` probe, the open, the claim transaction), and+ * `withOutboxTimeout` only REJECTS at its deadline — it cannot abort the+ * transaction — so a stalled one lands arbitrarily later. What keeps the+ * race remote is the other leg. A record only ever appears under that key+ * from `handleServerInstanceMismatch`, and every still-current-branch+ * discard runs through `close()`, which destroys the POOL entry first (not+ * the outbox record) — so the doc has to be REOPENED and hit a SECOND+ * mismatch inside that window.+ * Closing it properly means identifying the record (stamp a token at write,+ * delete only on match) rather than trusting the key.+ *+ * A failure is still reported, since it leaves a resurrectable edit behind.** Deliberately NOT called from `dispose()`: that is a pool-lifecycle end* (HMR remount, collab-URL swap, test teardown), not a user discard, and thediff --git a/packages/app/src/editor/replay-outbox.ts b/packages/app/src/editor/replay-outbox.tsindex 95d55509f..bf605e715 100644--- a/packages/app/src/editor/replay-outbox.ts+++ b/packages/app/src/editor/replay-outbox.ts@@ -50,8 +50,8 @@* null namespace reproduces the old name exactly. The stranded set is* every LIVE pre-scoping record, not just one caught mid-recycle. Every* consume path runs INSIDE a live session: a reopen's replay, or an- * intentional discard through `discardBufferedUpdate` (explicit close, LRU- * eviction, cross-branch invalidation). The RAM buffer's `durable` flag+ * intentional discard through `discardBufferedUpdate` (see its docblock for+ * the full trigger set). The RAM buffer's `durable` flag* gates every one of those EXCEPT the reopen that finds no RAM buffer at* all — the tab-died case this outbox exists for, which reads the record* directly and claims it unconditionally. Ordinary app termination — quit,@@ -337,12 +337,20 @@ export async function readReplayOutboxEntry(** That boolean is the cross-tab exactly-once claim. Tabs resolving the SAME* namespace share one `(namespace, branch, docName)` record, so a `false`- * return means another such tab already consumed it and owns the replay —+ * return USUALLY means another such tab consumed it and owns the replay —* re-applying on top would not be idempotent (see `replayBufferedContent`'s- * surface attribution). The count and the delete run in ONE `readwrite`- * transaction and IndexedDB serializes overlapping readwrite transactions- * across connections, so the pair is an atomic compare-and-claim, not a- * check-then-act.+ * surface attribution). Not always: this claims the KEY, not the record, so a+ * stale detached consume from an earlier discard can also take it, in which+ * case no tab owns the edit. `discardBufferedUpdate`'s docblock has that race+ * and why it is accepted. Standing down is right either way — this caller+ * cannot tell the cases apart, and applying against a real winner does not+ * duplicate the edit, it REVERTS it: once the winner's content is on the+ * server the surface attribution inverts, so the splice puts this tab's stale+ * pre-recycle bytes back over the recovery.+ *+ * The count and the delete run in ONE `readwrite` transaction and IndexedDB+ * serializes overlapping readwrite transactions across connections, so the+ * pair is an atomic compare-and-claim, not a check-then-act.** A window of a DIFFERENT project must never lose this claim: its buffered* edit belongs to a different document that merely shares a path and a branch