mixdog 1.4.0 → 1.4.2

package/src/standalone/session-service/projection/transcript-window.mjs

@@ -15,6 +15,13 @@ import { sanitizeForWire } from '../../session-wire-values.mjs';
  *  whatever their size: a window always shows something and paging always
  *  progresses. A viewport the rows do not fill pages further on its own. */
 const TRANSCRIPT_WINDOW_MIN_ITEMS = 8;
+/** The most rows one answer to a paged request (one naming the rows it holds,
+ *  `transcriptHeld`) carries, whatever window it names: a window sent whole,
+ *  or the rows one page reveals above the ones it holds. History itself has
+ *  no limit; it pages in steps of at most this many. */
+export const TRANSCRIPT_RESPONSE_MAX_ITEMS = 512;
+/** A request naming no held rows keeps its earlier contract: a window of at
+ *  most this many rows, answered whole. */
 const TRANSCRIPT_WINDOW_MAX_ITEMS = 8_192;
 // Deterministic restore ids: hist_<sessionId>_<messageIndex>_<part>.
 const RESTORED_ITEM_ID = /^hist_.+_(\d+)_\d+$/;
@@ -31,18 +38,26 @@ function itemBytes(item) {
 }
 
 /** The window a read/subscribe asked for, or null for a legacy view.
- *  `transcriptPageBase` names how many newest items the reader already holds:
- *  the byte budget then bounds only the older rows revealed above them. */
+ *  A paged request (`paged`: it names the rows it holds, `transcriptHeld`)
+ *  names how far back it wants history, without bound; what one answer
+ *  carries is bounded by TRANSCRIPT_RESPONSE_MAX_ITEMS and the byte budget.
+ *  Any other request keeps its earlier contract: at most
+ *  TRANSCRIPT_WINDOW_MAX_ITEMS rows, answered whole, and `transcriptPageBase`
+ *  names how many newest items the reader already holds — the byte budget
+ *  then bounds only the older rows revealed above them. */
 export function requestedTranscriptWindow(params) {
-  const limit = Number(params?.transcriptItemLimit);
-  if (!Number.isInteger(limit) || limit < 1) return null;
+  const requested = Number(params?.transcriptItemLimit);
+  if (!Number.isSafeInteger(requested) || requested < 1) return null;
   const budget = Number(params?.transcriptByteBudget);
+  const byteBudget = Number.isSafeInteger(budget) && budget > 0 ? budget : null;
+  if (requestedHeldTranscript(params)) return { limit: requested, byteBudget, pageBase: 0, paged: true };
+  const limit = Math.min(TRANSCRIPT_WINDOW_MAX_ITEMS, requested);
   const pageBase = Number(params?.transcriptPageBase);
-  const cappedLimit = Math.min(TRANSCRIPT_WINDOW_MAX_ITEMS, limit);
   return {
-    limit: cappedLimit,
-    byteBudget: Number.isInteger(budget) && budget > 0 ? budget : null,
-    pageBase: Number.isInteger(pageBase) && pageBase > 0 ? Math.min(pageBase, cappedLimit) : 0,
+    limit,
+    byteBudget,
+    pageBase: Number.isInteger(pageBase) && pageBase > 0 ? Math.min(pageBase, limit) : 0,
+    paged: false,
   };
 }
 
@@ -57,17 +72,46 @@ export function requestedHeldTranscript(params) {
   return { firstId: held.firstId, count, digest: held.digest };
 }
 
