dsh-log-contract 0.3.10 → 0.3.12

package/docs/CONTRACTS.md

@@ -1,15 +1,20 @@
 # 契约规则目录（CONTRACTS）
 
+> **自动生成**（2026-09-06 起）：本文件由 `node scripts/gen-contracts-doc.mjs`
+> 从 `lib/contracts.js` 的 `CONTRACT_RULES` 注册表生成——**勿手改**，规则只增不减，
+> 新增规则后跑一次生成即同步（此前手工维护滞后 15+ 条，外部审计指出）。
+>
 > DSH 会话日志契约的**可执行 spec**。每条规则在 `lib/checks.js`（逐事件判定）
 > 与 `lib/prewrite.js`（写前校验）中有对应实现；离线体检（`lib/validate.js`）
 > 逐条执行并在最后用官方 `foldSurface` 终验（S8）。
 >
 > 规则来源：`dsh-scale-audit-疑点记录.md`（59 条审计发现）+ `复盘-会话修复事故-20260825.md`
-> （三层契约）+ `@deepseek-ai/dsh-session@0.1.0-rc.7` 官方源码逐行核对。
+> （三层契约）+ `@deepseek-ai/dsh-session@0.1.0-rc.7` 官方源码逐行核对
+> （后续规则随官方版本演进追加：T3/T4 渲染层 = 1e99e1ff 复盘，T5 = 1f4d986e malformed）。
 >
 > 严重度：**error** = 违反即会话不可加载/写入被拒（fail-loud）；**warning** = 合法但可疑。
 
-## 规则索引
+## 规则索引（共 38 条）
 
 | id | 严重度 | 层级 | 规则 |
 |---|---|---|---|
@@ -20,6 +25,8 @@
 | R3 | error | persistence | chunk 行展开后成员 seq/time 安全 |
 | E1 | error | persistence | 每个事件携带非负安全整数 seq |
 | E2 | error | persistence | seq 严格连续（单写入者假设） |
+| S9 | error | persistence | 文件物理序 seq 单调（多写入者交织现场特征） |
+| I1 | error | engine | inbox seed 相对重放（fork 边界孤儿 spliced） |
 | E3 | error | persistence | type 必须在已知词汇表内（或带 ignorable 标记） |
 | E4 | error | persistence | data 与 surface 元数据必须 JSON 无损 |
 | E5 | error | persistence | 禁用遗留词汇 |
@@ -28,16 +35,27 @@
 | S2 | error | persistence | 非 surface 类型不得携带 surface 元数据 |
 | S3 | error | persistence | append 的 sourceEventSeqs 契约 |
 | S4 | error | persistence | replace 操作数与范围合法性 |
-| S5 | error | persistence | ★ replace 的 sourceEventSeqs 必须完整覆盖被替换节点 |
+| S5 | error | persistence | replace 的 sourceEventSeqs 必须完整覆盖被替换节点 |
 | S6 | error | persistence | sourceEventSeqs 自身约束 |
 | S7 | error | persistence | tool/result 替换仅允许单节点内容改写 |
-| S8 | error | persistence | 整日志 foldSurface 可重放（终验） |
+| S8 | error | persistence | 整日志 foldSurface 可重放 |
+| T1 | error | engine | token-meter 配对：assistant/message 与 step/end 必须匹配当前打开的 step/start |
+| T2 | error | engine | token-meter 源引用：assistant/message 的 sourceEventSeqs 引用的 chunk 必须同 turn/step |
+| T3 | error | engine | step 节点 key 唯一（同 turn 内 step/start 的 step 号不得复用） |
+| T4 | error | engine | step/消息本体 turn 缺失（null/undefined）→ 渲染死循环 |
+| T5 | error | engine | turn/end 必须带 data.reason.kind |
+| E7 | warning | persistence | ignorable 未知 type 合法性（带被忽略标记的未知事件须有消费者） |
+| Z3 | warning | framing | 空会话文件（有 header 无事件）显式报出 |
+| P3 | warning | plugin | tool/call ↔ tool/result 配对完整性（考古 B1） |
+| P4 | warning | plugin | tool/result 输出结构可解析（考古 B2） |
 | M1 | error | engine | turn/step 为 null 的 assistant/message 只能 replace，不能 append |
 | P1 | warning | plugin | marker id 前缀必须被识别 |
 | P2 | error | plugin | marker 自身 seq 不得出现在自身 shadowed 集 |
 | C1 | warning | concurrency | seq 缺口/倒退提示多写入者 |
 | Z1 | warning | framing | zstd 尾帧撕裂 |
 | Z2 | error | framing | zstd 帧解码失败 = 单帧全损 |
