@deepseek-ai/dsh-session 0.0.1-rc.1

package/lib/types/invariant.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Package-owned relational invariants for the session event log. Load this
+ * companion beside `@deepseek-ai/dsh-invariants` to enable the checks.
+ *
+ * @module @deepseek-ai/dsh-session/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "session-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register the session invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/invariant.js

@@ -0,0 +1,199 @@
+/**
+ * Package-owned relational invariants for the session event log. Load this
+ * companion beside `@deepseek-ai/dsh-invariants` to enable the checks.
+ *
+ * @module @deepseek-ai/dsh-session/invariant
+ */
+import { assertNever } from '@deepseek-ai/dsh-llm';
+import { TOOL_NOT_STARTED } from "./repair.js";
+const PACKAGE_NAME = '@deepseek-ai/dsh-session';
+/** Cordis companion plugin name. */
+export const name = 'session-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/** Assert that a step-scoped event names the currently open turn and step. */
+function requireOpenStep(trace, kind, turn, step, fail) {
+    if (trace.openTurn !== turn || trace.openStep !== step) {
+        fail(`${kind} names turn ${turn}/step ${step} but open is turn ${trace.openTurn}/step ${trace.openStep}`);
+    }
+}
+/** Validate one candidate event without mutating the committed trace. */
+function validateEvent(trace, event, fail) {
+    if (event.seq <= trace.lastSeq) {
+        fail(`seq must strictly increase: saw ${event.seq} after ${trace.lastSeq}`);
+    }
+    let openTurn = trace.openTurn;
+    let openStep = trace.openStep;
+    let nextTurn = trace.nextTurn;
+    let nextStep = trace.nextStep;
+    let pendingCalls = { kind: 'none' };
+    // Context and plugin-owned log-only events may be appended between model
+    // executions. Core execution events retain their explicit turn relations.
+    switch (event.type) {
+        case 'turn/start': {
+            if (trace.openTurn !== null) {
+                fail(`turn/start ${event.data.turn} while turn ${trace.openTurn} is still open`);
+            }
+            if (event.data.turn !== trace.nextTurn) {
+                fail(`turn/start expected turn ${trace.nextTurn}, got ${event.data.turn}`);
+            }
+            openTurn = event.data.turn;
+            nextStep = 1;
+            break;
+        }
+        case 'turn/end': {
+            if (trace.openTurn !== event.data.turn) {
+                fail(`turn/end ${event.data.turn} does not match open turn ${trace.openTurn}`);
+            }
+            if (trace.openStep !== null) {
+                fail(`turn/end ${event.data.turn} while step ${trace.openStep} is still open`);
+            }
+            openTurn = null;
+            nextTurn += 1;
+            break;
+        }
+        case 'step/start': {
+            if (trace.openTurn !== event.data.turn) {
+                fail(`step/start in turn ${event.data.turn} but open turn is ${trace.openTurn}`);
+            }
+            if (trace.openStep !== null) {
+                fail(`step/start ${event.data.step} while step ${trace.openStep} is still open`);
+            }
+            if (event.data.step !== trace.nextStep) {
+                fail(`step/start expected step ${trace.nextStep} in turn ${event.data.turn}, got ${event.data.step}`);
+            }
+            openStep = event.data.step;
+            break;
+        }
+        case 'step/end': {
+            requireOpenStep(trace, 'step/end', event.data.turn, event.data.step, fail);
+            pendingCalls = { kind: 'clear' };
+            openStep = null;
+            nextStep += 1;
+            break;
+        }
+        case 'assistant/chunk': {
+            requireOpenStep(trace, 'assistant/chunk', event.data.turn, event.data.step, fail);
+            break;
+        }
+        case 'assistant/message': {
+            requireOpenStep(trace, 'assistant/message', event.data.turn, event.data.step, fail);
+            break;
+        }
+        case 'tool/call': {
+            requireOpenStep(trace, 'tool/call', event.data.turn, event.data.step, fail);
+            pendingCalls = { kind: 'add', callId: event.data.callId };
+            break;
+        }
+        case 'tool/result': {
+            // Session has already validated a content rewrite that cites its replaced event.
+            // It is durable turn work, not a second execution of the original call.
+            if (event.surfaceOp !== 'append') {
+                if (trace.openTurn === null) {
+                    fail('tool/result surface replacement appended outside any open turn');
+                }
+                break;
+            }
+            requireOpenStep(trace, 'tool/result', event.data.turn, event.data.step, fail);
+            const callId = event.data.message.source.callId;
+            const syntheticNotStarted = event.data.message.content[0].isError === true && event.data.error?.code === TOOL_NOT_STARTED;
+            if (!trace.pendingCalls.has(callId) && !syntheticNotStarted) {
+                fail(`tool/result for ${callId} with no prior tool/call in this step`);
+            }
+            pendingCalls = { kind: 'delete', callId };
+            break;
+        }
+        case 'user/message':
+            break;
+        case 'session/end-seed':
+            // Unconstrained: an unbalanced seed legally puts it inside an open turn.
+            break;
+        case 'todo/write':
+        case 'request/header':
+        case 'request/context': {
+            if (trace.openTurn === null) {
+                fail(`${event.type} appended outside any open turn (core execution events must be turn-enclosed)`);
+            }
+            break;
+        }
+        default:
+            // Merge-extensible event relations belong to their owning plugin.
+            break;
+    }
+    return {
+        scalars: { lastSeq: event.seq, openTurn, openStep, nextTurn, nextStep },
+        pendingCalls,
+    };
+}
+/** Apply one already-validated transition after its event commits. */
+function applyTransition(trace, transition) {
+    Object.assign(trace, transition.scalars);
+    switch (transition.pendingCalls.kind) {
+        case 'none':
+            break;
+        case 'add':
+            trace.pendingCalls.add(transition.pendingCalls.callId);
+            break;
+        case 'delete':
+            trace.pendingCalls.delete(transition.pendingCalls.callId);
+            break;
+        case 'clear':
+            trace.pendingCalls.clear();
+            break;
+        /* v8 ignore next -- validateEvent produces this closed transition union */
+        default:
+            assertNever(transition.pendingCalls, 'session trace pending-call transition');
+    }
+}
+/** Install the session contribution into its child registration fiber. */
+const install = Object.assign((ctx, fail) => {
+    const traces = new WeakMap();
+    const stagedTransitions = new WeakMap();
+    const freshTrace = () => ({
+        lastSeq: -1,
+        openTurn: null,
+        openStep: null,
+        nextTurn: 1,
+        nextStep: 1,
+        pendingCalls: new Set(),
+    });
+    const seedSession = (session) => {
+        const trace = freshTrace();
+        traces.set(session, trace);
+        for (const event of session.events) {
+            applyTransition(trace, validateEvent(trace, event, fail));
+        }
+        return trace;
+    };
+    /* v8 ignore next -- session/event always follows list() or session/created seeding */
+    const traceFor = (session) => traces.get(session) ?? seedSession(session);
+    for (const session of ctx.sessions.list())
+        seedSession(session);
+    ctx.on('session/created', (session) => { seedSession(session); }, { global: true });
+    ctx.on('session/event', (session, event) => {
+        const staged = stagedTransitions.get(event);
+        /* v8 ignore next 2 -- internal/dispatch stages the exact callback arguments */
+        if (staged === undefined || staged.session !== session) {
+            return fail('session/event reached publication without matching pre-commit validation');
+        }
+        stagedTransitions.delete(event);
+        applyTransition(staged.trace, staged.transition);
+    }, { global: true });
+    ctx.on('internal/dispatch', (_mode, eventName, args) => {
+        if (eventName !== 'session/event')
+            return;
+        const [session, event] = args;
+        const trace = traceFor(session);
+        const transition = validateEvent(trace, event, fail);
+        // A later dispatch listener may veto. Validation is pure, so abandoning
+        // this weakly keyed transition does not advance or retain the session.
+        stagedTransitions.set(event, { session, trace, transition });
+    }, { global: true });
+}, { inject: ['sessions'] });
+/**
+ * Register the session invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//# sourceMappingURL=invariant.js.map

package/lib/types/json.d.ts

@@ -0,0 +1,36 @@
+/** 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

@@ -0,0 +1,174 @@
+/** 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

package/lib/types/preparation.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Ownership of one unpublished Session before registry publication.
+ * @module @deepseek-ai/dsh-session/preparation
+ */
+import type { Session } from './index.ts';
+/** Options for a preparation whose provider retains unpublished state. */
+export interface SessionPreparationOptions {
+    /** Release provider-owned state when the Session was not published. */
+    readonly release?: () => void;
+}
+/**
+ * One exact unpublished Session and the provider state that keeps it usable.
+ * Disposal is synchronous and idempotent. Providers decide whether release
+ * returns the Session to a cache or discards it; publication may consume that
+ * state before disposal, making the callback a no-op.
+ */
+export declare class SessionPreparation implements Disposable {
+    private readonly options;
+    private released;
+    /** The exact Session to use for setup and publication. */
+    readonly session: Session;
+    private constructor();
+    /**
+     * Wrap an unpublished Session in one preparation lifetime.
+     * @param session - exact unpublished Session.
+     * @param options - optional provider release behavior.
+     * @returns a preparation disposed after publication or rollback.
+     */
+    static create(session: Session, options?: SessionPreparationOptions): SessionPreparation;
+    /** Release provider state once when this preparation leaves its caller. */
+    [Symbol.dispose](): void;
+}
+//# sourceMappingURL=preparation.d.ts.map

