dsh-log-contract 0.3.10 → 0.3.12

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），对旧格式文件会误报，不可借用。',
   },
 
   {
@@ -253,6 +255,22 @@ export const CONTRACT_RULES = [
     source: '官方 dsh-agent-loop lib/index.js:620（turn/end = {turn, reason:{kind}}）；1f4d986e malformed turn/end 事故（2026-09-02，修复线 check-turn-end-reason.mjs）',
     description: '官方 validation 强制 turn/end 的 data.reason.kind 存在（kind ∈ completed|max-tokens|blocked|aborted|error|interrupted）。缺失 = malformed → 官方 SessionPersistenceCorruptionError → 会话加载失败。1f4d986e：retrace 情形③信封 turn/end 漏 reason → 每次编辑后加载失败（已修 0.4.18）。',
   },
+  {
+    id: 'E7',
+    title: 'ignorable 未知 type 合法性（带被忽略标记的未知事件须有消费者）',
+    layer: LAYER.PERSISTENCE,
+    severity: SEVERITY.WARNING,
+    source: '反向挑刺 2026-09-09 T2（E3 ignorable 无合法性校验 = 后门）',
+    description: '未知 type + ignorable:true 被读路径接纳但无人消费 = 静默垃圾。排除已知消费者白名单（retrace/marker、retrace/goal-marker、message-editor/ 前缀等 retrace 客户端消费的插件 marker）后，其余 ignorable 未知事件报 warning。',
+  },
+  {
+    id: 'Z3',
+    title: '空会话文件（有 header 无事件）显式报出',
+    layer: LAYER.FRAMING,
+    severity: SEVERITY.WARNING,
+    source: '反向挑刺 2026-09-09 T3（36 条规则全来自有内容事故,空态无覆盖）',
+    description: '有 header 但零事件 = 异常空会话（新建即空或写入未落盘）。空态不在任何有内容规则的覆盖下,显式 warning 供人判断。',
+  },
   {
     id: 'P3',
     title: 'tool/call ↔ tool/result 配对完整性（考古 B1）',
@@ -342,6 +360,28 @@ 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 取规则。 */

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 { tokenMeterViolations, tokenMeterSourceViolations, stepKeyViolations, nullTurnStepViolations, turnEndReasonViolations, physicalOrderViolations, inboxReplayViolations } from './checks.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';

package/lib/legacy-fold.js

@@ -0,0 +1,177 @@
+/**
+ * dsh-log-contract · lib/legacy-fold.js —— **v0/v1/v2 旧格式的 surface 终验器**
+ *
+ * 为什么需要这个文件（一手证据，2026-09-14）：
+ *
+ * 官方 `@deepseek-ai/dsh-session` 的 `foldSurface` 在 0.1.5-rc.1 里换成了 **v3 语义**，
+ * 它**不是** rc.7（v0 语义）的超集，而是一个**不同格式**的校验器：
+ * - replace 操作数字段改名：rc.7 `{op,start,end}` → 0.1.5 `{op,startSeq,endSeq}`
+ *   （0.1.5 `lib/index.js:279`：`isReplaceOp` 要求 startSeq/endSeq ⇒ 旧 marker 直接
+ *   “carries an invalid replace surfaceOp”）；
+ * - provenance 收紧：0.1.5 `lib/index.js:285` 起对 `assistant/message` **一律**禁止
+ *   `sourceEventSeqs`（“embeds its source stream and cannot carry sourceEventSeqs”）；
+ *   rc.7 允许（空数组仅限 assistant/message）。
+ *
+ * App 2.0.9 的真实文件版本分布证明旧格式仍在线上：App 内置
+ * `dsh-session-format-v0-to-v1` / `v1-to-v2` / `v2-to-v3` 三个迁移包，
+ * `SESSION_FORMAT_VERSION = 3`；且 `v2-to-v3/lib/index.js:361-371` 明示 **v2 仍是
+ * `{start,end}`**、由迁移改名为 `startSeq/endSeq`。
+ *
+ * ⇒ 结论：**用运行时的 v3 `foldSurface` 去终验 v0/v1/v2 文件必然误报**；旧格式必须用
+ *   本文件这份等价实现（rc.7 `foldSurface` 的逐条移植，语义等价、同样 fail-loud）。
+ *
+ * 移植源：`@deepseek-ai/dsh-session@0.1.0-rc.7` `lib/index.js:229-455`
+ * （`isSurfaceEligibleType` / `isEventSeq` / `isReplaceOp` / `surfaceOpOf` /
+ * `assertProvenance` / `replacementRange` / `isDeepEqualJson` / `assertToolResultRewrite` /
+ * `planSurfaceEvent` / `applySurfacePlan` / `foldSurface`）。
+ *
+ * 与官方相同的点：**抛错即拒绝**（官方加载期 `SessionPersistenceCorruptionError` 同源
+ * 判据）；事件按 `index` 作为期望 seq（`baseSeq = 0`），与官方 `foldSurface(events)` 一致。
+ */
+
+/** v0/v1/v2 的 surface 候选类型（官方 rc.7 `SURFACE_EVENT_TYPES`，3 条）。 */
+const SURFACE_EVENT_TYPES = new Set(['user/message', 'assistant/message', 'tool/result']);
+
+/** Whether an event type can join the model-visible surface（rc.7 `isSurfaceEligibleType`）。 */
+export function isLegacySurfaceEligibleType(type) {
+  return SURFACE_EVENT_TYPES.has(type);
+}
+
+/** Whether a runtime value is a non-negative safe event sequence（rc.7 `isEventSeq`）。 */
+function isEventSeq(value) {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+
+/** Whether a runtime value is the exact positional-replacement shape（rc.7 `isReplaceOp`：start/end）。 */
+function isReplaceOp(value) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return false;
+  const op = value;
+  return (
+    Object.keys(op).length === 3 &&
+    Object.hasOwn(op, 'op') && Object.hasOwn(op, 'start') && Object.hasOwn(op, 'end') &&
+    op.op === 'replace' && isEventSeq(op.start) && isEventSeq(op.end)
+  );
+}
+
+/** Validate event-local surface eligibility and return its operation（rc.7 `surfaceOpOf`）。 */
+function surfaceOpOf(event) {
+  if (!SURFACE_EVENT_TYPES.has(event.type)) {
+    if (event.surfaceOp !== undefined) throw new Error(`session event "${event.type}" is not surface-eligible and cannot carry surfaceOp`);
+    if (event.sourceEventSeqs !== undefined) throw new Error(`session event "${event.type}" is not surface-eligible and cannot carry sourceEventSeqs`);
+    return undefined;
+  }
+  const op = event.surfaceOp;
+  if (op === undefined) throw new Error(`session event "${event.type}" is surface-eligible and requires a surfaceOp marker`);
+  if (op === 'append') return op;
+  if (op === null || typeof op !== 'object' || Array.isArray(op)) throw new Error(`session event "${event.type}" carries an invalid surfaceOp`);
+  if (!isReplaceOp(op)) throw new Error(`session event "${event.type}" carries an invalid replace surfaceOp`);
+  return op;
+}
+
+/** Validate cited source-event seqs against prior log entries and the replacement range（rc.7 `assertProvenance`）。 */
+function assertProvenance(event, shadowedSeqs) {
+  const raw = event.sourceEventSeqs;
+  const sources = new Set();
+  if (raw !== undefined) {
+    if (!Array.isArray(raw)) throw new Error(`sourceEventSeqs on event at seq ${event.seq} must be an array when present`);
+    if (raw.length === 0 && event.type !== 'assistant/message') throw new Error('sourceEventSeqs must not be empty except on assistant/message');
+    let nonEarlierSource;
+    for (const source of raw) {
+      if (!isEventSeq(source)) throw new Error(`session event "${event.type}" sourceEventSeqs must densely contain non-negative safe integers`);
+      sources.add(source);
+      if (nonEarlierSource === undefined && source >= event.seq) nonEarlierSource = source;
+    }
+    if (sources.size !== raw.length) throw new Error('sourceEventSeqs must not contain duplicates');
+    if (nonEarlierSource !== undefined) throw new Error(`sourceEventSeqs must reference earlier events: ${nonEarlierSource} >= current seq ${event.seq}`);
+  }
+  const missing = shadowedSeqs.filter((seq) => !sources.has(seq));
+  if (missing.length > 0) throw new Error(`surface replace: sourceEventSeqs must include every shadowed surface node; missing ${missing.join(', ')}`);
+}
+
+/** Locate one replacement range without mutating the current fold state（rc.7 `replacementRange`）。 */
+function replacementRange(state, op) {
+  const startIdx = state.nodes.indexOf(op.start);
+  if (startIdx === -1) throw new Error(`surface replace: start seq ${op.start} not found in surface`);
+  const endIdx = state.nodes.indexOf(op.end);
+  if (endIdx === -1) throw new Error(`surface replace: end seq ${op.end} not found in surface`);
+  if (startIdx > endIdx) throw new Error(`surface replace: start seq ${op.start} (index ${startIdx}) is after end seq ${op.end} (index ${endIdx})`);
+  return { startIdx, endIdx, shadowedSeqs: state.nodes.slice(startIdx, endIdx + 1) };
+}
+
+/** Deep structural equality over the session-event JSON value domain（rc.7 `isDeepEqualJson`）。 */
+function isDeepEqualJson(a, b) {
+  if (a === b) return true;
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+    return a.every((item, i) => isDeepEqualJson(item, b[i]));
+  }
+  if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null) return false;
+  const aKeys = Object.keys(a);
+  if (aKeys.length !== Object.keys(b).length) return false;
+  return aKeys.every((key) => Object.hasOwn(b, key) && isDeepEqualJson(a[key], b[key]));
+}
+
+/** Restrict a tool-result replacement to one current result's content（rc.7 `assertToolResultRewrite`）。 */
+function assertToolResultRewrite(event, shadowedSeqs, events, baseSeq) {
+  if (event.type !== 'tool/result') return;
+  if (shadowedSeqs.length !== 1) throw new Error('tool/result surface replacement must rewrite exactly one current node');
+  for (const originalSeq of shadowedSeqs) {
+    const original = events[originalSeq - baseSeq];
+    if (original?.type !== 'tool/result') throw new Error('tool/result surface replacement must target a current tool/result');
+    const originalRest = { ...original.data };
+    const replacementRest = { ...event.data };
+    const originalResult = original.data.message.content[0];
+    const replacementResult = event.data.message.content[0];
+    originalRest.message = { ...original.data.message, content: [{ ...originalResult, content: null }] };
+    replacementRest.message = { ...event.data.message, content: [{ ...replacementResult, content: null }] };
+    if (!isDeepEqualJson(originalRest, replacementRest)) throw new Error('tool/result surface replacement may change only content');
+  }
+}
+
+/** Validate one event at its replay boundary and prepare its atomic fold transition（rc.7 `planSurfaceEvent`）。 */
+function planSurfaceEvent(state, event, expectedSeq, events, baseSeq) {
+  if (event.seq !== expectedSeq) throw new Error(`session event seq ${event.seq} is not contiguous; expected ${expectedSeq}`);
+  const surfaceOp = surfaceOpOf(event);
+  if (surfaceOp === undefined) return undefined;
+  if (surfaceOp === 'append') {
+    assertProvenance(event, []);
+    return { kind: 'append', seq: event.seq };
+  }
+  const range = replacementRange(state, surfaceOp);
+  assertProvenance(event, range.shadowedSeqs);
+  assertToolResultRewrite(event, range.shadowedSeqs, events, baseSeq);
+  return { kind: 'replace', seq: event.seq, start: surfaceOp.start, end: surfaceOp.end, ...range };
+}
+
+/** Commit one previously validated surface transition（rc.7 `applySurfacePlan`）。 */
+function applySurfacePlan(state, plan) {
+  if (plan?.kind === 'append') state.nodes.push(plan.seq);
+  else if (plan?.kind === 'replace') {
+    state.nodes.splice(plan.startIdx, plan.endIdx - plan.startIdx + 1, plan.seq);
+    state.replaceGeneration += 1;
+  }
+  if (plan?.kind !== 'replace') return undefined;
+  return { seq: plan.seq, start: plan.start, end: plan.end, shadowedSeqs: plan.shadowedSeqs };
+}
+
+/** Apply one event and return replacement metadata only when one occurred（rc.7 `applySurfaceEvent`）。 */
+function applySurfaceEvent(state, event, expectedSeq, events, baseSeq) {
+  return applySurfacePlan(state, planSurfaceEvent(state, event, expectedSeq, events, baseSeq));
+}
+
+/**
+ * Replay a complete session log through the **v0/v1/v2** canonical surface fold.
+ *
+ * @param events - session events in contiguous seq order（seq 从 0 起，与官方 `foldSurface` 同约定）。
+ * @returns {{ nodes: number[], replacements: Array<{seq:number,start:number,end:number,shadowedSeqs:number[]}> }}
+ * @throws when an event violates surface metadata, source-event references, range, or tool-result rewrite rules.
+ */
+export function legacyFoldSurface(events) {
+  const state = { nodes: [], replaceGeneration: 0 };
+  const replacements = [];
+  for (const [index, event] of events.entries()) {
+    const replacement = applySurfaceEvent(state, event, index, events, 0);
+    if (replacement !== undefined) replacements.push(replacement);
+  }
+  return { nodes: [...state.nodes], replacements };
+}

