dsh-log-contract 0.3.11 → 0.3.13

package/lib/validate.js

@@ -3,11 +3,15 @@
  *
  * 离线体检引擎：对 `loadSessionLog` 的结果逐条跑契约规则，产出违规报告。
  *
- * 判定哲学（复盘事故 §四-1）：**持久化层以官方 `foldSurface` 不抛为通过**，
+ * 判定哲学（复盘事故 §四-1）：**持久化层以 fold 不抛为通过**，
  * 但为定位问题，先用与官方同语义的增量重放做逐事件归因（S1–S7），
- * 再跑官方 foldSurface 作终验（S8）——两套都绿才算过。
+ * 再跑 fold 终验（S8）——两套都绿才算过。
+ * 终验按**被检文件 header.version** 选：v3 → 运行时官方 `foldSurface`；
+ * v0/v1/v2 → 本地等价实现 `legacyFoldSurface`（0.1.5 的 foldSurface 是 v3 语义，对旧格式会误报）。
  */
 import { ruleById } from './contracts.js';
+import { normalizeEventSeqRanges } from './compat.js';
+import { HOST_MAX_FILE_VERSION, MIGRATION_TARGET_VERSION, hostCapability, isAssessableFileVersion } from './vocab.js';
 import {
   CHUNK_ROW_TYPES,
   envelopeViolations,
@@ -16,6 +20,7 @@ import {
   finalFold,
   inboxReplayViolations,
   isSafeInt,
+  migrationPrecheckViolations,
   nullTurnStepViolations,
   physicalOrderViolations,
   pluginViolations,
@@ -30,6 +35,9 @@ import {
   wireViolations,
 } from './checks.js';
 
+/** 宿主能力闸触发时**跳过**的规则（v3/被检版本语义相关）——报告里显式列出，避免"静默通过"。 */
+const VERSION_DEPENDENT_RULES = ['E3', 'E7', 'S1', 'S2', 'S3', 'S4', 'S5', 'S6', 'S7', 'S8', 'W1', 'W2', 'T1', 'T2', 'T3', 'T4', 'T5', 'G1', 'G2'];
+
 /**
  * 对会话日志执行全量离线体检。
  *
@@ -45,7 +53,23 @@ import {
 export function validateSessionLog(log, opts = {}) {
   const { baseSeq = 0 } = opts;
   const violations = [];
-  const { header, headerLine, rows, events, frameInfo } = log;
+  const { header, headerLine, rows, frameInfo } = log;
+  // C1 防御（多入口一致）：即使调用方手搓 log 对象、未经 `loadSessionLog`，也在体检入口
+  // 归一一次 v3 区间编码。正常路径（loadSessionLog 已展开）下这是幂等的恒等映射。
+  const events = (log.events ?? []).map((e) => ({ ...e, event: normalizeEventSeqRanges(e.event) }));
+  // 1.3 第二半：词表/折叠路径按**被检文件自身版本**选择（不按运行时）。
+  // C2：版本是**本次调用的局部量**，显式传给每条按版本择路的判定——不再写模块级全局
+  // （旧实现 `setFileFormatVersion()` 会被同进程后调用的 prewrite 读到，造成结论翻转）。
+  const formatVersion = Number.isSafeInteger(header?.version) && header.version >= 0 ? header.version : 0;
+
+  // ── 宿主能力闸（S2·安全）──────────────────────────────────────────────────
+  // 被检文件版本 > 本宿主支持的最大文件版本 ⇒ 本宿主没有该版本的词表/折叠语义。继续按
+  // 本宿主语义判定会产出**假阳性**（独立复核实测：rc.7 上同一真实 v3 文件 →
+  // `S8×1 + E3×40 / verdict=broken / loadable:false`），危险是用户以为日志坏了去跑
+  // `fix --apply`。改为：只跑与版本无关的结构检查 + 显式"不可在本宿主评估"档。
+  if (!isAssessableFileVersion(formatVersion)) {
+    return unassessableResult({ header, headerLine, rows, events, frameInfo, baseSeq, formatVersion });
+  }
 
   // ── Z · 帧结构 ─────────────────────────────────────────────────────────
   if (frameInfo?.torn) {
@@ -62,8 +86,8 @@ export function validateSessionLog(log, opts = {}) {
     if (header.type !== 'session') {
       violations.push(violation('H1', { lineNo: headerLine }, `首行 type 必须为 "session"（实际 ${String(header.type)}）`));
     }
-    if (header.version !== 0) {
-      violations.push(violation('H2', { lineNo: headerLine }, `header.version 必须为 0（实际 ${String(header.version)}）——格式版本演进无迁移机制（F1）`));
+    if (![0, 1, 2, 3].includes(header.version)) {
+      violations.push(violation('H2', { lineNo: headerLine }, `header.version 未知（实际 ${String(header.version)}）——已知 0/1/2/3；未知版本按 0 处理会误判，请先确认格式`));
     }
     if (typeof header.id !== 'string' || header.id === '') {
       violations.push(violation('H2', { lineNo: headerLine }, 'header.id 必须为非空字符串'));
@@ -100,7 +124,7 @@ export function validateSessionLog(log, opts = {}) {
   let seqBroken = false;
   for (const { event, lineNo } of events) {
     const loc = { seq: event.seq, lineNo, eventType: event.type };
-    violations.push(...envelopeViolations(event, loc));
+    violations.push(...envelopeViolations(event, loc, formatVersion));
     if (typeof event.seq === 'number' && Number.isSafeInteger(event.seq) && event.seq >= 0) {
       if (event.seq !== expectedSeq) {
         const kind = event.seq < expectedSeq ? '倒退（backward）' : '缺口（gap）';
@@ -117,10 +141,10 @@ export function validateSessionLog(log, opts = {}) {
   violations.push(...physicalOrderViolations(rows));
 
   // ── S · surface 增量重放（归因）+ 官方 foldSurface 终验 ────────────────
-  const replay = replaySurface(events);
+  const replay = replaySurface(events, formatVersion);
   violations.push(...replay.violations);
 
-  const folded = finalFold(events.map((e) => e.event));
+  const folded = finalFold(events.map((e) => e.event), formatVersion);
 
   // ── T · token meter 配对（事故根因 3 + 2026-08-30 两类刷屏）──
   violations.push(...tokenMeterViolations(events));
@@ -133,7 +157,7 @@ export function validateSessionLog(log, opts = {}) {
   violations.push(...turnEndReasonViolations(events));
 
   // ── E7 · ignorable 未知 type 合法性（反向挑刺 T2）────────────────────
-  violations.push(...ignorableTypeViolations(events));
+  violations.push(...ignorableTypeViolations(events, formatVersion));
 
   // ── I1 · inbox seed 相对重放（fork 边界孤儿；交接书 L1）──────────────
   violations.push(...inboxReplayViolations(events, header));
@@ -142,11 +166,11 @@ export function validateSessionLog(log, opts = {}) {
   violations.push(...toolPairingViolations(events));
   violations.push(...toolResultStructureViolations(events));
   if (folded.error) {
-    violations.push(violation('S8', { lineNo: null }, `官方 foldSurface 重放失败：${folded.error.message} —— 会话加载会被拒（SessionPersistenceCorruptionError）`));
+    violations.push(violation('S8', { lineNo: null }, `foldSurface 重放失败（按文件版本选：v3 官方 / v0–v2 本地等价）：${folded.error.message} —— 会话加载会被拒（SessionPersistenceCorruptionError）`));
   }
 
   // ── W · wire 消息流（严格端点拒绝的悬空 tool / 顺序破坏）──────────────
-  violations.push(...wireViolations(events));
+  violations.push(...wireViolations(events, formatVersion));
 
   // ── M / P ──────────────────────────────────────────────────────────────
   for (const { event, lineNo } of events) {
@@ -160,6 +184,11 @@ export function validateSessionLog(log, opts = {}) {
     violations.push(violation('C1', { lineNo: null }, 'seq 缺口/倒退是多写入者（≥2 个 Host 进程共享同一 session 目录）并发写的典型后果；离线体检无法观测竞态本身，但此痕迹需人工核查（N6）'));
   }
 
+  // ── G · 迁移预检（**独立维度**：官方升级路径会不会拒；不进 ok/verdict）──────
+  // 官方把 v0/v1/v2 升到当前格式时的规则集比本工具的"读取/折叠"规则集更严：本工具判
+  // ok/compactable **不代表**官方迁移会接受。这里只加 migration 层 warning（见 contracts G1/G2）。
+  violations.push(...migrationPrecheckViolations(events, formatVersion));
+
   // ── 汇总 ───────────────────────────────────────────────────────────────
   violations.sort((a, b) => (a.seq ?? -1) - (b.seq ?? -1) || (a.lineNo ?? -1) - (b.lineNo ?? -1));
   const bySeverity = { error: 0, warning: 0, info: 0 };
@@ -178,14 +207,196 @@ export function validateSessionLog(log, opts = {}) {
     frames: frameInfo?.frames ?? 0,
     compressedBytes: frameInfo?.compressedBytes ?? 0,
     plaintextBytes: frameInfo?.plaintextBytes ?? 0,
+    fileVersion: formatVersion,
+    hostMaxFileVersion: HOST_MAX_FILE_VERSION,
+    assessable: true,
   };
 
-  return {
+  const result = {
     ok: bySeverity.error === 0,
+    assessable: true,
     violations,
     summary,
     surface: folded.surface ?? { nodes: replay.nodes, replacements: [] },
   };
+  result.migration = migrationVerdict(result);
+  result.assessmentScope = result.migration.assessmentScope;
+  return result;
+}
+
+/**
+ * 宿主能力闸的结果（S2）：被检文件版本 > 本宿主支持的最大版本。
+ *
+ * 只跑**与版本无关**的结构检查（Z 帧 / H header / R 行 / E1·E2·E4·E5·E6 信封不含 E3 词表 /
+ * S9 物理序 / M·P / P3·P4 / I1），其余（S1–S8/W/T/E3/E7/G）显式跳过并在 `notAssessable.skippedRules`
+ * 里列出。**ok 固定 false**（不认证），但 `structuralOk` 单独给出结构层结论——
+ * 语义是"本宿主评估不了"，不是"日志坏了"。
+ */
+function unassessableResult({ header, headerLine, rows, events, frameInfo, baseSeq, formatVersion }) {
+  const violations = [];
+  const cap = hostCapability();
+  const notAssessable = {
+    fileVersion: formatVersion,
+    hostMaxFileVersion: HOST_MAX_FILE_VERSION,
+    hostPackage: cap.hostPackage,
+    skippedRules: VERSION_DEPENDENT_RULES,
+    reason: `被检文件 version=${formatVersion} 高于本宿主 @deepseek-ai/dsh-session@${cap.hostPackage} 支持的最大文件版本 ${HOST_MAX_FILE_VERSION}`
+      + `（本宿主只有 ≤${HOST_MAX_FILE_VERSION} 的词表/折叠语义）⇒ 按本宿主语义判定会产出假阳性（如 S8/E3）。`
+      + '这不表示日志损坏；请用 0.1.5+ 宿主评估。',
+  };
+
+  // ── Z · 帧结构（版本无关）──
+  if (frameInfo?.torn) violations.push(violation('Z1', { lineNo: null }, `zstd 尾帧撕裂：可能是写入中的 in-flight 帧或文件被截断（帧数 ${frameInfo.frames}）`));
+  if (frameInfo?.error) violations.push(violation('Z2', { lineNo: null }, frameInfo.error));
+
+  // ── H · header（版本无关）──
+  if (header === null) {
+    violations.push(violation('H1', { lineNo: headerLine }, '首行不是合法 JSON —— 整个会话不可读'));
+  } else {
+    if (header.type !== 'session') violations.push(violation('H1', { lineNo: headerLine }, `首行 type 必须为 "session"（实际 ${String(header.type)}）`));
+    if (![0, 1, 2, 3].includes(header.version)) violations.push(violation('H2', { lineNo: headerLine }, `header.version 未知（实际 ${String(header.version)}）`));
+    if (typeof header.id !== 'string' || header.id === '') violations.push(violation('H2', { lineNo: headerLine }, 'header.id 必须为非空字符串'));
+    if (!Number.isSafeInteger(header.createdAt) || header.createdAt < 0) violations.push(violation('H2', { lineNo: headerLine }, 'header.createdAt 必须为非负安全整数'));
+    if (header.cwd !== undefined && (typeof header.cwd !== 'string' || !header.cwd.startsWith('/'))) violations.push(violation('H2', { lineNo: headerLine }, 'header.cwd 若存在必须为绝对路径'));
+    if (header.origin !== undefined && header.origin !== 'subagent') violations.push(violation('H2', { lineNo: headerLine }, `header.origin 只能为 "subagent"（实际 ${String(header.origin)}）`));
+  }
+  if (header !== null && events.length === 0) violations.push(violation('Z3', { lineNo: headerLine }, '会话文件无任何事件（仅 header）——异常空会话'));
+
+  // ── R · 存储行（版本无关）──
+  for (const row of rows) {
+    if (row.error && row.value === null) violations.push(violation('R1', { lineNo: row.lineNo }, '该行不是合法 JSON（损坏行）'));
+    else if (row.error && CHUNK_ROW_TYPES.has(row.value?.type)) violations.push(violation('R2', { lineNo: row.lineNo }, `chunk 行 "${row.value.type}" 损坏：${row.error.message}`));
+  }
+
+  // ── E · 信封 + seq（E3 词表判定**跳过**：词表随被检版本而变，本宿主没有该版本词表）──
+  let expectedSeq = baseSeq;
+  let seqBroken = false;
+  for (const { event, lineNo } of events) {
+    const loc = { seq: event.seq, lineNo, eventType: event.type };
+    violations.push(...envelopeViolations(event, loc, formatVersion).filter((v) => v.id !== 'E3'));
+    if (typeof event.seq === 'number' && Number.isSafeInteger(event.seq) && event.seq >= 0) {
+      if (event.seq !== expectedSeq) {
+        violations.push(violation('E2', loc, `seq ${event.seq} 不连续：${event.seq < expectedSeq ? '倒退（backward）' : '缺口（gap）'}，期望 ${expectedSeq}`));
+        seqBroken = true;
+        expectedSeq = event.seq + 1;
+      } else expectedSeq = event.seq + 1;
+    }
+  }
+  violations.push(...physicalOrderViolations(rows));
+  violations.push(...inboxReplayViolations(events, header));
+  violations.push(...toolPairingViolations(events));
+  violations.push(...toolResultStructureViolations(events));
+  for (const { event, lineNo } of events) {
+    const loc = { seq: event.seq, lineNo, eventType: event.type };
+    violations.push(...engineViolations(event, loc));
+    violations.push(...pluginViolations(event, loc));
+  }
+  if (seqBroken) violations.push(violation('C1', { lineNo: null }, 'seq 缺口/倒退是多写入者并发写的典型后果（N6）'));
+
+  violations.sort((a, b) => (a.seq ?? -1) - (b.seq ?? -1) || (a.lineNo ?? -1) - (b.lineNo ?? -1));
+  const bySeverity = { error: 0, warning: 0, info: 0 };
+  const byLayer = {};
+  for (const v of violations) {
+    bySeverity[v.severity] = (bySeverity[v.severity] ?? 0) + 1;
+    byLayer[v.layer] = (byLayer[v.layer] ?? 0) + 1;
+  }
+  const result = {
+    ok: false,                 // 不认证（**不是**"broken"——语义见 notAssessable.reason）
+    assessable: false,
+    structuralOk: bySeverity.error === 0,
+    notAssessable,
+    violations,
+    summary: {
+      total: violations.length,
+      bySeverity,
+      byLayer,
+      events: events.length,
+      surfaceNodes: null,
+      replaceGeneration: null,
+      frames: frameInfo?.frames ?? 0,
+      compressedBytes: frameInfo?.compressedBytes ?? 0,
+      plaintextBytes: frameInfo?.plaintextBytes ?? 0,
+      fileVersion: formatVersion,
+      hostMaxFileVersion: HOST_MAX_FILE_VERSION,
+      assessable: false,
+    },
+    surface: null,
+  };
+  result.migration = migrationVerdict(result);
+  result.assessmentScope = result.migration.assessmentScope;
+  return result;
+}
+
+/**
+ * 迁移预检结论（S1）——**独立维度**：官方把 v0/v1/v2 升到当前格式会不会拒。
+ *
+ * 与 `ok` / `loadable` / `resumable` / `compactable` **并列且互不蕴含**：
+ * 本工具判 ok **不代表**官方迁移会接受（反之亦然）。只统计 `layer === 'migration'` 的违规
+ * （G1/G2），并**显式声明覆盖边界**——未覆盖的官方迁移规则不等于通过。
+ *
+ * @param {object} result `validateSessionLog()` 的返回值
+ */
+export function migrationVerdict(result) {
+  const violations = result?.violations ?? [];
+  const fileVersion = result?.summary?.fileVersion ?? result?.notAssessable?.fileVersion ?? null;
+  const coverage = {
+    implemented: [
+      'G1  v0 源：subagent/descriptor.data.version !== 3',
+      'G2  v0 源：事件类型不在官方 v0 dispositions 内（含 ignorable:true）',
+      'G3  v0 源：session/title 系列 messageSeqs 必须引用更早的人类 user/message（含"空 ⟺ 用户标题"）',
+    ],
+    uncovered: [
+      // 2026-09-15 第五轮：`turn/start` 试做后在**真实语料**上被判定为"应用对象错"——
+      // 官方状态机（assertReleasedArtifactRelationships）由 v1→v2 在**变换后的 v1/v2 artifact**
+      // 上调用（v1-to-v2/lib/index.js:104），带 cut/继承切点处理；在原始 v0 上照抄会在已 seed
+      // 的会话上狂报（样本 session-62c5b531：0.1.5 链并不以该规则拒它，原始 v0 上会报 19 条）。
+      // ⇒ 忠实复现需先做 v0→v1→v2 变换；本轮不做，保持未覆盖。
+      'turn/start 闭合/预期轮（官方 v1→v2 在**变换后** artifact 上判：does not close the prior turn / does not open expected turn）',
+      'assistant/attempt 配对/闭合（migration refuses the transformed artifact）',
+      'Session inheritedEventCut / 继承切点（官方在变换后 artifact 上按 cut 判；header 只有 seedLength）',
+      'stored log corrupt（SessionFormatError）',
+      'v0→v1 对其余事件的形状拒绝',
+      'turn/end 无匹配 open turn / open step 穿越 / 未解析 tool / open compaction 穿越（官方同一状态机的其余分支）',
+    ],
+    note: '未覆盖 ≠ 通过：本维度只对 implemented 三条负责。官方判据版本：@deepseek-ai/dsh-session-format-v0-to-v1@0.1.5-rc.2 + v1-to-v2@0.1.5-rc.2',
+  };
+  if (result?.assessable === false) {
+    return { assessable: false, applies: null, ready: null, fileVersion, blocked: [], coverage, assessmentScope: 'none', reason: result?.notAssessable?.reason ?? null };
+  }
+  const blocked = violations.filter((v) => v.layer === 'migration');
+  if (fileVersion !== null && fileVersion === MIGRATION_TARGET_VERSION) {
+    return { assessable: true, applies: false, ready: null, fileVersion, targetFileVersion: MIGRATION_TARGET_VERSION, blocked, coverage, assessmentScope: 'full', reason: `被检文件已是当前官方格式（version=${fileVersion}），无需迁移` };
+  }
+  const applies = fileVersion !== null && fileVersion < MIGRATION_TARGET_VERSION;
+  return {
+    assessable: true,
+    applies,
+    ready: applies ? blocked.length === 0 : null,
+    fileVersion,
+    targetFileVersion: MIGRATION_TARGET_VERSION,
+    hostMaxFileVersion: HOST_MAX_FILE_VERSION,
+    blocked,
+    coverage,
+    // 2026-09-14 第四轮（最终复核）：待迁移文件（applies=true）**只**被 2 条 G 规则覆盖，
+    // 另有 6 类官方迁移规则未覆盖 ⇒ 评估范围只能是 "partial"。工具无法逐文件知道
+    // 本文件是否命中未覆盖类（那要先把 6 类实现出来或跑官方迁移），但它**知道**这件事。
+    assessmentScope: applies ? 'partial' : 'full',
+  };
+}
+
+/**
+ * 评估范围（S1 收窄后的机器可判字段）。
+ * - `'partial'`：被检文件需要迁移（`migration.applies === true`）⇒ 迁移维度只覆盖 2 条规则，
+ *   另有 6 类未覆盖；`ok`/`loadable`/`compactable` **不构成**"官方升级会接受"。
+ * - `'full'`：被检文件已是当前官方格式（无需迁移）⇒ 迁移维度不适用，结构维度为全集。
+ * - `'none'`：本宿主能力不足以评估该文件版本（S2 闸）⇒ 不给任何档位结论。
+ * @param {object} result `validateSessionLog()` 的返回值
+ * @returns {'full'|'partial'|'none'}
+ */
+export function assessmentScope(result) {
+  return result?.migration?.assessmentScope
+    ?? result?.assessmentScope
+    ?? migrationVerdict(result).assessmentScope;
 }
 
 /**
@@ -202,13 +413,30 @@ export function validateSessionLog(log, opts = {}) {
  *
  * @param {{ok: boolean, violations: Array, summary: object}} result validateSessionLog 的返回值
  * @returns {{
- *   verdict: 'loadable' | 'resumable' | 'compactable' | 'broken',
+ *   verdict: 'loadable' | 'resumable' | 'compactable' | 'broken' | 'not-assessable',
+ *   assessable: boolean,
  *   loadable: boolean, resumable: boolean, compactable: boolean,
+ *   migration: object,
  *   blocking: { loadable: Array, resumable: Array, compactable: Array },
  * }}
  */
 export function resumeVerdict(result) {
   const { ok, violations = [] } = result;
+  // 宿主能力闸（S2）：本宿主评估不了 ⇒ 新档位 `not-assessable`（**不是** broken）。
+  // 三档 loadable/resumable/compactable 一律 false（不认证），原因在 notAssessable.reason。
+  if (result?.assessable === false) {
+    return {
+      verdict: 'not-assessable',
+      assessable: false,
+      loadable: false,
+      resumable: false,
+      compactable: false,
+      notAssessable: result.notAssessable ?? null,
+      migration: result.migration ?? migrationVerdict(result),
+      blocking: { loadable: [], resumable: [], compactable: [] },
+      violationsByTier: { structural: [], inbox: [], tokenMeter: [] },
+    };
+  }
   // 三档各自的「阻断规则集」——按任务书 §L3 档位定义：
   //   可加载：结构层（PERSISTENCE/FRAMING）+ 引擎层非 I1/T1/T2/T3/T4 的 error；
   //   可继续：+ I1（inbox 重放）；
@@ -241,9 +469,11 @@ export function resumeVerdict(result) {
 
   return {
     verdict,
+    assessable: true,
     loadable,
     resumable,
     compactable,
+    migration: result.migration ?? migrationVerdict(result),
     blocking: {
       loadable: [...new Set(loadableBlockers)],
       resumable: resumableBlockers,

package/lib/vocab.js

@@ -0,0 +1,193 @@
+/**
+ * dsh-log-contract · lib/vocab.js —— **按被检文件自身版本选词表与折叠路径**（1.3 第二半，engineer comm-369 裁定）
+ *
+ * 背景（一手实测）：同一健康会话，在**生产 0.1.1 解析**下 0 违规，在 **0.1.5 解析**下 3606 违规——
+ * 根因是本包原先用**运行时导出**的 `KNOWN_SESSION_EVENT_TYPES` / `foldSurface` 去判**旧格式(v0)文件**：
+ * 官方 0.1.5 的词汇表已不含 `assistant/chunk`（v0 词表 51 条里**有**），于是每个 chunk 事件被 E3 误报。
+ * 裁定原文（comm-369 §二）：**"判据必须来自文件自身的版本，不是判官(运行时)的版本"**。
+ *
+ * 2026-09-14 复核补强（同一裁定的完整落地）——一手证据：
+ * 1. **0.1.5 的 `foldSurface` 不是"放宽"，而是换成了 v3 语义**（对照 `dsh-session@0.1.0-rc.7`
+ *    与 `0.1.5-rc.1` 的 `isReplaceOp` / `assertProvenance`）：
+ *    - replace 字段改名：rc.7 `{op,start,end}`（`lib/index.js:300-303`）→ 0.1.5 `{op,startSeq,endSeq}`
+ *      （`lib/index.js:279`）；旧 marker 在 0.1.5 直接 “carries an invalid replace surfaceOp”；
+ *    - 0.1.5 `lib/index.js:285` 起 `assistant/message` **一律**不得携带 `sourceEventSeqs`
+ *      （“embeds its source stream”）；rc.7 允许（空数组仅限 assistant/message）。
+ *    ⇒ 0.1.5 的 `foldSurface` **只能**终验 v3 文件；v0/v1/v2 用它会误报，必须走本地等价实现
+ *      （`./legacy-fold.js`，rc.7 `foldSurface` 逐条移植、同样 fail-loud）。
+ * 2. **版本边界是 v3，不是 v2**：App 2.0.9 内置 `dsh-session-format-v2-to-v3`，其
+ *    `lib/index.js:361-371` 明示 v2 仍是 `{start,end}`、由迁移改名为 `startSeq/endSeq`
+ *    ⇒ v2 属于"旧格式"。App 内置 `SESSION_FORMAT_VERSION = 3` 并带 v0→v1→v2→v3 三个迁移包。
+ * 3. **顶层 chunk 行只在旧格式里存在**：App 2.0.9 的真实持久化层
+ *    `dsh-session-persistence-jsonl@0.1.5-rc.1/lib/worker.cjs:4237-4280` 把 chunk run 内嵌进
+ *    `assistant/attempt.data.stream`（紧凑记录 `{type,time0,index,dt,texts}`，**无 seq0/turn/step**），
+ *    不再写顶层 `text-chunks` 行；v0/v1/v2 才用顶层行（`dsh-session/lib/types/chunk-rows.js`）。
+ *    ⇒ v3 词表**不**需要 `assistant/chunk`（官方 `KNOWN_SESSION_EVENT_TYPES` 原样即正确）；
+ *      v2 需要 `assistant/attempt`（官方 v2 dispositions = v0 − assistant/chunk + assistant/attempt）。
+ *
+ * 形态：
+ * - 文件版本 0/1 → **vendored v0 词表**（来源：App 内置 `dsh-session-format-v0-to-v1` 的
+ *   `RELEASED_V0_EVENT_DISPOSITIONS`，51 条，逐条比对零差异）；
+ * - 文件版本 2 → (v0 词表 − `assistant/chunk`) ∪ {`assistant/attempt`}（官方 v2 dispositions
+ *   构造式实测：chunk 被显式剔除；见 `V2_EVENT_TYPES` 注释）；
+ * - 文件版本 3 → **运行时导出**的 `KNOWN_SESSION_EVENT_TYPES`；
+ * - 折叠终验：v0/v1/v2 → `legacyFoldSurface`；v3 → 运行时 `foldSurface`。
+ */
+import { foldSurface, KNOWN_SESSION_EVENT_TYPES, SESSION_FORMAT_VERSION } from '@deepseek-ai/dsh-session';
+import { createRequire } from 'node:module';
+import { legacyFoldSurface } from './legacy-fold.js';
+
+/** v0/v1 词表（vendored；来源见文件头注释，与官方 v0 dispositions 逐条对应）。 */
+export const V0_EVENT_TYPES = new Set([
+  'agent-preset/selected', 'agent/inbox/spliced', 'approval/asked', 'approval/decided', 'approval/policy',
+  'assistant/chunk', 'assistant/message', 'command/done', 'command/run', 'compaction/end', 'compaction/prune',
+  'compaction/start', 'compaction/summary', 'feedback/record', 'goal/change', 'hook/invoked', 'hook/result',
+  'llm/retry', 'llm/retry-started', 'model/selection', 'permission/preset', 'plan/mode', 'request/context',
+  'request/header', 'sandbox/mode', 'schedule/change', 'session-log-deepseek/delivery-accepted',
+  'session/end-seed', 'session/title', 'session/title-llm-request', 'step/end', 'step/start',
+  'subagent/descriptor', 'subagent/model-selection-policy', 'team/member', 'team/message/delivered',
+  'team/message/queued', 'team/task', 'todo/write', 'tool-workflow/agent-end', 'tool-workflow/agent-start',
+  'tool-workflow/run-end', 'tool-workflow/run-start', 'tool/call', 'tool/code-dispatch',
+  'tool/code-dispatch-start', 'tool/result', 'turn/end', 'turn/start', 'user/message',
+  'web/deepseek-search-llm-request',
+]);
+
+/**
+ * v2 词表（官方 `RELEASED_V2_EVENT_DISPOSITIONS` 推导；App 2.0.9 内置
+ * `dsh-session-format-v2-to-v3` 的构造式逐字实测）：
+ *   retained = v0 − {assistant/chunk, assistant/message, session-log-deepseek/delivery-accepted, session/end-seed}
+ *   v2 = retained ∪ {assistant/attempt, assistant/message, delivery-accepted, session/end-seed}
+ *      = v0 − assistant/chunk + assistant/attempt
+ * ⇒ **v2 不含 `assistant/chunk`**（旧实现误用 `V0 ∪ {attempt}`，把 chunk 留在 v2 词表里 =
+ * 宽松口径，会漏报 v2 里的顶层 chunk 行 ⇒ F9 修正）。
+ */
+export const V2_EVENT_TYPES = new Set([
+  ...[...V0_EVENT_TYPES].filter((t) => t !== 'assistant/chunk'),
+  'assistant/attempt',
+]);
+
+/** 旧的顶层 `{start,end}` replace 语义适用的最高文件版本（v3 起改为 `{startSeq,endSeq}`）。 */
+export const LEGACY_FORMAT_MAX_VERSION = 2;
+
+/**
+ * 当前应使用的词表（**必须显式传 version**）。
+ *
+ * 这里**不再有模块级可变全局**：旧实现 `let fileVersion` + `setFileFormatVersion()`（唯一写入点
+ * `validate.js`）会让同一进程里后调用的 prewrite 读到**别人文件**的版本——C2 实测：先
+ * validate(v3) 再 prewrite(v0)，同一份合法 v0 输入的结论从 ok 翻成 S4+S8。改为参数后，
+ * 每个入口各自持有本次被检文件的版本。
+ */
+export function currentVocabulary(version) {
+  if (version <= 1) return V0_EVENT_TYPES;
+  if (version === 2) return V2_EVENT_TYPES;
+  return KNOWN_SESSION_EVENT_TYPES;
+}
+
+/** 当前可用的**终验**折叠：旧格式用本地等价实现，v3 用运行时导出。 */
+export function currentFold(version) {
+  return isLegacyFormat(version) ? legacyFoldSurface : foldSurface;
+}
+
+/** 文件版本是否属于"旧格式"（v0/v1/v2：`{start,end}` replace + 允许 assistant/message 携带 sourceEventSeqs）。 */
+export function isLegacyFormat(version) {
+  return version <= LEGACY_FORMAT_MAX_VERSION;
+}
+
+/**
+ * 从事件形状推断文件版本——调用方只给 `events`、拿不到 header 时的兜底（C2）。
+ * 判据（可靠性从高到低）：
+ *   1. replace 的字段名：v3 `{startSeq,endSeq}` / v0–v2 `{start,end}`（最强，直接决定 S4/S8 路由）；
+ *   2. `system/message`：官方 v3 才有的 surface 类型（V0/V2 词表均无）；
+ *   3. `assistant/chunk`：顶层 chunk 行只在旧格式出现（v2 dispositions 已剔除它）；
+ *   4. `assistant/attempt`：v2 与 v3 都有（v0 无）⇒ 只能推出"≥2"。
+ * 返回 3 / 2 / 0。**这是启发式**；有 `header.version` 或显式 `formatVersion` 时优先用它们。
+ */
+export function inferFormatVersion(events = []) {
+  let sawLegacyReplace = false;
+  let sawModernReplace = false;
+  let sawSystemMessage = false;
+  let sawChunk = false;
+  let sawAttempt = false;
+  for (const event of events) {
+    if (!event || typeof event !== 'object') continue;
+    const op = event.surfaceOp;
+    if (op && typeof op === 'object' && op.op === 'replace') {
+      if (Object.hasOwn(op, 'startSeq') || Object.hasOwn(op, 'endSeq')) sawModernReplace = true;
+      else if (Object.hasOwn(op, 'start') || Object.hasOwn(op, 'end')) sawLegacyReplace = true;
+    }
+    if (event.type === 'system/message') sawSystemMessage = true;
+    else if (event.type === 'assistant/chunk') sawChunk = true;
+    else if (event.type === 'assistant/attempt') sawAttempt = true;
+  }
+  if (sawModernReplace || sawSystemMessage) return 3;
+  if (sawLegacyReplace) return sawAttempt ? 2 : 0;
+  if (sawAttempt) return 2;
+  if (sawChunk) return 0;
+  return 0;
+}
+
+/**
+ * 解析本次校验应使用的文件版本：显式 `formatVersion` > `header.version` > 事件形状推断 > 0。
+ * @param {{formatVersion?:number, header?:object|null, events?:Array}} [input]
+ * @returns {number}
+ */
+export function resolveFormatVersion({ formatVersion, header, events } = {}) {
+  if (Number.isSafeInteger(formatVersion) && formatVersion >= 0) return formatVersion;
+  if (header && Number.isSafeInteger(header.version) && header.version >= 0) return header.version;
+  return inferFormatVersion(events ?? []);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 宿主能力闸（S2）——**被检文件版本 > 宿主支持的最大版本**时不能按本宿主语义判定。
+// 一手依据：`@deepseek-ai/dsh-session` 导出 `SESSION_FORMAT_VERSION`（rc.7 = 0，0.1.5 = 3），
+// 词表 `KNOWN_SESSION_EVENT_TYPES` 与 `foldSurface` 都随它变。rc.7 上拿 v3 文件跑本包的
+// v3 语义检查会产出**假阳性**（实测 S8×1 + E3×40 / verdict=broken），危险在于用户会以为
+// 日志坏了去跑 `fix --apply`。故此处显式暴露宿主能力，由入口输出"不可在本宿主评估"档。
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** 本宿主支持的最大被检文件版本（= 运行时 `SESSION_FORMAT_VERSION`；缺失按 0）。 */
+export const HOST_MAX_FILE_VERSION = Number.isSafeInteger(SESSION_FORMAT_VERSION) && SESSION_FORMAT_VERSION >= 0
+  ? SESSION_FORMAT_VERSION
+  : 0;
+
+/**
+ * 官方迁移链的目标格式版本（固定 3）——**不是宿主版本**。
+ * 依据：App 2.0.9 / `@deepseek-ai/dsh-session-format-*@0.1.5-rc.2` 的迁移链是 v0→v1→v2→v3，
+ * `SESSION_FORMAT_VERSION = 3`。迁移预检问的是"升到目标格式会不会被拒"，与当前宿主能不能
+ * 评估 v3 **无关**（rc.7 宿主上同样可以预检一个 v0 文件将来能否升级）。
+ */
+export const MIGRATION_TARGET_VERSION = 3;
+
+let hostVersionMemo;
+/** 宿主 `@deepseek-ai/dsh-session` 的包版本（用于输出/报告；不可解析时给未知标记，不抛）。 */
+export function hostPackageVersion() {
+  if (hostVersionMemo !== undefined) return hostVersionMemo;
+  try {
+    const req = createRequire(import.meta.url);
+    hostVersionMemo = String(req('@deepseek-ai/dsh-session/package.json').version);
+  } catch {
+    hostVersionMemo = `unknown (SESSION_FORMAT_VERSION=${HOST_MAX_FILE_VERSION})`;
+  }
+  return hostVersionMemo;
+}
+
+/** 被检文件版本能否在本宿主上按其自身语义评估。
+ *
+ * 判据（两层）：
+ * - **v0/v1/v2**：本包自带 vendored 词表 + 本地等价折叠（`legacyFoldSurface`），**宿主无关** ⇒ 任何宿主都能评估；
+ * - **v3+**：词表用运行时 `KNOWN_SESSION_EVENT_TYPES`、折叠用运行时 `foldSurface` ⇒
+ *   需要宿主 `SESSION_FORMAT_VERSION >= 该版本`（rc.7 = 0 ⇒ v3 不可评估）。
+ */
+export function isAssessableFileVersion(version) {
+  if (!Number.isSafeInteger(version) || version < 0) return false;
+  if (version <= LEGACY_FORMAT_MAX_VERSION) return true;
+  return version <= HOST_MAX_FILE_VERSION;
+}
+
+/** 宿主能力描述（CLI/--json 共用）。 */
+export function hostCapability() {
+  return {
+    hostPackage: hostPackageVersion(),
+    hostMaxFileVersion: HOST_MAX_FILE_VERSION,
+  };
+}

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "dsh-log-contract",
   "description": "日志契约守护 — DSH session log contract guard: offline health check (CLI) + pre-write validation for DeepSeek Harness session logs",
-  "version": "0.3.11",
+  "version": "0.3.13",
+  "packageManager": "pnpm@11.7.0",
   "type": "module",
   "main": "lib/index.js",
   "bin": {
@@ -27,6 +28,11 @@
     "LICENSE",
     "README.zh.md"
   ],
+  "scripts": {
+    "check": "node scripts/check-syntax.mjs",
+    "test": "vitest run",
+    "prepublishOnly": "node scripts/check-pkg-meta.mjs && pnpm check && pnpm test"
+  },
   "keywords": [
     "dsh",
     "deepseek-harness",
@@ -53,15 +59,11 @@
     "node": ">=22"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh-session": "^0.1.0-rc.7"
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.7 || ^0.1.5-rc.1"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-session": "0.1.0-rc.7",
+    "@deepseek-ai/dsh-session": "0.1.5-rc.1",
     "esbuild": "0.28.2",
     "vitest": "4.1.11"
-  },
-  "scripts": {
-    "check": "node scripts/check-syntax.mjs",
-    "test": "vitest run"
   }
-}
+}