dsh-log-contract 0.1.0

package/lib/log-reader.js

@@ -0,0 +1,179 @@
+/**
+ * dsh-log-contract · lib/log-reader.js
+ *
+ * 会话日志读取层：zstd 帧扫描 → 解压 → 逐行 JSON.parse → 官方
+ * `decodeStorageRecord` 展开（chunk 行展开 / 损坏行报错）。
+ *
+ * 契约来源：
+ * - 帧扫描/撕裂尾帧判定：复用本项目审计方法论（scan-seq-gaps.mjs），
+ *   帧头布局对齐 zstd 规范（magic 0xFD2FB528、descriptor、block 头）。
+ * - 行解码：`@deepseek-ai/dsh-session` 的 `decodeStorageRecord`
+ *   （lib/index.js:1029，validateRow :922 / expandRow :973）。
+ * - 损坏语义：R2 —— chunk 行损坏 = 整段 run 丢失且加载失败（dsh-session
+ *   lib/index.js:1022-1024 注释明示 fail-loud，无跳过逃生舱）。
+ */
+import fs from 'node:fs';
+import { zstdDecompressSync } from 'node:zlib';
+import { decodeStorageRecord } from '@deepseek-ai/dsh-session';
+
+const ZSTD_MAGIC = 0xfd2fb528;
+
+/** 扫描 zstd 帧边界；返回 [start, end] 列表与是否出现撕裂尾帧。 */
+export function scanZstdFrames(buf) {
+  const frames = [];
+  let offset = 0;
+  let torn = false;
+  while (offset < buf.length) {
+    const start = offset;
+    if (buf.length - offset < 4 || buf.readUInt32LE(offset) !== ZSTD_MAGIC) {
+      torn = true;
+      break;
+    }
+    offset += 4;
+    if (offset === buf.length) {
+      torn = true;
+      break;
+    }
+    const descriptor = buf.readUInt8(offset);
+    offset += 1;
+    if ((descriptor & 24) !== 0) {
+      // 保留位被置位：非法帧头
+      return { frames, torn: true, reason: 'reserved-bit' };
+    }
+    const contentSizeFlag = descriptor >>> 6;
+    const singleSegment = (descriptor & 32) !== 0;
+    const checksum = (descriptor & 4) !== 0;
+    const dictFlag = descriptor & 3;
+    const dictBytes = dictFlag === 3 ? 4 : dictFlag;
+    const contentSizeBytes = contentSizeFlag === 0 ? (singleSegment ? 1 : 0) : (1 << contentSizeFlag);
+    const hdrExtra = (singleSegment ? 0 : 1) + dictBytes + contentSizeBytes;
+    if (buf.length - offset < hdrExtra) {
+      torn = true;
+      break;
+    }
+    offset += hdrExtra;
+    let lastBlock = false;
+    while (!lastBlock) {
+      if (buf.length - offset < 3) {
+        torn = true;
+        break;
+      }
+      const bh = buf.readUInt32LE(offset);
+      offset += 3;
+      lastBlock = (bh & 1) !== 0;
+      offset += (bh >>> 3) & 0x1fffff;
+    }
+    if (torn) break;
+    if (offset > buf.length) {
+      // 块内容越过文件末尾：最后一帧被截断，不能算完整帧
+      torn = true;
+      break;
+    }
+    if (checksum) offset += 4;
+    frames.push([start, offset]);
+  }
+  return { frames, torn, reason: torn ? 'incomplete-tail' : undefined };
+}
+
+/** 把 zstd 多帧拼成完整明文；任一帧解码失败即抛错（N5 单帧全损语义）。 */
+export function decompressZstd(buf) {
+  const { frames, torn } = scanZstdFrames(buf);
+  if (torn) throw new Error('zstd 尾帧撕裂（incomplete tail frame）——日志可能正在写入或已截断');
+  // 逐帧解码后一次性 Buffer.concat：避免每帧一次 concat 的 O(n²) 拷贝
+  const parts = new Array(frames.length);
+  for (let i = 0; i < frames.length; i++) {
+    const [s, e] = frames[i];
+    try {
+      parts[i] = zstdDecompressSync(buf.subarray(s, e));
+    } catch (err) {
+      throw new Error(`zstd 帧解码失败 [${s},${e})：${err.message}`);
+    }
+  }
+  return Buffer.concat(parts);
+}
+
+/**
+ * 读取并解码一个会话日志文件（.jsonl / .jsonl.zstd / 任意带 zstd 魔数的文件）。
+ *
+ * @param {string} path 日志文件路径
+ * @returns {{
+ *   header: object|null, headerLine: number|null,
+ *   rows: Array<{lineNo:number, value:unknown, decoded:Array|null, error:Error|null}>,
+ *   events: Array<{seq:number, event:object, lineNo:number}>,
+ *   frameInfo: {frames:number, torn:boolean, compressedBytes:number, plaintextBytes:number},
+ * }}
+ */
+export function loadSessionLog(path) {
+  const buf = fs.readFileSync(path);
+  const isZstd = buf.length >= 4 && buf.readUInt32LE(0) === ZSTD_MAGIC;
+
+  let plain;
+  let frameInfo;
+  let loadError = null;
+  if (isZstd) {
+    try {
+      plain = decompressZstd(buf);
+    } catch (err) {
+      loadError = err;
+      plain = Buffer.alloc(0);
+    }
+    const { frames, torn } = scanZstdFrames(buf);
+    frameInfo = { frames: frames.length, torn, compressedBytes: buf.length, plaintextBytes: plain.length };
+  } else {
+    plain = buf;
+    frameInfo = { frames: 0, torn: false, compressedBytes: 0, plaintextBytes: plain.length };
+  }
+  if (loadError) {
+    return {
+      header: null,
+      headerLine: 0,
+      rows: [],
+      events: [],
+      frameInfo: { ...frameInfo, error: loadError.message },
+    };
+  }
+
+  const text = plain.toString('utf8');
+  const lines = text.split('\n');
+
+  // 第一行 = header
+  const headerLine = 0;
+  let header = null;
+  const headerRaw = lines[0];
+  try {
+    header = JSON.parse(headerRaw);
+  } catch {
+    header = null;
+  }
+
+  const rows = [];
+  const events = [];
+  for (let i = 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.trim().length === 0) continue; // 帧边界产物（空行）跳过
+    const lineNo = i;
+    let value;
+    try {
+      value = JSON.parse(line);
+    } catch (err) {
+      rows.push({ lineNo, value: null, decoded: null, error: err });
+      continue;
+    }
+    let decoded;
+    try {
+      decoded = decodeStorageRecord(value);
+    } catch (err) {
+      rows.push({ lineNo, value, decoded: null, error: err });
+      continue;
+    }
+    for (const event of decoded) {
+      events.push({ seq: event.seq, event, lineNo });
+    }
+    rows.push({ lineNo, value, decoded, error: null });
+  }
+
+  // 按 seq 排序（文件顺序即日志顺序，此处防御性排序以便下游契约检查）
+  events.sort((a, b) => a.seq - b.seq);
+
+  return { header, headerLine, rows, events, frameInfo };
+}

