@vellumai/assistant 0.8.8 → 0.8.9-dev.202606091926.ebb2d62

package/src/plugins/defaults/memory-v3-shadow/__tests__/orchestrate.test.ts

@@ -0,0 +1,662 @@
+/**
+ * Tests for `orchestrate.ts` (section-lane pipeline).
+ *
+ * The orchestrator composes three deterministic candidate lanes — the
+ * section-grain BM25 needle, the dense lane, and link-graph edge expansion —
+ * into ONE unified pool, runs a SINGLE forced-tool select over the pool, then
+ * carries forward the working set. Synthetic capability pages (skills / CLI
+ * commands) are indexed like any other page, so they enter the pool through the
+ * lanes (e.g. the needle) rather than being always-added.
+ *
+ * The select provider is stubbed (no network); a single stub answers the one
+ * `select_pages` call per turn by reading the numbered `<candidates>` block.
+ * The dense lane is stubbed at the module boundary. The needle and edge graph
+ * are real, built from tiny inline fixtures so the pool union is exercised
+ * end-to-end.
+ */
+
+import { afterAll, beforeEach, describe, expect, mock, test } from "bun:test";
+
+import type { PageIndexEntry } from "../../../../memory/v2/page-index.js";
+import type {
+  Message,
+  Provider,
+  ProviderResponse,
+} from "../../../../providers/types.js";
+import type { EdgeGraph } from "../edge.js";
+import { buildEdgeGraph } from "../edge.js";
+import { buildSectionNeedle } from "../section-needle.js";
+import { buildSectionIndex } from "../sections.js";
+import type { MemoryRoutingTurn, SectionIndex, Slug } from "../types.js";
+
+// ---------------------------------------------------------------------------
+// Module stubs installed BEFORE the orchestrator import so pool-select and the
+// dense lane observe them at load time.
+// ---------------------------------------------------------------------------
+
+let providerStub: Provider | null = null;
+
+mock.module("../../../../providers/provider-send-message.js", () => ({
+  getConfiguredProvider: async () => providerStub,
+  extractToolUse: (response: ProviderResponse) =>
+    response.content.find((b) => b.type === "tool_use"),
+}));
+
+mock.module("../../../../util/logger.js", () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, {
+      get: (_t, prop) => (prop === "child" ? () => ({}) : () => {}),
+    }),
+}));
+
+// The dense lane is stubbed: each test sets `denseHits` to control which
+// articles (+ matched ordinals) the dense lane returns. The stub DELEGATES to
+// the real `denseLane` unless this file's tests are running (`denseMockActive`),
+// so the process-global `mock.module` cannot leak fake behavior into
+// dense.test.ts (which exercises the real lane). Spread the real module so
+// every other export (`OVERSAMPLE`) stays present.
+const realDense = { ...(await import("../dense.js")) };
+let denseMockActive = false;
+let denseHits: Array<{ article: Slug; section: number }> = [];
+mock.module("../dense.js", () => ({
+  ...realDense,
+  denseLane: async (...args: Parameters<typeof realDense.denseLane>) =>
+    denseMockActive ? denseHits : realDense.denseLane(...args),
+}));
+
+const { orchestrate, DEFAULT_NEEDLE_K, DEFAULT_DENSE_K } =
+  await import("../orchestrate.js");
+const { WorkingSet } = await import("../working-set.js");
+
+// ---------------------------------------------------------------------------
+// Fixtures: a tiny corpus of pages with bodies + `links:` frontmatter.
+// ---------------------------------------------------------------------------
+
+const PAGES: Record<Slug, string> = {
+  "topic-a": "lead for topic a\n## Details\napple banana about topic a",
+  "topic-b": "lead for topic b\n## More\ncherry date about topic b",
+  "topic-c": "lead for topic c\n## Notes\nelderberry fig about topic c",
+  "topic-d": "lead for topic d\n## Notes\ngrape about topic d",
+};
+
+/** Raw page = frontmatter (with `links:`) + body. */
+const RAW: Record<Slug, string> = {
+  "topic-a": `---\nlinks:\n  - "topic-d — the curated edge from a to d"\n---\n${PAGES["topic-a"]}`,
+  "topic-b": `---\nedges: []\n---\n${PAGES["topic-b"]}`,
+  "topic-c": `---\nedges: []\n---\n${PAGES["topic-c"]}`,
+  "topic-d": `---\nedges: []\n---\n${PAGES["topic-d"]}`,
+};
+
+const SLUGS = Object.keys(PAGES);
+
+function makeEntries(): PageIndexEntry[] {
+  return SLUGS.map((slug, i) => ({
+    id: i + 1,
+    slug,
+    summary: `summary of ${slug}`,
+    edges: [],
+    leaves: [],
+    modifiedAt: 0,
+  }));
+}
+
+async function buildLanes(): Promise<{
+  sectionIndex: SectionIndex;
+  needle: ReturnType<typeof buildSectionNeedle>;
+  edgeGraph: EdgeGraph;
+}> {
+  const sectionIndex = await buildSectionIndex(SLUGS, async (s) => PAGES[s]!);
+  const needle = buildSectionNeedle(sectionIndex);
+  const edgeGraph = await buildEdgeGraph(makeEntries(), async (s) => RAW[s]!);
+  return { sectionIndex, needle, edgeGraph };
+}
+
+const config = {} as never;
+
+function makeTurn(
+  turnNumber: number,
+  currentMessage: string,
+): MemoryRoutingTurn {
+  return {
+    conversationId: "conv-xyz",
+    turnNumber,
+    currentMessage,
+    recentContext: "prior context",
+  };
+}
+
+function toolUseResponse(input: Record<string, unknown>): ProviderResponse {
+  return {
+    model: "stub-model",
+    stopReason: "tool_use",
+    usage: { inputTokens: 0, outputTokens: 0 },
+    content: [{ type: "tool_use", id: "tu-1", name: "select_pages", input }],
+  };
+}
+
+/** Parse the numbered `<candidates>` block back into an ordered slug list. */
+function candidateSlugs(messages: Message[]): Slug[] {
+  for (const msg of messages) {
+    for (const block of msg.content) {
+      if (block.type !== "text") continue;
+      const m = /<candidates>\n([\s\S]*?)\n<\/candidates>/.exec(block.text);
+      if (!m) continue;
+      return m[1]
+        .split("\n")
+        .map((line) => /^\[\d+\] (\S+) —/.exec(line)?.[1])
+        .filter((s): s is string => !!s);
+    }
+  }
+  return [];
+}
+
+/**
+ * Provider that selects the pool candidates whose slug is in `keep` (mapping
+ * each back to its 1-based id), pinning those in `pin`. Captures the rendered
+ * candidate list for pool assertions.
+ */
+let lastPool: Slug[] = [];
+let selectCalls = 0;
+function selectProvider(keep: Slug[], pin: Slug[] = []): Provider {
+  return {
+    name: "stub",
+    sendMessage: async (messages) => {
+      selectCalls++;
+      const pool = candidateSlugs(messages);
+      lastPool = pool;
+      const ids: number[] = [];
+      const pinned_ids: number[] = [];
+      pool.forEach((slug, i) => {
+        if (keep.includes(slug)) ids.push(i + 1);
+        if (pin.includes(slug)) pinned_ids.push(i + 1);
+      });
+      return toolUseResponse({ ids, pinned_ids });
+    },
+  };
+}
+
+beforeEach(() => {
+  denseMockActive = true;
+  providerStub = null;
+  denseHits = [];
+  lastPool = [];
+  selectCalls = 0;
+});
+
+afterAll(() => {
+  denseMockActive = false;
+});
+
+// ---------------------------------------------------------------------------
+// Pool composition: the candidate pool is the union of the lanes. Synthetic
+// capability pages are no longer always-added — they enter through a lane (see
+// the dedicated test below).
+// ---------------------------------------------------------------------------
+
+describe("orchestrate — candidate pool composition", () => {
+  test("pool unions needle ∪ dense ∪ edge; one select runs", async () => {
+    const lanes = await buildLanes();
+    // "apple" hits topic-a (needle). Dense returns topic-b. topic-a links to
+    // topic-d (edge).
+    denseHits = [{ article: "topic-b", section: 0 }];
+    providerStub = selectProvider([]); // selection is irrelevant to pool union
+
+    await orchestrate(makeTurn(1, "apple"), {
+      sectionIndex: lanes.sectionIndex,
+      needle: lanes.needle,
+      denseConfig: config,
+      edgeGraph: lanes.edgeGraph,
+      workingSet: new WorkingSet(),
+    });
+
+    expect(selectCalls).toBe(1);
+    expect(new Set(lastPool)).toEqual(
+      new Set(["topic-a", "topic-b", "topic-d"]),
+    );
+  });
+
+  test("a synthetic capability page enters the pool via the needle lane", async () => {
+    // A capability slug indexed with body content (the section index treats it
+    // like any other page) is ranked by the real needle when the query matches
+    // its text — this is how synthetic pages reach the pool now that they are no
+    // longer always-added.
+    const CAP: Slug = "skills/example";
+    const sectionIndex = await buildSectionIndex([...SLUGS, CAP], async (s) =>
+      s === CAP
+        ? "# Skill: example\nuse the kumquat skill to do the thing"
+        : PAGES[s]!,
+    );
+    const needle = buildSectionNeedle(sectionIndex);
+    const edgeGraph = await buildEdgeGraph(makeEntries(), async (s) => RAW[s]!);
+
+    providerStub = selectProvider([]); // selection irrelevant to pool union
+    await orchestrate(makeTurn(1, "kumquat"), {
+      sectionIndex,
+      needle,
+      denseConfig: config,
+      edgeGraph,
+      workingSet: new WorkingSet(),
+    });
+
+    // The needle ranked the capability page on the "kumquat" term, so it is in
+    // the candidate pool.
+    expect(lastPool).toContain(CAP);
+  });
+
+  test("edge curated link description becomes the edge candidate's descriptor", async () => {
+    const lanes = await buildLanes();
+    let descriptorLine = "";
+    providerStub = {
+      name: "stub",
+      sendMessage: async (messages) => {
+        for (const msg of messages) {
+          for (const block of msg.content) {
+            if (block.type !== "text") continue;
+            const m = /\[\d+\] topic-d — ([^\n]+)/.exec(block.text);
+            if (m) descriptorLine = m[1]!;
+          }
+        }
+        return toolUseResponse({ ids: [] });
+      },
+    };
+
+    await orchestrate(makeTurn(1, "apple"), {
+      sectionIndex: lanes.sectionIndex,
+      needle: lanes.needle,
+      denseConfig: config,
+      edgeGraph: lanes.edgeGraph,
+      workingSet: new WorkingSet(),
+    });
+
+    expect(descriptorLine).toContain("the curated edge from a to d");
+  });
+
+  test("needleK and denseK default to their constants", async () => {
+    const lanes = await buildLanes();
+    let needleK = -1;
+    const needle = {
+      query: (_t: string, k: number) => {
+        needleK = k;
+        return [];
+      },
+      bestSection: () => -1,
+    };
+    providerStub = selectProvider([]);
+    await orchestrate(makeTurn(1, "x"), {
+      sectionIndex: lanes.sectionIndex,
+      needle,
+      denseConfig: config,
+      edgeGraph: lanes.edgeGraph,
+      workingSet: new WorkingSet(),
+    });
+    expect(needleK).toBe(DEFAULT_NEEDLE_K);
+    expect(DEFAULT_DENSE_K).toBe(100);
+  });
+
+  test("sectionBySlug is populated from matched lane sections", async () => {
+    const lanes = await buildLanes();
+    denseHits = [];
+    providerStub = selectProvider(["topic-a"]);
+    const result = await orchestrate(makeTurn(1, "apple"), {
+      sectionIndex: lanes.sectionIndex,
+      needle: lanes.needle,
+      denseConfig: config,
+      edgeGraph: lanes.edgeGraph,
+      workingSet: new WorkingSet(),
+    });
+    // topic-a matched "apple" in its `## Details` section.
+    expect(result.sectionBySlug.get("topic-a")?.article).toBe("topic-a");
+    expect(result.sectionBySlug.get("topic-a")?.text).toContain("apple");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Edge-only injection: a page surfaced ONLY by the edge lane (the query did not
+// lexically hit it) records NO matched section, so injection falls back to the
+// FULL page (the curated `links` description — not the often-empty lead the
+// query never hit — is what made the candidate relevant). The best-section text
+// is kept only as the select-pool descriptor fallback.
+// ---------------------------------------------------------------------------
+
+describe("orchestrate — edge-only injection", () => {
+  test("an edge-only page records NO sectionBySlug entry (→ full-page inject)", async () => {
+    const lanes = await buildLanes();
+    // "apple" hits topic-a (needle); topic-a links to topic-d (edge-only — the
+    // query never hits topic-d). Select topic-d so it is in the result.
+    denseHits = [];
+    providerStub = selectProvider(["topic-d"]);
+    const result = await orchestrate(makeTurn(1, "apple"), {
+      sectionIndex: lanes.sectionIndex,
+      needle: lanes.needle,
+      denseConfig: config,
+      edgeGraph: lanes.edgeGraph,
+      workingSet: new WorkingSet(),
+    });
+
+    // topic-d was selected and injected, but with NO matched section — so
+    // `renderV3SectionContent(slug, undefined)` falls back to the full page.
+    expect(result.finalInjection).toContain("topic-d");
+    expect(result.sectionBySlug.has("topic-d")).toBe(false);
+  });
+
+  test("an edge-only page still carries the curated links description as its descriptor", async () => {
+    const lanes = await buildLanes();
+    let descriptorLine = "";
+    providerStub = {
+      name: "stub",
+      sendMessage: async (messages) => {
+        for (const msg of messages) {
+          for (const block of msg.content) {
+            if (block.type !== "text") continue;
+            const m = /\[\d+\] topic-d — ([^\n]+)/.exec(block.text);
+            if (m) descriptorLine = m[1]!;
+          }
+        }
+        return toolUseResponse({ ids: [] });
+      },
+    };
+
+    await orchestrate(makeTurn(1, "apple"), {
+      sectionIndex: lanes.sectionIndex,
+      needle: lanes.needle,
+      denseConfig: config,
+      edgeGraph: lanes.edgeGraph,
+      workingSet: new WorkingSet(),
+    });
+
+    // The curated `links` description (not the lead text) is the descriptor.
+    expect(descriptorLine).toContain("the curated edge from a to d");
+  });
+
+  test("an edge-only page with no curated description falls back to bestSection text as the descriptor", async () => {
+    // A bare `links:` entry (no ` — `) carries NO description, so the edge
+    // candidate's descriptor falls back to the page's best section against the
+    // query. The query never hits dst-page, so bestSection returns its lead;
+    // that lead text becomes the descriptor (and the page is still injected in
+    // full, with no sectionBySlug entry).
+    const pages: Record<Slug, string> = {
+      "src-page": "lead for src\n## Body\nalpha bravo about src",
+      "dst-page": "lead content for dst page\n## Extra\nnothing relevant here",
+    };
+    const raw: Record<Slug, string> = {
+      // bare slug — no ` — ` separator → undefined curated description.
+      "src-page": `---\nlinks:\n  - "dst-page"\n---\n${pages["src-page"]}`,
+      "dst-page": `---\nedges: []\n---\n${pages["dst-page"]}`,
+    };
+    const slugs = Object.keys(pages);
+    const entries: PageIndexEntry[] = slugs.map((slug, i) => ({
+      id: i + 1,
+      slug,
+      summary: `summary of ${slug}`,
+      edges: [],
+      leaves: [],
+      modifiedAt: 0,
+    }));
+    const sectionIndex = await buildSectionIndex(slugs, async (s) => pages[s]!);
+    const needle = buildSectionNeedle(sectionIndex);
+    const edgeGraph = await buildEdgeGraph(entries, async (s) => raw[s]!);
+
+    let descriptorLine = "";
+    providerStub = {
+      name: "stub",
+      sendMessage: async (messages) => {
+        for (const msg of messages) {
+          for (const block of msg.content) {
+            if (block.type !== "text") continue;
+            const m = /\[\d+\] dst-page — ([^\n]+)/.exec(block.text);
+            if (m) descriptorLine = m[1]!;
+          }
+        }
+        return toolUseResponse({ ids: [] });
+      },
+    };
+
+    // "alpha" hits src-page (needle); src-page links to dst-page (edge-only, no
+    // curated description).
+    const result = await orchestrate(makeTurn(1, "alpha"), {
+      sectionIndex,
+      needle,
+      denseConfig: config,
+      edgeGraph,
+      workingSet: new WorkingSet(),
+    });
+
+    // Descriptor fell back to dst-page's lead text; still no matched section.
+    expect(descriptorLine).toContain("lead content for dst page");
+    expect(result.sectionBySlug.has("dst-page")).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Dense liveness: a dense hit whose article is no longer in the live section
+// index (its page was deleted; its Qdrant points linger) is dropped from the
+// pool, so a deleted page can never be surfaced via the dense lane.
+// ---------------------------------------------------------------------------
+
+describe("orchestrate — dense liveness filter", () => {
+  test("a dense hit absent from sectionIndex.byArticle is dropped from the pool", async () => {
+    const lanes = await buildLanes();
+    // Dense returns a live page (topic-b) AND a deleted page (gone-page) whose
+    // points still linger in Qdrant but which is absent from the section index.
+    denseHits = [
+      { article: "topic-b", section: 0 },
+      { article: "gone-page", section: 0 },
+    ];
+    providerStub = selectProvider([]); // selection irrelevant to pool membership
+    const result = await orchestrate(makeTurn(1, "apple"), {
+      sectionIndex: lanes.sectionIndex,
+      needle: lanes.needle,
+      denseConfig: config,
+      edgeGraph: lanes.edgeGraph,
+      workingSet: new WorkingSet(),
+    });
+
+    // The live dense hit is pooled; the deleted page is dropped entirely.
+    expect(lastPool).toContain("topic-b");
+    expect(lastPool).not.toContain("gone-page");
+    expect(result.laneBySlug.has("gone-page")).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Lane provenance: each pooled slug records the candgen lane that FIRST
+// surfaced it (needle → dense → edge precedence), exposed via
+// `result.laneBySlug` so the selection telemetry can attribute true sources.
+// ---------------------------------------------------------------------------
+
+describe("orchestrate — lane provenance (laneBySlug)", () => {
+  test("laneBySlug tags each pooled slug with its surfacing lane", async () => {
+    const lanes = await buildLanes();
+    // "apple" hits topic-a (needle). Dense returns topic-b. topic-a links to
+    // topic-d (edge). So each lane contributes exactly one distinct slug.
+    denseHits = [{ article: "topic-b", section: 0 }];
+    providerStub = selectProvider([]); // selection irrelevant to pool provenance
+    const result = await orchestrate(makeTurn(1, "apple"), {
+      sectionIndex: lanes.sectionIndex,
+      needle: lanes.needle,
+      denseConfig: config,
+      edgeGraph: lanes.edgeGraph,
+      workingSet: new WorkingSet(),
+    });
+
+    expect(result.laneBySlug.get("topic-a")).toBe("needle");
+    expect(result.laneBySlug.get("topic-b")).toBe("dense");
+    expect(result.laneBySlug.get("topic-d")).toBe("edge");
+  });
+
+  test("a slug surfaced by needle AND dense keeps the needle lane (first wins)", async () => {
+    const lanes = await buildLanes();
+    // topic-a is surfaced by the needle on "apple"; dense ALSO returns topic-a.
+    // Needle runs first (step 2a before 2b), so the recorded lane stays needle.
+    denseHits = [{ article: "topic-a", section: 0 }];
+    providerStub = selectProvider([]);
+    const result = await orchestrate(makeTurn(1, "apple"), {
+      sectionIndex: lanes.sectionIndex,
+      needle: lanes.needle,
+      denseConfig: config,
+      edgeGraph: lanes.edgeGraph,
+      workingSet: new WorkingSet(),
+    });
+
+    expect(result.laneBySlug.get("topic-a")).toBe("needle");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Carry-forward: same working-set semantics as the prior tree pipeline.
+// ---------------------------------------------------------------------------
+
+describe("orchestrate — carry-forward", () => {
+  test("a page selected+pinned in turn 1 carries into turn 2 without re-selection", async () => {
+    const lanes = await buildLanes();
+    const workingSet = new WorkingSet();
+
+    // Turn 1 selects+pins topic-a.
+    providerStub = selectProvider(["topic-a"], ["topic-a"]);
+    await orchestrate(makeTurn(1, "apple"), {
+      sectionIndex: lanes.sectionIndex,
+      needle: lanes.needle,
+      denseConfig: config,
+      edgeGraph: lanes.edgeGraph,
+      workingSet,
+    });
+
+    // Turn 2 selects a DIFFERENT page and never re-selects topic-a.
+    denseHits = [{ article: "topic-b", section: 0 }];
+    providerStub = selectProvider(["topic-b"]);
+    const t2 = await orchestrate(makeTurn(2, "cherry"), {
+      sectionIndex: lanes.sectionIndex,
+      needle: lanes.needle,
+      denseConfig: config,
+      edgeGraph: lanes.edgeGraph,
+      workingSet,
+    });
+
+    expect(t2.currentSelections.map((s) => s.slug)).not.toContain("topic-a");
+    expect(t2.finalInjection).toContain("topic-a");
+  });
+
+  test("carry-forward survives a turn whose selections fill the cap", async () => {
+    const lanes = await buildLanes();
+    // Cap of 1: under a naive record-then-cap order this turn's own selection
+    // would evict the carried page before injection. Snapshotting the carry
+    // BEFORE recording this turn keeps the earlier page in the injection.
+    const workingSet = new WorkingSet(1);
+
+    providerStub = selectProvider(["topic-a"]); // turn 1 → topic-a
+    await orchestrate(makeTurn(1, "apple"), {
+      sectionIndex: lanes.sectionIndex,
+      needle: lanes.needle,
+      denseConfig: config,
+      edgeGraph: lanes.edgeGraph,
+      workingSet,
+    });
+
+    denseHits = [{ article: "topic-b", section: 0 }];
+    providerStub = selectProvider(["topic-b"]); // turn 2 → topic-b
+    const t2 = await orchestrate(makeTurn(2, "cherry"), {
+      sectionIndex: lanes.sectionIndex,
+      needle: lanes.needle,
+      denseConfig: config,
+      edgeGraph: lanes.edgeGraph,
+      workingSet,
+    });
+
+    expect(t2.currentSelections.map((s) => s.slug)).toEqual(["topic-b"]);
+    expect(t2.finalInjection).toContain("topic-a"); // carried despite the cap
+  });
+
+  test("a stale non-pinned page ages out of the carry-forward window", async () => {
+    const lanes = await buildLanes();
+    // window 2: a non-pinned entry unseen for >2 turns evicts.
+    const workingSet = new WorkingSet(150, 2);
+
+    providerStub = selectProvider(["topic-a"]); // turn 1 selects topic-a
+    const t1 = await orchestrate(makeTurn(1, "apple"), {
+      sectionIndex: lanes.sectionIndex,
+      needle: lanes.needle,
+      denseConfig: config,
+      edgeGraph: lanes.edgeGraph,
+      workingSet,
+    });
+    expect(t1.finalInjection).toContain("topic-a");
+
+    // Turns 2–4 never re-select topic-a. By turn 4 (4-1=3 > 2) it ages out.
+    providerStub = selectProvider([]);
+    await orchestrate(makeTurn(2, "x"), {
+      sectionIndex: lanes.sectionIndex,
+      needle: lanes.needle,
+      denseConfig: config,
+      edgeGraph: lanes.edgeGraph,
+      workingSet,
+    });
+    await orchestrate(makeTurn(3, "x"), {
+      sectionIndex: lanes.sectionIndex,
+      needle: lanes.needle,
+      denseConfig: config,
+      edgeGraph: lanes.edgeGraph,
+      workingSet,
+    });
+    const t4 = await orchestrate(makeTurn(4, "x"), {
+      sectionIndex: lanes.sectionIndex,
+      needle: lanes.needle,
+      denseConfig: config,
+      edgeGraph: lanes.edgeGraph,
+      workingSet,
+    });
+    expect(t4.finalInjection).not.toContain("topic-a");
+  });
+
+  test("pinned current-turn selections land in the working set", async () => {
+    const lanes = await buildLanes();
+    const ws = new WorkingSet();
+    providerStub = selectProvider(["topic-a"], ["topic-a"]);
+    await orchestrate(makeTurn(1, "apple"), {
+      sectionIndex: lanes.sectionIndex,
+      needle: lanes.needle,
+      denseConfig: config,
+      edgeGraph: lanes.edgeGraph,
+      workingSet: ws,
+    });
+    expect(ws.union().has("topic-a")).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Degradation: an empty pool and a provider-unavailable path are recall-safe.
+// ---------------------------------------------------------------------------
+
+describe("orchestrate — degradation", () => {
+  test("an empty pool yields no selections and an empty injection", async () => {
+    const lanes = await buildLanes();
+    providerStub = selectProvider([]);
+    const result = await orchestrate(makeTurn(1, "zzzzz no-match"), {
+      sectionIndex: lanes.sectionIndex,
+      needle: { query: () => [], bestSection: () => -1 },
+      denseConfig: config,
+      edgeGraph: lanes.edgeGraph,
+      workingSet: new WorkingSet(),
+    });
+    expect(result.currentSelections).toEqual([]);
+    expect(result.finalInjection).toEqual([]);
+  });
+
+  test("omitted ids keeps ALL pooled candidates (recall-safe)", async () => {
+    const lanes = await buildLanes();
+    denseHits = [{ article: "topic-b", section: 0 }];
+    providerStub = {
+      name: "stub",
+      sendMessage: async () => toolUseResponse({}), // omitted ids → keep all
+    };
+    const result = await orchestrate(makeTurn(1, "apple"), {
+      sectionIndex: lanes.sectionIndex,
+      needle: lanes.needle,
+      denseConfig: config,
+      edgeGraph: lanes.edgeGraph,
+      workingSet: new WorkingSet(),
+    });
+    expect(new Set(result.finalInjection)).toEqual(
+      new Set(["topic-a", "topic-b", "topic-d"]),
+    );
+  });
+});