dsh-plugin-usage-stats 0.4.0

package/tests/cordis.test.ts

@@ -0,0 +1,96 @@
+/** 服务入口契约测试（不起真宿主）：
+ *  ① 原型 SRC 标记形态 = typert-protocol mark() 产物（version:1 + direct invocation，overview 单方法）；
+ *  ② applyCordis 经 ctx.reflect.provide 注册 usageStats 服务，typertRemote 绑定形态过 validateBinding；
+ *  ③ overview（含 model/provider 过滤）在真实会话目录上出非零数据（增量解码 + 价目折算全链路）。 */
+import test from "node:test";
+import assert from "node:assert/strict";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+// W1 官方插件形（default = {name, inject, apply} 对象）：函数本体走命名导入。
+import { applyCordis, UsageStatsService } from "../src/cordis.ts";
+
+const MARKER_KEY = "@deepseek-ai/dsh-typert-protocol/remote-methods";
+const ROOT = join(homedir(), ".dsh", "sessions");
+
+/** 原型标记的运行时形态（跨副本可读，测试侧本地声明，避免 import 宿主协议包）。 */
+interface RemoteMethodsMarker {
+  version: number;
+  methods: Array<{ method: string; invocation: { kind: string } }>;
+}
+/** 桩宿主 ctx：真实形态由宿主决定，测试只关心被断言的子集，故宽类型为 any。 */
+type StubCtx = any;
+
+test("SRC 标记与 typertRemote 绑定形态符合 gateway 读取契约", () => {
+  const marker = Object.getOwnPropertyDescriptor(UsageStatsService.prototype, MARKER_KEY) as { value: RemoteMethodsMarker } | undefined;
+  assert.ok(marker, "原型必须挂字符串键 remote-methods 标记（跨副本可读）");
+  assert.equal(marker.value.version, 1);
+  assert.deepEqual(
+    marker.value.methods.map((m) => m.method),
+    ["overview"],
+    "Remote 收口为 overview 单方法（会话视图宿主自带，不预留死接口）",
+  );
+  assert.deepEqual(
+    marker.value.methods.map((m) => m.invocation.kind),
+    ["direct"],
+  );
+  // SRC 参数形态：复刻网关 methodParameterNames 的解析（Node type-strip 会把 `: unknown` 注解替换为等长空白，
+  // 网关按「逗号切分 + trim + 纯标识符且唯一」校验；默认值/解构/rest 会被拒绝）。
+  const srcParamNames = (fn: Function): string[] => {
+    const source = Function.prototype.toString.call(fn);
+    const open = source.indexOf("(");
+    const close = source.indexOf(")", open + 1);
+    const body = source.slice(open + 1, close).trim();
+    return body.length === 0 ? [] : body.split(",").map((p) => p.trim());
+  };
+  const proto = UsageStatsService.prototype as any;
+  const names = srcParamNames(proto.overview);
+  assert.equal(names.length, 1, "overview 必须是单一业务参数");
+  assert.match(names[0], /^[$A-Z_a-z][$\w]*$/u, "参数必须是纯标识符（无默认值/解构/rest/注解残留逗号）");
+  assert.deepEqual(names, ["filter"], "wire 参数名 = 客户端 descriptor 的 name（隐式契约）");
+});
+
+test("applyCordis：provide 注册 + 绑定可被 validateBinding 语义接受", () => {
+  const provided: Record<string, unknown> = {};
+  const logs: string[] = [];
+  const ctx: StubCtx = {
+    reflect: {
+      provide: (name: string, value: unknown) => {
+        provided[name] = value;
+        return () => delete provided[name];
+      },
+    },
+    inject: () => {},
+    logger: { info: (msg: string) => logs.push(msg) },
+  };
+  const svc = applyCordis(ctx, {});
+  assert.equal(provided.usageStats, svc);
+  const b = svc.typertRemote;
+  assert.equal(b.service, svc, "binding.service 必须 === receiver 本体（validateBinding 比对）");
+  assert.equal(b.serviceKey, "usageStats");
+  assert.equal(b.namespace, "usageStats");
+});
+
+test("真实链路：overview 出数 + 维度过滤 + 热缓存", { skip: existsSync(ROOT) ? false : "无会话目录" }, async () => {
+  const ctx: StubCtx = { reflect: { provide: () => () => {} }, logger: undefined };
+  const svc = applyCordis(ctx, {});
+  const o = await svc.overview({});
+  assert.ok(o.totals.requests > 0);
+  assert.equal(typeof o.hitRate, "number", "真实数据缓存字段有上报");
+  assert.ok(o.byModel.length > 0);
+  assert.equal("cost" in o, false, "v4 起 Overview 不再携带费用/按天/消息口径");
+  // 维度过滤：不存在的模型 → 空视图；存在的首行模型 → 非空且只含该键
+  const empty = await svc.overview({ model: "no/such-model-xyz" });
+  assert.equal(empty.totals.requests, 0);
+  assert.equal(empty.byModel.length, 0);
+  const first = o.byModel[0]!;
+  const one = await svc.overview({ model: first.key });
+  assert.equal(one.totals.requests, first.requests, "全键过滤应命中该模型行");
+  assert.equal(one.byModel.length, 1);
+  const prov = await svc.overview({ provider: first.provider });
+  assert.ok(prov.totals.requests >= first.requests, "provider 过滤是其模型并集");
+  // 热缓存：第二次 overview 不重新解码
+  const t0 = Date.now();
+  await svc.overview({});
+  assert.ok(Date.now() - t0 < 500, "热缓存 overview 应亚秒返回");
+});

