@vellumai/assistant 0.7.0 → 0.7.2

package/src/memory/v2/__tests__/activation.test.ts

@@ -7,8 +7,9 @@
  *   - `computeOwnActivation`: applies `A_o = d·prev + c_user·simU + c_a·simA +
  *      c_now·simN`; clamps to [0,1]; orphan in candidates returns 0 when no
  *      sim hits.
- *   - `spreadActivation`: orphan yields A == A_o; symmetric two-node ring is
- *      symmetric; hops=2 reaches second-degree but not third; bounded in [0,1].
+ *   - `spreadActivation`: orphan yields A == A_o; spread walks incoming edges
+ *      only (A→B boosts B but not A); hops=2 reaches second-degree predecessors
+ *      but not third; bounded in [0,1].
  *   - `selectInjections`: top-K rank, deterministic tie-break, delta against
  *      `everInjected`.
  *
@@ -139,14 +140,14 @@ mock.module("@qdrant/js-client-rest", () => ({
 
 // Static `import type` is fine — types erase, so they don't run module-init
 // code that would race the mocks above.
-import type { ActivationState, EdgesIndex } from "../types.js";
+import type { EdgeIndex } from "../edge-index.js";
+import type { ActivationState } from "../types.js";
 
 const {
   computeOwnActivation,
   computeSkillActivation,
   selectCandidates,
   selectInjections,
-  selectSkillCandidates,
   selectSkillInjections,
   spreadActivation,
 } = await import("../activation.js");
@@ -191,6 +192,7 @@ function makeConfig(
     epsilon: number;
     dense_weight: number;
     sparse_weight: number;
+    ann_candidate_limit: number | null;
   }> = {},
 ): AssistantConfig {
   return {
@@ -203,6 +205,7 @@ function makeConfig(
         epsilon: 0.01,
         dense_weight: 1.0,
         sparse_weight: 0.0,
+        ann_candidate_limit: null,
         ...overrides,
       },
     },
@@ -241,7 +244,9 @@ describe("selectCandidates", () => {
       nowText: "",
       config: makeConfig(),
     });
-    expect(out.size).toBe(0);
+    expect(out.candidates.size).toBe(0);
+    expect(out.fromPrior.size).toBe(0);
+    expect(out.fromAnn.size).toBe(0);
     // No turn text → no embedding call, no Qdrant call.
     expect(state.embedCalls).toHaveLength(0);
     expect(state.queryCalls).toHaveLength(0);
@@ -266,7 +271,9 @@ describe("selectCandidates", () => {
       nowText: "",
       config: makeConfig({ epsilon: 0.01 }),
     });
-    expect(out).toEqual(new Set(["alice-vscode", "carol-jazz"]));
+    expect(out.candidates).toEqual(new Set(["alice-vscode", "carol-jazz"]));
+    expect(out.fromPrior).toEqual(new Set(["alice-vscode", "carol-jazz"]));
+    expect(out.fromAnn).toEqual(new Set());
   });
 
   test("unions ANN hits with prior-state survivors", async () => {
@@ -289,10 +296,60 @@ describe("selectCandidates", () => {
       nowText: "",
       config: makeConfig(),
     });
-    expect(out).toEqual(new Set(["alice-vscode", "delta-recipe"]));
+    expect(out.candidates).toEqual(new Set(["alice-vscode", "delta-recipe"]));
+    expect(out.fromPrior).toEqual(new Set(["alice-vscode"]));
+    expect(out.fromAnn).toEqual(new Set(["alice-vscode", "delta-recipe"]));
   });
 
-  test("ANN top-K limit equals 50 and runs without slug restriction", async () => {
+  test("tags overlap: a slug in both sources lands in fromPrior ∩ fromAnn", async () => {
+    const priorState: ActivationState = {
+      messageId: "msg-1",
+      state: {
+        "alice-vscode": 0.5, // in prior AND in ANN
+        "carol-jazz": 0.3, // prior only
+      },
+      everInjected: [],
+      currentTurn: 1,
+      updatedAt: 1,
+    };
+    stageHybridResponse([
+      { slug: "alice-vscode", denseScore: 0.7, sparseScore: 1 }, // overlap
+      { slug: "delta-recipe", denseScore: 0.4, sparseScore: 1 }, // ANN only
+    ]);
+
+    const out = await selectCandidates({
+      priorState,
+      userText: "hello",
+      assistantText: "",
+      nowText: "",
+      config: makeConfig(),
+    });
+
+    // Overlap: alice-vscode appears in both source sets.
+    const overlap = new Set(
+      [...out.fromPrior].filter((slug) => out.fromAnn.has(slug)),
+    );
+    expect(overlap).toEqual(new Set(["alice-vscode"]));
+
+    // candidates = fromPrior ∪ fromAnn.
+    const union = new Set<string>([...out.fromPrior, ...out.fromAnn]);
+    expect(out.candidates).toEqual(union);
+    expect(out.candidates).toEqual(
+      new Set(["alice-vscode", "carol-jazz", "delta-recipe"]),
+    );
+
+    // Source-set membership matches each slug's actual provenance.
+    expect(out.fromPrior).toEqual(new Set(["alice-vscode", "carol-jazz"]));
+    expect(out.fromAnn).toEqual(new Set(["alice-vscode", "delta-recipe"]));
+  });
+
+  test("ANN candidate query honors `config.memory.v2.ann_candidate_limit` and runs without slug restriction", async () => {
+    // Default `ann_candidate_limit: null` → unlimited, so the unlimited
+    // sentinel (1_000_000 — a Qdrant-safe stand-in for "every page") is
+    // passed to both channels. We don't pin to `MAX_SAFE_INTEGER` here:
+    // Qdrant's sparse `SearchContext` pre-allocates `limit * 16` bytes,
+    // and `MAX_SAFE_INTEGER` triggers a ~144 PB alloc that SIGABRTs the
+    // Qdrant process — so the constant deliberately undercuts it.
     stageHybridResponse([{ slug: "alpha", denseScore: 0.5, sparseScore: 1 }]);
     await selectCandidates({
       priorState: null,
@@ -301,10 +358,25 @@ describe("selectCandidates", () => {
       nowText: "",
       config: makeConfig(),
     });
-    // Both channels (dense + sparse) ran with limit=50 and no filter.
     expect(state.queryCalls).toHaveLength(2);
     for (const call of state.queryCalls) {
-      expect(call.limit).toBe(50);
+      expect(call.limit).toBe(1_000_000);
+      expect(call.filter).toBeUndefined();
+    }
+
+    // Explicit override flows through both channels verbatim.
+    state.queryCalls.length = 0;
+    stageHybridResponse([{ slug: "beta", denseScore: 0.5, sparseScore: 1 }]);
+    await selectCandidates({
+      priorState: null,
+      userText: "hello",
+      assistantText: "",
+      nowText: "",
+      config: makeConfig({ ann_candidate_limit: 25 }),
+    });
+    expect(state.queryCalls).toHaveLength(2);
+    for (const call of state.queryCalls) {
+      expect(call.limit).toBe(25);
       expect(call.filter).toBeUndefined();
     }
   });
@@ -324,7 +396,8 @@ describe("computeOwnActivation", () => {
       nowText: "now",
       config: makeConfig(),
     });
-    expect(out.size).toBe(0);
+    expect(out.activation.size).toBe(0);
+    expect(out.breakdown.size).toBe(0);
     expect(state.embedCalls).toHaveLength(0);
     expect(state.queryCalls).toHaveLength(0);
   });
@@ -357,7 +430,7 @@ describe("computeOwnActivation", () => {
       }),
     });
     // Expected: 0.3*0.6 + 0.3*0.5 + 0.2*0.4 + 0.2*0.2 = 0.18+0.15+0.08+0.04 = 0.45
-    expect(out.get("alice")).toBeCloseTo(0.45, 6);
+    expect(out.activation.get("alice")).toBeCloseTo(0.45, 6);
   });
 
   test("clamps over-1.0 results down to [0, 1]", async () => {
@@ -388,7 +461,7 @@ describe("computeOwnActivation", () => {
         c_now: 0.5,
       }),
     });
