@deepseek-ai/dsh-session-persistence-jsonl 0.0.1-rc.1 → 0.0.1-rc.2

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: 628833513a8092280970230c8657a50d00db4527
-README.zh.md: 4eb2d4f2bebf9ed17190ef3cb21a2bc3c8d9123b
+README.md: 4cff3215cdb083d2fdb7c4a8f1b60e8c4028ba84
+README.zh.md: 7e3ba5be4f2707ff6408d296ece1f43550d76286

package/README.md

@@ -42,7 +42,7 @@ A root belongs to one encoding. Startup discovery and targeted lookup reject the
 - **Bound storage identity.** Lookup requires one matching session directory across the readable project directories, then verifies that the header id equals the requested id and that the header's id/cwd derive the selected transcript path. Listing applies the same path check and rejects duplicate ids. Identity failures occur before repair or append.
 - **Lazy materialization.** `create(meta)` writes nothing; on the first `append`, the backend writes and `fsync`s the encoded header and first batch in a temporary file. POSIX publishes it without overwrite via a hard link and `fsync`s the parent directory. Windows publishes it without overwrite via `MoveFileExW(..., MOVEFILE_WRITE_THROUGH)` and creates missing directories through the same write-through pattern. A created-but-never-appended session leaves nothing on disk and is absent from `list`.
 - **Append-only.** Flushed events are never rewritten. Subsequent raw batches append lines; compressed batches append one frame. Both paths `fsync`, and a caught write or sync failure rolls the file back to its prior byte length.
-- **Crash recovery — preserve valid tail work.** `load` validates every complete compressed frame and scans their decompressed JSONL. If the last frame is structurally incomplete, the reader keeps its complete decoded records, truncates from that frame's start, and re-encodes those records with the synthetic tool, step, and turn closers required by the shared [persistence contract](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md). Raw mode truncates from its first incomplete line. A checksum/decompression failure in a complete frame, or a defect at or before the last committed `turn/end`, is corruption and rejects.
+- **Crash recovery — preserve valid tail work.** `load` validates every complete compressed frame and scans their decompressed JSONL. If the last frame is structurally incomplete, the reader keeps its complete decoded records, truncates from that frame's start, and re-encodes those records with the synthetic tool, step, and turn closers required by the shared [persistence contract](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md). Raw mode truncates from its first incomplete line. An existing compressed artifact with no complete header frame, a checksum/decompression failure in a complete frame, or a defect at or before the last committed `turn/end` is corruption and rejects.
 - **Non-mutating inspection.** `inspect()` returns an immutable balanced logical view and may synthesize recovery closers in memory, without truncating an incomplete tail or changing the lightweight revision.
 - **Contiguous-seq.** `append` rejects a batch whose first `seq` does not continue the stored log, and rejects non-JSON-serializable `event.data` naming the offending event type.
 - **Lightweight revisions.** `listSnapshots(signal?)` identifies a log by its device, inode, size, and nanosecond timestamps, avoiding a full-log parse while changing after append, repair, replacement, or store changes. A full-prefix read requires the same identity before and after reading the bytes, and `readStoredRevision()` uses that identity to validate retained preparations without loading the log. Snapshot listing forwards the exact signal through artifact discovery and checks cancellation around every `stat`; because filesystem `stat` is not interruptible, cancellation waits for the active call to settle, then rejects without starting another.
@@ -72,6 +72,6 @@ JSONL storage does not mutate live request prefixes. A resumed loop can reuse pr
 - **Only the configured encoding and current `SESSION_FORMAT_VERSION` (v0) load** — changing compression requires a separate/fresh root or selecting the legacy raw mode; the pre-release format has no migration.
 - **The flat-file storage layout does not load** — use a separate root or move pre-release artifacts into the project/session directory layout before loading.
 - **Compressed files are not directly line-readable** — use the backend to load them, or select `compression: 'none'` before writing a fresh root when external line readers are required.
-- **Nothing deletes session files** — logs accumulate under `root` until removed externally (the seam has no deletion surface).
+- **Nothing deletes session files** — logs accumulate under `root` until removed externally (the seam has no deletion API).
 - **One live writer per session** — append and repair are coordinated only inside the owning backend instance. Another backend instance or process must not write the same session until that owner reaches quiescent disposal; initial same-id publication remains collision-safe through the POSIX no-overwrite hard link or Windows write-through rename without replacement.
 - **POSIX materialization requires hard-link support** — first append uses `link()` so same-id races fail instead of overwriting a committed log; Windows uses write-through rename without replacement.

package/README.zh.md

