@vellumai/assistant 0.8.8 → 0.8.9-dev.202606091853.fbaa2ae

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

@@ -0,0 +1,156 @@
+/**
+ * Read-side store for the inspector's Memory V3 section. Reads the persisted
+ * `memory_v3_selections` rows for a turn and re-renders the `<memory>` block
+ * the v3 working set selected, so the inspector can show what v3 chose (and,
+ * in live mode, what it actually injected) without re-running orchestration —
+ * which would be wrong anyway, since the working set is stateful (carry-forward
+ * across turns) and can't be reproduced after the fact.
+ */
+
+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 { renderV3SectionContent } from "./page-content.js";
+import { renderMemoryBlock } from "./render-injection.js";
+import {
+  type Section,
+  SELECTION_SOURCES,
+  type SelectionSource,
+  type Slug,
+} from "./types.js";
+
+const MEMORY_V3_SHADOW = "memory-v3-shadow" as const;
+const MEMORY_V3_LIVE = "memory-v3-live" as const;
+
+interface SelectionRow {
+  slug: string;
+  source: string;
+  pinned: number;
+}
+
+function rowsForTurn(conversationId: string, turn: number): SelectionRow[] {
+  return getSqliteFrom(getDb())
+    .query(
+      /*sql*/ `
+      SELECT slug, source, pinned FROM memory_v3_selections
+      WHERE conversation_id = ? AND turn = ?
+      ORDER BY rowid
+    `,
+    )
+    .all(conversationId, turn) 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 `finalInjection` order (this turn's L2
+ * selections, then carry-forward), so rendering them in row order reproduces
+ * the block v3 would inject.
+ */
+export async function getMemoryV3SelectionForInspector(
+  conversationId: string,
+  turn: number | null | undefined,
+): Promise<MemoryV3SelectionLog | null> {
+  if (turn == null) return null;
+
+  const rows = rowsForTurn(conversationId, turn);
+  if (rows.length === 0) return null;
+
+  const config = getConfig();
+  const selections = rows.map((r) => ({
+    slug: r.slug,
+    source: r.source,
+    pinned: r.pinned === 1,
+  }));
+  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 injectedText = await renderMemoryBlock(
+    slugs,
+    new Map<Slug, Section>(),
+    renderV3SectionContent,
+  );
+
+  return {
+    turn,
+    live: isAssistantFeatureFlagEnabled(MEMORY_V3_LIVE, config),
+    shadow: isAssistantFeatureFlagEnabled(MEMORY_V3_SHADOW, config),
+    selections,
+    injectedText,
+  };
+}
+
+/**
+ * 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
+ * for shadow-vs-v2 inspection without re-rendering any blocks:
+ *
+ *   - `bySource`: count of selection rows per lane source (`needle` / `dense` /
+ *     `edge` / `carry-forward`). Every known source is present (zero when
+ *     unused) so callers can diff two runs without null-guarding; an unknown
+ *     historical/free-text source is ignored (the column is permissive).
+ *   - `turns`: number of distinct turns that logged at least one selection.
+ *   - `distinctSlugs`: number of distinct page slugs selected across all turns —
+ *     the conversation's working-set footprint.
+ *
+ * This is read-only telemetry for comparing a shadow run's lane mix against
+ * v2's logged selections offline; it never re-runs orchestration.
+ */
+export interface SelectionSummary {
+  bySource: Record<SelectionSource, number>;
+  turns: number;
+  distinctSlugs: number;
+}
+
+function isSelectionSource(source: string): source is SelectionSource {
+  return (SELECTION_SOURCES as readonly string[]).includes(source);
+}
+
+export function summarizeSelections(conversationId: string): SelectionSummary {
+  const rows = getSqliteFrom(getDb())
+    .query(
+      /*sql*/ `
+      SELECT turn, slug, source FROM memory_v3_selections
+      WHERE conversation_id = ?
+    `,
+    )
+    .all(conversationId) as Array<{
+    turn: number;
+    slug: string;
+    source: string;
+  }>;
+
+  const bySource = Object.fromEntries(
+    SELECTION_SOURCES.map((source) => [source, 0]),
+  ) as Record<SelectionSource, number>;
+  const turns = new Set<number>();
+  const slugs = new Set<string>();
+  for (const row of rows) {
+    if (isSelectionSource(row.source)) bySource[row.source] += 1;
+    turns.add(row.turn);
+    slugs.add(row.slug);
+  }
+
+  return { bySource, turns: turns.size, distinctSlugs: slugs.size };
+}

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

@@ -0,0 +1,382 @@
+/**
+ * Memory v3 — flag-gated shadow/live orchestration engine.
+ *
+ * Runs the v3 orchestrator each turn and records its selection set to
+ * `memory_v3_selections`. Two flags gate behavior:
+ *
+ *   - `memory-v3-shadow` (live OFF): observation-only. {@link observeTurn}
+ *     orchestrates and logs the selection set; no injection is produced, so v2
+ *     injection is bit-for-bit identical — the only difference is the
+ *     side-effect telemetry write.
+ *   - `memory-v3-live`: live injection. The injector (`memoryV3Injector` in
+ *     `./injector.ts`) additionally renders the working-set selection into a
+ *     `<memory>` block and returns it at v2's dynamic-memory placement
+ *     (`after-memory-prefix`). Selections are still logged.
+ *   - both OFF: orchestration is skipped entirely.
+ *
+ * On each turn (either flag on):
+ *   1. Lazy-init the v3 lanes ONCE across the whole process (section index,
+ *      section-grain BM25 needle, dense lane config, link-graph edge graph,
+ *      carry-forward working set), memoizing the init promise so concurrent
+ *      first turns share a single build.
+ *   2. Build a {@link MemoryRoutingTurn} from the conversation's recent messages.
+ *   3. Run {@link orchestrate} and record its selection set to
+ *      `memory_v3_selections` with a best-effort lane attribution.
+ *
+ * {@link observeTurn} wraps everything after the flag read in try/catch — any
+ * failure is logged and swallowed so it can never affect the live turn. The
+ * injector treats a `null`/empty result as "no v3 injection", so v2 memory
+ * remains the fallback rather than dropping all memory.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+
+import { isAssistantFeatureFlagEnabled } from "../../../config/assistant-feature-flags.js";
+import { getConfig } from "../../../config/loader.js";
+import type { AssistantConfig } from "../../../config/schema.js";
+import { getMessages } from "../../../memory/conversation-crud.js";
+import { getDb, getSqliteFrom } from "../../../memory/db-connection.js";
+import { stringifyMessageContent } from "../../../memory/message-content.js";
+import { getPageIndex } from "../../../memory/v2/page-index.js";
+import { readPage, renderPageContent } from "../../../memory/v2/page-store.js";
+import { getLogger } from "../../../util/logger.js";
+import {
+  getWorkspaceDir,
+  getWorkspacePromptPath,
+} from "../../../util/platform.js";
+import { stripCommentLines } from "../../../util/strip-comment-lines.js";
+import { capabilityOrDiskBody } from "./capabilities.js";
+import type { EdgeGraph } from "./edge.js";
+import { buildEdgeGraph } from "./edge.js";
+import type { OrchestrateResult } from "./orchestrate.js";
+import { orchestrate } from "./orchestrate.js";
+import { ensureSectionCollection } from "./section-dense-store.js";
+import type { SectionNeedle } from "./section-needle.js";
+import { buildSectionNeedle } from "./section-needle.js";
+import { buildSectionIndex } from "./sections.js";
+import {
+  type MemoryRoutingTurn,
+  type SectionIndex,
+  type SelectionSource,
+  type Slug,
+} from "./types.js";
+import { WorkingSet } from "./working-set.js";
+
+export const MEMORY_V3_SHADOW = "memory-v3-shadow" as const;
+export const MEMORY_V3_LIVE = "memory-v3-live" as const;
+
+const log = getLogger("memory-v3-shadow");
+
+/** How many recent messages to fold into the shadow `recentContext` string. */
+const RECENT_CONTEXT_MESSAGES = 6;
+
+/**
+ * The lazily-built, process-lifetime v3 lanes. The working set is stateful
+ * (carry-forward across turns), so it is intentionally shared across every
+ * shadow turn rather than rebuilt per turn — that is the whole point of the
+ * carry-forward lane.
+ */
+export interface ShadowLanes {
+  sectionIndex: SectionIndex;
+  needle: SectionNeedle;
+  /** Config the dense lane needs to embed the query + search the section
+   *  collection. */
+  denseConfig: AssistantConfig;
+  edgeGraph: EdgeGraph;
+  workingSet: WorkingSet;
+}
+
+/**
+ * Memoized init promise. Caching the PROMISE (not the resolved value) means
+ * concurrent first turns all await the same build instead of racing several
+ * section-index / needle / edge-graph passes.
+ */
+let lanesPromise: Promise<ShadowLanes> | null = null;
+
+/**
+ * Drop the memoized lanes so the NEXT `getLanes` rebuilds them from scratch
+ * (fresh section index + fresh needle + fresh edge graph). The rebuild is lazy
+ * — this only clears the cache, so the cost is paid by the next caller, and
+ * concurrent first-callers after the invalidation still share a single build via
+ * the re-memoized promise. Call this whenever the underlying pages change on
+ * disk.
+ */
+export function invalidateLanes(): void {
+  lanesPromise = null;
+}
+
+/** Test-only alias for {@link invalidateLanes}. */
+export function resetShadowLanesForTests(): void {
+  invalidateLanes();
+}
+
+async function initLanes(config: AssistantConfig): Promise<ShadowLanes> {
+  const pageIndex = await getPageIndex(getWorkspaceDir());
+  const slugs = pageIndex.entries.map((entry) => entry.slug);
+
+  // Read each page ONCE and feed BOTH forms downstream: the frontmatter-stripped
+  // body to the section index (lexical/dense matching), and the raw page
+  // (frontmatter + body) to the edge graph (so the `links:` frontmatter is
+  // available). A per-slug cache holds the parsed page so the second consumer
+  // reuses the first read.
+  const pageCache = new Map<Slug, { body: string; raw: string } | null>();
+  async function loadPage(
+    slug: Slug,
+  ): Promise<{ body: string; raw: string } | null> {
+    if (pageCache.has(slug)) return pageCache.get(slug)!;
+    let loaded: { body: string; raw: string } | null = null;
+    try {
+      const page = await readPage(getWorkspaceDir(), slug);
+      if (page) loaded = { body: page.body, raw: renderPageContent(page) };
+    } catch {
+      loaded = null;
+    }
+    pageCache.set(slug, loaded);
+    return loaded;
+  }
+  // Synthetic capability slugs (skills / CLI commands) have no on-disk page, so
+  // they contribute their rendered capability content to the section index —
+  // exactly the content `page-content.ts` injects for them. This puts them in
+  // the section index, so the needle lane (and, once a backfill embeds them, the
+  // dense lane) ranks them by relevance like any other page, instead of being
+  // blindly added to the select pool every turn. Real pages read their body
+  // through the cached `loadPage`.
+  const pageBody = async (slug: Slug): Promise<string> =>
+    capabilityOrDiskBody(slug, async (s) => (await loadPage(s))?.body ?? "");
+  const pageRaw = async (slug: Slug): Promise<string> => {
+    const loaded = await loadPage(slug);
+    if (!loaded) throw new Error(`page not found: ${slug}`);
+    return loaded.raw;
+  };
+
+  const sectionIndex = await buildSectionIndex(slugs, pageBody);
+  const needle = buildSectionNeedle(sectionIndex);
+  const edgeGraph = await buildEdgeGraph(pageIndex.entries, pageRaw, {
+    hubDegree: config.memory.v3.edge.hubDegree,
+  });
+  // Ensuring the dense collection is best-effort: the needle + edge lanes and
+  // carry-forward are in-memory and independent of Qdrant, so a Qdrant outage
+  // must NOT reject lane init (which would return `null` from observeTurn and
+  // disable ALL of v3, plus poison the memoized lanes until invalidation). On
+  // failure we log and continue with the dense lane degraded — denseLane already
+  // returns no hits on a Qdrant error, and maintain/backfill re-ensure the
+  // collection once Qdrant recovers.
+  try {
+    await ensureSectionCollection(config);
+  } catch (err) {
+    log.warn(
+      { err: err instanceof Error ? err.message : String(err) },
+      "memory-v3: section collection ensure failed; continuing with the dense lane degraded",
+    );
+  }
+
+  const workingSet = new WorkingSet(
+    config.memory.v3.workingSet.maxPages,
+    config.memory.v3.workingSet.evictWindow,
+  );
+
+  return {
+    sectionIndex,
+    needle,
+    denseConfig: config,
+    edgeGraph,
+    workingSet,
+  };
+}
+
+/** Lazy, memoized accessor for the shadow lanes. */
+function getLanes(config: AssistantConfig): Promise<ShadowLanes> {
+  if (!lanesPromise) {
+    lanesPromise = initLanes(config).catch((err) => {
+      // Reset on failure so a transient init error doesn't permanently wedge
+      // the shadow lane — the next turn retries.
+      lanesPromise = null;
+      throw err;
+    });
+  }
+  return lanesPromise;
+}
+
+/**
+ * Read the live NOW.md scratchpad (the user's short "what's salient right now"
+ * file), stripped of its comment lines. Mirrors `readNowScratchpad` but reads
+ * through the light platform / strip utilities directly, keeping the v3
+ * plugin's load (and its test) free of heavier module graphs. Returns `null`
+ * when absent, empty, or unreadable.
+ */
+function readNowContext(): string | null {
+  const nowPath = getWorkspacePromptPath("NOW.md");
+  if (!existsSync(nowPath)) return null;
+  try {
+    const stripped = stripCommentLines(readFileSync(nowPath, "utf-8")).trim();
+    return stripped.length > 0 ? stripped : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Compose the situational signal threaded into pool selection: the current date
+ * plus the live NOW.md scratchpad. The date alone is a weak signal, but together
+ * with the scratchpad it lets retrieval surface a page the message never names
+ * (e.g. an anniversary that falls today). Always returns at least the date line
+ * — this mirrors the `c_now`/NOW.md signal the v2 retriever uses.
+ */
+function buildSituationalContext(): string {
+  const now = readNowContext();
+  const today = `Today is ${new Date().toDateString()}.`;
+  return now ? `${today}\n\n${now}` : today;
+}
+
+/**
+ * Build a v3 {@link MemoryRoutingTurn} from the conversation's persisted messages.
+ * `currentMessage` is the latest user message; `recentContext` is the tail of
+ * the recent transcript; `situationalContext` carries the current date and the
+ * live NOW.md scratchpad. Returns `null` when there is no user message to route
+ * on (nothing to shadow this turn).
+ */
+function buildShadowTurn(
+  conversationId: string,
+  turnIndex: number,
+): MemoryRoutingTurn | null {
+  const rows = getMessages(conversationId);
+  if (rows.length === 0) return null;
+
+  let currentMessage = "";
+  for (let i = rows.length - 1; i >= 0; i--) {
+    if (rows[i]!.role === "user") {
+      currentMessage = stringifyMessageContent(rows[i]!.content);
+      if (currentMessage.length > 0) break;
+    }
+  }
+  if (currentMessage.length === 0) return null;
+
+  const recentContext = rows
+    .slice(-RECENT_CONTEXT_MESSAGES)
+    .map((r) => stringifyMessageContent(r.content))
+    .filter((t) => t.length > 0)
+    .join("\n");
+
+  return {
+    conversationId,
+    turnNumber: turnIndex,
+    currentMessage,
+    recentContext,
+    situationalContext: buildSituationalContext(),
+  };
+}
+
+interface SelectionRow {
+  slug: Slug;
+  source: SelectionSource;
+  pinned: number;
+}
+
+/**
+ * Map an orchestrate result onto telemetry rows with precise per-lane source
+ * attribution.
+ *
+ * - A current selection is tagged with the candgen lane that FIRST surfaced its
+ *   page this turn — `result.laneBySlug` (`"needle"` / `"dense"` / `"edge"`),
+ *   recorded at pool-build time. (`"needle"` is the fallback if a selected slug
+ *   is somehow absent from the lane map, which should not happen since every
+ *   pooled candidate is recorded there.)
+ * - A slug in `finalInjection` but NOT re-selected this turn → `"carry-forward"`.
+ */
+export function attributeSelections(result: OrchestrateResult): SelectionRow[] {
+  const rows: SelectionRow[] = [];
+  const seen = new Set<Slug>();
+  for (const sel of result.currentSelections) {
+    seen.add(sel.slug);
+    rows.push({
+      slug: sel.slug,
+      source: result.laneBySlug.get(sel.slug) ?? "needle",
+      pinned: sel.pinned ? 1 : 0,
+    });
+  }
+  for (const slug of result.finalInjection) {
+    if (seen.has(slug)) continue;
+    seen.add(slug);
+    rows.push({ slug, source: "carry-forward", pinned: 0 });
+  }
+  return rows;
+}
+
+/** Write the attributed selection rows to `memory_v3_selections`. */
+export function writeSelections(
+  conversationId: string,
+  turn: number,
+  rows: SelectionRow[],
+): void {
+  if (rows.length === 0) return;
+  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).
+  const stmt = raw.query(/*sql*/ `
+    INSERT OR REPLACE INTO memory_v3_selections (
+      conversation_id, turn, slug, source, pinned, created_at
+    ) VALUES (?, ?, ?, ?, ?, ?)
+  `);
+  const now = Date.now();
+  for (const row of rows) {
+    stmt.run(conversationId, turn, row.slug, row.source, row.pinned, now);
+  }
+}
+
+/**
+ * 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
+ * failures are logged and swallowed (returning `null`) so the live turn is
+ * unaffected. Returns `null` when there is no user message to route on.
+ */
+export async function observeTurn(
+  conversationId: string,
+  turnIndex: number,
+): Promise<OrchestrateResult | null> {
+  try {
+    const turn = buildShadowTurn(conversationId, turnIndex);
+    if (!turn) return null;
+
+    const cfg = getConfig();
+    const lanes = await getLanes(cfg);
+    const v3 = cfg.memory.v3;
+    const result = await orchestrate(turn, {
+      sectionIndex: lanes.sectionIndex,
+      needle: lanes.needle,
+      denseConfig: lanes.denseConfig,
+      edgeGraph: lanes.edgeGraph,
+      workingSet: lanes.workingSet,
+      needleK: v3.needleK,
+      denseK: v3.denseK,
+      edgeSeeds: v3.edge.seedCount,
+      edgePerSeed: v3.edge.perSeed,
+      edgeCap: v3.edge.cap,
+    });
+
+    const rows = attributeSelections(result);
+    writeSelections(conversationId, turnIndex, rows);
+    return result;
+  } catch (err) {
+    log.warn(
+      { err: err instanceof Error ? err.message : String(err), conversationId },
+      "memory-v3 orchestration failed (non-fatal)",
+    );
+    return null;
+  }
+}
+
+/**
+ * Test-facing shadow wrapper: gate on the shadow flag, then run v3
+ * orchestration for one turn and log the selection set. Production injection
+ * goes through `produce()` → {@link observeTurn} directly (which checks both
+ * flags); this wrapper exists so tests can drive shadow observation in
+ * isolation. Never throws — all failures are logged and swallowed so the live
+ * turn is unaffected.
+ */
+export async function runShadowObservation(
+  conversationId: string,
+  turnIndex: number,
+): Promise<void> {
+  if (!isAssistantFeatureFlagEnabled(MEMORY_V3_SHADOW, getConfig())) return;
+  await observeTurn(conversationId, turnIndex);
+}

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

@@ -0,0 +1,92 @@
+export type Slug = string;
+
+/**
+ * Injection-block id for the v3 live `<memory>` block. Shared between the
+ * producer (the v3 injector in `shadow-plugin.ts`) and the v2-suppression
+ * consumer (`conversation-runtime-assembly.ts`), which keys off this id to
+ * detect that v3 actually produced a block this turn. Keeping it in one place
+ * makes a rename a compile error on both sides instead of a silent
+ * suppression bypass.
+ */
+export const MEMORY_V3_BLOCK_ID = "memory-v3" as const;
+
+/**
+ * A single section of a page: the lead (text before the first `## heading`,
+ * ordinal 0) or a heading-delimited block. Over-long sections are split into
+ * multiple ordered `Section`s, each with its own consecutive `ordinal`, so each
+ * fits a typical embedding window. `text` is prefixed with a
+ * `${lastSlugSegment} — ${title}` head line for lexical/dense matching.
+ */
+export interface Section {
+  article: Slug;
+  title: string;
+  text: string;
+  ordinal: number;
+}
+
+/**
+ * A flat, deterministic index of every page's sections plus an article→section
+ * lookup. `byArticle` maps each article slug to the indices (into `sections`)
+ * of that article's sections, in order.
+ */
+export interface SectionIndex {
+  sections: Section[];
+  byArticle: Map<Slug, number[]>;
+}
+
+/** A page selected from the candidate pool, with whether the turn centers on it. */
+export interface SelectedPage {
+  slug: Slug;
+  pinned: boolean;
+}
+
+export interface WorkingSetEntry {
+  slug: Slug;
+  selectedAtTurn: number;
+  pinned: boolean;
+  lastSeenTurn: number;
+}
+
+export interface MemoryRoutingTurn {
+  conversationId: string;
+  turnNumber: number;
+  currentMessage: string;
+  recentContext: string;
+  /**
+   * Optional situational signal — the current date plus the live NOW.md
+   * scratchpad — so a leaf or page can be routed/selected on a date or
+   * live-state cue the message itself never names (e.g. a person whose
+   * anniversary is today). Omitted when unavailable; the router and selector
+   * render nothing for an undefined value.
+   */
+  situationalContext?: string;
+}
+
+/**
+ * Canonical ordered list of the lane sources recorded per selection. The
+ * {@link SelectionSource} type is derived from this so a new lane is added in
+ * exactly one place and the runtime list (used for telemetry roll-ups and
+ * source validation) can never drift from the type.
+ *
+ * The `memory_v3_selections.source` column is free-text, so tightening this set
+ * needs no migration: any historical rows with older labels still read back
+ * fine via the permissive `z.string()` row schema.
+ */
+export const SELECTION_SOURCES = [
+  "needle",
+  "dense",
+  "edge",
+  "carry-forward",
+] as const;
+
+export type SelectionSource = (typeof SELECTION_SOURCES)[number];
+
+/**
+ * The candidate-generation lanes — the strict subset of {@link SelectionSource}
+ * a pooled candidate can be tagged with at pool-build time. (`carry-forward` is
+ * the one source assigned later, by the orchestrator's working-set union, not by
+ * a candgen lane.) Defined as `Exclude<SelectionSource, "carry-forward">` so it
+ * can never drift from {@link SELECTION_SOURCES}: adding a lane there widens this
+ * automatically.
+ */
+export type CandidateLane = Exclude<SelectionSource, "carry-forward">;

package/src/{memory/v3 → plugins/defaults/memory-v3-shadow}/working-set.ts

@@ -42,13 +42,16 @@ export class WorkingSet {
   /**
    * Prune the working set, in order:
    *   1. Core slugs never belong here — drop any entry whose slug is core.
+   *      The section-lane pipeline has no core set, so `coreSlugs` defaults to
+   *      empty (no-op); the tree pipeline passed its core slugs here. Stale and
+   *      cap eviction semantics are identical either way.
    *   2. Pinned entries never evict.
    *   3. Window eviction: drop a non-pinned entry unseen for more than
    *      `evictWindow` turns.
    *   4. Cap eviction: while over `maxPages`, evict the lowest-scoring
    *      non-pinned entry first (ties broken deterministically).
    */
-  evict(currentTurn: number, coreSlugs: Set<Slug>): void {
+  evict(currentTurn: number, coreSlugs: Set<Slug> = new Set()): void {
     // 1. Core slugs are owned by core, not the working set.
     for (const slug of this.entries.keys()) {
       if (coreSlugs.has(slug)) {

package/src/plugins/defaults/title-generate/package.json

@@ -5,7 +5,6 @@
   "private": true,
   "license": "MIT",
   "type": "module",
-  "main": "./register.ts",
   "engines": {
     "node": ">=20.12.0"
   },

package/src/plugins/defaults/tool-error/package.json

@@ -5,7 +5,6 @@
   "private": true,
   "license": "MIT",
   "type": "module",
-  "main": "./register.ts",
   "engines": {
     "node": ">=20.12.0"
   },

package/src/plugins/defaults/tool-result-truncate/package.json

@@ -5,7 +5,6 @@
   "private": true,
   "license": "MIT",
   "type": "module",
-  "main": "./register.ts",
   "engines": {
     "node": ">=20.12.0"
   },