@deepseek-ai/dsh-session-snapshot 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/test-support/session-snapshot/README.md
-README.md: 51aaff9af7dfce83ed032b42ce0bb471aa384002
-README.zh.md: ad136b19a75170c130bbb872ba02bb88e010bb02
+README.md: 2bc7b9eaf9ebd8e7a2fa357e60eddd594d21d9a7
+README.zh.md: ea26aa50d9dc835c8f234ad224afff9f5a33483e

package/README.md

@@ -68,13 +68,15 @@ defineAcpSnapshotSuite({
 })
 ```
 
-Each recorded-session directory carries a closed `snapshot.yml` manifest plus canonical parent and contiguous child roles. Parent filenames are `session[.vN].jsonl`; children are `session.<ordinal>[.vN].jsonl`; v0 omits `.v0`, positive versions use lowercase `.vN`, and every filename agrees with its header. A role may retain older generations, but the harness selects the numerically highest one. An owning manifest may declare `sessionFormat.version` plus one or more closed `coverage` names to keep that historical generation as an explicit migration fixture; absence tracks the current writer. The manifest also names the scenario, shipped profile, composition/header class, recording source, and only the replay, platform, permission, environment, workspace, or input facts the completed Session cannot reconstruct. Storage guards check tool results and portable paths in every selected parent and child role. Prompt/schema scrubbing, message identity, and prompt-before-request ordering apply to current generations; retained predecessors keep their historical representation. The adapter registers expected-output, Session-log, and optional `workspace.expected/` comparisons; guards reject orphan directories, missing roles, noncanonical names, absolute paths, malformed manifests, and platform-specific separators.
+Each recorded-session directory carries a closed `snapshot.yml` manifest plus canonical parent and contiguous child roles. Parent filenames are `session[.vN].jsonl`; children are `session.<ordinal>[.vN].jsonl`; v0 omits `.v0`, positive versions use lowercase `.vN`, and every filename agrees with its header. A role may retain older generations, but the harness selects the numerically highest one. An owning manifest may declare `sessionFormat.version` plus one or more closed `coverage` names to keep that historical generation as an explicit migration fixture. Without that declaration, record and refresh write the current generation; replay also accepts the retained V3 baseline under the [corpus policy](../../../snapshots/AGENTS.md). The manifest also names the scenario, shipped profile, composition/header class, recording source, and only the replay, platform, permission, environment, workspace, or input facts the completed Session cannot reconstruct. Storage guards check tool results and portable paths in every selected parent and child role. Prompt/schema scrubbing, message identity, and prompt-before-request ordering apply to current generations; retained predecessors keep their historical representation. The adapter registers expected-output, Session-log, and optional `workspace.expected/` comparisons; guards reject orphan directories, missing roles, noncanonical names, absolute paths, malformed manifests, and platform-specific separators.
 
-`normalizeSessionSnapshot` retains the complete Session header and event payloads but omits top-level `seq`/`time` envelopes from committed fixtures after normalizing paths and scrubbing system-prompt text and tool schemas; it also normalizes embedded stream clocks and historical packed-row `seq0`/`time0` envelopes, and catalog child-creation clocks. Event order and source-event references are preserved. Replay synthesizes the top-level envelopes in memory, while runtime persistence continues to write complete logs. Multi-session comparison validates expected and harvested logs through the strict build-static Session format catalog before identity redaction and normalization; source filenames cannot alter format validation. A retained historical replay input is not the native current-format writer-output oracle: structural migration preserves request meaning but can produce a different event layout. Normalization preserves unexpected request-header fields, including `system`, so regressions remain visible. Versionless protocol-adapter unit fixtures remain outside the released Session format corpus. Fixtures in the [current writer format](../../../docs/session-format-status.md) use one row per event; retained v0/v1 fixtures may use canonical packed rows. The [temporary repository migrator](../../../scripts/migrate-packed-session-fixtures.ts) (`pnpm run migrate:packed-session-fixtures`) rewrites older historical layouts, and its [removal proposal](../../../.agents/notes/proposed/process/2026-07-26-remove-packed-session-fixture-migrator.md) owns its deletion.
+`normalizeSessionSnapshot` retains the complete Session header and event payloads but omits top-level `seq`/`time` envelopes from committed fixtures after normalizing paths and scrubbing system-prompt text and tool schemas; it also normalizes embedded stream clocks and historical packed-row `seq0`/`time0` envelopes, and catalog child-creation clocks. Event order and source-event reference order are preserved. Record and refresh write top-level `sourceEventSeqs` as expanded arrays. Replay synthesizes the top-level envelopes in memory, while runtime persistence continues to write complete logs. Multi-session comparison validates expected and harvested logs through the strict build-static Session format catalog before identity redaction and normalization; source filenames cannot alter format validation. A retained historical replay input is not the native current-format writer-output oracle: structural migration preserves request meaning but can produce a different event layout. Normalization preserves unexpected request-header fields, including `system`, so regressions remain visible. Versionless protocol-adapter unit fixtures remain outside the released Session format corpus. Fixtures in the [current writer format](../../../docs/session-format-status.md) use one row per event; retained v0/v1 fixtures may use canonical packed rows. The [temporary repository migrator](../../../scripts/migrate-packed-session-fixtures.ts) (`pnpm run migrate:packed-session-fixtures`) rewrites older historical layouts, and its [removal proposal](../../../.agents/notes/proposed/process/2026-07-26-remove-packed-session-fixture-migrator.md) owns its deletion.
 
 Spill scenarios save through the real local provider under a private temporary root. Their fixture adapter exposes fixed-length logical locators and maps only this run’s saved locators back to real files for retrieval, preserving preview budgets without writing into a shared logical path. Known snapshot spill paths normalize to stable locator tokens, including paths quoted inside JSON omission notices with JSON-escaped Windows separators. Refresh extraction preserves the matched serialized path spelling for literal replacement. Normalization changes only the locator: saved byte lengths and omission counts remain comparison evidence.
 
-Retained historical scenarios keep their canonical Session files unchanged and selected for replay, with no newer canonical sibling in the pinned directory. Their exact normalized native current-format output is recorded separately in `writer.expected.jsonl` for the parent and `writer.<ordinal>.expected.jsonl` for children; these are output oracles, not replay generations. Retained SDK scenarios use `notifications.current.expected.jsonl` for current protocol output. Comparisons neither project current events back into a historical format nor strip structural differences. Independent migration tests verify the official transform rather than treating native writer layout as its expected event sequence.
+Retained historical scenarios keep their canonical Session files unchanged and selected for replay, with no newer canonical sibling in the pinned directory. Their exact normalized native writer output is recorded separately in `writer.expected.jsonl` for the parent and `writer.<ordinal>.expected.jsonl` for children; these are output oracles, not replay generations. Output oracles may retain an older supported generation: comparison restores them through the strict catalog, while harvested logs must use the checkout writer. Fresh-writer golden comparisons select `nativeWriterOutput` to tokenize only delivery markers qualified by each input’s original writer generation after strict restoration. Other delivery generations and captured-source fields remain numeric; source-versus-migrated-artifact comparisons preserve exact generations by default. Recording and refresh never store these comparison tokens. Retained SDK scenarios use `notifications.current.expected.jsonl` for current protocol output. Comparisons neither project current events back into a historical format nor strip structural differences. Independent migration tests verify the official transform rather than treating native writer layout as its expected event sequence.
+
+Headless/ACP and SDK adapters compare raw catalog child-creation times with harvested child headers before normalization. Refresh preserves the chosen child header time in every matching catalog entry, including inherited copies, so retained header clocks cannot diverge from freshly written catalog clocks. Committed historical inconsistencies remain unchanged migration-refusal evidence; normalizing their clocks does not establish successful migration.
 
 ### Record, replay, and refresh
 

package/README.zh.md

@@ -68,13 +68,15 @@ defineAcpSnapshotSuite({
 })
 ```
 
