@deepseek-ai/dsh-session-persistence 0.1.2-alpha.3 → 0.1.2-alpha.5

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-persistence/README.md
-README.md: 687241c604254152538e152a62d0c78b31369cf3
-README.zh.md: 170f194c247bf680db554c4ecb2beca97184ff0b
+README.md: 6d430173b985d7e32b615e0b42713a925bc8b344
+README.zh.md: a3b6cd90fa4ccba2b28f0e81517bbabab0ce047e

package/README.md

@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-`dsh-session-persistence` stores a session's event log durably, reloads it on resume, and lists stored sessions through the backend-neutral `ctx.sessionPersistence` service. The persisted unit is the existing `SessionEvent` log — there is no parallel stored message type — and non-replayable metadata (format version, working directory, lineage, seed boundary) travels separately as `SessionHeader`. A backend owns its storage, while the service owns append-only logs, contiguous sequence numbers, crash recovery that preserves an interrupted turn instead of truncating it, and durable writes that resolve only after the batch is safe. The shipped JSONL provider implements this service with one artifact per Session; third-party providers may implement the same contract without changing the loop or model.
+`dsh-session-persistence` stores a session's event log durably, reloads it on resume, and lists stored sessions through the backend-neutral `ctx.sessionPersistence` service. The persisted unit is the existing `SessionEvent` log — there is no parallel stored message type. `SessionHeader.isSeeded` makes lineage visible to lightweight listing, while the exact `inheritedEventCount` accompanies every body-bearing storage read and prepared Session. A backend owns its storage, while the service owns append-only logs, contiguous sequence numbers, crash recovery that preserves an interrupted turn instead of truncating it, and durable writes that resolve only after the batch is safe. The shipped JSONL provider implements this service with one artifact per Session; third-party providers may implement the same contract without changing the loop or model.
 
 ## Table of Contents
 
@@ -36,18 +36,18 @@ The seam ships the [JSONL](../session-persistence-jsonl/README.md) backend. It s
 With a backend mounted, you can store a session's events durably, reload the stored log, and list what is stored:
 
 ```text
-await ctx.sessionPersistence.create(meta)                  // register a session
+await ctx.sessionPersistence.create(meta, inheritedEventCount) // cut required when meta.isSeeded
 await ctx.sessionPersistence.ensureMaterialized(session)   // persist an empty resumable session
 await ctx.sessionPersistence.append(id, events)            // durably persist a batch
-const { meta, events } = await ctx.sessionPersistence.load(id)   // reload on resume
+const { meta, inheritedEventCount, events } = await ctx.sessionPersistence.load(id)
 const headers = await ctx.sessionPersistence.list()        // every stored session
 ```
 
-`append` resolves only after the batch is durable, so a resolved write survives an OS crash or power loss. Ordinary `create` remains lazy; a lifecycle frontend calls `ensureMaterialized` only when an empty session must itself appear in durable listing without inventing an event. `load` returns an immutable balanced log and commits any needed crash recovery; `inspect` reads the same view without committing recovery. Consumers that resume from a watermark can read only the events at or past a sequence number, and a session's artifact location (`locate`) resolves without filesystem I/O.
+`append` resolves only after the batch is durable, so a resolved write survives an OS crash or power loss. Ordinary `create(meta, inheritedEventCount)` remains lazy; `meta.isSeeded: true` requires the sibling exact cut, while unseeded metadata may omit it and rejects a nonzero value. The first materializing batch for a seeded session must reach the complete inherited prefix, so storage never exposes metadata whose cut exceeds its log. A lifecycle frontend calls `ensureMaterialized` only when an empty session must itself appear in durable listing without inventing an event. `load` returns an immutable balanced log and commits any needed crash recovery; `inspect` reads the same complete view without committing recovery. `readFrom` accepts a `SessionLogOffset` and returns a detached `SessionEventSuffix` carrying that `fromSeq`, the unchanged inherited cut, and only stored events at or after the cut. A session's artifact location (`locate`) resolves without filesystem I/O.
 
 ### Resuming and crash recovery
 
-Resume is `load` plus session preparation: the stored log comes back with its header lineage intact, so a resumed agent sees the same history and composition. A session that crashed mid-turn reloads with its interrupted final turn preserved and balanced: `load` appends synthetic `tool/result` and `turn/end {interrupted}` closers for unanswered calls instead of dropping the events — a single turn can be large, and those events were durably written before the crash. Only a never-fully-written torn tail fragment is discarded.
+Resume is `load` plus session preparation: the stored log comes back with its header lineage and exact inherited cut intact, so ownership checks do not infer the cut from a marker or the full restore length. A session that crashed mid-turn reloads with its interrupted final turn preserved and balanced: `load` appends synthetic `tool/result` and `turn/end {interrupted}` closers for unanswered calls instead of dropping the events — a single turn can be large, and those events were durably written before the crash. Only a never-fully-written torn tail fragment is discarded.
 
 ### Failures and recovery
 
@@ -83,7 +83,7 @@ The package is the Service Definition of a capability seam with two halves. The
 | [`src/write-behind.ts`](src/write-behind.ts) | The per-session bounded write controller and flush barrier |
 | [`src/preparations.ts`](src/preparations.ts) | Bounded retention of unpublished Session preparations for resume reuse |
 | [`src/revision.ts`](src/revision.ts) | The branded opaque revision token |