@@ -42,7 +42,7 @@ JSONL 持久会话存储后端：`SessionPersistence` 的一个具体实现（`d
 - **绑定存储身份。** 查找要求可读项目目录中只有一个匹配会话目录，然后验证 header id 等于请求 id，且 header id/cwd 派生所选 transcript 路径。列表应用同一路径检查，并拒绝重复 id。身份失败发生在修复或 append 前。
 - **延迟实体化。**`create(meta)` 不写入；第一次 `append` 将编码 header 和第一批写入临时文件并执行 `fsync`。POSIX 通过硬链接无覆盖发布，并对父目录 `fsync`。Windows 通过 `MoveFileExW(..., MOVEFILE_WRITE_THROUGH)` 无覆盖发布，并通过同一 write-through pattern 创建缺失目录。已创建但从未 append 的会话不留下磁盘内容，不在 `list` 中。
 - **仅追加。** 已 flush 事件绝不重写。后续原始批次 append 行；压缩批次 append 一个 frame。两条路径都执行 `fsync`，并在捕获到写入或同步失败时回滚到之前字节长度。
-- **崩溃恢复：保留有效尾部工作。**`load` 验证每个完整压缩 frame，并扫描解压 JSONL。最后 frame 结构不完整时，读取器保留其完整解码记录，从 frame 开头截断，并使用共享[持久化约定](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md) 需要的合成工具、步骤和轮次 closer 重新编码这些记录。原始 mode 从第一个不完整行截断。完整 frame 中的 checksum/解压失败，或位于最后已提交的 `turn/end` 处或之前的缺陷属于损坏，会被拒绝。
+- **崩溃恢复：保留有效尾部工作。**`load` 验证每个完整压缩 frame，并扫描解压 JSONL。最后 frame 结构不完整时，读取器保留其完整解码记录，从 frame 开头截断，并使用共享[持久化约定](../../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md) 需要的合成工具、步骤和轮次 closer 重新编码这些记录。原始 mode 从第一个不完整行截断。已经存在却没有完整 header frame 的压缩工件、完整 frame 中的 checksum/解压失败，或位于最后已提交的 `turn/end` 处或之前的缺陷都属于损坏，会被拒绝。
 - **非变更检查。**`inspect()` 返回不可变、平衡的逻辑视图，并可在内存中合成恢复 closer，但不会截断不完整尾部或更改轻量修订。
 - **连续 seq。**`append` 拒绝第一个 `seq` 不继续已存储日志的批次，并拒绝非 JSON 可序列化 `event.data`，同时命名违规事件类型。
 - **轻量修订。**`listSnapshots(signal?)` 使用 device、inode、size 和纳秒时间戳标识日志，避免解析完整日志；该标识会在 append、修复、替换或存储变更后改变。完整前缀读取要求读取字节前后的身份一致，`readStoredRevision()` 使用同一身份校验保留的 preparation，而不加载日志。快照列表通过产物发现转发精确信号，并在每个 `stat` 前后检查取消；由于文件系统 `stat` 不可中断，取消会等待活动调用完成，然后在不启动另一次调用的情况下拒绝。

package/lib/index.js

@@ -5,8 +5,8 @@ import { dirname, join, parse, resolve, toNamespacedPath } from "node:path";
 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, SessionPersistence, SessionPersistenceRevision } from "@deepseek-ai/dsh-session-persistence";
-import { decodeStorageRecord, packChunkRuns } from "@deepseek-ai/dsh-session";
+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, decodeStorageRecord, 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";
@@ -171,6 +171,19 @@ function eventLines(events, packChunks) {
 	return (packChunks ? packChunkRuns(events) : events).map((record) => JSON.stringify(record)).join("\n");
 }
 /** Parse one complete header record supplied independently from event rows. */
+/**
+* Refuse a header carrying a format version this build does not read BEFORE
+* validating the current header shape or decoding any event row: a future
+* format need not satisfy today's structural checks at all, and its user must
+* see "upgrade the harness", never "corrupt session log".
+* @param parsed - the JSON-parsed first line of a session artifact.
+*/
+function refuseForeignFormatVersion(parsed) {
+	if (typeof parsed !== "object" || parsed === null) return;
+	const { version, id } = parsed;
+	if (typeof version !== "number" || version === SESSION_FORMAT_VERSION) return;
+	throw new SessionFormatUnsupportedError(sessionFormatVersionRefusal(typeof id === "string" ? id : String(id), version));
+}
 function parseHeaderRecord(record) {
 	if (record.length === 0 || record.at(-1) !== 10 || record.indexOf(10) !== record.length - 1) throw new Error("empty or header-less session log");
 	let parsed;
@@ -179,6 +192,7 @@ function parseHeaderRecord(record) {
 	} catch {
 		throw new Error("corrupt session log: header line is not valid JSON");
 	}
+	refuseForeignFormatVersion(parsed);
 	if (!isHeaderLine(parsed)) throw new Error("corrupt session log: first line is not a session header");
 	return fromHeaderLine(parsed);
 }
@@ -607,7 +621,7 @@ const ERROR_FILE_EXISTS = 80;
 const ERROR_INVALID_NAME = 123;
 const ERROR_ALREADY_EXISTS = 183;
 let bindings;
-/** Load the small Win32 surface lazily so non-Windows processes never load Koffi. */
+/** Load the small Win32 API lazily so non-Windows processes never load Koffi. */
 async function win32() {
 	if (bindings !== void 0) return bindings;
 	const kernel32 = (await import("koffi")).default.load("kernel32.dll");
@@ -751,6 +765,7 @@ function isENOENT(error) {
 */
 var SessionPersistenceJsonl = class extends SessionPersistence {
 	config;
+	supportsRawArtifacts = true;
 	static inject = ["sessions"];
 	static Config = z.object({
 		root: z.string().required(),
@@ -839,37 +854,94 @@ var SessionPersistenceJsonl = class extends SessionPersistence {
 		}
 	}
 	/**
-	* Read a stored prefix and convert torn-tail state to the opaque marker the
-	* coordinator can round-trip without knowing the physical encoding.
+	* Read a session's stored artifact text verbatim: the durable file bytes
+	* decoded from this backend's physical encoding (complete zstd frames
+	* concatenated, or UTF-8 plaintext). The content is the exact JSONL text the
+	* backend wrote — never a reconstruction from parsed events — so packed-
+	* chunk rows, key order, and line breaks survive byte-for-byte. A torn
+	* final frame is omitted, matching the committed-prefix semantics of every
+	* other read.
+	* @param id - the persisted session to read.
+	* @param signal - optional cancellation for the stat/read/decode work.
+	* @returns the raw artifact text plus the header parsed from its own first
+	* line, or `undefined` when the session has no stored artifact.
 	*/
-	async readPrefix(path, expectedId, signal) {
-		let buffer;
-		let revision;
+	async readRaw(id, signal) {
+		signal?.throwIfAborted();
+		await this.ensureRootEncoding();
+		signal?.throwIfAborted();
+		const path = await this.findLog(id, signal);
+		if (path === void 0) return void 0;
+		const { buffer } = await this.readStableFile(path, signal);
+		let content;
+		if (this.compression === "zstd") {
+			const { frames } = scanZstdFrames(buffer);
+			if (frames.length === 0) throw new Error("empty or header-less Zstandard session log");
+			const decoder = createZstdFrameDecoder();
+			const plaintexts = [];
+			for (const plaintext of decoder.decode(buffer, frames)) {
+				signal?.throwIfAborted();
+				plaintexts.push(Buffer.from(plaintext));
+			}
+			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}"`);
+		return {
+			meta,
+			filename: "session.jsonl",
+			content
+		};
+	}
+	/**
+	* Read a file's bytes under a revision-stable loop: a writer appending
+	* between stat and readFile would yield a torn physical file, so retry
+	* while the stat revision changes.
+	* @param path - the artifact file to read.
+	* @param signal - optional cancellation for the stat/read work.
+	* @returns the stable bytes and the revision that matched both stats.
+	*/
+	async readStableFile(path, signal) {
 		for (;;) {
 			signal?.throwIfAborted();
 			const before = fileRevision(await stat(path, { bigint: true }));
-			buffer = await readFile(path, { signal });
+			const buffer = await readFile(path, { signal });
 			signal?.throwIfAborted();
 			const after = fileRevision(await stat(path, { bigint: true }));
-			if (before === after) {
-				revision = after;
-				break;
-			}
+			if (before === after) return {
+				buffer,
+				revision: after
+			};
 		}
+	}
+	/**
+	* Read a stored prefix and convert torn-tail state to the opaque marker the
+	* coordinator can round-trip without knowing the physical encoding.
+	*/
+	async readPrefix(path, expectedId, signal) {
+		const { buffer, revision } = await this.readStableFile(path, signal);
 		let prefix;
-		if (this.compression === "zstd") prefix = await this.readZstdPrefix(buffer, signal);
-		else {
-			signal?.throwIfAborted();
-			const { meta, events, committedBytes } = scanLog(buffer);
-			signal?.throwIfAborted();
-			prefix = {
-				meta,
-				events,
-				...committedBytes < buffer.byteLength ? { tornMarker: {
-					truncateTo: committedBytes,
-					recoveredEvents: []
-				} } : {}
-			};
+		try {
+			if (this.compression === "zstd") prefix = await this.readZstdPrefix(buffer, signal);
+			else {
+				signal?.throwIfAborted();
+				const { meta, events, committedBytes } = scanLog(buffer);
+				signal?.throwIfAborted();
+				prefix = {
+					meta,
+					events,
+					...committedBytes < buffer.byteLength ? { tornMarker: {
+						truncateTo: committedBytes,
+						recoveredEvents: []
+					} } : {}
+				};
+			}
+		} catch (error) {
+			if (error instanceof SessionFormatUnsupportedError && error.location === void 0) throw new SessionFormatUnsupportedError(`${error.message} (raw log: ${path})`, {
+				kind: "jsonl",
+				path
+			});
+			throw error;
 		}
 		signal?.throwIfAborted();
 		await this.assertStoredIdentity(path, prefix.meta, expectedId, signal);

package/lib/types/index.d.ts

@@ -7,7 +7,7 @@
  */
 import { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
-import { SessionPersistence, type PersistenceBackend, type SessionLocation, type SessionPersistenceSnapshot, type SessionInspection, type SessionPersistenceRevision as PersistenceRevision, type StoredPrefix } from '@deepseek-ai/dsh-session-persistence';
+import { SessionPersistence, type PersistenceBackend, type SessionLocation, type SessionPersistenceSnapshot, type SessionInspection, type SessionPersistenceRevision as PersistenceRevision, type SessionRawArtifact, type StoredPrefix } from '@deepseek-ai/dsh-session-persistence';
 import type { SessionEvent, SessionId, SessionHeader, SessionPreparation } from '@deepseek-ai/dsh-session';
 import { type JsonlCompression } from './format.ts';
 export type { JsonlCompression } from './format.ts';
@@ -51,6 +51,7 @@ interface JsonlTornMarker {
  */
 export declare class SessionPersistenceJsonl extends SessionPersistence implements PersistenceBackend<JsonlTornMarker> {
     config: Config;
+    readonly supportsRawArtifacts = true;
     static inject: string[];
     static Config: z<Config>;
     /**
@@ -83,6 +84,29 @@ export declare class SessionPersistenceJsonl extends SessionPersistence implemen
      * Resolving an id with unknown cwd still scans the project directories.
      */
     readStoredRevision(id: SessionId, signal?: AbortSignal): Promise<PersistenceRevision | undefined>;
+    /**
+     * Read a session's stored artifact text verbatim: the durable file bytes
+     * decoded from this backend's physical encoding (complete zstd frames
+     * concatenated, or UTF-8 plaintext). The content is the exact JSONL text the
+     * backend wrote — never a reconstruction from parsed events — so packed-
+     * chunk rows, key order, and line breaks survive byte-for-byte. A torn
+     * final frame is omitted, matching the committed-prefix semantics of every
+     * other read.
+     * @param id - the persisted session to read.
+     * @param signal - optional cancellation for the stat/read/decode work.
+     * @returns the raw artifact text plus the header parsed from its own first
+     * line, or `undefined` when the session has no stored artifact.
+     */
+    readRaw(id: SessionId, signal?: AbortSignal): Promise<SessionRawArtifact | undefined>;
+    /**
+     * Read a file's bytes under a revision-stable loop: a writer appending
+     * between stat and readFile would yield a torn physical file, so retry
+     * while the stat revision changes.
+     * @param path - the artifact file to read.
+     * @param signal - optional cancellation for the stat/read work.
+     * @returns the stable bytes and the revision that matched both stats.
+     */
+    private readStableFile;
     /**
      * Read a stored prefix and convert torn-tail state to the opaque marker the
      * coordinator can round-trip without knowing the physical encoding.

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.0.1-rc.1",
+  "version": "0.0.1-rc.2",
   "publishConfig": {
     "access": "restricted"
   },
@@ -32,19 +32,19 @@
   ],
   "license": "BSD-3-Clause",
   "peerDependencies": {
-    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-session-persistence": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
-    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-session-persistence": "^0.0.1-rc.2",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.2"
   },
   "dependencies": {
     "koffi": "^3.1.0",
     "@deepseek-ai/schemastery": "^3.18.1-rc.1"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-session-persistence": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-session-persistence": "^0.0.1-rc.2",
     "@deepseek-ai/cordis": "^4.0.1-rc.1"
   }
 }