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

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, 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 = 2;
 /**
  * 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';
@@ -229,8 +235,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,12 +278,6 @@ export interface SessionEventMap {
      * project their `content` verbatim; `source` tells them apart.
      */
     'user/message': UserMessage;
-    /** Raw stream chunk — token-level replay fidelity. */
-    'assistant/chunk': {
-        turn: number;
-        step: number;
-        chunk: StreamChunk;
-    };
     /**
      * Assembled assistant message for one step (derived history uses this).
      * Carries the step's `usage` when the adapter reported token accounting, so
@@ -292,9 +292,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
@@ -347,12 +359,12 @@ export interface SessionEventMap {
      * 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,14 +377,17 @@ 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}; user and tool events may also cite
+ * earlier sources through {@link SessionEvent.sourceEventSeqs}.
  */
 export type SurfaceEventType = 'user/message' | 'assistant/message' | 'tool/result';
 /**
@@ -409,16 +424,15 @@ export type SurfaceOp = 'append' | {
  * 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' ? {
+    /** V2 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.
  *
@@ -428,7 +442,7 @@ export interface SurfaceIntent {
  * The {@link sourceEventSeqs} and {@link surfaceOp} fields are conditional:
  * they only exist on {@link SurfaceEventType} variants (`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.
  */
@@ -453,12 +467,9 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
         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.
+         * Seq numbers of earlier events that this event cites as sources, such as
+         * the surface nodes shadowed by a compaction replacement. A v2
+         * `assistant/message` embeds its provider stream and cannot carry this field.
          */
         sourceEventSeqs?: SessionSeq[];
         /** How this event entered the surface; absent for non-surface events. */

package/lib/types/types.js