-    expect(out.get("alice")).toBe(1);
+    expect(out.activation.get("alice")).toBe(1);
   });
 
   test("missing prior state defaults `prev` to 0", async () => {
@@ -410,7 +483,7 @@ describe("computeOwnActivation", () => {
       }),
     });
     // 0.3*0 + 0.3*1 + 0.2*0 + 0.2*0 = 0.3
-    expect(out.get("fresh")).toBeCloseTo(0.3, 6);
+    expect(out.activation.get("fresh")).toBeCloseTo(0.3, 6);
   });
 
   test("candidate with no sim hits resolves to 0", async () => {
@@ -426,7 +499,60 @@ describe("computeOwnActivation", () => {
       nowText: "n",
       config: makeConfig(),
     });
-    expect(out.get("ghost")).toBe(0);
+    expect(out.activation.get("ghost")).toBe(0);
+  });
+
+  test("breakdown captures `d * prev` and the raw sims for each candidate", async () => {
+    stageHybridResponse([{ slug: "alice", denseScore: 0.5 }]); // simU
+    stageHybridResponse([{ slug: "alice", denseScore: 0.4 }]); // simA
+    stageHybridResponse([{ slug: "alice", denseScore: 0.2 }]); // simN
+
+    const priorState: ActivationState = {
+      messageId: "msg-1",
+      state: { alice: 0.6 },
+      everInjected: [],
+      currentTurn: 1,
+      updatedAt: 1,
+    };
+    const d = 0.3;
+    const out = await computeOwnActivation({
+      candidates: new Set(["alice"]),
+      priorState,
+      userText: "u",
+      assistantText: "a",
+      nowText: "n",
+      config: makeConfig({
+        d,
+        c_user: 0.3,
+        c_assistant: 0.2,
+        c_now: 0.2,
+      }),
+    });
+    const breakdown = out.breakdown.get("alice");
+    expect(breakdown).toBeDefined();
+    // priorContribution is `d * prev`, not the weighted sim term.
+    expect(breakdown?.priorContribution).toBeCloseTo(d * 0.6, 6);
+    // Raw sims, captured before c_user / c_assistant / c_now weighting.
+    expect(breakdown?.simUser).toBeCloseTo(0.5, 6);
+    expect(breakdown?.simAssistant).toBeCloseTo(0.4, 6);
+    expect(breakdown?.simNow).toBeCloseTo(0.2, 6);
+  });
+
+  test("breakdown defaults priorContribution to 0 when priorState is null", async () => {
+    stageHybridResponse([{ slug: "fresh", denseScore: 0.5 }]);
+    stageHybridResponse([{ slug: "fresh", denseScore: 0.5 }]);
+    stageHybridResponse([{ slug: "fresh", denseScore: 0.5 }]);
+
+    const out = await computeOwnActivation({
+      candidates: new Set(["fresh"]),
+      priorState: null,
+      userText: "u",
+      assistantText: "a",
+      nowText: "n",
+      config: makeConfig({ d: 0.9 }),
+    });
+    // No prior state → prev=0 → priorContribution=0 regardless of `d`.
+    expect(out.breakdown.get("fresh")?.priorContribution).toBe(0);
   });
 });
 
