@vellumai/assistant 0.8.5 → 0.8.7-dev.202606052118.34cd356

package/src/runtime/routes/memory-v3-routes.ts

@@ -1,316 +1,372 @@
 /**
- * Memory v3 route definitions — read-only diagnostics over the hand-authored
- * v3 tree DAG.
+ * Memory v3 route definitions — tree-gardening + core-editing operations for
+ * the leaf-tree memory model.
  *
- * Two operations, both side-effect-free (no LLM, no writes):
+ * The daemon owns the live tree, so the *mutating* gardening verbs
+ * (`reconcile`, `set-core --write`, `rebuild-index`) run here, inside the
+ * daemon process, where the in-memory shadow lanes can be invalidated after a
+ * write. The read-only `health` report and the `set-core` cost preview also
+ * route through the daemon so it stays the single source of truth for the live
+ * workspace tree.
  *
- *   - `memory_v3_validate` — returns the {@link TreeValidationReport} from
- *     `validateTree(workspaceDir)` (orphan pages, cycles, dangling refs,
- *     stale-index, unknown edge targets).
- *   - `memory_v3_tree` — returns a JSON-serializable view of
- *     `getTreeIndex(workspaceDir)`: the root id, every node id, and each
- *     node's ordered child refs. `TreeIndex` is Map-based, so the handler
- *     flattens it into arrays/objects the wire protocol can carry.
- *
- * The v3 tree is authored by the v2 → v3 data-migration; these routes are the
- * on-demand inspection surface operators run while that migration is in flight.
- * They are NOT invoked on any turn.
+ * Each route's behavior lives in a small DI-friendly `handle*` function that
+ * takes an optional `MemoryV3Deps` (filesystem overrides) so tests can drive it
+ * against a temp workspace without mocking module globals. The exported
+ * `RouteDefinition`s are thin `RouteHandlerArgs` adapters over those handlers.
  */
 
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
 import { z } from "zod";
 
-import { loadConfig } from "../../config/loader.js";
-import type { AssistantConfig } from "../../config/types.js";
-import { getDb } from "../../memory/db-connection.js";
+import { getPageIndex } from "../../memory/v2/page-index.js";
+import { loadCore } from "../../plugins/defaults/memory-v3-shadow/core.js";
+import {
+  computeV3Health,
+  renderV3Health,
+} from "../../plugins/defaults/memory-v3-shadow/health.js";
+import {
+  type LeafRef,
+  reconcileTree,
+} from "../../plugins/defaults/memory-v3-shadow/reconcile.js";
+import { invalidateLanes } from "../../plugins/defaults/memory-v3-shadow/shadow-plugin.js";
+import {
+  coreSlugs,
+  loadLeafTree,
+  resolveDataDir,
+} from "../../plugins/defaults/memory-v3-shadow/tree.js";
 import type {
-  RetrievalCost,
-  RetrievalInput,
-} from "../../memory/v2/harness/retriever.js";
-import type { DescentTrace } from "../../memory/v2/harness/trace.js";
-import { loadNowText } from "../../memory/v2/now-text.js";
-import type { LlmCallRecord } from "../../memory/v3/llm-capture.js";
-import { runRetrievalLoop } from "../../memory/v3/loop.js";
-import { getTreeIndex } from "../../memory/v3/tree-index.js";
-import type { TreeValidationReport } from "../../memory/v3/validate.js";
-import { validateTree } from "../../memory/v3/validate.js";
+  LeafPath,
+  LeafTree,
+  Slug,
+} from "../../plugins/defaults/memory-v3-shadow/types.js";
+import { getLogger } from "../../util/logger.js";
 import { getWorkspaceDir } from "../../util/platform.js";
