@vellumai/assistant 0.8.10 → 0.8.11-staging.1

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

@@ -1,54 +1,57 @@
 /**
- * Memory v3 — orchestrator composing the section-grain lanes into one turn.
+ * Memory v3 — orchestrator composing the candidate lanes into one turn.
  *
  * Each turn runs:
- *   1. Candidate generation over three deterministic lanes:
+ *   1. Candidate generation over three deterministic finder lanes:
  *        - the section-grain BM25 needle (`SectionNeedle.query`, KB articles),
  *        - the dense lane (`denseLane`, KD articles), and
  *        - link-graph edge expansion (`edgeExpand`) over the top needle+dense
  *          article seeds.
  *      Each lane only ever ADDS candidates, so the pool is recall-safe by
  *      construction.
- *   2. Build the unified candidate pool of `{ slug, descriptor }`. The
- *      descriptor is the matched section's text for needle/dense hits (resolved
- *      via the section index); for edge-only pages it is the curated `links`
- *      description when the traversed edge carried one, else the page's best
- *      section against the query. Edge-only pages record NO matched section, so
- *      they inject the FULL page (the lead the query never hit is often empty;
- *      the link-relevant content is elsewhere) — the best-section text is only a
- *      descriptor fallback. Synthetic capability pages (skills / CLI commands)
- *      carry sections in the section index too, so they enter the pool through
- *      the lanes like any other page rather than being always-added.
+ *   2. Build the candidate pool in CACHE ORDER: the stable prefix —
+ *      `[...core (file order), ...hot (score order)]`, both computed at lane
+ *      init — followed by the finder candidates (needle → dense → edge
+ *      surfacing order). The stable prefix is identical across consecutive
+ *      turns while the lanes are unchanged (lane invalidation at consolidation
+ *      is the recompute cadence), so the selector input's leading segment
+ *      rides the provider KV cache (the cache breakpoint itself lives in
+ *      `pool-select.ts`).
+ *
+ *      Stable-prefix candidates render as FULL CARDS (`renderCard` — head
+ *      section + TOC), pre-rendered at lane init (`prefixCards`) so the
+ *      rendered prefix is byte-identical across turns. Finder candidates
+ *      render as compact snippet lines: the matched section's text (or the
+ *      curated `links` description for an edge hit), falling back to the
+ *      page's lead-section text when no match text exists.
+ *
+ *      The finder tail is NOT deduped against the stable prefix: a finder hit
+ *      on a core/hot page keeps its matched-section line (and its
+ *      `matchedSections` ref + `lanes.finder` entry), so the selector and the
+ *      section spotlight see that page's CURRENT relevance even though the
+ *      page itself sits in the stable prefix. The selector dedupes selections
+ *      by slug.
  *   3. A SINGLE forced-tool select (`selectPool`) over the whole pool. The
- *      result is this turn's selections.
- *   4. Age the carry-forward working set to this turn (evict stale non-pinned
- *      entries, then the cap) and snapshot it — the pages carried in from
- *      EARLIER turns.
- *   5. Final injection = unique union of this turn's selected slugs and that
- *      carried-forward set, so pages selected on earlier turns carry forward
- *      even when this turn does not re-select them.
- *   6. Record this turn's selections into the working set for LATER turns. This
- *      runs AFTER the snapshot so the cap is spent on genuinely carried pages,
- *      not on this turn's selections (which are injected directly) — otherwise a
- *      turn selecting more pages than the cap would evict the entire carry.
+ *      result is this turn's selections — current turn only. Cross-turn
+ *      persistence is the injector's job (net-new blocks frozen into history),
+ *      not a per-turn re-rendered carry set.
  */
 
 import type { AssistantConfig } from "../../../config/schema.js";
 import { denseLane } from "./dense.js";
 import type { EdgeGraph } from "./edge.js";
 import { edgeExpand } from "./edge.js";
-import type { PoolCandidate } from "./pool-select.js";
+import type { PoolCandidate, StableCandidate } from "./pool-select.js";
 import { selectPool } from "./pool-select.js";
 import type { SectionNeedle } from "./section-needle.js";
 import type {
-  CandidateLane,
+  FinderLane,
   MemoryRoutingTurn,
   Section,
   SectionIndex,
   SelectedPage,
   Slug,
 } from "./types.js";