+| W1 | error | engine | wire 流：tool 消息必须跟在带 tool-call 的 assistant 消息之后 |
+| W2 | error | engine | wire 流：user 文本不得插在 tool_calls 与其 tool 结果之间 |
 
 ## 详细规则
 
@@ -83,6 +101,18 @@
 - **出处**: @deepseek-ai/dsh-session lib/index.js:398 (planSurfaceEvent "not contiguous")；审计 S2/N6
 - **契约**: seq 必须从 0（或窗口 baseSeq）严格连续递增。缺口/倒退 = 违反单写入者假设（多实例共享存储并发写的痕迹），加载时直接 throw。
 
+### S9 — 文件物理序 seq 单调（多写入者交织现场特征）
+
+- **层级**: persistence ｜ **严重度**: error
+- **出处**: 2026-08-28 实锤：526f1835 文件物理序 734056→733539→735470；单进程 appendCore 断言 seq==cursor+i 且按 id 串行化不可能写出
+- **契约**: 按文件物理行序要求展开后事件 seq 严格单调递增。E2 在排序后检查（loadSessionLog 会 sort），物理序倒退被掩盖；S9 在排序前按行序检查，非单调 = 多写入者/旧光标回放交织的直接现场证据，加载会被拒。
+
+### I1 — inbox seed 相对重放（fork 边界孤儿 spliced）
+
+- **层级**: engine ｜ **严重度**: error
+- **出处**: @deepseek-ai/dsh-agent lib/types/inbox.js:155-178 (apply/validate)；2026-08-28 实锤：62c5b531/73ed35d8 fork 边界 removedCount=1 孤儿
+- **契约**: 从 header.seedLength 起重放 agent/inbox/spliced，next-turn/next-step 双队列；start+removedCount 不得超过队列长、不得产生重复 pending id。fork 时"移除父待处理提示词"的 splice 假设父会话 inbox，子会话 seed 相对空 inbox 上非法 → resume 被拒（invalid persisted inbox splice）。
+
 ### E3 — type 必须在已知词汇表内（或带 ignorable 标记）
 
 - **层级**: persistence ｜ **严重度**: error
@@ -155,6 +185,60 @@
 - **出处**: @deepseek-ai/dsh-session lib/index.js:444-455 (foldSurface)；复盘"官方 foldSurface 不抛 = 通过"
 - **契约**: 终验：把全部事件按序喂给官方 foldSurface，不抛 = 持久化层通过。S1–S7 任何一条违反都会在此暴露。
 
