@remnic/core 9.3.685 → 9.3.687

package/src/access-operations.ts

@@ -20,6 +20,11 @@ import type {
   EngramAccessMemoryResponse,
   EngramAccessWriteResponse,
 } from "./access-service.js";
+import {
+  DECISION_SUBCOMMANDS,
+  type DecisionSurfaceRequest,
+  type DecisionSurfaceResponse,
+} from "./coding/decision-surfaces.js";
 
 // ---------------------------------------------------------------------------
 // memory_get — fetch one memory by id
@@ -135,12 +140,72 @@ export const memoryStoreOperation = defineOperation<MemoryStoreInput, MemoryStor
       // so the hook still fires inside the service's idempotent-write lock —
       // never before, never on a replay (#1434 invariant preserved by the
       // boundary migration).
+
       ctx.hooks,
     );
     return { result };
   },
 });
 
+// ---------------------------------------------------------------------------
+// coding_decision — decision-record surfaces (issue #1548 Track A PR 2)
+// ---------------------------------------------------------------------------
+
+/**
+ * The subcommand field is required and MUST be one of the four valid values
+ * (rule 51 — reject loudly, list the options, never silently default). The
+ * remaining fields are optional because each subcommand uses a different
+ * subset; the handler validates subcommand-specific requirements after
+ * routing.
+ */
+/**
+ * MCP clients send `null` for absent optional fields. Zod `.optional()`
+ * rejects `null`, so strip nulls at the object level before the inner
+ * schema validates (review: cursor null-field thread).
+ */
+const codingDecisionSchema = z.preprocess(
+  (data) => {
+    if (data && typeof data === "object" && !Array.isArray(data)) {
+      const out: Record<string, unknown> = {};
+      for (const [k, v] of Object.entries(data as Record<string, unknown>)) {
+        if (v !== null) out[k] = v;
+      }
+      return out;
+    }
+    return data;
+  },
+  z.object({
+    subcommand: z.enum(DECISION_SUBCOMMANDS),
+    sessionKey: z.string().trim().max(512).optional(),
+    namespace: z.string().trim().max(256).optional(),
+    id: z.string().trim().max(512).optional(),
+    title: z.string().trim().max(512).optional(),
+    status: z.string().trim().max(64).optional(),
+    context: z.string().trim().max(8192).optional(),
+    decision: z.string().trim().max(8192).optional(),
+    consequences: z.string().trim().max(8192).optional(),
+    entityRefs: z.array(z.string().trim().min(1).max(256)).optional(),
+    supersedesId: z.string().trim().max(512).optional(),
+  }),
+);
+
+export type CodingDecisionInput = DecisionSurfaceRequest;
+export type CodingDecisionOutput = { result: DecisionSurfaceResponse };
+
+export const codingDecisionOperation = defineOperation<
+  CodingDecisionInput,
+  CodingDecisionOutput
+>({
+  name: "coding_decision",
+  description:
+    "List, get, record, or supersede decision records in the session's coding namespace (issue #1548 Track A).",
+  schema: codingDecisionSchema as z.ZodType<CodingDecisionInput>,
+  handler: async (input, ctx) => {
+    const result = await ctx.service.codingDecision(input, ctx.authenticatedPrincipal);
+    return { result };
+  },
+});
+
 // ---------------------------------------------------------------------------
 // Surface registration map — what each transport calls the pilot ops
 // ---------------------------------------------------------------------------
@@ -154,4 +219,5 @@ export const REGISTERED_OPERATIONS = [
   memoryGetOperation.spec.name,
   memorySearchOperation.spec.name,
   memoryStoreOperation.spec.name,
+  codingDecisionOperation.spec.name,
 ] as const;

package/src/access-service.ts

@@ -12,7 +12,13 @@ import {
   lcmSessionKeyForNamespace,
   projectTagProjectId,
   resolveCodingNamespaceOverlay,
+  type CodingNamespaceOverlay,
 } from "./coding/coding-namespace.js";