package/tests/fold.test.ts

@@ -0,0 +1,122 @@
+/** 折叠与聚合口径测试：fixture 驱动（含重试替换、缓存归因、命中率 null 口径、日期窗口）。
+ *  v4 起聚合面收缩为纯 token 统计：消息数 / 按天 / 费用全部移出 Overview（UI 无消费者）；
+ *  scanner 的 SessionMeta 计数解析保留（会话画像本身仍有语义，由本文件的 foldJsonl 用例看护）。 */
+import test from "node:test";
+import assert from "node:assert/strict";
+import { foldJsonl, localDate } from "../src/scanner.ts";
+import { buildOverview, hitRate, normalizeRange } from "../src/aggregate.ts";
+
+const DAY = "2026-09-19";
+const T = Date.parse(`${DAY}T08:00:00`); // 本地时区
+
+function line(type: string, seq: number, extra: Record<string, unknown> = {}): string {
+  return JSON.stringify({ type, seq, time: T + seq * 1000, ...extra });
+}
+
+const FIXTURE = [
+  line("session", 0, { id: "s-1", cwd: "/w/测试", createdAt: T, delegationDepth: 1, origin: { parentSession: "p" } }),
+  line("session/title", 1, { data: { title: "测试会话" } }),
+  line("turn/start", 2, { data: { turn: 1 } }),
+  line("step/start", 3, { data: { turn: 1, step: 1 } }),
+  line("request/header", 4, { data: { header: { config: { provider: "buzz", model: "qwen-x" } } } }),
+  line("assistant/message", 5, { data: { usage: { inputTokens: 100, outputTokens: 20, cacheReadTokens: 800, cacheWriteTokens: 50, totalTokens: 970 } } }),
+  line("llm/retry-started", 6, { data: { retryId: "r1", turn: 1, step: 2, retry: 1 } }),
+  line("step/start", 7, { data: { turn: 1, step: 2 } }),
+  line("request/header", 8, { data: { header: { config: { provider: "buzz", model: "qwen-x" } } } }),
+  // step2 第一次样本（重试场景：step/start 重发）
+  line("assistant/message", 9, { data: { usage: { inputTokens: 111, outputTokens: 1, totalTokens: 112 } } }),
+  line("llm/retry-started", 10, { data: { retryId: "r1", turn: 1, step: 2, retry: 2 } }),
+  line("assistant/message", 11, { data: { usage: { inputTokens: 120, outputTokens: 30, cacheReadTokens: 400, totalTokens: 550 } } }),
+  // 无 header 会话片段：归 unknown
+  line("session", 12, { id: "s-2", cwd: "/w/2", createdAt: T }),
+  line("assistant/message", 13, { data: { usage: { inputTokens: 5, outputTokens: 5, totalTokens: 10 } } }),
+].join("\n");
+
+test("foldJsonl：折叠数量、重试取末条、unknown 模型、子代理标记", () => {
+  const { facts, meta } = foldJsonl("hint", FIXTURE);
+  assert.equal(facts.length, 3, "s1 step1 + s1 step2(末条) + s2");
+  const step2 = facts.find((f) => f.scope === "s-1:1:2");
+  assert.equal(step2?.input, 120, "重试同 scope 只留末条样本");
+  assert.equal(step2?.cacheWrite, 0);
+  const s2 = facts.find((f) => f.sessionId === "s-2");
+  assert.equal(s2?.model, "unknown");
+  assert.equal(s2?.date, localDate(T + 13000));
+  // meta 是「最后一条 session 行」——s-2；s-1 的 meta 由聚合层按 fold 处理，此处只验证解析不崩
+  assert.equal(meta?.sessionId, "s-2");
+});
+
+/** foldJsonl 单 fold 场景（s-1 单独一份）供聚合断言。 */
+const FOLD_S1 = foldJsonl("hint", FIXTURE.split("\n").slice(0, 12).join("\n"));
+const FOLD_S2 = foldJsonl("hint", [FIXTURE.split("\n")[0].replace("s-1", "s-2x"), FIXTURE.split("\n")[12], FIXTURE.split("\n")[13]].join("\n"));
+
+test("buildOverview：总计/命中率/byModel/会话数", () => {
+  const o = buildOverview([FOLD_S1], {});
+  assert.equal(o.totals.requests, 2);
+  assert.equal(o.totals.input, 220);
+  assert.equal(o.totals.output, 50);
+  assert.equal(o.totals.cacheRead, 1200);
+  assert.equal(o.totals.cacheWrite, 50);
+  assert.equal(o.totals.total, 1520);
+  assert.ok(Math.abs(o.hitRate! - 1200 / 1420) < 1e-9);
+  assert.equal(o.byModel.length, 1);
+  assert.equal(o.byModel[0].key, "buzz/qwen-x");
+  assert.equal(o.sessionCount, 1);
+  // 死字段回归锁：v4 移除的口径不得借尸还魂。
+  assert.equal("cost" in o, false);
+  assert.equal("byDay" in o, false);
+  assert.equal("messages" in o, false);
+  assert.equal("configuredPrices" in o, false);
+});
+
+test("命中率口径：缓存字段未上报 → null（UI 显示“—”），空分母 → null", () => {
+  const o = buildOverview([FOLD_S2], {});
+  // s-2x 的 usage 完全没报 cacheReadTokens/cacheWriteTokens → 无命中率口径
+  assert.equal(o.hitRate, null);
+  assert.equal(hitRate({ requests: 0, input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0, reportsCache: false }), null);
+});
+
+test("normalizeRange：非法值丢弃、倒挂交换、model/provider 只收非空字符串", () => {
+  assert.deepEqual(normalizeRange({ from: "2026-09-01", to: "bad" }), { from: "2026-09-01" });
+  assert.deepEqual(normalizeRange({ from: "2026-09-10", to: "2026-09-01" }), { from: "2026-09-01", to: "2026-09-10" });
+  assert.deepEqual(normalizeRange({ model: "a/b", provider: " ", n: 3 }), { model: "a/b" });
+});
+
+test("buildOverview：model/provider 过滤在 fact 层生效", () => {
+  const full = buildOverview([FOLD_S1, FOLD_COUNTS], {});
+  assert.equal(full.totals.requests, 3);
+  const byModel = buildOverview([FOLD_S1, FOLD_COUNTS], { model: "buzz/qwen-x" });
+  assert.equal(byModel.totals.requests, 3, "全键匹配 s-1 两条 + s-9 一条");
+  assert.equal(byModel.byModel.length, 1);
+  assert.equal(byModel.sessionCount, 2);
+  const bare = buildOverview([FOLD_S1, FOLD_S2], { model: "qwen-x" });
+  assert.equal(bare.totals.requests, 2, "裸 model 兜底匹配");
+  const prov = buildOverview([FOLD_S1, FOLD_S2], { provider: "unknown" });
+  assert.equal(prov.totals.requests, 1, "provider 段精确匹配 s-2x");
+  assert.equal(prov.byModel[0].key, "unknown/unknown");
+});
+
+/* ---------------- 会话级计数（scanner SessionMeta 画像，聚合层已不消费） ---------------- */
+
+/** 覆盖 user/message、tool/call、无 usage 的 assistant/message 三类计数行的独立 fixture。 */
+const FIXTURE_COUNTS = [
+  line("session", 0, { id: "s-9", cwd: "/w/c", createdAt: T }),
+  line("user/message", 1, { data: { content: "你好" } }),
+  line("turn/start", 2, { data: { turn: 1 } }),
+  line("step/start", 3, { data: { turn: 1, step: 1 } }),
+  line("request/header", 4, { data: { header: { config: { provider: "buzz", model: "qwen-x" } } } }),
+  line("assistant/message", 5, { data: { usage: { inputTokens: 10, outputTokens: 2, cacheReadTokens: 30, totalTokens: 42 } } }),
+  line("tool/call", 6, { data: { name: "bash" } }),
+  line("tool/call", 7, { data: { name: "read" } }),
+  line("user/message", 8, { data: { content: "继续" } }),
+  // 无 usage 的 assistant 行：计消息数，但不出 usage 事实
+  line("assistant/message", 9, { data: { content: "收尾" } }),
+].join("\n");
+
+const FOLD_COUNTS = foldJsonl("hint", FIXTURE_COUNTS);
+
+test("foldJsonl：三计数（user/assistant/tool），无 usage 的 assistant 也计数", () => {
+  assert.equal(FOLD_COUNTS.meta?.userMessages, 2);
+  assert.equal(FOLD_COUNTS.meta?.assistantMessages, 2);
+  assert.equal(FOLD_COUNTS.meta?.toolCalls, 2);
+  assert.equal(FOLD_COUNTS.facts.length, 1, "无 usage 行不产事实");
+});

