@deepseek-ai/dsh-session-log-deepseek 0.1.2-alpha.2 → 0.1.2-alpha.4

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/session/session-log-deepseek/README.md
-README.md: e76a4ba7d48deafb13f5dfcc1e7ea6532a4452d7
-README.zh.md: f2bf91418430fee960350fa0feb6053704dad543
+README.md: b08b2d3cde78e7a3cf7050e90ff57655ad70d409
+README.zh.md: 0ee216c6c69178695eb629b2a81faef73103b13d

package/README.md

@@ -34,7 +34,7 @@ Shipped profiles mount the plugin so an overlay can enable it, but the default c
 <a id="request-field"></a>
 ## Request field
 
-For a request carrying a live `sessionId`, the plugin folds the greatest accepted watermark for that exact Session identity, snapshots `Session.events`, and sends the contiguous suffix after the watermark. A process-local fold scans each event once and consumes later appends incrementally; restart and HMR rebuild it from the durable log. The version-1 field contains the immutable `SessionHeader`, `afterSeq`, `throughSeq`, and every complete canonical `SessionEvent` in that range as a direct array element. Forked sessions ignore inherited parent watermarks because each watermark records the Session id sent on the accepted request.
+For a request carrying a live `sessionId`, the plugin folds the greatest accepted watermark for that exact Session identity, snapshots `Session.events`, and sends the contiguous suffix after the watermark. A process-local fold scans each event once and consumes later appends incrementally; restart and HMR rebuild it from the durable log. The version-1 field contains a v0-compatible raw session header (`seedLength` is present only for a seeded Session), numeric `afterSeq` and `throughSeq`, and every complete canonical event translated to raw-number envelope fields. Forked sessions ignore inherited parent watermarks because each watermark records the Session id sent on the accepted request.
 
 <a id="acceptance-and-retry"></a>
 ## Acceptance and retry

package/README.zh.md

@@ -34,7 +34,7 @@ kind: "package-reference"
 <a id="request-field"></a>
 ## 请求字段
 
-对于携带存活 `sessionId` 的请求，插件会折叠该确切会话身份的最大已接受水位，对 `Session.events` 取快照，并发送水位之后的连续后缀。进程内 fold 会让每条事件只被扫描一次并增量消费后续追加；重启与 HMR 会从持久日志重建它。版本 1 字段包含不可变的 `SessionHeader`、`afterSeq`、`throughSeq`，以及作为数组直接元素的该范围内每个完整权威 `SessionEvent`。每个水位都会记录已接受请求发送的会话 id，因此 fork 会话会忽略从父会话继承的水位。
+对于携带存活 `sessionId` 的请求，插件会折叠该确切会话身份的最大已接受水位，对 `Session.events` 取快照，并发送水位之后的连续后缀。进程内 fold 会让每条事件只被扫描一次并增量消费后续追加；重启与 HMR 会从持久日志重建它。版本 1 字段包含兼容 v0 的原始会话 header（仅 seeded Session 携带 `seedLength`）、数值型 `afterSeq` 与 `throughSeq`，以及把完整权威事件翻译为原始数值 envelope 字段后的数组元素。每个水位都会记录已接受请求发送的会话 id，因此 fork 会话会忽略从父会话继承的水位。
 
 <a id="acceptance-and-retry"></a>
 ## 接受与重试

package/lib/index.js

@@ -1,5 +1,6 @@
 import z from "@deepseek-ai/schemastery";
 import { brandString } from "@deepseek-ai/dsh-brand";
+import { SessionLogOffset, SessionSeq, isSurfaceEvent } from "@deepseek-ai/dsh-session";
 //#region lib/types/index.js
 /**
 * Incremental session-log contribution for official DeepSeek LLM API requests.
@@ -14,6 +15,39 @@ const inject = ["deepseekLlmApiExtensions", "sessions"];
 /** Validated Session-log request contribution configuration. */
 const Config = z.object({ enabled: z.boolean().default(false) });
 const acceptanceFolds = /* @__PURE__ */ new WeakMap();
