@remnic/core 9.3.762 → 9.3.764

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remnic/core",
-  "version": "9.3.762",
+  "version": "9.3.764",
   "description": "Framework-agnostic Remnic memory engine — orchestrator, storage, extraction, search, trust zones",
   "type": "module",
   "main": "dist/index.js",
@@ -3000,7 +3000,7 @@
     "core"
   ],
   "peerDependencies": {
-    "@remnic/coding-graph": "^9.3.762"
+    "@remnic/coding-graph": "^9.3.764"
   },
   "peerDependenciesMeta": {
     "@remnic/coding-graph": {

package/src/access-service.ts

@@ -2121,8 +2121,8 @@ export class EngramAccessService {
     if (!includeDebug) return undefined;
     if (!sessionKey?.trim()) return undefined;
     const [intent, graph] = await Promise.all([
-      this.orchestrator.getLastIntentSnapshot(namespace),
-      this.orchestrator.getLastGraphRecallSnapshot(namespace),
+      this.orchestrator.recallIntrospection.getLastIntentSnapshot(namespace),
+      this.orchestrator.recallIntrospection.getLastGraphRecallSnapshot(namespace),
     ]);
     return snapshot || intent || graph
       ? {
@@ -2831,8 +2831,8 @@ export class EngramAccessService {
     })();
     if (!namespace) return { found: false };
     const [intent, graph] = await Promise.all([
-      this.orchestrator.getLastIntentSnapshot(namespace),
-      this.orchestrator.getLastGraphRecallSnapshot(namespace),
+      this.orchestrator.recallIntrospection.getLastIntentSnapshot(namespace),
+      this.orchestrator.recallIntrospection.getLastGraphRecallSnapshot(namespace),
     ]);
     if (!readableSnapshot && !intent && !graph) return { found: false };
     return { found: true, snapshot: readableSnapshot ?? undefined, intent, graph };
@@ -4817,17 +4817,17 @@ export class EngramAccessService {
   }
 
   async intentDebug(namespace?: string): Promise<unknown> {
-    const snapshot = await this.orchestrator.getLastIntentSnapshot(namespace);
+    const snapshot = await this.orchestrator.recallIntrospection.getLastIntentSnapshot(namespace);
     return snapshot ?? { message: "No intent debug snapshot available" };
   }
 
   async qmdDebug(namespace?: string): Promise<unknown> {
-    const snapshot = await this.orchestrator.getLastQmdRecallSnapshot(namespace);
+    const snapshot = await this.orchestrator.recallIntrospection.getLastQmdRecallSnapshot(namespace);
     return snapshot ?? { message: "No QMD debug snapshot available" };
   }
 
   async graphExplainLastRecall(namespace?: string): Promise<unknown> {
-    const explanation = await this.orchestrator.explainLastGraphRecall({ namespace });
+    const explanation = await this.orchestrator.recallIntrospection.explainLastGraphRecall({ namespace });
     return { explanation };
   }
 

package/src/maintenance/purge.test.ts

@@ -5,6 +5,9 @@ import path from "node:path";
 import test from "node:test";
 
 import { purgeMemories } from "./purge.js";
+import { rebuildMemoryProjection } from "./rebuild-memory-projection.js";
+import { readProjectedMemoryBrowse } from "../memory-projection-store.js";
+import { StorageManager } from "../storage.js";
 import type { MemoryFile } from "../types.js";
 
 test("purgeMemories records audit errors without blocking hard delete", async () => {
@@ -54,6 +57,79 @@ test("purgeMemories records audit errors without blocking hard delete", async ()
   }
 });
 
+test("purgeMemories invalidates projection rows for hard-deleted memories", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-purge-projection-"));
+  try {
+    const storage = new StorageManager(dir);
+    const { id } = await storage.writeMemory("fact", "purge projection target", {
+      source: "test",
+    });
+    const memory = await storage.getMemoryById(id);
+    assert.ok(memory);
+    await rebuildMemoryProjection({ memoryDir: dir, dryRun: false });
+    assert.equal(readProjectedMemoryBrowse(dir, { limit: 5, offset: 0 })?.total, 1);
+
+    const result = await purgeMemories({
+      storage,
+      olderThanMs: 1,
+      tier: "all",
+      dryRun: false,
+      now: () => new Date(Date.now() + 86_400_000),
+    });
+
+    assert.equal(result.purgedCount, 1);
+    assert.equal(readProjectedMemoryBrowse(dir, { limit: 5, offset: 0 })?.total, 0);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("purgeMemories invalidates projection rows for already-absent files but not failed deletes, and dry-run never mutates", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-purge-projection-branches-"));
+  try {
+    // Real projection with two rows; candidates come from a mock storage so the
+    // unlink outcomes are deterministic: one path is already absent (ENOENT),
+    // the other is a non-empty directory (unlink fails, not ENOENT).
+    const realStorage = new StorageManager(dir);
+    const first = await realStorage.writeMemory("fact", "purge branch enoent", { source: "test" });
+    const second = await realStorage.writeMemory("fact", "purge branch failure", { source: "test" });
+    await rebuildMemoryProjection({ memoryDir: dir, dryRun: false });
+    assert.equal(readProjectedMemoryBrowse(dir, { limit: 5, offset: 0 })?.total, 2);
+
+    const firstMemory = await realStorage.getMemoryById(first.id);
+    const secondMemory = await realStorage.getMemoryById(second.id);
+    assert.ok(firstMemory && secondMemory);
+    await rm(firstMemory.path);
+    await rm(secondMemory.path);
+    await mkdir(secondMemory.path);
+    await writeFile(path.join(secondMemory.path, "block.txt"), "x", "utf8");
+
+    const mockStorage = {
+      dir,
+      readAllMemories: async () => [firstMemory, secondMemory],
+      readAllColdMemories: async () => [],
+      readArchivedMemories: async () => [],
+    };
+    const future = () => new Date(Date.now() + 86_400_000);
+
+    // Dry-run: no projection mutation.
+    await purgeMemories({ storage: mockStorage as never, olderThanMs: 1, tier: "all", dryRun: true, now: future });
+    assert.equal(readProjectedMemoryBrowse(dir, { limit: 5, offset: 0 })?.total, 2);
+
+    const result = await purgeMemories({ storage: mockStorage as never, olderThanMs: 1, tier: "all", dryRun: false, now: future });
+
+    assert.equal(result.alreadyAbsentCount, 1);
+    assert.equal(result.purgedCount, 0);
+    assert.equal(result.errors.filter((e) => e.id === second.id).length, 1);
+    const page = readProjectedMemoryBrowse(dir, { limit: 5, offset: 0 });
+    assert.ok(page);
+    // ENOENT row invalidated; failed-delete row keeps its projection entry.
+    assert.equal(page.total, 1);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
 async function fileExists(filePath: string): Promise<boolean> {
   try {
     await access(filePath);

package/src/maintenance/purge.ts

@@ -23,6 +23,7 @@ import path from "node:path";
 import { appendFile, mkdir, unlink } from "node:fs/promises";
 import type { StorageManager } from "../storage.js";
 import type { MemoryFile } from "../types.js";
+import { markProjectedMemoryPathInvalid } from "../memory-projection-store.js";
 import type { SearchBackend } from "../search/port.js";
 
 export type PurgeTierFilter = "cold" | "all";
@@ -236,12 +237,14 @@ export async function purgeMemories(
       await unlink(candidate.path);
       actuallyPurged.push(candidate);
       addCollectionForCandidate(candidate);
+      markProjectedMemoryPathInvalid(storage.dir, candidate.id);
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
       // ENOENT is fine — already gone
       if (hasErrorCode(err, "ENOENT")) {
         alreadyAbsent.push(candidate);
         addCollectionForCandidate(candidate);
+        markProjectedMemoryPathInvalid(storage.dir, candidate.id);
       } else {
         errors.push({ id: candidate.id, path: candidate.path, error: message });
       }

package/src/maintenance/rebuild-memory-projection.ts

@@ -24,6 +24,7 @@ import {
 import {
   getMemoryProjectionPath,
   initializeMemoryProjectionDb,
+  isProjectedMemoryPathValid,
   type ProjectedEntityMentionRow,
   type MemoryProjectionGovernanceAppliedActionRow,
   type MemoryProjectionGovernanceReviewQueueRow,
@@ -794,6 +795,7 @@ function writeProjectionDb(
   usedLifecycleLedger: boolean,
 ): void {
   const db = openBetterSqlite3(dbPath);
+  const memoryDir = path.dirname(path.dirname(dbPath));
   try {
     initializeMemoryProjectionDb(db);
 
@@ -810,6 +812,7 @@ function writeProjectionDb(
         status,
         lifecycle_state,
         path_rel,
+        path_valid,
         created_at,
         updated_at,
         archived_at,
@@ -823,7 +826,7 @@ function writeProjectionDb(
         last_accessed,
         tags_json,
         preview_text
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `);
 
     const insertTimeline = db.prepare(`
@@ -921,6 +924,7 @@ function writeProjectionDb(
           row.status,
           row.lifecycleState ?? null,
           row.pathRel,
+          isProjectedMemoryPathValid(memoryDir, row.pathRel) ? 1 : 0,
           row.created,
           row.updated,
           row.archivedAt ?? null,

package/src/memory-projection-store.ts

@@ -17,7 +17,7 @@ import {
   type BetterSqlite3Database,
 } from "./runtime/better-sqlite.js";
 
-export const MEMORY_PROJECTION_SCHEMA_VERSION = 2;
+export const MEMORY_PROJECTION_SCHEMA_VERSION = 3;
 
 export interface ProjectedMemoryBrowseOptions {
   query?: string;
@@ -153,11 +153,13 @@ function migrateProjectionSchemaIfNeeded(memoryDir: string): void {
 export function memoryCurrentSelectExpressions(db: BetterSqlite3Database): {
   tagsJson: string;
   previewText: string;
+  hasPathValid: boolean;
 } {
   const columns = listTableColumns(db, "memory_current");
   return {
     tagsJson: columns.has("tags_json") ? "tags_json" : `'[]' AS tags_json`,
     previewText: columns.has("preview_text") ? "preview_text" : `'' AS preview_text`,
+    hasPathValid: columns.has("path_valid"),
   };
 }
 
@@ -174,6 +176,7 @@ export function initializeMemoryProjectionDb(db: BetterSqlite3Database): void {
       status TEXT NOT NULL,
       lifecycle_state TEXT,
       path_rel TEXT NOT NULL,
+      path_valid INTEGER NOT NULL DEFAULT 0 CHECK (path_valid IN (0, 1)),
       created_at TEXT NOT NULL,
       updated_at TEXT NOT NULL,
       archived_at TEXT,
@@ -195,8 +198,6 @@ export function initializeMemoryProjectionDb(db: BetterSqlite3Database): void {
     CREATE INDEX IF NOT EXISTS idx_memory_current_category
       ON memory_current(category);
 
-    CREATE INDEX IF NOT EXISTS idx_memory_current_updated
-      ON memory_current(updated_at DESC);
 
     CREATE TABLE IF NOT EXISTS memory_timeline (
       event_id TEXT PRIMARY KEY,
@@ -297,6 +298,18 @@ export function initializeMemoryProjectionDb(db: BetterSqlite3Database): void {
   `);
 
   migrateMemoryCurrentTable(db);
+  if (listTableColumns(db, "memory_current").has("path_valid")) {
+    db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_memory_current_browse_updated_desc
+        ON memory_current(path_valid, updated_at DESC, created_at DESC, memory_id ASC);
+      CREATE INDEX IF NOT EXISTS idx_memory_current_browse_updated_asc
+        ON memory_current(path_valid, updated_at ASC, created_at ASC, memory_id ASC);
+      CREATE INDEX IF NOT EXISTS idx_memory_current_browse_created_desc
+        ON memory_current(path_valid, created_at DESC, updated_at DESC, memory_id ASC);
+      CREATE INDEX IF NOT EXISTS idx_memory_current_browse_created_asc
+        ON memory_current(path_valid, created_at ASC, updated_at ASC, memory_id ASC);
+    `);
+  }
   db.prepare("INSERT OR REPLACE INTO meta(key, value) VALUES (?, ?)")
     .run("schemaVersion", String(MEMORY_PROJECTION_SCHEMA_VERSION));
 }
@@ -309,6 +322,42 @@ function openProjectionReadonly(memoryDir: string): BetterSqlite3Database | null
     return null;
   }
 }
+function updateProjectionBestEffort(
+  memoryDir: string,
+  sql: string,
+  params: unknown[],
+): void {
+  let db: BetterSqlite3Database | null = null;
+  try {
+    db = openBetterSqlite3(getMemoryProjectionPath(memoryDir), { fileMustExist: true });
+    db.prepare(sql).run(...params);
+  } catch {
+    // Projection updates must never block the canonical filesystem mutation.
+  } finally {
+    db?.close();
+  }
+}
+
+export function markProjectedMemoryPathInvalid(memoryDir: string, memoryId: string): void {
+  updateProjectionBestEffort(
+    memoryDir,
+    "UPDATE memory_current SET path_valid = 0 WHERE memory_id = ?",
+    [memoryId],
+  );
+}
+
+export function updateProjectedMemoryPath(
+  memoryDir: string,
+  memoryId: string,
+  pathRel: string,
+): void {
+  const pathValid = isProjectedMemoryPathValid(memoryDir, pathRel) ? 1 : 0;
+  updateProjectionBestEffort(
+    memoryDir,
+    "UPDATE memory_current SET path_rel = ?, path_valid = ? WHERE memory_id = ?",
+    [pathRel, pathValid, memoryId],
+  );
+}
 
 function withProjectionReadonly<T>(
   memoryDir: string,
@@ -363,7 +412,11 @@ function isPathInsideRoot(candidatePath: string, rootPath: string): boolean {
   return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
 }
 
-function resolveProjectedMemoryPath(memoryDir: string, pathRel: string): string | null {
+function resolveProjectedMemoryPath(
+  memoryDir: string,
+  pathRel: string,
+  requireExisting = false,
+): string | null {
   if (path.isAbsolute(pathRel)) return null;
   const root = resolveMemoryDirRoot(memoryDir);
   const candidate = path.resolve(root, pathRel);
@@ -372,14 +425,21 @@ function resolveProjectedMemoryPath(memoryDir: string, pathRel: string): string
     const realCandidate = fs.realpathSync(candidate);
     if (!isPathInsideRoot(realCandidate, root)) return null;
   } catch {
+    if (requireExisting) return null;
     // Missing files are handled by callers. Still keep the lexical guard above.
   }
   return candidate;
 }
 
+export function isProjectedMemoryPathValid(memoryDir: string, pathRel: string): boolean {
+  return resolveProjectedMemoryPath(memoryDir, pathRel) !== null;
+}
+
 function projectedBrowseRowFromCurrentRow(
   memoryDir: string,
   row: Record<string, unknown>,
+  resolvedFilePath?: string,
+  requireExisting = false,
 ): ProjectedMemoryBrowseRow | null {
   if (
     typeof row.memory_id !== "string" ||
@@ -389,7 +449,7 @@ function projectedBrowseRowFromCurrentRow(
   ) {
     return null;
   }
-  const filePath = resolveProjectedMemoryPath(memoryDir, row.path_rel);
+  const filePath = resolvedFilePath ?? resolveProjectedMemoryPath(memoryDir, row.path_rel, requireExisting);
   if (!filePath) return null;
   return {
     id: row.memory_id,
@@ -613,8 +673,15 @@ export function readProjectedMemoryBrowse(
     const whereSql = whereClauses.length > 0 ? `WHERE ${whereClauses.join(" AND ")}` : "";
 
     if (normalizedQuery) {
-      // Query-based browse: fetch all matching rows, filter by full file content, then paginate in JS
-      const allRows = db
+      // Full-content search still examines every eligible row so totals and
+      // matches stay exact, but iteration keeps memory use proportional to the page.
+      const queryWhereClauses = currentSelect.hasPathValid
+        ? [...whereClauses, ...projectedBrowsePathSqlClauses(), "path_valid = 1"]
+        : whereClauses;
+      const queryWhereSql = queryWhereClauses.length > 0
+        ? `WHERE ${queryWhereClauses.join(" AND ")}`
+        : "";
+      const rows = db
         .prepare(`
           SELECT
             memory_id,
@@ -627,47 +694,88 @@ export function readProjectedMemoryBrowse(
             ${currentSelect.tagsJson},
             ${currentSelect.previewText}
           FROM memory_current
-          ${whereSql}
+          ${queryWhereSql}
           ORDER BY ${orderBySql}
         `)
-        .all(...params) as Array<Record<string, unknown>>;
+        .iterate(...params) as Iterable<Record<string, unknown>>;
+      const pageRows: ProjectedMemoryBrowseRow[] = [];
+      let total = 0;
 
-      const filtered = allRows.filter((row) => {
-        if (typeof row.memory_id !== "string" || typeof row.path_rel !== "string") return false;
-        const filePath = resolveProjectedMemoryPath(memoryDir, row.path_rel);
-        if (!filePath) return false;
-        // Check preview, category, entity_ref, tags first (fast)
+      for (const row of rows) {
+        if (typeof row.memory_id !== "string" || typeof row.path_rel !== "string") continue;
+        const filePath = resolveProjectedMemoryPath(
+          memoryDir,
+          row.path_rel,
+          currentSelect.hasPathValid,
+        );
+        if (!filePath) continue;
         const preview = typeof row.preview_text === "string" ? row.preview_text.toLowerCase() : "";
         const category = typeof row.category === "string" ? row.category.toLowerCase() : "";
         const entityRef = typeof row.entity_ref === "string" ? row.entity_ref.toLowerCase() : "";
         const tags = typeof row.tags_json === "string" ? row.tags_json.toLowerCase() : "";
-        if (preview.includes(normalizedQuery) || category.includes(normalizedQuery) ||
-            entityRef.includes(normalizedQuery) || tags.includes(normalizedQuery)) {
-          return true;
+        let matches = preview.includes(normalizedQuery) || category.includes(normalizedQuery) ||
+          entityRef.includes(normalizedQuery) || tags.includes(normalizedQuery);
+        if (!matches) {
+          try {
+            matches = fs.readFileSync(filePath, "utf-8").toLowerCase().includes(normalizedQuery);
+          } catch {
+            matches = false;
+          }
         }
-        // Fall back to reading full file content from disk
-        try {
-          const content = fs.readFileSync(filePath, "utf-8").toLowerCase();
-          return content.includes(normalizedQuery);
-        } catch {
-          return false;
+        if (!matches) continue;
+        if (total >= options.offset && pageRows.length < options.limit) {
+          const browseRow = projectedBrowseRowFromCurrentRow(memoryDir, row, filePath);
+          if (browseRow) pageRows.push(browseRow);
         }
-      });
-
-      const pageRows = filtered.slice(options.offset, options.offset + options.limit);
-      return {
-        total: filtered.length,
-        memories: pageRows
-          .map((row) => projectedBrowseRowFromCurrentRow(memoryDir, row))
-          .filter((row): row is ProjectedMemoryBrowseRow => row !== null),
-      };
+        total += 1;
+      }
+
+      return { total, memories: pageRows };
     }
 
-    // No query: push lexical path safety into SQL, then count through the same
-    // realpath-aware row parser used for returned rows so symlink escapes do not
-    // inflate totals.
     const browseWhereClauses = [...whereClauses, ...projectedBrowsePathSqlClauses()];
+    if (currentSelect.hasPathValid) {
+      browseWhereClauses.push("path_valid = 1");
+    }
     const browseWhereSql = `WHERE ${browseWhereClauses.join(" AND ")}`;
+
+    if (currentSelect.hasPathValid) {
+      const rows = db
+        .prepare(`
+          SELECT
+            memory_id,
+            path_rel,
+            category,
+            status,
+            created_at,
+            updated_at,
+            entity_ref,
+            ${currentSelect.tagsJson},
+            ${currentSelect.previewText}
+          FROM memory_current
+          ${browseWhereSql}
+          ORDER BY ${orderBySql}
+        `)
+        .iterate(...params) as Iterable<Record<string, unknown>>;
+      const pageRows: ProjectedMemoryBrowseRow[] = [];
+      let validRowsSeen = 0;
+      for (const row of rows) {
+        const browseRow = projectedBrowseRowFromCurrentRow(memoryDir, row, undefined, true);
+        if (!browseRow) continue;
+        if (validRowsSeen >= options.offset) {
+          pageRows.push(browseRow);
+          if (pageRows.length >= options.limit) break;
+        }
+        validRowsSeen += 1;
+      }
+      const totalRow = db
+        .prepare(`SELECT COUNT(*) AS total FROM memory_current ${browseWhereSql}`)
+        .get(...params) as { total: number };
+      return { total: totalRow.total, memories: pageRows };
+    }
+
+    // Legacy projections have no materialized path validity. Preserve the
+    // realpath-aware full scan rather than trusting rows from an older writer.
     const pageRows: ProjectedMemoryBrowseRow[] = [];
     const fetchSize = Math.max(options.limit * 2, 50);
     let validRowsSeen = 0;

package/src/orchestration/recall-introspection.ts

@@ -54,15 +54,6 @@ export interface RecallIntrospectionDeps {
   effectiveCronRecallInstructionHeavyTokenCap(): number;
   readonly faithfulnessCounters: FaithfulnessGateCounters;
   getCodingContextForSession(sessionKey: string | undefined): CodingContext | null;
-  getLastGraphRecallSnapshot(
-    namespace?: string,
-  ): Promise<GraphRecallSnapshot | null>;
-  getLastIntentSnapshot(
-    namespace?: string,
-  ): Promise<IntentDebugSnapshot | null>;
-  getLastQmdRecallSnapshot(
-    namespace?: string,
-  ): Promise<QmdRecallSnapshot | null>;
   getStorage(namespace?: string): Promise<StorageManager>;
   readonly graphRecallCoordinator: GraphRecallCoordinator;
   readonly lastRecall: LastRecallStore;
@@ -299,7 +290,7 @@ export class RecallIntrospectionCoordinator {
     namespace?: string;
     maxExpanded?: number;
   }): Promise<string> {
-    const snapshot = await this.deps.getLastGraphRecallSnapshot(options?.namespace);
+    const snapshot = await this.getLastGraphRecallSnapshot(options?.namespace);
     if (!snapshot) return "No graph-recall snapshot found yet.";
     const maxExpanded = Math.max(1, Math.min(50, options?.maxExpanded ?? 10));
     const expanded = snapshot.expanded.slice(0, maxExpanded);
@@ -353,7 +344,7 @@ export class RecallIntrospectionCoordinator {
   }
 
   async explainLastIntent(options?: { namespace?: string }): Promise<string> {
-    const snapshot = await this.deps.getLastIntentSnapshot(options?.namespace);
+    const snapshot = await this.getLastIntentSnapshot(options?.namespace);
     if (!snapshot) return "No intent-debug snapshot found yet.";
     return [
       "## Last Intent Debug",
@@ -375,7 +366,7 @@ export class RecallIntrospectionCoordinator {
     namespace?: string;
     maxResults?: number;
   }): Promise<string> {
-    const snapshot = await this.deps.getLastQmdRecallSnapshot(options?.namespace);
+    const snapshot = await this.getLastQmdRecallSnapshot(options?.namespace);
     if (!snapshot) return "No QMD recall snapshot found yet.";
     const maxResults = Math.max(1, Math.min(25, options?.maxResults ?? 10));
     const shown = snapshot.results.slice(0, maxResults);

package/src/orchestrator.ts

@@ -611,7 +611,7 @@ export class Orchestrator {
   }
 
   getConsoleFaithfulnessDistribution(): FaithfulnessGateCounters | undefined {
-    return this.recallIntrospectionCoordinator.getConsoleFaithfulnessDistribution(
+    return this.recallIntrospection.getConsoleFaithfulnessDistribution(
     );
   }
   readonly modelRegistry: ModelRegistry;
@@ -2158,54 +2158,6 @@ export class Orchestrator {
     }
   }
 
-  async getLastGraphRecallSnapshot(
-    namespace?: string,
-  ): Promise<GraphRecallSnapshot | null> {
-    return this.recallIntrospectionCoordinator.getLastGraphRecallSnapshot(
-      namespace,
-    );
-  }
-
-  async getLastIntentSnapshot(
-    namespace?: string,
-  ): Promise<IntentDebugSnapshot | null> {
-    return this.recallIntrospectionCoordinator.getLastIntentSnapshot(
-      namespace,
-    );
-  }
-
-  async getLastQmdRecallSnapshot(
-    namespace?: string,
-  ): Promise<QmdRecallSnapshot | null> {
-    return this.recallIntrospectionCoordinator.getLastQmdRecallSnapshot(
-      namespace,
-    );
-  }
-
-  async explainLastGraphRecall(options?: {
-    namespace?: string;
-    maxExpanded?: number;
-  }): Promise<string> {
-    return this.recallIntrospectionCoordinator.explainLastGraphRecall(
-      options,
-    );
-  }
-
-  async explainLastIntent(options?: { namespace?: string }): Promise<string> {
-    return this.recallIntrospectionCoordinator.explainLastIntent(
-      options,
-    );
-  }
-
-  async explainLastQmdRecall(options?: {
-    namespace?: string;
-    maxResults?: number;
-  }): Promise<string> {
-    return this.recallIntrospectionCoordinator.explainLastQmdRecall(
-      options,
-    );
-  }
-
   private async searchConversationRecallResults(
     retrievalQuery: string,
     topK: number,
@@ -2341,7 +2293,7 @@ export class Orchestrator {
   async waitForDirectAnswerObservationIdle(
     timeoutMs: number = 60_000,
   ): Promise<boolean> {
-    return this.recallIntrospectionCoordinator.waitForDirectAnswerObservationIdle(
+    return this.recallIntrospection.waitForDirectAnswerObservationIdle(
       timeoutMs,
     );
   }
@@ -2354,7 +2306,7 @@ export class Orchestrator {
     caps: CapabilitySet,
     namespacesEnabled: boolean,
   ): void {
-    return this.recallIntrospectionCoordinator.enqueueDirectAnswerObservation(
+    return this.recallIntrospection.enqueueDirectAnswerObservation(
       prompt,
       sessionKey,
       namespaceOverride,
@@ -2374,7 +2326,7 @@ export class Orchestrator {
     caps: CapabilitySet,
     _parentAbortSignal?: AbortSignal,
   ): Promise<void> {
-    return this.recallIntrospectionCoordinator.annotateDirectAnswerTier(
+    return this.recallIntrospection.annotateDirectAnswerTier(
       prompt,
       sessionKey,
       namespaces,
@@ -2540,7 +2492,7 @@ export class Orchestrator {
     finalResults?: GraphRecallRankedResult[];
     shadowComparison?: GraphRecallShadowComparison;
   }): Promise<void> {
-    return this.recallIntrospectionCoordinator.recordLastGraphRecallSnapshot(
+    return this.recallIntrospection.recordLastGraphRecallSnapshot(
       options,
     );
   }
@@ -2548,7 +2500,7 @@ export class Orchestrator {
     storage: StorageManager;
     snapshot: IntentDebugSnapshot;
   }): Promise<void> {
-    return this.recallIntrospectionCoordinator.recordLastIntentSnapshot(
+    return this.recallIntrospection.recordLastIntentSnapshot(
       options,
     );
   }
@@ -2557,7 +2509,7 @@ export class Orchestrator {
     storage: StorageManager;
     snapshot: QmdRecallSnapshot;
   }): Promise<void> {
-    return this.recallIntrospectionCoordinator.recordLastQmdRecallSnapshot(
+    return this.recallIntrospection.recordLastQmdRecallSnapshot(
       options,
     );
   }
@@ -2566,7 +2518,7 @@ export class Orchestrator {
     namespace: string;
     snapshot: IntentDebugSnapshot;
   }): Promise<void> {
-    return this.recallIntrospectionCoordinator.recordLastIntentSnapshotForNamespace(
+    return this.recallIntrospection.recordLastIntentSnapshotForNamespace(
       options,
     );
   }
@@ -2746,7 +2698,7 @@ export class Orchestrator {
    */
   private _recallIntrospectionCoordinator: RecallIntrospectionCoordinator | undefined;
 
-  private get recallIntrospectionCoordinator(): RecallIntrospectionCoordinator {
+  get recallIntrospection(): RecallIntrospectionCoordinator {
     if (!this._recallIntrospectionCoordinator) {
       this._recallIntrospectionCoordinator = new RecallIntrospectionCoordinator(
         selfDeps<ConstructorParameters<typeof RecallIntrospectionCoordinator>[0]>(this),