Merge branch 'codex/simp-session-dead-surface' into codex/simp-session-log-representation

# Conflicts: # docs/core-data-structures/session.md # docs/rfc/implemented/feature/2026-07-06-sandbox.md # examples/acp-agent/tests/snapshots/permission-switching/system-prompt.golden.md # examples/sandbox-acp-agent/tests/acp.snapshot.ts # examples/sandbox-acp-agent/tests/snapshots/mode-switching/session.jsonl # packages/core/session/README.md # packages/core/session/src/index.ts # packages/core/session/src/surface.ts # packages/core/session/tests/surface.spec.ts # scripts/type-equiv.manifest.json
2026-07-14 11:49:46 +08:00
parent b35d66b86d 34fe20962f
commit 4d5fb2cb1d
164 changed files with 3273 additions and 1694 deletions
--- a/packages/core/session/src/index.ts
+++ b/packages/core/session/src/index.ts
@@ -22,7 +22,8 @@ export * from './types.ts'
 export { isJsonValue, snapshotJsonValue } from './json.ts'
 export type { JsonValue } from './json.ts'
 export { interruptedTurnClosers } from './repair.ts'
-export { isSurfaceEvent, isSurfaceEligibleType } from './surface.ts'
+export type { SurfaceFoldReplacement, SurfaceFoldResult } from './surface.ts'
+export { foldSurface, isSurfaceEvent, isSurfaceEligibleType } from './surface.ts'
 export { isToolPairingBalanced } from './tool-pairing.ts'
 export { canonicalHeader, foldRequestHeader, headerEquals } from './request-header.ts'

--- a/packages/core/session/src/surface.ts
+++ b/packages/core/session/src/surface.ts
@@ -1,19 +1,13 @@
 /**
- * Surface layer on top of the session event log: a derived, cached sequence
- * list of events that produce LLM messages. Folded 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 sequence.
- * 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,115 +17,144 @@ const SURFACE_EVENT_TYPES = new Set<string>([
 ])

 /**
- * Whether an event's `type` is surface-eligible (one of the five
- * message-producing {@link SurfaceEventType} values). This is the TYPE check
- * only — it does NOT require `surfaceOp` to be present. Use it to detect a
- * surface-eligible event that is MISSING its mandatory marker (e.g. validating
- * a seed/load log); use {@link isSurfaceEvent} to narrow to a fully-formed
- * {@link SurfaceEvent} with `surfaceOp` 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
+  return (event as SessionEvent<SurfaceEventType>).surfaceOp !== undefined
+}
+
+/** One replacement operation observed while folding a session surface. */
+export interface SurfaceFoldReplacement {
+  /** Seq of the event that replaced the prior surface range. */
+  seq: number
+  /** Declared inclusive start seq of the replaced surface range. */
+  start: number
+  /** Declared inclusive end seq of the replaced surface range. */
+  end: number
+  /** 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 event sequences in model-visible order. */
+  nodes: number[]
+  /** Replacement operations in event order. */
+  replacements: SurfaceFoldReplacement[]
+}
+
+/** Mutable state shared by complete and incremental folds. */
+interface SurfaceFoldState {
+  nodes: number[]
+  replaceGeneration: number
+}
+
+/** Create one empty fold state. */
+function createFoldState(): SurfaceFoldState {
+  return { nodes: [], replaceGeneration: 0 }
+}
+
+/** Apply one event and return replacement metadata when one occurred. */
+function applySurfaceEvent(
+  state: SurfaceFoldState,
+  event: SessionEvent,
+): SurfaceFoldReplacement | undefined {
+  if (!isSurfaceEligibleType(event.type)) return
+  if (!isSurfaceEvent(event)) {
+    throw new Error(`surface event "${event.type}" (seq ${event.seq}) carries no surfaceOp marker`)
+  }
+  if (event.surfaceOp === 'append') {
+    state.nodes.push(event.seq)
+    return
+  }
+
+  const shadowedSeqs = replaceSurface(state, event.seq, event.surfaceOp)
+  return {
+    seq: event.seq,
+    start: event.surfaceOp.start,
+    end: event.surfaceOp.end,
+    shadowedSeqs,
+  }
+}
+
+/** Replace one inclusive surface range and return the removed sequences. */
+function replaceSurface(
+  state: SurfaceFoldState,
+  newSeq: number,
+  op: Extract<SurfaceOp, { op: 'replace' }>,
+): number[] {
+  const startIdx = state.nodes.indexOf(op.start)
+  if (startIdx === -1) {
+    throw new Error(`surface replace: start seq ${op.start} not found in surface`)
+  }
+  const endIdx = state.nodes.indexOf(op.end)
+  if (endIdx === -1) {
+    throw new Error(`surface replace: end seq ${op.end} not found in surface`)
+  }
+  if (startIdx > endIdx) {
+    throw new Error(`surface replace: start seq ${op.start} (index ${startIdx}) is after end seq ${op.end} (index ${endIdx})`)
+  }
+
+  const shadowedSeqs = state.nodes.splice(startIdx, endIdx - startIdx + 1, newSeq)
+  state.replaceGeneration += 1
+  return shadowedSeqs
 }

 /**
- * Maintains a cached ordered list of surface event sequences, folded lazily from
- * `surfaceOp` markers in the event log. Because the log is append-only, it
- * processes only the delta since the last rebuild — new events are folded
- * into the existing surface in O(new events) rather than rescanning the
- * whole log.
+ * Replay a complete event log through the canonical surface fold.
+ * @param events - events in contiguous seq order.
+ * @returns detached current sequences and replacement history.
+ * @throws when a surface marker is missing or names an invalid range.
 */
