@vellumai/assistant 0.8.12 → 0.9.0-staging.2

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.

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

@@ -86,7 +86,40 @@ export async function ensureSectionCollection(
   const onDisk = config.memory.qdrant.onDisk;
 
   const exists = await client.collectionExists(SECTION_COLLECTION);
-  if (!exists.exists) {
+  let needsCreate = !exists.exists;
+
+  // An existing collection sized to a different embedding dimension (e.g. a
+  // 384-dim collection now serving a 3072-dim embedder) carries the right
+  // vector at the wrong size — every upsert then fails with HTTP 400 and the
+  // collection is never repaired. Probe the schema and recreate on dimension
+  // drift; on a probe failure, assume compatible rather than risk a destructive
+  // recreate (mirrors the v2 concept-page collection posture). The next
+  // `backfillAllSections` regenerates the embeddings.
+  if (exists.exists) {
+    try {
+      const info = await client.getCollection(SECTION_COLLECTION);
+      const vectors = info.config?.params?.vectors;
+      const size =
+        vectors && typeof vectors === "object" && "size" in vectors
+          ? (vectors as { size?: unknown }).size
+          : undefined;
+      if (typeof size === "number" && size !== vectorSize) {
+        log.warn(
+          { collection: SECTION_COLLECTION, expected: vectorSize, found: size },
+          "Memory v3 section collection dimension drift — deleting and recreating; embeddings will be regenerated by the next backfill",
+        );
+        await client.deleteCollection(SECTION_COLLECTION);
+        needsCreate = true;
+      }
+    } catch (err) {
+      log.warn(
+        { err, collection: SECTION_COLLECTION },
+        "Failed to probe v3 section collection schema; assuming compatible",
+      );
+    }
+  }
+
+  if (needsCreate) {
     log.info(
       { collection: SECTION_COLLECTION, vectorSize },
       "Creating Qdrant collection for memory v3 sections",

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

@@ -1,25 +1,32 @@
 /**
- * Read-side store for the inspector's Memory V3 section. Reads the persisted
- * `memory_v3_selections` rows for a turn and re-renders an APPROXIMATE
- * `<memory>` block for what v3 selected, so the inspector can show the turn's
- * selection without re-running orchestration — which would be wrong anyway,
- * since the hot lane is frecency-stateful and can't be reproduced after the
- * fact.
+ * Read-side store for the inspector's Memory V3 panel. Reads the persisted
+ * `memory_v3_selections` rows for a turn (by the turn's message ids) and
+ * re-renders the `<memory>` block for what v3 selected, so the inspector can
+ * show the turn's selection without re-running orchestration — which would be
+ * wrong anyway, since the hot lane is frecency-stateful and can't be reproduced
+ * after the fact.
  *
- * The rendered text is inspector-only and NOT byte-identical to live
- * injection: the live injector freezes net-new compact CARDS into history
- * (`renderV3CardContent`) plus an ephemeral spotlight, while this store
- * re-renders the whole selection set as full/lead pages
- * (`renderV3SectionContent` with no persisted section identity — see the
- * inline note at `injectedText`).
+ * The rendered text is inspector-only and NOT byte-identical to live injection:
+ * the live injector freezes net-new compact CARDS into history
+ * (`renderV3CardContent`) plus an ephemeral spotlight. Here we re-render each
+ * selection's MATCHED SECTION — resolved from the persisted `(slug, ordinal)`
+ * against the current page — when one was recorded, falling back to the
+ * full/lead page otherwise. Section text is re-derived from the current page,
+ * so it reflects bounded page-drift if the page changed since the turn (the
+ * same approximation the v2 inspector accepts).
  */
 
 import type { MemoryV3SelectionLog } from "../../../api/responses/memory-v3-selection-log.js";
 import { isAssistantFeatureFlagEnabled } from "../../../config/assistant-feature-flags.js";
 import { getConfig } from "../../../config/loader.js";
 import { getDb, getSqliteFrom } from "../../../memory/db-connection.js";
+import { readPage } from "../../../memory/v2/page-store.js";
+import { getWorkspaceDir } from "../../../util/platform.js";
+import { capabilityOrDiskBody } from "./capabilities.js";
+import { sectionByOrdinal } from "./orchestrate.js";
 import { renderV3SectionContent } from "./page-content.js";
 import { renderMemoryBlock } from "./render-injection.js";
+import { buildSectionIndex } from "./sections.js";
 import {
   type Section,
   SELECTION_SOURCES,
@@ -31,16 +38,21 @@ const MEMORY_V3_SHADOW = "memory-v3-shadow" as const;
 const MEMORY_V3_LIVE = "memory-v3-live" as const;
 
 interface SelectionRow {
+  turn: number;
   slug: string;
   source: string;
   pinned: number;
+  section_ordinal: number | null;
+  section_title: string | null;
 }
 
+const SELECTION_COLUMNS = `turn, slug, source, pinned, section_ordinal, section_title`;
+
 function rowsForTurn(conversationId: string, turn: number): SelectionRow[] {
   return getSqliteFrom(getDb())
     .query(
       /*sql*/ `
-      SELECT slug, source, pinned FROM memory_v3_selections
+      SELECT ${SELECTION_COLUMNS} FROM memory_v3_selections
       WHERE conversation_id = ? AND turn = ?
       ORDER BY rowid
     `,
@@ -48,32 +60,59 @@ function rowsForTurn(conversationId: string, turn: number): SelectionRow[] {
     .all(conversationId, turn) as SelectionRow[];
 }
 
+function rowsForMessageIds(messageIds: string[]): SelectionRow[] {
+  if (messageIds.length === 0) return [];
+  const placeholders = messageIds.map(() => "?").join(", ");
+  return getSqliteFrom(getDb())
+    .query(
+      /*sql*/ `
+      SELECT ${SELECTION_COLUMNS} FROM memory_v3_selections
+      WHERE message_id IN (${placeholders})
+      ORDER BY rowid
+    `,
+    )
+    .all(...messageIds) as SelectionRow[];
+}
+
 /**
- * Build the inspector's v3 selection log for one turn of a conversation.
- *
- * `turn` is the inspected message's turn (the v2-activation log's turn). The
- * selection is returned ONLY for that exact turn; when there are no v3 rows for
- * it — including when `turn` is null (the message has no v2-activation turn) —
- * this returns `null` rather than falling back to a different turn. A fallback
- * would attribute another turn's selection (e.g. a later turn's pages and
- * rendered block) to the inspected message, which corrupts shadow validation.
- *
- * Caveat: v3 rows are keyed by the orchestrator turn counter (`ctx.turnCount`)
- * while `turn` here is the v2 memory-tracker turn. They coincide for normal
- * turns, but if they diverge this simply yields `null` (no section) rather than
- * wrong data. Tying v3 rows to a message id for exact per-message attribution
- * regardless of counter drift is a documented follow-up.
- *
- * Selection rows are stored in selection order, so rendering them in row order
- * reproduces the block v3 would inject.
+ * Resolve each selection's persisted matched section `(slug, ordinal)` to the
+ * concrete `Section` in the CURRENT page, so the injected block renders the
+ * matched section rather than the full page. Only slugs with a recorded ordinal
+ * are resolved (core/hot/fresh/edge selections have none and render full-page).
+ * A page edited since the turn re-derives the current section at that ordinal,
+ * or falls back to full-page when the ordinal no longer exists.
  */
-export async function getMemoryV3SelectionForInspector(
-  conversationId: string,
-  turn: number | null | undefined,
-): Promise<MemoryV3SelectionLog | null> {
-  if (turn == null) return null;
+async function reconstructMatchedSections(
+  rows: SelectionRow[],
+): Promise<Map<Slug, Section>> {
+  const sectionSlugs = rows
+    .filter((r) => r.section_ordinal != null)
+    .map((r) => r.slug);
+  if (sectionSlugs.length === 0) return new Map();
+
+  const workspaceDir = getWorkspaceDir();
+  const pageBody = (slug: Slug): Promise<string> =>
+    capabilityOrDiskBody(slug, async (s) => {
+      try {
+        return (await readPage(workspaceDir, s))?.body ?? "";
+      } catch {
+        return "";
+      }
+    });
+  const index = await buildSectionIndex(sectionSlugs, pageBody);
+
+  const sectionBySlug = new Map<Slug, Section>();
+  for (const row of rows) {
+    if (row.section_ordinal == null) continue;
+    const section = sectionByOrdinal(index, row.slug, row.section_ordinal);
+    if (section) sectionBySlug.set(row.slug, section);
+  }
+  return sectionBySlug;
+}
 
-  const rows = rowsForTurn(conversationId, turn);
+async function buildSelectionLog(
+  rows: SelectionRow[],
+): Promise<MemoryV3SelectionLog | null> {
   if (rows.length === 0) return null;
 
   const config = getConfig();
@@ -81,25 +120,19 @@ export async function getMemoryV3SelectionForInspector(
     slug: r.slug,
     source: r.source,
     pinned: r.pinned === 1,
+    sectionOrdinal: r.section_ordinal,
+    sectionHeading: r.section_title,
   }));
   const slugs: Slug[] = selections.map((s) => s.slug);
-  // NOTE: `injectedText` is APPROXIMATE — it renders the full/lead page for
-  // every slug, not the exact matched section live injection used. The inspector
-  // re-renders from persisted rows without re-running orchestration, and the
-  // section identity is not persisted (`memory_v3_selections` stores
-  // slug/source/pinned, not the section ordinal), so the section map is empty
-  // and `renderV3SectionContent` falls back to the full page. Persisting the
-  // injected section (a schema migration) is deliberately deferred: the A/B's
-  // primary signal is slug-level recall via `summarizeSelections`, which is
-  // exact — only this debug-oriented injected text is an approximation.
+  const sectionBySlug = await reconstructMatchedSections(rows);
   const injectedText = await renderMemoryBlock(
     slugs,
-    new Map<Slug, Section>(),
+    sectionBySlug,
     renderV3SectionContent,
   );
 
   return {
-    turn,
+    turn: rows[0]!.turn,
     live: isAssistantFeatureFlagEnabled(MEMORY_V3_LIVE, config),
     shadow: isAssistantFeatureFlagEnabled(MEMORY_V3_SHADOW, config),
     selections,
@@ -107,6 +140,38 @@ export async function getMemoryV3SelectionForInspector(
   };
 }
 
+/**
+ * Build the inspector's v3 selection log for the inspected message's turn,
+ * keyed by the turn's message ids. This is the durable join: `writeSelections`
+ * logs rows with `message_id = NULL` and the turn-end backfill stamps them with
+ * the assistant message id, so a per-message lookup is robust against the drift
+ * between v2's tracker turn and v3's orchestrator `turnCount`. Returns `null`
+ * when no v3 rows match (e.g. a turn predating the message-id backfill, or a
+ * conversation with no v3 data). Message ids are globally unique, so no
+ * conversation scope is needed.
+ *
+ * Selection rows are stored in selection order, so rendering them in row order
+ * reproduces the block v3 would inject.
+ */
+export async function getMemoryV3SelectionForInspectorByMessageIds(
+  messageIds: string[],
+): Promise<MemoryV3SelectionLog | null> {
+  return buildSelectionLog(rowsForMessageIds(messageIds));
+}
+
+/**
+ * Turn-keyed variant, retained for callers/tests that look up by an exact
+ * `(conversation, turn)`. Returns `null` when `turn` is null or there are no
+ * rows for it.
+ */
+export async function getMemoryV3SelectionForInspector(
+  conversationId: string,
+  turn: number | null | undefined,
+): Promise<MemoryV3SelectionLog | null> {
+  if (turn == null) return null;
+  return buildSelectionLog(rowsForTurn(conversationId, turn));
+}
+
 /**
  * Offline A/B aggregate over a conversation's logged v3 selections. Reads every
  * `memory_v3_selections` row for the conversation (all turns) and rolls them up

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

@@ -55,6 +55,7 @@ import { computeHotSet } from "./hot-set.js";
 import { computeLearnedEdgeGraph } from "./learned-edges.js";
 import type { OrchestrateResult } from "./orchestrate.js";
 import { orchestrate } from "./orchestrate.js";
+import { MemoryV3RetrievalUnavailableError } from "./pool-select.js";
 import { ensureSectionCollection } from "./section-dense-store.js";
 import type { SectionNeedle } from "./section-needle.js";
 import { buildSectionNeedle } from "./section-needle.js";
@@ -418,6 +419,11 @@ interface SelectionRow {
   slug: Slug;
   source: SelectionSource;
   pinned: number;
+  /** Ordinal of the matched section a finder lane surfaced; null for
+   *  core/hot/fresh/edge selections with no matched section. */
+  sectionOrdinal: number | null;
+  /** Heading of the matched section; null when there is no matched section. */
+  sectionTitle: string | null;
 }
 
 /**
@@ -438,17 +444,24 @@ export function attributeSelections(result: OrchestrateResult): SelectionRow[] {
   const finderLane = new Map(
     result.lanes.finder.map((c) => [c.slug, c.lane] as const),
   );
-  return result.selections.map((sel) => ({
-    slug: sel.slug,
-    source: core.has(sel.slug)
-      ? ("core" as const)
-      : hot.has(sel.slug)
-        ? ("hot" as const)
-        : fresh.has(sel.slug)
-          ? ("fresh" as const)
-          : (finderLane.get(sel.slug) ?? "needle"),
-    pinned: sel.pinned ? 1 : 0,
-  }));
+  return result.selections.map((sel) => {
+    // The matched section is populated only for finder-lane hits (including
+    // hits on core/hot pages); core/hot/fresh/edge-only selections have none.
+    const section = result.matchedSections.get(sel.slug);
+    return {
+      slug: sel.slug,
+      source: core.has(sel.slug)
+        ? ("core" as const)
+        : hot.has(sel.slug)
+          ? ("hot" as const)
+          : fresh.has(sel.slug)
+            ? ("fresh" as const)
+            : (finderLane.get(sel.slug) ?? "needle"),
+      pinned: sel.pinned ? 1 : 0,
+      sectionOrdinal: section?.ordinal ?? null,
+      sectionTitle: section?.title ?? null,
+    };
+  });
 }
 
 /** Write the attributed selection rows to `memory_v3_selections`. */
@@ -461,17 +474,51 @@ export function writeSelections(
   const raw = getSqliteFrom(getDb());
   // PK is (conversation_id, turn, slug); OR REPLACE keeps the write
   // idempotent if the same turn is observed twice (e.g. a retried turn).
+  // `message_id` is written NULL here (the assistant message does not exist at
+  // injection time) and stamped at turn end by
+  // `backfillMemoryV3SelectionMessageId`.
   const stmt = raw.query(/*sql*/ `
     INSERT OR REPLACE INTO memory_v3_selections (
-      conversation_id, turn, slug, source, pinned, created_at
-    ) VALUES (?, ?, ?, ?, ?, ?)
+      conversation_id, turn, slug, source, pinned, created_at,
+      message_id, section_ordinal, section_title
+    ) VALUES (?, ?, ?, ?, ?, ?, NULL, ?, ?)
   `);
   const now = Date.now();
   for (const row of rows) {
-    stmt.run(conversationId, turn, row.slug, row.source, row.pinned, now);
+    stmt.run(
+      conversationId,
+      turn,
+      row.slug,
+      row.source,
+      row.pinned,
+      now,
+      row.sectionOrdinal,
+      row.sectionTitle,
+    );
   }
 }
 
+/**
+ * Stamp the turn's assistant message id onto the selection rows just written
+ * for it. Mirrors the v2 activation-log backfill: `writeSelections` writes
+ * `message_id = NULL` at injection time, and this runs at turn end once the
+ * assistant message exists. Relies on the single-threaded-per-conversation turn
+ * invariant — every NULL-`message_id` row for the conversation belongs to the
+ * turn that just finished. Lets the inspector look v3 selections up by the
+ * turn's message ids (robust against v2/v3 turn-counter drift).
+ */
+export function backfillMemoryV3SelectionMessageId(
+  conversationId: string,
+  assistantMessageId: string,
+): void {
+  getSqliteFrom(getDb())
+    .query(
+      /*sql*/ `UPDATE memory_v3_selections SET message_id = ?
+               WHERE conversation_id = ? AND message_id IS NULL`,
+    )
+    .run(assistantMessageId, conversationId);
+}
+
 /**
  * Run v3 orchestration for one turn and log the selection set, returning the
  * orchestrate result so a live caller can render it. Never throws — all
@@ -530,6 +577,16 @@ export async function observeTurn(
     writeSelections(conversationId, turnIndex, rows);
     return result;
   } catch (err) {
+    // An INFRASTRUCTURE failure (the selector lost its provider — e.g. a
+    // transient CES credential blip) must NOT be silently swallowed: re-throw
+    // so the LIVE injector hard-fails the turn (a clean, retryable failure)
+    // rather than shipping it with no `<memory>` block. The shadow/observation
+    // callers (the injector in shadow mode, runShadowObservation) catch this
+    // and swallow it, so observation never fails a turn. Other (non-infra)
+    // errors stay non-fatal and degrade to no v3 block, as before.
+    if (err instanceof MemoryV3RetrievalUnavailableError) {
+      throw err;
+    }
     log.warn(
       { err: err instanceof Error ? err.message : String(err), conversationId },
       "memory-v3 orchestration failed (non-fatal)",
@@ -553,5 +610,11 @@ export async function runShadowObservation(
   const config = getConfig();
   if (config.memory.enabled === false) return;
   if (!isAssistantFeatureFlagEnabled(MEMORY_V3_SHADOW, config)) return;
-  await observeTurn(conversationId, turnIndex);
+  try {
+    await observeTurn(conversationId, turnIndex);
+  } catch {
+    // Shadow observation is fire-and-forget and must NEVER fail a turn.
+    // `observeTurn` now re-throws infra failures so the LIVE injector can
+    // hard-fail on them; here (observation only) we swallow them.
+  }
 }