@deepseek-ai/dsh-session-persistence-jsonl 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-persistence-jsonl/README.md
-README.md: 69fb2901d783c327878cd37570aec730a3ca0841
-README.zh.md: 188982028374d4ca11a5a658acabce5fe5df9930
+README.md: d3dfaf8affb142979ede69d86bbf0b1587e8c39c
+README.zh.md: 15fc815523355674a1f325b604dd2655f56f7f58

package/README.md

@@ -29,7 +29,7 @@ Mount this backend when a composition needs durable sessions backed by per-sessi
 
 ### When to choose it
 
-Choose this backend when consumers benefit from one artifact per session — navigation, external tooling, or a raw line-readable log. Choose [SQLite](../session-persistence-sqlite/README.md) when a single queryable database fits the deployment instead. The backend keeps sessions under a deployment-controlled root: project-local, shared, temporary, or centralized.
+Choose this backend when consumers benefit from one artifact per session — navigation, external tooling, or a raw line-readable log. It is the sole first-party Session-persistence provider. The backend keeps sessions under a deployment-controlled root: project-local, shared, temporary, or centralized.
 
 ### Minimal configuration
 
@@ -54,7 +54,7 @@ The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-a
 
 ### On-disk layout
 
-Each session gets a session-owned directory under a readable project directory; the first logical line of the log is the immutable `SessionHeader`, followed by one storage record per logical event (or one packed chunk row per eligible run). Storage records use the lossless provenance representation described below:
+Each session gets a session-owned directory under a readable project directory; the first logical line is the private v0 physical header, followed by one storage record per logical event (or one packed chunk row per eligible run). Its optional numeric `seedLength` remains byte-compatible: absence decodes to `SessionHeader.isSeeded: false`, while zero or a positive value decodes to `isSeeded: true` plus the exact `inheritedEventCount`. Storage records use the lossless provenance representation described below:
 
 ```text
 <root>/
@@ -72,7 +72,7 @@ A session is materialized lazily: `create(meta)` writes nothing, and the first `
 
 ### Reading the logs
 
-`inspect(id)` returns an immutable balanced view without committing recovery. `readFrom(id, fromSeq)` returns stored events at or past a sequence number for watermark consumers; sequential media like JSONL parse the whole artifact and skip forward. With `compression: 'none'`, the log is newline-delimited text an external reader can consume directly; the compressed default must be read through the backend.
+`inspect(id)` returns an immutable balanced view with its exact inherited cut without committing recovery. `readFrom(id, fromOffset)` accepts a `SessionLogOffset`, returns stored events at or past that offset, and retains the same cut beside the suffix; sequential media like JSONL parse the whole artifact and skip forward. Header-only listing exposes `isSeeded` without reading event bodies. With `compression: 'none'`, the log is newline-delimited text an external reader can consume directly; the compressed default must be read through the backend.
 
 -----
 
