@vellumai/assistant 0.8.5 → 0.8.6

package/src/memory/v3/__tests__/gate.test.ts

@@ -2,8 +2,8 @@
  * Tests for `assistant/src/memory/v3/gate.ts`.
  *
  * Coverage matrix:
- *   - ready + selection → selection maps from candidates, in model order, and
- *     includes sticky slugs even when the model omits them.
+ *   - ready + selection → numbered `[N]` candidate ids map back to slugs in
+ *     model order, and includes sticky slugs even when the model omits them.
  *   - more + questions → `decision.questions` surfaced; selection still returned.
  *   - more with no/blank questions → decision is `{ decision: "more" }` (no
  *     empty `questions` array).
@@ -12,7 +12,7 @@
  *   - provider throws → fail-safe (ready, all candidates).
  *   - missing tool_use block → fail-safe (ready, all candidates).
  *   - tool input failing schema → fail-safe (ready, all candidates).
- *   - model selecting a slug outside the candidate set → dropped.
+ *   - model returning an out-of-range id (0 / past the end) → dropped.
  *   - request shape: forced tool_choice on `decide_selection`, candidate set in
  *     the user message, abort signal forwarded.
  *
@@ -132,7 +132,7 @@ describe("runGate — ready decision", () => {
     const provider = makeProvider(
       // Model selects b, a (its own order). Sticky `c` is omitted by the
       // model but must survive in the final selection.
-      gateToolResponse({ decision: "ready", selected_slugs: ["b", "a"] }),
+      gateToolResponse({ decision: "ready", selected_ids: [2, 1] }),
       calls,
     );
 
@@ -153,7 +153,7 @@ describe("runGate — ready decision", () => {
   test("forces tool_choice on decide_selection and surfaces candidates", async () => {
     const calls: ProviderCall[] = [];
     const provider = makeProvider(
-      gateToolResponse({ decision: "ready", selected_slugs: ["a"] }),
+      gateToolResponse({ decision: "ready", selected_ids: [1] }),
       calls,
     );
 
@@ -172,18 +172,30 @@ describe("runGate — ready decision", () => {
     });
     expect(call.options?.config?.callSite).toBe("memoryV3Gate");
     expect(call.tools?.[0].name).toBe("decide_selection");
+    // The output schema is candidate-independent: selected_ids is a plain
+    // integer array (no per-candidate enum), so it stays byte-identical per turn.
+    const schema = call.tools![0].input_schema as {
+      properties: Record<
+        string,
+        { type?: string; items?: { type?: string; enum?: unknown } }
+      >;
+    };
+    expect(schema.properties.selected_ids?.type).toBe("array");
+    expect(schema.properties.selected_ids?.items?.type).toBe("integer");
+    expect(schema.properties.selected_ids?.items?.enum).toBeUndefined();
     const userText = call.messages[0].content
       .map((b) => (b.type === "text" ? b.text : ""))
       .join("\n");
     expect(userText).toContain("NOW-MARKER");
-    expect(userText).toContain("a");
-    expect(userText).toContain("b");
+    // Candidates are numbered from 1 in candidate order.
+    expect(userText).toContain("[1] a");
+    expect(userText).toContain("[2] b");
   });
 
   test("includes the just-arrived turn so the selection is query-aware", async () => {
     const calls: ProviderCall[] = [];
     const provider = makeProvider(
-      gateToolResponse({ decision: "ready", selected_slugs: ["a"] }),
+      gateToolResponse({ decision: "ready", selected_ids: [1] }),
       calls,
     );
 
@@ -211,10 +223,58 @@ describe("runGate — ready decision", () => {
     expect(userText).toContain("an earlier reply");
   });
 
-  test("drops a model-selected slug outside the candidate set", async () => {
+  test("omitted selected_ids falls back to all candidates (recall-safe)", async () => {
+    const calls: ProviderCall[] = [];
+    // `ready` verdict with no `selected_ids` field at all. A silent omission
+    // must keep everything surfaced, not drop all non-sticky context.
+    const provider = makeProvider(
+      gateToolResponse({ decision: "ready" }),
+      calls,
+    );
+
+    const result = await runGate({
+      input: makeInput(),
+      candidates: new Set(["frames/example-a", "people/alice", "people/bob"]),
+      sticky: new Set(["people/bob"]),
+      passNumber: 1,
+      provider,
+    });
+
+    expect(result.decision).toEqual({ decision: "ready" });
+    expect([...result.selectedSlugs].sort()).toEqual([
+      "frames/example-a",
+      "people/alice",
+      "people/bob",
+    ]);
+  });
+
+  test("explicit empty selected_ids selects nothing but sticky", async () => {
+    const calls: ProviderCall[] = [];
+    // An *explicit* `[]` is the model genuinely choosing nothing — honored as-is
+    // (only sticky survives), unlike an omitted field.
+    const provider = makeProvider(
+      gateToolResponse({ decision: "ready", selected_ids: [] }),
+      calls,
+    );
+
+    const result = await runGate({
+      input: makeInput(),
+      candidates: new Set(["frames/example-a", "people/alice", "people/bob"]),
+      sticky: new Set(["people/bob"]),
+      passNumber: 1,
+      provider,
+    });
+
+    expect(result.decision).toEqual({ decision: "ready" });
+    // Only sticky carries over; the model dropped everything else.
+    expect(result.selectedSlugs).toEqual(["people/bob"]);
+  });
+
+  test("drops out-of-range ids (0, past the end) without throwing", async () => {
     const calls: ProviderCall[] = [];
     const provider = makeProvider(
-      gateToolResponse({ decision: "ready", selected_slugs: ["a", "ghost"] }),
+      // id 1 -> "a"; 0 and 99 are out of range (1-based, only 2 candidates).
+      gateToolResponse({ decision: "ready", selected_ids: [1, 0, 99] }),
       calls,
     );
 
@@ -234,7 +294,7 @@ describe("runGate — ready decision", () => {
     const controller = new AbortController();
     controller.abort();
     const provider = makeProvider(
-      gateToolResponse({ decision: "ready", selected_slugs: ["a"] }),
+      gateToolResponse({ decision: "ready", selected_ids: [1] }),
       calls,
     );
 
@@ -257,7 +317,8 @@ describe("runGate — candidate summaries", () => {
   test("renders candidates as `slug — summary` when summaryBySlug is provided", async () => {
     const calls: ProviderCall[] = [];
     const provider = makeProvider(
-      gateToolResponse({ decision: "ready", selected_slugs: ["a/one"] }),
+      // id 1 -> "a/one".
+      gateToolResponse({ decision: "ready", selected_ids: [1] }),
       calls,
     );
 
@@ -273,19 +334,20 @@ describe("runGate — candidate summaries", () => {
       provider,
     });
 
-    // The model still answers in bare slugs (the enum is slug-only).
+    // The model answers with the [N] numbers, mapped back to slugs by the gate.
     expect(result.selectedSlugs).toEqual(["a/one"]);
     const userText = calls[0].messages[0].content
       .map((b) => (b.type === "text" ? b.text : ""))
       .join("\n");
-    expect(userText).toContain("a/one — first summary");
-    expect(userText).toContain("b/two — second summary");
+    // Candidates are numbered `[N] slug — summary`, in candidate order.
+    expect(userText).toContain("[1] a/one — first summary");
+    expect(userText).toContain("[2] b/two — second summary");
   });
 
   test("falls back to the bare slug when no summary is available", async () => {
     const calls: ProviderCall[] = [];
     const provider = makeProvider(
-      gateToolResponse({ decision: "ready", selected_slugs: [] }),
+      gateToolResponse({ decision: "ready", selected_ids: [] }),
       calls,
     );
 
@@ -300,7 +362,7 @@ describe("runGate — candidate summaries", () => {
     const userText = calls[0].messages[0].content
       .map((b) => (b.type === "text" ? b.text : ""))
       .join("\n");
-    expect(userText).toContain("a/one");
+    expect(userText).toContain("[1] a/one");
     expect(userText).not.toContain("a/one —");
   });
 });
@@ -311,7 +373,7 @@ describe("runGate — more decision", () => {
     const provider = makeProvider(
       gateToolResponse({
         decision: "more",
-        selected_slugs: ["a"],
+        selected_ids: [1],
         questions: ["What is the user's deadline?", "Who else is involved?"],
       }),
       calls,
@@ -338,7 +400,7 @@ describe("runGate — more decision", () => {
     const provider = makeProvider(
       gateToolResponse({
         decision: "more",
-        selected_slugs: ["a"],
+        selected_ids: [1],
         questions: ["   ", ""],
       }),
       calls,
@@ -360,7 +422,7 @@ describe("runGate — more decision", () => {
     const provider = makeProvider(
       gateToolResponse({
         decision: "more",
-        selected_slugs: ["a"],
+        selected_ids: [1],
         questions: ["follow-up?"],
       }),
       calls,
@@ -382,7 +444,7 @@ describe("runGate — system prompt", () => {
   test("uses the bundled default when no override is configured", async () => {
     const calls: ProviderCall[] = [];
     const provider = makeProvider(
-      gateToolResponse({ decision: "ready", selected_slugs: ["a"] }),
+      gateToolResponse({ decision: "ready", selected_ids: [1] }),
       calls,
     );
 
@@ -400,7 +462,7 @@ describe("runGate — system prompt", () => {
   test("uses the configured inline override as the system prompt", async () => {
     const calls: ProviderCall[] = [];
     const provider = makeProvider(
-      gateToolResponse({ decision: "ready", selected_slugs: ["a"] }),
+      gateToolResponse({ decision: "ready", selected_ids: [1] }),
       calls,
     );
 
@@ -468,10 +530,7 @@ describe("runGate — fail-safe", () => {
       sticky: new Set(),
       passNumber: 1,
       // `decision` is required; missing it fails the Zod schema.
-      provider: makeProvider(
-        gateToolResponse({ selected_slugs: ["a"] }),
-        calls,
-      ),
+      provider: makeProvider(gateToolResponse({ selected_ids: [1] }), calls),
     });
 
     expect(result.decision).toEqual({ decision: "ready" });
@@ -484,7 +543,7 @@ describe("runGate — capture", () => {
     const calls: ProviderCall[] = [];
     const captured: Omit<LlmCallRecord, "pass">[] = [];
     const provider = makeProvider(
-      gateToolResponse({ decision: "ready", selected_slugs: ["a"] }),
+      gateToolResponse({ decision: "ready", selected_ids: [1] }),
       calls,
     );
 
@@ -526,7 +585,7 @@ describe("runGate — reasoning field", () => {
   test("exposes an optional reasoning property in the forced tool schema", async () => {
     const calls: ProviderCall[] = [];
     const provider = makeProvider(
-      gateToolResponse({ decision: "ready", selected_slugs: ["a"] }),
+      gateToolResponse({ decision: "ready", selected_ids: [1] }),
       calls,
     );
 
@@ -547,12 +606,12 @@ describe("runGate — reasoning field", () => {
     expect(schema.required ?? []).not.toContain("reasoning");
   });
 
-  test("accepts model-supplied reasoning without altering the decision", async () => {
+  test("surfaces model-supplied reasoning on the decision without altering the verdict", async () => {
     const calls: ProviderCall[] = [];
     const provider = makeProvider(
       gateToolResponse({
         decision: "ready",
-        selected_slugs: ["b", "a"],
+        selected_ids: [2, 1],
         reasoning: "kept the two query-relevant pages, dropped the rest",
       }),
       calls,
@@ -566,9 +625,13 @@ describe("runGate — reasoning field", () => {
       provider,
     });
 
-    // Reasoning is ignored by control flow: decision + ordered selection
-    // (model order, omitted sticky appended) are unchanged.
-    expect(result.decision).toEqual({ decision: "ready" });
+    // Reasoning does not alter control flow — the verdict and ordered selection
+    // (model order, omitted sticky appended) are unchanged — but it IS carried
+    // on the decision so a run can be analyzed (trace + shadow telemetry).
+    expect(result.decision).toEqual({
+      decision: "ready",
+      reasoning: "kept the two query-relevant pages, dropped the rest",
+    });
     expect(result.selectedSlugs).toEqual(["b", "a", "c"]);
   });
 });

package/src/memory/v3/__tests__/index-composition.test.ts

@@ -230,4 +230,62 @@ describe("composeNodeIndex", () => {
 
     expect(composeNodeIndex("root", tree, pageIndex([]))).toBe("[node:empty]");
   });
+
+  test("collapses a multi-line node summary to a single index line", () => {
+    const tree = treeIndex(
+      [
+        treeNode("root", {}),
+        treeNode("multiline", {
+          summary: "First sentence.\nSecond sentence.\n  Third.",
+        }),
+      ],
+      { root: [{ kind: "node", ref: "multiline" }] },
+    );
+
+    const block = composeNodeIndex("root", tree, pageIndex([]));
+
+    expect(block).toBe(
+      "[node:multiline] First sentence. Second sentence. Third.",
+    );
+    expect(block.split("\n")).toHaveLength(1);
+  });
+
+  test("collapses a multi-line page summary to a single index line", () => {
+    const tree = treeIndex([treeNode("root", {})], {
+      root: [{ kind: "page", ref: "notes" }],
+    });
+    const pages = pageIndex([
+      pageEntry("notes", "Line one\nLine two\n\nLine three"),
+    ]);
+
+    const block = composeNodeIndex("root", tree, pages);
+
+    expect(block).toBe("[page:notes] Line one Line two Line three");
+    expect(block.split("\n")).toHaveLength(1);
+  });
+
+  test("a multi-line summary cannot inject extra index lines", () => {
+    // A summary crafted to look like another child entry must not become its
+    // own parsed line once collapsed.
+    const tree = treeIndex(
+      [
+        treeNode("root", {}),
+        treeNode("a", { summary: "Real summary\n[node:injected] fake entry" }),
+        treeNode("b", { summary: "Sibling" }),
+      ],
+      {
+        root: [
+          { kind: "node", ref: "a" },
+          { kind: "node", ref: "b" },
+        ],
+      },
+    );
+
+    const block = composeNodeIndex("root", tree, pageIndex([]));
+
+    expect(block.split("\n")).toEqual([
+      "[node:a] Real summary [node:injected] fake entry",
+      "[node:b] Sibling",
+    ]);
+  });
 });

package/src/memory/v3/__tests__/loop.test.ts

@@ -86,12 +86,20 @@ const lane = {
 /** Records the args the loop passed each lane, one entry per call. */
 const laneCalls = {
   scouts: [] as Array<{ nowText: string }>,
-  filter: [] as Array<{ nowText: string; dense: ScoutResult }>,
+  filter: [] as Array<{
+    nowText: string;
+    dense: ScoutResult;
+    sticky: string[];
+    bypass: string[];
+  }>,
   walk: [] as Array<{
     nowText: string;
     scouts: ScoutResult[];
   }>,
-  edges: [] as Array<{ seeds: string[] }>,
+  edges: [] as Array<{
+    seeds: string[];
+    extraAdjacency?: ReadonlyMap<string, ReadonlySet<string>>;
+  }>,
   gate: [] as Array<{
     nowText: string;
     passNumber: number;
@@ -110,6 +118,14 @@ let walkCallCount = 0;
 let edgeCallCount = 0;
 let gateCallCount = 0;
 
+// Learned-adjacency mock state: what `aboveThreshold` returns, and a recorder of
+// the thresholds the loop read it at (empty when the loop never reads it).
+let aboveThresholdCalls: Array<{ threshold: number }> = [];
+let learnedAdjacencyResult: ReadonlyMap<
+  string,
+  ReadonlySet<string>
+> = new Map();
+
 mock.module("../scouts.js", () => ({
   runScouts: async (input: RetrievalInput): Promise<RunScoutsResult> => {
     laneCalls.scouts.push({ nowText: input.nowText });
@@ -121,8 +137,15 @@ mock.module("../filter.js", () => ({
   filterDenseHits: async (args: {
     input: RetrievalInput;
     dense: ScoutResult;
+    sticky: Set<string>;
+    bypass: Set<string>;
   }): Promise<FilterResult> => {
-    laneCalls.filter.push({ nowText: args.input.nowText, dense: args.dense });
+    laneCalls.filter.push({
+      nowText: args.input.nowText,
+      dense: args.dense,
+      sticky: [...args.sticky],
+      bypass: [...args.bypass],
+    });
     // Filter calls share the scout pass index (one filter call per dense pass).
     return nextOf(lane.filter, laneCalls.filter.length - 1);
   },
@@ -144,12 +167,23 @@ mock.module("../tree-walk.js", () => ({
 mock.module("../edges.js", () => ({
   expandEdges: async (args: {
     seeds: Iterable<string>;
+    extraAdjacency?: ReadonlyMap<string, ReadonlySet<string>>;
   }): Promise<ExpandResult> => {
-    laneCalls.edges.push({ seeds: [...args.seeds] });
+    laneCalls.edges.push({
+      seeds: [...args.seeds],
+      extraAdjacency: args.extraAdjacency,
+    });
     return nextOf(lane.edges, edgeCallCount++);
   },
 }));
 
+mock.module("../auto-edges.js", () => ({
+  aboveThreshold: (_db: unknown, threshold: number) => {
+    aboveThresholdCalls.push({ threshold });
+    return learnedAdjacencyResult;
+  },
+}));
+
 mock.module("../gate.js", () => ({
   runGate: async (args: {
     input: RetrievalInput;
@@ -213,6 +247,7 @@ function makeInput(opts?: {
   nowText?: string;
   passCap?: number;
   lanes?: LaneConfig;
+  edgesThreshold?: number;
 }): RetrievalInput {
   const lanes = {
     hot: true,
@@ -228,7 +263,13 @@ function makeInput(opts?: {
     nowText: opts?.nowText ?? "NOW",
     priorEverInjected: [],
     config: {
-      memory: { v3: { passCap: opts?.passCap ?? 3, lanes } },
+      memory: {
+        v3: {
+          passCap: opts?.passCap ?? 3,
+          lanes,
+          edges: { learnedAdjacencyThreshold: opts?.edgesThreshold ?? 0 },
+        },
+      },
     } as unknown as RetrievalInput["config"],
   };
 }
@@ -260,6 +301,8 @@ function reset(): void {
   walkCallCount = 0;
   edgeCallCount = 0;
   gateCallCount = 0;
+  aboveThresholdCalls = [];
+  learnedAdjacencyResult = new Map();
 }
 
 beforeEach(reset);
@@ -405,6 +448,46 @@ describe("runRetrievalLoop — multi pass", () => {
     expect(out.selectedSlugs).toEqual(["p1", "p2"]);
   });
 
+  test("candidates accumulate across passes so the final gate sees pass-1 hits", async () => {
+    // Each pass surfaces a distinct dense hit. Without cross-pass accumulation
+    // the pass-2 gate would only see "p2"; with it, the cumulative pool carries
+    // pass-1's "p1" into the final gate input.
+    lane.scouts = [
+      {
+        scouts: [scout("dense", ["p1"])],
+        sticky: new Set(),
+        bypass: new Set(),
+      },
+      {
+        scouts: [scout("dense", ["p2"])],
+        sticky: new Set(),
+        bypass: new Set(),
+      },
+    ];
+    lane.filter = [
+      { kept: ["p1"], trace: { judged: ["p1"], dropped: [] } },
+      { kept: ["p2"], trace: { judged: ["p2"], dropped: [] } },
+    ];
+    lane.walk = [
+      { pages: new Set(), levels: [] },
+      { pages: new Set(), levels: [] },
+    ];
+    lane.edges = [
+      { pulled: new Set(), expansions: [] },
+      { pulled: new Set(), expansions: [] },
+    ];
+    lane.gate = [moreGate(["p1"], ["more?"]), readyGate(["p1", "p2"])];
+
+    const out = await runRetrievalLoop(makeInput({ passCap: 3 }), { db });
+
+    // Pass 1's gate saw only p1; pass 2's gate saw the cumulative pool.
+    expect(laneCalls.gate[0].candidates).toEqual(["p1"]);
+    expect(laneCalls.gate[1].candidates).toEqual(
+      expect.arrayContaining(["p1", "p2"]),
+    );
+    expect(out.selectedSlugs).toEqual(["p1", "p2"]);
+  });
+
   test("passCap force-exits with the current selection when the gate keeps asking for more", async () => {
     lane.scouts = [
       { scouts: [scout("dense", ["p"])], sticky: new Set(), bypass: new Set() },
@@ -492,6 +575,125 @@ describe("runRetrievalLoop — lane toggles", () => {
   });
 });
 
+describe("runRetrievalLoop — sourceBySlug lane trust", () => {
+  test("upgrades a slug's lane when a higher-trust lane re-surfaces it in one pass", async () => {
+    // `shared` is surfaced by the low-trust hot lane AND survives the
+    // higher-trust dense filter in the same pass. Provenance must end on the
+    // more trusted lane (dense) so the downstream seed cap ranks it by its
+    // strongest signal, not the stale first-seen hot lane.
+    lane.scouts = [
+      {
+        scouts: [scout("hot", ["shared"]), scout("dense", ["shared"])],
+        sticky: new Set(),
+        bypass: new Set(),
+      },
+    ];
+    lane.filter = [
+      { kept: ["shared"], trace: { judged: ["shared"], dropped: [] } },
+    ];
+    lane.walk = [{ pages: new Set(), levels: [] }];
+    lane.edges = [{ pulled: new Set(), expansions: [] }];
+    lane.gate = [readyGate(["shared"])];
+
+    const out = await runRetrievalLoop(makeInput(), { db });
+
+    // hot tagged first, then upgraded to the more trusted dense lane.
+    expect(out.sourceBySlug.get("shared")).toBe("dense");
+  });
+
+  test("does not downgrade a slug's lane when a lower-trust lane re-surfaces it", async () => {
+    // `s` is a dense survivor (trusted) in pass 1, then edge-pulled (lowest
+    // trust) in pass 2. The lane must stay dense — only upgrades apply.
+    lane.scouts = [
+      {
+        scouts: [scout("dense", ["s"])],
+        sticky: new Set(),
+        bypass: new Set(),
+      },
+      { scouts: [], sticky: new Set(), bypass: new Set() },
+    ];
+    lane.filter = [
+      { kept: ["s"], trace: { judged: ["s"], dropped: [] } },
+      { kept: [], trace: { judged: [], dropped: [] } },
+    ];
+    lane.walk = [
+      { pages: new Set(), levels: [] },
+      { pages: new Set(), levels: [] },
+    ];
+    // Pass 2's edge expansion re-pulls the already-dense `s`.
+    lane.edges = [
+      { pulled: new Set(), expansions: [] },
+      { pulled: new Set(["s"]), expansions: [{ from: "s", pulled: ["s"] }] },
+    ];
+    lane.gate = [moreGate(["s"], ["more?"]), readyGate(["s"])];
+
+    const out = await runRetrievalLoop(makeInput({ passCap: 2 }), { db });
+
+    expect(out.sourceBySlug.get("s")).toBe("dense");
+  });
+
+  test("upgrades the lane across passes while preserving earliest-pass provenance", async () => {
+    // `s` first enters via the low-trust edge lane on pass 1, then is surfaced
+    // by the higher-trust dense lane on pass 2. The lane upgrades to dense, but
+    // the co-activation provenance must still treat it as a pass-1 hit: the lane
+    // upgrades, the first-seen pass does not.
+    lane.scouts = [
+      { scouts: [], sticky: new Set(), bypass: new Set() },
+      {
+        scouts: [scout("dense", ["s"])],
+        sticky: new Set(),
+        bypass: new Set(),
+      },
+    ];
+    // Pass 1 has no dense scout, so the filter is called only once (pass 2);
+    // the mock indexes filter results by call count, so the single entry keeps `s`.
+    lane.filter = [{ kept: ["s"], trace: { judged: ["s"], dropped: [] } }];
+    lane.walk = [
+      { pages: new Set(), levels: [] },
+      { pages: new Set(), levels: [] },
+    ];
+    lane.edges = [
+      { pulled: new Set(["s"]), expansions: [{ from: "x", pulled: ["s"] }] },
+      { pulled: new Set(), expansions: [] },
+    ];
+    lane.gate = [moreGate([], ["more?"]), readyGate(["s"])];
+
+    const out = await runRetrievalLoop(makeInput({ passCap: 2 }), { db });
+
+    // Lane upgraded from edge (pass 1) to dense (pass 2).
+    expect(out.sourceBySlug.get("s")).toBe("dense");
+  });
+});
+
+describe("runRetrievalLoop — sticky excluded from dense filter", () => {
+  test("forwards the full sticky set to the filter while keeping sticky in the selection", async () => {
+    // `sk` is sticky (and a dense hit); `keep` is a plain dense candidate. The
+    // loop must hand the filter the full sticky set so it can exclude `sk` from
+    // judgment — `sk` is force-selected by the gate regardless. `keep` is
+    // judged and kept normally.
+    lane.scouts = [
+      {
+        scouts: [scout("dense", ["sk", "keep"])],
+        sticky: new Set(["sk"]),
+        bypass: new Set(),
+      },
+    ];
+    lane.filter = [
+      { kept: ["keep"], trace: { judged: ["keep"], dropped: [] } },
+    ];
+    lane.walk = [{ pages: new Set(), levels: [] }];
+    lane.edges = [{ pulled: new Set(), expansions: [] }];
+    lane.gate = [readyGate(["sk", "keep"])];
+
+    const out = await runRetrievalLoop(makeInput(), { db });
+
+    // The loop forwarded the full sticky set to the filter so it can subtract it.
+    expect(laneCalls.filter[0].sticky).toEqual(["sk"]);
+    // The sticky slug is still in the final selection (gate force-injects it).
+    expect(out.selectedSlugs).toEqual(expect.arrayContaining(["sk", "keep"]));
+  });
+});
+
 describe("runRetrievalLoop — failure + cost", () => {
   test("surfaces a filter failureReason on the output", async () => {
     lane.scouts = [
@@ -528,3 +730,46 @@ describe("runRetrievalLoop — failure + cost", () => {
     expect(out.cost?.ms).toBeGreaterThanOrEqual(0);
   });
 });
+
+describe("runRetrievalLoop — learned edge adjacency", () => {
+  /** Minimal single-pass fixture; the edge lane is the subject under test. */
+  function singlePassFixture(): void {
+    lane.scouts = [
+      {
+        scouts: [scout("hot", ["seed-x"])],
+        sticky: new Set(),
+        bypass: new Set(),
+      },
+    ];
+    lane.filter = [{ kept: [], trace: { judged: [], dropped: [] } }];
+    lane.walk = [{ pages: new Set(), levels: [] }];
+    lane.edges = [
+      {
+        pulled: new Set(["learned-y"]),
+        expansions: [{ from: "seed-x", pulled: ["learned-y"] }],
+      },
+    ];
+    lane.gate = [readyGate(["seed-x", "learned-y"])];
+  }
+
+  test("reads and merges learned adjacency into edge expansion when threshold > 0", async () => {
+    singlePassFixture();
+    learnedAdjacencyResult = new Map([["seed-x", new Set(["learned-y"])]]);
+
+    await runRetrievalLoop(makeInput({ edgesThreshold: 1.5 }), { db });
+
+    // The loop reads the learned graph once at the configured threshold and
+    // hands it to the edge lane as extraAdjacency.
+    expect(aboveThresholdCalls).toEqual([{ threshold: 1.5 }]);
+    expect(laneCalls.edges[0].extraAdjacency).toBe(learnedAdjacencyResult);
+  });
+
+  test("does not read or pass learned adjacency when the threshold is 0", async () => {
+    singlePassFixture();
+
+    await runRetrievalLoop(makeInput({ edgesThreshold: 0 }), { db });
+
+    expect(aboveThresholdCalls).toHaveLength(0);
+    expect(laneCalls.edges[0].extraAdjacency).toBeUndefined();
+  });
+});