-export class SurfaceManager {
-  /** Surface event sequences in head-to-tail order. Empty until first access. */
-  private _nodes: number[] = []
-  /** The last processed seq. -1 folds the seeded log on first access. */
-  private _lastProcessedSeq = -1
+export function foldSurface(events: readonly SessionEvent[]): SurfaceFoldResult {
+  const state = createFoldState()
+  const replacements: SurfaceFoldReplacement[] = []
+  for (const event of events) {
+    const replacement = applySurfaceEvent(state, event)
+    if (replacement !== undefined) replacements.push(replacement)
+  }
+  return { nodes: [...state.nodes], replacements }
+}

-  /** Rewrite generation — see {@link replaceGeneration}. */
-  private _replaceGeneration = 0
+/** Incremental ordered surface view over an append-only session log. */
+export class SurfaceManager {
+  /** Shared transition state; replacement history is not retained. */
+  private _state = createFoldState()
+  /** Last processed seq; -1 folds a seeded log on first access. */
+  private _lastProcessedSeq = -1

  constructor(private log: readonly SessionEvent[]) {}

-  /**
-   * 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._replaceGeneration
+    return this._state.replaceGeneration
  }

-  /** Surface event sequences in head-to-tail order. */
+  /** Surface event sequences in model-visible order. */
  get nodes(): readonly number[] {
    if (this._lastProcessedSeq < this.log.length - 1) this._processDelta()
-    return this._nodes
+    return this._state.nodes
  }

-  /**
-   * Process events from `_lastProcessedSeq + 1` through the end of the log,
-   * folding new surface markers into the existing sequence 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]!
-      // isSurfaceEvent checks event.type first (is it a surface-eligible type?)
-      // then checks that surfaceOp is present. Only after both pass do we treat
-      // it as a SurfaceEvent with mandatory surfaceOp.
-      if (!isSurfaceEvent(event)) continue
-
-      if (event.surfaceOp === 'append') {
-        this._nodes.push(event.seq)
-      } else {
-        this._replace(event.seq, event.surfaceOp)
-      }
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- bounded by the loop condition
+      applySurfaceEvent(this._state, this.log[i]!)
    }
    this._lastProcessedSeq = this.log.length - 1
  }
-
-  /** Apply a replace operation to the in-progress surface. */
-  private _replace(
-    newSeq: number,
-    op: Extract<SurfaceOp, { op: 'replace' }>,
-  ): void {
-    const startIdx = this._nodes.indexOf(op.start)
-    if (startIdx === -1) {
-      throw new Error(`surface replace: start seq ${op.start} not found in surface`)
-    }
-    const endIdx = this._nodes.indexOf(op.end)
-    if (endIdx === -1) {
-      throw new Error(`surface replace: end seq ${op.end} not found in surface`)
-    }
-    if (startIdx > endIdx) {
-      throw new Error(`surface replace: start seq ${op.start} (index ${startIdx}) is after end seq ${op.end} (index ${endIdx})`)
-    }
-
-    // Remove shadowed nodes from `[startIdx, endIdx]` inclusive.
-    const count = endIdx - startIdx + 1
-    this._nodes.splice(startIdx, count, newSeq)
-    this._replaceGeneration += 1
-  }
 }