@@ -434,143 +560,258 @@ describe("computeOwnActivation", () => {
 // spreadActivation
 // ---------------------------------------------------------------------------
 
+/**
+ * Build a directed `EdgeIndex` from a flat list of `[from, to]` pairs. Each
+ * entry is interpreted as a directed edge `from → to`; self-loops are dropped.
+ */
+function buildEdgeIndex(edges: Array<[string, string]>): EdgeIndex {
+  const outgoing = new Map<string, Set<string>>();
+  const incoming = new Map<string, Set<string>>();
+  for (const [from, to] of edges) {
+    if (from === to) continue;
+    let outSet = outgoing.get(from);
+    if (!outSet) {
+      outSet = new Set<string>();
+      outgoing.set(from, outSet);
+    }
+    outSet.add(to);
+    let inSet = incoming.get(to);
+    if (!inSet) {
+      inSet = new Set<string>();
+      incoming.set(to, inSet);
+    }
+    inSet.add(from);
+  }
+  return { outgoing, incoming };
+}
+
 describe("spreadActivation", () => {
   test("orphan node yields A == A_o", () => {
-    const edges: EdgesIndex = { version: 1, edges: [] };
+    const edges = buildEdgeIndex([]);
     const own = new Map([["alice", 0.7]]);
     const out = spreadActivation(own, edges, 0.5, 2);
-    expect(out.get("alice")).toBeCloseTo(0.7, 6);
+    expect(out.final.get("alice")).toBeCloseTo(0.7, 6);
   });
 
-  test("symmetric two-node ring yields symmetric activation", () => {
-    const edges: EdgesIndex = {
-      version: 1,
-      edges: [["alice", "bob"]],
-    };
+  test("directed edge boosts only the target, not the source", () => {
+    // Edge alice→bob: alice activation flows into bob; bob does NOT push back
+    // into alice. alice (a pure source under this graph) keeps its own value.
+    const edges = buildEdgeIndex([["alice", "bob"]]);
     const own = new Map([
       ["alice", 0.6],
-      ["bob", 0.6],
+      ["bob", 0.0],
     ]);
     const out = spreadActivation(own, edges, 0.5, 2);
-    // Both nodes have one neighbor, equal own-activation → equal final A.
-    expect(out.get("alice")).toBeCloseTo(out.get("bob") ?? 0, 6);
-    // Numerator: 0.6 + 0.5*0.6 = 0.9. Denominator: 1 + 0.5*1 = 1.5. A = 0.6.
-    expect(out.get("alice")).toBeCloseTo(0.6, 6);
+    // alice has no incoming edges → final == own.
+    expect(out.final.get("alice")).toBeCloseTo(0.6, 6);
+    // bob's incoming = {alice}: numerator = 0 + 0.5*0.6 = 0.3, denom = 1.5.
+    expect(out.final.get("bob")).toBeCloseTo(0.3 / 1.5, 6);
   });
 
-  test("asymmetric two-node ring picks up neighbor activation", () => {
-    const edges: EdgesIndex = {
-      version: 1,
-      edges: [["alice", "bob"]],
-    };
+  test("two-cycle (A→B and B→A) lets activation flow both ways", () => {
+    // With both directions present, each node is the other's predecessor.
+    const edges = buildEdgeIndex([
+      ["alice", "bob"],
+      ["bob", "alice"],
+    ]);
     const own = new Map([
       ["alice", 0.0],
       ["bob", 0.8],
     ]);
     const out = spreadActivation(own, edges, 0.5, 2);
-    // alice: numerator = 0 + 0.5*0.8 = 0.4. denominator = 1 + 0.5 = 1.5.
-    //        A = 0.2666...
-    expect(out.get("alice")).toBeCloseTo(0.4 / 1.5, 6);
-    // bob:   numerator = 0.8 + 0.5*0 = 0.8. denominator = 1.5. A = 0.5333...
-    expect(out.get("bob")).toBeCloseTo(0.8 / 1.5, 6);
-  });
-
-  test("hops=2 reaches second-degree neighbors but stops there", () => {
-    // Path graph: alice -- bob -- carol -- delta
-    // From alice's perspective: bob is 1-hop, carol is 2-hop, delta is 3-hop.
-    const edges: EdgesIndex = {
-      version: 1,
-      edges: [
-        ["alice", "bob"],
-        ["bob", "carol"],
-        ["carol", "delta"],
-      ],
-    };
+    // alice: incoming {bob}=0.8 → numerator = 0 + 0.5*0.8 = 0.4, denom = 1.5.
+    expect(out.final.get("alice")).toBeCloseTo(0.4 / 1.5, 6);
+    // bob:   incoming {alice}=0.0 → numerator = 0.8 + 0 = 0.8, denom = 1.5.
+    expect(out.final.get("bob")).toBeCloseTo(0.8 / 1.5, 6);
+  });
+
+  test("pure source (high outgoing, zero incoming) collapses to final == own", () => {
+    // alice → bob → carol; alice has no incoming edges.
+    const edges = buildEdgeIndex([
+      ["alice", "bob"],
+      ["bob", "carol"],
+    ]);
     const own = new Map([
-      ["alice", 0.0],
+      ["alice", 0.5],
       ["bob", 0.0],
-      ["carol", 1.0], // 2 hops from alice
-      ["delta", 1.0], // 3 hops from alice — must NOT contribute
+      ["carol", 0.0],
     ]);
     const out = spreadActivation(own, edges, 0.5, 2);
-    // alice: 1-hop = {bob} (0), 2-hop = {carol} (1.0).
+    expect(out.final.get("alice")).toBeCloseTo(0.5, 6);
+  });
+
+  test("hops=2 reaches second-degree predecessors but stops there", () => {
+    // Directed path: alice → bob → carol → delta
+    // From delta's perspective: carol is 1-hop predecessor, bob is 2-hop,
+    // alice is 3-hop. Activation on bob (2-hop) reaches delta; activation on
+    // alice (3-hop) does NOT.
+    const edges = buildEdgeIndex([
+      ["alice", "bob"],
+      ["bob", "carol"],
+      ["carol", "delta"],
+    ]);
+    const own = new Map([
+      ["alice", 1.0], // 3-hop predecessor of delta — must NOT contribute
+      ["bob", 1.0], // 2-hop predecessor of delta
+      ["carol", 0.0],
+      ["delta", 0.0],
+    ]);
+    const out = spreadActivation(own, edges, 0.5, 2);
+    // delta: 1-hop {carol}=0, 2-hop {bob}=1.0.
     //   numerator   = 0 + 0.5*0 + 0.25*1.0 = 0.25
     //   denominator = 1 + 0.5*1 + 0.25*1   = 1.75
     //   A = 0.25 / 1.75 ≈ 0.142857
-    expect(out.get("alice")).toBeCloseTo(0.25 / 1.75, 6);
+    expect(out.final.get("delta")).toBeCloseTo(0.25 / 1.75, 6);
   });
 
   test("output is bounded in [0, 1] for arbitrary inputs", () => {
-    const edges: EdgesIndex = {
-      version: 1,
-      edges: [
-        ["alice", "bob"],
-        ["bob", "carol"],
-        ["alice", "carol"],
-      ],
-    };
+    const edges = buildEdgeIndex([
+      ["alice", "bob"],
+      ["bob", "carol"],
+      ["alice", "carol"],
+    ]);
     const own = new Map([
       ["alice", 1.0],
       ["bob", 1.0],
       ["carol", 1.0],
     ]);
     const out = spreadActivation(own, edges, 0.99, 2);
-    for (const [, value] of out) {
+    for (const [, value] of out.final) {
       expect(value).toBeGreaterThanOrEqual(0);
       expect(value).toBeLessThanOrEqual(1);
     }
   });
 
   test("hops=0 collapses to A == A_o", () => {
-    const edges: EdgesIndex = {
-      version: 1,
-      edges: [["alice", "bob"]],
-    };
+    const edges = buildEdgeIndex([["alice", "bob"]]);
     const own = new Map([
       ["alice", 0.4],
       ["bob", 0.9],
     ]);
     const out = spreadActivation(own, edges, 0.5, 0);
-    expect(out.get("alice")).toBeCloseTo(0.4, 6);
-    expect(out.get("bob")).toBeCloseTo(0.9, 6);
+    expect(out.final.get("alice")).toBeCloseTo(0.4, 6);
+    expect(out.final.get("bob")).toBeCloseTo(0.9, 6);
   });
 
   test("k=0 collapses to A == A_o", () => {
-    const edges: EdgesIndex = {
-      version: 1,
-      edges: [["alice", "bob"]],
-    };
+    const edges = buildEdgeIndex([["alice", "bob"]]);
     const own = new Map([
       ["alice", 0.4],
       ["bob", 0.9],
     ]);
     const out = spreadActivation(own, edges, 0, 5);
-    expect(out.get("alice")).toBeCloseTo(0.4, 6);
-    expect(out.get("bob")).toBeCloseTo(0.9, 6);
+    expect(out.final.get("alice")).toBeCloseTo(0.4, 6);
+    expect(out.final.get("bob")).toBeCloseTo(0.9, 6);
   });
 
-  test("missing neighbor activation contributes 0 to the numerator", () => {
-    // alice and bob are connected, but bob is not in `ownActivation` — so
-    // bob's contribution is 0, while the denominator still counts the
-    // structural neighbor.
-    const edges: EdgesIndex = {
-      version: 1,
-      edges: [["alice", "bob"]],
-    };
-    const own = new Map([["alice", 0.6]]);
+  test("predecessors not in the candidate set are dropped from both numerator and denominator", () => {
+    // Edge alice→bob: bob has structural predecessor alice, but alice is not
+    // in `ownActivation`. With the new formula she contributes nothing —
+    // hop1 has no active predecessors so the whole hop drops out of both
+    // sides of the ratio. Bob therefore stays at his own activation.
+    const edges = buildEdgeIndex([["alice", "bob"]]);
+    const own = new Map([["bob", 0.6]]);
+    const out = spreadActivation(own, edges, 0.5, 2);
+    expect(out.final.get("bob")).toBeCloseTo(0.6, 6);
+  });
+
+  test("L_2 norm over multiple active predecessors rewards strong outliers more than avg would", () => {
+    // bob has 4 predecessors in the candidate set: one strong, three weak.
+    // L_2 = √((0.8² + 0.1² + 0.1² + 0.1²) / 4) = √(0.1675) ≈ 0.40927
+    // Plain avg of the same set = 0.275, so L_2 lifts bob more than avg
+    // would — the design goal of preferring quality over quantity.
+    const edges = buildEdgeIndex([
+      ["a1", "bob"],
+      ["a2", "bob"],
+      ["a3", "bob"],
+      ["a4", "bob"],
+    ]);
+    const own = new Map([
+      ["a1", 0.8],
+      ["a2", 0.1],
+      ["a3", 0.1],
+      ["a4", 0.1],
+      ["bob", 0.0],
+    ]);
     const out = spreadActivation(own, edges, 0.5, 2);
-    // numerator = 0.6 + 0.5*0 = 0.6. denominator = 1 + 0.5*1 = 1.5.
-    expect(out.get("alice")).toBeCloseTo(0.4, 6);
+    const rms = Math.sqrt((0.8 * 0.8 + 3 * 0.1 * 0.1) / 4);
+    // numerator   = 0 + 0.5 · rms
+    // denominator = 1 + 0.5
+    expect(out.final.get("bob")).toBeCloseTo((0.5 * rms) / 1.5, 6);
+  });
+
+  test("high-in-degree hub with mostly-inactive predecessors stays near A_o", () => {
+    // 100 structural predecessors point at hub; only one (`pred0`) is in
+    // the candidate set. The old formula would crush hub by the structural
+    // count (denominator ≈ 51); the new formula folds the empty bulk out
+    // and the L_2 averages over the single active predecessor only.
+    const rawEdges: Array<[string, string]> = [];
+    for (let i = 0; i < 100; i++) rawEdges.push([`pred${i}`, "hub"]);
+    const edges = buildEdgeIndex(rawEdges);
+    const own = new Map([
+      ["hub", 0.6],
+      ["pred0", 0.5],
+    ]);
+    const out = spreadActivation(own, edges, 0.5, 2);
+    // hop1 active = {pred0}, L_2([0.5]) = 0.5.
+    //   numerator   = 0.6 + 0.5 · 0.5 = 0.85
+    //   denominator = 1 + 0.5         = 1.5
+    expect(out.final.get("hub")).toBeCloseTo(0.85 / 1.5, 6);
   });
 
   test("empty own-activation map returns empty result", () => {
     const out = spreadActivation(
       new Map(),
-      { version: 1, edges: [["a", "b"]] },
+      buildEdgeIndex([["a", "b"]]),
       0.5,
       2,
     );
-    expect(out.size).toBe(0);
+    expect(out.final.size).toBe(0);
+    expect(out.contribution.size).toBe(0);
+  });
+
+  test("contribution equals final - own for each slug", () => {
+    // Two-cycle: A→B and B→A so both nodes have predecessors and the spread
+    // moves each off its own value in opposite directions.
+    const edges = buildEdgeIndex([
+      ["alice", "bob"],
+      ["bob", "alice"],
+    ]);
+    const own = new Map([
+      ["alice", 0.0],
+      ["bob", 0.8],
+    ]);
+    const out = spreadActivation(own, edges, 0.5, 2);
+    for (const [slug, finalValue] of out.final) {
+      const ownValue = own.get(slug) ?? 0;
+      expect(out.contribution.get(slug)).toBeCloseTo(finalValue - ownValue, 6);
+    }
+    // alice gained spread (predecessor bob=0.8); bob lost some (predecessor
+    // alice=0 dilutes its own 0.8).
+    expect(out.contribution.get("alice")).toBeGreaterThan(0);
+    expect(out.contribution.get("bob")).toBeLessThan(0);
+  });
+
+  test("contribution is 0 for every slug when hops == 0", () => {
+    const edges = buildEdgeIndex([["alice", "bob"]]);
+    const own = new Map([
+      ["alice", 0.4],
+      ["bob", 0.9],
+    ]);
+    const out = spreadActivation(own, edges, 0.5, 0);
+    expect(out.contribution.get("alice")).toBe(0);
+    expect(out.contribution.get("bob")).toBe(0);
+  });
+
+  test("contribution is 0 for every slug when k == 0", () => {
+    const edges = buildEdgeIndex([["alice", "bob"]]);
+    const own = new Map([
+      ["alice", 0.4],
+      ["bob", 0.9],
+    ]);
+    const out = spreadActivation(own, edges, 0, 5);
+    expect(out.contribution.get("alice")).toBe(0);
+    expect(out.contribution.get("bob")).toBe(0);
   });
 });
 
@@ -654,7 +895,7 @@ describe("selectInjections", () => {
 });
 
 // ---------------------------------------------------------------------------
-// selectSkillCandidates
+// computeSkillActivation
 // ---------------------------------------------------------------------------
 
 /** Stage a single hybrid response on the skills queues (payload key = `id`). */
@@ -673,90 +914,6 @@ function stageSkillHybridResponse(
   });
 }
 
-describe("selectSkillCandidates", () => {
-  test("returns hit ids from the skills collection", async () => {
-    stageSkillHybridResponse([
-      { id: "example-skill-a", denseScore: 0.5, sparseScore: 1 },
-      { id: "example-skill-b", denseScore: 0.3, sparseScore: 1 },
-    ]);
-    const out = await selectSkillCandidates({
-      userText: "user said hello",
-      assistantText: "",
-      nowText: "",
-      config: makeConfig(),
-      topK: 10,
-    });
-    expect(out).toEqual(new Set(["example-skill-a", "example-skill-b"]));
-  });
-
-  test("empty turn text short-circuits without backend calls", async () => {
-    const out = await selectSkillCandidates({
-      userText: "",
-      assistantText: "",
-      nowText: "",
-      config: makeConfig(),
-      topK: 10,
-    });
-    expect(out.size).toBe(0);
-    expect(state.embedCalls).toHaveLength(0);
-    expect(state.queryCalls).toHaveLength(0);
-  });
-
-  test("topK=0 short-circuits without backend calls", async () => {
-    const out = await selectSkillCandidates({
-      userText: "anything",
-      assistantText: "anything",
-      nowText: "anything",
-      config: makeConfig(),
-      topK: 0,
-    });
-    expect(out.size).toBe(0);
-    expect(state.embedCalls).toHaveLength(0);
-    expect(state.queryCalls).toHaveLength(0);
-  });
-
-  test("forwards topK and queries the skills collection unrestricted", async () => {
-    stageSkillHybridResponse([
-      { id: "example-skill-a", denseScore: 0.5, sparseScore: 1 },
-    ]);
-    await selectSkillCandidates({
-      userText: "hello",
-      assistantText: "",
-      nowText: "",
-      config: makeConfig(),
-      topK: 7,
-    });
-    // Both channels (dense + sparse) ran with limit=7 and no slug/id filter,
-    // against the dedicated skills collection.
-    expect(state.queryCalls).toHaveLength(2);
-    for (const call of state.queryCalls) {
-      expect(call.collection).toBe("memory_v2_skills");
-      expect(call.limit).toBe(7);
-      expect(call.filter).toBeUndefined();
-    }
-  });
-
-  test("embeds concatenated turn text exactly once", async () => {
-    stageSkillHybridResponse([]);
-    await selectSkillCandidates({
-      userText: "user line",
-      assistantText: "assistant line",
-      nowText: "now line",
-      config: makeConfig(),
-      topK: 5,
-    });
-    expect(state.embedCalls).toHaveLength(1);
-    expect(state.embedCalls[0].inputs).toEqual([
-      "user line\nassistant line\nnow line",
-    ]);
-    expect(state.sparseCalls).toEqual(["user line\nassistant line\nnow line"]);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// computeSkillActivation
-// ---------------------------------------------------------------------------
-
 describe("computeSkillActivation", () => {
   test("empty candidates short-circuits without backend calls", async () => {
     const out = await computeSkillActivation({
@@ -766,7 +923,8 @@ describe("computeSkillActivation", () => {
       nowText: "n",
       config: makeConfig(),
     });
-    expect(out.size).toBe(0);
+    expect(out.activation.size).toBe(0);
+    expect(out.breakdown.size).toBe(0);
     expect(state.embedCalls).toHaveLength(0);
     expect(state.queryCalls).toHaveLength(0);
   });
@@ -790,7 +948,7 @@ describe("computeSkillActivation", () => {
       }),
     });
     // No `d · prev` term: 0.3*0.5 + 0.2*0.4 + 0.2*0.2 = 0.15 + 0.08 + 0.04 = 0.27
-    expect(out.get("example-skill-a")).toBeCloseTo(0.27, 6);
+    expect(out.activation.get("example-skill-a")).toBeCloseTo(0.27, 6);
   });
 
   test("output excludes any decay term — d coefficient is unused", async () => {
@@ -824,8 +982,8 @@ describe("computeSkillActivation", () => {
     });
 
     // Both equal `0.3*0.4 + 0.2*0.4 + 0.2*0.4 = 0.28` — d is ignored.
-    expect(withHighD.get("alpha")).toBeCloseTo(0.28, 6);
-    expect(withZeroD.get("alpha")).toBeCloseTo(0.28, 6);
+    expect(withHighD.activation.get("alpha")).toBeCloseTo(0.28, 6);
+    expect(withZeroD.activation.get("alpha")).toBeCloseTo(0.28, 6);
   });
 
   test("clamps over-1.0 results down to [0, 1]", async () => {
@@ -846,7 +1004,7 @@ describe("computeSkillActivation", () => {
         c_now: 0.5,
       }),
     });
-    expect(out.get("loud-skill")).toBe(1);
+    expect(out.activation.get("loud-skill")).toBe(1);
   });
 
   test("candidate with no sim hits resolves to 0", async () => {
@@ -861,7 +1019,30 @@ describe("computeSkillActivation", () => {
       nowText: "n",
       config: makeConfig(),
     });
-    expect(out.get("ghost-skill")).toBe(0);
+    expect(out.activation.get("ghost-skill")).toBe(0);
+  });
+
+  test("breakdown captures the raw sims for each candidate", async () => {
+    stageSkillHybridResponse([{ id: "example-skill-a", denseScore: 0.5 }]); // simU
+    stageSkillHybridResponse([{ id: "example-skill-a", denseScore: 0.4 }]); // simA
+    stageSkillHybridResponse([{ id: "example-skill-a", denseScore: 0.2 }]); // simN
+
+    const out = await computeSkillActivation({
+      candidates: new Set(["example-skill-a"]),
+      userText: "u",
+      assistantText: "a",
+      nowText: "n",
+      config: makeConfig({
+        c_user: 0.3,
+        c_assistant: 0.2,
+        c_now: 0.2,
+      }),
+    });
+    const breakdown = out.breakdown.get("example-skill-a");
+    expect(breakdown).toBeDefined();
+    expect(breakdown?.simUser).toBeCloseTo(0.5, 6);
+    expect(breakdown?.simAssistant).toBeCloseTo(0.4, 6);
+    expect(breakdown?.simNow).toBeCloseTo(0.2, 6);
   });
 
   test("uses the dedicated skills collection and never queries concept pages", async () => {