dsh-gokifu-compact 1.11.4 → 1.11.6

package/CHANGELOG.md

@@ -1,5 +1,93 @@
 # 更新记录
 
+## 1.11.6 — 2026-10-31
+
+### tier-2 解耦：checkpoint 的常驻成本不再随 fold 次数线性涨
+
+**问题（只读核实）**：fold 的 range 从**上一个 checkpoint 之后**开始 ⇒ 旧 checkpoint **全部留在 surface**
+（实测 `start=1009 > cp8=1008`），每 fold 一次就 +1 条；而旧代码**只在 pressure 分支**才收 tier-2。
+⇒ auto 路径连做 12 次 fold，surface 上就线性涨到 **12 条旧 checkpoint**。
+
+**改法**
+
+- `src/engine.mjs`：删掉那个**空的 `#tier2`**（调用点 + 定义一起删）；常规 fold **成功后**
+  （`tier2After > 0`）`await #tier2IfNeeded()`；**失败只 warn，不影响本次 fold**。
+- `#tier2IfNeeded` 加 `_tier2InFlight` **防重入**（同一时刻只允许一个 tier-2 在跑，防递归 / 二次 `compactRegion`）。
+
+**前后对照（同一会话 12 次 fold）**
+
+| | surface 上旧 checkpoint 条数 | tier-2 次数 |
+|---|---|---|
+| 旧 | **12**（`[1..12]`，max 12） | 0（auto 路径从不触发） |
+| 新 | **8**（`[1..8,7,8,7,8]`，max 8） | 14 次 = 12 fold + **2 tier-2** |
+
+**测试 6 → 7**：T2-0 改写（空方法已删、fold 后调用、防重入）、T2-5 改写（auto 也触发）、
+T2-6 新增（不递归 / 压回上限 / `tier2After=0` 不触发）。变异：删掉 fold 后的触发 ⇒ T2-0/T2-5/T2-6 红。
+
+### 迁移守卫补上 delta：只看 `graph.json` 会漏掉「插件其实在写」
+
+**问题**：`migrate-dangling --apply` 的 120s 新鲜度守卫**只 stat `graph.json`**。但 1.9.2 起是**增量落盘** ——
+`graph.json` 只在回合边界写，插件活跃时往往**只有 `graph.json.delta.jsonl` 在动**。
+真实库实测：**8 个会话的 delta 在 120s 内被写过，而旧守卫一个都没拦住** ⇒ apply 可能在插件仍活跃时放行，
+随后内存 flush 把迁移结果覆盖回去（这正是 P6-C 反复强调的 `netCleaned=0` 场景）。
+
+**改法**
+
+- 新增导出 **`DELTA_NAME = "graph.json.delta.jsonl"`**（与 `kifu-persist.sessionPaths().deltaFile` 的 basename
+  必须一致，测试有断言盯着这两个名字）。
+- 新增 **`freshEvidence()`**：返回每个「120s 内被写过」的会话**及具体文件**；`freshSessions()` 在其上去重。
+- 判据：`graph.json` **必看**（缺失照旧抛 ENOENT，不静默跳过）；**delta 存在就看 delta**；
+  delta 缺失不判 fresh（老库没有 delta 文件也照样能迁移）。
+- 拒绝 apply 时的报错会**点名会话与文件**，而不是只说「有会话新鲜」。
+
+**测试 +4**：P6C-11（只有 delta 在写 ⇒ 拦住并点名文件）/ P6C-12（delta 缺失不影响）/ P6C-13（两者都旧 ⇒ 放行）/
+P6C-14（多会话混判：按会话去重，逐个点名）。
+
+### 验证
+
+- 全量：**481 passed / 0 skipped / 0 failed**（36 个测试文件；476 + 1 tier-2 + 4 migrate）
+- `tier2` **7/0** · `migrate` **14/0** · `engine-harness` 25/0 · `rooms` 15/0 · `verify-install` **16/16**
+- `bench 2000`：**351 tokens**（与基线一致）
+- `npm pack --dry-run --json`：**71 文件**（数量不变：只改 `src/` 与 `test/`，无新增文件）
+
+**未验证**
+
+- tier-2 的**运行期**收益未在真机观测 —— 8 vs 12 是引擎级前后对照（同一会话、同一 fold 序列）。
+- delta 守卫只在测试夹具与**只读扫描**真实库上验证过；**真实 apply 仍未执行**（需主人授权 + 停插件窗口）。
+
+## 1.11.5 — 2026-10-31
+
+### S10d · 测试运行器终于能区分「跳过」与「通过」，「空壳用例」不再是绿的
+
+**问题**：旧 `run.mjs` 里，平台/权限不对时用 `return` 早退，**会计入 passed** —— 单看
+「N passed」根本排除不了跳过；而且一个**一条断言都没有**的用例也会静默算通过。
+
+**改法**
+
+| 能力 | 说明 |
+|---|---|
+| `t.skip(reason)` | 计入 `skipped`，不计 pass/failed；**exit code 只由 failed 决定** |
+| 汇总行 | `== N passed, M skipped, K failed ==`（新增中间那段，跳过不再藏在 passed 里） |
+| **零断言检测** | `assertions === 0` **且**源码里没有 `throw` / `assert` 证明 ⇒ 计入 `zeroAssertions` 并**按失败处理**。本仓 300+ 用例是 throw 风格（算有证明），空壳用例从此不再静默算 pass |
+| `--dir=` | 仅供 `run-skip` 夹具指向临时目录 |
+
+- **`install-link` 6 处平台/权限早退改为 `t.skip(...)`**，原有断言一字未改。
+- 新增 `test/run-skip.test.mjs` **3 条**：四态（pass/fail/skip/零断言）可区分、skip 不导致失败、零断言严格红。
+
+**变异自检**：删掉 skip 分支 ⇒ `run-skip` 红；删掉零断言检测 ⇒ `run-skip` 红。
+
+### 验证
+
+- 全量：**476 passed / 0 failed / 0 skipped**（36 个测试文件；473 + 3）
+- `install-link` **29/0** · `run-skip` **3/0** · `rooms` 15/0 · `verify-install` **16/16**
+- `bench 2000`：**351 tokens**（与基线一致）
+- `npm pack --dry-run --json`：**71 文件**（数量不变，只改 `test/`）
+
+**未验证**
+
+- 零断言检测只认 `assertions` 计数与 `throw`/`assert` 的**文本证据**：如果一个用例用别的方式实打实地检查了东西（例如把结果写进外部文件再断言），仍可能被误判 —— 目前本仓没有这种写法。
+- `skipped` 总数现在是 0（本机 Windows）。**跨平台**（Linux/macOS 上那 6 条会真的 skip）没有实跑过。
+
 ## 1.11.4 — 2026-10-31
 
 ### 发布脚本加固：坏 remote 在预演阶段就红，git 步骤事务化

