@danceiny/gotry 0.0.1-rc.9 → 0.2.0-rc.27

package/dist/scripts/dsh-http-proxy-sse-proof.js

@@ -0,0 +1,90 @@
+/**
+ * dsh-http-proxy 本地 SSE + 中毒 HTTP 代理反例(issue #268):启动回环 SSE 服务器和
+ * 统计命中次数的中毒代理,用公共 installProxyFromEnvironment API 安装代理策略,
+ * 将 HTTP(S)_PROXY 指向中毒代理。在 127.0.0.1 上获取 SSE 端点,断言负载成功且
+ * 中毒命中计数保持为零;同时断言 proxyRouteFor(loopback) 是直接的,非回环 URL
+ * 被分类为代理,且 proxyEnvironmentForChild() 携带回环 NO_PROXY 以及 Node 24 下的
+ * NODE_USE_ENV_PROXY。始终 await 返回的 disposer 并在 finally 中关闭两个服务器;
+ * 证明全局路由返回到先前的直接状态。
+ *
+ * 运行:cd ts && npx tsx scripts/dsh-http-proxy-sse-proof.ts
+ */
+import assert from 'node:assert/strict';
+import http from 'node:http';
+import { installProxyFromEnvironment, proxyRouteFor, proxyEnvironmentForChild } from '@deepseek-ai/dsh-http-proxy';
+// 1. 回环 SSE 服务器。
+const sseServer = http.createServer((req, res) => {
+    res.writeHead(200, {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        Connection: 'keep-alive',
+    });
+    res.write('data: hello-sse\n\n');
+    res.end();
+});
+await new Promise((resolve) => sseServer.listen(0, '127.0.0.1', resolve));
+const sseAddr = sseServer.address();
+assert.ok(sseAddr !== null && typeof sseAddr === 'object', 'SSE 服务器必须已绑定地址');
+const ssePort = sseAddr.port;
+const sseUrl = `http://127.0.0.1:${ssePort}/`;
+// 2. 中毒代理:统计命中次数,返回 502。
+let poisonHits = 0;
+const poisonServer = http.createServer((req, res) => {
+    poisonHits++;
+    res.writeHead(502);
+    res.end('poisoned');
+});
+await new Promise((resolve) => poisonServer.listen(0, '127.0.0.1', resolve));
+const poisonAddr = poisonServer.address();
+assert.ok(poisonAddr !== null && typeof poisonAddr === 'object', '中毒代理必须已绑定地址');
+const poisonPort = poisonAddr.port;
+let disposer;
+try {
+    // 3. 用公共 installProxyFromEnvironment API 安装代理策略,指向中毒代理。
+    const envMap = new Map([
+        ['HTTP_PROXY', `http://127.0.0.1:${poisonPort}`],
+        ['HTTPS_PROXY', `http://127.0.0.1:${poisonPort}`],
+    ]);
+    const envLookup = {
+        get(name) {
+            const v = envMap.get(name) ?? envMap.get(name.toLowerCase());
+            return v !== undefined ? { value: v } : undefined;
+        },
+    };
+    disposer = await installProxyFromEnvironment(envLookup, () => { });
+    // 4. proxyRouteFor(loopback) 是直接的;非回环 URL 被分类为代理。
+    const loopbackRoute = proxyRouteFor(new URL(sseUrl));
+    assert.equal(loopbackRoute.proxied, false, '回环 URL 必须路由为直接(proxyRouteFor)');
+    const externalRoute = proxyRouteFor(new URL('http://example.com/'));
+    assert.equal(externalRoute.proxied, true, '非回环 URL 必须被分类为代理(proxyRouteFor)');
+    // 5. proxyEnvironmentForChild() 携带回环 NO_PROXY 以及 Node 24 下的 NODE_USE_ENV_PROXY。
+    const childEnv = proxyEnvironmentForChild();
+    assert.equal(childEnv.NODE_USE_ENV_PROXY, '1', 'proxyEnvironmentForChild 必须携带 NODE_USE_ENV_PROXY=1(Node 24)');
+    assert.ok(typeof childEnv.NO_PROXY === 'string' && childEnv.NO_PROXY.includes('127.0.0.1'), `proxyEnvironmentForChild NO_PROXY 必须包含 127.0.0.1(当前 ${JSON.stringify(childEnv.NO_PROXY)})`);
+    // 6. 在 127.0.0.1 上获取 SSE 端点:负载成功且中毒命中计数保持为零。
+    const resp = await fetch(sseUrl);
+    assert.equal(resp.status, 200, `SSE fetch 必须成功(status=${resp.status})`);
+    const body = await resp.text();
+    assert.ok(body.includes('hello-sse'), `SSE 负载必须包含 hello-sse(当前 ${JSON.stringify(body)})`);
+    assert.equal(poisonHits, 0, `中毒代理命中计数必须为零(当前 ${poisonHits})——回环绕过代理`);
+}
+finally {
+    // 7. 始终 await 返回的 disposer 并在 finally 中 await 关闭两个服务器(包括失败路径)。
+    //    不依赖未 await 的 server.close() 让进程退出——显式 await 完成资源清理。
+    try {
+        if (disposer)
+            await disposer();
+    }
+    finally {
+        await Promise.all([
+            new Promise((resolve, reject) => sseServer.close((err) => (err ? reject(err) : resolve()))),
+            new Promise((resolve, reject) => poisonServer.close((err) => (err ? reject(err) : resolve()))),
+        ]);
+    }
+}
+// 8. 证明全局路由返回到先前的直接状态。
+const externalAfter = proxyRouteFor(new URL('http://example.com/'));
+assert.equal(externalAfter.proxied, false, 'disposer 后全局路由必须返回直接状态');
+console.log(`HTTP PROXY SSE PROOF: loopback SSE fetch=200 payload-has-hello-sse=true poison-hits=0, ` +
+    `loopback route=direct external route=proxied, NODE_USE_ENV_PROXY=1 NO_PROXY has 127.0.0.1, ` +
+    `routing restored to direct after dispose`);

