create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/lib/walle-history-serve.js

@@ -0,0 +1,838 @@
+'use strict';
+
+// Landing-throughput WP-6 shard S8 (design doc §5 D-10 "move-only", §6 "Shard
+// module seam"): the nine Wall-E history-serving functions move out of server.js
+// VERBATIM into this module behind the same configure(deps) seam as
+// lib/api/session-messages.js (S3), lib/api/session-attach.js and
+// lib/terminal-attach-geometry.js (S6). It registers NO route and NO socket
+// handler: lib/ws/walle-control.js (wsWalleControlApi) and lib/ws/state-sync.js
+// (wsStateSyncApi) keep their tables and now receive this module's exports, the two
+// session-create configure() closures (identity/transcript) likewise, and server.js
+// keeps no wrapper -- the only surviving reference there is the by-value
+// walleHistoryServe.handleWalleHistoryRequest handed to wsWalleControlApi. Bodies
+// are identical to server.js's declarations except for the `_deps.` prefix on every
+// identifier that used to resolve to a server.js top-level binding (D-10 rule 1),
+// proven by `node bin/move-only-check.js`. Seven inline `require('./lib/...')` calls
+// are rebased to this module's own sibling paths and one
+// `require('./public/js/...')` to `../public/js/...` (S1/S3/S6 precedent: injecting
+// server.js's `require` is a loader-value transfer the public runtime closure guard
+// refuses) -- the one deviation from a pure move-only diff.
+//
+// The module deliberately lives at lib/walle-history-serve.js and NOT under lib/ws/:
+// this is not a router handler (two of the functions take the socket as their first
+// parameter, the other seven are payload/lifecycle helpers), and lib/ws/*.js is the
+// ws-router handler directory whose contract (tests/ws-router-parity) allows socket
+// access only through ctx.
+//
+// The episode/cursor lifecycles SPLIT across this seam on purpose: the bodies that
+// OWN the state stay in server.js -- `_walleHistoryCatchUpEpisodes`,
+// `_walleHistoryCursorExpiredDiagnosticAt`, `_resetWalleHistoryCatchUpEpisode`,
+// `_sweepWalleHistoryCatchUpEpisodes` and the two `_scheduleWalle*` schedulers --
+// and are injected here by reference, so the maps keep one identity.
+//
+// Injected deps, per function:
+//   _walleHistoryForSessionUi: _capToolCallsForDisplay, normalizeWalleDisplayContent
+//   _walleHistoryKeyRange: (none)
+//   _walleHistoryPayload: CTM_CONV_ORDER_AUTHORITY_ENABLED, _publicTimelineIdentity,
+//     _resolveSessionTimelineIdentity, _resolveWalleHistorySource,
+//     _walleHistoryCorrelationFields, _wallePromptEntriesForSessionUi, publicHistoryMessage
+//   _noteWalleHistoryCatchUp: _scheduleWalleSessionRowsCatchUp,
+//     _walleHistoryCatchUpEpisodes, recordSessionDiagnostic
+//   _noteWalleHistoryCursorExpired: _walleHistoryCursorExpiredDiagnosticAt,
+//     recordSessionDiagnostic
+//   _sendWalleHistoryReply: ADMISSION_RESULTS, CTM_WS_SOLICITED_REPLY_INTERACTIVE_ENABLED,
+//     _WS_ADMISSION_COUNTER_KEY, _wsSend, _wsSolicitedReplyCounters, errorSink,
+//     recordSessionDiagnostic
+//   _sendWalleHistoryErrorFrame: ADMISSION_RESULTS, _walleHistoryCorrelationFields
+//   _sendWalleSessionHistory: WALLE_HISTORY_SERIALIZE_MAX_MESSAGES, _perfTracker,
+//     _resetWalleHistoryCatchUpEpisode, _resolveWalleHistorySourceOffThread,
+//     _scheduleWalleProjectionRepair, _scheduleWalleSessionRowsCatchUp,
+//     _walleHistoryCorrelationFields, _walleHistoryForReview,
+//     _walleOpenTurnActivityForNewestPage, _wallePromptEntriesForSessionUi,
+//     _walleRowHistoryForCtmId, _walleSessionRowsFreshness, createHistoryLaneBudget,
+//     recordSessionDiagnostic, sessions
+//   handleWalleHistoryRequest: _hydrateRuntimeGoalProjectionForSocket,
+//     _sendRuntimeWorkStateToSocket, _subscribeStateSyncClient,
+//     _walleHistoryCorrelationFields, isWalleLikeSession, recordSessionDiagnostic,
+//     sessionEvents, sessions, subscribeWalleHistoryRequestClient
+//
+// No moved body assigns server.js state (D-10 rule 2), so nothing is injected as a
+// getter: every dep is a by-value reference. The two per-session Maps, the
+// admission counters and the sessions map are mutated in place, never rebound.
+
+let _deps = null;
+
+function configure(deps = {}) {
+  _deps = deps;
+}
+
+function _walleHistoryForSessionUi(history, baseIndex = 0) {
+  const offset = Number.isFinite(Number(baseIndex)) ? Number(baseIndex) : 0;
+  return (Array.isArray(history) ? history : []).map((m, index) => {
+    const role = m.role;
+    const content = m.content || m.text || '';
+    const projected = {
+      role,
+      content: role === 'assistant' ? _deps.normalizeWalleDisplayContent(content) : content,
+      model: m.model_id || m.model || '',
+      model_id: m.model_id || m.model || '',
+      latency_ms: m.latency_ms || m.latencyMs || 0,
+      timestamp: m.timestamp || m.created_at || m.createdAt || 0,
+      created_at: m.created_at || m.timestamp || m.createdAt || 0,
+      toolCalls: _deps._capToolCallsForDisplay(m.toolCalls),
+      codingSummary: m.codingSummary || undefined,
+      metadata: m.metadata || undefined,
+      runtimeDiagnostic: m.runtimeDiagnostic || undefined,
+      liveActivity: !!m.liveActivity,
+      agentLabel: m.agentLabel || undefined,
+      attachments: m.attachments || undefined,
+      // Append-only tree edges for the session view's flag-gated branch projection.
+      // displayParentUuid bridges the intervening tool_call/tool_result records so the
+      // client tree's edges land assistant->user (computed server-side in readWalleCtmHistory).
+      uuid: m.uuid || undefined,
+      historyRowUuid: m.historyRowUuid || m.uuid || undefined,
+      parentUuid: m.parentUuid != null ? m.parentUuid : undefined,
+      historyIndex: Number.isFinite(Number(m.historyIndex)) ? Number(m.historyIndex) : offset + index,
+      messageIndex: Number.isFinite(Number(m.messageIndex)) ? Number(m.messageIndex) : offset + index,
+      orderKey: m.orderKey || m.order_key || undefined, kind: m.kind || undefined, provenance: m.provenance || undefined, turnId: m.turnId != null ? String(m.turnId) : undefined,
+    };
+    if (m.displayParentUuid !== undefined) projected.displayParentUuid = m.displayParentUuid;
+    return projected;
+  });
+}
+
+function _walleHistoryKeyRange(messages) {
+  let first = null;
+  let last = null;
+  for (const message of Array.isArray(messages) ? messages : []) {
+    const key = message && (message.orderKey != null ? message.orderKey : message.order_key);
+    if (typeof key !== 'string' || key === '') continue;
+    if (first === null || key < first) first = key;
+    if (last === null || key > last) last = key;
+  }
+  return first === null ? null : { first, last };
+}
+
+function _walleHistoryPayload(sessionOrId, history, options = {}, extra = {}) {
+  const source = _deps._resolveWalleHistorySource(sessionOrId);
+  const id = source?.ctmSessionId || (typeof sessionOrId === 'object' ? sessionOrId?.id : sessionOrId);
+  const windowStart = Number.isFinite(extra.windowStart) ? Number(extra.windowStart) : 0;
+  const messages = _walleHistoryForSessionUi(history, windowStart).map(_deps.publicHistoryMessage);
+  const promptEntries = Array.isArray(extra.promptEntries)
+    ? extra.promptEntries
+    : _deps._wallePromptEntriesForSessionUi(history, windowStart);
+  const turnFields = require('./walle-turn-projection').walleTurnResponseFields(messages, {
+    scope: extra.mode || options.mode ? 'page' : 'full',
+  });
+  const historyIntegrity = require('../public/js/walle-history-integrity')
+    .buildWalleHistoryState(messages, {
+      headUuid: extra.headUuid || '',
+      hasOlder: extra.hasMore === true,
+      projectionValid: extra.projection?.valid === true,
+    });
+  const correlation = _deps._walleHistoryCorrelationFields({
+    ...options,
+    mode: extra.mode || options.mode,
+  });
+  const payload = {
+    contractVersion: 2,
+    type: 'walle-history',
+    id,
+    messages,
+    promptEntries,
+    promptCount: Number.isFinite(extra.promptCount) ? Number(extra.promptCount) : promptEntries.length,
+    integrity: {
+      schemaVersion: 1,
+      counts: historyIntegrity.counts,
+      activeHeadUuid: historyIntegrity.activeHeadUuid || '',
+      diagnosticEventIds: historyIntegrity.diagnosticEvents
+        .map((message) => message.uuid || message.id || '')
+        .filter(Boolean),
+    },
+    ...turnFields,
+    ...correlation,
+    request: {
+      mode: correlation.historyMode,
+      requestedCursor: correlation.requestedCursor,
+      requestedGeneration: correlation.requestedGeneration,
+      requestedOrderingGeneration: correlation.requestedOrderingGeneration,
+    },
+    source: extra.source || options.source || 'walle-history',
+    cacheFresh: extra.cacheFresh,
+    stale: extra.stale,
+    // Windowing metadata (OpenCode-style): the client renders this page and lazy-loads older on
+    // scroll-up. `mode` 'replace' (initial/newest) vs 'prepend' (older page). Absent total ⇒ a
+    // legacy (non-windowed) serve; the client treats it as the full set.
+    total: Number.isFinite(extra.total) ? extra.total : undefined,
+    hasMore: extra.hasMore === true ? true : (extra.total != null ? false : undefined),
+    offset: Number.isFinite(extra.offset) ? extra.offset : undefined,
+    mode: extra.mode || undefined,
+    ...require('./session-messages-page').walleHistoryPageFields(extra),
+  };
+  const projection = require('./session-messages-projection');
+  const coverage = projection.conversationPageCoverage({
+    offset: payload.offset,
+    has_more: payload.hasMore,
+    olderCursor: payload.olderCursor,
+    newerCursor: payload.newerCursor,
+    projectionEpoch: payload.projection?.epoch,
+    orderingEpoch: payload.projection?.orderingEpoch,
+    settled: extra.degraded === true ? false : extra.settled,
+    partial: extra.partial,
+    stale: payload.stale,
+    catchingUp: extra.catchingUp === true,
+    // D-2/S-4 (WP-0): a lag-only catch-up page carries its measured lag so WP-1's
+    // conversationPageCoverage can render the catch-up lifecycle from a declared lag instead
+    // of a synthesized gap.
+    lag: extra.lag || null,
+    degraded: extra.degraded,
+    degradedReason: extra.degradedReason,
+    readiness: extra.readiness,
+  }, messages);
+  const identity = _deps._publicTimelineIdentity(_deps._resolveSessionTimelineIdentity(id));
+  payload.coverage = coverage;
+  payload.timelineIdentity = identity;
+  Object.assign(payload, projection.conversationLifecycleEnvelope({
+    ...payload,
+    coverage,
+    timelineIdentity: identity,
+    catchingUp: extra.catchingUp,
+    degraded: extra.degraded,
+    degradedReason: extra.degradedReason,
+    settled: extra.degraded === true ? false : extra.settled,
+    readiness: extra.readiness,
+  }));
+  // WP-3 (D-5, §6): the envelope gains keyRange so the client can render the gap pill
+  // from a DECLARED range instead of inferring it. Flag-gated: kill-switch OFF keeps the
+  // envelope byte-shape unchanged (no keyRange field at all).
+  if (_deps.CTM_CONV_ORDER_AUTHORITY_ENABLED) payload.keyRange = _walleHistoryKeyRange(messages);
+  return payload;
+}
+
+function _noteWalleHistoryCatchUp(source, lag, turnOpen) {
+  const id = source?.ctmSessionId;
+  if (!id) return;
+  const now = Date.now();
+  let episode = _deps._walleHistoryCatchUpEpisodes.get(id);
+  if (!episode) {
+    episode = { firstSeenMs: now, lastRecordedAt: 0, lastStallLoggedAt: 0, lastTouchedMs: now };
+    _deps._walleHistoryCatchUpEpisodes.set(id, episode);
+  }
+  episode.lastTouchedMs = now;
+  if (now - episode.lastRecordedAt >= 30_000) {
+    episode.lastRecordedAt = now;
+    _deps.recordSessionDiagnostic(id, 'walle-history-catchup', {
+      lagBytes: Number(lag?.bytes) || 0,
+      lagSeconds: Number(lag?.seconds) || 0,
+      turnOpen: !!turnOpen,
+      firstSeenMs: episode.firstSeenMs,
+    });
+  }
+  if (turnOpen) return;
+  _deps._scheduleWalleSessionRowsCatchUp(source, 'walle-history-catchup');
+  if (now - episode.firstSeenMs >= 60_000 && now - episode.lastStallLoggedAt >= 300_000) {
+    episode.lastStallLoggedAt = now;
+    console.error(`[walle-history] catch-up stalled session=${String(id).slice(0, 8)} `
+      + `lagBytes=${Number(lag?.bytes) || 0} lagSeconds=${Number(lag?.seconds) || 0} `
+      + `sinceMs=${now - episode.firstSeenMs}`);
+    _deps._scheduleWalleSessionRowsCatchUp(source, 'walle-history-catchup-stalled');
+  }
+}
+
+function _noteWalleHistoryCursorExpired(sessionId, details) {
+  if (!sessionId) return;
+  const now = Date.now();
+  const lastAt = _deps._walleHistoryCursorExpiredDiagnosticAt.get(sessionId) || 0;
+  if (now - lastAt < 30_000) return;
+  _deps._walleHistoryCursorExpiredDiagnosticAt.set(sessionId, now);
+  _deps.recordSessionDiagnostic(sessionId, 'walle-history-cursor-expired', details);
+}
+
+function _sendWalleHistoryReply(ws, payload, sessionId = '') {
+  const id = String(sessionId || payload?.id || '').trim();
+  const result = _deps._wsSend(ws, payload, _deps.CTM_WS_SOLICITED_REPLY_INTERACTIVE_ENABLED ? {
+    class: 'interactive',
+    channel: 'walle-history',
+    sessionId: id,
+  } : { channel: 'walle-history', sessionId: id });
+  const counterKey = _deps._WS_ADMISSION_COUNTER_KEY[result];
+  if (counterKey) _deps._wsSolicitedReplyCounters[counterKey] += 1;
+  if (result !== _deps.ADMISSION_RESULTS.SENT && id) {
+    _deps.recordSessionDiagnostic(id, 'walle-history-reply-dropped', {
+      result,
+      channel: 'walle-history',
+    });
+    _deps.errorSink.report('walle-history:reply-dropped', Object.assign(new Error(result), {
+      code: 'CTM_WALLE_HISTORY_REPLY_DROPPED',
+    }), { sessionId: id, result });
+  }
+  return result;
+}
+
+function _sendWalleHistoryErrorFrame(ws, sessionId, options = {}, error = null) {
+  if (!ws || ws.readyState !== 1) return _deps.ADMISSION_RESULTS.DROPPED_BACKPRESSURE;
+  const id = String(sessionId || '').trim();
+  const code = String(error?.code || error?.message || 'walle_history_failed');
+  const correlation = _deps._walleHistoryCorrelationFields(options);
+  return _sendWalleHistoryReply(ws, JSON.stringify({
+    type: 'walle-history',
+    id,
+    messages: [],
+    ...correlation,
+    mode: correlation.historyMode,
+    request: {
+      mode: correlation.historyMode,
+      requestedCursor: correlation.requestedCursor,
+      requestedGeneration: correlation.requestedGeneration,
+      requestedOrderingGeneration: correlation.requestedOrderingGeneration,
+    },
+    source: options.source || 'walle-history',
+    error: code,
+    degraded: true,
+    degradedReason: 'internal_error',
+    projection: {
+      valid: true,
+      revalidating: true,
+      status: 'missing',
+      error: '',
+      staleReason: 'no_verdict',
+      epoch: 0,
+    },
+  }), id);
+}
+
+async function _sendWalleSessionHistory(ws, session, options = {}) {
+  if (!ws || ws.readyState !== 1 || !session) return false;
+  const budget = _deps.createHistoryLaneBudget(options.deadlineMs);
+  const source = await _deps._resolveWalleHistorySourceOffThread(session);
+  if (!source) {
+    const correlation = _deps._walleHistoryCorrelationFields(options);
+    _sendWalleHistoryReply(ws, JSON.stringify({
+      type: 'walle-history',
+      id: typeof session === 'object' ? session.id : session,
+      messages: [],
+      ...correlation,
+      request: {
+        mode: correlation.historyMode,
+        requestedCursor: correlation.requestedCursor,
+        requestedGeneration: correlation.requestedGeneration,
+        requestedOrderingGeneration: correlation.requestedOrderingGeneration,
+      },
+      source: options.source || 'walle-history',
+      error: 'not_walle_session',
+      degraded: true,
+      degradedReason: 'not_walle_session',
+      projection: {
+        valid: true,
+        revalidating: true,
+        status: 'missing',
+        error: '',
+        staleReason: 'no_verdict',
+        epoch: 0,
+      },
+    }), typeof session === 'object' ? session.id : session);
+    return false;
+  }
+
+  // OpenCode-style windowing: the client requests a small newest page (offset 0, limit ~60) and
+  // lazy-loads older pages (offset bumps, mode 'prepend') on scroll-up. Serializing just the page
+  // — not the whole ~23MB history — is what removes the main-loop JSON.stringify block measured in
+  // the /ctm-dev E2E. Missing or oversized limits are clamped to the bounded server page.
+  const offset = Math.max(0, Number(options.offset) || 0);
+  const historyParentAdoptionEnabled = process.env.WALLE_HISTORY_REPAIR !== '0';
+  const beforeRaw = String(options.before || '').trim();
+  // Preserve an over-limit value as invalid while bounding what crosses the
+  // read-pool boundary; decodeWalleHistoryCursor rejects anything over 2048.
+  const before = beforeRaw.length > 2048 ? beforeRaw.slice(0, 2049) : beforeRaw;
+  const afterCursorRaw = historyParentAdoptionEnabled ? String(options.afterCursor || '').trim() : '';
+  const afterCursor = afterCursorRaw.length > 2048 ? afterCursorRaw.slice(0, 2049) : afterCursorRaw;
+  const around = historyParentAdoptionEnabled ? String(options.around || '').trim().slice(0, 200) : '';
+  const afterRaw = String(options.historyWatermark || options.after || '').trim();
+  const after = afterRaw.length > 200 ? afterRaw.slice(0, 200) : afterRaw;
+  const projectionEpoch = Math.max(0, Number(options.projectionEpoch) || 0);
+  // Thread orderingEpoch end-to-end (D-1 ledger row 3): additive-only, same clamp as
+  // projectionEpoch, so getWalleHistoryDelta can fence an ordering-epoch change without
+  // refusing on a plain projection-epoch bump.
+  const orderingEpoch = Math.max(0, Number(options.orderingEpoch) || 0);
+  const requestedLimit = Number.isFinite(Number(options.limit)) ? Number(options.limit) : 0;
+  const limit = Math.min(_deps.WALLE_HISTORY_SERIALIZE_MAX_MESSAGES,
+    requestedLimit > 0 ? requestedLimit : _deps.WALLE_HISTORY_SERIALIZE_MAX_MESSAGES);
+  const requestedMode = options.mode === 'prepend'
+    ? 'prepend'
+    : (options.mode === 'around' && around
+      ? 'around'
+      : (options.mode === 'newer' && afterCursor
+        ? 'newer'
+        : (options.mode === 'append' && after && projectionEpoch > 0 ? 'append' : 'replace')));
+  const projectionLag = _deps._walleSessionRowsFreshness(source);
+  const sendHistory = (history, src, extra = {}) => {
+    if (ws.readyState !== 1) return;
+    const payloadExtra = { ...extra };
+    const prewindowed = payloadExtra.prewindowed === true;
+    delete payloadExtra.prewindowed;
+    const suppliedPromptEntries = payloadExtra.promptEntries;
+    delete payloadExtra.promptEntries;
+    const suppliedPromptCount = payloadExtra.promptCount;
+    delete payloadExtra.promptCount;
+    const responseMode = payloadExtra.responseMode || requestedMode;
+    delete payloadExtra.responseMode;
+    const promptEntries = Array.isArray(suppliedPromptEntries)
+      ? suppliedPromptEntries
+      : _deps._wallePromptEntriesForSessionUi(history);
+    let win;
+    if (prewindowed) {
+      win = {
+        window: Array.isArray(history) ? history : [],
+        total: Math.max(0, Number(payloadExtra.total) || 0),
+        hasMore: payloadExtra.hasMore === true,
+        offset: Math.max(0, Number(payloadExtra.offset) || 0),
+        start: Math.max(0, Number(payloadExtra.windowStart) || 0),
+      };
+    } else {
+      const pageHelpers = require('./session-messages-page');
+      const { buildProjectionManifest, WALLE_HISTORY_PROJECTOR_VERSION } = require('./walle-history-projection');
+      const sourceRows = Array.isArray(history) ? history : [];
+      const sourceManifest = buildProjectionManifest(_deps._walleHistoryForReview(sourceRows));
+      payloadExtra.projection = {
+        valid: sourceManifest.valid,
+        revalidating: false,
+        status: 'source',
+        version: WALLE_HISTORY_PROJECTOR_VERSION,
+        epoch: 0,
+        rowCount: sourceManifest.rowCount,
+        identityDigest: sourceManifest.identityDigest,
+        error: sourceManifest.error || '',
+        staleReason: '',
+      };
+      if (sourceManifest.valid === false) {
+        _deps._scheduleWalleProjectionRepair(source.ctmSessionId, 'walle-history-source-structural');
+      }
+      // Invalid topology is still paginated: the projection metadata forces the
+      // client into audit mode, while the cursor lets a large damaged transcript
+      // reveal every event without one unbounded main-loop serialization.
+      const sourceWindow = pageHelpers.getWalleSourceHistoryWindow(sourceRows, {
+        sessionId: source.ctmSessionId,
+        offset,
+        limit,
+        before,
+        afterCursor,
+        around,
+      });
+      win = {
+        window: sourceWindow.messages,
+        total: sourceWindow.total,
+        hasMore: sourceWindow.hasMore,
+        offset: sourceWindow.offset,
+        start: sourceWindow.windowStart,
+      };
+      Object.assign(payloadExtra, pageHelpers.walleHistoryPageFields(sourceWindow));
+    }
+    const openActivity = _deps._walleOpenTurnActivityForNewestPage(
+      typeof session === 'object' && session ? session : _deps.sessions.get(String(session || '')),
+      source,
+      { mode: responseMode, offset: win.offset, before, around, hasMoreNewer: payloadExtra.hasMoreNewer },
+    );
+    if (openActivity) win = { ...win, window: [...win.window, openActivity] };
+    let serializedChars = 0;
+    const serialized = _deps._perfTracker.runSyncProbed('walleWsHistory:serialize', () => {
+      const json = JSON.stringify(_walleHistoryPayload(session, win.window, options, {
+          source: options.source || src,
+          cacheFresh: payloadExtra.cacheFresh !== undefined
+            ? payloadExtra.cacheFresh
+            : payloadExtra.settled === true,
+          total: win.total,
+          hasMore: win.hasMore,
+          offset: win.offset,
+          windowStart: win.start,
+          promptEntries,
+          promptCount: Number.isFinite(Number(suppliedPromptCount))
+            ? Number(suppliedPromptCount)
+            : promptEntries.length,
+          mode: responseMode,
+          historyParentAdoptionEnabled,
+          // One-release compatibility for clients predating the terminology fix.
+          historyRepairEnabled: historyParentAdoptionEnabled,
+          projectionLagBytes: Math.max(0, Number(projectionLag.lagBytes || 0)),
+          projectionLagSeconds: Math.max(0, Number(projectionLag.lagSeconds || 0)),
+          ...payloadExtra,
+        }));
+      serializedChars = json.length;
+      return json;
+    }, { context: () => ({
+      msgs: Array.isArray(win.window) ? win.window.length : 0,
+      total: win.total,
+      src,
+      serializedChars,
+    }) });
+    return _sendWalleHistoryReply(ws, serialized, source.ctmSessionId);
+  };
+
+  // (1) Durable row store under the canonical ctm id — fresh ⇒ serve without touching the JSONL.
+  // D-12: degradedReason is honesty about what actually happened during THIS
+  // read, not a precomputed guess seeded from options.noCache — a client
+  // passing noCache:true (WP-4's auto-retry does exactly this) is asking to
+  // skip the fresh row-store lane below, not asserting that the read is
+  // degraded. Only a real miss (rowHistory.__miss / stale.__miss) sets this now.
+  let degradedReason = '';
+  if (options.noCache !== true) {
+    // D-4 (WP-0): the P11 byte-identical retry that used to sit here (a second, identical
+    // off-thread read whenever the first came back watermarkStale) is deleted -- D-1 makes
+    // getWalleHistoryDelta resolve the anchor before ever refusing, so a repeat read with the
+    // SAME inputs could only ever reproduce the SAME reply. It never healed anything; it only
+    // doubled read cost and hid the true cause behind a generic degraded page.
+    const rowHistory = await _deps._walleRowHistoryForCtmId(source, {
+      offset,
+      limit,
+      before,
+      afterCursor: requestedMode === 'newer' ? afterCursor : '',
+      around: requestedMode === 'around' ? around : '',
+      after: requestedMode === 'append' ? after : '',
+      projectionEpoch,
+      orderingEpoch: requestedMode === 'append' ? orderingEpoch : 0,
+      budget,
+    });
+    if (rowHistory?.__miss) degradedReason = rowHistory.__miss;
+    if (limit > 0 && rowHistory && Array.isArray(rowHistory.messages)) {
+      // S-8 (WP-0): a cursor/watermark expiry is a THIRD lane, distinct from both catching-up
+      // and complete -- it must not enter the catch-up lifecycle (no _noteWalleHistoryCatchUp,
+      // no _resetWalleHistoryCatchUpEpisode: an expiry says nothing about lag) and must not
+      // report settled:true (nothing was actually served).
+      const expired = rowHistory.cursorStale === true || rowHistory.error === 'cursor_expired';
+      // D-2/S-4 (WP-0): rowHistory.catchingUp === true means catchUpKind classified this v2
+      // window as 'lag' -- renderable, complete-to-its-cursor history that is not a miss. It
+      // gets the SAME extras as a complete page except for the catch-up lifecycle markers
+      // below; a fresh (non-catching-up) page closes out any open lag episode for the session.
+      const catchingUp = !expired && rowHistory.catchingUp === true;
+      if (expired) {
+        _noteWalleHistoryCursorExpired(source.ctmSessionId, {
+          expiredReason: rowHistory.expiredReason,
+          requestedEpoch: projectionEpoch,
+          servedEpoch: rowHistory.projection?.epoch,
+        });
+      } else if (catchingUp) {
+        // D-3 review fix: the production call site (handleWalleHistoryRequest) passes a bare
+        // session id STRING here, not the session object -- this function already branches on
+        // `typeof session === 'object'` above for exactly that reason. Resolve the LIVE session
+        // from the session map so turnOpen reflects reality instead of always reading undefined
+        // off a string.
+        const liveSession = typeof session === 'object' && session
+          ? session
+          : _deps.sessions.get(String(session || ''));
+        _noteWalleHistoryCatchUp(source, rowHistory.lag, !!liveSession?.abortController);
+      } else {
+        _deps._resetWalleHistoryCatchUpEpisode(source.ctmSessionId);
+      }
+      sendHistory(rowHistory.messages, 'walle-session-rows', {
+        prewindowed: true,
+        total: rowHistory.total,
+        hasMore: rowHistory.hasMore,
+        offset: rowHistory.offset,
+        windowStart: rowHistory.windowStart,
+        promptEntries: rowHistory.promptEntries,
+        promptCount: rowHistory.promptCount,
+        olderCursor: rowHistory.olderCursor,
+        newerCursor: rowHistory.newerCursor,
+        hasMoreNewer: rowHistory.hasMoreNewer === true,
+        windowEnd: rowHistory.windowEnd,
+        firstMessageIndex: rowHistory.firstMessageIndex,
+        lastMessageIndex: rowHistory.lastMessageIndex,
+        // S-32b: getWalleHistoryDelta's watermark-miss reply (append/newer mode) sets
+        // watermarkStale/error:'watermark_stale' — a DIFFERENT field than the cursor-miss
+        // cursorStale/error:'cursor_stale' the client's stale-recovery branches already key off
+        // (handleHistoryPrepend, and WP-6's handleHistoryAppend). Fold it into the same signal
+        // the client understands instead of silently shipping an empty "loaded" page.
+        cursorStale: expired || require('./session-messages-page').walleReplyCursorStale(rowHistory),
+        expiredReason: rowHistory.expiredReason || undefined,
+        resume: rowHistory.resume || undefined,
+        epochAdvanced: rowHistory.epochAdvanced === true || undefined,
+        newerRemaining: Math.max(0, Number(rowHistory.newerRemaining) || 0),
+        projection: rowHistory.projection,
+        // WP-5 (S-29): honest fallback marker — set when the served store's cutover is not
+        // 'active' (getSelectedWalleHistoryWindow), null/undefined otherwise.
+        importProgress: rowHistory.importProgress || undefined,
+        error: rowHistory.error || undefined,
+        // H1b-v2 (§10.22): forward ONLY the producer's own conditional observation properties.
+        ...(Object.hasOwn(rowHistory, 'historyViewProof') ? { historyViewProof: rowHistory.historyViewProof } : {}),
+        ...(Object.hasOwn(rowHistory, 'historyViewProofError') ? { historyViewProofError: rowHistory.historyViewProofError } : {}),
+        ...(Object.hasOwn(rowHistory, 'resumeHistoryViewProof') ? { resumeHistoryViewProof: rowHistory.resumeHistoryViewProof } : {}),
+        ...(Object.hasOwn(rowHistory, 'resumeHistoryViewProofError') ? { resumeHistoryViewProofError: rowHistory.resumeHistoryViewProofError } : {}),
+        responseMode: rowHistory.mode === 'append' ? 'append' : requestedMode,
+        promptMode: rowHistory.mode === 'append' ? 'append' : requestedMode,
+        ...(expired
+          ? {
+            settled: false,
+            cacheFresh: false,
+            stale: false,
+            catchingUp: false,
+            degraded: false,
+            readiness: { reason: 'cursor_expired' },
+          }
+          : catchingUp
+            ? {
+              settled: false,
+              cacheFresh: false,
+              stale: true,
+              catchingUp: true,
+              degraded: false,
+              readiness: { reason: 'rows_behind' },
+              lag: { bytes: rowHistory.lag.bytes, seconds: rowHistory.lag.seconds },
+            }
+            : {
+              settled: true,
+              readiness: { reason: 'complete' },
+            }),
+      });
+      return true;
+    }
+    if (Array.isArray(rowHistory) && rowHistory.length > 0) {
+      sendHistory(rowHistory, 'walle-session-rows', {
+        settled: true,
+        readiness: { reason: 'complete' },
+      });
+      return true;
+    }
+  }
+
+  // (2) Stale/missing rows: render the last committed page and schedule the
+  // uniform incremental source importer. A request path never parses an
+  // enrolled append log or writes a reconstructed snapshot.
+  try {
+    _deps._scheduleWalleSessionRowsCatchUp(source, 'walle-history-attach');
+    const stale = await _deps._walleRowHistoryForCtmId(source, {
+      offset,
+      limit,
+      before,
+      afterCursor: requestedMode === 'newer' ? afterCursor : '',
+      around: requestedMode === 'around' ? around : '',
+      after: requestedMode === 'append' ? after : '',
+      projectionEpoch,
+      orderingEpoch: requestedMode === 'append' ? orderingEpoch : 0,
+      allowStale: true,
+      budget,
+      budgetRung: 'stale',
+    });
+    if (stale?.__miss) degradedReason = stale.__miss; if (stale?.__miss === 'projection_empty' && Array.isArray(stale.fallbackRows) && stale.fallbackRows.length > 0) { sendHistory(stale.fallbackRows, 'walle-session-rows-syncing', { cacheFresh: false, settled: false, stale: true, catchingUp: true, degraded: true, degradedReason: 'projection_empty', readiness: { reason: 'rows_behind' } }); return true; } // P1-1: an empty v2 projection over a non-empty transcript serves the raw fold instead of the source_unavailable page below
+    if (limit > 0 && stale && Array.isArray(stale.messages)) {
+      // D-12: an honest label for a miss with no classified cause, not a
+      // borrowed 'freshness_gate' — that reason belongs to the freshness
+      // predicates in _walleRowHistoryForCtmId, which set degradedReason
+      // themselves (via __miss) when they actually fire.
+      const reason = degradedReason || 'unknown_miss';
+      // Fix round 1 (WP-0 review): the stale lane can ALSO serve an expired cursor/watermark
+      // (allowStale:true does not bypass D-1's own refusal reasons) -- a zero-row expiry here
+      // is exactly as much "not a lag frame" as it is in the fresh lane (D-6), so it must not
+      // be stamped catchingUp:true, and must carry expiredReason/resume for WP-1.
+      const staleExpired = stale.cursorStale === true || stale.error === 'cursor_expired';
+      sendHistory(stale.messages, 'walle-session-rows-syncing', {
+        prewindowed: true,
+        total: stale.total,
+        hasMore: stale.hasMore,
+        offset: stale.offset,
+        windowStart: stale.windowStart,
+        promptEntries: stale.promptEntries,
+        promptCount: stale.promptCount,
+        olderCursor: stale.olderCursor,
+        newerCursor: stale.newerCursor,
+        hasMoreNewer: stale.hasMoreNewer === true,
+        firstMessageIndex: stale.firstMessageIndex,
+        lastMessageIndex: stale.lastMessageIndex,
+        windowEnd: stale.windowEnd,
+        // S-32b: same watermarkStale->cursorStale fold as the fresh-row reply above.
+        cursorStale: staleExpired || require('./session-messages-page').walleReplyCursorStale(stale),
+        expiredReason: stale.expiredReason || undefined,
+        resume: stale.resume || undefined,
+        projection: stale.projection,
+        importProgress: stale.importProgress || undefined,
+        error: stale.error || undefined,
+        // H1b-v2 (§10.22): the same four OWN observation properties, forwarded from this lane's
+        // own page object. An unobserved page adds nothing here (no absent identity is minted).
+        ...(Object.hasOwn(stale, 'historyViewProof') ? { historyViewProof: stale.historyViewProof } : {}),
+        ...(Object.hasOwn(stale, 'historyViewProofError') ? { historyViewProofError: stale.historyViewProofError } : {}),
+        ...(Object.hasOwn(stale, 'resumeHistoryViewProof') ? { resumeHistoryViewProof: stale.resumeHistoryViewProof } : {}),
+        ...(Object.hasOwn(stale, 'resumeHistoryViewProofError') ? { resumeHistoryViewProofError: stale.resumeHistoryViewProofError } : {}),
+        cacheFresh: false,
+        settled: false,
+        // The source is being revalidated, but these committed rows are still
+        // a usable durable snapshot. Reserve source_unavailable for the branch
+        // below where no rows can be served at all.
+        readiness: { reason: staleExpired ? 'cursor_expired' : 'rows_behind' },
+        stale: true,
+        catchingUp: !staleExpired,
+        // WP-3 (D-5): degradedReason is honesty, not a feature — a stale/degraded page
+        // always carries the reason it's degraded so the client renders the gap pill
+        // from the declared range instead of guessing. Never flag-gated (the flag that
+        // used to gate this, CTM_WALLE_HISTORY_DEGRADED_HONESTY, is retired).
+        // I-2 (final review): an expiry is a THIRD lane, not a fault (D-2) — the stale
+        // lane must ship the same degraded:false/no-degradedReason contract the fresh
+        // lane already does, or the live degraded-rate metric this design is gated on
+        // (AC-1e/AC-4c) goes blind to every expiry that lands on this lane.
+        degraded: !staleExpired,
+        ...(staleExpired ? {} : { degradedReason: reason }),
+        responseMode: requestedMode,
+      });
+      if (staleExpired) {
+        _noteWalleHistoryCursorExpired(source.ctmSessionId, {
+          expiredReason: stale.expiredReason,
+          requestedEpoch: projectionEpoch,
+          servedEpoch: stale.projection?.epoch,
+        });
+      } else {
+        _deps.recordSessionDiagnostic(source.ctmSessionId, 'walle-history-degraded', { reason });
+      }
+      return true;
+    }
+    const reason = stale?.__miss || degradedReason || budget.reason() || 'meta_unavailable';
+    sendHistory(Array.isArray(stale) ? stale : [], 'walle-session-rows-syncing', {
+      cacheFresh: false,
+      settled: false,
+      readiness: { reason: 'source_unavailable' },
+      stale: true,
+      catchingUp: true,
+      // WP-3 (D-5): see the matching comment on the rows_behind branch above — always on.
+      degraded: true,
+      degradedReason: reason,
+      responseMode: 'replace',
+    });
+    _deps.recordSessionDiagnostic(source.ctmSessionId, 'walle-history-degraded', { reason });
+    return true;
+  } catch (e) {
+    console.error('[walle-history] rehydrate error:', e.message);
+    _sendWalleHistoryErrorFrame(ws, source.ctmSessionId, options, e);
+    return false;
+  }
+}
+
+function handleWalleHistoryRequest(ws, msg = {}) {
+  const id = String(msg.id || '').trim();
+  const correlation = _deps._walleHistoryCorrelationFields(msg);
+  if (!id) {
+    if (ws?.readyState === 1) {
+      _sendWalleHistoryReply(ws, JSON.stringify({
+        type: 'walle-history',
+        id,
+        messages: [],
+        ...correlation,
+        request: {
+          mode: correlation.historyMode,
+          requestedCursor: correlation.requestedCursor,
+          requestedGeneration: correlation.requestedGeneration,
+          requestedOrderingGeneration: correlation.requestedOrderingGeneration,
+        },
+        error: 'missing_session_id',
+        degraded: true,
+        degradedReason: 'internal_error',
+      }), id);
+    }
+    return;
+  }
+  const hasOwn = (field) => Object.prototype.hasOwnProperty.call(msg, field);
+  // H2 controller incarnation: the marker is OPTIONAL (a markerless request stays accepted --
+  // unfenced compatibility with old/qualifying callers), but an explicitly supplied malformed
+  // one -- own undefined/null/zero/fraction/non-canonical text -- is a contract fault that keeps its own null
+  // sentinel, whatever contract version the caller declares. It is never newly REQUIRED.
+  if (hasOwn('historyControllerInstanceId')
+      && correlation.historyControllerInstanceId === null) {
+    const error = Object.assign(new Error('invalid_history_contract'), {
+      code: 'invalid_history_contract',
+    });
+    _sendWalleHistoryErrorFrame(ws, id, msg, error);
+    return;
+  }
+  if (correlation.historyContractVersion >= 3
+      && ((!hasOwn('historyRequestId')
+        || !hasOwn('historyCycleId')
+        || !hasOwn('historyMode')
+        || !hasOwn('historyCursor')
+        || !hasOwn('requestedGeneration')
+        || !hasOwn('requestedOrderingGeneration'))
+        || !correlation.historyRequestId
+        || !correlation.historyCycleId
+        || !['replace', 'prepend', 'append', 'newer', 'around'].includes(correlation.historyMode))) {
+    const error = Object.assign(new Error('invalid_history_contract'), {
+      code: 'invalid_history_contract',
+    });
+    _sendWalleHistoryErrorFrame(ws, id, msg, error);
+    return;
+  }
+
+  const session = _deps.sessions.get(id);
+  const isWalleLike = !!session && _deps.isWalleLikeSession(session);
+  // WI-3 (RC-2 fix): subscribe the ws as a client of ANY existing walle-like session —
+  // INCLUDING one still `_restoreDeferred` after a restart (see subscribeWalleHistoryRequestClient
+  // for why). work-state/`session:attached` stay gated on !_restoreDeferred below since they
+  // read state that isn't populated yet for a deferred session.
+  // I-6: no PTY/terminal to attach a worker to or reset a reconnect ladder for.
+  if (session && isWalleLike && _deps._subscribeStateSyncClient(ws, id, 'walle-history-request', { skipWorkerAttach: true })) {
+    _deps.subscribeWalleHistoryRequestClient(session, ws);
+  }
+  if (session && !session._restoreDeferred && session.type === 'walle') {
+    try { _deps._sendRuntimeWorkStateToSocket(ws, id, 'history'); } catch {}
+    _deps._hydrateRuntimeGoalProjectionForSocket(ws, id, 'history-goal-hydrated');
+    _deps.sessionEvents.emit('session:attached', { id, clientCount: session.clients.length, walle: true, historyOnly: true });
+  } else if (session?._restoreDeferred && isWalleLike) {
+    _deps.recordSessionDiagnostic(id, 'walle-history-request-deferred', {
+      source: msg.reason || msg.source || 'walle-history-request',
+      clients: Array.isArray(session.clients) ? session.clients.length : 0,
+    });
+  }
+
+  // H2 controller incarnation: forwarded ONLY when the caller supplied it own, and then VERBATIM
+  // (a valid number and the explicit null sentinel both survive; never truthiness, never a
+  // default of 0). The absence case carries no key at all -- an old internal caller stays
+  // unfenced compatibility rather than being given a fabricated identity.
+  const historyControllerMarker = hasOwn('historyControllerInstanceId')
+    ? { historyControllerInstanceId: msg.historyControllerInstanceId }
+    : {};
+  _sendWalleSessionHistory(ws, session?.id || id, {
+    ...historyControllerMarker,
+    limit: msg.limit,
+    offset: msg.offset,
+    before: msg.before,
+    afterCursor: msg.afterCursor,
+    around: msg.around,
+    mode: msg.mode,
+    historyWatermark: msg.historyWatermark,
+    projectionEpoch: msg.projectionEpoch,
+    orderingEpoch: msg.orderingEpoch,
+    noCache: msg.noCache === true,
+    deadlineMs: msg.deadlineMs,
+    historyRequestId: msg.historyRequestId || null,
+    historyContractVersion: msg.historyContractVersion,
+    historyCycleId: msg.historyCycleId,
+    historyMode: msg.historyMode || msg.mode,
+    historyCursor: msg.historyCursor,
+    requestedGeneration: msg.requestedGeneration,
+    requestedOrderingGeneration: msg.requestedOrderingGeneration,
+    source: msg.reason || msg.source || 'walle-history-request',
+  }).catch((error) => _sendWalleHistoryErrorFrame(ws, id, {
+    ...historyControllerMarker,
+    historyRequestId: msg.historyRequestId || null,
+    historyContractVersion: msg.historyContractVersion,
+    historyCycleId: msg.historyCycleId,
+    historyMode: msg.historyMode || msg.mode,
+    historyCursor: msg.historyCursor,
+    requestedGeneration: msg.requestedGeneration,
+    requestedOrderingGeneration: msg.requestedOrderingGeneration,
+    source: msg.reason || msg.source || 'walle-history-request',
+    mode: msg.mode,
+    before: msg.before,
+    afterCursor: msg.afterCursor,
+    around: msg.around,
+    historyWatermark: msg.historyWatermark,
+    projectionEpoch: msg.projectionEpoch,
+    orderingEpoch: msg.orderingEpoch,
+  }, error));
+}
+
+module.exports = {
+  configure,
+  _walleHistoryForSessionUi,
+  _walleHistoryKeyRange,
+  _walleHistoryPayload,
+  _noteWalleHistoryCatchUp,
+  _noteWalleHistoryCursorExpired,
+  _sendWalleHistoryReply,
+  _sendWalleHistoryErrorFrame,
+  _sendWalleSessionHistory,
+  handleWalleHistoryRequest,
+};