package/README.md

@@ -1,6 +1,6 @@
 # dsh-GOkifu-compact
 
-> 当前版本：**`1.11.4`** · npm [`dsh-gokifu-compact`](https://www.npmjs.com/package/dsh-gokifu-compact) · [GitHub Releases](https://github.com/MYCF711/dsh-GOkifu-compact/releases) · 更新记录见 [CHANGELOG.md](CHANGELOG.md)
+> 当前版本：**`1.11.6`** · npm [`dsh-gokifu-compact`](https://www.npmjs.com/package/dsh-gokifu-compact) · [GitHub Releases](https://github.com/MYCF711/dsh-GOkifu-compact/releases) · 更新记录见 [CHANGELOG.md](CHANGELOG.md)
 
 **DSH 的棋谱式上下文压缩后端 —— 把「历史 → 一段摘要」换成「历史 → 可复盘的棋谱 DAG + 每步只有 351 tokens 的热清单」。**
 
@@ -8,7 +8,7 @@
 热清单     351 tokens       （2000 边合成夹具 · L5 降级档 · 2026-10-30/10-31 两次实测同值；旧版全量 28,800）
 失败保留   8 / 8            （历史口径 †；官方 8 段模板 4.67 / 8）
 清单开销   未复现/待测       （原载 0.2% = 历史单会话 v1.3.1 后实测；无复跑命令、无对照组；源 evidence/真实计费核对.md）
-验证       473 项单测 · 真实包 8/8 † · 真实进程 fold 3~6/6 †
+验证       481 项单测（0 skipped） · 真实包 8/8 † · 真实进程 fold 3~6/6 †
 ```
 
 GO = 围棋，kifu = 棋谱，compact = 压缩。一局棋下完，棋谱上不只有落子顺序，还有每一手的评语。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-gokifu-compact",
-  "version": "1.11.4",
+  "version": "1.11.6",
   "description": "DSH context-compression backend with a go game record (kifu) DAG: node = position, edge = attempted move + result. Incremental fold (each span summarized once), failure memory that survives compaction, transposition detection (chess-engine style), and a tiny hot ledger rebuilt every step.",
   "repository": {
     "type": "git",

package/src/engine.mjs

@@ -131,6 +131,9 @@ export default class ChessCompactionEngine extends BasicCompactionEngine {
     /** ★ P3：每会话基线 graph.json 的内容哈希（16 位）；delta 帧用它做 generation 保护。 */
     /** ★ P3：已进入 graph.json/delta 但还没写过 nodes/<id>.md 的节点（fold 时补写）。 */
     this.runtime = new Map();
+    /** ★ TIER2-SEMANTICS（task-142）：tier-2 重入保护 —— 常规 fold 之后与 pressure 分支都会收 checkpoint，
+     *  同一时刻只允许一个 tier-2 在跑（防递归 / 二次 compactRegion）。 */
+    this._tier2InFlight = false;
     /** ★ P7：热清单预算统计（跨会话累计；doctor 从这里读）。 */
     this.ledgerBudget = { none: 0, "over-budget": 0, impossible: 0, 未采集: 0, maxOverBudgetBy: 0, updatedAt: 0, samples: 0 };
     if (this.chess.hotLedger) this.#bindLedger();
@@ -608,7 +611,6 @@ ${constraintsBlock.split("\n").map((l) => `- ${l}`).join("\n")}` });
       shadowedTokens: range.shadowedTokens,
       totalAfter: after.totalTokens,
     });