+import {
+  handleCodingDecision,
+  type DecisionSurfaceRequest,
+  type DecisionSurfaceResponse,
+} from "./coding/decision-surfaces.js";
 import { WorkStorage } from "./work/storage.js";
 import {
   exportWorkBoardMarkdown,
@@ -59,6 +65,7 @@ import { canReadNamespace, canWriteNamespace, defaultNamespaceForPrincipal, reca
 import {
   expandScopeProfileReadNamespaces,
   resolveScopeProfilePlan,
+  type ResolvedScopeProfilePlan,
   type ScopeProfileLayerResolution,
   type ScopeProfilePromotionResolution,
 } from "./namespaces/scope-profiles.js";
@@ -1346,74 +1353,29 @@ export class EngramAccessService {
     return null;
   }
 
-  /**
-   * Resolve the write namespace for explicit-write tools (memory_store /
-   * suggestion_submit), project-scoping the write the same way recall does so a
-   * memory stored with a client-injected `cwd`/`projectTag` is discoverable by
-   * project-scoped recall (#1434, rule 42).
-   *
-   * Precedence:
-   *  - An explicit `namespace` always wins and is authorized strictly via
-   *    `resolveWritableNamespace` → `canWriteNamespace`. A coding-overlay
-   *    namespace string (`<base>-project-*`) is NOT a writable target via the
-   *    explicit field — project scoping is requested with `cwd`/`projectTag`,
-   *    never by naming the derived namespace — so there is no way to bypass the
-   *    policy allow-list by guessing/forging an overlay name (Codex review).
-   *  - With NO coding overlay, the write stays on `config.defaultNamespace` —
-   *    exactly the pre-#1434 behavior, so an unqualified write is NOT silently
-   *    moved to a principal self namespace (Codex review).
-   *  - WITH a coding overlay, the base is the principal self namespace
-   *    (`defaultNamespaceForPrincipal`, write-checked) — the SAME base recall,
-   *    observe, and the orchestrator buffer-flush write path overlay onto
-   *    (rule 42 / Cursor) — so a project-scoped store lands exactly where
-   *    project-scoped recall searches. The overlay namespace is always REBUILT
-   *    from the authenticated principal's base, never accepted as a caller
-   *    string, so a caller can never reach another principal's subtree.
-   *
-   * Read-only: this NEVER mutates session coding context, so the idempotency
-   * peeks and dryRun preflights that call it stay side-effect free (Codex
-   * review). It prefers the per-call `cwd`/`projectTag` (the project explicitly
-   * identified for this write), else the session's existing context. The HTTP
-   * surface lets the peek and the write each resolve independently; the peek's
-   * namespace only gates rate-limiting (memory_store/suggestion_submit run their
-   * own idempotency check), so a benign session-context change between the two
-   * never fails a write — there is no namespace to "pin".
-   */
-  private async resolveCodingScopedWriteNamespace(
+  /** Shared coding-scope derivation for the read/write resolvers below —
+   *  coding context, overlay, principal, scope-profile plan for an IMPLICIT
+   *  request, IDENTICAL to recall precedence (session-first, per-call fallback)
+   *  so a scoped store is discoverable by scoped recall (#1434). Single source
+   *  of truth for the namespacesEnabled/projectScope gates (rule 22; keeps the
+   *  scattered-config-read ratchet flat). READ-ONLY: never mutates session. */
+  private async resolveCodingScopeInputs(
     request: CodingScopedWriteInput & {
       namespace?: string;
       sessionKey?: string;
       authenticatedPrincipal?: string;
     },
-  ): Promise<string> {
-    const hasExplicitNamespace =
-      typeof request.namespace === "string" && request.namespace.trim().length > 0;
-    if (hasExplicitNamespace) {
-      return this.resolveWritableNamespace(
-        request.namespace,
-        request.sessionKey,
-        request.authenticatedPrincipal,
-      );
-    }
-    // Project scoping only applies when namespaces are enabled (else overlaying
-    // would create false isolation over a single storage dir) and projectScope
-    // is on. The coding context MUST be resolved exactly as the recall path
-    // resolves it, or a scoped store won't be discoverable by scoped recall
-    // (the whole point of #1434). Recall calls `maybeAttachCodingContext`, which
-    // returns early when the session already has a context — so recall is
-    // SESSION-FIRST: an existing session binding wins, and the per-call
-    // cwd/projectTag is only used to seed a context when none is attached yet.
-    // Mirror that precedence here: session context first, per-call as fallback
-    // (Codex review — a per-call-wins write would land in a project that the
-    // same session's recall, still on the bound project, never searches).
-    //
+  ): Promise<{
+    principal: string | undefined;
+    codingContext: CodingContext | null;
+    overlay: CodingNamespaceOverlay | null;
+    profilePlan: ResolvedScopeProfilePlan | null;
+  }> {
     // A sessionKey is REQUIRED to apply the overlay. The recall path can only
-    // attach/look up coding context per session (`maybeAttachCodingContext` and
-    // `applyCodingNamespaceOverlay` both no-op without a sessionKey), so a
-    // sessionless recall always searches the base namespace. A sessionless
-    // write must therefore also stay on the base — otherwise a client that
-    // injects cwd/projectTag but no sessionKey would store into
-    // `default-project-*` that its own recall never searches (Codex review).
+    // attach/look up coding context per session, so a sessionless recall always
+    // searches the base namespace; a sessionless write/read must too — otherwise
+    // a client that injects cwd/projectTag but no sessionKey would land in a
+    // `default-project-*` namespace its own recall never searches (Codex review).
     const hasSession =
       typeof request.sessionKey === "string" && request.sessionKey.length > 0;
     const codingContext =
@@ -1443,6 +1405,35 @@ export class EngramAccessService {
       codingContext,
       codingOverlay: overlay,
     });
+    return { principal, codingContext, overlay, profilePlan };
+  }
+
+  /**
+   * Resolve the write namespace for explicit-write tools (memory_store /
+   * suggestion_submit), project-scoping the write the same way recall does so a
+   * memory stored with a client-injected `cwd`/`projectTag` is discoverable by
+   * project-scoped recall (#1434, rule 42). Shared derivation lives in
+   * {@link resolveCodingScopeInputs}; this method enforces the WRITE acl
+   * (`canWriteNamespace` / profile-layer writability). Read-only: never mutates
+   * session coding context.
+   */
+  private async resolveCodingScopedWriteNamespace(
+    request: CodingScopedWriteInput & {
+      namespace?: string;
+      sessionKey?: string;
+      authenticatedPrincipal?: string;
+    },
+  ): Promise<string> {
+    const hasExplicitNamespace =
+      typeof request.namespace === "string" && request.namespace.trim().length > 0;
+    if (hasExplicitNamespace) {
+      return this.resolveWritableNamespace(
+        request.namespace,
+        request.sessionKey,
+        request.authenticatedPrincipal,
+      );
+    }
+    const { principal, overlay, profilePlan } = await this.resolveCodingScopeInputs(request);
     if (profilePlan) {
       const selectedLayer = profilePlan.layers.find((layer) => layer.id === profilePlan.writeLayer);
       const writeNamespaceReadable =
@@ -1475,6 +1466,60 @@ export class EngramAccessService {
     return combineNamespaces(base, overlay.namespace);
   }
 
+  /** Read-side mirror of {@link resolveCodingScopedWriteNamespace}. Decision
+   *  `list`/`get` use this so a record written by a project-scoped session is
+   *  listable/fetchable by the SAME session without manually supplying the
+   *  overlaid namespace (review P2). Derivation is IDENTICAL to the write path
+   *  (shared via {@link resolveCodingScopeInputs}); the only difference is the
+   *  ACL — reads enforce {@link canReadNamespace}, so a read-but-not-write
+   *  principal can still list/fetch (rule 42). */
+  private async resolveCodingScopedReadableNamespace(
+    request: CodingScopedWriteInput & {
+      namespace?: string;
+      sessionKey?: string;
+      authenticatedPrincipal?: string;
+    },
+  ): Promise<string> {
+    const principal = this.resolveRequestPrincipal(
+      request.sessionKey,
+      request.authenticatedPrincipal,
+    );
+    const hasExplicitNamespace =
+      typeof request.namespace === "string" && request.namespace.trim().length > 0;
+    if (hasExplicitNamespace) {
+      return this.resolveReadableNamespace(request.namespace, principal);
+    }
+    const inputs = await this.resolveCodingScopeInputs(request);
+    const { overlay, profilePlan, principal: resolvedPrincipal } = inputs;
+    if (profilePlan) {
+      // The write layer is the namespace decisions are RECORDED under. The
+      // WRITE path authorizes it through the profile plan (selectedLayer.
+      // writable AND readNamespaces.includes(writeNamespace)), NOT the raw
+      // namespace ACL, so the READ path must use the SAME profile-plan
+      // authorization. canReadNamespace only recognizes explicit policies
+      // plus default/shared namespaces, which would reject a profile-granted
+      // layer the same session just wrote through (review P2: scope-profile
+      // read authorization for decision reads; rule 42).
+      const target = profilePlan.writeNamespace;
+      if (!profilePlan.readNamespaces.includes(target)) {
+        throw new EngramAccessInputError(`namespace is not readable: ${target}`);
+      }
+      return target;
+    }
+    if (!overlay) {
+      // No coding overlay → read the base namespace through the standard read
+      // ACL, identical to memory_get with no explicit namespace.
+      return this.resolveReadableNamespace(undefined, resolvedPrincipal);
+    }
+    // Coding overlay → overlay onto the principal self base, the SAME namespace
+    // the write path writes to, then enforce the read ACL.
+    const base = defaultNamespaceForPrincipal(resolvedPrincipal, this.orchestrator.config);
+    if (!canReadNamespace(resolvedPrincipal, base, this.orchestrator.config)) {
+      throw new EngramAccessInputError(`namespace is not readable: ${base}`);
+    }
+    return combineNamespaces(base, overlay.namespace);
+  }
+
   /**
    * Resolve ONE effective memory scope plan for a write-producing request
    * (#1495 / seed for epic #1494). The returned {@link MemoryScopePlan} is the
@@ -4401,6 +4446,45 @@ export class EngramAccessService {
     };
   }
 
+  /** Whether the coding_decision tool should appear in tools/list (rule 39). */
+  get decisionRecordSurfaceVisible(): boolean {
+    return this.orchestrator.config.codingKnowledge?.enabled === true
+      && this.orchestrator.config.codingKnowledge?.decisionRecords === true;
+  }
+  /**
+   * Thin delegate — handler logic in coding/decision-surfaces.ts (#1548 PR2).
+   * All three surfaces (MCP/HTTP/CLI) arrive here via the boundary operation.
+   * Namespace resolution uses the SAME path as memory_store (principal ACL +
+   * coding overlay + default fallback) so decision records land in the same
+   * storage root.
+   */
+  async codingDecision(
+    request: DecisionSurfaceRequest,
+    authenticatedPrincipal?: string,
+  ): Promise<DecisionSurfaceResponse> {
+    return handleCodingDecision(request, {
+      codingKnowledge: this.orchestrator.config.codingKnowledge,
+      getCodingContext: (sk) => this.orchestrator.getCodingContextForSession(sk),
+      resolveStorage: async (req) => {
+        const isWrite = req.subcommand === "record" || req.subcommand === "supersede";
+        const ns = isWrite
+          ? await this.resolveCodingScopedWriteNamespace({
+              namespace: req.namespace,
+              sessionKey: req.sessionKey,
+              authenticatedPrincipal,
+            })
+        : await this.resolveCodingScopedReadableNamespace({
+            namespace: req.namespace,
+            sessionKey: req.sessionKey,
+            authenticatedPrincipal,
+          });
+        const storage = await this.orchestrator.getStorage(ns);
+        return Object.assign(storage, { namespace: ns });
+      },
+      throwInputError: (msg) => { throw new EngramAccessInputError(msg); },
+    });
+  }
+
   async memoryBrowse(
     request: EngramAccessMemoryBrowseRequest = {},
   ): Promise<EngramAccessMemoryBrowseResponse> {
@@ -8264,3 +8348,4 @@ export class EngramAccessService {
     });
   }
 }
+

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

@@ -67,7 +67,7 @@ function shortToolName(advertised: string): string {
 /** Spin up a server with emitLegacyTools=true and read the deduped short names. */
 async function liveMcpToolShortNames(): Promise<ReadonlySet<string>> {
   const stub = { briefingEnabled: true } as unknown as EngramAccessService;
-  const server = new EngramMcpServer(stub, { emitLegacyTools: true });
+  const server = new EngramMcpServer(stub, { emitLegacyTools: true, codingDecisionVisible: true });
   const response = await server.handleRequest({ jsonrpc: "2.0", id: 1, method: "tools/list" });
   const result = (response as { result?: { tools?: Array<{ name: string }> } }).result;
   const names = new Set<string>();

package/src/access-surface-catalog.ts

@@ -72,6 +72,7 @@ export const MCP_TOOLS: readonly McpToolEntry[] = [
   { tool: "memory_get", operation: "memory_get" },
   { tool: "memory_timeline", operation: null },
   { tool: "memory_store", operation: "memory_store" },
+  { tool: "coding_decision", operation: "coding_decision" },
   { tool: "suggestion_submit", operation: null },
   { tool: "entity_get", operation: null },
   { tool: "review_queue_list", operation: null },
@@ -168,6 +169,7 @@ export const HTTP_ROUTES: readonly HttpRouteEntry[] = [
   { method: "POST", pathname: "/engram/v1/lcm/compaction/record", operation: null },
   { method: "GET", pathname: "/engram/v1/lcm/status", operation: null },
   { method: "POST", pathname: "/engram/v1/memories", operation: "memory_store" },
+  { method: "POST", pathname: "/engram/v1/coding/decisions", operation: "coding_decision" },
   { method: "POST", pathname: "/engram/v1/suggestions", operation: null },
   { method: "GET", pathname: "/engram/v1/memories", operation: null },
   { method: "GET", pathname: "/engram/v1/memories/:id", operation: "memory_get" },

package/src/cli.ts

@@ -2800,6 +2800,7 @@ export async function runAccessMcpServeCliCommand(
     new EngramMcpServer(service, {
       principal: options.principal,
       emitLegacyTools: options.emitLegacyTools,
+      codingDecisionVisible: service.decisionRecordSurfaceVisible,
     });
   await server.runStdio(options.stdin ?? process.stdin, options.stdout ?? process.stdout);
   return { ok: true };

package/src/coding/decision-surfaces.test.ts

@@ -0,0 +1,279 @@
+/**
+ * Decision-record surface tests (issue #1548 Track A PR 2).
+ *
+ * Covers:
+ *  - Gate predicate: all three conditions (config.enabled + decisionRecords +
+ *    coding context) checked identically.
+ *  - Subcommand validation: invalid subcommand → error listing valid ones.
+ *  - Unknown decision id → explicit not-found, not empty success (rule 34).
+ *  - Prove-fail-before: `engram.coding_decision` absent from tools/list when
+ *    the config gate is off; present when on (rule 39 byte-identical contract).
+ *  - Three surfaces → one service method (rule 22 spirit).
+ *  - Registry fitness: the operation resolves through the boundary.
+ */
+import assert from "node:assert/strict";
+import test from "node:test";
+import { EngramAccessInputError, type EngramAccessService } from "../access-service.js";
+import type { Orchestrator } from "../orchestrator.js";
+import { getOperation, type OperationName } from "../access-boundary.js";
+import "../access-operations.js";
+import { EngramMcpServer } from "../access-mcp.js";
+import {
+  DECISION_SUBCOMMANDS,
+  formatDecisionSubcommands,
+  isDecisionRecordSurfaceEnabled,
+  isDecisionRecordSurfaceVisible,
+  isDecisionSubcommand,
+  type DecisionSurfaceRequest,
+  type DecisionSurfaceResponse,
+} from "./decision-surfaces.js";
+import type { CodingContext, CodingKnowledgeConfig, PluginConfig } from "../types.js";
+
+// ──────────────────────────────────────────────────────────────────────────
+// Test helpers
+// ──────────────────────────────────────────────────────────────────────────
+
+const GATE_OFF_CONFIG: CodingKnowledgeConfig = {
+  enabled: false,
+  decisionRecords: true,
+  architectureCard: true,
+  sessionDelta: true,
+  architectureCardLlmSummary: false,
+  structuralProvider: "none",
+  structuralProviderCommand: "",
+};
+
+const GATE_ON_CONFIG: CodingKnowledgeConfig = {
+  ...GATE_OFF_CONFIG,
+  enabled: true,
+};
+
+const CODING_CONTEXT: CodingContext = {
+  projectId: "acme-backend",
+  branch: "main",
+  rootPath: "/repo/acme",
+  defaultBranch: "main",
+};
+
+/**
+ * Mock service that records calls to `codingDecision`. The mock signature MUST
+ * match the production method (rule 33).
+ */
+function makeMockService(
+  response: DecisionSurfaceResponse = {
+    subcommand: "list",
+    records: [],
+    count: 0,
+  },
+): { service: EngramAccessService; calls: DecisionSurfaceRequest[] } {
+  const calls: DecisionSurfaceRequest[] = [];
+  const service = {
+    codingDecision(
+      req: DecisionSurfaceRequest,
+      _authenticatedPrincipal?: string,
+    ): Promise<DecisionSurfaceResponse> {
+      calls.push(req);
+      return Promise.resolve(response);
+    },
+  } as unknown as EngramAccessService;
+  return { service, calls };
+}
+
+function makeMockServiceWithConfig(
+  config: CodingKnowledgeConfig,
+  codingContext: CodingContext | null,
+): EngramAccessService {
+  const pluginConfig = {
+    codingKnowledge: config,
+    codingMode: { projectScope: true },
+  } as unknown as PluginConfig;
+  const orchestrator = {
+    config: pluginConfig,
+    getCodingContextForSession: (_sk: string) => codingContext,
+  } as unknown as Orchestrator;
+  return {
+    orchestrator,
+  } as unknown as EngramAccessService;
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Gate predicate tests
+// ──────────────────────────────────────────────────────────────────────────
+
+test("gate: disabled when config.enabled is false", () => {
+  assert.equal(isDecisionRecordSurfaceEnabled(GATE_OFF_CONFIG, CODING_CONTEXT), false);
+});
+
+test("gate: disabled when decisionRecords is false", () => {
+  const cfg: CodingKnowledgeConfig = { ...GATE_ON_CONFIG, decisionRecords: false };
+  assert.equal(isDecisionRecordSurfaceEnabled(cfg, CODING_CONTEXT), false);
+});
+
+test("gate: disabled when no coding context attached", () => {
+  assert.equal(isDecisionRecordSurfaceEnabled(GATE_ON_CONFIG, null), false);
+  assert.equal(isDecisionRecordSurfaceEnabled(GATE_ON_CONFIG, undefined), false);
+});
+
+test("gate: enabled only when all three conditions hold", () => {
+  assert.equal(isDecisionRecordSurfaceEnabled(GATE_ON_CONFIG, CODING_CONTEXT), true);
+});
+
+test("visibility gate: config-only check for tools/list construction", () => {
+  assert.equal(isDecisionRecordSurfaceVisible(GATE_OFF_CONFIG), false);
+  assert.equal(isDecisionRecordSurfaceVisible(GATE_ON_CONFIG), true);
+  assert.equal(
+    isDecisionRecordSurfaceVisible({ ...GATE_ON_CONFIG, decisionRecords: false }),
+    false,
+  );
+});
+
+// ──────────────────────────────────────────────────────────────────────────
+// Subcommand validation tests
+// ──────────────────────────────────────────────────────────────────────────
+
+test("subcommand: isDecisionSubcommand accepts all valid values", () => {
+  for (const sc of DECISION_SUBCOMMANDS) {
+    assert.equal(isDecisionSubcommand(sc), true);
+  }
+});
+
+test("subcommand: isDecisionSubcommand rejects invalid values", () => {
+  assert.equal(isDecisionSubcommand("delete"), false);
+  assert.equal(isDecisionSubcommand(""), false);
+  assert.equal(isDecisionSubcommand(undefined), false);
+  assert.equal(isDecisionSubcommand(42), false);
+});
+
+test("subcommand: formatDecisionSubcommands lists all valid options", () => {
+  const formatted = formatDecisionSubcommands();
+  for (const sc of DECISION_SUBCOMMANDS) {
+    assert.ok(formatted.includes(sc), `formatted list should contain "${sc}"`);
+  }
+});
+
+// ──────────────────────────────────────────────────────────────────────────
+// Prove-fail-before: tools/list gate (rule 39)
+// ──────────────────────────────────────────────────────────────────────────
+
+test("tools/list: engram.coding_decision absent when gate off (byte-identical to main)", async () => {
+  const stub = { briefingEnabled: true } as unknown as EngramAccessService;
+  const server = new EngramMcpServer(stub, { emitLegacyTools: true });
+  const response = await server.handleRequest({
+    jsonrpc: "2.0",
+    id: 1,
+    method: "tools/list",
+  });
+  const tools = (response as { result?: { tools?: Array<{ name: string }> } }).result?.tools ?? [];
+  const names = new Set(tools.map((t) => t.name));
+  assert.equal(names.has("engram.coding_decision"), false, "tool must be absent when gate is off");
+  assert.equal(names.has("remnic.coding_decision"), false, "alias must be absent when gate is off");
+});
+
+// ──────────────────────────────────────────────────────────────────────────
+// Registry fitness: coding_decision operation is registered
+// ──────────────────────────────────────────────────────────────────────────
+
+test("registry: coding_decision operation is registered through the boundary", () => {
+  const op = getOperation("coding_decision" as OperationName);
+  assert.ok(op, "coding_decision must be registered in the operation registry");
+  assert.equal(op?.spec.name, "coding_decision");
+});
+
+// ──────────────────────────────────────────────────────────────────────────
+// Three surfaces → one service method (rule 22 spirit)
+// ──────────────────────────────────────────────────────────────────────────
+
+test("MCP surface: engram.coding_decision dispatches through the boundary to service.codingDecision", async () => {
+  const { service, calls } = makeMockService();
+  const server = new EngramMcpServer(service, { emitLegacyTools: true });
+  await server.handleRequest({
+    jsonrpc: "2.0",
+    id: 1,
+    method: "tools/call",
+    params: {
+      name: "engram.coding_decision",
+      arguments: { subcommand: "list", sessionKey: "s1" },
+    },
+  });
+  assert.equal(calls.length, 1, "service.codingDecision called exactly once");
+  assert.equal(calls[0]?.subcommand, "list");
+});
+
+test("MCP surface: remnic.coding_decision alias dispatches identically", async () => {
+  const { service, calls } = makeMockService();
+  const server = new EngramMcpServer(service, { emitLegacyTools: true });
+  await server.handleRequest({
+    jsonrpc: "2.0",
+    id: 1,
+    method: "tools/call",
+    params: {
+      name: "remnic.coding_decision",
+      arguments: { subcommand: "list", sessionKey: "s1" },
+    },
+  });
+  assert.equal(calls.length, 1);
+  assert.equal(calls[0]?.subcommand, "list");
+});
+
+test("operation handler: invalid subcommand → error listing valid options", async () => {
+  const op = getOperation("coding_decision" as OperationName);
+  assert.ok(op);
+  await assert.rejects(
+    () =>
+      op!.run(
+        { subcommand: "delete", sessionKey: "s1" },
+        { service: makeMockService().service },
+      ),
+    (err: unknown) => {
+      assert.ok(err instanceof EngramAccessInputError, "should be EngramAccessInputError");
+      const msg = (err as Error).message;
+      assert.ok(msg.includes("list"), "error lists 'list'");
+      assert.ok(msg.includes("get"), "error lists 'get'");
+      assert.ok(msg.includes("record"), "error lists 'record'");
+      assert.ok(msg.includes("supersede"), "error lists 'supersede'");
+      return true;
+    },
+  );
+});
+
+test("operation handler: record subcommand calls service with record params", async () => {
+  const { service, calls } = makeMockService({
+    subcommand: "record",
+    memoryId: "mem-1",
+    status: "proposed",
+  });
+  const op = getOperation("coding_decision" as OperationName);
+  assert.ok(op);
+  await op!.run(
+    {
+      subcommand: "record",
+      sessionKey: "s1",
+      title: "Use SQLite for graph store",
+      context: "Need a local graph store",
+      decision: "Adopt better-sqlite3",
+      consequences: "Adds native dep",
+    },
+    { service },
+  );
+  assert.equal(calls.length, 1);
+  assert.equal(calls[0]?.subcommand, "record");
+  assert.equal(calls[0]?.title, "Use SQLite for graph store");
+});
+
+test("operation handler: get subcommand with unknown id → not-found response", async () => {
+  const { service } = makeMockService({
+    subcommand: "get",
+    found: false,
+  });
+  const op = getOperation("coding_decision" as OperationName);
+  assert.ok(op);
+  const output = (await op!.run(
+    { subcommand: "get", id: "nonexistent", sessionKey: "s1" },
+    { service },
+  )) as { result: DecisionSurfaceResponse };
+  const result = output.result;
+  assert.equal(result.subcommand, "get");
+  if (result.subcommand === "get") {
+    assert.equal(result.found, false, "unknown id → explicit not-found, not empty success");
+  }
+});