-每个已记录 Session 目录携带封闭的 `snapshot.yml` manifest，以及规范 parent 与连续 child 角色。parent 文件名是 `session[.vN].jsonl`；child 是 `session.<ordinal>[.vN].jsonl`；v0 省略 `.v0`，正版本使用小写 `.vN`，且每个文件名与其 header 一致。一个角色可以保留旧 generation，但 harness 会选择数值最高的一项。拥有 fixture 的 manifest 可以声明 `sessionFormat.version` 与一个或多个封闭 `coverage` 名称，把该历史 generation 保留为显式迁移 fixture；省略此字段时跟随当前 writer。manifest 还会指名场景、随附 profile、组合／header 类别、录制来源，以及已完成 Session 无法重建的 replay、平台、权限、环境、workspace 或输入事实。存储保护检查每个选定 parent 与 child 角色的工具结果和可移植路径。提示词／schema 擦除、消息身份及提示词先于请求的顺序检查适用于当前 generation；保留的前代维持其历史表示。适配器注册预期输出、Session 日志与可选 `workspace.expected/` 比较；保护会拒绝遗留目录、缺失角色、非规范名称、绝对路径、格式错误的 manifest 与平台专用分隔符。
+每个已记录 Session 目录携带封闭的 `snapshot.yml` manifest，以及规范 parent 与连续 child 角色。parent 文件名是 `session[.vN].jsonl`；child 是 `session.<ordinal>[.vN].jsonl`；v0 省略 `.v0`，正版本使用小写 `.vN`，且每个文件名与其 header 一致。一个角色可以保留旧 generation，但 harness 会选择数值最高的一项。拥有 fixture 的 manifest 可以声明 `sessionFormat.version` 与一个或多个封闭 `coverage` 名称，把该历史 generation 保留为显式迁移 fixture。未声明时，record 与 refresh 写入当前 generation；replay 也按[语料策略](../../../snapshots/AGENTS.md)接受保留的 V3 基线。manifest 还会指名场景、随附 profile、组合／header 类别、录制来源，以及已完成 Session 无法重建的 replay、平台、权限、环境、workspace 或输入事实。存储保护检查每个选定 parent 与 child 角色的工具结果和可移植路径。提示词／schema 擦除、消息身份及提示词先于请求的顺序检查适用于当前 generation；保留的前代维持其历史表示。适配器注册预期输出、Session 日志与可选 `workspace.expected/` 比较；保护会拒绝遗留目录、缺失角色、非规范名称、绝对路径、格式错误的 manifest 与平台专用分隔符。
 
