dsh-log-contract 0.3.15 → 0.3.17

package/README.md

@@ -8,7 +8,7 @@ offline health check + pre-write validation. The business layer's **doctor**.
 [![npm version](https://img.shields.io/npm/v/dsh-log-contract)](https://www.npmjs.com/package/dsh-log-contract)
 [![npm downloads](https://img.shields.io/npm/dm/dsh-log-contract)](https://www.npmjs.com/package/dsh-log-contract)
 [![License: MIT](https://img.shields.io/npm/l/dsh-log-contract)](https://github.com/yamingmou/dsh-log-contract/blob/main/LICENSE)
-[![DSH plugin](https://img.shields.io/badge/DSH-plugin-4A90D9)](https://github.com/topics/dsh-plugin)
+[![DSH ecosystem](https://img.shields.io/badge/DSH-ecosystem-4A90D9)](https://github.com/topics/dsh-plugin)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)](https://github.com/yamingmou/dsh-log-contract/pulls)
 
 **English** · [简体中文](./README.zh.md)
@@ -38,31 +38,33 @@ plugin marker semantics).
 
 > **dsh-log-contract is the core capability component of [dsh-retrace](https://github.com/yamingmou/dsh-retrace)** (the business layer's "doctor" module): it **checks and repairs** session logs so every recall/edit/rollback lands on a legal log — pre-write validation (`prewrite`) rejects error-level violations **before** anything is written.
 >
-> **About `/compact` (stated honestly)**: what this tool guarantees is that **new writes** stop creating token-meter pairing debt — since two-segment atomic pairs (marker + paired segment) landed, new markers pass T1 by construction. **Legacy** (single-segment) markers are still **known design debt**: pre-write validation downgrades their T1 violation to a warning (`isKnownMarkerCandidate` in `lib/prewrite.js`, which applies to **historical markers only**), so such sessions need **one check + cleanup before compaction** (`check` to locate → `fix --remove-markers`; the plugin side calls this "the doctor"). Otherwise the T1 self-check blocks `/compact`.
+> **About `/compact` (stated honestly)**: what this tool guarantees is that **new writes** stop creating token-meter pairing debt — since two-segment atomic pairs (marker + paired segment) landed, new markers pass T1 by construction. **Legacy** (single-segment) markers are still **known design debt**: pre-write validation downgrades their T1 violation to a warning (`legacyMarkerKindOf` in `lib/prewrite.js`, which applies to **historical markers only**), so such sessions need **one check + cleanup before compaction** (`check` to locate → `fix --remove-markers`; the plugin side calls this "the doctor"). Otherwise the T1 self-check blocks `/compact`.
 
 | Layer | What it is | Components |
 |---|---|---|
 | **Agent business layer (production-grade)** | Framework-agnostic core: session hygiene / retraceability / auditability / recoverability | Four modules: governance / retrospect / archaeology / **doctor** |
 | **dsh-retrace** | The business layer's DeepSeek Harness implementation | recall/edit/version/rollback/watchdog |
-| **dsh-log-contract** | dsh-retrace's core component = the business layer's **doctor** (check & repair) | check / prewrite / fix / extract / audit |
+| **dsh-log-contract** | dsh-retrace's core component = the business layer's **doctor** (check & repair) | check / prewrite / fix / extract / audit-report |
 
 **Meaning**: dsh-log-contract is published standalone (for direct use or
 re-implementation), but it is first the "check & repair" capability of dsh-retrace —
 together they form the **Agent business layer (production-grade guarantees)** on
-DSH (see the [dsh-retrace roadmap](https://github.com/yamingmou/dsh-retrace/blob/main/docs/ROADMAP.md)).
+DSH (see the [dsh-retrace repository](https://github.com/yamingmou/dsh-retrace)).
 
 ---
 
 ## Why it exists
 
-**#3632 "one log, two consumers, two verdicts"**: one log is consumed by both
+**"one log, two consumers, two verdicts"**: one log is consumed by both
 humans and automated programs. Humans tolerate format drift; programs depend on
 strict contracts. Once the format drifts, humans see nothing wrong while programs
 crash or misreport.
 
-**Real incidents shaped every rule here** — see the [Incident log](#-incident-log)
-below. Each incident is a regression fixture: a corrupted session that this tool
-must flag, and a fixed session that it must pass.
+**Real incidents shaped most of the rules here** — see the [Incident log](#-incident-log)
+below. The incident-derived cases are pinned by regression tests: a corrupt log shape
+this tool must flag, and the repaired shape it must pass. The remaining rules come from
+line-by-line verification against the official Host source (each rule carries its
+`source`).
 
 ---
 
@@ -86,21 +88,21 @@ must flag, and a fixed session that it must pass.
 
 ## ⚡ Incident log — why "production-grade" is not a slogan
 
-Every rule below was born from a **real incident** in our workspace. These are the
-sessions that made us build this tool. Dates and shapes are real; session ids are
-omitted for privacy.
+Each entry below is a **real incident** from production sessions — the cases that
+made us build this tool. Dates and shapes are real; session ids and file names are
+omitted.
 
 | # | Date | What happened | The rule / fix it produced |
 |---|---|---|---|
 | 1 | 2026-08-25 | A "restore hidden content" repair wrote a replace marker with **emptied `sourceEventSeqs`** → the session refused to load (`SessionPersistenceCorruptionError`); a second attempt changed the marker to **append** → the client engine crashed. Both were **violating writes that nothing caught**. | **S5** (sourceEventSeqs must cover shadowed nodes), **M1** (turn-null assistant/message can only be replace), pre-write validation |
 | 2 | 2026-08-27~28 | Interrupted/restarted turns replayed with a **stale in-memory cursor**, re-appending old seqs to the file tail (tail regression, duplicate batches); two writers interleaved → **file-physical order non-monotonic** (`734056 → 733539 → 735470`). Sessions failed to load with `seq gap`. | **S9** (physical-order monotonic), fix `--tail-renumber` |
 | 3 | 2026-08-27~28 | **Fork-boundary orphan splice**: the fork's "remove parent's pending prompt" splice assumed the parent's inbox; the child's seed-relative replay has an empty inbox → `resume failed: invalid persisted inbox splice`. | **I1** (inbox seed-relative replay), fix `--neutralize-orphan` |
-| 4 | 2026-08-28 | An oversized session (**1,052,557 tokens** vs the 1M window) could neither continue nor `/compact`; the trim budget estimator underpriced CJK by ~3.7×. | T1 (token-meter pairing) for compactability, `fix --trim` budget guidance |
+| 4 | 2026-08-28 | An oversized session (**1,052,557 tokens** vs the 1M window) could neither continue nor `/compact`; the trim budget estimator underpriced CJK by ~3.7×. | T1 (token-meter pairing) for compactability, `fix --trim-budget` guidance |
 | 5 | 2026-08-29 | **W1/W2 wire violations**: markers shadowed an assistant with tool_calls but left the tool results dangling → strict endpoints (`INVALID_REQUEST`) reject the session's request stream. | **W1 / W2** (wire message flow) |
 | 6 | 2026-08-30 | A single **turn-null marker** made the token-meter listener throw on **every** appended event (`consumedEvents` never advanced → full-prefix re-fold per event) → **30s / 10,008 log lines**, host event loop crushed, all sessions locked. Same session also had a **cross-step sourceEventSeqs** (steps 7/8/9 mixed in one assistant message) — offline checks were green, the live meter crashed. | **T1** (turn/step pairing), **T2** (cross-step source refs), `fix --neutralize`, `fix --clip-crossstep` |
 
-> **Takeaway**: every rule in this tool is a scar from a real session — validated
-> against the actual corrupted-session fixtures, not synthetic theory. That is what
+> **Takeaway**: these rules are not synthetic theory — each one is pinned by a
+> regression test that reproduces the corrupt shape it guards against. That is what
 > "production-grade" means here.
 
 ---
@@ -111,7 +113,7 @@ omitted for privacy.
 
 | Item | Baseline | Note |
 |---|---|---|
-| Host package | `@deepseek-ai/dsh-session@0.1.5-rc.1` | version used on the dev box and in CI; the four `prepublishOnly` steps are green on it |
+| Host package | `@deepseek-ai/dsh-session@0.1.5-rc.1` | the version this rule set is developed and CI-tested against (CI runs `pnpm check` + `pnpm test`; the four `prepublishOnly` steps are green locally on it) |
 | Session format | **v3** (`SESSION_FORMAT_VERSION = 3`) | v3 uses the runtime vocabulary + official `foldSurface` final check |
 | Declared range | `peerDependencies: ^0.1.0-rc.7 || ^0.1.5-rc.1` | installable — a declared range is **not** a per-version verification |
 | Known formats | 0 / 1 / 2 / 3 | 0–2 are supported by this package's **vendored** vocabulary + local equivalent fold (`legacyFoldSurface`), independent of the host |
@@ -145,8 +147,8 @@ pnpm dlx dsh-log-contract --help
 > repair primitives) comes with the plugin automatically. This package is published
 > standalone for direct use or re-implementation.
 >
-> **Downloaded the repo as a ZIP?** `cd dsh-log-contract && npm install && npm run build`,
-> then `node bin/dsh-log-contract.mjs check <session-log>` — no global install needed.
+> **Downloaded the repo as a ZIP?** `cd dsh-log-contract && npm install`, then
+> `node bin/dsh-log-contract.mjs check <session-log>` — no build step and no global install needed.
 
 Dependencies: Node ≥ 22 (`node:zlib` has built-in zstd), `@deepseek-ai/dsh-session`
 (peer; validation/decode reuse the official implementation, so it stays in sync
@@ -176,7 +178,8 @@ Sample output (the CLI reports in Chinese — it is the tool's UI language):
 ❌ 未通过：见上方违规明细（error 级 = 会话不可读/不可写）
 ```
 
-Exit code: 0 = pass (no error-level violations); 1 = error-level violations exist.
+Exit code: 0 = pass (no error-level violations); 1 = error-level violations exist;
+3 = not assessable on this host; 4 = the migration pre-check is blocked (see the upgrade notes below).
 
 `check` adds **W1/W2 wire-level checks** since 0.2.0: expand the model request
 stream in surface order and catch "dangling tool messages" (a tool result with no
@@ -246,7 +249,7 @@ audit asset. Read-only archaeology:
 
 ```sh
 # Export tool outputs matching a command regex (original text preserved)
-dsh-log-contract extract <session-log> --pattern "seed-scale" --min-size 50 --out ./found
+dsh-log-contract extract <session-log> --pattern "build-report" --min-size 50 --out ./found
 
 # Archaeology audit report: call count / pairing rate / orphans / command distribution
 dsh-log-contract audit-report <session-log>
@@ -299,17 +302,21 @@ pnpm check && pnpm test    # syntax check + contract-doc drift gate + all unit t
 > Local maintainer tooling is not part of the public repository, so `pnpm check` and `pnpm test`
 > work from a clean clone.
 
-Known truth table (updated 2026-08-31 — after 0.3.5 added I1, `spliced-orphan`
-now FAILs; the old PASS row was stale):
-- `<session>-corrupt` / `<session>-seqgap` / `<session>-rewritten-230542` → FAIL (seq gaps)
-- `<session>-spliced-orphan` → **FAIL (0.3.5+)** (T1/I1: invalid inbox splice + turn-null)
-- `<session>-pre-markerfix-20260825` → FAIL (pre-fix sample: turn-null markers remain)
-- `<session>-pre-cleanstate-20260831` → PASS (a multi-thousand-span replace marker is data-legal;
-  official foldSurface replays cleanly — see the plugin ledger)
-The truth table tracks rule evolution (0.3.5's I1 flipped spliced-orphan PASS→FAIL);
-"repaired sessions PASS" must be verified on rebuilt samples — `pre-` backups are
-usually pre-fix bad samples. See the boundary note in
-[docs/CONTRACTS.md](docs/CONTRACTS.md)).
+Verdict by **log shape** — what the tool must say about each defect class, not about
+any particular file:
+
+| Log shape | Verdict | Rules that fire |
+|---|---|---|
+| seq gap, or non-monotonic file-physical order | FAIL | S8 / C1 / T1 / E2 (plus S9 when seq goes backwards) |
+| a rewrite that introduces a gap | FAIL | S8 / C1 / T1 / E2 / I1 |
+| invalid inbox splice + turn-null marker | FAIL | T1 / I1 |
+| pre-fix shape: legacy turn-null markers still present | FAIL | T1 |
+| a multi-thousand-span replace marker with full coverage | PASS | error 0 — data-legal, official `foldSurface` replays cleanly |
+
+Rule evolution moves rows: 0.3.5 added I1, which flipped the "invalid inbox splice"
+shape from PASS to FAIL. And "a repaired session passes" holds only for the repaired
+artifact — the pre-repair form of the same session is normally still a FAIL. See the
+boundary note in [docs/CONTRACTS.md](docs/CONTRACTS.md).
 
 ---
 
@@ -323,6 +330,9 @@ usually pre-fix bad samples. See the boundary note in
   fold-position fix → 0.3.2 `tailSeq` → 0.3.3 `fix --neutralize` (in-place
   turn-null neutralization) → 0.3.4 `fix --clip-crossstep` (cross-step clipping) →
   0.3.5 **T2/S9/I1 rules** (cross-step source refs / physical order / inbox replay)
+- [x] **0.3.6 → 0.3.15**: per-version rule routing for v0–v3 (T3/T4/T5, L3–L5, E8/E9/E10),
+  exit codes `3`/`4` for the host-capability and migration gates, and a version-support
+  report that says what was *not* verified (see [CHANGELOG.md](CHANGELOG.md))
 - [ ] Phase 2: runtime guard (subscribe to the session append stream, validate live,
   mark violations as `dsh/contract-violation`, policy configurable alert/block) —
   DSH plugin form
@@ -334,11 +344,13 @@ MIT © OfferKuai Team
 
 ---
 
-## ⚠️ Upgrading to 0.3.15 — behaviour changes you must know (0.3.12 → 0.3.15)
+## ⚠️ Upgrading to 0.3.17 — behaviour changes you must know (0.3.12 → 0.3.17)
 
-> **0.3.15 itself changes no behaviour.** It removes two internal identifiers that had leaked into the
-> 0.3.14 published artifact (a README naming note and one source comment) and widens the pre-publish
-> leak gate vocabulary. Everything below applies unchanged when going from 0.3.12 to 0.3.15.
+> **0.3.17 changes no behaviour.** It rewrites comments, test titles, a few diagnostic strings and the
+> README so that they describe the product and its contract only. Every verdict, exit code and `--json`
+> field is unchanged from 0.3.15, so everything below applies unchanged when going from 0.3.12 to 0.3.17.
+>
+> 0.3.15 was a documentation-only release as well.
 
 **1. New exit codes `3` / `4` — a defect fix that is also a breaking change.**
 - `3` = **not assessable on this host**: the file's `header.version` is higher than the host supports
@@ -356,7 +368,7 @@ MIT © OfferKuai Team
 
 | value | meaning |
 |---|---|
-| `full` | file is already the host's target format (no migration) — coverage is complete（已是当前格式、**无需迁移**）（已是当前格式、**无需迁移**） |
+| `full` | file is already the host's target format (no migration) — coverage is complete |
 | `partial` | file needs migration ⇒ the migration pre-check covers **2 rules only; 6 classes are uncovered** (≠ pass; see `coverage.uncovered`) |
 | `none` | **not assessable on this host** — no "usable / upgradable" claim is certified |
 

package/README.zh.md

@@ -7,7 +7,7 @@
 [![npm version](https://img.shields.io/npm/v/dsh-log-contract)](https://www.npmjs.com/package/dsh-log-contract)
 [![npm downloads](https://img.shields.io/npm/dm/dsh-log-contract)](https://www.npmjs.com/package/dsh-log-contract)
 [![License: MIT](https://img.shields.io/npm/l/dsh-log-contract)](https://github.com/yamingmou/dsh-log-contract/blob/main/LICENSE)
-[![DSH plugin](https://img.shields.io/badge/DSH-plugin-4A90D9)](https://github.com/topics/dsh-plugin)
+[![DSH ecosystem](https://img.shields.io/badge/DSH-ecosystem-4A90D9)](https://github.com/topics/dsh-plugin)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)](https://github.com/yamingmou/dsh-log-contract/pulls)
 
 [English](./README.md) · **简体中文**
@@ -32,25 +32,25 @@
 
 > **dsh-log-contract 是 [dsh-retrace](https://github.com/yamingmou/dsh-retrace) 的核心能力组件**（业务层的「医生」模块）：负责会话日志的**体检与修复**——让每一次撤回/编辑/回退都落在合法日志上，写前校验（`prewrite`）会把 error 级违约**拦在落盘之前**。
 >
-> **关于 `/compact`（如实表述）**：本工具保证的是**新写入**不再制造 token-meter 配对债——自两段原子成对（marker + 配对段）起，新 marker 天然通过 T1。**历史**（单段）marker 仍属**已知设计债**：写前校验对它的 T1 违规降级为 warning（`lib/prewrite.js` 的 `isKnownMarkerCandidate` 白名单，**只适用于历史 marker**），因此这类会话**压缩（`/compact`）前需要先跑一次体检 + 清理**（`check` 定位 → `fix --remove-markers`；插件侧即「医生」），否则 T1 自检会拦住压缩。
+> **关于 `/compact`（如实表述）**：本工具保证的是**新写入**不再制造 token-meter 配对债——自两段原子成对（marker + 配对段）起，新 marker 天然通过 T1。**历史**（单段）marker 仍属**已知设计债**：写前校验对它的 T1 违规降级为 warning（`lib/prewrite.js` 的 `legacyMarkerKindOf` 白名单，**只适用于历史 marker**），因此这类会话**压缩（`/compact`）前需要先跑一次体检 + 清理**（`check` 定位 → `fix --remove-markers`；插件侧即「医生」），否则 T1 自检会拦住压缩。
 
 | 层 | 是什么 | 组件 |
 |---|---|---|
-| **Agent 业务层（生产级保证）** | 抽象核心能力：会话卫生 / 可回溯 / 可审计 / 可恢复，与平台无关 | 四模块：治理 / 看 / 考古 / **医生** |
+| **Agent 业务层（生产级保证）** | 抽象核心能力：会话卫生 / 可回溯 / 可审计 / 可恢复，与平台无关 | 四模块：治理（governance）/ 回溯（retrospect）/ 考古（archaeology）/ **医生（doctor）** |
 | **dsh-retrace** | 业务层在 DeepSeek Harness 上的实现（生产级业务插件） | 撤回/编辑/版本/回退/看门狗 |
-| **dsh-log-contract** | dsh-retrace 的核心能力组件 = 业务层的**医生**（体检/修复） | check / prewrite / fix / extract / audit |
+| **dsh-log-contract** | dsh-retrace 的核心能力组件 = 业务层的**医生**（体检/修复） | check / prewrite / fix / extract / audit-report |
 
 **含义**：dsh-log-contract 独立发布（供单独使用或二次开发），但它首先是
 dsh-retrace 的「日志体检与修复」能力——与 dsh-retrace 一起构成
-**Agent 业务层（生产级保证）** 在 DSH 上的落地（详见 [dsh-retrace 路线图](https://github.com/yamingmou/dsh-retrace/blob/main/docs/ROADMAP.md)）。
+**Agent 业务层（生产级保证）** 在 DSH 上的落地（详见 [dsh-retrace 仓库](https://github.com/yamingmou/dsh-retrace)）。
 
 ---
 
 ## 为什么需要它
 
-**#3632「one log, two consumers, two verdicts」**：一条日志同时被人类与自动化程序消费，人眼容忍格式微调，程序解析依赖严格契约；格式一旦漂移，人看不出问题，程序直接崩溃或误报。
+**「one log, two consumers, two verdicts」**：一条日志同时被人类与自动化程序消费，人眼容忍格式微调，程序解析依赖严格契约；格式一旦漂移，人看不出问题，程序直接崩溃或误报。
 
-**这里每一条规则都来自真实事故**——见下方 [⚡ 事故记录](#-事故记录)。每起事故都是一个回归夹具：损坏的会话本工具必须报出，修复后的会话必须通过。
+**这里大多数规则都来自真实事故**——见下方 [⚡ 事故记录](#-事故记录)。事故派生的用例都有回归测试钉住：损坏的日志形态本工具必须报出，修复后的形态必须通过。其余规则来自对官方宿主源码的逐行核对（每条规则都带 `source`）。
 
 ---
 
@@ -71,18 +71,18 @@ dsh-retrace 的「日志体检与修复」能力——与 dsh-retrace 一起构
 
 ## ⚡ 事故记录 ——「生产级保证」不是口号
 
-下面的每一条规则都来自我们工作区的一起**真实事故**。日期与形态真实，会话 id 为隐私省略。
+下面每一条都是一起来自生产会话的**真实事故**——正是这些案例促成了本工具。日期与形态真实，会话 id 与文件名省略。
 
 | # | 日期 | 发生了什么 | 产出的规则/修复 |
 |---|---|---|---|
 | 1 | 2026-08-25 | 一次「恢复被隐藏内容」的修复写了**清空 `sourceEventSeqs`** 的 replace marker → 会话加载被拒（`SessionPersistenceCorruptionError`）；第二次尝试把 marker 改成 **append** → 客户端引擎崩溃。两次都是**违约写入没被拦**。 | **S5**（sourceEventSeqs 必须覆盖被替换节点）、**M1**（turn-null 的 assistant/message 只能 replace）、写前校验 |
 | 2 | 2026-08-27~28 | 中断/暂停的轮次恢复时按**过期内存光标**重放，把旧 seq 追加到文件尾（尾部回归、重复批次）；两个写入者交织 → **文件物理序非单调**（`734056 → 733539 → 735470`）。会话 `seq gap` 加载失败。 | **S9**（物理序单调）、fix `--tail-renumber` |
 | 3 | 2026-08-27~28 | **fork 边界孤儿 spliced**：fork 的「移除父待处理提示词」splice 假设父会话 inbox；子会话 seed 相对重放里 inbox 为空 → `resume failed: invalid persisted inbox splice`。 | **I1**（inbox seed 相对重放）、fix `--neutralize-orphan` |
-| 4 | 2026-08-28 | 超限会话（**1,052,557 tokens** vs 1M 窗口）既无法继续也无法 `/compact`；裁剪预算估算对中文低估 ~3.7×。 | T1（token-meter 配对，保障可压缩）、`fix --trim` 预算指引 |
+| 4 | 2026-08-28 | 超限会话（**1,052,557 tokens** vs 1M 窗口）既无法继续也无法 `/compact`；裁剪预算估算对中文低估 ~3.7×。 | T1（token-meter 配对，保障可压缩）、`fix --trim-budget` 预算指引 |
 | 5 | 2026-08-29 | **W1/W2 wire 违规**：marker 遮蔽了带 tool_calls 的 assistant 但漏盖 tool 结果 → 悬空 tool，严格端点 `INVALID_REQUEST` 拒绝请求流。 | **W1 / W2**（wire 消息流） |
 | 6 | 2026-08-30 | 单个 **turn-null marker** 让 token-meter 监听器在**每条**追加事件上抛错（`consumedEvents` 不前进 → 每事件全前缀重折）→ **30 秒 / 10,008 行日志**、host 事件循环被压垮、全部会话锁定。同会话还有**跨 step sourceEventSeqs**（step 7/8/9 混进一条 assistant 消息）——离线 check 全绿、实机 meter 崩溃。 | **T1**（turn/step 配对）、**T2**（跨 step 源引用）、`fix --neutralize`、`fix --clip-crossstep` |
 
-> **结论**：这个工具的每条规则都是一次真实会话留下的疤——用真实的损坏会话夹具验证过，不是合成理论。这就是这里「生产级」的含义。
+> **结论**：这些规则不是合成理论——每一条都有回归测试复现它守护的那种损坏形态。这就是这里「生产级」的含义。
 
 ---
 
@@ -92,7 +92,7 @@ dsh-retrace 的「日志体检与修复」能力——与 dsh-retrace 一起构
 
 | 项 | 基线 | 说明 |
 |---|---|---|
-| 宿主包 | `@deepseek-ai/dsh-session@0.1.5-rc.1` | 开发机与 CI 实装版本；`prepublishOnly` 四步在此版本上全绿 |
+| 宿主包 | `@deepseek-ai/dsh-session@0.1.5-rc.1` | 本规则集开发与 CI 验证所用的版本（CI 跑 `pnpm check` + `pnpm test`；`prepublishOnly` 四步在本机该版本上全绿） |
 | 会话格式 | **v3**（`SESSION_FORMAT_VERSION = 3`） | v3 走运行时词表 + 官方 `foldSurface` 终验 |
 | 声明范围 | `peerDependencies: ^0.1.0-rc.7 || ^0.1.5-rc.1` | 允许安装；**范围内不等于逐个验证过** |
 | 已知格式 | 0 / 1 / 2 / 3 | 0–2 由本包**自带** vendored 词表 + 本地等价折叠（`legacyFoldSurface`）支持，与宿主版本无关 |
@@ -126,8 +126,8 @@ pnpm dlx dsh-log-contract --help
 > 声明为依赖，装 retrace 时自动带好契约守护（体检/写前校验/修复原语全部随插件生效）。
 > 本包独立发布，供愿意单独使用或二次开发的用户直接引入。
 >
-> **从 GitHub 下载了 ZIP？** 解压后 `cd dsh-log-contract && npm install && npm run build`，
-> 然后 `node bin/dsh-log-contract.mjs check <session-log>` 即可使用（无需全局安装）。
+> **从 GitHub 下载了 ZIP？** 解压后 `cd dsh-log-contract && npm install`，
+> 然后 `node bin/dsh-log-contract.mjs check <session-log>` 即可使用（无需构建、无需全局安装）。
 
 依赖：Node ≥ 22（`node:zlib` 内置 zstd）、`@deepseek-ai/dsh-session`（peer，校验/解码复用官方实现，保证与 Harness 读路径同源）。
 
@@ -216,7 +216,7 @@ DSH 会话日志持久化了每次工具调用的完整输入输出——数据
 
 ```sh
 # 按命令正则导出工具输出（保留原始文本）
-dsh-log-contract extract <session-log> --pattern "seed-scale" --min-size 50 --out ./found
+dsh-log-contract extract <session-log> --pattern "build-report" --min-size 50 --out ./found
 
 # 考古审计报告：调用数 / 配对率 / 孤儿数 / 命令分布
 dsh-log-contract audit-report <session-log>
@@ -265,19 +265,18 @@ pnpm check && pnpm test    # 语法检查 + 契约文档漂移闸 + 全部单测
 > **发布包范围**：只含运行时代码与文档。维护者本地工具不在公开仓内，
 > 因此 `pnpm check` / `pnpm test` 在干净的克隆里即可通过。
 
-已知真值表（2026-08-31 实测更新——0.3.5 加 I1 后，`spliced-orphan` 已可报错，旧表 PASS 过时）：
+按**日志形态**给出的判定——本工具对每类缺陷该说什么，而不是对某个具体文件：
 
-| 化石 | 判定 | 违规 |
+| 日志形态 | 判定 | 触发的规则 |
 |---|---|---|
-| `<session>-corrupt` | FAIL | S8/C1/T1/E2（seq 缺口 → 加载被拒） |
-| `<session>-seqgap` / `<session>-recorrupt` | FAIL | S8/C1/T1/E2/S9（seq 缺口/倒退） |
-| `<session>-rewritten-230542` | FAIL | S8/C1/T1/E2/I1（重写引入缺口） |
-| `<session>-spliced-orphan` | **FAIL（0.3.5+）** | T1/I1（inbox splice 无效 + turn-null）——旧表 PASS 已过时 |
-| `<session>-pre-markerfix-20260825` | FAIL | T1×5（修复前样本：turn-null marker 残留，非「修复后」） |
-| `<session>-pre-cleanstate-20260831` | **PASS** | error 0（数千跨度的 replace marker 数据合规，官方 foldSurface 重放通过） |
+| seq 缺口，或文件物理序非单调 | FAIL | S8 / C1 / T1 / E2（seq 倒退时另加 S9） |
+| 重写引入缺口 | FAIL | S8 / C1 / T1 / E2 / I1 |
+| inbox splice 无效 + turn-null marker | FAIL | T1 / I1 |
+| 修复前形态：遗留 turn-null marker | FAIL | T1 |
+| 完整覆盖的数千跨度 replace marker | PASS | error 0——数据合规，官方 `foldSurface` 重放通过 |
 
-> 说明：真值表随规则演进更新（0.3.5 新增 I1 后 spliced-orphan 从 PASS 变 FAIL）；
-> 「修复后会话 PASS」需用重建/修复后的样本验证，pre- 前缀备份多为修复前坏样本。
+> 规则演进会移动表中行：0.3.5 新增 I1 后，「inbox splice 无效」这一形态从 PASS 变 FAIL。
+> 而「修复后会话通过」只对被修复后的产物成立——同一会话修复前的形态通常仍是 FAIL。
 
 ---
 
@@ -286,6 +285,7 @@ pnpm check && pnpm test    # 语法检查 + 契约文档漂移闸 + 全部单测
 - [x] **Phase 1（0.1.0）**：CLI 离线体检 + 写前校验 + 契约目录
 - [x] **Phase 1.5（0.2.0）**：`fix` 子命令（严格 seq 扫描 + W1/W2 wire 检查 + 移除 marker 重编号 + 官方帧格式重建）；CI 集成（`dsh-log-contract check` 作为 Harness 会话目录的定时守护）
 - [x] **0.3.x（2026-08-30 事故固化）**：T1 token-meter 配对 → 0.3.1 W1/W2 折叠位置修复 → 0.3.2 `tailSeq` → 0.3.3 `fix --neutralize`（turn-null marker 原地中和）→ 0.3.4 `fix --clip-crossstep`（跨 step 引用裁剪）→ 0.3.5 **T2/S9/I1 规则**（跨 step 源引用 / 物理序单调 / inbox 重放）
+- [x] **0.3.6 → 0.3.15**：按被检文件版本择路的 v0–v3 规则（T3/T4/T5、L3–L5、E8/E9/E10）、宿主能力与迁移预检的退出码 `3`/`4`，以及如实报告"哪些版本**未**验证"的版本支持说明（详见 [CHANGELOG.md](CHANGELOG.md)）
 - [ ] Phase 2：运行时守护（订阅 session append 事件流实时校验，断裂即标记 `dsh/contract-violation` 事件，策略可配 告警/拦截）——DSH 插件形态
 - [ ] Phase 3：与 dsh-turn-guard / dsh-retrace 时间线联动
 
@@ -295,11 +295,13 @@ MIT © OfferKuai Team
 
 ---
 
-## ⚠️ 升级到 0.3.15 —— 必须知道的行为变更（0.3.12 → 0.3.15）
+## ⚠️ 升级到 0.3.17 —— 必须知道的行为变更（0.3.12 → 0.3.17）
 
-> **0.3.15 本身不含行为变更。** 它只做两件事：清掉 0.3.14 已发布产物里的两处内部标识
-> （README 的定名说明 + 一处源码注释），并补齐发布前泄漏闸门的词表。
-> 从 0.3.12 升到 0.3.15 时，下面各条与原来完全一致。
+> **0.3.17 不含行为变更。** 它只重写了注释、测试标题、少量诊断文案与 README，让它们
+> 只描述产品与契约本身。所有判定结果、退出码与 `--json` 字段与 0.3.15 完全一致，
+> 因此从 0.3.12 升到 0.3.17 时，下面各条与原来完全一致。
+>
+> 0.3.15 同样只是文档层面的发布。
 
 **1. 新增退出码 `3` / `4`：本质是缺陷修复，形式上也是破坏性变更。**
 - `3` = **不可在本宿主评估**：被检文件的 `header.version` 高于当前宿主支持的上限

package/bin/dsh-log-contract.mjs

@@ -16,9 +16,9 @@ import fs from 'node:fs';
 import { loadSessionLog, validateSessionLog, resumeVerdict, migrationVerdict, assessmentScope, createPreWriter, repairSession, readSessionHeader, CONTRACT_RULES, ruleById, extractToolOutputs, auditToolCalls, hostCapability, HOST_MAX_FILE_VERSION, detectSupport } from '../lib/index.js';
 
 /**
- * 同步写 fd（F4 修复）——`process.stdout.write` 在**管道**下是异步的，紧跟着的
+ * 同步写 fd——`process.stdout.write` 在**管道**下是异步的，紧跟着的
  * `process.exit()` 不会等待 flush：>~64KiB 的输出会丢尾，`--json` 因此变成非法 JSON
- * （独立审核在 3000 事件夹具与真实 14.5MB v3 会话上复现，stdout 56648B 处 "Unterminated string"）。
+ * （实测在 3000 事件夹具与真实 14.5MB v3 会话上复现，stdout 56648B 处 "Unterminated string"）。
  * 这里直接同步写 fd 1/2（非阻塞管道 EAGAIN 时自旋重试），做到"先写完再 exit"。
  */
 function writeAllSync(fd, text) {
@@ -49,7 +49,7 @@ const USAGE = `dsh-log-contract —— 日志契约守护（DSH session log cont
       --resume        输出分层结论：可加载 / 可继续 / 可压缩（本工具规则集内）
                       + 迁移预检（官方 v0/v1/v2→当前格式会不会拒）；--json 时附带。
       --fail-on-migration     migration.ready===false（工具判"官方升级会拒"）时退出码 4。
-                      **注意：默认已经是这个行为**（第四轮把"报告与退出码不一致"的假阴性修掉了）；
+                      **注意：默认已经是这个行为**（已把"报告与退出码不一致"的假阴性修掉）；
                       本开关是**显式别名**，便于 CI 把意图写进命令行。
       --no-fail-on-migration  **真 opt-out**：恢复 0.3.11 的行为——迁移 blocked 不再改退出码
                       （结构绿即 exit 0）。两者同时给时 **opt-out 优先**。若你的流水线依赖旧退出码，
@@ -74,7 +74,7 @@ const USAGE = `dsh-log-contract —— 日志契约守护（DSH session log cont
                        ignorable:true，删 surfaceOp/sourceEventSeqs，seq/行数不变）
                        —— token-meter 不再刷屏，会话驻留也安全（2026-08-30 事故）
       --neutralize-legacy-markers
-                       **一次性根治历史载体债**（R-C）：只中和
+                       **一次性根治历史载体债**：只中和
                        assistant/message + data.editor 形态的历史 retrace marker
                        （新载体是 user/message + data.id，不在此列）。清理后，
                        写前校验不再需要"≤v2 历史 marker T1 降级"那条豁免。
@@ -138,7 +138,7 @@ function printViolations(violations, maxDetails = 8) {
   }
 }
 
-/** R-E 抬头（2026-09-14 裁定）:漂移清单 + 未复核清单 + "勿据此跑 fix --apply"。 */
+/** 漂移抬头（2026-09-14）:漂移清单 + 未复核清单 + "勿据此跑 fix --apply"。 */
 function driftLines(drift, probes) {
   if (!drift) return '';
   const host = probes ? `${probes.hostPackage}（SESSION_FORMAT_VERSION=${probes.sessionFormatVersion},词表 ${probes.knownTypes} 类）` : '未知';
@@ -150,8 +150,8 @@ function driftLines(drift, probes) {
   if (drift.unverifiedRules.length > 0) {
     out += `     ⛔ **UNVERIFIED**（探针与规则假设不一致,结论不可采信）:${drift.unverifiedRules.join('、')}\n`;
   }
-  out += `     出处未复核（R-F,已知债,仅告警）:${drift.driftedSources.join('、')}\n`;
-  out += `     判定前提存疑（复核 §1,仅告警）:${drift.premiseStale.join('、')}${drift.undecidable.length ? `；无法判定:${drift.undecidable.join('、')}` : ''}\n`;
+  out += `     出处未复核（已知债,仅告警）:${drift.driftedSources.join('、')}\n`;
+  out += `     判定前提存疑（仅告警）:${drift.premiseStale.join('、')}${drift.undecidable.length ? `；无法判定:${drift.undecidable.join('、')}` : ''}\n`;
   if (drift.fixApplyBlocked) {
     out += '     ⛔ **禁止据此跑 `fix --apply`**（存在未验证规则:写入类动作不可逆）——先按 report 复核这些规则或显式确认。\n';
   }
@@ -186,7 +186,7 @@ function notAssessableBanner(result) {
 /** 迁移预检（独立维度）文本。
  * @param {object} mig `migrationVerdict()` 结果
  * @param {boolean} partial 待迁移文件（`migration.applies===true`）⇒ 迁移维度只部分覆盖，
- *   不得给无条件绿（2026-09-14 最终复核规格 (i)+(iii)）。
+ *   不得给无条件绿（2026-09-14 规格 (i)+(iii)）。
  */
 function migrationLine(mig, partial = false) {
   if (!mig) return '';
@@ -213,7 +213,7 @@ function migrationLine(mig, partial = false) {
 function cmdCheck(args) {
   const json = args.includes('--json');
   const resume = args.includes('--resume');
-  // 第四轮/第五轮：`--fail-on-migration` 是**默认已生效行为**的显式别名；
+  // `--fail-on-migration` 是**默认已生效行为**的显式别名；
   // `--no-fail-on-migration` 是**真 opt-out**（恢复旧行为：迁移 blocked 不再改退出码）。
   // 两者同时给 ⇒ opt-out 优先（help/README 写明）。
   const failOnMigration = args.includes('--fail-on-migration');
@@ -233,11 +233,11 @@ function cmdCheck(args) {
   const { summary, violations, ok } = result;
   const notAssessable = result.assessable === false;
   const migration = result.migration ?? migrationVerdict(result);
-  // 第四轮：机器可判的评估范围（partial = 待迁移文件，迁移维度只部分覆盖）。
+  // 机器可判的评估范围（partial = 待迁移文件，迁移维度只部分覆盖）。
   const scope = result.assessmentScope ?? assessmentScope(result);
   const partial = scope === 'partial';
   const migBlocked = migration?.applies === true && migration.ready === false;
-  // 默认：`ready===false` ⇒ 非 0（第四轮修复的假阴性）。
+  // 默认：`ready===false` ⇒ 非 0（修掉的假阴性）。
   // `--fail-on-migration` = 显式别名（同默认）；`--no-fail-on-migration` = 真 opt-out（恢复旧行为）。
   const migGate = !noFailOnMigration && (migBlocked || (failOnMigration && migration?.ready === false));
   // 退出码：3 不可评估 > 1 结构 error > 4 迁移 blocked > 0。
@@ -363,7 +363,7 @@ function cmdPrewrite(args) {
 
   out(`\n✍️  dsh-log-contract prewrite —— ${file}（op: ${result.op}，nextSeq: ${prewriter.nextSeq}）\n\n`);
   if (result.legacyMarkerDebt) {
-    // R-C「降级可见」:历史 marker 债不只是 warning 里的一句话,这里显式打印并给出根治命令。
+    // 「降级可见」:历史 marker 债不只是 warning 里的一句话,这里显式打印并给出根治命令。
     const d = result.legacyMarkerDebt;
     out(`  ⚠️  检测到**历史 marker 载体**（${d.kind} 形态，id=${d.id}，targetSeq=${d.targetSeq}，seq=${d.seq}）：\n`);
     out(`     T1 已按 ≤v${d.formatVersion <= 2 ? 2 : d.formatVersion} 白名单降级为 warning（仅历史载体、仅旧格式文件）——\n`);
@@ -382,7 +382,7 @@ function cmdPrewrite(args) {
 }
 
 function cmdContracts() {
-  out('dsh-log-contract 契约规则目录（spec：59 条审计发现 + 官方源码逐行核对）\n\n');
+  out('dsh-log-contract 契约规则目录（spec：官方源码逐行核对 + 实测事故固化）\n\n');
   for (const r of CONTRACT_RULES) {
     const flags = [
       r.candidate ? '候选规则' : null,
@@ -397,7 +397,7 @@ function cmdFix(args) {
   const json = args.includes('--json');
   const removeMarkers = args.includes('--remove-markers');
   const neutralize = args.includes('--neutralize');
-  // R-C 一次性根治路径:只中和**历史载体**(assistant/message + data.editor)的 retrace marker
+  // 一次性根治路径:只中和**历史载体**(assistant/message + data.editor)的 retrace marker
   const neutralizeLegacyMarkers = args.includes('--neutralize-legacy-markers');
   const clipCrossStep = args.includes('--clip-crossstep');
   const dropFailedTurns = args.includes('--drop-failed-turns');
@@ -423,7 +423,7 @@ function cmdFix(args) {
   const file = args.find((a) => !a.startsWith('-'));
   if (!file) fail(USAGE);
 
-  // S2 安全闸：本宿主评估不了的文件**不许**修。危害路径（独立复核指出）：rc.7 上把健康 v3
+  // S2 安全闸：本宿主评估不了的文件**不许**修。危害路径（实测指出）：rc.7 上把健康 v3
   // 日志报成 broken → 用户以为日志坏了去跑 `fix --apply` ⇒ 在健康日志上动手。这里直接拒绝。
   const head = readSessionHeader(file);
   const fileVersion = Number.isSafeInteger(head?.version) ? head.version : 0;

package/docs/CONTRACTS.md

@@ -2,14 +2,14 @@
 
 > **自动生成**（2026-09-06 起）：本文件由 `node scripts/gen-contracts-doc.mjs`
 > 从 `lib/contracts.js` 的 `CONTRACT_RULES` 注册表生成——**勿手改**，规则只增不减，
-> 新增规则后跑一次生成即同步（此前手工维护滞后 15+ 条，外部审计指出）。
+> 新增规则后跑一次生成即同步（此前手工维护滞后 15+ 条）。
 > **漂移闸**：`pnpm check` 会跑 `--check` 逐字节比对，改了注册表没重生成 ⇒ 直接红。
 >
 > DSH 会话日志契约的**可执行 spec**。每条规则在 `lib/checks.js`（逐事件判定）
 > 与 `lib/prewrite.js`（写前校验）中有对应实现；离线体检（`lib/validate.js`）
 > 逐条执行并在最后用官方 `foldSurface` 终验（S8）。
 >
-> 规则来源：早期内部审计发现（59 条）+ 三层契约事故复盘 + 官方源码逐行核对
+> 规则来源：历史会话日志的实测事故与契约缺口（持久化/客户端引擎/插件语义三层）+ 官方源码逐行核对
 > （`@deepseek-ai/dsh-session`，各条出处见下）。后续规则随官方版本演进追加：
 > T3/T4 = 渲染层白屏事故复盘，T5 = malformed turn/end 事故复盘。
 >
@@ -22,7 +22,7 @@
 >
 > 严重度：**error** = 违反即会话不可加载/写入被拒（fail-loud）；**warning** = 合法但可疑。
 
-## 规则索引（共 44 条）
+## 规则索引（共 46 条）
 
 | id | 严重度 | 层级 | 规则 |
 |---|---|---|---|
@@ -65,6 +65,8 @@
 | C1 | warning | concurrency | seq 缺口/倒退提示多写入者 |
 | Z1 | warning | framing | zstd 尾帧撕裂 |
 | Z2 | error | framing | zstd 帧解码失败 = 单帧全损 |
+| Z4 | error | framing | 首帧必须恰好一行 header |
+| Z5 | error | framing | 多行日志不得压成单帧 |
 | W1 | error | engine | wire 流：tool 消息必须跟在带 tool-call 的 assistant 消息之后 |
 | W2 | error | engine | wire 流：user 文本不得插在 tool_calls 与其 tool 结果之间 |
 | G1 | warning | migration | 迁移预检：v0 源文件的 subagent/descriptor.data.version 必须为 3 |
@@ -88,7 +90,7 @@
 ### R1 — 每行必须是合法 JSON
 
 - **层级**: persistence ｜ **严重度**: error
-- **出处**: 审计方法论（scan-seq-gaps.mjs）；dsh-session-persistence-jsonl 读路径
+- **出处**: seq 缺口扫描；dsh-session-persistence-jsonl 读路径
 - **契约**: 非空行无法 JSON.parse = 损坏行。帧边界产生的空行是合法的（跳过）。
 
 ### R2 — chunk 行必须满足精确信封形状
@@ -112,7 +114,7 @@
 ### E2 — seq 严格连续（单写入者假设）
 
 - **层级**: persistence ｜ **严重度**: error
-- **出处**: @deepseek-ai/dsh-session lib/index.js:398 (planSurfaceEvent "not contiguous")；审计 S2/N6
+- **出处**: @deepseek-ai/dsh-session lib/index.js:398 (planSurfaceEvent "not contiguous")
 - **契约**: seq 必须从 0（或窗口 baseSeq）严格连续递增。缺口/倒退 = 违反单写入者假设（多实例共享存储并发写的痕迹），加载时直接 throw。
 
 ### S9 — 文件物理序 seq 单调（多写入者交织现场特征）
@@ -143,7 +145,7 @@
 
 - **层级**: persistence ｜ **严重度**: error
 - **出处**: @deepseek-ai/dsh-session lib/index.js:1273-1277 (assertSupportedRequestHeader)
-- **契约**: request/header-delta 与 reason=fallback 的 request/header 是已删除的遗留格式。注意（R-F 订正复核 §1 E5）：宿主 Session.append/appendLines 不看 type ⇒ 写入会成功、下一次读取才炸（依据 dsh-session@0.1.5-rc.1 lib/index.js:1170-1210 / persistence-jsonl:3046-3073），不是写入即被拒。
+- **契约**: request/header-delta 与 reason=fallback 的 request/header 是已删除的遗留格式。注意（订正 E5）：宿主 Session.append/appendLines 不看 type ⇒ 写入会成功、下一次读取才炸（依据 dsh-session@0.1.5-rc.1 lib/index.js:1170-1210 / persistence-jsonl:3046-3073），不是写入即被拒。
 
 ### E6 — 消息类事件消息形状
 
@@ -178,8 +180,8 @@
 ### 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）正是违反此规则。
+- **出处**: @deepseek-ai/dsh-session lib/index.js:335-336 (assertProvenance)；复盘事故第 1 次尝试
+- **契约**: ★ 写前校验核心规则：sourceEventSeqs 必须包含每一个被替换（shadowed）的 surface 节点，缺一个 = 会话加载被拒（SessionPersistenceCorruptionError）。2026-08-25 事故第 1 次尝试（清空 sourceEventSeqs）正是违反此规则。
 
 ### S6 — sourceEventSeqs 自身约束
 
@@ -232,31 +234,31 @@
 ### E7 — ignorable 未知 type 合法性（带被忽略标记的未知事件须有消费者）
 
 - **层级**: persistence ｜ **严重度**: warning
-- **出处**: 对抗性复查 2026-09-09 T2（E3 ignorable 无合法性校验 = 后门）
+- **出处**: 实测 2026-09-09 T2（E3 ignorable 无合法性校验 = 后门）
 - **契约**: 未知 type + ignorable:true 被读路径接纳但无人消费 = 静默垃圾。排除已知消费者白名单（retrace/marker、retrace/goal-marker、message-editor/ 前缀等 retrace 客户端消费的插件 marker）后，其余 ignorable 未知事件报 warning。
 
 ### E8 — 事件信封键白名单（多余键：seed/restore 路径会拒）
 
 - **层级**: persistence ｜ **严重度**: warning
 - **出处**: @deepseek-ai/dsh-session@0.1.5-rc.1 lib/index.js:849-861（assertSessionEventEnvelope）+ :1063-1068（唯一调用点=seed 路径）；load 路径容忍见行为探针 p5
-- **契约**: 事件对象只允许 7 个信封键（type/seq/time/data/surfaceOp/sourceEventSeqs/ignorable）。独立复核变异 05 指出"宿主拒、旧契约 0 违规"；R-D 行为探针进一步订正口径：**load 路径容忍、seed/restore 路径拒** ⇒ warning。
+- **契约**: 事件对象只允许 7 个信封键（type/seq/time/data/surfaceOp/sourceEventSeqs/ignorable）。实测反例指出"宿主拒、旧契约 0 违规"；行为探针进一步订正口径：**load 路径容忍、seed/restore 路径拒** ⇒ warning。
 
 ### E9 — system/message 必须带 plugin source
 
 - **层级**: persistence ｜ **严重度**: error
 - **出处**: @deepseek-ai/dsh-session@0.1.5-rc.1 lib/index.js:942-944（"must have plugin source"）；角色表 :917-926
-- **契约**: v3 新增的 system/message：role 必须为 system，source.kind 必须为 plugin 且 plugin 非空。实测（变异 03）：source.kind='user' 宿主拒、旧契约 0 违规 ⇒ 漏检。
+- **契约**: v3 新增的 system/message：role 必须为 system，source.kind 必须为 plugin 且 plugin 非空。实测（反例）：source.kind='user' 宿主拒、旧契约 0 违规 ⇒ 漏检。
 
 ### E10 — request/header 的 data.header 字段约束
 
 - **层级**: persistence ｜ **严重度**: error
 - **出处**: @deepseek-ai/dsh-session@0.1.5-rc.1 lib/index.js:231-248（validateSessionEventData：omit header.system / omit empty tools / omit empty adapterDefaults）
-- **契约**: request/header 必须省略 header.system（系统提示改走 system/message）、空 tools、空 adapterDefaults。实测（变异 12）：带 header.system 的写入宿主拒、旧契约 0 违规 ⇒ 漏检。
+- **契约**: request/header 必须省略 header.system（系统提示改走 system/message）、空 tools、空 adapterDefaults。实测（反例）：带 header.system 的写入宿主拒、旧契约 0 违规 ⇒ 漏检。
 
 ### Z3 — 空会话文件（有 header 无事件）显式报出
 
 - **层级**: framing ｜ **严重度**: warning
-- **出处**: 对抗性复查 2026-09-09 T3（36 条规则全来自有内容事故,空态无覆盖）
+- **出处**: 实测 2026-09-09 T3（36 条规则全来自有内容事故,空态无覆盖）
 - **契约**: 有 header 但零事件 = 异常空会话（新建即空或写入未落盘）。空态不在任何有内容规则的覆盖下,显式 warning 供人判断。
 
 ### P3 — tool/call ↔ tool/result 配对完整性（考古 B1）
@@ -274,7 +276,7 @@
 ### M1 — turn/step 为 null 的 assistant/message 只能 replace，不能 append
 
 - **层级**: engine ｜ **严重度**: error
-- **出处**: 复盘事故第 2 轮（rt.js:6816 崩溃）；实证 data.turn/data.step：正常消息为数字、插件 marker 为 null
+- **出处**: 复盘事故第 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 前缀必须被识别
@@ -292,21 +294,33 @@
 ### C1 — seq 缺口/倒退提示多写入者
 
 - **层级**: concurrency ｜ **严重度**: warning
-- **出处**: 审计 N6：dsh-session-persistence-jsonl appendLines 无锁（:1200-1227），全仓无会话级排他锁
+- **出处**: dsh-session-persistence-jsonl appendLines 无锁（:1200-1227），全仓无会话级排他锁
 - **契约**: 离线体检无法直接观测跨进程竞态，但 E2 暴露的缺口/倒退即是"≥2 个 Host 进程共享同一 session 目录并发写"的后果。单实例部署不触发。
 
 ### Z1 — zstd 尾帧撕裂
 
 - **层级**: framing ｜ **严重度**: warning
-- **出处**: 审计 N5 相关；帧扫描方法论
+- **出处**: zstd 帧布局（dsh-session-persistence-jsonl 多帧）
 - **契约**: 尾帧不完整（torn）：可能正在写入（in-flight）或文件被截断。若这是唯一异常，通常可等待写入完成；若持续存在则是截断证据。
 
 ### Z2 — zstd 帧解码失败 = 单帧全损
 
 - **层级**: framing ｜ **严重度**: error
-- **出处**: 审计 N5：多帧单帧全损 → 整会话不可读
+- **出处**: 多帧单帧全损 → 整会话不可读
 - **契约**: 任一帧解码失败（磁盘 bitrot / 传输截断 / 并发写撕裂）即整会话不可读；帧越多，单帧损坏下丢失概率线性上升。
 
+### Z4 — 首帧必须恰好一行 header
+
+- **层级**: framing ｜ **严重度**: error
+- **出处**: 宿主 assertZstdHeaderFrame（0.1.5-rc.2 lib/index.js:2184）：首帧非"恰好一行"即抛
+- **契约**: 官方写盘形状是 header **独占第一帧**。首帧装多行时宿主抛错，且抛点在 listArtifacts **遍历全库**、无 per-session 容错 ⇒ **整个客户端起不来**（2026-09-16 真机事故：有人把整份日志重压成单帧写回）。
+
+### Z5 — 多行日志不得压成单帧
+
+- **层级**: framing ｜ **严重度**: error
+- **出处**: 官方形状：header 第一帧 + 事件批次逐帧追加
+- **契约**: 把整份日志重压成 1 帧会同时触发 Z4；任何"重写会话"的路径都必须**保形**（逐帧解、逐帧回写，或走宿主写入器），不得整体重压缩。
+
 ### W1 — wire 流：tool 消息必须跟在带 tool-call 的 assistant 消息之后
 
 - **层级**: engine ｜ **严重度**: error