dsh-log-contract 0.1.0 → 0.2.1

package/README.md

@@ -66,6 +66,28 @@ dsh-log-contract check ~/.dsh/sessions/<id>.jsonl.zstd --json   # 机器可读
 
 退出码：0 = 通过（无 error 级违规）；1 = 存在 error 级违规。
 
+`check` 自 0.2.0 起新增 **W1/W2 wire 级检查**：按 surface 顺序展开模型请求消息流，
+捕获"悬空 tool 消息"（tool 结果没有前置 assistant tool_calls）与"user 文本插在
+tool_calls 与其结果之间"——这类问题 DeepSeek 曾容忍，但 MiMo 等严格端点会直接
+`INVALID_REQUEST`（2026-08-27 实锤）。
+
+### 1.5. ★ 修复（2026-08 事故固化方案）
+
+```bash
+# 干跑（只报告）：严格 seq 连续扫描 + 全契约体检（含 W1/W2）+ 可移除 marker 数
+dsh-log-contract fix ~/.dsh/sessions/<id>.jsonl.zstd --remove-markers
+
+# 应用：备份后落盘（.zstd 走官方帧格式重建：帧1=header、帧2=其余、checksum、单个结尾换行）
+dsh-log-contract fix ~/.dsh/sessions/<id>.jsonl.zstd --remove-markers --apply
+```
+
+- `--remove-markers`：移除 retrace/message-editor marker 并全量重编号
+  （seq/seq0/sourceEventSeqs/surfaceOp 同步）——用于大范围 marker 遮蔽历史、
+  marker 漏盖 tool/result 导致的悬空 tool。
+- 手术安全协议：改前备份、改后全量复检（strictScan + check + foldSurface）、
+  marker 只能遮蔽其之前的节点、marker 绝不能改成 append（M1 客户端崩溃）。
+- ⚠️ 若会话已被运行中的应用驻留内存，修复文件后需**重启应用**（强杀避免脏状态刷回）。
+
 ### 2. ★ 写前校验（本次事故的直接解药）
 
 `edit-file` 为 JSON，两种形状：
@@ -144,7 +166,7 @@ node scripts/check-local-fossils.mjs   # 扫描 ../ 下 backup-session-*.jsonl.z
 | 工具 | 象限 | 状态 |
 |---|---|---|
 | [workbuddy-session-fork](https://github.com/yamingmou/workbuddy-session-fork) | 会话分叉 · 状态管理 | ✅ 已发布 v1.2.0 |
-| **dsh-log-contract**（本仓库） | 日志契约 · 接口稳定性 | 🆕 Phase 1 CLI 离线体检 + 写前校验 |
+| **dsh-log-contract**（本仓库） | 日志契约 · 接口稳定性 | ✅ Phase 1（check/prewrite）+ Phase 1.5（fix）0.2.0 |
 | dsh-turn-guard（规划中） | 中断回合 · 异常韧性 | 待立项 |
 
 三者共享同一份 DSH 日志事件契约认知（59 条审计发现 = spec，aborted/corrupt/seqgap 化石 = 测试集）。dsh-retrace（回溯时间线）可把本工具的违规标记渲染到时间线上；本工具是 retrace 投影源健康度的**前置保险**。
@@ -153,8 +175,8 @@ node scripts/check-local-fossils.mjs   # 扫描 ../ 下 backup-session-*.jsonl.z
 
 ## Roadmap
 
-- [x] **Phase 1（本版 0.1.0）**：CLI 离线体检 + 写前校验 + 契约目录
-- [ ] Phase 1.5：违规报告的 `--fix` 建议（seq 缺口修复复用 `fix-seq-gap.mjs` 方法论）、CI 集成（`dsh-log-contract check` 作为 Harness 会话目录的定时守护）
+- [x] **Phase 1（0.1.0）**：CLI 离线体检 + 写前校验 + 契约目录
+- [x] **Phase 1.5（0.2.0）**：`fix` 子命令（严格 seq 扫描 + W1/W2 wire 检查 + 移除 marker 重编号 + 官方帧格式重建）；CI 集成（`dsh-log-contract check` 作为 Harness 会话目录的定时守护）
 - [ ] Phase 2：运行时守护（订阅 session append 事件流实时校验，断裂即标记 `dsh/contract-violation` 事件，策略可配 告警/拦截）——DSH 插件形态
 - [ ] Phase 3：与 dsh-turn-guard / dsh-retrace 时间线联动
 

package/bin/dsh-log-contract.mjs

@@ -13,7 +13,7 @@
  *   contracts                     列出内置契约规则目录
  */
 import fs from 'node:fs';
-import { loadSessionLog, validateSessionLog, createPreWriter, CONTRACT_RULES, ruleById } from '../lib/index.js';
+import { loadSessionLog, validateSessionLog, createPreWriter, repairSession, CONTRACT_RULES, ruleById } from '../lib/index.js';
 
 const USAGE = `dsh-log-contract —— 日志契约守护（DSH session log contract guard）
 
@@ -23,6 +23,16 @@ const USAGE = `dsh-log-contract —— 日志契约守护（DSH session log cont
       --json          输出机器可读 JSON 报告
       --max-details N 每条违规最多列 N 个缺失 seq（默认 8，--json 忽略）
 
+  dsh-log-contract fix <session-log> [--remove-markers] [--apply] [--backup-dir DIR] [--json]
+      诊断 + 修复（2026-08 事故固化方案）。先做严格 seq 连续扫描 + 契约体检
+      （含 W1/W2 wire 级悬空 tool 检查），再按需修复：
+      --remove-markers 移除 retrace/message-editor marker 并全量重编号
+                       （用于大范围遮蔽历史 / marker 漏盖 tool/result）
+      --apply          备份后落盘（.zstd 走官方帧格式重建：帧1=header、
+                       帧2=其余、带 checksum、单个结尾换行）
+      不传 --apply 为干跑（只报告）。
+      注意：若会话已被运行中的应用驻留，修复文件后需重启（强杀避免脏状态刷回）。
+
   dsh-log-contract prewrite <edit-file> --log <session-log> [--json]
       写前校验。edit-file 为 JSON，两种形状：
         { "append": { ...事件... } }            拟追加一个事件到日志尾部
@@ -148,6 +158,41 @@ function cmdContracts() {
   }
 }
 
