dsh-log-contract 0.3.8 → 0.3.10

package/lib/checks.js

@@ -361,6 +361,32 @@ export function nullTurnStepViolations(events) {
   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

@@ -245,6 +245,14 @@ export const CONTRACT_RULES = [
     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

@@ -4,10 +4,10 @@
  * 日志契约守护（DSH session log contract guard）。
  * 公开 API：离线体检 + 写前校验 + 修复 + 契约目录。
  */
-export { loadSessionLog, tailSeq } from './log-reader.js';
+export { loadSessionLog, tailSeq, readSessionHeader } from './log-reader.js';
 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, stepKeyViolations, nullTurnStepViolations, 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/log-reader.js

@@ -220,3 +220,52 @@ export function loadSessionLog(path) {
 
   return { header, headerLine, rows, events, frameInfo };
 }
+
+/**
+ * 轻量读取会话文件 header（只解第一帧，不读全文件帧）。
+ *
+ * 帧布局：帧 1 = header 行（单行 JSON，~几百字节），帧 2+ = 事件流。
+ * 短码推导（工作区 createdAt 序号）需要扫全部会话但只需要 header——
+ * 读文件前缀 64KiB 足够覆盖完整帧 1，避免全量读大文件（opena 工作区
+ * ~108MiB 压缩）。失败返回 null（调用方降级）。
+ *
+ * @param {string} path 会话日志文件路径（.jsonl.zstd 或明文 .jsonl）。
+ * @returns {object|null} header 对象；无法解析返回 null。
+ */
+export function readSessionHeader(path) {
+  let head;
+  try {
+    const fd = fs.openSync(path, 'r');
+    const buf = Buffer.alloc(64 * 1024);
+    const n = fs.readSync(fd, buf, 0, buf.length, 0);
+    fs.closeSync(fd);
+    head = buf.subarray(0, n);
+  } catch {
+    return null;
+  }
+  if (head.length < 4 || head.readUInt32LE(0) !== ZSTD_MAGIC) {
+    // 明文（无 zstd magic）：直接取首行
+    try {
+      const line = head.toString('utf8').split('\n').find((l) => l.trim().length > 0);
+      return line ? JSON.parse(line) : null;
+    } catch {
+      return null;
+    }
+  }
+  const { frames } = scanZstdFrames(head);
+  if (frames.length === 0) return null;
+  const [s, e] = frames[0];
+  let plain;
+  try {
+    plain = zstdDecompressSync(head.subarray(s, e));
+  } catch {
+    return null;
+  }
+  const line = plain.toString('utf8').split('\n').find((l) => l.trim().length > 0);
+  if (!line) return null;
+  try {
+    return JSON.parse(line);
+  } catch {
+    return null;
+  }
+}

package/lib/prewrite.js

@@ -17,7 +17,7 @@
  * 所有判定复用 `lib/checks.js`（与离线体检同一套逻辑），
  * 保证"体检看到的问题 = 写入前拦下的问题"。
  */
-import { envelopeViolations, engineViolations, finalFold, isSafeInt, nullTurnStepViolations, pluginViolations, replaySurface, stepKeyViolations, 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) {
@@ -111,6 +111,11 @@ export function createPreWriter(input = {}) {
       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

@@ -20,6 +20,7 @@ import {
   pluginViolations,
   replaySurface,
   stepKeyViolations,
+  turnEndReasonViolations,
   violation,
   tokenMeterViolations,
   tokenMeterSourceViolations,
@@ -117,10 +118,11 @@ export function validateSessionLog(log, opts = {}) {
   violations.push(...tokenMeterViolations(events));
   violations.push(...tokenMeterSourceViolations(events));
 
-  // ── T3/T4 · 渲染层（复盘 2026-09-02 1e99e1ff 白屏）：节点 key 唯一 + turn 缺失 ──
-  // 数据层"健康"≠ 客户端能渲染：check/官方加载/分页全绿仍可能白屏（节点 key 冲突）。
+  // ── 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));
@@ -211,7 +213,7 @@ export function resumeVerdict(result) {
   // 注意：不能用 result.ok（它把 T1/T2/T3/T4/I1 也计为 error）——三档判定按任务书定义，
   // T1/T2/T3/T4 只影响「可压缩」档、I1 只影响「可继续」档。
   const loadableBlockers = violations.filter(
-    (v) => v.severity === 'error' && !['I1', 'T1', 'T2', 'T3', 'T4'].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;
 
@@ -219,9 +221,9 @@ export function resumeVerdict(result) {
   const resumable = loadable && !has('I1');
 
   const compactableBlockers = resumable
-    ? (has('T1') || has('T2') || has('T3') || has('T4') ? ['T1', 'T2', 'T3', 'T4'].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') && !has('T3') && !has('T4');
+  const compactable = resumable && !has('T1') && !has('T2') && !has('T3') && !has('T4') && !has('T5');
 
   // 最差档位
   const verdict = !loadable ? 'broken' : !resumable ? 'loadable' : !compactable ? 'resumable' : 'compactable';
@@ -239,7 +241,7 @@ export function resumeVerdict(result) {
     violationsByTier: {
       structural: [...new Set(loadableBlockers)],
       inbox: has('I1') ? ['I1'] : [],
-      tokenMeter: has('T1') || has('T2') || has('T3') || has('T4') ? ['T1', 'T2', 'T3', 'T4'].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.8",
+  "version": "0.3.10",
   "packageManager": "pnpm@11.7.0",
   "type": "module",
   "main": "lib/index.js",