Merge newest origin/master into token-meter-service

packages/core/session/README.md

@@ -1,6 +1,6 @@
 # dsh-session
 
-Event-sourced session log and in-memory store. A `Session` is the append-only source of truth for an agent's whole interaction history — the LLM message history is *derived* from it. A **surface** layer (a linked list of message-producing events) is maintained on top of the raw log for efficient derivation and compaction.
+Event-sourced session log and in-memory store. A `Session` is the append-only source of truth for an agent's whole interaction history — the LLM message history is *derived* from it. A **surface** layer (an ordered projection of message-producing events) is maintained on top of the raw log for efficient derivation and compaction.
 
 ## Service: `SessionStore` (ctx key: `sessions`)
 
@@ -33,7 +33,7 @@ The store pairs announced creation with disposal, publishes post-commit append n
 Plain class (not a Cordis Service). Create via `ctx.sessions.create()`.
 
 - `session.append(type, data, opts?)` snapshots and freezes durable data and surface metadata, validates marker shape, provenance, and complete replacement coverage, commits synchronously, then notifies observers with independent failure containment. Reentrant attached-session appends reject, and runtime checks cover widened unions and loaded logs.
-- `session.deriveMessages()` incrementally projects each new surface node once and returns a fresh array over shared frozen messages. Assistant projections preserve provider/model provenance and adapter-private replay state. A surface rewrite rebuilds the projection; there is no raw-log fallback.
+- `session.deriveMessages()` incrementally projects each new surface entry once and returns a fresh array over shared frozen messages. Assistant projections preserve provider/model provenance and adapter-private replay state. A surface rewrite rebuilds the projection; there is no raw-log fallback.
 - `session.deriveEventMessage(event)` is the canonical per-event projection used by reconstruction and invariants.
 - `session.surface` lazily folds only new `surfaceOp` markers; `replaceGeneration` changes on every rewrite.
 - `session.events` is a cached frozen snapshot invalidated by append; accepted events remain deeply frozen.
@@ -46,15 +46,14 @@ Durable values need one accepted representation, not a check followed by a secon
 
 ### Surface types
 
-- `SurfaceOp` — how a surface node entered the linked list: `'append'` (normal tail append) or `{ op: 'replace', start, end }` (replace nodes from `start` through `end` inclusive — both must be valid surface node seqs; `start === end` replaces a single node). Used by compaction to shadow old nodes without deleting them.
+- `SurfaceOp` — how an event entered the ordered surface: `'append'` (normal tail append) or `{ op: 'replace', start, end }` (replace entries from `start` through `end` inclusive — both must be valid surface seqs; `start === end` replaces one entry). Used by compaction to shadow old events without deleting them.
 - `SurfaceIntent` — `{ surfaceOp: SurfaceOp; sourceEventSeqs?: number[] }`, the required third parameter to `session.append()` for surface-eligible types.
