@vellumai/assistant 0.8.12 → 0.9.0-staging.1

package/src/plugins/defaults/memory-v3-shadow/__tests__/section-dense-store.test.ts

@@ -45,6 +45,12 @@ type ScrollPage = {
   next_page_offset: string | number | null;
 };
 
+// A getCollection() response for an existing collection whose single dense
+// vector matches the configured dimension (CONFIG.vectorSize === 4).
+const MATCHING_SECTION_SCHEMA = {
+  config: { params: { vectors: { size: 4, distance: "Cosine" } } },
+};
+
 const state = {
   collectionExists: false,
   collectionExistsCalls: 0,
@@ -54,6 +60,10 @@ const state = {
   upsertCalls: [] as Array<{ wait: boolean; points: MockPoint[] }>,
   deleteCalls: [] as Array<{ wait: boolean; filter: unknown }>,
   createCollectionThrows: null as Error | null,
+  getCollectionCalls: 0,
+  getCollectionInfo: MATCHING_SECTION_SCHEMA as unknown,
+  getCollectionThrows: null as Error | null,
+  deleteCollectionCalls: [] as string[],
   // Programmed `scroll` pages, consumed in order; each `scroll` call shifts one.
   scrollPages: [] as ScrollPage[],
   scrollCalls: [] as Array<{ limit: number; offset: unknown }>,
@@ -72,6 +82,16 @@ class MockQdrantClient {
     state.collectionExists = true;
     return {};
   }
+  async getCollection(_name: string) {
+    state.getCollectionCalls++;
+    if (state.getCollectionThrows) throw state.getCollectionThrows;
+    return state.getCollectionInfo;
+  }
+  async deleteCollection(name: string) {
+    state.deleteCollectionCalls.push(name);
+    state.collectionExists = false;
+    return {};
+  }
   async createPayloadIndex(
     _name: string,
     params: { field_name: string; field_schema: string },
@@ -131,6 +151,10 @@ function resetState(): void {
   state.upsertCalls.length = 0;
   state.deleteCalls.length = 0;
   state.createCollectionThrows = null;
+  state.getCollectionCalls = 0;
+  state.getCollectionInfo = MATCHING_SECTION_SCHEMA;
+  state.getCollectionThrows = null;
+  state.deleteCollectionCalls.length = 0;
   state.scrollPages.length = 0;
   state.scrollCalls.length = 0;
   embedState.calls.length = 0;
@@ -197,6 +221,49 @@ describe("memory v3 section-dense-store — collection lifecycle", () => {
     ]);
   });
 
+  test("recreates the collection when its dense vector dimension drifts", async () => {
+    state.collectionExists = true;
+    // Existing collection sized to a different embedding dimension than the
+    // configured 4 (e.g. a 384-dim collection from a prior model). Every upsert
+    // would fail with HTTP 400 until it is recreated; the next backfill
+    // re-embeds the sections.
+    state.getCollectionInfo = {
+      config: { params: { vectors: { size: 384, distance: "Cosine" } } },
+    };
+
+    await ensureSectionCollection(CONFIG);
+
+    expect(state.getCollectionCalls).toBe(1);
+    expect(state.deleteCollectionCalls).toEqual([SECTION_COLLECTION]);
+    expect(state.createCollectionCalls).toBe(1);
+    // The recreated collection is sized to the configured dimension.
+    const params = state.createCollectionParams as {
+      vectors: { size: number };
+    };
+    expect(params.vectors.size).toBe(4);
+  });
+
+  test("leaves a dimension-matched existing collection untouched", async () => {
+    state.collectionExists = true;
+    // Default getCollectionInfo (MATCHING_SECTION_SCHEMA) is size 4 === CONFIG.
+
+    await ensureSectionCollection(CONFIG);
+
+    expect(state.getCollectionCalls).toBe(1);
+    expect(state.deleteCollectionCalls).toEqual([]);
+    expect(state.createCollectionCalls).toBe(0);
+  });
+
+  test("treats a getCollection probe failure as compatible (no destructive recreate)", async () => {
+    state.collectionExists = true;
+    state.getCollectionThrows = new Error("transient REST error");
+
+    await ensureSectionCollection(CONFIG);
+
+    expect(state.deleteCollectionCalls).toEqual([]);
+    expect(state.createCollectionCalls).toBe(0);
+  });
+
   test("re-running ensure latches readiness (single existence probe)", async () => {
     state.collectionExists = false;
 

package/src/plugins/defaults/memory-v3-shadow/__tests__/selection-log-store.test.ts

@@ -1,18 +1,20 @@
 /**
- * Tests for `assistant/src/memory/v3/selection-log-store.ts`.
+ * Tests for `selection-log-store.ts`.
  *
  * Asserts the inspector read path over `memory_v3_selections`:
- *   - the selection for the exact turn;
- *   - null for a null turn, and null for a turn with no v3 rows;
- *   - NO fallback to another turn (would misattribute a future turn's
- *     selection to the inspected message);
- *   - source/pinned mapping and the rendered `<memory>` block;
+ *   - the selection for the exact turn (turn-keyed variant);
+ *   - the selection keyed by the turn's message ids (the route's path), which
+ *     is robust against v2/v3 turn-counter drift and does not match rows that
+ *     predate the message-id backfill;
+ *   - null for a null turn, empty message ids, or no matching rows;
+ *   - NO fallback to another turn/message;
+ *   - source/pinned/section mapping and the rendered `<memory>` block;
  *   - `live` / `shadow` reflect the flag resolver.
  *
  * `mock.module` is process-global and leaks into sibling files in a
- * `bun test src/memory/v3/` run, so every stub DELEGATES to the real
- * implementation unless this test is actively running (`storeMockActive`,
- * toggled in beforeEach/afterAll). Mirrors `shadow-plugin.test.ts`.
+ * `bun test <dir>` run, so every stub DELEGATES to the real implementation
+ * unless this test is actively running (`storeMockActive`, toggled in
+ * beforeEach/afterAll). Mirrors `shadow-plugin.test.ts`.
  */
 
 import { Database } from "bun:sqlite";
@@ -21,6 +23,7 @@ import { afterAll, beforeEach, describe, expect, mock, test } from "bun:test";
 import { drizzle } from "drizzle-orm/bun-sqlite";
 
 import { migrateAddMemoryV3Selections } from "../../../../memory/migrations/268-add-memory-v3-selections.js";
+import { migrateMemoryV3SelectionsMessageIdAndSections } from "../../../../memory/migrations/283-memory-v3-selections-message-id-and-sections.js";
 import * as schema from "../../../../memory/schema.js";
 
 const realFlags = {
@@ -41,16 +44,27 @@ function makeDb() {
   testSqlite.exec("PRAGMA journal_mode=WAL");
   const db = drizzle(testSqlite, { schema });
   migrateAddMemoryV3Selections(db);
+  migrateMemoryV3SelectionsMessageIdAndSections(db);
   return db;
 }
 
 function seed(
   conversationId: string,
   turn: number,
-  rows: Array<{ slug: string; source: string; pinned?: boolean }>,
+  rows: Array<{
+    slug: string;
+    source: string;
+    pinned?: boolean;
+    sectionOrdinal?: number;
+    sectionTitle?: string;
+  }>,
+  messageId: string | null = null,
 ): void {
   const stmt = testSqlite.query(
-    `INSERT INTO memory_v3_selections (conversation_id, turn, slug, source, pinned, created_at) VALUES (?, ?, ?, ?, ?, ?)`,
+    `INSERT INTO memory_v3_selections
+       (conversation_id, turn, slug, source, pinned, created_at,
+        message_id, section_ordinal, section_title)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
   );
   for (const r of rows) {
     stmt.run(
@@ -60,6 +74,9 @@ function seed(
       r.source,
       r.pinned ? 1 : 0,
       1000 + turn,
+      messageId,
+      r.sectionOrdinal ?? null,
+      r.sectionTitle ?? null,
     );
   }
 }
@@ -97,17 +114,23 @@ mock.module("../../../../memory/db-connection.js", () => ({
 
 mock.module("../page-content.js", () => ({
   ...realPageContent,
-  // The inspector store renders via `renderV3SectionContent` with an empty
-  // section map (sections are unavailable post-orchestration), so it falls back
-  // to the full page. The mock stands in for that full-page render.
-  renderV3SectionContent: async (slug: string) =>
+  // The inspector store reconstructs each selection's matched section from the
+  // current page; in this unit the test pages don't exist on disk, so the
+  // section map is empty and the renderer falls back to the full page. The mock
+  // stands in for that render and reflects whether a section was supplied.
+  renderV3SectionContent: async (slug: string, section?: { title: string }) =>
     storeMockActive
-      ? `body for ${slug}`
+      ? section
+        ? `section[${section.title}] for ${slug}`
+        : `body for ${slug}`
       : realPageContent.renderV3SectionContent(slug, undefined),
 }));
 
-const { getMemoryV3SelectionForInspector, summarizeSelections } =
-  await import("../selection-log-store.js");
+const {
+  getMemoryV3SelectionForInspector,
+  getMemoryV3SelectionForInspectorByMessageIds,
+  summarizeSelections,
+} = await import("../selection-log-store.js");
 
 beforeEach(() => {
   storeMockActive = true;
@@ -150,9 +173,11 @@ describe("getMemoryV3SelectionForInspector", () => {
     expect(await getMemoryV3SelectionForInspector("conv-3", 3)).toBeNull();
   });
 
-  test("maps source/pinned and renders the <memory> block", async () => {
+  test("maps source/pinned/section and renders the <memory> block", async () => {
     // The second row carries a retired free-text source label (the column is
-    // permissive); the inspector passes it through verbatim.
+    // permissive); the inspector passes it through verbatim. Neither row has a
+    // matched section, so section fields are null and the block falls back to
+    // full pages.
     seed("conv-4", 1, [
       { slug: "domain-a/page-1", source: "edge", pinned: true },
       { slug: "domain-b/page-2", source: "legacy-carry", pinned: false },
@@ -160,8 +185,20 @@ describe("getMemoryV3SelectionForInspector", () => {
 
     const log = await getMemoryV3SelectionForInspector("conv-4", 1);
     expect(log?.selections).toEqual([
-      { slug: "domain-a/page-1", source: "edge", pinned: true },
-      { slug: "domain-b/page-2", source: "legacy-carry", pinned: false },
+      {
+        slug: "domain-a/page-1",
+        source: "edge",
+        pinned: true,
+        sectionOrdinal: null,
+        sectionHeading: null,
+      },
+      {
+        slug: "domain-b/page-2",
+        source: "legacy-carry",
+        pinned: false,
+        sectionOrdinal: null,
+        sectionHeading: null,
+      },
     ]);
     expect(log?.injectedText).toContain("<memory>");
     expect(log?.injectedText).toContain("body for domain-a/page-1");
@@ -183,6 +220,69 @@ describe("getMemoryV3SelectionForInspector", () => {
   });
 });
 
+describe("getMemoryV3SelectionForInspectorByMessageIds", () => {
+  test("returns the turn's selection (with section fields) keyed by message id", async () => {
+    seed(
+      "conv-m",
+      0,
+      [
+        {
+          slug: "domain-a/page-1",
+          source: "needle",
+          sectionOrdinal: 2,
+          sectionTitle: "Heading A",
+        },
+        { slug: "domain-b/page-2", source: "core" },
+      ],
+      "msg-assistant-1",
+    );
+    // A different turn under a different message must not bleed in.
+    seed(
+      "conv-m",
+      1,
+      [{ slug: "domain-c/page-9", source: "dense" }],
+      "msg-assistant-2",
+    );
+
+    const log = await getMemoryV3SelectionForInspectorByMessageIds([
+      "msg-assistant-1",
+    ]);
+    expect(log?.turn).toBe(0);
+    expect(log?.selections).toEqual([
+      {
+        slug: "domain-a/page-1",
+        source: "needle",
+        pinned: false,
+        sectionOrdinal: 2,
+        sectionHeading: "Heading A",
+      },
+      {
+        slug: "domain-b/page-2",
+        source: "core",
+        pinned: false,
+        sectionOrdinal: null,
+        sectionHeading: null,
+      },
+    ]);
+    expect(log?.injectedText).toContain("<memory>");
+  });
+
+  test("returns null for empty message ids and for an unmatched id", async () => {
+    seed("conv-m", 0, [{ slug: "domain-a/page-1", source: "needle" }], "msg-1");
+    expect(await getMemoryV3SelectionForInspectorByMessageIds([])).toBeNull();
+    expect(
+      await getMemoryV3SelectionForInspectorByMessageIds(["nope"]),
+    ).toBeNull();
+  });
+
+  test("does not match rows that predate the message-id backfill (null message_id)", async () => {
+    seed("conv-m", 0, [{ slug: "domain-a/page-1", source: "needle" }]); // message_id null
+    expect(
+      await getMemoryV3SelectionForInspectorByMessageIds(["any"]),
+    ).toBeNull();
+  });
+});
+
 describe("summarizeSelections", () => {
   test("aggregates per-source counts, turn count, and distinct slugs", () => {
     // Turn 1: a needle + an edge selection.

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

@@ -34,6 +34,7 @@ import { afterAll, beforeEach, describe, expect, mock, test } from "bun:test";
 import { drizzle } from "drizzle-orm/bun-sqlite";
 
 import { migrateAddMemoryV3Selections } from "../../../../memory/migrations/268-add-memory-v3-selections.js";
+import { migrateMemoryV3SelectionsMessageIdAndSections } from "../../../../memory/migrations/283-memory-v3-selections-message-id-and-sections.js";
 import * as schema from "../../../../memory/schema.js";
 import type { PageIndexEntry } from "../../../../memory/v2/page-index.js";
 import type {
@@ -105,6 +106,7 @@ function makeDb() {
   testSqlite.exec("PRAGMA journal_mode=WAL");
   const db = drizzle(testSqlite, { schema });
   migrateAddMemoryV3Selections(db);
+  migrateMemoryV3SelectionsMessageIdAndSections(db);
   return db;
 }
 mock.module("../../../../memory/db-connection.js", () => ({

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

@@ -29,6 +29,7 @@ import { drizzle } from "drizzle-orm/bun-sqlite";
 
 import { migrateAddMemoryV3Selections } from "../../../../memory/migrations/268-add-memory-v3-selections.js";
 import { migrateAddMemoryV3EverInjected } from "../../../../memory/migrations/277-add-memory-v3-ever-injected.js";
+import { migrateMemoryV3SelectionsMessageIdAndSections } from "../../../../memory/migrations/283-memory-v3-selections-message-id-and-sections.js";
 import * as schema from "../../../../memory/schema.js";
 import type { HotSetEntry, HotSetOptions } from "../hot-set.js";
 import type { OrchestrateResult } from "../orchestrate.js";
@@ -154,6 +155,7 @@ function makeDb() {
   testSqlite.exec("PRAGMA journal_mode=WAL");
   const db = drizzle(testSqlite, { schema });
   migrateAddMemoryV3Selections(db);
+  migrateMemoryV3SelectionsMessageIdAndSections(db);
   // The live injector's net-new dedup reads/writes the everInjected store.
   migrateAddMemoryV3EverInjected(db);
   return db;
@@ -386,6 +388,7 @@ const {
 } = await import("../shadow-plugin.js");
 const { memoryV3Injector, resetMemoryV3InjectorStateForTests } =
   await import("../injector.js");
+const { MemoryV3RetrievalUnavailableError } = await import("../pool-select.js");
 
 afterAll(() => {
   shadowMockActive = false;
@@ -545,7 +548,15 @@ describe("memory-v3 shadow plugin", () => {
         finder: [{ slug: "page-core", descriptor: "", lane: "needle" }],
       },
     });
-    expect(rows).toEqual([{ slug: "page-core", source: "core", pinned: 0 }]);
+    expect(rows).toEqual([
+      {
+        slug: "page-core",
+        source: "core",
+        pinned: 0,
+        sectionOrdinal: null,
+        sectionTitle: null,
+      },
+    ]);
   });
 
   test("the turn passed to orchestrate carries the latest user message", async () => {
@@ -795,3 +806,54 @@ describe("memory-v3 shadow plugin", () => {
     });
   });
 });
+
+describe("memory-v3 infrastructure-failure handling (hard-fail vs swallow)", () => {
+  const throwInfra = () =>
+    orchestrateSpy.mockImplementationOnce(async () => {
+      throw new MemoryV3RetrievalUnavailableError(
+        "selector provider unavailable",
+      );
+    });
+
+  test("LIVE injector HARD-FAILS the turn on an infra failure (no silent memory loss)", async () => {
+    liveEnabled = true;
+    shadowEnabled = false;
+    throwInfra();
+
+    await expect(produce("conv-infra-live", 0)).rejects.toThrow(
+      MemoryV3RetrievalUnavailableError,
+    );
+  });
+
+  test("SHADOW injector swallows an infra failure (v2 fallback) — no throw, no block", async () => {
+    liveEnabled = false;
+    shadowEnabled = true;
+    throwInfra();
+
+    // Shadow mode: v2 retrieval still ran this turn, so the v3 injector returns
+    // null rather than failing the turn.
+    expect(await produce("conv-infra-shadow", 0)).toBeNull();
+  });
+
+  test("runShadowObservation never throws on an infra failure (fire-and-forget)", async () => {
+    liveEnabled = false;
+    shadowEnabled = true;
+    throwInfra();
+
+    await expect(
+      runShadowObservation("conv-infra-obs", 0),
+    ).resolves.toBeUndefined();
+  });
+
+  test("LIVE injector stays NON-fatal on a non-infra error (degrades to no v3 block)", async () => {
+    liveEnabled = true;
+    shadowEnabled = false;
+    orchestrateSpy.mockImplementationOnce(async () => {
+      throw new Error("some unexpected non-infra bug");
+    });
+
+    // Only INFRA failures hard-fail; any other error stays non-fatal so a bug
+    // in one lane can't take every turn down.
+    expect(await produce("conv-nonfatal-live", 0)).toBeNull();
+  });
+});

package/src/plugins/defaults/memory-v3-shadow/injector.ts

@@ -24,17 +24,22 @@
  *    all-repeat turn returns an EMPTY-TEXT block: assembly attaches nothing,
  *    but the block's presence still keys v2 suppression (v3 ran and owns the
  *    `<memory>` layer this turn). A `null` return (failure / empty selection /
- *    every net-new card rendered empty) leaves v2's block intact — fallback to
- *    v2 rather than a memory-less turn.
+ *    every net-new card rendered empty) attaches no v3 block: in shadow mode
+ *    (`memory-v3-live` off) v2 still ran this turn, so its block stays as the
+ *    fallback; under `memory-v3-live` the user-prompt-submit hook skips v2
+ *    retrieval entirely, so a null return leaves the turn with no NEW injected
+ *    memory (prior turns' frozen cards still ride history).
  *
  *  - {@link memoryV3SpotlightInjector} (id `memory-v3-spotlight`,
- *    `append-user-tail`): the EPHEMERAL layer. Renders the top `spotlight.n`
+ *    `after-memory-prefix`): the EPHEMERAL layer. Renders the top `spotlight.n`
  *    selected finder hits' matched sections, plus the previous
  *    `spotlight.windowTurns` turns' entries from an in-memory per-conversation
  *    ring (a daemon restart simply re-warms it), as a `<memory_spotlight>`
- *    block at the current-message tail. Assembly strip-and-replaces this block
- *    every turn (scoped to this block id only); it is never persisted to
- *    metadata.
+ *    block spliced immediately after the `<memory>` cards block (so the two
+ *    memory layers sit adjacent in the prefix, ahead of the user's message
+ *    text). Assembly strip-and-replaces this block every turn (scoped to this
+ *    block id only); it is never persisted to metadata, so the frozen card
+ *    prefix it follows stays byte-stable and cached regardless.
  *
  * Flag gating is unchanged: `memory-v3-live` attaches blocks; `memory-v3-shadow`
  * (live off) logs what WOULD inject (net-new slugs + bytes + spotlight refs)
@@ -73,6 +78,7 @@ import { cardBytes } from "./card.js";
 import { getActiveSlugs, recordInjected } from "./ever-injected-store.js";
 import type { OrchestrateResult } from "./orchestrate.js";
 import { renderV3CardContent } from "./page-content.js";
+import { MemoryV3RetrievalUnavailableError } from "./pool-select.js";
 import { schedulePruneValve } from "./prune.js";
 import {
   renderCardsBlockInner,
@@ -238,11 +244,32 @@ export const memoryV3Injector: Injector = {
     if (!live && !shadow) return null;
     if (!isPersonalMemoryAllowed(ctx.trust)) return null;
 
-    const result = await observeTurnOnce(ctx.conversationId, ctx.turnIndex);
-    // Empty selection falls back to v2 (return null): v2 suppression keys off
-    // BOTH the flag AND a produced block, so a selector failure or a turn with
-    // nothing selected ships v2 memory rather than no memory.
-    if (!result || result.selections.length === 0) return null;
+    let observed: OrchestrateResult | null;
+    try {
+      observed = await observeTurnOnce(ctx.conversationId, ctx.turnIndex);
+    } catch (err) {
+      // A memory-v3 INFRASTRUCTURE failure (the selector lost its provider —
+      // e.g. a transient CES credential blip). Under `memory-v3-live` the
+      // user-prompt-submit hook already skipped v2 retrieval, so swallowing
+      // here would ship the turn with NO memory at all — exactly the silent
+      // degradation we want to eliminate. Hard-fail the turn instead (a clean,
+      // retryable error). In shadow mode v2 still ran this turn, so fall back
+      // to it (return null). Non-infra errors are already swallowed inside
+      // observeTurn; anything else reaching here stays non-fatal.
+      if (live && err instanceof MemoryV3RetrievalUnavailableError) {
+        throw err;
+      }
+      return null;
+    }
+    // Empty selection → return null (attach nothing). Returning null (vs an
+    // empty block) preserves the shadow-mode v2 fallback: v2 suppression keys
+    // off BOTH the flag AND a produced block, so in shadow a turn with nothing
+    // selected ships v2's memory. Under `memory-v3-live` the hook skipped v2
+    // retrieval, so the turn simply gets no injected memory.
+    if (!observed || observed.selections.length === 0) return null;
+    // `const` so the non-null narrowing survives capture in the `commit`
+    // closure below (a `let` would re-widen to `OrchestrateResult | null`).
+    const result = observed;
 
     try {
       const active = getActiveSlugs(ctx.conversationId);
@@ -258,11 +285,13 @@ export const memoryV3Injector: Injector = {
         const card = await renderV3CardContent(slug);
         if (card.trim().length > 0) cards.push({ slug, card });
       }
-      // Every net-new card rendered empty: return null (fall back to v2)
-      // rather than an empty-text block — suppressing v2 with nothing to show
-      // would ship a memory-less turn. Distinct from the all-repeat case
-      // (empty `netNew`), where the empty block correctly keeps v2 suppressed
-      // because the cards already ride history.
+      // Every net-new card rendered empty: return null rather than an
+      // empty-text block. Returning null preserves the shadow-mode v2 fallback
+      // (an empty block would key v2 suppression yet show nothing); under
+      // `memory-v3-live` there is no v2 block, so the turn simply gets no new
+      // memory. Distinct from the all-repeat case (empty `netNew`), where the
+      // empty block correctly keeps v2 suppressed because the cards already
+      // ride history.
       if (netNew.length > 0 && cards.length === 0) return null;
       const entries = cards.map(({ slug, card }) => ({
         slug,
@@ -332,7 +361,7 @@ export const memoryV3Injector: Injector = {
           err: err instanceof Error ? err.message : String(err),
           conversationId: ctx.conversationId,
         },
-        "memory-v3 live render failed (non-fatal) — falling back to v2",
+        "memory-v3 live render failed (non-fatal) — returning null (no v3 block this turn)",
       );
       return null;
     }
@@ -369,9 +398,23 @@ export const memoryV3SpotlightInjector: Injector = {
       return {
         id: MEMORY_V3_SPOTLIGHT_BLOCK_ID,
         text: wrapMemorySpotlightBlock(renderSpotlightInner(window)),
-        placement: "append-user-tail",
+        // Splices right after the `<memory>` cards block (this injector's
+        // order 1001 runs after the cards' 1000, and `countMemoryPrefixBlocks`
+        // counts the cards `<memory>` block but not `<memory_spotlight>`, so the
+        // spotlight lands immediately after the cards rather than at the user
+        // tail). Cache-neutral: the block is strip-and-replaced from prior
+        // messages by block id every turn regardless of placement, so the
+        // frozen card prefix stays byte-stable and cached.
+        placement: "after-memory-prefix",
       };
     } catch (err) {
+      // Live-only injector: an infra failure must hard-fail the turn. The cards
+      // injector (ordered ahead of this one) normally throws first, so this
+      // path is defensive — it keeps the behavior correct if the cards injector
+      // is ever disabled or reordered.
+      if (err instanceof MemoryV3RetrievalUnavailableError) {
+        throw err;
+      }
       log.warn(
         {
           err: err instanceof Error ? err.message : String(err),

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

@@ -383,7 +383,7 @@ export async function orchestrate(
  * when the article or ordinal is not in the index (e.g. the dense store is
  * ahead of the in-memory rebuild).
  */
-function sectionByOrdinal(
+export function sectionByOrdinal(
   index: SectionIndex,
   article: Slug,
   ordinal: number,

package/src/plugins/defaults/memory-v3-shadow/pool-select.ts

@@ -30,15 +30,22 @@
  * stable-prefix card and as a finder line (its current matched section);
  * selections are deduped by slug.
  *
- * Failure handling is recall-safe by construction:
+ * Failure handling distinguishes a DELIBERATE empty selection from an
+ * INFRASTRUCTURE failure — the two are different outcomes, not the same one:
  *   - explicit `ids` → select exactly those candidates,
- *   - explicit empty `ids: []` → select none (deliberate abstention),
+ *   - explicit empty `ids: []` → select none (deliberate abstention) — a
+ *     normal, non-error result; the turn proceeds,
  *   - omitted `ids` → keep ALL candidates (the recall-safe "all of these are
  *     relevant" signal),
- *   - infrastructure failure (provider unavailable, a throw that survived the
- *     provider's own retries, no usable `tool_use`, or a schema mismatch) →
- *     select nothing after a short re-prompt retry, degrading to the
- *     deterministic recall lanes the orchestrator unions in regardless.
+ *   - empty candidate pool → return none (nothing to select),
+ *   - infrastructure failure (selector provider unavailable — e.g. a transient
+ *     CES credential blip drops the API key — or no usable `tool_use` / schema
+ *     mismatch surviving the short re-prompt retry) → throw
+ *     {@link MemoryV3RetrievalUnavailableError}. There is NO deterministic-lane
+ *     fallback: the LIVE injector propagates this to hard-fail the turn
+ *     (retryable) rather than silently shipping it with no `<memory>` block,
+ *     while the shadow/observation path swallows it and lets v2 retrieval serve
+ *     the turn.
  */
 
 import { z } from "zod";
@@ -60,6 +67,24 @@ import type { MemoryRoutingTurn, SelectedPage, Slug } from "./types.js";
 
 const log = getLogger("memory-v3-pool-select");
 
+/**
+ * Thrown when the pool selector cannot produce a selection because of an
+ * INFRASTRUCTURE failure — its LLM provider is unavailable (e.g. a transient
+ * CES credential blip drops the API key), or no usable `tool_use` survives the
+ * re-prompt retry. Deliberately DISTINCT from a deliberate empty selection
+ * (`ids: []`) and an empty candidate pool, both of which return normally.
+ *
+ * The LIVE memory-v3 injector propagates this to hard-fail the turn (a clean,
+ * retryable failure) rather than silently shipping with no memory; the
+ * shadow/observation path catches and swallows it.
+ */
+export class MemoryV3RetrievalUnavailableError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "MemoryV3RetrievalUnavailableError";
+  }
+}
+
 /** A dynamic-tail (finder) candidate: the slug plus the descriptor that
  *  justifies it — a matched section for a needle/dense hit, or a curated link
  *  description for an edge page. Rendered as a one-line snippet, prefixed
@@ -213,9 +238,11 @@ export async function selectPool(
   if (!provider) {
     log.warn(
       { candidateCount: ordered.length },
-      "pool selector provider unavailable; degrading to deterministic lanes",
+      "pool selector provider unavailable — failing the turn rather than dropping memory",
+    );
+    throw new MemoryV3RetrievalUnavailableError(
+      "memory-v3 pool selector provider unavailable",
     );
-    return [];
   }
 
   // Two content blocks: the stable prefix (cards) carries the cache
@@ -265,9 +292,11 @@ export async function selectPool(
   if (parsed === null) {
     log.warn(
       { candidateCount: ordered.length },
-      "pool selector could not obtain a selection after retries; degrading to deterministic lanes",
+      "pool selector could not obtain a selection after retries — failing the turn rather than dropping memory",
+    );
+    throw new MemoryV3RetrievalUnavailableError(
+      "memory-v3 pool selector returned no usable selection after retries",
     );
-    return [];
   }
 
   // Omitted `ids` is the recall-safe "keep all candidates" signal.