dsh-log-contract 0.3.16 → 0.3.17

package/README.md

@@ -344,11 +344,11 @@ MIT © OfferKuai Team
 
 ---
 
-## ⚠️ Upgrading to 0.3.16 — behaviour changes you must know (0.3.12 → 0.3.16)
+## ⚠️ Upgrading to 0.3.17 — behaviour changes you must know (0.3.12 → 0.3.17)
 
-> **0.3.16 changes no behaviour.** It rewrites comments, test titles, a few diagnostic strings and the
+> **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.16.
+> 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.
 

package/README.zh.md

@@ -295,11 +295,11 @@ MIT © OfferKuai Team
 
 ---
 
-## ⚠️ 升级到 0.3.16 —— 必须知道的行为变更（0.3.12 → 0.3.16）
+## ⚠️ 升级到 0.3.17 —— 必须知道的行为变更（0.3.12 → 0.3.17）
 
-> **0.3.16 不含行为变更。** 它只重写了注释、测试标题、少量诊断文案与 README，让它们
+> **0.3.17 不含行为变更。** 它只重写了注释、测试标题、少量诊断文案与 README，让它们
 > 只描述产品与契约本身。所有判定结果、退出码与 `--json` 字段与 0.3.15 完全一致，
-> 因此从 0.3.12 升到 0.3.16 时，下面各条与原来完全一致。
+> 因此从 0.3.12 升到 0.3.17 时，下面各条与原来完全一致。
 >
 > 0.3.15 同样只是文档层面的发布。
 

package/docs/CONTRACTS.md

@@ -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 |
@@ -307,6 +309,18 @@
 - **出处**: 多帧单帧全损 → 整会话不可读
 - **契约**: 任一帧解码失败（磁盘 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

package/lib/contracts.js

@@ -408,6 +408,22 @@ export const CONTRACT_RULES = [
     source: '多帧单帧全损 → 整会话不可读',
     description: '任一帧解码失败（磁盘 bitrot / 传输截断 / 并发写撕裂）即整会话不可读；帧越多，单帧损坏下丢失概率线性上升。',
   },
+  {
+    id: 'Z4',
+    title: '首帧必须恰好一行 header',
+    layer: LAYER.FRAMING,
+    severity: SEVERITY.ERROR,
+    source: '宿主 assertZstdHeaderFrame（0.1.5-rc.2 lib/index.js:2184）：首帧非"恰好一行"即抛',
+    description: '官方写盘形状是 header **独占第一帧**。首帧装多行时宿主抛错，且抛点在 listArtifacts **遍历全库**、无 per-session 容错 ⇒ **整个客户端起不来**（2026-09-16 真机事故：有人把整份日志重压成单帧写回）。',
+  },
+  {
+    id: 'Z5',
+    title: '多行日志不得压成单帧',
+    layer: LAYER.FRAMING,
+    severity: SEVERITY.ERROR,
+    source: '官方形状：header 第一帧 + 事件批次逐帧追加',
+    description: '把整份日志重压成 1 帧会同时触发 Z4；任何"重写会话"的路径都必须**保形**（逐帧解、逐帧回写，或走宿主写入器），不得整体重压缩。',
+  },
 
   // ── W · wire 消息流（模型请求序列）───────────────────────────────────────
   {

package/lib/log-reader.js

@@ -173,7 +173,19 @@ export function loadSessionLog(path) {
       plain = Buffer.alloc(0);
     }
     const { frames, torn } = scanZstdFrames(buf);
-    frameInfo = { frames: frames.length, torn, compressedBytes: buf.length, plaintextBytes: plain.length };
+    // 帧形状事实（Z4/Z5，2026-09-16 真机事故）：官方写盘形状 = **header 独占第一帧** +
+    // 事件逐帧追加；读取端有硬断言 `assertZstdHeaderFrame`（首帧必须**恰好一行**）。
+    // 这里把该事实带出来给 validate 判：整文件被重压成单帧时，首帧装的是全部行 ⇒ 宿主必抛，
+    // 而抛点在 `listArtifacts` **遍历全库**、无 per-session 容错 ⇒ 整个客户端起不来。
+    let firstFrameOneLine = true, firstFrameLines = 1;
+    try {
+      const [s0, e0] = frames[0];
+      const first = zstdDecompressSync(buf.subarray(s0, e0)).toString('utf8');
+      const nl = first.indexOf('\n');
+      firstFrameOneLine = nl === first.length - 1 && first.length > 1;
+      firstFrameLines = first.split('\n').filter((x) => x !== '').length;
+    } catch { /* 首帧解码失败另有 Z2 报 */ }
+    frameInfo = { frames: frames.length, torn, compressedBytes: buf.length, plaintextBytes: plain.length, firstFrameOneLine, firstFrameLines };
   } else {
     plain = buf;
     frameInfo = { frames: 0, torn: false, compressedBytes: 0, plaintextBytes: plain.length };

package/lib/validate.js

@@ -81,6 +81,16 @@ export function validateSessionLog(log, opts = {}) {
   if (frameInfo?.error) {
     violations.push(violation('Z2', { lineNo: null }, frameInfo.error));
   }
+  // Z4 · 首帧必须恰好一行 header（2026-09-16 真机事故：整份日志被重压成单帧 ⇒ 客户端起不来）
+  if (frameInfo?.firstFrameOneLine === false) {
+    violations.push(violation('Z4', { lineNo: null },
+      `首帧不是"恰好一行 header"（实测 ${frameInfo.firstFrameLines ?? '?'} 行）——宿主 assertZstdHeaderFrame 必抛；抛点在 listArtifacts 遍历全库 ⇒ 整个客户端不可用`));
+  }
+  // Z5 · 多行日志不得压成单帧
+  if (Number.isSafeInteger(frameInfo?.frames) && frameInfo.frames === 1 && Array.isArray(rows) && rows.length > 1) {
+    violations.push(violation('Z5', { lineNo: null },
+      `整份日志被压成 1 帧（${rows.length} 行）——官方形状是 header 独占第一帧 + 事件逐帧追加；不要这样写回`));
+  }
 
   // ── H · header ─────────────────────────────────────────────────────────
   if (header === null) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-log-contract",
   "description": "日志契约守护 — DSH session log contract guard: offline health check (CLI) + pre-write validation for DeepSeek Harness session logs",
-  "version": "0.3.16",
+  "version": "0.3.17",
   "packageManager": "pnpm@11.7.0",
   "type": "module",
   "main": "lib/index.js",