-- `SurfaceNode` — `{ seq: number; prev: number | null; next: number | null }`, one node in the surface linked list.
-- `foldSurface(events)` — replay the one canonical surface contract into detached current nodes and actual replacement ranges. The same pass rejects non-contiguous event seqs, misplaced or malformed metadata, empty or duplicate provenance, non-earlier sources, invalid positional ranges, and replacements that fail to cite every shadowed surface node; `SurfaceManager` shares the atomic transition while retaining its incremental cache.
-- `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.
+- `foldSurface(events)` — replay the canonical surface contract into detached current event sequences and actual replacement ranges. The same pass rejects non-contiguous seqs, misplaced or malformed metadata, empty or duplicate provenance, non-earlier sources, invalid positional ranges, and replacements that fail to cite every shadowed surface entry; `SurfaceManager` shares the atomic transition while retaining only its incremental sequence cache.
+- `isSurfaceEvent(event)` / `isSurfaceEligibleType(type)` — the first narrows a `SessionEvent` to a fully formed surface event; the second detects a surface-eligible event missing its marker when validating a seed or loaded log.
 
 ### Request-header reconstruction (`request-header.ts`)
 
-`request/header` and `request/header-delta` make the non-history request envelope reconstructable from the log. `foldRequestHeader()` reconstructs the active header, `diffHeader()` encodes changes, and `applyHeaderDelta()` replays them; unsupported deltas fall back to a full snapshot. `messagePrefix` remains separate from derived history. See the [reconstructable-requests RFC](../../../docs/rfc/implemented/architecture/2026-07-05-reconstructable-requests.md).
+`request/header` records a full canonical snapshot of the non-history request envelope with reason `initial`, `resume`, or `change`. `foldRequestHeader()` selects the latest snapshot; legacy delta events and the removed `fallback` reason are rejected. `messagePrefix` remains separate from derived history. See the [reconstructable-requests RFC](../../../docs/rfc/implemented/architecture/2026-07-05-reconstructable-requests.md).
 
 `context/message` defaults to the canonical tagged context projection. A producer may set `envelope: 'raw'` when its `content` already contains the complete model-facing frame, and may attach JSON `meta` for replayable plugin state; metadata remains durable but is excluded from `deriveMessages()`.
 
@@ -68,7 +67,7 @@ Also defines `TurnTriggerMap` and `TurnEndReasonMap` (merge-extensible sum types
 
 Every `SessionEvent` carries two optional top-level fields (structural metadata):
 
-- `sourceEventSeqs?: number[]` — seq numbers of provenance sources (e.g., the `assistant/chunk` seqs behind an `assistant/message`, or the shadowed nodes behind a compaction replace node). On `assistant/message`, a present `[]` records a known empty provider stream, while omission means legacy or otherwise unrecorded provenance; other surface events require a non-empty list when this field is present.
+- `sourceEventSeqs?: number[]` — seq numbers of provenance sources (e.g., the `assistant/chunk` seqs behind an `assistant/message`, or the shadowed entries behind a compaction replacement entry). On `assistant/message`, a present `[]` records a known empty provider stream, while omission means legacy or otherwise unrecorded provenance; other surface events require a non-empty list when this field is present.
 - `surfaceOp?: SurfaceOp` — how this event entered the surface. Absent for non-surface events (boundaries, chunks, usage, errors).
 
 ### Metadata types (`types.ts`)
@@ -79,15 +78,15 @@ Every `SessionEvent` carries two optional top-level fields (structural metadata)
 
 - Persistence plugins: subscribe to `session/event` (write-behind) and drain on `session/flush` (awaited) and fiber dispose. A durable backend reads the log and reloads it into a live session; the metadata seam (`SessionHeader`, `session.header`) is what such a backend stores beside the log.
 - Replay/fork: `create(id, { seed })` validates and freezes a contiguous current-format log and rebuilds its surface; request headers require provider/model and assistant messages require provider/model provenance. `fork(source, boundary?, childSessionId?)` selects a completed-turn prefix and records lineage.
-- Compaction: the `dsh-compact-basic` plugin appends a `user/message` with `surfaceOp: { op: 'replace', start, end }` to shadow old surface nodes behind a summary checkpoint. Tool-pairing boundary policy and its cache belong to the [`dsh-compact` seam](../../compact/compact/README.md), while this package owns surface membership, positional links, and `replaceGeneration`.
+- Compaction: the `dsh-compact-basic` plugin appends a `user/message` with `surfaceOp: { op: 'replace', start, end }` to shadow old surface entries behind a summary checkpoint. Tool-pairing boundary policy and its cache belong to the [`dsh-compact` seam](../../compact/compact/README.md), while this package owns ordered surface membership and `replaceGeneration`.
 
 ## Model Experience
 
 ### Derived message history
 
-**What the model sees**: The model receives projections of `user/message`, `assistant/message`, and `tool/result` surface nodes verbatim. A `context/message` is a user-role message containing exactly `<context source="<source-kind>">`, its content blocks, and `</context>`; `steering/message` uses the identical `<steering source="<source-kind>">` / `</steering>` wrapper. Tool calls live inside assistant messages. Chunks, boundaries, usage, hook records, todo records, and other log-only events add no message.
+**What the model sees**: The model receives projections of `user/message`, `assistant/message`, and `tool/result` surface entries verbatim. A `context/message` is a user-role message containing exactly `<context source="<source-kind>">`, its content blocks, and `</context>`; `steering/message` uses the identical `<steering source="<source-kind>">` / `</steering>` wrapper. Tool calls live inside assistant messages. Chunks, boundaries, usage, hook records, todo records, and other log-only events add no message.
 
-**Token effect**: Appended surface nodes are resent on later steps. A `replace` surface operation removes the shadowed nodes from future inputs without deleting their raw log records.
+**Token effect**: Appended surface entries are resent on later steps. A `replace` surface operation removes the shadowed entries from future inputs without deleting their raw log records.
 
 ### Crash-repair result
 

packages/core/session/src/index.ts

@@ -22,9 +22,9 @@ export * from './types.ts'
 export { isJsonValue, snapshotJsonValue } from './json.ts'
 export type { JsonValue } from './json.ts'
 export { interruptedTurnClosers } from './repair.ts'
-export type { SurfaceFoldReplacement, SurfaceFoldResult, SurfaceNode } from './surface.ts'
+export type { SurfaceFoldReplacement, SurfaceFoldResult } from './surface.ts'
 export { foldSurface, isSurfaceEvent, isSurfaceEligibleType } from './surface.ts'
-export { applyHeaderDelta, canonicalHeader, diffHeader, foldRequestHeader, headerEquals } from './request-header.ts'
+export { canonicalHeader, foldRequestHeader, headerEquals } from './request-header.ts'
 
 declare module 'cordis' {
   interface Context {
@@ -133,6 +133,9 @@ function snapshotSessionHeader(id: SessionId, source?: SessionHeader): SessionHe
 /** Validate the fixed event envelope after one-pass JSON materialization. */
 function assertSessionEventEnvelope(value: Record<string, unknown>, index: number): asserts value is SessionEvent {
   const event = value
+  if (event['type'] === 'request/header-delta') {
+    throw new Error(`seed event at index ${index} uses unsupported legacy request/header-delta format`)
+  }
   const allowed = new Set(['type', 'seq', 'time', 'data', 'surfaceOp', 'sourceEventSeqs'])
   if (Object.keys(event).some(key => !allowed.has(key))
     || !Object.hasOwn(event, 'type') || typeof event['type'] !== 'string'
@@ -156,9 +159,6 @@ function assertCurrentLlmShape(event: Record<string, unknown>, index: number): v
     const config = typeof header === 'object' && header !== null ? (header as Record<string, unknown>)['config'] : undefined
     if (!hasProviderModel(config)) throw new Error(`seed request/header at index ${index} lacks provider/model`)
   }
-  if (event['type'] === 'request/header-delta' && record['config'] !== undefined && !hasProviderModel(record['config'])) {
-    throw new Error(`seed request/header-delta at index ${index} lacks provider/model`)
-  }
   if (event['type'] === 'assistant/message' && !hasProviderModel(record['provenance'])) {
     throw new Error(`seed assistant/message at index ${index} lacks provider/model provenance`)
   }
@@ -172,6 +172,18 @@ function hasProviderModel(value: unknown): boolean {
     && typeof pair['model'] === 'string' && pair['model'].length > 0
 }
 
+/** Reject request-header vocabulary removed with the legacy delta codec. */
+function assertSupportedRequestHeader(type: string, data: unknown, location: string): void {
+  if (type === 'request/header-delta') {
+    throw new Error(`${location} uses unsupported legacy request/header-delta format`)
+  }
+  if (type === 'request/header'
+    && data !== null && typeof data === 'object' && !Array.isArray(data)
+    && (data as Record<string, unknown>)['reason'] === 'fallback') {
+    throw new Error(`${location} uses unsupported legacy request/header reason "fallback"`)
+  }
+}
+
 type SessionCallback = (...args: unknown[]) => unknown
 
 /** Resolve one listener snapshot, including Cordis's internal dispatch checks. */
@@ -243,7 +255,7 @@ export class Session {
   private readonly surfaceValidator = new SurfaceManager(this.log)
 
   /**
-   * Derived surface — a cached linked list of message-producing events.
+   * Derived surface — a cached order of message-producing event sequences.
    * 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.
@@ -251,7 +263,7 @@ export class Session {
    */
   private _surface: SurfaceManager | undefined
 
-  /** The surface linked list over this session's event log. */
+  /** The ordered surface over this session's event log. */
   get surface(): SurfaceManager {
     if (!this._surface) this._surface = new SurfaceManager(this.log)
     return this._surface
@@ -284,6 +296,7 @@ export class Session {
           throw new Error(`seed event at index ${index} is not losslessly JSON-serializable`)
         }
         assertSessionEventEnvelope(snapshot, index)
+        assertSupportedRequestHeader(snapshot.type, snapshot.data, `seed event at index ${index}`)
         if (snapshot.seq !== index) {
           throw new Error(`seed event at index ${index} has seq ${snapshot.seq} (expected ${index}); seed must be contiguous from 0`)
         }
@@ -331,7 +344,7 @@ export class Session {
    * @param type - The event type (key of {@link SessionEventMap}).
    * @param data - The event payload; must be JSON-serializable.
    * @param opts - Surface metadata: `surfaceOp` controls how the event enters
-   *   the surface linked list; `sourceEventSeqs` records provenance (the seq
+   *   the ordered surface; `sourceEventSeqs` records provenance (the seq
    *   numbers of events this one derives from). REQUIRED for
    *   {@link SurfaceEventType} events (every message-producing event must
    *   declare how it joins the surface, the sole source of derived history) and
@@ -368,6 +381,7 @@ export class Session {
     if (dataSnapshot === undefined) {
       throw new Error(`session event "${type}" carries non-JSON-serializable data`)
     }
+    assertSupportedRequestHeader(type, dataSnapshot, `session event "${type}"`)
     const surfaceMetadataSnapshot = snapshotJsonValue(surfaceMetadata)
     if (surfaceMetadataSnapshot === undefined) {
       throw new Error(`session event "${type}" carries non-JSON-serializable surface metadata`)
@@ -439,8 +453,8 @@ export class Session {
   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
+   * Derive the LLM message history by walking the ordered sequences 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
@@ -464,11 +478,11 @@ export class Session {
       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
+    for (const seq of nodes.slice(this.derivedNodes)) {
+      // Surface sequences are built from this.log — 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.deriveEventMessage(this.log[node.seq]!)
+      const msg = this.deriveEventMessage(this.log[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.

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

@@ -1,28 +1,20 @@
 /**
- * Request-header reconstruction utilities over `request/header` snapshots and
- * `request/header-delta` events. Writers round-trip each proposed delta and use
- * a full snapshot when the encoding cannot represent the change.
+ * Request-header reconstruction utilities over full `request/header` session
+ * events. Anyone holding a session log reconstructs the {@link EpochHeader}
+ * any request was built under by taking the latest canonical snapshot; the
+ * loop uses the same equality helper to avoid logging unchanged headers.
+ *
  * @module dsh-session/request-header
  */
 
 import { callConfigEquals } from '@deepseek-ai/dsh-llm'
-import type { LlmCallConfig, Message, ToolSchema } from '@deepseek-ai/dsh-llm'
-import type { EpochHeader, SessionEvent, SystemDelta, ToolsDelta } from './types.ts'
-
-/** The `request/header-delta` payload shape: each present field amends the folded header. */
-type HeaderDelta = {
-  system?: SystemDelta
-  tools?: ToolsDelta
-  config?: LlmCallConfig
-  messagePrefix?: Message[]
-}
+import type { Message, ToolSchema } from '@deepseek-ai/dsh-llm'
+import type { EpochHeader, SessionEvent } from './types.ts'
 
 /**
- * Normalize a header to canonical form: an empty system prompt, an empty
- * tool list, and an empty session prefix become ABSENT fields, matching how
- * requests are built (the request-build spreads skip empty values). Diff,
- * fold, and comparison all operate on canonical headers, so "no system
- * prompt" (and "no session prefix") has exactly one representation.
+ * Normalize a header to canonical form: an empty system prompt, an empty tool
+ * list, and an empty session prefix become absent fields, matching how requests
+ * are built. Logging, folding, and comparison use this one representation.
  * @param header - the header to normalize (not mutated).
  * @returns the canonical header.
  */
@@ -35,85 +27,22 @@ export function canonicalHeader(header: EpochHeader): EpochHeader {
   }
 }
 
-/** 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. */
+/** Canonical JSON equality for tool schemas assembled through the same path. */
 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]
+/** Canonical JSON equality over session-prefix arrays; absence equals empty. */
+function sameMessages(a: readonly Message[] | undefined, b: readonly Message[] | undefined): boolean {
+  return JSON.stringify(a ?? []) === JSON.stringify(b ?? [])
 }
 
 /**
- * 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.
- *
+ * Field-wise equality over canonical headers. Tool schemas compare in order;
+ * the session prefix compares as canonical JSON.
  * @param a - one canonical header.
  * @param b - the other.
- * @returns whether config, system, tools (in order), and the session prefix all match.
+ * @returns whether config, system, tools, and session prefix all match.
  */
 export function headerEquals(a: EpochHeader, b: EpochHeader): boolean {
   if (!callConfigEquals(a.config, b.config) || a.system !== b.system) return false
@@ -123,74 +52,19 @@ export function headerEquals(a: EpochHeader, b: EpochHeader): boolean {
   return at.length === bt.length && at.every((tool, i) => sameSchema(tool, bt[i] as ToolSchema))
 }
 
-/** Canonical JSON equality over session-prefix arrays; absence equals the empty array. */
-function sameMessages(a: readonly Message[] | undefined, b: readonly Message[] | undefined): boolean {
-  return JSON.stringify(a ?? []) === JSON.stringify(b ?? [])
-}
-
 /**
- * Compute the `request/header-delta` payload between two canonical headers, or
- * `undefined` when they are equal. The encoding cannot represent every change,
- * including pure tool reordering, so callers must apply and compare the result
- * before logging it and fall back to a full snapshot on mismatch. The session
- * prefix is replaced whole; an empty array removes it.
- *
- * @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): HeaderDelta | undefined {
-  const delta: HeaderDelta = {}
-  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
-  if (!sameMessages(prev.messagePrefix, next.messagePrefix)) delta.messagePrefix = next.messagePrefix ?? []
-  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: HeaderDelta): 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
-  const messagePrefix = delta.messagePrefix ?? prev.messagePrefix
-  return canonicalHeader({
-    config: delta.config ?? prev.config,
-    ...system !== undefined ? { system } : {},
-    ...tools !== undefined ? { tools } : {},
-    ...messagePrefix !== undefined ? { messagePrefix } : {},
-  })
-}
-
-/**
- * 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.
- *
- * @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.
+ * Fold the header events of a log (or any prefix) into the
+ * {@link EpochHeader} in force after the last snapshot. Non-header events are
+ * skipped. This is the pure offline reconstruction path; the live session
+ * tracks the same fold incrementally.
+ * @param events - session events in log order.
+ * @param from - a previously folded state to continue from.
+ * @returns the latest canonical header, or undefined when none exists yet.
  */
 export function foldRequestHeader(events: readonly SessionEvent[], from?: EpochHeader): EpochHeader | undefined {
-  let state: EpochHeader | undefined = from
+  let state = 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)
-    }
+    if (event.type === 'request/header') state = canonicalHeader(event.data.header)
   }
   return state
 }

packages/core/session/src/surface.ts

@@ -1,19 +1,13 @@
 /**
- * Surface layer on top of the session event log: a derived, cached linked list
- * of events that produce LLM messages. Rebuilt deterministically from
- * `surfaceOp` markers in the log — the log is the source of truth; the surface
- * is a view.
+ * Surface layer on top of the session event log: an ordered view of events
+ * that produce LLM messages. The append-only log remains the source of truth.
  *
  * @module @deepseek-ai/dsh-session/surface
  */
 
 import type { SessionEvent, SurfaceEvent, SurfaceEventType, SurfaceOp } from './types.ts'
 
-/**
- * The set of event type strings that are eligible for the surface linked list.
- * Mirrors the {@link SurfaceEventType} union; kept as a runtime set so the
- * type guard can check membership without a chain of string comparisons.
- */
+/** Runtime counterpart of the message-producing event union. */
 const SURFACE_EVENT_TYPES = new Set<string>([
   'user/message',
   'assistant/message',
@@ -23,39 +17,22 @@ const SURFACE_EVENT_TYPES = new Set<string>([
 ])
 
 /**
- * Check only whether a type may enter the message surface; it does not require `surfaceOp`. This
- * detects eligible seed/load events missing their mandatory marker. Use {@link isSurfaceEvent} to
- * narrow a fully formed event whose marker is present.
- * @param type - the event type string to test.
- * @returns true when the type is one of the five message-producing types.
+ * Whether an event type can join the model-visible surface.
+ * @param type - event type to test.
+ * @returns true for one of the five message-producing event types.
  */
 export function isSurfaceEligibleType(type: string): boolean {
   return SURFACE_EVENT_TYPES.has(type)
 }
 
 /**
- * Narrow a {@link SessionEvent} to {@link SurfaceEvent}: checks that the
- * event's `type` is surface-eligible AND that `surfaceOp` is present.
- * The narrowed type has mandatory {@link SurfaceOp}.
- * @param event - the event to narrow.
- * @returns true when the event is surface-eligible and carries its `surfaceOp` marker.
+ * Narrow an event to a surface-eligible event carrying its required marker.
+ * @param event - event to test.
+ * @returns true when both the type and marker identify a surface event.
  */
 export function isSurfaceEvent(event: SessionEvent): event is SurfaceEvent {
   if (!SURFACE_EVENT_TYPES.has(event.type)) return false
-  // surfaceOp is optional on SessionEvent (even for surface-eligible types)
-  // but mandatory on SurfaceEvent — this check is the narrowing gate.
-  if ((event as SessionEvent<SurfaceEventType>).surfaceOp === undefined) return false
-  return true
-}
-
-/** One node in the surface linked list. */
-export interface SurfaceNode {
-  /** The event seq of this surface node. */
-  seq: number
-  /** The previous surface node's seq, or null if this is the head. */
-  prev: number | null
-  /** The next surface node's seq, or null if this is the tail. */
-  next: number | null
+  return (event as SessionEvent<SurfaceEventType>).surfaceOp !== undefined
 }
 
 /** One replacement operation observed while folding a session surface. */
@@ -66,22 +43,21 @@ export interface SurfaceFoldReplacement {
   start: number
   /** Declared inclusive end seq of the replaced surface range. */
   end: number
-  /** Actual surface nodes removed by the operation, in surface order. */
+  /** Actual surface entries removed by the operation, in surface order. */
   shadowedSeqs: number[]
 }
 
 /** Complete result of replaying the surface operations in a session log. */
 export interface SurfaceFoldResult {
-  /** Current surface nodes in linked-list order. */
-  nodes: SurfaceNode[]
+  /** Current surface event sequences in model-visible order. */
+  nodes: number[]
   /** Replacement operations in event order. */
   replacements: SurfaceFoldReplacement[]
 }
 
-/** Mutable state shared by the incremental manager and the full-log fold. */
+/** Mutable state shared by complete and incremental folds. */
 interface SurfaceFoldState {
-  nodes: SurfaceNode[]
-  nodeBySeq: Map<number, SurfaceNode>
+  nodes: number[]
   replaceGeneration: number
 }
 
@@ -98,12 +74,8 @@ type SurfacePlan =
   | SurfaceReplacePlan
 
 /** Create an empty surface fold state. */
-function createFoldState(replaceGeneration = 0): SurfaceFoldState {
-  return {
-    nodes: [],
-    nodeBySeq: new Map(),
-    replaceGeneration,
-  }
+function createFoldState(): SurfaceFoldState {
+  return { nodes: [], replaceGeneration: 0 }
 }
 
 /** Whether a runtime value is a non-negative safe event sequence. */
@@ -189,23 +161,21 @@ function replacementRange(
   state: SurfaceFoldState,
   op: Extract<SurfaceOp, { op: 'replace' }>,
 ): Pick<SurfaceReplacePlan, 'startIdx' | 'endIdx' | 'shadowedSeqs'> {
-  const startNode = state.nodeBySeq.get(op.start)
-  if (!startNode) {
+  const startIdx = state.nodes.indexOf(op.start)
+  if (startIdx === -1) {
     throw new Error(`surface replace: start seq ${op.start} not found in surface`)
   }
-  const endNode = state.nodeBySeq.get(op.end)
-  if (!endNode) {
+  const endIdx = state.nodes.indexOf(op.end)
+  if (endIdx === -1) {
     throw new Error(`surface replace: end seq ${op.end} not found in surface`)
   }
-  const startIdx = state.nodes.indexOf(startNode)
-  const endIdx = state.nodes.indexOf(endNode)
   if (startIdx > endIdx) {
     throw new Error(`surface replace: start seq ${op.start} (index ${startIdx}) is after end seq ${op.end} (index ${endIdx})`)
   }
   return {
     startIdx,
     endIdx,
-    shadowedSeqs: state.nodes.slice(startIdx, endIdx + 1).map(node => node.seq),
+    shadowedSeqs: state.nodes.slice(startIdx, endIdx + 1),
   }
 }
 
@@ -235,27 +205,6 @@ function planSurfaceEvent(
   }
 }
 
-/** Apply one already-validated positional replacement. */
-function replaceSurface(state: SurfaceFoldState, plan: SurfaceReplacePlan): void {
-  const { startIdx, endIdx } = plan
-
-  const removed = state.nodes.splice(startIdx, endIdx - startIdx + 1)
-  for (const node of removed) state.nodeBySeq.delete(node.seq)
-
-  const prevNode = startIdx > 0 ? state.nodes[startIdx - 1] : undefined
-  const nextNode = startIdx < state.nodes.length ? state.nodes[startIdx] : undefined
-  const newNode: SurfaceNode = {
-    seq: plan.seq,
-    prev: prevNode?.seq ?? null,
-    next: nextNode?.seq ?? null,
-  }
-  if (prevNode) prevNode.next = plan.seq
-  if (nextNode) nextNode.prev = plan.seq
-  state.nodes.splice(startIdx, 0, newNode)
-  state.nodeBySeq.set(plan.seq, newNode)
-  state.replaceGeneration += 1
-}
-
 /** Apply one event and return replacement metadata only when one occurred. */
 function applySurfaceEvent(
   state: SurfaceFoldState,
@@ -264,13 +213,10 @@ function applySurfaceEvent(
 ): SurfaceFoldReplacement | undefined {
   const plan = planSurfaceEvent(state, event, expectedSeq)
   if (plan?.kind === 'append') {
-    const tail = state.nodes.at(-1)
-    const node: SurfaceNode = { seq: plan.seq, prev: tail?.seq ?? null, next: null }
-    if (tail) tail.next = plan.seq
-    state.nodes.push(node)
-    state.nodeBySeq.set(plan.seq, node)
+    state.nodes.push(plan.seq)
   } else if (plan?.kind === 'replace') {
-    replaceSurface(state, plan)
+    state.nodes.splice(plan.startIdx, plan.endIdx - plan.startIdx + 1, plan.seq)
+    state.replaceGeneration += 1
   }
   if (plan?.kind !== 'replace') return
   return {
@@ -283,16 +229,9 @@ function applySurfaceEvent(
 
 /**
  * Replay a complete session log through the canonical surface fold.
- *
- * The returned arrays and nodes are detached snapshots. The incremental
- * {@link SurfaceManager} uses the same transition functions, so query read
- * models cannot disagree with `deriveMessages()` about replacement ranges.
  * @param events - session events in contiguous seq order.
- * @returns the current surface and every positional replacement.
- * @throws when any event violates the unified surface contract: metadata must
- * be well shaped and type-eligible, event seqs must be contiguous, provenance
- * must name unique earlier events, and a positional replacement must name and
- * cite its complete range.
+ * @returns detached current sequences and replacement history.
+ * @throws when an event violates surface metadata, provenance, or range rules.
  */
 export function foldSurface(events: readonly SessionEvent[]): SurfaceFoldResult {
   const state = createFoldState()
@@ -301,68 +240,44 @@ export function foldSurface(events: readonly SessionEvent[]): SurfaceFoldResult
     const replacement = applySurfaceEvent(state, event, index)
     if (replacement !== undefined) replacements.push(replacement)
   }
-  return {
-    nodes: state.nodes.map(node => ({ ...node })),
-    replacements,
-  }
+  return { nodes: [...state.nodes], replacements }
 }
 
-/**
- * Maintains a cached linked list of surface nodes and validates each candidate
- * before it enters the event log. Because the log is append-only, it processes
- * only committed deltas and plans the candidate without mutation rather than
- * rescanning the whole log.
- */
+/** Incremental ordered surface view and append-boundary validator. */
 export class SurfaceManager {
-  /** Incremental state shared with the complete surface fold. */
+  /** Shared transition state; replacement history is not retained. */
   private _state = createFoldState()
-  /** The last processed seq. -1 folds the seeded log on first access. */
+  /** Last processed seq; -1 folds a seeded log on first access. */
   private _lastProcessedSeq = -1
 
   constructor(private log: readonly SessionEvent[]) {}
 
   /**
-   * Validate one candidate as the next log event without applying it. The
-   * committed log is folded first, then the candidate's complete surface and
-   * provenance transition is planned atomically; a failure leaves the current
-   * surface unchanged.
-   * @param event - candidate event that has not entered `log` yet.
+   * Validate the next candidate without mutating the committed surface.
+   * @param event - candidate event that has not entered the log yet.
    */
   validateNext(event: SessionEvent): void {
     if (this._lastProcessedSeq < this.log.length - 1) this._processDelta()
     planSurfaceEvent(this._state, event, this.log.length)
   }
 
-  /**
-   * The surface's rewrite generation, bumped by every folded `replace` op.
-   * 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.
-   */
+  /** Monotonic count of folded positional replacements. */
   get replaceGeneration(): number {
     if (this._lastProcessedSeq < this.log.length - 1) this._processDelta()
     return this._state.replaceGeneration
   }
 
-  /** The surface nodes in linked-list order (head to tail). */
-  get nodes(): readonly SurfaceNode[] {
+  /** Surface event sequences in model-visible order. */
+  get nodes(): readonly number[] {
     if (this._lastProcessedSeq < this.log.length - 1) this._processDelta()
     return this._state.nodes
   }
 
-  /**
-   * Process events from `_lastProcessedSeq + 1` through the end of the log,
-   * folding new surface markers into the existing linked list.
-   */
+  /** Fold events appended since the previous access. */
   private _processDelta(): void {
     for (let i = this._lastProcessedSeq + 1; i < this.log.length; i++) {
-      // Index is bounded by i < this.log.length — never undefined.
-      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-      const event = this.log[i]!
-      applySurfaceEvent(this._state, event, i)
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- bounded by the loop condition
+      applySurfaceEvent(this._state, this.log[i]!, i)
       this._lastProcessedSeq = i
     }
   }

packages/core/session/src/types.ts

@@ -143,7 +143,7 @@ export interface TodoItem {
 
 /**
  * Logged request state outside derived history: call config, system prompt,
- * tools, and session prefix. Header snapshots and deltas reconstruct it;
+ * tools, and prefix. The latest full `request/header` snapshot reconstructs it;
  * canonical empty optional fields are absent.
  */
 export interface EpochHeader {
@@ -167,43 +167,9 @@ export interface EpochHeader {
  * 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.
+ * `'change'` — a later request used a different header.
  */
-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[]
-}
+export type RequestHeaderReason = 'initial' | 'resume' | 'change'
 
 /**
  * The merge-extensible, append-only source of truth for an agent interaction.
@@ -276,22 +242,13 @@ export interface SessionEventMap {
   'tool/result': { turn: number; step: number; callId: CallId; content: ContentBlock[]; isError: boolean; error?: { name: string; code: string }; meta?: unknown }
   /** Steering content injected between steps of a running turn. */
   'steering/message': { turn: number; content: ContentBlock[]; source: MessageSource }
-  /**
-   * Whole-list snapshot; the latest write wins on replay. It is log-only UI
-   * state and never enters derived model history.
-   */
+  /** Whole-list snapshot; latest write wins on replay. Log-only UI state; never derived history. */
   'todo/write': { todos: TodoItem[] }
   /**
-   * Full {@link EpochHeader} for the next request, appended inside its step
-   * before dispatch. It is log-only and anchors subsequent deltas.
+   * Full header for the next request, appended inside its step before dispatch.
+   * It is log-only; the latest snapshot reconstructs the request header.
    */
   'request/header': { header: EpochHeader; reason: RequestHeaderReason }
-  /**
-   * Log-only amendment to the folded {@link EpochHeader}. System and tools use
-   * their delta codecs; config and prefix replace whole, with an empty prefix
-   * encoding removal. Writers verify round-trip equality or log a fallback snapshot.
-   */
-  'request/header-delta': { system?: SystemDelta; tools?: ToolsDelta; config?: LlmCallConfig; messagePrefix?: Message[] }
 }
 
 /** The appendable event-type keys of {@link SessionEventMap}, plugin-merged extensions included. */
@@ -299,7 +256,7 @@ export type SessionEventType = keyof SessionEventMap
 
 /**
  * The subset of {@link SessionEventType} values whose events produce LLM
- * messages and are eligible to appear on the surface linked list. Only these
+ * messages and are eligible to appear on the ordered surface. Only these
  * event types may carry {@link SurfaceOp} and {@link SessionEvent.sourceEventSeqs}.
  */
 export type SurfaceEventType =
@@ -310,7 +267,7 @@ export type SurfaceEventType =
   | 'steering/message'
 
 /**
- * A {@link SessionEvent} that is **on** the surface linked list — its
+ * A {@link SessionEvent} that is **on** the ordered surface — its
  * `surfaceOp` is guaranteed present (mandatory), narrowed from a
  * surface-eligible {@link SessionEvent} by checking both `type` and
  * `surfaceOp` at runtime.
@@ -321,7 +278,7 @@ export type SurfaceEventType =
 export type SurfaceEvent = SessionEvent<SurfaceEventType> & { surfaceOp: SurfaceOp }
 
 /**
- * How a session event entered the surface linked list. Only valid on
+ * How a session event entered the ordered surface. Only valid on
  * {@link SurfaceEventType} events.
  *
  * - `'append'`: added to the tail — normal path for user/assistant/tool/context

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

@@ -40,7 +40,7 @@ describe('derived-message cache', () => {
     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] })
+    }, { surfaceOp: { op: 'replace', start: nodes[0]!, end: nodes[1]! }, sourceEventSeqs: [nodes[0]!, nodes[1]!] })
 
     expect(session.deriveMessages()).toHaveLength(1)
     expect(session.deriveMessages()).toEqual(scratch(session))

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

@@ -1,14 +1,7 @@
-/**
- * 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.
- */
+/** Request-header canonicalization, equality, snapshot folding, and format rejection. */
 
 import { describe, expect, it } from 'vitest'
-import { Session, SessionId, applyHeaderDelta, canonicalHeader, diffHeader, foldRequestHeader, headerEquals } from '@deepseek-ai/dsh-session'
+import { Session, SessionId, canonicalHeader, foldRequestHeader, headerEquals } from '@deepseek-ai/dsh-session'
 import type { EpochHeader, SessionEvent } from '@deepseek-ai/dsh-session'
 import type { Message, ToolSchema } from '@deepseek-ai/dsh-llm'
 
@@ -22,165 +15,77 @@ function msg(text: string): Message {
   return { role: 'user', content: [{ type: 'text', text }] }
 }
 
-/** 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)
+  it('normalizes empty optional fields to absence and preserves populated fields', () => {
+    expect(canonicalHeader({ config: CONFIG, system: '', tools: [], messagePrefix: [] })).toEqual({ config: CONFIG })
+    const full = canonicalHeader({ config: CONFIG, system: 's', tools: [tool('a')], messagePrefix: [msg('p')] })
+    expect(full).toEqual({ config: CONFIG, system: 's', tools: [tool('a')], messagePrefix: [msg('p')] })
   })
 })
 
-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()
+describe('headerEquals', () => {
+  const base = canonicalHeader({ config: CONFIG, system: 's', tools: [tool('a')], messagePrefix: [msg('p')] })
+
+  it('compares every canonical field and preserves tool order', () => {
+    expect(headerEquals(base, structuredClone(base))).toBe(true)
+    expect(headerEquals(base, { ...base, config: { provider: 'mock', model: 'other' } })).toBe(false)
+    expect(headerEquals(base, { ...base, system: 'other' })).toBe(false)
+    expect(headerEquals(base, { ...base, messagePrefix: [msg('other')] })).toBe(false)
+    expect(headerEquals(base, { ...base, tools: [] })).toBe(false)
+    expect(headerEquals(base, { ...base, tools: [tool('a', 'changed')] })).toBe(false)
+    expect(headerEquals({ config: CONFIG, tools: [tool('a'), tool('b')] }, { config: CONFIG, tools: [tool('b'), tool('a')] })).toBe(false)
   })
 
-  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: { provider: 'mock', model: 'm' }, system: 's', tools: [tool('t')] })
-    const next = canonicalHeader({ config: { provider: 'mock', model: 'm2', temperature: 0.1 }, system: 's', tools: [tool('t')] })
-    const delta = roundTrip(prev, next)
-    expect(delta).toEqual({ config: { provider: 'mock', model: 'm2', temperature: 0.1 } })
-  })
-})
-
-describe('the session prefix (messagePrefix)', () => {
-  it('canonicalHeader normalizes an empty prefix to an absent field', () => {
-    expect(canonicalHeader({ config: CONFIG, messagePrefix: [] })).toEqual({ config: CONFIG })
-    const full = canonicalHeader({ config: CONFIG, messagePrefix: [msg('p')] })
-    expect(full.messagePrefix).toEqual([msg('p')])
-  })
-
-  it('headerEquals treats absence and empty as one representation, content differences as unequal', () => {
-    expect(headerEquals(canonicalHeader({ config: CONFIG }), { config: CONFIG, messagePrefix: [] })).toBe(true)
-    expect(headerEquals({ config: CONFIG, messagePrefix: [msg('a')] }, { config: CONFIG, messagePrefix: [msg('b')] })).toBe(false)
-    expect(headerEquals({ config: CONFIG, messagePrefix: [msg('a')] }, { config: CONFIG })).toBe(false)
-  })
-
-  it('replaces a changed prefix whole and leaves untouched parts alone', () => {
-    const prev = canonicalHeader({ config: CONFIG, system: 'keep', messagePrefix: [msg('old')] })
-    const next = canonicalHeader({ config: CONFIG, system: 'keep', messagePrefix: [msg('new'), msg('more')] })
-    const delta = roundTrip(prev, next)
-    expect(delta).toEqual({ messagePrefix: [msg('new'), msg('more')] })
-  })
-
-  it('round-trips a prefix gained from a bare header and lost back to one (empty array encodes absence)', () => {
-    const none = canonicalHeader({ config: CONFIG })
-    const some = canonicalHeader({ config: CONFIG, messagePrefix: [msg('p')] })
-    const gained = roundTrip(none, some)
-    expect(gained).toEqual({ messagePrefix: [msg('p')] })
-    const lost = roundTrip(some, none)
-    expect(lost).toEqual({ messagePrefix: [] })
-  })
-
-  it('folds prefix deltas over the log like any other header amendment', () => {
-    const session = new Session(SessionId('fold-prefix'))
-    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
-    const first = canonicalHeader({ config: CONFIG, messagePrefix: [msg('catalog v1')] })
-    session.append('request/header', { header: first, reason: 'initial' })
-    const second = canonicalHeader({ config: CONFIG, messagePrefix: [msg('catalog v2')] })
-    session.append('request/header-delta', diffHeader(first, second)!)
-    expect(foldRequestHeader(session.events)).toEqual(second)
-    session.append('request/header-delta', diffHeader(second, canonicalHeader({ config: CONFIG }))!)
-    expect(foldRequestHeader(session.events)).toEqual({ config: CONFIG })
+  it('treats absent and empty prefix/tool arrays as equivalent canonical absence', () => {
+    expect(headerEquals({ config: CONFIG }, { config: CONFIG, tools: [], messagePrefix: [] })).toBe(true)
   })
 })
 
 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('returns the supplied baseline when no snapshot follows', () => {
+    const from: EpochHeader = { config: CONFIG, system: 'baseline' }
+    const unrelated: SessionEvent[] = [
+      { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
+    ]
+    expect(foldRequestHeader(unrelated)).toBeUndefined()
+    expect(foldRequestHeader(unrelated, from)).toBe(from)
   })
 
-  it('folds snapshot then deltas into the header in force, skipping unrelated events', () => {
+  it('takes the latest full snapshot and skips unrelated events', () => {
     const session = new Session(SessionId('fold'))
     session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
-    const first = canonicalHeader({ config: { provider: 'mock', model: 'm' }, system: 'a\nb', tools: [tool('t')] })
-    session.append('request/header', { header: first, reason: 'initial' })
+    session.append('request/header', { header: { config: CONFIG, system: 'first' }, reason: 'initial' })
     session.append('user/message', { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
-
-    const second = canonicalHeader({ config: { provider: 'mock', 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: { provider: 'mock', 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: { provider: 'mock', model: 'x' } })
-    expect(() => foldRequestHeader(headerEvents(session))).toThrow(/before any request\/header snapshot/)
+    session.append('request/header', { header: { config: { provider: 'mock', model: 'other' }, tools: [] }, reason: 'change' })
+    expect(foldRequestHeader(session.events)).toEqual({ config: { provider: 'mock', model: 'other' } })
+  })
+})
+
+describe('legacy request-header format', () => {
+  it('rejects request/header-delta in seeds and untyped appends', () => {
+    const legacy = [{
+      type: 'request/header-delta', seq: 0, time: 1, data: { config: CONFIG },
+    }] as unknown as SessionEvent[]
+    expect(() => new Session(SessionId('legacy'), legacy)).toThrow(/unsupported legacy request\/header-delta/)
+
+    const session = new Session(SessionId('legacy-append-delta'))
+    const appendLegacy = session.append.bind(session) as (type: string, data: unknown) => SessionEvent
+    expect(() => appendLegacy('request/header-delta', { config: CONFIG }))
+      .toThrow(/unsupported legacy request\/header-delta/)
+    expect(session.events).toHaveLength(0)
+  })
+
+  it('rejects the removed fallback reason in seeds and untyped appends', () => {
+    const legacy = [{
+      type: 'request/header', seq: 0, time: 1, data: { header: { config: CONFIG }, reason: 'fallback' },
+    }] as unknown as SessionEvent[]
+    expect(() => new Session(SessionId('legacy-seed-reason'), legacy))
+      .toThrow('unsupported legacy request/header reason "fallback"')
+
+    const session = new Session(SessionId('legacy-append-reason'))
+    const appendLegacy = session.append.bind(session) as (type: string, data: unknown) => SessionEvent
+    expect(() => appendLegacy('request/header', { header: { config: CONFIG }, reason: 'fallback' }))
+      .toThrow('unsupported legacy request/header reason "fallback"')
+    expect(session.events).toHaveLength(0)
   })
 })

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

@@ -101,13 +101,6 @@ describe('Session', () => {
     expect(() => new Session(SessionId('old-header'), [requestHeader]))
       .toThrow('seed request/header at index 0 lacks provider/model')
 
-    const requestDelta = {
-      type: 'request/header-delta', seq: 0, time: 1,
-      data: { config: { model: 'old-model' } },
-    } as unknown as SessionEvent
-    expect(() => new Session(SessionId('old-delta'), [requestDelta]))
-      .toThrow('seed request/header-delta at index 0 lacks provider/model')
-
     const assistantMessage = {
       type: 'assistant/message', seq: 0, time: 1,
       data: { turn: 1, step: 1, content: [{ type: 'text', text: 'old' }] },
@@ -1244,8 +1237,8 @@ describe('todo/write event', () => {
     session.append('todo/write', { todos: [{ content: 'a task', status: 'pending' }] })
     // The todo event must not add a message to the derived history…
     expect(session.deriveMessages()).toHaveLength(before)
-    // …and must not appear on the surface linked list.
-    expect(session.surface.nodes.some(node => node.seq === session.seq - 1)).toBe(false)
+    // …and must not appear on the ordered surface.
+    expect(session.surface.nodes).not.toContain(session.seq - 1)
   })
 
   it('round-trips through a seeded replay identically (durable, no surfaceOp needed)', () => {

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

@@ -95,7 +95,7 @@ describe('foldSurface provenance', () => {
 })
 
 describe('SurfaceManager', () => {
-  it('shares exact nodes and nested replacement ranges with foldSurface', () => {
+  it('shares ordered entries and nested replacement ranges with foldSurface', () => {
     const s = new Session(SessionId('shared-fold'))
     s.append('user/message', { content: [{ type: 'text', text: 'a' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
     s.append('user/message', { content: [{ type: 'text', text: 'b' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
@@ -108,9 +108,10 @@ describe('SurfaceManager', () => {
       { seq: 2, start: 0, end: 0, shadowedSeqs: [0] },
       { seq: 3, start: 2, end: 1, shadowedSeqs: [2, 1] },
     ])
-    folded.nodes[0]!.next = 99
+    folded.nodes[0] = 99
     folded.replacements[0]!.shadowedSeqs.push(99)
-    expect(s.surface.nodes).toEqual([{ seq: 3, prev: null, next: null }])
+    expect(s.surface.nodes).toEqual([3])
+    expect(foldSurface(s.events).nodes).toEqual([3])
     expect(foldSurface(s.events).replacements[0]!.shadowedSeqs).toEqual([0])
   })
 
@@ -119,7 +120,7 @@ describe('SurfaceManager', () => {
     s.append('user/message', { content: [{ type: 'text', text: 'a' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
     s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'text', text: 'b' }] }, { surfaceOp: { op: 'replace', start: 0, end: 0 }, sourceEventSeqs: [0] })
 
-    expect(s.surface.nodes).toEqual([{ seq: 1, prev: null, next: null }])
+    expect(s.surface.nodes).toEqual([1])
     const manager = s.surface as unknown as { _state: object }
     expect(Object.hasOwn(manager._state, 'replacements')).toBe(false)
     expect(foldSurface(s.events).replacements).toEqual([
@@ -150,7 +151,7 @@ describe('SurfaceManager', () => {
 
     expect(s.events).toHaveLength(1)
     s.append('user/message', { content: [{ type: 'text', text: 'b' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
-    expect(s.surface.nodes.map(node => node.seq)).toEqual([0, 1])
+    expect(s.surface.nodes).toEqual([0, 1])
   })
 
   it('foldSurface rejects a surface-eligible event without its mandatory marker', () => {
@@ -178,18 +179,12 @@ describe('SurfaceManager', () => {
       .toThrow(/not surface-eligible and cannot carry surfaceOp/)
   })
 
-  it('rebuilds a linked list from surfaceOp: append markers', () => {
+  it('folds an ordered sequence list from surfaceOp: append markers', () => {
     const s = surfaceSession()
     const nodes = s.surface.nodes
     // Only the user/message and assistant/message carry surfaceOp: 'append'.
     // The turn boundaries do not have surface markers.
-    expect(nodes.length).toBe(2)
-    expect(nodes[0]!.seq).toBe(1) // user/message (turn/start is seq 0)
-    expect(nodes[0]!.prev).toBeNull()
-    expect(nodes[0]!.next).toBe(2) // assistant/message (seq 2)
-    expect(nodes[1]!.seq).toBe(2)
-    expect(nodes[1]!.prev).toBe(1)
-    expect(nodes[1]!.next).toBeNull()
+    expect(nodes).toEqual([1, 2])
   })
 
   it('empty surface yields empty nodes', () => {
@@ -210,9 +205,7 @@ describe('SurfaceManager', () => {
     // Append another surface node
     s.append('tool/result', { turn: 1, step: 1, callId: CallId('c1'), content: [{ type: 'text', text: 'ok' }], isError: false }, { surfaceOp: 'append' })
     expect(s.surface.nodes.length).toBe(3)
-    expect(s.surface.nodes[2]!.seq).toBe(4) // seq 4: after turn/end at seq 3
-    expect(s.surface.nodes[2]!.prev).toBe(2)
-    expect(s.surface.nodes[1]!.next).toBe(4)
+    expect(s.surface.nodes[2]!).toBe(4) // seq 4: after turn/end at seq 3
   })
 
   it('replays identically from a seeded log with surface markers', () => {
@@ -220,21 +213,17 @@ describe('SurfaceManager', () => {
     original.append('tool/result', { turn: 1, step: 1, callId: CallId('c1'), content: [{ type: 'text', text: 'ok' }], isError: false }, { surfaceOp: 'append' })
     const replayed = new Session(SessionId('replay'), [...original.events])
     // Surface rebuilds from the seeded log's markers.
-    expect(replayed.surface.nodes.map(n => n.seq)).toEqual([1, 2, 4])
+    expect(replayed.surface.nodes).toEqual([1, 2, 4])
     expect(replayed.deriveMessages()).toEqual(original.deriveMessages())
   })
 
   it('rebuild with replace operation splices out shadowed nodes', () => {
     const s = surfaceSession()
-    // Replace surface seqs 1 (user) and 2 (assistant) with the summary.
     s.append('assistant/message',
       { provenance: { provider: 'mock', model: 'mock' }, turn: 2, step: 1, content: [{ type: 'text', text: 'summary' }] },
       { surfaceOp: { op: 'replace', start: 1, end: 2 }, sourceEventSeqs: [1, 2] },
     )
-    expect(s.surface.nodes.length).toBe(1)
-    expect(s.surface.nodes[0]!.seq).toBe(4) // seq of the compaction marker
-    expect(s.surface.nodes[0]!.prev).toBeNull()
-    expect(s.surface.nodes[0]!.next).toBeNull()
+    expect(s.surface.nodes).toEqual([4])
   })
 
   it('replace with both ends at real nodes splices only the range', () => {
@@ -247,12 +236,7 @@ describe('SurfaceManager', () => {
       { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'text', text: 'summary' }] },
       { surfaceOp: { op: 'replace', start: 0, end: 1 }, sourceEventSeqs: [0, 1] },
     ) // seq 3
-    expect(s.surface.nodes.map(n => n.seq)).toEqual([3, 2])
-    // Links: 3 ↔ 2
-    expect(s.surface.nodes[0]!.prev).toBeNull()
-    expect(s.surface.nodes[0]!.next).toBe(2)
-    expect(s.surface.nodes[1]!.prev).toBe(3)
-    expect(s.surface.nodes[1]!.next).toBeNull()
+    expect(s.surface.nodes).toEqual([3, 2])
   })
 
   it('single-node replacement (start === end)', () => {
@@ -264,9 +248,7 @@ describe('SurfaceManager', () => {
       { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'text', text: 'x' }] },
       { surfaceOp: { op: 'replace', start: 1, end: 1 }, sourceEventSeqs: [1] },
     ) // seq 2
-    expect(s.surface.nodes.map(n => n.seq)).toEqual([0, 2])
-    expect(s.surface.nodes[0]!.next).toBe(2)
-    expect(s.surface.nodes[1]!.prev).toBe(0)
+    expect(s.surface.nodes).toEqual([0, 2])
   })
 
   it('throws when replace start is not found', () => {
@@ -310,7 +292,7 @@ describe('SurfaceManager', () => {
     expect(logged.sourceEventSeqs).toEqual([0])
   })
 
-  it('replace starting at non-head position links to previous node correctly', () => {
+  it('replace starting at non-head position preserves surrounding order', () => {
     const s = new Session(SessionId('mid-replace'))
     s.append('user/message', { content: [{ type: 'text', text: 'a' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) // seq 0
     s.append('user/message', { content: [{ type: 'text', text: 'b' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) // seq 1
@@ -320,14 +302,7 @@ describe('SurfaceManager', () => {
       { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'text', text: 'x' }] },
       { surfaceOp: { op: 'replace', start: 1, end: 1 }, sourceEventSeqs: [1] },
     ) // seq 3
-    expect(s.surface.nodes.map(n => n.seq)).toEqual([0, 3, 2])
-    // Links: 0 → 3 → 2
-    expect(s.surface.nodes[0]!.prev).toBeNull()
-    expect(s.surface.nodes[0]!.next).toBe(3)
-    expect(s.surface.nodes[1]!.prev).toBe(0)
-    expect(s.surface.nodes[1]!.next).toBe(2)
-    expect(s.surface.nodes[2]!.prev).toBe(3)
-    expect(s.surface.nodes[2]!.next).toBeNull()
+    expect(s.surface.nodes).toEqual([0, 3, 2])
   })
 
   it('surfaceOp replace object is snapshot so caller mutation is isolated', () => {
@@ -501,7 +476,7 @@ describe('SurfaceManager.replaceGeneration', () => {
     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] })
+    }, { surfaceOp: { op: 'replace', start: nodes[0]!, end: nodes[1]! }, sourceEventSeqs: [nodes[0]!, nodes[1]!] })
     expect(s.surface.replaceGeneration).toBe(1)
   })
 })