dsh-log-contract 0.2.1 → 0.2.2

package/bin/dsh-log-contract.mjs

@@ -164,13 +164,15 @@ function cmdFix(args) {
   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 compactIdx = args.indexOf('--compact-last');
+  const compactLast = compactIdx >= 0 && args[compactIdx + 1] ? Number(args[compactIdx + 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 });
+  const result = repairSession(file, { removeMarkers, dropFailedTurns, trimLast, compactLast, apply, backupDir });
   if (json) {
     process.stdout.write(JSON.stringify(result, null, 2) + '\n');
     process.exit(result.ok ? 0 : 1);

package/lib/checks.js

@@ -265,6 +265,53 @@ export function finalFold(events) {
   }
 }
 
+/**
+ * T1 —— token-meter 配对（复刻 @deepseek-ai/dsh-token-meter 的 _foldEvent 状态机，
+ * 2026-08-28 事故根因 3 固化）：
+ * - `step/start` 打开一个 step（记录 turn/step）；
+ * - `step/end` 必须匹配当前打开的 step/start，否则抛错；
+ * - `assistant/message` 必须匹配当前打开的 step/start（turn/step 完全一致），否则抛错；
+ * - `user/message` / `tool/result` 不检查（token meter 不配对）。
+ *
+ * 违反 = token meter 折叠抛错 → 该会话 `/compact` 与压力测量永久失败。
+ * 已知命中：retrace 的 turn/step=null 编辑/撤回 marker（空 assistant/message replace）——
+ * foldSurface 认可其合法性（M1 只约束 append 形态），但 token meter 崩溃。这是
+ * M1 规则的盲区：M1 没约束"replace 也必须过 token meter"。
+ *
+ * @param events - 行序事件流（`{event, lineNo}`）。
+ * @returns T1 违规列表。
+ */
+export function tokenMeterViolations(events) {
+  const out = [];
+  // 无任何 step/start 的日志：现代 DSH 每个 assistant 回合必有 step/start，
+  // 完全没有说明是极早期格式或简化日志——token-meter 的 step 配对兼容性未
+  // 定义，不做配对检查（避免对旧结构误报；真实事故会话都是现代结构）。
+  if (!events.some(({ event }) => event.type === 'step/start')) return out;
+  let stepStart = undefined;
+  for (const { event, lineNo } of events) {
+    const loc = { seq: event.seq, lineNo, eventType: event.type };
+    if (event.type === 'step/start') {
+      if (stepStart !== undefined) {
+        out.push(violation('T1', loc, `step/start at seq ${event.seq} arrived before turn ${stepStart.turn}/step ${stepStart.step} ended——token meter 折叠会抛错`));
+      }
+      stepStart = { turn: event.data?.turn, step: event.data?.step };
+    } else if (event.type === 'step/end') {
+      if (stepStart === undefined || stepStart.turn !== event.data?.turn || stepStart.step !== event.data?.step) {
+        out.push(violation('T1', loc, `step/end at seq ${event.seq} has no matching step/start event（turn=${String(event.data?.turn)}, step=${String(event.data?.step)}）——token meter 折叠会抛错`));
+      }
+      stepStart = undefined;
+    } else if (event.type === 'assistant/message') {
+      const turn = event.data?.turn;
+      const step = event.data?.step;
+      if (stepStart === undefined || stepStart.turn !== turn || stepStart.step !== step) {
+        const open = stepStart === undefined ? '无打开的 step' : `打开的 step 为 turn ${stepStart.turn}/step ${stepStart.step}`;
+        out.push(violation('T1', loc, `assistant/message at seq ${event.seq} has no matching step/start event（turn=${String(turn)}, step=${String(step)}；${open}）——token meter 折叠会抛错，/compact 与压力测量永久失败（retrace 的 turn-null 编辑/撤回 marker 即命中此条）`));
+      }
+    }
+  }
+  return out;
+}
+
 /** 从事件推导 wire 消息（与 dsh-session deriveEventMessage 同语义）。 */
 export function deriveWireMessage(event) {
   if (event.type === 'user/message') {

package/lib/contracts.js

@@ -197,6 +197,14 @@ export const CONTRACT_RULES = [
     description: '终验：把全部事件按序喂给官方 foldSurface，不抛 = 持久化层通过。S1–S7 任何一条违反都会在此暴露。',
   },
 
+  {
+    id: 'T1',
+    title: 'token-meter 配对：assistant/message 与 step/end 必须匹配当前打开的 step/start',
+    layer: LAYER.ENGINE,
+    severity: SEVERITY.ERROR,
+    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 形态的盲区），压缩前需清理。',
+  },
   // ── M · 客户端引擎层 ────────────────────────────────────────────────────
   {
     id: 'M1',

package/lib/index.js

@@ -7,5 +7,6 @@
 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 { repairSession, strictScanText, removeMarkersText, dropFailedTurnsText, trimLastMessagesText, compactLastMessagesText, rebuildZstdText } from './repair.js';
 export { CONTRACT_RULES, LAYER, SEVERITY, ruleById } from './contracts.js';
+export { tokenMeterViolations } from './checks.js';

package/lib/prewrite.js

@@ -17,7 +17,12 @@
  * 所有判定复用 `lib/checks.js`（与离线体检同一套逻辑），
  * 保证"体检看到的问题 = 写入前拦下的问题"。
  */
-import { envelopeViolations, engineViolations, finalFold, isSafeInt, pluginViolations, replaySurface, violation } from './checks.js';
+import { envelopeViolations, engineViolations, finalFold, isSafeInt, pluginViolations, replaySurface, tokenMeterViolations, violation } from './checks.js';
+
+/** retrace 类 marker：data.editor 存在（assistant/message replace，turn/step=null）。 */
+function isKnownMarkerCandidate(event) {
+  return Boolean(event) && event.type === 'assistant/message' && event.surfaceOp && event.surfaceOp !== 'append' && event.data?.editor !== undefined;
+}
 
 /** 把一个"拟写事件"规整为带 seq 的事件；seq 未携带时按追加位置赋值。 */
 function normalizeCandidate(candidate, nextSeq) {
@@ -78,6 +83,21 @@ export function createPreWriter(input = {}) {
     if (folded.error) {
       violations.push(violation('S8', { lineNo: null }, `官方 foldSurface 重放失败：${folded.error.message} —— 会话加载会被拒（SessionPersistenceCorruptionError）`));
     }
+    // T1 —— token-meter 配对（事故根因 3 固化）。写前校验只判定**拟写事件自身**
+    // 的 step 配对：retrace 的 turn-null 编辑/撤回 marker 必然命中（空
+    // assistant/message replace 无 step 可配对），但编辑功能必须可用——白名单
+    // 降级为 warning（已知设计债，压缩前需 doctor 清理）；非 marker 的
+    // assistant/message 配对失败保持 error。历史已有事件的 T1 归属离线体检
+    // （check），不在这里重复拦截（否则历史 marker 会让后续编辑全部被拒）。
+    const lastCandidate = candidateEvents[candidateEvents.length - 1];
+    for (const t1 of tokenMeterViolations(candidateEvents.map((event) => ({ event })))) {
+      if (t1.id !== 'T1' || t1.seq !== lastCandidate?.seq) continue;
+      if (isKnownMarkerCandidate(lastCandidate)) {
+        violations.push({ ...t1, severity: 'warning', message: `${t1.message}（已知 retrace marker 设计债：压缩前需 doctor 清理）` });
+      } else {
+        violations.push(t1);
+      }
+    }
     const bySeverity = { error: 0, warning: 0, info: 0 };
     for (const v of violations) bySeverity[v.severity] = (bySeverity[v.severity] ?? 0) + 1;
     return {

package/lib/repair.js

@@ -31,7 +31,7 @@ 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';
+import { CHUNK_ROW_TYPES, MARKER_PREFIXES, SURFACE_TYPES } from './checks.js';
 
 /** 复刻 dsh-session expandRow：chunk 行展开为完整事件（含 data/turn/step）。 */
 function expandChunkRow(row) {
@@ -370,6 +370,165 @@ export function trimLastMessagesText(text, keepMessages) {
   return { ...r, kept: keepMessages, cutoff };
 }
 
+/** 从被遮蔽的 user/assistant 消息做提取式摘要（跨范围均匀采样，不依赖模型）。 */
+function extractiveSummary(msgEvents) {
+  const lines = [];
+  const step = Math.max(1, Math.ceil(msgEvents.length / 18));
+  const sampled = [];
+  for (let i = 0; i < msgEvents.length; i += step) sampled.push(msgEvents[i]);
+  const last = msgEvents[msgEvents.length - 1];
+  if (sampled[sampled.length - 1] !== last) sampled.push(last);
+  for (const ev of sampled) {
+    let text = '';
+    if (ev.type === 'user/message') {
+      text = (ev.data?.content ?? []).filter((b) => b.type === 'text').map((b) => b.text).join(' ');
+    } else if (ev.type === 'assistant/message') {
+      text = (ev.data?.message?.content ?? []).filter((b) => b.type === 'text').map((b) => b.text).join(' ');
+    }
+    text = text.replace(/\s+/g, ' ').trim();
+    if (!text) continue;
+    const chunk = text.length > 120 ? `${text.slice(0, 120)}…` : text;
+    lines.push(`${ev.type === 'user/message' ? '问' : '答'} ${chunk}`);
+    if (lines.join('\n').length > 1800) break;
+  }
+  if (lines.length === 0) return '（早期对话无文本内容）';
+  return `【早期对话提取式摘要 · 完整原文保留在会话日志与备份中】\n${lines.join('\n')}`;
+}
+
+/**
+ * DSH 官方压缩（compaction）：不删除任何事件——在日志尾部追加
+ * compaction/start → compaction/summary → checkpoint(user/message, replace
+ * [start..end]) → compaction/end，把 [start..end] 从模型表面遮蔽，替换为
+ * 提取式摘要。旧事件全部保留（append-only 审计），日志一行不删。
+ * @param {string} text - JSONL 全文（严格连续）。
+ * @param {number} keepMessages - 保留的最近 append 消息数。
+ * @returns {{ text: string, compacted: boolean, kept: number, shadowed: number, summary: string }}
+ */
+export function compactLastMessagesText(text, keepMessages) {
+  const parts = text.split('\n');
+  const bySeq = new Map();
+  const surfaceNodes = [];
+  for (let i = 1; i < parts.length; i++) {
+    const raw = parts[i].trim();
+    if (!raw) continue;
+    const decoded = decodeLine(raw);
+    if (decoded === null) continue;
+    for (const ev of decoded) {
+      bySeq.set(ev.seq, ev);
+      if (SURFACE_TYPES.has(ev.type)) {
+        const op = ev.surfaceOp;
+        if (op === 'append') surfaceNodes.push(ev.seq);
+        else if (op && op.op === 'replace') {
+          const s = surfaceNodes.indexOf(op.start);
+          const e = surfaceNodes.indexOf(op.end);
+          if (s !== -1 && e !== -1 && s <= e) surfaceNodes.splice(s, e - s + 1);
+          surfaceNodes.push(ev.seq);
+        }
+      }
+    }
+  }
+  const appendMsgs = surfaceNodes.filter((seq) => {
+    const ev = bySeq.get(seq);
+    return ev && (ev.type === 'user/message' || (ev.type === 'assistant/message' && ev.surfaceOp === 'append'));
+  });
+  const total = appendMsgs.length;
+  if (total <= keepMessages) return { text, compacted: false, kept: total, shadowed: 0, summary: '' };
+  const target = appendMsgs[total - keepMessages];
+  let boundary = target;
+  for (const seq of appendMsgs) {
+    const ev = bySeq.get(seq);
+    if (ev.type === 'user/message' && seq <= target) boundary = seq;
+  }
+  const shadowedSeqs = surfaceNodes.filter((seq) => seq < boundary);
+  const start = shadowedSeqs[0];
+  const end = shadowedSeqs[shadowedSeqs.length - 1];
+  const summary = extractiveSummary(shadowedSeqs.map((seq) => bySeq.get(seq)).filter(Boolean));
+  // 压缩事件插入到"第一个保留事件"之前（seq = boundary..boundary+3），
+  // 之后的事件整体 +4 重编号——保证表面顺序为 [checkpoint, 近期轮次…]。
+  const boundarySeq = boundary;
+  const compactionId = `dsh-fix-${Date.now().toString(36)}${Math.floor(Math.random() * 1e6).toString(36)}`;
+  const startSeq = boundarySeq;
+  const summarySeq = boundarySeq + 1;
+  const checkpointSeq = boundarySeq + 2;
+  const endSeq = boundarySeq + 3;
+  const now = Date.now();
+  const appended = [
+    { type: 'compaction/start', seq: startSeq, time: now, data: { compactionId, turn: null } },
+    {
+      type: 'compaction/summary',
+      seq: summarySeq,
+      time: now,
+      data: {
+        compactionId,
+        summary,
+        shadowedRange: { start, end },
+        shadowedSeqs,
+        shadowedTokenCount: Math.round(summary.length / 4),
+        provider: 'dsh-log-contract',
+        model: 'extractive',
+      },
+    },
+    {
+      type: 'user/message',
+      seq: checkpointSeq,
+      time: now,
+      surfaceOp: { op: 'replace', start, end },
+      sourceEventSeqs: [startSeq, summarySeq, ...shadowedSeqs],
+      data: {
+        id: `checkpoint-${compactionId}`,
+        role: 'user',
+        source: { kind: 'user' },
+        content: [{ type: 'text', text: summary }],
+      },
+    },
+    { type: 'compaction/end', seq: endSeq, time: now, data: { compactionId, turn: null } },
+  ];
+  // 找到第一个事件 seq >= boundary 的行（保留区起点），在其前插入压缩事件
+  let insertIdx = parts.length - 1;
+  for (let i = 1; i < parts.length; i++) {
+    const raw = parts[i].trim();
+    if (!raw) continue;
+    const decoded = decodeLine(raw);
+    if (decoded === null || decoded.length === 0) continue;
+    if (decoded[0].seq >= boundarySeq) {
+      insertIdx = i;
+      break;
+    }
+  }
+  const shiftFields = (v) => {
+    if (typeof v.seq === 'number') v.seq += 4;
+    if (CHUNK_ROW_TYPES.has(v.type) && typeof v.seq0 === 'number') v.seq0 += 4;
+    if (Array.isArray(v.sourceEventSeqs)) v.sourceEventSeqs = v.sourceEventSeqs.map((x) => x + 4);
+    if (v.surfaceOp && v.surfaceOp.op === 'replace') {
+      v.surfaceOp.start += 4;
+      v.surfaceOp.end += 4;
+    }
+    return v;
+  };
+  const out = [];
+  for (let i = 0; i < parts.length; i++) {
+    if (i === insertIdx) for (const e of appended) out.push(JSON.stringify(e));
+    const raw = parts[i];
+    if (i > 0 && i >= insertIdx && raw.trim()) {
+      let v;
+      try {
+        v = JSON.parse(raw);
+      } catch {
+        out.push(raw);
+        continue;
+      }
+      if (typeof v.seq === 'number') {
+        out.push(JSON.stringify(shiftFields(v)));
+        continue;
+      }
+    }
+    out.push(raw);
+  }
+  const newText = out.join('\n');
+  if (!newText.endsWith('\n')) return { text: newText + '\n', compacted: true, kept: keepMessages, shadowed: shadowedSeqs.length, summary };
+  return { text: newText, compacted: true, kept: keepMessages, shadowed: shadowedSeqs.length, summary };
+}
+
 /**
  * 按官方 writer 帧格式重建 .jsonl.zstd（帧1=header，帧2=其余，均带 checksum）。
  * @param {string} text - JSONL 全文（以 "\n" 结尾）。
@@ -395,7 +554,7 @@ export function rebuildZstdText(text) {
  * 对单个会话日志执行诊断 +（可选）修复。
  * @param {string} file - .jsonl 或 .jsonl.zstd 路径。
  * @param {{
- *   removeMarkers?: boolean, dropFailedTurns?: boolean, trimLast?: number,
+ *   removeMarkers?: boolean, dropFailedTurns?: boolean, trimLast?: number, compactLast?: number,
  *   apply?: boolean, backupDir?: string
  * }} opts
  * @returns {{
@@ -455,6 +614,13 @@ export function repairSession(file, opts = {}) {
     const r = trimLastMessagesText(plain, opts.trimLast);
     applyFix('trim', r, `裁剪到最近 ${r.kept} 条消息（丢弃 ${r.removed} 行，重编号 ${r.renumbered} 行）`);
   }
+  if (typeof opts.compactLast === 'number') {
+    const r = compactLastMessagesText(plain, opts.compactLast);
+    if (r.compacted) {
+      issues.push({ kind: 'compact', detail: `官方压缩：遮蔽 ${r.shadowed} 个 surface 节点，保留最近 ${r.kept} 条消息；旧事件全部保留（日志零删除）` });
+      plain = r.text;
+    }
+  }
   // 全部修复完成后做一次终检（中间态的临时违规不阻塞——后续修复可能已消除）
   const scanFinal = strictScanText(plain);
   const checkFinal = validateSessionLog(loadSessionLogFromText(plain));

package/lib/validate.js

@@ -17,6 +17,7 @@ import {
   pluginViolations,
   replaySurface,
   violation,
+  tokenMeterViolations,
   wireViolations,
 } from './checks.js';
 
@@ -101,6 +102,9 @@ export function validateSessionLog(log, opts = {}) {
   violations.push(...replay.violations);
 
   const folded = finalFold(events.map((e) => e.event));
+
+  // ── T · token meter 配对（事故根因 3）──
+  violations.push(...tokenMeterViolations(events));
   if (folded.error) {
     violations.push(violation('S8', { lineNo: null }, `官方 foldSurface 重放失败：${folded.error.message} —— 会话加载会被拒（SessionPersistenceCorruptionError）`));
   }

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