+/** Translate logical Session metadata back to the stable version-0 wire header. */
+function wireHeader(session) {
+	const header = session.header;
+	return {
+		version: header.version,
+		id: String(header.id),
+		createdAt: header.createdAt,
+		...header.cwd === void 0 ? {} : { cwd: header.cwd },
+		...header.parentSession === void 0 ? {} : { parentSession: String(header.parentSession) },
+		...header.isSeeded ? { seedLength: Number(session.inheritedEventCount) } : {},
+		...header.origin === void 0 ? {} : { origin: header.origin },
+		...header.delegationDepth === void 0 ? {} : { delegationDepth: header.delegationDepth },
+		...header.agentPreset === void 0 ? {} : { agentPreset: header.agentPreset }
+	};
+}
+/** Translate compile-time sequence brands to raw numeric request fields. */
+function wireEvent(event) {
+	const surfaceEvent = isSurfaceEvent(event) ? event : void 0;
+	const surfaceOp = surfaceEvent?.surfaceOp;
+	return {
+		type: event.type,
+		seq: Number(event.seq),
+		time: event.time,
+		data: event.data,
+		...event.ignorable === void 0 ? {} : { ignorable: event.ignorable },
+		...surfaceEvent?.sourceEventSeqs === void 0 ? {} : { sourceEventSeqs: surfaceEvent.sourceEventSeqs.map(Number) },
+		...surfaceOp === void 0 ? {} : surfaceOp === "append" ? { surfaceOp } : { surfaceOp: {
+			op: "replace",
+			start: Number(surfaceOp.start),
+			end: Number(surfaceOp.end)
+		} }
+	};
+}
 /**
 * Highest confirmed sequence for this exact session identity.
 * @param session - canonical log whose matching acceptance events are folded.
@@ -22,17 +56,24 @@ const acceptanceFolds = /* @__PURE__ */ new WeakMap();
 function acceptedThrough(session) {
 	const previous = acceptanceFolds.get(session);
 	let throughSeq = previous?.throughSeq ?? -1;
-	const events = session.events;
-	const start = previous?.scannedEvents ?? 0;
-	for (let index = start; index < events.length; index++) {
-		const event = events[index];
+	const length = session.seq;
+	const start = previous?.scannedEvents ?? SessionLogOffset(0);
+	for (let index = start; index < length; index++) {
+		const event = session.eventAt(SessionSeq(index));
+		if (event === void 0) throw new Error(`session-log-deepseek: missing event ${String(index)} below captured length ${String(length)}`);
 		if (event.type !== "session-log-deepseek/delivery-accepted") continue;
-		if (typeof event.data.sessionId !== "string" || event.data.sessionId.length === 0 || !Number.isSafeInteger(event.data.throughSeq) || event.data.throughSeq < 0 || event.data.throughSeq >= event.seq) throw new Error(`session-log-deepseek: malformed acceptance watermark at seq ${event.seq}`);
+		let acceptedSeq;
+		try {
+			acceptedSeq = SessionSeq(event.data.throughSeq);
+		} catch {
+			throw new Error(`session-log-deepseek: malformed acceptance watermark at seq ${event.seq}`);
+		}
+		if (typeof event.data.sessionId !== "string" || event.data.sessionId.length === 0 || acceptedSeq >= event.seq) throw new Error(`session-log-deepseek: malformed acceptance watermark at seq ${event.seq}`);
 		if (event.data.sessionId !== session.id) continue;
-		throughSeq = Math.max(throughSeq, event.data.throughSeq);
+		if (acceptedSeq > throughSeq) throughSeq = acceptedSeq;
 	}
 	acceptanceFolds.set(session, {
-		scannedEvents: events.length,
+		scannedEvents: length,
 		throughSeq
 	});
 	return throughSeq;
@@ -49,17 +90,16 @@ function apply(ctx, config) {
 		const session = ctx.sessions.get(brandString(request.sessionId));
 		if (session === void 0) return void 0;
 		const afterSeq = acceptedThrough(session);
-		const snapshot = session.events;
-		const throughSeq = snapshot.length - 1;
-		if (throughSeq < 0) return void 0;
-		const suffix = snapshot.slice(afterSeq + 1);
+		const throughSeq = session.snapshotEvents().at(-1)?.seq;
+		if (throughSeq === void 0) return void 0;
+		const suffix = session.snapshotEvents(SessionLogOffset(afterSeq + 1));
 		return {
 			value: {
 				version: 1,
-				session: session.header,
-				afterSeq,
-				throughSeq,
-				events: suffix
+				session: wireHeader(session),
+				afterSeq: Number(afterSeq),
+				throughSeq: Number(throughSeq),
+				events: suffix.map(wireEvent)
 			},
 			accept: () => {
 				session.append("session-log-deepseek/delivery-accepted", {

package/lib/invariant.js

@@ -1,3 +1,4 @@
+import { SessionSeq } from "@deepseek-ai/dsh-session";
 //#region lib/types/invariant.js
 /** Package-owned invariants for DeepSeek session-log acceptance watermarks. */
 const PACKAGE_NAME = "@deepseek-ai/dsh-session-log-deepseek";
@@ -8,13 +9,19 @@ const inject = ["invariants"];
 /** Validate one acceptance watermark against its containing event and session. */
 function validateDeliveryAccepted(session, event, fail) {
 	const { sessionId, throughSeq } = event.data;
-	const inherited = session.header.parentSession !== void 0 && session.header.seedLength !== void 0 && event.seq < session.header.seedLength;
+	const inherited = session.header.parentSession !== void 0 && !session.isOwnSeq(event.seq);
 	if (sessionId !== session.id && !inherited) fail("a non-inherited session-log-deepseek/delivery-accepted event must name its containing session");
-	if (!Number.isSafeInteger(throughSeq) || throughSeq < 0 || throughSeq >= event.seq) fail(`session-log-deepseek/delivery-accepted throughSeq must identify an earlier event, got ${throughSeq} at seq ${event.seq}`);
+	let acceptedSeq;
+	try {
+		acceptedSeq = SessionSeq(throughSeq);
+	} catch {
+		fail(`session-log-deepseek/delivery-accepted throughSeq must identify an earlier event, got ${throughSeq} at seq ${event.seq}`);
+	}
+	if (acceptedSeq >= event.seq) fail(`session-log-deepseek/delivery-accepted throughSeq must identify an earlier event, got ${throughSeq} at seq ${event.seq}`);
 }
 /** Validate acceptance watermarks already present in one Session. */
 function validateSession(session, fail) {
-	for (const event of session.events) if (event.type === "session-log-deepseek/delivery-accepted") validateDeliveryAccepted(session, event, fail);
+	for (const event of session.snapshotEvents()) if (event.type === "session-log-deepseek/delivery-accepted") validateDeliveryAccepted(session, event, fail);
 }
 /** Validate one live session-event dispatch. */
 function validateDispatched(args, fail) {

package/lib/types/index.d.ts

@@ -6,7 +6,7 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
-import type { Session } from '@deepseek-ai/dsh-session';
+import type { Session, SessionSeqCursor } from '@deepseek-ai/dsh-session';
 export type * from './types.ts';
 /** Cordis plugin name. */
 export declare const name = "session-log-deepseek";
@@ -24,7 +24,7 @@ export declare const Config: z<Config>;
  * @param session - canonical log whose matching acceptance events are folded.
  * @returns greatest accepted sequence, or `-1` before any accepted request.
  */
-export declare function acceptedThrough(session: Session): number;
+export declare function acceptedThrough(session: Session): SessionSeqCursor;
 /**
  * Register the incremental `dsh_session_log` request contribution when enabled.
  * @param ctx - plugin context carrying Sessions and the DeepSeek request-extension registry.

package/lib/types/index.js

@@ -6,6 +6,7 @@
  */
 import z from '@deepseek-ai/schemastery';
 import { brandString } from '@deepseek-ai/dsh-brand';
+import { isSurfaceEvent, SessionLogOffset, SessionSeq } from '@deepseek-ai/dsh-session';
 /** Cordis plugin name. */
 export const name = 'session-log-deepseek';
 /** Services required to resolve sessions and contribute the provider request field. */
@@ -15,6 +16,41 @@ export const Config = z.object({
     enabled: z.boolean().default(false),
 });
 const acceptanceFolds = new WeakMap();
+/** Translate logical Session metadata back to the stable version-0 wire header. */
+function wireHeader(session) {
+    const header = session.header;
+    return {
+        version: header.version,
+        id: String(header.id),
+        createdAt: header.createdAt,
+        ...header.cwd === undefined ? {} : { cwd: header.cwd },
+        ...header.parentSession === undefined ? {} : { parentSession: String(header.parentSession) },
+        ...header.isSeeded ? { seedLength: Number(session.inheritedEventCount) } : {},
+        ...header.origin === undefined ? {} : { origin: header.origin },
+        ...header.delegationDepth === undefined ? {} : { delegationDepth: header.delegationDepth },
+        ...header.agentPreset === undefined ? {} : { agentPreset: header.agentPreset },
+    };
+}
+/** Translate compile-time sequence brands to raw numeric request fields. */
+function wireEvent(event) {
+    const surfaceEvent = isSurfaceEvent(event) ? event : undefined;
+    const surfaceOp = surfaceEvent?.surfaceOp;
+    return {
+        type: event.type,
+        seq: Number(event.seq),
+        time: event.time,
+        data: event.data,
+        ...event.ignorable === undefined ? {} : { ignorable: event.ignorable },
+        ...surfaceEvent?.sourceEventSeqs === undefined
+            ? {}
+            : { sourceEventSeqs: surfaceEvent.sourceEventSeqs.map(Number) },
+        ...surfaceOp === undefined
+            ? {}
+            : surfaceOp === 'append'
+                ? { surfaceOp }
+                : { surfaceOp: { op: 'replace', start: Number(surfaceOp.start), end: Number(surfaceOp.end) } },
+    };
+}
 /**
  * Highest confirmed sequence for this exact session identity.
  * @param session - canonical log whose matching acceptance events are folded.
@@ -23,22 +59,32 @@ const acceptanceFolds = new WeakMap();
 export function acceptedThrough(session) {
     const previous = acceptanceFolds.get(session);
     let throughSeq = previous?.throughSeq ?? -1;
-    const events = session.events;
-    const start = previous?.scannedEvents ?? 0;
-    for (let index = start; index < events.length; index++) {
-        const event = events[index];
+    const length = session.seq;
+    const start = previous?.scannedEvents ?? SessionLogOffset(0);
+    for (let index = start; index < length; index++) {
+        const event = session.eventAt(SessionSeq(index));
+        if (event === undefined) {
+            throw new Error(`session-log-deepseek: missing event ${String(index)} below captured length ${String(length)}`);
+        }
         if (event.type !== 'session-log-deepseek/delivery-accepted')
             continue;
+        let acceptedSeq;
+        try {
+            acceptedSeq = SessionSeq(event.data.throughSeq);
+        }
+        catch {
+            throw new Error(`session-log-deepseek: malformed acceptance watermark at seq ${event.seq}`);
+        }
         if (typeof event.data.sessionId !== 'string' || event.data.sessionId.length === 0
-            || !Number.isSafeInteger(event.data.throughSeq) || event.data.throughSeq < 0
-            || event.data.throughSeq >= event.seq) {
+            || acceptedSeq >= event.seq) {
             throw new Error(`session-log-deepseek: malformed acceptance watermark at seq ${event.seq}`);
         }
         if (event.data.sessionId !== session.id)
             continue;
-        throughSeq = Math.max(throughSeq, event.data.throughSeq);
+        if (acceptedSeq > throughSeq)
+            throughSeq = acceptedSeq;
     }
-    acceptanceFolds.set(session, { scannedEvents: events.length, throughSeq });
+    acceptanceFolds.set(session, { scannedEvents: length, throughSeq });
     return throughSeq;
 }
 /**
@@ -58,17 +104,17 @@ export function apply(ctx, config) {
             if (session === undefined)
                 return undefined;
             const afterSeq = acceptedThrough(session);
-            const snapshot = session.events;
-            const throughSeq = snapshot.length - 1;
-            if (throughSeq < 0)
+            const snapshot = session.snapshotEvents();
+            const throughSeq = snapshot.at(-1)?.seq;
+            if (throughSeq === undefined)
                 return undefined;
-            const suffix = snapshot.slice(afterSeq + 1);
+            const suffix = session.snapshotEvents(SessionLogOffset(afterSeq + 1));
             const value = {
                 version: 1,
-                session: session.header,
-                afterSeq,
-                throughSeq,
-                events: suffix,
+                session: wireHeader(session),
+                afterSeq: Number(afterSeq),
+                throughSeq: Number(throughSeq),
+                events: suffix.map(wireEvent),
             };
             return {
                 value,

package/lib/types/invariant.js

@@ -1,4 +1,5 @@
 /** Package-owned invariants for DeepSeek session-log acceptance watermarks. */
+import { SessionSeq } from '@deepseek-ai/dsh-session';
 const PACKAGE_NAME = '@deepseek-ai/dsh-session-log-deepseek';
 /** Cordis companion plugin name. */
 export const name = 'session-log-deepseek-invariant';
@@ -8,18 +9,24 @@ export const inject = ['invariants'];
 function validateDeliveryAccepted(session, event, fail) {
     const { sessionId, throughSeq } = event.data;
     const inherited = session.header.parentSession !== undefined
-        && session.header.seedLength !== undefined
-        && event.seq < session.header.seedLength;
+        && !session.isOwnSeq(event.seq);
     if (sessionId !== session.id && !inherited) {
         fail('a non-inherited session-log-deepseek/delivery-accepted event must name its containing session');
     }
-    if (!Number.isSafeInteger(throughSeq) || throughSeq < 0 || throughSeq >= event.seq) {
+    let acceptedSeq;
+    try {
+        acceptedSeq = SessionSeq(throughSeq);
+    }
+    catch {
+        fail(`session-log-deepseek/delivery-accepted throughSeq must identify an earlier event, got ${throughSeq} at seq ${event.seq}`);
+    }
+    if (acceptedSeq >= event.seq) {
         fail(`session-log-deepseek/delivery-accepted throughSeq must identify an earlier event, got ${throughSeq} at seq ${event.seq}`);
     }
 }
 /** Validate acceptance watermarks already present in one Session. */
 function validateSession(session, fail) {
-    for (const event of session.events) {
+    for (const event of session.snapshotEvents()) {
         if (event.type === 'session-log-deepseek/delivery-accepted')
             validateDeliveryAccepted(session, event, fail);
     }

package/lib/types/types.d.ts

@@ -1,15 +1,45 @@
 /** Wire types for lossless incremental DeepSeek session-log upload. */
-import type { SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session';
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+import type { JsonValue } from '@deepseek-ai/dsh-util-values';
+/** Version-0 Session header fields serialized on the external request wire. */
+export interface DeepSeekSessionLogWireHeader {
+    readonly version: number;
+    readonly id: string;
+    readonly createdAt: number;
+    readonly cwd?: string;
+    readonly parentSession?: string;
+    /** Exact inherited prefix length; absent for an unseeded Session. */
+    readonly seedLength?: number;
+    readonly origin?: 'subagent';
+    readonly delegationDepth?: number;
+    readonly agentPreset?: string;
+}
+/** Raw-number surface mutation serialized on the external request wire. */
+export type DeepSeekSessionLogWireSurfaceOp = 'append' | {
+    readonly op: 'replace';
+    readonly start: number;
+    readonly end: number;
+};
+/** One complete canonical event translated to raw JSON primitives for upload. */
+export interface DeepSeekSessionLogWireEvent {
+    readonly type: SessionEvent['type'];
+    readonly seq: number;
+    readonly time: number;
+    readonly data: JsonValue;
+    readonly ignorable?: true;
+    readonly sourceEventSeqs?: readonly number[];
+    readonly surfaceOp?: DeepSeekSessionLogWireSurfaceOp;
+}
 /** Versioned incremental session-log field carried by an official DeepSeek request. */
 export interface DeepSeekSessionLogExtension {
     readonly version: 1;
-    readonly session: SessionHeader;
+    readonly session: DeepSeekSessionLogWireHeader;
     /** Highest sequence durably recorded as accepted before this request, or `-1`. */
     readonly afterSeq: number;
     /** Highest sequence represented by {@link events}. */
     readonly throughSeq: number;
     /** Complete canonical event envelopes for every sequence from `afterSeq + 1` through `throughSeq`. */
-    readonly events: readonly SessionEvent[];
+    readonly events: readonly DeepSeekSessionLogWireEvent[];
 }
 declare module '@deepseek-ai/dsh-deepseek-llm-api-extensions/types' {
     interface DeepSeekLlmApiExtensionMap {
@@ -23,7 +53,7 @@ declare module '@deepseek-ai/dsh-session/types' {
             /** Session identity the accepted delivery carried; inherited fork markers retain the parent's id. */
             sessionId: import('@deepseek-ai/dsh-session/types').SessionId;
             /** Last canonical event included in the accepted request. */
-            throughSeq: number;
+            throughSeq: import('@deepseek-ai/dsh-session/types').SessionSeq;
         };
     }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-session-log-deepseek",
   "description": "Incremental lossless session-log request extension for the official DeepSeek LLM API",
-  "version": "0.1.2-alpha.2",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
@@ -37,19 +37,20 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@deepseek-ai/dsh-brand": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-util-values": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-brand": "^0.1.2-alpha.4",
     "@deepseek-ai/schemastery": "^3.18.2"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh-deepseek-llm-api-extensions": "^0.1.2-alpha.2",
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-session": "^0.1.2-alpha.2"
+    "@deepseek-ai/dsh-deepseek-llm-api-extensions": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-session": "^0.1.2-alpha.4"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-deepseek-llm-api-extensions": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-session": "^0.1.2-alpha.2"
+    "@deepseek-ai/dsh-deepseek-llm-api-extensions": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-session": "^0.1.2-alpha.4"
   }
 }