@modusensus/dsh-mneme 0.11.0 → 0.12.0

package/test/tools.test.js

@@ -49,11 +49,148 @@ function walkSchema(node, path, problems) {
   }
 }
 
-test("registers eleven tools with correct names", () => {
+// memory_pin 的 injectable 回执必须跟注入侧同一个出口判定（#249 第二批）。
+//
+// 这条单独立在 tools 侧而不是注入侧：注入侧早已锁了「暂停作用域的行不进块」，
+// 但回执那句话是另一段代码，它可以照样撒谎——描述文案与 README 都写着
+// 「遗忘 / 归档 / 暂停作用域都优先于 pin」，而 execute 里只算了 forgotten/archived
+// 两个标志位，暂停作用域被漏掉。于是同一条行在「真会注入」与「被作用域挡住」
+// 两种完全相反的处境下都报 injectable: true，正是「返回成功不等于生效」那一类。
+//
+// 三档一起锁，是因为 filterPaused 的出口语义是分档的（见 src/scope-state.js:215）：
+//   enforce 开 → 真正剔掉，回执必须 false；
+//   只开 enabled（观察档）→ 不拦任何东西，回执必须 true（此时报 false 才是假警报）；
+//   两个都关 → 同样不拦，回执 true。
+function setupPinReceipt(config) {
+  // pin 预算从 config 读（src/service.js:1885），不是 injectCandidates 的入参——
+  // 传进调用参数会被静默忽略，那样这几条测试就测不到 pin 池。
+  const cfg = { pinnedInjectBudget: 5, ...config };
+  const store = createStore(":memory:");
+  // 注意 config 必须同时喂 service 与 tools：作用域闸在 service 侧构造，
+  // 而 memory_pin 的 execute 走的是 service 暴露的那个出口。
+  const service = createService({ store, mirror: null, config: cfg });
+  const registered = [];
+  const ctx = { tools: { register(def) { registered.push(def); return () => {}; } } };
+  createTools(ctx, service, cfg, undefined);
+  return { store, service, byName: Object.fromEntries(registered.map((d) => [d.name, d])) };
+}
+
+test("memory_pin 的 injectable 如实报告暂停作用域（而不是只算遗忘与归档）", async () => {
+  const config = { scopeState: { enabled: true, enforce: true } };
+  const { store, service, byName } = setupPinReceipt(config);
+  const target = store.save({
+    type: "preference",
+    title: "暂停域里的偏好",
+    content: "这一路现在被按下了。",
+    workspace_scope: "proj-a",
+    importance: 5
+  });
+  await service.setScopeState({ dimension: "workspace", scope_value: "proj-a", state: "paused" });
+
+  const receipt = await byName.memory_pin.execute({ id: target.id }, undefined);
+  // 钉是钉上了（存储确实写了），但它在当前状态下不会被注入——两件事分开报。
+  assert.equal(receipt.pinned, true);
+  assert.equal(receipt.injectable, false, "暂停作用域里的行必须报 injectable: false");
+
+  // 回执与行为必须同向：真的注入一次，这条不许出现。
+  const pinnedStats = {};
+  const injected = service.injectCandidates({
+    query: "随便问个问题",
+    maxItems: 5,
+    pinnedStats
+  });
+  assert.equal(pinnedStats.source, "explicit", "这一条本身钉住了，口径应留在 explicit");
+  assert.ok(
+    !injected.some((m) => m.id === target.id),
+    "被暂停作用域挡住的行不该出现在注入块里（回执说 false，行为也必须一致）"
+  );
+});
+
+test("暂停作用域只开观察档（enforce 关）时，injectable 仍报 true", async () => {
+  // 观察档的语义是「记录本应被拦下多少，但一条都不拦」。此时那条行确实会进上下文，
+  // 所以回执必须报 true；报 false 会让用户以为它被挡了，比漏掉暂停作用域更难查。
+  const config = { scopeState: { enabled: true, enforce: false } };
+  const { store, service, byName } = setupPinReceipt(config);
+  const target = store.save({
+    type: "preference",
+    title: "观察档下的偏好",
+    content: "按下但未生效。",
+    workspace_scope: "proj-a",
+    importance: 5
+  });
+  await service.setScopeState({ dimension: "workspace", scope_value: "proj-a", state: "paused" });
+
+  const receipt = await byName.memory_pin.execute({ id: target.id }, undefined);
+  assert.equal(receipt.injectable, true, "观察档不拦任何东西，回执必须报 true");
+
+  const pinnedStats = {};
+  const injected = service.injectCandidates({
+    query: "随便问个问题",
+    maxItems: 5,
+    pinnedStats
+  });
+  assert.ok(
+    injected.some((m) => m.id === target.id),
+    "观察档下这条应当照常注入，回执与行为必须同向"
+  );
+});
+
+test("pinnedInjectBudget=0（默认，pin 池整体关闭）时 injectable 必须报 false", async () => {
+  // #593 遗留缺口：pin 池由 pinnedInjectBudget 开关（src/service.js:1885 的
+  // pinnedBudget > 0 才读表选路），默认 0。上一版只看遗忘/归档/暂停作用域，
+  // 预算为 0 的一条照样报 true——钉住成功但一条都不会被注入，正是「返回成功
+  // 不等于生效」。这里把默认档（不传任何 config）与显式 0 两档一起锁。
+  const { store, service, byName } = setupPinReceipt({ pinnedInjectBudget: 0 });
+  const target = store.save({ type: "preference", title: "预算关着", content: "x", importance: 5 });
+  const receipt = await byName.memory_pin.execute({ id: target.id }, undefined);
+  assert.equal(receipt.pinned, true, "钉的动作确实成功了，两件事分开报");
+  assert.equal(receipt.injectable, false, "预算 0 = pin 池关闭，此刻不会经 pin 通道注入，回执必须报 false");
+
+  // 这里不断言「注入序列里一定没有它」：预算 0 关掉的是 **pin 通道**，不是这条记忆
+  // 本身——它仍可能靠自己的重要性走常规候选路进块（既有用例
+  // inject-pin-explicit.test.js:176 锁的是「注入序列与改前逐字节一致」，不是「不出现」）。
+});
+
+test("autoInject=false（注入器未注册）时 injectable 必须报 false", async () => {
+  // #596 评审指出的第二处：autoInject 是 pin 通道的总闸，关着时 src/index.js:617
+  // 根本不注册注入器——pin 段一行都跑不到，回执照样报 true 就是同一个「返回成功
+  // 不等于生效」。判据按「只有显式 false 才算关」写，故这里显式传 false。
+  const { store, byName } = setupPinReceipt({ autoInject: false });
+  const target = store.save({ type: "preference", title: "注入器没挂", content: "x", importance: 5 });
+  const receipt = await byName.memory_pin.execute({ id: target.id }, undefined);
+  assert.equal(receipt.pinned, true, "钉的动作照样成功，两件事分开报");
+  assert.equal(receipt.injectable, false, "autoInject 关 = 注入器不存在，此刻不可能经 pin 通道注入");
+
+  // 反例：不显式传 autoInject 时不能因为 config 里没这个键就误报 false
+  // （createTools 的测试直连场景拿不到已填 defaults 的 config）。
+  const on = setupPinReceipt({});
+  const t2 = on.store.save({ type: "preference", title: "默认开", content: "y", importance: 5 });
+  assert.equal(
+    (await on.byName.memory_pin.execute({ id: t2.id }, undefined)).injectable,
+    true,
+    "未显式关 autoInject 时必须报 true（预算 5 已满足）"
+  );
+});
+
+test("遗忘或归档的 pin：injectable 报 false（原有两项不能被这次改动弄丢）", async () => {
+  const { store, byName } = setupPinReceipt({});
+  const target = store.save({ type: "preference", title: "会被归档", content: "x", importance: 5 });
+  assert.equal((await byName.memory_pin.execute({ id: target.id }, undefined)).injectable, true);
+  store.setArchived(target.id, true);
+  const archived = await byName.memory_pin.execute({ id: target.id }, undefined);
+  assert.equal(archived.pinned, true);
+  assert.equal(archived.injectable, false);
+  store.setArchived(target.id, false);
+  store.setForget(target.id, true);
+  const forgotten = await byName.memory_pin.execute({ id: target.id }, undefined);
+  assert.equal(forgotten.injectable, false);
+});
+
+test("registers twelve tools with correct names", () => {
   const { registered } = setup();
   const names = registered.map((t) => t.name).sort();
   // #230 新增 memory_register_document（agent 产长文档的指针行铸造口）。
-  assert.deepEqual(names, ["memory_archive", "memory_delete", "memory_forget", "memory_get", "memory_list", "memory_register_document", "memory_runtime", "memory_save", "memory_search", "memory_update", "set_scope_state"]);
+  assert.deepEqual(names, ["memory_archive", "memory_delete", "memory_forget", "memory_get", "memory_list", "memory_pin", "memory_register_document", "memory_runtime", "memory_save", "memory_search", "memory_update", "set_scope_state"]);
 });
 
 // v0.8.5 tool-exposure gate: disabling a tool hides it from the model entirely
@@ -62,19 +199,19 @@ test("registers eleven tools with correct names", () => {
 test("disableMemorySearch hides only memory_search", () => {
   const { registered } = setup({}, { disableMemorySearch: true });
   const names = registered.map((t) => t.name).sort();
-  assert.deepEqual(names, ["memory_archive", "memory_delete", "memory_forget", "memory_get", "memory_list", "memory_register_document", "memory_runtime", "memory_save", "memory_update", "set_scope_state"]);
+  assert.deepEqual(names, ["memory_archive", "memory_delete", "memory_forget", "memory_get", "memory_list", "memory_pin", "memory_register_document", "memory_runtime", "memory_save", "memory_update", "set_scope_state"]);
 });
 
 test("disableMemoryArchive hides only memory_archive", () => {
   const { registered } = setup({}, { disableMemoryArchive: true });
   const names = registered.map((t) => t.name).sort();
-  assert.deepEqual(names, ["memory_delete", "memory_forget", "memory_get", "memory_list", "memory_register_document", "memory_runtime", "memory_save", "memory_search", "memory_update", "set_scope_state"]);
+  assert.deepEqual(names, ["memory_delete", "memory_forget", "memory_get", "memory_list", "memory_pin", "memory_register_document", "memory_runtime", "memory_save", "memory_search", "memory_update", "set_scope_state"]);
 });
 
 test("both disable flags hide both tools", () => {
   const { registered } = setup({}, { disableMemorySearch: true, disableMemoryArchive: true });
   const names = registered.map((t) => t.name).sort();
-  assert.deepEqual(names, ["memory_delete", "memory_forget", "memory_get", "memory_list", "memory_register_document", "memory_runtime", "memory_save", "memory_update", "set_scope_state"]);
+  assert.deepEqual(names, ["memory_delete", "memory_forget", "memory_get", "memory_list", "memory_pin", "memory_register_document", "memory_runtime", "memory_save", "memory_update", "set_scope_state"]);
 });
 
 // Description discipline: with all tools exposed, the descriptions must steer a
@@ -90,12 +227,12 @@ test("memory_search/archive descriptions carry tool-use discipline", () => {
 
 test("compiled schemas pass the enforced DSH subset (defineTool projection)", () => {
   const { registered } = setup();
-  assert.equal(registered.length, 11);
+  assert.equal(registered.length, 12);
   // opt-in 暴露的工具在默认配置下不注册（#231 的 memory_organize），所以本用例还得
   // 把暴露闸打开再走一遍——否则新工具的编译 schema 从来没被这条护栏看过，
   // 「子集不支持的写法」要到运行时才炸。
   const { registered: exposed } = setup(undefined, { organizeEnabled: true });
-  assert.equal(exposed.length, 12, "organizeEnabled 只多带一个工具，不许顺手改在场的别的东西");
+  assert.equal(exposed.length, 13, "organizeEnabled 只多带一个工具，不许顺手改在场的别的东西");
   for (const tool of [...registered, ...exposed]) {
     assertSupportedJsonSchema(tool.parameters);
     assertSupportedJsonSchema(tool.output.schema);

package/test/wiki-api.test.js

@@ -5,7 +5,7 @@
 import test from "node:test";
 import assert from "node:assert/strict";
 import { EventEmitter } from "node:events";
-import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync, existsSync, unlinkSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { execFileSync } from "node:child_process";
@@ -50,6 +50,18 @@ async function invoke(route, path) {
   return { status: res.statusCode, body: JSON.parse(res.body || "{}") };
 }
 
+// POST 版：带 JSON body（readBody 走 data/end 事件）
+async function invokePost(route, path, body) {
+  const r = req(path, "POST");
+  process.nextTick(() => {
+    r.emit("data", Buffer.from(JSON.stringify(body ?? {})));
+    r.emit("end");
+  });
+  const res = new FakeRes();
+  await route.handler(r, res);
+  return { status: res.statusCode, body: JSON.parse(res.body || "{}") };
+}
+
 function makeRepo(store) {
   const root = mkdtempSync(join(tmpdir(), "choro-api-"));
   writeFileSync(join(root, "package.json"), JSON.stringify({ name: "apifix", scripts: { test: "node --test" } }, null, 2) + "\n", "utf8");
@@ -151,3 +163,111 @@ test("repo 解析失败各归各位：未知 → 404；歧义 → 400 带清单
     rmTempBestEffort(root);
   }
 });
+
+test("地志页路由区分缺失文件和不可读文件", async () => {
+  const store = createStore(":memory:");
+  const root = makeRepo(store);
+  try {
+    const { routes } = setup({ config: { chorographyEnabled: true }, choro: createChoroQueries({ store }) });
+    const pageRoute = handler(routes, "/api/dsh-mneme/choro/page");
+    const url = "/api/dsh-mneme/choro/page?slug=src";
+    const file = join(root, ".chorography", "modules", "src.md");
+    unlinkSync(file);
+    const missing = await invoke(pageRoute, url);
+    assert.equal(missing.status, 409);
+    assert.equal(missing.body.error, "page-missing");
+    assert.match(missing.body.hint, /dsh-mneme-choro/);
+    mkdirSync(file);
+    const unreadable = await invoke(pageRoute, url);
+    assert.equal(unreadable.status, 409);
+    assert.equal(unreadable.body.error, "page-unreadable");
+    assert.match(unreadable.body.hint, /permissions/);
+  } finally {
+    store.close();
+    rmTempBestEffort(root);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// 收尾档：POST /choro/run（面板重建入口，P34）+ /choro/search 的 semantic 路（P37–P39）
+// ---------------------------------------------------------------------------
+test("/choro/run：policy token-write，GET 405，POST 快乐路径重跑 T0", async () => {
+  const store = createStore(":memory:");
+  const root = makeRepo(store);
+  try {
+    const { routes } = setup({
+      config: { chorographyEnabled: true },
+      choro: {
+        ...createChoroQueries({ store }),
+        // 与 index.js 的装配同形：runT0Apply 闭包住 store（P35：写路径与读侧分开装配）
+        runT0Apply: ({ repoRoot }) => runChoroT0({ repoRoot, store, apply: true }),
+      },
+    });
+    const route = handler(routes, "/api/dsh-mneme/choro/run");
+    assert.equal(route.policy, "token-write", "写仓库磁盘的口归 token-write");
+
+    const get = await invoke(route, "/api/dsh-mneme/choro/run");
+    assert.equal(get.status, 405, "只收 POST");
+
+    // 破坏页面文件后重建：POST 走真 T0，页回来
+    rmSync(join(root, ".chorography", "modules", "src.md"));
+    const ok = await invokePost(route, "/api/dsh-mneme/choro/run", { repo: 1 });
+    assert.equal(ok.status, 200);
+    assert.equal(ok.body.ok, true);
+    assert.ok(ok.body.receipt.moduleCount >= 2, "receipt 带划分计数");
+    assert.ok(existsSync(join(root, ".chorography", "modules", "src.md")), "重建把页写了回来");
+  } finally {
+    rmTempBestEffort(root);
+  }
+});
+
+test("/choro/run：开关关 409；repo 未知 404（与读路由同一道闸）", async () => {
+  const store = createStore(":memory:");
+  const root = makeRepo(store);
+  try {
+    const off = setup({
+      config: { chorographyEnabled: false },
+      choro: { ...createChoroQueries({ store }), runT0Apply: () => { throw new Error("不该被调到"); } },
+    });
+    const a = await invokePost(handler(off.routes, "/api/dsh-mneme/choro/run"), "/api/dsh-mneme/choro/run", { repo: 1 });
+    assert.equal(a.status, 409);
+
+    const on = setup({
+      config: { chorographyEnabled: true },
+      choro: { ...createChoroQueries({ store }), runT0Apply: () => { throw new Error("不该被调到") } },
+    });
+    const b = await invokePost(handler(on.routes, "/api/dsh-mneme/choro/run"), "/api/dsh-mneme/choro/run", { repo: 99 });
+    assert.equal(b.status, 404);
+  } finally {
+    rmTempBestEffort(root);
+  }
+});
+
+test("/choro/search：embedder 在场 → 惰性物化 + semantic 数组；缺席 → semantic null", async () => {
+  const store = createStore(":memory:");
+  const root = makeRepo(store);
+  try {
+    // stub embedder：向量按内容方向分类（src 相关 → [1,0]），保证可排序断言
+    const embedder = {
+      model: "stub-1",
+      embedSingle: async (text) => (/src|b\.js/.test(text) ? [1, 0] : [0, 1]),
+      embed: async (text) => (/src|b\.js/.test(text) ? [1, 0] : [0, 1]),
+    };
+    const { routes } = setup({
+      config: { chorographyEnabled: true },
+      choro: { ...createChoroQueries({ store }), embedder },
+    });
+    const s = await invoke(handler(routes, "/api/dsh-mneme/choro/search"), "/api/dsh-mneme/choro/search?repo=1&q=b.js");
+    assert.equal(s.status, 200);
+    assert.ok(Array.isArray(s.body.hits) && s.body.hits.length >= 1, "keyword hits 照旧");
+    assert.ok(Array.isArray(s.body.semantic) && s.body.semantic.length >= 1, "semantic 数组在场（惰性物化发生在这次请求里）");
+    assert.equal(s.body.semantic[0].slug, "src", "与查询同向的页排前");
+    assert.equal(typeof s.body.semantic[0].score, "number");
+
+    const noEmbedder = setup({ config: { chorographyEnabled: true }, choro: createChoroQueries({ store }) });
+    const t = await invoke(handler(noEmbedder.routes, "/api/dsh-mneme/choro/search"), "/api/dsh-mneme/choro/search?repo=1&q=b.js");
+    assert.equal(t.body.semantic, null, "embedder 缺席 → null（调用方退纯关键词）");
+  } finally {
+    rmTempBestEffort(root);
+  }
+});

package/test/wiki-queries.test.js

@@ -4,7 +4,7 @@
 // 盘上缺页如实报 page-missing、检索分节与行号、repo 解析的歧义处理。
 import test from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, rmSync, writeFileSync, mkdirSync, unlinkSync } from "node:fs";
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync, unlinkSync, readFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { execFileSync } from "node:child_process";
@@ -46,6 +46,89 @@ function setup() {
   return { root, store, q: createChoroQueries({ store }) };
 }
 
+// stub embedder：文本含 "src" → [1,0]，否则 [0,1]（固定二维，可断言方向与失配）
+function stubEmbedder(model = "stub-1") {
+  return {
+    model,
+    embedSingle: async (text) => (/src/.test(text) ? [1, 0] : [0, 1]),
+    embed: async (text) => (/src/.test(text) ? [1, 0] : [0, 1]),
+  };
+}
+
+// --- 收尾档 P37–P39：向量惰性物化与检索 -------------------------------------
+
+test("embedPageVectors：首次全嵌，generated_at 没变就跳过，变了重嵌（staleness 两维之一）", async () => {
+  const { root, store, q } = setup();
+  try {
+    const repo = q.resolveRepo(undefined);
+    const emb = stubEmbedder();
+    const r1 = await q.embedPageVectors(repo.id, emb);
+    assert.equal(r1.embedded, 2, "两页全嵌");
+    const r2 = await q.embedPageVectors(repo.id, emb);
+    assert.equal(r2.embedded, 0);
+    assert.equal(r2.skipped, 2, "generated_at 没变 → 全跳过");
+    // 页面内容变了（generated_at 推进）→ 只重嵌变的那页
+    const pagePath = join(root, ".chorography", "modules", "src.md");
+    const before = readFileSync(pagePath, "utf8");
+    writeFileSync(pagePath, `${before}<!-- CHORO:HUMAN:START -->\n人工补充\n<!-- CHORO:HUMAN:END -->\n`, "utf8");
+    store.db.prepare(
+      "UPDATE choro_pages SET generated_at = ? WHERE generated_at IS NOT NULL AND id IN (SELECT p.id FROM choro_pages p JOIN choro_modules m ON p.module_id = m.id WHERE m.slug = 'src')"
+    ).run("2026-11-06T00:00:00.000Z");
+    const r3 = await q.embedPageVectors(repo.id, emb);
+    assert.equal(r3.embedded, 1, "只有 src 页重嵌");
+    assert.equal(r3.stale, 1, "旧向量按 stale 记账");
+  } finally {
+    store.close();
+    rmTempBestEffort(root);
+  }
+});
+
+test("dim 失配（换 embedder 模型）→ 惰性全量重嵌（P38：不锁死，代价只是几十页）", async () => {
+  const { root, store, q } = setup();
+  try {
+    const repo = q.resolveRepo(undefined);
+    await q.embedPageVectors(repo.id, stubEmbedder("stub-1"));
+    // 换模型：维度从 2 → 3。expectDim 来自查询向量（路由先嵌查询再物化）
+    const emb3 = {
+      model: "stub-2",
+      embedSingle: async () => [1, 0, 0],
+      embed: async () => [1, 0, 0],
+    };
+    const r = await q.embedPageVectors(repo.id, emb3, { expectDim: 3 });
+    assert.equal(r.embedded, 2, "维度变了 → 全部重嵌（fresh 检查被 dimDrift 压过）");
+    assert.equal(r.dimMismatch, true, "失配被记账");
+    const rows = store.getChoroPageVectors(repo.id);
+    assert.ok(rows.every((row) => row.dim === 3 && row.model === "stub-2"), "旧维度行不复存");
+    // 不给 expectDim（无查询场景）→ fresh 行照旧跳过
+    const r2 = await q.embedPageVectors(repo.id, emb3);
+    assert.equal(r2.embedded, 0);
+    assert.equal(r2.skipped, 2);
+  } finally {
+    store.close();
+    rmTempBestEffort(root);
+  }
+});
+
+test("searchSemantic：cosine 排序 + dim 失配行被过滤 + embedder 缺席返回 null", async () => {
+  const { root, store, q } = setup();
+  try {
+    const repo = q.resolveRepo(undefined);
+    await q.embedPageVectors(repo.id, stubEmbedder("stub-1"));
+    const hits = await q.searchSemantic(repo.id, stubEmbedder("stub-1"), "src 相关的页");
+    assert.ok(Array.isArray(hits) && hits.length >= 1);
+    assert.equal(hits[0].slug, "src", "查询向量 [1,0] 与 src 页同向 → 排前");
+    // 查询向量三维：与所有行 dim 失配 → 无可比行，返回空数组而不是抛
+    const dim3 = { embedSingle: async () => [1, 0, 0], embed: async () => [1, 0, 0] };
+    const empty = await q.searchSemantic(repo.id, dim3, "x");
+    assert.deepEqual(empty, []);
+    assert.equal(await q.searchSemantic(repo.id, null, "x"), null);
+    assert.deepEqual(await q.searchSemantic(repo.id, stubEmbedder(), "  "), [], "空查询不嵌入、返回空数组");
+  } finally {
+    store.close();
+    rmTempBestEffort(root);
+  }
+});
+
 test("listRepos / resolveRepo：单仓自动收敛，多仓歧义要显式给键", () => {
   const { root, store, q } = setup();
   try {