recallnest 2.3.0 → 2.6.0

package/src/__tests__/retroactive-boost.test.ts

@@ -0,0 +1,223 @@
+import { describe, expect, it } from "bun:test";
+
+import {
+  retroactiveBoost,
+  DEFAULT_RETROACTIVE_BOOST_CONFIG,
+  type RetroactiveBoostConfig,
+} from "../retroactive-boost.js";
+import type { MemoryEntry, MemorySearchResult } from "../store.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeEntry(id: string, text: string, overrides: Partial<MemoryEntry> = {}): MemoryEntry {
+  return {
+    id,
+    text,
+    vector: [1, 0, 0],
+    category: "events",
+    scope: "project:test",
+    importance: 0.5,
+    timestamp: Date.now() - 7 * 86_400_000, // 7 days old by default
+    metadata: "{}",
+    ...overrides,
+  };
+}
+
+function createMockStore(
+  entries: MemoryEntry[],
+  searchResults: MemorySearchResult[] = [],
+) {
+  const data = new Map(entries.map(e => [e.id, { ...e }]));
+  const updates: Array<{ id: string; importance?: number; metadata?: string }> = [];
+
+  return {
+    updates,
+    data,
+    async vectorSearch(_vector: number[], limit = 5, minScore = 0.3, _scopeFilter?: string[]) {
+      return searchResults.filter(r => r.score >= minScore).slice(0, limit);
+    },
+    async update(id: string, upd: any, _scopeFilter?: string[]) {
+      const entry = data.get(id);
+      if (!entry) return null;
+      if (upd.importance !== undefined) entry.importance = upd.importance;
+      if (upd.metadata !== undefined) entry.metadata = upd.metadata;
+      updates.push({ id, ...upd });
+      return entry;
+    },
+  } as any;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("retroactive-boost (STC)", () => {
+  it("skips when new entry has low importance", async () => {
+    const store = createMockStore([]);
+    const newEntry = makeEntry("new-1", "low importance note", { importance: 0.5 });
+
+    const result = await retroactiveBoost(store, newEntry);
+    expect(result.triggered).toBe(false);
+    expect(result.reason).toBe("below_importance_threshold");
+  });
+
+  it("skips when new entry has no vector", async () => {
+    const store = createMockStore([]);
+    const newEntry = makeEntry("new-1", "important note", {
+      importance: 0.9,
+      vector: [],
+    });
+
+    const result = await retroactiveBoost(store, newEntry);
+    expect(result.triggered).toBe(false);
+    expect(result.reason).toBe("no_vector");
+  });
+
+  it("boosts related low-importance old entries", async () => {
+    const oldEntry = makeEntry("old-1", "Singapore weather info", {
+      importance: 0.3,
+      timestamp: Date.now() - 30 * 86_400_000, // 30 days old
+    });
+    const searchResults: MemorySearchResult[] = [
+      { entry: oldEntry, score: 0.85 },
+    ];
+    const store = createMockStore([oldEntry], searchResults);
+
+    const newEntry = makeEntry("new-1", "I'm moving to Singapore", {
+      importance: 0.9,
+      vector: [1, 0, 0],
+    });
+
+    const result = await retroactiveBoost(store, newEntry);
+    expect(result.triggered).toBe(true);
+    expect(result.boostedCount).toBe(1);
+    expect(result.boostedIds).toContain("old-1");
+
+    // Verify the update was applied
+    expect(store.updates.length).toBe(1);
+    expect(store.updates[0].importance).toBe(0.3 + 0.15); // 0.45
+  });
+
+  it("does not boost entries that are already high importance", async () => {
+    const highEntry = makeEntry("high-1", "already important", {
+      importance: 0.7,
+      timestamp: Date.now() - 30 * 86_400_000,
+    });
+    const searchResults: MemorySearchResult[] = [
+      { entry: highEntry, score: 0.85 },
+    ];
+    const store = createMockStore([highEntry], searchResults);
+
+    const newEntry = makeEntry("new-1", "trigger", { importance: 0.9, vector: [1, 0, 0] });
+
+    const result = await retroactiveBoost(store, newEntry);
+    expect(result.triggered).toBe(true);
+    expect(result.boostedCount).toBe(0); // high-1 was already above threshold
+  });
+
+  it("does not boost very recent entries", async () => {
+    const recentEntry = makeEntry("recent-1", "just stored", {
+      importance: 0.3,
+      timestamp: Date.now() - 3_600_000, // 1 hour old
+    });
+    const searchResults: MemorySearchResult[] = [
+      { entry: recentEntry, score: 0.85 },
+    ];
+    const store = createMockStore([recentEntry], searchResults);
+
+    const newEntry = makeEntry("new-1", "trigger", { importance: 0.9, vector: [1, 0, 0] });
+
+    const result = await retroactiveBoost(store, newEntry);
+    expect(result.triggered).toBe(true);
+    expect(result.boostedCount).toBe(0); // too recent
+  });
+
+  it("caps boosted importance at maxBoostedImportance", async () => {
+    const oldEntry = makeEntry("old-1", "related note", {
+      importance: 0.55,
+      timestamp: Date.now() - 30 * 86_400_000,
+    });
+    const searchResults: MemorySearchResult[] = [
+      { entry: oldEntry, score: 0.85 },
+    ];
+    const store = createMockStore([oldEntry], searchResults);
+
+    const newEntry = makeEntry("new-1", "trigger", { importance: 0.9, vector: [1, 0, 0] });
+
+    const config: RetroactiveBoostConfig = {
+      ...DEFAULT_RETROACTIVE_BOOST_CONFIG,
+      boostAmount: 0.3,           // would push to 0.85
+      maxBoostedImportance: 0.75, // but capped at 0.75
+    };
+
+    const result = await retroactiveBoost(store, newEntry, config);
+    expect(result.boostedCount).toBe(1);
+    expect(store.updates[0].importance).toBe(0.75); // capped
+  });
+
+  it("promotes tier from peripheral to working when boosted above 0.5", async () => {
+    const oldEntry = makeEntry("old-1", "peripheral memory", {
+      importance: 0.3,
+      timestamp: Date.now() - 30 * 86_400_000,
+      metadata: JSON.stringify({ tier: "peripheral" }),
+    });
+    const searchResults: MemorySearchResult[] = [
+      { entry: oldEntry, score: 0.85 },
+    ];
+    const store = createMockStore([oldEntry], searchResults);
+
+    const newEntry = makeEntry("new-1", "important trigger", { importance: 0.9, vector: [1, 0, 0] });
+
+    const config: RetroactiveBoostConfig = {
+      ...DEFAULT_RETROACTIVE_BOOST_CONFIG,
+      boostAmount: 0.25, // 0.3 + 0.25 = 0.55 > 0.5
+    };
+
+    const result = await retroactiveBoost(store, newEntry, config);
+    expect(result.boostedCount).toBe(1);
+
+    // Check metadata for tier promotion
+    const updatedMeta = JSON.parse(store.updates[0].metadata);
+    expect(updatedMeta.tier).toBe("working");
+    expect(updatedMeta.stc_boosts).toHaveLength(1);
+    expect(updatedMeta.stc_boosts[0].triggeredBy).toBe("new-1".slice(0, 8));
+  });
+
+  it("respects maxBoostPerTrigger limit", async () => {
+    const entries: MemoryEntry[] = [];
+    const searchResults: MemorySearchResult[] = [];
+
+    for (let i = 0; i < 10; i++) {
+      const e = makeEntry(`old-${i}`, `entry ${i}`, {
+        importance: 0.3,
+        timestamp: Date.now() - 30 * 86_400_000,
+      });
+      entries.push(e);
+      searchResults.push({ entry: e, score: 0.85 - i * 0.01 });
+    }
+
+    const store = createMockStore(entries, searchResults);
+    const newEntry = makeEntry("new-1", "trigger", { importance: 0.9, vector: [1, 0, 0] });
+
+    const result = await retroactiveBoost(store, newEntry);
+    expect(result.boostedCount).toBe(5); // default maxBoostPerTrigger
+  });
+
+  it("skips self in search results", async () => {
+    const newEntry = makeEntry("new-1", "I'm important", {
+      importance: 0.9,
+      vector: [1, 0, 0],
+    });
+    // Search returns the new entry itself
+    const searchResults: MemorySearchResult[] = [
+      { entry: newEntry, score: 1.0 },
+    ];
+    const store = createMockStore([newEntry], searchResults);
+
+    const result = await retroactiveBoost(store, newEntry);
+    expect(result.triggered).toBe(true);
+    expect(result.boostedCount).toBe(0);
+  });
+});

package/src/__tests__/salience-scoring.test.ts

@@ -0,0 +1,106 @@
+import { describe, it, expect } from "bun:test";
+import type { LLMClient } from "../llm-client.js";
+
+function createMockLLM(response: string): LLMClient {
+  return {
+    async chat() {
+      return response;
+    },
+    async assessImportance(text: string) {
+      const parsed = JSON.parse(response);
+      return parsed.importance ?? null;
+    },
+    async reassessImportanceBatch(
+      entries: Array<{ id: string; text: string; category: string; currentImportance: number }>,
+    ) {
+      const results = new Map<string, number>();
+      try {
+        const parsed = JSON.parse(response);
+        if (Array.isArray(parsed)) {
+          for (const item of parsed) {
+            if (item.idx >= 0 && item.idx < entries.length) {
+              results.set(entries[item.idx].id, item.importance);
+            }
+          }
+        }
+      } catch {
+        // match real implementation: non-fatal
+      }
+      return results;
+    },
+  } as any;
+}
+
+describe("HP-4: Salience scoring anchoring", () => {
+  describe("assessImportance anchored tiers", () => {
+    it("identity/correction → 0.85+", async () => {
+      const llm = createMockLLM(JSON.stringify({ importance: 0.92, reason: "用户明确纠正" }));
+      const result = await llm.assessImportance("不要用 rm 删除文件", "profile");
+      expect(result).toBeGreaterThanOrEqual(0.85);
+    });
+
+    it("decision/case → 0.70-0.84", async () => {
+      const llm = createMockLLM(JSON.stringify({ importance: 0.75, reason: "架构决策" }));
+      const result = await llm.assessImportance("选用 LanceDB 作为向量存储", "cases");
+      expect(result).toBeGreaterThanOrEqual(0.70);
+      expect(result).toBeLessThan(0.85);
+    });
+
+    it("entity/background → 0.55-0.69", async () => {
+      const llm = createMockLLM(JSON.stringify({ importance: 0.60, reason: "项目信息" }));
+      const result = await llm.assessImportance("RecallNest 使用 Bun 运行时", "entities");
+      expect(result).toBeGreaterThanOrEqual(0.55);
+      expect(result).toBeLessThan(0.70);
+    });
+
+    it("event/one-off → 0.40-0.54", async () => {
+      const llm = createMockLLM(JSON.stringify({ importance: 0.45, reason: "一次性操作" }));
+      const result = await llm.assessImportance("今天部署了 v2.1", "events");
+      expect(result).toBeGreaterThanOrEqual(0.40);
+      expect(result).toBeLessThan(0.55);
+    });
+
+    it("chatter/temp → 0.10-0.30", async () => {
+      const llm = createMockLLM(JSON.stringify({ importance: 0.15, reason: "临时上下文" }));
+      const result = await llm.assessImportance("好的，我看一下", "events");
+      expect(result).toBeGreaterThanOrEqual(0.10);
+      expect(result).toBeLessThan(0.40);
+    });
+  });
+
+  describe("reassessImportanceBatch", () => {
+    it("returns adjusted entries with ≥ 0.1 delta", async () => {
+      const batchResponse = JSON.stringify([
+        { idx: 0, importance: 0.90 },
+        { idx: 2, importance: 0.30 },
+      ]);
+      const llm = createMockLLM(batchResponse);
+      const entries = [
+        { id: "a", text: "永远不要用 rm", category: "profile", currentImportance: 0.70 },
+        { id: "b", text: "选用 LanceDB", category: "cases", currentImportance: 0.75 },
+        { id: "c", text: "今天天气不错", category: "events", currentImportance: 0.70 },
+      ];
+      const result = await llm.reassessImportanceBatch(entries);
+      expect(result.size).toBe(2);
+      expect(result.get("a")).toBe(0.90);
+      expect(result.get("c")).toBe(0.30);
+      expect(result.has("b")).toBe(false);
+    });
+
+    it("returns empty map on empty input", async () => {
+      const llm = createMockLLM("[]");
+      const result = await llm.reassessImportanceBatch([]);
+      expect(result.size).toBe(0);
+    });
+
+    it("handles invalid LLM response gracefully", async () => {
+      const llm = createMockLLM("not-json");
+      const entries = [
+        { id: "a", text: "test", category: "events", currentImportance: 0.5 },
+      ];
+      // Should not throw
+      const result = await llm.reassessImportanceBatch(entries);
+      expect(result.size).toBe(0);
+    });
+  });
+});

package/src/__tests__/scope-inventory.test.ts

@@ -0,0 +1,200 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { collectScopeInventory, formatScopeInventoryReport } from "../scope-inventory.js";
+import { MemoryStore } from "../store.js";
+
+const cleanupPaths: string[] = [];
+
+afterEach(() => {
+  while (cleanupPaths.length > 0) {
+    const target = cleanupPaths.pop();
+    if (target) {
+      rmSync(target, { recursive: true, force: true });
+    }
+  }
+});
+
+function createTempRoot(): string {
+  const root = mkdtempSync(join(tmpdir(), "recallnest-scope-inventory-"));
+  cleanupPaths.push(root);
+  return root;
+}
+
+function writeJson(dir: string, name: string, payload: unknown): void {
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, name), JSON.stringify(payload, null, 2) + "\n");
+}
+
+describe("collectScopeInventory", () => {
+  it("audits memories, pins, checkpoints, and workflow observations separately", async () => {
+    const root = createTempRoot();
+    const store = new MemoryStore({
+      dbPath: join(root, "db"),
+      vectorDim: 3,
+    });
+
+    await store.store({
+      text: "Scoped durable memory.",
+      vector: [1, 0, 0],
+      category: "entities",
+      scope: "project:recallnest",
+      importance: 0.8,
+      metadata: "{}",
+    });
+    await store.store({
+      text: "Historical global memory row.",
+      vector: [0, 1, 0],
+      category: "events",
+      scope: "global",
+      importance: 0.5,
+      metadata: "{}",
+    });
+
+    const pinsDir = join(root, "pins");
+    writeJson(pinsDir, "pin-legacy.json", {
+      id: "pin-legacy",
+      type: "pinned-memory",
+      title: "Legacy pin",
+      summary: "Pinned from an old global row.",
+      source: {
+        memoryId: "memory-1",
+        scope: "global",
+        timestamp: Date.now(),
+        metadata: {},
+      },
+      createdAt: "2026-03-18T00:00:00.000Z",
+      updatedAt: "2026-03-18T00:00:00.000Z",
+      snippet: "Legacy pin snippet.",
+    });
+
+    const checkpointsDir = join(root, "session-checkpoints");
+    writeJson(checkpointsDir, "checkpoint-legacy.json", {
+      checkpointId: "checkpoint-legacy",
+      sessionId: "session-1",
+      resolvedScope: "   ",
+      summary: "Old checkpoint that never got a real resolved scope.",
+      updatedAt: "2026-03-18T00:01:00.000Z",
+    });
+
+    const workflowDir = join(root, "workflow-observations");
+    writeJson(workflowDir, "workflow-legacy.json", {
+      observationId: "workflow-legacy",
+      workflowId: "resume_context",
+      resolvedScope: null,
+      summary: "Legacy workflow observation missing scope.",
+      recordedAt: "2026-03-18T00:02:00.000Z",
+    });
+    mkdirSync(workflowDir, { recursive: true });
+    writeFileSync(join(workflowDir, "broken.json"), "{not-json");
+
+    const report = await collectScopeInventory({
+      store,
+      sampleLimit: 10,
+      pinsDir,
+      checkpointsDir,
+      workflowObservationsDir: workflowDir,
+    });
+
+    expect(report.totalScannedCount).toBe(6);
+    expect(report.totalAnomalyCount).toBe(4);
+    expect(report.totalInvalidCount).toBe(1);
+    expect(report.totalReviewedCount).toBe(0);
+
+    const memoryLayer = report.layers.find((layer) => layer.layer === "memories");
+    const pinLayer = report.layers.find((layer) => layer.layer === "pins");
+    const checkpointLayer = report.layers.find((layer) => layer.layer === "session-checkpoints");
+    const workflowLayer = report.layers.find((layer) => layer.layer === "workflow-observations");
+
+    expect(memoryLayer?.anomalyCount).toBe(1);
+    expect(memoryLayer?.counts.global).toBe(1);
+    expect(pinLayer?.anomalyCount).toBe(1);
+    expect(pinLayer?.counts.global).toBe(1);
+    expect(checkpointLayer?.anomalyCount).toBe(1);
+    expect(checkpointLayer?.counts.empty).toBe(1);
+    expect(workflowLayer?.anomalyCount).toBe(1);
+    expect(workflowLayer?.counts.missing).toBe(1);
+    expect(workflowLayer?.invalidCount).toBe(1);
+    expect(workflowLayer?.reviewedCount).toBe(0);
+
+    const output = formatScopeInventoryReport(report);
+    expect(output).toContain("Scope inventory");
+    expect(output).toContain("[memories]");
+    expect(output).toContain("[pins]");
+    expect(output).toContain("[session-checkpoints]");
+    expect(output).toContain("[workflow-observations]");
+  });
+
+  it("returns a clean report when every layer is scoped correctly", async () => {
+    const root = createTempRoot();
+    const store = new MemoryStore({
+      dbPath: join(root, "db"),
+      vectorDim: 3,
+    });
+
+    await store.store({
+      text: "Scoped memory.",
+      vector: [1, 0, 0],
+      category: "entities",
+      scope: "project:recallnest",
+      importance: 0.9,
+      metadata: "{}",
+    });
+
+    const report = await collectScopeInventory({
+      store,
+      sampleLimit: 5,
+      pinsDir: join(root, "missing-pins"),
+      checkpointsDir: join(root, "missing-checkpoints"),
+      workflowObservationsDir: join(root, "missing-workflows"),
+    });
+
+    expect(report.totalScannedCount).toBe(1);
+    expect(report.totalAnomalyCount).toBe(0);
+    expect(report.totalInvalidCount).toBe(0);
+    expect(report.totalReviewedCount).toBe(0);
+    expect(report.layers.every((layer) => layer.samples.length === 0)).toBe(true);
+    expect(formatScopeInventoryReport(report)).toContain("No unresolved legacy scope anomalies found");
+  });
+
+  it("suppresses reviewed keep-global workflow observations from unresolved anomaly counts", async () => {
+    const root = createTempRoot();
+    const store = new MemoryStore({
+      dbPath: join(root, "db"),
+      vectorDim: 3,
+    });
+
+    const workflowDir = join(root, "workflow-observations");
+    writeJson(workflowDir, "workflow-reviewed.json", {
+      observationId: "workflow-reviewed",
+      workflowId: "resume_context",
+      resolvedScope: "global",
+      summary: "Legacy workflow observation intentionally left global.",
+      recordedAt: "2026-03-18T00:02:00.000Z",
+      legacyScopeReview: {
+        decision: "keep",
+        kind: "global",
+        reason: "external-task",
+        reviewedAt: "2026-03-18T00:03:00.000Z",
+      },
+    });
+
+    const report = await collectScopeInventory({
+      store,
+      sampleLimit: 5,
+      workflowObservationsDir: workflowDir,
+      pinsDir: join(root, "missing-pins"),
+      checkpointsDir: join(root, "missing-checkpoints"),
+    });
+
+    const workflowLayer = report.layers.find((layer) => layer.layer === "workflow-observations");
+    expect(report.totalAnomalyCount).toBe(0);
+    expect(report.totalReviewedCount).toBe(1);
+    expect(workflowLayer?.anomalyCount).toBe(0);
+    expect(workflowLayer?.reviewedCount).toBe(1);
+    expect(workflowLayer?.samples).toHaveLength(0);
+    expect(formatScopeInventoryReport(report)).toContain("Reviewed keeps : 1");
+  });
+});