@@ -100,7 +100,7 @@ The default artifact is a standard concatenation of independent [Zstandard frame
 | [`src/format.ts`](src/format.ts) | Log path derivation, header encoding, record scanning, packed-row layout |
 | [`src/zstd.ts`](src/zstd.ts) | Zstandard frame compression, decoding, and frame scanning |
 | [`src/win32.ts`](src/win32.ts) | Windows write-through publish and directory creation |
-| [`src/invariant.ts`](src/invariant.ts) | Invariant companion (no runtime invariant; identity is enforced at the storage layer) |
+| — | 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. |
 
 </details>
 
@@ -113,7 +113,6 @@ Read these pages when the package-level contract is not enough. They move from t
 
 - [Session persistence subsystem](../../../docs/subsystems/persistence.md) — backend-neutral service semantics and provider relationships.
 - [Session persistence seam](../session-persistence/README.md) — the service contract this backend implements.
-- [SQLite persistence backend](../session-persistence-sqlite/README.md) — the opt-in single-database alternative.
 - [Project-session directory decision](../../../.agents/notes/implemented/architecture/2026-07-24-project-session-directories.md) — the layout tradeoff behind project and session directories.
 - [Zstandard JSONL session logs](../../../.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.md) — the checksummed-frame encoding rationale.
 

package/README.zh.md

@@ -29,7 +29,7 @@ kind: "package-reference"
 
 ### 何时选择
 
-当消费方受益于每会话一份产物——导航、外部工具或可逐行读取的原始日志——时选择此后端。当单一可查询数据库更适合部署时，选择 [SQLite](../session-persistence-sqlite/README.zh.md)。后端把会话保存在部署控制的根下：项目本地、共享、临时或集中式。
+当消费方受益于每会话一份产物——导航、外部工具或可逐行读取的原始日志——时选择此后端。它是随产品交付的唯一 Session 持久化 provider。后端把会话保存在部署控制的根下：项目本地、共享、临时或集中式。
 
 ### 最小配置
 
@@ -54,7 +54,7 @@ kind: "package-reference"
 
 ### 磁盘布局
 
-每个会话在可读项目目录下获得一个会话自有目录；日志第一个逻辑行是不可变 `SessionHeader`，之后每个逻辑事件一条存储记录（或每个符合条件的连续段一条打包分片行）。存储记录使用下文所述的无损来源序列表示：
+每个会话在可读项目目录下获得一个会话自有目录；第一个逻辑行是私有 v0 物理 header，之后每个逻辑事件一条存储记录（或每个符合条件的连续段一条打包分片行）。其可选数字 `seedLength` 保持字节兼容：缺席解码为 `SessionHeader.isSeeded: false`，零或正值解码为 `isSeeded: true` 加精确 `inheritedEventCount`。存储记录使用下文所述的无损来源序列表示：
 
 ```text
 <root>/
@@ -72,7 +72,7 @@ kind: "package-reference"
 
 ### 读取日志
 
-`inspect(id)` 返回不可变的平衡视图，不提交恢复。`readFrom(id, fromSeq)` 为水位消费方返回该序列号及之后的已存储事件；JSONL 这类顺序介质解析整个产物并向前跳过。选择 `compression: 'none'` 后，日志是外部读取方可直接消费的换行分隔文本；压缩默认值必须经后端读取。
+`inspect(id)` 返回带精确继承切点的不可变平衡视图，不提交恢复。`readFrom(id, fromOffset)` 接受 `SessionLogOffset`，返回该偏移及之后的已存储事件，并在后缀旁保留同一切点；JSONL 这类顺序介质解析整个产物并向前跳过。仅 header 的列表读取不读事件正文即可公开 `isSeeded`。选择 `compression: 'none'` 后，日志是外部读取方可直接消费的换行分隔文本；压缩默认值必须经后端读取。
 
 -----
 
@@ -100,7 +100,7 @@ kind: "package-reference"
 | [`src/format.ts`](src/format.ts) | 日志路径派生、header 编码、记录扫描、打包行布局 |
 | [`src/zstd.ts`](src/zstd.ts) | Zstandard 帧压缩、解码与帧扫描 |
 | [`src/win32.ts`](src/win32.ts) | Windows write-through 发布与目录创建 |
-| [`src/invariant.ts`](src/invariant.ts) | 不变式伴生插件（无运行时不变式；身份在存储层强制） |
+| — | 不发布运行时不变式伴生入口；身份在存储层强制。 |
 
 </details>
 
@@ -113,7 +113,6 @@ kind: "package-reference"
 
 - [会话持久化子系统](../../../docs/subsystems/persistence.zh.md)——后端无关的服务语义与提供方关系。
 - [会话持久化 seam](../session-persistence/README.zh.md)——本后端实现的服务约定。
-- [SQLite 持久化后端](../session-persistence-sqlite/README.zh.md)——可选启用的单数据库替代方案。
 - [项目会话目录决策](../../../.agents/notes/implemented/architecture/2026-07-24-project-session-directories.zh.md)——项目与会话目录布局背后的取舍。
 - [Zstandard JSONL 会话日志](../../../.agents/notes/implemented/architecture/2026-07-19-zstandard-jsonl-session-logs.zh.md)——带校验和帧编码的理由。
 

package/lib/index.js

@@ -6,7 +6,7 @@ import { performance } from "node:perf_hooks";
 import { scheduler } from "node:timers/promises";
 import { randomBytes } from "node:crypto";
 import { DEFAULT_PREPARED_SESSION_CACHE_SIZE, DEFAULT_WRITE_BATCH_MAX_DELAY_MS, MAX_WRITE_BATCH_DELAY_MS, PersistenceCoordinator, SessionFormatUnsupportedError, SessionPersistence, SessionPersistenceRevision, sessionFormatVersionRefusal } from "@deepseek-ai/dsh-session-persistence";
-import { SESSION_FORMAT_VERSION, decodeSeqRanges, decodeStorageRecord, encodeSeqRanges, packChunkRuns } from "@deepseek-ai/dsh-session";
+import { SESSION_FORMAT_VERSION, SessionLogOffset, decodeSeqRanges, decodeStorageRecord, encodeSeqRanges, packChunkRuns } from "@deepseek-ai/dsh-session";
 import { constants, createZstdDecompress, zstdCompress, zstdDecompress, zstdDecompressSync } from "node:zlib";
 import { promisify } from "node:util";
 import { constants as constants$1 } from "node:buffer";
@@ -31,9 +31,14 @@ function logSuffix(compression) {
 /**
 * Build the header line object from a {@link SessionHeader}.
 * @param header - the immutable session metadata to serialize.
+* @param inheritedEventCount - exact inherited prefix length; required for a
+* seeded header and omitted only for an unseeded header.
 * @returns the `type: 'session'`-tagged line object, absent optional fields omitted (never null).
 */
-function toHeaderLine(header) {
+function toHeaderLine(header, inheritedEventCount) {
+	if (header.isSeeded && inheritedEventCount === void 0) throw new Error("seeded session header requires an inherited event count");
+	const cut = SessionLogOffset(inheritedEventCount ?? 0);
+	if (!header.isSeeded && cut !== 0) throw new Error("unseeded session header inherited event count must be 0");
 	return {
 		type: "session",
 		version: header.version,
@@ -41,34 +46,37 @@ function toHeaderLine(header) {
 		createdAt: header.createdAt,
 		...header.cwd !== void 0 ? { cwd: header.cwd } : {},
 		...header.parentSession !== void 0 ? { parentSession: header.parentSession } : {},
-		...header.seedLength !== void 0 ? { seedLength: header.seedLength } : {},
+		...header.isSeeded ? { seedLength: cut } : {},
 		...header.origin !== void 0 ? { origin: header.origin } : {},
 		delegationDepth: header.delegationDepth ?? 0,
 		...header.agentPreset !== void 0 ? { agentPreset: header.agentPreset } : {}
 	};
 }
 /**
-* Parse a header line back into a {@link SessionHeader}.
+* Translate one version-0 physical header into logical metadata and its cut.
 * @param line - the shape-checked first line of a log (see the `isHeaderLine` guard).
-* @returns the header, absent optional fields omitted.
+* @returns logical Session metadata paired with the exact inherited prefix length.
 */
 function fromHeaderLine(line) {
 	if (Object.hasOwn(line, "sandboxMode") || Object.hasOwn(line, "approvalPolicy")) throw new Error("session header uses retired policy baseline fields");
 	return {
-		version: line.version,
-		id: line.id,
-		createdAt: line.createdAt,
-		...line.cwd !== void 0 ? { cwd: line.cwd } : {},
-		...line.parentSession !== void 0 ? { parentSession: line.parentSession } : {},
-		...line.seedLength !== void 0 ? { seedLength: line.seedLength } : {},
-		...line.origin !== void 0 ? { origin: line.origin } : {},
-		delegationDepth: line.delegationDepth,
-		...line.agentPreset !== void 0 ? { agentPreset: line.agentPreset } : {}
+		meta: {
+			version: line.version,
+			id: line.id,
+			createdAt: line.createdAt,
+			...line.cwd !== void 0 ? { cwd: line.cwd } : {},
+			...line.parentSession !== void 0 ? { parentSession: line.parentSession } : {},
+			isSeeded: line.seedLength !== void 0,
+			...line.origin !== void 0 ? { origin: line.origin } : {},
+			delegationDepth: line.delegationDepth,
+			...line.agentPreset !== void 0 ? { agentPreset: line.agentPreset } : {}
+		},
+		inheritedEventCount: SessionLogOffset(line.seedLength ?? 0)
 	};
 }
 /** Type guard: a parsed first line is a well-formed session header. */
 function isHeaderLine(value) {
-	return typeof value === "object" && value !== null && value.type === "session" && typeof value.version === "number" && typeof value.id === "string" && typeof value.createdAt === "number" && Number.isSafeInteger(value.createdAt) && value.createdAt >= 0 && !Object.is(value.createdAt, -0) && typeof value.delegationDepth === "number" && Number.isSafeInteger(value.delegationDepth) && value.delegationDepth >= 0 && !Object.is(value.delegationDepth, -0) && (value.origin === void 0 || value.origin === "subagent") && (value.agentPreset === void 0 || typeof value.agentPreset === "string");
+	return typeof value === "object" && value !== null && value.type === "session" && typeof value.version === "number" && typeof value.id === "string" && typeof value.createdAt === "number" && Number.isSafeInteger(value.createdAt) && value.createdAt >= 0 && !Object.is(value.createdAt, -0) && typeof value.delegationDepth === "number" && Number.isSafeInteger(value.delegationDepth) && value.delegationDepth >= 0 && !Object.is(value.delegationDepth, -0) && (value.seedLength === void 0 || typeof value.seedLength === "number" && Number.isSafeInteger(value.seedLength) && value.seedLength >= 0 && !Object.is(value.seedLength, -0)) && (value.origin === void 0 || value.origin === "subagent") && (value.agentPreset === void 0 || typeof value.agentPreset === "string");
 }
 /**
 * Encode an arbitrary string as a single safe path segment, injectively over ALL JS (UTF-16)
@@ -176,7 +184,7 @@ function eventLines(events, packChunks) {
 * stays verbatim.
 * @param record - one stored record (event or packed row).
 * @returns the record with its provenance in storage form (widened from the
-*   in-memory `number[]`; {@link expandProvenanceFromStorage} restores it).
+*   in-memory `SessionSeq[]`; {@link expandProvenanceFromStorage} restores it).
 */
 function encodeProvenanceForStorage(record) {
 	if (!("sourceEventSeqs" in record)) return record;
@@ -186,7 +194,7 @@ function encodeProvenanceForStorage(record) {
 	};
 }
 /**
-* Expand a parsed line's storage-form provenance back to `number[]`.
+* Expand a parsed line's storage-form provenance back to `SessionSeq[]`.
 * @param parsed - the JSON-parsed value of one stored line.
 * @returns the value with provenance expanded.
 * @throws when the record or its storage-form provenance is malformed.
@@ -235,6 +243,7 @@ function parseHeaderRecord(record) {
 */
 var SessionLogScanner = class {
 	meta;
+	inheritedEventCount;
 	events = [];
 	fragments = [];
 	fragmentBytes = 0;
@@ -248,7 +257,9 @@ var SessionLogScanner = class {
 	* @param headerRecord - the complete first JSONL record, including its newline.
 	*/
 	constructor(headerRecord) {
-		this.meta = parseHeaderRecord(headerRecord);
+		const parsed = parseHeaderRecord(headerRecord);
+		this.meta = parsed.meta;
+		this.inheritedEventCount = parsed.inheritedEventCount;
 		this.inputBytes = headerRecord.length;
 		this.committedBytes = headerRecord.length;
 	}
@@ -287,7 +298,7 @@ var SessionLogScanner = class {
 		return {
 			inputBytes: this.inputBytes,
 			committedBytes: this.committedBytes,
-			eventCount: this.events.length
+			eventCount: SessionLogOffset(this.events.length)
 		};
 	}
 	/**
@@ -298,6 +309,7 @@ var SessionLogScanner = class {
 		this.finished = true;
 		return {
 			meta: this.meta,
+			inheritedEventCount: this.inheritedEventCount,
 			events: this.events,
 			committedBytes: this.committedBytes
 		};
@@ -346,23 +358,30 @@ function scanLog(buffer) {
 	return scanner.finish();
 }
 /**
-* Parse just the header line of a log into a {@link SessionHeader}, or
-* `undefined` if it is missing/not a header. Used by `list()` to read session
-* metadata WITHOUT parsing the whole log: a session picker scales with the
-* number of sessions, not the total size of every conversation.
+* Parse just the header line of a log into logical metadata plus its exact
+* inherited cut, or `undefined` if it is missing/not a header.
 * @param firstLine - the first line of a log file (without its trailing newline).
-* @returns the parsed header, or `undefined` when the line is not a well-formed session header.
+* @returns parsed storage metadata, or `undefined` for a malformed header.
 */
-function parseHeaderMeta(firstLine) {
+function parseHeader(firstLine) {
 	let parsed;
 	try {
 		parsed = JSON.parse(firstLine);
 	} catch {
 		return;
 	}
+	refuseForeignFormatVersion(parsed);
 	if (!isHeaderLine(parsed)) return void 0;
 	return fromHeaderLine(parsed);
 }
+/**
+* Parse only the logical header fields needed by lightweight listing.
+* @param firstLine - first JSONL line without its trailing newline.
+* @returns the logical Session header, or `undefined` for a malformed line.
+*/
+function parseHeaderMeta(firstLine) {
+	return parseHeader(firstLine)?.meta;
+}
 //#endregion
 //#region lib/types/zstd-private-decoder.js
 /**
@@ -837,8 +856,8 @@ var JsonlSessionPersistence = class extends SessionPersistence {
 			path: logPath(this.root, meta.cwd, meta.id, this.compression)
 		};
 	}
-	create(meta) {
-		return this.coordinator.create(meta);
+	create(meta, inheritedEventCount) {
+		return this.coordinator.create(meta, inheritedEventCount);
 	}
 	ensureMaterialized(session) {
 		return this.coordinator.ensureMaterialized(session);
@@ -922,10 +941,10 @@ var JsonlSessionPersistence = class extends SessionPersistence {
 			}
 			content = Buffer.concat(plaintexts).toString("utf8");
 		} else content = buffer.toString("utf8");
-		const meta = parseHeaderMeta(content.split("\n", 1)[0]);
-		if (meta === void 0 || meta.id !== id) throw new Error(`corrupt session log: invalid header line in "${path}"`);
+		const storage = parseHeader(content.split("\n", 1)[0]);
+		if (storage === void 0 || storage.meta.id !== id) throw new Error(`corrupt session log: invalid header line in "${path}"`);
 		return {
-			meta,
+			...storage,
 			filename: "session.jsonl",
 			content
 		};
@@ -962,10 +981,11 @@ var JsonlSessionPersistence = class extends SessionPersistence {
 			if (this.compression === "zstd") prefix = await this.readZstdPrefix(buffer, signal);
 			else {
 				signal?.throwIfAborted();
-				const { meta, events, committedBytes } = scanLog(buffer);
+				const { meta, inheritedEventCount, events, committedBytes } = scanLog(buffer);
 				signal?.throwIfAborted();
 				prefix = {
 					meta,
+					inheritedEventCount,
 					events,
 					...committedBytes < buffer.byteLength ? { tornMarker: {
 						truncateTo: committedBytes,
@@ -1023,6 +1043,7 @@ var JsonlSessionPersistence = class extends SessionPersistence {
 				const prefix = scanner.finish();
 				return {
 					meta: prefix.meta,
+					inheritedEventCount: prefix.inheritedEventCount,
 					events: prefix.events
 				};
 			}
@@ -1040,6 +1061,7 @@ var JsonlSessionPersistence = class extends SessionPersistence {
 			signal?.throwIfAborted();
 			return {
 				meta: recoveredPrefix.meta,
+				inheritedEventCount: recoveredPrefix.inheritedEventCount,
 				events: recoveredPrefix.events,
 				tornMarker: {
 					truncateTo: tornStart,
@@ -1055,21 +1077,22 @@ var JsonlSessionPersistence = class extends SessionPersistence {
 		}
 	}
 	/** Durably append a batch, lazily materializing the file when not yet present. */
-	async appendBatch(meta, events, isMaterialized) {
+	async appendBatch(storage, events, isMaterialized) {
 		await this.ensureRootEncoding();
-		if (isMaterialized) await this.appendLines(meta, events);
-		else await this.materialize(meta, events);
+		if (isMaterialized) await this.appendLines(storage.meta, events);
+		else await this.materialize(storage, events);
 	}
 	/** Materialize a header-only JSONL artifact for an explicitly durable empty session. */
-	async materializeHeader(meta) {
-		await this.materialize(meta, []);
+	async materializeHeader(storage) {
+		await this.materialize(storage, []);
 	}
 	/**
 	* Make a crash repair durable: truncate a torn tail, restore complete events
 	* decoded from it, then append synthetic closers. Two fsync'd steps — the seam
 	* does not require this to be atomic.
 	*/
-	async commitRepair(meta, tornMarker, closers) {
+	async commitRepair(storage, tornMarker, closers) {
+		const { meta } = storage;
 		if (tornMarker !== void 0) await this.repair(meta, tornMarker.truncateTo);
 		const repairedEvents = [...tornMarker?.recoveredEvents ?? [], ...closers];
 		if (repairedEvents.length > 0) await this.appendLines(meta, repairedEvents);
@@ -1136,12 +1159,13 @@ var JsonlSessionPersistence = class extends SessionPersistence {
 		return artifacts;
 	}
 	/** Atomically write the header line + first batch (temp-write, fsync, publish). */
-	async materialize(meta, events) {
+	async materialize(storage, events) {
+		const { meta } = storage;
 		const project = projectDir(this.root, meta.cwd);
 		const dir = sessionDir(this.root, meta.cwd, meta.id);
 		const finalPath = logPath(this.root, meta.cwd, meta.id, this.compression);
 		await this.rejectOppositeArtifact(meta.cwd, meta.id);
-		const content = await this.encodeMaterialization(meta, events);
+		const content = await this.encodeMaterialization(storage, events);
 		/* v8 ignore next -- native Windows coverage exercises this platform dispatch; Linux covers the POSIX peer */
 		if (process.platform === "win32") await this.materializeWin32(project, dir, finalPath, meta.id, content);
 		else await this.materializePosix(project, dir, finalPath, meta.id, content);
@@ -1210,8 +1234,8 @@ var JsonlSessionPersistence = class extends SessionPersistence {
 		return tmp;
 	}
 	/** Encode the header and first batch without combining their frame boundaries. */
-	async encodeMaterialization(meta, events) {
-		const header = JSON.stringify(toHeaderLine(meta)) + "\n";
+	async encodeMaterialization(storage, events) {
+		const header = JSON.stringify(toHeaderLine(storage.meta, storage.inheritedEventCount)) + "\n";
 		if (events.length === 0) return this.compression === "none" ? header : compressZstdFrame(header);
 		const body = eventLines(events, this.packChunks) + "\n";
 		if (this.compression === "none") return header + body;

package/lib/types/format.d.ts

@@ -7,7 +7,8 @@
  *
  * @module dsh-session-persistence-jsonl/format
  */
-import type { SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session';
+import type { SessionEvent, SessionHeader, SessionId, SessionLogOffset as SessionLogOffsetType } from '@deepseek-ai/dsh-session';
+import { type SessionStorageMetadata } from '@deepseek-ai/dsh-session-persistence';
 /** Physical encoding selected for JSONL session artifacts. */
 export type JsonlCompression = 'zstd' | 'none';
 /**
@@ -17,11 +18,11 @@ export type JsonlCompression = 'zstd' | 'none';
  */
 export declare function logSuffix(compression: JsonlCompression): '.jsonl.zstd' | '.jsonl';
 /**
- * The first JSONL record of a session artifact: the immutable
- * {@link SessionHeader} tagged as a `session` record so a reader can tell it
- * apart from an event line.
+ * The private version-0 physical header stored as the first JSONL record.
+ * Its optional numeric `seedLength` translates to logical lineage metadata
+ * plus a separately carried exact inherited cut.
  */
-export interface HeaderLine {
+interface HeaderLine {
     type: 'session';
     version: number;
     id: SessionId;
@@ -36,15 +37,11 @@ export interface HeaderLine {
 /**
  * Build the header line object from a {@link SessionHeader}.
  * @param header - the immutable session metadata to serialize.
+ * @param inheritedEventCount - exact inherited prefix length; required for a
+ * seeded header and omitted only for an unseeded header.
  * @returns the `type: 'session'`-tagged line object, absent optional fields omitted (never null).
  */
-export declare function toHeaderLine(header: SessionHeader): HeaderLine;
-/**
- * Parse a header line back into a {@link SessionHeader}.
- * @param line - the shape-checked first line of a log (see the `isHeaderLine` guard).
- * @returns the header, absent optional fields omitted.
- */
-export declare function fromHeaderLine(line: HeaderLine): SessionHeader;
+export declare function toHeaderLine(header: SessionHeader, inheritedEventCount?: SessionLogOffsetType): HeaderLine;
 /**
  * Encode an arbitrary string as a single safe path segment, injectively over ALL JS (UTF-16)
  * strings — including lone surrogates. A {@link SessionId} is an unvalidated branded string,
@@ -107,6 +104,7 @@ export declare function logPath(root: string, cwd: string | undefined, id: Sessi
 export declare function eventLines(events: readonly SessionEvent[], packChunks: boolean): string;
 interface SessionLogScan {
     meta: SessionHeader;
+    inheritedEventCount: SessionLogOffsetType;
     events: SessionEvent[];
     committedBytes: number;
 }
@@ -118,6 +116,7 @@ interface SessionLogScan {
  */
 export declare class SessionLogScanner {
     private readonly meta;
+    private readonly inheritedEventCount;
     private readonly events;
     private fragments;
     private fragmentBytes;
@@ -143,7 +142,7 @@ export declare class SessionLogScanner {
     checkpoint(): {
         inputBytes: number;
         committedBytes: number;
-        eventCount: number;
+        eventCount: SessionLogOffsetType;
     };
     /**
      * Finish scanning, ignoring a final record without a newline as a torn tail.
@@ -163,12 +162,16 @@ export declare class SessionLogScanner {
  */
 export declare function scanLog(buffer: Buffer): SessionLogScan;
 /**
- * Parse just the header line of a log into a {@link SessionHeader}, or
- * `undefined` if it is missing/not a header. Used by `list()` to read session
- * metadata WITHOUT parsing the whole log: a session picker scales with the
- * number of sessions, not the total size of every conversation.
+ * Parse just the header line of a log into logical metadata plus its exact
+ * inherited cut, or `undefined` if it is missing/not a header.
  * @param firstLine - the first line of a log file (without its trailing newline).
- * @returns the parsed header, or `undefined` when the line is not a well-formed session header.
+ * @returns parsed storage metadata, or `undefined` for a malformed header.
+ */
+export declare function parseHeader(firstLine: string): SessionStorageMetadata | undefined;
+/**
+ * Parse only the logical header fields needed by lightweight listing.
+ * @param firstLine - first JSONL line without its trailing newline.
+ * @returns the logical Session header, or `undefined` for a malformed line.
  */
 export declare function parseHeaderMeta(firstLine: string): SessionHeader | undefined;
 export {};

package/lib/types/index.d.ts

@@ -7,8 +7,8 @@
  */
 import { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
-import { SessionPersistence, type BorrowedSessionSource, type PersistenceBackend, type SessionLocation, type SessionPersistenceSnapshot, type SessionInspection, type SessionPersistenceRevision as PersistenceRevision, type SessionRawArtifact, type StoredPrefix } from '@deepseek-ai/dsh-session-persistence';
-import type { Session, SessionEvent, SessionId, SessionHeader, SessionPreparation } from '@deepseek-ai/dsh-session';
+import { SessionPersistence, type BorrowedSessionSource, type PersistenceBackend, type SessionLocation, type SessionPersistenceSnapshot, type SessionEventSuffix, type SessionInspection, type SessionPersistenceRevision as PersistenceRevision, type SessionRawArtifact, type SessionStorageMetadata, type StoredPrefix } from '@deepseek-ai/dsh-session-persistence';
+import type { Session, SessionEvent, SessionId, SessionHeader, SessionLogOffset, SessionPreparation } from '@deepseek-ai/dsh-session';
 import { type JsonlCompression } from './format.ts';
 export type { JsonlCompression } from './format.ts';
 /** Loader schema for the JSONL artifact's physical encoding. */
@@ -68,17 +68,14 @@ export declare class JsonlSessionPersistence extends SessionPersistence implemen
     constructor(ctx: Context, config: Config);
     /** Resolve the absolute target path without touching the filesystem. */
     locate(meta: SessionHeader): SessionLocation;
-    create(meta: SessionHeader): Promise<void>;
+    create(meta: SessionHeader, inheritedEventCount?: SessionLogOffset): Promise<void>;
     ensureMaterialized(session: Session): Promise<void>;
     append(id: SessionId, events: readonly SessionEvent[]): Promise<void>;
     prepare(id: SessionId, signal?: AbortSignal): Promise<SessionPreparation>;
     load(id: SessionId): Promise<SessionInspection>;
     inspect(id: SessionId, signal?: AbortSignal): Promise<SessionInspection>;
     borrowSession(id: SessionId, signal?: AbortSignal): Promise<BorrowedSessionSource>;
-    readFrom(id: SessionId, fromSeq: number, signal?: AbortSignal): Promise<{
-        meta: SessionHeader;
-        events: SessionEvent[];
-    }>;
+    readFrom(id: SessionId, fromSeq: SessionLogOffset, signal?: AbortSignal): Promise<SessionEventSuffix>;
     /** Read a stored prefix by id across all project directories when cwd is unknown. */
     loadStored(id: SessionId, signal?: AbortSignal): Promise<StoredPrefix<JsonlTornMarker> | undefined>;
     /**
@@ -117,15 +114,15 @@ export declare class JsonlSessionPersistence extends SessionPersistence implemen
     /** Decode complete frames and retain complete JSONL records from a torn final frame. */
     private readZstdPrefix;
     /** Durably append a batch, lazily materializing the file when not yet present. */
-    appendBatch(meta: SessionHeader, events: readonly SessionEvent[], isMaterialized: boolean): Promise<void>;
+    appendBatch(storage: SessionStorageMetadata, events: readonly SessionEvent[], isMaterialized: boolean): Promise<void>;
     /** Materialize a header-only JSONL artifact for an explicitly durable empty session. */
-    materializeHeader(meta: SessionHeader): Promise<void>;
+    materializeHeader(storage: SessionStorageMetadata): Promise<void>;
     /**
      * Make a crash repair durable: truncate a torn tail, restore complete events
      * decoded from it, then append synthetic closers. Two fsync'd steps — the seam
      * does not require this to be atomic.
      */
-    commitRepair(meta: SessionHeader, tornMarker: JsonlTornMarker | undefined, closers: readonly SessionEvent[]): Promise<void>;
+    commitRepair(storage: SessionStorageMetadata, tornMarker: JsonlTornMarker | undefined, closers: readonly SessionEvent[]): Promise<void>;
     /** List valid unique stored sessions' metadata (header line only — no full-log parse). */
     list(signal?: AbortSignal): Promise<SessionHeader[]>;
     /** List metadata plus a stat-derived identity for each append-only log. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-session-persistence-jsonl",
   "description": "JSONL durable session persistence backend for the DeepSeek Harness",
-  "version": "0.1.2-alpha.2",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
@@ -18,23 +18,17 @@
       "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-invariants": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-session": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-session-persistence": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-session": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-session-persistence": "^0.1.2-alpha.4",
     "@deepseek-ai/cordis": "^4.0.2"
   },
   "dependencies": {
@@ -42,9 +36,8 @@
     "@deepseek-ai/schemastery": "^3.18.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-session-persistence": "^0.1.2-alpha.2",
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-session": "^0.1.2-alpha.2"
+    "@deepseek-ai/dsh-session": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-session-persistence": "^0.1.2-alpha.4",
+    "@deepseek-ai/cordis": "^4.0.2"
   }
 }

package/lib/invariant.js

@@ -1,23 +0,0 @@
-//#region lib/types/invariant.js
-/**
-* Package-owned invariant companion for `@deepseek-ai/dsh-session-persistence-jsonl`.
-* @module @deepseek-ai/dsh-session-persistence-jsonl/invariant
-*/
-const PACKAGE_NAME = "@deepseek-ai/dsh-session-persistence-jsonl";
-/** Cordis companion plugin name. */
-const name = "session-persistence-jsonl-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-jsonl`.
- * @module @deepseek-ai/dsh-session-persistence-jsonl/invariant
- */
-import type { Context } from '@deepseek-ai/cordis';
-/** Cordis companion plugin name. */
-export declare const name = "session-persistence-jsonl-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