-    this.#tier2(session, g);
     // ★ 2026-10-29 修复：这里原来传的是 `{ md: true }`，而 `#flush(session, { tree = false })`
     //   只认 `tree` —— 参数名不匹配 ⇒ fold 后**从不**重写 `nodes/*.md`，
     //   压缩后的节点详情停在第一次落盘的样子（Kimi 评估实测发现）。
@@ -616,6 +618,20 @@ ${constraintsBlock.split("\n").map((l) => `- ${l}`).join("\n")}` });
     this.ctx.logger?.info?.(
       `chess-context: fold #${g.foldCount} 遮蔽 ${range.end - range.start >= 0 ? `${range.start}-${range.end}` : "?"} (~${range.shadowedTokens} tokens) → 总 ${after.totalTokens} tokens（死路 ${failureEdges(g).length} 条，节点 ${g.order.length}）`,
     );
+    // ★ TIER2-SEMANTICS（task-142，方案 A）：checkpoint 常驻成本与「压力」无关，常规 fold 之后也要收。
+    //   证据（ws-tier2-semantics/REPORT.md）：fold 的 range 从**上一个 checkpoint 之后**开始
+    //   （实测 8 个 checkpoint 之后 start=1009 > cp8=1008）⇒ 旧 checkpoint 全部留在 surface 上，
+    //   每 fold 一次 +1，数量随 fold 次数线性增长。旧版只在 trigger === "pressure" 收，
+    //   auto / context-overflow 路径会无限堆积（旧的空 `#tier2` 调用不做事）。
+    //   安全性：`#tier2IfNeeded` 只调 `compactRegion`（不会回到 `compactIfNeeded`）⇒ 无递归；
+    //   另有 `_tier2InFlight` 防重入；`tier2After = 0` 直接跳过（与 compactIfNeeded 的守卫一致）。
+    if (this.chess.tier2After > 0) {
+      try {
+        await this.#tier2IfNeeded(agent, signal);
+      } catch (error) {
+        this.ctx.logger?.warn?.(`chess-context: fold 后 tier-2 失败（不影响本次 fold）：${String(error)}`);
+      }
+    }
     return result;
   }
 