package/tests/realscan.test.ts

@@ -0,0 +1,24 @@
+/** 真实数据集成测试：全局扫描本机 DSH 会话目录（增量多帧解码），断言事实非空 + 存量持久化生效。
+ *  无会话目录时跳过；本测试与 fold.test.ts 的 fixture 测试互补（golden 口径在 fixture，链路在真数据）。 */
+import test from "node:test";
+import assert from "node:assert/strict";
+import { existsSync } from "node:fs";
+import { sessionsRoot } from "../src/scanner.ts";
+import { scanFolds, buildOverview } from "../src/aggregate.ts";
+import { FoldStore } from "../src/store.ts";
+
+const root = sessionsRoot();
+test("真实会话：多帧解码出非零事实，二次扫描 0 重载且 cache 落盘", { skip: existsSync(root) ? false : "无 DSH 会话目录" }, async () => {
+  const store = new FoldStore(root);
+  const t0 = Date.now();
+  const first = await scanFolds(root, store);
+  assert.ok(first.files > 0, "至少应发现一个会话文件");
+  const o = buildOverview(first.folds, {});
+  assert.ok(o.totals.requests > 0, "真实数据应折叠出非零 usage 事实（多帧解码生效）");
+  assert.ok(o.totals.input + o.totals.output > 0);
+  assert.equal("cost" in o, false, "v4 契约：真实链路输出同样不含费用字段");
+  assert.ok(Date.now() - t0 < 60_000, "首扫应远小于 60s 挂起阈值");
+  // 落盘路径断言在 scan.test.ts（tmp 目录，可控）；此处不重复——真实 home 可能处于只读沙箱。
+  const second = await scanFolds(root, store);
+  assert.ok(second.reloaded <= 5, `未变文件应全复用（实况写入导致的推进 ${second.reloaded} 个，容忍 ≤5）`);
+});