package/dist/scripts/dsh-runtime-closure-tests.js

@@ -0,0 +1,182 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { parsePnpmDshLock, parsePnpmRootDshImporter, REQUIRED_DSH_RUNTIME_PACKAGE_COUNT, validateDshRuntimeClosure, validatePnpmRootDshImporter, } from './dsh-runtime-closure.js';
+const VERSION = '0.2.0-rc.2';
+function validInput() {
+    return {
+        dependencies: {
+            '@deepseek-ai/dsh': VERSION,
+            '@deepseek-ai/dsh-session-title': VERSION,
+        },
+        lockPackages: {
+            'node_modules/@deepseek-ai/dsh': { version: VERSION },
+            'node_modules/@deepseek-ai/dsh-session-title': { version: VERSION },
+        },
+        runtimeVersion: VERSION,
+    };
+}
+test('accepts an exact coherent DSH prerelease closure', () => {
+    assert.deepEqual(validateDshRuntimeClosure(validInput()), {
+        names: ['@deepseek-ai/dsh', '@deepseek-ai/dsh-session-title'],
+        version: VERSION,
+    });
+});
+test('rejects a lock package missing from the published direct dependencies', () => {
+    const input = validInput();
+    input.dependencies = { '@deepseek-ai/dsh': VERSION };
+    assert.throws(() => validateDshRuntimeClosure(input), /DSH closure 未精确声明/);
+});
+test('rejects an extra ranged DSH dependency absent from the tested lock closure', () => {
+    const input = validInput();
+    input.dependencies['@deepseek-ai/dsh-web'] = '^0.2.0-rc.2';
+    assert.throws(() => validateDshRuntimeClosure(input), /DSH manifest 与 lock 集合不一致/);
+});
+test('rejects a nested DSH package from another prerelease', () => {
+    const input = validInput();
+    input.lockPackages['node_modules/@deepseek-ai/dsh/node_modules/@deepseek-ai/dsh-session-title'] = {
+        version: '0.1.5-alpha.2',
+    };
+    assert.throws(() => validateDshRuntimeClosure(input), /DSH lock 版本漂移/);
+});
+test('rejects drift from the runtime spawn guard version', () => {
+    const input = validInput();
+    input.runtimeVersion = '0.1.5-alpha.2';
+    assert.throws(() => validateDshRuntimeClosure(input), /DSH runtime guard 版本漂移/);
+});
+test('parses each pnpm DSH resolution once across packages and snapshots', () => {
+    const lock = `
+packages:
+  '@deepseek-ai/dsh@0.2.0-rc.2': {}
+  '@deepseek-ai/dsh-session@0.2.0-rc.2': {}
+snapshots:
+  '@deepseek-ai/dsh@0.2.0-rc.2': {}
+`;
+    assert.deepEqual(parsePnpmDshLock(lock), {
+        'node_modules/@deepseek-ai/dsh': { version: VERSION },
+        'node_modules/@deepseek-ai/dsh-session': { version: VERSION },
+    });
+});
+test('preserves two pnpm resolutions of the same DSH package for mixed-version rejection', () => {
+    const lock = `
+packages:
+  '@deepseek-ai/dsh@0.2.0-rc.2': {}
+  '@deepseek-ai/dsh-session@0.2.0-rc.2': {}
+  '@deepseek-ai/dsh-session@0.1.5-alpha.2': {}
+`;
+    const parsed = parsePnpmDshLock(lock);
+    assert.equal(Object.keys(parsed).length, 3);
+    assert.throws(() => validateDshRuntimeClosure({
+        dependencies: {
+            '@deepseek-ai/dsh': VERSION,
+            '@deepseek-ai/dsh-session': VERSION,
+        },
+        lockPackages: parsed,
+        runtimeVersion: VERSION,
+    }), /DSH lock 版本漂移/);
+});
+test('parses only the root pnpm importer DSH entries', () => {
+    const lock = `
+lockfileVersion: '9.0'
+importers:
+  .:
+    dependencies:
+      '@deepseek-ai/dsh':
+        specifier: 0.2.0-rc.2
+        version: 0.2.0-rc.2(peer@1.0.0)
+      '@deepseek-ai/dsh-session':
+        specifier: 0.2.0-rc.2
+        version: 0.2.0-rc.2
+  ts:
+    dependencies:
+      '@deepseek-ai/dsh-web':
+        specifier: 0.1.5-alpha.2
+        version: 0.1.5-alpha.2
+packages: {}
+`;
+    assert.deepEqual(parsePnpmRootDshImporter(lock), {
+        '@deepseek-ai/dsh': { specifier: VERSION, resolvedVersion: VERSION },
+        '@deepseek-ai/dsh-session': { specifier: VERSION, resolvedVersion: VERSION },
+    });
+});
+test('rejects a pnpm root importer missing a published DSH dependency', () => {
+    assert.throws(() => validatePnpmRootDshImporter({
+        dependencies: validInput().dependencies,
+        importerEntries: {
+            '@deepseek-ai/dsh': { specifier: VERSION, resolvedVersion: VERSION },
+        },
+        runtimeVersion: VERSION,
+    }), /pnpm root importer 与 manifest 集合不一致/);
+});
+test('rejects a ranged DSH specifier in the pnpm root importer', () => {
+    assert.throws(() => validatePnpmRootDshImporter({
+        dependencies: validInput().dependencies,
+        importerEntries: {
+            '@deepseek-ai/dsh': { specifier: VERSION, resolvedVersion: VERSION },
+            '@deepseek-ai/dsh-session-title': { specifier: '^0.2.0-rc.2', resolvedVersion: VERSION },
+        },
+        runtimeVersion: VERSION,
+    }), /pnpm root importer 未精确锁定/);
+});
+test('rejects a drifted resolved DSH version in the pnpm root importer', () => {
+    assert.throws(() => validatePnpmRootDshImporter({
+        dependencies: validInput().dependencies,
+        importerEntries: {
+            '@deepseek-ai/dsh': { specifier: VERSION, resolvedVersion: '0.1.5-alpha.2' },
+            '@deepseek-ai/dsh-session-title': { specifier: VERSION, resolvedVersion: VERSION },
+        },
+        runtimeVersion: VERSION,
+    }), /pnpm root importer resolved 版本漂移/);
+});
+test('rejects a missing resolved DSH version in the pnpm root importer', () => {
+    const lock = `
+importers:
+  .:
+    dependencies:
+      '@deepseek-ai/dsh':
+        specifier: 0.2.0-rc.2
+`;
+    assert.throws(() => parsePnpmRootDshImporter(lock), /pnpm root importer version 不可用/);
+});
+test('rejects duplicate resolved DSH versions in the pnpm root importer', () => {
+    const lock = `
+importers:
+  .:
+    dependencies:
+      '@deepseek-ai/dsh':
+        specifier: 0.2.0-rc.2
+        version: 0.2.0-rc.2
+        version: 0.1.5-alpha.2
+`;
+    assert.throws(() => parsePnpmRootDshImporter(lock), /pnpm root importer version 不可用/);
+});
+test('rejects a coherent closure below the required package count', () => {
+    assert.throws(() => validateDshRuntimeClosure({
+        ...validInput(),
+        expectedPackageCount: REQUIRED_DSH_RUNTIME_PACKAGE_COUNT,
+    }), /DSH closure 包数量不符/);
+});
+test('rejects a coherent root importer below the required package count', () => {
+    assert.throws(() => validatePnpmRootDshImporter({
+        dependencies: validInput().dependencies,
+        importerEntries: {
+            '@deepseek-ai/dsh': { specifier: VERSION, resolvedVersion: VERSION },
+            '@deepseek-ai/dsh-session-title': { specifier: VERSION, resolvedVersion: VERSION },
+        },
+        runtimeVersion: VERSION,
+        expectedPackageCount: REQUIRED_DSH_RUNTIME_PACKAGE_COUNT,
+    }), /pnpm root importer 包数量不符/);
+});
+test('rejects duplicate DSH entries in the pnpm root importer', () => {
+    const lock = `
+importers:
+  .:
+    dependencies:
+      '@deepseek-ai/dsh':
+        specifier: 0.2.0-rc.2
+        version: 0.2.0-rc.2
+      '@deepseek-ai/dsh':
+        specifier: 0.2.0-rc.2
+        version: 0.2.0-rc.2
+`;
+    assert.throws(() => parsePnpmRootDshImporter(lock), /pnpm root importer DSH 依赖重复/);
+});

