recallnest 2.6.1 → 3.0.0

package/src/__tests__/age-label.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from "bun:test";
+
+import { AGE_UNKNOWN, formatAgeLabel, formatIsoAgeLabel } from "../age-label.js";
+
+const DAY = 86_400_000;
+const NOW = Date.parse("2026-08-17T12:00:00.000Z");
+
+describe("age label", () => {
+  it("renders whole days, floored", () => {
+    expect(formatAgeLabel(NOW, NOW)).toBe("0d");
+    expect(formatAgeLabel(NOW - 23 * 3_600_000, NOW)).toBe("0d");
+    expect(formatAgeLabel(NOW - 1 * DAY, NOW)).toBe("1d");
+    expect(formatAgeLabel(NOW - 14 * DAY - 5 * 3_600_000, NOW)).toBe("14d");
+    expect(formatAgeLabel(NOW - 400 * DAY, NOW)).toBe("400d");
+  });
+
+  it("reads a future stamp as today, not a negative age", () => {
+    expect(formatAgeLabel(NOW + 3 * DAY, NOW)).toBe("0d");
+  });
+
+  it("does not fabricate an age for unusable stamps", () => {
+    expect(formatAgeLabel(0, NOW)).toBe(AGE_UNKNOWN);
+    expect(formatAgeLabel(undefined, NOW)).toBe(AGE_UNKNOWN);
+    expect(formatAgeLabel(Number.NaN, NOW)).toBe(AGE_UNKNOWN);
+    expect(formatIsoAgeLabel("not-a-date", NOW)).toBe(AGE_UNKNOWN);
+    expect(formatIsoAgeLabel("", NOW)).toBe(AGE_UNKNOWN);
+  });
+
+  it("accepts ISO strings the same way", () => {
+    expect(formatIsoAgeLabel("2026-08-03T09:30:00.000Z", NOW)).toBe("14d");
+    expect(formatIsoAgeLabel("2026-08-17T00:00:00.000Z", NOW)).toBe("0d");
+  });
+});

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

@@ -3,10 +3,13 @@ import { describe, expect, it } from "bun:test";
 import {
   clusterAndConsolidate,
   deduplicateByClusterInsight,
+  SYNTHESIS_CONTRACT_VERSION,
   type ClusterConsolidationResult,
 } from "../consolidation-engine.js";
+import { extractBoundaryMetadata } from "../memory-boundaries.js";
 import type { MemoryEntry, MemoryStore } from "../store.js";
 import type { LLMClient } from "../llm-client.js";
+import type { SynthesisVerdict } from "../synthesis-contract.js";
 import type { Embedder } from "../embedder.js";
 import { cosineSimilarity } from "../multi-vector.js";
 
@@ -38,13 +41,21 @@ function makeEntry(overrides: Partial<MemoryEntry> & { id: string; text: string
   };
 }
 