+/** Whether the window's newest `held.count` rows are exactly the rows the
+ *  caller holds: same first id and, unless the caller already proved them
+ *  (`proven`), the same content digest. */
+export function holdsTranscriptTail(items, held, proven = false) {
+  const start = items.length - held.count;
+  if (start < 0 || items[start]?.id !== held.firstId) return false;
+  return proven || transcriptItemsDigest(start ? items.slice(start) : items) === held.digest;
+}
+
+/** Whether rows one answer carries are within its bounds: at most
+ *  TRANSCRIPT_RESPONSE_MAX_ITEMS, and within `byteBudget` past
+ *  TRANSCRIPT_WINDOW_MIN_ITEMS. */
+function withinAnswerBounds(items, byteBudget, maxItems = TRANSCRIPT_RESPONSE_MAX_ITEMS) {
+  if (items.length > maxItems) return false;
+  return (
+    !byteBudget ||
+    items.length <= TRANSCRIPT_WINDOW_MIN_ITEMS ||
+    items.reduce((bytes, item) => bytes + itemBytes(item), 0) <= byteBudget
+  );
+}
+
 /** A FULL answer to a paged read, reduced to what the caller lacks: the rows
  *  above the ones it holds, the identity of its first held row, and every
- *  other field. Only when the window's tail is exactly those held rows (same
- *  first id, count and content digest); otherwise the full answer stands. */
-export function transcriptPageBody(result, held) {
+ *  other field. Only when the window's tail is exactly those held rows
+ *  (holdsTranscriptTail; `proven` when the reader already verified them) and
+ *  the rows above them fit one answer (withinAnswerBounds, `byteBudget`);
+ *  otherwise the full answer stands. */
+export function transcriptPageBody(result, held, { proven = false, byteBudget = null, pageOnly = false } = {}) {
   const snapshot = result?.full;
   if (!held || !snapshot || !Array.isArray(snapshot.items)) return result;
+  if (pageOnly) {
+    // Already only the (bounded) rows above the proven held ones.
+    const { full: _full, ...body } = result;
+    const { items, ...state } = snapshot;
+    return { ...body, page: { firstHeldId: held.firstId, heldCount: held.count, items, state } };
+  }
   const items = snapshot.items;
+  if (!holdsTranscriptTail(items, held, proven)) return result;
   const start = items.length - held.count;
-  if (start < 0 || items[start]?.id !== held.firstId) return result;
-  if (transcriptItemsDigest(start ? items.slice(start) : items) !== held.digest) return result;
+  if (!withinAnswerBounds(items.slice(0, start), byteBudget)) return result;
   const { full: _full, ...body } = result;
   const { items: _items, ...state } = snapshot;
   return {
@@ -91,25 +135,44 @@ function budgetedStart(items, end, maxItems, byteBudget, minItems) {
   return start;
 }
 
-/** First index of the kept tail: at most `limit` items. A first window spends
- *  `byteBudget` on the whole tail; a page keeps the `pageBase` newest items
- *  the reader holds and spends it on the rows revealed above them. Neither
- *  goes below TRANSCRIPT_WINDOW_MIN_ITEMS. */
+/** First index of the kept tail: at most `limit` items (never more than
+ *  TRANSCRIPT_WINDOW_MAX_ITEMS). A first window spends `byteBudget` on the
+ *  whole tail; a page keeps the `pageBase` newest items the reader holds and
+ *  spends it on the rows revealed above them. Neither goes below
+ *  TRANSCRIPT_WINDOW_MIN_ITEMS. */
 function tailWindowStart(items, { limit, byteBudget = null, pageBase = 0 }) {
-  const held = Math.min(pageBase || 0, limit, items.length);
-  return budgetedStart(items, items.length - held, limit - held, byteBudget, TRANSCRIPT_WINDOW_MIN_ITEMS);
-}
-
-/** A stored projection already holds at most `window.limit` items; the byte
- *  budget may cut it further. */
-export function budgetStoredWindow(wire, window) {
-  if (!window?.byteBudget || !Array.isArray(wire?.items)) return wire;
-  const start = tailWindowStart(wire.items, {
-    limit: wire.items.length,
-    byteBudget: window.byteBudget,
-    pageBase: window.pageBase,
-  });
-  return start === 0 ? wire : { ...wire, items: wire.items.slice(start), transcriptHasOlder: true };
+  const maxItems = Math.min(limit, TRANSCRIPT_WINDOW_MAX_ITEMS);
+  const held = Math.min(pageBase || 0, maxItems, items.length);
+  return budgetedStart(items, items.length - held, maxItems - held, byteBudget, TRANSCRIPT_WINDOW_MIN_ITEMS);
+}
+
+/** The answer a stored window (at most `window.limit` newest rows) gives. A
+ *  paged request: the `held` newest rows the caller is proven to hold, and
+ *  above them at most TRANSCRIPT_RESPONSE_MAX_ITEMS more within the byte
+ *  budget — or, proving none, a tail within the same bounds. Any other
+ *  request: the whole window, byte-budgeted above its `pageBase`. */
+export function clampStoredWindow(wire, window, held = 0) {
+  if (!window || !Array.isArray(wire?.items)) return wire;
+  const items = wire.items;
+  let start = 0;
+  if (window.paged) {
+    const maxItems = Math.min(window.limit - held, TRANSCRIPT_RESPONSE_MAX_ITEMS);
+    start = budgetedStart(items, items.length - held, maxItems, window.byteBudget, TRANSCRIPT_WINDOW_MIN_ITEMS);
+  } else if (window.byteBudget) {
+    start = tailWindowStart(items, { limit: items.length, byteBudget: window.byteBudget, pageBase: window.pageBase });
+  }
+  return start === 0 ? wire : { ...wire, items: items.slice(start), transcriptHasOlder: true };
+}
+
+/** A stored page (only the rows above the `held` ones a paged caller proved)
+ *  cut to one answer: at most TRANSCRIPT_RESPONSE_MAX_ITEMS (and the window's
+ *  limit) newest of them within the byte budget. */
+export function clampStoredPage(wire, window, held) {
+  if (!Array.isArray(wire?.items)) return wire;
+  const items = wire.items;
+  const maxItems = Math.max(0, Math.min(window.limit - held, TRANSCRIPT_RESPONSE_MAX_ITEMS));
+  const start = budgetedStart(items, items.length, maxItems, window.byteBudget, TRANSCRIPT_WINDOW_MIN_ITEMS);
+  return start === 0 ? wire : { ...wire, items: items.slice(start), transcriptHasOlder: true };
 }
 
 /** A restored runtime transcript that starts after message 0 may have older
@@ -128,11 +191,68 @@ function runtimeArchiveRange(state) {
   return Number.isInteger(after) && Number.isInteger(before) && before - 1 > after ? { after, before } : null;
 }
 
+/** The rows the runtime spilled out of memory above its first row
+ *  (`transcriptSpilled`: `{ rows, epoch }`), published with the rows
+ *  themselves and independent of the TUI's reading cursor; null when none. */
+function spilledOf(state) {
+  const spilled = spillStateOf(state);
+  return spilled && spilled.rows > 0 ? spilled : null;
+}
+
+/** The published spill state, zero rows included (null: none published). */
+function spillStateOf(state) {
+  const spilled = state?.transcriptSpilled;
+  const rows = Number(spilled?.rows);
+  const epoch = Number(spilled?.epoch);
+  return Number.isSafeInteger(rows) && rows >= 0 && Number.isSafeInteger(epoch) ? { rows, epoch } : null;
+}
+
+const sameSpill = (left, right) => left?.rows === right?.rows && left?.epoch === right?.epoch;
+
+/** Whether spilled rows sit above the runtime's first row, readable through
+ *  its spill accessor. A loaded head answers for itself. */
+function spilledAbove(entry, state, view) {
+  return !view.head.length && spilledOf(state) !== null && typeof entry.runtime?.readSpilledTranscript === 'function';
+}
+
 function resetLoadedHead(view) {
   view.head = [];
   view.headOlder = null;
   view.headSource = null;
   view.archiveHeld = 0;
+  // Absolute index of the oldest spilled row the head holds (null: none).
+  view.spillFrom = null;
+}
+
+/** Older rows a spilled head leaves above itself: more spilled rows, or the
+ *  source above the first spilled row. */
+function spilledHeadOlder(view, archive) {
+  return view.spillFrom > 0 || (view.head.length > 0 && headSourceFor(view.head[0], archive) !== null);
+}
+
+/** The runtime spilled its oldest rows while the window showed them (its
+ *  anchor among them): those rows join the head exactly as spilled, so the
+ *  window keeps its rows and its place. False when the spill does not
+ *  continue the rows this window last saw. */
+function followSpilledAnchor(entry, view, wire) {
+  const spilled = spilledOf(wire);
+  const before = view.spilled;
+  const read = entry.runtime?.readSpilledTranscript;
+  if (!spilled || typeof read !== 'function' || view.start === null) return false;
+  // Rows spilled when the window last looked: none, or a count in this epoch.
+  if (before && before.epoch !== spilled.epoch) return false;
+  const from = (before?.rows ?? 0) + view.start;
+  if (from >= spilled.rows) return false;
+  const page = read({ epoch: spilled.epoch, end: spilled.rows, limit: spilled.rows - from });
+  if (!page || page.broken || page.start !== from || page.items[0]?.id !== view.anchorId) return false;
+  view.head = view.head.concat(sanitizeForWire(page.items));
+  if (view.headSource !== 'stored' && view.headSource !== 'archive') {
+    view.spillFrom ??= from;
+    view.headSource = 'spill';
+    view.headOlder = spilledHeadOlder(view, runtimeArchiveRange(wire));
+  }
+  view.start = 0;
+  return true;
 }
 
 /** Fold a read/subscribe request into a live entry's window. */
@@ -145,9 +265,11 @@ export function requestLiveTranscriptWindow(entry, request) {
   if (view?.full) return;
   if (!view) {
     entry.transcriptView = {
-      limit: request.limit,
+      // Its first window goes out whole: for a paged request,
+      // TRANSCRIPT_RESPONSE_MAX_ITEMS at most.
+      limit: request.paged ? Math.min(request.limit, TRANSCRIPT_RESPONSE_MAX_ITEMS) : request.limit,
       byteBudget: request.byteBudget,
-      pageBase: request.pageBase,
+      pageBase: request.paged ? 0 : request.pageBase || 0,
       start: null,
       anchorId: undefined,
       grow: false,
@@ -156,16 +278,29 @@ export function requestLiveTranscriptWindow(entry, request) {
       paged: false,
       head: [],
       headOlder: null,
-      // Where the loaded head came from: 'stored' (durable history aligned by
-      // restore ids) or 'archive' (compaction-archive pages).
+      // Where the loaded head came from: 'spill' (the rows the runtime spilled
+      // out of memory, exactly), 'stored' (durable history aligned by restore
+      // ids) or 'archive' (compaction-archive pages).
       headSource: null,
       archiveHeld: 0,
+      spillFrom: null,
+      // The spilled rows (`{ rows, epoch }`) when the window last looked.
+      spilled: null,
+      // Rows the window last showed.
+      size: 0,
       cache: null,
     };
     return;
   }
-  if (request.limit > view.limit) {
-    view.limit = request.limit;
+  if (request.limit > view.limit && view.limit < TRANSCRIPT_WINDOW_MAX_ITEMS) {
+    // One paged request reveals at most TRANSCRIPT_RESPONSE_MAX_ITEMS older
+    // rows; any other names at most TRANSCRIPT_WINDOW_MAX_ITEMS. The shared
+    // window never grows past TRANSCRIPT_WINDOW_MAX_ITEMS: deeper history is
+    // a historical-position read (readTranscriptHistory), which no view shares.
+    view.limit = Math.min(
+      TRANSCRIPT_WINDOW_MAX_ITEMS,
+      request.paged ? Math.min(request.limit, view.size + TRANSCRIPT_RESPONSE_MAX_ITEMS) : request.limit
+    );
     // The page's own budget bounds the rows it reveals.
     view.grow = { byteBudget: request.byteBudget };
     view.paged = true;
@@ -188,6 +323,36 @@ export function inheritTranscriptWindow(entry, view) {
   );
 }
 
+/** The most rows the answer to `window` (requestedTranscriptWindow) carries
+ *  whole, and its byte bound: a paged request's TRANSCRIPT_RESPONSE_MAX_ITEMS
+ *  within its budget, any other's TRANSCRIPT_WINDOW_MAX_ITEMS. */
+export function transcriptAnswerBounds(window) {
+  return window?.paged
+    ? { maxItems: TRANSCRIPT_RESPONSE_MAX_ITEMS, byteBudget: window.byteBudget }
+    : { maxItems: TRANSCRIPT_WINDOW_MAX_ITEMS, byteBudget: null };
+}
+
+/** Whether `snapshot`, the entry's window about to go out whole, exceeds
+ *  `bounds` (transcriptAnswerBounds). A legacy whole view has no window and
+ *  never does. */
+export function transcriptWindowOversized(entry, snapshot, bounds) {
+  const view = entry.transcriptView;
+  const items = snapshot?.items;
+  if (!view || view.full || !Array.isArray(items)) return false;
+  return !withinAnswerBounds(items, bounds.byteBudget, bounds.maxItems);
+}
+
+/** The window restarts from a fresh tail of at most `maxItems` rows at its
+ *  next snapshot, as a first window: its readers page older rows again. */
+export function restartTranscriptWindow(entry, maxItems) {
+  const view = entry.transcriptView;
+  if (!view || view.full) return;
+  view.start = null;
+  view.paged = true;
+  view.limit = Math.min(view.limit, maxItems);
+  view.pageBase = 0;
+}
+
 /** The entry's wire snapshot seen through its window. Identity-stable for an
  *  unchanged source and window, so revision steps still detect "unchanged". */
 export function windowTranscriptSnapshot(entry, wire) {
@@ -195,17 +360,34 @@ export function windowTranscriptSnapshot(entry, wire) {
   if (!view || view.full || !wire || !Array.isArray(wire.items)) return wire;
   const items = wire.items;
   let start = view.start;
+  const spill = spillStateOf(wire);
+  // The spill store was reset or restored (another epoch, or no spill state):
+  // spilled and older rows the window loaded name another page list, so it
+  // restarts from the tail whether or not its anchor is still live.
+  if (view.spilled && spill?.epoch !== view.spilled.epoch) start = null;
   if (start !== null && view.anchorId !== undefined && items[start]?.id !== view.anchorId) {
-    // The runtime rewrote its transcript before the anchor (compaction,
-    // rewind, clear): follow the anchor, or restart from the tail.
     const moved = items.findIndex((item) => item?.id === view.anchorId);
-    start = moved < 0 ? null : moved;
-    resetLoadedHead(view);
+    if (moved < 0 && followSpilledAnchor(entry, view, wire)) {
+      // The runtime spilled the rows the window starts with: they are head now.
+      start = 0;
+    } else {
+      // The runtime rewrote its transcript before the anchor (compaction,
+      // rewind, clear): follow the anchor, or restart from the tail.
+      start = moved < 0 ? null : moved;
+      resetLoadedHead(view);
+    }
   }
   if (start !== null && start > items.length) start = null;
   if (start === null) {
     start = tailWindowStart(items, view);
     resetLoadedHead(view);
+    if (view.paged) {
+      // A paged window restarted from a fresh tail is a first window again:
+      // its limit is what it shows, so the reader's next page grows it.
+      view.paged = false;
+      view.grow = false;
+      view.limit = items.length - start;
+    }
   }
   // The sticky start lets appends travel as suffix patches, so an unpaged
   // tail grows past its byte budget while views stay attached (a worker
@@ -223,10 +405,19 @@ export function windowTranscriptSnapshot(entry, wire) {
     start = budgetedStart(items, start, view.limit - held, view.grow.byteBudget, TRANSCRIPT_WINDOW_MIN_ITEMS);
     view.grow = false;
   }
+  if (!view.private && view.head.length + items.length - start > TRANSCRIPT_WINDOW_MAX_ITEMS) {
+    // Appends under a sticky start outgrew the shared window: its oldest rows
+    // go (a page's worth below the bound, so this does not recur per append).
+    resetLoadedHead(view);
+    start = Math.max(start, items.length - (TRANSCRIPT_WINDOW_MAX_ITEMS - TRANSCRIPT_RESPONSE_MAX_ITEMS));
+  }
   view.start = start;
   view.anchorId = items[start]?.id;
+  view.spilled = spill;
   const older =
-    start > 0 || (view.headOlder ?? headSourceFor(view.head[0] ?? items[0], runtimeArchiveRange(wire)) !== null);
+    start > 0 ||
+    (view.headOlder ??
+      headSourceFor(view.head[0] ?? items[0], runtimeArchiveRange(wire), spilledAbove(entry, wire, view)) !== null);
   const cache = view.cache;
   if (cache && cache.wire === wire && cache.start === start && cache.head === view.head && cache.older === older) {
     return cache.value;
@@ -236,14 +427,17 @@ export function windowTranscriptSnapshot(entry, wire) {
   else if (start) windowed = items.slice(start);
   const value = { ...wire, items: windowed, transcriptHasOlder: older };
   view.cache = { wire, start, head: view.head, older, value };
+  view.size = windowed.length;
   return value;
 }
 
-/** Where older rows above `first` come from: durable history aligned by
- *  restore ids (which continues into the compaction archive), or — once the
- *  runtime's rows are not restored ones (a live compaction archived them, or
- *  nothing was restored) — compaction-archive pages alone. */
-function headSourceFor(first, archive) {
+/** Where older rows above `first` come from: the rows the runtime spilled out
+ *  of memory above it (`spilled`), then durable history aligned by restore
+ *  ids (which continues into the compaction archive), or — once the runtime's
+ *  rows are not restored ones (a live compaction archived them, or nothing was
+ *  restored) — compaction-archive pages alone. */
+function headSourceFor(first, archive, spilled = false) {
+  if (spilled) return 'spill';
   const restoredId = RESTORED_ITEM_ID.test(String(first?.id ?? ''));
   if (restoredId && first?.archived !== true) return restoredAfterFirstMessage(first) || archive ? 'stored' : null;
   if (archive) return 'archive';
@@ -324,11 +518,12 @@ function verifiedIdentityIndex(history, first, live) {
 }
 
 /** Load history OLDER than the runtime's first item when a grown window
- *  reaches past what the runtime holds (a resumed runtime restores only a
- *  bounded tail; a compaction moved earlier rows to the display-only
- *  archive). Durable items align by their deterministic restore ids; archive
- *  pages continue below the archived rows already held. Returns whether
- *  durable history was read. */
+ *  reaches past what the runtime holds (the runtime spilled its oldest rows
+ *  out of memory; a resumed runtime restores only a bounded tail; a compaction
+ *  moved earlier rows to the display-only archive). Spilled rows come first,
+ *  exactly as spilled; then durable items align by their deterministic
+ *  restore ids; archive pages continue below the archived rows already held.
+ *  Returns whether durable history was read. */
 export async function loadLiveTranscriptHead(entry, sessionId, readStoredSession) {
   const view = entry.transcriptView;
   if (!view || view.full || !view.paged || typeof readStoredSession !== 'function' || view.headOlder === false) {
@@ -340,12 +535,19 @@ export async function loadLiveTranscriptHead(entry, sessionId, readStoredSession
   const state = entry.runtime?.getState?.();
   const runtimeItems = Array.isArray(state?.items) ? state.items : [];
   const missing = view.limit - runtimeItems.length - view.head.length;
+  // The rows were spilled since the window last looked: its next snapshot
+  // moves them into the head first, so spilled indices stay its own.
+  if (!sameSpill(spillStateOf(state), view.spilled)) return false;
+  const spilled = spilledOf(state);
   const first = view.head[0] ?? runtimeItems[0];
   const archive = runtimeArchiveRange(state);
-  const source = view.headSource || headSourceFor(first, archive);
+  const spilling = view.headSource === 'spill' ? view.spillFrom > 0 : spilledAbove(entry, state, view);
+  const source = spilling ? 'spill' : (view.headSource !== 'spill' && view.headSource) || headSourceFor(first, archive);
   if (missing <= 0 || !source) return false;
   const generation = compactionGeneration(runtimeItems);
-  if (view.head.length && view.headGeneration !== generation) {
+  // Spilled rows are the runtime's own, joined exactly whatever compacted
+  // since; a durable head is valid only for its generation.
+  if (view.head.length && view.headSource !== 'spill' && view.headGeneration !== generation) {
     // A compaction since the head was loaded: keep the rows as they are, and
     // never join older rows across the generation.
     view.headOlder = false;
@@ -357,9 +559,26 @@ export async function loadLiveTranscriptHead(entry, sessionId, readStoredSession
     entry.transcriptView === view &&
     (view.head[0] ?? currentItems()?.[0]) === first &&
     compactionGeneration(Array.isArray(currentItems()) ? currentItems() : []) === generation;
+  if (source === 'spill') {
+    // Synchronous: the rows read are exactly the ones above `first` now.
+    const end = view.spillFrom ?? spilled.rows;
+    const page = entry.runtime.readSpilledTranscript({ epoch: spilled.epoch, end, limit: missing });
+    if (!page) return false;
+    const rows = page.items;
+    const from = budgetedStart(rows, rows.length, missing, pageBudget, TRANSCRIPT_WINDOW_MIN_ITEMS);
+    view.head = sanitizeForWire(rows.slice(from)).concat(view.head);
+    view.spillFrom = end - (rows.length - from);
+    view.headSource = 'spill';
+    // An unreadable page ends the history there: nothing above it joins
+    // without a gap. Past the spilled rows, the first of them names the next
+    // source.
+    view.headOlder = page.broken && from === 0 ? false : spilledHeadOlder(view, archive);
+    return false;
+  }
   if (source === 'archive') {
     const page = await readStoredSession(sessionId, {
       compactionArchive: { ...archive, skip: view.archiveHeld || 0, limit: missing },
+      paging: true,
     });
     if (!stillCurrent()) return true;
     const rows = Array.isArray(page?.items) ? page.items : [];
@@ -371,10 +590,15 @@ export async function loadLiveTranscriptHead(entry, sessionId, readStoredSession
     view.headOlder = from > 0 || page?.hasOlder === true;
     return true;
   }
-  const stored = await readStoredSession(sessionId, { transcriptItemLimit: view.limit + runtimeItems.length });
+  const stored = await readStoredSession(sessionId, {
+    transcriptItemLimit: view.limit + runtimeItems.length,
+    paging: true,
+  });
   if (!stillCurrent()) return true;
   const history = Array.isArray(stored?.items) ? stored.items : [];
-  const overlap = alignedHistoryIndex(history, first, view.head.concat(runtimeItems), view.head.length > 0);
+  // Only a head read from this durable history aligns by its ids; spilled
+  // rows are live rows like the runtime's own.
+  const overlap = alignedHistoryIndex(history, first, view.head.concat(runtimeItems), view.headSource === 'stored');
   if (overlap < 0) {
     view.headOlder = false;
     return true;
@@ -387,6 +611,402 @@ export async function loadLiveTranscriptHead(entry, sessionId, readStoredSession
   return true;
 }
 
+/** The newest `requested` rows of a live session through a private window
+ *  (never the entry's own, which its views share): spilled rows, durable
+ *  history and archive load above the runtime's rows as for a view. */
+async function isolatedLiveRows(entry, sessionId, readStoredSession, requested) {
+  const state = entry.runtime.getState();
+  const isolated = {
+    runtime: { getState: () => state, readSpilledTranscript: entry.runtime.readSpilledTranscript },
+  };
+  requestLiveTranscriptWindow(isolated, { limit: requested, byteBudget: null, pageBase: 0 });
+  const view = isolated.transcriptView;
+  // Not shared: the shared window's row cap does not apply.
+  view.private = true;
+  windowTranscriptSnapshot(isolated, state);
+  view.limit = requested;
+  view.paged = true;
+  view.grow = { byteBudget: null };
+  let snapshot = windowTranscriptSnapshot(isolated, state);
+  // One load reads one source (spilled rows, durable history, archive): keep
+  // loading until the rows are covered, history ends, or a load adds nothing.
+  while (snapshot.items.length < requested && snapshot.transcriptHasOlder) {
+    const held = snapshot.items.length;
+    await loadLiveTranscriptHead(isolated, sessionId, readStoredSession);
+    snapshot = windowTranscriptSnapshot(isolated, state);
+    if (snapshot.items.length <= held) break;
+  }
+  privateViews.set(snapshot, view);
+  return snapshot;
+}
+
+/** The private window each isolatedLiveRows snapshot was read through. */
+const privateViews = new WeakMap();
+
+/** Positions (see HISTORY_POSITION) of rows `[from, to)` of a private
+ *  window's snapshot: its loaded head is archive rows (when it reached them)
+ *  then spilled rows from `spillFrom`; other rows need none. */
+function privateRowPositions(snapshot, state, from, to) {
+  const view = privateViews.get(snapshot);
+  const spilled = spilledOf(state);
+  const archive = runtimeArchiveRange(state);
+  const head = view?.head.length ?? 0;
+  const spillRows = view && view.spillFrom !== null && spilled ? spilled.rows - view.spillFrom : 0;
+  const archiveRows = view?.headSource === 'archive' ? head - spillRows : 0;
+  const positions = [];
+  for (let index = from; index < to; index += 1) {
+    if (index < archiveRows && archive) positions.push(archivePosition(archive, archiveRows - 1 - index));
+    else if (index >= head - spillRows && index < head && spilled) {
+      positions.push(spillPosition(spilled.epoch, view.spillFrom + index - (head - spillRows)));
+    } else positions.push(null);
+  }
+  return positions;
+}
+
+/** The most rows one historical-position read carries. */
+export const TRANSCRIPT_HISTORY_MAX_ITEMS = TRANSCRIPT_RESPONSE_MAX_ITEMS;
+
+/** A historical-position read (`transcriptHistory`: `{ before | after: row
+ *  id, limit, byteBudget? }`), validated; null when the params name none. */
+export function requestedTranscriptHistory(params) {
+  const request = params?.transcriptHistory;
+  if (request == null) return null;
+  const limit = Number(request?.limit);
+  const older = request?.before != null;
+  const id = older ? request.before : request?.after;
+  const budget = Number(request?.byteBudget);
+  if (
+    (typeof id !== 'string' && typeof id !== 'number') ||
+    (older && request.after != null) ||
+    !Number.isInteger(limit) ||
+    limit < 1 ||
+    limit > TRANSCRIPT_HISTORY_MAX_ITEMS
+  ) {
+    throw new TypeError('invalid transcript history request');
+  }
+  const position = request.position;
+  if (position != null && (typeof position !== 'string' || !HISTORY_POSITION.test(position))) {
+    throw new TypeError('invalid transcript history request');
+  }
+  return {
+    ...(older ? { before: id } : { after: id }),
+    limit,
+    byteBudget: Number.isSafeInteger(budget) && budget > 0 ? budget : null,
+    ...(position != null ? { position } : {}),
+  };
+}
+
+const historyAnswer = (sessionId, items, hasOlder, hasNewer, positions = null) => ({
+  sessionId,
+  items: sanitizeForWire(items),
+  hasOlder: hasOlder === true,
+  hasNewer: hasNewer === true,
+  ...(positions?.some((position) => position !== null) ? { positions } : {}),
+});
+
+/** Where a row of a live session's history sits in a store addressed by
+ *  position — `s:<epoch>:<index>`: a spilled row (absolute index in that spill
+ *  epoch); `a:<after>:<before>:<skip>`: a compaction-archive row (`skip` rows
+ *  newer than it in that archive range). An answer names its rows' positions
+ *  (`positions`) and a request may name its boundary row's (`position`): the
+ *  row is then read where it is — one page, verified by id — never searched
+ *  for. Rows of the runtime and of durable history need none (found by id). */
+const HISTORY_POSITION = /^(?:s:\d{1,15}:\d{1,15}|a:\d{1,15}:\d{1,15}:\d{1,15})$/;
+
+function parseHistoryPosition(position) {
+  if (typeof position !== 'string' || !HISTORY_POSITION.test(position)) return null;
+  const [kind, ...numbers] = position.split(':');
+  const values = numbers.map(Number);
+  return kind === 's'
+    ? { kind, epoch: values[0], index: values[1] }
+    : { kind, after: values[0], before: values[1], skip: values[2] };
+}
+
+const spillPosition = (epoch, index) => `s:${epoch}:${index}`;
+const archivePosition = (range, skip) => `a:${range.after}:${range.before}:${skip}`;
+
+/** Older (`before`) or newer rows than one positioned row, read where they
+ *  are: spilled rows by absolute index, archive rows by skip, past either end
+ *  into the next source (spill → archive or durable history above it; archive
+ *  → spill or runtime below it). Null when the position no longer names that
+ *  row (another epoch or range, or another row there): the caller looks up
+ *  the row instead. Every read is one bounded page. */
+async function readAtHistoryPosition(entry, state, sessionId, readStoredSession, request, older, id, position) {
+  const items = Array.isArray(state?.items) ? state.items : [];
+  const spilled = spilledOf(state);
+  const readSpill =
+    typeof entry.runtime?.readSpilledTranscript === 'function'
+      ? (range) => entry.runtime.readSpilledTranscript(range)
+      : null;
+  const archive = runtimeArchiveRange(state);
+  const readArchive = async (skip, limit) => {
+    if (!archive || limit <= 0 || typeof readStoredSession !== 'function') return null;
+    const page = await readStoredSession(sessionId, { compactionArchive: { ...archive, skip, limit }, paging: true });
+    return Array.isArray(page?.items) ? page : null;
+  };
+  const { limit, byteBudget } = request;
+  // Rows below the archive or the spill: the spill's first rows, else the runtime's.
+  const newerFromSpillStart = () => {
+    if (spilled && readSpill) {
+      const page = readSpill({ epoch: spilled.epoch, end: Math.min(spilled.rows, limit), limit });
+      // An unreadable spill page is a gap: never skipped to the runtime's rows.
+      if (!page || page.broken || page.start !== 0) return historyReset(sessionId);
+      const end = budgetedEnd(page.items, 0, limit, byteBudget);
+      const rows = page.items.slice(0, end);
+      return historyAnswer(
+        sessionId,
+        rows,
+        true,
+        true,
+        rows.map((_, i) => spillPosition(spilled.epoch, i))
+      );
+    }
+    const end = budgetedEnd(items, 0, limit, byteBudget);
+    return historyAnswer(sessionId, items.slice(0, end), true, end < items.length);
+  };
+  // Rows above the spill's first row (or the runtime's, when nothing spilled).
+  const olderThanSpillStart = async (first) => {
+    const source = headSourceFor(first, archive);
+    if (source === 'archive') return olderFromArchive(-1);
+    if (source === 'stored' && typeof readStoredSession === 'function' && first?.id != null) {
+      const page = await readStoredSession(sessionId, {
+        transcriptCursor: { before: first.id, maxRows: limit, byteBudget },
+        paging: true,
+      });
+      if (page && !page.cursorMissing && typeof page.transcriptHasNewer === 'boolean') {
+        return historyAnswer(sessionId, page.items, page.transcriptHasOlder, true);
+      }
+    }
+    return historyAnswer(sessionId, [], false, true);
+  };
+  // Archive rows older than the one `skip` rows from its newest (-1: from the newest).
+  const olderFromArchive = async (skip) => {
+    const page = await readArchive(skip + 1, limit);
+    if (!page) return historyAnswer(sessionId, [], false, true);
+    const start = budgetedStart(page.items, page.items.length, limit, byteBudget, TRANSCRIPT_WINDOW_MIN_ITEMS);
+    const rows = page.items.slice(start);
+    const positions = rows.map((_, i) => archivePosition(archive, skip + rows.length - i));
+    return historyAnswer(sessionId, rows, start > 0 || page.hasOlder === true, true, positions);
+  };
+  // Spilled rows ending just above index `end`.
+  const olderFromSpill = (end) => {
+    const page = readSpill({ epoch: spilled.epoch, end, limit });
+    if (!page || page.broken) return null;
+    const start = budgetedStart(page.items, page.items.length, limit, byteBudget, TRANSCRIPT_WINDOW_MIN_ITEMS);
+    const first = page.start + start;
+    const rows = page.items.slice(start);
+    const above = first > 0 || headSourceFor(rows[0], archive) !== null;
+    return historyAnswer(
+      sessionId,
+      rows,
+      above,
+      true,
+      rows.map((_, i) => spillPosition(spilled.epoch, first + i))
+    );
+  };
+  if (position.kind === 'runtime-start') {
+    // Older than the runtime's first row: the spill's last rows, else what
+    // lies above the runtime.
+    if (spilled && readSpill) return olderFromSpill(spilled.rows);
+    return olderThanSpillStart(items[0]);
+  }
+  if (position.kind === 's') {
+    if (!spilled || !readSpill || position.epoch !== spilled.epoch || position.index >= spilled.rows) return null;
+    const at = readSpill({ epoch: spilled.epoch, end: position.index + 1, limit: 1 });
+    if (!at || at.broken || at.items[0]?.id !== id) return null;
+    if (older) return position.index === 0 ? olderThanSpillStart(at.items[0]) : olderFromSpill(position.index);
+    const from = position.index + 1;
+    if (from >= spilled.rows) {
+      const end = budgetedEnd(items, 0, limit, byteBudget);
+      return historyAnswer(sessionId, items.slice(0, end), true, end < items.length);
+    }
+    const page = readSpill({ epoch: spilled.epoch, end: Math.min(spilled.rows, from + limit), limit });
+    if (!page || page.broken || page.start !== from) return null;
+    const end = budgetedEnd(page.items, 0, limit, byteBudget);
+    const rows = page.items.slice(0, end);
+    return historyAnswer(
+      sessionId,
+      rows,
+      true,
+      true,
+      rows.map((_, i) => spillPosition(spilled.epoch, from + i))
+    );
+  }
+  if (!archive || position.after !== archive.after || position.before !== archive.before) return null;
+  const at = await readArchive(position.skip, 1);
+  if (!at || at.items.at(-1)?.id !== id) return null;
+  if (older) return olderFromArchive(position.skip);
+  if (position.skip === 0) return newerFromSpillStart();
+  const take = Math.min(limit, position.skip);
+  const page = await readArchive(position.skip - take, take);
+  if (!page) return null;
+  const end = budgetedEnd(page.items, 0, limit, byteBudget);
+  const rows = page.items.slice(0, end);
+  return historyAnswer(
+    sessionId,
+    rows,
+    true,
+    true,
+    rows.map((_, i) => archivePosition(archive, position.skip - 1 - i))
+  );
+}
+const historyReset = (sessionId) => ({ sessionId, items: [], hasOlder: false, hasNewer: false, reset: true });
+
+/** Rows next to one row of the session's whole history — the rows directly
+ *  older than `before`, or newer than `after` — at most `limit` within
+ *  `byteBudget` (never fewer than TRANSCRIPT_WINDOW_MIN_ITEMS), with whether
+ *  more exist each way. Stateless and read-only: no view's window, baseline or
+ *  revision moves, so a reader deep in history never grows what live views
+ *  share. Rows are found by their stable ids (append-only history keeps
+ *  them); a row no longer there answers `reset` and the reader returns to the
+ *  live tail. */
+export async function readTranscriptHistory(entry, sessionId, readStoredSession, request) {
+  const older = request.before != null;
+  const id = older ? request.before : request.after;
+  const stored = async (rowId, before) => {
+    if (typeof readStoredSession !== 'function') return null;
+    const page = await readStoredSession(sessionId, {
+      transcriptCursor: {
+        ...(before ? { before: rowId } : { after: rowId }),
+        maxRows: request.limit,
+        byteBudget: request.byteBudget,
+      },
+      paging: true,
+    });
+    // A reader without historical positions answers no cursor fields.
+    if (!page || page.cursorMissing || typeof page.transcriptHasNewer !== 'boolean') return null;
+    return page;
+  };
+  if (!entry) {
+    const page = await stored(id, older);
+    return page
+      ? historyAnswer(sessionId, page.items, page.transcriptHasOlder, page.transcriptHasNewer)
+      : historyReset(sessionId);
+  }
+  const state = entry.runtime.getState();
+  const items = Array.isArray(state?.items) ? state.items : [];
+  const at = items.findIndex((item) => item?.id === id);
+  const spilled = spilledOf(state) !== null && typeof entry.runtime?.readSpilledTranscript === 'function';
+  const olderSource = headSourceFor(items[0], runtimeArchiveRange(state), spilled);
+  if (older && at > 0) {
+    const start = budgetedStart(items, at, request.limit, request.byteBudget, TRANSCRIPT_WINDOW_MIN_ITEMS);
+    return historyAnswer(sessionId, items.slice(start, at), start > 0 || olderSource !== null, true);
+  }
+  if (!older && at >= 0) {
+    const end = budgetedEnd(items, at + 1, request.limit, request.byteBudget);
+    return historyAnswer(sessionId, items.slice(at + 1, end), true, end < items.length);
+  }
+  // A row whose position the reader names (spilled or archived) is read
+  // where it is, and so is what lies above the runtime's first row.
+  const position = parseHistoryPosition(request.position);
+  if (position) {
+    const answer = await readAtHistoryPosition(
+      entry,
+      state,
+      sessionId,
+      readStoredSession,
+      request,
+      older,
+      id,
+      position
+    );
+    if (answer) return answer;
+  }
+  if (older && at === 0 && (olderSource === 'spill' || olderSource === 'archive')) {
+    const answer = await readAtHistoryPosition(entry, state, sessionId, readStoredSession, request, true, id, {
+      kind: 'runtime-start',
+    });
+    if (answer) return answer;
+  }
+  // Above the runtime's rows. Durable history aligns with restored rows by
+  // their ids while no compaction rewrote them: read it there directly.
+  if (olderSource === 'stored' && !items.some(isCompactionMark)) {
+    const page = await stored(older && at === 0 ? items[0].id : id, older);
+    if (!page) return historyReset(sessionId);
+    if (older) return historyAnswer(sessionId, page.items, page.transcriptHasOlder, true);
+    // Newer rows run into the runtime's own rows: continue there.
+    const joined = page.items.findIndex((item) => item?.id === items[0]?.id);
+    let rows = joined >= 0 ? page.items.slice(0, joined) : page.items;
+    if (rows.length === 0 && (joined >= 0 || !page.transcriptHasNewer)) {
+      rows = items.slice(0, budgetedEnd(items, 0, request.limit, request.byteBudget));
+      return historyAnswer(sessionId, rows, true, rows.length < items.length);
+    }
+    return historyAnswer(sessionId, rows, true, true);
+  }
+  // Spilled or archived rows (a live compaction): a private window loaded
+  // down to the row, deeper on each pass — but never more than
+  // TRANSCRIPT_HISTORY_LOOKUP_MAX_ITEMS rows above the runtime's own, nor on
+  // after a pass that loaded nothing new. Past that the row answers `reset`:
+  // no lookup here scales with the history's depth.
+  const bound = items.length + TRANSCRIPT_HISTORY_LOOKUP_MAX_ITEMS;
+  let requested = Math.min(bound, items.length + Math.max(request.limit * 2, 64));
+  let loaded = -1;
+  for (;;) {
+    const snapshot = await isolatedLiveRows(entry, sessionId, readStoredSession, requested);
+    const rows = snapshot.items;
+    const index = rows.findIndex((item) => item?.id === id);
+    // Found where a position names it: the page is read there.
+    const [own] = index >= 0 ? privateRowPositions(snapshot, state, index, index + 1) : [];
+    if (own) {
+      const answer = await readAtHistoryPosition(
+        entry,
+        state,
+        sessionId,
+        readStoredSession,
+        request,
+        older,
+        id,
+        parseHistoryPosition(own)
+      );
+      if (answer) return answer;
+    }
+    if (index >= 0 && (!older || index >= request.limit || !snapshot.transcriptHasOlder || requested >= bound)) {
+      if (older) {
+        const start = budgetedStart(rows, index, request.limit, request.byteBudget, TRANSCRIPT_WINDOW_MIN_ITEMS);
+        return historyAnswer(
+          sessionId,
+          rows.slice(start, index),
+          start > 0 || snapshot.transcriptHasOlder,
+          true,
+          privateRowPositions(snapshot, state, start, index)
+        );
+      }
+      const end = budgetedEnd(rows, index + 1, request.limit, request.byteBudget);
+      return historyAnswer(
+        sessionId,
+        rows.slice(index + 1, end),
+        true,
+        end < rows.length,
+        privateRowPositions(snapshot, state, index + 1, end)
+      );
+    }
+    if (!snapshot.transcriptHasOlder || rows.length < requested || rows.length <= loaded || requested >= bound) {
+      return historyReset(sessionId);
+    }
+    loaded = rows.length;
+    requested = Math.min(bound, requested * 2);
+  }
+}
+
+/** The most rows a live historical-position lookup loads above the runtime's
+ *  own (spilled or archived ones), as the stored reader's own bound. */
+const TRANSCRIPT_HISTORY_LOOKUP_MAX_ITEMS = TRANSCRIPT_WINDOW_MAX_ITEMS;
+
+/** Last index (exclusive) of the rows kept from `start`: at most `maxItems`
+ *  and, past TRANSCRIPT_WINDOW_MIN_ITEMS, within `byteBudget`. */
+function budgetedEnd(items, start, maxItems, byteBudget) {
+  let end = start;
+  let bytes = 0;
+  while (end < items.length && end - start < maxItems) {
+    const next = itemBytes(items[end]);
+    if (byteBudget && end - start >= Math.min(maxItems, TRANSCRIPT_WINDOW_MIN_ITEMS) && bytes + next > byteBudget)
+      break;
+    bytes += next;
+    end += 1;
+  }
+  return end;
+}
+
 /** A one-shot range must not grow or rebudget an attached desktop's window. */
 export async function readTranscriptRange(entry, sessionId, readStoredSession, { offset, limit }) {
   if (
@@ -401,15 +1021,31 @@ export async function readTranscriptRange(entry, sessionId, readStoredSession, {
   const requested = offset + limit;
   let snapshot;
   if (entry) {
-    const state = entry.runtime.getState();
-    const isolated = { runtime: { getState: () => state } };
-    requestLiveTranscriptWindow(isolated, { limit: requested, byteBudget: null, pageBase: 0 });
-    windowTranscriptSnapshot(isolated, state);
-    isolated.transcriptView.paged = true;
-    await loadLiveTranscriptHead(isolated, sessionId, readStoredSession);
-    snapshot = windowTranscriptSnapshot(isolated, state);
+    snapshot = await isolatedLiveRows(entry, sessionId, readStoredSession, requested);
   } else {
-    snapshot = await readStoredSession(sessionId, { transcriptItemLimit: requested });
+    // Only the range itself is sliced from the stored history.
+    const slice = await readStoredSession(sessionId, {
+      transcriptItemLimit: requested,
+      transcriptSkip: offset,
+      paging: true,
+    });
+    if (!slice) throw new Error(`session ${sessionId} is not available`);
+    const items = slice.items || [];
+    // A reader that ignores `transcriptSkip` answers the whole window — and
+    // one that holds less than the range reaches says so, rather than an
+    // empty page that never advances.
+    const honored = Object.hasOwn(slice, 'skippedFirstId');
+    if (!honored && offset >= items.length && slice.transcriptHasOlder) {
+      throw new Error('session: requested history is not available in the retained projection');
+    }
+    const end = honored ? items.length : Math.max(0, items.length - offset);
+    const start = Math.max(0, end - limit);
+    return {
+      sessionId,
+      offset,
+      items: sanitizeForWire(items.slice(start, end)),
+      hasOlder: start > 0 || slice.transcriptHasOlder === true,
+    };
   }
   if (!snapshot) throw new Error(`session ${sessionId} is not available`);
   const source = snapshot.items || [];