@modusensus/dsh-mneme 0.8.3 → 0.8.5

package/test/narrative-bars.test.js

@@ -0,0 +1,162 @@
+// 叙述条（#164 对齐，PR-4）测试。
+// 覆盖：evidence 列迁移与透传（save/update/parse 回环）/ clusterByTag 纯函数
+// （≥K 门槛、降序、cap）/ intersectEvidence（捏造 id 剔除、交空回落全簇）/
+// dream 叙述阶段端到端（enabled 时第三次 LLM 调用、求交落库、source=narrative）/
+// 默认关零调用 / 低于门槛零调用 / 注入排除（narrative 不进候选，dream 总览保留）。
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createStore } from "../src/store.js";
+import { createService } from "../src/service.js";
+import { createDreamScheduler } from "../src/dream.js";
+import { clusterByTag, intersectEvidence } from "../src/dream/narratives.js";
+
+function setup(config = {}) {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config });
+  return { store, service };
+}
+
+function mockCtx(sequence, callsRef) {
+  return {
+    llm: {
+      stream: async function* () {
+        const step = sequence[callsRef.n] ?? { summary: "空转" };
+        callsRef.n++;
+        const text = step.decisions !== undefined ? JSON.stringify(step.decisions) : step.summary;
+        yield { type: "text-delta", text };
+        yield { type: "finish", reason: { kind: "ok" } };
+      }
+    },
+    logger: { warn: () => {} }
+  };
+}
+
+// ============================================================ store evidence 回环
+
+test("evidence column roundtrips through save and update", () => {
+  const { store, service } = setup();
+  const ev = [{ memory_id: "m1", op: "support", at: "2026-09-17T00:00:00.000Z" }];
+  const { memory } = service.saveWithDedupe({
+    type: "summary", title: "叙述：部署", content: "叙述正文", source: "narrative", evidence: ev
+  });
+  assert.deepEqual(store.getById(memory.id).evidence, ev);
+  const ev2 = [{ memory_id: "m2", op: "weaken", at: "2026-09-18T00:00:00.000Z" }];
+  store.update(memory.id, { evidence: ev2 });
+  assert.deepEqual(store.getById(memory.id).evidence, ev2);
+  store.close();
+});
+
+test("rows without evidence parse to an empty array", () => {
+  const { store, service } = setup();
+  const { memory } = service.saveWithDedupe({ type: "project", title: "普通", content: "无证据" });
+  assert.deepEqual(store.getById(memory.id).evidence, []);
+  store.close();
+});
+
+// ============================================================ 纯函数
+
+test("clusterByTag: threshold, size desc, cap", () => {
+  const mems = [
+    { id: "a", tags: ["部署"] }, { id: "b", tags: ["部署"] }, { id: "c", tags: ["部署"] },
+    { id: "d", tags: ["检索"] }, { id: "e", tags: ["检索"] }, { id: "f", tags: ["检索"] },
+    { id: "g", tags: ["检索"] }, { id: "h", tags: ["孤儿"] }, { id: "i", tags: [123] }
+  ];
+  const clusters = clusterByTag(mems, { minCluster: 3, cap: 1 });
+  assert.equal(clusters.length, 1);
+  assert.equal(clusters[0].tag, "检索");
+  assert.equal(clusters[0].members.length, 4);
+  const two = clusterByTag(mems, { minCluster: 3, cap: 3 });
+  assert.deepEqual(two.map((c) => c.tag), ["检索", "部署"]);
+});
+
+test("intersectEvidence drops fabricated ids; empty falls back to all members", () => {
+  const members = [{ id: "a" }, { id: "b" }, { id: "c" }];
+  assert.deepEqual(intersectEvidence(["a", "fabricated"], members), ["a"]);
+  assert.deepEqual(intersectEvidence(["x", "y"], members), ["a", "b", "c"]);
+  assert.deepEqual(intersectEvidence(undefined, members), ["a", "b", "c"]);
+});
+
+// ============================================================ dream 叙述阶段
+
+function seedDeploy(store, service) {
+  const mems = [];
+  for (const t of ["发布", "回滚", "盯盘"]) {
+    mems.push(service.saveWithDedupe({ type: "project", title: t, content: `${t}相关的事实记录。`, tags: ["部署"] }).memory);
+  }
+  service.saveWithDedupe({ type: "preference", title: "无关", content: "别的话题。", tags: ["其他"] });
+  return mems;
+}
+
+test("narrative phase synthesizes per-topic bars with intersected evidence", async () => {
+  const { store, service } = setup();
+  const mems = seedDeploy(store, service);
+  const callsRef = { n: 0 };
+  const narrativeJson = JSON.stringify([
+    { tag: "部署", content: "部署主题已积累三条事实：发布、回滚与盯盘均已闭环。", evidence: [mems[0].id, "fabricated-id"] }
+  ]);
+  const ctx = mockCtx([{ decisions: [] }, { summary: "总览叙述" }, { summary: narrativeJson }], callsRef);
+  const dream = createDreamScheduler({ thresholdCount: 1, thresholdChars: 0, delayMs: 0 });
+  const result = await dream.runDream(ctx, service, { dreamProvider: "deepseek", dreamModel: "deepseek-chat", dreamNarrativeEnabled: true });
+  assert.equal(result.narratives, 1, "one narrative stored");
+  const bar = store.all().find((m) => m.source === "narrative");
+  assert.ok(bar, "narrative row exists");
+  assert.equal(bar.title, "叙述：部署");
+  assert.equal(bar.type, "summary");
+  assert.equal(bar.evidence.length, 1, "fabricated id dropped by intersection");
+  assert.equal(bar.evidence[0].memory_id, mems[0].id);
+  assert.equal(bar.evidence[0].op, "support");
+  store.close();
+});
+
+test("narrative phase off by default: no extra LLM call", async () => {
+  const { store, service } = setup();
+  seedDeploy(store, service);
+  const callsRef = { n: 0 };
+  const ctx = mockCtx([{ decisions: [] }, { summary: "总览叙述" }], callsRef);
+  const dream = createDreamScheduler({ thresholdCount: 1, thresholdChars: 0, delayMs: 0 });
+  await dream.runDream(ctx, service, { dreamProvider: "deepseek", dreamModel: "deepseek-chat" });
+  assert.equal(callsRef.n, 2, "only consolidation + summary calls");
+  assert.equal(store.all().filter((m) => m.source === "narrative").length, 0);
+  store.close();
+});
+
+test("below minCluster threshold: no narrative call even when enabled", async () => {
+  const { store, service } = setup();
+  service.saveWithDedupe({ type: "project", title: "甲", content: "c", tags: ["部署"] });
+  service.saveWithDedupe({ type: "project", title: "乙", content: "c", tags: ["部署"] });
+  const callsRef = { n: 0 };
+  const ctx = mockCtx([{ decisions: [] }, { summary: "总览叙述" }], callsRef);
+  const dream = createDreamScheduler({ thresholdCount: 1, thresholdChars: 0, delayMs: 0 });
+  await dream.runDream(ctx, service, { dreamProvider: "deepseek", dreamModel: "deepseek-chat", dreamNarrativeEnabled: true });
+  assert.equal(callsRef.n, 2, "no narrative call without a qualifying cluster");
+  store.close();
+});
+
+// ============================================================ 注入排除
+
+test("narrative dedupes by tag across language switches (no duplicate row)", () => {
+  const { store, service } = setup();
+  service.saveWithDedupe({ type: "summary", title: "叙述：部署", content: "中文叙述", importance: 3, source: "narrative", tags: ["部署"] });
+  // generateNarratives 落库恒走 _overwrite（标题=主题键，原地刷新）。
+  service.saveWithDedupe({ type: "summary", title: "Narrative: 部署", content: "English narrative", importance: 3, source: "narrative", tags: ["部署"], _overwrite: true });
+  const bars = store.all().filter((m) => m.source === "narrative");
+  assert.equal(bars.length, 1, "language switch must not create a duplicate narrative row");
+  assert.equal(bars[0].title, "Narrative: 部署", "row refreshes to the new language title");
+  assert.equal(bars[0].content, "English narrative");
+  store.close();
+});
+
+test("narrative bars are on-demand: excluded from injection, reachable via search", async () => {
+  const { store, service } = setup({ dreamNarrativeEnabled: false });
+  service.saveWithDedupe({ type: "summary", title: "记忆库总览", content: "当前状态叙述", importance: 5, source: "dream" });
+  service.saveWithDedupe({ type: "summary", title: "叙述：部署", content: "部署主题的事实聚合，含部署关键词。", importance: 3, source: "narrative" });
+  const candidates = service.injectCandidates({ query: "", maxItems: 5 });
+  const ids = new Set(candidates.map((c) => c.id));
+  const overview = store.all().find((m) => m.source === "dream");
+  const bar = store.all().find((m) => m.source === "narrative");
+  assert.ok(ids.has(overview.id), "dream overview stays resident-injectable");
+  assert.ok(!ids.has(bar.id), "per-topic narrative excluded from injection");
+  const rows = await service.searchMemories("部署", { mode: "keyword" });
+  assert.ok(rows.some((r) => r.id === bar.id), "narrative reachable via search");
+  store.close();
+});