+function cmdFix(args) {
+  const json = args.includes('--json');
+  const removeMarkers = args.includes('--remove-markers');
+  const dropFailedTurns = args.includes('--drop-failed-turns');
+  const trimIdx = args.indexOf('--trim-last');
+  const trimLast = trimIdx >= 0 && args[trimIdx + 1] ? Number(args[trimIdx + 1]) : undefined;
+  const apply = args.includes('--apply');
+  const backupDirIdx = args.indexOf('--backup-dir');
+  const backupDir = backupDirIdx >= 0 && args[backupDirIdx + 1] ? args[backupDirIdx + 1] : undefined;
+  const file = args.find((a) => !a.startsWith('-'));
+  if (!file) fail(USAGE);
+
+  const result = repairSession(file, { removeMarkers, dropFailedTurns, trimLast, apply, backupDir });
+  if (json) {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    process.exit(result.ok ? 0 : 1);
+  }
+
+  process.stdout.write(`\n🔧 dsh-log-contract fix —— ${file}\n`);
+  process.stdout.write(`   诊断：${result.issues.length === 0 ? '无问题' : result.issues.map((i) => `[${i.kind}] ${i.detail}`).join('\n         ')}\n`);
+  if (result.applied) {
+    process.stdout.write(`   已应用修复：移除 ${result.removed} 项，重编号 ${result.renumbered} 行\n`);
+    process.stdout.write(`   备份：${result.backupPath}\n`);
+    process.stdout.write(`   修复后体检：error ${result.check.summary?.bySeverity?.error ?? '?'} ｜ surface ${result.check.summary?.surfaceNodes ?? '?'} 节点\n`);
+  } else if (apply && !result.ok) {
+    process.stdout.write('   ❌ 存在 error 级问题，拒绝应用（改前基线必须绿；先修基线或检查输出）\n');
+  } else if (apply) {
+    process.stdout.write('   （--apply 且无问题——无内容可修）\n');
+  } else {
+    process.stdout.write(`   （干跑模式：${result.removed} 项可移除、${result.renumbered} 行待重编号；加 --apply 落盘，--remove-markers / --drop-failed-turns / --trim-last N 启用于对应修复）\n`);
+  }
+  process.stdout.write('\n');
+  process.exit(result.ok ? 0 : 1);
+}
+
 const args = process.argv.slice(2);
 const cmd = args[0];
 if (!cmd || cmd === '--help' || cmd === '-h' || cmd === 'help') {
@@ -161,5 +206,6 @@ if (cmd === '--version' || cmd === '-v') {
 }
 if (cmd === 'check') cmdCheck(args.slice(1));
 else if (cmd === 'prewrite') cmdPrewrite(args.slice(1));
+else if (cmd === 'fix') cmdFix(args.slice(1));
 else if (cmd === 'contracts') cmdContracts();
 else fail(`未知子命令 "${cmd}"\n\n${USAGE}`);

package/lib/checks.js

@@ -264,3 +264,82 @@ export function finalFold(events) {
     return { error: err };
   }
 }
