@modusensus/dsh-mneme 0.12.0 → 0.14.0-beta.1

package/test/wiki-claims.test.js

@@ -0,0 +1,194 @@
+// claims 粒度的失效判定（借 openwiki 的 Grounded Claims，issue #607 后续）。
+//
+// 锁的是「结论失准 vs 锚点错位」这条分界线：把 shifted 混进 touched，面板就会对一堆
+// 只是行号偏了几行的结论喊「要重写」，喊几次就没人信了——这是本模块存在的全部理由。
+// 还锁三种「算不出来」不许冒充「没事」：基线认不出、git 目录不可读、空 diff。
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+import { parseDiffRanges, assessClaims, summarizeClaims, diffSince } from "../src/wiki/claims.js";
+
+const DIFF = [
+  "diff --git a/src/a.js b/src/a.js",
+  "--- a/src/a.js",
+  "+++ b/src/a.js",
+  "@@ -7,3 +7,4 @@ export function x() {",
+  "-old",
+  "+new",
+  "+extra",
+  "diff --git a/src/gone.js b/src/gone.js",
+  "--- a/src/gone.js",
+  "+++ /dev/null",
+  "@@ -1,2 +0,0 @@",
+  "-a",
+  "-b",
+].join("\n");
+
+test("parseDiffRanges：hunk 头取新旧两侧坐标，/dev/null 进 deleted", () => {
+  const d = parseDiffRanges(DIFF);
+  assert.deepEqual([...d.files.keys()], ["src/a.js"]);
+  assert.deepEqual(d.files.get("src/a.js"), [{ oldStart: 7, oldCount: 3, newStart: 7, newCount: 4 }]);
+  assert.deepEqual(d.deleted, ["src/gone.js"]);
+  // `@@ -c +c @@` 不带计数时按 1 算（`+c` 与 `+c,1` 同义；只有显式 `,0` 才是纯增删）。
+  const one = parseDiffRanges("diff --git a/x b/x\n--- a/x\n+++ b/x\n@@ -3 +3,2 @@\n-a\n+b\n+c\n");
+  assert.deepEqual(one.files.get("x"), [{ oldStart: 3, oldCount: 1, newStart: 3, newCount: 2 }]);
+});
+
+test("assessClaims：touched / shifted / deleted / unverifiable 四档分开，未变的不报", () => {
+  const d = parseDiffRanges(DIFF);
+  const claims = [
+    { id: 1, statement: "A", sourcePath: "src/a.js", startLine: 8, endLine: 9, pageSlug: "p1" },
+    { id: 2, statement: "B", sourcePath: "src/a.js", startLine: 2, endLine: 3, pageSlug: "p1" },
+    { id: 3, statement: "C", sourcePath: "src/gone.js", startLine: 1, endLine: 1, pageSlug: "p2" },
+    { id: 4, statement: "D", sourcePath: "src/a.js", pageSlug: "p1" },
+    { id: 5, statement: "E", sourcePath: "src/untouched.js", startLine: 1, endLine: 1, pageSlug: "p3" },
+  ];
+  const out = assessClaims(claims, d);
+  assert.deepEqual(out.map((c) => [c.id, c.reason]), [
+    [1, "touched"],
+    [2, null],
+    [3, "deleted"],
+    [4, "unverifiable"],
+    [5, null],
+  ]);
+  assert.equal(out[0].shift, 0, "相交时 shift 记的是「相交之前累计了多少行");
+});
+
+test("assessClaims：区间没被碰但上方有增删 → shifted 带 shift，不升级成 touched", () => {
+  // 第 2 行插了一行 → 第 10 行的结论内容还在，只是行号往后挪 1。
+  const diff = parseDiffRanges("diff --git a/y b/y\n--- a/y\n+++ b/y\n@@ -2,0 +3,1 @@\n+inserted\n");
+  const [c] = assessClaims([{ id: 9, statement: "S", sourcePath: "y", startLine: 10, endLine: 11, pageSlug: "p" }], diff);
+  assert.equal(c.reason, "shifted");
+  assert.equal(c.shift, 1);
+});
+
+test("assessClaims：纯插入落在结论行区间内部也算 touched，插在首行之前只是 shifted", () => {
+  // @@ -5,0 +6,1 @@ 表示「旧第 5 行之后插入一行」。结论占旧第 4-6 行时，新行插在
+  // 第 5 与第 6 行之间——结论的原文区间被切开了，不能报「没事」。
+  const inside = parseDiffRanges("diff --git a/z b/z\n--- a/z\n+++ b/z\n@@ -5,0 +6,1 @@\n+inserted\n");
+  const [hit] = assessClaims([{ id: 1, statement: "S", sourcePath: "z", startLine: 4, endLine: 6, pageSlug: "p" }], inside);
+  assert.equal(hit.reason, "touched", "插在结论区间内部：原文被切断");
+  // 插在结论首行之前（旧第 2 行之后）只是把整个区间推下去，内容没变。
+  const above = parseDiffRanges("diff --git a/z b/z\n--- a/z\n+++ b/z\n@@ -2,0 +3,1 @@\n+inserted\n");
+  const [pushed] = assessClaims([{ id: 2, statement: "S", sourcePath: "z", startLine: 4, endLine: 6, pageSlug: "p" }], above);
+  assert.equal(pushed.reason, "shifted");
+  assert.equal(pushed.shift, 1);
+  // 单行结论（start === end）边界：插在它上面一行 → shifted（内容没动，行号后移）；
+  // 插在它下面 → null（既不碰到也不移动）。把「后面插」算成 shifted 会让一堆没变的
+  // 结论被喊去复核。
+  const [singleAbove] = assessClaims([{ id: 3, statement: "S", sourcePath: "z", startLine: 4, endLine: 4, pageSlug: "p" }], above);
+  assert.equal(singleAbove.reason, "shifted", "单行结论上方插一行，内容没动只是后移");
+  assert.equal(singleAbove.shift, 1);
+  const [singleBelow] = assessClaims([{ id: 4, statement: "S", sourcePath: "z", startLine: 4, endLine: 4, pageSlug: "p" }], inside);
+  assert.equal(singleBelow.reason, null, "单行结论下方插一行，既不碰到也不移动");
+});
+
+test("parseDiffRanges + assessClaims：git 八进制转义的中文路径要还原（否则漏判成没事）", () => {
+  // core.quotepath 默认开着，中文路径在 diff 里长这样：
+  //   --- "a/\344\270\255\346\226\207.js"
+  // 只脱引号不解转义的话，归一出来的字符串永远对不上库里存的 source_path，
+  // 这些文件上的结论就再也判不成 touched——不是报错，是静默漏判。
+  const quoted = '"a/\\344\\270\\255\\346\\226\\207.js"';
+  const diff = parseDiffRanges(
+    "diff --git " + quoted + " " + quoted + "\n"
+    + "--- " + quoted + "\n"
+    + "+++ " + quoted + "\n"
+    + "@@ -2,2 +2,2 @@\n-a\n+b\n"
+  );
+  assert.deepEqual([...diff.files.keys()], ["中文.js"], "八进制转义要还原成真文件名");
+  const [c] = assessClaims([{ id: 1, statement: "S", sourcePath: "中文.js", startLine: 2, endLine: 3, pageSlug: "p" }], diff);
+  assert.equal(c.reason, "touched", "中文名文件上的结论必须能判成 touched");
+});
+
+test("diffSince：重命名按「删旧 + 增新」处理，旧路径上的结论判成 deleted", () => {
+  const root = mkdtempSync(join(tmpdir(), "choro-claims-rename-"));
+  try {
+    mkdirSync(join(root, "src"), { recursive: true });
+    // 中文名一起测：rename 与 quotepath 两条转义路径都走一遍。
+    writeFileSync(join(root, "src", "旧名.js"), "export const a = 1;\nexport const b = 2;\n", "utf8");
+    execFileSync("git", ["init", "-b", "main"], { cwd: root, stdio: "pipe" });
+    execFileSync("git", ["-c", "user.email=t@t", "-c", "user.name=t", "add", "-A"], { cwd: root, stdio: "pipe" });
+    execFileSync("git", ["-c", "user.email=t@t", "-c", "user.name=t", "commit", "-m", "init", "--no-gpg-sign"], { cwd: root, stdio: "pipe" });
+    const base = execFileSync("git", ["rev-parse", "HEAD"], { cwd: root, encoding: "utf8" }).trim();
+    execFileSync("git", ["mv", "src/旧名.js", "src/新名.js"], { cwd: root, stdio: "pipe" });
+    execFileSync("git", ["-c", "user.email=t@t", "-c", "user.name=t", "commit", "-m", "rename", "--no-gpg-sign"], { cwd: root, stdio: "pipe" });
+    const head = execFileSync("git", ["rev-parse", "HEAD"], { cwd: root, encoding: "utf8" }).trim();
+    const d = diffSince(root, base, head);
+    assert.equal(d.ok, true);
+    // 不传 --no-renames 时 git 只输出 `rename from/to`，files 与 deleted 里都没有这条
+    // 路径，结论会被静默判成 untouched（漏判）。关掉检测后旧路径必须进 deleted。
+    assert.ok(d.deleted.includes("src/旧名.js"), "重命名后旧路径上的结论必须判成 deleted");
+    const [c] = assessClaims([{ id: 1, statement: "S", sourcePath: "src/旧名.js", startLine: 1, endLine: 2, pageSlug: "p" }], d);
+    assert.equal(c.reason, "deleted");
+  } finally {
+    for (let i = 0; i < 5; i++) {
+      try { rmSync(root, { recursive: true, force: true }); break; } catch { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 200); }
+    }
+  }
+});
+
+test("summarizeClaims：按页聚合，hasT1 却零 claims 的页单独记 inconsistent", () => {
+  const d = parseDiffRanges(DIFF);
+  const claims = [
+    { id: 1, statement: "A", sourcePath: "src/a.js", startLine: 8, endLine: 9, pageSlug: "p1", pageTitle: "P1" },
+    { id: 3, statement: "C", sourcePath: "src/gone.js", startLine: 1, endLine: 1, pageSlug: "p2", pageTitle: "P2" },
+  ];
+  const s = summarizeClaims(claims, d, {
+    pages: [
+      { slug: "p1", title: "P1", hasT1: true },
+      { slug: "p2", title: "P2", hasT1: true },
+      { slug: "p3", title: "P3", hasT1: true },
+      { slug: "p4", title: "P4", hasT1: false },
+    ],
+  });
+  assert.deepEqual(s.pages.map((p) => p.slug), ["p1", "p2", "p3", "p4"], "有风险的排前面，干净的在后");
+  assert.equal(s.totals.claims, 2);
+  assert.equal(s.totals.atRiskClaims, 2);
+  assert.equal(s.totals.atRiskPages, 2);
+  assert.equal(s.totals.inconsistentPages, 1, "p3 有 T1 段但库里零 claims：T1 落盘非原子的残局");
+  assert.equal(s.pages.find((p) => p.slug === "p4").inconsistent, false, "没 T1 段也没 claims 是正常骨架页");
+});
+
+test("summarizeClaims：diff 为 null（算不出来）时一条都不判，交回执 honesty 给调用方", () => {
+  const claims = [{ id: 1, statement: "A", sourcePath: "src/a.js", startLine: 1, endLine: 1, pageSlug: "p1" }];
+  const s = summarizeClaims(claims, null, { pages: [{ slug: "p1", title: "P1", hasT1: true }] });
+  assert.equal(s.totals.atRiskClaims, 0, "不能把「没算」说成「有风险」");
+  assert.equal(s.totals.claims, 1);
+});
+
+test("diffSince：基线非法 / 不是 git 目录 / 真 diff 三态分开", () => {
+  const bad = diffSince(tmpdir(), "not-a-sha", "abc1234");
+  assert.equal(bad.ok, false);
+  assert.equal(bad.reason, "baseline-unreadable");
+
+  const root = mkdtempSync(join(tmpdir(), "choro-claims-"));
+  try {
+    mkdirSync(join(root, "src"), { recursive: true });
+    writeFileSync(join(root, "src", "a.js"), "export const a = 1;\n", "utf8");
+    // 还没 git init：必须如实报算不出来，不许返回空 diff 冒充「没变」。
+    const notRepo = diffSince(root, "0123456", "0123456");
+    assert.equal(notRepo.ok, false);
+    assert.equal(notRepo.reason, "diff-failed");
+
+    execFileSync("git", ["init", "-b", "main"], { cwd: root, stdio: "pipe" });
+    execFileSync("git", ["-c", "user.email=t@t", "-c", "user.name=t", "add", "-A"], { cwd: root, stdio: "pipe" });
+    execFileSync("git", ["-c", "user.email=t@t", "-c", "user.name=t", "commit", "-m", "init", "--no-gpg-sign"], { cwd: root, stdio: "pipe" });
+    const base = execFileSync("git", ["rev-parse", "HEAD"], { cwd: root, encoding: "utf8" }).trim();
+    writeFileSync(join(root, "src", "a.js"), "export const a = 1;\nexport const b = 2;\n", "utf8");
+    execFileSync("git", ["-c", "user.email=t@t", "-c", "user.name=t", "commit", "-am", "more", "--no-gpg-sign"], { cwd: root, stdio: "pipe" });
+    const head = execFileSync("git", ["rev-parse", "HEAD"], { cwd: root, encoding: "utf8" }).trim();
+
+    const ok = diffSince(root, base, head);
+    assert.equal(ok.ok, true);
+    const [c] = assessClaims([{ id: 1, statement: "A", sourcePath: "src/a.js", startLine: 2, endLine: 2, pageSlug: "p" }], ok);
+    assert.equal(c.reason, "shifted", "第 1 行后追加一行 → 第 2 行结论行号后移");
+    assert.equal(c.shift, 1);
+  } finally {
+    for (let i = 0; i < 5; i++) {
+      try { rmSync(root, { recursive: true, force: true }); break; } catch { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 200); }
+    }
+  }
+});

