dsh-log-contract 0.3.7 → 0.3.9

package/README.md

@@ -274,10 +274,16 @@ pnpm check && pnpm test    # syntax check + 79 unit tests (incl. incident regres
 node scripts/check-local-fossils.mjs   # scans ../ for backup-session-*.jsonl.zstd
 ```
 
-Known truth table: incident-repaired sessions PASS; `seqgap`/`corrupt`/
-`rewritten-230542` FAIL; `spliced-orphan` PASS (legal for the persistence layer —
-#3632's "consumer path deems it unreadable" is a different contract; this tool only
-guards the persistence contract layer, see the boundary note in
+Known truth table (updated 2026-08-31 — after 0.3.5 added I1, `spliced-orphan`
+now FAILs; the old PASS row was stale):
+- `2c3f87d4-corrupt` / `b7713ea1-seqgap` / `rewritten-230542` → FAIL (seq gaps)
+- `2c3f87d4-spliced-orphan` → **FAIL (0.3.5+)** (T1/I1: invalid inbox splice + turn-null)
+- `e61d70da-pre-markerfix-20260825` → FAIL (pre-fix sample: turn-null markers remain)
+- `c2d05ce9-pre-cleansession-20260831` → PASS (3256-span replace marker is data-legal;
+  official foldSurface replays cleanly — see the plugin ledger)
+The truth table tracks rule evolution (0.3.5's I1 flipped spliced-orphan PASS→FAIL);
+"repaired sessions PASS" must be verified on rebuilt samples — `pre-` backups are
+usually pre-fix bad samples. See the boundary note in
 [docs/CONTRACTS.md](docs/CONTRACTS.md)).
 
 ---

package/README.zh.md

@@ -236,7 +236,19 @@ pnpm check && pnpm test    # 语法检查 + 79 个单测（含事故回归用例
 node scripts/check-local-fossils.mjs   # 扫描 ../ 下 backup-session-*.jsonl.zstd
 ```
 
-已知真值表：事故修复后会话 PASS；`seqgap`/`corrupt`/`rewritten-230542` FAIL；`spliced-orphan` PASS（持久化层合法——#3632 的"消费路径判不可读"属于另一类契约，本工具只守护持久化契约层，见 [docs/CONTRACTS.md](docs/CONTRACTS.md) 边界说明）。
+已知真值表（2026-08-31 实测更新——0.3.5 加 I1 后，`spliced-orphan` 已可报错，旧表 PASS 过时）：
+
+| 化石 | 判定 | 违规 |
+|---|---|---|
+| `2c3f87d4-corrupt` | FAIL | S8/C1/T1/E2（seq 缺口 → 加载被拒） |
+| `b7713ea1-seqgap` / `recorrupt` | FAIL | S8/C1/T1/E2/S9（seq 缺口/倒退） |
+| `2c3f87d4-rewritten-230542` | FAIL | S8/C1/T1/E2/I1（重写引入缺口） |
+| `2c3f87d4-spliced-orphan` | **FAIL（0.3.5+）** | T1/I1（inbox splice 无效 + turn-null）——旧表 PASS 已过时 |
+| `e61d70da-pre-markerfix-20260825` | FAIL | T1×5（修复前样本：turn-null marker 残留，非「修复后」） |
+| `c2d05ce9-pre-cleansession-20260831` | **PASS** | error 0（3256 跨度 replace marker 数据合规，官方 foldSurface 重放通过——见插件任务台账） |
+
+> 说明：真值表随规则演进更新（0.3.5 新增 I1 后 spliced-orphan 从 PASS 变 FAIL）；
+> 「修复后会话 PASS」需用重建/修复后的样本验证，pre- 前缀备份多为修复前坏样本。
 
 ---
 

package/lib/checks.js

@@ -296,6 +296,97 @@ export function finalFold(events) {
   }
 }
 
