@remnic/core 9.65.1 → 9.65.3

package/src/access-boundary.ts

@@ -68,6 +68,7 @@ export const OPERATION_NAMES = [
   "recall_tier_explain",
   "recall_xray",
   "who_knows",
+  "promotion_candidates",
   "namespace_writable",
   "wearables_status",
   "wearables_sync",
@@ -88,6 +89,7 @@ export const OPERATION_NAMES = [
   "procedure_mining_run",
   "pattern_reinforcement_run",
   "procedural_stats",
+  "procedure_library_maintenance",
   "memory_timeline",
   "suggestion_submit",
   "entity_get",
@@ -138,6 +140,7 @@ export const OPERATION_NAMES = [
   "review_list",
   "review_resolve",
   "contradiction_scan_run",
+  "preference_drift_scan",
   "memory_summarize_hourly",
   "conversation_index_update",
   "profiling_report",
@@ -182,6 +185,9 @@ export const OPERATION_NAMES = [
   "trust_zones_status",
   "trust_zones_records",
   "review_disposition",
+  "review_deck_list",
+  "review_deck_action",
+  "review_deck_undo",
   "trust_zones_promote",
   "trust_zones_demo_seed",
   "citations_observed",

package/src/access-http.ts

@@ -68,7 +68,7 @@ import { cleanupExpiredChatSessions, enforceChatSessionNamespace } from "./chat/
 import { isDefaultReviewNamespace, listPairs, readPair } from "./contradiction/contradiction-review.js";
 import { isValidResolutionVerb, executeResolution } from "./contradiction/resolution.js";
 import { RelayMissionStoreError } from "./relay/mission.js";
-import { SupportPassportAccessHttpBase } from "./support-passport/access-http-base.js";
+import { ReviewDeckAccessHttpBase } from "./review/review-deck-http-base.js";
 import { serializeInlineScriptValue } from "./inline-script.js";
 import type { SupportPassportExternalRequestHandler } from "./support-passport/public-http.js";
 export interface AccessHttpReadinessState {
@@ -386,7 +386,7 @@ function codingContextFromProjectTag(projectTag: string): {
   };
 }
 
-export class EngramAccessHttpServer extends SupportPassportAccessHttpBase {
+export class EngramAccessHttpServer extends ReviewDeckAccessHttpBase {
   protected readonly service: EngramAccessService;
   private readonly host: string;
   private readonly requestedPort: number;
@@ -396,7 +396,7 @@ export class EngramAccessHttpServer extends SupportPassportAccessHttpBase {
   private readonly authTokenEntriesGetter?: () => ReadonlyArray<{ token: string; connector?: string; capabilities?: TokenCapabilities }>;
   private readonly tokenPathPolicy?: (connector: string, pathname: string | undefined) => boolean;
   private readonly authenticatedPrincipal?: string;
-  private readonly maxBodyBytes: number;
+  protected readonly maxBodyBytes: number;
   private readonly adminConsoleEnabled: boolean;
   protected readonly adminConsolePublicDir: string;
   private readonly adminConsolePrefillToken?: string;
@@ -730,7 +730,7 @@ export class EngramAccessHttpServer extends SupportPassportAccessHttpBase {
   /** Resolve namespace: only use the explicit body value. Adapter-inferred namespace
    *  is intentionally NOT used as a fallback for REST requests — omitting namespace
    *  should default to the server's global namespace, not silently scope to an adapter. */
-  private resolveNamespace(_req: IncomingMessage, bodyNamespace?: string): string | undefined {
+  protected resolveNamespace(_req: IncomingMessage, bodyNamespace?: string): string | undefined {
     const namespace = bodyNamespace || undefined;
     // Per-token namespace enforcement (issues #1837/#1850): every HTTP
     // namespace-scoped route routes through this helper so none can dodge the
@@ -901,6 +901,7 @@ export class EngramAccessHttpServer extends SupportPassportAccessHttpBase {
     if (req.method === "POST" && pathname === "/mcp") return this.handleMcpRequest(req, res, abortSignal);
 
     if (await this.handleSupportPassportOwnerRequest(req, res, pathname, parsed.search.length > 0, abortSignal)) return;
+    if (await this.handleReviewDeckRequest(req, res, pathname, abortSignal)) return;
 
     if (req.method === "GET" && pathname === "/engram/v1/live") return this.respondJson(res, 200, { ok: true, ready: true });
     if (req.method === "GET" && pathname === "/engram/v1/health") {
@@ -3906,7 +3907,7 @@ export class EngramAccessHttpServer extends SupportPassportAccessHttpBase {
    * pass. Throws {@link EngramAccessForbiddenError} (→ 403) when a scoped
    * token calls a non-permitted op (issue #1837).
    */
-  private enforceTokenOp(op: OperationName): void {
+  protected enforceTokenOp(op: OperationName): void {
     void getOperation(op); // preserve the registration side-effect assertion
     assertOperationAllowed(tokenCapabilityStore.getStore(), op);
   }

package/src/access-mcp-admin-tools.ts

@@ -168,4 +168,42 @@ export const MCP_ADMIN_OPS_TOOLS: Array<{
     additionalProperties: false,
   },
 },
+{
+  name: "engram.procedure_library_maintenance",
+  description:
+    "Run procedure library health maintenance (issue #2370): merge near-duplicate active procedures, flag stale-tool procedures for repair, and retire failure-dominant or idle ones — from Memory Worth + trajectory telemetry. Shadow-first: default run writes nothing and returns a proposed-transition report. apply=true (and procedural.maintenance.enabled) executes transitions; dryRun=true forces shadow.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      namespace: { type: "string" },
+      apply: { type: "boolean" },
+      dryRun: { type: "boolean" },
+    },
+    additionalProperties: false,
+  },
+},
+{
+  name: "engram.preference_drift_scan",
+  description:
+    "Run a preference drift scan (issue #2371): classify aging preference memories as corroborated / stale / drifted from recent same-namespace evidence. Shadow-first — the default run reports only. apply=true (and driftDetection.enabled) stamps lastCorroborated / driftState and opens one review item per drifted preference. Never auto-deletes and never auto-supersedes.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      namespace: { type: "string" },
+      apply: { type: "boolean" },
+    },
+    additionalProperties: false,
+  },
+},
 ];
+
+/**
+ * Tool-name → operation-name entries contributed by this module, spread into
+ * `MCP_MIGRATED_OPERATIONS` in access-mcp.ts. Declared here (rather than
+ * inline in the transport) for the same structural-ratchet reason the tool
+ * table above lives here. `remnic.*` aliases resolve by suffix, so only the
+ * `engram.*` name is listed.
+ */
+export const MCP_ADMIN_OPS_MIGRATED_OPERATIONS: Readonly<Record<string, string>> = {
+  "engram.preference_drift_scan": "preference_drift_scan",
+};

package/src/access-mcp-output-schemas.ts

@@ -55,6 +55,7 @@ const TOOL_OUTPUT_SCHEMAS: Readonly<Record<string, Record<string, unknown>>> = {
   recall_tier_explain: objectSchema({ snapshotFound: T_BOOLEAN, tierExplain: T_NULLABLE_OBJECT }),
   recall_xray: objectSchema({ snapshotFound: T_BOOLEAN, snapshot: T_OBJECT }),
   who_knows: objectSchema({ topic: T_STRING, results: T_ARRAY }),
+  promotion_candidates: objectSchema({ namespace: T_STRING, targetNamespace: T_STRING, candidates: T_ARRAY }),
   set_coding_context: objectSchema({ ok: T_BOOLEAN }),
   wearables_status: objectSchema({
     enabled: T_BOOLEAN,
@@ -132,6 +133,11 @@ const TOOL_OUTPUT_SCHEMAS: Readonly<Record<string, Record<string, unknown>>> = {
     duplicatesSuperseded: T_NUMBER,
   }),
   procedural_stats: objectSchema({ namespace: T_STRING, counts: T_OBJECT, recent: T_OBJECT }),
+  procedure_library_maintenance: objectSchema({
+    enabled: T_BOOLEAN,
+    namespace: T_STRING,
+    report: T_OBJECT,
+  }),
   memory_get: objectSchema({ found: T_BOOLEAN, namespace: T_STRING, memory: T_NULLABLE_OBJECT }),
   memory_timeline: objectSchema({ found: T_BOOLEAN, namespace: T_STRING, count: T_NUMBER, timeline: T_ARRAY }),
   memory_store: objectSchema({
@@ -381,6 +387,20 @@ const TOOL_OUTPUT_SCHEMAS: Readonly<Record<string, Record<string, unknown>>> = {
     cooledDown: T_NUMBER,
     elapsedMs: T_NUMBER,
   }),
+  preference_drift_scan: objectSchema({
+    schemaVersion: T_NUMBER,
+    generatedAt: T_STRING,
+    mode: T_STRING,
+    namespace: T_STRING,
+    scanned: T_NUMBER,
+    eligible: T_NUMBER,
+    findings: T_ARRAY,
+    counts: T_OBJECT,
+    appliedCount: T_NUMBER,
+    reviewItemsOpened: T_NUMBER,
+    elapsedMs: T_NUMBER,
+    skippedReason: T_STRING,
+  }),
   memory_summarize_hourly: objectSchema({ ok: T_BOOLEAN, message: T_STRING }),
   conversation_index_update: objectSchema({
     enabled: T_BOOLEAN,

package/src/access-mcp.ts

@@ -1,6 +1,6 @@
 import { randomUUID } from "node:crypto";
 import {
-  MCP_ADMIN_OPS_TOOLS,
+  MCP_ADMIN_OPS_MIGRATED_OPERATIONS, MCP_ADMIN_OPS_TOOLS,
   MCP_GIT_CONTEXT_SCHEMA_PROPS_IGNORED,
 } from "./access-mcp-admin-tools.js";
 import { readFile } from "node:fs/promises";
@@ -46,6 +46,7 @@ import { MCP_READ_ONLY_TOOL_SUFFIXES } from "./mcp-read-only-tools.js";
 import { MEETINGS_MCP_TOOLS } from "./meetings/mcp-tools.js";
 import { WEARABLES_MCP_TOOLS } from "./wearables/mcp-tools.js";
 import { WHO_KNOWS_MCP_TOOLS } from "./who-knows.js";
+import { PROMOTION_CANDIDATES_MCP_TOOLS } from "./memory-subject.js";
 import { EXTERNAL_WIKI_MCP_TOOLS } from "./external-wiki-mcp-tools.js";
 import { abortError, isAbortError } from "./abort-error.js";
 import { SUPPORT_PASSPORT_MCP_MIGRATED_OPERATIONS, SUPPORT_PASSPORT_MCP_TOOLS } from "./support-passport/mcp-tools.js";
@@ -156,7 +157,7 @@ function withToolAliases(tool: McpTool, emitLegacyTools = true): McpTool[] {
   return emitLegacyTools ? [canonicalTool, tool] : [canonicalTool];
 }
 
-const MCP_MIGRATED_OPERATIONS: Readonly<Record<string, OperationName>> = {
+export const MCP_MIGRATED_OPERATIONS: Readonly<Record<string, OperationName>> = {
   "engram.memory_get": "memory_get",
   "engram.memory_search": "memory_search",
   "engram.external_wiki_search": "external_wiki_search",
@@ -185,9 +186,8 @@ const MCP_MIGRATED_OPERATIONS: Readonly<Record<string, OperationName>> = {
   // Fully migrated through the strict-schema boundary (#1668).
   "engram.recall": "recall",
   "engram.recall_explain": "recall_explain",
-  "engram.set_coding_context": "set_coding_context",
-  "engram.recall_tier_explain": "recall_tier_explain",
-  "engram.recall_xray": "recall_xray", "engram.who_knows": "who_knows",
+  "engram.set_coding_context": "set_coding_context", "engram.recall_tier_explain": "recall_tier_explain",
+  "engram.recall_xray": "recall_xray", "engram.who_knows": "who_knows", "engram.promotion_candidates": "promotion_candidates",
   "engram.wearables_status": "wearables_status",
   "engram.wearables_sync": "wearables_sync",
   "engram.transcript_day": "transcript_day",
@@ -203,7 +203,7 @@ const MCP_MIGRATED_OPERATIONS: Readonly<Record<string, OperationName>> = {
   "engram.entity_synthesis_run": "entity_synthesis_run",
   "engram.procedure_mining_run": "procedure_mining_run",
   "engram.pattern_reinforcement_run": "pattern_reinforcement_run",
-  "engram.procedural_stats": "procedural_stats",
+  "engram.procedural_stats": "procedural_stats", "engram.procedure_library_maintenance": "procedure_library_maintenance",
   "engram.memory_timeline": "memory_timeline",
   "engram.suggestion_submit": "suggestion_submit",
   "engram.entity_get": "entity_get",
@@ -265,7 +265,7 @@ const MCP_MIGRATED_OPERATIONS: Readonly<Record<string, OperationName>> = {
   "engram.console_state": "console_state",
   "engram.dreams_status": "dreams_status",
   "engram.dreams_run": "dreams_run",
-  ...SUPPORT_PASSPORT_MCP_MIGRATED_OPERATIONS,
+  ...SUPPORT_PASSPORT_MCP_MIGRATED_OPERATIONS, ...MCP_ADMIN_OPS_MIGRATED_OPERATIONS,
   "engram.memory_chat": "chat_message",
 };
 
@@ -706,7 +706,7 @@ export class EngramMcpServer {
           additionalProperties: false,
         },
       },
-      ...WEARABLES_MCP_TOOLS, ...MEETINGS_MCP_TOOLS, ...WHO_KNOWS_MCP_TOOLS,
+      ...WEARABLES_MCP_TOOLS, ...MEETINGS_MCP_TOOLS, ...WHO_KNOWS_MCP_TOOLS, ...PROMOTION_CANDIDATES_MCP_TOOLS,
       ...(service.supportPassportEnabled ? SUPPORT_PASSPORT_MCP_TOOLS : []),
       {
         name: "engram.action_confidence",

package/src/access-operations-batch.ts

@@ -35,6 +35,7 @@ import {
 import { listPairs, isDefaultReviewNamespace, readPair } from "./contradiction/contradiction-review.js";
 import { executeResolution, isValidResolutionVerb } from "./contradiction/resolution.js";
 import { runContradictionScan } from "./contradiction/contradiction-scan.js";
+import { runPreferenceDriftScan } from "./preferences/preference-drift.js";
 import { runGraphEdgeDecayMaintenanceAcrossNamespaces } from "./maintenance/graph-edge-decay.js";
 import { normalizeDreamsStatusWindowHours } from "./maintenance/dreams-ledger.js";
 
@@ -147,6 +148,13 @@ defineOperation({ name: "who_knows", description: "Rank entities by demonstrated
     return { result: await ctx.service.whoKnows({ topic, ...(limit !== undefined ? { limit } : {}), namespace: optStr(input.namespace), authenticatedPrincipal: ctx.authenticatedPrincipal }) };
   },
 });
+defineOperation({ name: "promotion_candidates", description: "List agent-subject reuse-signaled promotion candidates (#2372).", schema: strictSchema({ namespace: S.str, targetNamespace: S.str, limit: S.flexNum }),
+  handler: async (input, ctx) => {
+    let limit: number | undefined;
+    if (input.limit !== undefined) { const p = typeof input.limit === "number" ? input.limit : Number(input.limit); if (!Number.isInteger(p) || p < 1 || p > 100) throw new EngramAccessInputError("promotion_candidates: limit expects an integer in [1, 100]"); limit = p; }
+    return { result: await ctx.service.promotionCandidates({ ...(limit !== undefined ? { limit } : {}), namespace: optStr(input.namespace), targetNamespace: optStr(input.targetNamespace), authenticatedPrincipal: ctx.authenticatedPrincipal }) };
+  },
+});
 defineOperation({ name: "namespace_writable", description: "Read-only preflight: is a namespace writable for the caller's principal?", allowedByOps: ["namespace_writable", "observe", "memory_store"], schema: strictSchema({ namespace: S.str, sessionKey: S.str, op: S.str, cwd: S.str, projectTag: S.str }), handler: async (input, ctx) => {
   const writeOp = parseNamespacePreflightWriteOp(optStr(input.op));
   const namespace = optStr(input.namespace);
@@ -213,6 +221,7 @@ defineOperation({ name: "entity_synthesis_run", description: "Bulk-drain the ent
 defineOperation({ name: "procedure_mining_run", description: "Run procedure mining.", schema: strictSchema({ namespace: S.str }), handler: async (input, ctx) => ({ result: await ctx.service.procedureMiningRun({ namespace: optStr(input.namespace), authenticatedPrincipal: ctx.authenticatedPrincipal }, ctx.authenticatedPrincipal) }) });
 defineOperation({ name: "pattern_reinforcement_run", description: "Run pattern reinforcement.", schema: strictSchema({ namespace: S.str, force: S.bool }), handler: async (input, ctx) => ({ result: await ctx.service.patternReinforcementRun({ namespace: optStr(input.namespace), force: input.force === true, authenticatedPrincipal: ctx.authenticatedPrincipal }, ctx.authenticatedPrincipal) }) });
 defineOperation({ name: "procedural_stats", description: "Procedural stats.", schema: strictSchema({ namespace: S.str }), handler: async (input, ctx) => ({ result: await ctx.service.procedureStats({ namespace: optStr(input.namespace) }, ctx.authenticatedPrincipal) }) });
+defineOperation({ name: "procedure_library_maintenance", description: "Run procedure library maintenance (issue #2370): shadow-first merge / repair-flag / retire from outcome telemetry. apply=true plus procedural.maintenance.enabled required for writes.", schema: strictSchema({ namespace: S.str, apply: S.bool, dryRun: S.bool }), handler: async (input, ctx) => ({ result: await ctx.service.procedureLibraryMaintenance({ namespace: optStr(input.namespace), apply: input.apply === true, dryRun: input.dryRun === true, authenticatedPrincipal: ctx.authenticatedPrincipal }, ctx.authenticatedPrincipal) }) });
 
 // === MEMORY/ENTITY/OBSERVE/LCM ===
 defineOperation({ name: "memory_timeline", description: "Memory timeline.", schema: strictSchema({ memoryId: S.str, namespace: S.str, limit: S.num }), handler: async (input, ctx) => ({ result: await ctx.service.memoryTimeline(optStr(input.memoryId) ?? "", optStr(input.namespace), optNum(input.limit) ?? 200, ctx.authenticatedPrincipal) }) });
@@ -339,6 +348,7 @@ defineOperation({ name: "review_resolve", description: "Resolve pair.", schema:
   },
 });
 defineOperation({ name: "contradiction_scan_run", description: "Run scan.", schema: strictSchema({ namespace: S.str }), handler: async (input, ctx) => ({ result: await runContradictionScan({ storage: ctx.service.storageRef, config: ctx.service.configRef, memoryDir: ctx.service.memoryDir, embeddingLookupFactory: ctx.service.embeddingLookupFactoryRef, storageForNamespace: (ns) => ctx.service.getWritableStorageForNamespace(ns ?? undefined, ctx.authenticatedPrincipal), localLlm: ctx.service.localLlmRef, fallbackLlm: ctx.service.fallbackLlmRef, namespace: optStr(input.namespace) }) }) });
+defineOperation({ name: "preference_drift_scan", description: "Run preference drift scan.", schema: strictSchema({ namespace: S.str, apply: S.bool }), handler: async (input, ctx) => ({ result: await runPreferenceDriftScan({ storage: ctx.service.storageRef, config: ctx.service.configRef, memoryDir: ctx.service.memoryDir, embeddingLookupFactory: ctx.service.embeddingLookupFactoryRef, storageForNamespace: (ns) => ctx.service.getWritableStorageForNamespace(ns ?? undefined, ctx.authenticatedPrincipal), localLlm: ctx.service.localLlmRef, fallbackLlm: ctx.service.fallbackLlmRef, namespace: optStr(input.namespace), apply: input.apply === true }) }) });
 defineOperation({ name: "graph_edge_decay_run", description: "Run edge decay.", fleetWide: true, schema: strictSchema({ dryRun: S.bool }), handler: async (input, ctx) => { const cfg = ctx.service.configRef; if (!cfg.graphEdgeDecayEnabled) return { result: { ranAt: new Date().toISOString(), disabled: true, reason: "graphEdgeDecayEnabled is false" } }; return { result: { results: await runGraphEdgeDecayMaintenanceAcrossNamespaces(ctx.service.memoryDir, { windowMs: cfg.graphEdgeDecayWindowMs, perWindow: cfg.graphEdgeDecayPerWindow, floor: cfg.graphEdgeDecayFloor, visibilityThreshold: cfg.graphEdgeDecayVisibilityThreshold, dryRun: input.dryRun === true, namespacesEnabled: cfg.namespacesEnabled === true, defaultNamespace: cfg.defaultNamespace }) } }; } });
 
 // === SUMMARIZE/PROFILING/PEERS/CONSOLE/DREAMS ===
@@ -389,6 +399,9 @@ defineOperation({ name: "quality_status", description: "Quality status.", schema
 defineOperation({ name: "trust_zones_status", description: "Trust-zone status.", schema: strictSchema({}), handler: async (_i, ctx) => ({ result: await ctx.service.trustZoneStatus() }) });
 defineOperation({ name: "trust_zones_records", description: "Browse trust-zone records.", schema: strictSchema({ namespace: S.str, limit: S.num, offset: S.num }), handler: async (input, ctx) => ({ result: await ctx.service.trustZoneBrowse({ namespace: optStr(input.namespace), limit: optNum(input.limit), offset: optNum(input.offset) }, ctx.authenticatedPrincipal) }) });
 defineOperation({ name: "review_disposition", description: "Review disposition.", schema: strictSchema({ memoryId: S.str, status: S.str, reasonCode: S.str, namespace: S.str }), handler: async (input, ctx) => ({ result: await ctx.service.reviewDisposition({ memoryId: optStr(input.memoryId) ?? "", status: (optStr(input.status) ?? "archived") as never, reasonCode: optStr(input.reasonCode) ?? "", namespace: optStr(input.namespace), authenticatedPrincipal: ctx.authenticatedPrincipal }) }) });
+defineOperation({ name: "review_deck_list", description: "List review deck.", schema: strictSchema({ namespace: S.str, cursor: S.str, limit: S.num }), handler: async (input, ctx) => ({ result: await ctx.service.reviewDeckList({ namespace: optStr(input.namespace), principal: ctx.authenticatedPrincipal, cursor: optStr(input.cursor), limit: optNum(input.limit) ?? 1 }) }) });
+defineOperation({ name: "review_deck_action", description: "Apply review deck action.", schema: strictSchema({ itemId: S.str, revision: S.str, action: S.str, correctionText: S.str, idempotencyKey: S.str }), handler: async (input, ctx) => ({ result: await ctx.service.reviewDeckAction({ schemaVersion: 1, itemId: reqStr(input.itemId, "itemId"), revision: reqStr(input.revision, "revision"), action: reqStr(input.action, "action") as "keep", idempotencyKey: reqStr(input.idempotencyKey, "idempotencyKey"), ...(optStr(input.correctionText) ? { correctionText: optStr(input.correctionText)! } : {}) } as never, { principal: ctx.authenticatedPrincipal, signal: ctx.abortSignal }) }) });
+defineOperation({ name: "review_deck_undo", description: "Undo review deck action.", schema: strictSchema({ receiptId: S.str, expectedRevision: S.str, idempotencyKey: S.str }), handler: async (input, ctx) => ({ result: await ctx.service.reviewDeckUndo({ schemaVersion: 1, receiptId: reqStr(input.receiptId, "receiptId"), expectedRevision: reqStr(input.expectedRevision, "expectedRevision"), idempotencyKey: reqStr(input.idempotencyKey, "idempotencyKey") }, { principal: ctx.authenticatedPrincipal, signal: ctx.abortSignal }) }) });
 defineOperation({ name: "trust_zones_promote", description: "Promote trust-zone.", schema: strictSchema({ recordId: S.str, targetZone: S.str, promotionReason: S.str, dryRun: S.bool, namespace: S.str }), handler: async (input, ctx) => ({ result: await ctx.service.trustZonePromote({ recordId: optStr(input.recordId) ?? "", targetZone: (optStr(input.targetZone) ?? "working") as never, promotionReason: optStr(input.promotionReason) ?? "", dryRun: input.dryRun === true, namespace: optStr(input.namespace), authenticatedPrincipal: ctx.authenticatedPrincipal }) }) });
 defineOperation({ name: "trust_zones_demo_seed", description: "Demo seed.", schema: strictSchema({ scenario: S.str, dryRun: S.bool, namespace: S.str }), handler: async (input, ctx) => ({ result: await ctx.service.trustZoneDemoSeed({ scenario: optStr(input.scenario), dryRun: input.dryRun === true, namespace: optStr(input.namespace), authenticatedPrincipal: ctx.authenticatedPrincipal }) }) });
 defineOperation({ name: "citations_observed", description: "Record citations.", schema: strictSchema({}), handler: async (_i, _ctx) => ({ result: { ok: true } }) });

package/src/access-service.ts

@@ -201,6 +201,10 @@ import type {
   RecallInvocationOptions,
 } from "./orchestrator.js";
 import { type ProcedureStatsReport, computeProcedureStats } from "./procedural/procedure-stats.js";
+import {
+  runProcedureLibraryMaintenance,
+  type ProcedureLibraryMaintenanceReport,
+} from "./procedural/library-maintenance.js";
 import type { RecallContextComposition } from "./recall-context-composition.js";
 import type { LastRecallSnapshot } from "./recall-state.js";
 import {
@@ -299,12 +303,14 @@ import {
   readOfflineSyncFileContentChunk,
 } from "./offline-sync.js";
 import { selfDeps } from "./orchestration/self-deps.js";
+import { ReviewDeckSurface } from "./review/review-deck-surface.js";
 import { formatProfileTraceAscii } from "./profiling.js";
 import { decideDisclosureEscalation } from "./recall-disclosure-escalation.js";
 import { toRecallExplainJson } from "./recall-explain-renderer.js";
 import { type TagMatchMode, applyTagFilter, normalizeTags, parseTagMatch } from "./recall-tag-filter.js";
 import { type RecallXraySnapshot, estimateRecallTokens } from "./recall-xray.js";
 import { computeWhoKnows, loadWhoKnowsEntities, validateWhoKnowsInput, WHO_KNOWS_DEFAULT_LIMIT, type WhoKnowsResult } from "./who-knows.js";
+import { computePromotionCandidates, type PromotionCandidatesResult } from "./memory-subject.js";
 import { SupportPassportAccessServiceBase } from "./support-passport/access-service-base.js";
 import {
   type ExportCapsuleOptions,
@@ -1238,6 +1244,7 @@ export class EngramAccessService extends SupportPassportAccessServiceBase {
   private readonly corpusWatermarkCache = new CorpusWatermarkCache();
   private readonly replicaDivergenceMonitor: ReplicaDivergenceMonitor;
   private readonly injectedSupportPassportGatewayRoute: SupportPassportModelRoute | null;
+  readonly reviewDeckEnabled: boolean;
 
   /** AccessObserveWriteSurface (access-service decomposition). Lazy; selfDeps live wiring. */
   private _accessObserveWriteSurface: AccessObserveWriteSurface | undefined;
@@ -1273,6 +1280,17 @@ export class EngramAccessService extends SupportPassportAccessServiceBase {
     return this._accessAdminOpsSurface;
   }
 
+  private _reviewDeckSurface: ReviewDeckSurface | undefined;
+
+  private get reviewDeckSurface(): ReviewDeckSurface {
+    if (!this._reviewDeckSurface) {
+      this._reviewDeckSurface = new ReviewDeckSurface(
+        selfDeps<ConstructorParameters<typeof ReviewDeckSurface>[0]>(this)
+      );
+    }
+    return this._reviewDeckSurface;
+  }
+
   /** AccessRecallSurface (access-service decomposition). Lazy; selfDeps live wiring. */
   private _accessRecallSurface: AccessRecallSurface | undefined;
 
@@ -1303,6 +1321,7 @@ export class EngramAccessService extends SupportPassportAccessServiceBase {
     options: {
       resolveSecretRef?: ResolveSecretRefFn | null;
       supportPassportGatewayRoute?: SupportPassportModelRoute | null;
+      reviewDeckEnabled?: boolean;
     } = {}
   ) {
     super();
@@ -1313,6 +1332,7 @@ export class EngramAccessService extends SupportPassportAccessServiceBase {
     // per-peer `unreachable` (never a throw).
     this.replicaDivergenceMonitor = new ReplicaDivergenceMonitor({ resolveSecretRef: options.resolveSecretRef });
     this.injectedSupportPassportGatewayRoute = options.supportPassportGatewayRoute ?? null;
+    this.reviewDeckEnabled = options.reviewDeckEnabled === true;
     const accessCaps = resolveAccessSetupCapabilities(orchestrator.config); // #1566 Cluster B
     this.budget = new CrossNamespaceBudget({
       enabled: accessCaps.recallCrossNamespaceBudget,
@@ -2738,6 +2758,41 @@ export class EngramAccessService extends SupportPassportAccessServiceBase {
     ]);
     return computeWhoKnows({ topic, limit, memories, entities });
   }
+  /**
+   * Read-only promotion-candidate surfacing (issue #2372): agent-subject,
+   * active, reuse-signaled memories in the caller's namespace with no
+   * equivalent in the target layer. No auto-promotion — callers use the
+   * existing promotion commands.
+   */
+  async promotionCandidates(request: {
+    namespace?: string;
+    targetNamespace?: string;
+    limit?: number;
+    authenticatedPrincipal?: string;
+  }): Promise<PromotionCandidatesResult> {
+    const limit = request.limit ?? 20;
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+      throw new EngramAccessInputError(
+        `promotion_candidates: limit expects an integer in [1, 100] (got ${String(request.limit)})`,
+      );
+    }
+    const resolvedNamespace = this.resolveReadableNamespace(request.namespace, request.authenticatedPrincipal);
+    const resolvedTarget = this.resolveReadableNamespace(
+      request.targetNamespace ?? this.orchestrator.config.sharedNamespace,
+      request.authenticatedPrincipal,
+    );
+    const minAccessCount = this.orchestrator.config.promotionCandidates.minAccessCount;
+    const [memories, targetMemories] = await Promise.all([
+      (await this.orchestrator.getStorage(resolvedNamespace)).readAllMemories(),
+      (await this.orchestrator.getStorage(resolvedTarget)).readAllMemories(),
+    ]);
+    return {
+      namespace: resolvedNamespace,
+      targetNamespace: resolvedTarget,
+      minAccessCount,
+      candidates: computePromotionCandidates({ memories, targetMemories, minAccessCount, limit }),
+    };
+  }
   async memoryStore(
     request: EngramAccessMemoryStoreRequest,
     hooks?: { enforceWriteQuota?: () => void | Promise<void> }
@@ -3580,6 +3635,51 @@ export class EngramAccessService extends SupportPassportAccessServiceBase {
     return { namespace: resolvedNamespace, ...report };
   }
 
+  /**
+   * Procedure library health maintenance (issue #2370). Shadow-first: the
+   * gate is checked BEFORE any storage read, so `maintenance.enabled=false`
+   * returns `{ enabled: false }` having touched nothing but config. Apply
+   * mode additionally requires `apply: true`; `dryRun: true` forces shadow.
+   *
+   * The authenticated principal (never a client-supplied actor) drives the
+   * namespace via the same writable resolver `procedureMiningRun` uses, so
+   * cross-tenant writes are impossible.
+   */
+  async procedureLibraryMaintenance(
+    request: {
+      namespace?: string;
+      apply?: boolean;
+      dryRun?: boolean;
+      authenticatedPrincipal?: string;
+    },
+    principal?: string
+  ): Promise<
+    | { enabled: false }
+    | {
+        enabled: true;
+        namespace: string;
+        report: ProcedureLibraryMaintenanceReport;
+      }
+  > {
+    const procedural = this.orchestrator.config.procedural;
+    if (procedural?.enabled !== true || procedural.maintenance?.enabled !== true) {
+      return { enabled: false };
+    }
+    const resolvedNamespace = this.writableNamespaceFor(
+      request.namespace,
+      undefined,
+      request.authenticatedPrincipal ?? principal
+    );
+    const storage = await this.orchestrator.getStorage(resolvedNamespace);
+    const report = await runProcedureLibraryMaintenance({
+      memoryDir: storage.dir,
+      storage,
+      config: this.orchestrator.config,
+      apply: request.apply === true && request.dryRun !== true,
+    });
+    return { enabled: true, namespace: resolvedNamespace, report };
+  }
+
   async memorySummarizeHourly(): Promise<{
     ok: true;
     message: string;
@@ -5602,4 +5702,16 @@ export class EngramAccessService extends SupportPassportAccessServiceBase {
   }) {
     return this.accessAdminOpsSurface.adminPromoteMemory(request);
   }
+
+  async reviewDeckList(opts: Parameters<ReviewDeckSurface["list"]>[0]) {
+    return this.reviewDeckSurface.list(opts);
+  }
+
+  async reviewDeckAction(...args: Parameters<ReviewDeckSurface["action"]>) {
+    return this.reviewDeckSurface.action(...args);
+  }
+
+  async reviewDeckUndo(...args: Parameters<ReviewDeckSurface["undo"]>) {
+    return this.reviewDeckSurface.undo(...args);
+  }
 }

package/src/access-surface-catalog.test.ts

@@ -170,6 +170,14 @@ function extractMcpDispatchMap(): Map<string, string> {
       new URL("./support-passport/mcp-tools.ts", import.meta.url),
       "SUPPORT_PASSPORT_MCP_MIGRATED_OPERATIONS",
     ),
+    // Third dispatch home (issue #2371): the admin/maintenance tool table
+    // contributes its own map fragment, spread into MCP_MIGRATED_OPERATIONS.
+    // Every module that can register a dispatch entry must be read here, or
+    // this validator reports a false "no dispatch wiring".
+    ...extractMcpOperationMap(
+      new URL("./access-mcp-admin-tools.ts", import.meta.url),
+      "MCP_ADMIN_OPS_MIGRATED_OPERATIONS",
+    ),
   ]);
 }
 
@@ -317,6 +325,22 @@ function extractHttpRouteDispatchMap(): Map<string, Set<string>> {
       }
     }
   }
+  if (/\bawait\s+this\.handleReviewDeckRequest\(/.test(source)) {
+    const deckSource = readFileSync(
+      new URL("./review/review-deck-http-base.ts", import.meta.url),
+      "utf-8",
+    );
+    const deckRoutes = [
+      ["GET", "/engram/v1/review/deck", "review_deck_list"],
+      ["POST", "/engram/v1/review/deck/action", "review_deck_action"],
+      ["POST", "/engram/v1/review/deck/undo", "review_deck_undo"],
+    ] as const;
+    for (const [method, pathname, operation] of deckRoutes) {
+      if (deckSource.includes(`"${pathname}"`) && deckSource.includes(`enforceTokenOp("${operation}")`)) {
+        routeOps.set(`${method} ${pathname}`, new Set([operation]));
+      }
+    }
+  }
   for (const [sourcePath, routes] of [
     ["./support-passport/access-http.ts", SUPPORT_PASSPORT_OWNER_HTTP_ROUTES],
     ["./support-passport/public-http.ts", SUPPORT_PASSPORT_PUBLIC_HTTP_ROUTES],

package/src/access-surface-catalog.ts

@@ -57,6 +57,7 @@ export const MCP_TOOLS: readonly McpToolEntry[] = [
   { tool: "recall_tier_explain", operation: "recall_tier_explain" },
   { tool: "recall_xray", operation: "recall_xray" },
   { tool: "who_knows", operation: "who_knows" },
+  { tool: "promotion_candidates", operation: "promotion_candidates" },
   { tool: "wearables_status", operation: "wearables_status" },
   { tool: "wearables_sync", operation: "wearables_sync" },
   { tool: "transcript_day", operation: "transcript_day" },
@@ -76,6 +77,7 @@ export const MCP_TOOLS: readonly McpToolEntry[] = [
   { tool: "procedure_mining_run", operation: "procedure_mining_run" },
   { tool: "pattern_reinforcement_run", operation: "pattern_reinforcement_run" },
   { tool: "procedural_stats", operation: "procedural_stats" },
+  { tool: "procedure_library_maintenance", operation: "procedure_library_maintenance" },
   { tool: "memory_get", operation: "memory_get" },
   { tool: "memory_timeline", operation: "memory_timeline" },
   { tool: "memory_store", operation: "memory_store" },
@@ -151,6 +153,7 @@ export const MCP_TOOLS: readonly McpToolEntry[] = [
   { tool: "review_list", operation: "review_list" },
   { tool: "review_resolve", operation: "review_resolve" },
   { tool: "contradiction_scan_run", operation: "contradiction_scan_run" },
+  { tool: "preference_drift_scan", operation: "preference_drift_scan" },
   { tool: "memory_summarize_hourly", operation: "memory_summarize_hourly" },
   { tool: "conversation_index_update", operation: "conversation_index_update" },
   { tool: "profiling_report", operation: "profiling_report" },
@@ -251,6 +254,9 @@ export const HTTP_ROUTES: readonly HttpRouteEntry[] = [
   { method: "GET", pathname: "/engram/v1/procedural/stats", operation: "procedural_stats" },
   { method: "GET", pathname: "/engram/v1/trust-zones/records", operation: "trust_zones_records" },
   { method: "POST", pathname: "/engram/v1/review-disposition", operation: "review_disposition" },
+  { method: "GET", pathname: "/engram/v1/review/deck", operation: "review_deck_list" },
+  { method: "POST", pathname: "/engram/v1/review/deck/action", operation: "review_deck_action" },
+  { method: "POST", pathname: "/engram/v1/review/deck/undo", operation: "review_deck_undo" },
   { method: "POST", pathname: "/engram/v1/trust-zones/promote", operation: "trust_zones_promote" },
   { method: "POST", pathname: "/engram/v1/trust-zones/demo-seed", operation: "trust_zones_demo_seed" },
   { method: "POST", pathname: "/v1/citations/observed", operation: "citations_observed" },