recallnest 2.6.0 → 3.0.0

package/src/__tests__/consolidation-engine.test.ts

@@ -59,6 +59,25 @@ function createMockStore(entries: MemoryEntry[], similarityMap: Map<string, Map<
         }
         return entry;
       },
+      // 2026-08-14: 忠实模拟生产语义 —— 以 mock 存储的最新行起底应用 patchFn、按序执行、
+      // 就地落库。批量写同样进 updates 数组，既有的 updates.find() 断言无需改动。
+      async patchMetadataBatch(
+        patches: Array<{ id: string; patchFn: (meta: Record<string, unknown>, entry: MemoryEntry) => Record<string, unknown> }>,
+        _scopeFilter?: string[],
+      ) {
+        let written = 0;
+        for (const { id, patchFn } of patches) {
+          const entry = data.get(id);
+          if (!entry) continue;
+          let meta: Record<string, unknown>;
+          try { meta = JSON.parse(entry.metadata || "{}") as Record<string, unknown>; } catch { meta = {}; }
+          const patched = patchFn(meta, entry);
+          entry.metadata = JSON.stringify(patched);
+          updates.push({ id, metadata: entry.metadata });
+          written++;
+        }
+        return written;
+      },
     },
   };
 }
@@ -81,6 +100,77 @@ describe("ConsolidationEngine", () => {
     expect(result.clustersFound).toBe(0);
   });
 