-`normalizeSessionSnapshot` 在规范化路径并擦除系统提示文本与工具 schema 后，会保留完整 Session header 与事件 payload，但从已提交 fixture 中省略顶层 `seq`/`time` envelope；它还会规范化嵌入式 stream clock 与历史 packed-row 的 `seq0`/`time0` envelope 与 catalog child 创建时钟。事件顺序与来源事件引用保持不变。Replay 只在内存中合成顶层 envelope，而运行时持久化仍写入完整日志。多 Session 比较会先通过严格的构建期静态 Session 格式目录校验预期日志与收集日志，再进行身份脱敏与规范化；来源文件名不能改变格式校验。保留的历史 replay 输入不是原生当前格式 writer 输出的比较基准：结构迁移保留请求含义，但可以产生不同的事件布局。归一化保留意外的 request-header 字段（包括 `system`），使回归保持可见。无版本的协议适配器单元测试 fixture 不属于已发布 Session 格式语料。[当前写入器格式](../../../docs/session-format-status.zh.md)的 fixture 每个事件占一行；保留的 v0/v1 fixture 可以使用规范 packed row。[临时仓库迁移器](../../../scripts/migrate-packed-session-fixtures.ts)（`pnpm run migrate:packed-session-fixtures`）会改写更旧的历史布局，由其[移除提案](../../../.agents/notes/proposed/process/2026-07-26-remove-packed-session-fixture-migrator.zh.md)负责删除该迁移器。
+`normalizeSessionSnapshot` 在规范化路径并擦除系统提示文本与工具 schema 后，会保留完整 Session header 与事件 payload，但从已提交 fixture 中省略顶层 `seq`/`time` envelope；它还会规范化嵌入式 stream clock 与历史 packed-row 的 `seq0`/`time0` envelope 与 catalog child 创建时钟。事件顺序与来源事件引用的顺序保持不变。录制与刷新会将顶层 `sourceEventSeqs` 以展开数组的形式写入 fixture。Replay 只在内存中合成顶层 envelope，而运行时持久化仍写入完整日志。多 Session 比较会先通过严格的构建期静态 Session 格式目录校验预期日志与收集日志，再进行身份脱敏与规范化；来源文件名不能改变格式校验。保留的历史 replay 输入不是原生当前格式 writer 输出的比较基准：结构迁移保留请求含义，但可以产生不同的事件布局。归一化保留意外的 request-header 字段（包括 `system`），使回归保持可见。无版本的协议适配器单元测试 fixture 不属于已发布 Session 格式语料。[当前写入器格式](../../../docs/session-format-status.zh.md)的 fixture 每个事件占一行；保留的 v0/v1 fixture 可以使用规范 packed row。[临时仓库迁移器](../../../scripts/migrate-packed-session-fixtures.ts)（`pnpm run migrate:packed-session-fixtures`）会改写更旧的历史布局，由其[移除提案](../../../.agents/notes/proposed/process/2026-07-26-remove-packed-session-fixture-migrator.zh.md)负责删除该迁移器。
 
 spill 场景通过真实本地提供方保存到私有临时根目录。fixture 适配器提供固定长度的逻辑定位符，并仅将本次运行已保存的定位符映射回实际文件以供检索，在不写入共享逻辑路径的情况下保留预览预算。已知的快照 spill 路径会规范化为稳定的定位符 token，包括 JSON 省略通知中带引号、使用 JSON 转义 Windows 分隔符的路径。刷新提取会保留匹配路径的序列化写法，以便进行字面替换。规范化只改变定位符：保存字节数与省略计数仍作为比较证据。
 