@@ -30,11 +30,11 @@ export function SessionLogOffset(value) {
     return brandNumber(value);
 }
 /**
- * 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,10 +47,9 @@ export function SessionLogOffset(value) {
  * 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 const SESSION_FORMAT_VERSION = 0;
+export const SESSION_FORMAT_VERSION = 2;
 //# sourceMappingURL=types.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-session",
   "description": "Event-sourced session store for the DeepSeek Harness",
-  "version": "0.1.2-alpha.5",
+  "version": "0.1.3-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -26,10 +26,6 @@
       "types": "./lib/types/types.d.ts",
       "default": "./lib/types/types.js"
     },
-    "./chunk-rows": {
-      "types": "./lib/types/chunk-rows.d.ts",
-      "default": "./lib/types/chunk-rows.js"
-    },
     "./src/*": "./src/*",
     "./package.json": "./package.json",
     "./surface": {
@@ -45,19 +41,19 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-scope": "^0.1.2-alpha.5",
+    "@deepseek-ai/dsh-scope": "^0.1.3-alpha.2",
     "@deepseek-ai/cordis": "^4.0.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.5",
-    "@deepseek-ai/dsh-scope": "^0.1.2-alpha.5",
-    "@deepseek-ai/dsh-typert-protocol": "^0.1.2-alpha.5",
-    "@deepseek-ai/dsh-typert-registry": "^0.1.2-alpha.5",
+    "@deepseek-ai/dsh-scope": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-typert-protocol": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-typert-registry": "^0.1.3-alpha.2",
     "@deepseek-ai/cordis": "^4.0.2"
   },
   "dependencies": {
-    "@deepseek-ai/dsh-brand": "^0.1.2-alpha.5",
-    "@deepseek-ai/dsh-util-values": "^0.1.2-alpha.5",
-    "@deepseek-ai/dsh-llm": "^0.1.2-alpha.5"
+    "@deepseek-ai/dsh-llm": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-brand": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-util-values": "^0.1.3-alpha.2"
   }
 }

package/lib/types/chunk-rows.d.ts

@@ -1,106 +0,0 @@
-/**
- * Lossless row packing for `assistant/chunk` delta runs. Providers stream
- * token-sized deltas, so a log stores hundreds of near-identical event lines
- * whose JSON envelopes dwarf their payloads (~56× measured on a real DeepSeek
- * session). This module packs each run of consecutive same-block delta chunks
- * into ONE storage row — `text-chunks`, `reasoning-chunks`, or
- * `tool-call-chunks` — and expands rows back to the exact original events.
- *
- * Packed rows are an encoding vocabulary, NOT session events: they never enter
- * `Session.snapshotEvents()`, have no `SessionEventMap` entry, and use bare (slash-less)
- * type tags so a reader cannot confuse them with the event taxonomy
- * (precedent: the JSONL header line's `session` tag). Persistence and bounded
- * history transport both use the codec. The encoder whitelists exact shapes —
- * anything it does not fully recognize stays verbatim, so unknown fields or
- * future chunk variants lose compression, never data. The decoder validates
- * before expanding and fails loud on a malformed row-tagged value instead of
- * silently dropping a whole run.
- *
- * @module @deepseek-ai/dsh-session/chunk-rows
- */
-import type { ToolCallId } from '@deepseek-ai/dsh-llm/brand';
-import type { SessionEvent, SessionSeq as SessionSeqType } from './types.ts';
-/**
- * Fields shared by every packed run: placement, block correlation, and member
- * timestamps as gaps. Member `k` reconstructs as seq `seq0 + k` and time
- * `time0` plus the first `k` gaps; a gap may be negative when the wall clock
- * stepped backwards between events.
- */
-interface RunDataBase {
-    turn: number;
-    step: number;
-    /** The stream block index every member shares. */
-    index: number;
-    /** Epoch-ms gaps between consecutive members; length is one less than the member count. */
-    dt: number[];
-}
-/** Payload of a `text-chunks`/`reasoning-chunks` row: one entry per member, never joined — token boundaries are data. */
-interface TextRunData extends RunDataBase {
-    texts: string[];
-}
-/** Payload of a `tool-call-chunks` row: the run-constant call identity plus each member's raw arguments fragment. */
-interface ToolCallRunData extends RunDataBase {
-    id: ToolCallId;
-    /** Present iff every member carried it, with one uniform value (a mixed run never packs). */
-    name?: string;
-    args: string[];
-}
-/**
- * A packed run of consecutive delta chunk events, discriminated on `type`.
- * `seq0`/`time0` anchor the first member; text and reasoning rows share the
- * {@link TextRunData} payload, tool-call rows carry {@link ToolCallRunData}.
- */
-export type ChunkRow = {
-    type: 'text-chunks';
-    seq0: SessionSeqType;
-    time0: number;
-    data: TextRunData;
-} | {
-    type: 'reasoning-chunks';
-    seq0: SessionSeqType;
-    time0: number;
-    data: TextRunData;
-} | {
-    type: 'tool-call-chunks';
-    seq0: SessionSeqType;
-    time0: number;
-    data: ToolCallRunData;
-};
-/** One durable log line's JSON value: a session event verbatim, or a packed chunk row. */
-export type StorageRecord = SessionEvent | ChunkRow;
-/**
- * Test whether an encoded record is a packed chunk row rather than a Session event.
- * @param record - one persistence or bounded-history encoding record.
- * @returns Whether the record is a packed chunk row.
- */
-export declare function isChunkRow(record: StorageRecord): record is ChunkRow;
-/**
- * Number of logical Session events represented by one packed row.
- * @param row - validated or encoder-produced packed row.
- * @returns Count of consecutive chunk events in the row.
- */
-export declare function chunkRowLength(row: ChunkRow): number;
-/**
- * Pack an event batch for storage: each run of at least {@link MIN_RUN}
- * consecutive whitelisted same-kind, same-block delta chunk events becomes one
- * {@link ChunkRow}; every other event passes through verbatim, in order.
- * Pure and stateless — safe over any array, including a batch whose runs were
- * split by flush boundaries (the split runs simply pack per batch).
- *
- * @param events - the batch to encode, in log order.
- * @returns the storage records to write, one JSONL line each.
- */
-export declare function packChunkRuns(events: readonly SessionEvent[]): StorageRecord[];
-/**
- * Decode one parsed JSONL line value into the session event(s) it stores.
- * Chunk-row-tagged values validate and expand (a malformed row throws — it is
- * corrupt storage, and treating it as an event would silently drop a whole
- * run); every other value passes through as a single event after admitting a
- * numeric `seq` through the Session-sequence constructor.
- *
- * @param value - one line's `JSON.parse` result.
- * @returns the stored events, in log order.
- */
-export declare function decodeStorageRecord(value: unknown): SessionEvent[];
-export {};
-//# sourceMappingURL=chunk-rows.d.ts.map