+import { ACTOR_PRINCIPALS, type RoutePolicy } from "../auth/route-policy.js";
+import { RouteError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
-// Re-export the loop trace/cost shapes so the CLI renderer can import them from
-// this route module (type-only) without reaching across the
-// `cli/no-daemon-internals` boundary into `memory/v2/harness/*`.
-export type { RetrievalCost } from "../../memory/v2/harness/retriever.js";
-export type {
-  DescentPass,
-  DescentTrace,
-  EdgeExpansion,
-  GateDecision,
-  ScoutResult,
-  TreeLevel,
-} from "../../memory/v2/harness/trace.js";
-export type { LlmCallRecord };
+const log = getLogger("memory-v3-routes");
 
-// ── Validate ────────────────────────────────────────────────────────────
+/**
+ * Filesystem location overrides. Production callers omit these and the handlers
+ * resolve the live workspace; tests inject a temp workspace + data dir to
+ * exercise the handlers without mocking module globals.
+ */
+export interface MemoryV3Deps {
+  dataDir?: string;
+  workspaceDir?: string;
+}
 
-const MemoryV3ValidateParams = z.object({}).strict();
+// ---------------------------------------------------------------------------
+// Shared loading helpers
+// ---------------------------------------------------------------------------
 
 /**
- * Wire shape for `memory_v3_validate`. Identical to the daemon-internal
- * {@link TreeValidationReport} — every field is already serializable, so the
- * route forwards it verbatim. Re-exported as its own type so the CLI can
- * import it without reaching into the validator module.
+ * Load the live leaf tree + its full slug universe.
+ *
+ * Page `leaves:` frontmatter is the authoritative source of page→leaf
+ * membership: we build a `pageLeaves` map from the page index and union it over
+ * `assignments.json` via `loadLeafTree(dataDir, pageLeaves)`, and derive the
+ * slug universe (`allSlugs`) from the page index itself. This mirrors
+ * `maybePrependV3Health` in `memory/v2/consolidation-job.ts` so the CLI
+ * `health` / `set-core` cost computations agree with the consolidation-injected
+ * health block instead of disagreeing by reading stale assignments.json only.
  */
-export type MemoryV3ValidateResult = TreeValidationReport;
-
-async function handleValidate({
-  body = {},
-}: RouteHandlerArgs): Promise<MemoryV3ValidateResult> {
-  // Read-only structural validation of the v3 tree. Like the v2 validate
-  // route, it is intentionally ungated: operators dry-run it while the
-  // v2 → v3 migration is mid-flight, well before any v3 flag flips.
-  MemoryV3ValidateParams.parse(body);
-  return validateTree(getWorkspaceDir());
+async function loadTreeAndSlugs(deps?: MemoryV3Deps): Promise<{
+  dataDir: string;
+  tree: LeafTree;
+  allSlugs: Slug[];
+}> {
+  const workspaceDir = deps?.workspaceDir ?? getWorkspaceDir();
+  const dataDir = deps?.dataDir ?? resolveDataDir();
+
+  // Each page contributes its `leaves:` frontmatter as the authoritative leaf
+  // set for that slug; the slug universe is every page the index knows about.
+  const pageIndex = await getPageIndex(workspaceDir);
+  const pageLeaves = new Map<Slug, LeafPath[]>();
+  const allSlugs: Slug[] = [];
+  for (const entry of pageIndex.entries) {
+    pageLeaves.set(entry.slug, entry.leaves);
+    allSlugs.push(entry.slug);
+  }
+
+  const tree = await loadLeafTree(dataDir, pageLeaves);
+  return { dataDir, tree, allSlugs };
 }
 
-// ── Tree ────────────────────────────────────────────────────────────────
+// ---------------------------------------------------------------------------
+// health
+// ---------------------------------------------------------------------------
 
-const MemoryV3TreeParams = z.object({}).strict();
+const MemoryV3HealthResultSchema = z.object({
+  /** Pre-rendered, human-readable report. Empty string when all-green. */
+  rendered: z.string(),
+  /** The structural counts, for `--json` consumers. */
+  counts: z.object({
+    unassigned: z.number(),
+    danglingRefs: z.number(),
+    novelClusters: z.number(),
+    oversizedLeaves: z.number(),
+    tinyLeaves: z.number(),
+  }),
+});
+export type MemoryV3HealthResult = z.infer<typeof MemoryV3HealthResultSchema>;
 
-/** One node in the serialized tree view: its id and ordered child refs. */
-export interface MemoryV3TreeNodeView {
-  id: string;
-  children: Array<{ kind: "node" | "page"; ref: string }>;
+export async function handleMemoryV3Health(
+  deps?: MemoryV3Deps,
+): Promise<MemoryV3HealthResult> {
+  const { dataDir, tree, allSlugs } = await loadTreeAndSlugs(deps);
+  const core = await loadCore(dataDir);
+  const report = computeV3Health({ tree, allSlugs, core });
+  return {
+    rendered: renderV3Health(report),
+    counts: {
+      unassigned: report.unassigned.length,
+      danglingRefs: report.danglingRefs.length,
+      novelClusters: report.novelClusters.length,
+      oversizedLeaves: report.oversizedLeaves.length,
+      tinyLeaves: report.tinyLeaves.length,
+    },
+  };
 }
 
-/**
- * JSON-serializable projection of the {@link TreeIndex}. `TreeIndex` keys its
- * adjacency by `Map`, which doesn't survive JSON, so the handler flattens it:
- * `root` is the entry-point node id and `nodes` is every node with its ordered
- * child refs. The CLI renderer walks `nodes`/`root` to print an indented tree,
- * marking shared-DAG re-entries.
- */
-export interface MemoryV3TreeResult {
-  root: string;
-  nodes: MemoryV3TreeNodeView[];
-}
+// ---------------------------------------------------------------------------
+// set-core
+// ---------------------------------------------------------------------------
 
-async function handleTree({
-  body = {},
-}: RouteHandlerArgs): Promise<MemoryV3TreeResult> {
-  MemoryV3TreeParams.parse(body);
+const MemoryV3SetCoreBodySchema = z.object({
+  /** Leaves to add to the always-on core set. */
+  add: z.array(z.string()).optional(),
+  /** Leaves to remove from the always-on core set. */
+  remove: z.array(z.string()).optional(),
+  /**
+   * When true, persist the new core to `core.json` and invalidate the lanes.
+   * When false (default), compute the preview WITHOUT writing.
+   */
+  write: z.boolean().optional(),
+});
+export type MemoryV3SetCoreBody = z.infer<typeof MemoryV3SetCoreBodySchema>;
 
-  const tree = await getTreeIndex(getWorkspaceDir());
+const MemoryV3SetCoreResultSchema = z.object({
+  /** The core leaf set that would result (or did result, when `write`). */
+  nextCore: z.array(z.string()),
+  /** Number of unique page slugs the new core set pins always-on. */
+  alwaysOnPageCount: z.number(),
+  /** Whether `core.json` was written. */
+  written: z.boolean(),
+});
+export type MemoryV3SetCoreResult = z.infer<typeof MemoryV3SetCoreResultSchema>;
 
-  const nodes: MemoryV3TreeNodeView[] = [...tree.nodes.keys()]
-    .sort()
-    .map((id) => ({
-      id,
-      children: (tree.childrenByNode.get(id) ?? []).map((child) => ({
-        kind: child.kind,
-        ref: child.ref,
-      })),
-    }));
+/** Wire-format error code for a `set-core` add referencing an unknown leaf. */
+export const MEMORY_V3_UNKNOWN_LEAF_CODE = "MEMORY_V3_UNKNOWN_LEAF";
 
-  return { root: tree.root, nodes };
+/** Thrown when a `set-core` add entry does not exist in the live tree. */
+export class UnknownLeafError extends Error {
+  constructor(public readonly unknown: LeafPath[]) {
+    super(
+      `Unknown leaf path(s) — not present in the tree: ${unknown.join(", ")}`,
+    );
+    this.name = "UnknownLeafError";
+  }
 }
 
-// ── Simulate ──────────────────────────────────────────────────────────────
-
-/** The five v3 retrieval lanes, in fanout order. */
-const V3_LANE_NAMES = ["hot", "sparse", "dense", "tree", "edges"] as const;
-
-const MemoryV3SimulateParams = z
-  .object({
-    /** The ad-hoc user query to route a single synthetic turn against. */
-    query: z.string().min(1, "memory.v3.simulate query must be non-empty"),
-    /**
-     * Optional `<now>` override. When omitted the live workspace NOW.md is
-     * loaded so the run exercises production-like standing context.
-     */
-    nowText: z.string().optional(),
-    /** Override `memory.v3.passCap` for this run only. */
-    passCap: z
-      .number()
-      .int("memory.v3.simulate passCap must be an integer")
-      .positive("memory.v3.simulate passCap must be positive")
-      .optional(),
-    /**
-     * Restrict the run to this allowlist of lanes (others forced off). Omit to
-     * inherit the live `memory.v3.lanes` toggles.
-     */
-    lanes: z.array(z.enum(V3_LANE_NAMES)).optional(),
-  })
-  .strict();
-
-/** The v3 lane toggle block, echoed back so the caller sees what actually ran. */
-export interface MemoryV3SimulateLanes {
-  hot: boolean;
-  sparse: boolean;
-  dense: boolean;
-  tree: boolean;
-  edges: boolean;
+/** Persist the always-on core set back to `<dataDir>/core.json`. */
+async function writeCore(dataDir: string, alwaysOn: LeafPath[]): Promise<void> {
+  await writeFile(
+    join(dataDir, "core.json"),
+    `${JSON.stringify({ alwaysOn }, null, 2)}\n`,
+  );
 }
 
-/**
- * Wire shape for `memory_v3_simulate`. The loop's `sourceBySlug` Map is
- * flattened to a plain object (lane label per slug); `trace`/`cost` are already
- * JSON-serializable. `effectiveConfig` echoes the passCap + lane toggles the
- * run actually used after overrides were applied.
- */
-export interface MemoryV3SimulateResult {
-  query: string;
-  selectedSlugs: string[];
-  /** Per-slug provenance lane: `hot` | `sparse` | `dense` | `tree` | `edge`. */
-  sourceBySlug: Record<string, string>;
-  trace: DescentTrace;
-  cost: RetrievalCost;
-  /** Non-null when the dense filter failed open on any pass. */
-  failureReason: string | null;
-  /**
-   * Every v3 LLM call made during the run (filter / each descender / gate),
-   * with full input + raw response. Empty unless capture was on (it always is
-   * for simulate). Read-only debug surface — persisted nowhere.
-   */
-  llmCalls: LlmCallRecord[];
-  effectiveConfig: {
-    passCap: number;
-    lanes: MemoryV3SimulateLanes;
-  };
+export async function handleMemoryV3SetCore(
+  body: MemoryV3SetCoreBody,
+  deps?: MemoryV3Deps,
+): Promise<MemoryV3SetCoreResult> {
+  const add = body.add ?? [];
+  const remove = body.remove ?? [];
+  const { dataDir, tree } = await loadTreeAndSlugs(deps);
+
+  // Validate every ADD entry exists in the live tree. Removing an entry that is
+  // already absent is a no-op (idempotent), so only adds are validated.
+  const unknown = add.filter((leaf) => !tree.leaves.has(leaf));
+  if (unknown.length > 0) throw new UnknownLeafError(unknown);
+
+  const core = await loadCore(dataDir);
+  for (const leaf of remove) core.delete(leaf);
+  for (const leaf of add) core.add(leaf);
+
+  // Drop any pre-existing core entry that no longer maps to a live leaf, so the
+  // preview reflects what the tree can actually pin. Sorted for stable output.
+  const nextCore = [...core].filter((leaf) => tree.leaves.has(leaf)).sort();
+  const nextCoreSet = new Set<LeafPath>(nextCore);
+
+  // Cost preview: the number of UNIQUE page slugs the new core pins always-on.
+  const alwaysOnPageCount = coreSlugs(tree, nextCoreSet).size;
+
+  if (body.write === true) {
+    await writeCore(dataDir, nextCore);
+    invalidateLanes();
+    log.info(
+      { coreSize: nextCore.length, alwaysOnPageCount },
+      "memory-v3 core updated",
+    );
+  }
+
+  return { nextCore, alwaysOnPageCount, written: body.write === true };
 }
 
+// ---------------------------------------------------------------------------
+// reconcile
+// ---------------------------------------------------------------------------
+
+const MemoryV3ReconcileResultSchema = z.object({
+  renames: z.array(
+    z.object({
+      id: z.string().optional(),
+      oldPath: z.string(),
+      newPath: z.string(),
+    }),
+  ),
+  deleted: z.array(z.string()),
+  prunedCore: z.array(z.string()),
+});
+export type MemoryV3ReconcileResult = z.infer<
+  typeof MemoryV3ReconcileResultSchema
+>;
+
 /**
- * Overlay the simulate overrides on the live config. Only the v3 passCap + lane
- * toggles are exposed; everything else (providers, prompts, scout quotas) stays
- * exactly as a live turn would see it. `write.coactivation` is forced off so the
- * simulate stays strictly read-only — the loop's only persistence path is the
- * co-activation insert, which this guarantees never fires.
+ * Reconcile page + core references against the live on-disk tree.
+ *
+ * `prevLeaves` describes the tree as it was BEFORE the maintainer's on-disk
+ * restructuring. We derive it from the current leaf set, which makes reconcile
+ * a safe convergence pass: renames/deletes already applied on disk diff to
+ * nothing, while it still rewrites any page/core ref left dangling and prunes
+ * stale core entries (and fail-closed restores on a residual dangling ref).
+ * `reconcileTree` snapshots, applies, validates, and invalidates the lanes.
  */
-function applyV3SimulateOverrides(
-  live: AssistantConfig,
-  overrides: { passCap?: number; lanes?: ReadonlyArray<string> },
-): AssistantConfig {
-  const liveV3 = live.memory.v3;
-  const lanes = overrides.lanes
-    ? {
-        hot: overrides.lanes.includes("hot"),
-        sparse: overrides.lanes.includes("sparse"),
-        dense: overrides.lanes.includes("dense"),
-        tree: overrides.lanes.includes("tree"),
-        edges: overrides.lanes.includes("edges"),
-      }
-    : liveV3.lanes;
+export async function handleMemoryV3Reconcile(
+  deps?: MemoryV3Deps,
+): Promise<MemoryV3ReconcileResult> {
+  const workspaceDir = deps?.workspaceDir ?? getWorkspaceDir();
+  const dataDir = deps?.dataDir ?? resolveDataDir();
+  // v1: prev == current is intentional. Without a captured prior leaf snapshot
+  // we cannot detect renames/moves/splits, so this runs as a convergence /
+  // dangling-ref prune pass. Full rename detection is a follow-up.
+  const prevLeaves = await loadPrevLeaves(dataDir);
+
+  const result = await reconcileTree({ prevLeaves, dataDir, workspaceDir });
   return {
-    ...live,
-    memory: {
-      ...live.memory,
-      v3: {
-        ...liveV3,
-        ...(overrides.passCap !== undefined
-          ? { passCap: overrides.passCap }
-          : {}),
-        lanes,
-        write: { ...liveV3.write, coactivation: false },
-      },
-    },
+    renames: result.renames,
+    deleted: result.deleted,
+    prunedCore: result.prunedCore,
   };
 }
 
-/**
- * Run the v3 retrieval loop read-only against a single ad-hoc query and return
- * its selection, per-lane provenance, and full descent trace. Mirrors the
- * single-turn semantics of `memory_v2_simulate_router` (the query becomes the
- * just-arrived `userMessage` of one synthetic turn) and the input-build of the
- * v3 shadow middleware, but persists nothing.
- *
- * The loop is invoked directly — it is NOT gated by `memory.v3.enabled` /
- * `.shadow` (those gates live in the shadow middleware), so operators can probe
- * v3 retrieval while the flags are still off.
- */
-async function handleSimulate({
-  body = {},
-}: RouteHandlerArgs): Promise<MemoryV3SimulateResult> {
-  const {
-    query,
-    nowText: rawNowText,
-    passCap,
-    lanes,
-  } = MemoryV3SimulateParams.parse(body);
-
-  const config = applyV3SimulateOverrides(loadConfig(), { passCap, lanes });
-
-  const workspaceDir = getWorkspaceDir();
-  const nowText =
-    rawNowText !== undefined ? rawNowText : await loadNowText(workspaceDir);
-
-  const input: RetrievalInput = {
-    workspaceDir,
-    recentTurnPairs: [{ assistantMessage: "", userMessage: query }],
-    nowText,
-    priorEverInjected: [],
-    config,
-  };
+/** The current leaf set as `LeafRef`s (path + stable id when present). */
+async function loadPrevLeaves(dataDir: string): Promise<LeafRef[]> {
+  const tree = await loadLeafTree(dataDir);
+  return [...tree.leaves.values()].map((node) => ({
+    path: node.path,
+    ...(node.frontmatter.id ? { id: node.frontmatter.id } : {}),
+  }));
+}
 
-  const llmCalls: LlmCallRecord[] = [];
-  const output = await runRetrievalLoop(input, {
-    db: getDb(),
-    capture: (record) => llmCalls.push(record),
-  });
+// ---------------------------------------------------------------------------
+// rebuild-index
+// ---------------------------------------------------------------------------
 
-  const sourceBySlug: Record<string, string> = {};
-  for (const [slug, lane] of output.sourceBySlug.entries()) {
-    sourceBySlug[slug] = lane;
-  }
+const MemoryV3RebuildIndexResultSchema = z.object({
+  ok: z.literal(true),
+});
+export type MemoryV3RebuildIndexResult = z.infer<
+  typeof MemoryV3RebuildIndexResultSchema
+>;
 
-  return {
-    query,
-    selectedSlugs: output.selectedSlugs,
-    sourceBySlug,
-    trace: output.trace ?? { passes: [] },
-    cost: output.cost ?? {},
-    failureReason: output.failureReason ?? null,
-    llmCalls,
-    effectiveConfig: {
-      passCap: config.memory.v3.passCap,
-      lanes: config.memory.v3.lanes,
-    },
-  };
+/**
+ * Invalidate the v3 shadow lanes so the next turn rebuilds the tree/needle
+ * from the current on-disk state. Runs in-daemon so it acts on the live
+ * process's cached lanes (an in-CLI call would invalidate nothing).
+ */
+export async function handleMemoryV3RebuildIndex(): Promise<MemoryV3RebuildIndexResult> {
+  invalidateLanes();
+  log.info("memory-v3 lanes invalidated (rebuild-index)");
+  return { ok: true };
 }
 
-// ── Route definitions ───────────────────────────────────────────────────
+// ---------------------------------------------------------------------------
+// Route definitions (RouteHandlerArgs adapters over the handlers above)
+// ---------------------------------------------------------------------------
+
+/** Read-only verbs (the `health` report) require only `settings.read`. */
+const READ_POLICY: RoutePolicy = {
+  requiredScopes: ["settings.read"],
+  allowedPrincipalTypes: ACTOR_PRINCIPALS,
+};
+
+/**
+ * Mutating verbs require `settings.write`. `set-core --write`, `reconcile`, and
+ * `rebuild-index` write `core.json`, rewrite page frontmatter, and invalidate
+ * the live lanes, so a `settings.read`-only principal must not reach them.
+ * (`set-core` without `write` is a preview, but it shares this route, so the
+ * route as a whole is gated on write.)
+ */
+const WRITE_POLICY: RoutePolicy = {
+  requiredScopes: ["settings.write"],
+  allowedPrincipalTypes: ACTOR_PRINCIPALS,
+};
 
 export const ROUTES: RouteDefinition[] = [
   {
-    operationId: "memory_v3_validate",
+    operationId: "memory_v3_health",
     method: "POST",
-    endpoint: "memory/v3/validate",
-    handler: handleValidate,
-    summary: "Validate the memory v3 tree structure (read-only)",
-    description:
-      "Read-only structural validation of the hand-authored v3 tree DAG. Reports dangling child refs, orphan pages, cycles, stale compositional indexes, and unknown edge targets. Writes nothing and runs no LLM — operators dry-run it while the v2 → v3 migration is in flight.",
+    policy: READ_POLICY,
+    endpoint: "memory/v3/health",
+    handler: () => handleMemoryV3Health(),
+    summary: "Print the v3 structural health report (read-only)",
     tags: ["memory"],
-    requestBody: MemoryV3ValidateParams,
+    responseBody: MemoryV3HealthResultSchema,
   },
   {
-    operationId: "memory_v3_tree",
+    operationId: "memory_v3_set_core",
     method: "POST",
-    endpoint: "memory/v3/tree",
-    handler: handleTree,
-    summary: "Return a serializable view of the memory v3 tree DAG (read-only)",
-    description:
-      "Returns the v3 tree root id plus every node and its ordered child refs (page:/node:) as a JSON-serializable projection of the in-memory TreeIndex. Read-only; the CLI uses it to print an indented tree with shared-DAG re-entries marked.",
+    policy: WRITE_POLICY,
+    endpoint: "memory/v3/set-core",
+    handler: async ({ body = {} }: RouteHandlerArgs) => {
+      try {
+        return await handleMemoryV3SetCore(body as MemoryV3SetCoreBody);
+      } catch (err) {
+        if (err instanceof UnknownLeafError) {
+          throw new RouteError(err.message, MEMORY_V3_UNKNOWN_LEAF_CODE, 422);
+        }
+        throw err;
+      }
+    },
+    summary: "Add/remove always-on core leaves (validates + previews cost)",
     tags: ["memory"],
-    requestBody: MemoryV3TreeParams,
+    requestBody: MemoryV3SetCoreBodySchema,
+    responseBody: MemoryV3SetCoreResultSchema,
   },
   {
-    operationId: "memory_v3_simulate",
+    operationId: "memory_v3_reconcile",
     method: "POST",
-    endpoint: "memory/v3/simulate",
-    handler: handleSimulate,
+    policy: WRITE_POLICY,
+    endpoint: "memory/v3/reconcile",
+    handler: () => handleMemoryV3Reconcile(),
     summary:
-      "Dry-run the v3 retrieval loop against an ad-hoc query (read-only)",
-    description:
-      "Runs the v3 multi-lane bounded-descent retrieval loop read-only against a single synthetic turn built from the supplied query plus the live (or supplied) NOW context. Returns the selected page slugs, per-lane provenance, the full multi-pass descent trace, and accumulated cost. Optional passCap / lane-allowlist overrides apply on top of live config. Invoked directly (not gated by memory.v3.enabled/shadow) so operators can probe v3 retrieval before flipping the flags; writes nothing (co-activation persistence is forced off), though each pass still spends the loop's filter + gate LLM calls.",
+      "v1 convergence/prune pass over page+core refs (no rename detection without a prior snapshot)",
+    tags: ["memory"],
+    responseBody: MemoryV3ReconcileResultSchema,
+  },
+  {
+    operationId: "memory_v3_rebuild_index",
+    method: "POST",
+    policy: WRITE_POLICY,
+    endpoint: "memory/v3/rebuild-index",
+    handler: () => handleMemoryV3RebuildIndex(),
+    summary: "Invalidate the v3 lanes so the next turn rebuilds",
     tags: ["memory"],
-    requestBody: MemoryV3SimulateParams,
+    responseBody: MemoryV3RebuildIndexResultSchema,
   },
 ];

package/src/runtime/routes/migration-rollback-routes.ts

@@ -19,6 +19,7 @@ import {
   loadCheckpoints,
   rollbackWorkspaceMigrations,
 } from "../../workspace/migrations/runner.js";
+import { GATEWAY_PRINCIPALS } from "../auth/route-policy.js";
 import { BadRequestError, InternalError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
@@ -160,11 +161,14 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "admin_rollbackmigrations_post",
     endpoint: "admin/rollback-migrations",
     method: "POST",
+    policy: {
+      requiredScopes: ["internal.write"],
+      allowedPrincipalTypes: GATEWAY_PRINCIPALS,
+    },
     summary: "Rollback migrations",
     description:
       "Roll back DB and/or workspace migrations to a specified target version. Restricted to gateway service principals.",
     tags: ["admin"],
-    requirePolicyEnforcement: true,
     handler: handleRollbackMigrations,
     requestBody: z.object({
       targetDbVersion: z