package/tests/scan.test.ts

@@ -0,0 +1,168 @@
+/** 增量扫描正确性：zstd 帧边界（RFC 8878 walker）+ foldFrom 与全量重放等价 + FoldStore 持久化/失效。
+ *  多帧 fixture 用真 zstd CLI 拼接生成（无 CLI 环境整体 skip——walker 的字节语义只有真帧能说清）。 */
+import test from "node:test";
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdtemp, mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { foldFrom, foldJsonl, foldSnapshot, frameSpans, frameWatermark, newFoldState } from "../src/scanner.ts";
+import { FoldStore, VERSION } from "../src/store.ts";
+
+let ZSTD_OK = false;
+try {
+  ZSTD_OK = execFileSync("zstd", ["--version"], { encoding: "utf8" }).includes("v");
+} catch {
+  ZSTD_OK = false;
+}
+
+const SESSION_LINES = [
+  JSON.stringify({ type: "session", time: Date.now(), id: "s-inc", cwd: "/w", createdAt: Date.now() }),
+  JSON.stringify({ type: "turn/start", time: Date.now(), data: { turn: 1 } }),
+  JSON.stringify({ type: "request/header", time: Date.now(), data: { header: { config: { provider: "prov-a", model: "m-1" } } } }),
+  JSON.stringify({ type: "assistant/message", time: Date.now(), data: { usage: { inputTokens: 7, outputTokens: 9, cacheReadTokens: 3 } } }),
+];
+const MORE_LINES = [
+  JSON.stringify({ type: "tool/call", time: Date.now(), data: { name: "bash" } }),
+  JSON.stringify({ type: "user/message", time: Date.now(), data: { content: "go" } }),
+  JSON.stringify({ type: "turn/start", time: Date.now(), data: { turn: 2 } }),
+  JSON.stringify({ type: "request/header", time: Date.now(), data: { header: { config: { provider: "prov-a", model: "m-1" } } } }),
+  // 与第一轮同 scope 的重试样本 → last-wins
+  JSON.stringify({ type: "assistant/message", time: Date.now(), data: { usage: { inputTokens: 1, outputTokens: 2 } } }),
+  JSON.stringify({ type: "step/start", time: Date.now(), data: { turn: 2, step: 1 } }),
+  JSON.stringify({ type: "assistant/message", time: Date.now(), data: { usage: { inputTokens: 100, outputTokens: 50 } } }),
+];
+
+let TMP = "";
+function newTmpFile(): string {
+  return join(TMP, `f-${Math.random().toString(36).slice(2)}.zst`);
+}
+
+async function compressFrame(text: string): Promise<Buffer> {
+  const src = newTmpFile();
+  const dst = newTmpFile();
+  await writeFile(src, text);
+  execFileSync("zstd", ["-f", "--no-check", "-1", src, "-o", dst]);
+  return readFile(dst);
+}
+
+test("zstd 帧 walker：多帧拼接的边界识别、半帧截断、垃圾即停", { skip: ZSTD_OK ? false : "无 zstd CLI" }, async () => {
+  TMP = await mkdtemp(join(tmpdir(), "usg-walk-"));
+  const f1 = await compressFrame(SESSION_LINES.join("\n") + "\n");
+  const f2 = await compressFrame(MORE_LINES.join("\n") + "\n");
+  const joined = Buffer.concat([f1, f2]);
+  const spans = frameSpans(joined);
+  assert.equal(spans.length, 2);
+  assert.deepEqual(spans[0], [0, f1.length]);
+  assert.deepEqual(spans[1], [f1.length, joined.length]);
+  assert.equal(frameWatermark(joined), joined.length);
+  // 截半帧：水位停在完整帧边界
+  const cut = joined.subarray(0, f1.length + Math.floor(f2.length / 2));
+  assert.equal(frameWatermark(cut), f1.length);
+  assert.equal(frameSpans(cut).length, 1);
+  // 尾追垃圾：walker 即停，不吞好帧
+  const dirty = Buffer.concat([joined, Buffer.from([1, 2, 3, 4, 5])]);
+  assert.deepEqual(frameSpans(dirty).length, 2);
+});
+
+test("foldFrom 增量重放 === 全量 foldJsonl（两帧 + 跨帧半行），逐字段等价", { skip: ZSTD_OK ? false : "无 zstd CLI" }, async () => {
+  TMP = TMP || (await mkdtemp(join(tmpdir(), "usg-inc-")));
+  // 故意把 MORE_LINES[0] 从中间劈开：前半压进帧1尾、后半作为帧2头（跨帧行必须由 tail 机制缝合）。
+  const half = Math.floor(MORE_LINES[0].length / 2);
+  const groupA = [...SESSION_LINES, MORE_LINES[0].slice(0, half)];
+  const groupB = [MORE_LINES[0].slice(half), ...MORE_LINES.slice(1)];
+  const f1 = await compressFrame(groupA.join("\n") + "\n");
+  const f2 = await compressFrame(groupB.join("\n") + "\n");
+  const file = join(TMP, "session.v3.jsonl.zstd");
+  await writeFile(file, Buffer.concat([f1, f2]));
+
+  // 全量基准
+  const full = foldJsonl("hint", [...groupA, ...groupB].join("\n") + "\n");
+
+  // 增量路径 1：从 0 开始吃两帧
+  const s1 = newFoldState("hint");
+  await foldFrom(file, s1, 0);
+  assert.deepEqual(foldSnapshot(s1), full, "增量自零 === 全量");
+
+  // 增量路径 2：只有帧1 时推进（水位=帧1尾），追加帧2 后再从水位续吃
+  const file2 = join(TMP, "session.v3.jsonl.b.zstd");
+  await writeFile(file2, f1);
+  const s2 = newFoldState("hint");
+  const wm1 = await foldFrom(file2, s2, 0);
+  assert.equal(wm1, f1.length, "单帧文件水位精确");
+  await writeFile(file2, Buffer.concat([f1, f2]));
+  const wm2 = await foldFrom(file2, s2, wm1);
+  assert.equal(wm2, f1.length + f2.length, "追加后水位推进到全帧尾");
+  assert.deepEqual(foldSnapshot(s2), full, "分段推进与一次到位等价（重试 last-wins + 计数单调）");
+});
+
+test("FoldStore：冷启动全量 → 未变复用零解压 → 追加走增量 → 持久化重启复用", { skip: ZSTD_OK ? false : "无 zstd CLI" }, async () => {
+  TMP = TMP || (await mkdtemp(join(tmpdir(), "usg-store-")));
+  const root = join(TMP, "ws", "s-inc");
+  const file = join(root, "session.v3.jsonl.zstd");
+  await mkdir(root, { recursive: true });
+  const f1 = await compressFrame(SESSION_LINES.join("\n") + "\n");
+  const f2 = await compressFrame(MORE_LINES.join("\n") + "\n");
+  await writeFile(file, f1);
+
+  const store = new FoldStore(join(TMP, "ws"));
+  const st1 = await stat(file);
+  const foldA = await store.foldFor(file, { size: st1.size, mtimeMs: st1.mtimeMs, ino: st1.ino });
+  assert.equal(foldA.facts.length, 1);
+  assert.equal(store.rows.get(file)!.bytes, f1.length, "首轮记录真实帧水位");
+
+  // 未变：直接复用（行对象同一引用 = 0 解压）
+  const foldA2 = await store.foldFor(file, { size: st1.size, mtimeMs: st1.mtimeMs, ino: st1.ino });
+  assert.equal(foldA2.facts, foldA.facts, "未变文件复用存量 fold 引用");
+
+  // 追加第二帧 → 增量推进，等价全量
+  await writeFile(file, Buffer.concat([f1, f2]));
+  const st2 = await stat(file);
+  const foldB = await store.foldFor(file, { size: st2.size, mtimeMs: st2.mtimeMs, ino: st2.ino });
+  const expected = foldJsonl("s-inc", SESSION_LINES.join("\n") + "\n" + MORE_LINES.join("\n") + "\n");
+  assert.deepEqual(
+    foldB.facts.map((f) => `${f.scope}:${f.input}`),
+    expected.facts.map((f) => `${f.scope}:${f.input}`),
+  );
+  assert.equal(foldB.meta!.userMessages, 1);
+  assert.equal(store.rows.get(file)!.bytes, f1.length + f2.length, "增量水位推进到文件尾");
+
+  // 落盘 + 新实例（= host 重启）复用存量
+  await store.flush(new Set([file]));
+  const reopened = new FoldStore(join(TMP, "ws"));
+  await reopened.load();
+  assert.ok(reopened.rows.has(file), "持久化行恢复");
+  const foldC = await reopened.foldFor(file, { size: st2.size, mtimeMs: st2.mtimeMs, ino: st2.ino });
+  assert.equal(foldC.facts.length, expected.facts.length, "重启后未变文件 0 重解出同数事实");
+});
+
+test("版本门：低于当前 VERSION 的存量 payload 整体作废冷重扫（unknown facts 冻结教训的保险丝）", { skip: ZSTD_OK ? false : "无 zstd CLI" }, async () => {
+  const T = await mkdtemp(join(tmpdir(), "usg-ver-")); // 独立 tmp：cache 文件不与其他用例共享
+  const ws = join(T, "ws-ver");
+  const root = join(ws, "s-ver");
+  const file = join(root, "session.v3.jsonl.zstd");
+  await mkdir(root, { recursive: true });
+  await writeFile(file, await compressFrame(SESSION_LINES.join("\n") + "\n"));
+  const store = new FoldStore(ws);
+  const st = await stat(file);
+  await store.foldFor(file, { size: st.size, mtimeMs: st.mtimeMs, ino: st.ino });
+  await store.flush(new Set([file]));
+
+  // 盘上必须是当前版本（flush 写 VERSION，不是历史常数）。constructor(root=sessions 区) → cache 落在其父级。
+  const cacheFile = join(T, "cache", "usage-stats.folds.json");
+  const payload = JSON.parse(await readFile(cacheFile, "utf8"));
+  assert.equal(payload.version, VERSION, "落盘 payload 带当前版本");
+  assert.ok(payload.version >= 2, "版本门至少为 2（v1 = 曾冻结 unknown facts 的带病存量）");
+
+  // 手动降级 = 模拟旧版折叠逻辑的存量：load 必须整体拒收，行清零。
+  payload.version = 1;
+  await writeFile(cacheFile, JSON.stringify(payload));
+  const cold = new FoldStore(ws);
+  await cold.load();
+  assert.equal(cold.rows.size, 0, "旧版本 payload 不得复用任何行");
+  // 拒收后重扫 = 全量重建并以当前版本回写。
+  const fold = await cold.foldFor(file, { size: st.size, mtimeMs: st.mtimeMs, ino: st.ino });
+  assert.equal(fold.facts.length, 1, "冷重扫产出正常事实");
+  await cold.flush(new Set([file]));
+  assert.equal(JSON.parse(await readFile(cacheFile, "utf8")).version, VERSION, "回写恢复当前版本");
+});