package/test/wiki-cli-hint.test.js

@@ -0,0 +1,118 @@
+// dsh-mneme/test/wiki-cli-hint.test.js
+// issue #607 的回归锁：提示里那条命令必须真能粘贴就跑。
+//
+// 这条 issue 的病因不是「文案不好看」，是**给了一条跑不起来的命令**：插件装在
+// profile 依赖里，npm 只为全局安装把 shim 放进 PATH，用户照抄 dsh-mneme-choro
+// 必然 command not found。所以真正要锁的不是字符串长相，而是三件事：
+//   1) 推导出的入口在这个仓库里真实存在（下面的 existsSync 与实跑验证）；
+//   2) 推导不依赖调用方在第几层目录（src/ 与 lib/ 同层、src/wiki/ 在第二层、
+//      bin/ 在第一层）——写死层数会悄悄算错，而算错的表现正是又给一条跑不起来的命令；
+//   3) 找不到入口时返回 null 让调用方降级，而不是硬编一个假路径。
+//
+// 引号部分单独锁：安装路径带空格是常态（Windows 的 C:\Program Files\），
+// POSIX 路径带单引号也必须转义成 '\''，否则「带引号的命令」照样跑不起来。
+import test from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { choroCliCommand, choroCliCommandFrom, choroCliEntry } from "../src/wiki/cli-hint.js";
+
+const ENTRY_TAIL = join("bin", "dsh-mneme-choro.mjs");
+
+test("从包内任意深度都能推出同一个 CLI 入口（不按固定层数）", () => {
+  // 四个不同深度、且真实存在于本仓的模块位置；写死 dirname 次数的实现只会有
+  // 其中一部分对，这条断言就会红。
+  const froms = [
+    new URL("../package.json", import.meta.url), // test/  -> 1 层
+    new URL("../src/tools.js", import.meta.url), // src/   -> 1 层
+    new URL("../src/wiki/t1.js", import.meta.url), // src/wiki/ -> 2 层
+    new URL("../bin/dsh-mneme-choro.mjs", import.meta.url) // bin/ -> 0 层
+  ];
+  const entries = froms.map((u) => choroCliEntry(u.href));
+  for (const [i, entry] of entries.entries()) {
+    assert.equal(typeof entry, "string", "caller #" + i + " must resolve an entry");
+    assert.ok(existsSync(entry), "caller #" + i + " resolved a path that does not exist: " + entry);
+    assert.ok(entry.endsWith(ENTRY_TAIL), entry);
+  }
+  // 四条路径必须收敛到同一个入口，否则「同一份代码在不同文件里给出不同命令」
+  assert.equal(new Set(entries).size, 1);
+});
+
+test("推出来的入口是这个包自己的 bin（不是同名外来目录）", () => {
+  const entry = choroCliEntry(new URL("../src/wiki/t1.js", import.meta.url).href);
+  assert.ok(entry);
+  // 包根必须同时有 bin/ 与 package.json —— 这正是推导的两个条件，反过来验一遍
+  const pkgRoot = entry.slice(0, entry.length - ENTRY_TAIL.length - 1);
+  assert.ok(existsSync(join(pkgRoot, "package.json")), pkgRoot);
+  assert.equal(join(pkgRoot, ENTRY_TAIL), entry);
+});
+
+test("源码树被裁剪（找不到 bin 或 package.json）时返回 null，不硬编假路径", () => {
+  const dir = mkdtempSync(join(tmpdir(), "mneme-cli-hint-"));
+  try {
+    // 只有 bin/ 没有 package.json：可能是别人的同名 bin，不能认
+    mkdirSync(join(dir, "bin"), { recursive: true });
+    writeFileSync(join(dir, "bin", "dsh-mneme-choro.mjs"), "");
+    assert.equal(choroCliEntry(pathToFileURL(join(dir, "bin", "dsh-mneme-choro.mjs")).href), null);
+
+    // 补齐 package.json 就该认出来（证明上一条的红不是「永远返回 null」）
+    writeFileSync(join(dir, "package.json"), "{}");
+    assert.equal(
+      choroCliEntry(pathToFileURL(join(dir, "bin", "dsh-mneme-choro.mjs")).href),
+      join(dir, "bin", "dsh-mneme-choro.mjs")
+    );
+
+    // 只有 package.json 没有 bin/：`files` 少了 bin 的裁剪树，同样不能认
+    const bare = mkdtempSync(join(tmpdir(), "mneme-cli-hint-bare-"));
+    try {
+      writeFileSync(join(bare, "package.json"), "{}");
+      mkdirSync(join(bare, "src"), { recursive: true });
+      assert.equal(choroCliEntry(pathToFileURL(join(bare, "src", "tools.js")).href), null);
+    } finally {
+      rmSync(bare, { recursive: true, force: true });
+    }
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("命令带引号：Windows 双引号，POSIX 单引号（路径含空格与单引号都要能跑）", () => {
+  // Windows：安装路径带空格是常态，不加引号那条命令在 cmd 里会被拆成两段
+  assert.equal(
+    choroCliCommand("C:\\Program Files\\mneme\\bin\\dsh-mneme-choro.mjs", "<repo>", "win32"),
+    'node "C:\\Program Files\\mneme\\bin\\dsh-mneme-choro.mjs" <repo> --apply'
+  );
+  // POSIX：无空格时也加引号（统一形态，便于用户照着改）
+  assert.equal(
+    choroCliCommand("/opt/mneme/bin/dsh-mneme-choro.mjs", "<repo>", "linux"),
+    "node '/opt/mneme/bin/dsh-mneme-choro.mjs' <repo> --apply"
+  );
+  // POSIX：路径里有单引号，必须转成 '\''，否则 shell 把命令截断在引号处
+  assert.equal(
+    choroCliCommand("/opt/it's here/bin/dsh-mneme-choro.mjs", "<repo>", "linux"),
+    "node '/opt/it'\\''s here/bin/dsh-mneme-choro.mjs' <repo> --apply"
+  );
+  // 占位符原样保留（面板给 <仓库路径>，工具报错给 <repo>），不被引号逻辑吞掉
+  assert.equal(
+    choroCliCommandFrom(new URL("../src/tools.js", import.meta.url).href, "<仓库路径>", "win32").endsWith(" <仓库路径> --apply"),
+    true
+  );
+  // 入口缺失时整体返回 null —— 调用方据此降级，绝不输出半条命令
+  assert.equal(choroCliCommand(null, "<repo>", "win32"), null);
+  assert.equal(choroCliCommandFrom("not a url", "<repo>", "win32"), null);
+});
+
+test("真的能跑：用推导出的入口执行一次 --help（issue 的验收就是「用户能跑起来」）", () => {
+  const entry = choroCliEntry(new URL("../src/wiki/t1.js", import.meta.url).href);
+  assert.ok(entry);
+  // 用真实入口起一次进程：issue 的验收标准就是「用户照着这条命令能跑起来」，
+  const res = spawnSync(process.execPath, [entry, "--help"], { encoding: "utf8", timeout: 30000 });
+  assert.equal(res.status, 0, entry + " --help failed: " + (res.stderr || res.stdout));
+  assert.match(res.stdout, /--apply/);
+});
+  // 用真实入口起一次进程：issue 的验收标准就是「用户照着这条命令能跑起来」，
+  // 字符串层面的断言证明不了这件事。

package/test/wiki-provenance.test.js

@@ -0,0 +1,202 @@
+// ① 语义段溯源（verifiedBaseline / verifiedAt）的回归锁。
+//
+// 这一层要防的不是「少写一个字段」，而是两个具体的假象：
+// 1. **T1 晚于 T0 的误报**：claims 的行号是 T1 那一刻的代码树，全仓 git_baseline 是 T0 的。
+//    若拿全仓基线起算 diff，T1 之前就发生、claim 早已算进去的改动会被报成 touched
+//    ——面板上就是「明明没动过，却催你复核」。所以起点必须是每页自己的 verified_baseline。
+// 2. **T0 的确定性被污染**：verified 字段只由 T1 写。T0 一旦也写时间戳，
+//    「同状态两次 apply 逐字节相同」这条不变量就破了（测试 wiki-t0.test.js 里那条）。
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+import { runChoroT0, gitHead } from "../src/wiki/t0.js";
+import { createStore } from "../src/store.js";
+import { createChoroQueries } from "../src/wiki/queries.js";
+import { createT1 } from "../src/wiki/t1.js";
+import {
+  FM_VERIFIED_AT,
+  FM_VERIFIED_BASELINE,
+  readFrontmatterKey,
+  setFrontmatterKeys,
+  T1_SECTION_START,
+} from "../src/wiki/render.js";
+
+const FIXED_NOW = () => "2026-11-05T12:00:00.000Z";
+
+function makeFixture() {
+  const root = mkdtempSync(join(tmpdir(), "choro-prov-"));
+  writeFileSync(join(root, "package.json"), JSON.stringify({ name: "provfix", scripts: { test: "node --test" } }, null, 2) + "\n", "utf8");
+  mkdirSync(join(root, "src"), { recursive: true });
+  writeFileSync(join(root, "src", "a.js"), 'import { b } from "./b.js";\nexport const a = () => b();\n', "utf8");
+  writeFileSync(join(root, "src", "b.js"), "export const b = () => 1;\n", "utf8");
+  execFileSync("git", ["init", "-b", "main"], { cwd: root, stdio: "pipe" });
+  commit(root, "init");
+  return root;
+}
+
+function commit(root, message) {
+  execFileSync("git", ["-c", "user.email=t@t", "-c", "user.name=t", "add", "-A"], { cwd: root, stdio: "pipe" });
+  execFileSync("git", ["-c", "user.email=t@t", "-c", "user.name=t", "commit", "-m", message, "--no-gpg-sign"], { cwd: root, stdio: "pipe" });
+  return gitHead(root);
+}
+
+function rmTempBestEffort(dir) {
+  try {
+    rmSync(dir, { recursive: true, force: true });
+  } catch {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 200);
+    try { rmSync(dir, { recursive: true, force: true }); } catch { /* 留给系统清理 */ }
+  }
+}
+
+const GOOD_OUTPUT = JSON.stringify({
+  architecture: "src 模块承载核心导出面，a.js 依赖 b.js。",
+  convention: "导出全部用 export const 函数式风格。",
+  techStack: "纯 ESM，无框架。",
+  setup: "npm test。",
+  claims: [{ statement: "a.js 从 b.js 导入 b", kind: "architecture", sourcePath: "src/a.js", startLine: 1, endLine: 1 }],
+});
+
+// --- frontmatter 读写（页面格式层，与 T0/T1 无关的纯函数）---------------------
+
+test("setFrontmatterKeys：无则追加、有则覆盖、空值删键、无 frontmatter 原样返回", () => {
+  const page = "---\nchoro: v1\nslug: src\n---\n\n# 标题\n";
+  const added = setFrontmatterKeys(page, [[FM_VERIFIED_BASELINE, "abc1234"], [FM_VERIFIED_AT, FIXED_NOW()]]);
+  assert.equal(readFrontmatterKey(added, FM_VERIFIED_BASELINE), "abc1234");
+  assert.equal(readFrontmatterKey(added, FM_VERIFIED_AT), FIXED_NOW());
+  assert.ok(added.indexOf("---") < added.indexOf("verifiedBaseline"), "落在 frontmatter 里，不是正文");
+
+  const overwritten = setFrontmatterKeys(added, [[FM_VERIFIED_BASELINE, "def5678"]]);
+  assert.equal(readFrontmatterKey(overwritten, FM_VERIFIED_BASELINE), "def5678");
+  assert.equal(overwritten.match(/^verifiedBaseline:/gm).length, 1, "覆盖而不是重复追加");
+
+  const removed = setFrontmatterKeys(added, [[FM_VERIFIED_BASELINE, null]]);
+  assert.equal(readFrontmatterKey(removed, FM_VERIFIED_BASELINE), null);
+  assert.equal(/^verifiedBaseline:/m.test(removed), false, "删键不留空行——「没记下」要查得出来");
+
+  // 人写的坏文件（没有 frontmatter）不许被凭空造一个块出来
+  assert.equal(setFrontmatterKeys("# 纯正文\n", [[FM_VERIFIED_BASELINE, "x"]]), "# 纯正文\n");
+  assert.equal(readFrontmatterKey("# 纯正文\n", FM_VERIFIED_BASELINE), null);
+});
+
+test("readFrontmatterKey：缩进列表项不算顶层键，带引号的值剥引号", () => {
+  const page = '---\nslug: src\nsourceFiles:\n  - verifiedBaseline: 假的\nverifiedBaseline: "a:b"\n---\n';
+  assert.equal(readFrontmatterKey(page, FM_VERIFIED_BASELINE), "a:b", "只认顶层键，列表里同名的行不误命中");
+});
+
+// --- T0 一个字节都不产出这两个键 ---------------------------------------------
+
+test("T0 骨架页不含 verified 键：确定性不变量不许被溯源污染", () => {
+  const root = makeFixture();
+  const store = createStore(":memory:");
+  try {
+    runChoroT0({ repoRoot: root, store, apply: true, now: FIXED_NOW });
+    const page = readFileSync(join(root, ".chorography", "modules", "src.md"), "utf8");
+    assert.equal(page.includes(FM_VERIFIED_BASELINE), false, "骨架页没有「哪次验证的」这回事");
+    assert.equal(page.includes(FM_VERIFIED_AT), false);
+  } finally {
+    store.close();
+    rmTempBestEffort(root);
+  }
+});
+
+// --- T1 写下那一刻的 HEAD，且 claims 起点跟着它走 -----------------------------
+
+test("T1 富化写下 verifiedBaseline/verifiedAt，且等于那一刻的 HEAD", async () => {
+  const root = makeFixture();
+  const store = createStore(":memory:");
+  try {
+    runChoroT0({ repoRoot: root, store, apply: true, now: FIXED_NOW });
+    const head = commit(root, "t1 之前的一次提交");
+    const t1 = createT1({ store, runSession: async () => ({ ok: true, text: GOOD_OUTPUT }), now: FIXED_NOW });
+    const receipt = await t1.runT1({ repoRoot: root, moduleSlug: "src" });
+    assert.equal(receipt.enriched.length, 1);
+    assert.equal(receipt.enriched[0].verifiedBaseline, head, "回执里带得出来，人不用去翻文件");
+
+    const page = readFileSync(join(root, ".chorography", "modules", "src.md"), "utf8");
+    assert.equal(readFrontmatterKey(page, FM_VERIFIED_BASELINE), head);
+    assert.equal(readFrontmatterKey(page, FM_VERIFIED_AT), FIXED_NOW());
+    assert.ok(page.includes(T1_SECTION_START), "语义段照旧");
+
+    const row = store.db.prepare(
+      "SELECT p.verified_baseline, p.verified_at FROM choro_pages p JOIN choro_modules m ON p.module_id = m.id WHERE m.slug = 'src'"
+    ).get();
+    assert.equal(row.verified_baseline, head, "文件与库同源同写");
+    assert.equal(row.verified_at, FIXED_NOW());
+
+    const evidence = JSON.parse(readFileSync(join(root, ".chorography", "evidence", "src.json"), "utf8"));
+    assert.equal(evidence.verifiedBaseline, head, "evidence 旁证也带起点");
+  } finally {
+    store.close();
+    rmTempBestEffort(root);
+  }
+});
+
+test("claimDrift：T1 晚于 T0 时，T1 之前的改动不误报 touched（这就是 per-page 基线的理由）", async () => {
+  const root = makeFixture();
+  const store = createStore(":memory:");
+  try {
+    runChoroT0({ repoRoot: root, store, apply: true, now: FIXED_NOW });
+    // T0 之后、T1 之前有人改了 a.js 第 1 行——claim 读的就是改完之后的这棵树。
+    writeFileSync(join(root, "src", "a.js"), 'export const a = () => 1;\n', "utf8");
+    commit(root, "T0 之后、T1 之前");
+    const t1 = createT1({ store, runSession: async () => ({ ok: true, text: GOOD_OUTPUT }), now: FIXED_NOW });
+    await t1.runT1({ repoRoot: root, moduleSlug: "src" });
+
+    const q = createChoroQueries({ store });
+    const repo = q.resolveRepo(undefined);
+    const drift = q.claimDrift(repo.id);
+    assert.equal(drift.totals.claims, 1);
+    assert.equal(drift.totals.atRiskClaims, 0, "拿全仓基线起算会在这里误报 touched（旧的 bug）");
+    assert.equal(drift.clean, true);
+    const pageDrift = drift.pages.find((p) => p.slug === "src");
+    assert.equal(pageDrift.verifiedBaseline, drift.head, "起点就是 HEAD");
+    assert.equal(pageDrift.baselineApprox, false);
+
+    // 真改了 claim 锚点所在行：这时必须报出来，别因为「起点是 HEAD」就永远说干净。
+    writeFileSync(join(root, "src", "a.js"), 'export const a = () => 2;\n', "utf8");
+    commit(root, "真的动了锚点");
+    const drift2 = q.claimDrift(repo.id);
+    assert.equal(drift2.clean, false);
+    assert.equal(drift2.totals.atRiskClaims, 1);
+    assert.equal(drift2.pages.find((p) => p.slug === "src").atRisk[0].reason, "touched");
+  } finally {
+    store.close();
+    rmTempBestEffort(root);
+  }
+});
+
+test("claimDrift：老数据（没有逐页基线）退到全仓基线，并标明这是近似起点", () => {
+  const root = makeFixture();
+  const store = createStore(":memory:");
+  try {
+    runChoroT0({ repoRoot: root, store, apply: true, now: FIXED_NOW });
+    const q = createChoroQueries({ store });
+    const repo = q.resolveRepo(undefined);
+    // 本功能之前富化的页：库里有 claims、没有 verified_baseline（迁移加列后的老行）。
+    const page = store.choroPageBySlug(repo.id, "src");
+    store.saveChoroPageClaims(page.id, [
+      { statement: "a 依赖 b", kind: "architecture", sourcePath: "src/a.js", startLine: 2, endLine: 2, createdAt: FIXED_NOW() },
+    ]);
+    store.db.prepare("UPDATE choro_pages SET verified_baseline = NULL, verified_at = NULL WHERE id = ?").run(page.id);
+
+    const drift = q.claimDrift(repo.id);
+    const pageDrift = drift.pages.find((p) => p.slug === "src");
+    assert.equal(pageDrift.verifiedBaseline, null, "真话：这页没记过逐页基线");
+    assert.equal(pageDrift.baselineApprox, true, "退而求其次的起点要标出来");
+    assert.equal(pageDrift.baselineUnknown, false, "有了保底起点就不再是「判不了」");
+    assert.equal(pageDrift.diffBaseline, drift.baseline, "用的就是全仓基线");
+
+    // 全仓基线也缺（极老的行）→ 才轮到 baselineUnknown，一条都不判。
+    store.db.prepare("UPDATE choro_repos SET git_baseline = '' WHERE id = ?").run(repo.id);
+    const drift2 = q.claimDrift(repo.id);
+    assert.equal(drift2.pages.find((p) => p.slug === "src").baselineUnknown, true);
+    assert.equal(drift2.totals.atRiskClaims, 0, "判不了就是判不了，不冒充没事");
+  } finally {
+    store.close();
+    rmTempBestEffort(root);
+  }
+});

package/test/wiki-queries.test.js

@@ -165,6 +165,13 @@ test("moduleMap：模块、页面状态与跨模块边同源返回", () => {
     assert.deepEqual(slugs, ["root", "src"]);
     const src = modules.find((m) => m.slug === "src");
     assert.equal(src.page_status, "skeleton");
+    // 面板从地志页导入知识点时读的是 mod.relPath（契约 §3.6）；SQL 行里只有
+    // page_rel_path，缺这层映射会让「选完模块点导入」永远提示请先选模块（#607）。
+    // 同时锁住原 snake_case 字段还在——choro_module_map 的 render 与 CLI 都在用。
+    assert.equal(typeof src.relPath, "string", "relPath 必须与 page_rel_path 同值");
+    assert.equal(src.relPath, src.page_rel_path);
+    assert.ok(src.relPath.endsWith(".md"), "页相对路径是磁盘上真实存在的 .md");
+    assert.equal(typeof src.file_count, "number", "file_count 原字段必须保留（choro_module_map 的 render 在吃）");
     // fixture 的引用全在 src 模块内部（a→b→b2），left-pad 是外部依赖，root 只有
     // package.json 没有代码——跨模块边应为空集。跨模块聚erge本身由 wiki-store 的
     // 整仓替换用例与 t0 的 moduleEdges 排序覆盖。
@@ -268,3 +275,124 @@ test("outline：模块名 + 文件数 + 页状态 + 页相对路径，不读正
     rmTempBestEffort(root);
   }
 });
+// --- claim 粒度失效（Grounded Claims）:DB 索引 × git diff 的对账 --------------
+
+test("claimDrift：基线 == HEAD 说 clean:true，改了锚点所在行 → 只有那页那条进 atRisk", () => {
+  const { root, store, q } = setup();
+  try {
+    const repo = q.resolveRepo(undefined);
+    const page = store.choroPageBySlug(repo.id, "src");
+    store.saveChoroPageClaims(page.id, [
+      { statement: "a 依赖 b", kind: "architecture", sourcePath: "src/a.js", startLine: 3, endLine: 3, createdAt: FIXED_NOW() },
+      { statement: "b2 只是常量", kind: "architecture", sourcePath: "src/b2.js", startLine: 1, endLine: 1, createdAt: FIXED_NOW() },
+    ]);
+
+    const same = q.claimDrift(repo.id);
+    assert.equal(same.clean, true, "基线就是 HEAD：确实没变，可以说没事");
+    assert.equal(same.anchorStale, false);
+    assert.equal(same.totals.claims, 2);
+    assert.equal(same.totals.atRiskClaims, 0);
+
+    // 改掉 a.js 第 3 行（claim 的锚点）并提交 → 基线落后 HEAD。
+    writeFileSync(join(root, "src", "a.js"), 'import { b } from "./b.js";\nimport h from "left-pad";\nexport const a = () => b() + 1;\n', "utf8");
+    execFileSync("git", ["-c", "user.email=t@t", "-c", "user.name=t", "commit", "-am", "change a", "--no-gpg-sign"], { cwd: root, stdio: "pipe" });
+
+    const drift = q.claimDrift(repo.id);
+    assert.equal(drift.clean, false);
+    assert.notEqual(drift.baseline, drift.head, "基线落后了");
+    assert.equal(drift.totals.claims, 2);
+    assert.equal(drift.totals.atRiskClaims, 1, "只有锚在 a.js 第 3 行那条受影响");
+    const pageRisk = drift.pages.find((p) => p.slug === "src");
+    assert.equal(pageRisk.atRisk.length, 1);
+    assert.equal(pageRisk.atRisk[0].reason, "touched");
+    assert.equal(pageRisk.atRisk[0].sourcePath, "src/a.js");
+    // 排序契约：有风险的页排最前（面板直接顺着读，不再排一遍）。
+    assert.equal(drift.pages[0].slug, "src");
+  } finally {
+    store.close();
+    rmTempBestEffort(root);
+  }
+});
+
+test("claimDrift：基线认不出时说 anchorStale，不说「都还准」也不说「全失效」", () => {
+  const { root, store, q } = setup();
+  try {
+    const repo = q.resolveRepo(undefined);
+    // force-push / 浅克隆的形态：基线 sha 合法但对象不在库里的任何一棵树上。
+    store.db.prepare("UPDATE choro_repos SET git_baseline = ? WHERE id = ?").run("0123456789abcdef0123456789abcdef01234567", repo.id);
+    const drift = q.claimDrift(repo.id);
+    assert.equal(drift.clean, false);
+    assert.equal(drift.anchorStale, true);
+    assert.equal(drift.reason, "diff-failed");
+    assert.equal(drift.totals.atRiskClaims, 0, "算不出来不等于有风险——一条都不许判");
+  } finally {
+    store.close();
+    rmTempBestEffort(root);
+  }
+});
+
+test("claimDrift：验证过却没记下基线（verified_at 有、verified_baseline 空）→ 判不了，不回退全仓基线", () => {
+  const { root, store, q } = setup();
+  try {
+    const repo = q.resolveRepo(undefined);
+    const page = store.choroPageBySlug(repo.id, "src");
+    store.saveChoroPageClaims(page.id, [
+      { statement: "a 依赖 b", kind: "architecture", sourcePath: "src/a.js", startLine: 3, endLine: 3, createdAt: FIXED_NOW() },
+    ]);
+    // 后半段的验证没留下凭据：T1 写了 verified_at，却没写 verified_baseline。
+    store.db.prepare("UPDATE choro_pages SET verified_at = ?, verified_baseline = NULL WHERE id = ?").run(FIXED_NOW(), page.id);
+
+    const drift = q.claimDrift(repo.id);
+    const p = drift.pages.find((x) => x.slug === "src");
+    // 退到全仓基线会把「富化之后才发生」的改动当成「富化之前就有」而放过——漏报。
+    // 不知道起点就不装作知道：diffBaseline 必须为 null，且这一页判 baselineUnknown。
+    assert.equal(p.diffBaseline, null, "没有验证点就不许回退全仓基线");
+    assert.equal(p.baselineApprox, false, "这不是「老数据退而求其次」，别标成约等于");
+    assert.equal(p.baselineUnknown, true);
+    assert.equal(drift.totals.baselineUnknownPages, 1);
+    // 基线 == HEAD 时 clean 仍可为真：一条提交都没发生过，锚点不可能被碰到，
+    // 「验证点没记下」在这里不影响结论（影响的是「变了之后能不能判」）。
+    assert.equal(drift.clean, true, "没变就是没变，不必因为起点没记下而说不知道");
+
+    // 有提交之后就不一样了：起点认不出的页不许被那些提交的改动「顺带放过」。
+    writeFileSync(join(root, "src", "a.js"), 'import { b } from "./b.js";\nexport const a = () => b() + 1;\n', "utf8");
+    execFileSync("git", ["-c", "user.email=t@t", "-c", "user.name=t", "commit", "-am", "change a", "--no-gpg-sign"], { cwd: root, stdio: "pipe" });
+    const after = q.claimDrift(repo.id);
+    assert.equal(after.clean, false, "有判不了的页，就不能说干净");
+    assert.equal(after.totals.baselineUnknownPages, 1);
+    assert.equal(after.totals.atRiskClaims, 0, "判不了不等于有风险，一条都不许判");
+  } finally {
+    store.close();
+    rmTempBestEffort(root);
+  }
+});
+
+test("claimDrift：repoAtHead 也不能掩盖 inconsistentPages（有语义段却没 claims 的页）", () => {
+  const { root, store, q } = setup();
+  try {
+    const repo = q.resolveRepo(undefined);
+    // 造一次「T1 落盘不完整」：页里有语义段，库里一条 claims 都没有。
+    // 仓库基线仍等于 HEAD，旧实现在这里会短路成 clean:true——把残局说成没事。
+    const pagePath = join(root, ".chorography", "modules", "src.md");
+    writeFileSync(pagePath, readFileSync(pagePath, "utf8") + "\n<!-- CHORO:T1:START -->\n## 架构\n\na.js 是入口。\n<!-- CHORO:T1:END -->\n", "utf8");
+
+    const drift = q.claimDrift(repo.id);
+    assert.equal(drift.baseline, drift.head, "前提：仓库基线就是 HEAD（走短路分支）");
+    assert.equal(drift.totals.inconsistentPages, 1, "有语义段、零 claims 的页要被数出来");
+    assert.equal(drift.totals.atRiskClaims, 0, "它一条结论都没有，谈不上有风险");
+    assert.equal(drift.clean, false, "残局不许被说成「全部干净」");
+  } finally {
+    store.close();
+    rmTempBestEffort(root);
+  }
+});
+
+test("claimDrift：未知仓库返回 null（调用方据此 404，不是空清单）", () => {
+  const { root, store, q } = setup();
+  try {
+    assert.equal(q.claimDrift(999999), null);
+  } finally {
+    store.close();
+    rmTempBestEffort(root);
+  }
+});