@remnic/core 9.65.2 → 9.65.3

package/src/access-service.ts

@@ -303,6 +303,7 @@ 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";
@@ -1243,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;
@@ -1278,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;
 
@@ -1308,6 +1321,7 @@ export class EngramAccessService extends SupportPassportAccessServiceBase {
     options: {
       resolveSecretRef?: ResolveSecretRefFn | null;
       supportPassportGatewayRoute?: SupportPassportModelRoute | null;
+      reviewDeckEnabled?: boolean;
     } = {}
   ) {
     super();
@@ -1318,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,
@@ -5687,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

@@ -153,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" },
@@ -253,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" },

package/src/coding/action-gate.test.ts

@@ -0,0 +1,341 @@
+import assert from "node:assert/strict";
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { recordCausalTrajectory } from "../causal-trajectory.js";
+import type { CodingContext, MemoryFile } from "../types.js";
+import {
+  ACTION_GATE_DEFAULTS,
+  type ActionGateAuditRecord,
+  type ActionGateCandidateSource,
+  type ActionGateRequest,
+  ActionGateService,
+  actionTermsFor,
+  createFailureMemoryCandidateSource,
+  createTrajectoryCandidateSource,
+  isFailureClassMemory,
+  parseActionGateConfig,
+} from "./action-gate.js";
+import { PreActionFailureGate, normalizeActionIntent } from "./pre-action-gate.js";
+
+const codingContext: CodingContext = {
+  projectId: "proj-gate",
+  branch: "main",
+  rootPath: "/work/project",
+  defaultBranch: null,
+};
+
+function memory(id: string, content: string, overrides: Record<string, unknown> = {}): MemoryFile {
+  return {
+    path: `facts/2026-08-18/${id}.md`,
+    content,
+    frontmatter: {
+      id,
+      category: "correction",
+      created: "2026-08-18T00:00:00Z",
+      updated: "2026-08-18T00:00:00Z",
+      source: "test",
+      confidence: 0.9,
+      confidenceTier: "explicit",
+      tags: [],
+      status: "active",
+      ...overrides,
+    } as MemoryFile["frontmatter"],
+  };
+}
+
+function request(overrides: Partial<ActionGateRequest> = {}): ActionGateRequest {
+  return {
+    sessionKey: "session-a",
+    turnId: "turn-1",
+    strategyId: "RUN_CHECK",
+    intent: { kind: "command", command: "pnpm", args: ["migrate", "--force"] },
+    codingContext,
+    memoryDir: "/tmp/does-not-matter",
+    ...overrides,
+  };
+}
+
+function staticSource(id: string, memoryIds: string[]): ActionGateCandidateSource {
+  return {
+    id,
+    async find() {
+      return {
+        ok: true,
+        candidates: memoryIds.map((memoryId, index) => ({
+          memoryId,
+          score: memoryIds.length - index,
+          advisoryText: `advisory for ${memoryId}`,
+        })),
+      };
+    },
+  };
+}
+
+test("parses the actionGate block with safe defaults and zero-limit semantics", () => {
+  assert.deepEqual(parseActionGateConfig(undefined), ACTION_GATE_DEFAULTS);
+  assert.equal(parseActionGateConfig(undefined).enabled, false);
+  // CLI values arrive as strings.
+  assert.equal(parseActionGateConfig({ enabled: "false" }).enabled, false);
+  assert.equal(parseActionGateConfig({ enabled: "on" }).enabled, true);
+  assert.equal(parseActionGateConfig({ maxAdvisoriesPerTurn: "0" }).maxAdvisoriesPerTurn, 0);
+  assert.equal(parseActionGateConfig({ timeoutMs: "120" }).timeoutMs, 120);
+  assert.equal(parseActionGateConfig({ timeoutMs: 0 }).timeoutMs, 1);
+  assert.throws(() => parseActionGateConfig({ enabled: "maybe" }), /actionGate.enabled/);
+  assert.throws(() => parseActionGateConfig([]), /must be an object/);
+  assert.throws(() => parseActionGateConfig(null), /must be an object/);
+});
+
+test("disabled gate performs no lookup on any path", async () => {
+  let calls = 0;
+  const source: ActionGateCandidateSource = {
+    id: "spy",
+    async find() {
+      calls += 1;
+      return { ok: true, candidates: [{ memoryId: "m1", advisoryText: "never" }] };
+    },
+  };
+  const audits: ActionGateAuditRecord[] = [];
+  const disabled = new ActionGateService(parseActionGateConfig({}), {
+    sources: [source],
+    audit: (record) => void audits.push(record),
+  });
+  const decision = await disabled.evaluate(request());
+  assert.equal(decision.status, "DISABLED");
+  assert.deepEqual(decision.advisories, []);
+  assert.equal(calls, 0);
+  assert.deepEqual(disabled.suppressedForTurnStart("session-a"), []);
+  disabled.noteTurnStartDelivery("session-a", ["m1"]);
+  assert.deepEqual(disabled.suppressedForTurnStart("session-a"), []);
+
+  const zeroBudget = new ActionGateService(parseActionGateConfig({ enabled: true, maxAdvisoriesPerTurn: 0 }), {
+    sources: [source],
+  });
+  const zeroDecision = await zeroBudget.evaluate(request());
+  assert.equal(zeroDecision.status, "DISABLED");
+  assert.match(zeroDecision.reason ?? "", /maxAdvisoriesPerTurn is 0/);
+  assert.equal(calls, 0);
+});
+
+test("delivers one bounded advisory and suppresses it from turn-start recall", async () => {
+  const audits: ActionGateAuditRecord[] = [];
+  const service = new ActionGateService(parseActionGateConfig({ enabled: true }), {
+    sources: [
+      createFailureMemoryCandidateSource({
+        async listMemories() {
+          return [
+            memory("mem-match", "Running pnpm migrate --force dropped the dev database."),
+            memory("mem-other", "Unrelated note about documentation."),
+            memory("mem-archived", "pnpm migrate --force failed again", { status: "archived" }),
+          ];
+        },
+      }),
+    ],
+    audit: (record) => void audits.push(record),
+  });
+
+  const decision = await service.evaluate(request());
+  assert.equal(decision.status, "MATCH_WARN");
+  assert.equal(decision.advisories.length, 1);
+  assert.equal(decision.advisories[0].memoryId, "mem-match");
+  assert.equal(decision.advisories[0].sourceId, "failure-memory");
+  assert.match(decision.advisories[0].text, /dropped the dev database/);
+  assert.ok(decision.advisories[0].text.length <= 400);
+  assert.deepEqual(decision.degradations, []);
+
+  // Double-delivery suppression: turn-start recall must skip what the gate sent.
+  assert.deepEqual(service.suppressedForTurnStart("session-a"), ["mem-match"]);
+
+  // Same turn, same action: deduplicated per fact per turn.
+  const repeat = await service.evaluate(request());
+  assert.deepEqual(repeat.advisories, []);
+  assert.deepEqual(repeat.suppressedIds, ["mem-match"]);
+  assert.equal(repeat.status, "NO_MATCH");
+
+  await new Promise((resolve) => setImmediate(resolve));
+  assert.equal(audits.length, 2);
+  assert.deepEqual(audits[0].deliveredIds, ["mem-match"]);
+  assert.deepEqual(audits[1].suppressedIds, ["mem-match"]);
+  assert.match(audits[0].fingerprint ?? "", /^v1:sha256:/);
+});
+
+test("skips candidates turn-start recall already delivered", async () => {
+  const service = new ActionGateService(parseActionGateConfig({ enabled: true }), {
+    sources: [staticSource("static", ["mem-a"])],
+  });
+  service.noteTurnStartDelivery("session-a", ["mem-a"]);
+  const decision = await service.evaluate(request());
+  assert.equal(decision.status, "NO_MATCH");
+  assert.deepEqual(decision.suppressedIds, ["mem-a"]);
+  assert.deepEqual(decision.advisories, []);
+});
+
+test("caps advisories per turn and resets the budget on the next turn", async () => {
+  const service = new ActionGateService(parseActionGateConfig({ enabled: true, maxAdvisoriesPerTurn: 2 }), {
+    sources: [staticSource("static", ["mem-a", "mem-b", "mem-c"])],
+  });
+  const first = await service.evaluate(request());
+  assert.deepEqual(
+    first.advisories.map((advisory) => advisory.memoryId),
+    ["mem-a", "mem-b"]
+  );
+  assert.deepEqual(first.suppressedIds, ["mem-c"]);
+
+  const nextTurn = await service.evaluate(request({ turnId: "turn-2" }));
+  // A new turn re-arms the budget: proposing the same action again warns again,
+  // which is the whole point of action-site delivery.
+  assert.deepEqual(
+    nextTurn.advisories.map((advisory) => advisory.memoryId),
+    ["mem-a", "mem-b"]
+  );
+  assert.deepEqual(nextTurn.suppressedIds, ["mem-c"]);
+});
+
+test("namespace scoping keeps advisories inside the requesting principal", async () => {
+  const byNamespace: Record<string, MemoryFile[]> = {
+    "tenant-a": [memory("mem-a", "pnpm migrate --force wiped tenant a data")],
+    "tenant-b": [memory("mem-b", "pnpm migrate --force wiped tenant b data")],
+  };
+  const service = new ActionGateService(parseActionGateConfig({ enabled: true }), {
+    sources: [
+      createFailureMemoryCandidateSource({
+        async listMemories({ namespace }) {
+          return byNamespace[namespace ?? ""] ?? [];
+        },
+      }),
+    ],
+  });
+  const a = await service.evaluate(request({ sessionKey: "s-a", namespace: "tenant-a" }));
+  const b = await service.evaluate(request({ sessionKey: "s-b", namespace: "tenant-b" }));
+  assert.deepEqual(
+    a.advisories.map((advisory) => advisory.memoryId),
+    ["mem-a"]
+  );
+  assert.deepEqual(
+    b.advisories.map((advisory) => advisory.memoryId),
+    ["mem-b"]
+  );
+});
+
+test("source failure fails open with a distinct status and audit degradation", async () => {
+  const audits: ActionGateAuditRecord[] = [];
+  const service = new ActionGateService(parseActionGateConfig({ enabled: true }), {
+    sources: [
+      {
+        id: "broken",
+        async find() {
+          throw new Error("store unreadable");
+        },
+      },
+    ],
+    audit: (record) => void audits.push(record),
+  });
+  const decision = await service.evaluate(request());
+  assert.equal(decision.status, "ERROR_FAIL_OPEN");
+  assert.deepEqual(decision.advisories, []);
+  assert.match(decision.degradations[0], /broken: store unreadable/);
+  await new Promise((resolve) => setImmediate(resolve));
+  assert.equal(audits[0].status, "ERROR_FAIL_OPEN");
+});
+
+test("an over-deadline source fails open instead of delaying the action", async () => {
+  const service = new ActionGateService(parseActionGateConfig({ enabled: true, timeoutMs: 5 }), {
+    sources: [
+      {
+        id: "slow",
+        find() {
+          return new Promise((resolve) =>
+            setTimeout(() => resolve({ ok: true, candidates: [{ memoryId: "late", advisoryText: "late" }] }), 200)
+          );
+        },
+      },
+    ],
+  });
+  const startedAt = Date.now();
+  const decision = await service.evaluate(request());
+  assert.ok(Date.now() - startedAt < 150, "gate must not wait for the slow source");
+  assert.equal(decision.status, "ERROR_FAIL_OPEN");
+  assert.match(decision.degradations[0], /timed out after 5ms/);
+});
+
+test("an invalid action intent fails open rather than throwing", async () => {
+  const service = new ActionGateService(parseActionGateConfig({ enabled: true }), {
+    sources: [staticSource("static", ["mem-a"])],
+  });
+  const decision = await service.evaluate(
+    request({ intent: { kind: "edit", filePath: "/elsewhere/secret.ts", editKind: "update" } })
+  );
+  assert.equal(decision.status, "ERROR_FAIL_OPEN");
+  assert.match(decision.reason ?? "", /contained/);
+  assert.deepEqual(decision.advisories, []);
+});
+
+test("trajectory source surfaces a recorded failure at the action site", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-action-gate-"));
+  try {
+    const intent = { kind: "command" as const, command: "pnpm", args: ["migrate", "--force"] };
+    await recordCausalTrajectory({
+      memoryDir,
+      record: {
+        schemaVersion: 1,
+        trajectoryId: "traj-failure",
+        recordedAt: "2026-08-17T12:00:00Z",
+        sessionKey: "historical-session",
+        goal: "Migrate the database",
+        actionSummary: "Ran the forced migration",
+        observationSummary: "The migration destroyed local data",
+        outcomeKind: "failure",
+        outcomeSummary: "Dev database dropped",
+        followUpSummary: "Take a snapshot before migrating",
+        codingContext: { projectId: codingContext.projectId, branch: "main" },
+        actionIdentity: {
+          fingerprintVersion: 1,
+          fingerprint: normalizeActionIntent(intent, "RUN_CHECK", codingContext).fingerprint,
+          strategyId: "RUN_CHECK",
+        },
+      },
+    });
+    const service = new ActionGateService(parseActionGateConfig({ enabled: true, timeoutMs: 2000 }), {
+      sources: [createTrajectoryCandidateSource(new PreActionFailureGate({ timeoutMs: 1000 }))],
+    });
+    const decision = await service.evaluate(request({ intent, memoryDir }));
+    assert.equal(decision.status, "MATCH_WARN");
+    assert.equal(decision.advisories[0].memoryId, "traj-failure");
+    assert.equal(decision.advisories[0].sourceId, "causal-trajectory");
+    assert.match(decision.advisories[0].text, /Dev database dropped/);
+
+    const unrelated = await service.evaluate(
+      request({
+        turnId: "turn-2",
+        intent: { kind: "command", command: "pnpm", args: ["build"] },
+        memoryDir,
+      })
+    );
+    assert.equal(unrelated.status, "NO_MATCH");
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("failure-class detection and action terms stay deterministic", () => {
+  assert.equal(isFailureClassMemory(memory("m", "x")), true);
+  assert.equal(isFailureClassMemory(memory("m", "x", { category: "fact" })), false);
+  assert.equal(
+    isFailureClassMemory(memory("m", "x", { category: "procedure", structuredAttributes: { needsRepair: "true" } })),
+    true
+  );
+  assert.equal(isFailureClassMemory(memory("m", "x", { category: "fact", mw_fail: 3, mw_success: 1 })), true);
+  assert.equal(isFailureClassMemory(memory("m", "x", { category: "fact", mw_fail: 1, mw_success: 4 })), false);
+  assert.equal(isFailureClassMemory(memory("m", "x", { status: "pending_review" })), false);
+
+  assert.deepEqual(actionTermsFor({ kind: "command", command: "pnpm", args: ["migrate", "-f", "migrate"] }), [
+    "pnpm",
+    "migrate",
+  ]);
+  assert.deepEqual(actionTermsFor({ kind: "edit", filePath: "src/config.ts", editKind: "update" }), [
+    "src",
+    "config.ts",
+    "update",
+  ]);
+});