recallnest 1.4.1

package/src/__tests__/ppr-traversal.test.ts

@@ -0,0 +1,256 @@
+import { describe, expect, it } from "bun:test";
+import {
+  buildGraph,
+  pprTraverse,
+  pprFromTriples,
+  edgeWeight,
+  DEFAULT_PPR_CONFIG,
+} from "../ppr-traversal.js";
+import type { KGTriple, NeighborhoodResult } from "../kg-store.js";
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function makeTriple(
+  subject: string,
+  predicate: string,
+  object: string,
+  confidence = 0.9,
+  id?: string,
+): KGTriple {
+  return {
+    id: id ?? `${subject}-${predicate}-${object}`,
+    scope: "test",
+    subject,
+    predicate,
+    object,
+    confidence,
+    source_memory_id: `mem-${subject}-${object}`,
+    source_text: `${subject} ${predicate} ${object}`,
+    timestamp: Date.now(),
+  };
+}
+
+function makeNeighborhood(triples: KGTriple[]): NeighborhoodResult[] {
+  const entities = new Set<string>();
+  for (const t of triples) {
+    entities.add(t.subject);
+    entities.add(t.object);
+  }
+  return [...entities].map(entity => ({
+    entity,
+    triples: triples.filter(t => t.subject === entity || t.object === entity),
+    hops: 0,
+  }));
+}
+
+// ============================================================================
+// edgeWeight
+// ============================================================================
+
+describe("edgeWeight", () => {
+  it("returns known weights for standard predicates", () => {
+    expect(edgeWeight("created_by")).toBe(0.95);
+    expect(edgeWeight("uses")).toBe(0.90);
+    expect(edgeWeight("related_to")).toBe(0.50);
+  });
+
+  it("returns default weight for unknown predicates", () => {
+    expect(edgeWeight("unknown_predicate")).toBe(0.60);
+  });
+});
+
+// ============================================================================
+// buildGraph
+// ============================================================================
+
+describe("buildGraph", () => {
+  it("builds undirected graph from neighborhood", () => {
+    const triples = [
+      makeTriple("Alice", "uses", "Python"),
+      makeTriple("Alice", "works_with", "Bob"),
+    ];
+    const neighborhood = makeNeighborhood(triples);
+    const graph = buildGraph(neighborhood);
+
+    expect(graph.nodes.size).toBe(3); // Alice, Python, Bob
+    expect(graph.adj.get("Alice")?.length).toBe(2); // -> Python, -> Bob
+    expect(graph.adj.get("Python")?.length).toBe(1); // -> Alice
+    expect(graph.adj.get("Bob")?.length).toBe(1); // -> Alice
+  });
+
+  it("deduplicates triples by id", () => {
+    const t = makeTriple("Alice", "uses", "Python", 0.9, "same-id");
+    const neighborhood: NeighborhoodResult[] = [
+      { entity: "Alice", triples: [t], hops: 0 },
+      { entity: "Python", triples: [t], hops: 1 },
+    ];
+    const graph = buildGraph(neighborhood);
+
+    // Should only have 1 edge per direction despite appearing in 2 neighborhood entries
+    expect(graph.adj.get("Alice")?.length).toBe(1);
+    expect(graph.adj.get("Python")?.length).toBe(1);
+  });
+
+  it("handles empty neighborhood", () => {
+    const graph = buildGraph([]);
+    expect(graph.nodes.size).toBe(0);
+    expect(graph.adj.size).toBe(0);
+  });
+});
+
+// ============================================================================
+// pprTraverse — convergence
+// ============================================================================
+
+describe("pprTraverse", () => {
+  it("converges on a simple chain A -> B -> C", () => {
+    const triples = [
+      makeTriple("A", "uses", "B"),
+      makeTriple("B", "uses", "C"),
+    ];
+    const graph = buildGraph(makeNeighborhood(triples));
+    const results = pprTraverse(graph, ["A"]);
+
+    // A should have highest score (it's the seed)
+    expect(results.length).toBeGreaterThan(0);
+    expect(results[0].entity).toBe("A");
+
+    // B should score higher than C (closer to seed)
+    const bResult = results.find(r => r.entity === "B");
+    const cResult = results.find(r => r.entity === "C");
+    expect(bResult).toBeDefined();
+    expect(cResult).toBeDefined();
+    expect(bResult!.score).toBeGreaterThan(cResult!.score);
+  });
+
+  it("respects hop limits", () => {
+    const triples = [
+      makeTriple("A", "uses", "B"),
+      makeTriple("B", "uses", "C"),
+      makeTriple("C", "uses", "D"),
+    ];
+    const graph = buildGraph(makeNeighborhood(triples));
+    const results = pprTraverse(graph, ["A"], { hopLimit: 1 });
+
+    // With hopLimit=1, only A and B should be reachable
+    const entities = results.map(r => r.entity);
+    expect(entities).toContain("A");
+    expect(entities).toContain("B");
+    expect(entities).not.toContain("C");
+    expect(entities).not.toContain("D");
+  });
+
+  it("handles multiple seed entities", () => {
+    const triples = [
+      makeTriple("A", "uses", "C"),
+      makeTriple("B", "uses", "C"),
+    ];
+    const graph = buildGraph(makeNeighborhood(triples));
+    const results = pprTraverse(graph, ["A", "B"]);
+
+    // C should be reachable from both seeds
+    const cResult = results.find(r => r.entity === "C");
+    expect(cResult).toBeDefined();
+    expect(cResult!.hops).toBe(1);
+  });
+
+  it("returns empty for empty graph", () => {
+    const graph = buildGraph([]);
+    const results = pprTraverse(graph, ["A"]);
+    expect(results).toEqual([]);
+  });
+
+  it("returns empty when seeds not in graph", () => {
+    const triples = [makeTriple("X", "uses", "Y")];
+    const graph = buildGraph(makeNeighborhood(triples));
+    const results = pprTraverse(graph, ["NotInGraph"]);
+    expect(results).toEqual([]);
+  });
+
+  it("respects topK limit", () => {
+    const triples = [
+      makeTriple("A", "uses", "B"),
+      makeTriple("A", "uses", "C"),
+      makeTriple("A", "uses", "D"),
+      makeTriple("A", "uses", "E"),
+    ];
+    const graph = buildGraph(makeNeighborhood(triples));
+    const results = pprTraverse(graph, ["A"], { topK: 2 });
+    expect(results.length).toBe(2);
+  });
+
+  it("computes shortest paths correctly", () => {
+    const triples = [
+      makeTriple("A", "uses", "B"),
+      makeTriple("B", "uses", "C"),
+    ];
+    const graph = buildGraph(makeNeighborhood(triples));
+    const results = pprTraverse(graph, ["A"]);
+
+    const aResult = results.find(r => r.entity === "A");
+    const bResult = results.find(r => r.entity === "B");
+    const cResult = results.find(r => r.entity === "C");
+
+    expect(aResult?.hops).toBe(0);
+    expect(aResult?.path).toEqual(["A"]);
+    expect(bResult?.hops).toBe(1);
+    expect(bResult?.path).toEqual(["A", "B"]);
+    expect(cResult?.hops).toBe(2);
+    expect(cResult?.path).toEqual(["A", "B", "C"]);
+  });
+
+  it("edge weights affect scores — stronger predicates yield higher scores", () => {
+    // Two separate subgraphs from same seed
+    const triples = [
+      makeTriple("A", "created_by", "B", 1.0), // weight 0.95
+      makeTriple("A", "related_to", "C", 1.0), // weight 0.50
+    ];
+    const graph = buildGraph(makeNeighborhood(triples));
+    const results = pprTraverse(graph, ["A"]);
+
+    const bResult = results.find(r => r.entity === "B");
+    const cResult = results.find(r => r.entity === "C");
+    expect(bResult).toBeDefined();
+    expect(cResult).toBeDefined();
+    // B should score higher due to stronger edge weight
+    expect(bResult!.score).toBeGreaterThan(cResult!.score);
+  });
+
+  it("all scores sum to approximately 1.0 (probability distribution)", () => {
+    const triples = [
+      makeTriple("A", "uses", "B"),
+      makeTriple("B", "uses", "C"),
+      makeTriple("C", "uses", "A"), // cycle
+    ];
+    const graph = buildGraph(makeNeighborhood(triples));
+    const results = pprTraverse(graph, ["A"], { maxIterations: 50 });
+
+    const totalScore = results.reduce((sum, r) => sum + r.score, 0);
+    // PPR scores approximate a probability distribution
+    expect(totalScore).toBeGreaterThan(0.8);
+    expect(totalScore).toBeLessThan(1.2);
+  });
+});
+
+// ============================================================================
+// pprFromTriples (convenience)
+// ============================================================================
+
+describe("pprFromTriples", () => {
+  it("works with raw triples", () => {
+    const triples = [
+      makeTriple("Alice", "uses", "Python"),
+      makeTriple("Alice", "works_at", "Google"),
+    ];
+    const results = pprFromTriples(triples, ["Alice"]);
+
+    expect(results.length).toBeGreaterThan(0);
+    expect(results[0].entity).toBe("Alice");
+
+    const entities = results.map(r => r.entity);
+    expect(entities).toContain("Python");
+    expect(entities).toContain("Google");
+  });
+});