package/lib/types/preparation.js

@@ -0,0 +1,37 @@
+/**
+ * Ownership of one unpublished Session before registry publication.
+ * @module @deepseek-ai/dsh-session/preparation
+ */
+/**
+ * One exact unpublished Session and the provider state that keeps it usable.
+ * Disposal is synchronous and idempotent. Providers decide whether release
+ * returns the Session to a cache or discards it; publication may consume that
+ * state before disposal, making the callback a no-op.
+ */
+export class SessionPreparation {
+    options;
+    released = false;
+    /** The exact Session to use for setup and publication. */
+    session;
+    constructor(session, options) {
+        this.options = options;
+        this.session = session;
+    }
+    /**
+     * Wrap an unpublished Session in one preparation lifetime.
+     * @param session - exact unpublished Session.
+     * @param options - optional provider release behavior.
+     * @returns a preparation disposed after publication or rollback.
+     */
+    static create(session, options) {
+        return new SessionPreparation(session, options ?? {});
+    }
+    /** Release provider state once when this preparation leaves its caller. */
+    [Symbol.dispose]() {
+        if (this.released)
+            return;
+        this.released = true;
+        this.options.release?.();
+    }
+}
+//# sourceMappingURL=preparation.js.map

package/lib/types/repair.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Crash-recovery repair for an interrupted session log. It preserves a fully
+ * written final turn and supplies the missing tool, step, and turn boundaries
+ * needed to resume with a provider-valid transcript, plus the activity-time
+ * read that must skip the end-seed boundary — which this module does
+ * not write (`Session`'s constructor does) but whose synthetic closers can
+ * inherit that boundary's timestamp, the one real coupling between the two.
+ * @module @deepseek-ai/dsh-session/repair
+ */
+import type { SessionEvent } from './types.ts';
+/**
+ * The `time` of the log's last event representing actual work, skipping the
+ * `session/end-seed` boundary — picking a session up is not activity, so
+ * activity ordering must exclude it.
+ *
+ * Excluded by type, so a pickup time still leaks when a boundary is the last
+ * event of an open turn: {@link interruptedTurnClosers} copies it onto the
+ * synthetic `turn/end`, which this counts as work. Reachable only by seeding an
+ * unbalanced log directly — `load()` balances first.
+ * @param events - the log to scan, in seq order.
+ * @returns the latest non-boundary event's `time`, or undefined when there is none.
+ */
+export declare function lastActivityTime(events: readonly SessionEvent[]): number | undefined;
+/** Recovery code for an assistant tool request that never reached a recorded call start. */
+export declare const TOOL_NOT_STARTED = "TOOL_NOT_STARTED";
+/** Recovery code for a recorded tool call whose completed outcome was not durably recorded. */
+export declare const TOOL_OUTCOME_UNKNOWN = "TOOL_OUTCOME_UNKNOWN";
+/**
+ * Return deterministic synthetic events that close an open tail turn. Unmatched
+ * calls receive error results first, followed by an open `step/end` and an
+ * interrupted `turn/end`; sequences continue the log and timestamps reuse the
+ * last real event. A balanced or empty log returns no events.
+ *
+ * @param events - the loaded durable log to scan (a valid committed prefix, possibly with a crash tail).
+ * @returns the synthetic closer events to append after `events`, in order; empty when the log is already balanced.
+ */
+export declare function interruptedTurnClosers(events: readonly SessionEvent[]): SessionEvent[];
+//# sourceMappingURL=repair.d.ts.map