-import { WorkingSet } from "./working-set.js";
 
 /** Default number of BM25 needle articles to fold into the pool. */
 export const DEFAULT_NEEDLE_K = 100;
@@ -62,7 +65,18 @@ export interface OrchestrateDeps {
    *  collection. */
   denseConfig: AssistantConfig;
   edgeGraph: EdgeGraph;
-  workingSet: WorkingSet;
+  /** The curated core set in file order (existence-filtered at lane init).
+   *  Heads the stable prefix of the candidate pool. */
+  coreSlugs: Slug[];
+  /** The frecency hot set in score order (computed at lane init with the core
+   *  set excluded). Follows core in the stable prefix. */
+  hotSlugs: Slug[];
+  /** Pre-rendered FULL cards for the stable-prefix slugs, keyed by slug.
+   *  Rendered ONCE at lane init so the selector's stable prefix is
+   *  byte-identical across turns (the cache contract). Every core/hot slug
+   *  MUST have an entry — a missing card is a lane-init bug and throws
+   *  (silently degrading would violate the byte-stable-prefix contract). */
+  prefixCards: ReadonlyMap<Slug, string>;
   /** Number of BM25 needle articles. Defaults to {@link DEFAULT_NEEDLE_K}. */
   needleK?: number;
   /** Number of dense-lane articles. Defaults to {@link DEFAULT_DENSE_K}. */
@@ -78,23 +92,43 @@ export interface OrchestrateDeps {
   edgeCap?: number;
 }
 
+/** A finder-lane candidate: the slug, the descriptor that justified it, and
+ *  the finder lane that FIRST surfaced it (needle → dense → edge precedence). */
+export interface FinderCandidate {
+  slug: Slug;
+  descriptor: string;
+  lane: FinderLane;
+}
+
+/**
+ * The three candidate lanes in cache order. `core` and `hot` are the stable
+ * prefix (byte-identical across turns while lanes are unchanged); `finder` is
+ * the dynamic tail and MAY repeat a stable-prefix slug (a finder hit on a
+ * core/hot page is kept so its current relevance stays visible downstream).
+ */
+export interface OrchestrateLanes {
+  /** Curated core set, file order. */
+  core: Slug[];
+  /** Frecency hot set, score order (never overlaps core). */
+  hot: Slug[];
+  /** Finder candidates in surfacing order, deduped among themselves only. */
+  finder: FinderCandidate[];
+}
+
 export interface OrchestrateResult {
-  /** This turn's selections, deduped by slug (pinned flags ORed). */
-  currentSelections: SelectedPage[];
-  /** The carried-forward set: selections from EARLIER turns, aged to this turn
-   *  (snapshotted before this turn's selections are recorded). */
-  workingSetUnion: Set<Slug>;
-  /** Slugs to inject: this turn's selections ∪ the carried-forward working set. */
-  finalInjection: Slug[];
-  /** The matched `Section` for each pooled slug that had one, keyed by slug.
-   *  Populated from the lane hits and consumed by the injector to render each
-   *  selected slug's matched section (progressive disclosure). */
-  sectionBySlug: Map<Slug, Section>;
-  /** The candgen lane that FIRST surfaced each pooled slug, keyed by slug.
-   *  Insertion order is needle → dense → edge, so a page surfaced by more than
-   *  one lane records the highest-precedence one. Consumed by the selection
-   *  telemetry to attribute each selection to its true lane. */
-  laneBySlug: Map<Slug, CandidateLane>;
+  /** This turn's selections, deduped by slug (pinned flags ORed; the dedup is
+   *  `selectPool`'s contract). Current turn only — there is no
+   *  carried-forward set unioned in. */
+  selections: SelectedPage[];
+  /** The matched `Section` for each candidate slug that had one, keyed by slug.
+   *  Populated from the finder-lane hits — including hits on core/hot pages —
+   *  and consumed by the injector to render each selected slug's matched
+   *  section (progressive disclosure). */
+  matchedSections: Map<Slug, Section>;
+  /** The candidate lanes in cache order; see {@link OrchestrateLanes}. Consumed
+   *  by the selection telemetry (lane attribution) and the downstream selector
+   *  rendering/spotlight. */
+  lanes: OrchestrateLanes;
 }
 
 /** Stable-order de-duplication preserving first occurrence. */
@@ -110,6 +144,13 @@ export async function orchestrate(
   const denseK = deps.denseK ?? DEFAULT_DENSE_K;
   const { sections } = deps.sectionIndex;
 
+  // The stable prefix: core (file order) then hot (score order). Hot is
+  // computed with core excluded at lane init; the filter here is a cheap
+  // defensive dedup so a misbehaving lane can never double-list a slug.
+  const core = deps.coreSlugs;
+  const hot = deps.hotSlugs.filter((slug) => !core.includes(slug));
+  const stablePrefix = new Set<Slug>([...core, ...hot]);
+
   // Step 1: needle (sync BM25) and dense (async embed + Qdrant) lanes run in
   // parallel. Both return distinct articles each tagged with their best-scoring
   // section index/ordinal.
@@ -118,43 +159,42 @@ export async function orchestrate(
     denseLane(deps.denseConfig, turn.currentMessage, denseK),
   ]);
 
-  // The pool accumulates one entry per distinct article. `sectionBySlug` records
-  // the matched `Section` (when one is known) for downstream injection;
-  // `laneBySlug` records the lane that first surfaced each slug for telemetry.
-  const poolBySlug = new Map<Slug, PoolCandidate>();
-  const sectionBySlug = new Map<Slug, Section>();
-  const laneBySlug = new Map<Slug, CandidateLane>();
+  // `matchedSections` records the matched `Section` (when one is known) for
+  // every finder hit — INCLUDING hits on stable-prefix slugs — for downstream
+  // injection/spotlight. `finder` accumulates one entry per distinct
+  // finder-surfaced article; the first lane to surface a slug wins the entry,
+  // so the needle → dense → edge call order encodes lane precedence.
+  const matchedSections = new Map<Slug, Section>();
+  const finder: FinderCandidate[] = [];
+  const finderSeen = new Set<Slug>();
 
-  // Add one pool candidate, recording its matched `Section` (when known) for
-  // downstream injection and the `lane` that surfaced it for telemetry.
-  // `descriptor` overrides the section text when supplied (the edge lane prefers
-  // a curated `links` description). The first lane to surface a slug wins the
-  // pool entry, the recorded section, AND the recorded lane — so the
-  // needle → dense → edge call order encodes lane precedence.
-  const addCandidate = (
+  // `descriptor` overrides the section text when supplied (the edge lane
+  // prefers a curated `links` description).
+  const addFinder = (
     slug: Slug,
     section: Section | undefined,
     descriptor: string | undefined,
-    lane: CandidateLane,
+    lane: FinderLane,
   ): void => {
-    if (section && !sectionBySlug.has(slug)) {
-      sectionBySlug.set(slug, section);
+    if (section && !matchedSections.has(slug)) {
+      matchedSections.set(slug, section);
     }
-    if (poolBySlug.has(slug)) return;
-    laneBySlug.set(slug, lane);
-    poolBySlug.set(slug, {
+    if (finderSeen.has(slug)) return;
+    finderSeen.add(slug);
+    finder.push({
       slug,
       descriptor: descriptor ?? section?.text ?? "",
+      lane,
     });
   };
 
-  // Step 2a: needle hits — descriptor is the matched section's text. `section`
+  // Step 1a: needle hits — descriptor is the matched section's text. `section`
   // is an index into `sections`.
   for (const hit of needled) {
-    addCandidate(hit.article, sections[hit.section], undefined, "needle");
+    addFinder(hit.article, sections[hit.section], undefined, "needle");
   }
 
-  // Step 2b: dense hits — `section` is the matched ORDINAL; resolve it to the
+  // Step 1b: dense hits — `section` is the matched ORDINAL; resolve it to the
   // concrete `Section` via the section index. Falls back to undefined (blank
   // descriptor) if the ordinal is not in the in-memory index.
   for (const hit of densed) {
@@ -163,7 +203,7 @@ export async function orchestrate(
     // so `byArticle` holds exactly the live pages (synthetic capability slugs
     // included) — only truly-deleted pages are dropped here.
     if (!deps.sectionIndex.byArticle.has(hit.article)) continue;
-    addCandidate(
+    addFinder(
       hit.article,
       sectionByOrdinal(deps.sectionIndex, hit.article, hit.section),
       undefined,
@@ -171,16 +211,19 @@ export async function orchestrate(
     );
   }
 
-  // Step 2c: edge expansion over the top needle+dense article seeds. `alive`
-  // skips slugs already pooled. An edge-only page was surfaced because its
-  // NEIGHBOUR matched — the query did not lexically hit the page itself, so
-  // `bestSection` returns its first/lead section on a zero-score match. That
-  // lead is often empty for heading-structured pages, and it is the curated
-  // `links` description (not the lead) that made the candidate relevant. So we
-  // record NO matched section for edge-only pages (pass `undefined`), which
-  // makes injection fall back to the FULL page — where the link-relevant content
-  // lives. `bestSection`'s text is kept only as the select-pool DESCRIPTOR
-  // fallback for when the traversed edge carried no curated `links` description.
+  // Step 1c: edge expansion over the top needle+dense article seeds. `alive`
+  // skips slugs already in the pool — finder-surfaced AND stable-prefix slugs
+  // (an edge hit carries no matched section, so re-surfacing a core/hot page
+  // adds nothing; needle/dense hits on those pages ARE kept for their
+  // sections). An edge-only page was surfaced because its NEIGHBOUR matched —
+  // the query did not lexically hit the page itself, so `bestSection` returns
+  // its first/lead section on a zero-score match. That lead is often empty for
+  // heading-structured pages, and it is the curated `links` description (not
+  // the lead) that made the candidate relevant. So we record NO matched
+  // section for edge-only pages (pass `undefined`), which makes injection fall
+  // back to the FULL page — where the link-relevant content lives.
+  // `bestSection`'s text is kept only as the select-pool DESCRIPTOR fallback
+  // for when the traversed edge carried no curated `links` description.
   const seeds = unique<Slug>([
     ...needled.map((h) => h.article),
     ...densed.map((h) => h.article),
@@ -189,12 +232,12 @@ export async function orchestrate(
     seedCount: deps.edgeSeeds,
     perSeed: deps.edgePerSeed,
     cap: deps.edgeCap,
-    alive: (slug) => !poolBySlug.has(slug),
+    alive: (slug) => !finderSeen.has(slug) && !stablePrefix.has(slug),
   });
   for (const neighbor of surfaced) {
     const best = deps.needle.bestSection(neighbor.article, turn.currentMessage);
     const fallbackDescriptor = best >= 0 ? sections[best]?.text : undefined;
-    addCandidate(
+    addFinder(
       neighbor.article,
       undefined,
       neighbor.description ?? fallbackDescriptor,
@@ -202,45 +245,45 @@ export async function orchestrate(
     );
   }
 
-  // Step 3: a SINGLE forced-tool select over the unified pool.
-  const selected = await selectPool([...poolBySlug.values()], turn);
-  const bySlug = new Map<Slug, SelectedPage>();
-  for (const page of selected) {
-    const existing = bySlug.get(page.slug);
-    bySlug.set(page.slug, {
-      slug: page.slug,
-      pinned: (existing?.pinned ?? false) || page.pinned,
-    });
-  }
-  const currentSelections = [...bySlug.values()];
-
-  // Step 4: age the carry-forward set to this turn (drop stale non-pinned
-  // entries, then the cap) and snapshot it. This is the set carried in from
-  // EARLIER turns; recording this turn happens afterward (step 6) so the cap is
-  // spent on genuinely carried pages, not on this turn's selections (which are
-  // injected directly anyway).
-  deps.workingSet.evict(turn.turnNumber);
-  const workingSetUnion = deps.workingSet.union();
-
-  // Step 5: final injection = this turn's selections ∪ the carried-forward set,
-  // so pages selected on earlier turns carry forward even when this turn does
-  // not re-select them.
-  const finalInjection = unique<Slug>([
-    ...currentSelections.map((s) => s.slug),
-    ...workingSetUnion,
-  ]);
+  // Step 2: assemble the selector pool in cache order — the stable prefix
+  // (core then hot) as FULL CARDS, then the finder tail. Cards are
+  // pre-rendered at lane init (`prefixCards`): query- AND
+  // conversation-state-INDEPENDENT by design, so the rendered prefix is
+  // byte-identical across turns while the lanes are unchanged. The tail is
+  // NOT deduped against the prefix — a finder hit on a core/hot page renders
+  // its own snippet line so its CURRENT relevance stays visible; `selectPool`
+  // dedupes selections by slug. Finder candidates with no match text fall
+  // back to the page's lead-section snippet.
+  const stable: StableCandidate[] = [...core, ...hot].map((slug) => {
+    const card = deps.prefixCards.get(slug);
+    if (card === undefined) {
+      // Lane init renders a card for every core/hot slug; a hole here means
+      // the lanes and the card map are out of sync. Throw rather than render
+      // a degraded card — the caller (observeTurn) logs and skips the turn,
+      // which is better than silently breaking the byte-stable prefix.
+      throw new Error(
+        `memory-v3: no pre-rendered card for stable-prefix slug "${slug}"`,
+      );
+    }
+    return { slug, card };
+  });
+  const finderTail: PoolCandidate[] = finder.map((c) => ({
+    slug: c.slug,
+    descriptor:
+      c.descriptor.trim().length > 0
+        ? c.descriptor
+        : leadSectionText(deps.sectionIndex, c.slug),
+  }));
 
-  // Step 6: record this turn's selections so they carry forward to LATER turns.
-  for (const sel of currentSelections) {
-    deps.workingSet.recordSelection(sel.slug, turn.turnNumber, sel.pinned);
-  }
+  // Step 3: a SINGLE forced-tool select over the cache-ordered pool. The
+  // selections come back slug-deduped (pinned flags ORed) — `selectPool`'s
+  // contract.
+  const selections = await selectPool({ stable, finder: finderTail }, turn);
 
   return {
-    currentSelections,
-    workingSetUnion,
-    finalInjection,
-    sectionBySlug,
-    laneBySlug,
+    selections,
+    matchedSections,
+    lanes: { core, hot, finder },
   };
 }
 
@@ -264,3 +307,15 @@ function sectionByOrdinal(
   }
   return undefined;
 }
+
+/**
+ * The text of an article's LEAD (first) section, or `""` when the article has
+ * no indexed sections. Used as the finder-line snippet fallback when a
+ * candidate carries no match text (e.g. an edge hit with neither a curated
+ * description nor a scoring section) — the lead is the closest free
+ * approximation of the card head.
+ */
+function leadSectionText(index: SectionIndex, article: Slug): string {
+  const first = index.byArticle.get(article)?.[0];
+  return first === undefined ? "" : (index.sections[first]?.text ?? "");
+}

package/src/plugins/defaults/memory-v3-shadow/page-content.ts

@@ -1,22 +1,24 @@
+import { injectedConceptHeader } from "../../../memory/v2/injected-block-slugs.js";
 import { readPage, renderPageContent } from "../../../memory/v2/page-store.js";
 import { getWorkspaceDir } from "../../../util/platform.js";
 import { renderCapabilityContent } from "./capabilities.js";
+import { renderCard } from "./card.js";
 import type { Section, Slug } from "./types.js";
 
 /**
  * Prefix `body` with the `# memory/concepts/<slug>.md` header marker the v3
- * `<memory>` block uses. Both the full-page and matched-section renderers emit
- * this exact marker, and the v2 stripper recognizes pages by it — so the two
- * call sites MUST stay byte-identical, which is why this lives in one place.
+ * `<memory>` block uses (shared builder: `injectedConceptHeader`, so the
+ * renderers, the card renderer, and the read-side parsers all agree on the
+ * exact bytes).
  */
 function withConceptHeader(slug: Slug, body: string): string {
-  return `# memory/concepts/${slug}.md\n${body}`;
+  return `${injectedConceptHeader(slug)}\n${body}`;
 }
 
 /**
  * Render a selected page's full content for the v3 `<memory>` block. Mirrors
  * the v2 dynamic-memory layout (`# memory/concepts/<slug>.md\n<frontmatter+body>`)
- * so the working-set block reads like v2's. A missing page (or any read
+ * so the v3 block reads like v2's. A missing page (or any read
  * failure) degrades to "" — `renderMemoryBlock` still emits a line for the
  * slug, and a blank section is preferable to throwing into the turn.
  *
@@ -25,9 +27,11 @@ function withConceptHeader(slug: Slug, body: string): string {
  * `readPage`. A non-null result (including "") means the slug was a capability
  * slug and was handled here.
  *
- * Shared by the live injector (`shadow-plugin.ts`) and the inspector
- * selection-log store (`selection-log-store.ts`) so the inspector's rendered
- * block is byte-identical to what live injection produces.
+ * INSPECTOR-ONLY (as the `renderV3SectionContent` fallback): live injection
+ * freezes compact CARDS into history via {@link renderV3CardContent} — it no
+ * longer renders full pages, so this output is an APPROXIMATE reconstruction
+ * for the inspector selection log (`selection-log-store.ts`), not what the
+ * model saw.
  */
 export async function renderV3PageContent(slug: Slug): Promise<string> {
   const capability = renderCapabilityContent(slug);
@@ -44,18 +48,45 @@ export async function renderV3PageContent(slug: Slug): Promise<string> {
 }
 
 /**
- * Render a slug's matched section for the v3 `<memory>` block (progressive
- * disclosure: inject only the section the lanes matched, not the full page).
- * Uses the same `# memory/concepts/<slug>.md` header marker as
- * {@link renderV3PageContent} so the block reads like v2's and the v2 stripper
- * recognizes it.
+ * Render a selected page's compact CARD for the v3 frozen-injection layer:
+ * the `# memory/concepts/<slug>.md` header, the page's head section, and a
+ * one-line section TOC (see `card.ts`). Cards are the persistent injection
+ * unit — frozen into history once and deduped by the everInjected store.
+ *
+ * - Capability slugs (skills, `assistant` CLI commands) have no on-disk page
+ *   and no meaningful head/TOC split, so they render their full capability
+ *   content via {@link renderCapabilityContent} (its own `# Skill:` /
+ *   `# CLI command:` header) instead of a card.
+ * - A missing page or any read failure degrades to "" — the injector skips
+ *   empty cards rather than throwing into the turn.
+ */
+export async function renderV3CardContent(slug: Slug): Promise<string> {
+  const capability = renderCapabilityContent(slug);
+  if (capability !== null) return capability;
+  try {
+    const page = await readPage(getWorkspaceDir(), slug);
+    if (!page) return "";
+    return renderCard(slug, renderPageContent(page));
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Render a slug's matched section under the `# memory/concepts/<slug>.md`
+ * header marker, the same marker as {@link renderV3PageContent}.
+ *
+ * INSPECTOR-ONLY: live injection freezes cards ({@link renderV3CardContent})
+ * and re-renders the ephemeral spotlight separately; this per-section render
+ * remains for the inspector selection log (`selection-log-store.ts`), which
+ * reconstructs an approximate view of a turn's selection after the fact.
  *
  * - Capability slugs (skills, `assistant` CLI commands) have no on-disk
  *   section, so they always render their capability content via
  *   {@link renderCapabilityContent}, never a section.
- * - When `section` is undefined (e.g. a carry-forward page with no current
- *   match), fall back to {@link renderV3PageContent} (the full/lead page) so the
- *   slug still contributes content.
+ * - When `section` is undefined (e.g. an edge-only or stable-prefix page with
+ *   no current match), fall back to {@link renderV3PageContent} (the full/lead
+ *   page) so the slug still contributes content.
  */
 export async function renderV3SectionContent(
   slug: Slug,