@deepseek-ai/dsh-llm-replay 0.1.2-alpha.5 → 0.1.3-alpha.2

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/test-support/llm-replay/README.md
-README.md: c0643bf6823e96cf3663f8299d0f5645d7974011
-README.zh.md: 1c2fe3393691b4988678497aa5948957f678c80b
+README.md: e8a257c2ee9f95f1e7d20197e6db67b2b4c7b45c
+README.zh.md: 5d085959982bcaa090a893089c0295426141bed2

package/README.md

@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-`dsh-llm-replay` makes snapshot tests run without an API key: it installs a replay LLM adapter that serves model streams reconstructed from a recorded session JSONL fixture, so a test boots the real agent against a fixed transcript. The fixture is a projection of the persisted session log — `assistant/chunk` events group into per-call chunk sequences, and an explicitly marked local compaction call replays as one canonical stream. A `replay.override.json` sidecar covers what a log cannot reconstruct: a throw before any chunk, a cancel/hang, or an injected retry. Live sessions bind to recorded scripts by first-call order, so parent-and-subagent scenarios each get their own script. It is the model source behind the ACP and headless snapshot suites and the Web browser e2e lane.
+`dsh-llm-replay` makes snapshot tests run without an API key: it installs a replay LLM adapter that serves model streams reconstructed from a recorded session JSONL fixture, so a test boots the real agent against a fixed transcript. The fixture is a projection of the persisted session log — each `assistant/message` or `assistant/attempt` embeds one model-call stream, and an explicitly marked local compaction call replays as one canonical stream. A `replay.override.json` sidecar covers what a settlement cannot reconstruct: a throw before any chunk, a cancel/hang, or an injected retry. Live sessions bind to recorded scripts by first-call order, so parent-and-subagent scenarios each get their own script. It is the model source behind the ACP and headless snapshot suites and the Web browser e2e lane.
 
 ## Table of Contents
 
@@ -55,7 +55,7 @@ With `providers` configured, the plugin registers a replay-only adapter whose ca
 
 | Field | Default | Meaning |
 |---|---|---|
-| `file` | `$DSH_SNAPSHOT_FILE` | Path to the primary (parent) `session.jsonl` fixture; required (config or env) |
+| `file` | `$DSH_SNAPSHOT_FILE` | Path to the selected primary fixture: `session.jsonl` for v0 or `session.vN.jsonl` for a positive generation; required (config or env) |
 | `overrideFile` | `$DSH_SNAPSHOT_OVERRIDE` | Optional `ReplayOverrideDoc` sidecar for the primary session |
 | `childFiles` | `$DSH_SNAPSHOT_CHILD_FILES` | Recorded subagent child-session logs for a nested scenario |
 | `providers` | — | Optional replay-only provider and model catalog; a model may declare `contextWindow`, text/image modalities, and positive `imageRequestTokens` when image-capable; invalid values fail at load and routes never perform provider I/O |
@@ -65,17 +65,17 @@ The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-a
 
 ### How the fixture works
 
-The fixture is a projection of a persisted session log (`<scenario>/session.jsonl`) produced by running the real agent once — this plugin does not record. It keeps the header and every event payload but omits body `seq`/`time` envelopes (`seq0`/`time0` for packed rows); replay restores contiguous synthetic envelopes while parsing, and one file cannot mix projected and complete body rows. Runtime persistence continues to write complete logs. Replay derives each model call's chunk sequence from `assistant/chunk` events, so a recorded fixture replays the same logical stream the live model produced. A fixture may carry its `request/header` content tokenized to `{{system}}`/`{{tools}}`; replay is indifferent because derivation reads only the chunk and summary events plus the line-0 session header.
+The fixture is a projection of one selected persisted Session generation produced by running the real agent once — this plugin does not record. The snapshot harness supplies the numerically highest canonical parent path (`<scenario>/session.jsonl` for v0 or `<scenario>/session.vN.jsonl` for a positive generation), and validates filename/header agreement before replay. The fixture keeps the header and every event payload but omits body `seq`/`time` envelopes (`seq0`/`time0` for historical packed rows). Replay supplies contiguous sequences and deterministic timestamps, restores typed values replaced by snapshot tokens, rejects partial or mixed envelopes, decodes the complete physical artifact through the build-static Session format catalog, and migrates historical input in memory before it exposes events or the inherited cut; current input takes direct restoration. For a projected v0 header only, an absent `delegationDepth` denotes `0`. The parser never rewrites or renames the fixture. Runtime persistence continues to write complete logs. Replay expands the compact stream on each current-view `assistant/message` or `assistant/attempt`, so a recorded fixture replays the same logical stream the live model produced. A fixture may carry its `request/header` content tokenized to `{{system}}`/`{{tools}}`; replay materializes validation-only values, while derivation reads only Assistant settlements, marked summary events, and Session metadata. Every replay and comparison fixture must pass the same content-only catalog validation; replay never repairs a refused artifact.
 
 ### Nested agents
 
-A scenario where a parent agent delegates to in-process subagents records one log per session: the parent (`session.jsonl`) plus one per child (`session.1.jsonl`, …). Live session ids are freshly random each run, so replay binds each live session to a recorded script by first-call order: the first live session to make a model call claims the first script, the next new session the next, and so on, with each session advancing its own cursor. More distinct live sessions than recorded scripts fails loud.
+A scenario where a parent agent delegates to in-process subagents records one role per Session: parent `session[.vN].jsonl`, then contiguous children `session.<ordinal>[.vN].jsonl`. The snapshot harness supplies only the highest generation of each role. Live Session ids are freshly random each run, so replay binds each live Session to a recorded script by first-call order: the first live Session to make a model call claims the parent script, the next new Session the next child script, and so on, with each Session advancing its own cursor. More distinct live Sessions than recorded scripts fails loud.
 
 ### Failure modes and overrides
 
 When replay serves `deepseek-official` with `ctx.deepseekLlmApiExtensions`, it prepares and accepts those fields after selecting a valid script entry and before yielding the first chunk. This mirrors the live adapter's post-2xx commit point, so durable acceptance watermarks and SDK event notifications behave the same in recording and replay. Replay supplies a synthetic `{ messages: [] }` base body: it proves acceptance side effects, not prepared field bytes.
 
