dsh-log-contract 0.1.0

package/lib/checks.js

@@ -0,0 +1,266 @@
+/**
+ * dsh-log-contract · lib/checks.js
+ *
+ * 逐事件契约检查（共享层）：离线体检（validate.js）与写前校验（prewrite.js）
+ * 复用同一套判定逻辑，保证"体检看到的问题 = 写入前拦下的问题"。
+ *
+ * 全部判定与 `@deepseek-ai/dsh-session@0.1.0-rc.7` 官方实现同语义，
+ * 每条违规都挂 `lib/contracts.js` 中的规则 id 与官方源码出处。
+ */
+import { foldSurface, isJsonValue, isSurfaceEligibleType, KNOWN_SESSION_EVENT_TYPES } from '@deepseek-ai/dsh-session';
+import { ruleById } from './contracts.js';
+
+export const SURFACE_TYPES = new Set(['user/message', 'assistant/message', 'tool/result']);
+export const CHUNK_ROW_TYPES = new Set(['text-chunks', 'reasoning-chunks', 'tool-call-chunks']);
+export const MARKER_PREFIXES = ['retrace', 'message-editor'];
+
+/** 构造一条违规记录。 */
+export function violation(id, eventOrLoc, message, extra = {}) {
+  const rule = ruleById(id);
+  const loc = eventOrLoc ?? {};
+  return {
+    id,
+    severity: rule?.severity ?? 'error',
+    layer: rule?.layer ?? 'unknown',
+    seq: typeof loc.seq === 'number' ? loc.seq : null,
+    lineNo: typeof loc.lineNo === 'number' ? loc.lineNo : null,
+    eventType: loc.eventType ?? null,
+    message,
+    source: rule?.source ?? null,
+    ...extra,
+  };
+}
+
+export function isSafeInt(v) {
+  return typeof v === 'number' && Number.isSafeInteger(v) && v >= 0;
+}
+
+/** 事件信封 shape：seq/type/time/data（E1/E3/E4/E5/E6）。 */
+export function envelopeViolations(event, loc) {
+  const out = [];
+  if (!isSafeInt(event.seq)) {
+    out.push(violation('E1', loc, `事件 seq 缺失或非法（${String(event.seq)}），必须为非负安全整数`));
+  }
+  if (typeof event.type !== 'string') {
+    out.push(violation('E3', loc, `事件缺少 type 字符串（${String(event.type)}）`));
+  } else if (!KNOWN_SESSION_EVENT_TYPES.has(event.type) && event.ignorable !== true) {
+    out.push(violation('E3', loc, `type "${event.type}" 不在已知词汇表内且未带 ignorable 标记（可能由更新版本的 harness 写入）`));
+  }
+  if (!isJsonValue(event.data)) {
+    out.push(violation('E4', loc, 'data 不是 lossless-JSON（函数/循环引用/非有限数等），写入热路径会拒绝'));
+  }
+  if (event.surfaceOp !== undefined && !isJsonValue(event.surfaceOp)) {
+    out.push(violation('E4', loc, 'surfaceOp 不是 lossless-JSON'));
+  }
+  if (event.sourceEventSeqs !== undefined && !isJsonValue(event.sourceEventSeqs)) {
+    out.push(violation('E4', loc, 'sourceEventSeqs 不是 lossless-JSON'));
+  }
+  if (event.type === 'request/header-delta') {
+    out.push(violation('E5', loc, '使用已删除的遗留格式 request/header-delta，写入即被拒'));
+  }
+  if (event.type === 'request/header' && event.data?.reason === 'fallback') {
+    out.push(violation('E5', loc, 'request/header 使用已删除的遗留 reason "fallback"'));
+  }
+  out.push(...messageShapeViolations(event, loc));
+  return out;
+}
+
+/** 镜像官方 assertMessageEventShape（lib/index.js:1242-1266）。 */
+export function messageShapeViolations(event, loc) {
+  const type = event.type;
+  if (type !== 'user/message' && type !== 'assistant/message' && type !== 'tool/result') return [];
+  const out = [];
+  const data = event.data;
+  const record = typeof data === 'object' && data !== null ? data : undefined;
+  const message = type === 'user/message' ? record : record?.message;
+  const shape = () => `（seq ${event.seq}）消息形状`;
+  if (typeof message !== 'object' || message === null) {
+    out.push(violation('E6', loc, `${shape()}：缺少 message 对象`));
+    return out;
+  }
+  if (typeof message.id !== 'string' || message.id === '') {
+    out.push(violation('E6', loc, `${shape()}：id 必须为非空字符串`));
+  }
+  const expectedRole = type === 'assistant/message' ? 'assistant' : 'user';
+  if (message.role !== expectedRole) {
+    out.push(violation('E6', loc, `${shape()}：role 必须为 "${expectedRole}"，实际 ${String(message.role)}`));
+  }
+  const source = message.source;
+  if (typeof source !== 'object' || source === null || typeof source.kind !== 'string' || source.kind === '') {
+    out.push(violation('E6', loc, `${shape()}：source.kind 缺失或非法`));
+  }
+  if (!Array.isArray(message.content)) {
+    out.push(violation('E6', loc, `${shape()}：content 必须为数组`));
+  }
+  if (type === 'assistant/message') {
+    if (source?.kind !== 'model' || typeof source.provider !== 'string' || source.provider === '' || typeof source.model !== 'string' || source.model === '') {
+      out.push(violation('E6', loc, `${shape()}：assistant/message 必须带 model source（provider/model 非空）`));
+    }
+  }
+  if (type === 'tool/result') {
+    if (source?.kind !== 'tool' || typeof source.callId !== 'string' || source.callId === '') {
+      out.push(violation('E6', loc, `${shape()}：tool/result 必须带 tool source（callId 非空）`));
+    }
+    const content = message.content;
+    const block = Array.isArray(content) ? content[0] : undefined;
+    if (content?.length !== 1 || typeof block !== 'object' || block === null || block.type !== 'tool-result' || !Array.isArray(block.content)) {
+      out.push(violation('E6', loc, `${shape()}：必须恰含一个 tool-result block`));
+    } else if (block.toolCallId !== source?.callId) {
+      out.push(violation('E6', loc, `${shape()}：block.toolCallId 与 source.callId 不匹配`));
+    }
+  }
+  return out;
+}
+
+/** replace 操作数精确形状（镜像 isReplaceOp，lib/index.js:300-303）。 */
+export function isReplaceOp(op) {
+  return (
+    typeof op === 'object' && op !== null &&
+    Object.keys(op).length === 3 &&
+    Object.hasOwn(op, 'op') && Object.hasOwn(op, 'start') && Object.hasOwn(op, 'end') &&
+    op.op === 'replace' && isSafeInt(op.start) && isSafeInt(op.end)
+  );
+}
+
+/**
+ * 与官方同语义的 surface 增量重放，逐事件归因 S1–S7。
+ * @param {Array<{event:object, lineNo?:number}>} events 按日志顺序的事件（带 loc 包装）
+ */
+export function replaySurface(events) {
+  const violations = [];
+  const nodes = [];
+  let replaceGeneration = 0;
+
+  for (const { event, lineNo } of events) {
+    const loc = { seq: event.seq, lineNo, eventType: event.type };
+    const eligible = SURFACE_TYPES.has(event.type);
+    const op = event.surfaceOp;
+    const src = event.sourceEventSeqs;
+
+    if (!eligible) {
+      if (op !== undefined || src !== undefined) {
+        violations.push(violation('S2', loc, `非 surface 类型 "${event.type}" 不得携带 surfaceOp/sourceEventSeqs`));
+      }
+      continue;
+    }
+    if (op === undefined) {
+      violations.push(violation('S1', loc, `surface 候选类型 "${event.type}" 必须携带 surfaceOp 标记`));
+      continue;
+    }
+
+    if (op === 'append') {
+      violations.push(...provenanceViolations(event, loc, []));
+      nodes.push(event.seq);
+      continue;
+    }
+
+    if (!isReplaceOp(op)) {
+      violations.push(violation('S4', loc, 'replace 操作数必须精确为 {op:"replace", start, end}（start/end 为非负安全整数）'));
+      continue;
+    }
+    const startIdx = nodes.indexOf(op.start);
+    const endIdx = nodes.indexOf(op.end);
+    if (startIdx === -1 || endIdx === -1) {
+      violations.push(violation('S4', loc, `replace 范围 ${op.start}..${op.end} 不在当前 surface 中（start 存在=${startIdx !== -1}，end 存在=${endIdx !== -1}）`));
+      continue;
+    }
+    if (startIdx > endIdx) {
+      violations.push(violation('S4', loc, `replace start ${op.start}（index ${startIdx}）在 end ${op.end}（index ${endIdx}）之后`));
+      continue;
+    }
+    const shadowedSeqs = nodes.slice(startIdx, endIdx + 1);
+    violations.push(...provenanceViolations(event, loc, shadowedSeqs));
+    violations.push(...toolResultRewriteViolations(event, loc, shadowedSeqs));
+    nodes.splice(startIdx, endIdx - startIdx + 1, event.seq);
+    replaceGeneration += 1;
+  }
+
+  return { violations, nodes, replaceGeneration };
+}
+
+/** 镜像官方 assertProvenance（lib/index.js:320-337）。 */
+export function provenanceViolations(event, loc, shadowedSeqs) {
+  const out = [];
+  const raw = event.sourceEventSeqs;
+  const sources = new Set();
+  if (raw !== undefined) {
+    if (!Array.isArray(raw)) {
+      out.push(violation('S6', loc, `sourceEventSeqs 必须为数组（实际 ${typeof raw}）`));
+      return out;
+    }
+    if (raw.length === 0 && event.type !== 'assistant/message') {
+      out.push(violation('S6', loc, 'sourceEventSeqs 不得为空（除 assistant/message 外）'));
+    }
+    let nonEarlier;
+    for (const source of raw) {
+      if (!isSafeInt(source)) {
+        out.push(violation('S6', loc, `sourceEventSeqs 必须稠密包含非负安全整数（非法值 ${String(source)}）`));
+        continue;
+      }
+      if (sources.has(source)) {
+        out.push(violation('S6', loc, `sourceEventSeqs 不得重复（${source}）`));
+      }
+      sources.add(source);
+      if (nonEarlier === undefined && source >= event.seq) nonEarlier = source;
+    }
+    if (nonEarlier !== undefined) {
+      out.push(violation('S6', loc, `sourceEventSeqs 必须引用更早事件：${nonEarlier} >= 当前 seq ${event.seq}`));
+    }
+  }
+  const missing = shadowedSeqs.filter((seq) => !sources.has(seq));
+  if (missing.length > 0) {
+    out.push(violation('S5', loc, `surface replace: sourceEventSeqs 必须覆盖每个被替换节点；缺失 ${missing.join(', ')}（共 ${missing.length} 个）`, { missingSeqs: missing }));
+  }
+  return out;
+}
+
+/** 镜像官方 assertToolResultRewrite（lib/index.js:369-395）的判定核心。 */
+export function toolResultRewriteViolations(event, loc, shadowedSeqs) {
+  if (event.type !== 'tool/result') return [];
+  const out = [];
+  if (shadowedSeqs.length !== 1) {
+    out.push(violation('S7', loc, `tool/result 替换必须恰好重写 1 个当前节点（实际 ${shadowedSeqs.length} 个）`));
+  }
+  return out;
+}
+
+/** M1 —— 客户端引擎层：turn/step 缺失（null）的 assistant/message 只能 replace。 */
+export function engineViolations(event, loc) {
+  const out = [];
+  if (event.type === 'assistant/message' && event.surfaceOp === 'append') {
+    // turn/step 位于 event.data 层（实证：正常消息 data.turn/data.step 为数字，
+    // 插件 marker data.turn/data.step 为 null —— 复盘事故第 2 轮）
+    const turn = event.data?.turn;
+    const step = event.data?.step;
+    if (turn == null || step == null) {
+      out.push(violation('M1', loc, `assistant/message 以 append 进入 surface 但 data.turn/data.step 缺失（turn=${String(turn)}, step=${String(step)}）——只能以 replace 承载（插件 marker 定义），append 会触发客户端引擎崩溃（rt.js:6816）`));
+    }
+  }
+  return out;
+}
+
+/** P 层 —— 插件 marker 语义（retrace 等以 assistant/message replace 承载的 marker）。 */
+export function pluginViolations(event, loc) {
+  const out = [];
+  const isMarkerReplace = event.type === 'assistant/message' && event.surfaceOp && event.surfaceOp !== 'append' && event.data?.editor !== undefined;
+  if (!isMarkerReplace) return out;
+  const id = event.data?.message?.id;
+  const known = typeof id === 'string' && MARKER_PREFIXES.some((p) => id.startsWith(`${p}-`));
+  if (!known) {
+    out.push(violation('P1', loc, `marker id "${String(id)}" 前缀不在已知列表（${MARKER_PREFIXES.join('/')}-）——改名后未登记遗留前缀，旧 marker 隐藏语义将断裂（软兼容丢失）`));
+  }
+  const src = event.sourceEventSeqs;
+  if (Array.isArray(src) && src.includes(event.seq)) {
+    out.push(violation('P2', loc, `marker 自身 seq ${event.seq} 出现在自身 sourceEventSeqs（shadowed 集）——自指语义错误（marker 节点被隐藏逻辑跳过，不应被自己隐藏）`));
+  }
+  return out;
+}
+
+/** 官方 foldSurface 终验；不抛返回折叠结果，抛则返回 { error }。 */
+export function finalFold(events) {
+  try {
+    return { surface: foldSurface(events) };
+  } catch (err) {
+    return { error: err };
+  }
+}

