@kabmo-labs/kabmo 0.8.0 → 0.9.0

package/src/shared/lib/workspace/session-state/merge.ts

@@ -0,0 +1,100 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Which copy wins when a session's stored blob arrives.
+ *
+ * Split out of `store.ts` for the file-size ceiling, and it is a coherent unit
+ * rather than an arbitrary cut: both halves answer the same question, and the
+ * store is the only caller. The store owns the CACHE (an entry's lifetime, the
+ * persist debounce, eviction); this owns the DECISION (a response describes the
+ * row as it was when the request arrived, so anything written since is newer).
+ */
+
+type SessionState = Record<string, unknown>;
+
+/**
+ * A monotonic counter bumped by every local write, and the counter value each
+ * `(session, key)` was last written at.
+ *
+ * This exists for ONE race, and `dirtySessions` cannot cover it: a load's
+ * response is served from a snapshot taken when the request arrived, while a
+ * write made in the meantime persists on its own schedule. Once that persist
+ * succeeds the dirty flag is cleared — so a response that arrives after it but
+ * was computed before it would be adopted as-is and silently drop the write.
+ * Measured in the browser (a rare e2e failure, `outline.e2e.ts`): a file opened
+ * while the page's first `/state` read was in flight came back with
+ * `layout.openedFiles` gone, so the editor drew "Select a file to open" over a
+ * file the user had just clicked.
+ *
+ * `loadSession` records the counter when it STARTS and merges exactly the keys
+ * written after that point, which is what makes "wrote it while the read was in
+ * flight" survive regardless of when the persist landed.
+ */
+let writeSeq = 0;
+const writeLog = new Map<string, Map<string, number>>();
+
+/** The counter as of now — a read takes this before it issues its request. */
+export function currentWriteSeq(): number {
+  return writeSeq;
+}
+
+/** Record that `key` was written locally just now. */
+export function noteWrite(sessionId: string, key: string): void {
+  writeSeq += 1;
+  let perSession = writeLog.get(sessionId);
+  if (!perSession) {
+    perSession = new Map();
+    writeLog.set(sessionId, perSession);
+  }
+  perSession.set(key, writeSeq);
+}
+
+/** The keys of `sessionId` written after `since` (strictly later). */
+export function keysWrittenAfter(sessionId: string, since: number): Set<string> {
+  const written = new Set<string>();
+  const perSession = writeLog.get(sessionId);
+  if (!perSession) return written;
+  for (const [key, seq] of perSession) {
+    if (seq > since) written.add(key);
+  }
+  return written;
+}
+
+/** Drop a session's write history — evicted, forgotten or adopted away. */
+export function forgetWrites(sessionId: string): void {
+  writeLog.delete(sessionId);
+}
+
+/**
+ * The blob to cache, given the response, the local entry, the keys written
+ * while the read was in flight, and whether the entry is still dirty.
+ *
+ * Only the keys written during the window win over the stored blob. Merging the
+ * WHOLE local cache over the blob (the old behavior) resurrected stale values on
+ * every tab: a second browser opening the session had cached the pre-write blob,
+ * and its stale copy clobbered another tab's fresh writes — queue items written
+ * in one tab never appeared in the other.
+ */
+export function mergeStoredBlob(
+  incoming: SessionState,
+  existing: SessionState,
+  written: Set<string>,
+  dirty: boolean,
+): SessionState {
+  // A dirty entry has a persist that has not landed: the whole local copy is
+  // newer than the response.
+  if (dirty) return { ...incoming, ...existing };
+  if (written.size === 0) return incoming;
+  const merged: SessionState = { ...incoming };
+  for (const key of written) {
+    // A key the local side still holds wins outright; one it no longer holds
+    // was CLEARED during the read (`clearSessionKey`), so the response's copy is
+    // the stale one and must not resurrect it.
+    if (key in existing) merged[key] = existing[key];
+    else delete merged[key];
+  }
+  return merged;
+}

