recallnest 2.2.1 → 2.5.4

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__/prediction-engine.test.ts

@@ -0,0 +1,349 @@
+/**
+ * Tests for HP-predictive Phase 5: Prediction Engine
+ *
+ * Validates:
+ * 1. collectSignals() — each signal type is correctly extracted
+ * 2. scorePredictions() — scoring, filtering by threshold, ranking
+ * 3. Edge cases — empty inputs, boundary conditions
+ */
+import { describe, expect, it } from "bun:test";
+import {
+  collectSignals,
+  scorePredictions,
+  _testConstants,
+  type PredictionContext,
+  type PredictionSignal,
+} from "../prediction-engine.js";
+import type { SessionCheckpointRecord } from "../session-schema.js";
+import type { WorkflowObservationRecord } from "../workflow-observation-schema.js";
+
+const { CONFIDENCE_THRESHOLD, STALE_OPEN_LOOP_HOURS, STALE_MEMORY_DAYS, MAX_PREDICTIONS, SIGNAL_WEIGHTS } = _testConstants;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeCheckpoint(overrides: Partial<SessionCheckpointRecord> & { openLoops?: string[]; updatedAt: string }): SessionCheckpointRecord {
+  return {
+    checkpointId: `cp-${Math.random().toString(36).slice(2, 8)}`,
+    sessionId: "test-session",
+    resolvedScope: "test",
+    scope: "test",
+    summary: "test checkpoint",
+    task: "test task",
+    decisions: [],
+    openLoops: overrides.openLoops ?? [],
+    nextActions: [],
+    entities: [],
+    files: [],
+    updatedAt: overrides.updatedAt,
+    ...overrides,
+  };
+}
+
+function makeWorkflowObservation(overrides: Partial<WorkflowObservationRecord>): WorkflowObservationRecord {
+  return {
+    observationId: `obs-${Math.random().toString(36).slice(2, 8)}`,
+    workflowId: "test-workflow",
+    outcome: "corrected",
+    summary: "Fixed a workflow issue",
+    scope: "test",
+    resolvedScope: "test",
+    source: "manual",
+    tags: [],
+    tools: [],
+    recordedAt: new Date().toISOString(),
+    ...overrides,
+  };
+}
+
+function emptyContext(overrides?: Partial<PredictionContext>): PredictionContext {
+  return {
+    checkpoints: [],
+    workflowObservations: [],
+    frequentMemories: [],
+    uncoveredTopics: [],
+    now: new Date("2026-04-11T12:00:00Z"),
+    ...overrides,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// collectSignals
+// ---------------------------------------------------------------------------
+
+describe("collectSignals", () => {
+  describe("stale open loop signals", () => {
+    it("detects stale open loops from checkpoints older than 24h", () => {
+      const now = new Date("2026-04-11T12:00:00Z");
+      const staleCheckpoint = makeCheckpoint({
+        openLoops: ["Fix CI pipeline", "Review PR #42"],
+        updatedAt: new Date(now.getTime() - 48 * 60 * 60 * 1000).toISOString(), // 48h ago
+      });
+
+      const signals = collectSignals(emptyContext({
+        checkpoints: [staleCheckpoint],
+        now,
+      }));
+
+      const openLoopSignals = signals.filter(s => s.type === "stale_open_loop");
+      expect(openLoopSignals.length).toBe(2);
+      expect(openLoopSignals[0].trigger).toBe("Fix CI pipeline");
+      expect(openLoopSignals[0].weight).toBeGreaterThan(0.6);
+      expect(openLoopSignals[0].evidence.length).toBeGreaterThan(0);
+    });
+
+    it("ignores fresh open loops (< 24h)", () => {
+      const now = new Date("2026-04-11T12:00:00Z");
+      const freshCheckpoint = makeCheckpoint({
+        openLoops: ["In-progress task"],
+        updatedAt: new Date(now.getTime() - 12 * 60 * 60 * 1000).toISOString(), // 12h ago
+      });
+
+      const signals = collectSignals(emptyContext({
+        checkpoints: [freshCheckpoint],
+        now,
+      }));
+
+      expect(signals.filter(s => s.type === "stale_open_loop").length).toBe(0);
+    });
+
+    it("deduplicates same open loop across checkpoints", () => {
+      const now = new Date("2026-04-11T12:00:00Z");
+      const cp1 = makeCheckpoint({
+        openLoops: ["Fix CI pipeline"],
+        updatedAt: new Date(now.getTime() - 48 * 60 * 60 * 1000).toISOString(),
+      });
+      const cp2 = makeCheckpoint({
+        openLoops: ["fix ci pipeline"], // same but different case
+        updatedAt: new Date(now.getTime() - 72 * 60 * 60 * 1000).toISOString(),
+      });
+
+      const signals = collectSignals(emptyContext({
+        checkpoints: [cp1, cp2],
+        now,
+      }));
+
+      expect(signals.filter(s => s.type === "stale_open_loop").length).toBe(1);
+    });
+
+    it("weights increase with staleness", () => {
+      const now = new Date("2026-04-11T12:00:00Z");
+      const cp24h = makeCheckpoint({
+        openLoops: ["Task A"],
+        updatedAt: new Date(now.getTime() - 25 * 60 * 60 * 1000).toISOString(),
+      });
+      const cp72h = makeCheckpoint({
+        openLoops: ["Task B"],
+        updatedAt: new Date(now.getTime() - 72 * 60 * 60 * 1000).toISOString(),
+      });
+
+      const signals = collectSignals(emptyContext({
+        checkpoints: [cp24h, cp72h],
+        now,
+      }));
+
+      const signalA = signals.find(s => s.trigger === "Task A")!;
+      const signalB = signals.find(s => s.trigger === "Task B")!;
+      expect(signalB.weight).toBeGreaterThan(signalA.weight);
+    });
+  });
+
+  describe("stale high-frequency memory signals", () => {
+    it("detects memories accessed frequently but not recently", () => {
+      const now = new Date("2026-04-11T12:00:00Z");
+      const signals = collectSignals(emptyContext({
+        frequentMemories: [{
+          text: "Auth migration plan",
+          topicTag: "auth",
+          lastAccessedAt: new Date(now.getTime() - 30 * 24 * 60 * 60 * 1000).toISOString(), // 30 days ago
+          accessCount: 5,
+        }],
+        now,
+      }));
+
+      const staleSignals = signals.filter(s => s.type === "stale_high_frequency");
+      expect(staleSignals.length).toBe(1);
+      expect(staleSignals[0].trigger).toBe("auth");
+      expect(staleSignals[0].evidence).toContain("Accessed 5 times but not in 30 days");
+    });
+
+    it("ignores recently accessed memories", () => {
+      const now = new Date("2026-04-11T12:00:00Z");
+      const signals = collectSignals(emptyContext({
+        frequentMemories: [{
+          text: "Recent memory",
+          lastAccessedAt: new Date(now.getTime() - 3 * 24 * 60 * 60 * 1000).toISOString(), // 3 days ago
+          accessCount: 10,
+        }],
+        now,
+      }));
+
+      expect(signals.filter(s => s.type === "stale_high_frequency").length).toBe(0);
+    });
+
+    it("ignores infrequently accessed memories (< 3 accesses)", () => {
+      const now = new Date("2026-04-11T12:00:00Z");
+      const signals = collectSignals(emptyContext({
+        frequentMemories: [{
+          text: "Rarely accessed",
+          lastAccessedAt: new Date(now.getTime() - 30 * 24 * 60 * 60 * 1000).toISOString(),
+          accessCount: 2,
+        }],
+        now,
+      }));
+
+      expect(signals.filter(s => s.type === "stale_high_frequency").length).toBe(0);
+    });
+  });
+
+  describe("workflow issue signals", () => {
+    it("detects corrected/missed workflow observations", () => {
+      const observations = [
+        makeWorkflowObservation({ workflowId: "deploy", outcome: "corrected", summary: "Forgot to run tests" }),
+        makeWorkflowObservation({ workflowId: "deploy", outcome: "missed", summary: "Missed the changelog update" }),
+        makeWorkflowObservation({ workflowId: "deploy", outcome: "success", summary: "All good" }),
+      ];
+
+      const signals = collectSignals(emptyContext({ workflowObservations: observations }));
+      const issueSignals = signals.filter(s => s.type === "workflow_issue");
+      expect(issueSignals.length).toBe(1);
+      expect(issueSignals[0].trigger).toBe("deploy");
+      expect(issueSignals[0].evidence[0]).toContain("2 corrected/missed");
+    });
+
+    it("ignores workflows with only successes", () => {
+      const observations = [
+        makeWorkflowObservation({ workflowId: "deploy", outcome: "success" }),
+      ];
+
+      const signals = collectSignals(emptyContext({ workflowObservations: observations }));
+      expect(signals.filter(s => s.type === "workflow_issue").length).toBe(0);
+    });
+  });
+
+  describe("uncovered topic signals", () => {
+    it("creates signals for uncovered topics", () => {
+      const signals = collectSignals(emptyContext({
+        uncoveredTopics: ["kubernetes", "migration"],
+      }));
+
+      const topicSignals = signals.filter(s => s.type === "uncovered_topic");
+      expect(topicSignals.length).toBe(2);
+      expect(topicSignals[0].trigger).toBe("kubernetes");
+      expect(topicSignals[0].weight).toBe(0.65);
+    });
+  });
+
+  describe("empty inputs", () => {
+    it("returns empty array for empty context", () => {
+      const signals = collectSignals(emptyContext());
+      expect(signals).toEqual([]);
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// scorePredictions
+// ---------------------------------------------------------------------------
+
+describe("scorePredictions", () => {
+  it("scores signals and filters by confidence threshold", () => {
+    const signals: PredictionSignal[] = [
+      {
+        type: "stale_open_loop",
+        trigger: "Fix CI",
+        action: "Unresolved: Fix CI",
+        weight: 0.9,
+        evidence: ["48h old"],
+      },
+      {
+        type: "uncovered_topic",
+        trigger: "obscure",
+        action: "No memories for obscure",
+        weight: 0.5, // Below threshold after scoring
+        evidence: ["No coverage"],
+      },
+    ];
+
+    const predictions = scorePredictions(signals);
+
+    // stale_open_loop: 0.9 * 0.9 = 0.81 (above 0.6)
+    // uncovered_topic: 0.5 * 0.65 = 0.325 (below 0.6)
+    expect(predictions.length).toBe(1);
+    expect(predictions[0].trigger).toBe("Fix CI");
+    expect(predictions[0].confidence).toBe(0.81);
+  });
+
+  it("sorts by confidence descending", () => {
+    const signals: PredictionSignal[] = [
+      { type: "uncovered_topic", trigger: "low", action: "low", weight: 1.0, evidence: [] },
+      { type: "stale_open_loop", trigger: "high", action: "high", weight: 1.0, evidence: [] },
+      { type: "workflow_issue", trigger: "mid", action: "mid", weight: 1.0, evidence: [] },
+    ];
+
+    const predictions = scorePredictions(signals);
+    // stale_open_loop: 1.0 * 0.9 = 0.9
+    // workflow_issue: 1.0 * 0.85 = 0.85
+    // uncovered_topic: 1.0 * 0.65 = 0.65
+    expect(predictions.length).toBe(3);
+    expect(predictions[0].trigger).toBe("high");
+    expect(predictions[1].trigger).toBe("mid");
+    expect(predictions[2].trigger).toBe("low");
+  });
+
+  it("limits to MAX_PREDICTIONS", () => {
+    const signals: PredictionSignal[] = Array.from({ length: 10 }, (_, i) => ({
+      type: "stale_open_loop" as const,
+      trigger: `task-${i}`,
+      action: `action-${i}`,
+      weight: 1.0,
+      evidence: [],
+    }));
+
+    const predictions = scorePredictions(signals);
+    expect(predictions.length).toBe(MAX_PREDICTIONS);
+  });
+
+  it("returns empty for all below threshold", () => {
+    const signals: PredictionSignal[] = [
+      { type: "uncovered_topic", trigger: "x", action: "x", weight: 0.3, evidence: [] },
+    ];
+
+    const predictions = scorePredictions(signals);
+    expect(predictions.length).toBe(0);
+  });
+
+  it("returns empty for empty signals", () => {
+    expect(scorePredictions([])).toEqual([]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Constants sanity
+// ---------------------------------------------------------------------------
+
+describe("prediction engine constants", () => {
+  it("confidence threshold is 0.6", () => {
+    expect(CONFIDENCE_THRESHOLD).toBe(0.6);
+  });
+
+  it("stale open loop hours is 24", () => {
+    expect(STALE_OPEN_LOOP_HOURS).toBe(24);
+  });
+
+  it("stale memory days is 14", () => {
+    expect(STALE_MEMORY_DAYS).toBe(14);
+  });
+
+  it("max predictions is 5", () => {
+    expect(MAX_PREDICTIONS).toBe(5);
+  });
+
+  it("signal weights are all between 0 and 1", () => {
+    for (const [, weight] of Object.entries(SIGNAL_WEIGHTS)) {
+      expect(weight).toBeGreaterThanOrEqual(0);
+      expect(weight).toBeLessThanOrEqual(1);
+    }
+  });
+});