-| [`src/invariant.ts`](src/invariant.ts) | Invariant companion (no runtime invariant; the coordinator asserts stored/live identity and cwd) |
+| — | No runtime invariant companion is published; persistence correctness requires backend round-trip and crash-tail tests; this package exposes no continuously observable in-process relation. |
 
 ### The write path at a glance
 

package/README.zh.md

@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-`dsh-session-persistence` 通过后端无关的 `ctx.sessionPersistence` 服务持久存储会话的事件日志、在恢复时重新加载并列出已存储会话。持久化单元就是现有 `SessionEvent` 日志——不存在另一套并行的存储消息类型——不可回放的元数据（格式版本、工作目录、血缘、种子边界）作为 `SessionHeader` 单独传输。后端拥有自己的存储，而服务拥有仅追加日志、连续序列号、保留中断轮次而非截断的崩溃恢复，以及只在批次安全后才返回的持久写入。随产品交付的 JSONL provider 用每个 Session 一份产物实现该服务；第三方 provider 可以实现同一约定，而不改变 loop 或模型。
+`dsh-session-persistence` 通过后端无关的 `ctx.sessionPersistence` 服务持久存储会话的事件日志、在恢复时重新加载并列出已存储会话。持久化单元就是现有 `SessionEvent` 日志——不存在另一套并行的存储消息类型。`SessionHeader.isSeeded` 让轻量列表可见血缘，而精确的 `inheritedEventCount` 随每次带正文的存储读取与 prepared Session 一同传输。后端拥有自己的存储，而服务拥有仅追加日志、连续序列号、保留中断轮次而非截断的崩溃恢复，以及只在批次安全后才返回的持久写入。随产品交付的 JSONL provider 用每个 Session 一份产物实现该服务；第三方 provider 可以实现同一约定，而不改变 loop 或模型。
 
 ## 目录
 
@@ -36,18 +36,18 @@ seam 随产品交付 [JSONL](../session-persistence-jsonl/README.zh.md) 后端
 挂载后端后，你可以持久存储会话事件、重新加载已存储日志并列出已存储内容：
 
 ```text
-await ctx.sessionPersistence.create(meta)                  // register a session
+await ctx.sessionPersistence.create(meta, inheritedEventCount) // cut required when meta.isSeeded
 await ctx.sessionPersistence.ensureMaterialized(session)   // persist an empty resumable session
 await ctx.sessionPersistence.append(id, events)            // durably persist a batch
-const { meta, events } = await ctx.sessionPersistence.load(id)   // reload on resume
+const { meta, inheritedEventCount, events } = await ctx.sessionPersistence.load(id)
 const headers = await ctx.sessionPersistence.list()        // every stored session
 ```
 
-`append` 只在批次持久后返回，因此成功返回的写入在操作系统崩溃或断电后依然存在。普通 `create` 保持惰性；只有当空会话本身必须出现在持久列表中时，生命周期前端才调用 `ensureMaterialized`，且不会虚构事件。`load` 返回不可变的平衡日志并提交任何需要的崩溃恢复；`inspect` 读取同一视图但不提交恢复。从水位恢复的消费方可以只读取该序列号及之后的已存储事件，会话的产物位置（`locate`）不经文件系统 I/O 即可解析。
+`append` 只在批次持久后返回，因此成功返回的写入在操作系统崩溃或断电后依然存在。普通 `create(meta, inheritedEventCount)` 保持惰性；`meta.isSeeded: true` 要求单独的精确 cut，unseeded metadata 可以省略它并拒绝非零值。seeded 会话的首个物化批次必须到达完整继承前缀，因此存储绝不公开 cut 超过日志的 metadata。只有当空会话本身必须出现在持久列表中时，生命周期前端才调用 `ensureMaterialized`，且不会虚构事件。`load` 返回不可变的平衡日志并提交任何需要的崩溃恢复；`inspect` 读取同一份完整视图但不提交恢复。`readFrom` 接受 `SessionLogOffset`，并返回分离的 `SessionEventSuffix`，其中携带该 `fromSeq`、不变的继承 cut，以及 cut 位置或之后的存储事件。会话的产物位置（`locate`）不经文件系统 I/O 即可解析。
 
 ### 恢复与崩溃恢复
 
-恢复就是 `load` 加会话准备：存储日志连同其头部血缘一起返回，因此恢复后的 agent（智能体）看到相同的历史与组装。中途崩溃的会话重新加载时，其被中断的最终轮次会保留并保持平衡：`load` 为未获回答的调用追加合成 `tool/result` 与 `turn/end {interrupted}` closer，而不是丢弃事件——单个轮次可能很大，而这些事件在崩溃前已持久写入。只有从未完整写入的撕裂尾部碎片会被丢弃。
+恢复就是 `load` 加会话准备：存储日志连同其 header 血缘与精确继承切点一起返回，因此所有权检查不从标记或完整恢复长度推断切点。中途崩溃的会话重新加载时，其被中断的最终轮次会保留并保持平衡：`load` 为未获回答的调用追加合成 `tool/result` 与 `turn/end {interrupted}` closer，而不是丢弃事件——单个轮次可能很大，而这些事件在崩溃前已持久写入。只有从未完整写入的撕裂尾部碎片会被丢弃。
 
 ### 失败与恢复
 
