Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

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.ts
index 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 which
diff --git a/packages/app/src/editor/provider-pool.test.ts b/packages/app/src/editor/provider-pool.test.ts
index 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.ts
index 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 into
diff --git a/packages/app/src/editor/replay-outbox.ts b/packages/app/src/editor/replay-outbox.ts
index 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).