+### T1 — token-meter 配对：assistant/message 与 step/end 必须匹配当前打开的 step/start
+
+- **层级**: engine ｜ **严重度**: error
+- **出处**: @deepseek-ai/dsh-token-meter lib/index.js:566-625 (_foldEvent)
+- **契约**: token meter 折叠要求 assistant/message 与 step/end 与打开的 step/start（turn/step 完全一致）匹配；违反即 /compact 与压力测量永久失败。retrace 的 turn-null 编辑/撤回 marker（空 assistant/message replace）命中此条——foldSurface 认可其合法性但 token meter 崩溃（M1 只约束 append 形态的盲区），压缩前需清理。
+
+### T2 — token-meter 源引用：assistant/message 的 sourceEventSeqs 引用的 chunk 必须同 turn/step
+
+- **层级**: engine ｜ **严重度**: error
+- **出处**: @deepseek-ai/dsh-token-meter lib/index.js:634-650 (_estimateProviderAssistant，:645 belongs to another step)
+- **契约**: token meter 重建 provider 输出时，逐条检查 assistant/message 的 sourceEventSeqs：指向 assistant/chunk 的引用必须与消息同 turn/step，且 seq 更早、不重复；跨 step 引用 → 官方抛 belongs to another step → 每次事件追加都重抛（consumedEvents 不前进）→ 刷屏压垮 host（2026-08-30 实测 526f1835 seq 936047 跨 step 7/8/9）。T1 只查 step 配对不查源引用，此条补盲区；修复用 fix --clip-crossstep。
+
+### T3 — step 节点 key 唯一（同 turn 内 step/start 的 step 号不得复用）
+
+- **层级**: engine ｜ **严重度**: error
+- **出处**: 复盘 2026-09-02 1e99e1ff 白屏（修复线 session-3f9e4f12）：客户端渲染节点 key = turn:step，冲突 → React 渲染死循环；工具 tools/check-step-keys.mjs
+- **契约**: 客户端渲染消息列表从事件流构建节点，节点 key = data.turn:data.step。同 turn 内两个 step/start 的 step 号相同 → key 冲突 → React 渲染死循环 → 白屏/不展示（1e99e1ff：580034 step 95/1 vs 580037 编辑块 step 95/1；6924781d/97786207/4b149a4a 同型）。修复：同 turn 内 step 递增、整块重编号（含块内 chunk/tool/assistant）。
+
+### T4 — step/消息本体 turn 缺失（null/undefined）→ 渲染死循环
+
+- **层级**: engine ｜ **严重度**: error
+- **出处**: 复盘 D8 1e99e1ff（2026-09-01）：retrace 0.4.17 编辑块 turn:null；修复线 tools/check-null-turn.mjs 判致命
+- **契约**: 客户端渲染状态机对 turn=null 的 step/start|step/end|assistant/message 无法归属任何 turn → 渲染死循环 → 白屏「载入历史」（1e99e1ff seq 580037-580039）。user/message 天然无 turn 不查；chunk 坐标可缺失不查。step/消息本体必须带真实 turn 号。
+
+### T5 — turn/end 必须带 data.reason.kind
+
+- **层级**: engine ｜ **严重度**: error
+- **出处**: 官方 dsh-agent-loop lib/index.js:620（turn/end = {turn, reason:{kind}}）；1f4d986e malformed turn/end 事故（2026-09-02，修复线 check-turn-end-reason.mjs）
+- **契约**: 官方 validation 强制 turn/end 的 data.reason.kind 存在（kind ∈ completed|max-tokens|blocked|aborted|error|interrupted）。缺失 = malformed → 官方 SessionPersistenceCorruptionError → 会话加载失败。1f4d986e：retrace 情形③信封 turn/end 漏 reason → 每次编辑后加载失败（已修 0.4.18）。
+
+### E7 — ignorable 未知 type 合法性（带被忽略标记的未知事件须有消费者）
+
+- **层级**: persistence ｜ **严重度**: warning
+- **出处**: 反向挑刺 2026-09-09 T2（E3 ignorable 无合法性校验 = 后门）
+- **契约**: 未知 type + ignorable:true 被读路径接纳但无人消费 = 静默垃圾。排除已知消费者白名单（retrace/marker、retrace/goal-marker、message-editor/ 前缀等 retrace 客户端消费的插件 marker）后，其余 ignorable 未知事件报 warning。
+
+### Z3 — 空会话文件（有 header 无事件）显式报出
+
+- **层级**: framing ｜ **严重度**: warning
+- **出处**: 反向挑刺 2026-09-09 T3（36 条规则全来自有内容事故,空态无覆盖）
+- **契约**: 有 header 但零事件 = 异常空会话（新建即空或写入未落盘）。空态不在任何有内容规则的覆盖下,显式 warning 供人判断。
+
+### P3 — tool/call ↔ tool/result 配对完整性（考古 B1）
+
+- **层级**: plugin ｜ **严重度**: warning
+- **出处**: dsh-会话日志考古-插件任务与方法.md §2/§4.2（callId 配对，不可用"上一个 call"推断）
+- **契约**: 每个 tool/call 的 data.callId 必须能在 tool/result 的 data.message.source.callId 中找到配对；孤儿 call（无 result）告警——中断/失败轮次可能产生孤儿（合法但要审计），考古提取将缺该输出。
+
+### P4 — tool/result 输出结构可解析（考古 B2）
+
+- **层级**: plugin ｜ **严重度**: warning
+- **出处**: dsh-会话日志考古-插件任务与方法.md §2/§4.2（content 递归 text 结构）
+- **契约**: tool/result 的 data.message.content 必须可递归解析（list[dict{type:text,text}] 或等价）；不可解析片段 = 考古提取将漏数据。空 content（失败/无输出）合法。
+
 ### M1 — turn/step 为 null 的 assistant/message 只能 replace，不能 append
 
 - **层级**: engine ｜ **严重度**: error