package/src/shared/lib/workspace/session-state/store-load.test.ts

@@ -0,0 +1,206 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The blob-arrival half of the session-state store: what wins when a stored
+ * blob lands, and what a read must not overwrite.
+ *
+ * Split from `store.test.ts` for the per-file ceiling. The contract pinned here
+ * is the one that produced two measured bugs:
+ *
+ *  - A response is served from a snapshot taken when the request arrived, so a
+ *    key written WHILE the read was in flight is newer — even once its own
+ *    persist landed and cleared the dirty flag. Without the write counter, a
+ *    file opened during the page's first `/state` read came back with
+ *    `layout.openedFiles` gone.
+ *  - A key CLEARED in that window must not be resurrected by a response that
+ *    still carries it.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import {
+  clearSessionKey,
+  flushSession,
+  getSessionValue,
+  hydrateSession,
+  loadSession,
+  setSessionKey,
+} from '@/shared/lib/workspace/session-state/store';
+import { counter, follow, installStoreTeardown, use } from '@/shared/lib/workspace/session-state/harness.test-util';
+
+installStoreTeardown();
+
+describe('session-state store: blob arrival (loadSession)', () => {
+  function stubWindow(): void {
+    Reflect.set(globalThis, 'window', {});
+  }
+
+  function stubFetch(response: unknown): void {
+    Reflect.set(globalThis, 'fetch', async () => response);
+  }
+
+  /**
+   * A fetch stub that HOLDS the blob read and lets writes through.
+   *
+   * Gating every call deadlocks the case: the write's own persist is a `POST`
+   * to the same path, and a stub that awaits the gate for both means the flush
+   * can never complete while the read is held.
+   */
+  function gateReads(state: unknown): () => void {
+    const { promise: gate, resolve } = Promise.withResolvers<void>();
+    Reflect.set(globalThis, 'fetch', async (_url: string, init?: { method?: string }) => {
+      if (init?.method === 'POST') return { ok: true, json: async () => ({}) };
+      await gate;
+      return { ok: true, json: async () => ({ state }) };
+    });
+    return resolve;
+  }
+
+  test('a clean session adopts the stored blob and notifies', async () => {
+    const id = use('load-clean');
+    stubWindow();
+    stubFetch({ ok: true, json: async () => ({ state: { a: 1, b: 2 } }) });
+    const probe = counter();
+    follow(id, null, probe.listener);
+
+    await loadSession(id);
+    expect<number | undefined>(getSessionValue(id, 'a')).toBe(1);
+    expect<string | number | boolean | Record<string, unknown> | unknown[] | null | undefined>(getSessionValue(id, 'b')).toBe(2);
+    expect(probe.calls).toBe(1);
+  });
+
+  test('a dirty session keeps its local writes over the blob', async () => {
+    const id = use('load-dirty');
+    stubWindow();
+    setSessionKey(id, 'a', 99);
+    stubFetch({ ok: true, json: async () => ({ state: { a: 1, b: 2 } }) });
+
+    await loadSession(id);
+    expect<string | number | boolean | Record<string, unknown> | unknown[] | null | undefined>(getSessionValue(id, 'a')).toBe(99);
+    expect<string | number | boolean | Record<string, unknown> | unknown[] | null | undefined>(getSessionValue(id, 'b')).toBe(2);
+  });
+
+  test('a non-ok response leaves the cache untouched but still notifies', async () => {
+    const id = use('load-error');
+    stubWindow();
+    stubFetch({ ok: false, json: async () => ({}) });
+    const probe = counter();
+    follow(id, null, probe.listener);
+
+    await loadSession(id);
+    expect(getSessionValue(id, 'a')).toBeUndefined();
+    expect(probe.calls).toBe(1);
+  });
+
+  test('a rejected fetch is swallowed and notifies', async () => {
+    const id = use('load-throw');
+    stubWindow();
+    Reflect.set(globalThis, 'fetch', async () => {
+      throw new Error('offline');
+    });
+    const probe = counter();
+    follow(id, null, probe.listener);
+
+    // The store logs the failure; keep the expected warning out of the run log.
+    const warn = console.warn;
+    console.warn = () => {};
+    try {
+      await loadSession(id);
+    } finally {
+      console.warn = warn;
+    }
+    expect(getSessionValue(id, 'a')).toBeUndefined();
+    expect(probe.calls).toBe(1);
+  });
+
+  test('loadSession without a window returns early: no fetch, no notify', async () => {
+    const id = use('load-nowindow');
+    // Removed for the case and put back after it: another file's hook can have
+    // installed one while this file runs, and leaving it missing would break
+    // whichever case follows.
+    const hadWindow = Object.getOwnPropertyDescriptor(globalThis, 'window');
+    Reflect.deleteProperty(globalThis, 'window');
+    let fetched = false;
+    Reflect.set(globalThis, 'fetch', async () => {
+      fetched = true;
+      throw new Error('must not be called');
+    });
+    try {
+      const probe = counter();
+      follow(id, null, probe.listener);
+      await loadSession(id);
+      expect(fetched).toBe(false);
+      expect(probe.calls).toBe(0);
+    } finally {
+      if (hadWindow) Object.defineProperty(globalThis, 'window', hadWindow);
+      Reflect.set(globalThis, 'fetch', Bun.fetch);
+    }
+  });
+
+  /**
+   * A write that lands WHILE the read is in flight must survive the response,
+   * even when its own persist already landed (so the dirty flag is clear).
+   *
+   * This is the race behind a rare e2e failure: the page's first `/state` read
+   * is served from a snapshot taken before the click, the click writes and
+   * persists, the persist clears `dirty`, and the late response was then adopted
+   * wholesale — `layout.openedFiles` came back empty and the editor drew
+   * "Select a file to open" over the file the user had just opened.
+   */
+  test('a key written during the read wins over the response, even once it persisted', async () => {
+    const id = use('load-inflight');
+    stubWindow();
+    const resolve = gateReads({ a: 1, b: 2 });
+
+    const pending = loadSession(id);
+    // The write and its persist both land while the response is held.
+    setSessionKey(id, 'a', 99);
+    await flushSession(id);
+    resolve();
+    await pending;
+
+    expect<number | undefined>(getSessionValue(id, 'a')).toBe(99);
+    // The rest of the blob is still adopted: only the written key is protected.
+    expect<number | undefined>(getSessionValue(id, 'b')).toBe(2);
+  });
+
+  test('a key untouched during the read is adopted from the response', async () => {
+    const id = use('load-untouched');
+    stubWindow();
+    const resolve = gateReads({ a: 1 });
+
+    const pending = loadSession(id);
+    // A DIFFERENT key, written and persisted during the same window.
+    setSessionKey(id, 'other', true);
+    await flushSession(id);
+    resolve();
+    await pending;
+
+    expect<number | undefined>(getSessionValue(id, 'a')).toBe(1);
+    expect<boolean | undefined>(getSessionValue(id, 'other')).toBe(true);
+  });
+
+  test('a cleared key is not resurrected by a response that still carries it', async () => {
+    const id = use('load-cleared');
+    stubWindow();
+    hydrateSession(id, { retired: 'old', keep: 1 });
+    const resolve = gateReads({ retired: 'old', keep: 1 });
+
+    const pending = loadSession(id);
+    clearSessionKey(id, 'retired');
+    await flushSession(id);
+    resolve();
+    await pending;
+
+    expect(getSessionValue(id, 'retired')).toBeUndefined();
+    expect<number | undefined>(getSessionValue(id, 'keep')).toBe(1);
+  });
+
+  test('flushSession is a resolved no-op without a window or id', async () => {
+    await expect(flushSession(null)).resolves.toBeUndefined();
+    await expect(flushSession(use('flush'))).resolves.toBeUndefined();
+  });
+});