package/dist/scripts/dsh-runtime-closure.js

@@ -0,0 +1,162 @@
+export const REQUIRED_DSH_RUNTIME_PACKAGE_COUNT = 279;
+function yamlScalar(value) {
+    const trimmed = value.trim().replace(/\s+#.*$/, '');
+    const quoted = trimmed.match(/^(['"])(.*)\1$/);
+    return quoted?.[2] ?? trimmed;
+}
+function indentation(line) {
+    return line.match(/^ */)?.[0].length ?? 0;
+}
+function resolvedPnpmVersion(value) {
+    return yamlScalar(value).replace(/\(.+$/, '');
+}
+export function parsePnpmRootDshImporter(text) {
+    const lines = text.split(/\r?\n/);
+    const importers = lines
+        .map((line, index) => line === 'importers:' ? index : -1)
+        .filter((index) => index >= 0);
+    if (importers.length !== 1)
+        throw new Error('pnpm lock importers 区块不可用');
+    const importersStart = importers[0];
+    const importersEnd = lines.findIndex((line, index) => index > importersStart && line.trim() !== '' && indentation(line) === 0);
+    const rootCandidates = lines
+        .map((line, index) => index > importersStart && (importersEnd < 0 || index < importersEnd)
+        && /^ {2}(?:\.|'\.'|"\."):\s*$/.test(line) ? index : -1)
+        .filter((index) => index >= 0);
+    if (rootCandidates.length !== 1)
+        throw new Error('pnpm root importer 不唯一');
+    const rootStart = rootCandidates[0];
+    const rootEndRelative = lines.slice(rootStart + 1, importersEnd < 0 ? lines.length : importersEnd)
+        .findIndex((line) => line.trim() !== '' && indentation(line) <= 2);
+    const rootEnd = rootEndRelative < 0
+        ? (importersEnd < 0 ? lines.length : importersEnd)
+        : rootStart + 1 + rootEndRelative;
+    const dependencyBlocks = lines
+        .map((line, index) => index > rootStart && index < rootEnd && /^ {4}dependencies:\s*$/.test(line) ? index : -1)
+        .filter((index) => index >= 0);
+    if (dependencyBlocks.length !== 1)
+        throw new Error('pnpm root importer dependencies 区块不可用');
+    const dependenciesStart = dependencyBlocks[0];
+    const dependenciesEndRelative = lines.slice(dependenciesStart + 1, rootEnd)
+        .findIndex((line) => line.trim() !== '' && indentation(line) <= 4);
+    const dependenciesEnd = dependenciesEndRelative < 0 ? rootEnd : dependenciesStart + 1 + dependenciesEndRelative;
+    const entries = lines
+        .map((line, index) => {
+        if (index <= dependenciesStart || index >= dependenciesEnd)
+            return null;
+        const match = line.match(/^ {6}(['"]?)([^'":\s]+)\1:\s*$/);
+        return match ? { index, name: match[2] } : null;
+    })
+        .filter((entry) => entry !== null);
+    const importerEntries = {};
+    for (let entryIndex = 0; entryIndex < entries.length; entryIndex += 1) {
+        const entry = entries[entryIndex];
+        if (entry.name !== '@deepseek-ai/dsh' && !entry.name.startsWith('@deepseek-ai/dsh-'))
+            continue;
+        if (Object.hasOwn(importerEntries, entry.name))
+            throw new Error(`pnpm root importer DSH 依赖重复:${entry.name}`);
+        const end = entries[entryIndex + 1]?.index ?? dependenciesEnd;
+        const block = lines.slice(entry.index + 1, end);
+        const specifiers = block
+            .map((line) => line.match(/^ {8}specifier:\s*(.+)$/)?.[1])
+            .filter((value) => value !== undefined);
+        if (specifiers.length !== 1)
+            throw new Error(`pnpm root importer specifier 不可用:${entry.name}`);
+        const versions = block
+            .map((line) => line.match(/^ {8}version:\s*(.+)$/)?.[1])
+            .filter((value) => value !== undefined);
+        if (versions.length !== 1)
+            throw new Error(`pnpm root importer version 不可用:${entry.name}`);
+        importerEntries[entry.name] = {
+            specifier: yamlScalar(specifiers[0]),
+            resolvedVersion: resolvedPnpmVersion(versions[0]),
+        };
+    }
+    return importerEntries;
+}
+export function validatePnpmRootDshImporter(input) {
+    const manifestNames = Object.keys(input.dependencies)
+        .filter((name) => name === '@deepseek-ai/dsh' || name.startsWith('@deepseek-ai/dsh-'))
+        .sort();
+    const importerNames = Object.keys(input.importerEntries).sort();
+    const missing = manifestNames.filter((name) => !importerNames.includes(name));
+    const extra = importerNames.filter((name) => !manifestNames.includes(name));
+    if (missing.length > 0 || extra.length > 0) {
+        throw new Error(`pnpm root importer 与 manifest 集合不一致:missing=${missing.join(',') || '-'};extra=${extra.join(',') || '-'}`);
+    }
+    for (const name of importerNames) {
+        const importerEntry = input.importerEntries[name];
+        if (input.dependencies[name] !== input.runtimeVersion || importerEntry.specifier !== input.runtimeVersion) {
+            throw new Error(`pnpm root importer 未精确锁定:${name}@${input.runtimeVersion}`);
+        }
+        if (importerEntry.resolvedVersion !== input.runtimeVersion) {
+            throw new Error(`pnpm root importer resolved 版本漂移:${name}@${importerEntry.resolvedVersion}(expected ${input.runtimeVersion})`);
+        }
+    }
+    if (input.expectedPackageCount !== undefined && importerNames.length !== input.expectedPackageCount) {
+        throw new Error(`pnpm root importer 包数量不符:${importerNames.length}(expected ${input.expectedPackageCount})`);
+    }
+    return { names: importerNames, version: input.runtimeVersion };
+}
+export function parsePnpmDshLock(text) {
+    const packages = {};
+    const seen = new Set();
+    const variants = new Map();
+    const entry = /^\s{2}['"]?(\@deepseek-ai\/dsh(?:-[^@'":\s]+)?)@([^'":\s(]+)(?:\([^'"]*\))?['"]?:/gm;
+    for (const match of text.matchAll(entry)) {
+        const name = match[1];
+        const version = match[2];
+        const identity = `${name}@${version}`;
+        if (seen.has(identity))
+            continue;
+        seen.add(identity);
+        const variant = variants.get(name) ?? 0;
+        variants.set(name, variant + 1);
+        const prefix = variant === 0 ? '' : `.pnpm-variant-${variant}/node_modules/`;
+        packages[`node_modules/${prefix}${name}`] = { version };
+    }
+    return packages;
+}
+export function validateDshRuntimeClosure(input) {
+    const dshVersion = input.dependencies['@deepseek-ai/dsh'];
+    if (typeof dshVersion !== 'string' || !/^\d+\.\d+\.\d+-[0-9A-Za-z.-]+$/.test(dshVersion)) {
+        throw new Error('@deepseek-ai/dsh 必须以精确 prerelease 版本声明');
+    }
+    if (dshVersion !== input.runtimeVersion) {
+        throw new Error(`DSH runtime guard 版本漂移:${input.runtimeVersion}(manifest ${dshVersion})`);
+    }
+    const dshNodes = Object.entries(input.lockPackages)
+        .flatMap(([path, metadata]) => {
+        const match = path.match(/(?:^|\/)node_modules\/(\@deepseek-ai\/dsh(?:-[^/]+)?)$/);
+        return match ? [{ name: match[1], version: metadata.version }] : [];
+    })
+        .sort((left, right) => left.name.localeCompare(right.name));
+    if (dshNodes.length === 0)
+        throw new Error('package-lock 未解析到 DSH runtime closure');
+    for (const dependency of dshNodes) {
+        if (dependency.version !== dshVersion) {
+            throw new Error(`DSH lock 版本漂移:${dependency.name}@${dependency.version ?? 'missing'}(expected ${dshVersion})`);
+        }
+    }
+    const lockNames = [...new Set(dshNodes.map((dependency) => dependency.name))].sort();
+    const manifestNames = Object.keys(input.dependencies)
+        .filter((name) => name === '@deepseek-ai/dsh' || name.startsWith('@deepseek-ai/dsh-'))
+        .sort();
+    const missing = lockNames.filter((name) => !manifestNames.includes(name));
+    const extra = manifestNames.filter((name) => !lockNames.includes(name));
+    if (missing.length > 0) {
+        throw new Error(`DSH closure 未精确声明:${missing[0]}@${dshVersion}`);
+    }
+    if (extra.length > 0) {
+        throw new Error(`DSH manifest 与 lock 集合不一致:missing=${missing.join(',') || '-'};extra=${extra.join(',') || '-'}`);
+    }
+    for (const name of manifestNames) {
+        if (input.dependencies[name] !== dshVersion) {
+            throw new Error(`DSH closure 未精确声明:${name}@${dshVersion}`);
+        }
+    }
+    if (input.expectedPackageCount !== undefined && lockNames.length !== input.expectedPackageCount) {
+        throw new Error(`DSH closure 包数量不符:${lockNames.length}(expected ${input.expectedPackageCount})`);
+    }
+    return { names: lockNames, version: dshVersion };
+}

package/dist/scripts/dsh-session-v3-migration-proof.js

@@ -0,0 +1,109 @@
+/**
+ * Session V3 确定性迁移契约(issue #268):在隔离临时目录下用真实发布的 V2 编解码器
+ * 生成 V2 header/events,序列化为 JSONL 字节写入磁盘,保存确切源字节快照;通过
+ * sessionFormatCatalog 从磁盘读取并解析这些字节,分类为 migration-required,迁移为
+ * V3,编码独立 V3 继任者写入磁盘;然后用 catalog validation:current 完全解码 V3
+ * 继任者;迁移后重新读取 V2 源文件做字节比较,证明迁移不修改源工件字节。
+ *
+ * 这是确定性格式兼容性证据(隔离文件字节,非内存 structuredClone),不是创始人状态
+ * 迁移,也不是 M5/M6 准入。
+ *
+ * 运行:cd ts && npx tsx scripts/dsh-session-v3-migration-proof.ts
+ */
+import assert from 'node:assert/strict';
+import { writeFileSync, readFileSync, mkdtempSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { createSessionFormatCatalogWithChildren } from '@deepseek-ai/dsh-session-format-catalog';
+import { releasedV2SessionFormatCodec } from '@deepseek-ai/dsh-session-format-v1-to-v2';
+// 最小有效 V2 工件:一个 turn 包含一个 step,turn 正常完成。
+// V2 事件处置要求 turn/start 需 ["turn"],step/start|step/end 需 ["turn","step"],
+// turn/end 需 ["turn","reason"],reason.kind="completed" 是最简有效种类。
+const v2Header = {
+    version: 2,
+    id: 's-min-v2',
+    createdAt: 1700000000000,
+    isSeeded: false,
+    delegationDepth: 0,
+};
+const v2Events = [
+    { type: 'turn/start', seq: 0, time: 1700000000000, data: { turn: 1 } },
+    { type: 'step/start', seq: 1, time: 1700000000001, data: { turn: 1, step: 1 } },
+    { type: 'step/end', seq: 2, time: 1700000000002, data: { turn: 1, step: 1 } },
+    { type: 'turn/end', seq: 3, time: 1700000000003, data: { turn: 1, reason: { kind: 'completed' } } },
+];
+// 1. 用真实发布的 V2 编解码器编码 header + 事件行为 JSON 对象,序列化为 JSONL 字节。
+const encodedHeader = releasedV2SessionFormatCodec.encodeHeader(v2Header, 0);
+const encodedRows = v2Events.map((e) => releasedV2SessionFormatCodec.encodeEvent(e));
+function toLine(obj) {
+    return JSON.stringify(obj);
+}
+const sourceLines = [toLine(encodedHeader), ...encodedRows.map(toLine)];
+const sourceJsonl = sourceLines.join('\n') + '\n';
+const tmp = mkdtempSync(join(tmpdir(), 'session-v3-migration-proof-'));
+const sourcePath = join(tmp, 'source.v2.jsonl');
+const successorPath = join(tmp, 'successor.current.jsonl');
+// 0.2.0-rc.2 起 catalog current = V4;V3→V4 边要求显式历史子代理证据,
+// 本 fixture 是无父会话,声明空数组(createSessionFormatCatalogWithChildren)。
+const catalog = createSessionFormatCatalogWithChildren([]);
+try {
+    // 2. 写 V2 源字节到磁盘,保存确切源字节快照。
+    writeFileSync(sourcePath, sourceJsonl, 'utf8');
+    const sourceBytes = readFileSync(sourcePath);
+    // 3. 从磁盘读取并解析 V2 源字节:首行 = header,其余 = 事件行。
+    const parsedLines = readFileSync(sourcePath, 'utf8').split('\n').filter((l) => l.length > 0);
+    assert.ok(parsedLines.length === sourceLines.length, `磁盘行数必须等于源行数(${parsedLines.length} vs ${sourceLines.length})`);
+    const headerValue = JSON.parse(parsedLines[0]);
+    const rowValues = parsedLines.slice(1).map((l) => JSON.parse(l));
+    // 4. catalog 当前版本 = 4(0.2.0-rc.2 起);V2 header 分类为 migration-required。
+    assert.equal(catalog.currentVersion, 4, 'catalog 当前版本必须为 4(0.2.0-rc.2 起 V4 为 current)');
+    const headerRead = catalog.readHeader(headerValue);
+    assert.equal(headerRead.status, 'migration-required', `V2 header 必须分类为 migration-required(当前 ${headerRead.status})`);
+    // 5. 创建恢复器,逐行解码,完成恢复为 V3 工件(validation:transformed,迁移后校验)。
+    const restore = catalog.createRestore(headerValue, {
+        recovery: 'recoverable',
+        validation: 'transformed',
+    });
+    for (const row of rowValues) {
+        restore.decodeRow(row);
+    }
+    const artifact = restore.finish();
+    // 6. 迁移链工件版本 = 4(V2→V3 插入 system head 后,V3→V4 不减事件)。
+    assert.equal(artifact.header.version, 4, '恢复后工件版本必须为 4');
+    assert.ok(artifact.events.length >= v2Events.length + 1, `迁移链事件数必须 ≥ V2 + 1(插入 system head),当前 ${artifact.events.length}`);
+    // 插入的 system head(原 step/start 后)必须是 system/message。
+    const inserted = artifact.events.find((event) => event.type === 'system/message');
+    assert.ok(inserted, '迁移链必须包含插入的 system/message head');
+    // 7. 编码 current(V4)继任者为 JSONL 字节,写入独立磁盘文件。
+    const currentHeaderRecord = catalog.encodeCurrentHeader(artifact.header, artifact.inheritedEventCount);
+    const currentRowRecords = artifact.events.map((e) => catalog.encodeCurrentEvent(e));
+    const successorLines = [toLine(currentHeaderRecord), ...currentRowRecords.map(toLine)];
+    const successorJsonl = successorLines.join('\n') + '\n';
+    writeFileSync(successorPath, successorJsonl, 'utf8');
+    // 8. 从磁盘读取 V3 继任者,用 catalog validation:current 完全解码。
+    const successorParsed = readFileSync(successorPath, 'utf8').split('\n').filter((l) => l.length > 0);
+    assert.ok(successorParsed.length === successorLines.length, `V3 磁盘行数必须等于继任者行数`);
+    const successorHeaderValue = JSON.parse(successorParsed[0]);
+    const successorRowValues = successorParsed.slice(1).map((l) => JSON.parse(l));
+    const successorRead = catalog.readHeader(successorHeaderValue);
+    assert.equal(successorRead.status, 'current', `V3 继任者必须重新打开为 current(当前 ${successorRead.status})`);
+    const successorRestore = catalog.createRestore(successorHeaderValue, {
+        recovery: 'recoverable',
+        validation: 'current',
+    });
+    for (const row of successorRowValues) {
+        successorRestore.decodeRow(row);
+    }
+    const successorArtifact = successorRestore.finish();
+    assert.equal(successorArtifact.header.version, 4, 'current 继任者完全解码后版本必须为 4');
+    assert.equal(successorArtifact.events.length, artifact.events.length, 'V3 继任者完全解码后事件数必须与迁移工件一致');
+    // 9. 迁移后重新读取 V2 源文件字节,与快照字节比较——证明迁移不修改源工件字节。
+    const sourceBytesAfter = readFileSync(sourcePath);
+    assert.ok(Buffer.compare(sourceBytes, sourceBytesAfter) === 0, '迁移后 V2 源文件字节必须与快照完全一致——迁移不修改源工件字节');
+    console.log(`SESSION V3 MIGRATION PROOF: V2 source ${sourceBytes.length}B (${v2Events.length} events) on disk → ` +
+        `current V4(${artifact.events.length} events, +system/message), successor ${successorJsonl.length}B reopens as current ` +
+        `and fully decodes (${successorArtifact.events.length} events), source bytes unchanged after migration`);
+}
+finally {
+    rmSync(tmp, { recursive: true, force: true });
+}