-保留历史输入的场景保持规范 Session 文件不变，并继续选择它们进行回放；固定历史版本的目录中没有更新的规范同角色文件。其精确的规范化原生当前格式输出单独记录在父会话的 `writer.expected.jsonl` 和子会话的 `writer.<ordinal>.expected.jsonl` 中；这些是输出比较基准，而非 replay 代际。保留历史输入的 SDK 场景使用 `notifications.current.expected.jsonl` 记录当前协议输出。比较既不将当前事件反向投影为历史格式，也不剥除结构差异。独立迁移测试验证正式转换，而不把原生 writer 布局当作其预期事件序列。
+保留历史输入的场景保持规范 Session 文件不变，并继续选择它们进行回放；固定历史版本的目录中没有更新的规范同角色文件。其精确的规范化原生 writer 输出单独记录在父会话的 `writer.expected.jsonl` 和子会话的 `writer.<ordinal>.expected.jsonl` 中；这些是输出比较基准，而非 replay 代际。输出比较基准可以保留较旧的受支持代际：比较通过严格 catalog 恢复它们，而收集的日志必须使用当前检出版本的 writer。新 writer 输出的 golden 比较选择 `nativeWriterOutput`，仅在严格恢复后，将版本限定为各输入原始 writer 代际的 delivery 标记转换为 token。其他 delivery 代际与 captured-source 字段保持数值；源文件与已迁移产物的比较默认保留精确代际。record 与 refresh 从不存储这些比较 token。保留历史输入的 SDK 场景使用 `notifications.current.expected.jsonl` 记录当前协议输出。比较既不将当前事件反向投影为历史格式，也不剥除结构差异。独立迁移测试验证正式转换，而不把原生 writer 布局当作其预期事件序列。
+
+Headless/ACP 与 SDK 适配器在规范化之前，将原始目录中的子创建时间与采集到的子 header 比较。刷新会在每条匹配的目录记录中保留选定的子 header 时间，包括继承副本，防止保留的 header 时钟与新写入的目录时钟分歧。已提交的历史不一致数据保持不变，作为迁移拒绝证据；将其时钟规范化不能证明迁移成功。
 
 ### 录制、回放与刷新
 

package/lib/index.js

@@ -1163,6 +1163,7 @@ const SYSTEM = "{{system}}";
 const TOOLS = "{{tools}}";
 const EVENT_TIME = "{{eventTime}}";
 const EVENT_OMITTED_BYTES = "{{eventOmittedBytes}}";
