@deepseek-ai/dsh-session 0.1.1-rc.2 → 0.1.2-alpha.2

package/lib/types/known-event-types.d.ts

@@ -12,8 +12,11 @@
  * in `./types.ts`): such a log was likely written by a newer harness, and
  * silently skipping a required event would reconstruct a wrong session.
  * Downstream (out-of-repo) plugin events are outside this list by
- * construction; a registration surface for them is deferred until such a
- * consumer exists.
+ * construction. The persisted `SessionEvent.ignorable` marker is the
+ * compatibility mechanism; event-name registration was rejected because
+ * it does not classify omission safety and would make reads
+ * composition-dependent. The rationale is in
+ * `.agents/notes/implemented/architecture/2026-08-30-retain-ignorable-external-session-events.md`.
  */
 export declare const KNOWN_SESSION_EVENT_TYPES: ReadonlySet<string>;
 //# sourceMappingURL=known-event-types.d.ts.map

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

@@ -12,8 +12,11 @@
  * in `./types.ts`): such a log was likely written by a newer harness, and
  * silently skipping a required event would reconstruct a wrong session.
  * Downstream (out-of-repo) plugin events are outside this list by
- * construction; a registration surface for them is deferred until such a
- * consumer exists.
+ * construction. The persisted `SessionEvent.ignorable` marker is the
+ * compatibility mechanism; event-name registration was rejected because
+ * it does not classify omission safety and would make reads
+ * composition-dependent. The rationale is in
+ * `.agents/notes/implemented/architecture/2026-08-30-retain-ignorable-external-session-events.md`.
  */
 export const KNOWN_SESSION_EVENT_TYPES = new Set([
     'agent-preset/selected',
@@ -35,18 +38,21 @@ export const KNOWN_SESSION_EVENT_TYPES = new Set([
     'hook/result',
     'llm/retry',
     'llm/retry-started',
+    'model/selection',
     'permission/preset',
     'plan/mode',
     'request/context',
     'request/header',
     'sandbox/mode',
     'schedule/change',
+    'session-log-deepseek/delivery-accepted',
     'session/end-seed',
     'session/title',
     'session/title-llm-request',
     'step/end',
     'step/start',
     'subagent/descriptor',
+    'subagent/model-selection-policy',
     'team/member',
     'team/message/delivered',
     'team/message/queued',

package/lib/types/repair.js

@@ -4,7 +4,8 @@
  * needed to resume with a provider-valid transcript.
  * @module @deepseek-ai/dsh-session/repair
  */
-import { MessageId, freezeMessage } from '@deepseek-ai/dsh-llm';
+import { brandString } from '@deepseek-ai/dsh-brand';
+import { deepFreeze } from '@deepseek-ai/dsh-util-values';
 /** Recovery code for an assistant tool request that never reached a recorded call start. */
 export const TOOL_NOT_STARTED = 'TOOL_NOT_STARTED';
 /** Recovery code for a recorded tool call whose completed outcome was not durably recorded. */
@@ -83,8 +84,8 @@ export function interruptedTurnClosers(events) {
     // and Map insertion order preserves their transcript order.
     for (const [callId, { step, callSeq }] of pendingCalls) {
         const started = callSeq !== undefined;
-        const message = freezeMessage({
-            id: MessageId(`interrupted-tool-result-${callId}-${seq}`),
+        const message = deepFreeze({
+            id: brandString(`interrupted-tool-result-${callId}-${seq}`),
             role: 'user',
             source: { kind: 'tool', callId },
             content: [{

package/lib/types/seq-ranges.d.ts

@@ -0,0 +1,17 @@
+/** Lossless range encoding for JSONL `sourceEventSeqs` arrays. */
+/** A stored source sequence or inclusive consecutive range. */
+export type EncodedSeq = number | [number, number];
+/**
+ * Replace profitable consecutive runs with inclusive pairs.
+ * @param values - validated in-memory source sequences.
+ * @returns a lossless JSON storage form.
+ */
+export declare function encodeSeqRanges(values: readonly number[]): EncodedSeq[];
+/**
+ * Expand a JSON storage-form source sequence array.
+ * @param value - parsed storage value.
+ * @param maxEntries - largest list permitted by the owning event.
+ * @returns the in-memory source sequences.
+ */
+export declare function decodeSeqRanges(value: unknown, maxEntries?: number): number[];
+//# sourceMappingURL=seq-ranges.d.ts.map

package/lib/types/seq-ranges.js

@@ -0,0 +1,73 @@
+/** Lossless range encoding for JSONL `sourceEventSeqs` arrays. */
+function isStrictlyIncreasing(values) {
+    return values.every((value, index) => index === 0 || value > values[index - 1]);
+}
+/**
+ * Replace profitable consecutive runs with inclusive pairs.
+ * @param values - validated in-memory source sequences.
+ * @returns a lossless JSON storage form.
+ */
+export function encodeSeqRanges(values) {
+    if (!isStrictlyIncreasing(values))
+        return [...values];
+    const encoded = [];
+    for (let start = 0; start < values.length;) {
+        let end = start;
+        while (end + 1 < values.length && values[end + 1] === values[end] + 1)
+            end += 1;
+        if (end - start >= 2)
+            encoded.push([values[start], values[end]]);
+        else
+            for (let index = start; index <= end; index += 1)
+                encoded.push(values[index]);
+        start = end + 1;
+    }
+    return encoded;
+}
+/**
+ * Expand a JSON storage-form source sequence array.
+ * @param value - parsed storage value.
+ * @param maxEntries - largest list permitted by the owning event.
+ * @returns the in-memory source sequences.
+ */
+export function decodeSeqRanges(value, maxEntries = Number.MAX_SAFE_INTEGER) {
+    if (!Array.isArray(value))
+        throw new TypeError('sourceEventSeqs must be an array');
+    const decoded = [];
+    let hasRange = false;
+    for (const entry of value) {
+        if (typeof entry === 'number') {
+            assertSeq(entry);
+            if (decoded.length >= maxEntries)
+                throw new TypeError('sourceEventSeqs exceeds its event sequence');
+            decoded.push(entry);
+            continue;
+        }
+        if (!Array.isArray(entry) || entry.length !== 2) {
+            throw new TypeError('sourceEventSeqs range entries must be [start, end] pairs');
+        }
+        const start = entry[0];
+        const end = entry[1];
+        assertSeq(start);
+        assertSeq(end);
+        if (end < start)
+            throw new TypeError('sourceEventSeqs ranges require start <= end');
+        const length = end - start + 1;
+        if (length > maxEntries - decoded.length) {
+            throw new TypeError('sourceEventSeqs range exceeds its event sequence');
+        }
+        for (let seq = start; seq <= end; seq += 1)
+            decoded.push(seq);
+        hasRange = true;
+    }
+    if (hasRange && !isStrictlyIncreasing(decoded)) {
+        throw new TypeError('sourceEventSeqs ranges must be strictly increasing');
+    }
+    return decoded;
+}
+function assertSeq(value) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new TypeError('sourceEventSeqs must contain non-negative safe integers');
+    }
+}
+//# sourceMappingURL=seq-ranges.js.map

package/lib/types/types.d.ts

@@ -1,13 +1,12 @@
-import type { Branded } from '@deepseek-ai/dsh-brand';
-import type { AssistantMessage, CallId, LlmCallConfig, LlmCallConfigAdapterDefaults, LlmFailure, StreamChunk, TokenUsage, ToolResultMessage, ToolSchema, UserMessage } from '@deepseek-ai/dsh-llm';
-import type { JsonValue } from './json.ts';
-export type { JsonValue } from './json.ts';
+import { type Branded } from '@deepseek-ai/dsh-brand';
+import type { AssistantMessage, ToolCallId, LlmCallConfig, LlmCallConfigAdapterDefaults, LlmFailure, StreamChunk, 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'>;
 /**
  * Brand a string as a {@link SessionId}.
  * @param id - the raw session id string.
- * @returns the same string, branded (a compile-time cast — no runtime cost).
+ * @returns the same string with the session-id brand.
  */
 export declare function SessionId(id: string): SessionId;
 /**
@@ -167,22 +166,6 @@ 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];
-/**
- * One entry in an agent's todo list — the unit of the `todo/write`
- * {@link SessionEventMap} event's whole-list snapshot.
- *
- * Deliberately minimal: a human-readable `content` line and a three-state
- * `status`. No id, priority, or `activeForm` — the list is replaced wholesale
- * on every write (last-write-wins), so entries need no stable identity. The
- * three statuses describe the complete portable lifecycle needed by model and
- * UI consumers.
- */
-export interface TodoItem {
-    /** What this task is — a short imperative line shown in the UI. */
-    content: string;
-    /** Lifecycle state. `in_progress` marks a task being worked now; parallel work may mark several. */
-    status: 'pending' | 'in_progress' | 'completed';
-}
 /**
  * Logged request state outside derived history: call config, system prompt, and
  * tools. The latest full `request/header` snapshot reconstructs it; canonical
@@ -211,9 +194,11 @@ export interface RequestContext {
  * Why a `request/header` snapshot was appended: `'initial'` — the log's first
  * header (a new conversation); `'resume'` — a loop instance's first request
  * over a log that already has header events (process restart, fork seed);
- * `'change'` — a later request used a different header.
+ * `'change'` — a later request used a different header, with `startsSeries`
+ * preserving a coincident series boundary; `'series'` — an unchanged header
+ * began an explicitly distinct message series or followed a surface replacement.
  */
-export type RequestHeaderReason = 'initial' | 'resume' | 'change';
+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
@@ -291,7 +276,7 @@ export interface SessionEventMap {
     'tool/call': {
         turn: number;
         step: number;
-        callId: CallId;
+        callId: ToolCallId;
         name: string;
         arguments: string;
     };
@@ -316,10 +301,6 @@ export interface SessionEventMap {
         };
         meta?: JsonValue;
     };
-    /** Whole-list snapshot; latest write wins on replay. Log-only UI state; never derived history. */
-    'todo/write': {
-        todos: TodoItem[];
-    };
     /**
      * Full header for the next request, appended inside its step before dispatch.
      * It is log-only; the latest snapshot reconstructs the request header.
@@ -327,6 +308,8 @@ export interface SessionEventMap {
     'request/header': {
         header: EpochHeader;
         reason: RequestHeaderReason;
+        /** A changed header also begins a distinct model-message series. */
+        startsSeries?: true;
     };
     /**
      * Route metadata for the next request, logged only when the route or capacity
@@ -455,4 +438,12 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
         surfaceOp?: SurfaceOp;
     } : object);
 }[T];
+declare module '@deepseek-ai/dsh-typert-protocol' {
+    interface RemoteErrorDetailsMap {
+        /** The named Session does not exist; produced by every layer that resolves a SessionId. */
+        'session/not-found': {
+            readonly sessionId: SessionId;
+        };
+    }
+}
 //# sourceMappingURL=types.d.ts.map

package/lib/types/types.js

@@ -1,10 +1,11 @@
+import { brandString } from '@deepseek-ai/dsh-brand';
 /**
  * Brand a string as a {@link SessionId}.
  * @param id - the raw session id string.
- * @returns the same string, branded (a compile-time cast — no runtime cost).
+ * @returns the same string with the session-id brand.
  */
 export function SessionId(id) {
-    return id;
+    return brandString(id);
 }
 /**
  * The on-disk session format version, stamped into every newly-written {@link SessionHeader}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-session",
   "description": "Event-sourced session store for the DeepSeek Harness",
-  "version": "0.1.1-rc.2",
+  "version": "0.1.2-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -26,6 +26,10 @@
       "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": {
@@ -41,20 +45,19 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-brand": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-llm": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-scope": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-typert-protocol": "^0.1.1-rc.2",
-    "@deepseek-ai/cordis": "^4.0.1"
+    "@deepseek-ai/dsh-scope": "^0.1.2-alpha.2",
+    "@deepseek-ai/cordis": "^4.0.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-llm": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-scope": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-typert-protocol": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-typert-registry": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-brand": "^0.1.1-rc.2",
-    "@deepseek-ai/cordis": "^4.0.1"
+    "@deepseek-ai/dsh-scope": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-typert-protocol": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.2",
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-typert-registry": "^0.1.2-alpha.2"
+  },
+  "dependencies": {
+    "@deepseek-ai/dsh-llm": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-brand": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-util-values": "^0.1.2-alpha.2"
   }
 }

package/lib/types/json.d.ts

@@ -1,36 +0,0 @@
-/** Lossless-JSON validation and detached snapshots for durable session data. @module @deepseek-ai/dsh-session/json */
-/**
- * A value that round-trips losslessly through JSON: `null`, a boolean, a finite
- * number other than negative zero, a string, an array of such values, or a
- * plain object whose values are such values. Arrays may carry only their dense
- * indexed elements; extra own properties would be discarded by JSON. TypeScript
- * cannot distinguish `-0` from `number`, so {@link isJsonValue} and
- * {@link snapshotJsonValue} enforce these details at runtime. Use this type for
- * a payload that must survive session-log persistence and replay byte-identically
- * — e.g. a tool's private presentation `meta`.
- */
-export type JsonValue = null | boolean | number | string | JsonValue[] | {
-    [key: string]: JsonValue;
-};
-/**
- * Validate and detach lossless JSON in one read per property, so a stateful
- * getter cannot change between validation and copying. Traversal is iterative,
- * so valid nesting is bounded by available memory rather than the JavaScript
- * call stack. Accepts ordinary arrays, plain or null-prototype objects, and JSON
- * scalars; rejects sparse, cyclic, exotic, negative-zero, and non-finite values.
- * Getter throws propagate.
- *
- * @param value - the candidate value to validate and detach.
- * @returns the detached snapshot, or `undefined` when the value is not
- *   losslessly JSON-serializable.
- */
-export declare function snapshotJsonValue<T>(value: T): T | undefined;
-/**
- * Test the same lossless JSON boundary as {@link snapshotJsonValue} without
- * detaching it. Only own enumerable string properties participate; `toJSON`
- * is ignored and getters run, so persistence boundaries use the snapshotter.
- * @param value - the candidate event data to test.
- * @returns whether `value` survives JSON round-trip losslessly.
- */
-export declare function isJsonValue(value: unknown): boolean;
-//# sourceMappingURL=json.d.ts.map

package/lib/types/json.js

@@ -1,174 +0,0 @@
-/** Lossless-JSON validation and detached snapshots for durable session data. @module @deepseek-ai/dsh-session/json */
-/** Whether a realm-owned intrinsic prototype is backed by its native constructor. */
-function hasIntrinsicConstructor(prototype, name) {
-    const descriptor = Object.getOwnPropertyDescriptor(prototype, 'constructor');
-    const constructor = descriptor?.value;
-    if (typeof constructor !== 'function')
-        return false;
-    try {
-        return constructor.name === name
-            && constructor.prototype === prototype
-            && Function.prototype.toString.call(constructor) === `function ${name}() { [native code] }`;
-    }
-    catch {
-        return false;
-    }
-}
-/** Whether a candidate is one realm's intrinsic `Object.prototype`. */
-function isIntrinsicObjectPrototype(value) {
-    return Object.getPrototypeOf(value) === null && hasIntrinsicConstructor(value, 'Object');
-}
-/** Whether an array uses one realm's intrinsic `Array.prototype`, not a subclass or forged prototype. */
-function hasPlainArrayPrototype(value) {
-    const prototype = Object.getPrototypeOf(value);
-    if (!Array.isArray(prototype) || !hasIntrinsicConstructor(prototype, 'Array'))
-        return false;
-    const objectPrototype = Object.getPrototypeOf(prototype);
-    return typeof objectPrototype === 'object'
-        && objectPrototype !== null
-        && isIntrinsicObjectPrototype(objectPrototype);
-}
-/** Whether an object is a plain or null-prototype record from any JavaScript realm. */
-function hasPlainObjectPrototype(value) {
-    const prototype = Object.getPrototypeOf(value);
-    return prototype === null
-        || typeof prototype === 'object' && isIntrinsicObjectPrototype(prototype);
-}
-/** Return every JSON-visible object key, or reject own data JSON would discard. */
-function enumerableStringKeys(value) {
-    const keys = Reflect.ownKeys(value);
-    if (keys.some(key => typeof key !== 'string' || !Object.prototype.propertyIsEnumerable.call(value, key)))
-        return undefined;
-    return keys;
-}
-/** Validate lossless JSON iteratively, optionally materializing a detached snapshot. */
-function walkJsonValue(value, detach) {
-    const ancestors = new Set();
-    let root;
-    const assign = (destination, item) => {
-        if (destination === undefined)
-            return;
-        if (destination.kind === 'root') {
-            root = item;
-        }
-        else if (destination.kind === 'array') {
-            destination.target[destination.index] = item;
-        }
-        else {
-            Object.defineProperty(destination.target, destination.key, {
-                value: item,
-                enumerable: true,
-                configurable: true,
-                writable: true,
-            });
-        }
-    };
-    const tasks = [{
-            kind: 'visit',
-            value,
-            ...(detach ? { destination: { kind: 'root' } } : {}),
-        }];
-    for (let task = tasks.pop(); task !== undefined; task = tasks.pop()) {
-        if (task.kind === 'leave') {
-            ancestors.delete(task.source);
-            continue;
-        }
-        if (task.kind === 'array-item') {
-            if (!Object.prototype.hasOwnProperty.call(task.source, task.index))
-                return undefined;
-            tasks.push({
-                kind: 'visit',
-                value: task.source[task.index],
-                ...(task.target === undefined ? {} : { destination: { kind: 'array', target: task.target, index: task.index } }),
-            });
-            continue;
-        }
-        if (task.kind === 'object-property') {
-            tasks.push({
-                kind: 'visit',
-                value: task.source[task.key],
-                ...(task.target === undefined ? {} : { destination: { kind: 'object', target: task.target, key: task.key } }),
-            });
-            continue;
-        }
-        const current = task.value;
-        if (current === null) {
-            assign(task.destination, null);
-            continue;
-        }
-        if (typeof current === 'boolean' || typeof current === 'string') {
-            assign(task.destination, current);
-            continue;
-        }
-        if (typeof current === 'number') {
-            if (!Number.isFinite(current) || Object.is(current, -0))
-                return undefined;
-            assign(task.destination, current);
-            continue;
-        }
-        if (typeof current !== 'object')
-            return undefined;
-        if (ancestors.has(current))
-            return undefined;
-        if (Array.isArray(current)) {
-            if (!hasPlainArrayPrototype(current))
-                return undefined;
-            const length = current.length;
-            if (Reflect.ownKeys(current).length !== length + 1)
-                return undefined;
-            const target = detach ? [] : undefined;
-            if (target !== undefined)
-                assign(task.destination, target);
-            ancestors.add(current);
-            tasks.push({ kind: 'leave', source: current });
-            for (let index = length - 1; index >= 0; index--) {
-                tasks.push({ kind: 'array-item', source: current, index, ...(target === undefined ? {} : { target }) });
-            }
-            continue;
-        }
-        if (!hasPlainObjectPrototype(current))
-            return undefined;
-        const keys = enumerableStringKeys(current);
-        if (keys === undefined)
-            return undefined;
-        const target = detach ? {} : undefined;
-        if (target !== undefined)
-            assign(task.destination, target);
-        ancestors.add(current);
-        tasks.push({ kind: 'leave', source: current });
-        for (let index = keys.length - 1; index >= 0; index--) {
-            const key = keys[index];
-            /* v8 ignore next -- the loop is bounded by the captured key count. */
-            if (key === undefined)
-                return undefined;
-            tasks.push({ kind: 'object-property', source: current, key, ...(target === undefined ? {} : { target }) });
-        }
-    }
-    return detach ? root : true;
-}
-/**
- * Validate and detach lossless JSON in one read per property, so a stateful
- * getter cannot change between validation and copying. Traversal is iterative,
- * so valid nesting is bounded by available memory rather than the JavaScript
- * call stack. Accepts ordinary arrays, plain or null-prototype objects, and JSON
- * scalars; rejects sparse, cyclic, exotic, negative-zero, and non-finite values.
- * Getter throws propagate.
- *
- * @param value - the candidate value to validate and detach.
- * @returns the detached snapshot, or `undefined` when the value is not
- *   losslessly JSON-serializable.
- */
-export function snapshotJsonValue(value) {
-    return walkJsonValue(value, true);
-}
-/**
- * Test the same lossless JSON boundary as {@link snapshotJsonValue} without
- * detaching it. Only own enumerable string properties participate; `toJSON`
- * is ignored and getters run, so persistence boundaries use the snapshotter.
- * @param value - the candidate event data to test.
- * @returns whether `value` survives JSON round-trip losslessly.
- */
-export function isJsonValue(value) {
-    return walkJsonValue(value, false) === true;
-}
-//# sourceMappingURL=json.js.map