+/**
+ * T3 —— step 节点 key 冲突（2026-09-02 · 1e99e1ff 白屏真正根因固化）。
+ *
+ * 客户端渲染消息列表 = 从事件流构建节点，节点 key = `data.turn:data.step`
+ * （React 列表 key）。同 turn 内两个 step/start 的 step 号相同 → key 冲突 →
+ * React 渲染死循环 → 白屏/不展示（1e99e1ff：seq 580034 step 95/1 vs 580037
+ * 编辑块 step 95/1；修复线 2026-09-02 全量扫描另发现 6924781d / 97786207 /
+ * 4b149a4a 同型冲突，均整块重编号修复）。
+ *
+ * 判定：扫 step/start，`data.turn:data.step` 组合重复 = error。
+ * - 无任何 step/start 的日志跳过（与 T1 同款宽松）；
+ * - turn/step 为 null/undefined 的 step/start 不参与 key 判定（那是 T4 的域，
+ *   且 null 自身已是致命）。
+ *
+ * @param events - 行序事件流（`{event, lineNo}`）。
+ * @returns T3 违规列表。
+ */
+export function stepKeyViolations(events) {
+  const out = []
+  if (!events.some(({ event }) => event.type === 'step/start')) return out
+  const seen = new Map() // `${turn}:${step}` → { seq, lineNo }
+  for (const { event, lineNo } of events) {
+    if (event.type !== 'step/start') continue
+    const turn = event.data?.turn
+    const step = event.data?.step
+    if (turn === null || turn === undefined || step === null || step === undefined) continue // T4 域
+    const key = `${String(turn)}:${String(step)}`
+    const prev = seen.get(key)
+    if (prev !== undefined) {
+      out.push(violation('T3', { seq: event.seq, lineNo, eventType: event.type }, `step 节点 key ${key} 冲突：seq ${prev.seq} 与 seq ${event.seq} 的 step/start 同 turn 同 step——客户端 React 渲染死循环白屏（1e99e1ff 事故；修复：同 turn 内 step 递增，不得复用；整块重编号）`))
+    } else {
+      seen.set(key, { seq: event.seq, lineNo })
+    }
+  }
+  return out
+}
+
+/**
+ * T4 —— step/消息本体 turn 缺失（null/undefined）（2026-09-01 · D8 1e99e1ff 固化）。
+ *
+ * 客户端渲染状态机对 turn=null 的 step/消息**无法归属任何 turn** → 渲染死循环 →
+ * 白屏「载入历史」（1e99e1ff seq 580037-580039：retrace 0.4.17 写的编辑块
+ * step/start+marker+step/end turn 全 null；修复线 check-null-turn.mjs 把 step
+ * 包裹/消息本体的 null-turn 判为致命）。
+ *
+ * 判定：`step/start|step/end|assistant/message` 的 `data.turn === null/undefined` = error。
+ * - user/message 天然不带 turn（坐标来自外层 step），不查；
+ * - assistant/chunk 坐标可能天然缺失，不查；
+ * - retrace/marker（neutralize 产物，ignorable）不查。
+ *
+ * @param events - 行序事件流（`{event, lineNo}`）。
+ * @returns T4 违规列表。
+ */
+export function nullTurnStepViolations(events) {
+  const out = []
+  for (const { event, lineNo } of events) {
+    if (event.type !== 'step/start' && event.type !== 'step/end' && event.type !== 'assistant/message') continue
+    const turn = event.data?.turn
+    if (turn === null || turn === undefined) {
+      out.push(violation('T4', { seq: event.seq, lineNo, eventType: event.type }, `${event.type} 的 data.turn 为 ${String(turn)}（缺失）——客户端渲染状态机无法归属任何 turn → 渲染死循环白屏（D8 1e99e1ff；step/消息本体必须带真实 turn 号）`))
+    }
+  }
+  return out
+}
+
+/**
+ * T5 —— turn/end 缺 reason.kind（2026-09-02 · 1f4d986e malformed turn/end 固化）。
+ *
+ * 官方 agent-loop 写 turn/end 恒带 `reason: { kind }`（dsh-agent-loop/lib/index.js:620；
+ * kind ∈ completed|max-tokens|blocked|aborted|error|interrupted，中断恢复补
+ * interrupted，见 dsh-session interruptedTurnClosers）。官方 validation 强制
+ * reason.kind 存在——缺失 = malformed → 会话加载失败
+ * （SessionPersistenceCorruptionError "malformed pre-react-loop turn/end"，1f4d986e）。
+ *
+ * 判定：turn/end 的 `data.reason?.kind` 缺失/非字符串 = error。
+ *
+ * @param events - 行序事件流（`{event, lineNo}`）。
+ * @returns T5 违规列表。
+ */
+export function turnEndReasonViolations(events) {
+  const out = []
+  for (const { event, lineNo } of events) {
+    if (event.type !== 'turn/end') continue
+    const reason = event.data?.reason
+    if (!reason || typeof reason.kind !== 'string') {
+      out.push(violation('T5', { seq: event.seq, lineNo, eventType: event.type }, `turn/end 缺 data.reason.kind（reason=${JSON.stringify(reason)}）——官方 validation 拒绝 → 会话加载失败（1f4d986e malformed turn/end；turn/end 必须带 reason.kind，镜像 dsh-agent-loop:620）`))
+    }
+  }
+  return out
+}
+
 /**
  * P3 —— tool/call ↔ tool/result 配对完整性（考古任务书 B1）。
  * 每个 tool/call 的 `data.callId` 必须能在 tool/result 的

package/lib/contracts.js

@@ -229,6 +229,30 @@ export const CONTRACT_RULES = [
     source: '@deepseek-ai/dsh-token-meter lib/index.js:634-650 (_estimateProviderAssistant，:645 belongs to another step)',
     description: '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。',
   },
+  {
+    id: 'T3',
+    title: 'step 节点 key 唯一（同 turn 内 step/start 的 step 号不得复用）',
+    layer: LAYER.ENGINE,
+    severity: SEVERITY.ERROR,
+    source: '复盘 2026-09-02 1e99e1ff 白屏（修复线 session-3f9e4f12）：客户端渲染节点 key = turn:step，冲突 → React 渲染死循环；工具 tools/check-step-keys.mjs',
+    description: '客户端渲染消息列表从事件流构建节点，节点 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）。',
+  },
+  {
+    id: 'T4',
+    title: 'step/消息本体 turn 缺失（null/undefined）→ 渲染死循环',
+    layer: LAYER.ENGINE,
+    severity: SEVERITY.ERROR,
+    source: '复盘 D8 1e99e1ff（2026-09-01）：retrace 0.4.17 编辑块 turn:null；修复线 tools/check-null-turn.mjs 判致命',
+    description: '客户端渲染状态机对 turn=null 的 step/start|step/end|assistant/message 无法归属任何 turn → 渲染死循环 → 白屏「载入历史」（1e99e1ff seq 580037-580039）。user/message 天然无 turn 不查；chunk 坐标可缺失不查。step/消息本体必须带真实 turn 号。',
+  },
+  {
+    id: 'T5',
+    title: 'turn/end 必须带 data.reason.kind',
+    layer: LAYER.ENGINE,
+    severity: SEVERITY.ERROR,
+    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: 'P3',
     title: 'tool/call ↔ tool/result 配对完整性（考古 B1）',

package/lib/index.js

@@ -9,5 +9,5 @@ export { validateSessionLog, resumeVerdict } 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, physicalOrderViolations, inboxReplayViolations } from './checks.js';
+export { tokenMeterViolations, tokenMeterSourceViolations, stepKeyViolations, nullTurnStepViolations, turnEndReasonViolations, physicalOrderViolations, inboxReplayViolations } from './checks.js';
 export { auditToolCalls, extractText, extractToolOutputs, indexToolCalls, toolCommandOf } from './archaeology.js';

package/lib/prewrite.js

@@ -17,7 +17,7 @@
  * 所有判定复用 `lib/checks.js`（与离线体检同一套逻辑），
  * 保证"体检看到的问题 = 写入前拦下的问题"。
  */
