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

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: 38b41cb9f7fa0f144923feced06152a185254c0a

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

@@ -14,9 +14,9 @@ JSONL 持久会话存储后端：`SessionPersistence` 的一个具体实现（`d
       session.jsonl              # only with compression: 'none'
 ```
 
-- 第一个逻辑行是不可变的 `SessionHeader`，标记为 `{ type: 'session', version, id, cwd?, createdAt, parentSession?, seedLength?, origin?, delegationDepth, agentPreset? }`。`delegationDepth` 在磁盘上必需，顶层会话为 `0`；缺失或无效值会拒绝日志。`agentPreset` 必须持久化，因为它决定了被恢复会话的工具与提示词——恢复成另一套组装，就会重放模型已无法据以行动的历史。后续每个逻辑行是一条存储记录；`assistant/chunk` 事件绝不丢弃，且 `seq` 在解码日志中保持连续（`events[i].seq === i`）。
-- 存储记录是原样 `SessionEvent` JSON，或在 `packChunks` 已启用且连续段符合条件时写入的**打包分片行**（`text-chunks` / `reasoning-chunks` / `tool-call-chunks`；像 header 的 `session` 一样不带斜杠，因此行 tag 不会与事件类型混淆）：一行保存至少 3 个连续同 block `assistant/chunk` delta 事件，`seq0`/`time0` 和每成员 `dt` 间隔精确重建每个成员的 `seq`/`time`。无损 codec 位于 `@deepseek-ai/dsh-session`（`packChunkRuns`/`decodeStorageRecord`），并使用精确形态 allowlist：任何未识别内容原样存储。读取与布局无关：`load` 始终解码行，因此打包、非打包和混合文件加载结果一致。
-- 项目目录保留规范化 cwd 可读，并限制在文件系统组件上限内。分隔符替换和截断刻意有损，因此规范化相同的 cwd 字符串共享项目目录；会话 id 仍选择不同会话目录。在不区分大小写的文件系统上，只有文件系统规范化将两种写法解析到同一 transcript（文本记录）时，身份验证才接受备选路径写法。配置根仍由部署控制：可以是项目本地、共享、临时或集中式。[项目会话目录决策](../../../.agents/notes/implemented/architecture/2026-07-24-project-session-directories.md) 记录这项取舍。
+- 第一个逻辑行是不可变的 `SessionHeader`，标记为 `{ type: 'session', version, id, cwd?, createdAt, parentSession?, seedLength?, origin?, delegationDepth, agentPreset? }`。`delegationDepth` 在磁盘上必需，顶层会话为 `0`；缺失或无效值会拒绝日志。`agentPreset` 必须持久化，因为它决定了被恢复会话的工具与提示词——恢复成另一套组装，就会回放模型已无法据以行动的历史。后续每个逻辑行是一条存储记录；`assistant/chunk` 事件绝不丢弃，且 `seq` 在解码日志中保持连续（`events[i].seq === i`）。
+- 存储记录是原样 `SessionEvent` JSON，或在 `packChunks` 已启用且连续段符合条件时写入的**打包分片行**（`text-chunks` / `reasoning-chunks` / `tool-call-chunks`；像 header 的 `session` 一样不带斜杠，因此行 tag 不会与事件类型混淆）：一行保存至少 3 个连续同 block `assistant/chunk` delta 事件，`seq0`/`time0` 和各成员的 `dt` 间隔精确重建每个成员的 `seq`/`time`。无损 codec 位于 `@deepseek-ai/dsh-session`（`packChunkRuns`/`decodeStorageRecord`），并使用精确形态 allowlist：任何未识别内容原样存储。读取与布局无关：`load` 始终解码行，因此打包、非打包和混合文件加载结果一致。
+- 项目目录保留规范化 cwd 的可读形式，便于导航，并限制在文件系统组件上限内。分隔符替换和截断刻意有损，因此规范化相同的 cwd 字符串共享项目目录；会话 id 仍选择不同会话目录。在不区分大小写的文件系统上，只有文件系统规范化将两种写法解析到同一 transcript（文本记录）时，身份验证才接受备选路径写法。配置根仍由部署控制：可以是项目本地、共享、临时或集中式。[项目会话目录决策](../../../.agents/notes/implemented/architecture/2026-07-24-project-session-directories.md) 记录这项取舍。
 - 会话 id 是未验证的带品牌类型的字符串，因此在使用前单射转义为一个安全路径段（无遍历、无冲突）。结果目录保留给其他会话自有产物；发现只读取固定 transcript 文件名。
 
 ## 配置