package/lib/log-reader.js

@@ -7,14 +7,14 @@
  * 契约来源：
  * - 帧扫描/撕裂尾帧判定：复用本项目审计方法论（scan-seq-gaps.mjs），
  *   帧头布局对齐 zstd 规范（magic 0xFD2FB528、descriptor、block 头）。
- * - 行解码：`@deepseek-ai/dsh-session` 的 `decodeStorageRecord`
+ * - 行解码：本地兼容层 `./compat.js` 的 `decodeStorageRecord`（原官方导出于 0.1.5 移除）
  *   （lib/index.js:1029，validateRow :922 / expandRow :973）。
  * - 损坏语义：R2 —— chunk 行损坏 = 整段 run 丢失且加载失败（dsh-session
  *   lib/index.js:1022-1024 注释明示 fail-loud，无跳过逃生舱）。
  */
 import fs from 'node:fs';
 import { zstdDecompressSync } from 'node:zlib';
-import { decodeStorageRecord } from '@deepseek-ai/dsh-session';
+import { decodeStorageRecord, normalizeEventSeqRanges } from './compat.js';
 
 const ZSTD_MAGIC = 0xfd2fb528;
 
@@ -209,10 +209,14 @@ export function loadSessionLog(path) {
       rows.push({ lineNo, value, decoded: null, error: err });
       continue;
     }
-    for (const event of decoded) {
+    // v3 storage-form `sourceEventSeqs` 区间编码 → 内存稠密序列（C1）。
+    // 必须在**读取层唯一入口**做：下游 S5/S6 与官方 foldSurface 都按稠密整数序列判定，
+    // 拿到含 `[start,end]` 对的未展开形态会误判真实健康会话（S5/S6/S8 + --resume broken）。
+    const normalized = decoded.map(normalizeEventSeqRanges);
+    for (const event of normalized) {
       events.push({ seq: event.seq, event, lineNo });
     }
-    rows.push({ lineNo, value, decoded, error: null });
+    rows.push({ lineNo, value, decoded: normalized, error: null });
   }
 
   // 按 seq 排序（文件顺序即日志顺序，此处防御性排序以便下游契约检查）