-import { envelopeViolations, engineViolations, finalFold, isSafeInt, pluginViolations, replaySurface, tokenMeterViolations, violation } from './checks.js';
+import { envelopeViolations, engineViolations, finalFold, isSafeInt, nullTurnStepViolations, pluginViolations, replaySurface, stepKeyViolations, tokenMeterViolations, turnEndReasonViolations, violation } from './checks.js';
 
 /** retrace 类 marker：data.editor 存在（assistant/message replace，turn/step=null）。 */
 function isKnownMarkerCandidate(event) {
@@ -98,6 +98,24 @@ export function createPreWriter(input = {}) {
         violations.push(t1);
       }
     }
+    // T3/T4 —— 渲染层（2026-09-02 1e99e1ff 白屏）。**error 级拒绝**：
+    // - T4：拟写事件（step/start|step/end|assistant/message）turn 缺失 → 客户端
+    //   渲染死循环白屏（D8），写入前直接拦下（防再犯：任何写 turn:null 的 marker）；
+    // - T3：拟写事件引入 step 节点 key 冲突（同 turn 同 step 的 step/start 重复）→
+    //   同样拒绝。只判拟写事件自身（历史冲突归属离线 check 的 T3/T4 扫描）。
+    for (const v of nullTurnStepViolations(candidateEvents.map((event) => ({ event })))) {
+      if (v.seq !== lastCandidate?.seq) continue;
+      violations.push(v);
+    }
+    for (const v of stepKeyViolations(candidateEvents.map((event) => ({ event })))) {
+      if (v.seq !== lastCandidate?.seq) continue;
+      violations.push(v);
+    }
+    // T5 —— 拟写 turn/end 缺 reason.kind → error 拒绝（1f4d986e 防再犯）
+    for (const v of turnEndReasonViolations(candidateEvents.map((event) => ({ event })))) {
+      if (v.seq !== lastCandidate?.seq) continue;
+      violations.push(v);
+    }
     const bySeverity = { error: 0, warning: 0, info: 0 };
     for (const v of violations) bySeverity[v.severity] = (bySeverity[v.severity] ?? 0) + 1;
     return {

package/lib/validate.js

@@ -15,9 +15,12 @@ import {
   finalFold,
   inboxReplayViolations,
   isSafeInt,
+  nullTurnStepViolations,
   physicalOrderViolations,
   pluginViolations,
   replaySurface,
+  stepKeyViolations,
+  turnEndReasonViolations,
   violation,
   tokenMeterViolations,
   tokenMeterSourceViolations,
@@ -115,6 +118,12 @@ export function validateSessionLog(log, opts = {}) {
   violations.push(...tokenMeterViolations(events));
   violations.push(...tokenMeterSourceViolations(events));
 
+  // ── T3/T4/T5 · 渲染/契约层（复盘 2026-09-02）：节点 key 唯一 + turn 缺失 + turn/end reason ──
+  // 数据层"健康"≠ 客户端能渲染/能加载：check/官方加载/分页全绿仍可能白屏或加载失败。
+  violations.push(...stepKeyViolations(events));
+  violations.push(...nullTurnStepViolations(events));
+  violations.push(...turnEndReasonViolations(events));
+
   // ── I1 · inbox seed 相对重放（fork 边界孤儿；交接书 L1）──────────────
   violations.push(...inboxReplayViolations(events, header));
 
@@ -190,9 +199,9 @@ export function validateSessionLog(log, opts = {}) {
 export function resumeVerdict(result) {
   const { ok, violations = [] } = result;
   // 三档各自的「阻断规则集」——按任务书 §L3 档位定义：
-  //   可加载：结构层（PERSISTENCE/FRAMING）+ 引擎层非 I1/T1/T2 的 error；
+  //   可加载：结构层（PERSISTENCE/FRAMING）+ 引擎层非 I1/T1/T2/T3/T4 的 error；
   //   可继续：+ I1（inbox 重放）；
-  //   可压缩：+ T1/T2（token-meter 配对）。
+  //   可压缩：+ T1/T2/T3/T4（token-meter 配对 + 渲染层节点 key/turn）。
   const byId = {};
   for (const v of violations) {
     if (v.severity !== 'error') continue;
@@ -200,11 +209,11 @@ export function resumeVerdict(result) {
   }
   const has = (id) => (byId[id]?.length ?? 0) > 0;
 
-  // 可加载阻断 = 除 I1/T1/T2 外的所有 error 违规（结构/信封/物理序/工具配对等）。
-  // 注意：不能用 result.ok（它把 T1/T2/I1 也计为 error）——三档判定按任务书定义，
-  // T1/T2 只影响「可压缩」档、I1 只影响「可继续」档。
+  // 可加载阻断 = 除 I1/T1/T2/T3/T4 外的所有 error 违规（结构/信封/物理序/工具配对等）。
+  // 注意：不能用 result.ok（它把 T1/T2/T3/T4/I1 也计为 error）——三档判定按任务书定义，
+  // T1/T2/T3/T4 只影响「可压缩」档、I1 只影响「可继续」档。
   const loadableBlockers = violations.filter(
-    (v) => v.severity === 'error' && !['I1', 'T1', 'T2'].includes(v.id),
+    (v) => v.severity === 'error' && !['I1', 'T1', 'T2', 'T3', 'T4', 'T5'].includes(v.id),
   ).map((v) => v.id);
   const loadable = loadableBlockers.length === 0;
 
@@ -212,9 +221,9 @@ export function resumeVerdict(result) {
   const resumable = loadable && !has('I1');
 
   const compactableBlockers = resumable
-    ? (has('T1') || has('T2') ? ['T1', 'T2'].filter((id) => has(id)) : [])
+    ? (has('T1') || has('T2') || has('T3') || has('T4') || has('T5') ? ['T1', 'T2', 'T3', 'T4', 'T5'].filter((id) => has(id)) : [])
     : [];
-  const compactable = resumable && !has('T1') && !has('T2');
+  const compactable = resumable && !has('T1') && !has('T2') && !has('T3') && !has('T4') && !has('T5');
 
   // 最差档位
   const verdict = !loadable ? 'broken' : !resumable ? 'loadable' : !compactable ? 'resumable' : 'compactable';
@@ -232,7 +241,7 @@ export function resumeVerdict(result) {
     violationsByTier: {
       structural: [...new Set(loadableBlockers)],
       inbox: has('I1') ? ['I1'] : [],
-      tokenMeter: has('T1') || has('T2') ? ['T1', 'T2'].filter((id) => has(id)) : [],
+      tokenMeter: has('T1') || has('T2') || has('T3') || has('T4') || has('T5') ? ['T1', 'T2', 'T3', 'T4', 'T5'].filter((id) => has(id)) : [],
     },
   };
 }

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.3.7",
+  "version": "0.3.9",
   "packageManager": "pnpm@11.7.0",
   "type": "module",
   "main": "lib/index.js",