@kabmo-labs/kabmo 0.7.0 → 0.9.0

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

@@ -0,0 +1,159 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The session-state cache: which entries are held, and for how long.
+ *
+ * Split out of `store.ts` for the file-size ceiling, and it is the natural seam
+ * rather than an arbitrary cut. `store.ts` owns the PUBLIC API (read, write,
+ * load, migrate) and the decisions about what a write means; this owns the
+ * STORAGE — the maps, the LRU order, the idle TTL, and the dirty flag that says
+ * an entry holds writes no persist has carried yet.
+ *
+ * The maps live here and nowhere else, so "is this session dirty" and "drop this
+ * session" cannot be answered from two places that disagree.
+ */
+
+type SessionState = Record<string, unknown>;
+
+const entries = new Map<string, SessionState>();
+/** Epoch ms of the last user-driven access per session (get/set/hydrate). */
+const lastTouched = new Map<string, number>();
+/** A session with writes no persist has carried yet. */
+const dirty = new Map<string, boolean>();
+const persistTimers = new Map<string, ReturnType<typeof setTimeout>>();
+
+// Bounded LRU cache: cap the number of sessions kept in memory so the tab
+// doesn't grow unboundedly as the user visits more sessions.
+const MAX_CACHED_SESSIONS = 10;
+/** A session whose last user access is older than this is evicted regardless
+ *  of the size cap, so stale per-session UI state (drafts, panel layouts)
+ *  stops occupying memory 10 minutes after the user last opened it. */
+const SESSION_IDLE_TTL_MS = 10 * 60 * 1000;
+
+/** The cached entry, as read-only — write through the store's own setters. */
+export function readEntry(sessionId: string): Readonly<SessionState> | undefined {
+  return entries.get(sessionId);
+}
+
+/**
+ * Reorder a cache entry to the end of the Map's iteration order (the
+ * most-recently-used position) via delete-then-set. Map.set on an existing
+ * key updates the value but keeps its original position, so the explicit
+ * delete is required for true LRU semantics.
+ */
+export function touchEntry(sessionId: string): void {
+  const value = entries.get(sessionId);
+  if (value !== undefined) {
+    entries.delete(sessionId);
+    entries.set(sessionId, value);
+  }
+  lastTouched.set(sessionId, Date.now());
+}
+
+/** Stamp the entry as most-recently-used without reordering it. */
+export function stampAccess(sessionId: string): void {
+  lastTouched.set(sessionId, Date.now());
+}
+
+export function lastAccess(sessionId: string): number | undefined {
+  return lastTouched.get(sessionId);
+}
+
+/** Replace an entry outright (a blob arriving, a migrate, a hydrate). */
+export function writeEntry(sessionId: string, state: SessionState): void {
+  entries.set(sessionId, state);
+}
+
+/**
+ * The MUTABLE entry for a write, created on demand.
+ *
+ * `setSessionKey` and `clearSessionKey` mutate the cached object in place, as
+ * they always have: a copy per write would give every reader a different object
+ * for the same slot, and `useSessionState` compares the store's entry against
+ * its own copy by IDENTITY to decide whether a fresher write exists.
+ */
+export function entryForWrite(sessionId: string): SessionState {
+  const existing = entries.get(sessionId);
+  if (existing) return existing;
+  const created: SessionState = {};
+  entries.set(sessionId, created);
+  return created;
+}
+
+/** Mark a session as holding writes no persist has carried yet. */
+export function markDirty(sessionId: string): void {
+  dirty.set(sessionId, true);
+}
+
+export function clearDirty(sessionId: string): void {
+  dirty.set(sessionId, false);
+}
+
+export function isDirty(sessionId: string): boolean {
+  return dirty.get(sessionId) === true;
+}
+
+export function setPersistTimer(sessionId: string, timer: ReturnType<typeof setTimeout>): void {
+  persistTimers.set(sessionId, timer);
+}
+
+export function persistTimer(sessionId: string): ReturnType<typeof setTimeout> | undefined {
+  return persistTimers.get(sessionId);
+}
+
+export function dropPersistTimer(sessionId: string): void {
+  const timer = persistTimers.get(sessionId);
+  if (timer) {
+    clearTimeout(timer);
+    persistTimers.delete(sessionId);
+  }
+}
+
+/** Remove an entry and everything recorded about it. */
+export function dropEntry(sessionId: string): void {
+  entries.delete(sessionId);
+  dirty.delete(sessionId);
+  lastTouched.delete(sessionId);
+  dropPersistTimer(sessionId);
+}
+
+/**
+ * Evict the oldest clean sessions until the cache is within bounds.
+ *
+ * Dirty-safety rule: a session with unsaved writes (`isDirty`) must never be
+ * evicted, or the user's drafts and editor state would be silently lost. If
+ * every candidate is dirty (or is the protected id currently being written),
+ * stop evicting rather than lose data.
+ *
+ * Entries idle past SESSION_IDLE_TTL_MS are evicted first — even when the
+ * cache is under the size cap — so long-unused sessions drop out on schedule.
+ */
+export function evictIfNeeded(protectedId: string | null, onEvict: (sessionId: string) => void): void {
+  const now = Date.now();
+  const evict = (id: string): void => {
+    dropEntry(id);
+    onEvict(id);
+  };
+  // TTL pass: safe to skip only while the timer still holds the unsaved state
+  // or the session is the one currently being written.
+  for (const [id, touched] of lastTouched) {
+    if (now - touched <= SESSION_IDLE_TTL_MS) continue;
+    if (id === protectedId) continue;
+    if (isDirty(id)) continue;
+    evict(id);
+  }
+  while (entries.size > MAX_CACHED_SESSIONS) {
+    let evicted = false;
+    for (const id of entries.keys()) {
+      if (id === protectedId) continue;
+      if (isDirty(id)) continue;
+      evict(id);
+      evicted = true;
+      break;
+    }
+    if (!evicted) break;
+  }
+}

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

@@ -0,0 +1,55 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Shared harness for the session-state store's suites.
+ *
+ * Split out when `store.test.ts` passed the per-file ceiling. Every case in
+ * every suite needs the same three things — an id that teardown forgets, a
+ * subscription that teardown cancels, and a counter — and a per-file copy is how
+ * two suites end up disagreeing about what teardown restores.
+ */
+
+import { afterEach, setSystemTime } from 'bun:test';
+
+import { subscribeSessionKey } from '@/shared/lib/workspace/session-state/listeners';
+import { forgetSession } from '@/shared/lib/workspace/session-state/store';
+
+/** The runner's own fetch, reached through `Bun` so a stub leaked onto the global cannot be mistaken for it. */
+export const originalFetch = Bun.fetch;
+export const originalWindow = Reflect.get(globalThis, 'window');
+
+const touched: string[] = [];
+const unsubs: Array<() => void> = [];
+
+/** Register a session id so teardown forgets it. */
+export function use(id: string): string {
+  touched.push(id);
+  return id;
+}
+
+/** Subscribe and auto-unsubscribe at teardown. */
+export 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 a notification reaches a listener. */
+export function counter(): { calls: number; listener: () => void } {
+  const state = { calls: 0, listener: () => { state.calls += 1; } };
+  return state;
+}
+
+/** Install the suite's teardown. Called once per test file. */
+export function installStoreTeardown(): void {
+  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();
+  });
+}

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();
+  });
+});