-Two failure modes are not reconstructable from `assistant/chunk` alone — a pure throw before any chunk (for example an HTTP 401, where the log holds only a `turn/end {error}`) and a cancel/hang. A scenario that needs those supplies an optional sidecar (`<scenario>/replay.override.json`) that either replaces the derived script with a bare `ReplayEntry[]` or augments it with `{ patches: [{ at, entry }] }`, which keeps every derived call and swaps the named 0-based call indexes; `at` equal to the derived length appends the retry attempt after an injected transient throw. A `throw` entry accepts DeepSeek request extensions when it has prefix chunks; a zero-chunk throw defaults to pre-2xx non-acceptance and may set `accepted: true` for a post-2xx failure. A `hang` entry may name `readyFile`, which replay writes before waiting for cancellation so an external driver can cancel deterministically.
+Two failure modes are not reconstructable from a durable Assistant settlement alone: a pure throw before any chunk has no exception-bearing stream member, and a cancel/hang requires nontermination rather than a replayed finite prefix. A scenario that needs those supplies an optional sidecar (`<scenario>/replay.override.json`) that either replaces the derived script with a bare `ReplayEntry[]` or augments it with `{ patches: [{ at, entry }] }`, which keeps every derived call and swaps the named 0-based call indexes; `at` equal to the derived length appends the retry attempt after an injected transient throw. A `throw` entry accepts DeepSeek request extensions when it has prefix chunks; a zero-chunk throw defaults to pre-2xx non-acceptance and may set `accepted: true` for a post-2xx failure. A `hang` entry may name `readyFile`, which replay writes before waiting for cancellation so an external driver can cancel deterministically.
 
 ### What can go wrong
 
@@ -95,13 +95,16 @@ This section explains the design of the replay plugin; the observable behavior i
 
 ### Design
 
-Replay is built on one idea: the projected session log is the fixture. `deriveReplayScript` parses the JSONL header (for `id`/`createdAt` ordering facts) and splits `assistant/chunk` events at every `finish` chunk, keyed by `(turn, step)`, so each recorded `stream()` call becomes one `chunks` entry; an assistant group without a `finish` chunk is the fingerprint of a thrown `stream()` and must be expressed through an override sidecar. A `compaction/summary` carrying `llmStreamCall: true` and a complete `rawOutput` replays as one canonical successful stream at that event's position. Scripted strings may embed `{{fromRequest:<regex>}}`; at stream time each placeholder resolves against the live request's string leaves, taking the pattern's last match and its first capture group (or the whole match) in place.
+Replay treats the selected projected Session generation as the fixture. One parser completes projected envelopes, validates and migrates the whole artifact through `sessionFormatCatalog`, and returns the current header, inherited cut, and event list as one result. `deriveReplayScript` expands each `assistant/message` or `assistant/attempt` stream in log order, so each durable settlement becomes one `chunks` entry; a non-empty stream without a `finish` chunk is the fingerprint of a thrown `stream()` and must be expressed through an override sidecar. A `compaction/summary` carrying `llmStreamCall: true` and a complete `rawOutput` replays as one canonical successful stream at that event's position. Scripted strings may embed `{{fromRequest:<regex>}}`; at stream time each placeholder resolves against the live request's string leaves, taking the pattern's last match and its first capture group (or the whole match) in place.
+
+The committed-corpus test discovers every versioned `session*.jsonl` under `snapshots/`, `packages/`, and `scripts/snapshots/python-sdk-single-exe/`. Every artifact must restore to the current view through the real catalog. Any refusal fails with the artifact path, so the fixture owner must correct the invalid relationship before replay or comparison.
 
 ### Source map
 
 | File | Role |
 |---|---|
 | [`src/index.ts`](src/index.ts) | Types, fixture derivation, override validation, placeholder resolution, session binding, `installLlmReplay`, and the plugin export |
+| [`tests/session-format-corpus.spec.ts`](tests/session-format-corpus.spec.ts) | Complete committed-generation restoration burn-in; every refusal is a failure |
 | — | No runtime invariant companion is published; this test-only adapter consumes a fixed replay script; its stream grammar is checked by the LLM companion and fixture derivation tests. |
 
 ### Binding and stream flow

package/README.zh.md

@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-`dsh-llm-replay` 让快照测试无需 API 密钥即可运行：它安装一个回放 LLM（大语言模型）适配器，从已记录的会话 JSONL fixture（测试前置数据）重建模型流，使测试针对固定 transcript（文本记录）启动真实 agent（智能体）。fixture 是持久化会话日志的投影——`assistant/chunk` 事件按调用分组为分片序列，显式标记的本地压缩（compaction）调用回放为一条规范流。`replay.override.json` 伴随文件覆盖日志无法重建的情况：任何分片之前就抛出、取消/挂起，或注入重试。实时会话按首次调用顺序绑定到已记录脚本，因此父会话与 subagent 场景各自获得自己的脚本。它是 ACP 与 headless 快照套件以及 Web 浏览器 e2e 流水线的模型来源。
+`dsh-llm-replay` 让快照测试无需 API 密钥即可运行：它安装一个回放 LLM（大语言模型）适配器，从已记录的会话 JSONL fixture（测试前置数据）重建模型流，使测试针对固定 transcript（文本记录）启动真实 agent（智能体）。fixture 是持久化会话日志的投影——每个 `assistant/message` 或 `assistant/attempt` 都嵌入一次模型调用的 stream，显式标记的本地压缩（compaction）调用则回放为一条规范流。`replay.override.json` 伴随文件覆盖 settlement 无法重建的情况：任何分片之前就抛出、取消/挂起，或注入重试。实时会话按首次调用顺序绑定到已记录脚本，因此父会话与 subagent 场景各自获得自己的脚本。它是 ACP 与 headless 快照套件以及 Web 浏览器 e2e 流水线的模型来源。
 
 ## 目录
 
@@ -55,7 +55,7 @@ kind: "package-reference"
 
 | 字段 | 默认值 | 含义 |
 |---|---|---|
-| `file` | `$DSH_SNAPSHOT_FILE` | 主（父）`session.jsonl` fixture 的路径；必需（配置或 env） |
+| `file` | `$DSH_SNAPSHOT_FILE` | 选定 primary fixture 路径：v0 为 `session.jsonl`，正 generation 为 `session.vN.jsonl`；必需（config 或 env） |
 | `overrideFile` | `$DSH_SNAPSHOT_OVERRIDE` | 主会话的可选 `ReplayOverrideDoc` 伴随文件 |
 | `childFiles` | `$DSH_SNAPSHOT_CHILD_FILES` | 嵌套场景中已记录的 subagent 子会话日志 |
 | `providers` | 无 | 可选的仅回放提供方与模型目录；模型可声明 `contextWindow`、文本／图片模态，以及图片模型使用的正整数 `imageRequestTokens`；非法值会在加载时失败，路由绝不执行提供方 I/O |
@@ -65,17 +65,17 @@ kind: "package-reference"
 
 ### fixture 的工作方式
 