package/src/shared/lib/workspace/session-state/store.test.ts

@@ -6,63 +6,37 @@
 /**
  * Pins the session-state store's observer contract and cache lifecycle.
  *
- * The store is a module singleton with private Maps, so the tests drive it
- * only through its exports and tear every touched session down with
- * `forgetSession` (which clears the cache entry, its dirty flag and its
- * pending persist timer). What matters here: a write notifies exactly the
- * followers of that (session, slot), a blob arriving notifies every follower
- * of the session, a delete notifies, and the merge rules keep a local write
- * from being clobbered by a stored blob that predates it.
+ * The store is the single source of a session's UI state: every panel reads and
+ * writes through it, and it persists the whole blob through
+ * `GET/POST /api/sessions/:sessionId/state`. Two contracts matter enough to pin
+ * here rather than in a component test:
+ *
+ *  - **Notification routing.** A write notifies the slot's followers and the
+ *    session-wide ones, never another session's, and an unsubscribed listener
+ *    stops receiving while an in-flight pass still reaches it.
+ *  - **Cache lifecycle.** The cache is bounded (10 sessions) and TTL'd (10
+ *    minutes), and eviction never takes a session with unsaved writes.
+ *
+ * The blob-arrival half — the write-during-read race — is `store-load.test.ts`,
+ * and the wholesale-replacement bus is `replacement.test.ts`.
  */
 
