@remnic/core 9.3.751 → 9.3.753

package/src/access-service.ts

@@ -251,6 +251,9 @@ import {
 import { formatProfileTraceAscii } from "./profiling.js";
 import { resolveAccessSetupCapabilities, resolveGraphConstructionCapabilities, resolveIndexingCapabilities } from "./capabilities.js";
 import { resolveRecallEnhancementCapabilities } from "./capabilities.js";
+import { AccessAdminOpsSurface } from "./access-admin-ops-surface.js";
+import { AccessRecallSurface } from "./access-recall-surface.js";
+import { selfDeps } from "./orchestration/self-deps.js";
 
 export class EngramAccessInputError extends Error {}
 
@@ -300,12 +303,12 @@ function qmdResultPathCandidates(
   return [...candidates];
 }
 
-type AccessProfilingReportRequest = {
+export type AccessProfilingReportRequest = {
   format?: string;
   limit?: number;
 };
 
-type AccessProfilingReportResponse = {
+export type AccessProfilingReportResponse = {
   enabled: boolean;
   format?: "ascii" | "json";
   report?: string;
@@ -858,7 +861,7 @@ export interface EngramAccessOfflineSyncApplyResponse extends OfflineSyncApplyCh
 export type EngramAccessActionConfidenceRequest = ActionConfidenceInput;
 export type EngramAccessActionConfidenceResponse = ActionConfidenceResult;
 
-async function buildProjectedGovernanceProposedActions(
+export async function buildProjectedGovernanceProposedActions(
   storage: Awaited<ReturnType<Orchestrator["getStorage"]>>,
   projected: NonNullable<Awaited<ReturnType<Awaited<ReturnType<Orchestrator["getStorage"]>>["getProjectedGovernanceRecord"]>>>,
 ): Promise<Awaited<ReturnType<typeof readMemoryGovernanceRunArtifact>>["appliedActions"]> {
@@ -877,7 +880,7 @@ async function buildProjectedGovernanceProposedActions(
   return buildProposedActions(reviewQueue, memories);
 }
 
-function hasGroupedGovernanceActions(
+export function hasGroupedGovernanceActions(
   grouped?: Awaited<ReturnType<typeof readMemoryGovernanceRunArtifact>>["transitionReport"]["proposed"],
 ): boolean {
   if (!grouped) return false;
@@ -1305,6 +1308,30 @@ export class EngramAccessService {
   private readonly budget: CrossNamespaceBudget;
   private readonly auditAdapter: AccessAuditAdapter | null;
 
+  /** AccessAdminOpsSurface (access-service decomposition). Lazy; selfDeps live wiring. */
+  private _accessAdminOpsSurface: AccessAdminOpsSurface | undefined;
+
+  private get accessAdminOpsSurface(): AccessAdminOpsSurface {
+    if (!this._accessAdminOpsSurface) {
+      this._accessAdminOpsSurface = new AccessAdminOpsSurface(
+        selfDeps<ConstructorParameters<typeof AccessAdminOpsSurface>[0]>(this),
+      );
+    }
+    return this._accessAdminOpsSurface;
+  }
+
+  /** AccessRecallSurface (access-service decomposition). Lazy; selfDeps live wiring. */
+  private _accessRecallSurface: AccessRecallSurface | undefined;
+
+  private get accessRecallSurface(): AccessRecallSurface {
+    if (!this._accessRecallSurface) {
+      this._accessRecallSurface = new AccessRecallSurface(
+        selfDeps<ConstructorParameters<typeof AccessRecallSurface>[0]>(this),
+      );
+    }
+    return this._accessRecallSurface;
+  }
+
   constructor(private readonly orchestrator: Orchestrator) {
     this.idempotency = new AccessIdempotencyStore(orchestrator.config.memoryDir);
     const accessCaps = resolveAccessSetupCapabilities(orchestrator.config); // #1566 Cluster B
@@ -2097,83 +2124,9 @@ export class EngramAccessService {
      */
     rawExcerptsSuppressed?: boolean;
   }): Promise<EngramAccessRecallResponse> {
-    const memoryIds = options.snapshot.results.map((result) => result.memoryId);
-    const resultPaths = options.snapshot.results.map((result) => result.path);
-    const namespace = options.snapshot.namespace
-      ? this.resolveNamespace(options.snapshot.namespace)
-      : this.orchestrator.config.defaultNamespace;
-    const sourcesUsed = Array.from(
-      new Set(options.snapshot.results.map((result) => result.servedBy)),
-    );
-    const snapshotForSerialization: LastRecallSnapshot = {
-      sessionKey: options.sessionKey ?? "",
-      recordedAt: new Date(options.snapshot.capturedAt).toISOString(),
-      queryHash: createHash("sha256").update(options.query).digest("hex"),
-      queryLen: options.query.length,
-      memoryIds,
-      namespace,
-      recallNamespaces: [namespace],
-      traceId: options.snapshot.traceId,
-      plannerMode: options.normalizedMode,
-      requestedMode:
-        options.requestedMode && options.requestedMode !== "auto"
-          ? options.requestedMode
-          : undefined,
-      sourcesUsed,
-      budgetsApplied: {
-        appliedTopK: memoryIds.length,
-        recallBudgetChars: options.snapshot.budget.chars,
-        maxMemoryTokens: this.orchestrator.config.maxMemoryTokens,
-        finalContextChars: options.snapshot.budget.used,
-      },
-      latencyMs: Date.now() - options.startedAt,
-      resultPaths,
-    };
-    const results = await this.serializeRecallResults(
-      snapshotForSerialization,
-      options.disclosure,
-      {
-        query: options.query,
-        ...(options.sessionKey ? { sessionKey: options.sessionKey } : {}),
-        ...(options.rawExcerptNamespace
-          ? { rawExcerptNamespace: options.rawExcerptNamespace }
-          : {}),
-        ...(options.rawExcerptSessionIds !== undefined
-          ? { rawExcerptSessionIds: options.rawExcerptSessionIds }
-          : {}),
-        ...(options.rawExcerptsSuppressed
-          ? { rawExcerptsSuppressed: options.rawExcerptsSuppressed }
-          : {}),
-      },
+    return this.accessRecallSurface.buildRecallResponseFromXraySnapshot(
+      options,
     );
-    const context = results
-      .map((result) => {
-        const content =
-          typeof result.content === "string" && result.content.length > 0
-            ? result.content
-            : "";
-        return content || result.preview;
-      })
-      .filter((text) => text.length > 0)
-      .join("\n\n");
-
-    return {
-      query: options.query,
-      ...(options.sessionKey ? { sessionKey: options.sessionKey } : {}),
-      namespace,
-      context,
-      count: memoryIds.length,
-      memoryIds,
-      results,
-      recordedAt: snapshotForSerialization.recordedAt,
-      traceId: options.snapshot.traceId,
-      plannerMode: options.normalizedMode,
-      fallbackUsed: sourcesUsed.some((source) => source !== "hybrid"),
-      sourcesUsed,
-      disclosure: options.disclosure,
-      budgetsApplied: snapshotForSerialization.budgetsApplied,
-      latencyMs: snapshotForSerialization.latencyMs,
-    };
   }
 
   private async serializeRecallResults(
@@ -2214,198 +2167,11 @@ export class EngramAccessService {
         }
       | null = null,
   ): Promise<EngramAccessMemorySummary[]> {
-    if (!snapshot) return [];
-    const namespace = snapshot.namespace ? this.resolveNamespace(snapshot.namespace) : this.orchestrator.config.defaultNamespace;
-    const storage = await this.orchestrator.getStorage(namespace);
-    const storageDir = storage.dir;
-    const recallNamespaces = Array.from(
-      new Set(
-        [
-          namespace,
-          ...(Array.isArray(snapshot.recallNamespaces)
-            ? snapshot.recallNamespaces.map((ns) => this.resolveNamespace(ns))
-            : []),
-          this.orchestrator.config.defaultNamespace,
-          this.orchestrator.config.sharedNamespace,
-          ...(this.orchestrator.config.namespacePolicies ?? []).map((p) => p.name),
-        ].filter((ns): ns is string => typeof ns === "string" && ns.length > 0),
-      ),
+    return this.accessRecallSurface.serializeRecallResults(
+      snapshot,
+      disclosure,
+      rawContext,
     );
-    const results: EngramAccessMemorySummary[] = [];
-    const seen = new Set<string>();
-    const collectionNamespaceFromPrefix = (collectionPrefix: string): string | null => {
-      const baseCollection = this.orchestrator.config.qmdCollection;
-      if (collectionPrefix === baseCollection) return this.orchestrator.config.defaultNamespace;
-      const namespaceSuffix = collectionPrefix.startsWith(`${baseCollection}--`)
-        ? collectionPrefix.slice(baseCollection.length + 2)
-        : "";
-      if (!namespaceSuffix) return null;
-
-      const decoded = namespaceIdentityFromToken(namespaceSuffix);
-      if (decoded !== null) return decoded || this.orchestrator.config.defaultNamespace;
-      if (namespaceSuffix.startsWith("ns--")) {
-        const legacyNamespace = namespaceSuffix.slice("ns--".length).trim();
-        return legacyNamespace || null;
-      }
-      return null;
-    };
-    const readResultPath = async (
-      memoryPath: string,
-    ): Promise<{ memory: MemoryFile; baseDir: string } | null> => {
-      const parts = qmdCollectionPathParts(memoryPath);
-      const coldCollection =
-        this.orchestrator.config.qmdColdCollection ?? "openclaw-engram-cold";
-      if (parts && parts.collection === coldCollection) {
-        const storages: Array<{ storage: StorageManager; dir: string }> = [];
-        const seenStorageDirs = new Set<string>();
-        const addStorage = (candidateStorage: StorageManager): void => {
-          const candidateDir = nodePath.resolve(candidateStorage.dir);
-          if (seenStorageDirs.has(candidateDir)) return;
-          seenStorageDirs.add(candidateDir);
-          storages.push({ storage: candidateStorage, dir: candidateDir });
-        };
-        addStorage(storage);
-        for (const recallNamespace of recallNamespaces) {
-          try {
-            addStorage(await this.orchestrator.getStorage(recallNamespace));
-          } catch {
-            continue;
-          }
-        }
-        for (const candidateStorage of storages) {
-          try {
-            const coldRoot = nodePath.join(candidateStorage.dir, "cold");
-            for (const candidatePath of qmdResultPathCandidates(
-              coldRoot,
-              parts.relativePath,
-            )) {
-              const memory =
-                await candidateStorage.storage.readMemoryByPath(candidatePath);
-              if (memory) return { memory, baseDir: candidateStorage.dir };
-            }
-          } catch (err) {
-            if (err instanceof SecureStoreLockedError) throw err;
-            continue;
-          }
-        }
-        return null;
-      }
-
-      const collectionNamespace = parts
-        ? collectionNamespaceFromPrefix(parts.collection)
-        : null;
-
-      if (parts && collectionNamespace) {
-        try {
-          const collectionStorage =
-            await this.orchestrator.getStorage(collectionNamespace);
-          for (const candidate of qmdResultPathCandidates(
-            collectionStorage.dir,
-            parts.relativePath,
-          )) {
-            const memory = await collectionStorage.readMemoryByPath(candidate);
-            if (memory) return { memory, baseDir: collectionStorage.dir };
-          }
-          return null;
-        } catch (err) {
-          if (err instanceof SecureStoreLockedError) throw err;
-          return null;
-        }
-      }
-
-      if (nodePath.isAbsolute(memoryPath)) {
-        const ownerStorage = await this.storageForAbsoluteRecallPath(
-          memoryPath,
-          namespace,
-          recallNamespaces,
-        );
-        if (!ownerStorage) return null;
-        for (const candidate of qmdResultPathCandidates(
-          ownerStorage.dir,
-          memoryPath,
-        )) {
-          const memory = await ownerStorage.storage.readMemoryByPath(candidate);
-          if (memory) return { memory, baseDir: ownerStorage.dir };
-        }
-        return null;
-      }
-
-      for (const candidate of qmdResultPathCandidates(storageDir, memoryPath)) {
-        const memory = await storage.readMemoryByPath(candidate);
-        if (memory) return { memory, baseDir: storageDir };
-      }
-      return null;
-    };
-
-    // Pre-fetch raw excerpts once when `disclosure === "raw"` so we don't
-    // hit the LCM archive per-result (issue #677 PR 2/4).  Excerpts are
-    // attached to the first result; per-result attribution is reserved
-    // for a future PR if/when the LCM index can be joined to memory ids.
-    // Coerce `null` (non-raw disclosure) to `undefined` so the optional
-    // serializer field is never explicitly `null`.
-    // Namespace for the LCM `${namespace}:${sessionKey}` prefix: prefer the
-    // caller-supplied READ-AUTHORIZATION-GATED `rawExcerptNamespace` (#1505
-    // thread 2f7) so raw disclosure honours the same read gate as normal recall
-    // + `lcmSearch` and never attaches `<principal>-project-*` overlay rows the
-    // gate excludes. Fall back to the snapshot's resolved namespace only when no
-    // gated namespace was threaded (sessionless / legacy callers) — unchanged.
-    const rawExcerptsResult =
-      rawContext?.rawExcerptsSuppressed === true
-        ? // Implicit raw recall with NO readable LCM namespace (#1505 thread
-          // NBHWz): emit empty excerpts rather than falling back to the
-          // write/overlay `namespace` the read gate excludes.
-          []
-        : await this.fetchRawExcerpts(
-            disclosure,
-            rawContext
-              ? {
-                  query: rawContext.query,
-                  ...(rawContext.sessionKey
-                    ? { sessionKey: rawContext.sessionKey }
-                    : {}),
-                  namespace: rawContext.rawExcerptNamespace ?? namespace,
-                  ...(rawContext.rawExcerptSessionIds !== undefined
-                    ? { lcmSessionIds: rawContext.rawExcerptSessionIds }
-                    : {}),
-                }
-              : null,
-          );
-    const rawExcerpts = rawExcerptsResult ?? undefined;
-
-    for (const memoryPath of snapshot.resultPaths ?? []) {
-      if (!memoryPath || seen.has(memoryPath)) continue;
-      const resolved = await readResultPath(memoryPath);
-      if (!resolved) continue;
-      const { memory, baseDir } = resolved;
-      seen.add(memoryPath);
-      results.push(
-        this.serializeMemorySummary(
-          memory,
-          baseDir,
-          disclosure,
-          // Attach the (possibly empty) raw excerpts to the first raw
-          // result; subsequent results do not duplicate the array.
-          results.length === 0 ? rawExcerpts : undefined,
-        ),
-      );
-    }
-
-    if (results.length > 0) return results;
-
-    for (const memoryId of snapshot.memoryIds) {
-      const memory = await storage.getMemoryById(memoryId);
-      if (!memory || seen.has(memory.path)) continue;
-      seen.add(memory.path);
-      results.push(
-        this.serializeMemorySummary(
-          memory,
-          storageDir,
-          disclosure,
-          results.length === 0 ? rawExcerpts : undefined,
-        ),
-      );
-    }
-    return results;
   }
 
   private async storageForAbsoluteRecallPath(
@@ -2460,19 +2226,6 @@ export class EngramAccessService {
     return matches[0] ?? null;
   }
 
-  /**
-   * Fetch raw transcript excerpts from the LCM archive for `disclosure ===
-   * "raw"` recalls (issue #677 PR 2/4).  Returns `null` for non-raw recall
-   * depths, an empty array when LCM is disabled / not initialized / has no
-   * matches, and an array of LCM-side excerpts otherwise.  Errors are
-   * swallowed and treated as "no excerpts" so a failing LCM never breaks
-   * the recall response.
-   *
-   * Namespace handling: LCM archival prefixes non-default-namespace
-   * sessions with `${namespace}:${sessionKey}` (see `observe()` around
-   * line 2498), so the lookup must mirror that prefix or raw recalls in
-   * non-default namespaces miss their own excerpts.
-   */
   private async fetchRawExcerpts(
     disclosure: RecallDisclosure,
     context: {
@@ -2493,63 +2246,10 @@ export class EngramAccessService {
       lcmSessionIds?: string[];
     } | null,
   ): Promise<EngramAccessMemorySummary["rawExcerpts"] | null> {
-    if (disclosure !== "raw") return null;
-    if (!context || !context.query) return [];
-    // Privacy guard: raw disclosure must be session-scoped.  Without a
-    // sessionKey, `lcm.searchContextFull(query, n, undefined)` searches
-    // across every archived session in the LCM store and would return
-    // excerpts from unrelated sessions (potentially crossing namespaces
-    // via their `${namespace}:${sessionKey}` prefix encoding).  Treat a
-    // missing sessionKey as "no excerpts" — callers asking for raw
-    // disclosure outside a session get an empty list, not a leak.
-    if (!context.sessionKey) return [];
-    const lcm = this.orchestrator.lcmEngine;
-    if (!lcm || !lcm.enabled) return [];
-    try {
-      const legacyKey =
-        context.namespace &&
-        context.namespace !== this.orchestrator.config.defaultNamespace
-          ? `${context.namespace}:${context.sessionKey}`
-          : context.sessionKey;
-      const lcmSessionIds =
-        context.lcmSessionIds !== undefined
-          ? context.lcmSessionIds
-          : [legacyKey];
-      // Cap the excerpt fanout so recall responses stay bounded.  Five matches
-      // is enough to anchor the model in the raw transcript without ballooning
-      // token spend; raw is meant as the escape hatch, not the default. The cap
-      // is applied across the MERGED result set so adding fallback keys never
-      // inflates the excerpt budget.
-      const limit = 5;
-      const seenRows = new Set<string>();
-      const excerpts: NonNullable<EngramAccessMemorySummary["rawExcerpts"]> = [];
-      const settledRows = await Promise.allSettled(
-        lcmSessionIds.map(async (lcmSessionKey) =>
-          lcm.searchContextFull(context.query, limit, lcmSessionKey),
-        ),
-      );
-      for (const result of settledRows) {
-        if (excerpts.length >= limit) break;
-        if (result.status !== "fulfilled") continue;
-        for (const r of result.value) {
-          const dedupeKey = `${r.session_id} ${r.turn_index}`;
-          if (seenRows.has(dedupeKey)) continue;
-          seenRows.add(dedupeKey);
-          excerpts.push({
-            turnIndex: r.turn_index,
-            role: r.role,
-            content: r.content,
-            sessionId: r.session_id,
-          });
-          if (excerpts.length >= limit) break;
-        }
-      }
-      return excerpts;
-    } catch {
-      // CLAUDE.md rule 13: never let an external subsystem (LCM/SQLite)
-      // crash the primary recall flow.
-      return [];
-    }
+    return this.accessRecallSurface.fetchRawExcerpts(
+      disclosure,
+      context,
+    );
   }
 
   private async handleIdempotentWrite<T extends { idempotencyReplay?: boolean }>(options: {
@@ -3267,453 +2967,9 @@ export class EngramAccessService {
     response: EngramAccessRecallResponse;
     budgetRecordPrincipal: string | null;
   }> {
-    const query = request.query;
-    // Disclosure depth (issue #677).  Default to `"chunk"` when omitted so
-    // pre-#677 callers see unchanged behavior.  Reject explicitly invalid
-    // string values per CLAUDE.md rule 51 (do not silently fall back).
-    const callerProvidedDisclosure =
-      request.disclosure !== undefined && request.disclosure !== null;
-    const requestedDisclosure: RecallDisclosure = (() => {
-      if (!callerProvidedDisclosure) {
-        return DEFAULT_RECALL_DISCLOSURE;
-      }
-      if (!isRecallDisclosure(request.disclosure)) {
-        throw new EngramAccessInputError(
-          `disclosure must be one of: chunk, section, raw (got: ${String(request.disclosure)})`,
-        );
-      }
-      return request.disclosure;
-    })();
-    // Attach any coding context shipped with the recall request BEFORE
-    // namespace resolution so the overlay applies to this recall (issue #569).
-    if (request.codingContext !== undefined && request.sessionKey) {
-      this.setCodingContext({
-        sessionKey: request.sessionKey,
-        codingContext: request.codingContext,
-      });
-    }
-    // Auto-resolve coding context from cwd/projectTag when no explicit
-    // codingContext was supplied (issue #569 wiring). This allows Claude
-    // Code hooks and OpenClaw connectors to get project-scoped memory
-    // transparently.
-    if (request.codingContext === undefined && request.sessionKey) {
-      await this.maybeAttachCodingContext(request.sessionKey, {
-        cwd: request.cwd,
-        projectTag: request.projectTag,
-      });
-    }
-    const authenticatedPrincipal = request.authenticatedPrincipal?.trim();
-    const namespaceOverride = this.resolveRecallNamespace(
-      request.namespace,
-      request.sessionKey,
-      authenticatedPrincipal,
+    return this.accessRecallSurface.executeRecall(
+      request,
     );
-    const namespace = namespaceOverride ?? this.orchestrator.config.defaultNamespace;
-    // Normalize mode early so that no_recall / invalid modes skip budget
-    // accounting (Codex P1: budget recorded before mode validation).
-    const mode = this.normalizeRecallMode(request.mode);
-    const maybePrincipal = this.resolveRequestPrincipal(request.sessionKey, authenticatedPrincipal);
-    if (resolveNamespaceCapabilities(this.orchestrator.config).namespaces && !maybePrincipal) {
-      throw new EngramAccessInputError(
-        "authentication required: namespaces are enabled and no principal was supplied",
-      );
-    }
-    const principal = maybePrincipal ?? "default";
-    const principalNamespace = defaultNamespaceForPrincipal(principal, this.orchestrator.config);
-    const profileCodingContext =
-      request.sessionKey && typeof this.orchestrator.getCodingContextForSession === "function"
-        ? this.orchestrator.getCodingContextForSession(request.sessionKey)
-        : null;
-    const profileCodingOverlay =
-      !namespaceOverride &&
-      profileCodingContext &&
-      resolveNamespaceCapabilities(this.orchestrator.config).namespaces &&
-      this.orchestrator.config.codingMode?.projectScope
-        ? resolveCodingNamespaceOverlay(
-            profileCodingContext,
-            this.orchestrator.config.codingMode,
-            this.orchestrator.config.defaultNamespace,
-          )
-        : null;
-    const profilePlan = namespaceOverride
-      ? null
-      : resolveScopeProfilePlan({
-          config: this.orchestrator.config,
-          principal,
-          codingContext: profileCodingContext,
-          codingOverlay: profileCodingOverlay,
-        });
-    // Skip budget checks for modes that never perform a cross-namespace read.
-    const modeSkipsBudget = mode === "no_recall";
-    // Derive the full set of namespaces the orchestrator will actually search.
-    // When no explicit override is provided, `recallNamespacesForPrincipal()` may
-    // expand to shared / policy-default namespaces.  Budget must be checked
-    // against every cross-namespace entry in the effective set so that omitting
-    // `namespace` cannot bypass the limiter (Cursor/Codex review feedback).
-    //
-    const legacyRecallNamespaces = Array.isArray(this.orchestrator.config.defaultRecallNamespaces)
-      ? recallNamespacesForPrincipal(principal, this.orchestrator.config)
-      : [];
-    const effectiveNamespaces = namespaceOverride
-      ? [namespaceOverride]
-      : profilePlan
-        ? expandScopeProfileReadNamespaces({
-            profilePlan,
-            principalSelfNamespace: profilePlan.baseNamespace,
-            config: this.orchestrator.config,
-            principal,
-            codingOverlay: profileCodingOverlay,
-            legacyRecallNamespaces,
-          })
-        : legacyRecallNamespaces;
-    const budgetPrincipalNamespace = profilePlan?.baseNamespace ?? principalNamespace;
-    let budgetDecision: BudgetDecision;
-    let recordBudgetAfterSuccess = false;
-    if (modeSkipsBudget) {
-      budgetDecision = {
-        allowed: true as const,
-        reason: "allowed-same-namespace" as const,
-        count: 0,
-        limit: {
-          softLimit: this.orchestrator.config.recallCrossNamespaceBudgetSoftLimit ?? 10,
-          hardLimit: this.orchestrator.config.recallCrossNamespaceBudgetHardLimit ?? 30,
-          windowMs: this.orchestrator.config.recallCrossNamespaceBudgetWindowMs ?? 60_000,
-        },
-      };
-    } else {
-      // Peek at every effective namespace to determine whether ANY would be
-      // cross-namespace WITHOUT recording side effects (Cursor review:
-      // multi-count bug).  Record a single budget event only when at least
-      // one effective namespace differs from the principal's self namespace,
-      // and only after recall succeeds so retried transient failures do not
-      // consume budget multiple times before a successful response can be
-      // cached behind the request idempotency key.
-      let anyCrossNamespace = false;
-      let denied: BudgetDecision | null = null;
-      let crossNamespaceDecision: BudgetDecision | null = null;
-      for (const ns of effectiveNamespaces) {
-        const peek = this.budget.peek({
-          principal,
-          principalNamespace: budgetPrincipalNamespace,
-          queryNamespace: ns,
-        });
-        if (peek.reason !== "allowed-same-namespace") {
-          anyCrossNamespace = true;
-          crossNamespaceDecision ??= peek;
-        }
-        if (!peek.allowed) {
-          denied = peek;
-          break;
-        }
-      }
-      if (denied) {
-        // The peek projected a denial — deny without recording so the
-        // bucket is not inflated by rejected attempts.
-        budgetDecision = denied;
-      } else if (anyCrossNamespace) {
-        budgetDecision = crossNamespaceDecision ?? {
-          allowed: true as const,
-          reason: "allowed-under-soft" as const,
-          count: 0,
-          limit: {
-            softLimit: this.orchestrator.config.recallCrossNamespaceBudgetSoftLimit ?? 10,
-            hardLimit: this.orchestrator.config.recallCrossNamespaceBudgetHardLimit ?? 30,
-            windowMs: this.orchestrator.config.recallCrossNamespaceBudgetWindowMs ?? 60_000,
-          },
-        };
-        recordBudgetAfterSuccess = true;
-      } else {
-        budgetDecision = {
-          allowed: true as const,
-          reason: "allowed-same-namespace" as const,
-          count: 0,
-          limit: {
-            softLimit: this.orchestrator.config.recallCrossNamespaceBudgetSoftLimit ?? 10,
-            hardLimit: this.orchestrator.config.recallCrossNamespaceBudgetHardLimit ?? 30,
-            windowMs: this.orchestrator.config.recallCrossNamespaceBudgetWindowMs ?? 60_000,
-          },
-        };
-      }
-      if (!budgetDecision.allowed) {
-        throw new EngramAccessInputError(
-          `recall denied: cross-namespace budget exceeded (${budgetDecision.count}/${budgetDecision.limit.hardLimit} in ${budgetDecision.limit.windowMs}ms window)`,
-        );
-      }
-      // Prune expired principal buckets to prevent unbounded Map growth from
-      // high-cardinality / transient principals (Codex P2 review feedback).
-      this.budget.gc();
-    }
-    const topK = Number.isFinite(request.topK) ? Math.max(0, Math.floor(request.topK ?? 0)) : undefined;
-    // Issue #680 — historical recall pin.  Validate at the input
-    // boundary so a malformed `asOf` is rejected with a structured
-    // 400 instead of silently flooring at NaN inside the orchestrator
-    // (CLAUDE.md rule 51, gotcha #51).  Empty / undefined is fine —
-    // means "no pin".
-    let asOf: string | undefined;
-    if (request.asOf !== undefined && request.asOf !== null) {
-      if (typeof request.asOf !== "string" || request.asOf.trim().length === 0) {
-        throw new EngramAccessInputError(
-          "asOf must be a non-empty ISO 8601 timestamp string",
-        );
-      }
-      const parsed = Date.parse(request.asOf);
-      if (!Number.isFinite(parsed)) {
-        throw new EngramAccessInputError(
-          `asOf must be a parseable ISO 8601 timestamp (got: "${request.asOf}")`,
-        );
-      }
-      asOf = request.asOf;
-    }
-    const recallOptions: RecallInvocationOptions = {
-      namespace: namespaceOverride,
-      topK,
-      mode,
-      ...(authenticatedPrincipal ? { principalOverride: authenticatedPrincipal } : {}),
-      ...(asOf !== undefined ? { asOf } : {}),
-      ...(request.includeLowConfidence === true ? { includeLowConfidence: true } : {}),
-    };
-    const startedAt = Date.now();
-    const context = await this.orchestrator.recall(query, request.sessionKey, recallOptions);
-    const snapshot = request.sessionKey
-      ? this.orchestrator.lastRecall.get(request.sessionKey)
-      : null;
-    const effectiveNamespace = snapshot?.namespace
-      ? this.resolveNamespace(snapshot.namespace)
-      : namespace;
-    // Auto-escalation policy (issue #677 PR 4/4).  When the operator
-    // configured `recallDisclosureEscalation: "auto"` AND the caller
-    // did not explicitly choose a disclosure level AND recall produced
-    // a low-confidence result set (proxied by fill ratio: results
-    // returned / topK requested), we escalate the default `chunk`
-    // shape to `section` so the LLM gets richer context to compensate
-    // for ambiguous retrieval.  Manual mode and explicit caller
-    // disclosure both bypass the policy.  Documented in
-    // `recall-disclosure-escalation.ts` and unit-tested there.
-    // Confidence-proxy denominator: priority order is
-    //   1. `snapshot.budgetsApplied.appliedTopK` (ALWAYS wins) — this is
-    //      the limit the orchestrator actually applied after planner /
-    //      minimal-mode / section-cap narrowing.  Codex P1 rounds 2+3
-    //      on #705 emphasize that even a caller's explicit `request.topK`
-    //      is wrong when the orchestrator caps below it (e.g. topK=50
-    //      but appliedTopK=3 makes a 2-hit recall actually 0.67, not
-    //      0.04).
-    //   2. The caller's explicit `topK` when the snapshot lacks
-    //      `budgetsApplied` (early-return paths, error cases).
-    //   3. Config `qmdMaxResults` as a last-resort fallback.
-    // Floor at observed-results so the ratio stays in [0, 1] even if
-    // any of the signals drifts below the actual hit count.
-    const resultsReturned = snapshot?.memoryIds?.length ?? 0;
-    const appliedTopK = snapshot?.budgetsApplied?.appliedTopK;
-    const configMaxResults =
-      typeof this.orchestrator.config.qmdMaxResults === "number" &&
-      Number.isFinite(this.orchestrator.config.qmdMaxResults) &&
-      this.orchestrator.config.qmdMaxResults > 0
-        ? this.orchestrator.config.qmdMaxResults
-        : 0;
-    const topKDenominator =
-      typeof appliedTopK === "number" &&
-      Number.isFinite(appliedTopK) &&
-      appliedTopK > 0
-        ? Math.max(appliedTopK, resultsReturned)
-        : typeof topK === "number" && topK > 0
-          ? Math.max(topK, resultsReturned)
-          : Math.max(configMaxResults, resultsReturned, 1);
-    // When the recall produced no snapshot (sessionless / namespace
-    // mismatch / early-return path), there is no confidence signal to
-    // base escalation on.  Pass `undefined` so the helper takes its
-    // `no-top-k-confidence` branch instead of computing 0/N=0 and
-    // forcing auto-escalation on every sessionless caller (Codex P2
-    // review on PR #705).
-    const topKConfidence =
-      snapshot && topKDenominator > 0
-        ? Math.min(1, resultsReturned / topKDenominator)
-        : undefined;
-    const escalationDecision = decideDisclosureEscalation({
-      mode: this.orchestrator.config.recallDisclosureEscalation,
-      threshold: this.orchestrator.config.recallDisclosureEscalationThreshold,
-      originalDisclosure: requestedDisclosure,
-      callerProvidedDisclosure,
-      topKConfidence,
-    });
-    const disclosure = escalationDecision.effective;
-    // Gate the raw-excerpt LCM read with the SAME read-authorization namespace
-    // `lcmSearch` + the in-prompt LCM sections use (#1505 thread 2f7), so
-    // `disclosure: "raw"` never attaches `<principal>-project-*` overlay rows
-    // when the principal can WRITE but not READ its self base (or
-    // `defaultRecallNamespaces` omits `self`). Computed ONLY for raw disclosure:
-    // it is the sole consumer, and resolving the overlay on every chunk/section
-    // recall would be wasted work — keeping non-raw recall byte-for-byte
-    // unchanged.
-    // Trim the sessionKey to match what `orchestrator.recall(...)` already does
-    // (`request.sessionKey?.trim() || undefined`) and what the x-ray raw-excerpt
-    // path uses (cursor "Raw excerpt key not trimmed"). A whitespace-padded key
-    // otherwise drives recall under one identity but resolves the raw-excerpt
-    // overlay namespace + LCM `session_id` under a DIFFERENT (untrimmed) prefix,
-    // so excerpts are gated/queried inconsistently with recall and the x-ray path.
-    const trimmedSessionKey = request.sessionKey?.trim() || undefined;
-    const rawExcerptNamespace =
-      disclosure === "raw"
-        ? this.resolveRawExcerptReadNamespace(
-            request.namespace,
-            trimmedSessionKey,
-            authenticatedPrincipal,
-          )
-        : undefined;
-    // `undefined` for an IMPLICIT raw recall means NO readable LCM namespace
-    // exists (restrictive `default` READ policy, no readable overlay/self) —
-    // suppress excerpts rather than fall back to the write/overlay namespace the
-    // read gate excludes (#1505 thread NBHWz). An EXPLICIT namespace always
-    // resolves (or throws) above, so suppression only applies to the implicit
-    // path.
-    const hasExplicitNamespace =
-      typeof request.namespace === "string" &&
-      request.namespace.trim().length > 0;
-    const rawExcerptsSuppressed =
-      disclosure === "raw" &&
-      !hasExplicitNamespace &&
-      rawExcerptNamespace === undefined;
-    // Ordered, read-authorized LCM read key SET (#1505 fallback unification) so
-    // raw disclosure finds excerpts a branch-scoped session archived at
-    // project/root scope — exactly as recall + `lcmSearch` do. Only with a
-    // concrete sessionKey; already read-gated.
-    const rawExcerptSessionIds =
-      disclosure === "raw" && rawExcerptNamespace && trimmedSessionKey
-        ? this.resolveLcmReadSessionIds(
-            request.namespace,
-            rawExcerptNamespace,
-            trimmedSessionKey,
-            authenticatedPrincipal,
-          )
-        : undefined;
-    let results = await this.serializeRecallResults(snapshot, disclosure, {
-      query,
-      sessionKey: trimmedSessionKey,
-      ...(rawExcerptNamespace ? { rawExcerptNamespace } : {}),
-      ...(rawExcerptSessionIds !== undefined ? { rawExcerptSessionIds } : {}),
-      ...(rawExcerptsSuppressed ? { rawExcerptsSuppressed } : {}),
-    });
-
-    // Tag filter (issue #689). Applied post-recall, post-serialization so
-    // the actual frontmatter tags are already loaded onto each result. When
-    // `tags` is absent or empty the filter is a no-op; an invalid `tagMatch`
-    // throws via `parseTagMatch` (CLAUDE.md rule 51).
-    const filterTags = normalizeTags(request.tags);
-    let tagMatchMode: TagMatchMode | undefined;
-    try {
-      tagMatchMode = parseTagMatch(request.tagMatch);
-    } catch (err) {
-      throw new EngramAccessInputError(
-        err instanceof Error ? err.message : String(err),
-      );
-    }
-    let effectiveContext = context;
-    if (filterTags && filterTags.length > 0) {
-      const beforeIds = results.map((r) => r.id);
-      const { results: admitted } = applyTagFilter(results, {
-        tags: filterTags,
-        tagMatch: tagMatchMode,
-      });
-      results = admitted;
-      // Codex P1: `context` was generated by orchestrator.recall(...)
-      // BEFORE the tag filter ran, so it can contain memories that don't
-      // match the requested tags. Surfaces consuming `context` (the
-      // prompt-injection string) would leak excluded content into the
-      // LLM. When the filter actually drops any result, rebuild context
-      // from the admitted set so excluded content is unreachable through
-      // any field of the response. The rebuilt context concatenates each
-      // admitted result's available text (full content at section/raw
-      // disclosure, otherwise the preview) — a different wire format
-      // than the orchestrator's native context, but a strict subset
-      // safe to inject.
-      const admittedIds = new Set(results.map((r) => r.id));
-      const droppedAny = beforeIds.some((id) => !admittedIds.has(id));
-      if (droppedAny) {
-        effectiveContext = results
-          .map((r) => {
-            const content =
-              typeof (r as { content?: unknown }).content === "string"
-                ? ((r as { content?: string }).content ?? "")
-                : "";
-            const preview =
-              typeof (r as { preview?: unknown }).preview === "string"
-                ? ((r as { preview?: string }).preview ?? "")
-                : "";
-            return content || preview;
-          })
-          .filter((s) => s.length > 0)
-          .join("\n\n");
-      }
-    }
-    const filteredMemoryIds = filterTags && filterTags.length > 0
-      ? results.map((r) => r.id)
-      : (snapshot?.memoryIds ?? []);
-    const debug = await this.buildRecallDebug(
-      snapshot,
-      effectiveNamespace,
-      request.includeDebug === true,
-      request.sessionKey,
-    );
-
-    // Fire-and-forget audit recording. Must never block or crash recall.
-    let auditAnomalies: AccessAuditResult["anomalies"] | undefined;
-    if (this.auditAdapter) {
-      try {
-        const resolvedAgentId = principal ?? "__anonymous__";
-        const auditEntry = {
-          ts: new Date().toISOString(),
-          sessionKey: request.sessionKey ?? "",
-          agentId: resolvedAgentId,
-          trigger: "access-surface",
-          queryText: query,
-          candidateMemoryIds: snapshot?.memoryIds ?? [],
-          // Audit must reflect what was actually injected, not what
-          // recall produced before the tag filter. Using `context`
-          // (pre-filter) overstates injectedChars and can leak content
-          // from excluded memories into the audit summary (cursor
-          // Medium on PR #712).
-          summary: effectiveContext.slice(0, 200) || null,
-          injectedChars: effectiveContext.length,
-          toggleState: "enabled" as const,
-          latencyMs: Date.now() - startedAt,
-          plannerMode: snapshot?.plannerMode ?? mode,
-          requestedMode: mode,
-          fallbackUsed: snapshot?.fallbackUsed ?? false,
-        };
-        const auditResult = await this.auditAdapter.record(
-          resolvedAgentId || "__anonymous__",
-          auditEntry,
-        );
-        auditAnomalies = auditResult.anomalies;
-      } catch {
-        // Audit failures must never crash the recall path.
-      }
-    }
-
-    return {
-      response: {
-        query,
-        sessionKey: request.sessionKey,
-        namespace: effectiveNamespace,
-        context: effectiveContext,
-        count: filterTags && filterTags.length > 0
-          ? results.length
-          : (snapshot?.memoryIds.length ?? results.length),
-        memoryIds: filteredMemoryIds,
-        results,
-        recordedAt: snapshot?.recordedAt,
-        traceId: snapshot?.traceId,
-        plannerMode: snapshot?.plannerMode ?? mode,
-        fallbackUsed: snapshot?.fallbackUsed ?? false,
-        sourcesUsed: snapshot?.sourcesUsed ?? [],
-        disclosure,
-        budgetsApplied: snapshot?.budgetsApplied,
-        auditAnomalies,
-        budgetWarning: budgetDecision.reason === "warn-over-soft" ? budgetDecision : undefined,
-        latencyMs: snapshot?.latencyMs ?? (Date.now() - startedAt),
-        debug,
-      },
-      budgetRecordPrincipal: recordBudgetAfterSuccess ? principal : null,
-    };
   }
 
   async recallExplain(
@@ -3814,15 +3070,6 @@ export class EngramAccessService {
     return toRecallExplainJson(snapshot);
   }
 
-  /**
-   * Recall X-ray (issue #570).  Runs a recall with `xrayCapture: true`
-   * and returns the resulting snapshot as structured JSON so every
-   * surface (CLI / HTTP / MCP) gets the same payload.  Namespace scope
-   * is enforced before the recall fires (CLAUDE.md rule 42 — read and
-   * write paths must resolve through the same namespace layer) so an
-   * unauthorized principal cannot capture an x-ray for a namespace it
-   * cannot read.
-   */
   async recallXray(request: {
     query: string;
     sessionKey?: string;
@@ -3867,433 +3114,9 @@ export class EngramAccessService {
     snapshot?: RecallXraySnapshot;
     recall?: EngramAccessRecallResponse;
   }> {
-    const query = typeof request.query === "string" ? request.query : "";
-    if (query.trim().length === 0) {
-      // Match the CLI contract (CLAUDE.md rule 51): reject empty
-      // input with an explicit error rather than silently producing
-      // an empty snapshot.
-      throw new Error("recallXray: query is required and must be non-empty");
-    }
-    // Validate disclosure UP FRONT — before recall executes, before
-    // the xray queue mutex is acquired, before namespace resolution.
-    // A bad value should fail fast rather than after we've burned
-    // cycles on an irreversible recall (Cursor Medium review on PR
-    // #699).
-    if (
-      request.disclosure !== undefined &&
-      !isRecallDisclosure(request.disclosure)
-    ) {
-      throw new EngramAccessInputError(
-        `recallXray: disclosure must be one of: chunk, section, raw (got: ${String(request.disclosure)})`,
-      );
-    }
-
-    const namespacesEnabled = resolveNamespaceCapabilities(this.orchestrator.config).namespaces;
-    const requestedNamespace = request.namespace?.trim()
-      ? this.resolveNamespace(request.namespace)
-      : undefined;
-    const authenticatedPrincipal = request.authenticatedPrincipal?.trim();
-    const principal =
-      authenticatedPrincipal
-      || resolvePrincipal(request.sessionKey, this.orchestrator.config);
-
-    if (requestedNamespace) {
-      if (
-        !canReadNamespace(
-          principal,
-          requestedNamespace,
-          this.orchestrator.config,
-        )
-      ) {
-        return { snapshotFound: false };
-      }
-    } else if (
-      namespacesEnabled
-      && !authenticatedPrincipal
-      && !request.sessionKey?.trim()
-    ) {
-      // Namespaces enabled but no identity supplied — reject rather
-      // than scanning the global namespace (CLAUDE.md rule 48:
-      // least-privileged default).
-      return { snapshotFound: false };
-    }
-
-    // Optional `--budget` override must be a positive integer.  Invalid
-    // values throw rather than silently defaulting (CLAUDE.md rule 51).
-    let budgetOverride: number | undefined;
-    if (request.budget !== undefined && request.budget !== null) {
-      const parsed =
-        typeof request.budget === "number"
-          ? request.budget
-          : Number(request.budget);
-      if (
-        !Number.isFinite(parsed)
-        || parsed <= 0
-        || !Number.isInteger(parsed)
-      ) {
-        throw new Error(
-          `recallXray: budget expects a positive integer; got ${JSON.stringify(request.budget)}`,
-        );
-      }
-      budgetOverride = parsed;
-    }
-    const mode = this.normalizeRecallMode(request.mode);
-    const disclosure = request.disclosure ?? DEFAULT_RECALL_DISCLOSURE;
-
-    // Serialize x-ray invocations behind a per-service mutex so the
-    // per-process `getLastXraySnapshot()` slot cannot be clobbered by
-    // a concurrent capturing call before this caller reads it back.
-    // Budget and principal are now threaded through
-    // `RecallInvocationOptions`, so global config mutation is gone
-    // (CLAUDE.md rule 47: no shared mutable state across async
-    // boundaries).  The mutex stays only for the snapshot-slot
-    // ordering guarantee.
-    const previousQueue = this.xrayQueue;
-    let release: () => void = () => {};
-    this.xrayQueue = new Promise<void>((resolve) => {
-      release = resolve;
-    });
-    await previousQueue;
-    const recallStartedAt = Date.now();
-
-    const recallSessionKey = request.sessionKey?.trim() || undefined;
-    let xrayResponse: {
-      snapshotFound: boolean;
-      snapshot?: RecallXraySnapshot;
-    } = { snapshotFound: false };
-
-    try {
-      // Clear any prior snapshot so a capture failure surfaces as
-      // `{snapshotFound: false}` rather than returning stale data
-      // from an earlier call on the same orchestrator.
-      this.orchestrator.clearLastXraySnapshot();
-      await this.orchestrator.recall(query, recallSessionKey, {
-        xrayCapture: true,
-        ...(requestedNamespace ? { namespace: requestedNamespace } : {}),
-        ...(budgetOverride !== undefined
-          ? { budgetCharsOverride: budgetOverride }
-          : {}),
-        ...(mode !== undefined ? { mode } : {}),
-        // When the caller supplies an authenticated principal, forward
-        // it via the dedicated override channel so orchestrator-side
-        // ACL decisions use the SAME principal the access-surface
-        // pre-check above authorized.  Threading an
-        // `authenticatedPrincipal` through `sessionKey` would be wrong:
-        // `resolvePrincipal(sessionKey)` only maps configured raw
-        // session keys and otherwise collapses to `"default"`, which
-        // in namespace-enabled deployments produces false denials /
-        // wrong-scope serving despite the pre-check passing
-        // (CLAUDE.md rule 42).
-        ...(authenticatedPrincipal
-          ? { principalOverride: authenticatedPrincipal }
-          : {}),
-        ...(request.currentContextScopes !== undefined
-          ? { currentContextScopes: request.currentContextScopes }
-          : {}),
-      });
-
-      const rawSnapshot = this.orchestrator.getLastXraySnapshot();
-      // Re-check namespace after capture: the recall may have served
-      // from a different namespace than the caller requested.  Drop
-      // the snapshot rather than leak cross-tenant data (CLAUDE.md
-      // rules 42 + 47).  The comparison is strict so a snapshot whose
-      // namespace is `undefined` cannot bypass the scope the caller
-      // asked for.
-      const namespaceMismatch =
-        requestedNamespace !== undefined &&
-        rawSnapshot?.namespace !== requestedNamespace;
-      if (!rawSnapshot) {
-        xrayResponse = { snapshotFound: false };
-      } else if (namespaceMismatch) {
-        xrayResponse = { snapshotFound: false };
-      } else {
-        // Tag filter (issue #689). Mirrors `recall()` semantics — applied
-        // post-capture by reading each result's frontmatter tags and
-        // dropping non-matching results. Filter activity surfaces as a
-        // `tag-filter` entry in `snapshot.filters` so X-ray consumers can
-        // see the "considered → admitted" delta.
-        let snapshot = rawSnapshot;
-        const xrayFilterTags = normalizeTags(request.tags);
-        let xrayTagMatch: TagMatchMode | undefined;
-        try {
-          xrayTagMatch = parseTagMatch(request.tagMatch);
-        } catch (err) {
-          throw new EngramAccessInputError(
-            err instanceof Error ? err.message : String(err),
-          );
-        }
-        if (xrayFilterTags && xrayFilterTags.length > 0) {
-          const namespace = snapshot.namespace
-            ? this.resolveNamespace(snapshot.namespace)
-            : this.orchestrator.config.defaultNamespace;
-          const tagsByIndex = await Promise.all(
-            snapshot.results.map(async (result) => {
-              try {
-                const storage = await this.orchestrator.getStorage(namespace);
-                const memory = await storage.readMemoryByPath(result.path);
-                const t = memory?.frontmatter?.tags;
-                // Normalize identically to the recall path
-                // (`normalizeProjectionTags`): trim and drop empty strings
-                // so X-ray tag matching stays consistent with the recall
-                // surface. Without this, a frontmatter tag like " draft "
-                // would match in recall but not in X-ray (cursor review).
-                return Array.isArray(t) ? normalizeProjectionTags(t) : [];
-              } catch {
-                return [];
-              }
-            }),
-          );
-          const tagged = snapshot.results.map((result, index) => ({
-            result,
-            tags: tagsByIndex[index] ?? [],
-          }));
-          const { results: admittedTagged, trace } = applyTagFilter(tagged, {
-            tags: xrayFilterTags,
-            tagMatch: xrayTagMatch,
-          });
-          const admittedResults = admittedTagged.map((entry) => entry.result);
-          const filters = trace ? [...snapshot.filters, trace] : snapshot.filters;
-          snapshot = { ...snapshot, results: admittedResults, filters };
-        }
-        // Decorate per-result disclosure + token estimate when the caller
-        // wired a depth knob (issue #677 PR 3/4 — codex review on #699
-        // flagged that the renderer's per-disclosure summary stays empty
-        // until callers populate these fields).  Estimate tokens from
-        // the actual rendered payload at the requested depth so the
-        // summary reflects real spend; chunk uses the preview, section
-        // and raw use full content.  Best-effort only — a missing
-        // memory or read failure is silently dropped (CLAUDE.md rule 13).
-        if (request.disclosure !== undefined) {
-          // Disclosure already validated up front; pin to the narrowed
-          // type here.  Re-validation inside the queue would be dead code.
-          const disclosure: RecallDisclosure = request.disclosure;
-          const namespace = snapshot.namespace
-            ? this.resolveNamespace(snapshot.namespace)
-            : this.orchestrator.config.defaultNamespace;
-          // Pre-fetch raw excerpts ONCE so the first raw-disclosure
-          // result's token estimate includes the LCM-side excerpt spend
-          // that `shapeMemorySummary` actually attaches in the recall
-          // response.  Without this, raw recalls systematically
-          // undercounted spend on the first result (Cursor Medium review
-          // on PR #699).  Excerpts are scoped to the same session +
-          // namespace as the recall.
-          // Trim sessionKey to match what `orchestrator.recall(...)`
-          // already does (`request.sessionKey?.trim() || undefined`),
-          // otherwise a whitespace-padded key drives recall under one
-          // identity but probes LCM under a different prefix and
-          // misses stored excerpts (Cursor Low review on PR #699).
-          const trimmedSessionKey = request.sessionKey?.trim() || undefined;
-          // Read-authorization-gated namespace for the raw-excerpt LCM lookup
-          // (#1505 thread 2f7). NOT `snapshot.namespace` (the write/overlay
-          // namespace), which would attach `<principal>-project-*` overlay rows
-          // when the principal can WRITE but not READ its self base. Mirrors the
-          // recall + `lcmSearch` read gate. Resolved ONLY for raw disclosure (its
-          // sole consumer); the `namespace` above is still used for the
-          // memory-FILE reads below (a separate, snapshot-scoped read), so non-raw
-          // x-ray decoration stays byte-for-byte unchanged.
-          const rawExcerptNamespace =
-            disclosure === "raw"
-              ? this.resolveRawExcerptReadNamespace(
-                  request.namespace,
-                  trimmedSessionKey,
-                  authenticatedPrincipal,
-                )
-              : namespace;
-          // `undefined` for an IMPLICIT raw recall means NO readable LCM namespace
-          // exists (restrictive `default` READ policy, no readable overlay/self)
-          // — suppress excerpts rather than fall back to the write/overlay
-          // namespace the read gate excludes (#1505 thread NBHWz).
-          const xrayHasExplicitNamespace =
-            typeof request.namespace === "string" &&
-            request.namespace.trim().length > 0;
-          const rawExcerptsSuppressed =
-            disclosure === "raw" &&
-            !xrayHasExplicitNamespace &&
-            rawExcerptNamespace === undefined;
-          // Ordered, read-authorized LCM read key SET (#1505 fallback
-          // unification) so raw disclosure finds excerpts a branch-scoped session
-          // archived at project/root scope — exactly as recall + `lcmSearch` do.
-          // Only meaningful with a concrete sessionKey + a readable namespace;
-          // already read-gated so no unauthorized overlay key is present.
-          const rawExcerptSessionIds =
-            disclosure === "raw" && trimmedSessionKey && rawExcerptNamespace
-              ? this.resolveLcmReadSessionIds(
-                  request.namespace,
-                  rawExcerptNamespace,
-                  trimmedSessionKey,
-                  authenticatedPrincipal,
-                )
-              : undefined;
-          const rawExcerpts =
-            disclosure === "raw" && !rawExcerptsSuppressed
-              ? await this.fetchRawExcerpts(disclosure, {
-                  query,
-                  ...(trimmedSessionKey ? { sessionKey: trimmedSessionKey } : {}),
-                  ...(rawExcerptNamespace
-                    ? { namespace: rawExcerptNamespace }
-                    : {}),
-                  ...(rawExcerptSessionIds !== undefined
-                    ? { lcmSessionIds: rawExcerptSessionIds }
-                    : {}),
-                })
-              : disclosure === "raw"
-                ? []
-                : null;
-          const rawExcerptText =
-            rawExcerpts && rawExcerpts.length > 0
-              ? rawExcerpts.map((e) => e.content).join("\n")
-              : "";
-          // Pre-load every memory in parallel so we can:
-          //   (a) re-attribute raw excerpts to the *first readable* result
-          //       rather than always to index 0 (Cursor Low review on PR
-          //       #699: a missing/unreadable result[0] orphaned the excerpt
-          //       budget); and
-          //   (b) include the metadata fields `shapeMemorySummary` actually
-          //       emits at every depth (id, path, category, status, created,
-          //       updated, tags, entityRef) in the token estimate, so the
-          //       summary reflects real spend rather than only payload-body
-          //       spend (Cursor Low review on PR #699).
-          const memoryByIndex = await Promise.all(
-            snapshot.results.map(async (result) => {
-              try {
-                const storage = await this.orchestrator.getStorage(namespace);
-                return await storage.readMemoryByPath(result.path);
-              } catch {
-                return null;
-              }
-            }),
-          );
-          const firstReadableIndex = memoryByIndex.findIndex((m) => m !== null);
-          const baseDir =
-            (await this.orchestrator.getStorage(namespace)).dir;
-          const decorated = snapshot.results.map((result, index) => {
-            const memory = memoryByIndex[index];
-            if (!memory) {
-              // Unreadable result: attach the disclosure tag anyway so
-              // the per-disclosure summary classifies it correctly,
-              // but skip the token estimate since we don't have the
-              // content to measure.  Without the disclosure tag the
-              // result silently flows into the `unspecified` bucket
-              // even though the caller explicitly requested a depth
-              // (Cursor Low review on PR #699).
-              return { ...result, disclosure };
-            }
-            // Build a representative shaped summary so the estimate
-            // counts every field `shapeMemorySummary` actually emits.
-            // The serialized JSON form is a close-enough proxy for the
-            // wire payload size.
-            const shaped = shapeMemorySummary(
-              memory,
-              baseDir,
-              disclosure,
-              disclosure === "raw" &&
-              index === firstReadableIndex &&
-              rawExcerpts &&
-              rawExcerpts.length > 0
-                ? rawExcerpts
-                : undefined,
-            );
-            return {
-              ...result,
-              disclosure,
-              estimatedTokens: estimateRecallTokens(JSON.stringify(shaped)),
-            };
-          });
-          // Edge case: every result was unreadable but rawExcerpts
-          // still has content — credit that spend to result[0] rather
-          // than dropping it on the floor.  Without this, the raw row
-          // in the per-disclosure summary under-reports spend whenever
-          // every memory file is missing/unreadable.
-          if (
-            disclosure === "raw" &&
-            firstReadableIndex === -1 &&
-            rawExcerptText.length > 0 &&
-            decorated.length > 0
-          ) {
-            decorated[0] = {
-              ...decorated[0]!,
-              disclosure,
-              estimatedTokens: estimateRecallTokens(rawExcerptText),
-            };
-          }
-          const decoratedSnapshot = { ...snapshot, results: decorated };
-          xrayResponse = {
-            snapshotFound: true,
-            snapshot: decoratedSnapshot,
-          };
-        } else {
-          xrayResponse = {
-            snapshotFound: true,
-            snapshot,
-          };
-        }
-      }
-    } finally {
-      release();
-    }
-
-    if (
-      request.includeRecall === true &&
-      xrayResponse.snapshotFound === true &&
-      xrayResponse.snapshot
-    ) {
-      // Same read-authorization-gated raw-excerpt namespace the recall path uses
-      // (#1505 thread 2f7), so the includeRecall x-ray path can't leak overlay
-      // transcript rows via raw disclosure. Resolved ONLY for raw disclosure (the
-      // sole consumer) so non-raw x-ray recall stays byte-for-byte unchanged. The
-      // ordered LCM read key SET (#1505 fallback unification) adds the coding read
-      // fallbacks so a branch-scoped session also finds excerpts at project/root
-      // scope.
-      const xrayRawExcerptNamespace =
-        disclosure === "raw"
-          ? this.resolveRawExcerptReadNamespace(
-              request.namespace,
-              recallSessionKey,
-              authenticatedPrincipal,
-            )
-          : undefined;
-      // `undefined` for an IMPLICIT raw recall means NO readable LCM namespace
-      // exists — suppress excerpts rather than fall back to the write/overlay
-      // namespace the read gate excludes (#1505 thread NBHWz).
-      const xrayHasExplicitNamespace =
-        typeof request.namespace === "string" &&
-        request.namespace.trim().length > 0;
-      const xrayRawExcerptsSuppressed =
-        disclosure === "raw" &&
-        !xrayHasExplicitNamespace &&
-        xrayRawExcerptNamespace === undefined;
-      const xrayRawExcerptSessionIds =
-        disclosure === "raw" && xrayRawExcerptNamespace && recallSessionKey
-          ? this.resolveLcmReadSessionIds(
-              request.namespace,
-              xrayRawExcerptNamespace,
-              recallSessionKey,
-              authenticatedPrincipal,
-            )
-          : undefined;
-      return {
-        ...xrayResponse,
-        recall: await this.buildRecallResponseFromXraySnapshot({
-          query,
-          sessionKey: recallSessionKey,
-          snapshot: xrayResponse.snapshot,
-          disclosure,
-          startedAt: recallStartedAt,
-          requestedMode: request.mode,
-          normalizedMode: mode,
-          ...(xrayRawExcerptNamespace
-            ? { rawExcerptNamespace: xrayRawExcerptNamespace }
-            : {}),
-          ...(xrayRawExcerptSessionIds !== undefined
-            ? { rawExcerptSessionIds: xrayRawExcerptSessionIds }
-            : {}),
-          ...(xrayRawExcerptsSuppressed
-            ? { rawExcerptsSuppressed: xrayRawExcerptsSuppressed }
-            : {}),
-        }),
-      };
-    }
-    return xrayResponse;
+    return this.accessRecallSurface.recallXray(
+      request,
+    );
   }
   // Sequence lock for `recallXray` — see comment inside the method.
   // Lives on the instance so every x-ray call on the same service
@@ -5025,97 +3848,11 @@ export class EngramAccessService {
   }
 
   async reviewQueue(runId?: string, namespace?: string, principal?: string): Promise<EngramAccessReviewQueueResponse> {
-    const resolvedNamespace = this.resolveReadableNamespace(namespace, principal);
-    const storage = await this.orchestrator.getStorage(resolvedNamespace);
-    const projected = await storage.getProjectedGovernanceRecord();
-    if (projected && (!runId || projected.runId === runId.trim())) {
-      const projectedAppliedActions = projected.appliedActionRows.map((row) => ({
-        action: row.action,
-        memoryId: row.memoryId,
-        reasonCode: row.reasonCode,
-        beforeStatus: row.beforeStatus,
-        afterStatus: row.afterStatus,
-        originalPath: row.originalPath,
-        currentPath: row.currentPath,
-      })) as Awaited<
-        ReturnType<typeof readMemoryGovernanceRunArtifact>
-      >["appliedActions"];
-      const projectedProposedActions = await buildProjectedGovernanceProposedActions(storage, projected);
-      const projectedArtifact = await (async () => {
-        try {
-          return await readMemoryGovernanceRunArtifact(storage.dir, projected.runId);
-        } catch {
-          return null;
-        }
-      })();
-      const metrics = projected.metrics as Awaited<ReturnType<typeof readMemoryGovernanceRunArtifact>>["metrics"];
-      const fallbackTransitionReport = {
-        proposed: groupActionsByStatus(projectedProposedActions),
-        applied: groupActionsByStatus(projectedAppliedActions),
-      };
-      const transitionReport = projectedArtifact?.transitionReport
-        ? {
-            proposed:
-              hasGroupedGovernanceActions(projectedArtifact.transitionReport.proposed) || projectedProposedActions.length === 0
-                ? projectedArtifact.transitionReport.proposed
-                : fallbackTransitionReport.proposed,
-            applied:
-              hasGroupedGovernanceActions(projectedArtifact.transitionReport.applied) || projectedAppliedActions.length === 0
-                ? projectedArtifact.transitionReport.applied
-                : fallbackTransitionReport.applied,
-          }
-        : fallbackTransitionReport;
-      const qualityScore = projectedArtifact?.qualityScore ?? metrics?.qualityScore ?? buildQualityScore(metrics?.reviewReasons ?? {
-        exact_duplicate: 0,
-        semantic_duplicate_candidate: 0,
-        disputed_memory: 0,
-        speculative_low_confidence: 0,
-        archive_candidate: 0,
-        explicit_capture_review: 0,
-        malformed_import: 0,
-      });
-      const effectiveMetrics = metrics ? { ...metrics, qualityScore: metrics.qualityScore ?? qualityScore } : metrics;
-
-      return {
-        found: true,
-        namespace: resolvedNamespace,
-        runId: projected.runId,
-        summary: projected.summary as Awaited<ReturnType<typeof readMemoryGovernanceRunArtifact>>["summary"],
-        metrics: effectiveMetrics,
-        qualityScore,
-        reviewQueue: projected.reviewQueueRows.map((row) => ({
-          entryId: row.entryId,
-          memoryId: row.memoryId,
-          path: row.path,
-          reasonCode: row.reasonCode,
-          severity: row.severity,
-          suggestedAction: row.suggestedAction,
-          suggestedStatus: row.suggestedStatus,
-          relatedMemoryIds: row.relatedMemoryIds,
-        })) as Awaited<
-          ReturnType<typeof readMemoryGovernanceRunArtifact>
-        >["reviewQueue"],
-        appliedActions: projectedAppliedActions,
-        transitionReport,
-        report: projected.report,
-      };
-    }
-
-    const resolvedRunId = runId?.trim() || (await listMemoryGovernanceRuns(storage.dir))[0];
-    if (!resolvedRunId) return { found: false, namespace: resolvedNamespace };
-    const artifact = await readMemoryGovernanceRunArtifact(storage.dir, resolvedRunId);
-    return {
-      found: true,
-      namespace: resolvedNamespace,
-      runId: resolvedRunId,
-      summary: artifact.summary,
-      metrics: artifact.metrics,
-      qualityScore: artifact.qualityScore,
-      reviewQueue: artifact.reviewQueue,
-      appliedActions: artifact.appliedActions,
-      transitionReport: artifact.transitionReport,
-      report: artifact.report,
-    };
+    return this.accessAdminOpsSurface.reviewQueue(
+      runId,
+      namespace,
+      principal,
+    );
   }
 
   async maintenance(namespace?: string, principal?: string): Promise<EngramAccessMaintenanceResponse> {
@@ -5200,56 +3937,10 @@ export class EngramAccessService {
     summaryPath: string;
     reportPath: string;
   }> {
-    const deepSleep = this.orchestrator.config.dreamsPhases.deepSleep;
-    if (deepSleep.enabled === false && deepSleep.enabledExplicitlySet === true) {
-      throw new Error("memory governance is disabled by dreams.phases.deepSleep.enabled=false");
-    }
-    const resolvedNamespace = this.writableNamespaceFor(
-      request.namespace,
-      undefined,
-      request.authenticatedPrincipal ?? principal,
+    return this.accessAdminOpsSurface.governanceRun(
+      request,
+      principal,
     );
-    const storage = await this.orchestrator.getStorage(resolvedNamespace);
-    const mode = request.mode === "apply" ? "apply" : "shadow";
-    const boundedBatchSize =
-      typeof request.batchSize === "number" && Number.isFinite(request.batchSize)
-        ? Math.max(1, Math.floor(request.batchSize))
-        : undefined;
-    const result = await runMemoryGovernance({
-      memoryDir: storage.dir,
-      mode,
-      recentDays:
-        typeof request.recentDays === "number" && Number.isFinite(request.recentDays)
-          ? Math.max(1, Math.floor(request.recentDays))
-          : undefined,
-      maxMemories:
-        typeof request.maxMemories === "number" && Number.isFinite(request.maxMemories)
-          ? Math.max(1, Math.floor(request.maxMemories))
-          : undefined,
-      batchSize: boundedBatchSize,
-    });
-    if (mode === "apply") {
-      try {
-        await this.orchestrator.processEntitySynthesisQueue(
-          resolvedNamespace,
-          Math.min(boundedBatchSize ?? 5, 5),
-        );
-      } catch (error) {
-        log.debug(`governanceRun: entity synthesis refresh failed after governance apply: ${error}`);
-      }
-    }
-
-    return {
-      namespace: resolvedNamespace,
-      runId: result.runId,
-      traceId: result.traceId,
-      mode: result.mode,
-      reviewQueueCount: result.reviewQueue.length,
-      proposedActionCount: result.proposedActions.length,
-      appliedActionCount: result.appliedActions.length,
-      summaryPath: result.summaryPath,
-      reportPath: result.reportPath,
-    };
   }
 
   async procedureMiningRun(
@@ -5415,160 +4106,17 @@ export class EngramAccessService {
     reason?: string;
     retryAfterMs?: number;
   }> {
-    if (!resolveIndexingCapabilities(this.orchestrator.config).conversationIndex) {
-      return {
-        enabled: false,
-        sessions: 0,
-        chunks: 0,
-        skipped: 0,
-        skippedSessionKeys: [],
-        embeddedRuns: 0,
-        reason: "disabled",
-      };
-    }
-
-    const hours =
-      typeof request.hours === "number" && Number.isFinite(request.hours)
-        ? Math.max(1, Math.floor(request.hours))
-        : 24;
-
-    let sessionKey: string | undefined;
-    if (request.sessionKey !== undefined) {
-      if (typeof request.sessionKey !== "string" || request.sessionKey.trim().length === 0) {
-        throw new EngramAccessInputError("sessionKey must be a non-empty string when provided");
-      }
-      sessionKey = request.sessionKey.trim();
-    }
-
-    if (sessionKey) {
-      const result = await this.orchestrator.updateConversationIndex(
-        sessionKey,
-        hours,
-        { embed: request.embed },
-      );
-      return {
-        enabled: true,
-        sessionKey,
-        sessions: 1,
-        chunks: result.chunks,
-        skipped: result.skipped ? 1 : 0,
-        skippedSessionKeys: result.skipped ? [sessionKey] : [],
-        embeddedRuns: result.embedded ? 1 : 0,
-        reason: result.reason,
-        retryAfterMs: result.retryAfterMs,
-      };
-    }
-
-    const sessionKeys = await this.orchestrator.transcript.listSessionKeys();
-    let chunks = 0;
-    let skipped = 0;
-    const skippedSessionKeys: string[] = [];
-    let embeddedRuns = 0;
-
-    for (const sessionKey of sessionKeys) {
-      const result = await this.orchestrator.updateConversationIndex(
-        sessionKey,
-        hours,
-        { embed: request.embed },
-      );
-      chunks += result.chunks;
-      if (result.skipped) {
-        skipped += 1;
-        skippedSessionKeys.push(sessionKey);
-      }
-      if (result.embedded) {
-        embeddedRuns += 1;
-      }
-    }
-
-    return {
-      enabled: true,
-      sessions: sessionKeys.length,
-      chunks,
-      skipped,
-      skippedSessionKeys,
-      embeddedRuns,
-    };
+    return this.accessAdminOpsSurface.conversationIndexUpdate(
+      request,
+    );
   }
 
   async profilingReport(
     request: AccessProfilingReportRequest = {},
   ): Promise<AccessProfilingReportResponse> {
-    const profiler = this.orchestrator.profiler;
-    if (!profiler.isEnabled) {
-      return {
-        enabled: false,
-        reason: "disabled",
-        message: "Profiling is disabled. Set profilingEnabled: true in your plugin config to enable.",
-      };
-    }
-
-    const format = request.format ?? "ascii";
-    if (format !== "ascii" && format !== "json") {
-      throw new EngramAccessInputError("format must be one of: ascii, json");
-    }
-
-    const limit = request.limit ?? 5;
-    if (!Number.isInteger(limit) || limit < 1 || limit > 20) {
-      throw new EngramAccessInputError("limit must be an integer between 1 and 20");
-    }
-
-    const traces = profiler.getRecentTraces(limit);
-    const stats = profiler.getStats();
-    const bottleneck = profiler.identifyBottleneck();
-
-    if (format === "json") {
-      return {
-        enabled: true,
-        format,
-        traces,
-        stats,
-        bottleneck,
-      };
-    }
-
-    const lines: string[] = [];
-    lines.push("Engram Profiling Report");
-    lines.push("=".repeat(60));
-    lines.push("");
-
-    type BucketEntry = { count: number; avgMs: number; p50Ms: number; p95Ms: number; maxMs: number };
-    const allBuckets: Array<[string, Record<string, BucketEntry>]> = [
-      ["byKind", stats.byKind],
-      ["bySpan", stats.bySpan],
-    ];
-    const hasStats = allBuckets.some(([, entries]) => Object.keys(entries).length > 0);
-    if (hasStats) {
-      lines.push("Aggregate Stats (all retained traces):");
-      for (const [bucket, entries] of allBuckets) {
-        for (const [key, summary] of Object.entries(entries)) {
-          lines.push(
-            `  ${bucket}/${key}: avg=${summary.avgMs}ms p50=${summary.p50Ms}ms p95=${summary.p95Ms}ms max=${summary.maxMs}ms (n=${summary.count})`,
-          );
-        }
-      }
-      lines.push("");
-    }
-
-    if (bottleneck) {
-      lines.push(`Bottleneck: ${bottleneck}`);
-      lines.push("");
-    }
-
-    if (traces.length === 0) {
-      lines.push("No traces recorded yet. Trigger a recall or extraction to see timing data.");
-    } else {
-      for (const trace of traces) {
-        lines.push(formatProfileTraceAscii(trace));
-        lines.push("");
-      }
-    }
-
-    return {
-      enabled: true,
-      format,
-      report: lines.join("\n"),
-    };
+    return this.accessAdminOpsSurface.profilingReport(
+      request,
+    );
   }
 
   async trustZoneStatus(namespace?: string, principal?: string): Promise<EngramAccessTrustZoneStatusResponse> {
@@ -7506,134 +6054,14 @@ export class EngramAccessService {
     return { explanation };
   }
 
-  /**
-   * Read-only graph snapshot for the admin pane (issue #691 PR 2/5).
-   *
-   * Reads adjacency from the JSONL edge store written by `GraphIndex` and
-   * resolves node metadata via the namespaced storage manager.  Namespace
-   * resolution mirrors the read-side path used by `recall` /
-   * `procedureStats`, so multi-principal deployments can't leak edges from
-   * a peer namespace (CLAUDE.md rule 42).
-   */
   async graphSnapshot(
     request: GraphSnapshotRequest & { namespace?: string },
     authenticatedPrincipal?: string,
   ): Promise<GraphSnapshotResponse> {
-    const namespace = this.resolveReadableNamespace(
-      request.namespace,
+    return this.accessAdminOpsSurface.graphSnapshot(
+      request,
       authenticatedPrincipal,
     );
-    const storage = await this.orchestrator.getStorage(namespace);
-    const cfg = this.orchestrator.config;
-    const graphCaps = resolveGraphConstructionCapabilities(cfg);
-    // Canonicalize the storage root once — through `realpath` so that any
-    // symlink in the namespace root path itself is resolved before we
-    // compare children against it.  This is required because
-    // `GraphEdge.from` / `to` are JSONL-parsed strings — a malformed edge
-    // with an absolute path, a `..` segment, OR a symlink that resolves
-    // to a file outside the namespace would otherwise read a memory file
-    // from a peer namespace, leaking metadata across tenants
-    // (codex P1 + follow-up on PR #734; CLAUDE.md rule 42).
-    let namespaceRootReal: string;
-    try {
-      namespaceRootReal = await nodeFs.realpath(storage.dir);
-    } catch {
-      // If the namespace root itself doesn't exist on disk yet (fresh
-      // install with no memories), fall back to the lexical resolve so
-      // the snapshot can still return an empty result rather than
-      // throwing.  No symlink can resolve through a missing path, so
-      // this fallback is safe — every candidate we see will fail the
-      // realpath step below and surface as `null`.
-      namespaceRootReal = nodePath.resolve(storage.dir);
-    }
-    const namespaceRootWithSep = namespaceRootReal.endsWith(nodePath.sep)
-      ? namespaceRootReal
-      : namespaceRootReal + nodePath.sep;
-    const loadNode = async (relPath: string): Promise<GraphSnapshotNodeMetadata | null> => {
-      // `GraphEdge.from` / `to` are storage-relative paths; resolve against
-      // the namespaced storage root so the metadata read honors namespace
-      // boundaries even when the same memory id exists in multiple
-      // namespaces.
-      //
-      // Three-stage guard:
-      //   1. Reject absolute paths up front — only relative endpoints are
-      //      ever produced by the writer, so anything else is malformed.
-      //   2. Lexical containment check on the resolved path.  This catches
-      //      `..` traversals before we touch the filesystem.
-      //   3. `fs.realpath` containment check — resolves symlinks so an
-      //      in-namespace path that *points* at an out-of-namespace file
-      //      is still rejected.  Without this step a symlinked endpoint
-      //      could leak a peer namespace's frontmatter.
-      // Bad paths surface a length-only warning (never echo the offending
-      // segments — those would themselves cross namespace boundaries
-      // through the log surface) and fall through to a `null` metadata
-      // result.
-      if (nodePath.isAbsolute(relPath)) {
-        log.warn(
-          `graphSnapshot: rejected absolute edge endpoint (len=${relPath.length}) `
-          + `outside namespace root`,
-        );
-        return null;
-      }
-      const candidate = nodePath.resolve(namespaceRootReal, relPath);
-      if (candidate !== namespaceRootReal && !candidate.startsWith(namespaceRootWithSep)) {
-        log.warn(
-          `graphSnapshot: rejected traversing edge endpoint (len=${relPath.length}) `
-          + `outside namespace root`,
-        );
-        return null;
-      }
-      let canonical: string;
-      try {
-        canonical = await nodeFs.realpath(candidate);
-      } catch {
-        // Missing file — `readMemoryByPath` will return null too.  We
-        // intentionally still call it so callers see a consistent
-        // "unknown" result rather than special-casing missing edges.
-        canonical = candidate;
-      }
-      if (canonical !== namespaceRootReal && !canonical.startsWith(namespaceRootWithSep)) {
-        log.warn(
-          `graphSnapshot: rejected symlinked edge endpoint (len=${relPath.length}) `
-          + `that resolved outside namespace root`,
-        );
-        return null;
-      }
-      // Both `canonical` (realpath of candidate) and `namespaceRootReal`
-      // (realpath of storage.dir) are fully resolved here, so the
-      // containment check above is comparing apples-to-apples even when
-      // storage.dir (= storage.baseDir) is itself a symlink to the real
-      // directory.  Pass `canonical` — not the pre-realpath `candidate` —
-      // so the storage read also uses the stable real path.
-      const memory = await storage.readMemoryByPath(canonical);
-      if (!memory) return null;
-      const fm = memory.frontmatter;
-      return {
-        category: fm.category ?? "unknown",
-        label: fm.id ?? nodePath.basename(canonical, nodePath.extname(canonical)),
-        updated: fm.updated,
-      };
-    };
-    // Use the realpath-resolved namespace root for the edge-file read so
-    // the JSONL location is stable whether storage.dir is a direct path
-    // or a symlink.  namespaceRootReal was computed via `fs.realpath`
-    // above; using it here keeps both the graph-file I/O and the loadNode
-    // containment check on the same resolved base path.
-    return buildGraphSnapshot({
-      memoryDir: namespaceRootReal,
-      graphConfig: {
-        entityGraph: graphCaps.entityGraph,
-        timeGraph: graphCaps.timeGraph,
-        causalGraph: graphCaps.causalGraph,
-      },
-      request: {
-        limit: request.limit,
-        since: request.since,
-        focusNodeId: request.focusNodeId,
-        categories: request.categories,
-      },
-      loadNode,
-    });
   }
 
   async memoryFeedback(request: {
@@ -8330,108 +6758,13 @@ export class EngramAccessService {
     });
   }
 
-  /**
-   * List capsule archives in the namespace-scoped capsule store.
-   *
-   * MCP uses this access-layer method instead of reading arbitrary paths so
-   * capsule discovery remains bound to the same namespace ACLs as export and
-   * import.
-   */
   async capsuleList(options?: {
     namespace?: string;
     principal?: string;
   }): Promise<EngramAccessCapsuleListResponse> {
-    const resolvedNamespace = this.resolveReadableNamespace(options?.namespace, options?.principal);
-    const storage = await this.orchestrator.getStorage(resolvedNamespace);
-    const capsulesDir = defaultCapsulesDir(storage.dir);
-    let dirEntries: import("node:fs").Dirent[];
-    try {
-      const capsulesDirStat = await nodeFs.lstat(capsulesDir);
-      if (capsulesDirStat.isSymbolicLink()) {
-        throw new EngramAccessInputError("capsule list failed: capsule store directory must not be a symlink");
-      }
-      if (!capsulesDirStat.isDirectory()) {
-        throw new EngramAccessInputError("capsule list failed: capsule store path must be a directory");
-      }
-      dirEntries = await nodeFs.readdir(capsulesDir, { withFileTypes: true });
-    } catch (err) {
-      const code = typeof err === "object" && err !== null && "code" in err
-        ? (err as { code?: unknown }).code
-        : undefined;
-      if (code === "ENOENT") {
-        return { namespace: resolvedNamespace, capsulesDir, capsules: [] };
-      }
-      throw err;
-    }
-
-    const archiveNames = dirEntries
-      .filter(
-        (entry) =>
-          entry.isFile() &&
-          (entry.name.endsWith(".capsule.json.gz") ||
-            entry.name.endsWith(".capsule.json.gz.enc")),
-      )
-      .map((entry) => entry.name)
-      .sort();
-
-    const capsules: CapsuleListEntry[] = [];
-    for (const archiveName of archiveNames) {
-      const archivePath = nodePath.join(capsulesDir, archiveName);
-      const id = archiveName
-        .replace(/\.capsule\.json\.gz\.enc$/, "")
-        .replace(/\.capsule\.json\.gz$/, "");
-      const manifestPath = nodePath.join(capsulesDir, `${id}.manifest.json`);
-
-      let createdAt: string | null = null;
-      let pluginVersion: string | null = null;
-      let fileCount: number | null = null;
-      let description: string | null = null;
-      let manifestPathOrNull: string | null = manifestPath;
-
-      try {
-        const manifestStat = await nodeFs.lstat(manifestPath);
-        if (manifestStat.isSymbolicLink() || !manifestStat.isFile()) {
-          capsules.push({
-            id,
-            archivePath,
-            manifestPath: manifestPathOrNull,
-            createdAt,
-            pluginVersion,
-            fileCount,
-            description,
-          });
-          continue;
-        }
-        const raw = await nodeFs.readFile(manifestPath, "utf-8");
-        const sidecar = JSON.parse(raw) as Record<string, unknown>;
-        createdAt = typeof sidecar.createdAt === "string" ? sidecar.createdAt : null;
-        pluginVersion = typeof sidecar.pluginVersion === "string" ? sidecar.pluginVersion : null;
-        fileCount = Array.isArray(sidecar.files) ? sidecar.files.length : null;
-        const capsule = sidecar.capsule as Record<string, unknown> | undefined;
-        description = capsule && typeof capsule.description === "string"
-          ? capsule.description
-          : null;
-      } catch (err) {
-        const code = typeof err === "object" && err !== null && "code" in err
-          ? (err as { code?: unknown }).code
-          : undefined;
-        if (code === "ENOENT") {
-          manifestPathOrNull = null;
-        }
-      }
-
-      capsules.push({
-        id,
-        archivePath,
-        manifestPath: manifestPathOrNull,
-        createdAt,
-        pluginVersion,
-        fileCount,
-        description,
-      });
-    }
-
-    return { namespace: resolvedNamespace, capsulesDir, capsules };
+    return this.accessAdminOpsSurface.capsuleList(
+      options,
+    );
   }
 
   /**
@@ -8674,87 +7007,15 @@ export class EngramAccessService {
     return getDreamsStatus(storage.dir, windowHours);
   }
 
-  /**
-   * Manually invoke a single Dreams phase pass (PR 4/4).
-   *
-   * Deep-sleep delegates to memory governance (shadow → dry-run, apply → live).
-   * Light-sleep and REM scan the observation ledger and memory corpus
-   * respectively, returning the same telemetry shape as a scheduled run.
-   */
   async dreamsRun(options: {
     phase: import("./types.js").DreamsPhase;
     dryRun?: boolean;
     namespace?: string;
     authenticatedPrincipal?: string;
   }): Promise<import("./types.js").DreamsRunResult> {
-    const { runDreamsPhase } = await import("./maintenance/dreams-ledger.js");
-    const validPhases = ["lightSleep", "rem", "deepSleep"];
-    if (!validPhases.includes(options.phase)) {
-      throw new EngramAccessInputError(
-        `Invalid phase: ${String(options.phase)}. Must be one of: ${validPhases.join(", ")}`,
-      );
-    }
-    const deepSleep = this.orchestrator.config.dreamsPhases.deepSleep;
-    if (
-      options.phase === "deepSleep" &&
-      deepSleep.enabled === false &&
-      deepSleep.enabledExplicitlySet === true
-    ) {
-      throw new EngramAccessInputError(
-        "memory governance is disabled by dreams.phases.deepSleep.enabled=false",
-      );
-    }
-    const dryRun = options.dryRun === true;
-    const resolvedNamespace = this.writableNamespaceFor(
-      options.namespace,
-      undefined,
-      options.authenticatedPrincipal,
+    return this.accessAdminOpsSurface.dreamsRun(
+      options,
     );
-    const storage = await this.orchestrator.getStorage(resolvedNamespace);
-    const memoryDir = storage.dir;
-    const phaseRunner = dryRun || options.phase === "deepSleep"
-      ? undefined
-      : async (_opts: { memoryDir: string; phase: "lightSleep" | "rem" }) => {
-          if (_opts.phase === "lightSleep") {
-            const result = await this.orchestrator.runLifecyclePolicyNow(storage);
-            return {
-              itemsProcessed: result.memoriesAssessed,
-              notes: `scored ${result.memoriesAssessed} memories`,
-            };
-          }
-          const result = await this.orchestrator.runSemanticConsolidationNow({
-            dryRun: false,
-            storage,
-          });
-          const itemsProcessed = result.clusters.reduce(
-            (sum, cluster) => sum + cluster.memories.length,
-            0,
-          );
-          return {
-            itemsProcessed,
-            notes: `REM consolidation found ${result.clustersFound} clusters`,
-          };
-        };
-    const governanceRunner = options.phase === "deepSleep"
-      ? async (_opts: { memoryDir: string; dryRun: boolean }) => {
-          return this.orchestrator.runDeepSleepGovernanceNow({
-            storage,
-            dryRun: _opts.dryRun,
-          });
-        }
-      : undefined;
-    const result = await runDreamsPhase(
-      { memoryDir, phase: options.phase, dryRun },
-      governanceRunner,
-      phaseRunner,
-    );
-    return {
-      phase: result.phase,
-      dryRun: result.dryRun,
-      durationMs: result.durationMs,
-      itemsProcessed: result.itemsProcessed,
-      notes: result.notes,
-    };
   }
 
   // ---------------------------------------------------------------------------
@@ -8913,12 +7174,6 @@ export class EngramAccessService {
     return redactSensitive(result);
   }
 
-  /**
-   * Manually promote a memory into one or more authorized targets. Requires
-   * a non-empty reason (audit-logged). Reuses the scope-profile promotion
-   * resolution and `canWriteNamespace` gate — there is no dashboard-only
-   * write path.
-   */
   async adminPromoteMemory(request: {
     sourceMemoryId: string;
     namespace?: string;
@@ -8928,111 +7183,9 @@ export class EngramAccessService {
     reason: string;
     actor?: never; // ignored — actor is derived from the authenticated principal
   }) {
-    const config = this.orchestrator.config;
-    const namespacesEnabled = resolveNamespaceCapabilities(config).namespaces === true;
-    // Fix OdCl3: when no namespace is supplied, resolve the source via the
-    // scope plan (principal self / scope-profile write layer / coding overlay)
-    // instead of falling through to config.defaultNamespace. This matches the
-    // runtime observe/write path.
-    let sourceNamespace: string;
-    if (request.namespace) {
-      sourceNamespace = this.resolveReadableNamespace(
-        request.namespace,
-        request.principal,
-      );
-    } else {
-      const codingContext = request.sessionKey
-        ? this.orchestrator.getCodingContextForSession(request.sessionKey) ?? null
-        : null;
-      const plan = resolveScopePlan({
-        config,
-        sessionKey: request.sessionKey,
-        principalOverride: request.principal,
-        codingContext,
-        namespacesEnabled,
-      });
-      sourceNamespace = this.resolveReadableNamespace(
-        plan.baseNamespace,
-        request.principal,
-      );
-    }
-    // Fix OdB0c: thread coding context into the scope-profile plan so
-    // userProject/teamProject promotion targets resolve for project-scoped
-    // sessions (previously hard-coded to null).
-    const codingContext = request.sessionKey
-      ? this.orchestrator.getCodingContextForSession(request.sessionKey) ?? null
-      : null;
-    const codingOverlay = codingContext
-      ? resolveCodingNamespaceOverlay(
-          codingContext,
-          config.codingMode,
-          config.defaultNamespace,
-        )
-      : null;
-    const scopeProfilePlan = resolveScopeProfilePlan({
-      config,
-      principal: request.principal,
-      codingContext,
-      codingOverlay,
-    });
-    const storage: PromotionStorageProvider = {
-      readMemory: async (namespace, memoryId) => {
-        const resolved = await this.orchestrator.getStorage(namespace);
-        const memory = await resolved.getMemoryById(memoryId);
-        if (!memory) return null;
-        return {
-          category: memory.frontmatter.category,
-          content: memory.content,
-          frontmatter: memory.frontmatter,
-        };
-      },
-      writePromotedMemory: async (namespace, memory) => {
-        const resolved = await this.orchestrator.getStorage(namespace);
-        const { id, tombstoneBlocked } = await resolved.writeMemory(
-          memory.category,
-          memory.content,
-          {
-            confidence: memory.confidence,
-            tags: memory.tags,
-            entityRef: memory.entityRef,
-            source: `admin-promotion:${memory.sourceNamespace}:${memory.reason.slice(0, 120)}`,
-            lineage: memory.lineage,
-            sourceMemoryId: memory.sourceMemoryId,
-            actor: memory.actor,
-            validAt: memory.validAt,
-          },
-        );
-        // #1645: a tombstone-blocked promotion lands pending_review (no active
-        // copy in the target). Report it as a failed promotion so the admin
-        // sees an honest result — the content is queued for review, not
-        // actively promoted. promoteMemory's catch block sanitizes this into
-        // a generic "promotion write failed" audit entry.
-        if (tombstoneBlocked) {
-          throw new Error(
-            "target namespace tombstone-blocked the promoted content (pending_review)",
-          );
-        }
-        return id;
-      },
-    };
-    try {
-      return await promoteMemory({
-        config,
-        sourceMemoryId: request.sourceMemoryId,
-        sourceNamespace,
-        principal: request.principal,
-        targets: request.targets,
-        reason: request.reason,
-        actor: request.principal ?? "admin-console",
-        storage,
-        scopeProfilePlan,
-      });
-    } catch (err) {
-      if (err instanceof AdminPromotionError) {
-        throw new EngramAccessInputError(err.message);
-      }
-      throw err;
-    }
+    return this.accessAdminOpsSurface.adminPromoteMemory(
+      request,
+    );
   }
 }