dsh-log-contract 0.3.11 → 0.3.13

package/lib/checks.js

@@ -7,11 +7,20 @@
  * 全部判定与 `@deepseek-ai/dsh-session@0.1.0-rc.7` 官方实现同语义，
  * 每条违规都挂 `lib/contracts.js` 中的规则 id 与官方源码出处。
  */
-import { foldSurface, isJsonValue, isSurfaceEligibleType, KNOWN_SESSION_EVENT_TYPES } from '@deepseek-ai/dsh-session';
+import { isSurfaceEligibleType } from '@deepseek-ai/dsh-session';
+import { isJsonValue } from './compat.js';
+import { currentVocabulary, currentFold, V0_EVENT_TYPES } from './vocab.js';
 import { ruleById } from './contracts.js';
 
 export const SURFACE_TYPES = new Set(['user/message', 'assistant/message', 'tool/result']);
+/** v3 新增 `system/message`（官方 `SURFACE_EVENT_TYPES`，0.1.5 `lib/index.js:149-154`）。 */
+export const MODERN_SURFACE_TYPES = new Set([...SURFACE_TYPES, 'system/message']);
 export const CHUNK_ROW_TYPES = new Set(['text-chunks', 'reasoning-chunks', 'tool-call-chunks']);
+
+/** 当前文件版本适用的 surface 候选类型集（v3 起含 system/message）。version = 被检文件版本。 */
+export function currentSurfaceTypes(version) {
+  return version >= 3 ? MODERN_SURFACE_TYPES : SURFACE_TYPES;
+}
 export const MARKER_PREFIXES = ['retrace', 'message-editor'];
 
 /** 构造一条违规记录。 */
@@ -35,15 +44,15 @@ export function isSafeInt(v) {
   return typeof v === 'number' && Number.isSafeInteger(v) && v >= 0;
 }
 