@@ -83,7 +83,7 @@ const headers = await ctx.sessionPersistence.list()        // every stored sessi
 | [`src/write-behind.ts`](src/write-behind.ts) | 每会话有界写入控制器与 flush 屏障 |
 | [`src/preparations.ts`](src/preparations.ts) | 为恢复复用而有界保留的未发布 Session 准备结果 |
 | [`src/revision.ts`](src/revision.ts) | 带品牌类型的不透明修订值 token |
-| [`src/invariant.ts`](src/invariant.ts) | 不变式伴生插件（无运行时不变式；协调器断言存储/活动身份与 cwd） |
+| — | 不发布运行时不变式伴生入口；协调器断言存储/活动身份与 cwd。 |
 
 ### 写入路径概览
 

package/lib/index.js

@@ -1,5 +1,5 @@
 import { Service } from "@deepseek-ai/cordis";
-import { KNOWN_SESSION_EVENT_TYPES, SESSION_FORMAT_VERSION, SessionPreparation, adoptSessionEvent, interruptedTurnClosers, snapshotSessionEvent } from "@deepseek-ai/dsh-session";
+import { KNOWN_SESSION_EVENT_TYPES, SESSION_FORMAT_VERSION, SessionLogOffset, SessionPreparation, SessionSeq, adoptSessionEvent, interruptedTurnClosers, snapshotSessionEvent } from "@deepseek-ai/dsh-session";
 import { MAX_TIMER_DELAY_MS } from "@deepseek-ai/dsh-timeout";
 import { snapshotJsonValue } from "@deepseek-ai/dsh-util-values";
 //#region lib/types/revision.js
@@ -549,6 +549,20 @@ function seedCoversPrefix(seed, prefix) {
 		return seedEvent !== void 0 && JSON.stringify(seedEvent) === JSON.stringify(event);
 	});
 }