package/src/__tests__/scope-policy.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from "bun:test";
+
+import { matchesScopeFilter, resolveScopeSelection, resolveSessionScope } from "../scope-policy.js";
+
+describe("scope-policy", () => {
+  it("prefers explicit scope over inferred values", () => {
+    const resolved = resolveScopeSelection({
+      scope: "project:recallnest",
+      sessionId: "session-123",
+      operation: "test:search",
+      env: {
+        RECALLNEST_DEFAULT_SCOPE: "project:other",
+      } as NodeJS.ProcessEnv,
+    });
+
+    expect(resolved.resolvedScope).toBe("project:recallnest");
+    expect(resolved.scopeFilter).toEqual(["project:recallnest"]);
+    expect(resolved.inferredFrom).toBe("scope");
+  });
+
+  it("falls back to session scope when explicit scope is absent", () => {
+    expect(resolveSessionScope("session-123")).toBe("session:session-123");
+
+    const resolved = resolveScopeSelection({
+      sessionId: "session-123",
+      operation: "test:search",
+      env: {} as NodeJS.ProcessEnv,
+    });
+
+    expect(resolved.resolvedScope).toBe("session:session-123");
+    expect(resolved.scopeFilter).toEqual(["session:session-123"]);
+    expect(resolved.inferredFrom).toBe("sessionId");
+  });
+
+  it("uses environment defaults when request scope is omitted", () => {
+    const resolved = resolveScopeSelection({
+      operation: "test:search",
+      env: {
+        RECALLNEST_DEFAULT_SCOPE: "project:recallnest",
+      } as NodeJS.ProcessEnv,
+    });
+
+    expect(resolved.resolvedScope).toBe("project:recallnest");
+    expect(resolved.scopeFilter).toEqual(["project:recallnest"]);
+    expect(resolved.inferredFrom).toBe("RECALLNEST_DEFAULT_SCOPE");
+  });
+
+  it("requires explicit opt-in before allowing cross-scope reads", () => {
+    expect(() => resolveScopeSelection({
+      operation: "test:search",
+      env: {} as NodeJS.ProcessEnv,
+    })).toThrow("requires a scope");
+
+    const allScopes = resolveScopeSelection({
+      operation: "test:search",
+      allScopes: true,
+      env: {} as NodeJS.ProcessEnv,
+    });
+
+    expect(allScopes.allScopes).toBe(true);
+    expect(allScopes.scopeFilter).toBeUndefined();
+  });
+
+  it("matches both exact and prefix scope filters", () => {
+    expect(matchesScopeFilter("project:recallnest", ["project:recallnest"])).toBe(true);
+    expect(matchesScopeFilter("cc:session-123", ["cc"])).toBe(true);
+    expect(matchesScopeFilter("project:other", ["project:recallnest"])).toBe(false);
+  });
+});