@@ -640,6 +656,18 @@ ${constraintsBlock.split("\n").map((l) => `- ${l}`).join("\n")}` });
    * @returns 合并结果，或 null（不需要/无法合并）
    */
   async #tier2IfNeeded(agent, signal) {
+    // ★ TIER2-SEMANTICS（task-142）：防重入 —— 常规 fold 之后与 pressure 分支都会调它。
+    //   重入时直接放弃（宁可少合并一次，也不要在一个 fold 事务里套第二个 compactRegion）。
+    if (this._tier2InFlight) return null;
+    this._tier2InFlight = true;
+    try {
+      return await this.#tier2IfNeededUnsafe(agent, signal);
+    } finally {
+      this._tier2InFlight = false;
+    }
+  }
+
+  async #tier2IfNeededUnsafe(agent, signal) {
     const session = agent.session;
     const cps = checkpointSeqs(session);
     if (cps.length < this.chess.tier2After) return null;
@@ -665,11 +693,6 @@ ${constraintsBlock.split("\n").map((l) => `- ${l}`).join("\n")}` });
     }
     return result;
   }
-
-  /** 记录一次常规 fold 的元数据（tier-2 由 #tier2IfNeeded 自己记）。 */
-  #tier2(_session, _g) {
-    /* 保留方法名以免外部调用点断裂；真正的合并在 #tier2IfNeeded。 */
-  }
 }
 
 /* ────────────────────────────── 辅助 ────────────────────────────── */

package/src/rooms/migrate.mjs

@@ -239,22 +239,55 @@ export function dryRun(root, { now = Date.now(), only = null } = {}) {
 }
 
 /**
- * 新鲜度守卫：返回「最近 maxAgeMs 内被写过」的会话（apply 前必须为空）。
- * 为什么需要：运行中的插件会在内存 flush 时把清理结果覆盖回去（实测 netCleaned=0）。
- * @returns {string[]} 会话目录名
+ * 增量帧文件名。
+ * ⚠ 必须与 `kifu-persist.sessionPaths().deltaFile` 的 basename 一致（那里的值由
+ * `<graphFile>.delta.jsonl` 拼出）。测试 `test/migrate.test.mjs` 有断言盯着这两个名字。
+ */
+export const DELTA_NAME = "graph.json.delta.jsonl";
+
+/**
+ * 新鲜度**证据**：返回每个「最近 maxAgeMs 内被写过」的会话及**具体文件**。
+ *
+ * 为什么要看 delta：1.9.2 起是**增量落盘** —— `graph.json` 只在回合边界写，
+ * 插件活跃时往往只有 `graph.json.delta.jsonl` 在动。旧实现只 stat `graph.json`，
+ * 真实库实测有 8 个会话的 delta 在 120s 内被写却没人拦 ⇒ apply 可能在插件
+ * 仍活跃时放行，随后内存 flush 覆盖迁移结果。
+ *
+ * 判据：
+ *   · `graph.json` 必看（缺失照旧抛 ENOENT，不静默跳过）；
+ *   · `graph.json.delta.jsonl` 存在才看；
+ *   · 任一文件的 |now - mtime| < maxAgeMs ⇒ 该会话算 fresh。
+ *
+ * 用**绝对值**：NTFS 的时间戳可能比 `Date.now()` 超前几毫秒（时钟粒度/回拨），
+ * 只看 age>=0 会把「刚写过」误判成「旧文件」，守卫就失效了。
+ *
+ * @returns {{session: string, file: string, ageMs: number}[]} 命中的（会话, 文件）对
  */
