@remnic/core 1.1.12 → 1.1.13

package/dist/chunk-M23FSH32.js

@@ -0,0 +1,3963 @@
+import {
+  exportWorkBoardMarkdown,
+  exportWorkBoardSnapshot,
+  importWorkBoardSnapshot
+} from "./chunk-ZKSK55RC.js";
+import {
+  WorkStorage
+} from "./chunk-WELDCG6C.js";
+import {
+  importCapsule
+} from "./chunk-GGKRUQOO.js";
+import {
+  applyTagFilter,
+  normalizeTags,
+  parseTagMatch
+} from "./chunk-BT7NVCML.js";
+import {
+  decideDisclosureEscalation
+} from "./chunk-H7XKCNR6.js";
+import {
+  toRecallExplainJson
+} from "./chunk-FBYESMQ2.js";
+import {
+  clusterByKey,
+  resolveGitContext
+} from "./chunk-FDU6HUUL.js";
+import {
+  getTrustZoneStoreStatus,
+  isTrustZoneName,
+  listTrustZoneRecords,
+  promoteTrustZoneRecord,
+  scoreTrustZoneProvenance,
+  seedTrustZoneDemoDataset,
+  summarizeTrustZonePromotionReadiness
+} from "./chunk-QDZ2RLEC.js";
+import {
+  estimateRecallTokens
+} from "./chunk-MGKYQQYF.js";
+import {
+  recordObjectiveStateSnapshotsFromObservedMessages
+} from "./chunk-GL6I6MEQ.js";
+import {
+  objectiveStateStoreOverrideForNamespace
+} from "./chunk-5UM2VJ6D.js";
+import {
+  buildProposedActions,
+  buildQualityScore,
+  groupActionsByStatus,
+  listMemoryGovernanceRuns,
+  readMemoryGovernanceRunArtifact,
+  runMemoryGovernance
+} from "./chunk-EFJ3MQ4V.js";
+import {
+  recordMemoryOutcome
+} from "./chunk-EIR5VLIH.js";
+import {
+  buildGraphSnapshot
+} from "./chunk-PCUKNJAZ.js";
+import {
+  wrapWorkLayerContext
+} from "./chunk-RRF5UOBJ.js";
+import {
+  formatProfileTraceAscii
+} from "./chunk-NBNN5GOB.js";
+import {
+  buildProcedurePersistBody,
+  normalizeProcedureSteps
+} from "./chunk-QDW3E4RD.js";
+import {
+  persistExplicitCapture,
+  queueExplicitCaptureForReview,
+  validateExplicitCaptureInput
+} from "./chunk-25MQ7IHJ.js";
+import {
+  CrossNamespaceBudget
+} from "./chunk-GDFS42HT.js";
+import {
+  FileCalendarSource,
+  buildBriefing,
+  parseBriefingFocus,
+  parseBriefingWindow
+} from "./chunk-VW676BEI.js";
+import {
+  parseEntityFile
+} from "./chunk-7AAT6G4Q.js";
+import {
+  DEFAULT_RECALL_DISCLOSURE,
+  isRecallDisclosure
+} from "./chunk-Q7P4WJDP.js";
+import {
+  normalizeProjectionPreview,
+  normalizeProjectionTags
+} from "./chunk-SCU65EZI.js";
+import {
+  getMemoryProjectionPath
+} from "./chunk-3KW65B36.js";
+import {
+  inferMemoryStatus,
+  toMemoryPathRel
+} from "./chunk-RULE4VG5.js";
+import {
+  defaultCapsulesDir
+} from "./chunk-ZY2MNJR6.js";
+import {
+  filterTrajectoriesByLookbackDays,
+  readCausalTrajectoryRecords
+} from "./chunk-MY6TPVXW.js";
+import {
+  canReadNamespace,
+  canWriteNamespace,
+  defaultNamespaceForPrincipal,
+  recallNamespacesForPrincipal,
+  resolvePrincipal
+} from "./chunk-UWVJF25J.js";
+import {
+  log
+} from "./chunk-2ODBA7MQ.js";
+import {
+  AccessAuditAdapter
+} from "./chunk-TVVEYCNW.js";
+import {
+  AccessIdempotencyStore,
+  hashAccessIdempotencyPayload
+} from "./chunk-XKECPATV.js";
+import {
+  exportCapsule
+} from "./chunk-2F2W355T.js";
+import {
+  evaluateActionConfidence
+} from "./chunk-AH2JUU6X.js";
+
+// src/access-service.ts
+import { stat } from "fs/promises";
+import * as nodeFs from "fs/promises";
+import { constants as fsConstants } from "fs";
+import { createHash } from "crypto";
+import { ZodError } from "zod";
+
+// src/procedural/procedure-miner.ts
+var PROCEDURE_CLUSTER_ATTR_MAX = 500;
+function clusterKey(record) {
+  const goal = record.goal.trim().toLowerCase().replace(/\s+/g, " ").slice(0, 120);
+  const refs = [...record.entityRefs ?? []].map((r) => r.trim().toLowerCase()).sort();
+  return `${goal}|${refs.join(",")}`;
+}
+function successRate(group) {
+  if (group.length === 0) return 0;
+  const ok = group.filter((g) => g.outcomeKind === "success" || g.outcomeKind === "partial").length;
+  return ok / group.length;
+}
+function pseudoStepsFromCluster(group) {
+  const sentences = [];
+  const pushUnique = (raw) => {
+    const t = raw.trim();
+    if (t.length < 8) return;
+    if (!sentences.includes(t)) sentences.push(t);
+  };
+  for (const g of group) {
+    const parts = [g.actionSummary, g.observationSummary, g.outcomeSummary].join(" ").split(/[.!?]\s+|;|\n+/).map((s) => s.trim()).filter((s) => s.length > 12);
+    for (const p of parts) pushUnique(p);
+    if (sentences.length >= 5) break;
+  }
+  if (sentences.length < 2 && group[0]) {
+    pushUnique(`${group[0].goal.trim()} \u2014 confirm prerequisites and context.`);
+    pushUnique("Execute the planned actions, then record the outcome.");
+  }
+  return sentences.slice(0, 6).map((intent, i) => ({
+    order: i + 1,
+    intent
+  }));
+}
+async function hasExistingClusterWrite(storage, cluster) {
+  const clusterKey2 = cluster.slice(0, PROCEDURE_CLUSTER_ATTR_MAX);
+  const memories = await storage.readAllMemories();
+  for (const m of memories) {
+    if (m.frontmatter.category !== "procedure") continue;
+    const c = m.frontmatter.structuredAttributes?.procedure_cluster;
+    if (c === clusterKey2) return true;
+  }
+  return false;
+}
+async function runProcedureMining(options) {
+  const cfg = options.config.procedural;
+  if (!cfg?.enabled) {
+    return { clustersProcessed: 0, proceduresWritten: 0, skippedReason: "procedural_disabled" };
+  }
+  if (cfg.minOccurrences <= 0) {
+    return { clustersProcessed: 0, proceduresWritten: 0, skippedReason: "minOccurrences_zero" };
+  }
+  const trajectoryDir = typeof options.config.causalTrajectoryStoreDir === "string" && options.config.causalTrajectoryStoreDir.trim().length > 0 ? options.config.causalTrajectoryStoreDir.trim() : void 0;
+  const { trajectories } = await readCausalTrajectoryRecords({
+    memoryDir: options.memoryDir,
+    causalTrajectoryStoreDir: trajectoryDir
+  });
+  const recent = filterTrajectoriesByLookbackDays(trajectories, cfg.lookbackDays);
+  const clusters = clusterByKey(recent, clusterKey);
+  let clustersProcessed = 0;
+  let proceduresWritten = 0;
+  for (const [key, group] of clusters) {
+    if (group.length < cfg.minOccurrences) continue;
+    const rate = successRate(group);
+    if (rate < cfg.successFloor) continue;
+    clustersProcessed += 1;
+    if (await hasExistingClusterWrite(options.storage, key)) {
+      log.debug(`procedure-miner: skip duplicate cluster key=${key.slice(0, 40)}\u2026`);
+      continue;
+    }
+    const steps = normalizeProcedureSteps(pseudoStepsFromCluster(group));
+    if (steps.length < 2) continue;
+    const title = `When you work on goals like: ${group[0].goal.trim().slice(0, 140)}`;
+    const body = buildProcedurePersistBody(title, steps);
+    const promote = cfg.autoPromoteEnabled === true && group.length >= cfg.autoPromoteOccurrences && rate >= cfg.successFloor;
+    await options.storage.writeMemory("procedure", body, {
+      source: "procedure-miner",
+      status: promote ? "active" : "pending_review",
+      tags: ["procedure-miner", "causal-trajectory"],
+      structuredAttributes: {
+        procedure_cluster: key.slice(0, PROCEDURE_CLUSTER_ATTR_MAX),
+        trajectory_ids: group.map((g) => g.trajectoryId).join(",").slice(0, 1900),
+        trajectory_count: String(group.length),
+        success_rate: rate.toFixed(4)
+      }
+    });
+    proceduresWritten += 1;
+  }
+  return { clustersProcessed, proceduresWritten };
+}
+
+// src/procedural/procedure-stats.ts
+function snapshotConfig(config) {
+  const p = config.procedural;
+  return {
+    enabled: p?.enabled === true,
+    minOccurrences: typeof p?.minOccurrences === "number" ? p.minOccurrences : 0,
+    successFloor: typeof p?.successFloor === "number" ? p.successFloor : 0,
+    autoPromoteOccurrences: typeof p?.autoPromoteOccurrences === "number" ? p.autoPromoteOccurrences : 0,
+    autoPromoteEnabled: p?.autoPromoteEnabled === true,
+    lookbackDays: typeof p?.lookbackDays === "number" ? p.lookbackDays : 0,
+    recallMaxProcedures: typeof p?.recallMaxProcedures === "number" ? p.recallMaxProcedures : 0
+  };
+}
+function tsMs(value) {
+  if (typeof value !== "string") return null;
+  const ms = Date.parse(value);
+  return Number.isFinite(ms) ? ms : null;
+}
+async function computeProcedureStats(options) {
+  const { storage, config } = options;
+  const nowMs = options.nowMs ?? Date.now();
+  const sevenDaysMs = 7 * 24 * 60 * 60 * 1e3;
+  const counts = {
+    total: 0,
+    active: 0,
+    pending_review: 0,
+    rejected: 0,
+    quarantined: 0,
+    superseded: 0,
+    archived: 0,
+    other: 0
+  };
+  let lastWriteMs = null;
+  let writesLast7Days = 0;
+  let minerSourced = 0;
+  const known = [
+    "active",
+    "pending_review",
+    "rejected",
+    "quarantined",
+    "superseded",
+    "archived"
+  ];
+  const seen = /* @__PURE__ */ new Set();
+  const live = await storage.readAllMemories();
+  const archived = await storage.readArchivedMemories();
+  const pool = [...live, ...archived];
+  for (const m of pool) {
+    if (m.frontmatter.category !== "procedure") continue;
+    if (seen.has(m.frontmatter.id)) continue;
+    seen.add(m.frontmatter.id);
+    counts.total += 1;
+    const status = m.frontmatter.status ?? "active";
+    if (known.includes(status)) {
+      counts[status] += 1;
+    } else {
+      counts.other += 1;
+    }
+    const createdMs = tsMs(m.frontmatter.created);
+    const updatedMs = tsMs(m.frontmatter.updated);
+    const latestMs = createdMs !== null && updatedMs !== null ? Math.max(createdMs, updatedMs) : updatedMs ?? createdMs;
+    if (latestMs !== null) {
+      if (lastWriteMs === null || latestMs > lastWriteMs) {
+        lastWriteMs = latestMs;
+      }
+      if (latestMs >= nowMs - sevenDaysMs && latestMs < nowMs) {
+        writesLast7Days += 1;
+      }
+    }
+    if (m.frontmatter.source === "procedure-miner") {
+      minerSourced += 1;
+    }
+  }
+  return {
+    schemaVersion: 1,
+    generatedAt: new Date(nowMs).toISOString(),
+    counts,
+    recent: {
+      lastWriteAt: lastWriteMs !== null ? new Date(lastWriteMs).toISOString() : null,
+      writesLast7Days,
+      minerSourced
+    },
+    config: snapshotConfig(config)
+  };
+}
+function formatProcedureStatsText(report) {
+  const { counts, recent, config } = report;
+  const lines = [];
+  lines.push(`Procedural memory stats (schema v${report.schemaVersion})`);
+  lines.push(`  generated: ${report.generatedAt}`);
+  lines.push("");
+  lines.push(`  config:`);
+  lines.push(`    enabled:                 ${config.enabled}`);
+  lines.push(`    minOccurrences:          ${config.minOccurrences}`);
+  lines.push(`    successFloor:            ${config.successFloor}`);
+  lines.push(`    autoPromoteOccurrences:  ${config.autoPromoteOccurrences}`);
+  lines.push(`    autoPromoteEnabled:      ${config.autoPromoteEnabled}`);
+  lines.push(`    lookbackDays:            ${config.lookbackDays}`);
+  lines.push(`    recallMaxProcedures:     ${config.recallMaxProcedures}`);
+  lines.push("");
+  lines.push(`  counts:`);
+  lines.push(`    total:           ${counts.total}`);
+  lines.push(`    active:          ${counts.active}`);
+  lines.push(`    pending_review:  ${counts.pending_review}`);
+  lines.push(`    rejected:        ${counts.rejected}`);
+  lines.push(`    quarantined:     ${counts.quarantined}`);
+  lines.push(`    superseded:      ${counts.superseded}`);
+  lines.push(`    archived:        ${counts.archived}`);
+  if (counts.other > 0) {
+    lines.push(`    other:           ${counts.other}`);
+  }
+  lines.push("");
+  lines.push(`  recent:`);
+  lines.push(`    lastWriteAt:      ${recent.lastWriteAt ?? "(none)"}`);
+  lines.push(`    writesLast7Days:  ${recent.writesLast7Days}`);
+  lines.push(`    minerSourced:     ${recent.minerSourced}`);
+  return lines.join("\n") + "\n";
+}
+
+// src/access-service.ts
+import * as nodePath from "path";
+var EngramAccessInputError = class extends Error {
+};
+var cachedPackageVersion = null;
+async function getPackageVersion() {
+  if (cachedPackageVersion !== null) return cachedPackageVersion;
+  try {
+    const raw = await nodeFs.readFile(new URL("../package.json", import.meta.url), "utf-8");
+    const parsed = JSON.parse(raw);
+    cachedPackageVersion = typeof parsed.version === "string" && parsed.version.length > 0 ? parsed.version : "unknown";
+  } catch {
+    cachedPackageVersion = "unknown";
+  }
+  return cachedPackageVersion;
+}
+function normalizeTrustZoneInputError(error) {
+  const message = error instanceof Error ? error.message : null;
+  if (!message) {
+    return null;
+  }
+  if (/^sourceRecordId must /.test(message) || /^promotionReason must /.test(message) || /^recordedAt must /.test(message) || /^trust zone promotion requires /.test(message) || /^source trust-zone record not found: /.test(message) || /^trust-zone promotion denied: /.test(message) || /^trust zone demo seed requires /.test(message) || /^unsupported trust-zone demo scenario: /.test(message)) {
+    return new EngramAccessInputError(message);
+  }
+  return null;
+}
+var ENGRAM_ACCESS_WRITE_SCHEMA_VERSION = 1;
+async function buildProjectedGovernanceProposedActions(storage, projected) {
+  const 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
+  }));
+  const memories = (await Promise.all(projected.reviewQueueRows.map((row) => storage.getMemoryById(row.memoryId)))).filter((memory) => Boolean(memory));
+  return buildProposedActions(reviewQueue, memories);
+}
+function hasGroupedGovernanceActions(grouped) {
+  if (!grouped) return false;
+  return Object.values(grouped).some((actions) => Array.isArray(actions) && actions.length > 0);
+}
+function normalizePagination(limit, offset) {
+  const normalizedLimit = Number.isFinite(limit) ? Math.max(1, Math.min(200, Math.floor(limit ?? 50))) : 50;
+  const normalizedOffset = Number.isFinite(offset) ? Math.max(0, Math.floor(offset ?? 0)) : 0;
+  return { limit: normalizedLimit, offset: normalizedOffset };
+}
+function normalizeBrowseSort(sort) {
+  switch (sort) {
+    case "updated_asc":
+    case "created_desc":
+    case "created_asc":
+      return sort;
+    case "updated_desc":
+    default:
+      return "updated_desc";
+  }
+}
+function bucketMemoryAge(referenceIso, nowMs) {
+  const referenceMs = referenceIso ? Date.parse(referenceIso) : Number.NaN;
+  if (!Number.isFinite(referenceMs)) return "unknown";
+  const ageDays = Math.floor((nowMs - referenceMs) / 864e5);
+  if (ageDays <= 7) return "0_7_days";
+  if (ageDays <= 30) return "8_30_days";
+  if (ageDays <= 90) return "31_90_days";
+  return "91_plus_days";
+}
+function incrementCount(counts, key) {
+  counts[key] = (counts[key] ?? 0) + 1;
+}
+function summarizeTrustZoneRecord(record, filePath, allRecords, poisoningDefenseEnabled, trustZonesEnabled, promotionEnabled) {
+  const trustScore = poisoningDefenseEnabled ? scoreTrustZoneProvenance(record) : void 0;
+  const readiness = summarizeTrustZonePromotionReadiness({
+    record,
+    allRecords,
+    poisoningDefenseEnabled
+  });
+  const promotionReasons = [...readiness.reasons];
+  const promotionAllowed = readiness.allowed && trustZonesEnabled === true && promotionEnabled === true;
+  if (trustZonesEnabled !== true) {
+    promotionReasons.push("trust zone promotion requires trustZonesEnabled=true");
+  }
+  if (promotionEnabled !== true) {
+    promotionReasons.push("trust zone promotion requires quarantinePromotionEnabled=true");
+  }
+  return {
+    recordId: record.recordId,
+    filePath,
+    zone: record.zone,
+    recordedAt: record.recordedAt,
+    kind: record.kind,
+    summary: record.summary,
+    sourceClass: record.provenance.sourceClass,
+    sessionKey: record.provenance.sessionKey,
+    sourceId: record.provenance.sourceId,
+    evidenceHashPresent: typeof record.provenance.evidenceHash === "string",
+    anchored: Boolean(record.provenance.sourceId && record.provenance.evidenceHash),
+    entityRefs: [...record.entityRefs ?? []],
+    tags: [...record.tags ?? []],
+    metadata: record.metadata,
+    trustScore,
+    nextPromotionTarget: readiness.nextTargetZone,
+    nextPromotionAllowed: promotionAllowed,
+    nextPromotionReasons: promotionReasons,
+    corroborationCount: readiness.requiresCorroboration ? readiness.corroborationCount : void 0,
+    corroborationSourceClasses: readiness.requiresCorroboration ? readiness.corroborationSourceClasses : void 0
+  };
+}
+function compareBrowseMemory(sort, left, right) {
+  const leftUpdated = left.frontmatter.updated ?? left.frontmatter.created ?? "";
+  const rightUpdated = right.frontmatter.updated ?? right.frontmatter.created ?? "";
+  const leftCreated = left.frontmatter.created ?? "";
+  const rightCreated = right.frontmatter.created ?? "";
+  switch (sort) {
+    case "updated_asc":
+      return leftUpdated.localeCompare(rightUpdated) || leftCreated.localeCompare(rightCreated) || left.frontmatter.id.localeCompare(right.frontmatter.id);
+    case "created_desc":
+      return rightCreated.localeCompare(leftCreated) || rightUpdated.localeCompare(leftUpdated) || left.frontmatter.id.localeCompare(right.frontmatter.id);
+    case "created_asc":
+      return leftCreated.localeCompare(rightCreated) || leftUpdated.localeCompare(rightUpdated) || left.frontmatter.id.localeCompare(right.frontmatter.id);
+    case "updated_desc":
+    default:
+      return rightUpdated.localeCompare(leftUpdated) || rightCreated.localeCompare(leftCreated) || left.frontmatter.id.localeCompare(right.frontmatter.id);
+  }
+}
+function shapeMemorySummary(memory, baseDir, disclosure, rawExcerpts) {
+  const includeFullContent = disclosure === "section" || disclosure === "raw";
+  return {
+    id: memory.frontmatter.id,
+    path: memory.path,
+    category: memory.frontmatter.category,
+    status: inferMemoryStatus(memory.frontmatter, toMemoryPathRel(baseDir, memory.path)),
+    created: memory.frontmatter.created,
+    updated: memory.frontmatter.updated,
+    tags: normalizeProjectionTags(memory.frontmatter.tags),
+    entityRef: memory.frontmatter.entityRef,
+    preview: normalizeProjectionPreview(memory.content),
+    ...disclosure !== void 0 ? { disclosure } : {},
+    ...includeFullContent ? { content: memory.content } : {},
+    ...disclosure === "raw" && rawExcerpts !== void 0 ? { rawExcerpts } : {}
+  };
+}
+var EngramAccessService = class {
+  constructor(orchestrator) {
+    this.orchestrator = orchestrator;
+    this.idempotency = new AccessIdempotencyStore(orchestrator.config.memoryDir);
+    this.budget = new CrossNamespaceBudget({
+      enabled: orchestrator.config.recallCrossNamespaceBudgetEnabled,
+      windowMs: orchestrator.config.recallCrossNamespaceBudgetWindowMs,
+      softLimit: orchestrator.config.recallCrossNamespaceBudgetSoftLimit,
+      hardLimit: orchestrator.config.recallCrossNamespaceBudgetHardLimit
+    });
+    const auditEnabled = orchestrator.config.recallAuditAnomalyDetectionEnabled === true;
+    const auditLogEnabled = false;
+    if (auditEnabled || auditLogEnabled) {
+      const auditConfig = {
+        audit: {
+          enabled: auditLogEnabled,
+          rootDir: orchestrator.config.memoryDir
+        },
+        detection: {
+          enabled: auditEnabled,
+          windowMs: orchestrator.config.recallAuditAnomalyWindowMs,
+          repeatQueryLimit: orchestrator.config.recallAuditAnomalyRepeatQueryLimit,
+          namespaceWalkLimit: orchestrator.config.recallAuditAnomalyNamespaceWalkLimit,
+          highCardinalityReturnLimit: orchestrator.config.recallAuditAnomalyHighCardinalityLimit,
+          rapidFireLimit: orchestrator.config.recallAuditAnomalyRapidFireLimit
+        }
+      };
+      this.auditAdapter = new AccessAuditAdapter(auditConfig);
+    } else {
+      this.auditAdapter = null;
+    }
+  }
+  orchestrator;
+  idempotency;
+  idempotencyLocks = /* @__PURE__ */ new Map();
+  budgetLocks = /* @__PURE__ */ new Map();
+  budget;
+  auditAdapter;
+  get briefingEnabled() {
+    return this.orchestrator.config.briefing?.enabled === true;
+  }
+  resolveNamespace(namespace) {
+    const requested = namespace?.trim();
+    if (!requested) return this.orchestrator.config.defaultNamespace;
+    if (!this.orchestrator.config.namespacesEnabled && requested !== this.orchestrator.config.defaultNamespace) {
+      throw new EngramAccessInputError(`unsupported namespace: ${requested}`);
+    }
+    return requested;
+  }
+  normalizeRecallMode(mode) {
+    if (!mode || mode === "auto") return void 0;
+    if (mode === "no_recall" || mode === "minimal" || mode === "full" || mode === "graph_mode") {
+      return mode;
+    }
+    throw new EngramAccessInputError(`unsupported recall mode: ${mode}`);
+  }
+  resolveRecallNamespace(namespace, sessionKey, authenticatedPrincipal) {
+    const requested = namespace?.trim();
+    if (!requested) return void 0;
+    const resolved = this.resolveNamespace(requested);
+    const principal = this.resolveRequestPrincipal(sessionKey, authenticatedPrincipal);
+    if (!canReadNamespace(principal, resolved, this.orchestrator.config)) {
+      throw new EngramAccessInputError(`namespace override is not readable: ${resolved}`);
+    }
+    return resolved;
+  }
+  resolveRequestPrincipal(sessionKey, authenticatedPrincipal) {
+    const trusted = authenticatedPrincipal?.trim();
+    if (trusted) return trusted;
+    return resolvePrincipal(sessionKey, this.orchestrator.config);
+  }
+  resolveWritableNamespace(namespace, sessionKey, authenticatedPrincipal) {
+    const resolved = this.resolveNamespace(namespace);
+    const principal = this.resolveRequestPrincipal(sessionKey, authenticatedPrincipal);
+    if (!canWriteNamespace(principal, resolved, this.orchestrator.config)) {
+      throw new EngramAccessInputError(`namespace is not writable: ${resolved}`);
+    }
+    return resolved;
+  }
+  async objectiveStateStoreLocationForNamespace(namespace) {
+    if (!this.orchestrator.config.namespacesEnabled) {
+      return {
+        memoryDir: this.orchestrator.config.memoryDir,
+        objectiveStateStoreDir: this.orchestrator.config.objectiveStateStoreDir
+      };
+    }
+    const storage = await this.orchestrator.getStorage(namespace);
+    return {
+      memoryDir: storage.dir,
+      objectiveStateStoreDir: objectiveStateStoreOverrideForNamespace({
+        memoryDir: this.orchestrator.config.memoryDir,
+        configuredStoreDir: this.orchestrator.config.objectiveStateStoreDir,
+        namespacesEnabled: this.orchestrator.config.namespacesEnabled,
+        namespace
+      })
+    };
+  }
+  resolveReadableNamespace(namespace, principal) {
+    const resolved = this.resolveNamespace(namespace);
+    const namespacesEnabled = this.orchestrator.config.namespacesEnabled;
+    if (!namespacesEnabled) {
+      return resolved;
+    }
+    if (!principal) {
+      throw new EngramAccessInputError(
+        "authentication required: namespaces are enabled and no principal was supplied"
+      );
+    }
+    if (!canReadNamespace(principal, resolved, this.orchestrator.config)) {
+      throw new EngramAccessInputError(`namespace is not readable: ${resolved}`);
+    }
+    return resolved;
+  }
+  async buildRecallDebug(snapshot, namespace, includeDebug, sessionKey) {
+    if (!includeDebug) return void 0;
+    if (!sessionKey?.trim()) return void 0;
+    const [intent, graph] = await Promise.all([
+      this.orchestrator.getLastIntentSnapshot(namespace),
+      this.orchestrator.getLastGraphRecallSnapshot(namespace)
+    ]);
+    return snapshot || intent || graph ? {
+      snapshot: snapshot ?? void 0,
+      intent,
+      graph
+    } : void 0;
+  }
+  async buildRecallResponseFromXraySnapshot(options) {
+    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 = {
+      sessionKey: options.sessionKey ?? "",
+      recordedAt: new Date(options.snapshot.capturedAt).toISOString(),
+      queryHash: createHash("sha256").update(options.query).digest("hex"),
+      queryLen: options.query.length,
+      memoryIds,
+      namespace,
+      traceId: options.snapshot.traceId,
+      plannerMode: options.normalizedMode,
+      requestedMode: options.requestedMode && options.requestedMode !== "auto" ? options.requestedMode : void 0,
+      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 } : {}
+      }
+    );
+    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
+    };
+  }
+  async serializeRecallResults(snapshot, disclosure, rawContext = null) {
+    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 results = [];
+    const seen = /* @__PURE__ */ new Set();
+    const rawExcerptsResult = await this.fetchRawExcerpts(
+      disclosure,
+      rawContext ? { ...rawContext, namespace } : null
+    );
+    const rawExcerpts = rawExcerptsResult ?? void 0;
+    for (const memoryPath of snapshot.resultPaths ?? []) {
+      if (!memoryPath || seen.has(memoryPath)) continue;
+      const memory = await storage.readMemoryByPath(memoryPath);
+      if (!memory) continue;
+      seen.add(memoryPath);
+      results.push(
+        this.serializeMemorySummary(
+          memory,
+          storageDir,
+          disclosure,
+          // Attach the (possibly empty) raw excerpts to the first raw
+          // result; subsequent results do not duplicate the array.
+          results.length === 0 ? rawExcerpts : void 0
+        )
+      );
+    }
+    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 : void 0
+        )
+      );
+    }
+    return results;
+  }
+  /**
+   * 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.
+   */
+  async fetchRawExcerpts(disclosure, context) {
+    if (disclosure !== "raw") return null;
+    if (!context || !context.query) return [];
+    if (!context.sessionKey) return [];
+    const lcm = this.orchestrator.lcmEngine;
+    if (!lcm || !lcm.enabled) return [];
+    try {
+      const lcmSessionKey = context.namespace && context.namespace !== this.orchestrator.config.defaultNamespace ? `${context.namespace}:${context.sessionKey}` : context.sessionKey;
+      const rows = await lcm.searchContextFull(
+        context.query,
+        // 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.
+        5,
+        lcmSessionKey
+      );
+      return rows.map((r) => ({
+        turnIndex: r.turn_index,
+        role: r.role,
+        content: r.content,
+        sessionId: r.session_id
+      }));
+    } catch {
+      return [];
+    }
+  }
+  async handleIdempotentWrite(options) {
+    if (options.skip === true) {
+      return options.execute();
+    }
+    const key = options.idempotencyKey?.trim();
+    if (!key) {
+      return options.execute();
+    }
+    return this.withIdempotencyLock(key, async () => {
+      return this.idempotency.withKeyLock(key, async () => {
+        const requestHash = hashAccessIdempotencyPayload({
+          operation: options.operation,
+          request: options.requestFingerprint
+        });
+        const existing = await this.idempotency.get(key, requestHash);
+        if (existing.conflict) {
+          throw new EngramAccessInputError(`idempotencyKey reuse conflict: ${key}`);
+        }
+        if (existing.response) {
+          return {
+            ...existing.response,
+            idempotencyReplay: true
+          };
+        }
+        const response = await options.execute();
+        await this.idempotency.put(key, requestHash, response);
+        return response;
+      });
+    });
+  }
+  async handleIdempotentRead(options) {
+    const key = options.idempotencyKey?.trim();
+    if (!key) {
+      const response = await options.execute();
+      await options.afterStore?.(response);
+      return response;
+    }
+    return this.withIdempotencyLock(key, async () => {
+      return this.idempotency.withKeyLock(key, async () => {
+        const requestHash = hashAccessIdempotencyPayload({
+          operation: options.operation,
+          request: options.requestFingerprint
+        });
+        const existing = await this.idempotency.get(key, requestHash);
+        if (existing.conflict) {
+          throw new EngramAccessInputError(`idempotencyKey reuse conflict: ${key}`);
+        }
+        if (existing.response) {
+          return existing.response;
+        }
+        const response = await options.execute();
+        await this.idempotency.put(key, requestHash, response);
+        await options.afterStore?.(response);
+        return response;
+      });
+    });
+  }
+  async peekIdempotentWrite(options) {
+    if (options.skip === true) {
+      return "miss";
+    }
+    const key = options.idempotencyKey?.trim();
+    if (!key) {
+      return "miss";
+    }
+    return this.withIdempotencyLock(key, async () => {
+      return this.idempotency.withKeyLock(key, async () => {
+        const requestHash = hashAccessIdempotencyPayload({
+          operation: options.operation,
+          request: options.requestFingerprint
+        });
+        const existing = await this.idempotency.get(key, requestHash);
+        if (existing.conflict) {
+          return "conflict";
+        }
+        return existing.response ? "replay" : "miss";
+      });
+    });
+  }
+  async withIdempotencyLock(key, fn) {
+    const previous = this.idempotencyLocks.get(key) ?? Promise.resolve();
+    let release;
+    const current = new Promise((resolve2) => {
+      release = resolve2;
+    });
+    const queued = previous.then(() => current, () => current);
+    this.idempotencyLocks.set(key, queued);
+    await previous.catch(() => {
+    });
+    try {
+      return await fn();
+    } finally {
+      release();
+      if (this.idempotencyLocks.get(key) === queued) {
+        this.idempotencyLocks.delete(key);
+      }
+    }
+  }
+  async withBudgetLock(principal, fn) {
+    const key = principal || "__anonymous__";
+    const previous = this.budgetLocks.get(key) ?? Promise.resolve();
+    let release;
+    const current = new Promise((resolve2) => {
+      release = resolve2;
+    });
+    const queued = previous.then(() => current, () => current);
+    this.budgetLocks.set(key, queued);
+    await previous.catch(() => {
+    });
+    try {
+      return await fn();
+    } finally {
+      release();
+      if (this.budgetLocks.get(key) === queued) {
+        this.budgetLocks.delete(key);
+      }
+    }
+  }
+  async health(namespace) {
+    const resolvedNamespace = this.resolveNamespace(namespace);
+    const storage = await this.orchestrator.getStorage(resolvedNamespace);
+    let projectionAvailable = false;
+    try {
+      await stat(getMemoryProjectionPath(storage.dir));
+      projectionAvailable = true;
+    } catch {
+      projectionAvailable = false;
+    }
+    return {
+      ok: true,
+      memoryDir: storage.dir,
+      namespacesEnabled: this.orchestrator.config.namespacesEnabled === true,
+      defaultNamespace: this.orchestrator.config.defaultNamespace,
+      searchBackend: this.orchestrator.config.searchBackend ?? "qmd",
+      qmdEnabled: this.orchestrator.config.qmdEnabled === true,
+      nativeKnowledgeEnabled: this.orchestrator.config.nativeKnowledge?.enabled === true,
+      projectionAvailable
+    };
+  }
+  async actionConfidence(request = {}) {
+    return evaluateActionConfidence(request);
+  }
+  async daySummary(request) {
+    if (!this.orchestrator.config.daySummaryEnabled) {
+      throw new EngramAccessInputError("day summary is disabled");
+    }
+    const memories = (request.memories ?? "").trim();
+    const namespace = this.resolveRecallNamespace(request.namespace, request.sessionKey);
+    if (memories.length === 0) {
+      return this.orchestrator.generateDaySummaryAuto(namespace);
+    }
+    return this.orchestrator.generateDaySummary(memories);
+  }
+  /**
+   * Build a daily context briefing. Gracefully degrades when the OpenAI key
+   * or Responses API is unavailable — never throws for LLM-related problems.
+   */
+  async briefing(request) {
+    const config = this.orchestrator.config;
+    if (!config.briefing.enabled) {
+      throw new EngramAccessInputError("briefing is disabled");
+    }
+    const namespace = this.resolveReadableNamespace(request.namespace, request.principal);
+    const storage = await this.orchestrator.getStorage(namespace);
+    const token = typeof request.since === "string" && request.since.trim().length > 0 ? request.since.trim() : config.briefing.defaultWindow;
+    const window = parseBriefingWindow(token);
+    if (!window) {
+      throw new EngramAccessInputError(`invalid briefing window: ${token}`);
+    }
+    const rawFocus = typeof request.focus === "string" ? request.focus.trim() : "";
+    let focus = null;
+    if (rawFocus.length > 0) {
+      focus = parseBriefingFocus(rawFocus);
+      if (!focus) {
+        throw new EngramAccessInputError(
+          `invalid briefing focus filter: ${request.focus}`
+        );
+      }
+    }
+    const SUPPORTED_FORMATS = ["markdown", "json"];
+    if (typeof request.format === "string" && !SUPPORTED_FORMATS.includes(request.format)) {
+      throw new EngramAccessInputError(
+        `unsupported briefing format: "${request.format}". Accepted: ${SUPPORTED_FORMATS.join(", ")}.`
+      );
+    }
+    const format = request.format === "json" ? "json" : request.format === "markdown" ? "markdown" : config.briefing.defaultFormat;
+    const maxFollowups = typeof request.maxFollowups === "number" && Number.isFinite(request.maxFollowups) ? Math.max(0, Math.min(10, Math.floor(request.maxFollowups))) : config.briefing.maxFollowups;
+    const calendarSource = config.briefing.calendarSource ? new FileCalendarSource(config.briefing.calendarSource) : void 0;
+    const result = await buildBriefing({
+      storage,
+      namespace,
+      window,
+      focus,
+      calendarSource,
+      maxFollowups,
+      allowLlm: config.briefing.llmFollowups,
+      openaiApiKey: config.openaiApiKey,
+      openaiBaseUrl: config.openaiBaseUrl,
+      model: config.model
+    });
+    return {
+      format,
+      window: result.window,
+      namespace,
+      markdown: result.markdown,
+      json: result.json,
+      followupsUnavailableReason: result.followupsUnavailableReason
+    };
+  }
+  /**
+   * Attach a coding context to a session (issue #569). Used by the Claude
+   * Code / Codex / generic-MCP connectors at session start so that recall +
+   * write paths can route to a project- / branch-scoped namespace.
+   *
+   * Validates the input shape and rejects malformed payloads rather than
+   * silently accepting them (CLAUDE.md #51). Pass `codingContext: null` to
+   * clear.
+   */
+  setCodingContext(request) {
+    const sessionKey = typeof request.sessionKey === "string" ? request.sessionKey.trim() : "";
+    if (!sessionKey) {
+      throw new EngramAccessInputError("sessionKey is required for setCodingContext");
+    }
+    if (request.codingContext === null) {
+      this.orchestrator.setCodingContextForSession(sessionKey, null);
+      return;
+    }
+    const ctx = request.codingContext;
+    if (!ctx || typeof ctx !== "object") {
+      throw new EngramAccessInputError("codingContext must be an object or null");
+    }
+    if (typeof ctx.projectId !== "string" || ctx.projectId.trim().length === 0) {
+      throw new EngramAccessInputError("codingContext.projectId must be a non-empty string");
+    }
+    if (typeof ctx.rootPath !== "string" || ctx.rootPath.trim().length === 0) {
+      throw new EngramAccessInputError("codingContext.rootPath must be a non-empty string");
+    }
+    if (ctx.branch !== null && typeof ctx.branch !== "string") {
+      throw new EngramAccessInputError("codingContext.branch must be a string or null");
+    }
+    if (ctx.defaultBranch !== null && typeof ctx.defaultBranch !== "string") {
+      throw new EngramAccessInputError("codingContext.defaultBranch must be a string or null");
+    }
+    this.orchestrator.setCodingContextForSession(sessionKey, {
+      projectId: ctx.projectId,
+      branch: ctx.branch,
+      rootPath: ctx.rootPath,
+      defaultBranch: ctx.defaultBranch
+    });
+  }
+  /**
+   * Auto-resolve and attach a coding context for a session when one is not
+   * already present. Resolves from `projectTag` (highest priority after
+   * explicit `codingContext`), then from `cwd` via git detection.
+   *
+   * This is a no-op when:
+   *   - `sessionKey` is missing
+   *   - the session already has a coding context attached
+   *   - codingMode.projectScope is disabled (CLAUDE.md #30)
+   *   - neither `cwd` nor `projectTag` is provided
+   *
+   * Never throws — git resolution failures are silently ignored because not
+   * being in a repo is a normal runtime state.
+   */
+  async maybeAttachCodingContext(sessionKey, options) {
+    if (!sessionKey) return;
+    if (!this.orchestrator.config.codingMode?.projectScope) return;
+    if (this.orchestrator.getCodingContextForSession(sessionKey)) return;
+    if (typeof options.projectTag === "string" && options.projectTag.trim().length > 0) {
+      const tag = options.projectTag.trim();
+      this.orchestrator.setCodingContextForSession(sessionKey, {
+        projectId: `tag:${tag}`,
+        branch: null,
+        rootPath: `tag:${tag}`,
+        defaultBranch: null
+      });
+      return;
+    }
+    if (typeof options.cwd === "string" && options.cwd.trim().length > 0) {
+      try {
+        const gitCtx = await resolveGitContext(options.cwd);
+        if (gitCtx) {
+          this.setCodingContext({
+            sessionKey,
+            codingContext: {
+              projectId: gitCtx.projectId,
+              branch: gitCtx.branch,
+              rootPath: gitCtx.rootPath,
+              defaultBranch: gitCtx.defaultBranch
+            }
+          });
+        }
+      } catch {
+      }
+    }
+  }
+  async recall(request) {
+    const query = request.query.trim();
+    if (query.length === 0) {
+      throw new EngramAccessInputError("query is required");
+    }
+    const normalizedRequest = { ...request, query };
+    const authenticatedPrincipal = request.authenticatedPrincipal?.trim();
+    const principal = this.resolveRequestPrincipal(request.sessionKey, authenticatedPrincipal);
+    return this.withBudgetLock(principal, async () => {
+      let budgetRecordPrincipal = null;
+      const response = await this.handleIdempotentRead({
+        operation: "recall",
+        idempotencyKey: request.idempotencyKey,
+        requestFingerprint: normalizedRequest,
+        execute: async () => {
+          const result = await this.executeRecall(normalizedRequest);
+          budgetRecordPrincipal = result.budgetRecordPrincipal;
+          return result.response;
+        },
+        afterStore: () => {
+          if (!budgetRecordPrincipal) return;
+          const recordedBudgetDecision = this.budget.record(budgetRecordPrincipal);
+          if (!recordedBudgetDecision.allowed) {
+            throw new EngramAccessInputError(
+              `recall denied: cross-namespace budget exceeded (${recordedBudgetDecision.count}/${recordedBudgetDecision.limit.hardLimit} in ${recordedBudgetDecision.limit.windowMs}ms window)`
+            );
+          }
+        }
+      });
+      return response;
+    });
+  }
+  async executeRecall(request) {
+    const query = request.query;
+    const callerProvidedDisclosure = request.disclosure !== void 0 && request.disclosure !== null;
+    const requestedDisclosure = (() => {
+      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;
+    })();
+    if (request.codingContext !== void 0 && request.sessionKey) {
+      this.setCodingContext({
+        sessionKey: request.sessionKey,
+        codingContext: request.codingContext
+      });
+    }
+    if (request.codingContext === void 0 && 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
+    );
+    const namespace = namespaceOverride ?? this.orchestrator.config.defaultNamespace;
+    const mode = this.normalizeRecallMode(request.mode);
+    const principal = this.resolveRequestPrincipal(request.sessionKey, authenticatedPrincipal);
+    const principalNamespace = defaultNamespaceForPrincipal(principal, this.orchestrator.config);
+    const modeSkipsBudget = mode === "no_recall";
+    const effectiveNamespaces = namespaceOverride ? [namespaceOverride] : recallNamespacesForPrincipal(principal, this.orchestrator.config);
+    let budgetDecision;
+    let recordBudgetAfterSuccess = false;
+    if (modeSkipsBudget) {
+      budgetDecision = {
+        allowed: true,
+        reason: "allowed-same-namespace",
+        count: 0,
+        limit: {
+          softLimit: this.orchestrator.config.recallCrossNamespaceBudgetSoftLimit ?? 10,
+          hardLimit: this.orchestrator.config.recallCrossNamespaceBudgetHardLimit ?? 30,
+          windowMs: this.orchestrator.config.recallCrossNamespaceBudgetWindowMs ?? 6e4
+        }
+      };
+    } else {
+      let anyCrossNamespace = false;
+      let denied = null;
+      let crossNamespaceDecision = null;
+      for (const ns of effectiveNamespaces) {
+        const peek = this.budget.peek({
+          principal,
+          principalNamespace,
+          queryNamespace: ns
+        });
+        if (peek.reason !== "allowed-same-namespace") {
+          anyCrossNamespace = true;
+          crossNamespaceDecision ??= peek;
+        }
+        if (!peek.allowed) {
+          denied = peek;
+          break;
+        }
+      }
+      if (denied) {
+        budgetDecision = denied;
+      } else if (anyCrossNamespace) {
+        budgetDecision = crossNamespaceDecision ?? {
+          allowed: true,
+          reason: "allowed-under-soft",
+          count: 0,
+          limit: {
+            softLimit: this.orchestrator.config.recallCrossNamespaceBudgetSoftLimit ?? 10,
+            hardLimit: this.orchestrator.config.recallCrossNamespaceBudgetHardLimit ?? 30,
+            windowMs: this.orchestrator.config.recallCrossNamespaceBudgetWindowMs ?? 6e4
+          }
+        };
+        recordBudgetAfterSuccess = true;
+      } else {
+        budgetDecision = {
+          allowed: true,
+          reason: "allowed-same-namespace",
+          count: 0,
+          limit: {
+            softLimit: this.orchestrator.config.recallCrossNamespaceBudgetSoftLimit ?? 10,
+            hardLimit: this.orchestrator.config.recallCrossNamespaceBudgetHardLimit ?? 30,
+            windowMs: this.orchestrator.config.recallCrossNamespaceBudgetWindowMs ?? 6e4
+          }
+        };
+      }
+      if (!budgetDecision.allowed) {
+        throw new EngramAccessInputError(
+          `recall denied: cross-namespace budget exceeded (${budgetDecision.count}/${budgetDecision.limit.hardLimit} in ${budgetDecision.limit.windowMs}ms window)`
+        );
+      }
+      this.budget.gc();
+    }
+    const topK = Number.isFinite(request.topK) ? Math.max(0, Math.floor(request.topK ?? 0)) : void 0;
+    let asOf;
+    if (request.asOf !== void 0 && 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 = {
+      namespace: namespaceOverride,
+      topK,
+      mode,
+      ...authenticatedPrincipal ? { principalOverride: authenticatedPrincipal } : {},
+      ...asOf !== void 0 ? { 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;
+    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);
+    const topKConfidence = snapshot && topKDenominator > 0 ? Math.min(1, resultsReturned / topKDenominator) : void 0;
+    const escalationDecision = decideDisclosureEscalation({
+      mode: this.orchestrator.config.recallDisclosureEscalation,
+      threshold: this.orchestrator.config.recallDisclosureEscalationThreshold,
+      originalDisclosure: requestedDisclosure,
+      callerProvidedDisclosure,
+      topKConfidence
+    });
+    const disclosure = escalationDecision.effective;
+    let results = await this.serializeRecallResults(snapshot, disclosure, {
+      query,
+      sessionKey: request.sessionKey
+    });
+    const filterTags = normalizeTags(request.tags);
+    let tagMatchMode;
+    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;
+      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.content === "string" ? r.content ?? "" : "";
+          const preview = typeof r.preview === "string" ? r.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
+    );
+    let auditAnomalies;
+    if (this.auditAdapter) {
+      try {
+        const resolvedAgentId = principal;
+        const auditEntry = {
+          ts: (/* @__PURE__ */ 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",
+          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 {
+      }
+    }
+    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 : void 0,
+        latencyMs: snapshot?.latencyMs ?? Date.now() - startedAt,
+        debug
+      },
+      budgetRecordPrincipal: recordBudgetAfterSuccess ? principal : null
+    };
+  }
+  async recallExplain(request = {}) {
+    const requestedNamespace = request.namespace?.trim() ? this.resolveNamespace(request.namespace) : void 0;
+    if (requestedNamespace) {
+      const principal = resolvePrincipal(request.sessionKey, this.orchestrator.config);
+      if (!canReadNamespace(principal, requestedNamespace, this.orchestrator.config)) {
+        return { found: false };
+      }
+    }
+    const snapshot = request.sessionKey ? (() => {
+      const candidate = this.orchestrator.lastRecall.get(request.sessionKey);
+      if (!candidate) return null;
+      if (!requestedNamespace) return candidate;
+      return candidate.namespace === requestedNamespace ? candidate : null;
+    })() : (() => {
+      const candidate = this.orchestrator.lastRecall.getMostRecent();
+      if (!candidate) return null;
+      if (!requestedNamespace) return candidate;
+      return candidate.namespace === requestedNamespace ? candidate : null;
+    })();
+    const namespace = requestedNamespace ?? snapshot?.namespace ?? this.orchestrator.config.defaultNamespace;
+    const [intent, graph] = await Promise.all([
+      this.orchestrator.getLastIntentSnapshot(namespace),
+      this.orchestrator.getLastGraphRecallSnapshot(namespace)
+    ]);
+    if (!snapshot && !intent && !graph) return { found: false };
+    return { found: true, snapshot: snapshot ?? void 0, intent, graph };
+  }
+  async recallTierExplain(sessionKey, namespace, authenticatedPrincipal) {
+    const namespacesEnabled = this.orchestrator.config.namespacesEnabled;
+    const requestedNamespace = namespace?.trim() ? this.resolveNamespace(namespace) : void 0;
+    const principal = authenticatedPrincipal?.trim() || resolvePrincipal(sessionKey, this.orchestrator.config);
+    if (requestedNamespace) {
+      if (!canReadNamespace(principal, requestedNamespace, this.orchestrator.config)) {
+        return toRecallExplainJson(null);
+      }
+    } else if (namespacesEnabled && !authenticatedPrincipal?.trim() && !sessionKey?.trim()) {
+      return toRecallExplainJson(null);
+    }
+    const candidate = sessionKey ? this.orchestrator.lastRecall.get(sessionKey) : this.orchestrator.lastRecall.getMostRecent();
+    const snapshot = (() => {
+      if (!candidate) return null;
+      if (requestedNamespace) {
+        return candidate.namespace === requestedNamespace ? candidate : null;
+      }
+      if (!namespacesEnabled) return candidate;
+      const snapshotNs = candidate.namespace ?? this.orchestrator.config.defaultNamespace;
+      return canReadNamespace(principal, snapshotNs, this.orchestrator.config) ? candidate : null;
+    })();
+    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) {
+    const query = typeof request.query === "string" ? request.query : "";
+    if (query.trim().length === 0) {
+      throw new Error("recallXray: query is required and must be non-empty");
+    }
+    if (request.disclosure !== void 0 && !isRecallDisclosure(request.disclosure)) {
+      throw new EngramAccessInputError(
+        `recallXray: disclosure must be one of: chunk, section, raw (got: ${String(request.disclosure)})`
+      );
+    }
+    const namespacesEnabled = this.orchestrator.config.namespacesEnabled;
+    const requestedNamespace = request.namespace?.trim() ? this.resolveNamespace(request.namespace) : void 0;
+    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()) {
+      return { snapshotFound: false };
+    }
+    let budgetOverride;
+    if (request.budget !== void 0 && 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;
+    const previousQueue = this.xrayQueue;
+    let release = () => {
+    };
+    this.xrayQueue = new Promise((resolve2) => {
+      release = resolve2;
+    });
+    await previousQueue;
+    const recallStartedAt = Date.now();
+    const recallSessionKey = request.sessionKey?.trim() || void 0;
+    let xrayResponse = { snapshotFound: false };
+    try {
+      this.orchestrator.clearLastXraySnapshot();
+      await this.orchestrator.recall(query, recallSessionKey, {
+        xrayCapture: true,
+        ...requestedNamespace ? { namespace: requestedNamespace } : {},
+        ...budgetOverride !== void 0 ? { budgetCharsOverride: budgetOverride } : {},
+        ...mode !== void 0 ? { 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 !== void 0 ? { currentContextScopes: request.currentContextScopes } : {}
+      });
+      const rawSnapshot = this.orchestrator.getLastXraySnapshot();
+      const namespaceMismatch = requestedNamespace !== void 0 && rawSnapshot?.namespace !== requestedNamespace;
+      if (!rawSnapshot) {
+        xrayResponse = { snapshotFound: false };
+      } else if (namespaceMismatch) {
+        xrayResponse = { snapshotFound: false };
+      } else {
+        let snapshot = rawSnapshot;
+        const xrayFilterTags = normalizeTags(request.tags);
+        let xrayTagMatch;
+        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;
+                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 };
+        }
+        if (request.disclosure !== void 0) {
+          const disclosure2 = request.disclosure;
+          const namespace = snapshot.namespace ? this.resolveNamespace(snapshot.namespace) : this.orchestrator.config.defaultNamespace;
+          const trimmedSessionKey = request.sessionKey?.trim() || void 0;
+          const rawExcerpts = disclosure2 === "raw" ? await this.fetchRawExcerpts(disclosure2, {
+            query,
+            ...trimmedSessionKey ? { sessionKey: trimmedSessionKey } : {},
+            namespace
+          }) : null;
+          const rawExcerptText = rawExcerpts && rawExcerpts.length > 0 ? rawExcerpts.map((e) => e.content).join("\n") : "";
+          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) {
+              return { ...result, disclosure: disclosure2 };
+            }
+            const shaped = shapeMemorySummary(
+              memory,
+              baseDir,
+              disclosure2,
+              disclosure2 === "raw" && index === firstReadableIndex && rawExcerpts && rawExcerpts.length > 0 ? rawExcerpts : void 0
+            );
+            return {
+              ...result,
+              disclosure: disclosure2,
+              estimatedTokens: estimateRecallTokens(JSON.stringify(shaped))
+            };
+          });
+          if (disclosure2 === "raw" && firstReadableIndex === -1 && rawExcerptText.length > 0 && decorated.length > 0) {
+            decorated[0] = {
+              ...decorated[0],
+              disclosure: disclosure2,
+              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) {
+      return {
+        ...xrayResponse,
+        recall: await this.buildRecallResponseFromXraySnapshot({
+          query,
+          sessionKey: recallSessionKey,
+          snapshot: xrayResponse.snapshot,
+          disclosure,
+          startedAt: recallStartedAt,
+          requestedMode: request.mode,
+          normalizedMode: mode
+        })
+      };
+    }
+    return xrayResponse;
+  }
+  // Sequence lock for `recallXray` — see comment inside the method.
+  // Lives on the instance so every x-ray call on the same service
+  // shares it, and so separate services in the same process (e.g.
+  // per-tenant) do not block each other.
+  xrayQueue = Promise.resolve();
+  async memoryStore(request) {
+    const namespace = this.resolveWritableNamespace(
+      request.namespace,
+      request.sessionKey,
+      request.authenticatedPrincipal
+    );
+    const schemaVersion = request.schemaVersion ?? ENGRAM_ACCESS_WRITE_SCHEMA_VERSION;
+    if (schemaVersion !== ENGRAM_ACCESS_WRITE_SCHEMA_VERSION) {
+      throw new EngramAccessInputError(`unsupported schemaVersion: ${schemaVersion}`);
+    }
+    const execute = async () => {
+      const candidate = this.validateWriteCandidate(request, namespace);
+      if (request.dryRun === true) {
+        return {
+          schemaVersion: ENGRAM_ACCESS_WRITE_SCHEMA_VERSION,
+          operation: "memory_store",
+          namespace,
+          dryRun: true,
+          accepted: true,
+          queued: false,
+          status: "validated",
+          idempotencyKey: request.idempotencyKey?.trim() || void 0
+        };
+      }
+      const result = await persistExplicitCapture(this.orchestrator, candidate, "memory_store");
+      const response = {
+        schemaVersion: ENGRAM_ACCESS_WRITE_SCHEMA_VERSION,
+        operation: "memory_store",
+        namespace,
+        dryRun: false,
+        accepted: true,
+        queued: false,
+        status: result.duplicateOf ? "duplicate" : "stored",
+        memoryId: result.id,
+        duplicateOf: result.duplicateOf,
+        idempotencyKey: request.idempotencyKey?.trim() || void 0
+      };
+      log.info(
+        `access-write op=memory_store namespace=${namespace} dryRun=false status=${response.status} memoryId=${response.memoryId ?? "-"} idempotency=${response.idempotencyKey ? "yes" : "no"}`
+      );
+      return response;
+    };
+    return this.handleIdempotentWrite({
+      operation: "memory_store",
+      idempotencyKey: request.idempotencyKey,
+      requestFingerprint: {
+        schemaVersion,
+        content: request.content,
+        category: request.category,
+        confidence: request.confidence,
+        namespace,
+        tags: request.tags,
+        entityRef: request.entityRef,
+        ttl: request.ttl,
+        sourceReason: request.sourceReason
+      },
+      skip: request.dryRun === true,
+      execute
+    });
+  }
+  async peekMemoryStoreIdempotency(request) {
+    const namespace = this.resolveWritableNamespace(
+      request.namespace,
+      request.sessionKey,
+      request.authenticatedPrincipal
+    );
+    const schemaVersion = request.schemaVersion ?? ENGRAM_ACCESS_WRITE_SCHEMA_VERSION;
+    if (schemaVersion !== ENGRAM_ACCESS_WRITE_SCHEMA_VERSION) {
+      throw new EngramAccessInputError(`unsupported schemaVersion: ${schemaVersion}`);
+    }
+    return this.peekIdempotentWrite({
+      operation: "memory_store",
+      idempotencyKey: request.idempotencyKey,
+      requestFingerprint: {
+        schemaVersion,
+        content: request.content,
+        category: request.category,
+        confidence: request.confidence,
+        namespace,
+        tags: request.tags,
+        entityRef: request.entityRef,
+        ttl: request.ttl,
+        sourceReason: request.sourceReason
+      },
+      skip: request.dryRun === true
+    });
+  }
+  async suggestionSubmit(request) {
+    const namespace = this.resolveWritableNamespace(
+      request.namespace,
+      request.sessionKey,
+      request.authenticatedPrincipal
+    );
+    const schemaVersion = request.schemaVersion ?? ENGRAM_ACCESS_WRITE_SCHEMA_VERSION;
+    if (schemaVersion !== ENGRAM_ACCESS_WRITE_SCHEMA_VERSION) {
+      throw new EngramAccessInputError(`unsupported schemaVersion: ${schemaVersion}`);
+    }
+    const execute = async () => {
+      const candidate = this.validateWriteCandidate(request, namespace);
+      if (request.dryRun === true) {
+        return {
+          schemaVersion: ENGRAM_ACCESS_WRITE_SCHEMA_VERSION,
+          operation: "suggestion_submit",
+          namespace,
+          dryRun: true,
+          accepted: true,
+          queued: true,
+          status: "validated",
+          idempotencyKey: request.idempotencyKey?.trim() || void 0
+        };
+      }
+      const result = await queueExplicitCaptureForReview(
+        this.orchestrator,
+        candidate,
+        "suggestion_submit",
+        new Error(request.sourceReason?.trim() || "submitted via engram suggestion_submit")
+      );
+      const response = {
+        schemaVersion: ENGRAM_ACCESS_WRITE_SCHEMA_VERSION,
+        operation: "suggestion_submit",
+        namespace,
+        dryRun: false,
+        accepted: true,
+        queued: true,
+        status: "queued_for_review",
+        memoryId: result.id,
+        duplicateOf: result.duplicateOf,
+        idempotencyKey: request.idempotencyKey?.trim() || void 0
+      };
+      log.info(
+        `access-write op=suggestion_submit namespace=${namespace} dryRun=false status=${response.status} memoryId=${response.memoryId ?? "-"} idempotency=${response.idempotencyKey ? "yes" : "no"}`
+      );
+      return response;
+    };
+    return this.handleIdempotentWrite({
+      operation: "suggestion_submit",
+      idempotencyKey: request.idempotencyKey,
+      requestFingerprint: {
+        schemaVersion,
+        content: request.content,
+        category: request.category,
+        confidence: request.confidence,
+        namespace,
+        tags: request.tags,
+        entityRef: request.entityRef,
+        ttl: request.ttl,
+        sourceReason: request.sourceReason
+      },
+      skip: request.dryRun === true,
+      execute
+    });
+  }
+  async peekSuggestionSubmitIdempotency(request) {
+    const namespace = this.resolveWritableNamespace(
+      request.namespace,
+      request.sessionKey,
+      request.authenticatedPrincipal
+    );
+    const schemaVersion = request.schemaVersion ?? ENGRAM_ACCESS_WRITE_SCHEMA_VERSION;
+    if (schemaVersion !== ENGRAM_ACCESS_WRITE_SCHEMA_VERSION) {
+      throw new EngramAccessInputError(`unsupported schemaVersion: ${schemaVersion}`);
+    }
+    return this.peekIdempotentWrite({
+      operation: "suggestion_submit",
+      idempotencyKey: request.idempotencyKey,
+      requestFingerprint: {
+        schemaVersion,
+        content: request.content,
+        category: request.category,
+        confidence: request.confidence,
+        namespace,
+        tags: request.tags,
+        entityRef: request.entityRef,
+        ttl: request.ttl,
+        sourceReason: request.sourceReason
+      },
+      skip: request.dryRun === true
+    });
+  }
+  validateWriteCandidate(request, namespace) {
+    try {
+      return validateExplicitCaptureInput(
+        {
+          ...request,
+          namespace
+        },
+        "legacy_tool"
+      );
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new EngramAccessInputError(message);
+    }
+  }
+  async memoryGet(memoryId, namespace, principal) {
+    const resolvedNamespace = this.resolveReadableNamespace(namespace, principal);
+    const storage = await this.orchestrator.getStorage(resolvedNamespace);
+    const memory = await storage.getMemoryById(memoryId);
+    if (!memory) {
+      return { found: false, namespace: resolvedNamespace };
+    }
+    return {
+      found: true,
+      namespace: resolvedNamespace,
+      memory: this.serializeMemory(memory)
+    };
+  }
+  async memoryBrowse(request = {}) {
+    const resolvedNamespace = this.resolveReadableNamespace(
+      request.namespace,
+      request.authenticatedPrincipal
+    );
+    const storage = await this.orchestrator.getStorage(resolvedNamespace);
+    const { limit, offset } = normalizePagination(request.limit, request.offset);
+    const sort = normalizeBrowseSort(request.sort);
+    const query = request.query?.trim().toLowerCase() ?? "";
+    const statusFilter = request.status?.trim().toLowerCase();
+    const categoryFilter = request.category?.trim().toLowerCase();
+    const projected = await storage.browseProjectedMemories({
+      query,
+      status: statusFilter,
+      category: categoryFilter,
+      sort,
+      limit,
+      offset
+    });
+    if (projected) {
+      return {
+        namespace: resolvedNamespace,
+        sort,
+        total: projected.total,
+        count: projected.memories.length,
+        limit,
+        offset,
+        memories: projected.memories.map((row) => ({ ...row }))
+      };
+    }
+    let memories = [...await storage.readAllMemories(), ...await storage.readArchivedMemories()];
+    memories = memories.filter((memory) => {
+      const status = inferMemoryStatus(memory.frontmatter, toMemoryPathRel(storage.dir, memory.path)).toLowerCase();
+      if (statusFilter && status !== statusFilter) return false;
+      if (categoryFilter && memory.frontmatter.category.toLowerCase() !== categoryFilter) return false;
+      if (!query) return true;
+      const haystack = [
+        memory.frontmatter.id,
+        memory.path,
+        memory.content,
+        memory.frontmatter.entityRef ?? "",
+        ...memory.frontmatter.tags
+      ].join("\n").toLowerCase();
+      return haystack.includes(query);
+    });
+    memories.sort((left, right) => compareBrowseMemory(sort, left, right));
+    const page = memories.slice(offset, offset + limit).map((memory) => this.serializeMemorySummary(memory, storage.dir));
+    return {
+      namespace: resolvedNamespace,
+      sort,
+      total: memories.length,
+      count: page.length,
+      limit,
+      offset,
+      memories: page
+    };
+  }
+  async memoryTimeline(memoryId, namespace, limit = 200, principal) {
+    const resolvedNamespace = this.resolveReadableNamespace(namespace, principal);
+    const storage = await this.orchestrator.getStorage(resolvedNamespace);
+    const timeline = await storage.getMemoryTimeline(memoryId, limit);
+    return {
+      found: timeline.length > 0,
+      namespace: resolvedNamespace,
+      count: timeline.length,
+      timeline
+    };
+  }
+  async entityList(options = {}) {
+    const storage = await this.orchestrator.getStorage(options.namespace);
+    const resolvedNamespace = options.namespace?.trim() || this.orchestrator.config.defaultNamespace;
+    const { limit, offset } = normalizePagination(options.limit, options.offset);
+    const query = options.query?.trim().toLowerCase() ?? "";
+    const names = await storage.listEntityNames();
+    const entities = [];
+    for (const name of names) {
+      const raw = await storage.readEntity(name);
+      if (!raw) continue;
+      const entity = parseEntityFile(raw, this.orchestrator.config.entitySchemas);
+      if (query) {
+        const haystack = [
+          entity.name,
+          entity.type,
+          entity.synthesis || entity.summary || "",
+          ...entity.aliases,
+          ...entity.facts,
+          ...(entity.structuredSections ?? []).flatMap((section) => [section.title, ...section.facts])
+        ].join("\n").toLowerCase();
+        if (!haystack.includes(query)) continue;
+      }
+      entities.push({
+        name: entity.name,
+        type: entity.type,
+        updated: entity.updated,
+        summary: entity.synthesis || entity.summary,
+        aliases: entity.aliases
+      });
+    }
+    entities.sort((left, right) => left.name.localeCompare(right.name));
+    const page = entities.slice(offset, offset + limit);
+    return {
+      namespace: resolvedNamespace,
+      total: entities.length,
+      count: page.length,
+      limit,
+      offset,
+      entities: page
+    };
+  }
+  async entityGet(name, namespace) {
+    const storage = await this.orchestrator.getStorage(namespace);
+    const resolvedNamespace = namespace?.trim() || this.orchestrator.config.defaultNamespace;
+    const raw = await storage.readEntity(name);
+    if (!raw) return { found: false, namespace: resolvedNamespace };
+    return {
+      found: true,
+      namespace: resolvedNamespace,
+      entity: parseEntityFile(raw, this.orchestrator.config.entitySchemas)
+    };
+  }
+  async reviewQueue(runId, namespace, principal) {
+    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
+      }));
+      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;
+      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,
+        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
+        })),
+        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
+    };
+  }
+  async maintenance(namespace, principal) {
+    const resolvedNamespace = this.resolveReadableNamespace(namespace, principal);
+    return {
+      namespace: resolvedNamespace,
+      health: await this.health(resolvedNamespace),
+      latestGovernanceRun: await this.reviewQueue(void 0, resolvedNamespace, principal)
+    };
+  }
+  async quality(namespace, principal) {
+    const resolvedNamespace = this.resolveReadableNamespace(namespace, principal);
+    const storage = await this.orchestrator.getStorage(resolvedNamespace);
+    const governance = await this.reviewQueue(void 0, resolvedNamespace, principal);
+    const nowMs = Date.now();
+    const statusCounts = {};
+    const categoryCounts = {};
+    const confidenceTierCounts = {};
+    const ageBucketCounts = {};
+    let staleActive = 0;
+    let lowConfidenceActive = 0;
+    const memories = [...await storage.readAllMemories(), ...await storage.readArchivedMemories()];
+    for (const memory of memories) {
+      const status = inferMemoryStatus(memory.frontmatter, toMemoryPathRel(storage.dir, memory.path)).toLowerCase();
+      const confidenceTier = memory.frontmatter.confidenceTier ?? "unknown";
+      const ageBucket = bucketMemoryAge(memory.frontmatter.updated ?? memory.frontmatter.created, nowMs);
+      incrementCount(statusCounts, status);
+      incrementCount(categoryCounts, memory.frontmatter.category);
+      incrementCount(confidenceTierCounts, confidenceTier);
+      incrementCount(ageBucketCounts, ageBucket);
+      if (status === "active") {
+        if (ageBucket === "91_plus_days") staleActive += 1;
+        if ((memory.frontmatter.confidence ?? 0) < 0.6) lowConfidenceActive += 1;
+      }
+    }
+    return {
+      namespace: resolvedNamespace,
+      totalMemories: memories.length,
+      statusCounts,
+      categoryCounts,
+      confidenceTierCounts,
+      ageBucketCounts,
+      archivePressure: {
+        pendingReview: statusCounts.pending_review ?? 0,
+        quarantined: statusCounts.quarantined ?? 0,
+        archived: statusCounts.archived ?? 0,
+        staleActive,
+        lowConfidenceActive
+      },
+      latestGovernanceRun: {
+        found: governance.found,
+        runId: governance.runId,
+        qualityScore: governance.qualityScore ?? governance.metrics?.qualityScore,
+        reviewQueueCount: governance.reviewQueue?.length ?? 0
+      }
+    };
+  }
+  async governanceRun(request, principal) {
+    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.resolveWritableNamespace(
+      request.namespace,
+      void 0,
+      request.authenticatedPrincipal ?? 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)) : void 0;
+    const result = await runMemoryGovernance({
+      memoryDir: storage.dir,
+      mode,
+      recentDays: typeof request.recentDays === "number" && Number.isFinite(request.recentDays) ? Math.max(1, Math.floor(request.recentDays)) : void 0,
+      maxMemories: typeof request.maxMemories === "number" && Number.isFinite(request.maxMemories) ? Math.max(1, Math.floor(request.maxMemories)) : void 0,
+      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(request, principal) {
+    const resolvedNamespace = this.resolveWritableNamespace(
+      request.namespace,
+      void 0,
+      request.authenticatedPrincipal ?? principal
+    );
+    const storage = await this.orchestrator.getStorage(resolvedNamespace);
+    const result = await runProcedureMining({
+      memoryDir: storage.dir,
+      storage,
+      config: this.orchestrator.config
+    });
+    return {
+      namespace: resolvedNamespace,
+      clustersProcessed: result.clustersProcessed,
+      proceduresWritten: result.proceduresWritten,
+      skippedReason: result.skippedReason
+    };
+  }
+  async liveConnectorsRun(request = {}, principal) {
+    this.resolveWritableNamespace(
+      void 0,
+      void 0,
+      request.authenticatedPrincipal ?? principal
+    );
+    return this.orchestrator.runLiveConnectors({
+      force: request.force === true
+    });
+  }
+  /**
+   * Run the pattern-reinforcement maintenance job (issue #687 PR 2/4).
+   *
+   * Cluster duplicate non-procedural memories and reinforce the
+   * canonical (most-recent) member.  Gated on
+   * `patternReinforcementEnabled` — when disabled, returns
+   * `{ ran: false, skippedReason: "disabled" }` so the cron payload
+   * surface in CI logs cleanly.
+   *
+   * Resolves the namespace via the same writable path used by
+   * `procedureMiningRun` so cross-tenant writes are impossible
+   * (CLAUDE.md rule 42).
+   *
+   * Delegates the run to `orchestrator.runPatternReinforcement` so
+   * the cadence floor (`patternReinforcementCadenceMs`) is enforced
+   * uniformly across cron + MCP paths (PR #730 review feedback,
+   * Codex P2).  Accepts `force: true` for ad-hoc operator runs that
+   * must bypass the cadence floor — mirrors the pattern used by
+   * other maintenance MCP tools.
+   */
+  async patternReinforcementRun(request = {}, principal) {
+    const resolvedNamespace = this.resolveWritableNamespace(
+      request.namespace,
+      void 0,
+      request.authenticatedPrincipal ?? principal
+    );
+    const outcome = await this.orchestrator.runPatternReinforcement({
+      namespace: resolvedNamespace,
+      force: request.force === true
+    });
+    if (!outcome.ran) {
+      return {
+        namespace: resolvedNamespace,
+        ran: false,
+        skippedReason: outcome.skippedReason,
+        clustersFound: 0,
+        canonicalsUpdated: 0,
+        duplicatesSuperseded: 0
+      };
+    }
+    const result = outcome.result;
+    return {
+      namespace: resolvedNamespace,
+      ran: true,
+      clustersFound: result.clustersFound,
+      canonicalsUpdated: result.canonicalsUpdated,
+      duplicatesSuperseded: result.duplicatesSuperseded,
+      result
+    };
+  }
+  /**
+   * Procedural memory stats (issue #567 PR 5/5). Read-only — resolves the
+   * namespace via the same path used by `recallExplain` / `trustZoneStatus`
+   * so cross-tenant reads are impossible (CLAUDE.md rule 42).
+   */
+  async procedureStats(request = {}, principal) {
+    const resolvedNamespace = this.resolveReadableNamespace(
+      request.namespace,
+      principal
+    );
+    const storage = await this.orchestrator.getStorage(resolvedNamespace);
+    const report = await computeProcedureStats({
+      storage,
+      config: this.orchestrator.config
+    });
+    return { namespace: resolvedNamespace, ...report };
+  }
+  async memorySummarizeHourly() {
+    await this.orchestrator.summarizer.runHourly();
+    return {
+      ok: true,
+      message: "Hourly summarization completed. Check the summaries directory for results."
+    };
+  }
+  async conversationIndexUpdate(request = {}) {
+    if (!this.orchestrator.config.conversationIndexEnabled) {
+      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;
+    if (request.sessionKey !== void 0) {
+      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 = [];
+    let embeddedRuns = 0;
+    for (const sessionKey2 of sessionKeys) {
+      const result = await this.orchestrator.updateConversationIndex(
+        sessionKey2,
+        hours,
+        { embed: request.embed }
+      );
+      chunks += result.chunks;
+      if (result.skipped) {
+        skipped += 1;
+        skippedSessionKeys.push(sessionKey2);
+      }
+      if (result.embedded) {
+        embeddedRuns += 1;
+      }
+    }
+    return {
+      enabled: true,
+      sessions: sessionKeys.length,
+      chunks,
+      skipped,
+      skippedSessionKeys,
+      embeddedRuns
+    };
+  }
+  async profilingReport(request = {}) {
+    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 = [];
+    lines.push("Engram Profiling Report");
+    lines.push("=".repeat(60));
+    lines.push("");
+    const allBuckets = [
+      ["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")
+    };
+  }
+  async trustZoneStatus(namespace, principal) {
+    const resolvedNamespace = this.resolveReadableNamespace(namespace, principal);
+    const storage = await this.orchestrator.getStorage(resolvedNamespace);
+    return {
+      namespace: resolvedNamespace,
+      status: await getTrustZoneStoreStatus({
+        memoryDir: storage.dir,
+        trustZoneStoreDir: this.orchestrator.config.trustZoneStoreDir,
+        enabled: this.orchestrator.config.trustZonesEnabled === true,
+        promotionEnabled: this.orchestrator.config.quarantinePromotionEnabled === true,
+        poisoningDefenseEnabled: this.orchestrator.config.memoryPoisoningDefenseEnabled === true
+      })
+    };
+  }
+  async trustZoneBrowse(request, principal) {
+    const resolvedNamespace = this.resolveReadableNamespace(request.namespace, principal);
+    const storage = await this.orchestrator.getStorage(resolvedNamespace);
+    const result = await listTrustZoneRecords({
+      memoryDir: storage.dir,
+      trustZoneStoreDir: this.orchestrator.config.trustZoneStoreDir,
+      query: request.query,
+      zone: request.zone,
+      kind: request.kind,
+      sourceClass: request.sourceClass,
+      limit: request.limit,
+      offset: request.offset
+    });
+    return {
+      namespace: resolvedNamespace,
+      total: result.total,
+      count: result.count,
+      limit: result.limit,
+      offset: result.offset,
+      records: result.records.map((entry) => summarizeTrustZoneRecord(
+        entry.record,
+        entry.filePath,
+        result.allRecords,
+        this.orchestrator.config.memoryPoisoningDefenseEnabled === true,
+        this.orchestrator.config.trustZonesEnabled === true,
+        this.orchestrator.config.quarantinePromotionEnabled === true
+      ))
+    };
+  }
+  async trustZonePromote(request) {
+    if (!isTrustZoneName(request.targetZone)) {
+      throw new EngramAccessInputError(`unsupported trust-zone target: ${String(request.targetZone)}`);
+    }
+    const resolvedNamespace = this.resolveWritableNamespace(
+      request.namespace,
+      void 0,
+      request.authenticatedPrincipal
+    );
+    const storage = await this.orchestrator.getStorage(resolvedNamespace);
+    let result;
+    try {
+      result = await promoteTrustZoneRecord({
+        memoryDir: storage.dir,
+        trustZoneStoreDir: this.orchestrator.config.trustZoneStoreDir,
+        enabled: this.orchestrator.config.trustZonesEnabled === true,
+        promotionEnabled: this.orchestrator.config.quarantinePromotionEnabled === true,
+        poisoningDefenseEnabled: this.orchestrator.config.memoryPoisoningDefenseEnabled === true,
+        sourceRecordId: request.recordId,
+        targetZone: request.targetZone,
+        recordedAt: request.recordedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+        promotionReason: request.promotionReason,
+        summary: request.summary,
+        dryRun: request.dryRun === true
+      });
+    } catch (error) {
+      throw normalizeTrustZoneInputError(error) ?? error;
+    }
+    return {
+      namespace: resolvedNamespace,
+      ...result,
+      dryRun: request.dryRun === true
+    };
+  }
+  async trustZoneDemoSeed(request) {
+    const resolvedNamespace = this.resolveWritableNamespace(
+      request.namespace,
+      void 0,
+      request.authenticatedPrincipal
+    );
+    const storage = await this.orchestrator.getStorage(resolvedNamespace);
+    let result;
+    try {
+      result = await seedTrustZoneDemoDataset({
+        memoryDir: storage.dir,
+        trustZoneStoreDir: this.orchestrator.config.trustZoneStoreDir,
+        enabled: this.orchestrator.config.trustZonesEnabled === true,
+        scenario: request.scenario,
+        recordedAt: request.recordedAt,
+        dryRun: request.dryRun === true
+      });
+    } catch (error) {
+      throw normalizeTrustZoneInputError(error) ?? error;
+    }
+    return {
+      namespace: resolvedNamespace,
+      ...result
+    };
+  }
+  async reviewDisposition(request) {
+    const memoryId = request.memoryId.trim();
+    const reasonCode = request.reasonCode.trim();
+    if (memoryId.length === 0) {
+      throw new EngramAccessInputError("memoryId is required");
+    }
+    if (reasonCode.length === 0) {
+      throw new EngramAccessInputError("reasonCode is required");
+    }
+    const resolvedNamespace = this.resolveWritableNamespace(
+      request.namespace,
+      void 0,
+      request.authenticatedPrincipal
+    );
+    const storage = await this.orchestrator.getStorage(resolvedNamespace);
+    const memory = await storage.getMemoryById(memoryId);
+    if (!memory) {
+      throw new EngramAccessInputError(`memory not found: ${memoryId}`);
+    }
+    const previousStatus = memory.frontmatter.status ?? "active";
+    const updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    const lifecycle = {
+      actor: "admin-console.review-disposition",
+      reasonCode,
+      ruleVersion: "memory-governance.v1"
+    };
+    if (request.status === "archived") {
+      const archivedPath = await storage.archiveMemory(memory, {
+        at: new Date(updatedAt),
+        ...lifecycle
+      });
+      if (!archivedPath) {
+        throw new Error(`failed to archive memory disposition: ${memoryId}`);
+      }
+      return {
+        ok: true,
+        namespace: resolvedNamespace,
+        memoryId,
+        status: "archived",
+        previousStatus,
+        currentPath: archivedPath
+      };
+    }
+    const updated = await storage.writeMemoryFrontmatter(memory, {
+      status: request.status,
+      updated: updatedAt
+    }, lifecycle);
+    if (!updated) {
+      throw new Error(`failed to update memory disposition: ${memoryId}`);
+    }
+    return {
+      ok: true,
+      namespace: resolvedNamespace,
+      memoryId,
+      status: request.status,
+      previousStatus,
+      currentPath: memory.path
+    };
+  }
+  serializeMemory(memory) {
+    return {
+      id: memory.frontmatter.id,
+      path: memory.path,
+      category: memory.frontmatter.category,
+      status: memory.frontmatter.status,
+      created: memory.frontmatter.created,
+      updated: memory.frontmatter.updated,
+      content: memory.content,
+      frontmatter: memory.frontmatter
+    };
+  }
+  serializeMemorySummary(memory, baseDir, disclosure, rawExcerpts) {
+    return shapeMemorySummary(memory, baseDir, disclosure, rawExcerpts);
+  }
+  async observe(request) {
+    if (!request.sessionKey || typeof request.sessionKey !== "string" || request.sessionKey.trim().length === 0) {
+      throw new EngramAccessInputError("sessionKey is required and must be a non-empty string");
+    }
+    if (!Array.isArray(request.messages) || request.messages.length === 0) {
+      throw new EngramAccessInputError("messages is required and must be a non-empty array");
+    }
+    for (const msg of request.messages) {
+      if (!msg || typeof msg !== "object" || typeof msg.role !== "string" || typeof msg.content !== "string") {
+        throw new EngramAccessInputError("each message must have a string 'role' and 'content'");
+      }
+      if (msg.role !== "user" && msg.role !== "assistant") {
+        throw new EngramAccessInputError(`invalid message role: ${msg.role} (expected 'user' or 'assistant')`);
+      }
+    }
+    const hasExplicitNamespace = typeof request.namespace === "string" && request.namespace.trim().length > 0;
+    const principal = this.resolveRequestPrincipal(
+      request.sessionKey,
+      request.authenticatedPrincipal
+    );
+    const namespace = this.resolveWritableNamespace(
+      request.namespace,
+      request.sessionKey,
+      request.authenticatedPrincipal
+    );
+    const shouldWriteObjectiveState = this.orchestrator.config.objectiveStateMemoryEnabled === true && this.orchestrator.config.objectiveStateSnapshotWritesEnabled === true;
+    const objectiveStateBaseNamespace = hasExplicitNamespace ? namespace : defaultNamespaceForPrincipal(principal, this.orchestrator.config);
+    if (shouldWriteObjectiveState && !hasExplicitNamespace && !canWriteNamespace(
+      principal,
+      objectiveStateBaseNamespace,
+      this.orchestrator.config
+    )) {
+      throw new EngramAccessInputError(
+        `namespace is not writable: ${objectiveStateBaseNamespace}`
+      );
+    }
+    await this.maybeAttachCodingContext(request.sessionKey, {
+      cwd: request.cwd,
+      projectTag: request.projectTag
+    });
+    const objectiveStateNamespace = hasExplicitNamespace ? namespace : this.orchestrator.applyCodingNamespaceOverlay(
+      request.sessionKey,
+      objectiveStateBaseNamespace
+    );
+    const lcmSessionKey = namespace !== this.orchestrator.config.defaultNamespace ? `${namespace}:${request.sessionKey}` : request.sessionKey;
+    if (shouldWriteObjectiveState) {
+      try {
+        const objectiveStateLocation = await this.objectiveStateStoreLocationForNamespace(
+          objectiveStateNamespace
+        );
+        await recordObjectiveStateSnapshotsFromObservedMessages({
+          memoryDir: objectiveStateLocation.memoryDir,
+          objectiveStateStoreDir: objectiveStateLocation.objectiveStateStoreDir,
+          objectiveStateMemoryEnabled: this.orchestrator.config.objectiveStateMemoryEnabled,
+          objectiveStateSnapshotWritesEnabled: this.orchestrator.config.objectiveStateSnapshotWritesEnabled,
+          sessionKey: request.sessionKey,
+          recordedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          messages: request.messages
+        });
+      } catch (err) {
+        log.error(`access-observe objective-state snapshot write failed: ${err}`);
+      }
+    }
+    let lcmArchived = false;
+    if (this.orchestrator.lcmEngine && this.orchestrator.lcmEngine.enabled) {
+      try {
+        this.orchestrator.lcmEngine.enqueueObserveMessages(lcmSessionKey, request.messages);
+        lcmArchived = true;
+      } catch (err) {
+        log.error(`access-observe LCM enqueue failed: ${err}`);
+      }
+    }
+    let extractionQueued = false;
+    if (request.skipExtraction !== true) {
+      const turns = request.messages.map((m) => ({
+        source: "openclaw",
+        sessionKey: lcmSessionKey,
+        role: m.role,
+        content: m.content,
+        parts: m.parts,
+        rawContent: m.rawContent,
+        sourceFormat: m.sourceFormat,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      }));
+      try {
+        const extractionPromise = this.orchestrator.ingestReplayBatch(turns, {
+          archiveLcm: false
+        });
+        extractionPromise.catch((err) => {
+          log.error(`access-observe background extraction failed: ${err}`);
+        });
+        extractionQueued = true;
+      } catch (err) {
+        log.error(`access-observe extraction enqueue failed: ${err}`);
+      }
+    }
+    log.info(
+      `access-observe namespace=${namespace} sessionKey=${request.sessionKey} messages=${request.messages.length} lcm=${lcmArchived} extraction=${extractionQueued}`
+    );
+    return {
+      accepted: request.messages.length,
+      sessionKey: request.sessionKey,
+      namespace,
+      lcmArchived,
+      extractionQueued
+    };
+  }
+  async lcmSearch(request) {
+    if (!request.query || typeof request.query !== "string" || request.query.trim().length === 0) {
+      throw new EngramAccessInputError("query is required and must be a non-empty string");
+    }
+    const principal = this.resolveRequestPrincipal(request.sessionKey, request.authenticatedPrincipal);
+    const namespace = this.resolveReadableNamespace(request.namespace, principal);
+    if (!this.orchestrator.lcmEngine || !this.orchestrator.lcmEngine.enabled) {
+      return {
+        query: request.query,
+        namespace,
+        results: [],
+        count: 0,
+        lcmEnabled: false
+      };
+    }
+    const limit = Math.max(1, Math.min(request.limit ?? 10, 100));
+    const lcmSessionKey = request.sessionKey && namespace !== this.orchestrator.config.defaultNamespace ? `${namespace}:${request.sessionKey}` : request.sessionKey;
+    const rawResults = await this.orchestrator.lcmEngine.searchContextFull(
+      request.query,
+      limit,
+      lcmSessionKey
+    );
+    const results = rawResults.map((r) => ({
+      sessionId: r.session_id,
+      content: r.content,
+      turnIndex: r.turn_index
+    }));
+    return {
+      query: request.query,
+      namespace,
+      results,
+      count: results.length,
+      lcmEnabled: true
+    };
+  }
+  async lcmCompactionFlush(request) {
+    if (!request.sessionKey || typeof request.sessionKey !== "string" || request.sessionKey.trim().length === 0) {
+      throw new EngramAccessInputError("sessionKey is required and must be a non-empty string");
+    }
+    const namespace = this.resolveWritableNamespace(
+      request.namespace,
+      request.sessionKey,
+      request.authenticatedPrincipal
+    );
+    if (!this.orchestrator.lcmEngine || !this.orchestrator.lcmEngine.enabled) {
+      return {
+        enabled: false,
+        flushed: false,
+        sessionKey: request.sessionKey,
+        namespace,
+        reason: "LCM is disabled"
+      };
+    }
+    const lcmSessionKey = namespace !== this.orchestrator.config.defaultNamespace ? `${namespace}:${request.sessionKey}` : request.sessionKey;
+    await this.orchestrator.lcmEngine.waitForSessionObserveIdle(lcmSessionKey);
+    await this.orchestrator.lcmEngine.preCompactionFlush(lcmSessionKey);
+    return {
+      enabled: true,
+      flushed: true,
+      sessionKey: request.sessionKey,
+      namespace
+    };
+  }
+  async lcmCompactionRecord(request) {
+    if (!request.sessionKey || typeof request.sessionKey !== "string" || request.sessionKey.trim().length === 0) {
+      throw new EngramAccessInputError("sessionKey is required and must be a non-empty string");
+    }
+    if (!Number.isInteger(request.tokensBefore) || request.tokensBefore < 0) {
+      throw new EngramAccessInputError("tokensBefore must be a non-negative integer");
+    }
+    if (!Number.isInteger(request.tokensAfter) || request.tokensAfter < 0) {
+      throw new EngramAccessInputError("tokensAfter must be a non-negative integer");
+    }
+    const namespace = this.resolveWritableNamespace(
+      request.namespace,
+      request.sessionKey,
+      request.authenticatedPrincipal
+    );
+    if (!this.orchestrator.lcmEngine || !this.orchestrator.lcmEngine.enabled) {
+      return {
+        enabled: false,
+        recorded: false,
+        sessionKey: request.sessionKey,
+        namespace,
+        reason: "LCM is disabled"
+      };
+    }
+    const lcmSessionKey = namespace !== this.orchestrator.config.defaultNamespace ? `${namespace}:${request.sessionKey}` : request.sessionKey;
+    await this.orchestrator.lcmEngine.waitForSessionObserveIdle(lcmSessionKey);
+    await this.orchestrator.lcmEngine.recordCompaction(
+      lcmSessionKey,
+      request.tokensBefore,
+      request.tokensAfter
+    );
+    return {
+      enabled: true,
+      recorded: true,
+      sessionKey: request.sessionKey,
+      namespace
+    };
+  }
+  // ── Parity tools (match OpenClaw plugin feature set) ──────────────────
+  // ── Continuity / Identity ──────────────────────────────────────────────
+  async continuityAuditGenerate(request) {
+    if (!this.orchestrator.config.identityContinuityEnabled) {
+      return { enabled: false, reason: "Identity continuity is disabled. Enable `identityContinuityEnabled: true`." };
+    }
+    if (!this.orchestrator.config.continuityAuditEnabled) {
+      return { enabled: false, reason: "Continuity audits are disabled. Enable `continuityAuditEnabled: true`." };
+    }
+    if (!this.orchestrator.compounding) {
+      return { enabled: false, reason: "Compounding engine is disabled. Enable `compoundingEnabled: true`." };
+    }
+    const period = request.period === "monthly" ? "monthly" : "weekly";
+    const key = request.key?.trim() || void 0;
+    const audit = await this.orchestrator.compounding.synthesizeContinuityAudit({ period, key });
+    return { enabled: true, period: audit.period, key: audit.key, reportPath: audit.reportPath };
+  }
+  async continuityIncidentOpen(request) {
+    if (!this.orchestrator.config.identityContinuityEnabled) {
+      return { enabled: false, reason: "Identity continuity is disabled. Enable `identityContinuityEnabled: true`." };
+    }
+    if (!this.orchestrator.config.continuityIncidentLoggingEnabled) {
+      return { enabled: false, reason: "Continuity incident logging is disabled. Enable `continuityIncidentLoggingEnabled: true`." };
+    }
+    const symptom = request.symptom?.trim();
+    if (!symptom) throw new EngramAccessInputError("symptom is required");
+    const resolvedNs = this.resolveWritableNamespace(request.namespace, void 0, request.principal);
+    const storage = await this.orchestrator.getStorage(resolvedNs);
+    const created = await storage.appendContinuityIncident({
+      symptom,
+      triggerWindow: request.triggerWindow?.trim() || void 0,
+      suspectedCause: request.suspectedCause?.trim() || void 0
+    });
+    return { created: true, incident: created };
+  }
+  async continuityIncidentClose(request) {
+    if (!this.orchestrator.config.identityContinuityEnabled) {
+      return { enabled: false, reason: "Identity continuity is disabled." };
+    }
+    if (!this.orchestrator.config.continuityIncidentLoggingEnabled) {
+      return { enabled: false, reason: "Continuity incident logging is disabled." };
+    }
+    const id = request.id?.trim();
+    if (!id) throw new EngramAccessInputError("id is required");
+    const fixApplied = request.fixApplied?.trim();
+    if (!fixApplied) throw new EngramAccessInputError("fixApplied is required");
+    const verificationResult = request.verificationResult?.trim();
+    if (!verificationResult) throw new EngramAccessInputError("verificationResult is required");
+    const resolvedNs = this.resolveWritableNamespace(request.namespace, void 0, request.principal);
+    const storage = await this.orchestrator.getStorage(resolvedNs);
+    const closed = await storage.closeContinuityIncident(id, {
+      fixApplied,
+      verificationResult,
+      preventiveRule: request.preventiveRule?.trim() || void 0
+    });
+    if (!closed) return { closed: false, reason: `Incident not found: ${id}` };
+    return { closed: true, incident: closed };
+  }
+  async continuityIncidentList(request) {
+    if (!this.orchestrator.config.identityContinuityEnabled) {
+      return { enabled: false, reason: "Identity continuity is disabled." };
+    }
+    const state = request.state === "closed" || request.state === "all" ? request.state : "open";
+    const limit = Math.max(1, Math.min(200, Math.floor(request.limit ?? 25)));
+    const resolvedNs = this.resolveReadableNamespace(request.namespace, request.principal);
+    const storage = await this.orchestrator.getStorage(resolvedNs);
+    const incidents = await storage.readContinuityIncidents(limit, state);
+    return { state, incidents, count: incidents.length };
+  }
+  async continuityLoopAddOrUpdate(request) {
+    if (!this.orchestrator.config.identityContinuityEnabled) {
+      return { enabled: false, reason: "Identity continuity is disabled." };
+    }
+    const resolvedNs = this.resolveWritableNamespace(request.namespace, void 0, request.principal);
+    const storage = await this.orchestrator.getStorage(resolvedNs);
+    const loop = await storage.upsertIdentityImprovementLoop({
+      id: request.id?.trim() || "",
+      cadence: request.cadence,
+      purpose: request.purpose?.trim() || "",
+      status: request.status,
+      killCondition: request.killCondition?.trim() || "",
+      lastReviewed: request.lastReviewed?.trim() || void 0,
+      notes: request.notes?.trim() || void 0
+    });
+    return { saved: true, loop };
+  }
+  async continuityLoopReview(request) {
+    if (!this.orchestrator.config.identityContinuityEnabled) {
+      return { enabled: false, reason: "Identity continuity is disabled." };
+    }
+    const id = request.id?.trim();
+    if (!id) throw new EngramAccessInputError("id is required");
+    const resolvedNs = this.resolveWritableNamespace(request.namespace, void 0, request.principal);
+    const storage = await this.orchestrator.getStorage(resolvedNs);
+    const reviewed = await storage.reviewIdentityImprovementLoop(id, {
+      status: request.status,
+      notes: request.notes?.trim() || void 0,
+      reviewedAt: request.reviewedAt?.trim() || void 0
+    });
+    if (!reviewed) return { reviewed: false, reason: `Continuity loop not found: ${id}` };
+    return { reviewed: true, loop: reviewed };
+  }
+  async identityAnchorGet(request) {
+    if (!this.orchestrator.config.identityContinuityEnabled) {
+      return { enabled: false, reason: "Identity continuity is disabled." };
+    }
+    const resolvedNs = this.resolveReadableNamespace(request.namespace, request.principal);
+    const storage = await this.orchestrator.getStorage(resolvedNs);
+    const anchor = await storage.readIdentityAnchor();
+    if (!anchor) return { found: false, message: "No identity anchor found yet. Use identity_anchor_update to create one." };
+    return { found: true, anchor };
+  }
+  /**
+   * @deprecated since issue #679 PR 5/5 — the identity-anchor model is
+   * superseded by the peer registry. Use `peerSet({ id: "self", ... })` or
+   * `remnic peer set self` to update the self peer's identity kernel, and
+   * `remnic peer migrate` to seed `peers/self/identity.md` from existing
+   * legacy anchor data. This method continues to function for backward
+   * compatibility but will be removed in a future major version.
+   */
+  async identityAnchorUpdate(request) {
+    if (!this.orchestrator.config.identityContinuityEnabled) {
+      return { enabled: false, reason: "Identity continuity is disabled." };
+    }
+    const updates = {
+      "Identity Traits": request.identityTraits?.trim() || void 0,
+      "Communication Preferences": request.communicationPreferences?.trim() || void 0,
+      "Operating Principles": request.operatingPrinciples?.trim() || void 0,
+      "Continuity Notes": request.continuityNotes?.trim() || void 0
+    };
+    const hasUpdate = Object.values(updates).some((v) => typeof v === "string" && v.length > 0);
+    if (!hasUpdate) throw new EngramAccessInputError("At least one section field is required.");
+    const resolvedNs = this.resolveWritableNamespace(request.namespace, void 0, request.principal);
+    const storage = await this.orchestrator.getStorage(resolvedNs);
+    const existing = await storage.readIdentityAnchor();
+    const merged = this.mergeIdentityAnchorSections(existing, updates);
+    await storage.writeIdentityAnchor(merged);
+    const updatedSections = Object.entries(updates).filter(([, v]) => typeof v === "string" && v.length > 0).map(([name]) => name);
+    return { updated: true, sections: updatedSections, anchor: merged };
+  }
+  async memoryIdentity(request) {
+    const resolvedNs = this.resolveReadableNamespace(request.namespace, request.principal);
+    const storage = await this.orchestrator.getStorage(resolvedNs);
+    const identity = await storage.readIdentityReflections();
+    if (!identity) return { found: false, message: "No identity reflections found." };
+    return { found: true, identity };
+  }
+  // ── Work Layer ──────────────────────────────────────────────────────────
+  async workTask(request) {
+    const STATUSES = /* @__PURE__ */ new Set(["todo", "in_progress", "blocked", "done", "cancelled"]);
+    const PRIORITIES = /* @__PURE__ */ new Set(["low", "medium", "high"]);
+    const asStatus = (v) => v && STATUSES.has(v) ? v : void 0;
+    const asPriority = (v) => v && PRIORITIES.has(v) ? v : void 0;
+    const storage = new WorkStorage(this.orchestrator.config.memoryDir);
+    await storage.ensureDirectories();
+    const action = request.action;
+    if (action === "create") {
+      if (!request.title?.trim()) throw new EngramAccessInputError("title is required for create");
+      const task = await storage.createTask({
+        title: request.title,
+        description: request.description,
+        status: asStatus(request.status),
+        priority: asPriority(request.priority),
+        owner: request.owner?.trim() || void 0,
+        assignee: request.assignee?.trim() || void 0,
+        projectId: request.projectId?.trim() || void 0,
+        tags: request.tags,
+        dueAt: request.dueAt?.trim() || void 0
+      });
+      return { action, task };
+    }
+    if (action === "get") {
+      if (!request.id?.trim()) throw new EngramAccessInputError("id is required for get");
+      return { action, task: await storage.getTask(request.id) };
+    }
+    if (action === "list") {
+      const tasks = await storage.listTasks({
+        status: asStatus(request.status),
+        owner: request.owner?.trim() || void 0,
+        assignee: request.assignee?.trim() || void 0,
+        projectId: request.projectId?.trim() || void 0
+      });
+      return { action, count: tasks.length, tasks };
+    }
+    if (action === "update") {
+      if (!request.id?.trim()) throw new EngramAccessInputError("id is required for update");
+      const patch = {};
+      if (request.title !== void 0) patch.title = request.title;
+      if (request.description !== void 0) patch.description = request.description;
+      const st = asStatus(request.status);
+      if (st) patch.status = st;
+      const pr = asPriority(request.priority);
+      if (pr) patch.priority = pr;
+      if (request.owner !== void 0) patch.owner = request.owner || null;
+      if (request.assignee !== void 0) patch.assignee = request.assignee || null;
+      if (request.projectId !== void 0) patch.projectId = request.projectId || null;
+      if (request.tags) patch.tags = request.tags;
+      if (request.dueAt !== void 0) patch.dueAt = request.dueAt || null;
+      return { action, task: await storage.updateTask(request.id, patch) };
+    }
+    if (action === "transition") {
+      if (!request.id?.trim()) throw new EngramAccessInputError("id is required for transition");
+      const st = asStatus(request.status);
+      if (!st) throw new EngramAccessInputError("valid status is required for transition");
+      return { action, task: await storage.transitionTask(request.id, st) };
+    }
+    if (action === "delete") {
+      if (!request.id?.trim()) throw new EngramAccessInputError("id is required for delete");
+      return { action, deleted: await storage.deleteTask(request.id) };
+    }
+    throw new EngramAccessInputError(`Unsupported work_task action: ${action}`);
+  }
+  async workProject(request) {
+    const STATUSES = /* @__PURE__ */ new Set(["active", "on_hold", "completed", "archived"]);
+    const asStatus = (v) => v && STATUSES.has(v) ? v : void 0;
+    const storage = new WorkStorage(this.orchestrator.config.memoryDir);
+    await storage.ensureDirectories();
+    const action = request.action;
+    if (action === "create") {
+      if (!request.name?.trim()) throw new EngramAccessInputError("name is required for create");
+      const project = await storage.createProject({
+        name: request.name,
+        description: request.description,
+        status: asStatus(request.status),
+        owner: request.owner?.trim() || void 0,
+        tags: request.tags
+      });
+      return { action, project };
+    }
+    if (action === "get") {
+      if (!request.id?.trim()) throw new EngramAccessInputError("id is required for get");
+      return { action, project: await storage.getProject(request.id) };
+    }
+    if (action === "list") {
+      const projects = await storage.listProjects();
+      return { action, count: projects.length, projects };
+    }
+    if (action === "update") {
+      if (!request.id?.trim()) throw new EngramAccessInputError("id is required for update");
+      const patch = {};
+      if (request.name !== void 0) patch.name = request.name;
+      if (request.description !== void 0) patch.description = request.description;
+      const st = asStatus(request.status);
+      if (st) patch.status = st;
+      if (request.owner !== void 0) patch.owner = request.owner || null;
+      if (request.tags) patch.tags = request.tags;
+      return { action, project: await storage.updateProject(request.id, patch) };
+    }
+    if (action === "delete") {
+      if (!request.id?.trim()) throw new EngramAccessInputError("id is required for delete");
+      return { action, deleted: await storage.deleteProject(request.id) };
+    }
+    if (action === "link_task") {
+      if (!request.taskId?.trim() || !request.projectId?.trim()) {
+        throw new EngramAccessInputError("taskId and projectId are required for link_task");
+      }
+      return { action, linked: await storage.linkTaskToProject(request.taskId, request.projectId) };
+    }
+    throw new EngramAccessInputError(`Unsupported work_project action: ${action}`);
+  }
+  async workBoard(request) {
+    const memoryDir = this.orchestrator.config.memoryDir;
+    await new WorkStorage(memoryDir).ensureDirectories();
+    const action = request.action;
+    const projectId = request.projectId?.trim() || void 0;
+    if (action === "export_markdown") {
+      const markdown = await exportWorkBoardMarkdown({ memoryDir, projectId });
+      return { action, markdown: wrapWorkLayerContext(markdown, { linkToMemory: request.linkToMemory === true }) };
+    }
+    if (action === "export_snapshot") {
+      const snapshot = await exportWorkBoardSnapshot({ memoryDir, projectId });
+      return { action, snapshot };
+    }
+    if (action === "import_snapshot") {
+      if (!request.snapshotJson?.trim()) throw new EngramAccessInputError("snapshotJson is required for import_snapshot");
+      const snapshot = JSON.parse(request.snapshotJson);
+      const result = await importWorkBoardSnapshot({ memoryDir, snapshot, projectId });
+      return { action, result };
+    }
+    throw new EngramAccessInputError(`Unsupported work_board action: ${action}`);
+  }
+  // ── Shared Context / Compounding ────────────────────────────────────────
+  async sharedContextWriteOutput(request) {
+    if (!this.orchestrator.sharedContext) {
+      return { enabled: false, reason: "Shared context is disabled. Enable `sharedContextEnabled: true`." };
+    }
+    const fp = await this.orchestrator.sharedContext.writeAgentOutput({
+      agentId: request.agentId,
+      title: request.title,
+      content: request.content
+    });
+    return { written: true, path: fp };
+  }
+  async sharedFeedbackRecord(request) {
+    if (!this.orchestrator.sharedContext) {
+      return { enabled: false, reason: "Shared context is disabled. Enable `sharedContextEnabled: true`." };
+    }
+    await this.orchestrator.sharedContext.appendFeedback({
+      agent: request.agent,
+      decision: request.decision,
+      reason: request.reason,
+      date: request.date?.trim() || (/* @__PURE__ */ new Date()).toISOString(),
+      learning: request.learning,
+      outcome: request.outcome,
+      severity: request.severity,
+      confidence: request.confidence,
+      workflow: request.workflow,
+      tags: request.tags,
+      evidenceWindowStart: request.evidenceWindowStart,
+      evidenceWindowEnd: request.evidenceWindowEnd,
+      refs: request.refs
+    });
+    return { recorded: true };
+  }
+  async sharedPrioritiesAppend(request) {
+    if (!this.orchestrator.sharedContext) {
+      return { enabled: false, reason: "Shared context is disabled. Enable `sharedContextEnabled: true`." };
+    }
+    await this.orchestrator.sharedContext.appendPrioritiesInbox({
+      agentId: request.agentId,
+      text: request.text
+    });
+    return { appended: true };
+  }
+  async sharedContextCrossSignalsRun(request) {
+    if (!this.orchestrator.sharedContext) {
+      return { enabled: false, reason: "Shared context is disabled. Enable `sharedContextEnabled: true`." };
+    }
+    const result = await this.orchestrator.sharedContext.synthesizeCrossSignals({ date: request.date });
+    return {
+      crossSignalsMarkdownPath: result.crossSignalsMarkdownPath,
+      crossSignalsPath: result.crossSignalsPath,
+      sourceCount: result.report.sourceCount,
+      feedbackCount: result.report.feedbackCount,
+      overlapCount: result.overlapCount
+    };
+  }
+  async sharedContextCurateDaily(request) {
+    if (!this.orchestrator.sharedContext) {
+      return { enabled: false, reason: "Shared context is disabled. Enable `sharedContextEnabled: true`." };
+    }
+    const result = await this.orchestrator.sharedContext.curateDaily({ date: request.date });
+    return {
+      roundtablePath: result.roundtablePath,
+      crossSignalsMarkdownPath: result.crossSignalsMarkdownPath,
+      crossSignalsPath: result.crossSignalsPath,
+      overlapCount: result.overlapCount
+    };
+  }
+  async compoundingWeeklySynthesize(request) {
+    if (!this.orchestrator.compounding) {
+      return { enabled: false, reason: "Compounding engine is disabled. Enable `compoundingEnabled: true`." };
+    }
+    const res = await this.orchestrator.compounding.synthesizeWeekly({ weekId: request.weekId });
+    return {
+      weekId: res.weekId,
+      reportPath: res.reportPath,
+      reportJsonPath: res.reportJsonPath,
+      rubricsPath: res.rubricsPath,
+      rubricsIndexPath: res.rubricsIndexPath,
+      mistakesCount: res.mistakesCount,
+      promotionCandidateCount: res.promotionCandidateCount
+    };
+  }
+  async compoundingPromoteCandidate(request) {
+    if (!this.orchestrator.compounding) {
+      return { enabled: false, reason: "Compounding engine is disabled. Enable `compoundingEnabled: true`." };
+    }
+    return await this.orchestrator.compounding.promoteCandidate({
+      weekId: request.weekId,
+      candidateId: request.candidateId,
+      dryRun: request.dryRun
+    });
+  }
+  // ── Compression Guidelines ────────────────────────────────────────────
+  async compressionGuidelinesOptimize(request) {
+    if (!this.orchestrator.config.compressionGuidelineLearningEnabled) {
+      return { enabled: false, reason: "Compression guideline learning is disabled. Enable `compressionGuidelineLearningEnabled: true`." };
+    }
+    return await this.orchestrator.optimizeCompressionGuidelines({
+      dryRun: request.dryRun,
+      eventLimit: request.eventLimit
+    });
+  }
+  async compressionGuidelinesActivate(request) {
+    if (!this.orchestrator.config.compressionGuidelineLearningEnabled) {
+      return { enabled: false, reason: "Compression guideline learning is disabled." };
+    }
+    return await this.orchestrator.activateCompressionGuidelineDraft({
+      expectedContentHash: request.expectedContentHash,
+      expectedGuidelineVersion: request.expectedGuidelineVersion
+    });
+  }
+  /** Conservative identity anchor section merge (matches tools.ts mergeIdentityAnchor logic). */
+  mergeIdentityAnchorSections(existingRaw, updates) {
+    const TITLE = "# Identity Continuity Anchor";
+    const SECTION_ORDER = ["Identity Traits", "Communication Preferences", "Operating Principles", "Continuity Notes"];
+    const lines = (existingRaw ?? "").replace(/\r/g, "").split("\n");
+    const headerLines = [];
+    const sectionContent = /* @__PURE__ */ new Map();
+    const order = [];
+    let current = null;
+    for (const line of lines) {
+      const m = line.match(/^##\s+(.+?)\s*$/);
+      if (m) {
+        current = m[1].trim();
+        if (!sectionContent.has(current)) {
+          sectionContent.set(current, []);
+          order.push(current);
+        }
+        continue;
+      }
+      if (!current) {
+        headerLines.push(line);
+      } else {
+        sectionContent.get(current)?.push(line);
+      }
+    }
+    const sections = /* @__PURE__ */ new Map();
+    for (const [name, cLines] of sectionContent) sections.set(name, cLines.join("\n").trim());
+    const header = headerLines.join("\n").trim() || TITLE;
+    for (const sectionName of SECTION_ORDER) {
+      const prev = sections.get(sectionName)?.trim();
+      const next = updates[sectionName]?.trim();
+      const existing = prev === "- (empty)" ? "" : prev;
+      if (!next) {
+        if (!sections.has(sectionName)) sections.set(sectionName, "");
+        continue;
+      }
+      if (!existing) {
+        sections.set(sectionName, next);
+        continue;
+      }
+      if (existing.includes(next)) continue;
+      if (next.includes(existing)) {
+        sections.set(sectionName, next);
+        continue;
+      }
+      sections.set(sectionName, `${existing}
+
+${next}`);
+    }
+    const finalOrder = [...SECTION_ORDER.filter((s) => sections.has(s)), ...order.filter((s) => !SECTION_ORDER.includes(s) && sections.has(s))];
+    const out = [header, ""];
+    for (const name of finalOrder) {
+      out.push(`## ${name}`, "");
+      const body = sections.get(name)?.trim();
+      if (body) out.push(body, "");
+      else out.push("");
+    }
+    return out.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
+  }
+  // ── Memory search & debug ─────────────────────────────────────────────
+  async memorySearch(request) {
+    const { query, namespace, maxResults, collection, principal } = request;
+    const resolvedNs = this.resolveReadableNamespace(namespace, principal);
+    const namespaceFilter = resolvedNs !== this.orchestrator.config.defaultNamespace ? resolvedNs : void 0;
+    const results = collection === "global" ? (await this.orchestrator.qmd.searchGlobal(query, maxResults)).filter(
+      (r) => namespaceFilter ? r.path.includes(`/namespaces/${namespaceFilter}/`) || !r.path.includes("/namespaces/") && namespaceFilter === this.orchestrator.config.defaultNamespace : true
+    ) : await this.orchestrator.searchAcrossNamespaces({
+      query,
+      namespaces: namespaceFilter ? [namespaceFilter] : void 0,
+      maxResults,
+      mode: "search"
+    });
+    return {
+      query,
+      results: results.map((r) => ({
+        path: r.path,
+        score: r.score,
+        snippet: (r.snippet ?? "").slice(0, 800)
+      })),
+      count: results.length
+    };
+  }
+  async memoryProfile(namespace, principal) {
+    const resolvedNs = this.resolveReadableNamespace(namespace, principal);
+    const storage = await this.orchestrator.getStorage(resolvedNs);
+    const profile = await storage.readProfile();
+    return {
+      profile: profile || "No profile built yet. The profile builds automatically through conversations."
+    };
+  }
+  async memoryEntitiesList(namespace, principal) {
+    const resolvedNs = this.resolveReadableNamespace(namespace, principal);
+    const storage = await this.orchestrator.getStorage(resolvedNs);
+    const entities = await storage.readEntities();
+    return { entities, count: entities.length };
+  }
+  async memoryQuestions(namespace, principal) {
+    const resolvedNs = this.resolveReadableNamespace(namespace, principal);
+    const storage = await this.orchestrator.getStorage(resolvedNs);
+    const questions = await storage.readQuestions();
+    return {
+      questions: questions.map((q) => ({ id: q.id, question: q.question, resolved: q.resolved })),
+      count: questions.length
+    };
+  }
+  async lastRecallSnapshot(sessionKey) {
+    const snapshot = sessionKey ? this.orchestrator.lastRecall.get(sessionKey) : this.orchestrator.lastRecall.getMostRecent();
+    return snapshot ?? { message: "No recall snapshot available" };
+  }
+  async intentDebug(namespace) {
+    const snapshot = await this.orchestrator.getLastIntentSnapshot(namespace);
+    return snapshot ?? { message: "No intent debug snapshot available" };
+  }
+  async qmdDebug(namespace) {
+    const snapshot = await this.orchestrator.getLastQmdRecallSnapshot(namespace);
+    return snapshot ?? { message: "No QMD debug snapshot available" };
+  }
+  async graphExplainLastRecall(namespace) {
+    const explanation = await this.orchestrator.explainLastGraphRecall({ namespace });
+    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, authenticatedPrincipal) {
+    const namespace = this.resolveReadableNamespace(
+      request.namespace,
+      authenticatedPrincipal
+    );
+    const storage = await this.orchestrator.getStorage(namespace);
+    const cfg = this.orchestrator.config;
+    let namespaceRootReal;
+    try {
+      namespaceRootReal = await nodeFs.realpath(storage.dir);
+    } catch {
+      namespaceRootReal = nodePath.resolve(storage.dir);
+    }
+    const namespaceRootWithSep = namespaceRootReal.endsWith(nodePath.sep) ? namespaceRootReal : namespaceRootReal + nodePath.sep;
+    const loadNode = async (relPath) => {
+      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;
+      try {
+        canonical = await nodeFs.realpath(candidate);
+      } catch {
+        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;
+      }
+      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
+      };
+    };
+    return buildGraphSnapshot({
+      memoryDir: namespaceRootReal,
+      graphConfig: {
+        entityGraphEnabled: cfg.entityGraphEnabled === true,
+        timeGraphEnabled: cfg.timeGraphEnabled === true,
+        causalGraphEnabled: cfg.causalGraphEnabled === true
+      },
+      request: {
+        limit: request.limit,
+        since: request.since,
+        focusNodeId: request.focusNodeId,
+        categories: request.categories
+      },
+      loadNode
+    });
+  }
+  async memoryFeedback(request) {
+    if (!this.orchestrator.config.feedbackEnabled) {
+      return {
+        recorded: false,
+        enabled: false,
+        reason: "Feedback is disabled. Enable `feedbackEnabled: true` in the Engram config to store feedback."
+      };
+    }
+    await this.orchestrator.recordMemoryFeedback(
+      request.memoryId,
+      request.vote,
+      request.note
+    );
+    return { recorded: true };
+  }
+  /**
+   * Record a Memory Worth outcome observation (issue #560 PR 3).
+   *
+   * This is distinct from `memoryFeedback` — feedback is a human thumbs
+   * up/down on whether a recalled memory was relevant; outcome is an
+   * automated signal about whether the session that consumed the memory
+   * ultimately succeeded or failed. Outcomes feed the Laplace-smoothed
+   * worth score (`computeMemoryWorth`, PR 2) that PR 4 will use to
+   * downweight memories correlated with bad sessions.
+   *
+   * The underlying writer only touches fact-category memories. Corrections,
+   * procedures, and other kinds return `{ ok: false, reason:
+   * "ineligible_category" }` so a ledger drainer doesn't need to pre-filter.
+   */
+  async memoryOutcome(request) {
+    if (request.memoryId.includes("/") || request.memoryId.includes("\\")) {
+      throw new EngramAccessInputError(
+        "memoryId must not contain path separators"
+      );
+    }
+    const resolvedNs = this.resolveWritableNamespace(
+      request.namespace,
+      request.sessionKey,
+      request.principal
+    );
+    const storage = await this.orchestrator.getStorage(resolvedNs);
+    return recordMemoryOutcome(storage, {
+      memoryPath: `${request.memoryId}.md`,
+      outcome: request.outcome,
+      timestamp: request.timestamp
+    });
+  }
+  async memoryPromote(request) {
+    const resolvedNs = this.resolveWritableNamespace(request.namespace, request.sessionKey, request.principal);
+    const storage = await this.orchestrator.getStorage(resolvedNs);
+    await storage.updateMemoryFrontmatter(request.memoryId, {
+      lifecycleState: "active",
+      updated: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    return { promoted: true, memoryId: request.memoryId };
+  }
+  async memoryActionApply(request) {
+    const actionTypes = /* @__PURE__ */ new Set([
+      "store_episode",
+      "store_note",
+      "update_note",
+      "create_artifact",
+      "summarize_node",
+      "discard",
+      "link_graph"
+    ]);
+    if (!actionTypes.has(request.action)) {
+      throw new EngramAccessInputError(
+        `memory_action_apply: invalid action ${JSON.stringify(request.action)}`
+      );
+    }
+    if (this.orchestrator.config.contextCompressionActionsEnabled !== true) {
+      throw new EngramAccessInputError(
+        "memory_action_apply is disabled; enable contextCompressionActionsEnabled to use this tool"
+      );
+    }
+    const outcome = request.outcome ?? "skipped";
+    if (outcome !== "applied" && outcome !== "skipped" && outcome !== "failed") {
+      throw new EngramAccessInputError(
+        `memory_action_apply: outcome must be "applied", "skipped", or "failed"; got ${JSON.stringify(outcome)}`
+      );
+    }
+    const resolvedNs = this.resolveWritableNamespace(
+      request.namespace,
+      request.sessionKey,
+      request.principal
+    );
+    const inputSummaryParts = [
+      request.content,
+      request.category ? `category=${request.category}` : void 0,
+      request.linkTargetId ? `linkTargetId=${request.linkTargetId}` : void 0,
+      request.linkType ? `linkType=${request.linkType}` : void 0,
+      typeof request.linkStrength === "number" ? `linkStrength=${request.linkStrength}` : void 0,
+      request.artifactType ? `artifactType=${request.artifactType}` : void 0,
+      typeof request.execute === "boolean" ? `execute=${request.execute}` : void 0
+    ].filter((part) => typeof part === "string" && part.length > 0);
+    const event = {
+      action: request.action,
+      outcome,
+      namespace: resolvedNs,
+      actor: "access.memory_action_apply",
+      subsystem: "access.memory_action_apply",
+      reason: request.reason,
+      memoryId: request.memoryId,
+      sourceSessionKey: request.sessionKey,
+      inputSummary: inputSummaryParts.length > 0 ? inputSummaryParts.join(" | ").slice(0, 500) : void 0,
+      dryRun: request.dryRun === true,
+      promptHash: typeof request.sourcePrompt === "string" && request.sourcePrompt.length > 0 ? createHash("sha256").update(request.sourcePrompt).digest("hex") : void 0
+    };
+    const preview = this.orchestrator.previewMemoryActionEvent(event);
+    if (request.dryRun === true) {
+      return { recorded: false, dryRun: true, event: preview };
+    }
+    const recorded = await this.orchestrator.appendMemoryActionEvent(event);
+    return { recorded, event: preview };
+  }
+  async contextCheckpoint(request) {
+    const resolvedNs = this.resolveWritableNamespace(request.namespace, request.sessionKey, request.principal);
+    const storage = await this.orchestrator.getStorage(resolvedNs);
+    const storageDir = storage.dir;
+    const { writeFile, mkdir } = await import("fs/promises");
+    const { join: join2, resolve: resolve2 } = await import("path");
+    const safeKey = request.sessionKey.replace(/[^a-zA-Z0-9_-]/g, "_");
+    if (!safeKey) throw new EngramAccessInputError("sessionKey is required");
+    const checkpointDir = join2(storageDir, "checkpoints", safeKey);
+    const resolved = resolve2(checkpointDir);
+    if (!resolved.startsWith(resolve2(storageDir))) {
+      throw new EngramAccessInputError("Invalid sessionKey");
+    }
+    await mkdir(checkpointDir, { recursive: true });
+    const ts = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+    const filePath = join2(checkpointDir, `checkpoint-${ts}.md`);
+    await writeFile(filePath, request.context, "utf-8");
+    return { saved: true };
+  }
+  async lcmStatus() {
+    if (!this.orchestrator.lcmEngine || !this.orchestrator.lcmEngine.enabled) {
+      return {
+        enabled: false,
+        archiveAvailable: false
+      };
+    }
+    const stats = await this.orchestrator.lcmEngine.getStats();
+    return {
+      enabled: true,
+      archiveAvailable: true,
+      stats: {
+        totalTurns: stats.totalMessages
+      }
+    };
+  }
+  /**
+   * Record citation usage from an observed oai-mem-citation block.
+   * For each citation entry, extract the memory ID from the path and
+   * increment its access tracking via the orchestrator. Returns the
+   * count of submitted IDs and the count of IDs that matched real memories.
+   */
+  async recordCitationUsage(request) {
+    if (request.entries.length === 0) return { submitted: 0, matched: 0 };
+    const resolvedNamespace = this.resolveWritableNamespace(
+      request.namespace,
+      request.sessionId,
+      request.authenticatedPrincipal
+    );
+    const memoryIds = [];
+    for (const entry of request.entries) {
+      const basename2 = entry.path.split("/").pop() ?? entry.path;
+      const id = basename2.endsWith(".md") ? basename2.slice(0, -3) : basename2;
+      if (id.length > 0) {
+        memoryIds.push(id);
+      }
+    }
+    if (memoryIds.length === 0) return { submitted: 0, matched: 0 };
+    const storage = await this.orchestrator.getStorage(resolvedNamespace);
+    const existingIds = await storage.filterExistingMemoryIds(memoryIds);
+    const matchedIds = memoryIds.filter((id) => existingIds.has(id));
+    if (matchedIds.length > 0) {
+      try {
+        this.orchestrator.trackMemoryAccess(matchedIds);
+      } catch {
+        log.debug("citation usage tracking: failed to record access for cited memories");
+      }
+    }
+    return { submitted: memoryIds.length, matched: matchedIds.length };
+  }
+  // ── Operator Console state (issue #688 PR 2/3) ────────────────────────────
+  /**
+   * Gather a point-in-time `ConsoleStateSnapshot` from the orchestrator.
+   *
+   * Principal-aware: `resolveReadableNamespace` enforces ACL before the
+   * snapshot is gathered, so callers cannot read a namespace they don't
+   * have read access to (CLAUDE.md rule 42).  The resolved namespace's
+   * storage directory is forwarded as `config.memoryDir` so the ledger-
+   * tail reader in `gatherConsoleState` scans the correct namespace root
+   * rather than the global root.  Read-only — never mutates orchestrator state.
+   */
+  async consoleState(namespace, principal) {
+    const resolvedNamespace = this.resolveReadableNamespace(namespace, principal);
+    const storage = await this.orchestrator.getStorage(resolvedNamespace);
+    const { gatherConsoleState } = await import("./state-NCHQ4TRG.js");
+    const orchestratorProxy = Object.create(this.orchestrator, {
+      config: {
+        value: { ...this.orchestrator.config, memoryDir: storage.dir },
+        enumerable: true,
+        configurable: true
+      }
+    });
+    return gatherConsoleState(orchestratorProxy);
+  }
+  // ── Peer Registry surfaces (issue #679 PR 4/5) ────────────────────────────
+  /**
+   * List all registered peers. Returns the array of `Peer` objects in
+   * deterministic alphabetical order (mirroring `listPeers` storage semantics).
+   */
+  async peerList() {
+    const { listPeers } = await import("./peers-HCVGHMAE.js");
+    const peers = await listPeers(this.orchestrator.config.memoryDir);
+    return { peers };
+  }
+  /**
+   * Get a single peer by id. Returns `{ found: false }` when the peer does
+   * not exist rather than throwing, matching the `memoryGet` / `entityGet`
+   * pattern used throughout the service.
+   */
+  async peerGet(peerId) {
+    const peers = await import("./peers-HCVGHMAE.js");
+    const validateId = peers.assertValidPeerId;
+    try {
+      validateId(peerId);
+    } catch (err) {
+      throw new EngramAccessInputError(err.message);
+    }
+    const peer = await peers.readPeer(this.orchestrator.config.memoryDir, peerId);
+    if (!peer) return { found: false };
+    return { found: true, peer };
+  }
+  /**
+   * Upsert a peer. Writes `peers/{id}/identity.md`. On first write the
+   * `createdAt` timestamp is set to now; on subsequent writes only
+   * `displayName` and `notes` are mutated (kind and createdAt are immutable
+   * once set, per the storage contract).
+   *
+   * Returns `{ created: true }` on first write, `{ created: false }` on update.
+   */
+  async peerSet(input) {
+    const peers = await import("./peers-HCVGHMAE.js");
+    const validateId = peers.assertValidPeerId;
+    const { id } = input;
+    try {
+      validateId(id);
+    } catch (err) {
+      throw new EngramAccessInputError(err.message);
+    }
+    const memoryDir = this.orchestrator.config.memoryDir;
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const existing = await peers.readPeer(memoryDir, id);
+    const ALLOWED_KINDS = /* @__PURE__ */ new Set(["self", "human", "agent", "integration"]);
+    if (!existing) {
+      const kind = input.kind ?? "human";
+      if (!ALLOWED_KINDS.has(kind)) {
+        throw new EngramAccessInputError(
+          `peer kind must be one of ${[...ALLOWED_KINDS].join(", ")}`
+        );
+      }
+      const newPeer = {
+        id,
+        kind,
+        displayName: input.displayName ?? id,
+        createdAt: now,
+        updatedAt: now,
+        ...typeof input.notes === "string" ? { notes: input.notes } : {}
+      };
+      await peers.writePeer(memoryDir, newPeer);
+      return { ok: true, created: true, peer: newPeer };
+    }
+    const updated = {
+      id: existing.id,
+      kind: existing.kind,
+      createdAt: existing.createdAt,
+      updatedAt: now,
+      displayName: input.displayName !== void 0 ? input.displayName : existing.displayName,
+      ...input.notes !== void 0 ? { notes: input.notes } : existing.notes !== void 0 ? { notes: existing.notes } : {}
+    };
+    await peers.writePeer(memoryDir, updated);
+    return { ok: true, created: false, peer: updated };
+  }
+  /**
+   * Delete a peer by removing `peers/{id}/identity.md`. If the file does not
+   * exist the call is a no-op (idempotent). The peer directory itself
+   * (`peers/{id}/`) is intentionally left in place — profile and interaction
+   * log data are not destroyed.
+   */
+  async peerDelete(peerId) {
+    const peers = await import("./peers-HCVGHMAE.js");
+    const validateId = peers.assertValidPeerId;
+    try {
+      validateId(peerId);
+    } catch (err) {
+      throw new EngramAccessInputError(err.message);
+    }
+    const deleted = await peers.deletePeer(this.orchestrator.config.memoryDir, peerId);
+    return { ok: true, deleted };
+  }
+  /**
+   * Destructively purge the entire peer directory for a given peerId —
+   * `identity.md`, `profile.md`, `interactions.log.md`, and any other
+   * files in `peers/{id}/`. Requires `confirm: "yes"` to prevent
+   * accidental invocation.
+   *
+   * This is the DESTRUCTIVE counterpart to `peerDelete`, which only
+   * removes `identity.md`. All companion files are permanently removed.
+   *
+   * Returns `{ ok: true, purged: true }` when the directory existed and
+   * was removed; `{ ok: true, purged: false }` when the directory did
+   * not exist (idempotent no-op).
+   */
+  async peerForget(peerId, opts) {
+    const peers = await import("./peers-HCVGHMAE.js");
+    const validateId = peers.assertValidPeerId;
+    try {
+      validateId(peerId);
+    } catch (err) {
+      throw new EngramAccessInputError(err.message);
+    }
+    if (opts.confirm !== "yes") {
+      throw new EngramAccessInputError(
+        "peerForget requires confirm: 'yes' to prevent accidental data loss"
+      );
+    }
+    const result = await peers.forgetPeer(this.orchestrator.config.memoryDir, peerId, {
+      confirm: "yes"
+    });
+    return { ok: true, purged: result.purged };
+  }
+  /**
+   * Get the evolving cognitive profile for a peer. Returns `{ found: false }`
+   * when no profile file exists yet (profile is written by the async reasoner,
+   * PR 2/5). The peer identity itself need not exist for a profile to exist,
+   * but in practice the reasoner only writes profiles for registered peers.
+   */
+  async peerProfileGet(peerId) {
+    const peers = await import("./peers-HCVGHMAE.js");
+    const validateId = peers.assertValidPeerId;
+    try {
+      validateId(peerId);
+    } catch (err) {
+      throw new EngramAccessInputError(err.message);
+    }
+    const profile = await peers.readPeerProfile(this.orchestrator.config.memoryDir, peerId);
+    if (!profile) return { found: false };
+    return { found: true, profile };
+  }
+  // ── Contradiction Review (issue #520) ──────────────────────────────────────
+  get memoryDir() {
+    return this.orchestrator.config.memoryDir;
+  }
+  /**
+   * Resolve the storage directory for a given namespace.  Used by the SSE
+   * graph-event handler to subscribe to the correct per-namespace bus rather
+   * than the global root (CLAUDE.md rule 42 — read/write paths must resolve
+   * through the same namespace layer).
+   *
+   * `principal` must be the transport-bound request principal (from
+   * `resolveRequestPrincipal`).  When namespaces are enabled, an absent
+   * principal causes `resolveReadableNamespace` to throw an auth error,
+   * matching the behaviour of every other authenticated read path.
+   *
+   * Falls back to `this.memoryDir` when namespaces are disabled or the
+   * namespace is absent, matching the behaviour of every other read path.
+   */
+  async getMemoryDirForNamespace(namespace, principal) {
+    const resolved = this.resolveReadableNamespace(namespace, principal);
+    const storage = await this.orchestrator.getStorage(resolved);
+    return storage.dir;
+  }
+  async getReadableStorageForNamespace(namespace, principal) {
+    const resolved = this.resolveReadableNamespace(namespace, principal);
+    const storage = await this.orchestrator.getStorage(resolved);
+    return { namespace: resolved, storage };
+  }
+  async getWritableStorageForNamespace(namespace, principal) {
+    if (this.orchestrator.config.namespacesEnabled && !principal?.trim()) {
+      throw new EngramAccessInputError(
+        "authentication required: namespaces are enabled and no principal was supplied"
+      );
+    }
+    const resolved = this.resolveWritableNamespace(namespace, void 0, principal);
+    const storage = await this.orchestrator.getStorage(resolved);
+    return { namespace: resolved, storage };
+  }
+  get storageRef() {
+    return this.orchestrator.storage;
+  }
+  get configRef() {
+    return this.orchestrator.config;
+  }
+  get localLlmRef() {
+    return this.orchestrator.localLlm ?? null;
+  }
+  get fallbackLlmRef() {
+    return this.orchestrator.fastGatewayLlm ?? null;
+  }
+  get embeddingLookupFactoryRef() {
+    return (storage) => {
+      if (!this.orchestrator.config.embeddingFallbackEnabled) return void 0;
+      return async (content, limit) => {
+        try {
+          return await this.orchestrator.semanticDedupLookup(content, limit, storage);
+        } catch {
+          return [];
+        }
+      };
+    };
+  }
+  /**
+   * Import a capsule archive into the orchestrator's memory directory.
+   *
+   * Delegates directly to the standalone {@link importCapsuleFn} function.
+   * The `root` parameter defaults to the orchestrator's `memoryDir` when
+   * omitted, so callers that only have access to the service do not need to
+   * thread the config value through.
+   *
+   * `versioning` defaults to the orchestrator's page-versioning config so
+   * `mode: "overwrite"` automatically snapshots prior content without the
+   * caller having to construct the config object.
+   */
+  async capsuleImport(opts) {
+    const { namespace, principal, root: explicitRoot, memoryDir: explicitMemoryDir, ...importOptions } = opts;
+    const resolvedNamespace = this.resolveWritableNamespace(namespace, void 0, principal);
+    const storage = await this.orchestrator.getStorage(resolvedNamespace);
+    const root = explicitRoot ?? storage.dir;
+    const memoryDir = explicitMemoryDir ?? this.orchestrator.config.memoryDir;
+    const versioning = importOptions.versioning ?? {
+      enabled: this.orchestrator.config.versioningEnabled,
+      maxVersionsPerPage: this.orchestrator.config.versioningMaxPerPage,
+      sidecarDir: this.orchestrator.config.versioningSidecarDir
+    };
+    await this.validateCapsuleImportArchivePath(importOptions.archivePath);
+    try {
+      return await importCapsule({ ...importOptions, root, memoryDir, versioning });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      if (this.isCapsuleImportArchiveInputError(err, message)) {
+        throw new EngramAccessInputError(`capsule import failed: ${message}`);
+      }
+      throw err;
+    }
+  }
+  async validateCapsuleImportArchivePath(archivePath) {
+    let archiveStat;
+    try {
+      archiveStat = await stat(archivePath);
+    } catch (err) {
+      if (!this.isCapsuleImportPathInputFsError(err)) throw err;
+      const message = err instanceof Error ? err.message : String(err);
+      throw new EngramAccessInputError(`capsule import failed: archive is not readable: ${message}`);
+    }
+    if (!archiveStat.isFile()) {
+      throw new EngramAccessInputError("capsule import failed: archivePath must point to a file");
+    }
+    try {
+      await nodeFs.access(archivePath, fsConstants.R_OK);
+    } catch (err) {
+      if (!this.isCapsuleImportPathInputFsError(err)) throw err;
+      const message = err instanceof Error ? err.message : String(err);
+      throw new EngramAccessInputError(`capsule import failed: archive is not readable: ${message}`);
+    }
+  }
+  isCapsuleImportPathInputFsError(err) {
+    const code = typeof err === "object" && err !== null && "code" in err ? err.code : void 0;
+    return code === "ENOENT" || code === "ENOTDIR" || code === "EACCES" || code === "EPERM" || code === "ELOOP";
+  }
+  isCapsuleImportArchiveInputError(err, message) {
+    if (err instanceof ZodError) return true;
+    const code = typeof err === "object" && err !== null && "code" in err ? err.code : void 0;
+    if (typeof code === "string" && code.startsWith("Z_")) return true;
+    return message.startsWith("importCapsule: archive") || message.startsWith("importCapsule: bundle") || message.startsWith("importCapsule: manifest") || message.startsWith("importCapsule: record") || /incorrect header check|invalid stored block lengths|not in gzip format|unexpected end of file/i.test(message);
+  }
+  /**
+   * Export a capsule archive from the orchestrator's memory directory.
+   *
+   * HTTP and future MCP surfaces use this rather than calling the transfer
+   * helper directly so namespace ACL checks stay consistent with the archive
+   * write side effect. The exporter still owns archive construction and
+   * validation.
+   */
+  async capsuleExport(opts) {
+    const { namespace, principal, root: explicitRoot, memoryDir: explicitMemoryDir, ...exportOptions } = opts;
+    const resolvedNamespace = this.resolveWritableNamespace(namespace, void 0, principal);
+    const storage = await this.orchestrator.getStorage(resolvedNamespace);
+    const root = explicitRoot ?? storage.dir;
+    const memoryDir = explicitMemoryDir ?? this.orchestrator.config.memoryDir;
+    const pluginVersion = exportOptions.pluginVersion ?? await getPackageVersion();
+    return exportCapsule({
+      ...exportOptions,
+      pluginVersion,
+      root,
+      memoryDir: exportOptions.encrypt === true ? memoryDir : void 0
+    });
+  }
+  /**
+   * 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) {
+    const resolvedNamespace = this.resolveReadableNamespace(options?.namespace, options?.principal);
+    const storage = await this.orchestrator.getStorage(resolvedNamespace);
+    const capsulesDir = defaultCapsulesDir(storage.dir);
+    let dirEntries;
+    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.code : void 0;
+      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 = [];
+    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 = null;
+      let pluginVersion = null;
+      let fileCount = null;
+      let description = null;
+      let manifestPathOrNull = 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);
+        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;
+        description = capsule && typeof capsule.description === "string" ? capsule.description : null;
+      } catch (err) {
+        const code = typeof err === "object" && err !== null && "code" in err ? err.code : void 0;
+        if (code === "ENOENT") {
+          manifestPathOrNull = null;
+        }
+      }
+      capsules.push({
+        id,
+        archivePath,
+        manifestPath: manifestPathOrNull,
+        createdAt,
+        pluginVersion,
+        fileCount,
+        description
+      });
+    }
+    return { namespace: resolvedNamespace, capsulesDir, capsules };
+  }
+  // ── Dreams pipeline telemetry surfaces (issue #678 PR 3+4) ──────────────
+  /**
+   * Return per-phase Dreams telemetry for the last N hours (default 24).
+   */
+  async dreamsStatus(options) {
+    const { getDreamsStatus, normalizeDreamsStatusWindowHours } = await import("./dreams-ledger-LR2NBAZE.js");
+    let windowHours;
+    try {
+      windowHours = normalizeDreamsStatusWindowHours(options?.windowHours);
+    } catch (error) {
+      throw new EngramAccessInputError(error instanceof Error ? error.message : String(error));
+    }
+    const resolvedNamespace = this.resolveReadableNamespace(options?.namespace, options?.principal);
+    const storage = await this.orchestrator.getStorage(resolvedNamespace);
+    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) {
+    const { runDreamsPhase } = await import("./dreams-ledger-LR2NBAZE.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.resolveWritableNamespace(
+      options.namespace,
+      void 0,
+      options.authenticatedPrincipal
+    );
+    const storage = await this.orchestrator.getStorage(resolvedNamespace);
+    const memoryDir = storage.dir;
+    const phaseRunner = dryRun || options.phase === "deepSleep" ? void 0 : async (_opts) => {
+      if (_opts.phase === "lightSleep") {
+        const result3 = await this.orchestrator.runLifecyclePolicyNow(storage);
+        return {
+          itemsProcessed: result3.memoriesAssessed,
+          notes: `scored ${result3.memoriesAssessed} memories`
+        };
+      }
+      const result2 = await this.orchestrator.runSemanticConsolidationNow({
+        dryRun: false,
+        storage
+      });
+      const itemsProcessed = result2.clusters.reduce(
+        (sum, cluster) => sum + cluster.memories.length,
+        0
+      );
+      return {
+        itemsProcessed,
+        notes: `REM consolidation found ${result2.clustersFound} clusters`
+      };
+    };
+    const governanceRunner = options.phase === "deepSleep" ? async (_opts) => {
+      return this.orchestrator.runDeepSleepGovernanceNow({
+        storage,
+        dryRun: _opts.dryRun
+      });
+    } : void 0;
+    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
+    };
+  }
+};
+
+export {
+  computeProcedureStats,
+  formatProcedureStatsText,
+  EngramAccessInputError,
+  ENGRAM_ACCESS_WRITE_SCHEMA_VERSION,
+  shapeMemorySummary,
+  EngramAccessService
+};
+//# sourceMappingURL=chunk-M23FSH32.js.map