@deepseek-ai/dsh-session 0.1.2-alpha.5 → 0.1.3-alpha.2

package/lib/types/index.d.ts

@@ -10,15 +10,13 @@ import type { Scoped } from '@deepseek-ai/dsh-scope';
 import type { Message } from '@deepseek-ai/dsh-llm';
 import { SessionLogOffset, SessionSeq } from './types.ts';
 import type { TypertLookup } from '@deepseek-ai/dsh-typert-protocol';
-import type { CreateSessionOptions, EpochHeader, PrepareSessionOptions, RequestContext, SessionEvent, SessionEventMap, SessionEventType, SessionHeader, SessionId, SurfaceIntent, SurfaceEventType } from './types.ts';
+import type { CreateSessionOptions, EpochHeader, PrepareSessionOptions, RequestContext, SessionEvent, SessionEventMap, SessionEventType, SessionHeader, SessionId, SessionSeedEventState, SurfaceIntent, SurfaceEventType } from './types.ts';
 import type { SessionSurface } from './surface.ts';
 export * from './types.ts';
 export { SessionPreparation } from './preparation.ts';
 export type { SessionPreparationOptions } from './preparation.ts';
 export type { AssistantMessage, ToolResultMessage, UserMessage } from '@deepseek-ai/dsh-llm';
 export { interruptedTurnClosers, TOOL_NOT_STARTED, TOOL_OUTCOME_UNKNOWN } from './repair.ts';
-export { decodeStorageRecord, packChunkRuns } from './chunk-rows.ts';
-export type { ChunkRow, StorageRecord } from './chunk-rows.ts';
 export type { SessionSurface, SurfaceFoldReplacement, SurfaceFoldResult } from './surface.ts';
 export { deriveEventMessage, foldSurface, isAppendSurfaceEvent, isReplacementSurfaceEvent, isSurfaceEvent, isSurfaceEligibleType } from './surface.ts';
 export { canonicalHeader, foldRequestHeader, headerEquals } from './request-header.ts';