@@ -191,19 +275,15 @@
 - **出处**: 审计 N5：多帧单帧全损 → 整会话不可读
 - **契约**: 任一帧解码失败（磁盘 bitrot / 传输截断 / 并发写撕裂）即整会话不可读；帧越多，单帧损坏下丢失概率线性上升。
 
----
-
-## 边界说明（诚实声明）
-
-1. **本工具守护"持久化契约层"**。`#3632` 的"one log, two consumers, two verdicts"中，
-   `agent/inbox/spliced` 孤儿在持久化层**是合法的**（官方 `foldSurface` 可通过）——
-   违规发生在**消费路径**（`sessionQuery`/UI 判不可读）。本工具的 `check` 会如实报 PASS，
-   不冒充能判消费路径契约；该层契约属另一类问题（可配合 dsh-retrace / 上游修复）。
-2. **M1 是引擎层启发式规则**：`data.turn/step` 为 null 的 `assistant/message` 以 append 进入
-   surface 会触发客户端引擎崩溃（rt.js:6816）——依据是 2026-08-25 事故第 2 轮实证。
-   离线场景无法渲染客户端，故以 error 级保守拦截，避免事故重演。
-3. **写前校验以"官方 foldSurface 不抛"为最终权威**：逐事件归因（S1–S7）负责定位，
-   官方重放（S8）负责背书；两套都绿才算通过。若官方实现更新导致判定漂移，
-   以官方为准并更新本 spec（本工具自己就是契约漂移的哨兵）。
-4. **seq 严格连续是单写入者假设**（N6）：离线 `check` 只能看到缺口/倒退的结果，
-   无法观测竞态本身；`C1` 给出解释性告警而非臆断。
+### W1 — wire 流：tool 消息必须跟在带 tool-call 的 assistant 消息之后
+
+- **层级**: engine ｜ **严重度**: error
+- **出处**: 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 之后都会产生
+- **契约**: 按 surface 折叠顺序展开 wire 消息流：每个 role=tool 消息必须消费一个仍未满足的 assistant tool-call；不足 = 悬空（provider 拒绝）。常见来源：marker 范围漏盖 tool/result、重放重复事件。
+
+### W2 — wire 流：user 文本不得插在 tool_calls 与其 tool 结果之间
+
+- **层级**: engine ｜ **严重度**: error
+- **出处**: OpenAI 兼容端点对 tool 消息顺序的严格校验；DSH 序列化器将混合 user 消息展开为 text 在前、tool-result 在后
+- **契约**: 当仍有未满足的 assistant tool-call 时出现 user 文本消息，会产生 [assistant(tool_calls), user(text), tool] 序列，严格端点同样拒绝。
+

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 };
   }
@@ -387,6 +429,35 @@ export function turnEndReasonViolations(events) {
   return out
 }
 
