Merge remote-tracking branch 'origin/master' into session-fork

# Conflicts:
#	docs/architecture.md
#	docs/cordis-catalog/services.md

packages/core/session/README.md

@@ -36,8 +36,9 @@ Creates and holds event-sourced `Session` instances. Persistence is intentionall
 Plain class (not a Cordis Service). Create via `ctx.sessions.create()`.
 
 - `session.append(type, data, opts?): SessionEvent` — synchronous, never blocks on I/O. **Throws** if `data` is not losslessly JSON-serializable (BigInt, function, symbol, undefined, non-finite number, circular ref, or an exotic object like Map/Set/Date) — the event log is the durable source of truth, so this invariant is enforced at the source (exported as `isJsonValue` for backends to reuse on their replay/fork entry points). A third parameter `opts: SurfaceIntent` carries surface metadata: `surfaceOp` controls how the event enters the surface linked list, and `sourceEventSeqs` records provenance (the seq numbers of events this one derives from). It is **required** for the five `SurfaceEventType` events (every message-producing event must declare how it joins the surface) and rejected by the compiler for non-surface types. The marker requirement is enforced two ways: the typed overload makes `opts` mandatory when `type` is a specific `SurfaceEventType` literal, AND `append` **throws** at runtime if a surface-eligible event arrives with no `surfaceOp` — covering the case where `type` widens to the `SessionEventType` union (a caller iterating raw events, where the conditional overload collapses to optional) so a marker-less message event can never silently land in the log and vanish from `deriveMessages()`.
-- `session.deriveMessages(): Message[]` — derive the LLM message history by walking the surface linked list (skipping non-surface events like chunks and boundaries; a `replace` shadows the nodes it covers). The surface is the single source of derived history — there is no raw-log fallback.
-- `session.surface: SurfaceManager` — the derived surface, lazily rebuilt from `surfaceOp` markers in the log. Processes only new events (delta) on each access — the log is append-only, so prior events never change.
+- `session.deriveMessages(): Message[]` — the LLM message history, CACHED: each surface node is projected exactly once, when first seen (O(new nodes) per call; a surface rewrite rebuilds via `surface.replaceGeneration`). Returns a fresh array snapshot per call over SHARED, deep-frozen `Message` objects — cloned once off the log at projection time, so a consumer can never mutate logged data (mutation throws). The surface is the single source of derived history — there is no raw-log fallback.
+- `session.deriveEventMessage(event): Message | null` — the per-event projection `deriveMessages()` folds: one event's derived message (an unfrozen clone), or `null` when it produces none (a non-surface event, or an empty-content `assistant/message` hosting only usage). External reconstructors and the dev invariant fold the same function over a log prefix's surface, so no two paths can disagree about what a request's messages were (the reconstructability RFC).
+- `session.surface: SurfaceManager` — the derived surface, lazily rebuilt from `surfaceOp` markers in the log. Processes only new events (delta) on each access — the log is append-only, so prior events never change. `surface.replaceGeneration` is the rewrite signal: bumped by every folded `replace` and by `invalidate()`, never reset, so an incremental consumer comparing generations cannot be fooled.
 - `session.events`, `session.seq`, `session.id`
 - `session.header: SessionHeader` — immutable creation metadata (`version`, `id`, `createdAt`, optional `cwd`/`parentSession`/`seedLength`). Kept out of the event log (a storage concern, not replayable state); a minimal header (stamped with the current `SESSION_FORMAT_VERSION`) is synthesized for bare `Session` construction.
 
@@ -48,6 +49,10 @@ Plain class (not a Cordis Service). Create via `ctx.sessions.create()`.
 - `SurfaceNode` — `{ seq: number; prev: number | null; next: number | null }`, one node in the surface linked list.
 - `isSurfaceEvent(event)` / `isSurfaceEligibleType(type)` — the first narrows a `SessionEvent` to a fully-formed surface node (type is surface-eligible AND `surfaceOp` present); the second is the type-only check (is this one of the five `SurfaceEventType` values?), used to detect a surface-eligible event MISSING its marker — e.g. when validating a seed/load log.
 
+### Request-header reconstruction (`request-header.ts`)
+
+The `request/header` (full `EpochHeader` snapshot with a `RequestHeaderReason`) and `request/header-delta` (system line-trim / name-keyed tools delta / whole config) events make the request envelope logged session state, so every conversation request is a pure function of the log. The pure trio reconstructs it: `foldRequestHeader(events)` folds a log (or any prefix) into the header in force; `diffHeader(prev, next)` encodes a change (undefined when equal); `applyHeaderDelta(prev, delta)` replays one. Writer contract: every logged delta is round-trip-verified (`apply(prev, delta)` deep-equals the new header) with a `'fallback'` snapshot when the encoding cannot express the change (a pure tool reordering), so folding never needs error recovery on a well-formed log. `canonicalHeader` pins the one representation of absence (empty system/tools ≡ absent fields).
+
 ### Session event vocabulary (`types.ts`)
 
 The append-only log's event types, enumerated member by member — payloads, surface badges, provenance — in the generated [persistence log event catalog](../../../docs/persistence-catalog/log-events.md). Token usage rides on `assistant/message.usage`; an operational error's step is on `turn/end.reason` for `kind: 'error'`.

packages/core/session/src/index.ts

@@ -8,11 +8,13 @@
 
 import { Context, Service } from 'cordis'
 import { isAbsolute } from 'node:path'
+import { deepFreeze } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock, Message, MessageSource } from '@deepseek-ai/dsh-llm'
 import { SESSION_FORMAT_VERSION, SessionId } from './types.ts'