+
+/** 从事件推导 wire 消息（与 dsh-session deriveEventMessage 同语义）。 */
+export function deriveWireMessage(event) {
+  if (event.type === 'user/message') {
+    return { role: 'user', content: event.data?.content ?? [] };
+  }
+  if (event.type === 'assistant/message') {
+    const m = event.data?.message;
+    if (!m || !Array.isArray(m.content) || m.content.length === 0) return null;
+    return { role: 'assistant', content: m.content };
+  }
+  if (event.type === 'tool/result') {
+    return { role: 'tool', content: event.data?.message?.content ?? [] };
+  }
+  return null;
+}
+
+/**
+ * Wire 级校验（W1/W2）：按 surface 顺序展开模型请求消息流，
+ * 检查 tool 消息是否悬空（缺前置 assistant tool-call）以及 user 文本
+ * 是否插在 tool_calls 与结果之间。strict 端点（MiMo 等）直接 INVALID_REQUEST。
+ * @param events - 展开后的完整事件流（含 chunk 展开）。
+ * @returns 违规列表。
+ */
+export function wireViolations(events) {
+  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;
+    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);
+      if (s !== -1 && e !== -1 && s <= e) nodes.splice(s, e - s + 1);
+      nodes.push(event.seq);
+    }
+  }
+  // 展开 wire 流
+  const wire = [];
+  for (const seq of nodes) {
+    const rec = bySeq.get(seq);
+    if (!rec) continue;
+    const m = deriveWireMessage(rec.event);
+    if (m === null) continue;
+    if (m.role === 'assistant') {
+      wire.push({ role: 'assistant', tc: m.content.filter((b) => b.type === 'tool-call').length, seq, lineNo: rec.lineNo });
+    } else if (m.role === 'user') {
+      const text = m.content.some((b) => b.type === 'text');
+      const trs = m.content.filter((b) => b.type === 'tool-result').length;
+      if (text) wire.push({ role: 'user', seq, lineNo: rec.lineNo });
+      for (let i = 0; i < trs; i++) wire.push({ role: 'tool', seq, lineNo: rec.lineNo });
+    } else {
+      wire.push({ role: m.role, seq, lineNo: rec.lineNo });
+    }
+  }
+  let pending = 0;
+  let pendingSeq = null;
+  for (const w of wire) {
+    if (w.role === 'assistant') {
+      pending = w.tc;
+      pendingSeq = pending > 0 ? w.seq : null;
+    } else if (w.role === 'tool') {
+      if (pending <= 0) {
+        out.push(violation('W1', { seq: w.seq, lineNo: w.lineNo }, `wire: tool 消息 @seq ${w.seq} 悬空——surface 中没有未满足的 assistant tool-call（严格端点会 INVALID_REQUEST）`));
+      } else {
+        pending--;
+        if (pending === 0) pendingSeq = null;
+      }
+    } else if (w.role === 'user' && pending > 0) {
+      out.push(violation('W2', { seq: w.seq, lineNo: w.lineNo }, `wire: user 文本 @seq ${w.seq} 插在 assistant tool_calls（@seq ${pendingSeq}）与其 tool 结果之间——严格端点会拒绝该序列`));
+    }
+  }
+  return out;
+}

package/lib/contracts.js

@@ -252,6 +252,24 @@ export const CONTRACT_RULES = [
     source: '审计 N5：多帧单帧全损 → 整会话不可读',
     description: '任一帧解码失败（磁盘 bitrot / 传输截断 / 并发写撕裂）即整会话不可读；帧越多，单帧损坏下丢失概率线性上升。',
   },
+
+  // ── W · wire 消息流（模型请求序列）───────────────────────────────────────
+  {
+    id: 'W1',
+    title: 'wire 流：tool 消息必须跟在带 tool-call 的 assistant 消息之后',
+    layer: LAYER.ENGINE,
+    severity: SEVERITY.ERROR,
+    source: '2026-08-27 实锤：MiMo 等严格端点对悬空 tool 直接 INVALID_REQUEST（Messages with role "tool" must be a response to a preceding message with "tool_calls"）；marker 遮蔽 assistant(tool_calls) 而未盖住 tool/result、或中断回合重放重复 tool/result 写在 marker 之后都会产生',
+    description: '按 surface 折叠顺序展开 wire 消息流：每个 role=tool 消息必须消费一个仍未满足的 assistant tool-call；不足 = 悬空（provider 拒绝）。常见来源：marker 范围漏盖 tool/result、重放重复事件。',
+  },
+  {
+    id: 'W2',
+    title: 'wire 流：user 文本不得插在 tool_calls 与其 tool 结果之间',
+    layer: LAYER.ENGINE,
+    severity: SEVERITY.ERROR,
+    source: 'OpenAI 兼容端点对 tool 消息顺序的严格校验；DSH 序列化器将混合 user 消息展开为 text 在前、tool-result 在后',
+    description: '当仍有未满足的 assistant tool-call 时出现 user 文本消息，会产生 [assistant(tool_calls), user(text), tool] 序列，严格端点同样拒绝。',
+  },
 ];
 
 /** 按 id 取规则。 */