package/lib/contracts.js

@@ -0,0 +1,267 @@
+/**
+ * dsh-log-contract · lib/contracts.js
+ *
+ * DSH 会话日志契约规则目录（spec）。
+ *
+ * 规则集来源：
+ * - `dsh-scale-audit-疑点记录.md`（59 条契约发现 / F1–F7 / N1–N6 / R1–R3）
+ * - `复盘-会话修复事故-20260825.md`（三层契约：持久化 / 客户端引擎 / 插件语义）
+ * - `@deepseek-ai/dsh-session@0.1.0-rc.7` 官方源码逐行核对（见每条 `source`）
+ *
+ * 每条规则只描述"契约是什么"；具体判定逻辑在 `lib/validate.js`（离线体检）
+ * 与 `lib/prewrite.js`（写前校验）中按 id 实现。severity：
+ * - error   —— 违反即会话不可加载 / 写入会被拒（fail-loud）
+ * - warning —— 合法但可疑（撕裂尾帧、未知 marker 前缀等）
+ * - info    —— 事实性观察（压缩统计等）
+ */
+
+export const LAYER = {
+  PERSISTENCE: 'persistence', // 持久化层：日志能被官方解码器完整重放
+  ENGINE: 'engine', // 客户端引擎层：事件形状匹配客户端定义
+  PLUGIN: 'plugin', // 插件语义层：marker 隐藏语义
+  CONCURRENCY: 'concurrency', // 并发/写入者假设
+  FRAMING: 'framing', // zstd 帧结构
+};
+
+export const SEVERITY = { ERROR: 'error', WARNING: 'warning', INFO: 'info' };
+
+/**
+ * 契约规则目录。id 前缀：
+ * - H  header / 会话头
+ * - R  存储行 / chunk 行
+ * - E  事件信封 / seq / type 词汇表
+ * - S  surface（模型可见面）不变量 —— 事故核心层
+ * - M  客户端引擎层
+ * - P  插件 marker 语义层
+ * - C  并发 / 写入者假设
+ * - Z  zstd 帧结构
+ */
+export const CONTRACT_RULES = [
+  // ── H · header ──────────────────────────────────────────────────────────
+  {
+    id: 'H1',
+    title: '首行为合法 JSON 且 type=session',
+    layer: LAYER.PERSISTENCE,
+    severity: SEVERITY.ERROR,
+    source: '@deepseek-ai/dsh-session lib/index.js:1109-1126 (validateSessionHeader)',
+    description: '会话日志首行必须是可 JSON.parse 的对象，且 type 为 "session"。首行损坏 = 整个会话不可读。',
+  },
+  {
+    id: 'H2',
+    title: 'header 版本与必填字段',
+    layer: LAYER.PERSISTENCE,
+    severity: SEVERITY.ERROR,
+    source: '@deepseek-ai/dsh-session lib/index.js:1110-1125',
+    description: 'header.version 必须为 0；id 为字符串；createdAt 为非负安全整数；cwd 若存在必须为绝对路径；origin 只能为 "subagent"。',
+  },
+
+  // ── R · 存储行 ──────────────────────────────────────────────────────────
+  {
+    id: 'R1',
+    title: '每行必须是合法 JSON',
+    layer: LAYER.PERSISTENCE,
+    severity: SEVERITY.ERROR,
+    source: '审计方法论（scan-seq-gaps.mjs）；dsh-session-persistence-jsonl 读路径',
+    description: '非空行无法 JSON.parse = 损坏行。帧边界产生的空行是合法的（跳过）。',
+  },
+  {
+    id: 'R2',
+    title: 'chunk 行必须满足精确信封形状',
+    layer: LAYER.PERSISTENCE,
+    severity: SEVERITY.ERROR,
+    source: '@deepseek-ai/dsh-session lib/index.js:922-971 (validateRow)',
+    description: 'text-chunks / reasoning-chunks / tool-call-chunks 行必须精确为 {type, seq0, time0, data}，data 精确为 {turn, step, index, dt, texts|args}。损坏 = 整段 run 丢失且加载失败（fail-loud，无跳过逃生舱）。',
+  },
+  {
+    id: 'R3',
+    title: 'chunk 行展开后成员 seq/time 安全',
+    layer: LAYER.PERSISTENCE,
+    severity: SEVERITY.ERROR,
+    source: '@deepseek-ai/dsh-session lib/index.js:964-969',
+    description: '展开后成员 seq 与 time 必须保持安全整数（seq0+len-1 与逐 gap 累加的 time 不溢出）。',
+  },
+
+  // ── E · 事件信封 ────────────────────────────────────────────────────────
+  {
+    id: 'E1',
+    title: '每个事件携带非负安全整数 seq',
+    layer: LAYER.PERSISTENCE,
+    severity: SEVERITY.ERROR,
+    source: '@deepseek-ai/dsh-session lib/index.js:295-298 (isEventSeq)、:1453-1459 (append 信封)',
+    description: '事件信封为 {type, seq, time, data, ...surfaceMetadata}；seq 必须是非负安全整数。',
+  },
+  {
+    id: 'E2',
+    title: 'seq 严格连续（单写入者假设）',
+    layer: LAYER.PERSISTENCE,
+    severity: SEVERITY.ERROR,
+    source: '@deepseek-ai/dsh-session lib/index.js:398 (planSurfaceEvent "not contiguous")；审计 S2/N6',
+    description: 'seq 必须从 0（或窗口 baseSeq）严格连续递增。缺口/倒退 = 违反单写入者假设（多实例共享存储并发写的痕迹），加载时直接 throw。',
+  },
+  {
+    id: 'E3',
+    title: 'type 必须在已知词汇表内（或带 ignorable 标记）',
+    layer: LAYER.PERSISTENCE,
+    severity: SEVERITY.ERROR,
+    source: '@deepseek-ai/dsh-session lib/index.js:1046-1049 (KNOWN_SESSION_EVENT_TYPES 注释)',
+    description: '词汇表外的 type 会被持久化读路径拒绝，除非事件带信封级 ignorable 标记（新版本 harness 写入的日志）。插件事件（如 retrace marker 以 assistant/message 承载）不在词汇表外——它们复用核心类型。',
+  },
+  {
+    id: 'E4',
+    title: 'data 与 surface 元数据必须 JSON 无损',
+    layer: LAYER.PERSISTENCE,
+    severity: SEVERITY.ERROR,
+    source: '@deepseek-ai/dsh-session lib/index.js:1446-1450 (snapshotJsonValue 双快照)',
+    description: 'append 热路径对 data 与 surfaceMetadata 各做一次 lossless-JSON 全量校验；非 JSON 安全值（函数/循环引用/非有限数）写入前即被拒。',
+  },
+  {
+    id: 'E5',
+    title: '禁用遗留词汇',
+    layer: LAYER.PERSISTENCE,
+    severity: SEVERITY.ERROR,
+    source: '@deepseek-ai/dsh-session lib/index.js:1273-1277 (assertSupportedRequestHeader)',
+    description: 'request/header-delta 与 reason=fallback 的 request/header 是已删除的遗留格式，写入即被拒。',
+  },
+  {
+    id: 'E6',
+    title: '消息类事件消息形状',
+    layer: LAYER.PERSISTENCE,
+    severity: SEVERITY.ERROR,
+    source: '@deepseek-ai/dsh-session lib/index.js:1242-1266 (assertMessageEventShape)',
+    description: 'user/message、assistant/message、tool/result 必须携带具名 message（非空 id、正确 role、合法 source、content 数组；assistant 需 model source，tool/result 需 tool source 且 toolCallId 匹配）。',
+  },
+
+  // ── S · surface 不变量（事故核心层）────────────────────────────────────
+  {
+    id: 'S1',
+    title: 'surface 候选类型必须携带 surfaceOp',
+    layer: LAYER.PERSISTENCE,
+    severity: SEVERITY.ERROR,
+    source: '@deepseek-ai/dsh-session lib/index.js:312-317 (surfaceOpOf)',
+    description: 'user/message、assistant/message、tool/result 是 surface-eligible 类型，缺 surfaceOp 即违反契约。',
+  },
+  {
+    id: 'S2',
+    title: '非 surface 类型不得携带 surface 元数据',
+    layer: LAYER.PERSISTENCE,
+    severity: SEVERITY.ERROR,
+    source: '@deepseek-ai/dsh-session lib/index.js:307-311 (surfaceOpOf)',
+    description: '词汇表内非 surface-eligible 类型带 surfaceOp / sourceEventSeqs = 违反契约。',
+  },
+  {
+    id: 'S3',
+    title: 'append 的 sourceEventSeqs 契约',
+    layer: LAYER.PERSISTENCE,
+    severity: SEVERITY.ERROR,
+    source: '@deepseek-ai/dsh-session lib/index.js:401-407、:320-337 (assertProvenance)',
+    description: 'append 以空 shadowed 集校验：sourceEventSeqs 若携带必须满足 assertProvenance（数组、无重复、全部引用更早事件）；任何违规即写入被拒。',
+  },
+  {
+    id: 'S4',
+    title: 'replace 操作数与范围合法性',
+    layer: LAYER.PERSISTENCE,
+    severity: SEVERITY.ERROR,
+    source: '@deepseek-ai/dsh-session lib/index.js:300-303 (isReplaceOp)、:339-350 (replacementRange)',
+    description: 'replace 必须是精确的 {op:"replace", start, end}；start/end 必须存在于当前 surface 节点且 startIdx ≤ endIdx。',
+  },
+  {
+    id: 'S5',
+    title: 'replace 的 sourceEventSeqs 必须完整覆盖被替换节点',
+    layer: LAYER.PERSISTENCE,
+    severity: SEVERITY.ERROR,
+    source: '@deepseek-ai/dsh-session lib/index.js:335-336 (assertProvenance)；复盘事故第 1 轮',
+    description: '★ 写前校验核心规则：sourceEventSeqs 必须包含每一个被替换（shadowed）的 surface 节点，缺一个 = 会话加载被拒（SessionPersistenceCorruptionError）。2026-08-25 事故第 1 轮（清空 sourceEventSeqs）正是违反此规则。',
+  },
+  {
+    id: 'S6',
+    title: 'sourceEventSeqs 自身约束',
+    layer: LAYER.PERSISTENCE,
+    severity: SEVERITY.ERROR,
+    source: '@deepseek-ai/dsh-session lib/index.js:320-333 (assertProvenance)',
+    description: 'sourceEventSeqs 存在时必须为数组、无重复、全部引用更早事件（< 当前 seq），且除 assistant/message 外不得为空。',
+  },
+  {
+    id: 'S7',
+    title: 'tool/result 替换仅允许单节点内容改写',
+    layer: LAYER.PERSISTENCE,
+    severity: SEVERITY.ERROR,
+    source: '@deepseek-ai/dsh-session lib/index.js:369-395 (assertToolResultRewrite)',
+    description: 'tool/result 的 replace 必须恰好重写 1 个当前节点、目标是 tool/result，且除 message.content 外不得改动任何字段。',
+  },
+  {
+    id: 'S8',
+    title: '整日志 foldSurface 可重放',
+    layer: LAYER.PERSISTENCE,
+    severity: SEVERITY.ERROR,
+    source: '@deepseek-ai/dsh-session lib/index.js:444-455 (foldSurface)；复盘"官方 foldSurface 不抛 = 通过"',
+    description: '终验：把全部事件按序喂给官方 foldSurface，不抛 = 持久化层通过。S1–S7 任何一条违反都会在此暴露。',
+  },
+
+  // ── M · 客户端引擎层 ────────────────────────────────────────────────────
+  {
+    id: 'M1',
+    title: 'turn/step 为 null 的 assistant/message 只能 replace，不能 append',
+    layer: LAYER.ENGINE,
+    severity: SEVERITY.ERROR,
+    source: '复盘事故第 2 轮（rt.js:6816 崩溃）；实证 data.turn/data.step：正常消息为数字、插件 marker 为 null',
+    description: 'data.turn/data.step 为 null 的 assistant/message（如插件 marker）只能以 replace 承载（走插件 marker 定义）；作为 append 会落进核心 assistant-step 定义，因 turn=null 发布 location data 导致客户端引擎崩溃。',
+  },
+
+  // ── P · 插件 marker 语义层 ──────────────────────────────────────────────
+  {
+    id: 'P1',
+    title: 'marker id 前缀必须被识别',
+    layer: LAYER.PLUGIN,
+    severity: SEVERITY.WARNING,
+    source: 'retrace 插件 RENAME RULE（lib/client.js:29-44）；复盘事故',
+    description: 'assistant/message 替换事件的 message.id 以 retrace- / message-editor- 为已知前缀。未知前缀 = 改名后未登记遗留前缀，旧 marker 的隐藏语义会断裂（软兼容丢失）。',
+  },
+  {
+    id: 'P2',
+    title: 'marker 自身 seq 不得出现在自身 shadowed 集',
+    layer: LAYER.PLUGIN,
+    severity: SEVERITY.ERROR,
+    source: 'retrace 插件 lib/client.js:393（"event and never a surface node"）',
+    description: 'marker 的 sourceEventSeqs（= shadowedSeqs，驱动 CSS 隐藏）不得包含 marker 自身 seq——marker 节点由隐藏逻辑跳过，出现在 shadowed 集属于自指语义错误。',
+  },
+
+  // ── C · 并发 / 写入者假设 ───────────────────────────────────────────────
+  {
+    id: 'C1',
+    title: 'seq 缺口/倒退提示多写入者',
+    layer: LAYER.CONCURRENCY,
+    severity: SEVERITY.WARNING,
+    source: '审计 N6：dsh-session-persistence-jsonl appendLines 无锁（:1200-1227），全仓无会话级排他锁',
+    description: '离线体检无法直接观测跨进程竞态，但 E2 暴露的缺口/倒退即是"≥2 个 Host 进程共享同一 session 目录并发写"的后果。单实例部署不触发。',
+  },
+
+  // ── Z · zstd 帧结构 ─────────────────────────────────────────────────────
+  {
+    id: 'Z1',
+    title: 'zstd 尾帧撕裂',
+    layer: LAYER.FRAMING,
+    severity: SEVERITY.WARNING,
+    source: '审计 N5 相关；帧扫描方法论',
+    description: '尾帧不完整（torn）：可能正在写入（in-flight）或文件被截断。若这是唯一异常，通常可等待写入完成；若持续存在则是截断证据。',
+  },
+  {
+    id: 'Z2',
+    title: 'zstd 帧解码失败 = 单帧全损',
+    layer: LAYER.FRAMING,
+    severity: SEVERITY.ERROR,
+    source: '审计 N5：多帧单帧全损 → 整会话不可读',
+    description: '任一帧解码失败（磁盘 bitrot / 传输截断 / 并发写撕裂）即整会话不可读；帧越多，单帧损坏下丢失概率线性上升。',
+  },
+];
+
+/** 按 id 取规则。 */
+export function ruleById(id) {
+  return CONTRACT_RULES.find((r) => r.id === id);
+}
+
+/** 生成 docs/CONTRACTS.md 的目录行（供文档维护）。 */
+export function ruleTableRows() {
+  return CONTRACT_RULES.map(
+    (r) => `| ${r.id} | ${r.severity} | ${r.layer} | ${r.title} |`,
+  ).join('\n');
+}

package/lib/index.js

@@ -0,0 +1,10 @@
+/**
+ * dsh-log-contract · lib/index.js
+ *
+ * 日志契约守护（DSH session log contract guard）。
+ * 公开 API：离线体检 + 写前校验 + 契约目录。
+ */
+export { loadSessionLog } from './log-reader.js';
+export { validateSessionLog } from './validate.js';
+export { createPreWriter, preWriterFromLog } from './prewrite.js';
+export { CONTRACT_RULES, LAYER, SEVERITY, ruleById } from './contracts.js';