-fixture 是运行一次真实 agent 所产生的持久化会话日志（`<scenario>/session.jsonl`）的投影——本插件不录制。它保留 header 与每个事件 payload，但省略正文的 `seq`/`time` envelope（打包行使用 `seq0`/`time0`）；回放在解析时恢复连续的 synthetic envelope，且同一文件不能混用投影正文行与完整正文行。运行时持久化仍写入完整日志。回放从 `assistant/chunk` 事件派生每次模型调用的分片序列，因此已记录 fixture 会回放与在线模型产生的相同逻辑流。fixture 的 `request/header` 内容可能被标记化为 `{{system}}`/`{{tools}}`；回放不受影响，因为派生只读取分片与摘要事件以及第 0 行的会话 header。
+fixture 是运行一次真实 agent 所产生的一份选定持久化 Session generation 投影，本插件不录制。snapshot harness 会提供数值最高的规范 parent 路径（v0 为 `<scenario>/session.jsonl`，正 generation 为 `<scenario>/session.vN.jsonl`），并在 replay 前校验文件名与 header 一致。fixture 保留 header 与每个事件 payload，但省略正文的 `seq`/`time` envelope（历史 packed row 使用 `seq0`/`time0`）。replay 补充连续序号与确定性 timestamp，恢复被 snapshot token 替换的类型化值，拒绝不完整或混合 envelope，通过构建期静态 Session 格式 catalog 解码完整物理产物，并在公开事件或继承 cut 前于内存中迁移历史输入；当前输入直接 restore。仅对投影 v0 header，缺失的 `delegationDepth` 表示 `0`。parser 从不重写或重命名 fixture。runtime persistence 继续写入完整日志。replay 会展开当前视图中每个 `assistant/message` 或 `assistant/attempt` 的紧凑 stream，因此已记录 fixture 会 replay 与在线模型产生的相同逻辑流。fixture 的 `request/header` 内容可能 token 化为 `{{system}}`/`{{tools}}`；replay 会物化仅用于校验的值，而派生只读取 Assistant settlement、带标记的 summary 事件与 Session metadata。每个 replay 与 comparison fixture 都必须通过同一个只基于内容的 catalog 校验；replay 绝不修复被拒绝的产物。
 
 ### 嵌套 agent
 
-父 agent 委托给进程内 subagent 的场景会按会话记录日志：父会话使用 `session.jsonl`，每个子会话各使用一个（`session.1.jsonl` 等）。实时会话 id 每次运行都会重新随机生成，因此回放按首次调用顺序把每个实时会话绑定到已记录脚本：第一个发起模型调用的实时会话取得第一个脚本，下一个新会话取得下一个，依此类推，每个会话分别推进自己的游标。不同实时会话数量超过已记录脚本数时会明确报错。
+parent agent 委托给进程内 subagent 的场景会为每个 Session 记录一个角色：parent 为 `session[.vN].jsonl`，随后是连续 child `session.<ordinal>[.vN].jsonl`。snapshot harness 只提供每个角色的最高 generation。live Session id 每次运行都会重新随机生成，因此 replay 按首次调用顺序把每个 live Session 绑定到已记录脚本：第一个发起模型调用的 live Session 取得 parent 脚本，下一个新 Session 取得下一条 child 脚本，依此类推，每个 Session 分别推进自己的 cursor。不同 live Session 数量超过已记录脚本数时会明确报错。
 
 ### 失败模式与覆盖
 
 当回放在带有 `ctx.deepseekLlmApiExtensions` 的组合中服务 `deepseek-official` 时，它会在选择有效脚本条目后、产生首个分片前准备并接受这些字段。这与实时适配器的 2xx 后提交点一致，因此持久接受水位与 SDK 事件通知在录制和回放中行为相同。回放提供合成 `{ messages: [] }` 基础 body：它证明接受副作用，而非准备后的字段字节。
 
-有两种失败模式无法仅根据 `assistant/chunk` 重建：在产生任何分片前直接抛出（例如 HTTP 401，此时日志只有 `turn/end {error}`），以及取消或挂起。需要这些行为的场景可提供可选伴随文件（`<scenario>/replay.override.json`）：它用裸 `ReplayEntry[]` 替换派生脚本，或用 `{ patches: [{ at, entry }] }` 增补——保留所有派生调用，只替换指定的从 0 开始计数的调用索引；当 `at` 等于派生长度时，则在注入瞬态异常后的重试位置追加。有前缀分片的 `throw` 条目会接受 DeepSeek 请求扩展；零分片 throw 默认表示 2xx 前未接受，也可设 `accepted: true` 表示 2xx 后无分片失败。`hang` 条目可以指定 `readyFile`，回放在等待取消前写入它，使外部 driver 可以确定性取消。
+有两种失败模式无法仅根据持久 Assistant settlement 重建：任何 chunk 之前的纯 throw 没有携带异常的 stream member，而 cancel/hang 需要的是不终止语义，不能用有限前缀回放。需要这些行为的场景可提供可选伴随文件（`<scenario>/replay.override.json`）：它用裸 `ReplayEntry[]` 替换派生脚本，或用 `{ patches: [{ at, entry }] }` 增补——保留所有派生调用，只替换指定的从 0 开始计数的调用索引；当 `at` 等于派生长度时，则在注入瞬态异常后的重试位置追加。有前缀分片的 `throw` 条目会接受 DeepSeek 请求扩展；零分片 throw 默认表示 2xx 前未接受，也可设 `accepted: true` 表示 2xx 后无分片失败。`hang` 条目可以指定 `readyFile`，回放在等待取消前写入它，使外部 driver 可以确定性取消。
 
 ### 可能出什么问题
 