package/lib/prewrite.js

@@ -0,0 +1,155 @@
+/**
+ * dsh-log-contract · lib/prewrite.js
+ *
+ * ★ 写前校验（pre-write validation）——本工具的第一公民。
+ *
+ * 复盘事故（2026-08-25）第 1 轮失败就是"违约写入没被拦"：surface-replace
+ * 的 `sourceEventSeqs` 被清空后写入，会话加载直接抛
+ * `SessionPersistenceCorruptionError`。如果写入前先校验，会话根本不会被改坏。
+ *
+ * 本模块把"三层契约"（持久化 / 客户端引擎 / 插件语义）固化为可执行检查：
+ * - `createPreWriter({ events }).validateAppend(candidate)` —— 追加写入前校验：
+ *   拟写事件在进入日志之前，先与当前日志的折叠状态比对（官方 append 的
+ *   SurfaceManager.validateNext 同思路：validate first, commit later）。
+ * - `createPreWriter({ events }).validateEdit(editedEvents)` —— 帧级手术校验：
+ *   修改后的完整事件列表端到端重放（安全修复协议第 2 步"改后确认"）。
+ *
+ * 所有判定复用 `lib/checks.js`（与离线体检同一套逻辑），
+ * 保证"体检看到的问题 = 写入前拦下的问题"。
+ */
+import { envelopeViolations, engineViolations, finalFold, isSafeInt, pluginViolations, replaySurface, violation } from './checks.js';
+
+/** 把一个"拟写事件"规整为带 seq 的事件；seq 未携带时按追加位置赋值。 */
+function normalizeCandidate(candidate, nextSeq) {
+  return candidate.seq === undefined ? { ...candidate, seq: nextSeq } : candidate;
+}
+
+/**
+ * 基于当前日志事件列表建立写前校验器。
+ *
+ * @param {{ events: Array<object>, baseSeq?: number }} input 当前日志的已解码事件
+ *   （按日志顺序；无 seq 字段的事件按位置补 seq，用于窗口校验）。
+ * @returns {{
+ *   events: Array, nextSeq: number,
+ *   validateAppend(candidate, opts?): { ok, violations, stateAfter },
+ *   validateEdit(editedEvents, opts?): { ok, violations, stateAfter },
+ * }}
+ */
+export function createPreWriter(input = {}) {
+  const { baseSeq = 0 } = input;
+  let events = [...input.events];
+  // 窗口校验支持"无 seq 的原始事件列表"：按位置补齐 seq 与 time。
+  let nextSeq = baseSeq;
+  events = events.map((e) => {
+    const normalized = e.seq === undefined ? { ...e, seq: nextSeq } : e;
+    nextSeq = Math.max(nextSeq, normalized.seq + 1);
+    return normalized;
+  });
+
+  const runChecks = (candidateEvents, tailHint) => {
+    const violations = [];
+    // E2 —— 全列表 seq 严格连续（含拟写事件）；tailHint 时给 append-only 语境
+    let expected = baseSeq;
+    for (let i = 0; i < candidateEvents.length; i++) {
+      const event = candidateEvents[i];
+      if (typeof event.seq === 'number' && Number.isSafeInteger(event.seq) && event.seq >= 0) {
+        if (event.seq !== expected) {
+          const kind = event.seq < expected ? '倒退（backward）' : '缺口（gap）';
+          const tail = tailHint !== undefined && i === candidateEvents.length - 1 ? ' —— 只能追加到日志尾部（append-only，N6）' : '';
+          violations.push(violation('E2', { seq: event.seq, eventType: event.type }, `seq ${event.seq} 不连续：${kind}，期望 ${expected}${tail}`));
+          expected = event.seq + 1;
+        } else {
+          expected = event.seq + 1;
+        }
+      }
+    }
+    // E1/E3/E4/E5/E6 + M1 + P1/P2 —— 逐事件
+    for (const event of candidateEvents) {
+      const loc = { seq: event.seq, lineNo: null, eventType: event.type };
+      violations.push(...envelopeViolations(event, loc));
+      violations.push(...engineViolations(event, loc));
+      violations.push(...pluginViolations(event, loc));
+    }
+    // S1–S7 —— 与官方同语义的增量重放（含拟写事件）
+    const replay = replaySurface(candidateEvents.map((event) => ({ event })));
+    violations.push(...replay.violations);
+    // S8 —— 官方 foldSurface 终验
+    const folded = finalFold(candidateEvents);
+    if (folded.error) {
+      violations.push(violation('S8', { lineNo: null }, `官方 foldSurface 重放失败：${folded.error.message} —— 会话加载会被拒（SessionPersistenceCorruptionError）`));
+    }
+    const bySeverity = { error: 0, warning: 0, info: 0 };
+    for (const v of violations) bySeverity[v.severity] = (bySeverity[v.severity] ?? 0) + 1;
+    return {
+      ok: bySeverity.error === 0,
+      violations,
+      bySeverity,
+      surface: folded.surface ?? { nodes: replay.nodes, replacements: [] },
+      nextSeq: candidateEvents.length ? candidateEvents[candidateEvents.length - 1].seq + 1 : baseSeq,
+    };
+  };
+
+  return {
+    events,
+    get nextSeq() {
+      return nextSeq;
+    },
+
+    /**
+     * 追加写入前校验：candidate 将以 nextSeq 进入日志。
+     * candidate 可携带 seq（必须等于 nextSeq）或不携带（自动赋 nextSeq）。
+     */
+    validateAppend(candidate, opts = {}) {
+      if (typeof candidate !== 'object' || candidate === null || Array.isArray(candidate)) {
+        return {
+          ok: false,
+          violations: [violation('E1', {}, '拟写事件必须是普通对象（会话事件信封）')],
+          bySeverity: { error: 1, warning: 0, info: 0 },
+          surface: null,
+          nextSeq,
+        };
+      }
+      const normalized = normalizeCandidate(candidate, nextSeq);
+      const after = [...events, normalized];
+      const result = runChecks(after, nextSeq);      result.stateAfter = {
+        events: after,
+        nextSeq: result.nextSeq,
+        surfaceNodes: result.surface?.nodes ?? [],
+      };
+      return result;
+    },
+
+    /**
+     * 帧级手术校验：editedEvents 是"写入后将存在的完整事件列表"。
+     * 用于安全修复协议第 2 步（改后确认）：必须与"改前基线
+     * （validateSessionLog 通过）"双绿才允许落盘。
+     */
+    validateEdit(editedEvents) {
+      if (!Array.isArray(editedEvents)) {
+        return {
+          ok: false,
+          violations: [violation('E1', {}, 'editedEvents 必须是事件数组')],
+          bySeverity: { error: 1, warning: 0, info: 0 },
+          surface: null,
+          nextSeq,
+        };
+      }
+      const result = runChecks(editedEvents, undefined);
+      result.stateAfter = {
+        events: editedEvents,
+        nextSeq: result.nextSeq,
+        surfaceNodes: result.surface?.nodes ?? [],
+      };
+      return result;
+    },
+  };
+}
+
+/**
+ * 一站式便利：加载会话日志 → 建立写前校验器。
+ * @param {import('./log-reader.js').loadSessionLog} log `loadSessionLog()` 结果
+ */
+export function preWriterFromLog(log) {
+  const events = (log.events ?? []).map((e) => e.event);
+  return createPreWriter({ events });
+}