+  // 2026-08-14 Bug-1 回归：旧逐条写路径里 cluster 循环基于从不刷新的旧内存串 patch，
+  // member 的 consolidatedMeta 写与 canonical 的 sourceMemories 写会把 createVersionGroup
+  // 刚落库的 version_group 抹掉（2 成员 cluster 同样全丢），下一个 member 还会新造 groupId。
+  // 断言口径是**最终存储态**（getById 终值）——旧测试用 updates.find() 只看首写，恰好
+  // 看不见覆盖（互审 C3 指出的断言形态缺陷）。
+  it("Bug-1 回归：2 成员 merge 后双方 version_group 同组共存，sourceMemories/consolidatedInto 齐全", async () => {
+    const entryA = makeEntry({ id: "a", text: "canonical fact", vector: [1, 0, 0], importance: 0.9 });
+    const entryB = makeEntry({ id: "b", text: "duplicate fact", vector: [0.99, 0.1, 0], importance: 0.5 });
+    const simMap = new Map([
+      ["a", new Map([["b", 0.95]])],
+      ["b", new Map([["a", 0.95]])],
+    ]);
+    const { store } = createMockStore([entryA, entryB], simMap);
+    const engine = new ConsolidationEngine(store, { ...DEFAULT_CONSOLIDATION_CONFIG, mergeThreshold: 0.92 });
+    await engine.run("project:test");
+
+    const finalA = JSON.parse((await store.getById("a"))!.metadata!) as Record<string, any>;
+    const finalB = JSON.parse((await store.getById("b"))!.metadata!) as Record<string, any>;
+    expect(typeof finalA.version_group).toBe("string");
+    expect(finalB.version_group).toBe(finalA.version_group); // 同组，且都没被后续写抹掉
+    expect(typeof finalA.version_rank).toBe("number");
+    expect(typeof finalB.version_rank).toBe("number");
+    expect(finalA.evolution.sourceMemories).toContain("b");
+    expect(finalB.evolution.status).toBe("consolidated");
+    expect(finalB.evolution.consolidatedInto).toBe("a");
+  });
+
+  it("Bug-1 回归：多 member merge 共享同一个 groupId，canonical 的 sourceMemories 不丢前面的 member", async () => {
+    const entryA = makeEntry({ id: "a", text: "fact v1", vector: [1, 0, 0], importance: 0.9 });
+    const entryB = makeEntry({ id: "b", text: "fact v2", vector: [0.99, 0.1, 0], importance: 0.5 });
+    const entryC = makeEntry({ id: "c", text: "fact v3", vector: [0.98, 0.15, 0], importance: 0.4 });
+    const simMap = new Map([
+      ["a", new Map([["b", 0.95], ["c", 0.94]])],
+      ["b", new Map([["a", 0.95], ["c", 0.93]])],
+      ["c", new Map([["a", 0.94], ["b", 0.93]])],
+    ]);
+    const { store } = createMockStore([entryA, entryB, entryC], simMap);
+    const engine = new ConsolidationEngine(store, { ...DEFAULT_CONSOLIDATION_CONFIG, mergeThreshold: 0.92 });
+    await engine.run("project:test");
+
+    const finalA = JSON.parse((await store.getById("a"))!.metadata!) as Record<string, any>;
+    const finalB = JSON.parse((await store.getById("b"))!.metadata!) as Record<string, any>;
+    const finalC = JSON.parse((await store.getById("c"))!.metadata!) as Record<string, any>;
+    expect(typeof finalA.version_group).toBe("string");
+    expect(finalB.version_group).toBe(finalA.version_group); // 旧路径这里各是一个新组
+    expect(finalC.version_group).toBe(finalA.version_group);
+    expect(finalA.evolution.sourceMemories).toEqual(expect.arrayContaining(["b", "c"])); // 旧路径只剩最后一个
+  });
+
+  it("link 分支回归：多 member 时 canonical 的 cluster_members 累积全部（不再只剩最后一个）", async () => {
+    const entryA = makeEntry({ id: "a", text: "topic center", vector: [1, 0, 0], importance: 0.9 });
+    const entryB = makeEntry({ id: "b", text: "related one", vector: [0.9, 0.3, 0], importance: 0.5 });
+    const entryC = makeEntry({ id: "c", text: "related two", vector: [0.88, 0.35, 0], importance: 0.4 });
+    // 0.85 落在 clusterThreshold(0.82) 与 mergeThreshold(0.92) 之间 → link 分支
+    const simMap = new Map([
+      ["a", new Map([["b", 0.85], ["c", 0.85]])],
+      ["b", new Map([["a", 0.85], ["c", 0.84]])],
+      ["c", new Map([["a", 0.85], ["b", 0.84]])],
+    ]);
+    const { store } = createMockStore([entryA, entryB, entryC], simMap);
+    const engine = new ConsolidationEngine(store, { ...DEFAULT_CONSOLIDATION_CONFIG, clusterThreshold: 0.82, mergeThreshold: 0.92 });
+    await engine.run("project:test");
+
+    const finalA = JSON.parse((await store.getById("a"))!.metadata!) as Record<string, any>;
+    const finalB = JSON.parse((await store.getById("b"))!.metadata!) as Record<string, any>;
+    const finalC = JSON.parse((await store.getById("c"))!.metadata!) as Record<string, any>;
+    expect(finalA.cluster_members).toEqual(expect.arrayContaining(["b", "c"]));
+    expect(finalB.clustered_with).toBe("a");
+    expect(finalC.clustered_with).toBe("a");
+  });
+
   it("merges near-duplicates above mergeThreshold", async () => {
     const entryA = makeEntry({ id: "a", text: "I prefer TypeScript", vector: [1, 0, 0], importance: 0.9 });
     const entryB = makeEntry({ id: "b", text: "I prefer TypeScript language", vector: [0.99, 0.1, 0], importance: 0.5 });

package/src/__tests__/contracts.test.ts

@@ -185,7 +185,7 @@ describe("MCP registry contract", () => {
   it("keeps registered tool count and tier header in sync", () => {
     const source = readFileSync(join(import.meta.dir, "..", "mcp-server.ts"), "utf8");
     const header = source.slice(0, source.indexOf("const TOOL_TIERS"));
-    // P3-B: the 43 registerTool(...) calls now live in the tier modules; mcp-server.ts
+    // P3-B: the 44 registerTool(...) calls now live in the tier modules; mcp-server.ts
     // still owns TOOL_TIERS and the tier-count header comment above it.
     const registeredTools = ["mcp-tools-core", "mcp-tools-advanced", "mcp-tools-governance"]
       .flatMap((name) =>
@@ -208,7 +208,7 @@ describe("MCP registry contract", () => {
       return Number(match![1]);
     };
 
-    expect(registeredTools).toHaveLength(43);
+    expect(registeredTools).toHaveLength(44);
     expect(missingTier).toEqual([]);
     expect(headerCount("core")).toBe(coreCount);
     expect(headerCount("advanced")).toBe(defaultCount);

package/src/__tests__/data-checkup.test.ts

@@ -32,11 +32,17 @@ function makeEntry(overrides: Partial<MemoryEntry> & { id: string }): MemoryEntr
   };
 }
 
-function createMockStore(entries: MemoryEntry[]): Pick<MemoryStore, "list" | "stats" | "getVectors"> {
+function createMockStore(entries: MemoryEntry[]): Pick<MemoryStore, "list" | "listPage" | "stats" | "getVectors"> {
   return {
     // 复刻真实 store:list() 为性能不返回向量(vector: []),维度/干扰检查需经 getVectors 补回。
     // 旧 mock 直接返回带向量的 entry,与生产行为不符,曾掩盖维度检查在生产假报健康的 bug。
-    async list() { return entries.map(e => ({ ...e, vector: [] })); },
+    async list(_scope?: string[], _category?: string, limit = 20, offset = 0) {
+      return entries.slice(offset, offset + limit).map(e => ({ ...e, vector: [] }));
+    },
+    async listPage(opts: { limit?: number; offset?: number } = {}) {
+      const { limit = 1000, offset = 0 } = opts;
+      return entries.slice(offset, offset + limit).map(e => ({ ...e, vector: [] }));
+    },
     async stats() {
       return { totalCount: entries.length, scopeCounts: {}, categoryCounts: {} };
     },
@@ -47,7 +53,7 @@ function createMockStore(entries: MemoryEntry[]): Pick<MemoryStore, "list" | "st
       }
       return map;
     },
-  } as Pick<MemoryStore, "list" | "stats" | "getVectors">;
+  } as Pick<MemoryStore, "list" | "listPage" | "stats" | "getVectors">;
 }
 
 // ---------------------------------------------------------------------------
@@ -242,6 +248,28 @@ describe("runDataCheckup", () => {
     expect(vgCheck.detail).toContain("missing rank");
   });
 
+  it("checks version groups against the full corpus when the 10k sample splits a healthy pair", async () => {
+    const pair = ["a", "b"].map(id => makeEntry({
+      id,
+      metadata: JSON.stringify({ version_group: "vg-split", version_rank: 1 }),
+    }));
+    const base = createMockStore(pair);
+    const store = {
+      ...base,
+      // Simulate the recent-sample boundary: only one member is visible to list(),
+      // while the paged full-corpus scan still sees both.
+      async list() { return [{ ...pair[0], vector: [] }]; },
+    };
+
+    const report = await runDataCheckup({ store, openConflictCount: 0 });
+
+    expect(report.totalEntries).toBe(1);
+    expect(report.totalAvailable).toBe(2);
+    const vgCheck = report.checks.find(c => c.name === "version_groups")!;
+    expect(vgCheck.status).toBe("ok");
+    expect(vgCheck.detail).toContain("all healthy");
+  });
+
   it("handles empty database", async () => {
     const report = await runDataCheckup({
       store: createMockStore([]),

package/src/__tests__/dream-pipeline.test.ts

@@ -79,6 +79,7 @@ function createMockStore(entries: MemoryEntry[]): MemoryStore {
         categoryCounts: {},
       };
     },
+    async repairSingletonVersionGroups() { return 0; },
     async store(entry: Partial<MemoryEntry>) {
       const full = {
         id: entry.id || `dream-${storeCounter++}`,
@@ -121,6 +122,29 @@ function createMockStore(entries: MemoryEntry[]): MemoryStore {
       entry.metadata = JSON.stringify(patchFn(meta, entry));
       return entry;
     },
+    // 2026-08-14 批量通道：语义同上面的单条 patchMetadata，按序逐条以最新行起底
+    async patchMetadataBatch(
+      patches: Array<{ id: string; patchFn: (meta: Record<string, unknown>, entry: MemoryEntry) => Record<string, unknown> }>,
+      _scopeFilter?: string[],
+    ) {
+      let written = 0;
+      for (const { id, patchFn } of patches) {
+        const entry = stored.find(e => e.id === id);
+        if (!entry) continue;
+        let meta: Record<string, unknown>;
+        try {
+          const parsed: unknown = JSON.parse(entry.metadata || "{}");
+          meta = parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)
+            ? (parsed as Record<string, unknown>)
+            : {};
+        } catch {
+          meta = {};
+        }
+        entry.metadata = JSON.stringify(patchFn(meta, entry));
+        written++;
+      }
+      return written;
+    },
     async vectorSearch(_vec: number[], limit: number, _threshold: number, _scopes?: string[]) {
       return stored.slice(0, limit).map(e => ({ entry: e, score: 0.85 }));
     },
@@ -679,12 +703,28 @@ describe("shouldBlockDreamRun", () => {
     expect(shouldBlockDreamRun({ totalScopes: 475, fatalFailures: 0, transientFailures: 0 })).toBe(false);
     expect(shouldBlockDreamRun({ totalScopes: 0, fatalFailures: 0, transientFailures: 0 })).toBe(false);
   });
+
+  // 2026-08-14: transcript 出队后队列缩到个位数，1/1 = 100% > 20% 曾把单个瞬态锁竞争
+  // 判成整轮红（当天验证轮实测）。绝对量豁免：transient ≤ 2 不算「成规模」。
+  it("小队列豁免：个位数队列里 1-2 个瞬态失败不判 blocked", () => {
+    expect(shouldBlockDreamRun({ totalScopes: 1, fatalFailures: 0, transientFailures: 1 })).toBe(false);
+    expect(shouldBlockDreamRun({ totalScopes: 2, fatalFailures: 0, transientFailures: 2 })).toBe(false);
+    expect(shouldBlockDreamRun({ totalScopes: 3, fatalFailures: 0, transientFailures: 2 })).toBe(false);
+  });
+
+  it("小队列豁免不放过 fatal，也不放过超出绝对量的比例失败", () => {
+    expect(shouldBlockDreamRun({ totalScopes: 1, fatalFailures: 1, transientFailures: 0 })).toBe(true);
+    // 3 个 transient 超出绝对豁免（2），且 3/5 = 60% > 20% → 该红还是红
+    expect(shouldBlockDreamRun({ totalScopes: 5, fatalFailures: 0, transientFailures: 3 })).toBe(true);
+  });
 });
 
 describe("autoRunBudgetMs default", () => {
   it("caps one --auto sweep well below a day", () => {
     // 07-24 那轮 4 天 15 小时，堵死三天调度。预算是防跨天的兜底闸。
-    expect(DEFAULT_DREAM_CONFIG.autoRunBudgetMs).toBe(6 * 60 * 60 * 1000);
+    // 2026-08-14: 6h→2h —— transcript 出队后 inline 队列只剩个位数 durable scope，
+    // 典型轮次分钟级，2h 是纯兜底（单 scope 路径不走本预算）。
+    expect(DEFAULT_DREAM_CONFIG.autoRunBudgetMs).toBe(2 * 60 * 60 * 1000);
     expect(DEFAULT_DREAM_CONFIG.autoRunBudgetMs).toBeLessThan(24 * 60 * 60 * 1000);
   });
 });

package/src/__tests__/dream-scope-isolation.test.ts

@@ -0,0 +1,386 @@
+/**
+ * dream 的 scope 隔离与策略排除（2026-08-16）。
+ *
+ * 为什么单开一个文件而不是塞进 dream-pipeline.test.ts：那边的 mock store **吞掉 scope
+ * 参数**（`list()` 无视 scopeFilter、`vectorSearch(_vec, limit, _threshold, _scopes)` 直接
+ * 返回全部行），所以哪怕 exact 模式压根没传到 3a，那些测试也照样全绿 —— 互审 C3 指出的
+ * 正是这一点。本文件两层：
+ *   L1 真实 MemoryStore 验 store 的 family/exact 两种语义（现有 prefix 行为必须保住）
+ *   L2 scope-aware mock 验 dream/3a 是否真把模式传到了每一层取数点
+ * 外加 L3 策略排除、L4 派生 insight 不参与 3a。
+ */
+import { afterEach, describe, expect, it } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { MemoryStore, type MemoryEntry } from "../store.js";
+import type { MemoryStorePort } from "../memory-store-port.js";
+import type { ScopeMatchMode } from "../scope-policy.js";
+import { matchesScopeFilter } from "../scope-policy.js";
+import { cosineSimilarity } from "../multi-vector.js";
+import { runDream, DEFAULT_DREAM_CONFIG } from "../dream-pipeline.js";
+import { ConsolidationEngine, DEFAULT_CONSOLIDATION_CONFIG } from "../consolidation-engine.js";
+import { getWriteCount, incrementWriteCount, resetWriteCount } from "../activity-counter.js";
+import type { LLMClient } from "../llm-client.js";
+import type { Embedder } from "../embedder.js";
+
+const cleanupPaths: string[] = [];
+
+afterEach(() => {
+  while (cleanupPaths.length > 0) {
+    const target = cleanupPaths.pop();
+    if (target) rmSync(target, { recursive: true, force: true });
+  }
+});
+
+function tempDb(): string {
+  const dbPath = mkdtempSync(join(tmpdir(), "recallnest-dream-scope-"));
+  cleanupPaths.push(dbPath);
+  return dbPath;
+}
+
+/**
+ * ⚠️ activity-counter 的默认 statsPath 指向**生产** `data/activity-stats.json`。
+ * 不传 statsPath 就调 resetWriteCount/incrementWriteCount = 直接改真库的写计数
+ * （本文件初版就这么干了：把生产的 `memory: 14` 删了，已手工恢复并留 bak）。
+ * 所有涉及写计数的测试一律走这个临时路径。
+ */
+function tempStatsPath(): { statsPath: string } {
+  const dir = mkdtempSync(join(tmpdir(), "recallnest-dream-stats-"));
+  cleanupPaths.push(dir);
+  return { statsPath: join(dir, "activity-stats.json") };
+}
+
+// ---------------------------------------------------------------------------
+// L1 — 真实 MemoryStore：family（历史行为）vs exact（新增）
+// ---------------------------------------------------------------------------
+
+describe("MemoryStore scope matching modes", () => {
+  async function seeded(): Promise<MemoryStore> {
+    const store = new MemoryStore({ dbPath: tempDb(), vectorDim: 3 });
+    await store.store({ text: "rule doc chunk", vector: [1, 0, 0], category: "fact", scope: "memory", importance: 0.5 });
+    await store.store({ text: "hand-written pivot", vector: [1, 0, 0], category: "fact", scope: "memory:pivot", importance: 0.9 });
+    await store.store({ text: "unrelated", vector: [0, 1, 0], category: "fact", scope: "project:other", importance: 0.5 });
+    return store;
+  }
+
+  it("list: family 模式对无冒号 scope 按前缀（保住既有行为）", async () => {
+    const store = await seeded();
+    const rows = await store.list(["memory"], undefined, 100, 0);
+    expect(rows.map(r => r.scope).sort()).toEqual(["memory", "memory:pivot"]);
+  });
+
+  it("list: exact 模式只命中同名 scope", async () => {
+    const store = await seeded();
+    const rows = await store.list(["memory"], undefined, 100, 0, "exact");
+    expect(rows.map(r => r.scope)).toEqual(["memory"]);
+  });
+
+  it("stats: 两种模式的 totalCount 不同", async () => {
+    const store = await seeded();
+    expect((await store.stats(["memory"])).totalCount).toBe(2);
+    expect((await store.stats(["memory"], "exact")).totalCount).toBe(1);
+  });
+
+  it("vectorSearch: exact 模式不返回兄弟 scope 的行", async () => {
+    const store = await seeded();
+    const family = await store.vectorSearch([1, 0, 0], 10, 0.1, ["memory"]);
+    expect(family.map(r => r.entry.scope).sort()).toEqual(["memory", "memory:pivot"]);
+
+    const exact = await store.vectorSearch([1, 0, 0], 10, 0.1, ["memory"], "exact");
+    expect(exact.map(r => r.entry.scope)).toEqual(["memory"]);
+  });
+
+  it("含冒号的 scope 两种模式都精确（family 的隐式规则不受影响）", async () => {
+    const store = await seeded();
+    expect((await store.list(["memory:pivot"], undefined, 100, 0)).length).toBe(1);
+    expect((await store.list(["memory:pivot"], undefined, 100, 0, "exact")).length).toBe(1);
+  });
+
+  it("exact 模式下 `memory:` 命中空集 —— 拿冒号形当修法会静默 noop", async () => {
+    // 互审 K2：曾被考虑过的"让 weekly 传 memory: 绕开前缀"路线在这里被钉死为反例。
+    const store = await seeded();
+    expect((await store.list(["memory:"], undefined, 100, 0)).length).toBe(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// L2/L3/L4 — scope-aware mock：验模式有没有真传到每一层
+// ---------------------------------------------------------------------------
+
+/**
+ * 与 dream-pipeline.test.ts 的 mock 的关键差别：**这个 mock 认 scope 也认 mode**。
+ * 漏传 exact 会让下面的断言真的红，这正是它存在的理由。
+ */
+function createScopeAwareStore(entries: MemoryEntry[]) {
+  const stored: MemoryEntry[] = entries.map(e => ({ ...e }));
+  let counter = 0;
+  const patchedIds: string[] = [];
+
+  const select = (scopeFilter?: string[], mode: ScopeMatchMode = "family") =>
+    stored.filter(e => matchesScopeFilter(e.scope, scopeFilter, mode));
+
+  const store = {
+    async list(scopeFilter?: string[], _category?: string, limit = 20, offset = 0, scopeMatch: ScopeMatchMode = "family") {
+      // 复刻生产：list 恒返回假空向量
+      return select(scopeFilter, scopeMatch).slice(offset, offset + limit).map(e => ({ ...e, vector: [] as number[] }));
+    },
+    async listPage(opts: { scopeFilter?: string[]; limit?: number; offset?: number } = {}) {
+      const { scopeFilter, limit = 1000, offset = 0 } = opts;
+      return select(scopeFilter).slice(offset, offset + limit).map(e => ({ ...e, vector: [] as number[] }));
+    },
+    async getVectors(ids: string[]) {
+      const m = new Map<string, number[]>();
+      for (const id of ids) {
+        const e = stored.find(x => x.id === id);
+        if (e?.vector?.length) m.set(id, e.vector);
+      }
+      return m;
+    },
+    async stats(scopeFilter?: string[], scopeMatch: ScopeMatchMode = "family") {
+      return { totalCount: select(scopeFilter, scopeMatch).length, scopeCounts: {}, categoryCounts: {} };
+    },
+    async repairSingletonVersionGroups() { return 0; },
+    async getById(id: string) {
+      return stored.find(e => e.id === id) ?? null;
+    },
+    async store(entry: Partial<MemoryEntry>) {
+      const full = {
+        id: entry.id || `gen-${counter++}`,
+        text: entry.text || "",
+        vector: entry.vector || [],
+        category: entry.category || "events",
+        scope: entry.scope || "project:test",
+        importance: entry.importance ?? 0.5,
+        timestamp: Date.now(),
+        metadata: entry.metadata || "{}",
+      } as MemoryEntry;
+      stored.push(full);
+      return full;
+    },
+    async update(id: string, upd: Partial<MemoryEntry>) {
+      const e = stored.find(x => x.id === id);
+      if (e && upd.metadata) e.metadata = upd.metadata;
+      return e ?? null;
+    },
+    async patchMetadata(id: string, patchFn: (m: Record<string, unknown>, e: MemoryEntry) => Record<string, unknown>) {
+      const e = stored.find(x => x.id === id);
+      if (!e) return null;
+      patchedIds.push(id);
+      e.metadata = JSON.stringify(patchFn(JSON.parse(e.metadata || "{}"), e));
+      return e;
+    },
+    async patchMetadataBatch(
+      patches: Array<{ id: string; patchFn: (m: Record<string, unknown>, e: MemoryEntry) => Record<string, unknown> }>,
+    ) {
+      let written = 0;
+      for (const { id, patchFn } of patches) {
+        const e = stored.find(x => x.id === id);
+        if (!e) continue;
+        patchedIds.push(id);
+        e.metadata = JSON.stringify(patchFn(JSON.parse(e.metadata || "{}"), e));
+        written++;
+      }
+      return written;
+    },
+    async vectorSearch(vec: number[], limit = 5, minScore = 0.3, scopeFilter?: string[], scopeMatch: ScopeMatchMode = "family") {
+      return select(scopeFilter, scopeMatch)
+        .filter(e => e.vector?.length)
+        .map(e => ({ entry: e, score: cosineSimilarity(vec, e.vector) }))
+        .filter(r => r.score >= minScore)
+        .sort((a, b) => b.score - a.score)
+        .slice(0, limit);
+    },
+  };
+
+  return { store: store as unknown as MemoryStorePort, stored, patchedIds };
+}
+
+function entry(over: Partial<MemoryEntry> & { id: string; scope: string }): MemoryEntry {
+  return {
+    text: over.text ?? `text-${over.id}`,
+    vector: over.vector ?? [1, 0, 0],
+    category: over.category ?? "events",
+    importance: over.importance ?? 0.7,
+    timestamp: over.timestamp ?? Date.now(),
+    metadata: over.metadata ?? JSON.stringify({ evolution: { status: "active", accessCount: 0 } }),
+    ...over,
+  } as MemoryEntry;
+}
+
+const mockLLM = {
+  async generateL0() { return "an insight"; },
+  async extractPattern() { return "a pattern"; },
+} as unknown as LLMClient;
+
+const mockEmbedder: Pick<Embedder, "embedPassage"> = {
+  async embedPassage() { return [1, 0, 0]; },
+};
+
+describe("dream scope isolation (exact mode threading)", () => {
+  it("exact 模式下 pivot 行既不进 insight 来源，也不被 patch", async () => {
+    const memRows = Array.from({ length: 4 }, (_, i) =>
+      entry({ id: `mem-${i}`, scope: "memory", text: `memory rule chunk ${i}`, vector: [1, 0.02 * i, 0] }));
+    const pivotRows = Array.from({ length: 3 }, (_, i) =>
+      entry({ id: `pivot-${i}`, scope: "memory:pivot", text: `hand-written pivot ${i}`, vector: [1, 0.01 * i, 0] }));
+    const { store, stored, patchedIds } = createScopeAwareStore([...memRows, ...pivotRows]);
+    const stats = tempStatsPath();
+
+    await runDream({
+      store, llm: mockLLM, embedder: mockEmbedder, scope: "memory",
+      force: true, scopeMatch: "exact", activityStatsPath: stats.statsPath,
+    });
+
+    // 任何新写入的派生行，其 sourceMemories 都不许含 pivot id
+    const derivedSources = stored
+      .map(e => { try { return JSON.parse(e.metadata || "{}"); } catch { return {}; } })
+      .filter((m: Record<string, unknown>) => m.cluster_insight === true || m.cross_memory_pattern === true)
+      .flatMap((m: any) => (m?.evolution?.sourceMemories ?? []) as string[]);
+    expect(derivedSources.filter(id => id.startsWith("pivot-"))).toEqual([]);
+
+    // 也不许有任何 pivot 行被改写 metadata
+    expect(patchedIds.filter(id => id.startsWith("pivot-"))).toEqual([]);
+  });
+
+  it("family 模式下 pivot 行会被卷进来 —— 这是修复前的行为，留作对照", async () => {
+    const memRows = Array.from({ length: 3 }, (_, i) =>
+      entry({ id: `mem-${i}`, scope: "memory", vector: [1, 0.01 * i, 0] }));
+    const pivotRows = Array.from({ length: 3 }, (_, i) =>
+      entry({ id: `pivot-${i}`, scope: "memory:pivot", vector: [1, 0.01 * i, 0] }));
+    const { store } = createScopeAwareStore([...memRows, ...pivotRows]);
+
+    // 只验取数面：family 下 gather 能看到 6 行，exact 下只有 3 行。
+    expect((await store.list(["memory"], undefined, 500, 0)).length).toBe(6);
+    expect((await store.list(["memory"], undefined, 500, 0, "exact")).length).toBe(3);
+  });
+});
+
+describe("neverDreamScopes policy gate", () => {
+  it("memory:pivot 被策略排除，force 也不越过", async () => {
+    const { store, stored, patchedIds } = createScopeAwareStore(
+      Array.from({ length: 5 }, (_, i) => entry({ id: `pivot-${i}`, scope: "memory:pivot", vector: [1, 0.01 * i, 0] })),
+    );
+    const before = stored.length;
+
+    const result = await runDream({
+      store, llm: mockLLM, embedder: mockEmbedder,
+      scope: "memory:pivot", force: true, scopeMatch: "exact",
+      activityStatsPath: tempStatsPath().statsPath,
+    });
+
+    expect(result.ran).toBe(false);
+    expect(result.output.kind).toBe("skipped");
+    expect(result.output.reason).toBe("policy_excluded");
+    expect(result.output.effectsWritten).toBe(0);
+    expect(stored.length).toBe(before);   // 一行都没新写
+    expect(patchedIds).toEqual([]);       // 一行都没改
+  });
+
+  it("默认名单里就有 memory:pivot（改这条要连同 open-loops 的翻盘条件一起改）", () => {
+    expect(DEFAULT_DREAM_CONFIG.neverDreamScopes).toContain("memory:pivot");
+    // 与 autoExcludeScopes 是两份名单，语义不同，不许合并
+    expect(DEFAULT_DREAM_CONFIG.autoExcludeScopes).not.toContain("memory:pivot");
+  });
+
+  it("不在名单里的 scope 照常跑（策略闸不误伤）", async () => {
+    const { store } = createScopeAwareStore(
+      Array.from({ length: 4 }, (_, i) => entry({ id: `p-${i}`, scope: "project:normal", vector: [1, 0.01 * i, 0] })),
+    );
+    const result = await runDream({
+      store, llm: mockLLM, embedder: mockEmbedder,
+      scope: "project:normal", force: true, scopeMatch: "exact",
+      activityStatsPath: tempStatsPath().statsPath,
+    });
+    expect(result.ran).toBe(true);
+    expect(result.output.reason).not.toBe("policy_excluded");
+  });
+});
+
+describe("3a: derived insights never participate in dedupe", () => {
+  it("LLM 派生行不当 canonical，也不把手写原件合并掉", async () => {
+    // 复刻 2026-08-16 实测的形状：一条手写原件 + 一条它的 LLM 复述，向量几乎重合、
+    // importance 与 accessCount 都打平 —— 修复前 canonicalScore 平局，派生行赢过原件。
+    const original = entry({
+      id: "hand-written",
+      scope: "memory:pivot",
+      text: "决定暂缓提交第二个 PR，坚持一次一个 PR 策略，理由是架构级变更需确认维护者意图。",
+      vector: [1, 0, 0],
+      importance: 0.7,
+      metadata: JSON.stringify({
+        evolution: { status: "active", accessCount: 0 },
+        canonicalKey: "pivot-decision-sequential-pr-submission",
+        tags: ["pinned", "src:c98b9988"],
+      }),
+    });
+    const derived = entry({
+      id: "llm-restatement",
+      scope: "memory:pivot",
+      text: "暂缓提交第二个 PR，等待首个 PR 审查反馈。",
+      vector: [1, 0.001, 0],
+      importance: 0.7,
+      metadata: JSON.stringify({
+        evolution: { status: "active", accessCount: 0, sourceMemories: ["hand-written"] },
+        cluster_insight: true,
+      }),
+    });
+    const { store, stored } = createScopeAwareStore([original, derived]);
+
+    const engine = new ConsolidationEngine(store, {
+      ...DEFAULT_CONSOLIDATION_CONFIG,
+      scopeMatch: "exact",
+    });
+    const result = await engine.run("memory:pivot");
+
+    expect(result.mergedCount).toBe(0);
+    const statusOf = (id: string) => {
+      const row = stored.find(e => e.id === id)!;
+      return (JSON.parse(row.metadata || "{}") as any)?.evolution?.status;
+    };
+    expect(statusOf("hand-written")).toBe("active");   // 原件没被顶掉
+    expect(statusOf("llm-restatement")).toBe("active"); // 派生行也没被动，只是不参与
+  });
+
+  it("两条同为原始记忆时仍正常合并（排除派生 ≠ 关掉去重）", async () => {
+    const a = entry({
+      id: "dup-a", scope: "project:dedupe", text: "构建命令是 bun run build", vector: [1, 0, 0], importance: 0.8,
+    });
+    const b = entry({
+      id: "dup-b", scope: "project:dedupe", text: "构建命令为 bun run build", vector: [1, 0.001, 0], importance: 0.5,
+    });
+    const { store, stored } = createScopeAwareStore([a, b]);
+
+    const engine = new ConsolidationEngine(store, { ...DEFAULT_CONSOLIDATION_CONFIG, scopeMatch: "exact" });
+    const result = await engine.run("project:dedupe");
+
+    expect(result.mergedCount).toBe(1);
+    const loser = stored.find(e => e.id === "dup-b")!;
+    expect((JSON.parse(loser.metadata || "{}") as any)?.evolution?.status).toBe("consolidated");
+  });
+});
+
+describe("--auto 的 activity-stats key 一律 exact（回归锚点）", () => {
+  it("无冒号 key 在 exact 下不再吞掉整个家族", async () => {
+    // 实测 activity-stats 里有 11 个无冒号 key（cc / global / memory / manual …）。
+    // `cc` 一旦达标，family 语义会以 LIKE 'cc%' 把 2026-08-14 刚出队的 transcript
+    // 原文层整批捞回 —— 这条测试锁住"不会再发生"。
+    const { store } = createScopeAwareStore([
+      entry({ id: "cc-durable", scope: "cc" }),
+      entry({ id: "cc-transcript-1", scope: "cc:019f0f70" }),
+      entry({ id: "cc-transcript-2", scope: "cc:019f60e2" }),
+    ]);
+    expect((await store.list(["cc"], undefined, 100, 0)).length).toBe(3);
+    expect((await store.list(["cc"], undefined, 100, 0, "exact")).map(r => r.id)).toEqual(["cc-durable"]);
+  });
+
+  it("写计数按具体 scope 记，pivot 与 memory 各记各的（不碰生产 stats 文件）", async () => {
+    const cfg = tempStatsPath();
+    await incrementWriteCount("memory", 3, cfg);
+    await incrementWriteCount("memory:pivot", 5, cfg);
+    expect(getWriteCount("memory", cfg)).toBe(3);
+    expect(getWriteCount("memory:pivot", cfg)).toBe(5);
+    await resetWriteCount("memory", cfg);
+    expect(getWriteCount("memory", cfg)).toBe(0);
+    expect(getWriteCount("memory:pivot", cfg)).toBe(5);  // 兄弟 scope 不受牵连
+  });
+});