-import { afterEach, describe, expect, setSystemTime, test } from 'bun:test';
+import { describe, expect, setSystemTime, test } from 'bun:test';
 
-import { notifySessionKey, subscribeSessionKey } from '@/shared/lib/workspace/session-state/listeners';
+import { notifySessionKey } from '@/shared/lib/workspace/session-state/listeners';
 import {
   clearSessionKey,
-  flushSession,
   forgetSession,
   getLastOpenedAt,
   getSessionValue,
   hydrateSession,
-  loadSession,
   migrateSessionState,
   recordSessionOpen,
   setSessionKey,
 } from '@/shared/lib/workspace/session-state/store';
+import { counter, follow, installStoreTeardown, use } from '@/shared/lib/workspace/session-state/harness.test-util';
 
-const originalWindow = Reflect.get(globalThis, 'window');
-/** The runner's own fetch, reached through `Bun` so a stub leaked onto the global cannot be mistaken for it. */
-const originalFetch = Bun.fetch;
-const touched: string[] = [];
-const unsubs: Array<() => void> = [];
-
-/** Register a session id so `afterEach` forgets it. */
-function use(id: string): string {
-  touched.push(id);
-  return id;
-}
-
-/** Subscribe and auto-unsubscribe at teardown. */
-function follow(sessionId: string | null, key: string | null, listener: () => void): () => void {
-  const unsubscribe = subscribeSessionKey(sessionId, key, listener);
-  unsubs.push(unsubscribe);
-  return unsubscribe;
-}
-
-/** Count how many times `notifySessionKey` reaches a listener. */
-function counter(): { calls: number; listener: () => void } {
-  const state = { calls: 0, listener: () => { state.calls += 1; } };
-  return state;
-}
-
-afterEach(() => {
-  for (const unsubscribe of unsubs.splice(0)) unsubscribe();
-  for (const id of touched.splice(0)) forgetSession(id);
-  Reflect.set(globalThis, 'window', originalWindow);
-  Reflect.set(globalThis, 'fetch', originalFetch);
-  setSystemTime();
-});
+installStoreTeardown();
 
 describe('session-state store: read/write', () => {
   test('a null session id is a no-op for reads and writes', () => {
@@ -211,102 +185,6 @@ describe('session-state store: notification routing', () => {
   });
 });
 
-describe('session-state store: blob arrival (loadSession)', () => {
-  function stubWindow(): void {
-    Reflect.set(globalThis, 'window', {});
-  }
-
-  function stubFetch(response: unknown): void {
-    Reflect.set(globalThis, 'fetch', async () => response);
-  }
-
-  test('a clean session adopts the stored blob and notifies', async () => {
-    const id = use('load-clean');
-    stubWindow();
-    stubFetch({ ok: true, json: async () => ({ state: { a: 1, b: 2 } }) });
-    const probe = counter();
-    follow(id, null, probe.listener);
-
-    await loadSession(id);
-    expect<number | undefined>(getSessionValue(id, 'a')).toBe(1);
-    expect<string | number | boolean | Record<string, unknown> | unknown[] | null | undefined>(getSessionValue(id, 'b')).toBe(2);
-    expect(probe.calls).toBe(1);
-  });
-
-  test('a dirty session keeps its local writes over the blob', async () => {
-    const id = use('load-dirty');
-    stubWindow();
-    setSessionKey(id, 'a', 99);
-    stubFetch({ ok: true, json: async () => ({ state: { a: 1, b: 2 } }) });
-
-    await loadSession(id);
-    expect<string | number | boolean | Record<string, unknown> | unknown[] | null | undefined>(getSessionValue(id, 'a')).toBe(99);
-    expect<string | number | boolean | Record<string, unknown> | unknown[] | null | undefined>(getSessionValue(id, 'b')).toBe(2);
-  });
-
-  test('a non-ok response leaves the cache untouched but still notifies', async () => {
-    const id = use('load-error');
-    stubWindow();
-    stubFetch({ ok: false, json: async () => ({}) });
-    const probe = counter();
-    follow(id, null, probe.listener);
-
-    await loadSession(id);
-    expect(getSessionValue(id, 'a')).toBeUndefined();
-    expect(probe.calls).toBe(1);
-  });
-
-  test('a rejected fetch is swallowed and notifies', async () => {
-    const id = use('load-throw');
-    stubWindow();
-    Reflect.set(globalThis, 'fetch', async () => {
-      throw new Error('offline');
-    });
-    const probe = counter();
-    follow(id, null, probe.listener);
-
-    // The store logs the failure; keep the expected warning out of the run log.
-    const warn = console.warn;
-    console.warn = () => {};
-    try {
-      await loadSession(id);
-    } finally {
-      console.warn = warn;
-    }
-    expect(getSessionValue(id, 'a')).toBeUndefined();
-    expect(probe.calls).toBe(1);
-  });
-
-  test('loadSession without a window returns early: no fetch, no notify', async () => {
-    const id = use('load-nowindow');
-    // Removed for the case and put back after it: another file's hook can have
-    // installed one while this file runs, and leaving it missing would break
-    // whichever case follows.
-    const hadWindow = Object.getOwnPropertyDescriptor(globalThis, 'window');
-    Reflect.deleteProperty(globalThis, 'window');
-    let fetched = false;
-    Reflect.set(globalThis, 'fetch', async () => {
-      fetched = true;
-      throw new Error('must not be called');
-    });
-    try {
-      const probe = counter();
-      follow(id, null, probe.listener);
-      await loadSession(id);
-      expect(fetched).toBe(false);
-      expect(probe.calls).toBe(0);
-    } finally {
-      if (hadWindow) Object.defineProperty(globalThis, 'window', hadWindow);
-      Reflect.set(globalThis, 'fetch', Bun.fetch);
-    }
-  });
-
-  test('flushSession is a resolved no-op without a window or id', async () => {
-    await expect(flushSession(null)).resolves.toBeUndefined();
-    await expect(flushSession(use('flush'))).resolves.toBeUndefined();
-  });
-});
-
 describe('session-state store: bounded cache', () => {
   test('the oldest clean session is evicted past the size cap', () => {
     const ids = Array.from({ length: 11 }, (_unused, index) => use(`lru-${index}`));