package/src/__tests__/preference-guard-smoke.test.ts

@@ -0,0 +1,211 @@
+import { describe, expect, it } from "bun:test";
+
+import { promoteMemory } from "../capture-engine.js";
+import { formatExplainResults, formatSearchResults } from "../memory-output.js";
+import type { RetrievalResult } from "../retriever.js";
+
+const TEST_SCOPE = "project:test";
+
+function createDeps() {
+  const storedEntries: any[] = [];
+  const conflicts: any[] = [];
+  let seq = 1;
+
+  return {
+    storedEntries,
+    conflicts,
+    deps: {
+      embedder: {
+        async embedPassage(text: string) {
+          return [text.length, 1, 0];
+        },
+      },
+      store: {
+        async store(entry: any) {
+          const stored = {
+            ...entry,
+            id: `00000000-0000-0000-0000-${String(seq).padStart(12, "0")}`,
+            timestamp: 1_700_000_000_000 + seq,
+          };
+          seq += 1;
+          storedEntries.push(stored);
+          return stored;
+        },
+        async list(_scopeFilter?: string[], category?: string, limit = 20, offset = 0) {
+          return storedEntries
+            .filter((entry) => !category || entry.category === category)
+            .slice(offset, offset + limit);
+        },
+        async update(id: string, updates: any) {
+          const index = storedEntries.findIndex((entry) => entry.id === id);
+          if (index < 0) return null;
+          storedEntries[index] = {
+            ...storedEntries[index],
+            ...updates,
+            timestamp: updates.timestamp ?? storedEntries[index].timestamp,
+          };
+          return storedEntries[index];
+        },
+        async getById(id: string) {
+          return storedEntries.find((entry) => entry.id === id) || null;
+        },
+        async get(id: string) {
+          const exact = storedEntries.find((entry) => entry.id === id);
+          if (exact) return exact;
+          const matches = storedEntries.filter((entry) => entry.id.startsWith(id));
+          if (matches.length > 1) {
+            throw new Error(`Ambiguous prefix "${id}" matches ${matches.length} memories. Use a longer prefix or full ID.`);
+          }
+          return matches[0] || null;
+        },
+      },
+      conflictStore: {
+        async save(record: any) {
+          conflicts.push(record);
+          return record;
+        },
+        async replace(record: any) {
+          const index = conflicts.findIndex((item) => item.conflictId === record.conflictId);
+          if (index >= 0) {
+            conflicts[index] = record;
+          } else {
+            conflicts.push(record);
+          }
+          return record;
+        },
+        async getOpenByFingerprint(fingerprint: string) {
+          return conflicts.find((item) => item.status === "open" && item.fingerprint === fingerprint) || null;
+        },
+        async getLatestByFingerprint(fingerprint: string) {
+          return conflicts.find((item) => item.fingerprint === fingerprint) || null;
+        },
+      },
+    },
+  };
+}
+
+function buildEvidenceEntry(
+  deps: ReturnType<typeof createDeps>["deps"],
+  text: string,
+  scope: string,
+) {
+  return deps.store.store({
+    text,
+    vector: [1, 2, 3],
+    category: "events",
+    scope,
+    importance: 0.55,
+    metadata: JSON.stringify({
+      source: "cc",
+      boundary: {
+        layer: "evidence",
+        authority: "transcript-ingest",
+        conflictPolicy: "append-only",
+        originalCategory: "preferences",
+      },
+    }),
+  });
+}
+
+function toResult(entry: any, score = 0.91): RetrievalResult {
+  return {
+    entry,
+    score,
+    sources: {
+      vector: { score: 0.9, rank: 1 },
+      bm25: { score: 0.8, rank: 2 },
+      fused: { score },
+    },
+  };
+}
+
+describe("preference guard smoke", () => {
+  it("renders slot provenance end-to-end for a promoted reply-style preference", async () => {
+    const { deps, storedEntries, conflicts } = createDeps();
+    const source = await buildEvidenceEntry(
+      deps,
+      "[用户] 用户偏好短句直说。",
+      "cc:session-reply-style-smoke",
+    );
+
+    const promoted = await promoteMemory(deps as any, {
+      memoryId: source.id,
+      text: "User prefers concise, direct replies.",
+      category: "preferences",
+      scope: TEST_SCOPE,
+      tags: ["writing"],
+    });
+
+    const entry = storedEntries.find((item) => item.id === promoted.id);
+    expect(entry).toBeDefined();
+
+    const searchOutput = formatSearchResults([toResult(entry)], {
+      query: "reply style",
+      profile: "default",
+    });
+    const explainOutput = formatExplainResults([toResult(entry)], {
+      query: "reply style",
+      profile: "default",
+    });
+
+    expect(searchOutput).toContain("key:preferences:reply-style:concise:direct");
+    expect(searchOutput).toContain("slot:reply-style:concise:direct");
+    expect(searchOutput).toContain(`promoted:${source.id.slice(0, 8)}<-evidence/transcript-ingest`);
+    expect(explainOutput).toContain("slot:reply-style:concise:direct");
+    expect(explainOutput).toContain(`promoted:${source.id.slice(0, 8)}<-evidence/transcript-ingest`);
+    expect(conflicts).toHaveLength(0);
+  });
+
+  it("keeps descriptive draft and migration notes on plain preferences keys end-to-end", async () => {
+    const { deps, storedEntries, conflicts } = createDeps();
+    const draftSource = await buildEvidenceEntry(
+      deps,
+      "[用户] 这段文案简洁直接，先别改。",
+      "cc:session-draft-note-smoke",
+    );
+    const migrationSource = await buildEvidenceEntry(
+      deps,
+      "[用户] 文档里写了 uses Bun over Node 的迁移说明。",
+      "cc:session-migration-note-smoke",
+    );
+
+    const promotedDraft = await promoteMemory(deps as any, {
+      memoryId: draftSource.id,
+      text: "这段文案简洁直接，先别改。",
+      category: "preferences",
+      scope: TEST_SCOPE,
+      tags: ["writing"],
+    });
+    const promotedMigration = await promoteMemory(deps as any, {
+      memoryId: migrationSource.id,
+      text: "文档里写了 uses Bun over Node 的迁移说明。",
+      category: "preferences",
+      scope: TEST_SCOPE,
+      tags: ["tooling"],
+    });
+
+    const results = [
+      storedEntries.find((item) => item.id === promotedDraft.id),
+      storedEntries.find((item) => item.id === promotedMigration.id),
+    ].filter(Boolean).map((entry) => toResult(entry));
+
+    const searchOutput = formatSearchResults(results, {
+      query: "preferences",
+      profile: "default",
+    });
+    const explainOutput = formatExplainResults(results, {
+      query: "preferences",
+      profile: "default",
+    });
+
+    expect(searchOutput).toContain("key:preferences:这段文案简洁直接-先别改");
+    expect(searchOutput).toContain("key:preferences:文档里写了-uses-bun-over-node-的迁移说明");
+    expect(searchOutput).not.toContain("slot:reply-style:");
+    expect(searchOutput).not.toContain("slot:tool-choice:");
+    expect(explainOutput).toContain("key:preferences:这段文案简洁直接-先别改");
+    expect(explainOutput).toContain("key:preferences:文档里写了-uses-bun-over-node-的迁移说明");
+    expect(explainOutput).not.toContain("slot:reply-style:");
+    expect(explainOutput).not.toContain("slot:tool-choice:");
+    expect(conflicts).toHaveLength(0);
+  });
+});