-/** Create a mock store that tracks store() and update() calls */
-function createMockStore() {
+/** Create a mock store that tracks store() and update() calls.
+ *  可选 seed：模拟"库中已有行"的 metadata（patchMetadataBatch 的生产语义是以库中
+ *  最新行起底应用 patchFn——不给 seed 时起底为空对象）。 */
+function createMockStore(seed: MemoryEntry[] = []) {
   const stored: MemoryEntry[] = [];
   const updates: Array<{ id: string; metadata: string }> = [];
+  // 2026-08-14: patchMetadataBatch 的最新态表 —— patchFn 以上一批的结果起底，
+  // 忠实模拟生产语义（锁内最新行起底、批间叠加而非互抹）。
+  const metaById = new Map<string, Record<string, unknown>>();
+  for (const e of seed) {
+    try { metaById.set(e.id, JSON.parse(e.metadata || "{}") as Record<string, unknown>); } catch { /* skip bad seed */ }
+  }
   let storeCounter = 0;
 
-  const store: Pick<MemoryStore, "store" | "update"> = {
+  const store: Pick<MemoryStore, "store" | "update" | "patchMetadataBatch"> = {
     async store(entry) {
       const full: MemoryEntry = {
         ...entry,
@@ -61,24 +72,47 @@ function createMockStore() {
       }
       return { id, text: "", vector: [], category: "events", scope: "project:test", importance: 0.5, timestamp: Date.now(), metadata: upd.metadata || "{}" } as MemoryEntry;
     },
+    async patchMetadataBatch(patches, _scopeFilter?) {
+      for (const { id, patchFn } of patches) {
+        const current = metaById.get(id) ?? {};
+        const entry = { id, text: "", vector: [], category: "events", scope: "project:test", importance: 0.5, timestamp: Date.now(), metadata: JSON.stringify(current) } as MemoryEntry;
+        const patched = patchFn(current, entry);
+        metaById.set(id, patched);
+        updates.push({ id, metadata: JSON.stringify(patched) });
+      }
+      return patches.length;
+    },
   };
 
-  return { store, stored, updates };
+  return { store, stored, updates, metaById };
+}
+
+/**
+ * Create a mock LLM that returns a fixed insight string (or null to simulate abstention).
+ *
+ * 2026-08-23：合成接口从「返回 string|null」换成 `SynthesisVerdict`（产出 / 弃权 /
+ * 校验不过三态）。这个 helper 保留旧的字符串签名，把 null 映射成 `abstained` ——
+ * 既有 30 多条断言测的是聚类与写库行为，不该因为合成签名换代而全部重写。
+ * 三态本身另有直接断言（见文件末尾「合成契约」一节）。
+ */
+function synthOk(text: string, evidence: number[] = [1, 2]): SynthesisVerdict {
+  return { status: "ok", output: { text, evidence } };
 }
 
-/** Create a mock LLM that returns a fixed insight string (or null to simulate failure) */
 function createMockLLM(
   insightFn: (text: string) => string | null,
   patternFn?: (texts: string[]) => string | null,
-): Pick<LLMClient, "generateL0" | "extractPattern"> {
+): Pick<LLMClient, "synthesizeClusterInsight" | "synthesizeClusterPattern"> {
   return {
-    async generateL0(text: string) {
-      return insightFn(text);
+    async synthesizeClusterInsight(texts: string[]) {
+      const out = insightFn(texts.join("\n---\n"));
+      return out === null ? { status: "abstained" } : synthOk(out);
     },
-    async extractPattern(texts: string[]) {
-      return patternFn ? patternFn(texts) : null;
+    async synthesizeClusterPattern(texts: string[]) {
+      const out = patternFn ? patternFn(texts) : null;
+      return out === null ? { status: "abstained" } : synthOk(out);
     },
-  } as Pick<LLMClient, "generateL0" | "extractPattern">;
+  } as Pick<LLMClient, "synthesizeClusterInsight" | "synthesizeClusterPattern">;
 }
 
 /** Create a mock embedder that returns a fixed vector */
@@ -147,7 +181,7 @@ describe("clusterAndConsolidate", () => {
       makeEntry({ id: "c", text: "TypeScript improves developer experience", vector: [0.92, 0.08, 0], importance: 0.6 }),
     ];
 
-    const { store, stored, updates } = createMockStore();
+    const { store, stored, updates } = createMockStore(entries);
     const llm = createMockLLM(() => "TypeScript benefits for development");
     const embedder = createMockEmbedder([0.5, 0.5, 0]);
 
@@ -187,6 +221,37 @@ describe("clusterAndConsolidate", () => {
     }
   });
 
+  // 2026-08-14 Bug-2 回归：旧路径 insight 源回写与 pattern 源回写都从同一个旧内存串
+  // 起底 patch，后者会把前者刚写库的 consolidatedInto 抹掉——凡走到 pattern 抽取的
+  // cluster，源条目的 consolidatedInto 全丢。新路径两段批量都以最新态起底，叠加共存。
+  it("Bug-2 回归：pattern 源回写后 consolidatedInto 与 contributedToPattern 并存（最终态）", async () => {
+    const entries = [
+      makeEntry({ id: "a", text: "TypeScript is great", vector: [0.9, 0.1, 0], importance: 0.8 }),
+      makeEntry({ id: "b", text: "TypeScript is safe", vector: [0.88, 0.12, 0], importance: 0.7 }),
+      makeEntry({ id: "c", text: "TypeScript is productive", vector: [0.92, 0.08, 0], importance: 0.6 }),
+    ];
+    const { store, stored, metaById } = createMockStore(entries);
+    const llm = createMockLLM(() => "TS insight", () => "TS pattern");
+    const embedder = createMockEmbedder([0.5, 0.5, 0]);
+
+    const result = await clusterAndConsolidate({
+      entries, embedder, llm: llm as unknown as LLMClient, store,
+      scope: "project:test", minClusterSize: 3, clusterThreshold: 0.75,
+      extractPatterns: true,
+    });
+
+    expect(result.insightsGenerated).toBe(1);
+    expect(result.patternsExtracted).toBe(1);
+    const insight = stored.find(e => JSON.parse(e.metadata!).cluster_insight === true)!;
+    const pattern = stored.find(e => JSON.parse(e.metadata!).cross_memory_pattern === true)!;
+    for (const id of ["a", "b", "c"]) {
+      const final = metaById.get(id) as { evolution: Record<string, unknown> };
+      expect(final.evolution.consolidatedInto).toBe(insight.id); // 旧路径这里被 pattern 批抹成 undefined
+      expect(final.evolution.contributedToPattern).toBe(pattern.id);
+      expect(final.evolution.status).toBe("active"); // 3b 不动 status
+    }
+  });
+
   // P0-2/P1-2: insight/pattern idempotency — deterministic id from source cluster ids.
   it("re-running on the same cluster yields a stable, deterministic insight id", async () => {
     const entries = [
@@ -238,6 +303,9 @@ describe("clusterAndConsolidate", () => {
       async update(id, upd) {
         return { id, text: "", vector: [], category: "events", scope: "project:test", importance: 0.5, timestamp: Date.now(), metadata: upd.metadata || "{}" } as MemoryEntry;
       },
+      async patchMetadataBatch(patches: Array<{ id: string; patchFn: (meta: Record<string, unknown>, entry: MemoryEntry) => Record<string, unknown> }>) {
+        return patches.length; // 本用例只断言 insight 幂等，源回写记录不参与断言
+      },
     };
 
     const params = {
@@ -326,11 +394,11 @@ describe("clusterAndConsolidate", () => {
 
     const { store, stored } = createMockStore();
     const llm = {
-      async generateL0(_text: string): Promise<string | null> {
+      async synthesizeClusterInsight(_texts: string[]): Promise<SynthesisVerdict> {
         throw new Error("Request was aborted.");
       },
-      async extractPattern(_texts: string[]): Promise<string | null> {
-        return null;
+      async synthesizeClusterPattern(_texts: string[]): Promise<SynthesisVerdict> {
+        return { status: "abstained" };
       },
     };
     const embedder = createMockEmbedder();
@@ -368,13 +436,13 @@ describe("clusterAndConsolidate", () => {
     const { store, stored } = createMockStore();
     let call = 0;
     const llm = {
-      async generateL0(_text: string): Promise<string | null> {
+      async synthesizeClusterInsight(_texts: string[]): Promise<SynthesisVerdict> {
         call++;
         if (call === 1) throw new Error("Request was aborted.");
-        return "第二个簇的 insight";
+        return synthOk("第二个簇的 insight");
       },
-      async extractPattern(_texts: string[]): Promise<string | null> {
-        return null;
+      async synthesizeClusterPattern(_texts: string[]): Promise<SynthesisVerdict> {
+        return { status: "abstained" };
       },
     };
     const embedder = createMockEmbedder();
@@ -406,10 +474,10 @@ describe("clusterAndConsolidate", () => {
 
     const { store, stored } = createMockStore();
     const llm = {
-      async generateL0(_text: string): Promise<string | null> {
-        return "insight 正常产出";
+      async synthesizeClusterInsight(_texts: string[]): Promise<SynthesisVerdict> {
+        return synthOk("insight 正常产出");
       },
-      async extractPattern(_texts: string[]): Promise<string | null> {
+      async synthesizeClusterPattern(_texts: string[]): Promise<SynthesisVerdict> {
         throw new Error("Request was aborted.");
       },
     };
@@ -943,3 +1011,226 @@ describe("deduplicateByClusterInsight (LC-P2)", () => {
     expect(deduped.length).toBe(2); // Both pass through
   });
 });
+
+// ---------------------------------------------------------------------------
+// 2026-08-23 合成契约上线带来的三件行为改动
+// ---------------------------------------------------------------------------
+
+/** 造一个三成员簇（向量足够接近，一定聚成一簇）。 */
+function trioEntries(): MemoryEntry[] {
+  return [
+    makeEntry({ id: "a", text: "记录 A", vector: [0.9, 0.1, 0], importance: 0.8 }),
+    makeEntry({ id: "b", text: "记录 B", vector: [0.88, 0.12, 0], importance: 0.7 }),
+    makeEntry({ id: "c", text: "记录 C", vector: [0.92, 0.08, 0], importance: 0.6 }),
+  ];
+}
+
+const trioParams = { minClusterSize: 3, clusterThreshold: 0.75 };
+
+describe("合成弃权路径（老 generateL0 完全没有这条路）", () => {
+  it("模型判定「没料可炼」时不写库，且记进 synthesisAbstained", async () => {
+    const { store, stored } = createMockStore();
+    const llm = {
+      async synthesizeClusterInsight(): Promise<SynthesisVerdict> { return { status: "abstained" }; },
+      async synthesizeClusterPattern(): Promise<SynthesisVerdict> { return { status: "abstained" }; },
+    };
+
+    const result = await clusterAndConsolidate({
+      entries: trioEntries(),
+      embedder: createMockEmbedder(),
+      llm: llm as unknown as LLMClient,
+      store,
+      scope: "project:test",
+      extractPatterns: true,
+      ...trioParams,
+    });
+
+    expect(stored.length).toBe(0);
+    expect(result.insightsGenerated).toBe(0);
+    expect(result.patternsExtracted).toBe(0);
+    expect(result.synthesisAbstained).toBe(2); // insight + pattern 各一次
+    expect(result.synthesisRejected).toBe(0);
+    expect(result.llmFailures).toBe(0); // 弃权不是失败
+    expect(result.clustersConsolidated).toBe(1); // 簇确实处理过
+  });
+
+  it("校验不过的输出不写库，且与弃权分开计数", async () => {
+    const { store, stored } = createMockStore();
+    const llm = {
+      async synthesizeClusterInsight(): Promise<SynthesisVerdict> {
+        return { status: "rejected", reason: "prompt-echo" };
+      },
+      async synthesizeClusterPattern(): Promise<SynthesisVerdict> {
+        return { status: "rejected", reason: "evidence-too-few" };
+      },
+    };
+
+    const result = await clusterAndConsolidate({
+      entries: trioEntries(),
+      embedder: createMockEmbedder(),
+      llm: llm as unknown as LLMClient,
+      store,
+      scope: "project:test",
+      extractPatterns: true,
+      ...trioParams,
+    });
+
+    expect(stored.length).toBe(0);
+    expect(result.synthesisRejected).toBe(2);
+    expect(result.synthesisAbstained).toBe(0);
+    expect(result.llmFailures).toBe(0); // 拿到回复了，只是不合契约——不是调用失败
+  });
+});
+
+describe("pattern 与 insight 解耦（R5）", () => {
+  it("insight 弃权时 pattern 照常抽取——改前这簇的 pattern 根本不会被执行", async () => {
+    const { store, stored } = createMockStore();
+    const llm = {
+      async synthesizeClusterInsight(): Promise<SynthesisVerdict> { return { status: "abstained" }; },
+      async synthesizeClusterPattern(): Promise<SynthesisVerdict> {
+        return { status: "ok", output: { text: "跨条目结论", evidence: [1, 2] } };
+      },
+    };
+
+    const result = await clusterAndConsolidate({
+      entries: trioEntries(),
+      embedder: createMockEmbedder(),
+      llm: llm as unknown as LLMClient,
+      store,
+      scope: "project:test",
+      extractPatterns: true,
+      ...trioParams,
+    });
+
+    expect(result.insightsGenerated).toBe(0);
+    expect(result.patternsExtracted).toBe(1);
+    expect(stored.length).toBe(1);
+    expect(stored[0].text).toBe("跨条目结论");
+  });
+
+  it("insight 抛异常时 pattern 仍然跑（两者独立失败）", async () => {
+    const { store } = createMockStore();
+    const llm = {
+      async synthesizeClusterInsight(): Promise<SynthesisVerdict> { throw new Error("Request was aborted."); },
+      async synthesizeClusterPattern(): Promise<SynthesisVerdict> {
+        return { status: "ok", output: { text: "跨条目结论", evidence: [1, 2] } };
+      },
+    };
+
+    const result = await clusterAndConsolidate({
+      entries: trioEntries(),
+      embedder: createMockEmbedder(),
+      llm: llm as unknown as LLMClient,
+      store,
+      scope: "project:test",
+      extractPatterns: true,
+      ...trioParams,
+    });
+
+    expect(result.llmFailures).toBe(1);
+    expect(result.insightsGenerated).toBe(0);
+    expect(result.patternsExtracted).toBe(1);
+  });
+
+  it("只有 pattern 产出的一轮不算零产出轮次（否则早停会提前触发）", async () => {
+    // 6 个成员分成两簇，insight 全弃权、pattern 全产出。
+    // 若沿用旧判据（没有 insight = 零产出），连续两簇就会触发 diminishing_returns 早停。
+    const entries = [
+      makeEntry({ id: "a1", text: "簇一 A", vector: [0.9, 0.1, 0] }),
+      makeEntry({ id: "a2", text: "簇一 B", vector: [0.88, 0.12, 0] }),
+      makeEntry({ id: "a3", text: "簇一 C", vector: [0.92, 0.08, 0] }),
+      makeEntry({ id: "b1", text: "簇二 A", vector: [0, 0.9, 0.1] }),
+      makeEntry({ id: "b2", text: "簇二 B", vector: [0, 0.88, 0.12] }),
+      makeEntry({ id: "b3", text: "簇二 C", vector: [0, 0.92, 0.08] }),
+    ];
+    const { store } = createMockStore();
+    const llm = {
+      async synthesizeClusterInsight(): Promise<SynthesisVerdict> { return { status: "abstained" }; },
+      async synthesizeClusterPattern(): Promise<SynthesisVerdict> {
+        return { status: "ok", output: { text: "跨条目结论", evidence: [1, 2] } };
+      },
+    };
+
+    const result = await clusterAndConsolidate({
+      entries,
+      embedder: createMockEmbedder(),
+      llm: llm as unknown as LLMClient,
+      store,
+      scope: "project:test",
+      extractPatterns: true,
+      ...trioParams,
+    });
+
+    expect(result.clustersFound).toBe(2);
+    expect(result.patternsExtracted).toBe(2);
+    expect(result.earlyStop).toBeUndefined();
+  });
+});
+
+describe("派生物的 boundary 层级（补的是「靠 scope 命名侥幸判对」那一刀）", () => {
+  it("insight 与 pattern 都显式落 evidence 层，不靠 scope 名字推断", async () => {
+    const { store, stored } = createMockStore();
+    const llm = createMockLLM(() => "一条结论", () => "一条跨条目结论");
+
+    await clusterAndConsolidate({
+      entries: trioEntries(),
+      embedder: createMockEmbedder(),
+      llm: llm as unknown as LLMClient,
+      store,
+      // 刻意用非 transcript scope：改前这里会静默拿到 durable 权威
+      scope: "project:test",
+      extractPatterns: true,
+      ...trioParams,
+    });
+
+    expect(stored.length).toBe(2);
+    for (const row of stored) {
+      const meta = JSON.parse(row.metadata!) as { boundary?: { layer?: string; authority?: string } };
+      expect(meta.boundary?.layer).toBe("evidence");
+      expect(meta.boundary?.authority).toBe("distillation");
+    }
+  });
+
+  it("检索侧读得到这个 boundary（与 extractBoundaryMetadata 对得上，不是写了个没人认的字段）", async () => {
+    const { store, stored } = createMockStore();
+    const llm = createMockLLM(() => "一条结论");
+
+    await clusterAndConsolidate({
+      entries: trioEntries(),
+      embedder: createMockEmbedder(),
+      llm: llm as unknown as LLMClient,
+      store,
+      scope: "project:test",
+      ...trioParams,
+    });
+
+    // coerceBoundaryMetadata 对 layer/authority/conflictPolicy 三项都做白名单校验，
+    // 任一项写错就整个返回 null —— 所以这条断言同时验了三项都合法。
+    const boundary = extractBoundaryMetadata(stored[0].metadata);
+    expect(boundary).not.toBeNull();
+    expect(boundary!.layer).toBe("evidence");
+  });
+
+  it("evidence 编号被翻译成真实的源记忆 id 存下来", async () => {
+    const { store, stored } = createMockStore();
+    const llm = {
+      async synthesizeClusterInsight(): Promise<SynthesisVerdict> {
+        return { status: "ok", output: { text: "一条结论", evidence: [1, 3] } };
+      },
+      async synthesizeClusterPattern(): Promise<SynthesisVerdict> { return { status: "abstained" }; },
+    };
+
+    await clusterAndConsolidate({
+      entries: trioEntries(),
+      embedder: createMockEmbedder(),
+      llm: llm as unknown as LLMClient,
+      store,
+      scope: "project:test",
+      ...trioParams,
+    });
+
+    const meta = JSON.parse(stored[0].metadata!) as { evidenceMemories?: string[]; synthesis_contract?: number };
+    expect(meta.evidenceMemories).toEqual(["a", "c"]); // 1-based → 第 1、第 3 个成员
+    expect(meta.synthesis_contract).toBe(SYNTHESIS_CONTRACT_VERSION);
+  });
+});

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([]),