package/lib/index.js

@@ -2,9 +2,10 @@
  * dsh-log-contract · lib/index.js
  *
  * 日志契约守护（DSH session log contract guard）。
- * 公开 API：离线体检 + 写前校验 + 契约目录。
+ * 公开 API：离线体检 + 写前校验 + 修复 + 契约目录。
  */
 export { loadSessionLog } from './log-reader.js';
 export { validateSessionLog } from './validate.js';
 export { createPreWriter, preWriterFromLog } from './prewrite.js';
+export { repairSession, strictScanText, removeMarkersText, dropFailedTurnsText, trimLastMessagesText, rebuildZstdText } from './repair.js';
 export { CONTRACT_RULES, LAYER, SEVERITY, ruleById } from './contracts.js';

package/lib/repair.js

@@ -0,0 +1,526 @@
+/**
+ * dsh-log-contract · lib/repair.js
+ *
+ * 会话日志修复（2026-08-26/27 事故后的固化方案）。
+ *
+ * 提供三类修复原语，全部经过两轮真实事故验证：
+ *  1. strictScanText —— 展开 chunk 行后做 seq==index 严格连续扫描（复刻
+ *     dsh-session-persistence-jsonl 的 committed-region 校验；该检查此前
+ *     未被离线体检覆盖，加载失败是它第一次暴露）。
+ *  2. removeMarkersText —— 移除 retrace / message-editor 的 replace marker
+ *     并全量重编号（seq / seq0 / sourceEventSeqs / surfaceOp 范围同步）。
+ *     用于"大范围 marker 遮蔽历史"（旧版 editFromScratch 产物）与
+ *     "marker 漏盖 tool/result 导致悬空 tool"。
+ *  3. rebuildZstdText —— 按官方 writer 的帧格式重建 .jsonl.zstd：
+ *     帧1 = header 行 + "\n"（单独压缩、带 checksum），帧2 = 其余行
+ *     + 结尾 "\n"（单独压缩、带 checksum）。**必须精确保持结尾单个换行**
+ *     ——双换行/无换行都会被读者判为"complete frame contains a torn
+ *     JSONL record"（2026-08-27 实锤踩坑）。
+ *
+ * 安全协议（每一步手术都必须遵守）：
+ *  - 改前备份原文件（`backup-<name>-<ts>` 同级目录或 --backup-dir）；
+ *  - 改后全量校验：strictScan + dsh-log-contract check（含 W1/W2 wire
+ *    检查）+ foldSurface；
+ *  - marker 只能遮蔽它之前的节点（replace start/end 必须已存在于 surface）；
+ *  - marker 绝不能改成 append（turn/step null → 客户端引擎崩溃 M1）；
+ *  - 运行中的 app 内存优先于文件——修复后若会话已驻留，需重启（强杀避免
+ *    脏状态刷回）。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { constants, zstdCompressSync, zstdDecompressSync } from 'node:zlib';
+import { decompressZstd, loadSessionLog } from './log-reader.js';
+import { validateSessionLog } from './validate.js';
+import { CHUNK_ROW_TYPES, MARKER_PREFIXES } from './checks.js';
+
+/** 复刻 dsh-session expandRow：chunk 行展开为完整事件（含 data/turn/step）。 */
+function expandChunkRow(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, ...(row.data.name ? { name: row.data.name } : {}), argumentsDelta: members[k] };
+        break;
+      default:
+        return [];
+    }
+    events.push({ type: 'assistant/chunk', seq: row.seq0 + k, time, data: { turn: row.data.turn, step: row.data.step, chunk } });
+  }
+  return events;
+}
+
+/** 按行解码一行 JSONL 为事件数组（chunk 行展开，损坏行返回 null）。 */
+function decodeLine(raw) {
+  let v;
+  try {
+    v = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!v || typeof v !== 'object') return null;
+  const tag = v.type;
+  if (CHUNK_ROW_TYPES.has(tag)) {
+    try {
+      return expandChunkRow(v);
+    } catch {
+      return null;
+    }
+  }
+  return [v];
+}
+
+function isRetraceMarker(event) {
+  if (event?.type !== 'assistant/message') return false;
+  if (!event.surfaceOp || typeof event.surfaceOp !== 'object' || event.surfaceOp.op !== 'replace') return false;
+  const id = event.data?.message?.id;
+  return typeof id === 'string' && MARKER_PREFIXES.some((p) => id.startsWith(`${p}-`));
+}
+
+/**
+ * 严格 seq 连续扫描（展开 chunk 行后 seq==index）。header 行（首行）跳过。
+ * @param {string} text - JSONL 全文（含 header 行）。
+ * @returns {{ failures: Array<{line:number, expected:number, got:number, type:string}>, count: number }}
+ */
+export function strictScanText(text) {
+  const lines = text.split('\n');
+  const failures = [];
+  let count = 0;
+  for (let i = 1; i < lines.length; i++) { // 跳过 header（第 1 行）
+    const raw = lines[i].trim();
+    if (!raw) continue;
+    const decoded = decodeLine(raw);
+    if (decoded === null) {
+      failures.push({ line: i + 1, kind: 'unparsable' });
+      continue;
+    }
+    for (const ev of decoded) {
+      if (typeof ev.seq !== 'number') {
+        failures.push({ line: i + 1, expected: count, got: ev.seq, type: ev.type ?? '?' });
+        continue;
+      }
+      if (ev.seq !== count) {
+        failures.push({ line: i + 1, expected: count, got: ev.seq, type: ev.type });
+        count = ev.seq + 1;
+        continue;
+      }
+      count++;
+    }
+  }
+  return { failures, count };
+}
+
+/**
+ * 移除 retrace/message-editor marker 并全量重编号。
+ * @param {string} text - JSONL 全文。
+ * @returns {{ text: string, removed: number, renumbered: number, markerSeqs: number[] }}
+ */
+export function removeMarkersText(text) {
+  const parts = text.split('\n');
+  const markerSeqs = [];
+  for (const raw of parts) {
+    if (!raw.trim()) continue;
+    const decoded = decodeLine(raw);
+    if (decoded && decoded.length === 1 && isRetraceMarker(decoded[0])) markerSeqs.push(decoded[0].seq);
+  }
+  markerSeqs.sort((a, b) => a - b);
+  if (markerSeqs.length === 0) {
+    return { text, removed: 0, renumbered: 0, markerSeqs };
+  }
+  const shiftFor = (seq) => {
+    let lo = 0;
+    let hi = markerSeqs.length;
+    while (lo < hi) {
+      const mid = (lo + hi) >> 1;
+      if (markerSeqs[mid] < seq) lo = mid + 1;
+      else hi = mid;
+    }
+    return lo;
+  };
+  const isMarkerSeq = (seq) => markerSeqs.includes(seq);
+  const out = [];
+  let removed = 0;
+  let renumbered = 0;
+  for (const raw of parts) {
+    if (!raw.trim()) {
+      out.push(raw); // 保留结尾空行（确保 join 后仍是单个结尾换行）
+      continue;
+    }
+    let v;
+    try {
+      v = JSON.parse(raw);
+    } catch {
+      out.push(raw);
+      continue;
+    }
+    if (v && typeof v === 'object' && v.type === 'assistant/message' && v.surfaceOp && v.surfaceOp.op === 'replace') {
+      const id = v.data?.message?.id;
+      if (typeof id === 'string' && MARKER_PREFIXES.some((p) => id.startsWith(`${p}-`))) {
+        removed++;
+        continue;
+      }
+    }
+    let touched = false;
+    if (typeof v.seq === 'number') {
+      const s = shiftFor(v.seq);
+      if (s) {
+        v.seq -= s;
+        touched = true;
+      }
+    }
+    if (CHUNK_ROW_TYPES.has(v.type) && typeof v.seq0 === 'number') {
+      const s = shiftFor(v.seq0);
+      if (s) {
+        v.seq0 -= s;
+        touched = true;
+      }
+    }
+    if (Array.isArray(v.sourceEventSeqs)) {
+      const next = v.sourceEventSeqs.filter((x) => !isMarkerSeq(x)).map((x) => x - shiftFor(x));
+      if (next.length !== v.sourceEventSeqs.length || next.some((x, k) => x !== v.sourceEventSeqs[k])) {
+        v.sourceEventSeqs = next;
+        touched = true;
+      }
+    }
+    if (v.surfaceOp && v.surfaceOp.op === 'replace') {
+      const ns = v.surfaceOp.start - shiftFor(v.surfaceOp.start);
+      const ne = v.surfaceOp.end - shiftFor(v.surfaceOp.end);
+      if (ns !== v.surfaceOp.start || ne !== v.surfaceOp.end) {
+        v.surfaceOp.start = ns;
+        v.surfaceOp.end = ne;
+        touched = true;
+      }
+    }
+    out.push(touched ? JSON.stringify(v) : raw);
+    if (touched) renumbered++;
+  }
+  let fixed = out.join('\n');
+  if (!fixed.endsWith('\n')) fixed += '\n';
+  return { text: fixed, removed, renumbered, markerSeqs };
+}
+
+/**
+ * 通用"删除事件 + 全量重编号"引擎：按谓词删行，seq/seq0/sourceEventSeqs/
+ * surfaceOp 范围同步平移。
+ * @param {string[]} parts - text.split('\n')。
+ * @param {(event: object) => boolean} dropPredicate - 命中即删除该事件行。
+ * @returns {{ text: string, removed: number, renumbered: number }}
+ */
+function renumberWithDrops(parts, dropPredicate) {
+  const dropped = new Set();
+  for (const raw of parts) {
+    if (!raw.trim()) continue;
+    let v;
+    try {
+      v = JSON.parse(raw);
+    } catch {
+      continue;
+    }
+    if (typeof v.seq === 'number' && dropPredicate(v)) dropped.add(v.seq);
+  }
+  const sortedDrops = [...dropped].sort((a, b) => a - b);
+  const shiftFor = (seq) => {
+    let lo = 0;
+    let hi = sortedDrops.length;
+    while (lo < hi) {
+      const mid = (lo + hi) >> 1;
+      if (sortedDrops[mid] < seq) lo = mid + 1;
+      else hi = mid;
+    }
+    return lo;
+  };
+  const isDrop = (seq) => dropped.has(seq);
+  const out = [];
+  let removed = 0;
+  let renumbered = 0;
+  for (const raw of parts) {
+    if (!raw.trim()) {
+      out.push(raw);
+      continue;
+    }
+    let v;
+    try {
+      v = JSON.parse(raw);
+    } catch {
+      out.push(raw);
+      continue;
+    }
+    if (typeof v.seq === 'number' && dropPredicate(v)) {
+      removed++;
+      continue;
+    }
+    let touched = false;
+    if (typeof v.seq === 'number') {
+      const s = shiftFor(v.seq);
+      if (s) {
+        v.seq -= s;
+        touched = true;
+      }
+    }
+    if (CHUNK_ROW_TYPES.has(v.type) && typeof v.seq0 === 'number') {
+      const s = shiftFor(v.seq0);
+      if (s) {
+        v.seq0 -= s;
+        touched = true;
+      }
+    }
+    if (Array.isArray(v.sourceEventSeqs)) {
+      const next = v.sourceEventSeqs.filter((x) => !isDrop(x)).map((x) => x - shiftFor(x));
+      if (next.length !== v.sourceEventSeqs.length || next.some((x, k) => x !== v.sourceEventSeqs[k])) {
+        v.sourceEventSeqs = next;
+        touched = true;
+      }
+    }
+    if (v.surfaceOp && v.surfaceOp.op === 'replace') {
+      const ns = v.surfaceOp.start - shiftFor(v.surfaceOp.start);
+      const ne = v.surfaceOp.end - shiftFor(v.surfaceOp.end);
+      if (ns !== v.surfaceOp.start || ne !== v.surfaceOp.end) {
+        v.surfaceOp.start = ns;
+        v.surfaceOp.end = ne;
+        touched = true;
+      }
+    }
+    out.push(touched ? JSON.stringify(v) : raw);
+    if (touched) renumbered++;
+  }
+  let fixed = out.join('\n');
+  if (!fixed.endsWith('\n')) fixed += '\n';
+  return { text: fixed, removed, renumbered };
+}
+
+/**
+ * 删除"本轮运行失败"的轮次（turn/end 带 reason.kind==='error' 的完整轮次：
+ * [turnStart..turnEnd]，含其中的 user 消息与失败产出），并全量重编号。
+ * 用于清掉界面上的失败报错气泡。
+ * @param {string} text - JSONL 全文。
+ * @returns {{ text: string, removed: number, renumbered: number, failedTurns: number }}
+ */
+export function dropFailedTurnsText(text) {
+  const parts = text.split('\n');
+  const spans = [];
+  let curTurnStart = null;
+  for (const raw of parts) {
+    if (!raw.trim()) continue;
+    let v;
+    try {
+      v = JSON.parse(raw);
+    } catch {
+      continue;
+    }
+    if (v.type === 'turn/start') curTurnStart = v.seq;
+    else if (v.type === 'turn/end') {
+      if (v.data?.reason?.kind === 'error' && curTurnStart !== null) spans.push([curTurnStart, v.seq]);
+      curTurnStart = null;
+    }
+  }
+  if (spans.length === 0) return { text, removed: 0, renumbered: 0, failedTurns: 0 };
+  const inSpan = (seq) => spans.some(([s, e]) => seq >= s && seq <= e);
+  const r = renumberWithDrops(parts, (v) => inSpan(v.seq));
+  return { ...r, failedTurns: spans.length };
+}
+
+/**
+ * 裁剪到最近 keepMessages 条 append 消息（保留其所在 turn 的结构），
+ * 同时移除全部 retrace/message-editor marker，并全量重编号。
+ * 用于"完整历史超出模型 context 窗口"（MiMo 1M tokens 实锤）。
+ * @param {string} text - JSONL 全文。
+ * @param {number} keepMessages - 保留的 append 消息数。
+ * @returns {{ text: string, removed: number, renumbered: number, kept: number, cutoff: number }}
+ */
+export function trimLastMessagesText(text, keepMessages) {
+  const parts = text.split('\n');
+  const msgSeqs = [];
+  let lastTurnStart = null;
+  for (const raw of parts) {
+    if (!raw.trim()) continue;
+    let v;
+    try {
+      v = JSON.parse(raw);
+    } catch {
+      continue;
+    }
+    if (v.type === 'user/message' || (v.type === 'assistant/message' && v.surfaceOp === 'append')) msgSeqs.push(v.seq);
+  }
+  const total = msgSeqs.length;
+  if (total <= keepMessages) return { text, removed: 0, renumbered: 0, kept: total, cutoff: 0 };
+  const cutoffMsg = msgSeqs[total - keepMessages];
+  // 往前取到包含 cutoffMsg 的那个 turn 的 turn/start，保住轮次结构
+  let cutoff = cutoffMsg;
+  for (const raw of parts) {
+    if (!raw.trim()) continue;
+    let v;
+    try {
+      v = JSON.parse(raw);
+    } catch {
+      continue;
+    }
+    if (v.type === 'turn/start' && v.seq < cutoffMsg) cutoff = v.seq;
+  }
+  const drop = (v) => (typeof v.seq === 'number' && v.seq < cutoff) || isRetraceMarker(v);
+  const r = renumberWithDrops(parts, drop);
+  return { ...r, kept: keepMessages, cutoff };
+}
+
+/**
+ * 按官方 writer 帧格式重建 .jsonl.zstd（帧1=header，帧2=其余，均带 checksum）。
+ * @param {string} text - JSONL 全文（以 "\n" 结尾）。
+ * @returns {Buffer}
+ */
+export function rebuildZstdText(text) {
+  const nl = text.indexOf('\n');
+  if (nl === -1) throw new Error('repair: JSONL 缺 header 行');
+  const header = text.slice(0, nl + 1);
+  const body = text.slice(nl + 1);
+  if (!body.endsWith('\n')) throw new Error('repair: JSONL 必须以单个换行结尾');
+  const opts = { params: { [constants.ZSTD_c_checksumFlag]: 1 } };
+  const f1 = zstdCompressSync(Buffer.from(header), opts);
+  const f2 = zstdCompressSync(Buffer.from(body), opts);
+  const out = Buffer.concat([f1, f2]);
+  // roundtrip 验证
+  const back = Buffer.concat([zstdDecompressSync(f1), zstdDecompressSync(f2)]).toString('utf8');
+  if (back !== text) throw new Error('repair: zstd 重建 roundtrip 不一致');
+  return out;
+}
+
+/**
+ * 对单个会话日志执行诊断 +（可选）修复。
+ * @param {string} file - .jsonl 或 .jsonl.zstd 路径。
+ * @param {{
+ *   removeMarkers?: boolean, dropFailedTurns?: boolean, trimLast?: number,
+ *   apply?: boolean, backupDir?: string
+ * }} opts
+ * @returns {{
+ *   file, ok, issues: Array<{kind:string, detail:string}>,
+ *   removed, renumbered, backupPath, applied,
+ *   check: { ok, summary }
+ * }}
+ */
+export function repairSession(file, opts = {}) {
+  const buf = fs.readFileSync(file);
+  const isZstd = buf.length >= 4 && buf.readUInt32LE(0) === 4247762216;
+  const issues = [];
+  let plain;
+  if (isZstd) {
+    try {
+      plain = decompressZstd(buf).toString('utf8');
+    } catch (err) {
+      return { file, ok: false, issues: [{ kind: 'zstd-decode', detail: String(err.message ?? err) }], removed: 0, renumbered: 0, applied: false };
+    }
+  } else {
+    plain = buf.toString('utf8');
+  }
+  if (!plain.endsWith('\n')) {
+    issues.push({ kind: 'trailing-newline', detail: '文件未以单个换行结尾——读者会判为撕裂记录；将补回' });
+    plain += '\n';
+  }
+  const scan = strictScanText(plain);
+  if (scan.failures.length > 0) {
+    const f = scan.failures[0];
+    issues.push({ kind: 'seq-gap', detail: `line ${f.line}：期望 ${f.expected} 实际 ${f.got}（${f.type}）——${scan.failures.length} 处` });
+  }
+  // 契约体检（含 W1/W2 wire 检查）
+  const check = validateSessionLog(loadSessionLogFromText(plain));
+  if (!check.ok) {
+    const errs = check.violations.filter((v) => v.severity === 'error');
+    issues.push({ kind: 'contract', detail: `${errs.length} 个 error 级违规（首条：${errs[0]?.id ?? '-'} ${errs[0]?.message?.slice(0, 90) ?? ''}）` });
+  }
+  let removed = 0;
+  let renumbered = 0;
+  const applyFix = (label, r, detail) => {
+    removed += r.removed;
+    renumbered += r.renumbered;
+    if (r.removed > 0) {
+      issues.push({ kind: label, detail });
+      plain = r.text;
+    }
+  };
+  if (opts.dropFailedTurns) {
+    const r = dropFailedTurnsText(plain);
+    applyFix('failed-turns', r, `移除 ${r.failedTurns} 个失败轮次（"本轮运行失败"报错气泡，重编号 ${r.renumbered} 行）`);
+  }
+  if (opts.removeMarkers) {
+    const r = removeMarkersText(plain);
+    applyFix('markers', r, `移除 ${r.removed} 个 retrace/message-editor marker（重编号 ${r.renumbered} 行）`);
+  }
+  if (typeof opts.trimLast === 'number') {
+    const r = trimLastMessagesText(plain, opts.trimLast);
+    applyFix('trim', r, `裁剪到最近 ${r.kept} 条消息（丢弃 ${r.removed} 行，重编号 ${r.renumbered} 行）`);
+  }
+  // 全部修复完成后做一次终检（中间态的临时违规不阻塞——后续修复可能已消除）
+  const scanFinal = strictScanText(plain);
+  const checkFinal = validateSessionLog(loadSessionLogFromText(plain));
+  if (scanFinal.failures.length > 0) {
+    const f = scanFinal.failures[0];
+    issues.push({ kind: 'final-scan', detail: `修复后仍不连续：line ${f.line} 期望 ${f.expected} 实际 ${f.got}——${scanFinal.failures.length} 处` });
+  }
+  if (!checkFinal.ok) {
+    const errs = checkFinal.violations.filter((v) => v.severity === 'error');
+    issues.push({ kind: 'final-contract', detail: `修复后仍有 ${errs.length} 个 error 级违规（首条：${errs[0]?.id ?? '-'} ${errs[0]?.message?.slice(0, 90) ?? ''}）` });
+  }
+  const ok = scanFinal.failures.length === 0 && checkFinal.ok;
+  let backupPath = null;
+  let applied = false;
+  if (opts.apply && ok) {
+    const dir = opts.backupDir ?? path.dirname(file);
+    const ts = new Date().toISOString().replace(/[:T]/g, '-').slice(0, 19);
+    const base = path.basename(file).replace(/\.(jsonl\.zstd|jsonl)$/, '');
+    backupPath = path.join(dir, `backup-${base}-${ts}.jsonl.zstd`);
+    fs.copyFileSync(file, backupPath);
+    const out = isZstd ? rebuildZstdText(plain) : Buffer.from(plain, 'utf8');
+    fs.writeFileSync(file + '.tmp', out);
+    fs.renameSync(file + '.tmp', file);
+    applied = true;
+  }
+  return {
+    file,
+    ok,
+    issues,
+    removed,
+    renumbered,
+    backupPath,
+    applied,
+    check,
+  };
+}
+
+/** 从文本构造 loadSessionLog 同形状对象（复用校验器）。 */
+function loadSessionLogFromText(text) {
+  const lines = text.split('\n');
+  let header = null;
+  try {
+    header = JSON.parse(lines[0]);
+  } catch {
+    header = null;
+  }
+  const rows = [];
+  const events = [];
+  for (let i = 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.trim().length === 0) continue;
+    let value;
+    try {
+      value = JSON.parse(line);
+    } catch {
+      rows.push({ lineNo: i, value: null, decoded: null, error: new Error('unparsable') });
+      continue;
+    }
+    const decoded = decodeLine(line);
+    if (decoded === null) {
+      rows.push({ lineNo: i, value, decoded: null, error: new Error('decode failed') });
+      continue;
+    }
+    for (const event of decoded) events.push({ seq: event.seq, event, lineNo: i });
+    rows.push({ lineNo: i, value, decoded, error: null });
+  }
+  events.sort((a, b) => a.seq - b.seq);
+  return { header, headerLine: 0, rows, events, frameInfo: {} };
+}

package/lib/validate.js

@@ -17,6 +17,7 @@ import {
   pluginViolations,
   replaySurface,
   violation,
+  wireViolations,
 } from './checks.js';
 
 /**
@@ -104,6 +105,9 @@ export function validateSessionLog(log, opts = {}) {
     violations.push(violation('S8', { lineNo: null }, `官方 foldSurface 重放失败：${folded.error.message} —— 会话加载会被拒（SessionPersistenceCorruptionError）`));
   }
 
+  // ── W · wire 消息流（严格端点拒绝的悬空 tool / 顺序破坏）──────────────
+  violations.push(...wireViolations(events));
+
   // ── M / P ──────────────────────────────────────────────────────────────
   for (const { event, lineNo } of events) {
     const loc = { seq: event.seq, lineNo, eventType: event.type };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-log-contract",
   "description": "日志契约守护 — DSH session log contract guard: offline health check (CLI) + pre-write validation for DeepSeek Harness session logs",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "packageManager": "pnpm@11.7.0",
   "type": "module",
   "main": "lib/index.js",