package/lib/validate.js

@@ -0,0 +1,147 @@
+/**
+ * dsh-log-contract · lib/validate.js
+ *
+ * 离线体检引擎：对 `loadSessionLog` 的结果逐条跑契约规则，产出违规报告。
+ *
+ * 判定哲学（复盘事故 §四-1）：**持久化层以官方 `foldSurface` 不抛为通过**，
+ * 但为定位问题，先用与官方同语义的增量重放做逐事件归因（S1–S7），
+ * 再跑官方 foldSurface 作终验（S8）——两套都绿才算过。
+ */
+import { ruleById } from './contracts.js';
+import {
+  CHUNK_ROW_TYPES,
+  envelopeViolations,
+  engineViolations,
+  finalFold,
+  isSafeInt,
+  pluginViolations,
+  replaySurface,
+  violation,
+} from './checks.js';
+
+/**
+ * 对会话日志执行全量离线体检。
+ *
+ * @param {object} log `loadSessionLog()` 的返回值
+ * @param {{ baseSeq?: number }} [opts]
+ * @returns {{
+ *   ok: boolean,
+ *   violations: Array,
+ *   summary: object,
+ *   surface: object,
+ * }}
+ */
+export function validateSessionLog(log, opts = {}) {
+  const { baseSeq = 0 } = opts;
+  const violations = [];
+  const { header, headerLine, rows, events, frameInfo } = log;
+
+  // ── Z · 帧结构 ─────────────────────────────────────────────────────────
+  if (frameInfo?.torn) {
+    violations.push(violation('Z1', { lineNo: null }, `zstd 尾帧撕裂：可能是写入中的 in-flight 帧或文件被截断（帧数 ${frameInfo.frames}）`));
+  }
+  if (frameInfo?.error) {
+    violations.push(violation('Z2', { lineNo: null }, frameInfo.error));
+  }
+
+  // ── H · header ─────────────────────────────────────────────────────────
+  if (header === null) {
+    violations.push(violation('H1', { lineNo: headerLine }, '首行不是合法 JSON —— 整个会话不可读'));
+  } else {
+    if (header.type !== 'session') {
+      violations.push(violation('H1', { lineNo: headerLine }, `首行 type 必须为 "session"（实际 ${String(header.type)}）`));
+    }
+    if (header.version !== 0) {
+      violations.push(violation('H2', { lineNo: headerLine }, `header.version 必须为 0（实际 ${String(header.version)}）——格式版本演进无迁移机制（F1）`));
+    }
+    if (typeof header.id !== 'string' || header.id === '') {
+      violations.push(violation('H2', { lineNo: headerLine }, 'header.id 必须为非空字符串'));
+    }
+    if (!Number.isSafeInteger(header.createdAt) || header.createdAt < 0) {
+      violations.push(violation('H2', { lineNo: headerLine }, 'header.createdAt 必须为非负安全整数'));
+    }
+    if (header.cwd !== undefined && (typeof header.cwd !== 'string' || !header.cwd.startsWith('/'))) {
+      violations.push(violation('H2', { lineNo: headerLine }, 'header.cwd 若存在必须为绝对路径'));
+    }
+    if (header.origin !== undefined && header.origin !== 'subagent') {
+      violations.push(violation('H2', { lineNo: headerLine }, `header.origin 只能为 "subagent"（实际 ${String(header.origin)}）`));
+    }
+  }
+
+  // ── R · 存储行 ─────────────────────────────────────────────────────────
+  for (const row of rows) {
+    if (row.error && row.value === null) {
+      violations.push(violation('R1', { lineNo: row.lineNo }, '该行不是合法 JSON（损坏行）'));
+    } else if (row.error && CHUNK_ROW_TYPES.has(row.value?.type)) {
+      violations.push(violation('R2', { lineNo: row.lineNo }, `chunk 行 "${row.value.type}" 损坏：${row.error.message} —— 整段 run 丢失且加载失败（fail-loud，无跳过逃生舱）`));
+    }
+  }
+
+  // ── E · 事件信封 + seq 连续性 ──────────────────────────────────────────
+  let expectedSeq = baseSeq;
+  let seqBroken = false;
+  for (const { event, lineNo } of events) {
+    const loc = { seq: event.seq, lineNo, eventType: event.type };
+    violations.push(...envelopeViolations(event, loc));
+    if (typeof event.seq === 'number' && Number.isSafeInteger(event.seq) && event.seq >= 0) {
+      if (event.seq !== expectedSeq) {
+        const kind = event.seq < expectedSeq ? '倒退（backward）' : '缺口（gap）';
+        violations.push(violation('E2', loc, `seq ${event.seq} 不连续：${kind}，期望 ${expectedSeq} —— 违反单写入者假设（N6）`));
+        seqBroken = true;
+        expectedSeq = event.seq + 1;
+      } else {
+        expectedSeq = event.seq + 1;
+      }
+    }
+  }
+
+  // ── S · surface 增量重放（归因）+ 官方 foldSurface 终验 ────────────────
+  const replay = replaySurface(events);
+  violations.push(...replay.violations);
+
+  const folded = finalFold(events.map((e) => e.event));
+  if (folded.error) {
+    violations.push(violation('S8', { lineNo: null }, `官方 foldSurface 重放失败：${folded.error.message} —— 会话加载会被拒（SessionPersistenceCorruptionError）`));
+  }
+
+  // ── M / P ──────────────────────────────────────────────────────────────
+  for (const { event, lineNo } of events) {
+    const loc = { seq: event.seq, lineNo, eventType: event.type };
+    violations.push(...engineViolations(event, loc));
+    violations.push(...pluginViolations(event, loc));
+  }
+
+  // ── C · 并发（仅当出现 seq 破坏时给出解释性告警）─────────────────────
+  if (seqBroken) {
+    violations.push(violation('C1', { lineNo: null }, 'seq 缺口/倒退是多写入者（≥2 个 Host 进程共享同一 session 目录）并发写的典型后果；离线体检无法观测竞态本身，但此痕迹需人工核查（N6）'));
+  }
+
+  // ── 汇总 ───────────────────────────────────────────────────────────────
+  violations.sort((a, b) => (a.seq ?? -1) - (b.seq ?? -1) || (a.lineNo ?? -1) - (b.lineNo ?? -1));
+  const bySeverity = { error: 0, warning: 0, info: 0 };
+  const byLayer = {};
+  for (const v of violations) {
+    bySeverity[v.severity] = (bySeverity[v.severity] ?? 0) + 1;
+    byLayer[v.layer] = (byLayer[v.layer] ?? 0) + 1;
+  }
+  const summary = {
+    total: violations.length,
+    bySeverity,
+    byLayer,
+    events: events.length,
+    surfaceNodes: replay.nodes.length,
+    replaceGeneration: replay.replaceGeneration,
+    frames: frameInfo?.frames ?? 0,
+    compressedBytes: frameInfo?.compressedBytes ?? 0,
+    plaintextBytes: frameInfo?.plaintextBytes ?? 0,
+  };
+
+  return {
+    ok: bySeverity.error === 0,
+    violations,
+    summary,
+    surface: folded.surface ?? { nodes: replay.nodes, replacements: [] },
+  };
+}
+
+export { ruleById };

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "dsh-log-contract",
+  "description": "日志契约守护 — DSH session log contract guard: offline health check (CLI) + pre-write validation for DeepSeek Harness session logs",
+  "version": "0.1.0",
+  "packageManager": "pnpm@11.7.0",
+  "type": "module",
+  "main": "lib/index.js",
+  "bin": {
+    "dsh-log-contract": "./bin/dsh-log-contract.mjs"
+  },
+  "exports": {
+    ".": {
+      "default": "./lib/index.js"
+    },
+    "./contracts": {
+      "default": "./lib/contracts.js"
+    },
+    "./prewrite": {
+      "default": "./lib/prewrite.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/**/*.js",
+    "bin/**/*.mjs",
+    "docs/**/*.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "check": "node scripts/check-syntax.mjs",
+    "test": "vitest run",
+    "prepublishOnly": "pnpm check && pnpm test"
+  },
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "session",
+    "log",
+    "contract",
+    "validator",
+    "prewrite",
+    "jsonl",
+    "zstd",
+    "cli"
+  ],
+  "author": "OfferKuai <contact@offerkuai.com> (https://www.offerkuai.com)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yamingmou/dsh-log-contract.git"
+  },
+  "bugs": {
+    "url": "https://github.com/yamingmou/dsh-log-contract/issues"
+  },
+  "homepage": "https://github.com/yamingmou/dsh-log-contract#readme",
+  "engines": {
+    "node": ">=22"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-session": "0.1.0-rc.7",
+    "esbuild": "0.28.2",
+    "vitest": "4.1.11"
+  }
+}