package/test/organize.test.js

@@ -0,0 +1,418 @@
+// #231：agent 主动整理接口——dryRun 比对报告 → agent 判断 → apply；筛除项进归档
+// 不删；调用全程复用 dream_runs 的 receipt 语义（不新建审计面）。维护者口径：
+// 功能本体落在 service 层并带测试，不进工具列表、不加独立 opt-in 开关。
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createStore } from "../src/store.js";
+import { createService } from "../src/service.js";
+import { createOrganizer } from "../src/organize.js";
+import { parseReceipt } from "../src/dream.js";
+
+const preference = (title, content = "内容", extra = {}) =>
+  ({ type: "preference", title, content, importance: 5, ...extra });
+
+/** 单元级 organizer：假 embedQuery 隔离向量档，写路径复用真 service。 */
+function makeOrganizer(embedQuery = async () => null, config = {}) {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config });
+  const finalizeCalls = [];
+  const { organize } = createOrganizer({
+    store,
+    embedQuery,
+    saveWithDedupe: service.saveWithDedupe,
+    transaction: service.transaction,
+    finalize: (rows) => finalizeCalls.push(rows)
+  });
+  return { store, service, organize, finalizeCalls };
+}
+
+test("#231: dryRun writes no memory and leaves one organize receipt", async () => {
+  const { store, service, organize } = makeOrganizer();
+  const seeded = service.saveWithDedupe(preference("偏好X", "既有内容")).memory;
+  const report = await organize({
+    mode: "dryRun",
+    candidates: [preference("偏好X", "同一标题的新内容"), { type: "decision", title: "全新决定", content: "库里没有" }]
+  });
+  assert.equal(report.items[0].verdict, "exact");
+  assert.equal(report.items[0].match.id, seeded.id);
+  assert.equal(report.items[1].verdict, "new");
+  assert.equal(report.counts.total, 2);
+  // 比对是报告不是动作：记忆表仍然只有种子那一行。
+  assert.equal(store.list({ limit: null }).length, 1);
+  const run = store.getDreamRun(report.run_id);
+  assert.equal(run.run_type, "organize");
+  assert.equal(run.status, "ok");
+  assert.equal(run.applied, 0);
+  assert.equal(parseReceipt(run.receipt).runId, report.run_id, "receipt 复用 dream 的既有格式");
+});
+
+test("#231: dryRun reports near duplicates with similarity (vector layer)", async () => {
+  const { store, service, organize } = makeOrganizer(async () => [0.99, 0.1, 0]);
+  const seeded = service.saveWithDedupe({ type: "decision", title: "令牌桶限流方案", content: "旧记录" }).memory;
+  store.setEmbedding(seeded.id, [1, 0, 0]);
+  const report = await organize({
+    mode: "dryRun",
+    candidates: [{ type: "decision", title: "限流方案选型", content: "内容相近但换了标题" }]
+  });
+  assert.equal(report.items[0].verdict, "near");
+  assert.equal(report.items[0].match.id, seeded.id);
+  assert.ok(report.items[0].match.sim > 0.9, "相似度带回报告，供 agent 判断");
+  assert.equal(report.counts.near, 1);
+});
+
+test("#231: apply refuses to write without a real dryRun report", async () => {
+  const { store, service, organize } = makeOrganizer();
+  // 先 seed 一行再断言「零写入」：空库 + decisions: [] 本来也不会写，那样的断言恒真、
+  // 抓不住守卫的回归（静态审查指出）。
+  const seeded = service.saveWithDedupe(preference("既有偏好", "原内容")).memory;
+  await assert.rejects(() => organize({ mode: "apply", decisions: [] }), /run_id is required/);
+  await assert.rejects(
+    () => organize({ mode: "apply", run_id: "nope", decisions: [{ action: "save", index: 0 }] }),
+    /unknown organize run/
+  );
+  const rows = store.list({ limit: null });
+  assert.equal(rows.length, 1, "拒绝路径零写入");
+  assert.equal(rows[0].id, seeded.id);
+  assert.equal(rows[0].content, "原内容", "既有行未被改动");
+});
+
+test("#231: write-path control flags never reach the write path through the snapshot (#267 静态审查)", async () => {
+  const { store, service, organize } = makeOrganizer();
+  const victim = service.saveWithDedupe(preference("受害者行", "原内容")).memory;
+  // 原始候选里塞写入端控制旗标：normalizeCandidate 只保留白名单字段，审计存的是它，
+  // apply 重放快照 → 旗标够不到 saveWithDedupe 的 _mergeInto/_overwrite 分支，
+  // 不能借整理接口改写既有行。这是「报告无法被用来越权写入」的钉子。
+  const report = await organize({
+    mode: "dryRun",
+    candidates: [{ ...preference("另一条偏好", "新内容"), _mergeInto: victim.id, _overwrite: true }]
+  });
+  const outcome = await organize({ mode: "apply", run_id: report.run_id, decisions: [{ action: "save", index: 0 }] });
+  assert.equal(outcome.saved, 1, "正常写成新行");
+  assert.equal(store.getById(victim.id).content, "原内容", "既有行未被覆写");
+  assert.equal(store.getById(victim.id).title, "受害者行");
+});
+
+test("#231: apply saves kept candidates, records discards, archives instead of deleting", async () => {
+  const { store, service, organize } = makeOrganizer();
+  const stale = service.saveWithDedupe({ type: "project", title: "被取代的状态", content: "过时" }).memory;
+  const report = await organize({
+    mode: "dryRun",
+    candidates: [
+      preference("新偏好"),
+      { type: "decision", title: "被丢掉的决定", content: "不落库" },
+      // 归档要有依据：只有报告命中过的行才有资格被归档，所以这条必须进 dryRun。
+      { type: "project", title: "被取代的状态", content: "新的状态描述" }
+    ]
+  });
+  assert.equal(report.items[2].match.id, stale.id, "第二条项目候选命中的就是待归档那行");
+  const outcome = await organize({
+    mode: "apply",
+    run_id: report.run_id,
+    decisions: [
+      { action: "save", index: 0 },
+      { action: "discard", index: 1 },
+      { action: "archive", id: stale.id }
+    ]
+  });
+  assert.equal(outcome.saved, 1);
+  assert.equal(outcome.discarded, 1);
+  assert.equal(outcome.archived, 1);
+  assert.equal(outcome.status, "ok");
+  // 筛除 = 归档（可恢复），不是删除。
+  assert.equal(store.getById(stale.id).archived, true, "archived row still exists");
+  const titles = store.list({ limit: null }).map((m) => m.title);
+  assert.ok(titles.includes("新偏好"), "kept candidate landed");
+  assert.ok(!titles.includes("被丢掉的决定"), "discarded candidate was not written");
+  // 审计链：apply 回执指向它依据的那份报告。
+  const applyRun = store.getDreamRun(outcome.run_id);
+  assert.equal(applyRun.outcome.dry_run_id, report.run_id);
+  assert.equal(applyRun.applied, 2);
+  assert.equal(parseReceipt(applyRun.receipt).status, "ok");
+});
+
+test("#231: the source columns do not split the match key (#267 评审第二轮)", async () => {
+  const { store, service, organize } = makeOrganizer();
+  const seeded = service.saveWithDedupe({
+    ...preference("同标题的约束"),
+    agent_scope: "agent-b",
+    agent_scope_source: "auto"
+  }).memory;
+  // 只差 agent_scope_source（auto vs explicit）：saveWithDedupe 的去重键不含来源两列，
+  // 所以这必须判成「命中既有行」。比对键里多带来源就会报 new，而 apply 却合并——错位。
+  const report = await organize({
+    mode: "dryRun",
+    candidates: [{ ...preference("同标题的约束"), agent_scope: "agent-b", agent_scope_source: "explicit" }]
+  });
+  assert.equal(report.items[0].verdict, "exact");
+  assert.equal(report.items[0].match.id, seeded.id);
+  const outcome = await organize({ mode: "apply", run_id: report.run_id, decisions: [{ action: "save", index: 0 }] });
+  assert.equal(outcome.merged, 1, "报告与写入同口径：命中既有行");
+  assert.equal(outcome.saved, 0);
+  assert.equal(store.list({ limit: null }).length, 1);
+});
+
+test("#231: dryRun compares in the candidate's own scope, not the payload's (#267 评审 1)", async () => {
+  const { service, organize } = makeOrganizer();
+  const seeded = service.saveWithDedupe({ ...preference("同标题的约束"), agent_scope: "agent-b" }).memory;
+  // 载荷级不给 scope，只在候选上给：报告必须按候选自己的 scope 看库，否则同一个
+  // scope 里明明已有同标题行也会报 "new"——报告 scope 与写入 scope 就此错位。
+  const report = await organize({
+    mode: "dryRun",
+    candidates: [{ ...preference("同标题的约束"), agent_scope: "agent-b" }]
+  });
+  assert.equal(report.items[0].verdict, "exact");
+  assert.equal(report.items[0].match.id, seeded.id);
+  // 反向：默认 scope 的候选看不到 agent-b 的行（跨 scope 永不互判，防泄漏）。
+  const other = await organize({ mode: "dryRun", candidates: [preference("同标题的约束")] });
+  assert.equal(other.items[0].verdict, "new");
+});
+
+test("#231: the same report cannot be applied twice (#267 评审 2)", async () => {
+  const { store, organize } = makeOrganizer();
+  const report = await organize({ mode: "dryRun", candidates: [preference("只应落一次")] });
+  await organize({ mode: "apply", run_id: report.run_id, decisions: [{ action: "save", index: 0 }] });
+  await assert.rejects(
+    () => organize({ mode: "apply", run_id: report.run_id, decisions: [{ action: "save", index: 0 }] }),
+    /already applied/
+  );
+  assert.equal(store.list({ limit: null }).filter((m) => m.title === "只应落一次").length, 1);
+  const receipts = store.listDreamRuns({}).filter((r) => r.outcome?.dry_run_id === report.run_id);
+  assert.equal(receipts.length, 1, "同一份报告只留一份落地回执");
+  assert.ok(store.getDreamRun(report.run_id).outcome.applied_at, "报告行上留了已落地凭证");
+});
+
+test("#231: archive only accepts ids the report flagged as matches (#267 评审 3)", async () => {
+  const { store, service, organize } = makeOrganizer();
+  const bystander = service.saveWithDedupe({ type: "project", title: "报告没提过的项目行", content: "无关" }).memory;
+  const report = await organize({ mode: "dryRun", candidates: [preference("只有偏好类")] });
+  const outcome = await organize({
+    mode: "apply",
+    run_id: report.run_id,
+    decisions: [{ action: "archive", id: bystander.id }]
+  });
+  assert.equal(outcome.archived, 0);
+  assert.match(outcome.skipped[0].error, /not flagged as a match/);
+  assert.equal(store.getById(bystander.id).archived, false, "报告没提过的行不许被动");
+  assert.equal(outcome.status, "degraded");
+});
+
+test("#231: merged candidates count as merged, not as new saves (#267 评审 2)", async () => {
+  const { store, service, organize } = makeOrganizer();
+  service.saveWithDedupe(preference("已被记下的偏好", "旧内容"));
+  const report = await organize({ mode: "dryRun", candidates: [preference("已被记下的偏好", "新内容")] });
+  assert.equal(report.items[0].verdict, "exact");
+  const outcome = await organize({ mode: "apply", run_id: report.run_id, decisions: [{ action: "save", index: 0 }] });
+  assert.equal(outcome.saved, 0, "同键命中走合并，不是新建");
+  assert.equal(outcome.merged, 1);
+  assert.equal(outcome.status, "ok", "合并也是落地生效，不能记成 noop");
+  assert.equal(store.list({ limit: null }).length, 1);
+  assert.equal(store.getDreamRun(outcome.run_id).applied, 1);
+});
+
+test("#231: a failing audit write does not replace the original error (#267 评审 4)", async () => {
+  const { store, organize } = makeOrganizer();
+  const report = await organize({ mode: "dryRun", candidates: [preference("会失败的落地")] });
+  // 审计整体不可用：事务内的「已落地」标记先抛 → 回滚 → 失败回执也写不进去。
+  store.saveDreamRun = () => {
+    throw new Error("audit unavailable");
+  };
+  await assert.rejects(
+    () => organize({ mode: "apply", run_id: report.run_id, decisions: [{ action: "save", index: 0 }] }),
+    (err) => {
+      assert.match(err.message, /audit unavailable/, "原始错误原样抛出");
+      assert.match(err.audit_error, /audit unavailable/, "审计的失败挂上去，不被静默吞掉");
+      return true;
+    }
+  );
+});
+
+test("#231: apply tolerates bad decisions — legal subset lands, run is degraded", async () => {
+  const { store, organize } = makeOrganizer();
+  const report = await organize({ mode: "dryRun", candidates: [preference("能落的")] });
+  const outcome = await organize({
+    mode: "apply",
+    run_id: report.run_id,
+    decisions: [
+      { action: "save", index: 0 },
+      { action: "save", index: 9 },           // 越界
+      { action: "archive", id: "m_missing" }, // 未知 id
+      { action: "explode", index: 0 }         // 未知动作
+    ]
+  });
+  assert.equal(outcome.saved, 1, "legal subset applied");
+  assert.equal(outcome.skipped.length, 3);
+  assert.equal(outcome.status, "degraded");
+  assert.equal(outcome.degraded, true);
+  assert.equal(store.getDreamRun(outcome.run_id).skipped.length, 3, "逐条跳过明细进审计");
+});
+
+test("#231: dryRun refuses document candidates (registerDocument is the only mint)", async () => {
+  const { organize } = makeOrganizer();
+  const report = await organize({ mode: "dryRun", candidates: [{ type: "document", title: "长文", content: "摘要" }] });
+  assert.equal(report.counts.total, 0);
+  assert.equal(report.status, "degraded");
+  assert.match(report.skipped[0].error, /registerDocument/);
+});
+
+test("#231: dryRun bounds the batch and reports the truncation", async () => {
+  const { organize } = makeOrganizer();
+  const report = await organize({
+    mode: "dryRun",
+    candidates: Array.from({ length: 55 }, (_, i) => preference(`偏好${i}`))
+  });
+  assert.equal(report.counts.total, 50);
+  assert.equal(report.counts.truncated, 5);
+});
+
+test("#231: single entry point with a mode parameter, exported through the service barrel", async () => {
+  const { service, organize } = makeOrganizer();
+  await assert.rejects(() => organize({ mode: "wat" }), /unknown mode/);
+  assert.equal(typeof service.organize, "function", "service 层 barrel 出口（调用方零改动）");
+  const report = await service.organize({ mode: "dryRun", candidates: [preference("走 service 的")] });
+  assert.equal(report.counts.total, 1);
+});
+
+// --- 以下为 CodeRabbit #267 复核后补的边界：报告的索引/scope 必须与落库严格一致 ---
+
+test("#231: payload-level scope travels with the snapshot into the write", async () => {
+  const { store, organize } = makeOrganizer();
+  const report = await organize({
+    mode: "dryRun",
+    agent_scope: "agent-a",
+    candidates: [preference("带 scope 的偏好")]
+  });
+  const run = store.getDreamRun(report.run_id);
+  assert.equal(run.input[0].agent_scope, "agent-a", "审计存的是带 scope 的规范化快照");
+  assert.equal(run.input[0].index, 0, "快照保留原始索引，apply 才能按索引重放");
+  assert.equal(run.input[0].type, "preference");
+  await organize({ mode: "apply", run_id: report.run_id, decisions: [{ action: "save", index: 0 }] });
+  assert.equal(store.list({ limit: null })[0].agent_scope, "agent-a", "比对用的 scope 就是落地用的 scope");
+});
+
+test("#231: apply cannot land an index the dryRun never accepted", async () => {
+  const { store, organize } = makeOrganizer();
+  const report = await organize({
+    mode: "dryRun",
+    candidates: [preference("合法的"), { type: "document", title: "长文", content: "摘要" }]
+  });
+  assert.equal(report.counts.skipped, 1);
+  const outcome = await organize({
+    mode: "apply",
+    run_id: report.run_id,
+    decisions: [{ action: "save", index: 1 }] // dryRun 当时就拒了这一条
+  });
+  assert.equal(outcome.saved, 0);
+  assert.equal(outcome.status, "degraded");
+  assert.match(outcome.skipped[0].error, /not accepted by this dryRun/);
+  assert.equal(store.list({ limit: null }).length, 0, "被跳过的候选没有资格落库");
+});
+
+test("#231: apply refuses an apply receipt as its dryRun reference", async () => {
+  const { organize } = makeOrganizer();
+  const report = await organize({ mode: "dryRun", candidates: [preference("第一条")] });
+  const first = await organize({ mode: "apply", run_id: report.run_id, decisions: [{ action: "save", index: 0 }] });
+  // 两者共用 run_type='organize'，只有 outcome.dry_run_id 能把回执与报告分开。
+  await assert.rejects(
+    () => organize({ mode: "apply", run_id: first.run_id, decisions: [{ action: "save", index: 0 }] }),
+    /apply receipt/
+  );
+});
+
+test("#231: a throwing embedder fails the dryRun, audits it and rethrows", async () => {
+  const { store, service } = makeOrganizer(async () => {
+    throw new Error("embedder offline");
+  });
+  const seeded = service.saveWithDedupe({ type: "preference", title: "已有向量", content: "内容" }).memory;
+  store.setEmbedding(seeded.id, [1, 0, 0]);
+  const seen = [];
+  const observed = createOrganizer({
+    store: { ...store, saveDreamRun: (row) => { seen.push(row); return store.saveDreamRun(row); } },
+    embedQuery: async () => {
+      throw new Error("embedder offline");
+    },
+    saveWithDedupe: service.saveWithDedupe,
+    transaction: service.transaction
+  });
+  await assert.rejects(() => observed.organize({ mode: "dryRun", candidates: [preference("新的一条")] }), /embedder offline/);
+  assert.equal(seen.at(-1).status, "failed", "基础设施错误留 failed 回执，不降级成「全是新条目」");
+  assert.match(seen.at(-1).error, /embedder offline/);
+  assert.equal(store.list({ limit: null }).length, 1, "失败路径零写入");
+});
+
+test("#231: an infrastructure write error rolls back and reports applied 0", async () => {
+  const { store, service, organize } = makeOrganizer();
+  const report = await organize({ mode: "dryRun", candidates: [preference("会写失败的")] });
+  const seen = [];
+  const failing = createOrganizer({
+    store: { ...store, saveDreamRun: (row) => { seen.push(row); return store.saveDreamRun(row); } },
+    embedQuery: async () => null,
+    saveWithDedupe: () => {
+      throw new Error("database is locked");
+    },
+    transaction: service.transaction
+  });
+  await assert.rejects(
+    () => failing.organize({ mode: "apply", run_id: report.run_id, decisions: [{ action: "save", index: 0 }] }),
+    /database is locked/
+  );
+  assert.equal(store.list({ limit: null }).length, 0, "整批回滚，零写入");
+  const failed = seen.at(-1);
+  assert.equal(failed.status, "failed");
+  assert.equal(failed.applied, 0, "回滚后不得虚报 applied");
+  assert.deepEqual(failed.outcome.byId, {});
+});
+
+test("#231: a failing success audit rolls the writes back with it", async () => {
+  const { store, service, organize } = makeOrganizer();
+  const report = await organize({ mode: "dryRun", candidates: [preference("回执写不进去")] });
+  let auditFailures = 0;
+  const audited = {
+    ...store,
+    saveDreamRun: (row) => {
+      if (row.run_type === "organize" && row.status === "ok" && row.id !== report.run_id) {
+        auditFailures++;
+        throw new Error("audit table is full");
+      }
+      return store.saveDreamRun(row);
+    }
+  };
+  const { organize: proxied } = createOrganizer({
+    store: audited,
+    embedQuery: async () => null,
+    saveWithDedupe: service.saveWithDedupe,
+    transaction: service.transaction
+  });
+  await assert.rejects(
+    () => proxied({ mode: "apply", run_id: report.run_id, decisions: [{ action: "save", index: 0 }] }),
+    /audit table is full/
+  );
+  assert.equal(auditFailures, 1);
+  assert.equal(store.list({ limit: null }).length, 0, "成功回执与数据同事务：回执写不进去 → 数据也回滚");
+});
+
+test("#231: finalize runs after commit with the saved rows, and not for empty batches", async () => {
+  const { store, organize, finalizeCalls } = makeOrganizer();
+  const report = await organize({ mode: "dryRun", candidates: [preference("要重嵌入的")] });
+  await organize({ mode: "apply", run_id: report.run_id, decisions: [{ action: "save", index: 0 }] });
+  assert.equal(finalizeCalls.length, 1, "提交后补一次重嵌入（transaction 里被 txDepth 挡掉）");
+  assert.equal(finalizeCalls[0][0].id, store.list({ limit: null })[0].id);
+  const discardsOnly = await organize({ mode: "dryRun", candidates: [preference("只丢弃")] });
+  await organize({ mode: "apply", run_id: discardsOnly.run_id, decisions: [{ action: "discard", index: 0 }] });
+  assert.equal(finalizeCalls.length, 1, "noop 批次不触发 finalize");
+});
+
+test("#231: archive honours the hidden-id set from the trusted caller, not the payload", async () => {
+  const { store, service, organize } = makeOrganizer();
+  const outOfScope = service.saveWithDedupe({ type: "project", title: "看不见的项目", content: "内容" }).memory;
+  const report = await organize({ mode: "dryRun", candidates: [preference("占位")] });
+  // opts 是第二参数（document 的 hiddenEvidenceIds 同款契约）：payload 里的同名字段
+  // 一律不认——那是调用方可自选的内容，不是授权。
+  const outcome = await service.organize(
+    { mode: "apply", run_id: report.run_id, decisions: [{ action: "archive", id: outOfScope.id }] },
+    { hiddenIds: [outOfScope.id] }
+  );
+  assert.equal(outcome.archived, 0);
+  assert.match(outcome.skipped[0].error, /out of scope/);
+  assert.equal(store.getById(outOfScope.id).archived, false, "看不见的行按不存在处理，不归档");
+});