@remnic/core 1.0.3 → 1.1.1

package/dist/{chunk-V7XCAHIB.js → chunk-GKFXUTJ2.js}

@@ -1,3 +1,14 @@
+import {
+  toRecallExplainJson
+} from "./chunk-ZAIM4TUE.js";
+import {
+  buildProposedActions,
+  buildQualityScore,
+  groupActionsByStatus,
+  listMemoryGovernanceRuns,
+  readMemoryGovernanceRunArtifact,
+  runMemoryGovernance
+} from "./chunk-3OGMS3PE.js";
 import {
   getTrustZoneStoreStatus,
   isTrustZoneName,
@@ -8,18 +19,8 @@ import {
   summarizeTrustZonePromotionReadiness
 } from "./chunk-EQINRHYR.js";
 import {
-  buildProposedActions,
-  buildQualityScore,
-  groupActionsByStatus,
-  listMemoryGovernanceRuns,
-  readMemoryGovernanceRunArtifact,
-  runMemoryGovernance
-} from "./chunk-POBPGDWI.js";
-import {
-  persistExplicitCapture,
-  queueExplicitCaptureForReview,
-  validateExplicitCaptureInput
-} from "./chunk-QDYXG4CS.js";
+  recordMemoryOutcome
+} from "./chunk-EIR5VLIH.js";
 import {
   wrapWorkLayerContext
 } from "./chunk-EEQLFRUM.js";
@@ -27,23 +28,34 @@ import {
   buildProcedurePersistBody,
   normalizeProcedureSteps
 } from "./chunk-QDW3E4RD.js";
+import {
+  persistExplicitCapture,
+  queueExplicitCaptureForReview,
+  validateExplicitCaptureInput
+} from "./chunk-3FPTCC3Z.js";
+import {
+  CrossNamespaceBudget
+} from "./chunk-GDFS42HT.js";
 import {
   filterTrajectoriesByLookbackDays,
   readCausalTrajectoryRecords
-} from "./chunk-4NRAJUDS.js";
+} from "./chunk-RBBWYEFJ.js";
 import {
-  AccessIdempotencyStore,
-  hashAccessIdempotencyPayload
-} from "./chunk-XKECPATV.js";
+  canReadNamespace,
+  canWriteNamespace,
+  defaultNamespaceForPrincipal,
+  recallNamespacesForPrincipal,
+  resolvePrincipal
+} from "./chunk-N5AKDXAI.js";
 import {
   FileCalendarSource,
   buildBriefing,
   parseBriefingFocus,
   parseBriefingWindow
-} from "./chunk-ECKDIK5F.js";
+} from "./chunk-WVVA7F5A.js";
 import {
   parseEntityFile
-} from "./chunk-POMSFKTB.js";
+} from "./chunk-F5VP6YCB.js";
 import {
   inferMemoryStatus,
   toMemoryPathRel
@@ -59,10 +71,12 @@ import {
   log
 } from "./chunk-2ODBA7MQ.js";
 import {
-  canReadNamespace,
-  canWriteNamespace,
-  resolvePrincipal
-} from "./chunk-N5AKDXAI.js";
+  AccessAuditAdapter
+} from "./chunk-TVVEYCNW.js";
+import {
+  AccessIdempotencyStore,
+  hashAccessIdempotencyPayload
+} from "./chunk-XKECPATV.js";
 
 // src/access-service.ts
 import { stat } from "fs/promises";
@@ -677,6 +691,7 @@ async function importWorkBoardSnapshot(options) {
 }
 
 // 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();
@@ -709,11 +724,12 @@ function pseudoStepsFromCluster(group) {
   }));
 }
 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 === cluster) return true;
+    if (c === clusterKey2) return true;
   }
   return false;
 }
@@ -725,8 +741,10 @@ async function runProcedureMining(options) {
   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
+    memoryDir: options.memoryDir,
+    causalTrajectoryStoreDir: trajectoryDir
   });
   const recent = filterTrajectoriesByLookbackDays(trajectories, cfg.lookbackDays);
   const clusters = /* @__PURE__ */ new Map();