package/src/__tests__/scope-suggester.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from "bun:test";
+
+import {
+  boundedLevenshtein,
+  createScopeSuggester,
+  formatScopeSuggestion,
+  normalizeScope,
+  suggestScopes,
+} from "../scope-suggester.js";
+
+describe("normalizeScope", () => {
+  it("lowercases and strips separators", () => {
+    expect(normalizeScope("CC-Foo")).toBe("ccfoo");
+    expect(normalizeScope("cc_foo bar")).toBe("ccfoobar");
+  });
+});
+
+describe("boundedLevenshtein", () => {
+  it("computes small distances and early-exits beyond max", () => {
+    expect(boundedLevenshtein("recallnest", "recallnest", 2)).toBe(0);
+    expect(boundedLevenshtein("recallnst", "recallnest", 2)).toBe(1);
+    expect(boundedLevenshtein("recalnst", "recallnest", 2)).toBe(2);
+    expect(boundedLevenshtein("abc", "xyzuvw", 2)).toBe(3); // max+1
+  });
+});
+
+describe("suggestScopes", () => {
+  const known = ["recallnest", "recallnest:self", "cc", "cc:55bcbfb3", "project:test"];
+
+  it("matches typos within edit distance 2", () => {
+    expect(suggestScopes("recallnst", known)).toContain("recallnest");
+  });
+
+  it("matches case differences via normalization", () => {
+    expect(suggestScopes("RecallNest", known)[0]).toBe("recallnest");
+  });
+
+  it("matches separator convention drift", () => {
+    expect(suggestScopes("recall-nest", known)[0]).toBe("recallnest");
+    expect(suggestScopes("recall_nest", known)[0]).toBe("recallnest");
+  });
+
+  it("matches by prefix in both directions", () => {
+    expect(suggestScopes("recall", known)).toContain("recallnest");
+  });
+
+  it("returns empty for unrelated input", () => {
+    expect(suggestScopes("totally-unrelated-thing", known)).toEqual([]);
+    expect(suggestScopes("", known)).toEqual([]);
+  });
+
+  it("caps suggestions at maxSuggestions", () => {
+    const many = ["aa1", "aa2", "aa3", "aa4", "aa5"];
+    expect(suggestScopes("aa", many, 3)).toHaveLength(3);
+  });
+});
+
+describe("createScopeSuggester", () => {
+  it("derives prefix families and caches scope counts", async () => {
+    let calls = 0;
+    const suggest = createScopeSuggester(async () => {
+      calls++;
+      return { "cc:55bcbfb3": 100, "cc:65314581": 50, "codex:019cc122": 30 };
+    });
+
+    // 拼错的 prefix 应命中 prefix 家族(cc),不需要整串 session scope 相似
+    const r1 = await suggest("ccc");
+    expect(r1).toContain("cc");
+
+    await suggest("codx");
+    expect(calls).toBe(1); // 60s TTL 内复用缓存
+  });
+});
+
+describe("formatScopeSuggestion", () => {
+  it("renders hint or empty string", () => {
+    expect(formatScopeSuggestion("recallnst", ["recallnest"])).toContain("recallnest");
+    expect(formatScopeSuggestion("x", [])).toBe("");
+  });
+});