+/**
+ * E7 —— ignorable 未知 type 合法性（2026-09-09 反向挑刺 T2 增量）。
+ *
+ * 盲区：E3 对"未知 type + ignorable:true"直接放行（容忍更新版本 harness 写入），
+ * 但 ignorable 标记无合法性校验 = 后门——被读路径接纳却无人消费的未知事件 =
+ * 静默垃圾（违 R3 精神）。补：未知 type + ignorable + **不在已知消费者白名单** →
+ * warning"有被忽略的未知事件"。
+ *
+ * 已知消费者（不算垃圾，排除）：retrace 家族 marker（retrace/marker、retrace/goal-marker，
+ * neutralize/插件产物，retrace 客户端识别消费）与旧前缀 message-editor。
+ * 判定：type ∉ KNOWN && ignorable && 非已知插件前缀 → warning。
+ */
+const KNOWN_IGNORABLE_CONSUMERS = new Set(['retrace/marker', 'retrace/goal-marker'])
+function isKnownIgnorableType(type) {
+  if (typeof type !== 'string') return false
+  if (KNOWN_IGNORABLE_CONSUMERS.has(type)) return true
+  return type.startsWith('message-editor/') || type.startsWith('retrace/')
+}
+export function ignorableTypeViolations(events, version) {
+  const out = []
+  for (const { event, lineNo } of events) {
+    if (typeof event?.type !== 'string' || event.ignorable !== true) 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）`))
+  }
+  return out
+}
+
 /**
  * P3 —— tool/call ↔ tool/result 配对完整性（考古任务书 B1）。
  * 每个 tool/call 的 `data.callId` 必须能在 tool/result 的
@@ -396,7 +467,7 @@ export function turnEndReasonViolations(events) {
 export function toolPairingViolations(events) {
   const out = [];
   const calls = new Map(); // callId → { command, loc }
-  const results = new Set();
+  const results = new Map(); // callId → loc（双向：孤儿 result 也要指认，2026-09-09 反向挑刺 T1）
   for (const { event, lineNo } of events) {
     if (event.type === 'tool/call') {
       const callId = event.data?.callId;
@@ -410,7 +481,7 @@ export function toolPairingViolations(events) {
       }
     } else if (event.type === 'tool/result') {
       const callId = event.data?.message?.source?.callId;
-      if (typeof callId === 'string' && callId !== '') results.add(callId);
+      if (typeof callId === 'string' && callId !== '') results.set(callId, { seq: event.seq, lineNo, eventType: event.type });
     }
   }
   for (const [callId, { command, loc }] of calls) {
@@ -418,6 +489,14 @@ export function toolPairingViolations(events) {
       out.push(violation('P3', loc, `tool/call ${callId}（命令 ${command || '(未知)'}）没有配对的 tool/result——孤儿调用（中断/失败未落结果），考古提取将缺该输出`));
     }
   }
+  // 双向（反向挑刺 T1 增量）：孤儿 result = result 无对应 tool/call。
+  // 折叠后 wire 流中无主 tool 消息 = provider 拒绝风险（W1/W2 同族、不同层）；
+  // 与孤儿 call 同为 warning 级——合法场景（中断/修复产物）不破坏日志。
+  for (const [callId, loc] of results) {
+    if (!calls.has(callId)) {
+      out.push(violation('P3', loc, `tool/result ${callId} 没有配对的 tool/call——孤儿结果（无主 tool 消息，wire 流 provider 拒绝风险；中断/修复产物合法但要审计），考古配对将无法归属`));
+    }
+  }
   return out;
 }
 
@@ -648,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);
     }
@@ -703,3 +783,39 @@ export function wireViolations(events) {
   }
   return out;
 }
+
+/**
+ * G · 迁移预检（payload 层 + 类型层）——**官方迁移会不会拒**，与"本工具能否读取/折叠"是
+ * **两个独立维度**（见 contracts.js 的 LAYER.MIGRATION 段）。
+ *
+ * 只覆盖已取得一手出处的两条（G1 descriptor version / G2 unknown historical type）；
+ * 官方迁移规则集更宽（turn/start 未闭合、继承切点、title messageSeqs、stored-log corrupt…），
+ * 未覆盖部分由 `migrationVerdict().coverage.uncovered` 显式列出——**不许**把未覆盖当通过。
+ *
+ * 范围：两条都只约束 **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`));
+    }
+  }
+  return out;
+}