-import type { CreateSessionOptions, SessionEvent, SessionEventMap, SessionEventType, SessionHeader, SurfaceIntent, SurfaceEventType } from './types.ts'
+import type { CreateSessionOptions, EpochHeader, SessionEvent, SessionEventMap, SessionEventType, SessionHeader, SurfaceIntent, SurfaceEventType } from './types.ts'
 import { isJsonValue } from './json.ts'
 import { SurfaceManager, isSurfaceEligibleType } from './surface.ts'
+import { foldRequestHeader } from './request-header.ts'
 
 export * from './types.ts'
 export { isJsonValue } from './json.ts'
@@ -21,6 +23,7 @@ export { interruptedTurnClosers } from './repair.ts'
 export type { SurfaceNode } from './surface.ts'
 export { isSurfaceEvent, isSurfaceEligibleType } from './surface.ts'
 export { isToolPairingBalanced } from './tool-pairing.ts'
+export { applyHeaderDelta, canonicalHeader, diffHeader, foldRequestHeader, headerEquals } from './request-header.ts'
 
 declare module 'cordis' {
   interface Context {
@@ -234,53 +237,93 @@ export class Session {
     return event
   }
 
+  /** Cached fold of the request-header events — see {@link requestHeader}. */
+  private headerFold: EpochHeader | undefined
+  /** Log position (events consumed) the header fold has reached. */
+  private headerFoldSeq = 0
+
+  /**
+   * The {@link EpochHeader} in force after the log's last header event — the
+   * header the NEXT request will be compared against — or undefined before
+   * the first `request/header` snapshot. The live, incrementally-maintained
+   * form of `foldRequestHeader(session.events)`: each header event is folded
+   * once, when first seen, so a per-step read costs O(new events).
+   * @returns the folded header, or undefined when no header event exists yet.
+   */
+  requestHeader(): EpochHeader | undefined {
+    if (this.headerFoldSeq < this.log.length) {
+      // Frozen on update: the fold is session state exposed by reference — a
+      // consumer mutating it in place (instead of building a replacement)
+      // would desync every later comparison against the log, so mutation
+      // throws instead.
+      this.headerFold = deepFreeze(foldRequestHeader(this.log.slice(this.headerFoldSeq), this.headerFold))
+      this.headerFoldSeq = this.log.length
+    }
+    return this.headerFold
+  }
+
+  /** The derived-message cache: frozen projections, extended per unseen node. */
+  private derived: Message[] = []
+  /** Surface position (nodes projected) the cache has reached. */
+  private derivedNodes = 0
+  /** {@link SurfaceManager.replaceGeneration} the cache was built under. */
+  private derivedGeneration = 0
+
   /**
    * Derive the LLM message history by walking the session surface — the linked
    * list of message-producing events maintained by `surfaceOp` markers. The
    * surface is the single source of derived history: every message-producing
    * append records its `surfaceOp`, so a raw event with no marker (a chunk, a
    * turn boundary) is correctly absent, and a compaction `replace` deletes the
-   * shadowed nodes from the derivation.
+   * shadowed nodes from the derivation. The projection rules are
+   * {@link deriveEventMessage}, folded per node.
    *
-   * - `user/message` → user message
-   * - `assistant/message` → assistant message (chunks are skipped — they are
-   *   replay/UI data; the assembled message is authoritative for history). An
-   *   EMPTY-content assistant/message is skipped: a max-tokens step cut off with
-   *   no content still records an assistant/message to host its `usage`, but a
-   *   content-less assistant turn must not enter the provider transcript.
-   * - `tool/result` → user message carrying a tool-result block
-   * - `context/message` / `steering/message` → tagged synthetic user messages
-   *   at their chronological position
-   *
-   * The returned `content` is **deep-cloned** off the logged events: the loop
-   * hands these messages into the mutable `agent/request` waterfall and on to
-   * adapters, where mutating the request is sanctioned — but the session log
-   * is append-only by contract. Cloning at this boundary keeps in-flight
-   * mutation from reaching back and rewriting history (which would silently
-   * break replay equivalence). Cost is one structured clone per step,
-   * negligible next to a model call.
+   * CACHED: each surface node is projected exactly once, when first seen — a
+   * call costs O(new nodes), and a surface rewrite (a `replace`;
+   * {@link SurfaceManager.replaceGeneration}) rebuilds. The returned array is
+   * a fresh snapshot per call (later appends never grow an array a caller
+   * already holds); the `Message` objects in it are SHARED and **deep-frozen**
+   * — cloned once off the log at projection time, so consumers can never
+   * mutate logged data, and mutation attempts throw instead of silently
+   * diverging replay from history.
+   * @returns a fresh array of the shared, frozen derived history.
    */
   deriveMessages(): Message[] {
-    const messages: Message[] = []
-    for (const node of this.surface.nodes) {
+    const nodes = this.surface.nodes
+    const generation = this.surface.replaceGeneration
+    if (generation !== this.derivedGeneration) {
+      this.derived = []
+      this.derivedNodes = 0
+      this.derivedGeneration = generation
+    }
+    for (const node of nodes.slice(this.derivedNodes)) {
       // Surface nodes are built from this.log — node.seq is always a valid
       // index by construction. The non-null assertion expresses that invariant.
       // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-      const msg = this._deriveOneMessage(this.log[node.seq]!)
+      const msg = this.deriveEventMessage(this.log[node.seq]!)
       // A surface node is one of the five message-producing types, but an
       // empty-content assistant/message (a max-tokens step that hosts only
       // usage) derives to null and must not enter the transcript.
-      if (msg) messages.push(msg)
+      if (msg) this.derived.push(deepFreeze(msg))
     }
-    return messages
+    this.derivedNodes = nodes.length
+    return [...this.derived]
   }
 
   /**
-   * Derive a single LLM message from one surface event, or null if it produces
-   * no message (an empty-content assistant/message that exists only to host
-   * usage).
+   * Project a single event into the LLM message it derives to, or null when
+   * it produces none — a non-surface event (chunk, boundary, log-only record)
+   * or an empty-content assistant/message (which exists only to host usage).
+   * The per-node pure function {@link deriveMessages} folds over the surface;
+   * an external reconstructor (or the dev invariant) folds the same function
+   * over a log prefix's surface to rebuild the exact messages any request was
+   * built from (the reconstructability RFC). The returned `content` is
+   * deep-cloned off the logged event: the log is append-only by contract, so
+   * no live reference to logged data leaves this boundary.
+   * @param event - the event to project.
+   * @returns the derived message, or null when the event produces none.
    */
-  private _deriveOneMessage(event: SessionEvent): Message | null {
+  deriveEventMessage(event: SessionEvent): Message | null {
     // Intentionally non-exhaustive: only message-producing events derive
     // history; turn/step boundaries, chunks, usage, and errors are
     // trace/replay data.
@@ -311,8 +354,9 @@ export class Session {
         const { content, source } = event.data
         return { role: 'user', content: renderTagged('steering', structuredClone(content), source) }
       }
-      /* v8 ignore next 2 -- unreachable: only surface nodes (the 5 message-producing types) reach here */
       default:
+        // A non-surface event (boundary, chunk, log-only record) projects to
+        // no message. Merge-extensible union: no assertNever here.
         return null
     }
   }

packages/core/session/src/request-header.ts

@@ -0,0 +1,191 @@
+/**
+ * Request-header reconstruction utilities: the pure fold/diff/apply trio over
+ * the `request/header` / `request/header-delta` session events. Anyone
+ * holding a session log reconstructs the {@link EpochHeader} any request was
+ * built under by folding these events in log order; the loop uses the same
+ * functions to decide whether a step's header changed and to encode the
+ * change. Deltas are an encoding optimization with a safety valve — the
+ * writer round-trip-verifies every delta before appending and falls back to
+ * a full snapshot when the encoding cannot express the change — so folding
+ * never needs error recovery on a well-formed log.
+ *
+ * @module dsh-session/request-header
+ */
+
+import { callConfigEquals } from '@deepseek-ai/dsh-llm'
+import type { LlmCallConfig, ToolSchema } from '@deepseek-ai/dsh-llm'
+import type { EpochHeader, SessionEvent, SystemDelta, ToolsDelta } from './types.ts'
+
+/**
+ * Normalize a header to canonical form: an empty system prompt and an empty
+ * tool list become ABSENT fields, matching how requests are built (both
+ * request-build spreads skip empty values). Diff, fold, and comparison all
+ * operate on canonical headers, so "no system prompt" has exactly one
+ * representation.
+ * @param header - the header to normalize (not mutated).
+ * @returns the canonical header.
+ */
+export function canonicalHeader(header: EpochHeader): EpochHeader {
+  return {
+    config: header.config,
+    ...header.system !== undefined && header.system.length > 0 ? { system: header.system } : {},
+    ...header.tools !== undefined && header.tools.length > 0 ? { tools: header.tools } : {},
+  }
+}
+
+/** Split a canonical (possibly absent) system prompt into lines; absence is zero lines. */
+function systemLines(system: string | undefined): string[] {
+  return system === undefined ? [] : system.split('\n')
+}
+
+/** Join lines back into a canonical system value; zero lines is absence. */
+function joinSystem(lines: string[]): string | undefined {
+  return lines.length === 0 ? undefined : lines.join('\n')
+}
+
+/**
+ * Compute the line-level {@link SystemDelta} between two canonical system
+ * prompts: trim the common prefix and (non-overlapping) common suffix, and
+ * carry the replacement lines between them. Deterministic and library-free;
+ * with nothing shared it degenerates to a full replacement.
+ */
+function diffSystem(prev: string | undefined, next: string | undefined): SystemDelta {
+  const a = systemLines(prev)
+  const b = systemLines(next)
+  let keepStart = 0
+  while (keepStart < a.length && keepStart < b.length && a[keepStart] === b[keepStart]) keepStart += 1
+  let keepEnd = 0
+  while (
+    keepEnd < a.length - keepStart &&
+    keepEnd < b.length - keepStart &&
+    a[a.length - 1 - keepEnd] === b[b.length - 1 - keepEnd]
+  ) keepEnd += 1
+  return { keepStart, keepEnd, insert: b.slice(keepStart, b.length - keepEnd) }
+}
+
+/** Apply a {@link SystemDelta} to a canonical system prompt. */
+function applySystem(prev: string | undefined, delta: SystemDelta): string | undefined {
+  const a = systemLines(prev)
+  return joinSystem([...a.slice(0, delta.keepStart), ...delta.insert, ...a.slice(a.length - delta.keepEnd)])
+}
+
+/** Canonical JSON equality for tool schemas — sound because schemas are
+ * JSON-serializable by construction and both sides come from the same
+ * assembly path, so key insertion order matches when the values do. */
+function sameSchema(a: ToolSchema, b: ToolSchema): boolean {
+  return JSON.stringify(a) === JSON.stringify(b)
+}
+
+/**
+ * Compute the name-keyed {@link ToolsDelta} between two canonical tool lists.
+ * A pure reordering produces an empty delta — the writer's round-trip guard
+ * catches that case and records a snapshot instead.
+ */
+function diffTools(prev: readonly ToolSchema[], next: readonly ToolSchema[]): ToolsDelta {
+  const prevByName = new Map(prev.map(tool => [tool.name, tool]))
+  const nextNames = new Set(next.map(tool => tool.name))
+  return {
+    added: next.filter(tool => !prevByName.has(tool.name)),
+    removed: prev.filter(tool => !nextNames.has(tool.name)).map(tool => tool.name),
+    changed: next.filter((tool) => {
+      const before = prevByName.get(tool.name)
+      return before !== undefined && !sameSchema(before, tool)
+    }),
+  }
+}
+
+/** Apply a {@link ToolsDelta} to a canonical tool list: drop removed, replace changed in place, append added. */
+function applyTools(prev: readonly ToolSchema[], delta: ToolsDelta): ToolSchema[] {
+  const removed = new Set(delta.removed)
+  const changedByName = new Map(delta.changed.map(tool => [tool.name, tool]))
+  const kept = prev
+    .filter(tool => !removed.has(tool.name))
+    .map(tool => changedByName.get(tool.name) ?? tool)
+  return [...kept, ...delta.added]
+}
+
+/**
+ * Field-wise equality over canonical headers — the cheap comparison the
+ * writer's round-trip guard runs (`applyHeaderDelta(prev, delta)` must equal
+ * the intended header) and the loop runs to skip logging an unchanged header.
+ * Tools compare per-schema IN ORDER (canonical JSON), so a pure reordering is
+ * correctly unequal.
+ * @param a - one canonical header.
+ * @param b - the other.
+ * @returns whether config, system, and tools (in order) all match.
+ */
+export function headerEquals(a: EpochHeader, b: EpochHeader): boolean {
+  if (!callConfigEquals(a.config, b.config) || a.system !== b.system) return false
+  const at = a.tools ?? []
+  const bt = b.tools ?? []
+  return at.length === bt.length && at.every((tool, i) => sameSchema(tool, bt[i] as ToolSchema))
+}
+
+/**
+ * Compute the `request/header-delta` payload between two canonical headers,
+ * or undefined when they are equal. The caller MUST round-trip the result
+ * ({@link applyHeaderDelta} on `prev` deep-equals `next`) before logging it —
+ * the encoding cannot express every change (a pure tool reordering) — and
+ * fall back to a full `request/header` snapshot when the check fails.
+ * @param prev - the folded header the log currently implies.
+ * @param next - the header the next request will actually use.
+ * @returns the delta payload, or undefined when nothing changed.
+ */
+export function diffHeader(
+  prev: EpochHeader, next: EpochHeader,
+): { system?: SystemDelta; tools?: ToolsDelta; config?: LlmCallConfig } | undefined {
+  const delta: { system?: SystemDelta; tools?: ToolsDelta; config?: LlmCallConfig } = {}
+  if (prev.system !== next.system) delta.system = diffSystem(prev.system, next.system)
+  const prevTools = prev.tools ?? []
+  const nextTools = next.tools ?? []
+  if (JSON.stringify(prevTools) !== JSON.stringify(nextTools)) delta.tools = diffTools(prevTools, nextTools)
+  if (!callConfigEquals(prev.config, next.config)) delta.config = next.config
+  return Object.keys(delta).length > 0 ? delta : undefined
+}
+
+/**
+ * Apply a `request/header-delta` payload to a canonical header, producing the
+ * canonical header it encodes. Total for well-formed logs (the writer only
+ * appends round-trip-verified deltas).
+ * @param prev - the folded header before the delta.
+ * @param delta - the logged delta payload.
+ * @returns the canonical header after the delta.
+ */
+export function applyHeaderDelta(
+  prev: EpochHeader, delta: { system?: SystemDelta; tools?: ToolsDelta; config?: LlmCallConfig },
+): EpochHeader {
+  const system = delta.system !== undefined ? applySystem(prev.system, delta.system) : prev.system
+  const tools = delta.tools !== undefined ? applyTools(prev.tools ?? [], delta.tools) : prev.tools
+  return canonicalHeader({
+    config: delta.config ?? prev.config,
+    ...system !== undefined ? { system } : {},
+    ...tools !== undefined ? { tools } : {},
+  })
+}
+
+/**
+ * Fold the header events of a log (or any prefix of one) into the
+ * {@link EpochHeader} in force after the last of them: each
+ * `request/header` snapshot replaces the state, each `request/header-delta`
+ * amends it. The pure, offline form of reconstruction — external tooling and
+ * the dev invariant both use it; the live session tracks the same fold
+ * incrementally.
+ * @param events - session events in log order (non-header events are skipped).
+ * @param from - a previously folded state to continue from (the live session's
+ *   incremental cursor); omit to fold from nothing.
+ * @returns the folded header, or undefined when no header event exists yet.
+ */
+export function foldRequestHeader(events: readonly SessionEvent[], from?: EpochHeader): EpochHeader | undefined {
+  let state: EpochHeader | undefined = from
+  for (const event of events) {
+    if (event.type === 'request/header') {
+      state = canonicalHeader(event.data.header)
+    } else if (event.type === 'request/header-delta') {
+      if (state === undefined) {
+        throw new Error(`request/header-delta at seq ${event.seq} before any request/header snapshot: corrupt log`)
+      }
+      state = applyHeaderDelta(state, event.data)
+    }
+  }
+  return state
+}

packages/core/session/src/surface.ts

@@ -72,6 +72,9 @@ export class SurfaceManager {
   /** The last processed seq. -1 forces a full rebuild on first access. */
   private _lastProcessedSeq = -1
 
+  /** Rewrite generation — see {@link replaceGeneration}. */
+  private _replaceGeneration = 0
+
   constructor(private log: readonly SessionEvent[]) {}
 
   /**
@@ -83,6 +86,23 @@ export class SurfaceManager {
     this._lastProcessedSeq = -1
     this._nodes = []
     this._nodeBySeq.clear()
+    // A wholesale rebuild is a rewrite: bump the generation so incremental
+    // consumers (the session's derived-message cache) discard their view.
+    this._replaceGeneration += 1
+  }
+
+  /**
+   * The surface's rewrite generation: bumped by every folded `replace` op and
+   * by {@link invalidate}. A replace is the ONE operation that rewrites the
+   * surface non-monotonically, so an incremental consumer of {@link nodes}
+   * (the session's derived-message cache) compares this between visits — an
+   * unchanged generation guarantees every node it has not seen is a pure tail
+   * append; a changed one means its view must rebuild. Monotonic: it never
+   * moves backwards, so comparisons cannot be fooled by a re-fold.
+   */
+  get replaceGeneration(): number {
+    if (this._lastProcessedSeq < this.log.length - 1) this._processDelta()
+    return this._replaceGeneration
   }
 
   /** The surface nodes in linked-list order (head to tail). */
@@ -155,5 +175,6 @@ export class SurfaceManager {
     if (nextNode) nextNode.prev = newSeq
     this._nodes.splice(startIdx, 0, newNode)
     this._nodeBySeq.set(newSeq, newNode)
+    this._replaceGeneration += 1
   }
 }

packages/core/session/src/types.ts

@@ -1,5 +1,5 @@
 import type { Branded } from '@deepseek-ai/dsh-brand'
-import type { CallId, ContentBlock, MessageSource, StreamChunk, TokenUsage } from '@deepseek-ai/dsh-llm'
+import type { CallId, ContentBlock, LlmCallConfig, MessageSource, StreamChunk, TokenUsage, ToolSchema } from '@deepseek-ai/dsh-llm'
 
 /** Identifies one session in the store (and its persistence artifacts). */
 export type SessionId = Branded<'SessionId'>
@@ -176,6 +176,67 @@ export interface TodoItem {
   status: 'pending' | 'in_progress' | 'completed'
 }
 
+/**
+ * The request header: everything about an LLM request besides its message
+ * content — the call configuration plus the rendered system prompt and tool
+ * schemas. Logged session state (the reconstructability RFC): a
+ * {@link SessionEventMap} `request/header` snapshot installs one, a
+ * `request/header-delta` amends it, and folding those events over the log
+ * (`foldRequestHeader`) reconstructs the header any request was built under.
+ * Canonical form: an empty system prompt and an empty tool list are ABSENT
+ * fields, matching how requests are built.
+ */
+export interface EpochHeader {
+  /** The conversation's call configuration (model + sampling scalars). */
+  config: LlmCallConfig
+  /** Rendered system prompt text; absent for a system-less request. */
+  system?: string
+  /** Assembled tool schemas; absent for a tool-less request. */
+  tools?: ToolSchema[]
+}
+
+/**
+ * Why a `request/header` snapshot was appended: `'initial'` — the log's first
+ * header (a new conversation); `'resume'` — a loop instance's first request
+ * over a log that already has header events (process restart, fork seed);
+ * `'fallback'` — a mid-run change the delta encoding could not round-trip
+ * (e.g. a pure tool reordering), recorded whole instead.
+ */
+export type RequestHeaderReason = 'initial' | 'resume' | 'fallback'
+
+/**
+ * Line-level edit of the system prompt: keep the first `keepStart` and last
+ * `keepEnd` lines of the previous text, with `insert` replacing everything
+ * between. Computed as a common-prefix/common-suffix trim — deterministic,
+ * library-free, degenerating to a full replacement when nothing is shared.
+ * Absence is encoded as zero lines (the canonical form has no empty-string
+ * system), so a transition to or from "no system prompt" round-trips.
+ */
+export interface SystemDelta {
+  /** Lines kept from the start of the previous system prompt. */
+  keepStart: number
+  /** Lines kept from the end of the previous system prompt. */
+  keepEnd: number
+  /** Lines replacing everything between the kept edges. */
+  insert: string[]
+}
+
+/**
+ * Tool-set edit keyed by tool name (names are unique — the registry rejects
+ * duplicates): `removed` names drop, `changed` schemas replace their
+ * predecessor in place, `added` schemas append at the end. A change this
+ * encoding cannot express (a pure reordering) fails the writer's round-trip
+ * guard and is recorded as a `'fallback'` snapshot instead.
+ */
+export interface ToolsDelta {
+  /** Schemas appended to the end of the tool list. */
+  added: ToolSchema[]
+  /** Names of schemas dropped from the tool list. */
+  removed: string[]
+  /** Schemas replacing the same-named predecessor in place. */
+  changed: ToolSchema[]
+}
+
 /**
  * The session event vocabulary — the append-only source of truth for an
  * agent's whole interaction history. The LLM message history is *derived*
@@ -274,6 +335,30 @@ export interface SessionEventMap {
    * cordis-catalog row.
    */
   'todo/write': { todos: TodoItem[] }
+  /**
+   * Full snapshot of the {@link EpochHeader} the NEXT request is built under,
+   * with the {@link RequestHeaderReason} it was recorded whole. Appended by
+   * the loop inside the step, before dispatch, on a loop instance's first
+   * request-building step (`'initial'`/`'resume'`) or when a delta failed its
+   * round-trip guard (`'fallback'`); always records what the request actually
+   * used, post-`agent/request`. Anchors the header fold: reconstruction reads
+   * the latest snapshot and applies the deltas after it. NOT a
+   * {@link SurfaceEventType}: it produces no LLM message — it is the request
+   * envelope, logged so every request is a pure function of the session log
+   * (the reconstructability RFC).
+   */
+  'request/header': { header: EpochHeader; reason: RequestHeaderReason }
+  /**
+   * Amendment to the folded {@link EpochHeader}: at least one of a
+   * {@link SystemDelta}, a {@link ToolsDelta}, or a whole replacement
+   * {@link LlmCallConfig} (four scalars — not worth diffing). Appended by the
+   * loop inside the step, before dispatch, when the header for this request
+   * differs from the fold of the log so far; the writer verifies
+   * `applyHeaderDelta(previous, delta)` reproduces the new header exactly and
+   * falls back to a `'fallback'` `request/header` snapshot when it cannot, so
+   * a logged delta ALWAYS round-trips. NOT a {@link SurfaceEventType}.
+   */
+  'request/header-delta': { system?: SystemDelta; tools?: ToolsDelta; config?: LlmCallConfig }
 }
 
 export type SessionEventType = keyof SessionEventMap

packages/core/session/tests/derived-cache.spec.ts

@@ -0,0 +1,112 @@
+/**
+ * Derived-message cache tests: the session projects each surface node exactly
+ * once (O(new nodes) per call), rebuilds on a surface rewrite (replace /
+ * invalidate — the replaceGeneration signal), returns a fresh array snapshot
+ * per call over shared frozen messages, and stays deep-equal to a from-scratch
+ * replay derivation at every step — the incremental==scratch property the
+ * reconstructability RFC's invariant enforces in dev at request time.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { Session, SessionId } from '@deepseek-ai/dsh-session'
+
+function userText(session: Session, text: string): void {
+  session.append('user/message', { content: [{ type: 'text', text }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+}
+
+/** From-scratch oracle: replay the log into a fresh session and derive. */
+function scratch(session: Session): unknown {
+  return new Session(SessionId(`${session.id}-scratch-${session.seq}`), [...session.events]).deriveMessages()
+}
+
+describe('derived-message cache', () => {
+  it('stays deep-equal to a from-scratch replay derivation as the log grows', () => {
+    const session = new Session(SessionId('cache-grow'))
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    userText(session, 'one')
+    expect(session.deriveMessages()).toEqual(scratch(session))
+    userText(session, 'two')
+    session.append('assistant/message', { turn: 1, step: 1, content: [{ type: 'text', text: 'reply' }] }, { surfaceOp: 'append' })
+    expect(session.deriveMessages()).toEqual(scratch(session))
+    // An empty-content assistant/message (usage host) projects to nothing.
+    session.append('assistant/message', { turn: 1, step: 2, content: [], usage: { inputTokens: 1, outputTokens: 0 } }, { surfaceOp: 'append' })
+    expect(session.deriveMessages()).toEqual(scratch(session))
+  })
+
+  it('rebuilds on a surface replace and still matches scratch', () => {
+    const session = new Session(SessionId('cache-replace'))
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    userText(session, 'one')
+    userText(session, 'two')
+    const beforeReplace = session.deriveMessages()
+    expect(beforeReplace).toHaveLength(2)
+
+    const nodes = session.surface.nodes
+    session.append('context/message', {
+      content: [{ type: 'text', text: 'summary' }], source: { kind: 'plugin', plugin: 'compact' },
+    }, { surfaceOp: { op: 'replace', start: nodes[0]!.seq, end: nodes[1]!.seq }, sourceEventSeqs: [nodes[0]!.seq, nodes[1]!.seq] })
+
+    expect(session.deriveMessages()).toHaveLength(1)
+    expect(session.deriveMessages()).toEqual(scratch(session))
+    // The array a caller took before the replace is untouched.
+    expect(beforeReplace).toHaveLength(2)
+  })
+
+  it('returns a fresh array per call: later appends never grow a held snapshot', () => {
+    const session = new Session(SessionId('cache-snapshot'))
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    userText(session, 'one')
+    const first = session.deriveMessages()
+    userText(session, 'two')
+    const second = session.deriveMessages()
+    expect(first).toHaveLength(1)
+    expect(second).toHaveLength(2)
+    // Shared projection objects: the same frozen message instance, once ever.
+    expect(second[0]).toBe(first[0])
+    expect(Object.isFrozen(first[0])).toBe(true)
+  })
+
+  it('rebuilds after surface.invalidate() (the generation covers wholesale rebuilds too)', () => {
+    const session = new Session(SessionId('cache-invalidate'))
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    userText(session, 'one')
+    const before = session.deriveMessages()
+    session.surface.invalidate()
+    const after = session.deriveMessages()
+    expect(after).toEqual(before)
+    // A rebuild re-projects: fresh objects, same values.
+    expect(after[0]).not.toBe(before[0])
+  })
+})
+
+describe('Session.deriveEventMessage — the per-event projection', () => {
+  it('projects one appended event exactly as the full derivation projects its node', () => {
+    const session = new Session(SessionId('per-event'))
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    const event = session.append('user/message', { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+    // The fold path (deriveMessages) and the per-event path share the
+    // projection, so an external reconstructor cannot disagree with the cache.
+    expect(session.deriveEventMessage(event)).toEqual(session.deriveMessages().at(-1))
+  })
+
+  it('clones content off the log: the projection never aliases the logged event', () => {
+    const session = new Session(SessionId('per-event-clone'))
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    const event = session.append('user/message', { content: [{ type: 'text', text: 'orig' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+    const message = session.deriveEventMessage(event)!
+    expect(message.content).not.toBe(event.data.content)
+    // deriveEventMessage returns an unfrozen clone (the cache freezes ITS
+    // copies); mutating it must not reach the log.
+    ;(message.content[0] as { text: string }).text = 'mutated'
+    expect(session.deriveMessages().at(-1)!.content).toEqual([{ type: 'text', text: 'orig' }])
+  })
+
+  it('projects null for events that produce no message (boundaries, empty assistant)', () => {
+    const session = new Session(SessionId('per-event-null'))
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    const boundary = session.append('step/start', { turn: 1, step: 1 })
+    expect(session.deriveEventMessage(boundary)).toBeNull()
+    const empty = session.append('assistant/message', { turn: 1, step: 1, content: [] }, { surfaceOp: 'append' })
+    expect(session.deriveEventMessage(empty)).toBeNull()
+  })
+})

packages/core/session/tests/properties.spec.ts

@@ -109,15 +109,17 @@ describe('Session properties', () => {
     ))
   })
 
-  it('every derived message has a known role and decoupled content', () => {
+  it('every derived message has a known role and is frozen (append-only contract)', () => {
     fc.assert(fc.property(logArb, (events) => {
       const session = build(events)
       const messages = session.deriveMessages()
       const before = structuredClone(session.events)
       for (const m of messages) {
         expect(['user', 'assistant', 'system']).toContain(m.role)
-        // Mutating derived content must not touch the log (append-only).
-        m.content.push({ type: 'text', text: 'mutation' })
+        // Derived messages are frozen shared projections: mutation THROWS
+        // (strict mode) instead of relying on per-call clones for isolation.
+        expect(Object.isFrozen(m)).toBe(true)
+        expect(() => { m.content.push({ type: 'text', text: 'mutation' }) }).toThrow(TypeError)
       }
       expect(session.events).toEqual(before)
     }))

packages/core/session/tests/request-header.spec.ts

@@ -0,0 +1,140 @@
+/**
+ * Request-header utility tests: canonical form, the system line-diff
+ * (prefix/suffix trim), the name-keyed tools delta, config replacement, the
+ * round-trip contract (including the reorder case the encoding cannot
+ * express), and the log fold. These pin the reconstruction algebra: for every
+ * logged delta, apply(prev, delta) === next, and folding a log prefix yields
+ * the header its next request was built under.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { Session, SessionId, applyHeaderDelta, canonicalHeader, diffHeader, foldRequestHeader } from '@deepseek-ai/dsh-session'
+import type { EpochHeader, SessionEvent } from '@deepseek-ai/dsh-session'
+import type { ToolSchema } from '@deepseek-ai/dsh-llm'
+
+const CONFIG = { model: 'm' }
+
+function tool(name: string, description = 'd'): ToolSchema {
+  return { name, description, parameters: { type: 'object' } }
+}
+
+/** Round-trip helper: diff must reproduce `next` from `prev` exactly. */
+function roundTrip(prev: EpochHeader, next: EpochHeader): ReturnType<typeof diffHeader> {
+  const delta = diffHeader(prev, next)
+  if (delta !== undefined) {
+    expect(applyHeaderDelta(prev, delta)).toEqual(canonicalHeader(next))
+  }
+  return delta
+}
+
+describe('canonicalHeader', () => {
+  it('normalizes empty system and empty tools to absent fields', () => {
+    expect(canonicalHeader({ config: CONFIG, system: '', tools: [] })).toEqual({ config: CONFIG })
+    const full = canonicalHeader({ config: CONFIG, system: 's', tools: [tool('a')] })
+    expect(full.system).toBe('s')
+    expect(full.tools).toHaveLength(1)
+  })
+})
+
+describe('diffHeader / applyHeaderDelta', () => {
+  it('returns undefined for equal headers', () => {
+    const header = canonicalHeader({ config: CONFIG, system: 'a\nb', tools: [tool('t')] })
+    expect(diffHeader(header, header)).toBeUndefined()
+  })
+
+  it('encodes a mid-prompt line change as a prefix/suffix trim', () => {
+    const prev = canonicalHeader({ config: CONFIG, system: 'keep1\nold\nkeep2\nkeep3' })
+    const next = canonicalHeader({ config: CONFIG, system: 'keep1\nnew A\nnew B\nkeep2\nkeep3' })
+    const delta = roundTrip(prev, next)
+    expect(delta?.system).toEqual({ keepStart: 1, keepEnd: 2, insert: ['new A', 'new B'] })
+    expect(delta?.tools).toBeUndefined()
+    expect(delta?.config).toBeUndefined()
+  })
+
+  it('degenerates to a full replacement when nothing is shared, and round-trips absence transitions', () => {
+    const none = canonicalHeader({ config: CONFIG })
+    const some = canonicalHeader({ config: CONFIG, system: 'x\ny' })
+    const gained = roundTrip(none, some)
+    expect(gained?.system).toEqual({ keepStart: 0, keepEnd: 0, insert: ['x', 'y'] })
+    const lost = roundTrip(some, none)
+    expect(lost?.system).toEqual({ keepStart: 0, keepEnd: 0, insert: [] })
+  })
+
+  it('does not double-count overlapping prefix and suffix (repeated lines)', () => {
+    const prev = canonicalHeader({ config: CONFIG, system: 'a\na' })
+    const next = canonicalHeader({ config: CONFIG, system: 'a\na\na' })
+    roundTrip(prev, next)
+  })
+
+  it('encodes tool addition, removal, and in-place schema change by name', () => {
+    const prev = canonicalHeader({ config: CONFIG, tools: [tool('keep'), tool('drop'), tool('edit', 'before')] })
+    const next = canonicalHeader({ config: CONFIG, tools: [tool('keep'), tool('edit', 'after'), tool('new')] })
+    const delta = roundTrip(prev, next)
+    expect(delta?.tools?.added.map(t => t.name)).toEqual(['new'])
+    expect(delta?.tools?.removed).toEqual(['drop'])
+    expect(delta?.tools?.changed.map(t => t.name)).toEqual(['edit'])
+  })
+
+  it('round-trips a tool set gained from a tool-less header and lost back to one', () => {
+    const none = canonicalHeader({ config: CONFIG })
+    const some = canonicalHeader({ config: CONFIG, tools: [tool('t')] })
+    const gained = roundTrip(none, some)
+    expect(gained?.tools?.added.map(t => t.name)).toEqual(['t'])
+    const lost = roundTrip(some, none)
+    expect(lost?.tools?.removed).toEqual(['t'])
+  })
+
+  it('cannot express a pure reordering — the writer detects it via the round-trip check', () => {
+    const prev = canonicalHeader({ config: CONFIG, tools: [tool('a'), tool('b')] })
+    const next = canonicalHeader({ config: CONFIG, tools: [tool('b'), tool('a')] })
+    const delta = diffHeader(prev, next)
+    // A delta IS produced (the lists differ)…
+    expect(delta).toBeDefined()
+    // …but applying it cannot reproduce the new order — exactly the case the
+    // writer's guard turns into a 'fallback' snapshot.
+    expect(applyHeaderDelta(prev, delta!)).not.toEqual(next)
+  })
+
+  it('replaces the config whole and leaves untouched parts alone', () => {
+    const prev = canonicalHeader({ config: { model: 'm' }, system: 's', tools: [tool('t')] })
+    const next = canonicalHeader({ config: { model: 'm2', temperature: 0.1 }, system: 's', tools: [tool('t')] })
+    const delta = roundTrip(prev, next)
+    expect(delta).toEqual({ config: { model: 'm2', temperature: 0.1 } })
+  })
+})
+
+describe('foldRequestHeader', () => {
+  function headerEvents(session: Session): readonly SessionEvent[] {
+    return session.events
+  }
+
+  it('returns undefined on a log with no header events', () => {
+    const session = new Session(SessionId('fold-none'))
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    expect(foldRequestHeader(headerEvents(session))).toBeUndefined()
+  })
+
+  it('folds snapshot then deltas into the header in force, skipping unrelated events', () => {
+    const session = new Session(SessionId('fold'))
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    const first = canonicalHeader({ config: { model: 'm' }, system: 'a\nb', tools: [tool('t')] })
+    session.append('request/header', { header: first, reason: 'initial' })
+    session.append('user/message', { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+
+    const second = canonicalHeader({ config: { model: 'm' }, system: 'a\nc', tools: [tool('t')] })
+    session.append('request/header-delta', diffHeader(first, second)!)
+    expect(foldRequestHeader(headerEvents(session))).toEqual(second)
+
+    // A later snapshot replaces the state wholesale (the 'resume'/'fallback' anchor).
+    const third = canonicalHeader({ config: { model: 'other' } })
+    session.append('request/header', { header: third, reason: 'resume' })
+    expect(foldRequestHeader(headerEvents(session))).toEqual(third)
+  })
+
+  it('throws on a delta before any snapshot (corrupt log)', () => {
+    const session = new Session(SessionId('fold-corrupt'))
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    session.append('request/header-delta', { config: { model: 'x' } })
+    expect(() => foldRequestHeader(headerEvents(session))).toThrow(/before any request\/header snapshot/)
+  })
+})

packages/core/session/tests/session.spec.ts

@@ -80,19 +80,25 @@ describe('Session', () => {
     }, { surfaceOp: 'append' })
     const before = structuredClone(session.events)
 
-    // A request middleware / adapter mutates the messages it was handed.
+    // A misbehaving consumer tries to mutate the messages it was handed.
+    // Derived messages are frozen shared projections (cloned once off the
+    // log, then deep-frozen): every mutation attempt THROWS in strict mode —
+    // isolation by unrepresentability, not by per-call cloning.
     const messages = session.deriveMessages()
     const userBlock = messages[0]!.content[0]!
-    if (userBlock.type === 'text') userBlock.text = 'HACKED'
+    expect(() => { if (userBlock.type === 'text') userBlock.text = 'HACKED' }).toThrow(TypeError)
     const toolBlock = messages[1]!.content[0]!
-    if (toolBlock.type === 'tool-result') {
-      toolBlock.content.push({ type: 'text', text: 'injected' })
-    }
-    messages[0]!.content.push({ type: 'text', text: 'extra' })
+    expect(() => {
+      if (toolBlock.type === 'tool-result') toolBlock.content.push({ type: 'text', text: 'injected' })
+    }).toThrow(TypeError)
+    expect(() => { messages[0]!.content.push({ type: 'text', text: 'extra' }) }).toThrow(TypeError)
+    // The returned ARRAY is the caller's own snapshot, though — reordering it
+    // is the caller's business and never reaches the cache or the log.
+    messages.reverse()
 
     // The log is unchanged: deep-equal to the snapshot taken before mutation.
     expect(session.events).toEqual(before)
-    // And a fresh derivation still reflects the original content.
+    // And a fresh derivation still reflects the original content and order.
     expect(session.deriveMessages()[0]!.content).toEqual([{ type: 'text', text: 'original' }])
   })
 

packages/core/session/tests/surface.spec.ts

@@ -334,3 +334,26 @@ describe('surface type guards', () => {
     expect(isSurfaceEvent(markerless)).toBe(false)
   })
 })
+
+describe('SurfaceManager.replaceGeneration', () => {
+  it('folds the pending log delta on access and counts replaces and invalidations', () => {
+    const s = new Session(SessionId('gen'))
+    s.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    s.append('user/message', { content: [{ type: 'text', text: 'one' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+    s.append('user/message', { content: [{ type: 'text', text: 'two' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+    // Read the generation FIRST — before nodes — so the getter itself folds
+    // the pending delta rather than piggybacking on a nodes read.
+    expect(s.surface.replaceGeneration).toBe(0)
+
+    const nodes = s.surface.nodes
+    s.append('context/message', {
+      content: [{ type: 'text', text: 'summary' }], source: { kind: 'plugin', plugin: 'compact' },
+    }, { surfaceOp: { op: 'replace', start: nodes[0]!.seq, end: nodes[1]!.seq }, sourceEventSeqs: [nodes[0]!.seq, nodes[1]!.seq] })
+    expect(s.surface.replaceGeneration).toBe(1)
+
+    // invalidate() is a rewrite too: the generation moves forward (and the
+    // refold re-counts the replace), never backwards.
+    s.surface.invalidate()
+    expect(s.surface.replaceGeneration).toBeGreaterThan(1)
+  })
+})