@@ -24,7 +24,7 @@ JSONL 持久会话存储后端：`SessionPersistence` 的一个具体实现（`d
 | 键 | 类型 | 说明 |
 |---|---|---|
 | `root` | `string`（必需） | 所有会话文件的根目录。**无默认值**：`process.cwd()` 默认值会随进程 cwd 变更（bash 调用、子进程）而分散文件。现有根必须是可读目录；缺失根在第一次实体化时创建。 |
-| `packChunks` | `boolean`（默认 `true`） | 将符合条件的 delta 分片连续段写为打包行（在真实编码会话上测得逻辑日志约小 60%）。设为 `false` 可用于每事件一行诊断；无论该写入侧开关如何，都能读取打包行。 |
+| `packChunks` | `boolean`（默认 `true`） | 将符合条件的 delta 分片连续段写为打包行（在真实编程会话上测得逻辑日志约小 60%）。设为 `false` 可用于每事件一行诊断；无论该写入侧开关如何，都能读取打包行。 |
 | `compression` | `'zstd' \| 'none'` | 默认 `'zstd'`；`'none'` 保留换行分隔 UTF-8 文本。 |
 | `preparedSessionCacheSize` | 正整数（默认 `5`） | 冷历史检查后保留、供恢复复用的未发布会话数量上限。 |
 | `writeBatchMaxDelayMs` | 正整数（默认 `200`） | 空闲的活动事件队列收到待写入事件后开启的固定合并窗口。后续事件不会重置窗口；flush 与 teardown 会绕过它。该值不限制事件循环、串行化操作或后端延迟。最大值为 Node 计时器上限 `2_147_483_647` ms。 |
@@ -42,10 +42,10 @@ 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` 处或之前的缺陷属于损坏，会被拒绝。
-- **非变更检查。**`inspect()` 返回不可变、平衡的逻辑视图，并可在内存中合成恢复 closer，但不会截断不完整尾部或更改轻量修订。
-- **连续 seq。**`append` 拒绝第一个 `seq` 不继续已存储日志的批次，并拒绝非 JSON 可序列化 `event.data`，同时命名违规事件类型。
-- **轻量修订。**`listSnapshots(signal?)` 使用 device、inode、size 和纳秒时间戳标识日志，避免解析完整日志；该标识会在 append、修复、替换或存储变更后改变。完整前缀读取要求读取字节前后的身份一致，`readStoredRevision()` 使用同一身份校验保留的 preparation，而不加载日志。快照列表通过产物发现转发精确信号，并在每个 `stat` 前后检查取消；由于文件系统 `stat` 不可中断，取消会等待活动调用完成，然后在不启动另一次调用的情况下拒绝。
+- **崩溃恢复：保留有效尾部工作。**`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` 不可中断，取消会等待活动调用完成，然后在不启动另一次调用的情况下拒绝。
 
 ## 写入路径
 