package/src/__tests__/preference-matcher.test.ts

@@ -0,0 +1,230 @@
+/**
+ * Tests for Tier 3.6: Preference Pattern Quick Matching
+ *
+ * Validates:
+ * 1. matchPreference returns "create" when no similar preferences exist
+ * 2. matchPreference returns "skip" for near-duplicate preferences (no LLM)
+ * 3. matchPreference uses LLM when available for decision
+ * 4. matchPreference returns "merge" with merged text from LLM
+ * 5. matchPreference handles LLM failure gracefully
+ * 6. applyPreferenceMatch handles merge and skip correctly
+ * 7. Non-preference categories are not filtered
+ */
+import { describe, expect, it } from "bun:test";
+import {
+  matchPreference,
+  applyPreferenceMatch,
+  DEFAULT_PREFERENCE_MATCHER_CONFIG,
+} from "../preference-matcher.js";
+import type { MemoryEntry, MemorySearchResult } from "../store.js";
+import type { LLMClient, DedupDecision } from "../llm-client.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeEntry(id: string, text: string, category = "preferences"): MemoryEntry {
+  return {
+    id,
+    text,
+    vector: [1, 0, 0],
+    category,
+    scope: "project:test",
+    importance: 0.7,
+    timestamp: Date.now(),
+    metadata: "{}",
+  };
+}
+
+function createMockStore(searchResults: MemorySearchResult[] = []) {
+  const updates: Array<{ id: string; text?: string }> = [];
+  const data = new Map<string, MemoryEntry>();
+  for (const r of searchResults) {
+    data.set(r.entry.id, { ...r.entry });
+  }
+
+  return {
+    updates,
+    data,
+    async vectorSearch(
+      _vector: number[],
+      _limit: number,
+      _minScore: number,
+      _scopeFilter?: string[],
+    ) {
+      return searchResults;
+    },
+    async update(id: string, upd: { text?: string; metadata?: string }, _scope?: string[]) {
+      const entry = data.get(id);
+      if (!entry) return null;
+      if (upd.text) {
+        entry.text = upd.text;
+        updates.push({ id, text: upd.text });
+      }
+      return entry;
+    },
+  };
+}
+
+function createMockLLM(dedupResult: DedupDecision, synthResult: string | null = "merged preference text"): LLMClient {
+  return {
+    async dedupDecision(_newText: string, _existingText: string) {
+      return dedupResult;
+    },
+    async synthesizeFragments(_fragments: string[], _query: string) {
+      return synthResult;
+    },
+  } as any;
+}
+
+// ---------------------------------------------------------------------------
+// matchPreference tests
+// ---------------------------------------------------------------------------
+
+describe("matchPreference", () => {
+  const vector = [1, 0, 0];
+  const scope = "project:test";
+
+  it("returns create when no similar preferences found", async () => {
+    const store = createMockStore([]);
+    const result = await matchPreference("I prefer dark mode", vector, scope, store as any, null);
+
+    expect(result.action).toBe("create");
+    expect(result.reason).toBe("no-similar-preferences");
+  });
+
+  it("returns create when matches are non-preference category", async () => {
+    const store = createMockStore([
+      { entry: makeEntry("e1", "some entity", "entities"), score: 0.85 },
+    ]);
+    const result = await matchPreference("I prefer dark mode", vector, scope, store as any, null);
+
+    expect(result.action).toBe("create");
+    expect(result.reason).toBe("no-similar-preferences");
+  });
+
+  it("returns skip for high similarity without LLM", async () => {
+    const store = createMockStore([
+      { entry: makeEntry("p1", "User prefers dark mode"), score: 0.95 },
+    ]);
+    const result = await matchPreference("I like dark mode", vector, scope, store as any, null);
+
+    expect(result.action).toBe("skip");
+    expect(result.reason).toContain("no-llm");
+  });
+
+  it("returns create for moderate similarity without LLM", async () => {
+    const store = createMockStore([
+      { entry: makeEntry("p1", "User prefers dark mode"), score: 0.82 },
+    ]);
+    const result = await matchPreference("I like vim keybindings", vector, scope, store as any, null);
+
+    expect(result.action).toBe("create");
+    expect(result.reason).toContain("no-llm");
+  });
+
+  it("uses LLM to decide SKIP", async () => {
+    const store = createMockStore([
+      { entry: makeEntry("p1", "User prefers dark mode"), score: 0.85 },
+    ]);
+    const llm = createMockLLM({ action: "SKIP", reason: "same preference" });
+
+    const result = await matchPreference("I like dark mode", vector, scope, store as any, llm);
+
+    expect(result.action).toBe("skip");
+    expect(result.reason).toContain("llm-skip");
+  });
+
+  it("uses LLM to decide MERGE and generates merged text", async () => {
+    const store = createMockStore([
+      { entry: makeEntry("p1", "User prefers dark mode"), score: 0.85 },
+    ]);
+    const llm = createMockLLM(
+      { action: "MERGE", reason: "compatible preferences" },
+      "User prefers dark mode and compact layout",
+    );
+
+    const result = await matchPreference("I also like compact layout", vector, scope, store as any, llm);
+
+    expect(result.action).toBe("merge");
+    expect(result.mergeTargetId).toBe("p1");
+    expect(result.mergedText).toBe("User prefers dark mode and compact layout");
+  });
+
+  it("uses LLM to decide CREATE", async () => {
+    const store = createMockStore([
+      { entry: makeEntry("p1", "User prefers dark mode"), score: 0.80 },
+    ]);
+    const llm = createMockLLM({ action: "CREATE", reason: "different preference" });
+
+    const result = await matchPreference("I prefer vim keybindings", vector, scope, store as any, llm);
+
+    expect(result.action).toBe("create");
+    expect(result.reason).toContain("llm-create");
+  });
+
+  it("falls back to create on LLM failure", async () => {
+    const store = createMockStore([
+      { entry: makeEntry("p1", "User prefers dark mode"), score: 0.85 },
+    ]);
+    const llm = {
+      async dedupDecision() { throw new Error("LLM down"); },
+      async synthesizeFragments() { return null; },
+    } as any;
+
+    const result = await matchPreference("test pref", vector, scope, store as any, llm);
+
+    expect(result.action).toBe("create");
+    expect(result.reason).toBe("llm-error");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// applyPreferenceMatch tests
+// ---------------------------------------------------------------------------
+
+describe("applyPreferenceMatch", () => {
+  it("handles skip action", async () => {
+    const store = createMockStore([]);
+    const result = await applyPreferenceMatch(
+      { action: "skip", reason: "duplicate" },
+      store as any,
+      "project:test",
+    );
+
+    expect(result.handled).toBe(true);
+    expect(result.entry).toBeUndefined();
+  });
+
+  it("handles merge action — updates existing entry text", async () => {
+    const existing = makeEntry("p1", "old preference text");
+    const store = createMockStore([{ entry: existing, score: 0.9 }]);
+
+    const result = await applyPreferenceMatch(
+      {
+        action: "merge",
+        mergeTargetId: "p1",
+        mergedText: "merged preference text",
+        reason: "llm-merge",
+      },
+      store as any,
+      "project:test",
+    );
+
+    expect(result.handled).toBe(true);
+    expect(result.entry).toBeDefined();
+    expect(store.updates.length).toBe(1);
+    expect(store.updates[0].text).toBe("merged preference text");
+  });
+
+  it("returns not handled for create action", async () => {
+    const store = createMockStore([]);
+    const result = await applyPreferenceMatch(
+      { action: "create", reason: "new" },
+      store as any,
+      "project:test",
+    );
+
+    expect(result.handled).toBe(false);
+  });
+});