+const SOURCE_SESSION_FORMAT = "{{sourceSessionFormatVersion}}";
 const PACKED_CHUNK_ROW_TYPES$1 = new Set([
 	"text-chunks",
 	"reasoning-chunks",
@@ -1448,32 +1449,43 @@ function normalizeSessionSnapshot(rawLog, ctx, options = {}) {
 }
 /**
 * Normalize one scenario's primary and child logs with shared typed identity redaction.
+* Native-writer comparison strictly restores each input before tokenizing its own delivery generation.
 * @param rawLogs - primary-first persisted or projected session JSONL.
 * @param ctx - generated cwd spellings and other volatile run facts.
-* @param options - separator controls; relationship-preserving identity mode is mandatory.
-* @returns normalized session fixtures in input order.
+* @param options - separator and native-writer comparison controls; identity relationships are preserved.
+* @returns comparison-only Session records in input order; not persistence or fixture write-back input.
 */
 function normalizeSessionSnapshots(rawLogs, ctx, options = {}) {
-	return redactSessionSnapshotIds(rawLogs.map((log) => hasSessionFormatVersion(log) ? prepareSessionSnapshotFixtureForComparison(log) : log).map(normalizeSessionFormatMetadata)).map((log) => projectSessionSnapshot(scrubSessionSnapshot(normalizeSessionLog(log, {
+	const { nativeWriterOutput, ...normalizeOptions } = options;
+	return redactSessionSnapshotIds(rawLogs.map((log) => {
+		if (!hasSessionFormatVersion(log)) return normalizeSessionFormatMetadata(log);
+		return normalizeSessionFormatMetadata(prepareSessionSnapshotFixtureForComparison(log), nativeWriterOutput ? sessionHeaderVersion(log, "source Session snapshot") : void 0);
+	})).map((log) => projectSessionSnapshot(scrubSessionSnapshot(normalizeSessionLog(log, {
 		...ctx,
 		sessionIds: []
 	}, {
-		...options,
+		...normalizeOptions,
 		identityMode: "preserve"
 	}))));
 }
 /**
 * Omit the artifact header generation after official migration for comparison.
-* Delivery and captured-source generations retain their opaque recorded values.
+* An explicit source version tokenizes only delivery markers for that original input generation.
+* Other delivery generations and every captured-source generation retain their recorded values.
 * @param rawLog - Session records or events as compact JSON lines.
-* @returns the same records with only the Session header version omitted.
+* @param sourceVersion - original generation of strictly validated native writer output; otherwise omit.
+* @returns comparison-only records with the Session header version omitted and native delivery qualifiers tokenized.
 */
-function normalizeSessionFormatMetadata(rawLog) {
+function normalizeSessionFormatMetadata(rawLog, sourceVersion) {
 	return rawLog.split("\n").map((line) => {
 		if (line.trim().length === 0) return line;
 		const record = JSON.parse(line);
-		if (record.type !== "session" || !Object.hasOwn(record, "version")) return line;
-		delete record.version;
+		if (record.type === "session" && Object.hasOwn(record, "version")) delete record.version;
+		else if (sourceVersion !== void 0 && record.type === "session-log-deepseek/delivery-accepted") {
+			const data = record.data;
+			if (data?.sessionFormatVersion !== sourceVersion) return line;
+			data.sessionFormatVersion = SOURCE_SESSION_FORMAT;
+		} else return line;
 		return JSON.stringify(record);
 	}).join("\n");
 }
@@ -1531,7 +1543,8 @@ function scrubModelRequestBulk(rawLog) {
 /**
 * Project a persisted session log while tokenizing prompt text and schema
 * bulk. Each non-empty line is parsed at most once; the session header stays
-* byte-identical. Body records omit their persistence-only envelopes.
+* byte-identical. Body records omit their persistence-only envelopes and expand
+* source-event ranges without changing reference order.
 *
 * @param rawLog - persisted or already-projected session JSONL.
 * @returns committed snapshot JSONL with prompt text and tool schemas tokenized.
@@ -1547,6 +1560,7 @@ function scrubSessionSnapshot(rawLog) {
 			return line;
 		}
 		omitFixtureEnvelope(record);
+		if (Object.hasOwn(record, "sourceEventSeqs")) record.sourceEventSeqs = decodeSeqRanges(record.sourceEventSeqs);
 		normalizeFeedbackClocks(record);
 		return JSON.stringify(record);
 	}).join("\n");
@@ -2183,6 +2197,7 @@ function surfaceEventMessage(record) {
 			message = data;
 			break;
 		case "system/message":
+		case "developer/message":
 		case "assistant/message":
 		case "tool/result":
 			message = data.message;
@@ -2352,6 +2367,28 @@ function refreshFixtureReplacements(logs, fixtures) {
 	}
 	return replacements;
 }
+/**
+* Check raw parent/child clocks before normalization, or preserve their equality during refresh.
+* @param logs - one scenario's parent and child logs with shared Session ids.
+* @param policy - validate live output, or align refreshed catalogs to the retained child headers.
+* @returns logs with only conflicting catalog creation times replaced under preserve-headers.
+*/
+function reconcileCatalogCreationTimes(logs, policy) {
+	const headers = new Map(logs.map((log) => {
+		const header = parseJsonlRecords(log)[0];
+		return [header?.["id"], header];
+	}));
+	return logs.map((log) => log.split("\n").map((line) => {
+		if (line.length === 0) return line;
+		const record = JSON.parse(line);
+		if (record.type !== "subagent/catalog" || !isRecord(record.data)) return line;
+		const child = headers.get(record.data.childId);
+		if (child === void 0 || record.data.childCreatedAt === child.createdAt) return line;
+		if (policy === "validate") throw new Error(`catalog child ${String(record.data.childId)} creation time ${String(record.data.childCreatedAt)} disagrees with child header ${String(child.createdAt)}`);
+		record.data.childCreatedAt = child.createdAt;
+		return JSON.stringify(record);
+	}).join("\n"));
+}
 function preserveFixtureVolatiles(record, existing) {
 	if (existing === void 0 || existing.type !== record.type) return;
 	if (record.type === "session") {
@@ -2612,6 +2649,7 @@ function defineAcpSnapshotSuite(options) {
 				...scenario.workspaceParent !== void 0 ? { workspaceParent: scenario.workspaceParent } : {},
 				...scenario.configPath !== void 0 ? { configPath: scenario.configPath } : {}
 			});
+			reconcileCatalogCreationTimes(result.sessionLogs.map((log) => log.content), "validate");
 			for (const log of result.sessionLogs) expect(unknownToolCallIds(log.content), `session ${log.id}: snapshot scenarios must not accept UNKNOWN_TOOL`).toEqual([]);
 			const ctx = {
 				sessionIds: [...result.sessionId !== void 0 ? [result.sessionId] : [], ...result.sessionLogs.map((l) => l.id)],
@@ -2631,7 +2669,7 @@ function defineAcpSnapshotSuite(options) {
 					return readFile(join(dir, file), "utf8");
 				}));
 				const refreshReplacements = REFRESHING ? refreshFixtureReplacements(result.sessionLogs, existingFixtures) : [];
-				const outputFixtures = redactSessionSnapshotIds(stabilizeFixtureMessageIds(REFRESHING ? result.sessionLogs.map((log, index) => scrubSessionSnapshot(portableFixture(stabilizeRefreshLog(log.content, existingFixtures[index], refreshReplacements, ctx)))) : result.sessionLogs.map((log) => scrubSessionSnapshot(portableFixture(log.content))), existingFixtures));
+				const outputFixtures = redactSessionSnapshotIds(stabilizeFixtureMessageIds(reconcileCatalogCreationTimes(REFRESHING ? result.sessionLogs.map((log, index) => scrubSessionSnapshot(portableFixture(stabilizeRefreshLog(log.content, existingFixtures[index], refreshReplacements, ctx)))) : result.sessionLogs.map((log) => scrubSessionSnapshot(portableFixture(log.content))), "preserve-headers"), existingFixtures));
 				await Promise.all(outputFixtures.map((fixture, index) => writeFile(join(dir, outputFixtureFiles[index]), fixture)));
 				fixtureFiles = outputFixtureFiles;
 				if (scenario.pinsHeader === true) {
@@ -2678,8 +2716,8 @@ function defineAcpSnapshotSuite(options) {
 					sessionIds: fixtureContexts.flatMap((context) => context.sessionIds),
 					cwd: fixtureContexts[0].cwd
 				};
-				const actualSnapshots = normalizeSessionSnapshots(harvested, ctx);
-				const expectedSnapshots = normalizeSessionSnapshots(fixtures, fixtureCtx);
+				const actualSnapshots = normalizeSessionSnapshots(harvested, ctx, { nativeWriterOutput: true });
+				const expectedSnapshots = normalizeSessionSnapshots(fixtures, fixtureCtx, { nativeWriterOutput: true });
 				for (const [index, actual] of actualSnapshots.entries()) expect(actual, `${fixtureFiles[index]} mismatch`).toEqual(expectedSnapshots[index]);
 			}
 			/* v8 ignore next -- construction guarantees the pin exists; a miss would fail the one-header assertion loudly. */
@@ -2848,4 +2886,4 @@ function defineAcpSnapshotSuite(options) {
 	});
 }
 //#endregion
-export { EMPTY_WORKSPACE_MARKER, assertPersistedSessionVersion, assertSessionFixtureVersion, captureExpectedWorkspaceSnapshot, captureWorkspaceSnapshot, defineAcpSnapshotSuite, extractSnapshotSpillPaths, fixtureContext, formatSystemPromptSnapshot, formatToolSchemasSnapshot, headerChangeCount, latestPersistedSessionPaths, launchAcpTestAgent, materializeProfilePatch, normalizeSessionFormatMetadata, normalizeSessionLog, normalizeSessionSnapshot, normalizeSessionSnapshots, normalizeStdout, normalizedHeaders, normalizedSystemPrompts, normalizedToolSchemas, parsePersistedSessionFilename, parseSessionFixtureName, parseSnapshotManifest, parseSystemPromptSnapshot, parseToolSchemasSnapshot, persistedSessionFilename, redactSessionSnapshotIds, refreshFixtureReplacements, restorePinnedToolSchemas, runScenario, scrubModelRequestBulk, scrubSessionSnapshot, scrubSystemPrompts, scrubToolSchemas, sessionFixtureFiles, sessionFixtureName, sessionFixtureNames, sessionHeaderVersion, snapshotSpillRoot, stabilizeFixtureMessageIds, stabilizeRefreshLog, systemPromptPrecedesRequests, tokenizeSessionFixtureCwd, writerSnapshotName, writesCurrentSessionFixtures };
+export { EMPTY_WORKSPACE_MARKER, assertPersistedSessionVersion, assertSessionFixtureVersion, captureExpectedWorkspaceSnapshot, captureWorkspaceSnapshot, defineAcpSnapshotSuite, extractSnapshotSpillPaths, fixtureContext, formatSystemPromptSnapshot, formatToolSchemasSnapshot, headerChangeCount, latestPersistedSessionPaths, launchAcpTestAgent, materializeProfilePatch, normalizeSessionFormatMetadata, normalizeSessionLog, normalizeSessionSnapshot, normalizeSessionSnapshots, normalizeStdout, normalizedHeaders, normalizedSystemPrompts, normalizedToolSchemas, parsePersistedSessionFilename, parseSessionFixtureName, parseSnapshotManifest, parseSystemPromptSnapshot, parseToolSchemasSnapshot, persistedSessionFilename, reconcileCatalogCreationTimes, redactSessionSnapshotIds, refreshFixtureReplacements, restorePinnedToolSchemas, runScenario, scrubModelRequestBulk, scrubSessionSnapshot, scrubSystemPrompts, scrubToolSchemas, sessionFixtureFiles, sessionFixtureName, sessionFixtureNames, sessionHeaderVersion, snapshotSpillRoot, stabilizeFixtureMessageIds, stabilizeRefreshLog, systemPromptPrecedesRequests, tokenizeSessionFixtureCwd, writerSnapshotName, writesCurrentSessionFixtures };

package/lib/types/index.d.ts

@@ -22,6 +22,6 @@ export { launchAcpTestAgent, materializeProfilePatch, type AcpTestLaunchOptions,
 export { extractSnapshotSpillPaths, normalizeSessionFormatMetadata, normalizeSessionLog, normalizeSessionSnapshot, normalizeSessionSnapshots, normalizeStdout, scrubModelRequestBulk, scrubSessionSnapshot, scrubSystemPrompts, scrubToolSchemas, tokenizeSessionFixtureCwd, type CwdPathMode, type NormalizeContext, type NormalizeOptions, } from './normalize.ts';
 export { parseSnapshotManifest, writesCurrentSessionFixtures, type SnapshotHeaderManifest, type SnapshotInputAttachment, type SnapshotInputManifest, type SnapshotManifest, type SnapshotPermission, type SnapshotPlatform, type SnapshotProfile, type SnapshotRecording, type SnapshotReplayManifest, type SnapshotSessionReference, type SnapshotSessionFormatCoverage, type SnapshotSessionFormatManifest, type SnapshotSessionWriteMode, type SnapshotWorkspaceManifest, } from './manifest.ts';
 export { assertPersistedSessionVersion, assertSessionFixtureVersion, latestPersistedSessionPaths, parsePersistedSessionFilename, parseSessionFixtureName, persistedSessionFilename, sessionFixtureFiles, sessionFixtureName, sessionFixtureNames, sessionHeaderVersion, writerSnapshotName, type PersistedSessionFile, type SessionFixtureFile, } from './session-files.ts';
-export { formatSystemPromptSnapshot, formatToolSchemasSnapshot, fixtureContext, headerChangeCount, defineAcpSnapshotSuite, normalizedHeaders, normalizedSystemPrompts, normalizedToolSchemas, parseSystemPromptSnapshot, parseToolSchemasSnapshot, refreshFixtureReplacements, restorePinnedToolSchemas, stabilizeFixtureMessageIds, stabilizeRefreshLog, systemPromptPrecedesRequests, type Scenario, type SnapshotSuiteOptions, } from './suite.ts';
+export { formatSystemPromptSnapshot, formatToolSchemasSnapshot, fixtureContext, headerChangeCount, defineAcpSnapshotSuite, normalizedHeaders, normalizedSystemPrompts, normalizedToolSchemas, parseSystemPromptSnapshot, parseToolSchemasSnapshot, refreshFixtureReplacements, reconcileCatalogCreationTimes, restorePinnedToolSchemas, stabilizeFixtureMessageIds, stabilizeRefreshLog, systemPromptPrecedesRequests, type Scenario, type SnapshotSuiteOptions, } from './suite.ts';
 export { captureExpectedWorkspaceSnapshot, captureWorkspaceSnapshot, EMPTY_WORKSPACE_MARKER, type CaptureWorkspaceSnapshotOptions, type WorkspaceBinaryFileSnapshot, type WorkspaceEmptyDirectorySnapshot, type WorkspaceSnapshotEntry, type WorkspaceSymlinkSnapshot, type WorkspaceTextFileSnapshot, } from './workspace.ts';
 //# sourceMappingURL=index.d.ts.map

package/lib/types/normalize.d.ts

@@ -30,6 +30,11 @@ export interface NormalizeOptions {
     /** Keep already-redacted typed ids and arbitrary UUID-like prose unchanged. */
     identityMode?: 'legacy' | 'preserve';
 }
+/** Comparison controls for complete primary and child Session logs. */
+export interface SessionSnapshotComparisonOptions extends Omit<NormalizeOptions, 'identityMode'> {
+    /** Inputs are captured native writer output, rather than source-versus-migrated-artifact comparisons. */
+    nativeWriterOutput?: true;
+}
 /**
  * Store one generated workspace as `{{cwd}}` while retaining every other
  * session value. The caller opts in only for workspaces created under a
@@ -85,19 +90,22 @@ export declare function normalizeSessionLog(rawLog: string, ctx: NormalizeContex
 export declare function normalizeSessionSnapshot(rawLog: string, ctx: NormalizeContext, options?: NormalizeOptions): string;
 /**
  * Normalize one scenario's primary and child logs with shared typed identity redaction.
+ * Native-writer comparison strictly restores each input before tokenizing its own delivery generation.
  * @param rawLogs - primary-first persisted or projected session JSONL.
  * @param ctx - generated cwd spellings and other volatile run facts.
- * @param options - separator controls; relationship-preserving identity mode is mandatory.
- * @returns normalized session fixtures in input order.
+ * @param options - separator and native-writer comparison controls; identity relationships are preserved.
+ * @returns comparison-only Session records in input order; not persistence or fixture write-back input.
  */
-export declare function normalizeSessionSnapshots(rawLogs: readonly string[], ctx: NormalizeContext, options?: Omit<NormalizeOptions, 'identityMode'>): string[];
+export declare function normalizeSessionSnapshots(rawLogs: readonly string[], ctx: NormalizeContext, options?: SessionSnapshotComparisonOptions): string[];
 /**
  * Omit the artifact header generation after official migration for comparison.
- * Delivery and captured-source generations retain their opaque recorded values.
+ * An explicit source version tokenizes only delivery markers for that original input generation.
+ * Other delivery generations and every captured-source generation retain their recorded values.
  * @param rawLog - Session records or events as compact JSON lines.
- * @returns the same records with only the Session header version omitted.
+ * @param sourceVersion - original generation of strictly validated native writer output; otherwise omit.
+ * @returns comparison-only records with the Session header version omitted and native delivery qualifiers tokenized.
  */
-export declare function normalizeSessionFormatMetadata(rawLog: string): string;
+export declare function normalizeSessionFormatMetadata(rawLog: string, sourceVersion?: number): string;
 /**
  * Replace the rendered prompt text of every `system/message` event with the
  * `{{system}}` token. The text block keeps its position and type, so the
@@ -135,7 +143,8 @@ export declare function scrubModelRequestBulk(rawLog: string): string;
 /**
  * Project a persisted session log while tokenizing prompt text and schema
  * bulk. Each non-empty line is parsed at most once; the session header stays
- * byte-identical. Body records omit their persistence-only envelopes.
+ * byte-identical. Body records omit their persistence-only envelopes and expand
+ * source-event ranges without changing reference order.
  *
  * @param rawLog - persisted or already-projected session JSONL.
  * @returns committed snapshot JSONL with prompt text and tool schemas tokenized.

package/lib/types/suite.d.ts

@@ -386,6 +386,13 @@ export declare function unknownToolCallIds(rawLog: string): string[];
  * @returns Literal replacements from fresh values to the fixture's existing values.
  */
 export declare function refreshFixtureReplacements(logs: HarvestedLog[], fixtures: string[]): FixtureReplacement[];
+/**
+ * Check raw parent/child clocks before normalization, or preserve their equality during refresh.
+ * @param logs - one scenario's parent and child logs with shared Session ids.
+ * @param policy - validate live output, or align refreshed catalogs to the retained child headers.
+ * @returns logs with only conflicting catalog creation times replaced under preserve-headers.
+ */
+export declare function reconcileCatalogCreationTimes(logs: readonly string[], policy: 'validate' | 'preserve-headers'): string[];
 /**
  * Rewrite a fresh replay-produced log so repeated refreshes do not churn
  * volatile fixture fields. Meaningful event payloads come from `fresh`; the

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-session-snapshot",
   "description": "Session-log snapshot core with an ACP protocol adapter, expected-output normalization, and fixture invariants",
-  "version": "0.1.6-alpha.2",
+  "version": "0.1.7-alpha.1",
   "publishConfig": {
     "access": "public"
   },
@@ -30,29 +30,29 @@
     "@agentclientprotocol/sdk": "1.4.0",
     "js-yaml": "^4.2.0",
     "vitest": "^4.1.8",
-    "@deepseek-ai/cordis-plugin-include": "1.0.7",
-    "@deepseek-ai/dsh-llm-replay": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-loader-smoke": "0.1.6-alpha.2",
-    "@deepseek-ai/dsh-session-format": "^0.1.6-alpha.2"
+    "@deepseek-ai/cordis-plugin-include": "1.0.8",
+    "@deepseek-ai/dsh-llm-replay": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-loader-smoke": "0.1.7-alpha.1",
+    "@deepseek-ai/dsh-session-format": "^0.1.7-alpha.1"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-session": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-http-proxy": "^0.1.6-alpha.2"
+    "@deepseek-ai/cordis": "^4.0.3",
+    "@deepseek-ai/dsh-session": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-http-proxy": "^0.1.7-alpha.1"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-agent": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-agent-loop": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-compaction": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-llm": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-sandbox": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-session": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-subagent": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-tools": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-user-questions": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-http-proxy": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-sandbox-policy": "^0.1.6-alpha.2"
+    "@deepseek-ai/cordis": "^4.0.3",
+    "@deepseek-ai/dsh-agent": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-compaction": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-agent-loop": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-sandbox": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-session": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-subagent": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-tools": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-user-questions": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-http-proxy": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-llm": "^0.1.7-alpha.1"
   }
 }