@deepseek-ai/dsh-session-persistence-jsonl 0.1.6-alpha.2 → 0.1.7-alpha.1

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: fc431ff27bcd236c4d44b8d3e7b20d4291b936d4
-README.zh.md: 3b265bf43f058d4c0711568df156825febed4d24
+README.md: 5846404961caaef7a91fb4dda562655d15fd2be9
+README.zh.md: b7dd646e57b75fe47f3683d2b230dace628f8eee

package/README.md

@@ -79,7 +79,11 @@ The current-generation scanner applies the current codec owner’s structural ad
 
 ### Reading the logs
 
-`open(id, 'read'|'write')` selects the highest canonical generation. Current input follows the ordinary fast path. For historical input, a read open decodes and migrates the source once, validates the current logical result, and returns it without publishing a successor. A write open reuses that revision-keyed preparation when available, or performs the same preparation, then encodes a same-directory temporary file in bounded chunks, verifies it in a Worker Thread, rechecks the source revision, and publishes the current successor without overwrite before returning. The source remains byte-identical. Source drift after preparation rejects that write open without replacing the logical history already returned to readers; a later write open prepares the new revision. The backend marks decoded event graphs `shared-frozen` when it freezes them before memoization; handle reads and slices preserve that state, including empty slices. Only an unmaterialized pending log reports `detached`. `stat(id)` and `list()` select and translate only the highest generation header without reading event rows or starting migration; snapshots carry `sizeBytes` and a best-effort stat-derived revision for the selected file. With `compression: 'none'`, the log is newline-delimited text an external reader can consume directly; the compressed default must be read through the backend.
+`open(id, 'read'|'write')` selects the highest canonical generation. Current input follows the ordinary fast path. For historical input, a read open decodes and migrates the source once, validates the current logical result, and returns it without publishing a successor. A write open reuses that revision-keyed preparation when available, or performs the same preparation, then encodes a same-directory temporary file in bounded chunks, verifies it in a Worker Thread, rechecks the source revision, and publishes the current successor without overwrite before returning. The source remains byte-identical. Source drift after preparation rejects that write open without replacing the logical history already returned to readers; a later write open prepares the new revision. The backend marks decoded event graphs `shared-frozen` when it freezes them before memoization; every nested object and array is frozen, and handle reads and slices preserve that state, including empty slices. Only an unmaterialized pending log reports `detached`. `stat(id)` and `list()` select and translate only the highest generation header without reading event rows or starting migration; snapshots carry the selected file’s `sizeBytes` and a best-effort revision. Current revisions identify that file; historical revisions also fingerprint the selected files across the persistence root, so child changes invalidate cached logical events. Fingerprinting reads filesystem metadata only; unrelated changes conservatively invalidate historical revisions. One `list()` call shares a corpus fingerprint across its historical entries. With `compression: 'none'`, the log is newline-delimited text an external reader can consume directly; the compressed default must be read through the backend.
+
+Historical body preparation completes the parent catalog through [V3→V4](../session-format-v3-to-v4/README.md). It finds candidate direct children from headers, reads each child's own descriptor through historical codecs, and retains compact evidence plus source revisions. It neither prepares child catalogs nor publishes child successors. Unreadable or unsupported headers, including corrupt Zstandard header frames, are omitted from discovery and `list()`. Direct access to a corrupt compressed header still rejects; header I/O and cancellation errors propagate. Child decoding and descriptor-field failures produce warnings naming the child path and retain header identity through `subagent/catalog` when the parent has no complete entry; healthy children and existing parent catalog entries remain available. Opening a damaged child still reports that child's error. Missing, unsupported, or multiple descriptors likewise produce unknown-mode membership without inventing a label. Published unknown entries remain browsable; child history reads retry the actual log and resolve its mode from a valid descriptor. Preparation rechecks membership and inspected source revisions before returning, reuse, and publication, including failed child reads so a repaired child invalidates stale preparation. Source drift retries a read open once and refuses a write open. Cancellation still aborts the operation. Current V4 opens bypass discovery and validate catalog fields, uniqueness, and current delivery ownership before exposing events.
+
+Historical `stat` and `list` revisions require metadata work proportional to the root’s Session count. Fresh body preparation scans all selected headers and decodes direct-child bodies; memo reuse still scans membership and checks revisions. Read-only access never publishes an upgrade, so cold processes and evicted preparations repeat that work. Current V4 body reads and revisions avoid the historical corpus scan. See the [measured costs and diagnostic command](../../../.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.md#catalog-scan-measurements).
 
 -----
 
@@ -93,7 +97,7 @@ This section explains the physical encoding and write path; the observable contr
 
 ### Design concept
 
-The backend owns its complete storage runtime (`src/storage.ts`): `JsonlSessionHandle` carries the per-handle mutation chain, the routed live-event buffer with its fixed batching window and single-flight drain, monotonic reads, and idempotent close; a tracker holds the in-process single-writer claims, the open-handle set teardown sweeps, and the created-but-unmaterialized pending sessions the backend's own session listeners route into. Historical body reads share one per-session Decode/Migrate preparation, and a bounded revision-keyed memo lets an immediate observe-to-resume handoff reuse that parse; the backend deep-freezes each event graph once before memoization, so later handle reads reuse it without copying or freezing. Only a write open publishes the prepared successor. The package deliberately exposes only its default plugin export plus configuration types — the concrete class is not a named export, so consumers couple to `ctx.sessionPersistence`, and the shared seam suites (`runPersistenceContract`/`runLiveWritePathContract`) pin its observable behavior. Its change token is a best-effort file revision: device, inode, size, and nanosecond timestamps identify one log for `stat`/`list`, for the stable-read loop that retries a read torn by a concurrent append, and for the pre-publication source check.
+The backend owns its complete storage runtime (`src/storage.ts`): `JsonlSessionHandle` carries the per-handle mutation chain, the routed live-event buffer with its fixed batching window and single-flight drain, monotonic reads, and idempotent close; a tracker holds the in-process single-writer claims, the open-handle set teardown sweeps, and the created-but-unmaterialized pending sessions the backend's own session listeners route into. Historical body reads share one per-session Decode/Migrate preparation, and a bounded revision-keyed memo lets an immediate observe-to-resume handoff reuse that parse; the backend deep-freezes each event graph once before memoization, so later handle reads reuse it without copying or freezing. Only a write open publishes the prepared successor. The package deliberately exposes only its default plugin export plus configuration types — the concrete class is not a named export, so consumers couple to `ctx.sessionPersistence`, and the shared seam suites (`runPersistenceContract`/`runLiveWritePathContract`) pin its observable behavior. Physical revisions combine device, inode, size, and nanosecond timestamps for the preparation memo, stable-read retries, and publication checks. Historical public revisions add a SHA-256 fingerprint of sorted selected paths and their physical revisions; lock files and retained unselected generations do not contribute.
 
 ### Physical encoding
 

package/README.zh.md

@@ -79,7 +79,11 @@ kind: "package-reference"
 
 ### 读取日志
 
-`open(id, 'read'|'write')` 选择最高规范 generation。当前格式输入走普通快速路径。对于历史输入，只读 open 会单遍解码并迁移源、校验当前逻辑结果，然后在不发布后继的情况下返回。写 open 会在可用时复用按 revision 为键的 preparation，否则执行同一套 preparation，再按有界分片编码同目录临时文件、在 Worker Thread 中校验、复查源修订，并在返回前以不覆盖方式发布当前后继。源保持逐字节不变。如果源在 preparation 后发生变化，该次写 open 会失败，已经返回给读方的逻辑历史不会被替换；后续写 open 会针对新的 revision 重新执行 preparation。后端在 memo 化前冻结已解码的 event graph，并在此时将其标记为 `shared-frozen`；句柄读取和 slice 即使为空也保留该状态。只有尚未实体化的 pending 空日志报告 `detached`。`stat(id)` 与 `list()` 只选择并转换最高 generation 的 header，不读取事件行，也不启动迁移；快照携带所选文件的 `sizeBytes` 与尽力而为的 stat 派生修订号。选择 `compression: 'none'` 后，日志是外部读取方可直接消费的换行分隔文本；压缩默认值必须经后端读取。
+`open(id, 'read'|'write')` 选择最高规范 generation。当前格式输入走普通快速路径。对于历史输入，只读 open 会单遍解码并迁移源、校验当前逻辑结果，然后在不发布后继的情况下返回。写 open 会在可用时复用按 revision 为键的 preparation，否则执行同一套 preparation，再按有界分片编码同目录临时文件、在 Worker Thread 中校验、复查源修订，并在返回前以不覆盖方式发布当前后继。源保持逐字节不变。如果源在 preparation 后发生变化，该次写 open 会失败，已经返回给读方的逻辑历史不会被替换；后续写 open 会针对新的 revision 重新执行 preparation。后端在 memo 化前冻结已解码的 event graph，并在此时将其标记为 `shared-frozen`；每个嵌套对象和数组都会冻结，句柄读取和 slice 即使为空也保留该状态。只有尚未实体化的 pending 空日志报告 `detached`。`stat(id)` 与 `list()` 只选择并转换最高 generation 的 header，不读取事件行，也不启动迁移；快照携带所选文件的 `sizeBytes` 与尽力而为的修订号。当前格式修订号标识该文件；历史格式修订号还包含持久化根目录中所选文件的指纹，因此子日志变化会使缓存的逻辑事件失效。指纹只读取文件系统元数据；无关变化也会保守地使历史修订号失效。一次 `list()` 为其历史条目共用一个全库指纹。选择 `compression: 'none'` 后，日志是外部读取方可直接消费的换行分隔文本；压缩默认值必须经后端读取。
+
+历史正文准备通过 [V3→V4](../session-format-v3-to-v4/README.zh.md) 补齐父目录：从 header 找到候选直属子 Session，通过历史编解码器逐个读取其自身 descriptor，保留紧凑证据与来源修订。此过程不准备子目录，也不发布子后继。不可读或不支持的 header（包括损坏的 Zstandard header 帧）不参与发现，也不出现在 `list()` 中。直接访问损坏的压缩 header 仍会失败；header 的 I/O 错误与取消错误继续传播。子日志解码或 descriptor 字段失败会产生带子路径的警告；父目录没有完整条目时，通过 `subagent/catalog` 保留 header 身份信息。健康子项和已有父目录项仍可使用。打开损坏子 Session 时仍报告该子会话的错误。缺失、不支持或多个 descriptor 同样生成模式未知的目录项，不编造标签。已发布的未知条目仍可浏览；读取子历史时会重试实际日志，并从有效 descriptor 确定模式。准备返回、复用与发布前会重新检查成员集合及已检查来源的修订，也包括读取失败的子日志，使修复后的子日志能够使旧准备缓存失效。来源变化时只读打开重试一次，写打开拒绝发布。取消仍会中止操作。当前 V4 打开跳过发现，并在暴露事件前校验目录字段、唯一性及当前投递归属。
+
+历史格式的 `stat` 与 `list` 修订号需要与根目录 Session 数量成正比的元数据工作。首次正文准备扫描所有所选 header 并解码直属子正文；复用准备缓存仍扫描成员集合并检查修订。只读访问从不发布升级，因此冷进程与被淘汰的准备缓存会重复这些工作。当前 V4 正文读取和修订号避开历史全库扫描。见[实测成本与诊断命令](../../../.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.zh.md#catalog-scan-measurements)。
 
 -----
 
@@ -93,7 +97,7 @@ kind: "package-reference"
 
 ### 设计理念
 
-该后端拥有自己完整的存储运行时（`src/storage.ts`）：`JsonlSessionHandle` 承载逐句柄修改链、带固定批处理窗口与 single-flight 排空的已路由实时事件缓冲、单调读取与幂等 close；一个 tracker 持有进程内单写者认领、teardown 清扫所遍历的打开句柄集合，以及后端自己的会话监听器所路由进的已创建但未实体化待定会话。历史正文读取共享每个 Session 唯一的一次 Decode/Migrate preparation，按 revision 为键的有界 memo 让紧接的观察到恢复交接复用该解析；backend 在 memo 化前只对每个 event graph 深度冻结一次，因此后续 handle read 无需复制或再次冻结。只有写 open 才发布准备好的后继。本包有意只暴露默认插件导出与配置类型——具体类不是具名导出，因此消费方只耦合 `ctx.sessionPersistence`，其可观察行为由共享 seam 测试套件（`runPersistenceContract`/`runLiveWritePathContract`）钉住。其变更令牌是尽力而为的文件修订值：device、inode、size 与纳秒时间戳标识一份日志，供 `stat`/`list`、在并发 append 撕裂读取时重试的稳定读取循环，以及发布前源检查使用。
+该后端拥有自己完整的存储运行时（`src/storage.ts`）：`JsonlSessionHandle` 承载逐句柄修改链、带固定批处理窗口与 single-flight 排空的已路由实时事件缓冲、单调读取与幂等 close；一个 tracker 持有进程内单写者认领、teardown 清扫所遍历的打开句柄集合，以及后端自己的会话监听器所路由进的已创建但未实体化待定会话。历史正文读取共享每个 Session 唯一的一次 Decode/Migrate preparation，按 revision 为键的有界 memo 让紧接的观察到恢复交接复用该解析；backend 在 memo 化前只对每个 event graph 深度冻结一次，因此后续 handle read 无需复制或再次冻结。只有写 open 才发布准备好的后继。本包有意只暴露默认插件导出与配置类型——具体类不是具名导出，因此消费方只耦合 `ctx.sessionPersistence`，其可观察行为由共享 seam 测试套件（`runPersistenceContract`/`runLiveWritePathContract`）钉住。物理修订号组合 device、inode、size 与纳秒时间戳，供准备缓存、稳定读取重试及发布检查使用。历史格式的公开修订号还加入所选路径排序后及其物理修订号的 SHA-256 指纹；锁文件与保留但未被选中的代际不参与计算。
 
 ### 物理编码
 

package/lib/index.js

@@ -1,5 +1,5 @@
 import z from "@deepseek-ai/schemastery";
-import { SessionFormatUnsupportedMigrationError, sessionFormatCatalog } from "@deepseek-ai/dsh-session-format-catalog";
+import { SessionFormatUnsupportedMigrationError, createSessionFormatCatalogWithChildren, historicalSessionFormatCatalog, sessionFormatCatalog } from "@deepseek-ai/dsh-session-format-catalog";
 import { readdirSync } from "node:fs";
 import { link, lstat, mkdir, mkdtemp, open, readFile, readdir, realpath, rm, stat, truncate } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, parse, resolve, toNamespacedPath } from "node:path";
@@ -9,9 +9,9 @@ import { createHash, randomBytes } from "node:crypto";
 import { SessionAlreadyExistsError, SessionAlreadyOwnedError, SessionFormatUnsupportedError, SessionHandleClosedError, SessionPersistence, SessionPersistenceCorruptionError, SessionPersistenceNotFoundError, SessionPersistenceRevision, SessionReadOnlyError, assertContiguous, assertStoredId, materializeAppendBatch, materializeCreateHeader, sessionFormatVersionRefusal, validateStoredEvents } from "@deepseek-ai/dsh-session-persistence";
 import { BlockAssembler, errorChain, expandAssistantStream } from "@deepseek-ai/dsh-llm";
 import { tryLockExclusive } from "@deepseek-ai/node-addon-system/flock";
-import { SESSION_FORMAT_VERSION, Session, SessionId, SessionLogOffset } from "@deepseek-ai/dsh-session";
-import { SessionFormatUnsupportedMigrationError as SessionFormatUnsupportedMigrationError$1, parseSessionFormatLogFilename, sessionFormatLogFilename } from "@deepseek-ai/dsh-session-format";
-import { assertV3RowAdmission } from "@deepseek-ai/dsh-session-format-v2-to-v3";
+import { KNOWN_SESSION_EVENT_TYPES, SESSION_FORMAT_VERSION, Session, SessionId, SessionLogOffset } from "@deepseek-ai/dsh-session";
+import { SessionFormatError, SessionFormatUnsupportedMigrationError as SessionFormatUnsupportedMigrationError$1, parseSessionFormatLogFilename, sessionFormatLogFilename } from "@deepseek-ai/dsh-session-format";
+import { assertReleasedV4Relationships, assertV4RowAdmission, historicalChildCatalogSource } from "@deepseek-ai/dsh-session-format-v3-to-v4";
 import { constants, createZstdCompress, createZstdDecompress, zstdCompress, zstdDecompress, zstdDecompressSync } from "node:zlib";
 import { isDeepStrictEqual, promisify } from "node:util";
 import { constants as constants$1 } from "node:buffer";
@@ -1069,6 +1069,7 @@ var SessionLogScanner = class {
 	finish() {
 		this.finished = true;
 		const artifact = this.restore.finish();
+		assertReleasedV4Relationships(artifact, KNOWN_SESSION_EVENT_TYPES);
 		return {
 			meta: this.meta,
 			inheritedEventCount: SessionLogOffset(artifact.inheritedEventCount),
@@ -1089,7 +1090,7 @@ var SessionLogScanner = class {
 			return;
 		}
 		try {
-			assertV3RowAdmission(decoded);
+			assertV4RowAdmission(decoded, KNOWN_SESSION_EVENT_TYPES);
 		} catch (error) {
 			if (error instanceof SessionFormatUnsupportedMigrationError$1) throw new SessionFormatUnsupportedError(error.message);
 			throw error;
@@ -2078,6 +2079,7 @@ async function publishPreparedMigration(options, suffix, artifact, sourceIdentit
 		const verifiedStage = await verifyCurrentFile(staged.path, compression, artifact.header.id, eventCount);
 		if (verifiedStage.bytes !== staged.bytes || verifiedStage.digest !== staged.digest) throw new Error("staged session generation changed during verification");
 		await internals.barrier("before-source-check", 1);
+		await options.validateRelatedSources?.();
 		if (identity(await internals.fs.stat(sourcePath)) !== identity(sourceIdentity)) throw new JsonlGenerationSourceChangedError(sourcePath);
 		const published = await publishCurrentExclusive(staged.path, currentPath, internals);
 		if (published && internals.platform === "win32") staged = {
@@ -2126,6 +2128,7 @@ async function prepareMigration(options, internals) {
 		throw error;
 	}
 	if (artifact.header.version !== format.currentVersion) throw new Error(`format migration returned v${artifact.header.version}, expected v${format.currentVersion}`);
+	await options.validateRelatedSources?.();
 	const sourceIdentity = source.identity;
 	let publication;
 	return {
@@ -2159,6 +2162,111 @@ function createJsonlGenerationRuntime(overrides = {}) {
 	};
 }
 const defaultGenerationRuntime = createJsonlGenerationRuntime();
+/**
+* Read one stable source through the shared streaming parser without publishing a generation.
+* @param path - selected source generation path.
+* @param version - physical source version identified by its filename.
+* @param compression - source encoding.
+* @param format - codec/restore factory, independent of current-generation publication.
+* @param signal - cancellation observed during source reads and decode yields.
+* @returns decoded artifact and physical source identity for later revalidation.
+* @throws SessionFormatError for physical decoding failures; storage, cancellation, and unsupported migration errors retain their category.
+*/
+async function readDecodedJsonlSource(path, version, compression, format, signal) {
+	const source = await readStableJsonlFile(path, signal);
+	let artifact;
+	try {
+		artifact = await decodeStreamingMigration(source.bytes, compression, version, format, void 0, signal);
+	} catch (error) {
+		if (signal?.aborted || error instanceof SessionFormatError) throw error;
+		throw new SessionFormatError(String(error), { cause: error });
+	}
+	return {
+		artifact,
+		identity: source.identity
+	};
+}
+//#endregion
+//#region lib/types/catalog-migration.js
+/** Collect historical discovery facts without recursively preparing related current generations. */
+/**
+* Collect each related child's own descriptor through existing historical codecs.
+* @param parentId - parent whose incoming migration consumes these facts.
+* @param sources - header-indexed direct children in the selected source corpus.
+* @param compression - configured source encoding.
+* @param signal - cancellation forwarded through each source read.
+* @returns compact facts and child-local failures; complete child event arrays are released after extraction.
+*/
+async function prepareCatalogFacts(parentId, sources, compression, signal) {
+	const facts = [];
+	const failures = [];
+	const witnesses = [];
+	for (const source of sources) {
+		signal.throwIfAborted();
+		const version = parseGenerationLogFilename(basename(source.path), compression);
+		if (version === void 0) throw new SessionFormatUnsupportedMigrationError$1(`unrecognized historical child generation ${source.path}`);
+		const witness = {
+			path: source.path,
+			identity: await stat(source.path, { bigint: true })
+		};
+		witnesses.push(witness);
+		const unavailable = {
+			childId: source.header.id,
+			childCreatedAt: source.header.createdAt,
+			descriptorCount: 0,
+			descriptor: null,
+			sourcePath: source.path
+		};
+		let restored;
+		try {
+			restored = await readDecodedJsonlSource(source.path, version, compression, { createRestore: (header) => (version <= 3 ? historicalSessionFormatCatalog : sessionFormatCatalog).createRestore(header, {
+				recovery: "recoverable",
+				validation: "current"
+			}) }, signal);
+		} catch (error) {
+			signal.throwIfAborted();
+			failures.push({
+				path: source.path,
+				error
+			});
+			facts.push(unavailable);
+			continue;
+		}
+		witness.identity = restored.identity;
+		const header = restored.artifact.header;
+		if (header.id !== source.header.id || header.createdAt !== source.header.createdAt || header.parentSession !== parentId || header.origin !== "subagent" || [
+			"cwd",
+			"isSeeded",
+			"delegationDepth",
+			"agentPreset"
+		].some((key) => header[key] !== source.header[key])) throw new JsonlGenerationSourceChangedError(source.path);
+		let fact;
+		try {
+			fact = historicalChildCatalogSource(restored.artifact);
+		} catch (error) {
+			failures.push({
+				path: source.path,
+				error
+			});
+			facts.push(unavailable);
+			continue;
+		}
+		facts.push({
+			...fact,
+			sourcePath: source.path
+		});
+	}
+	return {
+		facts,
+		failures,
+		async validate() {
+			for (const witness of witnesses) {
+				const current = await stat(witness.path, { bigint: true });
+				if (current.dev !== witness.identity.dev || current.ino !== witness.identity.ino || current.size !== witness.identity.size || current.mtimeNs !== witness.identity.mtimeNs || current.ctimeNs !== witness.identity.ctimeNs) throw new JsonlGenerationSourceChangedError(witness.path);
+			}
+		}
+	};
+}
 //#endregion
 //#region lib/types/index.js
 /**
@@ -2187,13 +2295,17 @@ function assertZstdHeaderFrame(plaintext) {
 }
 /** Loader schema for the JSONL artifact's physical encoding. */
 const JsonlCompressionSchema = z.union([z.const("zstd"), z.const("none")]).default(DEFAULT_COMPRESSION);
-/** Deep-freeze one acyclic stored JSON event without recursive calls. */
+/** Deep-freeze acyclic stored JSON; its arrays contain only indexed JSON values. */
 function freezeStoredEvent(event) {
 	const pending = [event];
 	while (pending.length > 0) {
 		const current = pending.pop();
 		Object.freeze(current);
-		for (const key in current) {
+		if (Array.isArray(current)) for (let index = 0; index < current.length; index += 1) {
+			const child = current[index];
+			if (child !== null && typeof child === "object") pending.push(child);
+		}
+		else for (const key in current) {
 			const child = current[key];
 			if (child !== null && typeof child === "object") pending.push(child);
 		}
@@ -2289,10 +2401,6 @@ var JsonlSessionPersistence = class extends SessionPersistence {
 		this.compression = config.compression ?? DEFAULT_COMPRESSION;
 		this.generationFormat = {
 			currentVersion: sessionFormatCatalog.currentVersion,
-			createRestore: (header) => sessionFormatCatalog.createRestore(header, {
-				recovery: "recoverable",
-				validation: "transformed"
-			}),
 			encodeHeader: (header, inheritedEventCount) => sessionFormatCatalog.encodeCurrentHeader(header, inheritedEventCount),
 			encodeEvent: (event) => sessionFormatCatalog.encodeCurrentEvent(event),
 			isUnsupportedMigrationError: (error) => error instanceof SessionFormatUnsupportedMigrationError
@@ -2354,7 +2462,13 @@ var JsonlSessionPersistence = class extends SessionPersistence {
 				materialized: false,
 				inheritedEventCount: pending.inheritedEventCount
 			}));
-			const stored = await this.requireStoredLog(id, options?.signal);
+			let stored;
+			try {
+				stored = await this.requireStoredLog(id, options?.signal);
+			} catch (error) {
+				if (!(error instanceof JsonlGenerationSourceChangedError)) throw error;
+				stored = await this.requireStoredLog(id, options?.signal);
+			}
 			let state;
 			if (stored.status === "prepared") state = {
 				cursor: 0,
@@ -2437,7 +2551,7 @@ var JsonlSessionPersistence = class extends SessionPersistence {
 			options?.signal?.throwIfAborted();
 			return {
 				header,
-				revision: fileRevision(identity),
+				revision: selected.sourceVersion < SESSION_FORMAT_VERSION ? SessionPersistenceRevision(`${fileRevision(identity)}:${await this.historicalCorpusRevision(options?.signal)}`) : fileRevision(identity),
 				sizeBytes: Number(identity.size)
 			};
 		} catch (error) {
@@ -2457,7 +2571,9 @@ var JsonlSessionPersistence = class extends SessionPersistence {
 		const snapshots = [];
 		const listed = /* @__PURE__ */ new Set();
 		const pending = [...this.tracker.pendingEntries()];
-		for (const artifact of await this.listArtifacts(signal)) {
+		const artifacts = await this.listArtifacts(signal);
+		const corpusRevision = artifacts.some((artifact) => artifact.sourceVersion < SESSION_FORMAT_VERSION) ? await this.historicalCorpusRevision(signal) : void 0;
+		for (const artifact of artifacts) {
 			signal?.throwIfAborted();
 			try {
 				const identity = await stat(artifact.path, { bigint: true });
@@ -2465,7 +2581,7 @@ var JsonlSessionPersistence = class extends SessionPersistence {
 				listed.add(artifact.header.id);
 				snapshots.push({
 					header: artifact.header,
-					revision: fileRevision(identity),
+					revision: artifact.sourceVersion < SESSION_FORMAT_VERSION ? SessionPersistenceRevision(`${fileRevision(identity)}:${corpusRevision}`) : fileRevision(identity),
 					sizeBytes: Number(identity.size)
 				});
 			} catch (error) {
@@ -2534,6 +2650,12 @@ var JsonlSessionPersistence = class extends SessionPersistence {
 		signal.throwIfAborted();
 		const memoized = this.coldLogMemo.get(id);
 		if (memoized?.status === "prepared" && memoized.revision === sourceRevision) {
+			try {
+				await memoized.validateRelatedSources();
+			} catch (error) {
+				this.coldLogMemo.delete(id);
+				throw this.generationFailure(id, selected, error);
+			}
 			this.coldLogMemo.delete(id);
 			this.coldLogMemo.set(id, memoized);
 			return memoized;
@@ -2557,13 +2679,34 @@ var JsonlSessionPersistence = class extends SessionPersistence {
 	/** Decode one historical generation without publishing a successor. */
 	async prepareStoredMigration(id, selected, signal) {
 		let prepared;
+		let validateRelatedSources;
 		try {
+			const children = async () => (await this.listArtifacts(signal)).filter((source) => source.header.origin === "subagent" && source.header.parentSession === id);
+			const sources = await children();
+			const related = await prepareCatalogFacts(id, sources, this.compression, signal);
+			for (const failure of related.failures) this.ctx.logger.warn(`${this.name}: session "${id}" catalog retained a child with unknown descriptor (raw log: ${failure.path}): ${String(failure.error)}`);
+			const membership = sources.map((source) => source.path).sort();
+			validateRelatedSources = async () => {
+				const current = (await children()).map((source) => source.path).sort();
+				const before = new Set(membership);
+				const after = new Set(current);
+				const changed = current.find((path) => !before.has(path)) ?? membership.find((path) => !after.has(path));
+				if (changed !== void 0) throw new JsonlGenerationSourceChangedError(changed);
+				await related.validate();
+			};
 			prepared = await prepareJsonlMigration({
 				sourcePath: selected.sourcePath,
 				sourceVersion: selected.sourceVersion,
 				currentPath: selected.currentPath,
 				compression: this.compression,
-				format: this.generationFormat,
+				format: {
+					...this.generationFormat,
+					createRestore: (header) => createSessionFormatCatalogWithChildren(related.facts).createRestore(header, {
+						recovery: "recoverable",
+						validation: "transformed"
+					})
+				},
+				validateRelatedSources,
 				verifyCurrentFile: verifyCurrentGenerationInWorker,
 				validateHistoricalHeader: (headerValue) => this.validateSourceIdentity(selected, headerValue, id, signal),
 				signal
@@ -2580,6 +2723,7 @@ var JsonlSessionPersistence = class extends SessionPersistence {
 		});
 		const stored = {
 			status: "prepared",
+			validateRelatedSources,
 			meta,
 			...freezeStoredEvents(events),
 			tornTruncateTo: void 0,
@@ -2856,33 +3000,57 @@ var JsonlSessionPersistence = class extends SessionPersistence {
 			decoder.close();
 		}
 	}
+	/** Enumerate selected physical generations without interpreting their headers or bodies. */
+	async listGenerations(signal) {
+		const sources = [];
+		for (const project of await this.listProjectDirs(signal)) for (const dir of await this.listSessionDirs(project, signal)) {
+			signal?.throwIfAborted();
+			const selected = await this.resolveGenerationInDirectory(dir, signal);
+			if (selected !== void 0) sources.push(selected);
+		}
+		return sources;
+	}
+	/** Historical logical events depend on the corpus, including members with unreadable headers. */
+	async historicalCorpusRevision(signal) {
+		const paths = (await this.listGenerations(signal)).map((source) => source.sourcePath).sort();
+		const hash = createHash("sha256");
+		for (const path of paths) {
+			signal?.throwIfAborted();
+			let revision;
+			try {
+				revision = fileRevision(await stat(path, { bigint: true }));
+			} catch (error) {
+				if (!isENOENT(error)) throw error;
+				revision = "missing";
+			}
+			hash.update(JSON.stringify([path, revision]));
+		}
+		signal?.throwIfAborted();
+		return hash.digest("hex");
+	}
 	async listArtifacts(signal) {
 		signal?.throwIfAborted();
 		await this.ensureRootEncoding();
 		signal?.throwIfAborted();
 		const artifacts = [];
 		const ids = /* @__PURE__ */ new Set();
-		for (const project of await this.listProjectDirs(signal)) {
+		for (const selected of await this.listGenerations(signal)) {
 			signal?.throwIfAborted();
-			for (const dir of await this.listSessionDirs(project, signal)) {
-				signal?.throwIfAborted();
-				const selected = await this.resolveGenerationInDirectory(dir, signal);
-				if (selected === void 0) continue;
-				let header;
-				try {
-					header = await this.readGenerationHeader(selected, void 0, signal);
-				} catch (error) {
-					if (error instanceof SessionFormatUnsupportedError) continue;
-					throw error;
-				}
-				if (header === void 0) continue;
-				if (ids.has(header.id)) throw new Error(`duplicate JSONL session id "${header.id}" appears in multiple project directories`);
-				ids.add(header.id);
-				artifacts.push({
-					header,
-					path: selected.sourcePath
-				});
+			let header;
+			try {
+				header = await this.readGenerationHeader(selected, void 0, signal);
+			} catch (error) {
+				if (error instanceof SessionFormatUnsupportedError || error instanceof SessionPersistenceCorruptionError) continue;
+				throw error;
 			}
+			if (header === void 0) continue;
+			if (ids.has(header.id)) throw new Error(`duplicate JSONL session id "${header.id}" appears in multiple project directories`);
+			ids.add(header.id);
+			artifacts.push({
+				header,
+				path: selected.sourcePath,
+				sourceVersion: selected.sourceVersion
+			});
 		}
 		signal?.throwIfAborted();
 		return artifacts;
@@ -3122,7 +3290,7 @@ var JsonlSessionPersistence = class extends SessionPersistence {
 			await handle.close();
 		}
 	}
-	/** Read and validate only the independently compressed header frame. */
+	/** Read only the header frame; compression failures reject as corruption, while I/O and cancellation propagate. */
 	async readFirstZstdLine(path, signal) {
 		signal?.throwIfAborted();
 		const handle = await open(path, "r");
@@ -3138,21 +3306,18 @@ var JsonlSessionPersistence = class extends SessionPersistence {
 				signal?.throwIfAborted();
 				content = Buffer.concat([content, chunk.subarray(0, bytesRead)]);
 				signal?.throwIfAborted();
-				const first = scanZstdFrames(content, 1).frames[0];
-				signal?.throwIfAborted();
-				if (first === void 0) continue;
-				let plaintext;
 				try {
+					const first = scanZstdFrames(content, 1).frames[0];
+					if (first === void 0) continue;
+					const plaintext = await decompressZstdFrame(content.subarray(first.start, first.end));
 					signal?.throwIfAborted();
-					plaintext = await decompressZstdFrame(content.subarray(first.start, first.end));
+					assertZstdHeaderFrame(plaintext);
+					return plaintext.subarray(0, -1).toString("utf8");
 				} catch (error) {
 					/* v8 ignore next -- decoder failure plus concurrent abort is timing-dependent */
 					if (signal?.aborted) signal.throwIfAborted();
-					throw new Error("corrupt Zstandard session log: header frame failed validation", { cause: error });
+					throw new SessionPersistenceCorruptionError(`corrupt Zstandard session log: header frame failed validation: ${String(error)} (raw log: ${path})`, { cause: error });
 				}
-				signal?.throwIfAborted();
-				assertZstdHeaderFrame(plaintext);
-				return plaintext.subarray(0, -1).toString("utf8");
 			}
 		} finally {
 			await handle.close();

package/lib/types/catalog-migration.d.ts

@@ -0,0 +1,28 @@
+/** Collect historical discovery facts without recursively preparing related current generations. */
+import type { SessionFormatJsonObject } from '@deepseek-ai/dsh-session-format';
+import type { SessionHeader, SessionId } from '@deepseek-ai/dsh-session';
+import type { JsonlCompression } from './format.ts';
+/** Per-parent supplemental facts and the source checks required before serving or publishing them. */
+interface PreparedCatalogFacts {
+    readonly facts: readonly SessionFormatJsonObject[];
+    readonly failures: readonly {
+        readonly path: string;
+        readonly error: unknown;
+    }[];
+    /** @returns resolves while every inspected child still has the captured physical revision. */
+    validate(): Promise<void>;
+}
+/**
+ * Collect each related child's own descriptor through existing historical codecs.
+ * @param parentId - parent whose incoming migration consumes these facts.
+ * @param sources - header-indexed direct children in the selected source corpus.
+ * @param compression - configured source encoding.
+ * @param signal - cancellation forwarded through each source read.
+ * @returns compact facts and child-local failures; complete child event arrays are released after extraction.
+ */
+export declare function prepareCatalogFacts(parentId: SessionId, sources: readonly {
+    readonly header: SessionHeader;
+    readonly path: string;
+}[], compression: JsonlCompression, signal: AbortSignal): Promise<PreparedCatalogFacts>;
+export {};
+//# sourceMappingURL=catalog-migration.d.ts.map

package/lib/types/generation.d.ts

@@ -24,6 +24,8 @@ export interface JsonlGenerationFormatAdapter {
 }
 /** Inputs for preparing one historical generation and publishing its current successor later. */
 export interface PrepareJsonlMigrationOptions {
+    /** Revalidate related source facts before preparation returns and immediately before publication. */
+    readonly validateRelatedSources?: () => Promise<void>;
     /** Immutable generation selected by the backend resolver. */
     readonly sourcePath: string;
     /** Version selected from the source filename and independently checked against its header. */
@@ -159,5 +161,19 @@ export declare function prepareJsonlMigration(options: PrepareJsonlMigrationOpti
  * @returns bound generation operations.
  */
 export declare function createJsonlGenerationRuntime(overrides?: JsonlGenerationRuntimeOverrides): JsonlGenerationRuntime;
+/**
+ * Read one stable source through the shared streaming parser without publishing a generation.
+ * @param path - selected source generation path.
+ * @param version - physical source version identified by its filename.
+ * @param compression - source encoding.
+ * @param format - codec/restore factory, independent of current-generation publication.
+ * @param signal - cancellation observed during source reads and decode yields.
+ * @returns decoded artifact and physical source identity for later revalidation.
+ * @throws SessionFormatError for physical decoding failures; storage, cancellation, and unsupported migration errors retain their category.
+ */
+export declare function readDecodedJsonlSource(path: string, version: number, compression: JsonlCompression, format: Pick<JsonlGenerationFormatAdapter, 'createRestore'>, signal?: AbortSignal): Promise<{
+    artifact: SessionFormatArtifact;
+    identity: JsonlPhysicalIdentity;
+}>;
 export {};
 //# sourceMappingURL=generation.d.ts.map

package/lib/types/index.d.ts

@@ -199,6 +199,10 @@ declare class JsonlSessionPersistence extends SessionPersistence {
     acquireWriteLease(header: SessionHeader): Promise<SessionWriteLease>;
     /** Decode complete frames and retain complete JSONL records from a torn final frame. */
     private readZstdPrefix;
+    /** Enumerate selected physical generations without interpreting their headers or bodies. */
+    private listGenerations;
+    /** Historical logical events depend on the corpus, including members with unreadable headers. */
+    private historicalCorpusRevision;
     private listArtifacts;
     /** Read and translate one selected generation header without inspecting its body. */
     private readGenerationHeader;
@@ -231,7 +235,7 @@ declare class JsonlSessionPersistence extends SessionPersistence {
      * Reads in bounded chunks so a huge log costs only the header read.
      */
     private readFirstLine;
-    /** Read and validate only the independently compressed header frame. */
+    /** Read only the header frame; compression failures reject as corruption, while I/O and cancellation propagate. */
     private readFirstZstdLine;
     /** Select the numerically highest canonical generation in one Session directory. */
     private resolveGenerationInDirectory;