dsh-log-contract 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OfferKuai Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,163 @@
+# dsh-log-contract · 日志契约守护
+
+> DSH（DeepSeek Harness）会话日志的**结构契约保险丝**：离线体检 + 写前校验。
+> 原名 `log-contract-validator`（候选二号），按 Offer快 三件套规划定名 **`dsh-log-contract`**。
+
+给 DSH 会话日志（`*.jsonl` / `*.jsonl.zstd`）装一条保险丝：人眼看不出、程序解析会崩的日志格式漂移，在它这里被拦下并告警。它不判断日志**内容**对不对，只守护日志**结构**是否破坏了下游消费者（Harness 读路径、客户端引擎、插件 marker 语义）的预期。
+
+- **`check <session-log>`** —— 离线体检：官方解码器全量解码 + 契约逐条校验 + foldSurface 终验，产出违规报告。
+- **`prewrite <edit-file> --log <session-log>`** —— ★ 写前校验：任何写入（追加 / 帧级手术）在落盘之前先过三层契约，违约即拦。
+- **`contracts`** —— 列出内置契约规则目录（每条附官方源码出处）。
+
+---
+
+## 为什么需要它
+
+**#3632「one log, two consumers, two verdicts」**：一条日志同时被人类与自动化程序消费，人眼容忍格式微调，程序解析依赖严格契约；格式一旦漂移，人看不出问题，程序直接崩溃或误报。
+
+**2026-08-25 会话修复事故（真实回归用例）**：一次"恢复被隐藏内容"的修复，第 1 轮清空 marker 的 `sourceEventSeqs` 直接写盘 → 会话加载抛 `SessionPersistenceCorruptionError`；第 2 轮把 marker 改成 `append` → 客户端引擎崩溃。两次都是**违约写入没被拦**。如果有写前校验，会话根本不会被改坏。本工具把这次事故沉淀为两条核心规则（S5、M1）与回归测试。
+
+---
+
+## 三层契约（判定模型）
+
+| 层 | 契约 | 本工具 |
+|---|---|---|
+| **持久化层** | seq 严格连续；type 在已知词汇表内；surface 事件携带合法 `surfaceOp`；replace 的 `sourceEventSeqs` 必须**完整覆盖被替换节点**；官方 `foldSurface` 不抛 = 通过 | 规则 H/R/E/S（含 S5 核心） |
+| **客户端引擎层** | `data.turn/step` 为 null 的 `assistant/message` 只能以 **replace** 承载（插件 marker 定义），append 会触发引擎崩溃 | 规则 M1 |
+| **插件语义层** | marker id 前缀必须可识别（改名登记遗留前缀）；marker 自身 seq 不得进入自身 shadowed 集 | 规则 P1/P2 |
+
+> 校验哲学：先用与官方同语义的增量重放做**逐事件归因**（定位到 seq/行号），再跑官方 `foldSurface` 做**终验**（不抛才算过）——两套都绿才过。
+
+---
+
+## 安装
+
+```bash
+pnpm add -D dsh-log-contract   # 或 npm install
+pnpm dlx dsh-log-contract --help
+```
+
+依赖：Node ≥ 22（`node:zlib` 内置 zstd）、`@deepseek-ai/dsh-session`（peer，校验/解码复用官方实现，保证与 Harness 读路径同源）。
+
+---
+
+## CLI 用法
+
+### 1. 离线体检
+
+```bash
+dsh-log-contract check ~/.dsh/sessions/<id>.jsonl.zstd
+dsh-log-contract check ~/.dsh/sessions/<id>.jsonl.zstd --json   # 机器可读
+```
+
+输出示例：
+
+```
+📋 dsh-log-contract check —— backup-session-xxxx.jsonl.zstd
+   事件 204754 ｜ surface 节点 16 ｜ replace 代数 5 ｜ 帧 8620（3439.5KiB → 8191.3KiB）
+   违规 1（error 1 / warning 0）
+
+  [error] S5 @ seq 156425 / line 778 (assistant/message)
+      surface replace: sourceEventSeqs 必须覆盖每个被替换节点；缺失 121774, 121779（共 2 个）
+
+❌ 未通过：见上方违规明细（error 级 = 会话不可读/不可写）
+```
+
+退出码：0 = 通过（无 error 级违规）；1 = 存在 error 级违规。
+
+### 2. ★ 写前校验（本次事故的直接解药）
+
+`edit-file` 为 JSON，两种形状：
+
+```jsonc
+// 拟追加一个事件到日志尾部（seq 缺省 = 自动按 nextSeq 赋值）
+{ "append": { "type": "assistant/message", "surfaceOp": { "op": "replace", "start": 121774, "end": 156421 }, "sourceEventSeqs": [121774, 121779, "…"], "data": { "turn": null, "step": null, "message": { "…": "…" }, "editor": { "targetSeq": 156430, "text": "…" } } } }
+
+// 帧级手术后的完整事件列表（改后确认，与改前基线双绿才允许落盘）
+{ "edit": [ "…完整事件列表…" ] }
+```
+
+```bash
+dsh-log-contract prewrite marker-write.json --log ~/.dsh/sessions/<id>.jsonl.zstd
+```
+
+- 基线本身有 error 级违规时直接拒绝校验（安全修复协议第 2 步：**改前基线必须绿**）。
+- 判定通过才允许落盘——**validate first, commit later**（与官方 `SurfaceManager.validateNext` 同思路）。
+
+### 3. 契约目录
+
+```bash
+dsh-log-contract contracts
+```
+
+完整契约清单见 [docs/CONTRACTS.md](docs/CONTRACTS.md)。
+
+---
+
+## Node API（写前校验嵌入你的脚本）
+
+```js
+import { loadSessionLog, validateSessionLog, createPreWriter } from 'dsh-log-contract';
+
+// ① 基线体检（改前基线必须绿）
+const log = loadSessionLog('session.jsonl.zstd');
+const baseline = validateSessionLog(log);
+if (!baseline.ok) throw new Error('基线已坏，先修基线');
+
+// ② 写前校验：拟写入一个 marker replace
+const prewriter = createPreWriter({ events: log.events.map((e) => e.event) });
+const verdict = prewriter.validateAppend({
+  type: 'assistant/message',
+  surfaceOp: { op: 'replace', start: 121774, end: 156421 },
+  sourceEventSeqs: [121774, 121779 /* …必须完整覆盖被替换节点… */],
+  data: { turn: null, step: null, message: { /* … */ } },
+});
+if (!verdict.ok) {
+  for (const v of verdict.violations) console.error(v.id, v.message);
+  process.exit(1); // 不落盘
+}
+// ③ 通过后才写
+```
+
+---
+
+## 测试
+
+```bash
+pnpm check && pnpm test    # 语法检查 + 40 个单测（含事故回归用例）
+```
+
+- **合成夹具**（入库）：合法会话 / seq 缺口 / 空 sourceEventSeqs / turn=null append / 未知 type / 坏 chunk 行 / 撕裂尾帧 / 未知 marker 前缀 / 自指 shadowed 等。
+- **真实化石**（不入库，含用户隐私）：本地跑
+
+```bash
+node scripts/check-local-fossils.mjs   # 扫描 ../ 下 backup-session-*.jsonl.zstd
+```
+
+已知真值表：事故修复后会话 PASS；`seqgap`/`corrupt`/`rewritten-230542` FAIL；`spliced-orphan` PASS（持久化层合法——#3632 的"消费路径判不可读"属于另一类契约，本工具只守护持久化契约层，见 [docs/CONTRACTS.md](docs/CONTRACTS.md) 边界说明）。
+
+---
+
+## 与三件套的关系
+
+| 工具 | 象限 | 状态 |
+|---|---|---|
+| [workbuddy-session-fork](https://github.com/yamingmou/workbuddy-session-fork) | 会话分叉 · 状态管理 | ✅ 已发布 v1.2.0 |
+| **dsh-log-contract**（本仓库） | 日志契约 · 接口稳定性 | 🆕 Phase 1 CLI 离线体检 + 写前校验 |
+| dsh-turn-guard（规划中） | 中断回合 · 异常韧性 | 待立项 |
+
+三者共享同一份 DSH 日志事件契约认知（59 条审计发现 = spec，aborted/corrupt/seqgap 化石 = 测试集）。dsh-retrace（回溯时间线）可把本工具的违规标记渲染到时间线上；本工具是 retrace 投影源健康度的**前置保险**。
+
+---
+
+## Roadmap
+
+- [x] **Phase 1（本版 0.1.0）**：CLI 离线体检 + 写前校验 + 契约目录
+- [ ] Phase 1.5：违规报告的 `--fix` 建议（seq 缺口修复复用 `fix-seq-gap.mjs` 方法论）、CI 集成（`dsh-log-contract check` 作为 Harness 会话目录的定时守护）
+- [ ] Phase 2：运行时守护（订阅 session append 事件流实时校验，断裂即标记 `dsh/contract-violation` 事件，策略可配 告警/拦截）——DSH 插件形态
+- [ ] Phase 3：与 dsh-turn-guard / dsh-retrace 时间线联动
+
+## 许可
+
+MIT © OfferKuai Team

package/bin/dsh-log-contract.mjs

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+/**
+ * dsh-log-contract · bin/dsh-log-contract.mjs
+ *
+ * CLI：日志契约守护（DSH session log contract guard）。
+ *
+ * 子命令：
+ *   check <session-log>           离线体检：解码 + 全契约校验 + 违规报告
+ *                                  （支持 .jsonl / .jsonl.zstd）
+ *   prewrite <edit-file> --log <session-log>
+ *                                 写前校验：edit 文件描述一次"拟写入"，
+ *                                 在落盘前用三层契约判定 通过/拒绝
+ *   contracts                     列出内置契约规则目录
+ */
+import fs from 'node:fs';
+import { loadSessionLog, validateSessionLog, createPreWriter, CONTRACT_RULES, ruleById } from '../lib/index.js';
+
+const USAGE = `dsh-log-contract —— 日志契约守护（DSH session log contract guard）
+
+用法：
+  dsh-log-contract check <session-log> [--json] [--max-details N]
+      离线体检。session-log 支持 .jsonl 与 .jsonl.zstd。
+      --json          输出机器可读 JSON 报告
+      --max-details N 每条违规最多列 N 个缺失 seq（默认 8，--json 忽略）
+
+  dsh-log-contract prewrite <edit-file> --log <session-log> [--json]
+      写前校验。edit-file 为 JSON，两种形状：
+        { "append": { ...事件... } }            拟追加一个事件到日志尾部
+        { "edit": [ ...事件列表... ] }          帧级手术后的完整事件列表
+      判定通过/拒绝并列出全部违规（三层契约：持久化/引擎/插件）。
+
+  dsh-log-contract contracts
+      列出内置契约规则目录（含官方源码出处）。
+
+  dsh-log-contract --version / --help
+`;
+
+function fail(message, code = 1) {
+  process.stderr.write(`${message}\n`);
+  process.exit(code);
+}
+
+function printViolations(violations, maxDetails = 8) {
+  if (violations.length === 0) {
+    process.stdout.write('  ✔ 无违规\n');
+    return;
+  }
+  for (const v of violations) {
+    const loc = [v.seq !== null ? `seq ${v.seq}` : null, v.lineNo !== null ? `line ${v.lineNo}` : null]
+      .filter(Boolean).join(' / ');
+    const head = `  [${v.severity}] ${v.id} ${loc ? `@ ${loc}` : ''}${v.eventType ? ` (${v.eventType})` : ''}`;
+    process.stdout.write(`${head}\n      ${v.message}\n`);
+    if (Array.isArray(v.missingSeqs) && v.missingSeqs.length > maxDetails) {
+      process.stdout.write(`      …另有 ${v.missingSeqs.length - maxDetails} 个缺失 seq 未列出\n`);
+    }
+  }
+}
+
+function cmdCheck(args) {
+  const json = args.includes('--json');
+  const maxDetailsIdx = args.indexOf('--max-details');
+  const maxDetails = maxDetailsIdx >= 0 && args[maxDetailsIdx + 1] ? Number(args[maxDetailsIdx + 1]) : 8;
+  const file = args.find((a) => !a.startsWith('-'));
+  if (!file) fail(USAGE);
+
+  let log;
+  try {
+    log = loadSessionLog(file);
+  } catch (err) {
+    fail(`读取失败：${err.message}`);
+  }
+  const result = validateSessionLog(log);
+  const { summary, violations, ok } = result;
+
+  if (json) {
+    process.stdout.write(JSON.stringify({ file, ok, summary, violations }, null, 2) + '\n');
+    process.exit(ok ? 0 : 1);
+  }
+
+  process.stdout.write(`\n📋 dsh-log-contract check —— ${file}\n`);
+  process.stdout.write(`   事件 ${summary.events} ｜ surface 节点 ${summary.surfaceNodes} ｜ replace 代数 ${summary.replaceGeneration} ｜ 帧 ${summary.frames}（${(summary.compressedBytes / 1024).toFixed(1)}KiB → ${(summary.plaintextBytes / 1024).toFixed(1)}KiB）\n`);
+  process.stdout.write(`   违规 ${summary.total}（error ${summary.bySeverity.error} / warning ${summary.bySeverity.warning}）\n\n`);
+  printViolations(violations, maxDetails);
+  process.stdout.write(`\n${ok ? '✅ 通过：官方 foldSurface 可重放，三层契约绿' : '❌ 未通过：见上方违规明细（error 级 = 会话不可读/不可写）'}\n\n`);
+  process.exit(ok ? 0 : 1);
+}
+
+function cmdPrewrite(args) {
+  const json = args.includes('--json');
+  const logIdx = args.indexOf('--log');
+  const file = args.find((a) => !a.startsWith('-') && a !== 'prewrite');
+  if (!file || logIdx < 0 || !args[logIdx + 1]) fail(USAGE);
+
+  let plan;
+  try {
+    plan = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (err) {
+    fail(`edit 文件读取/解析失败：${err.message}`);
+  }
+  if (typeof plan !== 'object' || plan === null) fail('edit 文件必须是 JSON 对象');
+
+  let log;
+  try {
+    log = loadSessionLog(args[logIdx + 1]);
+  } catch (err) {
+    fail(`会话日志读取失败：${err.message}`);
+  }
+  const baseline = validateSessionLog(log);
+  if (!baseline.ok) {
+    // 基线已坏：写前校验无法在坏基线上给出可信结论
+    fail(`基线会话已有 ${baseline.summary.bySeverity.error} 个 error 级违规，请先修复基线再校验写入（安全修复协议第 2 步：改前基线必须绿）`);
+  }
+
+  const prewriter = createPreWriter({ events: log.events.map((e) => e.event) });
+  let result;
+  if (Object.hasOwn(plan, 'append')) {
+    result = prewriter.validateAppend(plan.append);
+    result.op = 'append';
+  } else if (Object.hasOwn(plan, 'edit')) {
+    if (!Array.isArray(plan.edit)) fail('edit 必须为事件数组');
+    result = prewriter.validateEdit(plan.edit);
+    result.op = 'edit';
+  } else {
+    fail('edit 文件必须含 "append" 或 "edit" 键');
+  }
+
+  if (json) {
+    process.stdout.write(JSON.stringify({ file, op: result.op, ok: result.ok, bySeverity: result.bySeverity, violations: result.violations }, null, 2) + '\n');
+    process.exit(result.ok ? 0 : 1);
+  }
+
+  process.stdout.write(`\n✍️  dsh-log-contract prewrite —— ${file}（op: ${result.op}，nextSeq: ${prewriter.nextSeq}）\n\n`);
+  if (result.ok) {
+    process.stdout.write('  ✅ 写入安全：三层契约全绿（持久化 foldSurface 可重放 / 引擎层无崩溃风险 / 插件 marker 语义自洽）\n');
+    process.stdout.write(`     写入后 surface 节点 ${result.stateAfter.surfaceNodes} 个，nextSeq ${result.stateAfter.nextSeq}\n\n`);
+    process.exit(0);
+  }
+  process.stdout.write('  ❌ 写入会被拒：\n');
+  printViolations(result.violations);
+  process.stdout.write('\n');
+  process.exit(1);
+}
+
+function cmdContracts() {
+  process.stdout.write('dsh-log-contract 契约规则目录（spec：59 条审计发现 + 官方源码逐行核对）\n\n');
+  for (const r of CONTRACT_RULES) {
+    process.stdout.write(`  ${r.id}  [${r.severity}/${r.layer}] ${r.title}\n      ${r.description}\n      出处: ${r.source}\n\n`);
+  }
+}
+
+const args = process.argv.slice(2);
+const cmd = args[0];
+if (!cmd || cmd === '--help' || cmd === '-h' || cmd === 'help') {
+  process.stdout.write(USAGE);
+  process.exit(0);
+}
+if (cmd === '--version' || cmd === '-v') {
+  const pkg = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+  process.stdout.write(`dsh-log-contract ${pkg.version}\n`);
+  process.exit(0);
+}
+if (cmd === 'check') cmdCheck(args.slice(1));
+else if (cmd === 'prewrite') cmdPrewrite(args.slice(1));
+else if (cmd === 'contracts') cmdContracts();
+else fail(`未知子命令 "${cmd}"\n\n${USAGE}`);

package/docs/CONTRACTS.md

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