@@ -124,9 +122,10 @@ export declare class Session {
      * The first seq appended IN THIS PROCESS: the length of the constructor
      * seed (0 without one). Events with smaller seq values entered through
      * construction — replay, fork, or resume — and were never published on the
-     * `session/event` firehose (constructor seeds do not emit), so consumers
-     * that replay the log as a publication substitute (telemetry adoption)
-     * start here. Distinct from {@link inheritedEventCount}, the DURABLE
+     * `session/event` firehose (constructor seeds do not emit). This offset marks
+     * the constructor-input boundary for lifecycle ownership and persistence
+     * adoption; consumers that need complete canonical history still start at
+     * seq 0. Distinct from {@link inheritedEventCount}, the DURABLE
      * fork-lineage cut: a resumed session's constructor seed is its full stored
      * log, while the inherited count keeps the original fork value — this field is the
      * in-process construction fact.
@@ -154,16 +153,19 @@ export declare class Session {
      */
     static create(id: SessionId, seed?: readonly SessionEvent[], header?: SessionHeader, inheritedEventCount?: SessionLogOffset): Session;
     /**
-     * Restore a detached session by taking ownership of fresh persistence values.
-     * The storage format, event envelopes, sequence continuity, surface transitions,
-     * and header fields are validated before the restored objects are frozen.
+     * Restore a detached session by adopting an independently owned or deeply frozen seed.
+     * Runtime-required event fields, event envelopes, sequence continuity, surface
+     * transitions, and header fields are validated without copying or freezing events.
+     * Embedded Assistant streams remain opaque until a stream consumer or storage
+     * verifier reads them.
      * @param id - restored session identity.
-     * @param seed - fresh detached events whose ownership is transferred.
-     * @param header - fresh detached metadata whose ownership is transferred.
+     * @param seed - independently owned or deeply frozen events.
+     * @param header - independently owned storage metadata.
      * @param inheritedEventCount - exact fork-inherited prefix length decoded from storage.
+     * @param eventState - aliasing state carried from the operation that produced the seed.
      * @returns a restored detached session.
      */
-    static fromRestore(id: SessionId, seed: readonly SessionEvent[], header: SessionHeader, inheritedEventCount: SessionLogOffset): Session;
+    static fromRestore(id: SessionId, seed: readonly SessionEvent[], header: SessionHeader, inheritedEventCount: SessionLogOffset, eventState: SessionSeedEventState): Session;
     private constructor();
     /** Cached immutable full snapshot of the private append-only log. */
     private eventsSnapshot;
@@ -212,7 +214,8 @@ export declare class Session {
      *   declare how it joins the surface, the sole source of derived model
      *   history) and
      *   rejected by the compiler for non-surface types like `turn/start` or
-     *   `assistant/chunk`.
+     *   `assistant/attempt`. Assistant messages embed their exact provider
+     *   stream and cannot cite top-level source events.
      * @returns the logged event — its assigned `seq`/`time` plus the SNAPSHOT of
      *   `data` that entered the log, so reading `event.data` back sees the logged
      *   value, never the caller's still-mutable input.
@@ -230,7 +233,7 @@ export declare class Session {
      *   append reentered while this acceptance/publication boundary is open also
      *   rejects before the log changes.
      */
-    append<T extends SessionEventType>(type: T, data: SessionEventMap[T], ...opts: T extends SurfaceEventType ? [opts: SurfaceIntent] : []): SessionEvent<T>;
+    append<T extends SessionEventType>(type: T, data: SessionEventMap[T], ...opts: T extends SurfaceEventType ? [opts: SurfaceIntent<T>] : []): SessionEvent<T>;
     /** Cached fold of the request-header events — see {@link requestHeader}. */
     private headerFold;
     /** Log position (events consumed) the header fold has reached. */
@@ -305,8 +308,9 @@ export declare class SessionForkError extends Error {
 /**
  * In-memory session store (`ctx.sessions`).
  *
- * Persistence is intentionally not implemented here — persistence plugins
- * subscribe to `session/event` and flush on `session/flush` / dispose.
+ * Persistence is intentionally not implemented here — the agent lifecycle
+ * attaches a session-log writer to each published session's write handle;
+ * a session published outside that lifecycle persists nothing.
  */
 export declare class SessionStore extends Service {
     private store;
@@ -345,10 +349,9 @@ export declare class SessionStore extends Service {
      *
      * @param id - the session id; omitted, the store mints `session-<n>`.
      * @param options - seed events and/or creation metadata for the header. With
-     *   `seedSource: 'persistence'`, metadata and events must be fresh detached
-     *   graphs whose ownership transfers to this call: they are validated and
-     *   frozen in place through {@link Session.fromRestore}, so the caller must
-     *   retain no mutable aliases.
+     *   `eventState`, every seed event is either independently owned or any
+     *   shared value is deeply frozen; {@link Session.fromRestore} validates and
+     *   adopts those values without copying or freezing them.
      * @returns the constructed session, NOT yet in the store.
      * @throws if a session with `id` already exists, metadata is not a plain
      *   lossless-JSON record with valid scalar fields, or `meta.cwd` is a

package/lib/types/index.js

@@ -8,7 +8,7 @@
 import { Service } from '@deepseek-ai/cordis';
 import { isAbsolute } from 'node:path';
 import { brandString } from '@deepseek-ai/dsh-brand';
-import { deepFreeze, snapshotJsonValue } from '@deepseek-ai/dsh-util-values';
+import { assertNever, deepFreeze, snapshotJsonValue } from '@deepseek-ai/dsh-util-values';
 import { scopeOf, scopeTarget } from '@deepseek-ai/dsh-scope';
 import { SESSION_FORMAT_VERSION, SessionLogOffset, SessionSeq } from "./types.js";
 import { deriveEventMessage, SurfaceManager } from "./surface.js";
@@ -16,7 +16,6 @@ import { foldRequestHeader } from "./request-header.js";
 export * from "./types.js";
 export { SessionPreparation } from "./preparation.js";
 export { interruptedTurnClosers, TOOL_NOT_STARTED, TOOL_OUTCOME_UNKNOWN } from "./repair.js";
-export { decodeStorageRecord, packChunkRuns } from "./chunk-rows.js";
 export { deriveEventMessage, foldSurface, isAppendSurfaceEvent, isReplacementSurfaceEvent, isSurfaceEvent, isSurfaceEligibleType } from "./surface.js";
 export { canonicalHeader, foldRequestHeader, headerEquals } from "./request-header.js";
 export { KNOWN_SESSION_EVENT_TYPES } from "./known-event-types.js";
@@ -117,28 +116,9 @@ export function adoptSessionEvent(event) {
 export function snapshotSessionEvent(event) {
     return adoptSessionEvent(structuredClone(event));
 }
-/** Deep-freeze one acyclic JSON tree without consuming the JavaScript call stack. */
-function freezeRestoredObject(value) {
-    const pending = [value];
-    while (pending.length > 0) {
-        // The non-empty check proves an object remains to visit.
-        // oxlint-disable-next-line typescript/no-non-null-assertion
-        const current = pending.pop();
-        Object.freeze(current);
-        for (const key in current) {
-            const child = current[key];
-            if (child !== null && typeof child === 'object')
-                pending.push(child);
-        }
-    }
-    return value;
-}
 /** Validate the fixed event envelope after one-pass JSON materialization. */
 function assertSessionEventEnvelope(value, index) {
     const event = value;
-    if (event['type'] === 'request/header-delta') {
-        throw new Error(`seed event at index ${index} uses unsupported legacy request/header-delta format`);
-    }
     for (const key in event) {
         switch (key) {
             case 'type':
@@ -166,6 +146,7 @@ function assertSessionEventEnvelope(value, index) {
     switch (type) {
         case 'request/header':
         case 'user/message':
+        case 'assistant/attempt':
         case 'assistant/message':
         case 'tool/result':
             assertCurrentLlmShape(event, index);
@@ -193,12 +174,36 @@ function assertCurrentLlmShape(event, index) {
             throw new Error(`seed request/header at index ${index} has an invalid reasoningEffort`);
         }
         assertAdapterDefaults(headerRecord?.['adapterDefaults'], configRecord, index);
+        const reason = record?.['reason'];
+        if (reason !== 'initial' && reason !== 'resume' && reason !== 'change' && reason !== 'series') {
+            throw new Error(`seed request/header at index ${index} has an invalid reason`);
+        }
+        if (record?.['startsSeries'] !== undefined && record['startsSeries'] !== true) {
+            throw new Error(`seed request/header at index ${index} has an invalid startsSeries marker`);
+        }
     }
     const type = event['type'];
+    if (type === 'assistant/attempt') {
+        assertAssistantSettlementShape(record, type, index);
+        return;
+    }
     if (type !== 'user/message' && type !== 'assistant/message'
         && type !== 'tool/result')
         return;
     assertMessageEventShape(event, `seed ${type} at index ${index}`);
+    if (type === 'assistant/message') {
+        assertAssistantSettlementShape(record, type, index);
+    }
+}
+/** Validate fields used directly by restored Session lifecycle logic without replaying the embedded stream. */
+function assertAssistantSettlementShape(data, type, index) {
+    const turn = data?.['turn'];
+    const step = data?.['step'];
+    if (typeof turn !== 'number' || !Number.isSafeInteger(turn) || turn < 0 || Object.is(turn, -0)
+        || typeof step !== 'number' || !Number.isSafeInteger(step) || step < 0 || Object.is(step, -0)
+        || !Array.isArray(data?.['stream'])) {
+        throw new Error(`seed ${type} at index ${index} has invalid settlement fields`);
+    }
 }
 const allowedAdapterKeys = new Set(['reasoningEffort', 'maxTokens']);
 /** Validate adapter-default markers imported from a durable request header. */
@@ -279,17 +284,6 @@ function hasProviderModel(value) {
     return typeof pair['provider'] === 'string' && pair['provider'].length > 0
         && typeof pair['model'] === 'string' && pair['model'].length > 0;
 }
-/** Reject request-header vocabulary removed with the legacy delta codec. */
-function assertSupportedRequestHeader(type, data, location) {
-    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['reason'] === 'fallback') {
-        throw new Error(`${location} uses unsupported legacy request/header reason "fallback"`);
-    }
-}
 /** Resolve one listener snapshot, including Cordis's internal dispatch checks. */
 function collectSessionCallbacks(ctx, args) {
     return [...ctx.events.dispatch('emit', args)];
@@ -345,9 +339,10 @@ export class Session {
      * The first seq appended IN THIS PROCESS: the length of the constructor
      * seed (0 without one). Events with smaller seq values entered through
      * construction — replay, fork, or resume — and were never published on the
-     * `session/event` firehose (constructor seeds do not emit), so consumers
-     * that replay the log as a publication substitute (telemetry adoption)
-     * start here. Distinct from {@link inheritedEventCount}, the DURABLE
+     * `session/event` firehose (constructor seeds do not emit). This offset marks
+     * the constructor-input boundary for lifecycle ownership and persistence
+     * adoption; consumers that need complete canonical history still start at
+     * seq 0. Distinct from {@link inheritedEventCount}, the DURABLE
      * fork-lineage cut: a resumed session's constructor seed is its full stored
      * log, while the inherited count keeps the original fork value — this field is the
      * in-process construction fact.
@@ -377,22 +372,23 @@ export class Session {
         return new Session(id, seed, header, 'snapshot', inheritedEventCount);
     }
     /**
-     * Restore a detached session by taking ownership of fresh persistence values.
-     * The storage format, event envelopes, sequence continuity, surface transitions,
-     * and header fields are validated before the restored objects are frozen.
+     * Restore a detached session by adopting an independently owned or deeply frozen seed.
+     * Runtime-required event fields, event envelopes, sequence continuity, surface
+     * transitions, and header fields are validated without copying or freezing events.
+     * Embedded Assistant streams remain opaque until a stream consumer or storage
+     * verifier reads them.
      * @param id - restored session identity.
-     * @param seed - fresh detached events whose ownership is transferred.
-     * @param header - fresh detached metadata whose ownership is transferred.
+     * @param seed - independently owned or deeply frozen events.
+     * @param header - independently owned storage metadata.
      * @param inheritedEventCount - exact fork-inherited prefix length decoded from storage.
+     * @param eventState - aliasing state carried from the operation that produced the seed.
      * @returns a restored detached session.
      */
-    static fromRestore(id, seed, header, inheritedEventCount) {
-        return new Session(id, seed, header, 'restore', inheritedEventCount);
+    static fromRestore(id, seed, header, inheritedEventCount, eventState) {
+        return new Session(id, seed, header, eventState, inheritedEventCount);
     }
     constructor(id, seed, header, mode = 'snapshot', suppliedInheritedEventCount) {
-        const restoredHeader = mode === 'restore'
-            ? validateRestoredSessionHeader(id, header)
-            : undefined;
+        const restoredHeader = mode === 'snapshot' ? undefined : validateRestoredSessionHeader(id, header);
         if (seed !== undefined) {
             // Validate the seed to the SAME invariants `append` enforces, so a
             // replay/fork (`ctx.sessions.create(id, { seed })`) cannot construct a
@@ -404,12 +400,11 @@ export class Session {
             for (const [index, source] of seed.entries()) {
                 // The seed is a persistence/replay boundary: validate and detach the
                 // complete event in one lossless-JSON pass.
-                const snapshot = mode === 'restore' ? source : snapshotJsonValue(source);
+                const snapshot = mode === 'snapshot' ? snapshotJsonValue(source) : source;
                 if (snapshot === undefined) {
                     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`);
                 }
@@ -422,7 +417,7 @@ export class Session {
                 catch (error) {
                     throw new Error(`invalid seed event at index ${index}: ${error instanceof Error ? error.message : 'invalid surface metadata'}`);
                 }
-                this.log.push(mode === 'restore' ? freezeRestoredObject(snapshot) : deepFreeze(snapshot));
+                this.log.push(mode === 'snapshot' ? deepFreeze(snapshot) : snapshot);
             }
         }
         this.firstLiveSeq = SessionLogOffset(this.log.length);
@@ -440,12 +435,17 @@ export class Session {
         if (inheritedEventCount > this.log.length) {
             throw new Error('session inherited event count exceeds its event log');
         }
+        if (mode === 'snapshot' && this.header.isSeeded && inheritedEventCount !== this.log.length) {
+            throw new Error('seeded session constructor seed must equal its inherited prefix');
+        }
         this.inheritedEventCount = inheritedEventCount;
-        // Appended here so the marker is already in `events` when a backend
-        // captures the creation seed: no load-time write. Re-marking is skipped
-        // because a cold session is resumed on first touch, so repeatedly opening
-        // one must not grow its log per open.
-        if (seed !== undefined && this.log.at(-1)?.type !== 'session/end-seed') {
+        // A fresh seeded child always owns one tagged marker at its inherited cut,
+        // even when the copied prefix already ends in an ancestor marker. Restore
+        // retains that durable marker and appends only the ordinary resume marker.
+        if (seed !== undefined && mode === 'snapshot' && this.header.isSeeded) {
+            this.append('session/end-seed', { inherited: true });
+        }
+        else if (seed !== undefined && this.log.at(-1)?.type !== 'session/end-seed') {
             this.append('session/end-seed', {});
         }
     }
@@ -510,7 +510,8 @@ export class Session {
      *   declare how it joins the surface, the sole source of derived model
      *   history) and
      *   rejected by the compiler for non-surface types like `turn/start` or
-     *   `assistant/chunk`.
+     *   `assistant/attempt`. Assistant messages embed their exact provider
+     *   stream and cannot cite top-level source events.
      * @returns the logged event — its assigned `seq`/`time` plus the SNAPSHOT of
      *   `data` that entered the log, so reading `event.data` back sees the logged
      *   value, never the caller's still-mutable input.
@@ -538,7 +539,6 @@ 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`);
@@ -688,8 +688,9 @@ export class SessionForkError extends Error {
 /**
  * In-memory session store (`ctx.sessions`).
  *
- * Persistence is intentionally not implemented here — persistence plugins
- * subscribe to `session/event` and flush on `session/flush` / dispose.
+ * Persistence is intentionally not implemented here — the agent lifecycle
+ * attaches a session-log writer to each published session's write handle;
+ * a session published outside that lifecycle persists nothing.
  */
 export class SessionStore extends Service {
     store = new Map();
@@ -750,10 +751,9 @@ export class SessionStore extends Service {
      *
      * @param id - the session id; omitted, the store mints `session-<n>`.
      * @param options - seed events and/or creation metadata for the header. With
-     *   `seedSource: 'persistence'`, metadata and events must be fresh detached
-     *   graphs whose ownership transfers to this call: they are validated and
-     *   frozen in place through {@link Session.fromRestore}, so the caller must
-     *   retain no mutable aliases.
+     *   `eventState`, every seed event is either independently owned or any
+     *   shared value is deeply frozen; {@link Session.fromRestore} validates and
+     *   adopts those values without copying or freezing them.
      * @returns the constructed session, NOT yet in the store.
      * @throws if a session with `id` already exists, metadata is not a plain
      *   lossless-JSON record with valid scalar fields, or `meta.cwd` is a
@@ -771,8 +771,18 @@ export class SessionStore extends Service {
         }
         if (this.store.has(sessionId))
             throw new Error(`session "${sessionId}" already exists`);
-        if (options?.seedSource === 'persistence') {
-            return Session.fromRestore(sessionId, options.seed, options.meta, options.inheritedEventCount);
+        if (options !== undefined) {
+            const { eventState } = options;
+            switch (eventState) {
+                case 'detached':
+                case 'shared-frozen':
+                    return Session.fromRestore(sessionId, options.seed, options.meta, options.inheritedEventCount, eventState);
+                case undefined:
+                    break;
+                /* v8 ignore next -- closed-union exhaustiveness guard */
+                default:
+                    assertNever(eventState, 'SessionStore.prepare event state');
+            }
         }
         const seed = options?.seed;
         const meta = options?.meta;

package/lib/types/invariant.js

@@ -72,8 +72,8 @@ function validateEvent(trace, event, fail) {
             nextStep += 1;
             break;
         }
-        case 'assistant/chunk': {
-            requireOpenStep(trace, 'assistant/chunk', event.data.turn, event.data.step, fail);
+        case 'assistant/attempt': {
+            requireOpenStep(trace, 'assistant/attempt', event.data.turn, event.data.step, fail);
             break;
         }
         case 'assistant/message': {

package/lib/types/known-event-types.js

@@ -24,7 +24,7 @@ export const KNOWN_SESSION_EVENT_TYPES = new Set([
     'approval/asked',
     'approval/decided',
     'approval/policy',
-    'assistant/chunk',
+    'assistant/attempt',
     'assistant/message',
     'command/done',
     'command/run',
@@ -32,6 +32,8 @@ export const KNOWN_SESSION_EVENT_TYPES = new Set([
     'compaction/prune',
     'compaction/start',
     'compaction/summary',
+    'feedback/message-delete',
+    'feedback/message-put',
     'feedback/record',
     'goal/change',
     'hook/invoked',

package/lib/types/surface.d.ts

@@ -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

package/lib/types/surface.js

@@ -58,7 +58,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 +71,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
@@ -97,7 +97,7 @@ 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;
     }
@@ -153,13 +153,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) {