-/** 事件信封 shape：seq/type/time/data（E1/E3/E4/E5/E6）。 */
-export function envelopeViolations(event, loc) {
+/** 事件信封 shape：seq/type/time/data（E1/E3/E4/E5/E6）。version = 被检文件版本。 */
+export function envelopeViolations(event, loc, version) {
   const out = [];
   if (!isSafeInt(event.seq)) {
     out.push(violation('E1', loc, `事件 seq 缺失或非法（${String(event.seq)}），必须为非负安全整数`));
   }
   if (typeof event.type !== 'string') {
     out.push(violation('E3', loc, `事件缺少 type 字符串（${String(event.type)}）`));
-  } else if (!KNOWN_SESSION_EVENT_TYPES.has(event.type) && event.ignorable !== true) {
+  } else if (!currentVocabulary(version).has(event.type) && event.ignorable !== true) {
     out.push(violation('E3', loc, `type "${event.type}" 不在已知词汇表内且未带 ignorable 标记（可能由更新版本的 harness 写入）`));
   }
   if (!isJsonValue(event.data)) {
@@ -112,7 +121,7 @@ export function messageShapeViolations(event, loc) {
   return out;
 }
 
-/** replace 操作数精确形状（镜像 isReplaceOp，lib/index.js:300-303）。 */
+/** replace 操作数精确形状（镜像旧格式 isReplaceOp，lib/index.js:300-303）。 */
 export function isReplaceOp(op) {
   return (
     typeof op === 'object' && op !== null &&
@@ -122,6 +131,29 @@ export function isReplaceOp(op) {
   );
 }
 
+/**
+ * 按**被检文件版本**归一化 replace 操作数到内部 `{start,end}`。
+ *
+ * 一手依据：官方 replace 字段在 v3 改名——旧格式（v0/v1/v2）`{op,start,end}`，
+ * v3 `{op,startSeq,endSeq}`（`dsh-session-format-v2-to-v3/lib/index.js:361-371`）。
+ * 用错形状会得 null，由调用方归因为 S4（真实违规）。
+ *
+ * @param {unknown} op 待归一化的 surfaceOp
+ * @returns {{start:number,end:number}|null}
+ */
+export function normalizeReplaceOp(op, version) {
+  if (typeof op !== 'object' || op === null || Array.isArray(op)) return null;
+  if (Object.keys(op).length !== 3 || op.op !== 'replace') return null;
+  if (version >= 3) {
+    return Object.hasOwn(op, 'startSeq') && Object.hasOwn(op, 'endSeq') && isSafeInt(op.startSeq) && isSafeInt(op.endSeq)
+      ? { start: op.startSeq, end: op.endSeq }
+      : null;
+  }
+  return Object.hasOwn(op, 'start') && Object.hasOwn(op, 'end') && isSafeInt(op.start) && isSafeInt(op.end)
+    ? { start: op.start, end: op.end }
+    : null;
+}
+
 /**
  * S9 —— 文件物理序 seq 单调（2026-08-30 事故固化；交接书 L2）。
  *
@@ -157,14 +189,14 @@ export function physicalOrderViolations(rows) {
  * 与官方同语义的 surface 增量重放，逐事件归因 S1–S7。
  * @param {Array<{event:object, lineNo?:number}>} events 按日志顺序的事件（带 loc 包装）
  */
-export function replaySurface(events) {
+export function replaySurface(events, version) {
   const violations = [];
   const nodes = [];
   let replaceGeneration = 0;
 
   for (const { event, lineNo } of events) {
     const loc = { seq: event.seq, lineNo, eventType: event.type };
-    const eligible = SURFACE_TYPES.has(event.type);
+    const eligible = currentSurfaceTypes(version).has(event.type);
     const op = event.surfaceOp;
     const src = event.sourceEventSeqs;
 
@@ -185,18 +217,19 @@ export function replaySurface(events) {
       continue;
     }
 
-    if (!isReplaceOp(op)) {
-      violations.push(violation('S4', loc, 'replace 操作数必须精确为 {op:"replace", start, end}（start/end 为非负安全整数）'));
+    const normalized = normalizeReplaceOp(op, version);
+    if (normalized === null) {
+      violations.push(violation('S4', loc, 'replace 操作数必须精确为 {op:"replace", start, end}（v0/v1/v2）或 {op:"replace", startSeq, endSeq}（v3），且端点为非负安全整数'));
       continue;
     }
-    const startIdx = nodes.indexOf(op.start);
-    const endIdx = nodes.indexOf(op.end);
+    const startIdx = nodes.indexOf(normalized.start);
+    const endIdx = nodes.indexOf(normalized.end);
     if (startIdx === -1 || endIdx === -1) {
-      violations.push(violation('S4', loc, `replace 范围 ${op.start}..${op.end} 不在当前 surface 中（start 存在=${startIdx !== -1}，end 存在=${endIdx !== -1}）`));
+      violations.push(violation('S4', loc, `replace 范围 ${normalized.start}..${normalized.end} 不在当前 surface 中（start 存在=${startIdx !== -1}，end 存在=${endIdx !== -1}）`));
       continue;
     }
     if (startIdx > endIdx) {
-      violations.push(violation('S4', loc, `replace start ${op.start}（index ${startIdx}）在 end ${op.end}（index ${endIdx}）之后`));
+      violations.push(violation('S4', loc, `replace start ${normalized.start}（index ${startIdx}）在 end ${normalized.end}（index ${endIdx}）之后`));
       continue;
     }
     const shadowedSeqs = nodes.slice(startIdx, endIdx + 1);
@@ -287,10 +320,19 @@ export function pluginViolations(event, loc) {
   return out;
 }
 
-/** 官方 foldSurface 终验；不抛返回折叠结果，抛则返回 { error }。 */
-export function finalFold(events) {
+/** 折叠终验：**按文件版本**择路（1.3 第二半 + 2026-09-14 复核补强）。
+ *
+ * - v3 文件 → 运行时导出的官方 `foldSurface`（与运行时同语义）；
+ * - v0/v1/v2 文件 → 本地 `legacyFoldSurface`（rc.7 `foldSurface` 逐条移植）。
+ *
+ * 为什么旧格式不能借用官方实现的 `violations` 字段：官方 `foldSurface` **只抛不报**，
+ * 旧口径下这里曾回退到 `replaySurface` 的 violations，但**没有任何调用方读它**
+ * （validate.js / prewrite.js 只看 `folded.error`）⇒ S8 在旧格式上永不触发——这正是
+ * 2026-09-14 六条失败里四条的真因。现在两条路径都是"抛错 = 拒绝"的同一种契约。 */
+export function finalFold(events, version) {
+  const fold = currentFold(version);
   try {
-    return { surface: foldSurface(events) };
+    return { surface: fold(events) };
   } catch (err) {
     return { error: err };
   }
@@ -405,11 +447,11 @@ function isKnownIgnorableType(type) {
   if (KNOWN_IGNORABLE_CONSUMERS.has(type)) return true
   return type.startsWith('message-editor/') || type.startsWith('retrace/')
 }
-export function ignorableTypeViolations(events) {
+export function ignorableTypeViolations(events, version) {
   const out = []
   for (const { event, lineNo } of events) {
     if (typeof event?.type !== 'string' || event.ignorable !== true) continue
-    if (KNOWN_SESSION_EVENT_TYPES.has(event.type)) continue
+    if (currentVocabulary(version).has(event.type)) continue
     if (isKnownIgnorableType(event.type)) continue
     out.push(violation('E7', { seq: event.seq, lineNo, eventType: event.type }, `type "${event.type}" 不在已知词汇表且带 ignorable 标记、无已知消费者——被读路径接纳但无人消费 = 静默垃圾（ignorable 后门；若你的插件消费它，登记到 KNOWN_IGNORABLE_CONSUMERS）`))
   }
@@ -685,20 +727,21 @@ export function deriveWireMessage(event) {
  * @param events - 展开后的完整事件流（含 chunk 展开）。
  * @returns 违规列表。
  */
-export function wireViolations(events) {
+export function wireViolations(events, version) {
   const out = [];
   // 先折叠 surface（append 入列；replace 移除 [start..end] 并将 marker 自身入列）
   const nodes = [];
   const bySeq = new Map();
   for (const { event, lineNo } of events) {
     bySeq.set(event.seq, { event, lineNo });
-    if (!SURFACE_TYPES.has(event.type)) continue;
+    if (!currentSurfaceTypes(version).has(event.type)) continue;
     const op = event.surfaceOp;
     if (op === 'append') {
       nodes.push(event.seq);
-    } else if (op && isReplaceOp(op)) {
-      const s = nodes.indexOf(op.start);
-      const e = nodes.indexOf(op.end);
+    } else if (op !== undefined) {
+      const normalized = normalizeReplaceOp(op, version);
+      const s = normalized === null ? -1 : nodes.indexOf(normalized.start);
+      const e = normalized === null ? -1 : nodes.indexOf(normalized.end);
       if (s !== -1 && e !== -1 && s <= e) nodes.splice(s, e - s + 1, event.seq);
       else nodes.push(event.seq);
     }
@@ -740,3 +783,88 @@ export function wireViolations(events) {
   }
   return out;
 }
+
+/**
+ * G · 迁移预检（payload 层 + 类型层）——**官方迁移会不会拒**，与"本工具能否读取/折叠"是
+ * **两个独立维度**（见 contracts.js 的 LAYER.MIGRATION 段）。
+ *
+ * 覆盖（每条都有一手出处，官方 `@0.1.5-rc.2`）：
+ * - **G1** `subagent/descriptor.data.version !== 3`
+ * - **G2** 事件类型不在官方 v0 dispositions 内（含 `ignorable:true`）
+ * - **G3** `session/title` / `session/title-llm-request` 的 `messageSeqs`（`v0-to-v1/lib/index.js:2543-2556`）
+ *
+ * 仍未覆盖（由 `migrationVerdict().coverage.uncovered` 显式列出，**不许**当通过）：
+ * `turn/start`（闭合/预期轮）、继承切点、`assistant/attempt` 配对、`stored log corrupt`、
+ * v0→v1 对其余事件的形状拒绝。
+ *
+ * **为什么 `turn/start` 不做（第五轮实测结论）**：官方那个状态机（`v0-to-v1:2270` 的
+ * `assertReleasedArtifactRelationships`）**不是**在原始 v0 事件上跑的——它由 **v1→v2**
+ * 以 `RELEASED_V2_RELATIONSHIP_EXTENSIONS` 调用在**变换后的 v1/v2 artifact** 上
+ * （`v1-to-v2/lib/index.js:104`），并带 `cut`（继承切点）处理。第五轮实测：在原始 v0 上照抄该
+ * 状态机会在**已 seed 的会话**上狂报（样本 `session-62c5b531`：v0→v1 官方并不以该规则拒绝，
+ * 而原始 v0 上会报 19 条），属"规则文本对、应用对象错"。要忠实复现必须先把 v0→v1→v2 的
+ * 变换做出来 ⇒ 记未覆盖。
+ *
+ * 范围：三条都只约束 **v0 源文件**（官方 v0→v1 迁移的规则；v1/v2 源走别的迁移代码）。
+ * severity 固定 warning、layer 固定 migration ⇒ 不进 ok / loadable / resumable / compactable。
+ *
+ * @param {Array<{event:object, lineNo?:number}>} events 已展开事件（带 loc 包装）
+ * @param {number} version 被检文件版本
+ */
+export function migrationPrecheckViolations(events, version) {
+  const out = [];
+  if (version !== 0) return out;
+  for (const { event, lineNo } of events) {
+    if (!event || typeof event !== 'object') continue;
+    if (event.type === 'subagent/descriptor') {
+      const dv = event.data?.version;
+      if (dv !== 3) {
+        out.push(violation('G1', { seq: event.seq, lineNo, eventType: event.type },
+          `subagent/descriptor data.version=${JSON.stringify(dv)}（官方 v0→v1 迁移要求 === 3）—— 升级到当前格式时官方会拒绝：subagent/descriptor ${event.seq} uses unsupported descriptor version ${String(dv)}`));
+      }
+    }
+    if (typeof event.type === 'string' && !V0_EVENT_TYPES.has(event.type)) {
+      // 官方对"unknown historical event"一律拒（原文 even when ignorable）；E3 的 ignorable
+      // 豁免只作用于**读取路径**，这里不改它，只在迁移维度表达。
+      out.push(violation('G2', { seq: event.seq, lineNo, eventType: event.type },
+        `type "${event.type}" 不在官方 v0 dispositions 内${event.ignorable === true ? '（即使 ignorable:true）' : ''}—— 官方迁移会拒：format v0 contains unknown historical event type`));
+    }
+  }
+  // ── G3 · session/title 系列 messageSeqs（官方 v0→v1 `assertTitleSources`，:2543-2556）──
+  // 判据：每个被引 seq 必须解析到更早的 `user/message`，且 `data.source.kind === 'user'`；
+  // 另 `session/title` 的 `source.kind === 'user'` ⟺ `messageSeqs` 空。
+  //
+  // ⚠️ 应用面说明（第五轮实测，2026-09-15）：官方 `assertTitleSources` 与 `turn/start` 状态机
+  //    同在 `assertReleasedArtifactRelationships` 里，而该函数被 **v1→v2** 以
+  //    `RELEASED_V2_RELATIONSHIP_EXTENSIONS` 调用在**变换后的 v1/v2 artifact** 上
+  //    （`dsh-session-format-v1-to-v2/lib/index.js:104`），不是原始 v0 事件。
+  //    对 `messageSeqs` 这类"按 seq 索引 + 事件类型/source 判定"的引用，变换保序保类型
+  //    ⇒ 在原始 v0 上判是**必要条件的近似**；实测 281 个真实 v0 上 **0 误报**（round5/rule-probe）。
+  const bySeq = new Map();
+  for (const { event } of events) if (event && typeof event === 'object') bySeq.set(event.seq, event);
+  for (const { event, lineNo } of events) {
+    if (!event || typeof event !== 'object') continue;
+    if (event.type !== 'session/title' && event.type !== 'session/title-llm-request') continue;
+    const seqs = event.data?.messageSeqs;
+    if (!Array.isArray(seqs)) {
+      out.push(violation('G3', { seq: event.seq, lineNo, eventType: event.type },
+        `${event.type} ${event.seq} 的 messageSeqs 必须是数组 —— 官方迁移会拒`));
+      continue;
+    }
+    if (event.type === 'session/title') {
+      const kind = event.data?.source?.kind;
+      if ((seqs.length === 0) !== (kind === 'user')) {
+        out.push(violation('G3', { seq: event.seq, lineNo, eventType: event.type },
+          `session/title ${event.seq} messageSeqs must be empty exactly for a user title（官方原文；source.kind=${String(kind)}，seqs=${seqs.length}）`));
+      }
+    }
+    for (const s of seqs) {
+      const src = bySeq.get(s);
+      if (!src || src.type !== 'user/message' || src.data?.source?.kind !== 'user') {
+        out.push(violation('G3', { seq: event.seq, lineNo, eventType: event.type },
+          `${event.type} ${event.seq} messageSeqs must cite earlier human user/message events（seq ${String(s)} 不是更早的人类 user/message）`));
+      }
+    }
+  }
+  return out;
+}

package/lib/compat.js

@@ -0,0 +1,282 @@
+/**
+ * dsh-log-contract · lib/compat.js —— 兼容层（任务 1.3 · 装即坏修复；2026-09-14 语义对齐重写）
+ *
+ * 背景：本包原先从 `@deepseek-ai/dsh-session` 直接导入 `decodeStorageRecord` 与 `isJsonValue`。
+ * 官方 0.1.5 树已**不再从包根导出**这两个符号（0.1.5-rc.1 `lib/index.js` 的 26 个导出里没有它们），
+ * 而本包是 plugin 的依赖 ⇒ 升级后"装即坏"（模块加载期报 does not provide an export named ...）。
+ *
+ * 本文件把这两个符号**本地化**，并把语义从"近似"改为**逐条移植**（原实现是宽松近似：
+ * `decodeStorageRecord` 对损坏 chunk 行返回 `[value]` 而非抛错，导致 R2 永不触发；
+ * `isJsonValue` 不拒 `-0`、不拒稀疏数组、不查原型——与官方 lossless-JSON 边界不一致）。
+ *
+ * 移植源（一手，2026-09-14 实测）：
+ * - `decodeStorageRecord` / `validateRow` / `expandRow`：
+ *   `@deepseek-ai/dsh-session@0.1.0-rc.7` `lib/index.js:922-1035`（该版本是最后一个把
+ *   `decodeStorageRecord` 从包根导出的版本；与 App 2.0.9 内置的
+ *   `dsh-session/lib/types/chunk-rows.js`（= 0.1.2-rc.1，sha256 前 16 位 `5724c4f798ed07e7`）
+ *   校验规则一致）。**fail-loud**：损坏的 chunk 行必须抛错——它是损坏存储，静默当普通事件
+ *   处理会丢掉整段 run。
+ * - `isJsonValue`：`@deepseek-ai/dsh-session@0.1.0-rc.7` `lib/index.js:74-205`
+ *   `walkJsonValue(value, false)`（lossless-JSON 边界：拒绝稀疏数组、非有限数、`-0`、
+ *   循环引用、非普通原型、symbol/不可枚举键）。
+ *
+ * 仍从官方导入的符号（升级后保留）：`foldSurface` / `isSurfaceEligibleType` /
+ * `KNOWN_SESSION_EVENT_TYPES`（见 `./vocab.js` / `./checks.js`）。
+ */
+
+/** Whether a value is a JSON-visible record (object, not null, not array)（rc.7 `isRecord`）。 */
+function isRecord(value) {
+  return typeof value === 'object' && value !== null;
+}
+
+/** Exact-key check: `value` has every key in `keys` and nothing else（rc.7 `hasExactKeys`）。 */
+function hasExactKeys(value, keys) {
+  return Object.keys(value).length === keys.length && keys.every((k) => Object.hasOwn(value, k));
+}
+
+//#region isJsonValue —— rc.7 walkJsonValue 的移植（不含 detach）
+/** Whether a value is an object whose prototype is an intrinsic (plain) object prototype, across realms. */
+function isIntrinsicObjectPrototype(prototype) {
+  return prototype === null || Object.getPrototypeOf(prototype) === null;
+}
+/** Whether an object is a plain or null-prototype record from any JavaScript realm. */
+function hasPlainObjectPrototype(value) {
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === null || (typeof prototype === 'object' && isIntrinsicObjectPrototype(prototype));
+}
+/** Whether an array is a plain array from any JavaScript realm (rejects subclasses/exotics). */
+function hasPlainArrayPrototype(value) {
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype === Array.prototype) return true;
+  return typeof prototype === 'object' && prototype !== null && Object.getPrototypeOf(prototype) === Object.prototype && Object.getPrototypeOf(Object.getPrototypeOf(prototype)) === null;
+}
+/** Return every JSON-visible object key, or reject own data JSON would discard. */
+function enumerableStringKeys(value) {
+  const keys = Reflect.ownKeys(value);
+  if (keys.some((key) => typeof key !== 'string' || !Object.prototype.propertyIsEnumerable.call(value, key))) return undefined;
+  return keys;
+}
+
+/**
+ * Validate lossless JSON iteratively（rc.7 `walkJsonValue(value, false)`）。
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isJsonValue(value) {
+  const ancestors = new Set();
+  const tasks = [{ kind: 'visit', value }];
+  for (let task = tasks.pop(); task !== undefined; task = tasks.pop()) {
+    if (task.kind === 'leave') {
+      ancestors.delete(task.source);
+      continue;
+    }
+    if (task.kind === 'array-item') {
+      if (!Object.prototype.hasOwnProperty.call(task.source, task.index)) return false;
+      tasks.push({ kind: 'visit', value: task.source[task.index] });
+      continue;
+    }
+    if (task.kind === 'object-property') {
+      tasks.push({ kind: 'visit', value: task.source[task.key] });
+      continue;
+    }
+    const current = task.value;
+    if (current === null) continue;
+    if (typeof current === 'boolean' || typeof current === 'string') continue;
+    if (typeof current === 'number') {
+      if (!Number.isFinite(current) || Object.is(current, -0)) return false;
+      continue;
+    }
+    if (typeof current !== 'object') return false;
+    if (ancestors.has(current)) return false;
+    if (Array.isArray(current)) {
+      if (!hasPlainArrayPrototype(current)) return false;
+      const length = current.length;
+      if (Reflect.ownKeys(current).length !== length + 1) return false;
+      ancestors.add(current);
+      tasks.push({ kind: 'leave', source: current });
+      for (let index = length - 1; index >= 0; index--) tasks.push({ kind: 'array-item', source: current, index });
+      continue;
+    }
+    if (!hasPlainObjectPrototype(current)) return false;
+    const keys = enumerableStringKeys(current);
+    if (keys === undefined) return false;
+    ancestors.add(current);
+    tasks.push({ kind: 'leave', source: current });
+    for (let index = keys.length - 1; index >= 0; index--) {
+      const key = keys[index];
+      /* v8 ignore next -- the loop is bounded by the captured key count. */
+      if (key === undefined) return false;
+      tasks.push({ kind: 'object-property', source: current, key });
+    }
+  }
+  return true;
+}
+//#endregion
+
+//#region decodeStorageRecord —— rc.7 validateRow/expandRow 的移植
+/** Throw the uniform malformed-row diagnostic（rc.7 `malformed`）。 */
+function malformed(tag, why) {
+  throw new Error(`malformed ${tag} storage row: ${why}`);
+}
+
+/** Validate the shared run-data fields and the payload/dt arity; returns the member payload（rc.7 `validateRunData`）。 */
+function validateRunData(tag, data, payloadKey) {
+  if (typeof data.turn !== 'number' || typeof data.step !== 'number' || typeof data.index !== 'number') malformed(tag, 'turn/step/index must be numbers');
+  const payload = data[payloadKey];
+  if (!Array.isArray(payload) || payload.length === 0 || payload.some((entry) => typeof entry !== 'string')) malformed(tag, `${payloadKey} must be a non-empty string array`);
+  const dt = data.dt;
+  if (!Array.isArray(dt) || dt.some((gap) => !Number.isSafeInteger(gap))) malformed(tag, 'dt must be an array of safe integers');
+  if (dt.length !== payload.length - 1) malformed(tag, `dt length ${dt.length} does not match ${payload.length} members`);
+  return payload;
+}
+
+/** Validate a row-tagged parsed value's envelope and data, throwing on any malformation（rc.7 `validateRow`）。 */
+function validateRow(value, tag) {
+  if (!hasExactKeys(value, ['type', 'seq0', 'time0', 'data'])) malformed(tag, 'envelope must be exactly {type, seq0, time0, data}');
+  if (!Number.isSafeInteger(value.seq0) || value.seq0 < 0) malformed(tag, 'seq0 must be a non-negative safe integer');
+  if (!Number.isSafeInteger(value.time0)) malformed(tag, 'time0 must be a safe integer');
+  const data = value.data;
+  if (!isRecord(data)) malformed(tag, 'data must be an object');
+  let payload;
+  if (tag === 'tool-call-chunks') {
+    const withName = hasExactKeys(data, ['turn', 'step', 'index', 'id', 'name', 'dt', 'args']);
+    if (!withName && !hasExactKeys(data, ['turn', 'step', 'index', 'id', 'dt', 'args'])) malformed(tag, 'data must be exactly {turn, step, index, id, name?, dt, args}');
+    if (typeof data.id !== 'string' || (withName && typeof data.name !== 'string')) malformed(tag, 'id (and name when present) must be strings');
+    payload = validateRunData(tag, data, 'args');
+  } else {
+    if (!hasExactKeys(data, ['turn', 'step', 'index', 'dt', 'texts'])) malformed(tag, 'data must be exactly {turn, step, index, dt, texts}');
+    payload = validateRunData(tag, data, 'texts');
+  }
+  if (!Number.isSafeInteger(value.seq0 + payload.length - 1)) malformed(tag, 'member seqs must stay safe integers');
+  let time = value.time0;
+  for (const gap of data.dt) {
+    time += gap;
+    if (!Number.isSafeInteger(time)) malformed(tag, 'member times must stay safe integers');
+  }
+  return value;
+}
+
+/** Expand a validated row back into its exact original events, in order（rc.7 `expandRow`）。 */
+function expandRow(row) {
+  const members = row.type === 'tool-call-chunks' ? row.data.args : row.data.texts;
+  const events = [];
+  let time = row.time0;
+  for (let k = 0; k < members.length; k++) {
+    if (k > 0) time += row.data.dt[k - 1];
+    let chunk;
+    switch (row.type) {
+      case 'text-chunks':
+        chunk = { type: 'text-delta', index: row.data.index, text: members[k] };
+        break;
+      case 'reasoning-chunks':
+        chunk = { type: 'reasoning-delta', index: row.data.index, text: members[k] };
+        break;
+      case 'tool-call-chunks':
+        chunk = {
+          type: 'tool-call-delta',
+          index: row.data.index,
+          id: row.data.id,
+          ...Object.hasOwn(row.data, 'name') ? { name: row.data.name } : {},
+          argumentsDelta: members[k],
+        };
+        break;
+      /* v8 ignore next 4 -- validateRow only returns the three row tags */
+      default:
+        throw new Error(`chunk-rows received unsupported row ${String(row)}`);
+    }
+    events.push({ type: 'assistant/chunk', seq: row.seq0 + k, time, data: { turn: row.data.turn, step: row.data.step, chunk } });
+  }
+  return events;
+}
+
+/**
+ * 存储行解码：chunk 行校验后展开为完整事件序列，其他行原样返回（rc.7 `decodeStorageRecord`）。
+ * 损坏的 chunk 行**抛错**（fail-loud）——调用方（log-reader）据此落 `row.error` → R2。
+ * @param {unknown} value 已 JSON.parse 的一行
+ * @returns {unknown[]} 事件数组
+ */
+export function decodeStorageRecord(value) {
+  if (!isRecord(value)) return [value];
+  const tag = value.type;
+  if (tag !== 'text-chunks' && tag !== 'reasoning-chunks' && tag !== 'tool-call-chunks') return [value];
+  return expandRow(validateRow(value, tag));
+}
+//#endregion
+
+//#region decodeSeqRanges —— v3 storage-form 区间编码解码（0.1.5 `lib/types/seq-ranges.js` 逐条移植）
+// 为什么本地化：`decodeSeqRanges` 只在 0.1.5+ 从包根导出；`0.1.0-rc.7` 实测 `undefined`
+// （见 vocab.js 的双宿主声明）。本包 peer 允许两个版本 ⇒ 必须在两种宿主上都能解码。
+//
+// 语义（官方 `seq-ranges.js:34-73`）：`sourceEventSeqs` 的 JSON 存储形态是"数字 + 闭区间对"
+// 混合数组，例 `[3, [174,176], 180, …]` ⇒ 内存形态 `[3,174,175,176,180,…]`。
+// v3 持久化层对连续段用区间对压缩（App 2.0.9 真实 v3 会话实测：1 个 `user/message` replace
+// 的 `sourceEventSeqs` 2251 个存储项展开为 2259 个 seq）。**不解码 = 拿物理未展开的序列
+// 喂 S5/S6 与官方 foldSurface ⇒ 真实健康会话被误判 S5/S6/S8 + `--resume` broken。**
+
+/** 非负安全整数（rc.7/0.1.5 `assertSeq`）。 */
+function assertSeq(value) {
+  if (!Number.isSafeInteger(value) || value < 0) throw new TypeError('sourceEventSeqs must contain non-negative safe integers');
+}
+/** 带 Session 序号 brand 的断言（官方 `SessionSeq`；额外拒绝 `-0`）。 */
+function sessionSeq(value) {
+  if (!Number.isSafeInteger(value) || value < 0 || Object.is(value, -0)) {
+    throw new TypeError(`SessionSeq must be a non-negative safe integer, got ${String(value)}`);
+  }
+  return value;
+}
+
+/**
+ * 展开 JSON 存储形态的 `sourceEventSeqs`（官方 `decodeSeqRanges` 逐条移植）。
+ * 任一形态非法即抛 `TypeError`（fail-loud：调用方据此报 S6/E4，不静默当稠密序列）。
+ * @param {unknown} value 已 JSON.parse 的 `sourceEventSeqs`
+ * @param {number} [maxEntries] 该事件允许的最大成员数
+ * @returns {number[]} 内存稠密序列
+ */
+export function decodeSeqRanges(value, maxEntries = Number.MAX_SAFE_INTEGER) {
+  if (!Array.isArray(value)) throw new TypeError('sourceEventSeqs must be an array');
+  const decoded = [];
+  let hasRange = false;
+  for (const entry of value) {
+    if (typeof entry === 'number') {
+      assertSeq(entry);
+      if (decoded.length >= maxEntries) throw new TypeError('sourceEventSeqs exceeds its event sequence');
+      decoded.push(sessionSeq(entry));
+      continue;
+    }
+    if (!Array.isArray(entry) || entry.length !== 2) {
+      throw new TypeError('sourceEventSeqs range entries must be [start, end] pairs');
+    }
+    const start = entry[0];
+    const end = entry[1];
+    assertSeq(start);
+    assertSeq(end);
+    if (end < start) throw new TypeError('sourceEventSeqs ranges require start <= end');
+    if (end - start + 1 > maxEntries - decoded.length) {
+      throw new TypeError('sourceEventSeqs range exceeds its event sequence');
+    }
+    for (let seq = start; seq <= end; seq += 1) decoded.push(sessionSeq(seq));
+    hasRange = true;
+  }
+  if (hasRange && !decoded.every((v, i) => i === 0 || v > decoded[i - 1])) {
+    throw new TypeError('sourceEventSeqs ranges must be strictly increasing');
+  }
+  return decoded;
+}
+
+/**
+ * 把一个已解码事件的 storage-form `sourceEventSeqs` 归一成内存稠密序列。
+ * - 无 `sourceEventSeqs` / 非对象 → 原样返回（同一引用）；
+ * - 解码成功 → 返回**新对象**（不修改入参；调用方须使用返回值）；
+ * - 解码失败 → 原样返回，保留存储形态交由 S6/E4 报违规（读取层不崩、不吞错）。
+ */
+export function normalizeEventSeqRanges(event) {
+  if (!isRecord(event) || event.sourceEventSeqs === undefined) return event;
+  let expanded;
+  try {
+    expanded = decodeSeqRanges(event.sourceEventSeqs);
+  } catch {
+    return event;
+  }
+  return { ...event, sourceEventSeqs: expanded };
+}
+//#endregion

package/lib/contracts.js

@@ -21,6 +21,7 @@ export const LAYER = {
   PLUGIN: 'plugin', // 插件语义层：marker 隐藏语义
   CONCURRENCY: 'concurrency', // 并发/写入者假设
   FRAMING: 'framing', // zstd 帧结构
+  MIGRATION: 'migration', // 迁移预检层：官方 v0/v1/v2 → 当前格式的升级路径会不会拒（**独立维度**）
 };
 
 export const SEVERITY = { ERROR: 'error', WARNING: 'warning', INFO: 'info' };
@@ -35,6 +36,7 @@ export const SEVERITY = { ERROR: 'error', WARNING: 'warning', INFO: 'info' };
  * - P  插件 marker 语义层
  * - C  并发 / 写入者假设
  * - Z  zstd 帧结构
+ * - G  迁移预检（migration gate，**独立维度**：官方迁移会不会拒；不进 ok/verdict）
  */
 export const CONTRACT_RULES = [
   // ── H · header ──────────────────────────────────────────────────────────
@@ -51,8 +53,8 @@ export const CONTRACT_RULES = [
     title: 'header 版本与必填字段',
     layer: LAYER.PERSISTENCE,
     severity: SEVERITY.ERROR,
-    source: '@deepseek-ai/dsh-session lib/index.js:1110-1125',
-    description: 'header.version 必须为 0；id 为字符串；createdAt 为非负安全整数；cwd 若存在必须为绝对路径；origin 只能为 "subagent"。',
+    source: '@deepseek-ai/dsh-session lib/index.js:1110-1125；已知格式版本 0/1/2/3（App 2.0.9 内置 v0→v1→v2→v3 迁移，SESSION_FORMAT_VERSION=3）',
+    description: 'header.version 必须为已知受支持版本（0/1/2/3）；未知版本报 H2。id 为字符串；createdAt 为非负安全整数；cwd 若存在必须为绝对路径；origin 只能为 "subagent"。',
   },
 
   // ── R · 存储行 ──────────────────────────────────────────────────────────
@@ -209,8 +211,8 @@ export const CONTRACT_RULES = [
     title: '整日志 foldSurface 可重放',
     layer: LAYER.PERSISTENCE,
     severity: SEVERITY.ERROR,
-    source: '@deepseek-ai/dsh-session lib/index.js:444-455 (foldSurface)；复盘"官方 foldSurface 不抛 = 通过"',
-    description: '终验：把全部事件按序喂给官方 foldSurface，不抛 = 持久化层通过。S1–S7 任何一条违反都会在此暴露。',
+    source: '@deepseek-ai/dsh-session lib/index.js:444-455 (foldSurface, v3)；v0/v1/v2 用本地等价实现 lib/legacy-fold.js（rc.7 lib/index.js:229-455 逐条移植）',
+    description: '终验：按被检文件 header.version 选折叠器（v3 → 官方 foldSurface；v0/v1/v2 → 本地 legacyFoldSurface），不抛 = 持久化层通过。S1–S7 任何一条违反都会在此暴露。注意 0.1.5 的官方 foldSurface 是 v3 语义（replace 用 startSeq/endSeq、assistant/message 禁 sourceEventSeqs），对旧格式文件会误报，不可借用。',
   },
 
   {
@@ -358,6 +360,36 @@ export const CONTRACT_RULES = [
     source: 'OpenAI 兼容端点对 tool 消息顺序的严格校验；DSH 序列化器将混合 user 消息展开为 text 在前、tool-result 在后',
     description: '当仍有未满足的 assistant tool-call 时出现 user 文本消息，会产生 [assistant(tool_calls), user(text), tool] 序列，严格端点同样拒绝。',
   },
+
+  // ── G · 迁移预检（migration precheck；**独立维度**，不是"可加载"判定）──────────
+  // 存在理由：官方把 v0/v1/v2 会话升到当前格式时会做一轮**迁移校验**，其规则比本工具的
+  // "读取/折叠"规则集更严（官方原文见各条 source）。本工具判"可加载"≠"可升级"。
+  // 这些规则只描述"官方迁移会不会拒"，因此 severity 固定 warning、layer 固定 migration：
+  // 它们**不参与** ok / loadable / resumable / compactable，只喂 `migrationVerdict()`。
+  {
+    id: 'G1',
+    title: '迁移预检：v0 源文件的 subagent/descriptor.data.version 必须为 3',
+    layer: LAYER.MIGRATION,
+    severity: SEVERITY.WARNING,
+    source: '@deepseek-ai/dsh-session-format-v0-to-v1@0.1.5-rc.2 lib/index.js:1584-1586（assertReleasedEventPayload）：data.version !== 3 且源版本 === 0 → SessionFormatUnsupportedMigrationError("uses unsupported descriptor version N")；源版本 1/2 时官方提前 return（容忍）',
+    description: '文件版本 0 且事件类型为 subagent/descriptor 且 data.version !== 3 → 官方 v0→v1 迁移直接拒绝（消息形如 `subagent/descriptor <seq> uses unsupported descriptor version 2`）；源版本 1/2 不受此条约束。',
+  },
+  {
+    id: 'G2',
+    title: '迁移预检：v0 源文件不得含词表外的历史事件类型（含 ignorable）',
+    layer: LAYER.MIGRATION,
+    severity: SEVERITY.WARNING,
+    source: '@deepseek-ai/dsh-session-format-v0-to-v1@0.1.5-rc.2 lib/index.js:1580-1583（assertReleasedEventPayload）：RELEASED_V0_EVENT_DISPOSITIONS 里没有该 type → "format v0 contains unknown historical event type … migration refuses unknown historical events even when ignorable"',
+    description: '文件版本 0 且事件 type 不在官方 v0 dispositions（本包 vendored 为 V0_EVENT_TYPES）内 → 官方迁移拒绝，**即使该事件带 ignorable:true**。E3 的 ignorable 豁免是**读取路径**语义（不改），本条只在迁移预检维度表达。',
+  },
+  {
+    id: 'G3',
+    title: '迁移预检：v0 源 session/title 系列的 messageSeqs 必须引用更早的人类 user/message',
+    layer: LAYER.MIGRATION,
+    severity: SEVERITY.WARNING,
+    source: '@deepseek-ai/dsh-session-format-v0-to-v1@0.1.5-rc.2 lib/index.js:2543-2556（assertTitleSources）：`session/title` 的 messageSeqs 为空 ⟺ source.kind === "user"；每个被引 seq 必须解析到 `user/message` 且其 `data.source.kind === "user"`，否则 "messageSeqs must cite earlier human user/message events" / "must be empty exactly for a user title"',
+    description: '文件版本 0 且事件为 session/title 或 session/title-llm-request：messageSeqs 必须是数组；session/title 的"空数组 ⟺ 用户标题"必须成立；每个被引 seq 必须是更早的 user/message 且 source.kind === "user"。违反 → 官方升级到当前格式时拒绝。**应用面说明**：官方 `assertTitleSources` 与 turn/start 状态机同在 `assertReleasedArtifactRelationships`，由 v1→v2 在**变换后的 v1/v2 artifact** 上调用（`dsh-session-format-v1-to-v2/lib/index.js:104`）；对 messageSeqs 这类按 seq 索引 + 类型/source 判定的引用，变换保序保类型 ⇒ 在原始 v0 上判是必要条件的近似，实测 281 真实 v0 上 0 误报。',
+  },
 ];
 
 /** 按 id 取规则。 */

package/lib/index.js

@@ -5,9 +5,10 @@
  * 公开 API：离线体检 + 写前校验 + 修复 + 契约目录。
  */
 export { loadSessionLog, tailSeq, readSessionHeader } from './log-reader.js';
-export { validateSessionLog, resumeVerdict } from './validate.js';
+export { validateSessionLog, resumeVerdict, migrationVerdict, assessmentScope } from './validate.js';
 export { createPreWriter, preWriterFromLog } from './prewrite.js';
 export { repairSession, strictScanText, removeMarkersText, neutralizeMarkersText, clipCrossStepSourcesText, dropFailedTurnsText, trimLastMessagesText, trimLastMessagesByBudget, estimateTokensText, compactLastMessagesText, rebuildZstdText, tailRenumberText, neutralizeOrphanText, extractTurnText, keepRangesText } from './repair.js';
 export { CONTRACT_RULES, LAYER, SEVERITY, ruleById } from './contracts.js';
+export { HOST_MAX_FILE_VERSION, hostPackageVersion, hostCapability, isAssessableFileVersion } from './vocab.js';
 export { tokenMeterViolations, tokenMeterSourceViolations, stepKeyViolations, nullTurnStepViolations, turnEndReasonViolations, ignorableTypeViolations, physicalOrderViolations, inboxReplayViolations } from './checks.js';
 export { auditToolCalls, extractText, extractToolOutputs, indexToolCalls, toolCommandOf } from './archaeology.js';