dsh-log-contract 0.3.4 → 0.3.5

package/README.md

@@ -38,6 +38,13 @@ pnpm add -D dsh-log-contract   # 或 npm install
 pnpm dlx dsh-log-contract --help
 ```
 
+> **你是 dsh-retrace 用户？** 无需单独安装——`dsh-retrace` 已把 `dsh-log-contract`
+> 声明为依赖，装 retrace 时自动带好契约守护（体检/写前校验/修复原语全部随插件生效）。
+> 本包独立发布，供愿意单独使用或二次开发的用户直接引入。
+>
+> **从 GitHub 下载了 ZIP？** 解压后 `cd dsh-log-contract && npm install && npm run build`，
+> 然后 `node bin/dsh-log-contract.mjs check <session-log>` 即可使用（无需全局安装）。
+
 依赖：Node ≥ 22（`node:zlib` 内置 zstd）、`@deepseek-ai/dsh-session`（peer，校验/解码复用官方实现，保证与 Harness 读路径同源）。
 
 ---

package/lib/checks.js

@@ -122,6 +122,37 @@ export function isReplaceOp(op) {
   );
 }
 
+/**
+ * S9 —— 文件物理序 seq 单调（2026-08-30 事故固化；交接书 L2）。
+ *
+ * 按**文件物理行序**（非 seq 排序）要求展开后的事件 seq 严格单调递增。
+ * 单进程 append 不可能写出非单调物理序（appendCore 断言 seq==cursor+i 且按
+ * id 串行化）——非单调 = 多写入者/旧光标回放交织的现场特征（526f1835 物理序
+ * 734056→733539→735470）。E2 只查「排序后连续」，排序会掩盖物理序倒退；
+ * S9 补「物理序单调」盲区。
+ *
+ * @param rows - loadSessionLog 的 rows（物理行序，每行含 decoded 数组）。
+ * @returns S9 违规列表（error 级）。
+ */
+export function physicalOrderViolations(rows) {
+  const out = [];
+  let prevSeq = -1;
+  let prevLineNo = null;
+  for (const row of rows) {
+    if (!Array.isArray(row.decoded) || row.decoded.length === 0) continue;
+    for (const event of row.decoded) {
+      if (typeof event.seq !== 'number' || !Number.isSafeInteger(event.seq) || event.seq < 0) continue; // E1 处理
+      if (event.seq < prevSeq) {
+        out.push(violation('S9', { seq: event.seq, lineNo: row.lineNo, eventType: event.type }, `文件物理序 seq 倒退：${prevSeq}（line ${prevLineNo}）→ ${event.seq}（line ${row.lineNo}）——非单调 = 多写入者/旧光标回放交织（单进程 append 不可能写出），会话加载会被拒`));
+        return out; // 首个倒退即现场特征，报一次足够（后续乱序都源自此）
+      }
+      prevSeq = event.seq;
+      prevLineNo = row.lineNo;
+    }
+  }
+  return out;
+}
+
 /**
  * 与官方同语义的 surface 增量重放，逐事件归因 S1–S7。
  * @param {Array<{event:object, lineNo?:number}>} events 按日志顺序的事件（带 loc 包装）
@@ -395,6 +426,110 @@ export function tokenMeterViolations(events) {
   return out;
 }
 
+/**
+ * T2 —— token-meter 的 sourceEventSeqs 引用必须同 turn/step（2026-08-30 第二类
+ * 刷屏事故固化）。
+ *
+ * 镜像官方 `_estimateProviderAssistant`（dsh-token-meter lib/index.js:634-650）：
+ * `assistant/message` 的每个 `sourceEventSeqs` 若指向 `assistant/chunk`，其
+ * turn/step 必须与消息自身一致；跨 step 引用 → 官方抛
+ * `token meter: assistant/message at seq N source seq M belongs to another step`
+ * （lib/index.js:645）。
+ *
+ * 事故现场：DSH resend/regenerate 在 agent 仍开着 step 时被触发，会把旧 step 的
+ * chunk 全部引用进新 assistant/message（526f1835 seq 936047 跨 step 7/8/9）→
+ * 离线 check（T1）全绿但实机 token-meter 崩溃 → 同样刷屏压垮 host。
+ *
+ * @param events - 行序事件流（`{event, lineNo}`）。
+ * @returns T2 违规列表（error 级，token-meter 实机必崩）。
+ */
+export function tokenMeterSourceViolations(events) {
+  const out = [];
+  const bySeq = new Map();
+  for (const { event, lineNo } of events) bySeq.set(event.seq, { event, lineNo });
+  for (const { event, lineNo } of events) {
+    if (event.type !== 'assistant/message' || !Array.isArray(event.sourceEventSeqs) || event.sourceEventSeqs.length === 0) continue;
+    const turn = event.data?.turn;
+    const step = event.data?.step;
+    if (turn == null || step == null) continue; // turn-null marker 由 T1 覆盖
+    const seen = new Set();
+    for (const s of event.sourceEventSeqs) {
+      if (s >= event.seq) {
+        out.push(violation('T2', { seq: event.seq, lineNo, eventType: event.type }, `assistant/message at seq ${event.seq} source seq ${s} is not earlier——token meter 折叠会抛错（_estimateProviderAssistant）`));
+        break;
+      }
+      if (seen.has(s)) {
+        out.push(violation('T2', { seq: event.seq, lineNo, eventType: event.type }, `assistant/message at seq ${event.seq} repeats source seq ${s}——token meter 折叠会抛错`));
+        break;
+      }
+      seen.add(s);
+      const src = bySeq.get(s);
+      if (!src || src.event.type !== 'assistant/chunk') continue; // 非 chunk 引用官方跳过
+      if (src.event.data?.turn !== turn || src.event.data?.step !== step) {
+        out.push(violation('T2', { seq: event.seq, lineNo, eventType: event.type }, `assistant/message at seq ${event.seq} source seq ${s} belongs to another step（消息 turn ${turn}/step ${step}，源 turn ${String(src.event.data?.turn)}/step ${String(src.event.data?.step)}）——token meter 折叠会抛错，/compact 与压力测量永久失败（DSH resend 在 step 未关时跨 step 引用）`));
+        break; // 官方抛一次即停（consumedEvents 不前进），只报首条
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * I1 —— inbox seed 相对重放（交接书 L1；镜像 dsh-agent lib/types/inbox.js）。
+ *
+ * 复刻官方 Inbox：从 `header.seedLength` 起重放 `agent/inbox/spliced`，
+ * next-turn/next-step 双队列；每条 splice 校验
+ * `start + removedCount <= 队列长` 且不产生重复 message id。违反 =
+ * `resume failed: invalid persisted inbox splice at seq N`（fork 边界孤儿：
+ * fork 时"移除父待处理提示词"的 removedCount=1 在子会话 seed 相对空 inbox 上非法）。
+ *
+ * @param events - 行序事件流（`{event, lineNo}`）。
+ * @param header - 日志 header（取 seedLength）。
+ * @returns I1 违规列表（error 级，resume 会被拒）。
+ */
+export function inboxReplayViolations(events, header) {
+  const out = [];
+  const seedLength = header?.seedLength;
+  if (typeof seedLength !== 'number' || !Number.isSafeInteger(seedLength) || seedLength < 0) {
+    // 无 seedLength（非 fork 会话）→ Inbox 从 0 重放，语义等同全量；仍做队列校验
+  }
+  const state = { 'next-turn': [], 'next-step': [] };
+  const startSeq = seedLength ?? 0;
+  for (const { event, lineNo } of events) {
+    if (event.seq < startSeq) continue;
+    if (event.type !== 'agent/inbox/spliced') continue;
+    const loc = { seq: event.seq, lineNo, eventType: event.type };
+    const splice = event.data;
+    if (!splice || typeof splice.target !== 'string' || !['next-turn', 'next-step'].includes(splice.target)) {
+      out.push(violation('I1', loc, `spliced 缺合法 target（next-turn/next-step）：${JSON.stringify(splice)?.slice(0, 80)}`));
+      continue;
+    }
+    const inbox = state[splice.target];
+    const removedCount = splice.removedCount ?? 0;
+    if (!Number.isSafeInteger(splice.start) || splice.start < 0 || splice.start > inbox.length
+      || !Number.isSafeInteger(removedCount) || removedCount < 0
+      || splice.start + removedCount > inbox.length) {
+      out.push(violation('I1', loc, `invalid inbox splice @seq ${event.seq}：target=${splice.target} start=${splice.start} removedCount=${removedCount} 但队列长 ${inbox.length}（seedLength=${seedLength}）——resume 会被拒（fork 边界孤儿 spliced 即此形态，removedCount 指向 seed 相对空 inbox）`));
+      continue;
+    }
+    const inserted = Array.isArray(splice.inserted) ? splice.inserted : [];
+    const candidate = inbox.slice(0, splice.start).concat(inserted, inbox.slice(splice.start + removedCount));
+    const ids = new Set();
+    const other = splice.target === 'next-turn' ? state['next-step'] : state['next-turn'];
+    for (const message of [...candidate, ...other]) {
+      const id = message?.id ?? message?.message?.id;
+      if (id === undefined) continue;
+      if (ids.has(id)) {
+        out.push(violation('I1', loc, `message "${id}" 已在待处理队列中（target=${splice.target}）——resume 会被拒（重复 pending id）`));
+        break;
+      }
+      ids.add(id);
+    }
+    inbox.splice(splice.start, removedCount, ...inserted);
+  }
+  return out;
+}
+
 /** 从事件推导 wire 消息（与 dsh-session deriveEventMessage 同语义）。 */
 export function deriveWireMessage(event) {
   if (event.type === 'user/message') {

package/lib/contracts.js

@@ -98,6 +98,22 @@ export const CONTRACT_RULES = [
     source: '@deepseek-ai/dsh-session lib/index.js:398 (planSurfaceEvent "not contiguous")；审计 S2/N6',
     description: 'seq 必须从 0（或窗口 baseSeq）严格连续递增。缺口/倒退 = 违反单写入者假设（多实例共享存储并发写的痕迹），加载时直接 throw。',
   },
+  {
+    id: 'S9',
+    title: '文件物理序 seq 单调（多写入者交织现场特征）',
+    layer: LAYER.PERSISTENCE,
+    severity: SEVERITY.ERROR,
+    source: '2026-08-28 实锤：526f1835 文件物理序 734056→733539→735470；单进程 appendCore 断言 seq==cursor+i 且按 id 串行化不可能写出',
+    description: '按文件物理行序要求展开后事件 seq 严格单调递增。E2 在排序后检查（loadSessionLog 会 sort），物理序倒退被掩盖；S9 在排序前按行序检查，非单调 = 多写入者/旧光标回放交织的直接现场证据，加载会被拒。',
+  },
+  {
+    id: 'I1',
+    title: 'inbox seed 相对重放（fork 边界孤儿 spliced）',
+    layer: LAYER.ENGINE,
+    severity: SEVERITY.ERROR,
+    source: '@deepseek-ai/dsh-agent lib/types/inbox.js:155-178 (apply/validate)；2026-08-28 实锤：62c5b531/73ed35d8 fork 边界 removedCount=1 孤儿',
+    description: '从 header.seedLength 起重放 agent/inbox/spliced，next-turn/next-step 双队列；start+removedCount 不得超过队列长、不得产生重复 pending id。fork 时"移除父待处理提示词"的 splice 假设父会话 inbox，子会话 seed 相对空 inbox 上非法 → resume 被拒（invalid persisted inbox splice）。',
+  },
   {
     id: 'E3',
     title: 'type 必须在已知词汇表内（或带 ignorable 标记）',
@@ -205,6 +221,14 @@ export const CONTRACT_RULES = [
     source: '@deepseek-ai/dsh-token-meter lib/index.js:566-625 (_foldEvent)',
     description: 'token meter 折叠要求 assistant/message 与 step/end 与打开的 step/start（turn/step 完全一致）匹配；违反即 /compact 与压力测量永久失败。retrace 的 turn-null 编辑/撤回 marker（空 assistant/message replace）命中此条——foldSurface 认可其合法性但 token meter 崩溃（M1 只约束 append 形态的盲区），压缩前需清理。',
   },
+  {
+    id: 'T2',
+    title: 'token-meter 源引用：assistant/message 的 sourceEventSeqs 引用的 chunk 必须同 turn/step',
+    layer: LAYER.ENGINE,
+    severity: SEVERITY.ERROR,
+    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: 'P3',
     title: 'tool/call ↔ tool/result 配对完整性（考古 B1）',

package/lib/index.js

@@ -9,5 +9,5 @@ export { validateSessionLog } from './validate.js';
 export { createPreWriter, preWriterFromLog } from './prewrite.js';
 export { repairSession, strictScanText, removeMarkersText, neutralizeMarkersText, clipCrossStepSourcesText, dropFailedTurnsText, trimLastMessagesText, compactLastMessagesText, rebuildZstdText } from './repair.js';
 export { CONTRACT_RULES, LAYER, SEVERITY, ruleById } from './contracts.js';
-export { tokenMeterViolations } from './checks.js';
+export { tokenMeterViolations, tokenMeterSourceViolations, physicalOrderViolations, inboxReplayViolations } from './checks.js';
 export { auditToolCalls, extractText, extractToolOutputs, indexToolCalls, toolCommandOf } from './archaeology.js';

package/lib/validate.js

@@ -13,11 +13,14 @@ import {
   envelopeViolations,
   engineViolations,
   finalFold,
+  inboxReplayViolations,
   isSafeInt,
+  physicalOrderViolations,
   pluginViolations,
   replaySurface,
   violation,
   tokenMeterViolations,
+  tokenMeterSourceViolations,
   toolPairingViolations,
   toolResultStructureViolations,
   wireViolations,
@@ -99,14 +102,21 @@ export function validateSessionLog(log, opts = {}) {
     }
   }
 
+  // ── S9 · 文件物理序 seq 单调（多写入者交织现场；E2 排序后检查看不到）──
+  violations.push(...physicalOrderViolations(rows));
+
   // ── S · surface 增量重放（归因）+ 官方 foldSurface 终验 ────────────────
   const replay = replaySurface(events);
   violations.push(...replay.violations);
 
   const folded = finalFold(events.map((e) => e.event));
 
-  // ── T · token meter 配对（事故根因 3）──
+  // ── T · token meter 配对（事故根因 3 + 2026-08-30 两类刷屏）──
   violations.push(...tokenMeterViolations(events));
+  violations.push(...tokenMeterSourceViolations(events));
+
+  // ── I1 · inbox seed 相对重放（fork 边界孤儿；交接书 L1）──────────────
+  violations.push(...inboxReplayViolations(events, header));
 
   // ── P3/P4 · 考古契约（工具配对 + 输出结构）──
   violations.push(...toolPairingViolations(events));

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.4",
+  "version": "0.3.5",
   "type": "module",
   "main": "lib/index.js",
   "bin": {