@@ -95,13 +95,16 @@ fixture 是运行一次真实 agent 所产生的持久化会话日志（`<scenar
 
 ### 设计
 
-回放建立在一个想法之上：投影后的会话日志就是 fixture。`deriveReplayScript` 解析 JSONL header（用于 `id`/`createdAt` 排序事实），并按 `(turn, step)` 键在每次 `finish` 分片处切分 `assistant/chunk` 事件，使每次已记录的 `stream()` 调用成为一条 `chunks` 条目；没有 `finish` 分片的 assistant 分组是 `stream()` 抛出异常的指纹，必须通过 override 伴随文件表达。携带 `llmStreamCall: true` 与完整 `rawOutput` 的 `compaction/summary` 会在该事件位置回放为一条规范成功流。脚本字符串可以内嵌 `{{fromRequest:<regex>}}`；流式输出时每个占位符针对实时请求的字符串叶子解析，取该模式的最后一次匹配，用其第一个捕获组（无捕获组时用整个匹配）原位替换。
+replay 把选定的投影 Session generation 视为 fixture。一个 parser 补全投影 envelope，通过 `sessionFormatCatalog` 校验并迁移完整产物，再以一个结果返回当前 header、继承 cut 与事件列表。`deriveReplayScript` 按日志顺序展开每个 `assistant/message` 或 `assistant/attempt` stream，因此每个持久 settlement 都成为一条 `chunks` entry；非空 stream 缺少 `finish` chunk 是 `stream()` 抛出异常的 fingerprint，必须通过 override sidecar 表达。携带 `llmStreamCall: true` 与完整 `rawOutput` 的 `compaction/summary` 会在该事件位置 replay 为一条规范成功 stream。脚本字符串可以内嵌 `{{fromRequest:<regex>}}`；stream 输出时每个 placeholder 针对 live request 的 string leaf 解析，取该 pattern 的最后一次 match，用其第一个 capture group（无 capture group 时用整个 match）原位替换。
+
+已提交语料测试会发现 `snapshots/`、`packages/` 与 `scripts/snapshots/python-sdk-single-exe/` 下每个带版本的 `session*.jsonl`。每个产物都必须通过真实 catalog 还原为当前视图。任何拒绝都会携带产物路径并使测试失败，因此 fixture owner 必须在 replay 或比较前修正无效关系。
 
 ### 源码地图
 
 | 文件 | 职责 |
 |---|---|
 | [`src/index.ts`](src/index.ts) | 类型、fixture 派生、override 校验、占位符解析、会话绑定、`installLlmReplay` 与插件导出 |
+| [`tests/session-format-corpus.spec.ts`](tests/session-format-corpus.spec.ts) | 完整已提交 generation restore burn-in；任何拒绝都是失败 |
 | — | 不发布运行时不变式伴生入口；流语法由 LLM 伴生插件与派生测试检验。 |
 
 ### 绑定与流式流程

package/lib/index.js

@@ -1,12 +1,13 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { delimiter } from "node:path";
-import { SessionLogOffset, decodeSeqRanges, decodeStorageRecord } from "@deepseek-ai/dsh-session";
-import { LlmAdapter, LlmError, ReasoningEffortId, requestImageHandleText, resolveRetryPolicy } from "@deepseek-ai/dsh-llm";
+import { SESSION_FORMAT_VERSION, SessionLogOffset } from "@deepseek-ai/dsh-session";
+import { SessionFormatUnsupportedMigrationError, sessionFormatCatalog } from "@deepseek-ai/dsh-session-format-catalog";
+import { LlmAdapter, LlmError, ReasoningEffortId, expandAssistantStream, requestImageHandleText, resolveRetryPolicy } from "@deepseek-ai/dsh-llm";
 import { assertNever } from "@deepseek-ai/dsh-util-values";
 //#region lib/types/index.js
 /**
 * Keyless snapshot-test LLM replay. It derives one model-call script per
-* recorded session from `assistant/chunk` events and explicitly marked local
+* recorded session from v2 embedded Assistant streams and explicitly marked local
 * compaction calls, then binds fresh live sessions to parent/child scripts by
 * first-call order. Throw and hang cases require an explicit override because
 * a session log cannot reconstruct them alone.
@@ -17,26 +18,30 @@ const PACKED_CHUNK_ROW_TYPES = new Set([
 	"reasoning-chunks",
 	"tool-call-chunks"
 ]);
+if (sessionFormatCatalog.currentVersion !== SESSION_FORMAT_VERSION) throw new Error(`llm-replay: format catalog v${sessionFormatCatalog.currentVersion} does not match Session v${SESSION_FORMAT_VERSION}`);
 /**
-* Parse a session `.jsonl` buffer into its event list. Line 0 is the session
-* header (a `{type:'session',…}` record), every subsequent non-empty line is a
-* {@link SessionEvent} or a packed chunk row. Packed rows expand back into
-* events, and JSONL storage-form provenance ranges expand back into
-* `number[]`, so physical fixture encodings derive the same script. The
-* header is skipped; malformed lines fail loud.
+* Parse a projected session `.jsonl` buffer into current events. The first
+* non-empty line is the physical header. Body rows either all carry complete
+* persistence envelopes or all omit them; projected rows receive deterministic
+* dense sequences and zero timestamps. The build-static format catalog then
+* decodes and migrates the complete artifact before this function returns.
 * @param text - the raw `.jsonl` file contents.
-* @returns every event after the header, in log order.
+* @returns every migrated current event, in log order.
 */
 function parseSessionLog(text) {
-	const events = [];
-	let nextSeq = SessionLogOffset(0);
-	let headerSkipped = false;
+	return parseSessionFixture(text).events;
+}
+/** Parse, complete, decode, and migrate one projected snapshot artifact without writing its source. */
+function parseSessionFixture(text) {
+	let headerLineNumber;
+	let sourceHeader;
+	let restore;
+	const rowLines = [];
+	const eventLines = [];
+	let bodyKind;
+	let nextSeq = 0;
 	for (const [index, line] of text.split(/\r?\n/).entries()) {
 		if (line.trim().length === 0) continue;
-		if (!headerSkipped) {
-			headerSkipped = true;
-			continue;
-		}
 		let value;
 		try {
 			value = JSON.parse(line);
@@ -44,46 +49,305 @@ function parseSessionLog(text) {
 			throw new Error(`session snapshot line ${index + 1} contains invalid JSON`, { cause: error });
 		}
 		if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error(`session snapshot line ${index + 1} must be a JSON object`);
-		const record = value;
+		const lineNumber = index + 1;
+		const recordValue = value;
+		if (restore === void 0) {
+			headerLineNumber = lineNumber;
+			sourceHeader = recordValue;
+			try {
+				restore = sessionFormatCatalog.createRestore(normalizeProjectedHeader(recordValue), {
+					recovery: "strict",
+					validation: "current"
+				});
+			} catch (error) {
+				throw fixtureFormatError(error, lineNumber, [], []);
+			}
+			continue;
+		}
+		const record = normalizeProjectedRow(recordValue);
 		const packed = PACKED_CHUNK_ROW_TYPES.has(record.type);
 		const seqKey = packed ? "seq0" : "seq";
 		const timeKey = packed ? "time0" : "time";
-		if (!Object.hasOwn(record, seqKey)) record[seqKey] = nextSeq;
-		if (!Object.hasOwn(record, timeKey)) record[timeKey] = 0;
-		let decoded;
+		const hasSeq = Object.hasOwn(record, seqKey);
+		if (hasSeq !== Object.hasOwn(record, timeKey)) throw new Error(`session snapshot line ${lineNumber} must contain both ${seqKey} and ${timeKey}, or neither`);
+		const currentKind = hasSeq ? "complete" : "projected";
+		if (bodyKind !== void 0 && currentKind !== bodyKind) throw new Error(`session snapshot line ${lineNumber} cannot mix projected and complete body rows`);
+		bodyKind = currentKind;
+		if (currentKind === "projected") {
+			record[seqKey] = nextSeq;
+			record[timeKey] = 0;
+		}
+		const cardinality = physicalRowCardinality(record);
+		rowLines.push(lineNumber);
+		eventLines.push(...Array.from({ length: cardinality }, () => lineNumber));
+		nextSeq += cardinality;
 		try {
-			if (Object.hasOwn(record, "sourceEventSeqs")) record.sourceEventSeqs = decodeSeqRanges(record.sourceEventSeqs);
-			decoded = decodeStorageRecord(record);
+			restore.decodeRow(record);
 		} catch (error) {
-			/* v8 ignore next -- decodeStorageRecord only throws Error instances; the String arm satisfies unknown narrowing. */
-			const detail = error instanceof Error ? error.message : String(error);
-			throw new Error(`session snapshot line ${index + 1}: ${detail}`, { cause: error });
+			throw fixtureFormatError(error, headerLineNumber, rowLines, eventLines, rowLines.length - 1);
+		}
+	}
+	if (restore === void 0 || sourceHeader === void 0 || headerLineNumber === void 0) throw new Error("session snapshot must start with a session header");
+	try {
+		return parsedSessionFixture(restore.finish(), sourceHeader);
+	} catch (error) {
+		throw fixtureFormatError(error, headerLineNumber, rowLines, eventLines);
+	}
+}
+/** Materialize the common replay view from a migrated artifact. */
+function parsedSessionFixture(artifact, sourceHeader) {
+	return {
+		id: artifact.header.id,
+		createdAt: artifact.header.createdAt,
+		inheritedEventCount: SessionLogOffset(artifact.inheritedEventCount),
+		events: [...artifact.events],
+		artifact,
+		sourceHeader
+	};
+}
+/**
+* Convert one persisted or projected snapshot fixture to the current physical format in memory for expected-output comparison.
+* Projected cwd tokens remain tokens so the ordinary snapshot normalizer can compare them with a fresh run.
+* @param text - one complete Session fixture.
+* @returns current-format JSONL with complete event envelopes; the input string and source file remain unchanged.
+*/
+function prepareSessionSnapshotFixtureForComparison(text) {
+	return encodeCurrentSessionSnapshotFixture(text, parseSessionFixture(text));
+}
+/** Read one headless or SDK event-notification wrapper. */
+function wrappedSessionEvent(row) {
+	if (row["type"] === "session_event" && typeof row["sessionId"] === "string" && row["event"] !== null && typeof row["event"] === "object" && !Array.isArray(row["event"])) return {
+		sessionId: row["sessionId"],
+		event: row["event"],
+		replace: (event) => ({
+			...row,
+			event
+		})
+	};
+	const params = row["params"];
+	if (row["method"] !== "session.event" || params === null || typeof params !== "object" || Array.isArray(params)) return;
+	const record = params;
+	if (typeof record["sessionId"] !== "string" || record["event"] === null || typeof record["event"] !== "object" || Array.isArray(record["event"])) return;
+	return {
+		sessionId: record["sessionId"],
+		event: record["event"],
+		replace: (event) => ({
+			...row,
+			params: {
+				...record,
+				event
+			}
+		})
+	};
+}
+/** Append one migrated event to the output assigned to its v1 source row. */
+function assignMigratedEvent(assigned, rowIndex, event) {
+	assigned.set(rowIndex, [...assigned.get(rowIndex) ?? [], event]);
+}
+/** Restore fixture tokens materialized only to satisfy released-format validation. */
+function restoreProjectedRequestHeader(target, source) {
+	if (target["type"] !== "request/header" || source["type"] !== "request/header") return target;
+	const targetData = target["data"];
+	const sourceData = source["data"];
+	const targetHeader = targetData["header"];
+	const sourceTools = sourceData["header"]["tools"];
+	if (sourceTools !== "{{tools}}") return target;
+	return {
+		...target,
+		data: {
+			...targetData,
+			header: {
+				...targetHeader,
+				tools: sourceTools
+			}
 		}
-		events.push(...decoded);
-		nextSeq = SessionLogOffset(nextSeq + decoded.length);
+	};
+}
+/** Omit delivery cursors whose numeric value depends on the source Session generation. */
+function normalizeWrappedEventProvenance(event) {
+	if (event["type"] !== "session-log-deepseek/delivery-accepted") return event;
+	const data = event["data"];
+	if (data === null || typeof data !== "object" || Array.isArray(data)) return event;
+	const normalized = { ...data };
+	delete normalized["sessionFormatVersion"];
+	delete normalized["throughSeq"];
+	return {
+		...event,
+		data: normalized
+	};
+}
+/** Migrate one session's contiguous v1 notification tail and align its surviving rows. */
+function migrateWrappedEventGroup(entries) {
+	const first = entries[0];
+	if (!entries.some((entry) => entry.event["type"] === "assistant/chunk")) return /* @__PURE__ */ new Map();
+	const firstSeq = first.event["seq"];
+	if (!Number.isSafeInteger(firstSeq) || firstSeq < 0) throw new Error("session event comparison requires a non-negative first seq");
+	for (const [index, entry] of entries.entries()) if (entry.event["seq"] !== firstSeq + index || typeof entry.event["type"] !== "string") throw new Error(`session event comparison requires a contiguous event tail for ${first.sessionId}`);
+	const prefix = Array.from({ length: firstSeq }, (_, seq) => ({
+		type: "feedback/record",
+		seq,
+		time: 0,
+		data: { text: `comparison prefix ${String(seq)}` }
+	}));
+	const restore = sessionFormatCatalog.createRestore({
+		type: "session",
+		version: 1,
+		id: first.sessionId,
+		createdAt: 0,
+		delegationDepth: 0
+	}, {
+		recovery: "strict",
+		validation: "current"
+	});
+	for (const event of prefix) restore.decodeRow(event);
+	for (const entry of entries) restore.decodeRow(normalizeProjectedRow(entry.event));
+	const migrated = restore.finish().events.slice(prefix.length);
+	const assigned = /* @__PURE__ */ new Map();
+	let migratedIndex = 0;
+	let lastChunkRow;
+	for (const entry of entries) {
+		if (entry.event["type"] === "assistant/chunk") {
+			lastChunkRow = entry.rowIndex;
+			continue;
+		}
+		while (migrated[migratedIndex]?.["type"] === "assistant/attempt") {
+			assignMigratedEvent(assigned, lastChunkRow, migrated[migratedIndex]);
+			migratedIndex += 1;
+		}
+		const next = migrated[migratedIndex];
+		assignMigratedEvent(assigned, entry.rowIndex, restoreProjectedRequestHeader(next, entry.event));
+		migratedIndex += 1;
+	}
+	while (migrated[migratedIndex]?.["type"] === "assistant/attempt") {
+		assignMigratedEvent(assigned, lastChunkRow, migrated[migratedIndex]);
+		migratedIndex += 1;
+	}
+	return assigned;
+}
+/**
+* Project v1 session-event notifications to current settlement cardinality in memory.
+* Non-event protocol rows retain their exact positions, and current v2 input passes through.
+* @param text - headless `session_event` or SDK `session.event` JSONL.
+* @returns comparison JSONL using current Session events without modifying its source file.
+*/
+function prepareSessionEventNotificationsForComparison(text) {
+	const trailingNewline = text.endsWith("\n");
+	const rows = text.split("\n").filter((line) => line.trim().length > 0).map((line, index) => {
+		const value = JSON.parse(line);
+		if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error(`session event comparison line ${String(index + 1)} must be an object`);
+		return value;
+	});
+	const entries = rows.flatMap((row, rowIndex) => {
+		const wrapped = wrappedSessionEvent(row);
+		return wrapped === void 0 ? [] : [{
+			...wrapped,
+			rowIndex
+		}];
+	});
+	const groups = [];
+	for (const entry of entries) {
+		const nextSeq = entry.event["seq"];
+		const group = groups.findLast((candidate) => {
+			const previous = candidate.at(-1);
+			const previousSeq = previous?.event["seq"];
+			return previous?.sessionId === entry.sessionId && Number.isSafeInteger(previousSeq) && Number.isSafeInteger(nextSeq) && nextSeq === previousSeq + 1;
+		});
+		if (group === void 0) groups.push([entry]);
+		else group.push(entry);
 	}
-	return events;
+	const assigned = /* @__PURE__ */ new Map();
+	for (const group of groups) for (const [rowIndex, events] of migrateWrappedEventGroup(group)) assigned.set(rowIndex, events);
+	const output = rows.flatMap((row, rowIndex) => {
+		const wrapped = wrappedSessionEvent(row);
+		if (wrapped === void 0) return [row];
+		const migrated = assigned.get(rowIndex);
+		if (migrated === void 0) return wrapped.event["type"] === "assistant/chunk" ? [] : [wrapped.replace(normalizeWrappedEventProvenance(wrapped.event))];
+		return migrated.map((event) => wrapped.replace(normalizeWrappedEventProvenance(event)));
+	}).map((row) => JSON.stringify(row)).join("\n");
+	return trailingNewline ? `${output}\n` : output;
+}
+/** Encode one migrated fixture while retaining a projected cwd token. */
+function encodeCurrentSessionSnapshotFixture(text, parsed) {
+	const header = { ...sessionFormatCatalog.encodeCurrentHeader(parsed.artifact.header, parsed.artifact.inheritedEventCount) };
+	const sourceCwd = parsed.sourceHeader["cwd"];
+	if (typeof sourceCwd === "string" && /^\{\{cwd\}\}(?:\/|$)/.test(sourceCwd)) header["cwd"] = sourceCwd;
+	const output = [JSON.stringify(header), ...parsed.artifact.events.map((event) => JSON.stringify(sessionFormatCatalog.encodeCurrentEvent(event)))].join("\n");
+	return text.endsWith("\n") ? `${output}\n` : output;
+}
+/** Restore typed request-header values replaced by snapshot sidecar tokens. */
+function normalizeProjectedRow(source) {
+	const record = { ...source };
+	if (record["type"] !== "request/header") return record;
+	const data = record["data"];
+	if (data === null || typeof data !== "object" || Array.isArray(data)) return record;
+	const header = data["header"];
+	if (header === null || typeof header !== "object" || Array.isArray(header)) return record;
+	const tools = header["tools"];
+	let materializedTools;
+	if (tools === "{{tools}}") materializedTools = [];
+	else if (Array.isArray(tools) && tools.every((tool) => typeof tool === "string" && tool.length > 0)) materializedTools = tools.map((name) => ({
+		name,
+		description: "",
+		parameters: {}
+	}));
+	else return record;
+	record["data"] = {
+		...data,
+		header: {
+			...header,
+			tools: materializedTools
+		}
+	};
+	return record;
+}
+/** Materialize fixture-only header omissions and tokens before physical validation. */
+function normalizeProjectedHeader(header) {
+	const normalized = { ...header };
+	if (normalized["version"] === 0 && !Object.hasOwn(header, "delegationDepth")) normalized["delegationDepth"] = 0;
+	if (typeof header["cwd"] === "string" && /^\{\{cwd\}\}(?:\/|$)/.test(header["cwd"])) normalized["cwd"] = header["cwd"].replace("{{cwd}}", "/dsh-snapshot-cwd");
+	return normalized;
+}
+/** Return how many logical events one physical row contributes for deterministic seq completion. */
+function physicalRowCardinality(row) {
+	if (!PACKED_CHUNK_ROW_TYPES.has(row["type"])) return 1;
+	const data = row["data"];
+	if (data === null || typeof data !== "object" || Array.isArray(data)) return 1;
+	const payload = data[row["type"] === "tool-call-chunks" ? "args" : "texts"];
+	return Array.isArray(payload) && payload.length > 0 ? payload.length : 1;
+}
+/** Attach the nearest physical source line while preserving unsupported-migration classification. */
+function fixtureFormatError(error, headerLine, rowLines, eventLines, physicalRow) {
+	const detail = error instanceof Error ? error.message : String(error);
+	const locationDetail = error instanceof Error && error.cause instanceof Error ? error.cause.message : detail;
+	const storedRow = /^released Session row (\d+)/.exec(locationDetail);
+	const event = /Session event (\d+)/.exec(locationDetail) ?? / at seq (\d+)/.exec(locationDetail) ?? /inherited Session cut (\d+)/.exec(locationDetail);
+	let line;
+	if (physicalRow !== void 0) line = rowLines[physicalRow];
+	else if (storedRow !== null) line = rowLines[Number(storedRow[1])] ?? headerLine;
+	else if (event === null) line = headerLine;
+	else line = eventLines[Number(event[1])] ?? headerLine;
+	const message = `session snapshot line ${line}: ${detail}`;
+	if (error instanceof SessionFormatUnsupportedMigrationError) return new SessionFormatUnsupportedMigrationError(message, { cause: error });
+	return new Error(message, { cause: error });
 }
 /**
 * Read replay identity, ordering, and fork-seed facts from the JSONL header.
 *
-* @param text - the raw `.jsonl` file contents (only the header line is read).
-* @returns the header's `id`, `createdAt`, and inherited-event count, defaulted when absent.
+* @param text - the raw `.jsonl` file contents; the complete artifact is validated and migrated.
+* @returns the migrated header's `id`, `createdAt`, and exact inherited-event count.
 */
 function parseSessionHeader(text) {
-	const firstLine = text.split("\n").find((line) => line.trim().length > 0) ?? "{}";
-	const parsed = JSON.parse(firstLine);
+	const parsed = parseSessionFixture(text);
 	return {
-		id: typeof parsed.id === "string" ? parsed.id : "",
-		createdAt: typeof parsed.createdAt === "number" ? parsed.createdAt : 0,
-		inheritedEventCount: SessionLogOffset(typeof parsed.seedLength === "number" ? parsed.seedLength : 0)
+		id: parsed.id,
+		createdAt: parsed.createdAt,
+		inheritedEventCount: parsed.inheritedEventCount
 	};
 }
 /**
 * Reconstruct the per-`stream()` replay script from a recorded session log.
 *
-* Splits `assistant/chunk` events at every `finish`, using turn and step changes
-* to detect an unterminated prior call. A `compaction/summary` explicitly marked
+* Reads one embedded stream from each Assistant settlement. A `compaction/summary` explicitly marked
 * as one local LLM-stream call becomes a canonical successful stream from its
 * complete `rawOutput` at the summary's log position. A
 * missing assistant terminator means the live stream threw, so derivation
@@ -94,8 +358,6 @@ function parseSessionHeader(text) {
 */
 function deriveReplayScript(events) {
 	const script = [];
-	let currentKey;
-	let current = [];
 	const close = (key, chunks) => {
 		if (chunks.length === 0) return;
 		if (chunks[chunks.length - 1]?.type !== "finish") throw new Error(`llm-replay: model call ${key} ended without a finish chunk (a thrown stream); this scenario needs a replay.override.json sidecar`);
@@ -106,9 +368,6 @@ function deriveReplayScript(events) {
 	};
 	for (const event of events) {
 		if (event.type === "compaction/summary") {
-			close(currentKey, current);
-			currentKey = void 0;
-			current = [];
 			const persisted = event.data;
 			if (persisted.llmStreamCall === true) {
 				if (persisted.rawOutput === void 0) throw new Error("llm-replay: compaction/summary marks an LLM stream call without rawOutput");
@@ -140,19 +399,10 @@ function deriveReplayScript(events) {
 			}
 			continue;
 		}
-		if (event.type !== "assistant/chunk") continue;
-		const { turn, step, chunk } = event.data;
-		const key = `${turn}/${step}`;
-		if (current.length > 0 && key !== currentKey) close(currentKey, current);
-		if (current.length === 0) currentKey = key;
-		current.push(chunk);
-		if (chunk.type === "finish") {
-			close(currentKey, current);
-			currentKey = void 0;
-			current = [];
-		}
+		if (event.type !== "assistant/message" && event.type !== "assistant/attempt") continue;
+		const chunks = expandAssistantStream(event.data.stream).map((member) => member.chunk);
+		close(`${String(event.data.turn)}/${String(event.data.step)}`, chunks);
 	}
-	close(currentKey, current);
 	return script;
 }
 const REPLAY_CHUNK_TYPES = new Set([
@@ -346,10 +596,19 @@ function readOverrideDoc(value, file) {
 * @returns the resolved primary-session script.
 */
 function loadReplayScript(config) {
+	return resolveReplayScript(config, readPrimaryFixture(config));
+}
+/** Read a primary JSONL unless a whole-script sidecar intentionally occupies the same path. */
+function readPrimaryFixture(config) {
+	if (!existsSync(config.file) || config.file === config.overrideFile) return void 0;
+	return parseSessionFixture(readFileSync(config.file, "utf8"));
+}
+/** Resolve an override or derive from one already validated and migrated fixture. */
+function resolveReplayScript(config, fixture) {
 	if (config.overrideFile !== void 0 && existsSync(config.overrideFile)) {
 		const doc = readOverrideDoc(JSON.parse(readFileSync(config.overrideFile, "utf8")), config.overrideFile);
 		if (Array.isArray(doc)) return doc;
-		const script = deriveScriptFromFile(config.file);
+		const script = deriveScriptFromFixture(config.file, fixture);
 		const derivedLength = script.length;
 		const seenIndexes = /* @__PURE__ */ new Set();
 		for (const patch of doc.patches) {
@@ -360,12 +619,12 @@ function loadReplayScript(config) {
 		}
 		return script;
 	}
-	return deriveScriptFromFile(config.file);
+	return deriveScriptFromFixture(config.file, fixture);
 }
-/** Derive the primary script from the session JSONL, failing loud on a missing fixture. */
-function deriveScriptFromFile(file) {
-	if (!existsSync(file)) throw new Error(`llm-replay: fixture not found: ${file} — run \`pnpm run test:snapshot:record\` first`);
-	return deriveReplayScript(parseSessionLog(readFileSync(file, "utf8")));
+/** Derive a script from an already migrated fixture, failing loud when it is absent. */
+function deriveScriptFromFixture(file, fixture) {
+	if (fixture === void 0) throw new Error(`llm-replay: fixture not found: ${file} — run \`pnpm run test:snapshot:record\` first`);
+	return deriveReplayScript(fixture.events);
 }
 /**
 * Load the primary and child scripts in bind order. Child derivation begins at
@@ -375,8 +634,9 @@ function deriveScriptFromFile(file) {
 * @returns the primary script first, then the child scripts in bind order.
 */
 function loadSessionScripts(config) {
-	const primaryEntries = loadReplayScript(config);
-	const primaryHeader = existsSync(config.file) ? parseSessionHeader(readFileSync(config.file, "utf8")) : {
+	const primaryFixture = readPrimaryFixture(config);
+	const primaryEntries = resolveReplayScript(config, primaryFixture);
+	const primaryHeader = primaryFixture ?? {
 		id: "",
 		createdAt: 0
 	};
@@ -389,12 +649,11 @@ function loadSessionScripts(config) {
 	const children = [];
 	for (const childFile of config.childFiles ?? []) {
 		if (!existsSync(childFile)) throw new Error(`llm-replay: child fixture not found: ${childFile} — re-record the scenario`);
-		const text = readFileSync(childFile, "utf8");
-		const header = parseSessionHeader(text);
-		const ownEvents = parseSessionLog(text).slice(header.inheritedEventCount);
+		const fixture = parseSessionFixture(readFileSync(childFile, "utf8"));
+		const ownEvents = fixture.events.slice(fixture.inheritedEventCount);
 		children.push({
-			recordedId: header.id,
-			createdAt: header.createdAt,
+			recordedId: fixture.id,
+			createdAt: fixture.createdAt,
 			entries: deriveReplayScript(ownEvents),
 			primary: false
 		});
@@ -659,4 +918,4 @@ function apply(ctx, config = {}) {
 	});
 }
 //#endregion
-export { apply, deriveReplayScript, inject, installLlmReplay, loadReplayScript, loadSessionScripts, name, parseSessionHeader, parseSessionLog, resolveScriptedEntry };
+export { apply, deriveReplayScript, inject, installLlmReplay, loadReplayScript, loadSessionScripts, name, parseSessionHeader, parseSessionLog, prepareSessionEventNotificationsForComparison, prepareSessionSnapshotFixtureForComparison, resolveScriptedEntry };

package/lib/types/index.d.ts

@@ -1,6 +1,6 @@
 /**
  * Keyless snapshot-test LLM replay. It derives one model-call script per
- * recorded session from `assistant/chunk` events and explicitly marked local
+ * recorded session from v2 embedded Assistant streams and explicitly marked local
  * compaction calls, then binds fresh live sessions to parent/child scripts by
  * first-call order. Throw and hang cases require an explicit override because
  * a session log cannot reconstruct them alone.
@@ -78,16 +78,17 @@ export interface ReplayProviderConfig {
 /** Resolved plugin configuration. */
 export interface ReplayConfig {
     /**
-     * Path to the PRIMARY (parent) `session.jsonl` fixture. For a single-session
-     * scenario this is the only log; for a nested-agent scenario it is the parent,
-     * and the child logs ride in {@link childFiles}.
+     * Path to the selected PRIMARY fixture (`session.jsonl` for v0 or
+     * `session.vN.jsonl` for vN). For a single-session scenario this is the only
+     * log; for a nested-agent scenario it is the parent, and child logs ride in
+     * {@link childFiles}.
      */
     file: string;
     /**
      * Optional sidecar for the PRIMARY session: a bare `ReplayEntry[]` replaces
      * the derived script; `{ patches }` keeps it and swaps the named call
      * indexes ({@link ReplayOverrideDoc}). Used by single-session scenarios not
-     * expressible as `assistant/chunk` (throw-before-chunk, cancel/hang,
+     * expressible as a durable embedded stream (throw-before-chunk, cancel/hang,
      * injected transient failures). Absent for normal and nested scenarios.
      */
     overrideFile?: string;
@@ -148,21 +149,34 @@ export interface SessionScript {
     primary: boolean;
 }
 /**
- * Parse a session `.jsonl` buffer into its event list. Line 0 is the session
- * header (a `{type:'session',…}` record), every subsequent non-empty line is a
- * {@link SessionEvent} or a packed chunk row. Packed rows expand back into
- * events, and JSONL storage-form provenance ranges expand back into
- * `number[]`, so physical fixture encodings derive the same script. The
- * header is skipped; malformed lines fail loud.
+ * Parse a projected session `.jsonl` buffer into current events. The first
+ * non-empty line is the physical header. Body rows either all carry complete
+ * persistence envelopes or all omit them; projected rows receive deterministic
+ * dense sequences and zero timestamps. The build-static format catalog then
+ * decodes and migrates the complete artifact before this function returns.
  * @param text - the raw `.jsonl` file contents.
- * @returns every event after the header, in log order.
+ * @returns every migrated current event, in log order.
  */
 export declare function parseSessionLog(text: string): SessionEvent[];
+/**
+ * Convert one persisted or projected snapshot fixture to the current physical format in memory for expected-output comparison.
+ * Projected cwd tokens remain tokens so the ordinary snapshot normalizer can compare them with a fresh run.
+ * @param text - one complete Session fixture.
+ * @returns current-format JSONL with complete event envelopes; the input string and source file remain unchanged.
+ */
+export declare function prepareSessionSnapshotFixtureForComparison(text: string): string;
+/**
+ * Project v1 session-event notifications to current settlement cardinality in memory.
+ * Non-event protocol rows retain their exact positions, and current v2 input passes through.
+ * @param text - headless `session_event` or SDK `session.event` JSONL.
+ * @returns comparison JSONL using current Session events without modifying its source file.
+ */
+export declare function prepareSessionEventNotificationsForComparison(text: string): string;
 /**
  * Read replay identity, ordering, and fork-seed facts from the JSONL header.
  *
- * @param text - the raw `.jsonl` file contents (only the header line is read).
- * @returns the header's `id`, `createdAt`, and inherited-event count, defaulted when absent.
+ * @param text - the raw `.jsonl` file contents; the complete artifact is validated and migrated.
+ * @returns the migrated header's `id`, `createdAt`, and exact inherited-event count.
  */
 export declare function parseSessionHeader(text: string): {
     id: string;
@@ -172,8 +186,7 @@ export declare function parseSessionHeader(text: string): {
 /**
  * Reconstruct the per-`stream()` replay script from a recorded session log.
  *
- * Splits `assistant/chunk` events at every `finish`, using turn and step changes
- * to detect an unterminated prior call. A `compaction/summary` explicitly marked
+ * Reads one embedded stream from each Assistant settlement. A `compaction/summary` explicitly marked
  * as one local LLM-stream call becomes a canonical successful stream from its
  * complete `rawOutput` at the summary's log position. A
  * missing assistant terminator means the live stream threw, so derivation

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-llm-replay",
   "description": "Replay LLM plugin: short-circuits llm/stream with model chunks reconstructed from a recorded session JSONL (keyless snapshot tests)",
-  "version": "0.1.2-alpha.5",
+  "version": "0.1.3-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -28,10 +28,10 @@
   "license": "MIT",
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-deepseek-llm-api-extensions": "^0.1.2-alpha.5",
-    "@deepseek-ai/dsh-llm": "^0.1.2-alpha.5",
-    "@deepseek-ai/dsh-session": "^0.1.2-alpha.5",
-    "@deepseek-ai/dsh-compaction": "^0.1.2-alpha.5"
+    "@deepseek-ai/dsh-compaction": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-deepseek-llm-api-extensions": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-llm": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-session": "^0.1.3-alpha.2"
   },
   "peerDependenciesMeta": {
     "@deepseek-ai/dsh-deepseek-llm-api-extensions": {
@@ -39,13 +39,14 @@
     }
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-compaction": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-deepseek-llm-api-extensions": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-llm": "^0.1.3-alpha.2",
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-compaction": "^0.1.2-alpha.5",
-    "@deepseek-ai/dsh-deepseek-llm-api-extensions": "^0.1.2-alpha.5",
-    "@deepseek-ai/dsh-llm": "^0.1.2-alpha.5",
-    "@deepseek-ai/dsh-session": "^0.1.2-alpha.5"
+    "@deepseek-ai/dsh-session": "^0.1.3-alpha.2"
   },
   "dependencies": {
-    "@deepseek-ai/dsh-util-values": "^0.1.2-alpha.5"
+    "@deepseek-ai/dsh-session-format-catalog": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-util-values": "^0.1.3-alpha.2"
   }
 }