-export function freshSessions(root, { now = Date.now(), maxAgeMs = APPLY_FRESHNESS_MS, only = null } = {}) {
+export function freshEvidence(root, { now = Date.now(), maxAgeMs = APPLY_FRESHNESS_MS, only = null } = {}) {
   const out = [];
   for (const dir of selectedSessions(root, only)) {
-    const st = nodeFs.statSync(nodePath.join(dir, "graph.json"));
-    // 用绝对值：NTFS 的时间戳可能比 Date.now() 超前几毫秒（时钟粒度/回拨），
-    // 只看 age>=0 会把「刚写过」误判成「旧文件」，守卫就失效了。
-    const age = now - st.mtimeMs;
-    if (Math.abs(age) < maxAgeMs) out.push(nodePath.basename(dir));
+    const session = nodePath.basename(dir);
+    for (const name of ["graph.json", DELTA_NAME]) {
+      const file = nodePath.join(dir, name);
+      // graph.json 缺失时 statSync 照旧抛错（与旧行为一致）；delta 允许不存在。
+      if (name !== "graph.json" && !nodeFs.existsSync(file)) continue;
+      const ageMs = Math.abs(now - nodeFs.statSync(file).mtimeMs);
+      if (ageMs < maxAgeMs) out.push({ session, file: name, ageMs });
+    }
   }
   return out;
 }
 
+/**
+ * 新鲜度守卫：返回「最近 maxAgeMs 内被写过」的会话（apply 前必须为空）。
+ * 为什么需要：运行中的插件会在内存 flush 时把清理结果覆盖回去（实测 netCleaned=0）。
+ * 同时看 `graph.json` 与 `graph.json.delta.jsonl`（增量落盘，见 `freshEvidence`）。
+ * @returns {string[]} 会话目录名（去重，保留发现顺序）
+ */
+export function freshSessions(root, opts = {}) {
+  return [...new Set(freshEvidence(root, opts).map((hit) => hit.session))];
+}
+
 /* ───────────────────────────── 备份 ───────────────────────────── */
 
 /** 整目录备份到 `<backupRoot>/backup-<ts>/`，返回备份目录与清单。 */
@@ -310,10 +343,14 @@ export function rollback(backupDir) {
  * @throws 有「最近 120s 内被写过」的会话时拒绝执行（插件可能正在跑）
  */
 export function apply(root, { now = Date.now(), backupRoot = backupsRoot(), stamp = new Date(), maxAgeMs = APPLY_FRESHNESS_MS, only = null } = {}) {
-  const fresh = freshSessions(root, { now, maxAgeMs, only });
+  // 守卫必须点名**具体文件**：图在 1.9.2 起是增量落盘，只报「graph.json 新鲜」
+  // 会让人误以为主图没动就能 apply —— 真正在写的是 delta。
+  const fresh = freshEvidence(root, { now, maxAgeMs, only });
   if (fresh.length > 0) {
+    const sessions = new Set(fresh.map((hit) => hit.session));
+    const detail = fresh.slice(0, 3).map((hit) => `${hit.session} 的 ${hit.file}`).join("、");
     throw new Error(
-      `migrate: 拒绝 apply —— ${fresh.length} 个会话的 graph.json 在 ${maxAgeMs / 1000}s 内被写过（${fresh.slice(0, 3).join(", ")}${fresh.length > 3 ? " …" : ""}）。` +
+      `migrate: 拒绝 apply —— ${sessions.size} 个会话的文件在 ${maxAgeMs / 1000}s 内被写过（${detail}${fresh.length > 3 ? " …" : ""}）。` +
         " 运行中的插件会用内存图 flush 覆盖磁盘清理（实测 netCleaned=0）；先停插件窗口再重试。",
     );
   }