@@ -757,7 +775,7 @@ async function runProcedureMining(options) {
       status: promote ? "active" : "pending_review",
       tags: ["procedure-miner", "causal-trajectory"],
       structuredAttributes: {
-        procedure_cluster: key.slice(0, 500),
+        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)
@@ -768,6 +786,125 @@ async function runProcedureMining(options) {
   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
 var EngramAccessInputError = class extends Error {
 };
@@ -887,10 +1024,39 @@ 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();
+  budget;
+  auditAdapter;
   get briefingEnabled() {
     return this.orchestrator.config.briefing?.enabled === true;
   }
@@ -1143,14 +1309,117 @@ var EngramAccessService = class {
       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
+    });
+  }
   async recall(request) {
     const query = request.query.trim();
     if (query.length === 0) {
       throw new EngramAccessInputError("query is required");
     }
+    if (request.codingContext !== void 0 && request.sessionKey) {
+      this.setCodingContext({
+        sessionKey: request.sessionKey,
+        codingContext: request.codingContext
+      });
+    }
     const namespaceOverride = this.resolveRecallNamespace(request.namespace, request.sessionKey);
     const namespace = namespaceOverride ?? this.orchestrator.config.defaultNamespace;
     const mode = this.normalizeRecallMode(request.mode);
+    const principal = resolvePrincipal(request.sessionKey, this.orchestrator.config);
+    const principalNamespace = defaultNamespaceForPrincipal(principal, this.orchestrator.config);
+    const modeSkipsBudget = mode === "no_recall";
+    const effectiveNamespaces = namespaceOverride ? [namespaceOverride] : recallNamespacesForPrincipal(principal, this.orchestrator.config);
+    let budgetDecision;
+    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;
+      for (const ns of effectiveNamespaces) {
+        const peek = this.budget.peek({
+          principal,
+          principalNamespace,
+          queryNamespace: ns
+        });
+        if (peek.reason !== "allowed-same-namespace") {
+          anyCrossNamespace = true;
+        }
+        if (!peek.allowed) {
+          denied = peek;
+          break;
+        }
+      }
+      if (denied) {
+        budgetDecision = denied;
+      } else if (anyCrossNamespace) {
+        budgetDecision = this.budget.record(principal);
+      } 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;
     const recallOptions = {
       namespace: namespaceOverride,
@@ -1168,6 +1437,36 @@ var EngramAccessService = class {
       request.includeDebug === true,
       request.sessionKey
     );
+    let auditAnomalies;
+    if (this.auditAdapter) {
+      try {
+        const resolvedAgentId = resolvePrincipal(
+          request.sessionKey,
+          this.orchestrator.config
+        );
+        const auditEntry = {
+          ts: (/* @__PURE__ */ new Date()).toISOString(),
+          sessionKey: request.sessionKey ?? "",
+          agentId: resolvedAgentId,
+          trigger: "access-surface",
+          queryText: query,
+          candidateMemoryIds: snapshot?.memoryIds ?? [],
+          summary: context.slice(0, 200) || null,
+          injectedChars: context.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 {
       query,
       sessionKey: request.sessionKey,
@@ -1182,6 +1481,8 @@ var EngramAccessService = class {
       fallbackUsed: snapshot?.fallbackUsed ?? false,
       sourcesUsed: snapshot?.sourcesUsed ?? [],
       budgetsApplied: snapshot?.budgetsApplied,
+      auditAnomalies,
+      budgetWarning: budgetDecision.reason === "warn-over-soft" ? budgetDecision : void 0,
       latencyMs: snapshot?.latencyMs ?? Date.now() - startedAt,
       debug
     };
@@ -1213,6 +1514,108 @@ var EngramAccessService = class {
     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");
+    }
+    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 previousQueue = this.xrayQueue;
+    let release = () => {
+    };
+    this.xrayQueue = new Promise((resolve) => {
+      release = resolve;
+    });
+    await previousQueue;
+    try {
+      this.orchestrator.clearLastXraySnapshot();
+      await this.orchestrator.recall(query, request.sessionKey?.trim() || void 0, {
+        xrayCapture: true,
+        ...requestedNamespace ? { namespace: requestedNamespace } : {},
+        ...budgetOverride !== void 0 ? { budgetCharsOverride: budgetOverride } : {},
+        // 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 } : {}
+      });
+      const snapshot = this.orchestrator.getLastXraySnapshot();
+      if (!snapshot) return { snapshotFound: false };
+      if (requestedNamespace && snapshot.namespace !== requestedNamespace) {
+        return { snapshotFound: false };
+      }
+      return { snapshotFound: true, snapshot };
+    } finally {
+      release();
+    }
+  }
+  // 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,
@@ -1727,6 +2130,23 @@ var EngramAccessService = class {
       skippedReason: result.skippedReason
     };
   }
+  /**
+   * 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 trustZoneStatus(namespace, principal) {
     const resolvedNamespace = this.resolveReadableNamespace(namespace, principal);
     const storage = await this.orchestrator.getStorage(resolvedNamespace);
@@ -2529,6 +2949,38 @@ ${next}`);
     );
     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);
@@ -2607,12 +3059,42 @@ ${next}`);
     }
     return { submitted: memoryIds.length, matched: matchedIds.length };
   }
+  // ── Contradiction Review (issue #520) ──────────────────────────────────────
+  get memoryDir() {
+    return this.orchestrator.config.memoryDir;
+  }
+  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 [];
+        }
+      };
+    };
+  }
 };
 
 export {
   WorkStorage,
+  computeProcedureStats,
+  formatProcedureStatsText,
   EngramAccessInputError,
   ENGRAM_ACCESS_WRITE_SCHEMA_VERSION,
   EngramAccessService
 };
-//# sourceMappingURL=chunk-V7XCAHIB.js.map
+//# sourceMappingURL=chunk-GKFXUTJ2.js.map