@@ -57,7 +57,7 @@ JSONL 持久会话存储后端：`SessionPersistence` 的一个具体实现（`d
 
 #### 模型看到的内容
 
-JSONL 存储不影响当前提示词或 schema。加载会恢复已存储的表层历史，并保留之前的请求 header 用于重建；新 loop 组合当前 envelope。恢复会用 `TOOL_NOT_STARTED` 平衡没有已持久化调用的 assistant 请求；已有已持久化调用但无结果时则变为 `TOOL_OUTCOME_UNKNOWN`，它要求模型只重试只读或幂等工作，并验证可能的副作用或询问用户。原始 `assistant/chunk` 记录不会重复生成消息。
+JSONL 存储不会向当前请求提供提示词或 schema。加载会恢复已存储的表层历史，并保留之前的请求 header 用于重建；新 loop 组合当前 envelope。恢复会用 `TOOL_NOT_STARTED` 平衡没有已持久化调用的 assistant 请求；已持久化调用无结果时则变为 `TOOL_OUTCOME_UNKNOWN`，它要求模型只重试只读或幂等工作，并验证可能的副作用或询问用户。原始 `assistant/chunk` 记录不会重复生成消息。
 
 #### Token 影响
 
@@ -69,9 +69,9 @@ JSONL 存储不修改实时请求前缀。只有重建历史、当前 envelope
 
 ## 已知限制与暂缓事项
 
-- **只加载已配置编码和当前 `SESSION_FORMAT_VERSION` (v0)**：更改压缩需要独立/全新根，或选择遗留原始 mode；预发布格式没有迁移。
+- **只加载已配置编码和当前 `SESSION_FORMAT_VERSION`（v0）**：更改压缩需要独立/全新根，或选择遗留原始 mode；预发布格式没有迁移。
 - **平铺文件存储布局不加载**：加载前使用独立根，或将预发布产物移入项目/会话目录布局。
 - **压缩文件不能直接按行读取**：使用后端加载；或在写入新根前选择 `compression: 'none'`，以便外部行 reader 使用。
 - **不删除会话文件**：日志在 `root` 下累积，直到外部移除（seam 无删除接口）。
-- **每会话一个实时 writer**：append 和修复只在所属后端实例内协调。在所有者完成完全停稳的 dispose 前，其他后端实例或进程不得写入同一会话；初始同 id 发布仍通过 POSIX 无覆盖硬链接或 Windows 无替换 write-through rename 保持冲突安全。
+- **每会话一个活动 writer**：append 和修复只在所属后端实例内协调。在所有者完成完全停稳的 dispose 前，其他后端实例或进程不得写入同一会话；初始同 id 发布仍通过 POSIX 无覆盖硬链接或 Windows 无替换 write-through rename 保持冲突安全。
 - **POSIX 实体化需要硬链接支持**：第一次 append 使用 `link()`，使同 id 竞态失败，而不覆盖已提交日志；Windows 使用无替换 write-through rename。

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");
@@ -749,8 +763,9 @@ function isENOENT(error) {
 * listeners. Its torn-tail marker carries the byte offset and any events
 * recovered from an incomplete final Zstandard frame.
 */
-var SessionPersistenceJsonl = class extends SessionPersistence {
+var JsonlSessionPersistence = 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);
@@ -1386,4 +1458,4 @@ var SessionPersistenceJsonl = class extends SessionPersistence {
 	}
 };
 //#endregion
-export { JsonlCompressionSchema, SessionPersistenceJsonl, SessionPersistenceJsonl as default };
+export { JsonlCompressionSchema, JsonlSessionPersistence, JsonlSessionPersistence as default };

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';
@@ -49,8 +49,9 @@ interface JsonlTornMarker {
  * listeners. Its torn-tail marker carries the byte offset and any events
  * recovered from an incomplete final Zstandard frame.
  */
-export declare class SessionPersistenceJsonl extends SessionPersistence implements PersistenceBackend<JsonlTornMarker> {
+export declare class JsonlSessionPersistence 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.
@@ -159,5 +183,5 @@ export declare class SessionPersistenceJsonl extends SessionPersistence implemen
     private exists;
     private assertLogParentAllowsAbsence;
 }
-export default SessionPersistenceJsonl;
+export default JsonlSessionPersistence;
 //# sourceMappingURL=index.d.ts.map

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.3",
   "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.3",
+    "@deepseek-ai/dsh-session-persistence": "^0.0.1-rc.3",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.3"
   },
   "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.3",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-session-persistence": "^0.0.1-rc.3",
     "@deepseek-ai/cordis": "^4.0.1-rc.1"
   }
 }