Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
docs(ok): correct two replay-outbox comments left inaccurate by #3897 (PRD-8314) (#3939)
Andrew Mikofalvy0397b227498e
diff --git a/packages/app/src/editor/provider-pool-cross-tab-replay.test.ts b/packages/app/src/editor/provider-pool-cross-tab-replay.test.tsindex 03e10f165..c2daef587 100644--- a/packages/app/src/editor/provider-pool-cross-tab-replay.test.ts+++ b/packages/app/src/editor/provider-pool-cross-tab-replay.test.ts@@ -2,10 +2,16 @@* Cross-tab exactly-once for the durable replay outbox.** The outbox record is keyed `(namespace, branch, docName)` with no tab- * component, so every tab of one project (a browser preview and the desktop- * shell both sit on `127.0.0.1:PORT`) sees ONE record. That record is- * therefore the cross-tab claim token: whichever tab consumes it owns the- * replay and the others must stand down.+ * component, so tabs that resolve the SAME namespace see ONE record — several+ * browser tabs on one `127.0.0.1:PORT` (all null-namespace), or several+ * desktop windows of one project. A browser preview and a desktop window are+ * NOT such a pair: the preview resolves a null namespace and addresses the+ * bare name, while any desktop host resolves a scoped one. That single record+ * is the cross-tab claim token: whichever tab consumes it owns the replay and+ * the others must stand down.+ *+ * These tests run the null-namespace case throughout, which is the shape a+ * web host and every pre-scoping record use.** They must stand down because `replayBufferedContent` is not re-entrant. It* decides which CRDT surface holds the un-delivered edit by asking whichdiff --git a/packages/app/src/editor/provider-pool.test.ts b/packages/app/src/editor/provider-pool.test.tsindex b82985b90..0276df412 100644--- a/packages/app/src/editor/provider-pool.test.ts+++ b/packages/app/src/editor/provider-pool.test.ts@@ -1431,17 +1431,17 @@ describe('cross-project storage-key isolation', () => {});test('an empty namespace is scoped, not treated as a web host', () => {- // `''` reaches the pool when an Electron host resolves a workspace with- // no contentDir — a broken config. It must not fall through to the- // app-wide key that correctly-configured windows would then share.+ // `''` is what a window opened WITHOUT a project reports (the preload+ // defaults `projectPath` to `''`). It must not fall through to the+ // app-wide key that project windows would then share.const { stub, store } = makeStubStorage();- const broken = new ProviderPool(3, DUMMY_WS, { storage: stub, storageNamespace: '' });+ const projectless = new ProviderPool(3, DUMMY_WS, { storage: stub, storageNamespace: '' });try {- broken.setObservedBranch('main');+ projectless.setObservedBranch('main');expect(store.has('ok-last-observed-branch')).toBe(false);expect(store.get('ok-last-observed-branch:811c9dc5')).toBe('main');} finally {- broken.dispose();+ projectless.dispose();}});diff --git a/packages/app/src/editor/provider-pool.ts b/packages/app/src/editor/provider-pool.tsindex 2b41a93b8..de33d13f3 100644--- a/packages/app/src/editor/provider-pool.ts+++ b/packages/app/src/editor/provider-pool.ts@@ -2462,13 +2462,14 @@ export class ProviderPool {// At-most-once in the tiny [consumed → server-synced] tail (matching the// RAM buffer, and past the crash window the outbox exists to close).//- // The consume is also the CROSS-TAB claim: tabs of the SAME project- // share one `(namespace, branch, docName)` record, so losing the claim- // means another tab of this project already replayed this edit and this- // one must stand down. 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 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).//// Only attempt it when a durable record actually backs this replay. An// unconditional consume would, on a RAM-only buffer, throw its way intodiff --git a/packages/app/src/editor/replay-outbox.ts b/packages/app/src/editor/replay-outbox.tsindex e990b721e..95d55509f 100644--- a/packages/app/src/editor/replay-outbox.ts+++ b/packages/app/src/editor/replay-outbox.ts@@ -23,7 +23,7 @@* client nulls its cached id and only relearns it from the reconnect* handshake), so the epoch cannot be part of the key.*- * The project component is REQUIRED for every packaged window, and omitted+ * The project component is REQUIRED for every desktop window, and omitted* only for a null namespace, where the origin already isolates — that is* `precedent #59`, applied here through `scopedStorageKey`* (`lib/storage-scope.ts`), not re-derived. What is specific to THIS@@ -49,15 +49,16 @@* content this scoping removes, which is the bug. Electron only, since a* 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 (from the RAM- * buffer when one survived, straight from the outbox when the tab died and- * none did), or an intentional discard through `discardBufferedUpdate`- * (explicit close, LRU eviction, cross-branch invalidation) — that second- * family is the one gated on the RAM buffer's `durable` flag. Ordinary app- * termination — quit, force-quit, `quitAndInstall` — runs none of them. So- * a doc not reopened between its write and the upgrade keeps an- * unreachable record. Stranding is also silent: a null read is- * indistinguishable from "nothing to recover".+ * 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+ * 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,+ * force-quit, `quitAndInstall` — runs none of them. So a doc not reopened+ * between its write and the upgrade keeps an unreachable record. Stranding+ * is also silent: a null read is indistinguishable from "nothing to+ * recover".* 2. Ongoing: the namespace is the project path AS THE USER PICKED IT, not* its realpath (`window-manager.ts` keeps `projectPath` and `canonicalKey`* deliberately distinct, and the renderer is handed the former). So@@ -84,7 +85,7 @@* RAM-only.** The single `(namespace, branch, docName)` record is also the CROSS-TAB- * exactly-once token: tabs of the same project share it, so+ * exactly-once token: tabs resolving the same namespace share it, so* `consumeReplayOutboxEntry` reports whether THIS caller was the one that* removed a live record. Its count+delete run in one `readwrite` transaction,* and IndexedDB serializes overlapping readwrite transactions across@@ -334,18 +335,18 @@ export async function readReplayOutboxEntry(* Consume a doc's buffer by deleting its record, and report whether THIS* caller was the one that removed a live record.*- * That boolean is the cross-tab exactly-once claim. Tabs of the SAME project- * share one `(namespace, branch, docName)` record, so a `false` return means- * another such tab already 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+ * 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 —+ * 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.** 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- * name. That is what the `namespace` component guarantees.+ * name. That is what the project component guarantees.** Idempotent for callers that only want the record gone (consuming an absent* record resolves `false` rather than throwing).