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

package/lib/invariant.js

@@ -0,0 +1,168 @@
+import { assertNever } from "@deepseek-ai/dsh-llm";
+//#endregion
+//#region lib/types/invariant.js
+/**
+* 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
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-session";
+/** Cordis companion plugin name. */
+const name = "session-invariant";
+/** Service required before the companion can reserve package ownership. */
+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" };
+	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": {
+			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": 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: 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 = /* @__PURE__ */ new WeakMap();
+	const stagedTransitions = /* @__PURE__ */ new WeakMap();
+	const freshTrace = () => ({
+		lastSeq: -1,
+		openTurn: null,
+		openStep: null,
+		nextTurn: 1,
+		nextStep: 1,
+		pendingCalls: /* @__PURE__ */ 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 === void 0 || 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);
+		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.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

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

@@ -0,0 +1,92 @@
+/**
+ * Lossless storage 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.
+ *
+ * Storage rows are a durable-encoding vocabulary, NOT session events: they
+ * never enter `Session.events`, 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). The encoder
+ * whitelists exact shapes — anything it does not fully recognize is stored
+ * 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 { CallId } from '@deepseek-ai/dsh-llm';
+import type { SessionEvent } 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: CallId;
+    /** 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: number;
+    time0: number;
+    data: TextRunData;
+} | {
+    type: 'reasoning-chunks';
+    seq0: number;
+    time0: number;
+    data: TextRunData;
+} | {
+    type: 'tool-call-chunks';
+    seq0: number;
+    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;
+/**
+ * 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, unvalidated.
+ *
+ * @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

package/lib/types/chunk-rows.js

@@ -0,0 +1,301 @@
+/**
+ * Lossless storage 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.
+ *
+ * Storage rows are a durable-encoding vocabulary, NOT session events: they
+ * never enter `Session.events`, 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). The encoder
+ * whitelists exact shapes — anything it does not fully recognize is stored
+ * 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 { CallId, assertNever } from '@deepseek-ai/dsh-llm';
+/**
+ * Minimum members before a run packs. Below it a row's envelope rivals the
+ * event lines it replaces. A format constant, not a tunable: both layouts
+ * decode identically, so changing it never invalidates stored logs.
+ */
+const MIN_RUN = 3;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+/** Exact-key check: `value` has every key in `keys` and nothing else. */
+function hasExactKeys(value, keys) {
+    return Object.keys(value).length === keys.length && keys.every(k => Object.hasOwn(value, k));
+}
+/**
+ * Classify an event for packing: its delta kind when the ENTIRE shape
+ * (envelope, data, chunk — exact keys, primitive types, integer seq/time) is
+ * whitelisted, else `undefined` (store verbatim). Inputs come from live typed
+ * appends AND parsed fixture files, so the checks are structural, not
+ * type-trusted. Integer times keep gap encoding exact: a fractional time would
+ * reconstruct through float subtraction/addition, which need not round-trip.
+ */
+function classify(event) {
+    if (event.type !== 'assistant/chunk')
+        return undefined;
+    if (!hasExactKeys(event, ['type', 'seq', 'time', 'data']))
+        return undefined;
+    if (!Number.isSafeInteger(event.seq) || event.seq < 0 || !Number.isSafeInteger(event.time))
+        return undefined;
+    const data = event.data;
+    if (!isRecord(data) || !hasExactKeys(data, ['turn', 'step', 'chunk']))
+        return undefined;
+    if (typeof data.turn !== 'number' || typeof data.step !== 'number')
+        return undefined;
+    const chunk = data.chunk;
+    if (!isRecord(chunk) || typeof chunk.index !== 'number')
+        return undefined;
+    switch (chunk.type) {
+        case 'text-delta':
+        case 'reasoning-delta':
+            return hasExactKeys(chunk, ['type', 'index', 'text']) && typeof chunk.text === 'string'
+                ? chunk.type
+                : undefined;
+        case 'tool-call-delta': {
+            const shapeOk = hasExactKeys(chunk, ['type', 'index', 'id', 'argumentsDelta'])
+                || (hasExactKeys(chunk, ['type', 'index', 'id', 'name', 'argumentsDelta']) && typeof chunk.name === 'string');
+            return shapeOk && typeof chunk.id === 'string' && typeof chunk.argumentsDelta === 'string'
+                ? chunk.type
+                : undefined;
+        }
+        // Whitelist fall-through over parsed data: block-start/end, usage, finish,
+        // and any future chunk variant stay one event per line.
+        default:
+            return undefined;
+    }
+}
+/** The tool-call fields of a whitelisted delta chunk (only after {@link classify} returned `'tool-call-delta'`). */
+function toolCallOf(event) {
+    return event.data.chunk;
+}
+/** The block index of a whitelisted delta chunk (not every {@link StreamChunk} variant carries one). */
+function indexOf(event) {
+    return event.data.chunk.index;
+}
+/** Whether `next` extends a run ending in `prev` (same kind already checked by the caller). */
+function continues(prev, next, kind) {
+    if (next.seq !== prev.seq + 1)
+        return false;
+    // Two safe-integer times can sit further apart than a double subtracts
+    // exactly (2^53-1 and its negation differ by ~2^54); a rounded gap would
+    // decode to a different timestamp. The check is exact in both directions: a
+    // true gap within safe range subtracts without rounding and passes, while a
+    // true gap beyond it rounds to a value that is itself beyond and fails.
+    if (!Number.isSafeInteger(next.time - prev.time))
+        return false;
+    if (next.data.turn !== prev.data.turn || next.data.step !== prev.data.step)
+        return false;
+    if (indexOf(next) !== indexOf(prev))
+        return false;
+    if (kind !== 'tool-call-delta')
+        return true;
+    const a = toolCallOf(prev);
+    const b = toolCallOf(next);
+    // `name` must match in presence AND value — a mixed run is not representable.
+    return a.id === b.id && Object.hasOwn(a, 'name') === Object.hasOwn(b, 'name') && a.name === b.name;
+}
+/** Build the row for a completed run (`run.length >= MIN_RUN`, uniform per {@link continues}). */
+function buildRow(kind, run) {
+    const first = run[0];
+    const base = {
+        turn: first.data.turn,
+        step: first.data.step,
+        index: indexOf(first),
+        dt: run.slice(1).map((event, i) => event.time - run[i].time),
+    };
+    const envelope = { seq0: first.seq, time0: first.time };
+    if (kind === 'tool-call-delta') {
+        const call = toolCallOf(first);
+        return {
+            type: 'tool-call-chunks',
+            ...envelope,
+            data: {
+                ...base,
+                id: CallId(call.id),
+                ...Object.hasOwn(call, 'name') ? { name: call.name } : {},
+                args: run.map(event => event.data.chunk.argumentsDelta),
+            },
+        };
+    }
+    const data = { ...base, texts: run.map(event => event.data.chunk.text) };
+    return kind === 'text-delta'
+        ? { type: 'text-chunks', ...envelope, data }
+        : { type: 'reasoning-chunks', ...envelope, data };
+}
+/**
+ * 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 function packChunkRuns(events) {
+    const out = [];
+    let kind;
+    let run = [];
+    const flush = () => {
+        if (kind !== undefined && run.length >= MIN_RUN)
+            out.push(buildRow(kind, run));
+        else
+            out.push(...run);
+        kind = undefined;
+        run = [];
+    };
+    for (const event of events) {
+        const k = classify(event);
+        if (k === undefined) {
+            flush();
+            out.push(event);
+            continue;
+        }
+        const delta = event;
+        const last = run[run.length - 1];
+        if (k === kind && last !== undefined && continues(last, delta, k)) {
+            run.push(delta);
+            continue;
+        }
+        flush();
+        kind = k;
+        run = [delta];
+    }
+    flush();
+    return out;
+}
+/** Throw the uniform malformed-row diagnostic. */
+function malformed(tag, why) {
+    throw new Error(`malformed ${tag} storage row: ${why}`);
+}
+/** Validate the shared run-data fields and the payload/dt arity; returns the member payload. */
+function validateRunData(tag, data, payloadKey) {
+    if (typeof data.turn !== 'number' || typeof data.step !== 'number' || typeof data.index !== 'number') {
+        malformed(tag, 'turn/step/index must be numbers');
+    }
+    const payload = data[payloadKey];
+    if (!Array.isArray(payload) || payload.length === 0 || payload.some(entry => typeof entry !== 'string')) {
+        malformed(tag, `${payloadKey} must be a non-empty string array`);
+    }
+    const dt = data.dt;
+    if (!Array.isArray(dt) || dt.some(gap => !Number.isSafeInteger(gap))) {
+        malformed(tag, 'dt must be an array of safe integers');
+    }
+    if (dt.length !== payload.length - 1) {
+        malformed(tag, `dt length ${dt.length} does not match ${payload.length} members`);
+    }
+    return payload;
+}
+/** Validate a row-tagged parsed value's envelope and data, throwing on any malformation. */
+function validateRow(value, tag) {
+    if (!hasExactKeys(value, ['type', 'seq0', 'time0', 'data'])) {
+        malformed(tag, 'envelope must be exactly {type, seq0, time0, data}');
+    }
+    if (!Number.isSafeInteger(value.seq0) || value.seq0 < 0) {
+        malformed(tag, 'seq0 must be a non-negative safe integer');
+    }
+    if (!Number.isSafeInteger(value.time0)) {
+        malformed(tag, 'time0 must be a safe integer');
+    }
+    const data = value.data;
+    if (!isRecord(data))
+        malformed(tag, 'data must be an object');
+    let payload;
+    if (tag === 'tool-call-chunks') {
+        const withName = hasExactKeys(data, ['turn', 'step', 'index', 'id', 'name', 'dt', 'args']);
+        if (!withName && !hasExactKeys(data, ['turn', 'step', 'index', 'id', 'dt', 'args'])) {
+            malformed(tag, 'data must be exactly {turn, step, index, id, name?, dt, args}');
+        }
+        if (typeof data.id !== 'string' || (withName && typeof data.name !== 'string')) {
+            malformed(tag, 'id (and name when present) must be strings');
+        }
+        payload = validateRunData(tag, data, 'args');
+    }
+    else {
+        if (!hasExactKeys(data, ['turn', 'step', 'index', 'dt', 'texts'])) {
+            malformed(tag, 'data must be exactly {turn, step, index, dt, texts}');
+        }
+        payload = validateRunData(tag, data, 'texts');
+    }
+    // Reconstruction bounds. The encoder only packs runs whose member seqs and
+    // times are all safe integers, so a running value that leaves safe range is
+    // outside any encoder's image: float arithmetic would round it to a
+    // different number than exact arithmetic, a silent corruption. Within safe
+    // range every step is exact, so the first departure is always caught.
+    if (!Number.isSafeInteger(value.seq0 + payload.length - 1)) {
+        malformed(tag, 'member seqs must stay safe integers');
+    }
+    let time = value.time0;
+    for (const gap of data.dt) {
+        time += gap;
+        if (!Number.isSafeInteger(time))
+            malformed(tag, 'member times must stay safe integers');
+    }
+    return value;
+}
+/** Expand a validated row back into its exact original events, in order. */
+function expandRow(row) {
+    const members = row.type === 'tool-call-chunks' ? row.data.args : row.data.texts;
+    const events = [];
+    let time = row.time0;
+    for (let k = 0; k < members.length; k++) {
+        if (k > 0)
+            time += row.data.dt[k - 1];
+        let chunk;
+        switch (row.type) {
+            case 'text-chunks':
+                chunk = { type: 'text-delta', index: row.data.index, text: members[k] };
+                break;
+            case 'reasoning-chunks':
+                chunk = { type: 'reasoning-delta', index: row.data.index, text: members[k] };
+                break;
+            case 'tool-call-chunks':
+                chunk = {
+                    type: 'tool-call-delta',
+                    index: row.data.index,
+                    id: row.data.id,
+                    ...Object.hasOwn(row.data, 'name') ? { name: row.data.name } : {},
+                    argumentsDelta: members[k],
+                };
+                break;
+            /* v8 ignore next 2 -- validateRow only returns the three row tags */
+            default:
+                return assertNever(row, 'chunk-rows expandRow');
+        }
+        events.push({
+            type: 'assistant/chunk',
+            seq: row.seq0 + k,
+            time,
+            data: { turn: row.data.turn, step: row.data.step, chunk },
+        });
+    }
+    return events;
+}
+/**
+ * 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, unvalidated.
+ *
+ * @param value - one line's `JSON.parse` result.
+ * @returns the stored events, in log order.
+ */
+export function decodeStorageRecord(value) {
+    if (!isRecord(value))
+        return [value];
+    const tag = value.type;
+    if (tag !== 'text-chunks' && tag !== 'reasoning-chunks' && tag !== 'tool-call-chunks') {
+        return [value];
+    }
+    return expandRow(validateRow(value, tag));
+}
+//# sourceMappingURL=chunk-rows.js.map