@deepseek-ai/dsh-session 0.1.2-rc.1 → 0.1.5-alpha.1

package/lib/types/surface.d.ts

@@ -13,7 +13,7 @@ import type { SessionEvent, SurfaceEvent, SurfaceOp } from './types.ts';
 /**
  * Whether an event type can join the model-visible surface.
  * @param type - event type to test.
- * @returns true for one of the three message-producing event types.
+ * @returns true for one of the four message-producing event types.
  */
 export declare function isSurfaceEligibleType(type: string): boolean;
 /**
@@ -50,7 +50,7 @@ export declare function isReplacementSurfaceEvent(event: SessionEvent): event is
 };
 /**
  * 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
+ * produces none — a non-surface event (attempt, boundary, log-only record) or an
  * empty-content assistant/message (which exists only to host usage). This is
  * THE per-node projection rule: `Session.deriveMessages` folds it over the
  * live surface, external reconstructors and pure projections fold the same
@@ -62,6 +62,14 @@ export declare function isReplacementSurfaceEvent(event: SessionEvent): event is
  * @returns the derived message, or null when the event produces none.
  */
 export declare function deriveEventMessage(event: SessionEvent): Message | null;
+/**
+ * Reject noncanonical request-header fields and contradictory tool failure metadata.
+ * This does not validate complete event payloads or embedded provider streams.
+ * @param event - event whose locally related payload fields are inspected.
+ * @param subject - event location to include in validation errors.
+ * @throws when request data/header is not an object, optional header fields are empty, or tool failure metadata contradicts its message.
+ */
+export declare function validateSessionEventData(event: Pick<SessionEvent, 'type' | 'data'>, subject: string): void;
 /** One replacement operation observed while folding a session surface. */
 export interface SurfaceFoldReplacement {
     /** Seq of the event that replaced the prior surface range. */
@@ -87,6 +95,14 @@ export interface SessionSurface {
     /** Monotonic count of committed positional replacements. */
     readonly replaceGeneration: number;
 }
+/**
+ * Validate one event's surface metadata without checking membership in a log or surface.
+ * @param event - event whose marker and source sequence values are inspected.
+ * Unknown ignorable records retain opaque metadata and never change the surface.
+ * @returns the validated operation, or undefined for a log-only or unknown ignorable event.
+ * @throws when metadata violates event-local eligibility, marker, or source-sequence rules.
+ */
+export declare function validateSurfaceMetadata(event: SessionEvent): SurfaceOp | undefined;
 /**
  * Replay a complete session log through the canonical surface fold.
  * @param events - session events in contiguous seq order.

package/lib/types/surface.js

@@ -8,8 +8,10 @@
  * @module @deepseek-ai/dsh-session/surface
  */
 import { SessionLogOffset, SessionSeq } from "./types.js";
+import { KNOWN_SESSION_EVENT_TYPES } from "./known-event-types.js";
 /** Runtime counterpart of the message-producing event union. */
 const SURFACE_EVENT_TYPES = new Set([
+    'system/message',
     'user/message',
     'assistant/message',
     'tool/result',
@@ -17,7 +19,7 @@ const SURFACE_EVENT_TYPES = new Set([
 /**
  * Whether an event type can join the model-visible surface.
  * @param type - event type to test.
- * @returns true for one of the three message-producing event types.
+ * @returns true for one of the four message-producing event types.
  */
 export function isSurfaceEligibleType(type) {
     return SURFACE_EVENT_TYPES.has(type);
@@ -30,7 +32,8 @@ export function isSurfaceEligibleType(type) {
 export function isSurfaceEvent(event) {
     if (!SURFACE_EVENT_TYPES.has(event.type))
         return false;
-    return event.surfaceOp !== undefined;
+    const candidate = event;
+    return candidate.surfaceOp !== undefined;
 }
 /**
  * Narrow an event to an append-origin surface event: one that entered the
@@ -58,7 +61,7 @@ export function isReplacementSurfaceEvent(event) {
 }
 /**
  * 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
+ * produces none — a non-surface event (attempt, boundary, log-only record) or an
  * empty-content assistant/message (which exists only to host usage). This is
  * THE per-node projection rule: `Session.deriveMessages` folds it over the
  * live surface, external reconstructors and pure projections fold the same
@@ -71,7 +74,7 @@ export function isReplacementSurfaceEvent(event) {
  */
 export function deriveEventMessage(event) {
     // Intentionally non-exhaustive: only message-producing events derive
-    // history; turn/step boundaries, chunks, usage, and errors are trace/replay
+    // history; turn/step boundaries, failed attempts, and errors are trace/replay
     // data.
     switch (event.type) {
         // Ordinary prompts and injected context project in user role: the event's
@@ -85,10 +88,13 @@ export function deriveEventMessage(event) {
         case 'user/message': {
             return event.data;
         }
+        // An empty-content message projects to no wire message. For
+        // system/message the node records "no system prompt" while keeping its
+        // surface position; for assistant/message the event exists only to host a
+        // max-tokens step's usage and must not inject a content-less assistant
+        // turn into the provider transcript.
+        case 'system/message':
         case 'assistant/message': {
-            // Skip an empty-content assistant/message: it exists only to host a
-            // max-tokens step's usage and must not inject a content-less assistant
-            // turn into the provider transcript.
             if (event.data.message.content.length === 0)
                 return null;
             return event.data.message;
@@ -97,11 +103,53 @@ export function deriveEventMessage(event) {
             return event.data.message;
         }
         default:
-            // A non-surface event (boundary, chunk, log-only record) projects to
+            // A non-surface event (boundary, attempt, log-only record) projects to
             // no message. Merge-extensible union: no assertNever here.
             return null;
     }
 }
+/** Whether a payload field is a JSON object rather than an array or scalar. */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Reject noncanonical request-header fields and contradictory tool failure metadata.
+ * This does not validate complete event payloads or embedded provider streams.
+ * @param event - event whose locally related payload fields are inspected.
+ * @param subject - event location to include in validation errors.
+ * @throws when request data/header is not an object, optional header fields are empty, or tool failure metadata contradicts its message.
+ */
+export function validateSessionEventData(event, subject) {
+    const data = event.data;
+    if (event.type === 'request/header') {
+        if (!isRecord(data))
+            throw new Error(`${subject} data must be an object`);
+        const header = data['header'];
+        if (!isRecord(header))
+            throw new Error(`${subject} header must be an object`);
+        if (Object.hasOwn(header, 'system'))
+            throw new Error(`${subject} must omit header.system; use system/message`);
+        if (Array.isArray(header['tools']) && header['tools'].length === 0) {
+            throw new Error(`${subject} must omit empty tools`);
+        }
+        const defaults = header['adapterDefaults'];
+        if (isRecord(defaults) && Object.keys(defaults).length === 0) {
+            throw new Error(`${subject} must omit empty adapterDefaults`);
+        }
+    }
+    else if (event.type === 'tool/result') {
+        if (!isRecord(data))
+            throw new Error(`${subject} data must be an object`);
+        if (data['error'] === undefined)
+            return;
+        const message = data['message'];
+        const content = isRecord(message) ? message['content'] : undefined;
+        const block = Array.isArray(content) ? content[0] : undefined;
+        if (!isRecord(block) || block['isError'] !== true) {
+            throw new Error(`${subject} error requires message content[0].isError === true`);
+        }
+    }
+}
 /** Create an empty surface fold state. */
 function createFoldState() {
     return { nodes: [], replaceGeneration: 0 };
@@ -118,16 +166,19 @@ function isReplaceOp(value) {
     const op = value;
     return Object.keys(op).length === 3
         && Object.hasOwn(op, 'op')
-        && Object.hasOwn(op, 'start')
-        && Object.hasOwn(op, 'end')
+        && Object.hasOwn(op, 'startSeq')
+        && Object.hasOwn(op, 'endSeq')
         && op['op'] === 'replace'
-        && isEventSeq(op['start'])
-        && isEventSeq(op['end']);
+        && isEventSeq(op['startSeq'])
+        && isEventSeq(op['endSeq']);
 }
 /** Validate event-local surface eligibility and return its operation. */
 function surfaceOpOf(event) {
     const raw = event;
     if (!isSurfaceEligibleType(event.type)) {
+        // Unknown ignorable records retain opaque metadata without affecting history.
+        if (!KNOWN_SESSION_EVENT_TYPES.has(event.type) && event.ignorable === true)
+            return;
         if (raw.surfaceOp !== undefined) {
             throw new Error(`session event "${event.type}" is not surface-eligible and cannot carry surfaceOp`);
         }
@@ -153,13 +204,16 @@ function surfaceOpOf(event) {
 /** Validate cited source-event seqs against prior log entries and the replacement range. */
 function assertProvenance(event, shadowedSeqs) {
     const raw = event.sourceEventSeqs;
+    if (event.type === 'assistant/message' && raw !== undefined) {
+        throw new Error('assistant/message embeds its source stream and cannot carry sourceEventSeqs');
+    }
     const sources = new Set();
     if (raw !== undefined) {
         if (!Array.isArray(raw)) {
             throw new Error(`sourceEventSeqs on event at seq ${event.seq} must be an array when present`);
         }
-        if (raw.length === 0 && event.type !== 'assistant/message') {
-            throw new Error('sourceEventSeqs must not be empty except on assistant/message');
+        if (raw.length === 0) {
+            throw new Error('sourceEventSeqs must not be empty');
         }
         let nonEarlierSource;
         for (const source of raw) {
@@ -182,18 +236,35 @@ function assertProvenance(event, shadowedSeqs) {
         throw new Error(`surface replace: sourceEventSeqs must include every shadowed surface node; missing ${missing.join(', ')}`);
     }
 }
+/**
+ * Validate one event's surface metadata without checking membership in a log or surface.
+ * @param event - event whose marker and source sequence values are inspected.
+ * Unknown ignorable records retain opaque metadata and never change the surface.
+ * @returns the validated operation, or undefined for a log-only or unknown ignorable event.
+ * @throws when metadata violates event-local eligibility, marker, or source-sequence rules.
+ */
+export function validateSurfaceMetadata(event) {
+    const op = surfaceOpOf(event);
+    if (op !== undefined && op !== 'append'
+        && (op.startSeq >= event.seq || op.endSeq >= event.seq)) {
+        throw new Error(`surface replace at seq ${event.seq}: startSeq and endSeq must reference earlier events`);
+    }
+    if (op !== undefined)
+        assertProvenance(event, []);
+    return op;
+}
 /** Locate one replacement range without mutating the current fold state. */
 function replacementRange(state, op) {
-    const startIdx = state.nodes.indexOf(op.start);
+    const startIdx = state.nodes.indexOf(op.startSeq);
     if (startIdx === -1) {
-        throw new Error(`surface replace: start seq ${op.start} not found in surface`);
+        throw new Error(`surface replace: start seq ${op.startSeq} not found in surface`);
     }
-    const endIdx = state.nodes.indexOf(op.end);
+    const endIdx = state.nodes.indexOf(op.endSeq);
     if (endIdx === -1) {
-        throw new Error(`surface replace: end seq ${op.end} not found in surface`);
+        throw new Error(`surface replace: end seq ${op.endSeq} 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})`);
+        throw new Error(`surface replace: start seq ${op.startSeq} (index ${startIdx}) is after end seq ${op.endSeq} (index ${endIdx})`);
     }
     return {
         startIdx,
@@ -251,26 +322,42 @@ function assertToolResultRewrite(event, shadowedSeqs, events, baseSeq) {
         }
     }
 }
+/**
+ * Protect the system prompt at surface node 0. A replacement covering node 0
+ * while that node is a `system/message` must itself be a `system/message` over
+ * exactly that node; later system nodes carry no protection and a compaction
+ * range may shadow them.
+ */
+function assertSystemHeadRewrite(event, state, startIdx, shadowedSeqs, events, baseSeq) {
+    if (startIdx !== 0)
+        return;
+    const head = events[state.nodes[0] - baseSeq];
+    if (head?.type !== 'system/message')
+        return;
+    if (event.type !== 'system/message' || shadowedSeqs.length !== 1) {
+        throw new Error('surface replace: node 0 holds the system prompt and may be rewritten only by a system/message over exactly that node');
+    }
+}
 /** Validate one event at its replay boundary and prepare its atomic fold transition. */
 function planSurfaceEvent(state, event, expectedSeq, events, baseSeq) {
     if (event.seq !== expectedSeq) {
         throw new Error(`session event seq ${event.seq} is not contiguous; expected ${expectedSeq}`);
     }
-    const surfaceOp = surfaceOpOf(event);
+    const surfaceOp = validateSurfaceMetadata(event);
     if (surfaceOp === undefined)
         return;
     if (surfaceOp === 'append') {
-        assertProvenance(event, []);
         return { kind: 'append', seq: event.seq };
     }
     const range = replacementRange(state, surfaceOp);
     assertProvenance(event, range.shadowedSeqs);
     assertToolResultRewrite(event, range.shadowedSeqs, events, baseSeq);
+    assertSystemHeadRewrite(event, state, range.startIdx, range.shadowedSeqs, events, baseSeq);
     return {
         kind: 'replace',
         seq: event.seq,
-        start: surfaceOp.start,
-        end: surfaceOp.end,
+        start: surfaceOp.startSeq,
+        end: surfaceOp.endSeq,
         ...range,
     };
 }

package/lib/types/types.d.ts

@@ -1,5 +1,5 @@
 import { type Branded, type BrandedNumber } from '@deepseek-ai/dsh-brand';
-import type { AssistantMessage, ToolCallId, LlmCallConfig, LlmCallConfigAdapterDefaults, LlmFailure, StreamChunk, TokenUsage, ToolResultMessage, ToolSchema, UserMessage } from '@deepseek-ai/dsh-llm';
+import type { AssistantMessage, AssistantStreamRecord, ToolCallId, LlmCallConfig, LlmCallConfigAdapterDefaults, LlmFailure, SystemMessage, SystemPromptUpdate, TokenUsage, ToolResultMessage, ToolSchema, UserMessage } from '@deepseek-ai/dsh-llm';
 import type { JsonValue } from '@deepseek-ai/dsh-util-values';
 /** Identifies one session in the store (and its persistence artifacts). */
 export type SessionId = Branded<'SessionId'>;
@@ -30,11 +30,11 @@ export type SessionSeqCursor = SessionSeq | -1;
 /** One existing Session event position, or explicit absence. */
 export type OptionalSessionSeq = SessionSeq | null;
 /**
- * The on-disk session format version, stamped into every newly-written {@link SessionHeader}
- * and enforced by every persistence backend on load. The single source of truth for the
- * version — write sites and the load-time check all read it.
- * While the harness is unreleased it is pinned at `0`: no compatibility is
- * implied, incompatible logs are rejected, and no migration is provided.
+ * Current logical Session format version, stamped into every newly written
+ * {@link SessionHeader}. Current Session and persistence code accept only this
+ * value; header-only readers classify supported historical formats, while an
+ * event-body read composes the build-static adjacent chain and publishes only
+ * this final generation before constructing a Session.
  *
  * The version is a single monotonic integer with no major/minor split. Whether
  * a bump is needed is decided by what the WRITER emits, never by what a newer
@@ -47,22 +47,20 @@ export type OptionalSessionSeq = SessionSeq | null;
  * Adding an ordinary event type does not bump — the per-event
  * {@link SessionEvent.ignorable} guard covers vocabulary growth instead. When
  * in doubt, bump: a near-identity upgrade step is almost free, a missed bump
- * makes older runtimes read new logs wrong silently. The full mechanism
- * (upgrade-step chain, in-memory view conversion, migrate-on-continue) is
- * recorded in the session-log-version-mechanism Agent Note
- * (`.agents/notes/implemented/architecture/2026-08-10-session-log-version-mechanism.md`).
+ * makes older runtimes read new logs wrong silently. The released migration,
+ * immutable prior-generation, and current fast-path rules are recorded in
+ * `.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.md`.
  */
-export declare const SESSION_FORMAT_VERSION = 0;
+export declare const SESSION_FORMAT_VERSION = 3;
 /**
  * Immutable validated storage metadata, kept outside the conversation event log.
  */
 export interface SessionHeader {
     /**
-     * On-disk format version, stamped from {@link SESSION_FORMAT_VERSION} when the
-     * session is created. A persistence backend rejects any other version on load
-     * (no migration — see the constant).
+     * Current logical format version, stamped from {@link SESSION_FORMAT_VERSION}.
+     * Historical physical headers are translated before entering this interface.
      */
-    readonly version: number;
+    readonly version: typeof SESSION_FORMAT_VERSION;
     /** The session's id (mirrors the {@link Session}'s id). */
     readonly id: SessionId;
     /** Non-negative safe-integer Unix epoch milliseconds when the session was created. */
@@ -104,8 +102,9 @@ export interface CreateSessionOptions {
     /** Initial replay or fork history supplied at construction. */
     readonly seed?: readonly SessionEvent[];
     /**
-     * Exact fork-inherited prefix length when `meta.isSeeded` is true. A
-     * constructor seed may also contain child-owned setup events after this cut.
+     * Exact fork-inherited prefix length when `meta.isSeeded` is true. In v2 the
+     * constructor seed is exactly this inherited prefix; the constructor
+     * appends the child-owned tagged marker at the cut.
      */
     readonly inheritedEventCount?: SessionLogOffset;
     /**
@@ -123,22 +122,27 @@ export interface CreateSessionOptions {
     };
 }
 /**
- * Fresh storage values transferred to {@link SessionStore.prepare} without a
- * second serialization copy. Callers retain no mutable aliases.
+ * Aliasing state of an adoptable Session seed. `shared-frozen` permits deeply
+ * frozen aliases plus independently owned unfrozen values in the same seed.
+ */
+export type SessionSeedEventState = 'detached' | 'shared-frozen';
+/**
+ * Adoptable storage values transferred to {@link SessionStore.prepare}
+ * without another copy or freeze pass.
  */
 export interface RestoredSessionOptions {
-    /** Fresh detached storage events to validate and freeze in place. */
+    /** Events that are independently owned or already deeply frozen. */
     readonly seed: SessionEvent[];
-    /** Fresh detached storage metadata to validate and freeze in place. */
+    /** Independently owned storage metadata to validate and freeze in place. */
     readonly meta: SessionHeader;
     /** Exact number of fork-inherited leading events decoded from storage. */
     readonly inheritedEventCount: SessionLogOffset;
-    /** Select the persistence ownership-transfer path. */
-    readonly seedSource: 'persistence';
+    /** Aliasing state carried from the operation that produced the seed. */
+    readonly eventState: SessionSeedEventState;
 }
 /** Inputs accepted while constructing an unpublished Session. */
 export type PrepareSessionOptions = (CreateSessionOptions & {
-    readonly seedSource?: undefined;
+    readonly eventState?: undefined;
 }) | RestoredSessionOptions;
 /** Why an active agent driver was cancelled. */
 export type AgentCancelCause = {
@@ -184,8 +188,10 @@ export interface TurnEndReasonMap {
         kind: 'max-tokens';
     };
     /**
-     * A persistence backend closed a crash-orphaned turn on reload. The loop never
-     * emits this marker, and the events recorded before the crash remain intact.
+     * A crash-orphaned turn was closed after the fact: agent-loop resume appends
+     * this closer for a stored log whose last turn never ended, and session-query
+     * synthesizes it on cold reads. The loop never emits this marker live, and
+     * the events recorded before the crash remain intact.
      */
     interrupted: {
         kind: 'interrupted';
@@ -194,8 +200,9 @@ export interface TurnEndReasonMap {
 /** The union over {@link TurnEndReasonMap} — why a turn ended; plugins extend it by merging variants into the map. */
 export type TurnEndReason = TurnEndReasonMap[keyof TurnEndReasonMap];
 /**
- * Logged request state outside derived history: call config, system prompt, and
- * tools. The latest full `request/header` snapshot reconstructs it; canonical
+ * Logged request state outside derived history: call config and tools. The
+ * system prompt is derived history — surface node 0, a `system/message` event.
+ * The latest full `request/header` snapshot reconstructs the header; canonical
  * empty optional fields are absent.
  */
 export interface EpochHeader {
@@ -203,8 +210,6 @@ export interface EpochHeader {
     config: LlmCallConfig;
     /** Effective config fields materialized from the exact adapter rather than proposed by a caller. */
     adapterDefaults?: LlmCallConfigAdapterDefaults;
-    /** Rendered system prompt text; absent for a system-less request. */
-    system?: string;
     /** Assembled tool schemas; absent for a tool-less request. */
     tools?: ToolSchema[];
 }
@@ -216,6 +221,8 @@ export interface RequestContext {
     model: string;
     /** Maximum combined request and response context in tokens, when advertised. */
     contextWindow?: number;
+    /** `'in-history'` when the route reads the latest `system` message at any position as the effective system prompt. */
+    systemPromptUpdate?: SystemPromptUpdate;
 }
 /**
  * Why a `request/header` snapshot was appended: `'initial'` — the log's first
@@ -229,8 +236,8 @@ export type RequestHeaderReason = 'initial' | 'resume' | 'change' | 'series';
 /**
  * The merge-extensible, append-only source of truth for an agent interaction.
  * Message history is derived from this log. Every event is lossless JSON and
- * sequence numbers stay contiguous, including raw chunks, so persistence can
- * store the canonical log verbatim.
+ * sequence numbers stay contiguous. Assistant attempt events embed their exact
+ * compact raw streams so persistence stores one durable settlement per attempt.
  */
 export interface SessionEventMap {
     /**
@@ -272,11 +279,22 @@ export interface SessionEventMap {
      * project their `content` verbatim; `source` tells them apart.
      */
     'user/message': UserMessage;
-    /** Raw stream chunk — token-level replay fidelity. */
-    'assistant/chunk': {
+    /**
+     * The rendered system prompt on the model-visible surface. The loop appends
+     * the first one as surface node 0 before the step's first `user/message`.
+     * A prepared in-history route can append nonempty changes in a continuing
+     * series. An incapable route or new series normalizes text to the first system
+     * node. Normalization empties nonempty later nodes, then rewrites the head if
+     * needed, through logged per-node replacements. An empty rendering always
+     * clears all active system nodes, leaving no older instructions model-visible.
+     * Empty later nodes are dormant and project to no message; an empty head with
+     * no active later node records "no system prompt". Restored nonempty text follows
+     * the same route and series rule; empty nodes never restore older text.
+     */
+    'system/message': {
         turn: number;
         step: number;
-        chunk: StreamChunk;
+        message: SystemMessage;
     };
     /**
      * Assembled assistant message for one step (derived history uses this).
@@ -292,9 +310,21 @@ export interface SessionEventMap {
         turn: number;
         step: number;
         message: AssistantMessage;
+        /** Exact timed model stream, compacted without joining delta boundaries. */
+        stream: AssistantStreamRecord[];
         usage?: TokenUsage;
         interrupted?: true;
     };
+    /**
+     * One model attempt that committed no surface message. The embedded stream
+     * preserves a failed, retried, cancelled, or stream-error attempt that
+     * reached settlement without fabricating model-visible history.
+     */
+    'assistant/attempt': {
+        turn: number;
+        step: number;
+        stream: AssistantStreamRecord[];
+    };
     /**
      * The model requested one tool invocation: `name` with the raw `arguments`
      * JSON string exactly as the model produced it (unparsed). `callId` pairs the
@@ -322,6 +352,7 @@ export interface SessionEventMap {
         turn: number;
         step: number;
         message: ToolResultMessage;
+        /** Optional failure identity; allowed only when the tool-result block has `isError: true`. */
         error?: {
             name: string;
             code: string;
@@ -339,20 +370,22 @@ export interface SessionEventMap {
         startsSeries?: true;
     };
     /**
-     * Route metadata for the next request, logged only when the route or capacity
-     * changes. It does not participate in request reconstruction or header equality.
+     * Route metadata for the next request, logged only when the route, capacity,
+     * or system prompt update mode changes. It does not participate in request
+     * reconstruction or header equality. Prompt admission uses the bound prepared
+     * call's capability, not this snapshot from an earlier request.
      */
     'request/context': RequestContext;
     /**
      * Marks the end of a constructor seed. Events before it have smaller seq
      * values and came from the seed (resume, fork, or replay); this lifecycle
      * produced none of them. This log-only event is the durable projection of
-     * {@link Session.firstLiveSeq}. Its payload is empty — position and `time`
-     * carry the meaning.
+     * {@link Session.firstLiveSeq}.
      *
-     * Locate the LAST one in stored history. A seed already ending in one is not
-     * re-marked, so reopening an untouched session does not grow its log per
-     * pickup and the event need not be at the current `firstLiveSeq`.
+     * A fresh fork child owns one `{ inherited: true }` marker at its exact
+     * inherited-prefix cut, even when that prefix ends in an ancestor marker.
+     * The last tagged marker is the current Session's cut; untagged markers keep
+     * ordinary restore and replay lifecycle boundaries.
      *
      * `Session`'s constructor is the only legitimate writer. The invariant
      * companion deliberately constrains nothing here, so a plugin appending one
@@ -365,60 +398,52 @@ export interface SessionEventMap {
      * writers — a concurrently live session holds its own boundary elsewhere,
      * so tolerating concurrent writers needs a signal beyond the log.
      */
-    'session/end-seed': Record<string, never>;
+    'session/end-seed': {
+        inherited?: true;
+    };
 }
 /** The appendable event-type keys of {@link SessionEventMap}, plugin-merged extensions included. */
 export type SessionEventType = keyof SessionEventMap;
 /**
  * The subset of {@link SessionEventType} values whose events produce LLM
  * messages and are eligible to appear on the ordered surface. Only these
- * event types may carry {@link SurfaceOp} and {@link SessionEvent.sourceEventSeqs}.
+ * event types may carry {@link SurfaceOp}; system, user, and tool events may also cite
+ * earlier sources through {@link SessionEvent.sourceEventSeqs}.
  */
-export type SurfaceEventType = 'user/message' | 'assistant/message' | 'tool/result';
-/**
- * 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.
- *
- * Use the `isSurfaceEvent` type guard (in `surface.ts`) to narrow a
- * `SessionEvent` to this type.
- */
-export type SurfaceEvent = SessionEvent<SurfaceEventType> & {
-    surfaceOp: SurfaceOp;
-};
+export type SurfaceEventType = 'system/message' | 'user/message' | 'assistant/message' | 'tool/result';
+/** A message-producing event carrying its required surface operation. */
+export type SurfaceEvent = SessionEvent<SurfaceEventType>;
 /**
  * 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
  *   messages.
- * - `{ op: 'replace', start, end }`: replaces surface nodes from `start`
- *   (inclusive) through `end` (inclusive) with this node. Both must exist as
- *   surface nodes in the current surface. `start === end` replaces a single
+ * - `{ op: 'replace', startSeq, endSeq }`: replaces surface nodes from `startSeq`
+ *   (inclusive) through `endSeq` (inclusive) with this node. Both must exist as
+ *   surface nodes in the current surface. `startSeq === endSeq` replaces a single
  *   node. The node's {@link SessionEvent.sourceEventSeqs} must include every
  *   shadowed surface node. Used by compaction; any surface-replacing producer
  *   may use it.
  */
 export type SurfaceOp = 'append' | {
     op: 'replace';
-    start: SessionSeq;
-    end: SessionSeq;
+    startSeq: SessionSeq;
+    endSeq: SessionSeq;
 };
 /**
  * Surface placement and cited source-event seqs for {@link Session.append}. Required on
  * message-producing events and forbidden on log-only events.
  */
-export interface SurfaceIntent {
+export type SurfaceIntent<T extends SurfaceEventType = SurfaceEventType> = {
     surfaceOp: SurfaceOp;
-    /**
-     * Complete set of known source-event seqs. `assistant/message` may use a
-     * present empty array for a known empty provider stream; when the field is
-     * absent, the event does not record which earlier events produced the message.
-     * Other surface events require a non-empty set when this field is present.
-     */
+} & (T extends 'assistant/message' ? {
+    /** Assistant messages embed their provider stream instead of citing source events. */
+    sourceEventSeqs?: never;
+} : {
+    /** Complete non-empty set of known earlier source-event seqs. */
     sourceEventSeqs?: SessionSeq[];
-}
+});
 /**
  * One immutable entry in the session log.
  *
@@ -426,9 +451,9 @@ export interface SurfaceIntent {
  * unions), so `switch (event.type)` narrows `event.data` without casts.
  *
  * The {@link sourceEventSeqs} and {@link surfaceOp} fields are conditional:
- * they only exist on {@link SurfaceEventType} variants (`user/message`,
+ * they only exist on {@link SurfaceEventType} variants (`system/message`, `user/message`,
  * `assistant/message`, `tool/result`).
- * Non-surface events (boundary markers, chunks, usage, errors) never carry
+ * Non-surface events (boundary markers, attempts, errors) never carry
  * surface metadata — the compiler enforces this at `Session.append()`
  * call sites.
  */
@@ -451,19 +476,10 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
          * inconvenience) rather than silently resuming a gutted session.
          */
         ignorable?: true;
-    } & (K extends SurfaceEventType ? {
-        /**
-         * Seq numbers of earlier events that this event cites as sources
-         * (e.g. the `assistant/chunk` seqs that built an `assistant/message`,
-         * or the surface nodes shadowed by a compaction replace node). An
-         * `assistant/message` may carry a present empty array for a known empty
-         * provider stream; when the field is absent, the event does not record which
-         * earlier events produced the message.
-         */
-        sourceEventSeqs?: SessionSeq[];
-        /** How this event entered the surface; absent for non-surface events. */
-        surfaceOp?: SurfaceOp;
-    } : object);
+    } & (K extends SurfaceEventType ? SurfaceIntent<K> : {
+        surfaceOp?: never;
+        sourceEventSeqs?: never;
+    });
 }[T];
 declare module '@deepseek-ai/dsh-typert-protocol' {
     interface RemoteErrorDetailsMap {