+/** Normalize the exact fork cut paired with one logical Session header. */
+function storageMetadata(meta, inheritedEventCount) {
+	if (meta.isSeeded && inheritedEventCount === void 0) throw new TypeError("seeded session metadata requires an inherited event count");
+	const cut = SessionLogOffset(inheritedEventCount ?? 0);
+	if (!meta.isSeeded && cut !== 0) throw new TypeError("unseeded session metadata inherited event count must be 0");
+	return {
+		meta,
+		inheritedEventCount: cut
+	};
+}
+/** Exact storage metadata owned by one live Session. */
+function sessionStorageMetadata(session) {
+	return storageMetadata(session.header, session.inheritedEventCount);
+}
 /** Reject events from an obsolete v0 vocabulary that this build cannot replay. */
 function assertSupportedEvents(events, id) {
 	const legacyType = "request/header-delta";
@@ -576,7 +590,12 @@ function legacyMessageId(id, seq) {
 /** Read a replacement target while leaving malformed surface metadata to the session validator. */
 function replacementStart(event) {
 	const op = asRecord(event.surfaceOp);
-	return op?.["op"] === "replace" && typeof op["start"] === "number" ? op["start"] : void 0;
+	if (op?.["op"] !== "replace" || typeof op["start"] !== "number") return void 0;
+	try {
+		return SessionSeq(op["start"]);
+	} catch {
+		return;
+	}
 }
 /** Whether one suffix event needs facts available only from the preceding stored prefix. */
 function needsLegacyPrefix(event) {
@@ -852,12 +871,21 @@ var PersistenceCoordinator = class {
 	/**
 	* Register detached session metadata for lazy creation on the first append.
 	* @param meta - header to snapshot; duplicate tracked or persisted ids reject.
+	* @param inheritedEventCount - exact inherited prefix length; required for
+	* a seeded header and omitted only for an unseeded header.
 	*/
-	create(meta) {
+	create(meta, inheritedEventCount) {
 		const snapshot = snapshotJsonValue(meta);
 		if (snapshot === void 0) return Promise.reject(/* @__PURE__ */ new TypeError("session metadata must be losslessly JSON-serializable"));
 		if (!Number.isSafeInteger(snapshot.createdAt) || snapshot.createdAt < 0) return Promise.reject(/* @__PURE__ */ new TypeError("session metadata createdAt must be a non-negative safe integer"));
-		return this.serialize(snapshot.id, () => this.createCore(snapshot));
+		let storage;
+		try {
+			storage = storageMetadata(snapshot, inheritedEventCount);
+		} catch (error) {
+			/* v8 ignore next -- Session storage validation only throws Error instances. */
+			return Promise.reject(error instanceof Error ? error : new TypeError("invalid session storage metadata", { cause: error }));
+		}
+		return this.serialize(snapshot.id, () => this.createCore(storage));
 	}
 	/**
 	* Materialize one exact live session without inventing a session event.
@@ -871,17 +899,18 @@ var PersistenceCoordinator = class {
 			if (state === void 0) throw new Error(`session "${session.id}" is not registered for persistence`);
 			if (state.materialized) return;
 			if (this.backend.materializeHeader === void 0) throw new Error("session persistence backend cannot materialize an empty session");
-			await this.backend.materializeHeader(state.meta);
+			await this.backend.materializeHeader(state.storage);
 			state.materialized = true;
 			this.preparations.invalidate(session.id);
 		});
 	}
-	async createCore(meta) {
+	async createCore(storage) {
+		const { meta } = storage;
 		if (this.states.has(meta.id) || this.preparations.has(meta.id)) throw new Error(`session "${meta.id}" already exists in this backend`);
 		if (await this.backend.loadStored(meta.id) !== void 0) throw new Error(`session "${meta.id}" already has a persisted log on disk; load/resume it instead of creating`);
 		this.states.set(meta.id, {
-			meta,
-			cursor: 0,
+			storage,
+			cursor: SessionLogOffset(0),
 			materialized: false
 		});
 	}
@@ -904,9 +933,11 @@ var PersistenceCoordinator = class {
 		let state = this.states.get(id);
 		if (state === void 0) state = await this.adopt(id);
 		for (const [i, event] of events.entries()) if (event.seq !== state.cursor + i) throw new Error(`append seq mismatch for "${id}": expected ${state.cursor + i} at index ${i}, got ${event.seq}`);
-		await this.backend.appendBatch(state.meta, events, state.materialized);
+		const nextCursor = SessionLogOffset(state.cursor + events.length);
+		if (!state.materialized && nextCursor < state.storage.inheritedEventCount) throw new Error(`session "${id}" cannot materialize before its inherited prefix is complete`);
+		await this.backend.appendBatch(state.storage, events, state.materialized);
 		state.materialized = true;
-		state.cursor += events.length;
+		state.cursor = nextCursor;
 		this.preparations.invalidate(id);
 	}
 	/**
@@ -928,7 +959,7 @@ var PersistenceCoordinator = class {
 				throw new Error(`cannot prepare session "${id}" while it is live`);
 			}
 			return SessionPreparation.create(reservation.source.session, { release: () => {
-				this.preparations.release(reservation, reservation.state.owner === void 0 && reservation.source.session.events.length === reservation.source.sessionLength);
+				this.preparations.release(reservation, reservation.state.owner === void 0 && reservation.source.session.seq === reservation.source.sessionLength);
 			} });
 		}
 	}
@@ -1058,10 +1089,15 @@ var PersistenceCoordinator = class {
 	* @param id - persisted session to read.
 	* @param fromSeq - first event seq to include; a non-negative safe integer.
 	* @param signal - optional cancellation for queued and backend read work.
-	* @returns stored header and the valid stored events with `seq >= fromSeq`.
+	* @returns stored metadata, the requested offset, and valid events with `seq >= fromSeq`.
 	*/
 	readFrom(id, fromSeq, signal) {
-		if (!Number.isSafeInteger(fromSeq) || fromSeq < 0) return Promise.reject(/* @__PURE__ */ new TypeError(`readFrom fromSeq must be a non-negative safe integer, got ${String(fromSeq)}`));
+		try {
+			SessionLogOffset(fromSeq);
+		} catch (error) {
+			/* v8 ignore next -- Session log-offset validation only throws Error instances. */
+			return Promise.reject(error instanceof Error ? error : new TypeError("invalid session read offset", { cause: error }));
+		}
 		const retired = Promise.resolve(this.retirements.get(id));
 		return (signal === void 0 ? retired : observeQueuedAbort(retired, signal, () => false)).then(() => this.serialize(id, () => this.readFromCore(id, fromSeq, signal), signal));
 	}
@@ -1083,6 +1119,8 @@ var PersistenceCoordinator = class {
 				const whole = await this.readStoredPrefix(id, signal);
 				return {
 					meta: whole.meta,
+					inheritedEventCount: whole.inheritedEventCount,
+					fromSeq,
 					events: whole.events.filter((event) => event.seq >= fromSeq)
 				};
 			}
@@ -1090,12 +1128,16 @@ var PersistenceCoordinator = class {
 			this.assertEventsSupported(suffix.meta, events);
 			return {
 				meta: structuredClone(suffix.meta),
+				inheritedEventCount: SessionLogOffset(suffix.inheritedEventCount),
+				fromSeq,
 				events
 			};
 		}
 		const whole = await this.readStoredPrefix(id, signal);
 		return {
 			meta: whole.meta,
+			inheritedEventCount: whole.inheritedEventCount,
+			fromSeq,
 			events: whole.events.slice(fromSeq)
 		};
 	}
@@ -1111,6 +1153,7 @@ var PersistenceCoordinator = class {
 		this.assertEventsSupported(stored.meta, events);
 		return {
 			meta: structuredClone(stored.meta),
+			inheritedEventCount: SessionLogOffset(stored.inheritedEventCount),
 			events
 		};
 	}
@@ -1119,26 +1162,29 @@ var PersistenceCoordinator = class {
 		const stored = await this.backend.loadStored(id);
 		if (stored === void 0) throw new SessionPersistenceNotFoundError(id);
 		try {
-			const { meta, events, revision, tornMarker } = stored;
+			const { meta, inheritedEventCount, events, revision, tornMarker } = stored;
 			this.assertStoredId(id, meta);
 			this.assertVersion(meta);
 			const storedEvents = adoptStoredEvents(events, id);
 			this.assertEventsSupported(meta, storedEvents);
+			if (inheritedEventCount > storedEvents.length) throw new Error(`session "${id}" inherited event count exceeds its stored event count`);
 			const closers = interruptedTurnClosers(storedEvents).map(adoptSessionEvent);
 			const balanced = [...storedEvents, ...closers];
 			const session = this.ctx.sessions.prepare(id, {
 				seed: balanced,
 				meta,
+				inheritedEventCount,
 				seedSource: "persistence"
 			});
 			return {
 				inspection: Object.freeze({
 					meta: session.header,
+					inheritedEventCount: session.inheritedEventCount,
 					events: Object.freeze(balanced)
 				}),
 				session,
 				revision,
-				sessionLength: session.events.length,
+				sessionLength: session.seq,
 				tornMarker,
 				closers
 			};
@@ -1150,20 +1196,20 @@ var PersistenceCoordinator = class {
 	/** Commit one prepared repair and establish its ownerless durable cursor. */
 	async commitPrepared(source) {
 		const id = source.inspection.meta.id;
-		const cursor = source.inspection.events.length;
+		const cursor = SessionLogOffset(source.inspection.events.length);
 		const existing = this.states.get(id);
 		if (existing?.owner !== void 0) throw new Error(`session "${id}" already has a live persistence owner`);
 		if (!await this.isPreparedSourceCurrent(source)) return void 0;
 		if (source.tornMarker !== void 0 || source.closers.length > 0) {
-			await this.backend.commitRepair(source.inspection.meta, source.tornMarker, source.closers);
+			await this.backend.commitRepair(source.inspection, source.tornMarker, source.closers);
 			return;
 		}
 		const state = existing ?? {
-			meta: source.inspection.meta,
+			storage: source.inspection,
 			cursor,
 			materialized: true
 		};
-		state.meta = source.inspection.meta;
+		state.storage = source.inspection;
 		state.cursor = cursor;
 		state.materialized = true;
 		this.states.set(id, state);
@@ -1178,7 +1224,7 @@ var PersistenceCoordinator = class {
 	}
 	/** Return one durable immutable view of an already-live Session. */
 	async loadLiveSnapshot(session) {
-		const events = session.events;
+		const events = session.snapshotEvents();
 		await this.flush(session);
 		const state = this.states.get(session.id);
 		/* v8 ignore next -- successful flush always publishes this live session's durable state */
@@ -1186,7 +1232,8 @@ var PersistenceCoordinator = class {
 		if (events.length === 0 && !state.materialized) throw new Error(`session "${session.id}" not found`);
 		if (interruptedTurnClosers(events).length > 0) throw new Error(`cannot load session "${session.id}" while its live turn is open; use the live Session or wait for the turn to close`);
 		return Object.freeze({
-			meta: state.meta,
+			meta: state.storage.meta,
+			inheritedEventCount: state.storage.inheritedEventCount,
 			events
 		});
 	}
@@ -1194,7 +1241,8 @@ var PersistenceCoordinator = class {
 	inspectLive(session) {
 		return Object.freeze({
 			meta: session.header,
-			events: session.events
+			inheritedEventCount: session.inheritedEventCount,
+			events: session.snapshotEvents()
 		});
 	}
 	/** Await one retiring lifecycle with caller cancellation. */
@@ -1325,7 +1373,7 @@ var PersistenceCoordinator = class {
 			this.live.set(session, restored);
 			return restored;
 		}
-		const seed = session.events;
+		const seed = session.snapshotEvents();
 		const live = {
 			init: Promise.resolve(),
 			writes: this.createWriteBehind(session, () => live.init)
@@ -1339,7 +1387,7 @@ var PersistenceCoordinator = class {
 	attachPrepared(session, reservation) {
 		const { source, state } = reservation;
 		if (source.session !== session || state.owner !== void 0 || state.cursor !== source.inspection.events.length || session.firstLiveSeq !== state.cursor) throw new Error(`session "${session.id}" preparation no longer matches its persistence state`);
-		const suffix = session.events.slice(state.cursor).map((event) => structuredClone(event));
+		const suffix = session.snapshotEvents(state.cursor).map((event) => structuredClone(event));
 		this.preparations.attach(reservation);
 		state.owner = session;
 		const live = {
@@ -1385,7 +1433,8 @@ var PersistenceCoordinator = class {
 			/* v8 ignore next -- initFor dedupes per session object; same-object re-entry can't occur */
 			if (tracked.owner === session) return;
 			if (tracked.owner === void 0) {
-				if (tracked.meta.cwd !== session.header.cwd) throw new Error(`session "${id}" is already persisted at a different cwd (persisted: ${String(tracked.meta.cwd)}, live: ${String(session.header.cwd)}) (id collision)`);
+				if (tracked.storage.meta.cwd !== session.header.cwd) throw new Error(`session "${id}" is already persisted at a different cwd (persisted: ${String(tracked.storage.meta.cwd)}, live: ${String(session.header.cwd)}) (id collision)`);
+				if (tracked.storage.inheritedEventCount !== session.inheritedEventCount) throw new Error(`session "${id}" is already persisted with a different inherited event count (id collision)`);
 				if (!await this.seedMatchesPersisted(id, seed, tracked.cursor)) throw new Error(`session "${id}" is already persisted with ${tracked.cursor} event(s) that do not match this live session (id collision)`);
 				tracked.owner = session;
 				const suffix = seed.slice(tracked.cursor);
@@ -1401,8 +1450,11 @@ var PersistenceCoordinator = class {
 			await this.adoptLivePrefix(session, seed, live);
 			return;
 		}
-		const meta = { ...session.header };
-		await this.createCore(meta);
+		const storage = sessionStorageMetadata(session);
+		await this.createCore({
+			meta: { ...storage.meta },
+			inheritedEventCount: storage.inheritedEventCount
+		});
 		const created = this.states.get(id);
 		/* v8 ignore next -- create() always sets the state for the id */
 		if (created !== void 0) created.owner = session;
@@ -1415,17 +1467,21 @@ var PersistenceCoordinator = class {
 	* live suffix that was ahead of the stored prefix.
 	*/
 	async adoptLivePrefix(session, seed, stored) {
-		const { meta, events, tornMarker } = stored;
+		const { meta, inheritedEventCount, events, tornMarker } = stored;
 		this.assertStoredId(session.header.id, meta);
 		if (meta.cwd !== session.header.cwd) throw new Error(`session "${session.header.id}" is already persisted at a different cwd (persisted: ${String(meta.cwd)}, live: ${String(session.header.cwd)}) (id collision)`);
+		if (inheritedEventCount !== session.inheritedEventCount) throw new Error(`session "${session.header.id}" is already persisted with a different inherited event count (id collision)`);
 		this.assertVersion(meta);
 		const storedEvents = snapshotStoredEvents(events, session.header.id);
 		this.assertEventsSupported(meta, storedEvents);
 		if (!seedCoversPrefix(seed, storedEvents)) throw new Error(`session "${session.header.id}" already has a persisted log on disk that does not match this live session (id collision)`);
-		if (tornMarker !== void 0) await this.backend.commitRepair(meta, tornMarker, []);
+		if (tornMarker !== void 0) await this.backend.commitRepair(stored, tornMarker, []);
 		this.states.set(session.header.id, {
-			meta: { ...meta },
-			cursor: storedEvents.length,
+			storage: {
+				meta: { ...meta },
+				inheritedEventCount
+			},
+			cursor: SessionLogOffset(storedEvents.length),
 			materialized: true,
 			owner: session
 		});
@@ -1529,6 +1585,7 @@ var SessionPersistence = class extends Service {
 		return SessionPreparation.create(sessions.prepare(id, {
 			seed: loaded.events.map((event) => structuredClone(event)),
 			meta: structuredClone(loaded.meta),
+			inheritedEventCount: SessionLogOffset(loaded.inheritedEventCount),
 			seedSource: "persistence"
 		}));
 	}

package/lib/types/coordinator.d.ts

@@ -6,8 +6,8 @@
  */
 import { Context } from '@deepseek-ai/cordis';
 import { SessionPreparation } from '@deepseek-ai/dsh-session';
-import type { Session, SessionEvent, SessionId, SessionHeader } from '@deepseek-ai/dsh-session';
-import type { BorrowedSessionSource, SessionInspection, SessionLocation } from './index.ts';
+import type { Session, SessionEvent, SessionId, SessionHeader, SessionLogOffset as SessionLogOffsetType } from '@deepseek-ai/dsh-session';
+import type { BorrowedSessionSource, SessionEventSuffix, SessionInspection, SessionLocation, SessionStorageMetadata } from './index.ts';
 import type { SessionPersistenceRevision } from './revision.ts';
 /** Default number of detached session preparations retained by a coordinator. */
 export declare const DEFAULT_PREPARED_SESSION_CACHE_SIZE = 5;
@@ -65,8 +65,7 @@ export interface PersistenceCoordinatorOptions {
  * returns its value to {@link PersistenceBackend.commitRepair}; each backend
  * owns the marker type.
  */
-export interface StoredPrefix<TornMarker = unknown> {
-    meta: SessionHeader;
+export interface StoredPrefix<TornMarker = unknown> extends SessionStorageMetadata {
     events: SessionEvent[];
     /** Revision observed for exactly this detached prefix. */
     revision: SessionPersistenceRevision;
@@ -78,8 +77,7 @@ export interface StoredPrefix<TornMarker = unknown> {
  * {@link PersistenceBackend.loadStoredFrom} hook. Non-mutating reads carry no
  * torn marker: there is nothing to repair.
  */
-export interface StoredSuffix {
-    meta: SessionHeader;
+export interface StoredSuffix extends SessionStorageMetadata {
     events: SessionEvent[];
 }
 /**
@@ -138,16 +136,18 @@ export interface PersistenceBackend<TornMarker = unknown> {
      *   validated by the coordinator before this hook runs).
      * @param signal - optional cancellation for backend read work.
      */
-    loadStoredFrom?(id: SessionId, fromSeq: number, signal?: AbortSignal): Promise<StoredSuffix | undefined>;
+    loadStoredFrom?(id: SessionId, fromSeq: SessionLogOffsetType, signal?: AbortSignal): Promise<StoredSuffix | undefined>;
     /** Durably create an empty header-only session artifact. */
-    materializeHeader?(meta: SessionHeader): Promise<void>;
+    materializeHeader?(storage: SessionStorageMetadata): Promise<void>;
     /**
      * Durably append a CONTIGUOUS batch, lazily materializing the session first
      * when `!isMaterialized`. The materialize-write and the first event batch MUST
      * commit ATOMICALLY (a crash between them must not leave a materialized-but-
      * empty session). Returns once the batch is durable.
+     * The coordinator calls this only after a first batch reaches the declared
+     * inherited prefix length.
      */
-    appendBatch(meta: SessionHeader, events: readonly SessionEvent[], isMaterialized: boolean): Promise<void>;
+    appendBatch(storage: SessionStorageMetadata, events: readonly SessionEvent[], isMaterialized: boolean): Promise<void>;
     /**
      * Make a crash repair durable: truncate the torn tail (iff
      * `tornMarker !== undefined`) and append `closers` (iff any). NOT required to
@@ -155,7 +155,7 @@ export interface PersistenceBackend<TornMarker = unknown> {
      * Used by load (truncate + synthetic closers) and by live-adoption (truncate
      * only, `closers = []`).
      */
-    commitRepair(meta: SessionHeader, tornMarker: TornMarker | undefined, closers: readonly SessionEvent[]): Promise<void>;
+    commitRepair(storage: SessionStorageMetadata, tornMarker: TornMarker | undefined, closers: readonly SessionEvent[]): Promise<void>;
     /**
      * List all stored (materialized) sessions' metadata.
      * @param signal - optional cancellation for backend listing work.
@@ -210,8 +210,10 @@ export declare class PersistenceCoordinator<TornMarker = unknown> {
     /**
      * Register detached session metadata for lazy creation on the first append.
      * @param meta - header to snapshot; duplicate tracked or persisted ids reject.
+     * @param inheritedEventCount - exact inherited prefix length; required for
+     * a seeded header and omitted only for an unseeded header.
      */
-    create(meta: SessionHeader): Promise<void>;
+    create(meta: SessionHeader, inheritedEventCount?: SessionLogOffsetType): Promise<void>;
     /**
      * Materialize one exact live session without inventing a session event.
      * @param session - live session already registered through the write path.
@@ -271,12 +273,9 @@ export declare class PersistenceCoordinator<TornMarker = unknown> {
      * @param id - persisted session to read.
      * @param fromSeq - first event seq to include; a non-negative safe integer.
      * @param signal - optional cancellation for queued and backend read work.
-     * @returns stored header and the valid stored events with `seq >= fromSeq`.
+     * @returns stored metadata, the requested offset, and valid events with `seq >= fromSeq`.
      */
-    readFrom(id: SessionId, fromSeq: number, signal?: AbortSignal): Promise<{
-        meta: SessionHeader;
-        events: SessionEvent[];
-    }>;
+    readFrom(id: SessionId, fromSeq: SessionLogOffsetType, signal?: AbortSignal): Promise<SessionEventSuffix>;
     private readFromCore;
     /** Read one detached physical prefix without logical recovery or caching. */
     private readStoredPrefix;

package/lib/types/index.d.ts

@@ -5,7 +5,7 @@
  * @module @deepseek-ai/dsh-session-persistence
  */
 import { Context, Service } from '@deepseek-ai/cordis';
-import { SessionPreparation } from '@deepseek-ai/dsh-session';
+import { SessionPreparation, SessionLogOffset } from '@deepseek-ai/dsh-session';
 import type { Session, SessionEvent, SessionId, SessionHeader } from '@deepseek-ai/dsh-session';
 import type { SessionPersistenceRevision } from './revision.ts';
 export type { SessionHeader } from '@deepseek-ai/dsh-session';
@@ -18,13 +18,25 @@ export interface SessionPersistenceSnapshot {
     /** Opaque source-qualified token that changes whenever this stored log changes. */
     revision: SessionPersistenceRevision;
 }
-/** Immutable logical session prepared from persistence or a live owner. */
-export interface SessionInspection {
-    /** Validated immutable session metadata. */
+/** Logical Session header paired with its exact inherited cut for body-bearing storage operations. */
+export interface SessionStorageMetadata {
+    /** Validated immutable Session header. */
     readonly meta: SessionHeader;
+    /** Number of leading events inherited from the Session's fork parent. */
+    readonly inheritedEventCount: SessionLogOffset;
+}
+/** Immutable logical session prepared from persistence or a live owner. */
+export interface SessionInspection extends SessionStorageMetadata {
     /** Validated contiguous logical event log. */
     readonly events: readonly SessionEvent[];
 }
+/** Detached logical suffix returned by one explicit stored-log offset read. */
+export interface SessionEventSuffix extends SessionStorageMetadata {
+    /** First requested log offset; {@link events} contains only seqs at or after it. */
+    readonly fromSeq: SessionLogOffset;
+    /** Valid contiguous stored events at or after {@link fromSeq}; not a complete Session log when the offset is nonzero. */
+    readonly events: readonly SessionEvent[];
+}
 /** A borrowed exact Session source returned from a cold materialization or concurrent live owner. */
 export type BorrowedSessionSource = Disposable & ({
     /** A reusable unpublished Session is pinned until this observation is disposed. */
@@ -42,9 +54,7 @@ export type BorrowedSessionSource = Disposable & ({
     readonly inspection: SessionInspection;
 });
 /** A backend's own raw artifact text for one session, verbatim. */
-export interface SessionRawArtifact {
-    /** The session header parsed from the artifact's own first line. */
-    readonly meta: SessionHeader;
+export interface SessionRawArtifact extends SessionStorageMetadata {
     /** The artifact's base filename on disk, without any physical encoding suffix. */
     readonly filename: string;
     /** The artifact's full text content, decoded from the backend's physical encoding. */
@@ -111,8 +121,10 @@ export declare abstract class SessionPersistence extends Service {
      * created-but-never-appended session is absent from {@link list}
      * — abandoned sessions leave nothing behind.
      * @param meta - the immutable header (id, version, cwd, lineage) to record.
+     * @param inheritedEventCount - exact fork-inherited prefix length. Required
+     * for a seeded header and omitted only for an unseeded header.
      */
-    abstract create(meta: SessionHeader): Promise<void>;
+    abstract create(meta: SessionHeader, inheritedEventCount?: SessionLogOffset): Promise<void>;
     /**
      * Ensure a live session has a durable header even when it has no events.
      * Ordinary sessions remain lazily materialized; lifecycle frontends call
@@ -125,6 +137,8 @@ export declare abstract class SessionPersistence extends Service {
      * seq contracts: the first event's `seq` MUST equal the stored next-seq
      * (after `load` has durably closed any interrupted turn). Rejects non-JSON-
      * serializable `event.data` with an error naming the offending event type.
+     * A seeded session's first materializing batch must reach its complete
+     * inherited prefix.
      * @param id - the session the batch belongs to.
      * @param events - the contiguous batch to persist, in seq order.
      */
@@ -194,14 +208,11 @@ export declare abstract class SessionPersistence extends Service {
      * forward. The primitive bounds what is returned and refolded, not every
      * backend's physical read.
      * @param id - the persisted session to read.
-     * @param fromSeq - first event seq to include; a non-negative safe integer.
+     * @param fromSeq - first event offset to include.
      * @param signal - optional cancellation for queued and backend read work.
-     * @returns the header and the stored events with `seq >= fromSeq`.
+     * @returns storage metadata, the requested offset, and stored events with `seq >= fromSeq`.
      */
-    abstract readFrom(id: SessionId, fromSeq: number, signal?: AbortSignal): Promise<{
-        meta: SessionHeader;
-        events: SessionEvent[];
-    }>;
+    abstract readFrom(id: SessionId, fromSeq: SessionLogOffset, signal?: AbortSignal): Promise<SessionEventSuffix>;
     /**
      * Lightweight listing from metadata, without a full-log parse.
      * @param signal - optional cancellation for backend listing work.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-session-persistence",
   "description": "Abstract durable session persistence seam (ctx.sessionPersistence) for the DeepSeek Harness",
-  "version": "0.1.2-alpha.3",
+  "version": "0.1.2-alpha.5",
   "publishConfig": {
     "access": "public"
   },
@@ -18,35 +18,28 @@
       "types": "./lib/types/index.d.ts",
       "default": "./lib/index.js"
     },
-    "./invariant": {
-      "types": "./lib/types/invariant.d.ts",
-      "default": "./lib/invariant.js"
-    },
     "./src/*": "./src/*",
     "./package.json": "./package.json"
   },
   "files": [
     "lib/index.js",
-    "lib/invariant.js",
     "lib/types/**/*.d.ts"
   ],
   "license": "MIT",
   "peerDependencies": {
+    "@deepseek-ai/dsh-brand": "^0.1.2-alpha.5",
+    "@deepseek-ai/dsh-session": "^0.1.2-alpha.5",
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-brand": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-session": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-timeout": "^0.1.2-alpha.3"
+    "@deepseek-ai/dsh-timeout": "^0.1.2-alpha.5"
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-brand": "^0.1.2-alpha.5",
+    "@deepseek-ai/dsh-scope": "^0.1.2-alpha.5",
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-brand": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-scope": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-session": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-timeout": "^0.1.2-alpha.3"
+    "@deepseek-ai/dsh-session": "^0.1.2-alpha.5",
+    "@deepseek-ai/dsh-timeout": "^0.1.2-alpha.5"
   },
   "dependencies": {
-    "@deepseek-ai/dsh-util-values": "^0.1.2-alpha.3"
+    "@deepseek-ai/dsh-util-values": "^0.1.2-alpha.5"
   }
 }

package/lib/invariant.js

@@ -1,23 +0,0 @@
-//#region lib/types/invariant.js
-/**
-* Package-owned invariant companion for `@deepseek-ai/dsh-session-persistence`.
-* @module @deepseek-ai/dsh-session-persistence/invariant
-*/
-const PACKAGE_NAME = "@deepseek-ai/dsh-session-persistence";
-/** Cordis companion plugin name. */
-const name = "session-persistence-invariant";
-/** Service required before the companion can reserve package ownership. */
-const inject = ["invariants"];
-/**
-* No runtime invariant: persistence correctness requires backend round-trip and crash-tail tests;
-* this package exposes no continuously observable in-process relation.
-*/
-const install = () => {};
-/**
-* Register this package's 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/invariant.d.ts

@@ -1,16 +0,0 @@
-/**
- * Package-owned invariant companion for `@deepseek-ai/dsh-session-persistence`.
- * @module @deepseek-ai/dsh-session-persistence/invariant
- */
-import type { Context } from '@deepseek-ai/cordis';
-/** Cordis companion plugin name. */
-export declare const name = "session-persistence-invariant";
-/** Service required before the companion can reserve package ownership. */
-export declare const inject: string[];
-/**
- * Register this package's 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