@remnic/core 9.3.685 → 9.3.686

package/src/access-cli.ts

@@ -11,10 +11,11 @@ import { getOperation } from "./access-boundary.js";
 // Importing access-operations registers the pilot boundary operations as a
 // side effect; the store command dispatches through the registry (issue #1525).
 import "./access-operations.js";
+import { projectTagProjectId } from "./coding/coding-namespace.js";
 
 const OPENCLAW_REMNIC_PLUGIN_IDS = ["openclaw-remnic", "openclaw-engram"] as const;
 
-type CommandName = "browse" | "store";
+type CommandName = "browse" | "store" | "decision";
 
 type ParsedArgs = {
   command: CommandName;
@@ -133,9 +134,9 @@ function writeCliOutput(text: string = ""): void {
 
 function usage(): string {
   return [
-    "Usage:",
     "  engram-access browse [options]",
     "  engram-access store [options]",
+    "  engram-access decision [options]",
     "",
     "Browse options:",
     "  --namespace <name>",
@@ -160,6 +161,21 @@ function usage(): string {
     "  --source-reason <text>",
     "  --idempotency-key <key>",
     "  --dry-run",
+    "",
+    "Decision options:",
+    "  --subcommand <list|get|record|supersede>",
+    "  --namespace <name>",
+    "  --session-key <key>",
+    "  --principal <principal>",
+    "  --id <id> (get/supersede)",
+    "  --title <title> (record/supersede)",
+    "  --status <proposed|accepted|superseded|rejected> (record)",
+    "  --context <text> (record/supersede)",
+    "  --decision <text> (record/supersede)",
+    "  --consequences <text> (record/supersede)",
+    "  --entity-ref <ref> (repeatable)",
+    "  --project-tag <tag> (attach coding context for this invocation)",
+    "  --supersedes-id <id> (alias for --id on supersede)",
   ].join("\n");
 }
 
@@ -194,8 +210,25 @@ const COMMAND_SPECS: Record<CommandName, CommandSpec> = {
     ]),
     flagOptions: new Set(["dry-run"]),
   },
+  decision: {
+    valueOptions: new Set([
+      "subcommand",
+      "namespace",
+      "session-key",
+      "principal",
+      "id",
+      "title",
+      "status",
+      "context",
+      "decision",
+      "consequences",
+      "entity-ref",
+      "project-tag",
+      "supersedes-id",
+    ]),
+    flagOptions: new Set(),
+  },
 };
-
 const BROWSE_SORT_VALUES = Object.freeze([
   "updated_desc",
   "updated_asc",
@@ -207,7 +240,7 @@ type BrowseSort = (typeof BROWSE_SORT_VALUES)[number];
 
 function parseArgs(argv: string[]): ParsedArgs {
   const [commandRaw, ...rest] = argv;
-  if (commandRaw !== "browse" && commandRaw !== "store") {
+  if (commandRaw !== "browse" && commandRaw !== "store" && commandRaw !== "decision") {
     throw new UsageError("unsupported-command");
   }
   const spec = COMMAND_SPECS[commandRaw];
@@ -466,6 +499,59 @@ function expandOptionalPath(value: string | undefined): string | undefined {
   return value === undefined ? undefined : expandTildePath(value);
 }
 
+/**
+ * Decision-record surface (issue #1548 Track A PR 2). Dispatches through the
+ * same `coding_decision` operation as the MCP tool and HTTP route — one
+ * validation boundary, three transports.
+ */
+async function runDecision(args: ParsedArgs, preferredId?: string): Promise<void> {
+  const subcommand = requireOption(args, "subcommand");
+  const { config, service } = buildRuntime(preferredId);
+  // The CLI creates a fresh Orchestrator per invocation, so the session
+  // coding-context map is empty. If --project-tag + --session-key are
+  // provided, attach a coding context BEFORE dispatching so the gate
+  // passes and project-scoped writes resolve to the right namespace
+  // (review P2).
+  const projectTag = getLastOption(args, "project-tag");
+  const sessionKey = getLastOption(args, "session-key");
+  if (projectTag && projectTag.trim().length > 0 && sessionKey && sessionKey.trim().length > 0) {
+    const projectId = projectTagProjectId(projectTag.trim());
+    service.setCodingContext({
+      sessionKey,
+      codingContext: {
+        projectId,
+        branch: null,
+        rootPath: projectId,
+        defaultBranch: null,
+      },
+    });
+  }
+  const op = getOperation("coding_decision");
+  if (!op) {
+    throw new Error("access-boundary: operation not registered: coding_decision");
+  }
+  const output = (await op.run(
+    {
+      subcommand,
+      namespace: getLastOption(args, "namespace"),
+      sessionKey,
+      id: getLastOption(args, "id"),
+      supersedesId: getLastOption(args, "supersedes-id"),
+      title: getLastOption(args, "title"),
+      status: getLastOption(args, "status"),
+      context: getLastOption(args, "context"),
+      decision: getLastOption(args, "decision"),
+      consequences: getLastOption(args, "consequences"),
+      entityRefs: getAllOptions(args, "entity-ref"),
+    },
+    {
+      service,
+      authenticatedPrincipal: getLastOption(args, "principal") ?? config.agentAccessHttp.principal,
+    },
+  )) as { result: unknown };
+  console.log(JSON.stringify(output.result, null, 2));
+}
+
 export async function main(
   argv: string[] = process.argv.slice(2),
   options: AccessCliOptions = {},
@@ -475,6 +561,10 @@ export async function main(
     await runBrowse(args, options.preferredId);
     return;
   }
+  if (args.command === "decision") {
+    await runDecision(args, options.preferredId);
+    return;
+  }
   await runStore(args, options.preferredId);
 }
 

package/src/access-http.ts

@@ -315,6 +315,7 @@ export class EngramAccessHttpServer {
       citationsEnabled: options.citationsEnabled,
       citationsAutoDetect: options.citationsAutoDetect,
       emitLegacyTools: options.emitLegacyTools,
+      codingDecisionVisible: this.service.decisionRecordSurfaceVisible,
     });
   }
 
@@ -1331,6 +1332,35 @@ export class EngramAccessHttpServer {
       return;
     }
 
+    if (req.method === "POST" && pathname === "/engram/v1/coding/decisions") {
+      // Migrated through the access boundary (issue #1525/#1548): the
+      // registry entry owns schema validation and service dispatch. HTTP
+      // resolves the request principal; the boundary re-validates the
+      // cleaned envelope. record/supersede persist decision memories, so they
+      // are gated by the same 30/min write quota as /engram/v1/memories,
+      // suggestions, and observe; list/get are pure reads and stay uncounted
+      // (review P2: apply write quotas to decision writes).
+      const body = await this.readJsonBody(req);
+      const isWriteSubcommand =
+        body.subcommand === "record" || body.subcommand === "supersede";
+      if (isWriteSubcommand) {
+        this.ensureWriteRateLimitAvailable();
+      }
+      const op = getOperation("coding_decision");
+      if (!op) {
+        throw new EngramAccessInputError("access-boundary: operation not registered: coding_decision");
+      }
+      const output = (await op.run(body, {
+        service: this.service,
+        authenticatedPrincipal: this.resolveRequestPrincipal(req),
+      })) as { result: unknown };
+      if (isWriteSubcommand) {
+        this.recordWriteRateLimitHit();
+      }
+      this.respondJson(res, 200, output.result);
+      return;
+    }
+
     if (req.method === "POST" && pathname === "/engram/v1/suggestions") {
       const body = await this.readValidatedBody(req, "suggestionSubmit");
       const request = {
@@ -2183,6 +2213,13 @@ export class EngramAccessHttpServer {
       typeof toolArgs === "object" &&
       !Array.isArray(toolArgs) &&
       (toolArgs as { dryRun?: unknown }).dryRun === true;
+    const codingDecisionWrite =
+      (toolName === "engram.coding_decision" || toolName === "remnic.coding_decision") &&
+      toolArgs !== null &&
+      typeof toolArgs === "object" &&
+      !Array.isArray(toolArgs) &&
+      ((toolArgs as { subcommand?: unknown }).subcommand === "record" ||
+        (toolArgs as { subcommand?: unknown }).subcommand === "supersede");
     const isMcpWrite =
       request.method === "tools/call" &&
       (
@@ -2210,7 +2247,8 @@ export class EngramAccessHttpServer {
             toolName === "engram.memory_action_apply" ||
             toolName === "remnic.memory_action_apply"
           )
-        )
+        ) ||
+        codingDecisionWrite
       );
     if (isMcpWrite) {
       this.ensureWriteRateLimitAvailable();

package/src/access-mcp.ts

@@ -109,6 +109,7 @@ const MCP_MIGRATED_OPERATIONS: Readonly<Record<string, OperationName>> = {
   "engram.memory_get": "memory_get",
   "engram.memory_search": "memory_search",
   "engram.memory_store": "memory_store",
+  "engram.coding_decision": "coding_decision",
 };
 
 function resolveChatGptInspectorRecallSessionKey(
@@ -304,7 +305,9 @@ export class EngramMcpServer {
    */
   private initSessionIds = new Map<string, string>();
 
-  /** Whether oai-mem-citation guidance is explicitly enabled via config. */
+  /**
+   * Whether oai-mem-citation guidance is explicitly enabled via config.
+   */
   private readonly citationsEnabled: boolean;
   /** Whether to auto-enable citations for Codex adapter connections. */
   private readonly citationsAutoDetect: boolean;
@@ -314,6 +317,13 @@ export class EngramMcpServer {
    * set false to halve the advertised `tools/list` surface.
    */
   private readonly emitLegacyTools: boolean;
+  /**
+   * Whether the `coding_decision` tool should appear in `tools/list`. Gated on
+   * `codingKnowledge.enabled && codingKnowledge.decisionRecords` (issue #1548
+   * Track A PR 2, rule 39). When false the tools array is byte-identical to
+   * pre-feature.
+   */
+  private readonly codingDecisionVisible: boolean;
 
   constructor(
     private readonly service: EngramAccessService,
@@ -322,11 +332,13 @@ export class EngramMcpServer {
       citationsEnabled?: boolean;
       citationsAutoDetect?: boolean;
       emitLegacyTools?: boolean;
+      codingDecisionVisible?: boolean;
     } = {},
   ) {
     this.citationsEnabled = options.citationsEnabled === true;
     this.citationsAutoDetect = options.citationsAutoDetect !== false;
     this.emitLegacyTools = options.emitLegacyTools !== false;
+    this.codingDecisionVisible = options.codingDecisionVisible === true;
     this.authenticatedPrincipal =
       options.principal?.trim() ||
       readEnvVar("OPENCLAW_ENGRAM_ACCESS_PRINCIPAL")?.trim() ||
@@ -1946,6 +1958,47 @@ export class EngramMcpServer {
         },
       },
     ].flatMap((tool) => withToolAliases(tool, this.emitLegacyTools));
+    if (this.codingDecisionVisible) {
+      const codingDecisionTools = withToolAliases(
+        {
+          name: "engram.coding_decision",
+          description:
+            "List, get, record, or supersede decision records in the session's coding namespace (issue #1548 Track A). Subcommands: list, get, record, supersede.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              subcommand: {
+                type: "string",
+                enum: ["list", "get", "record", "supersede"],
+                description: "Which decision-record operation to run.",
+              },
+              sessionKey: { type: "string", description: "Session identifier whose coding context scopes the operation." },
+              namespace: { type: "string", description: "Optional explicit namespace (overrides coding-context overlay)." },
+              id: { type: "string", description: "Decision record id (required for get and supersede)." },
+              title: { type: "string", description: "Decision title (required for record and supersede)." },
+              status: {
+                type: "string",
+                enum: ["proposed", "accepted", "superseded", "rejected"],
+                description: "Decision status (record only; defaults to proposed).",
+              },
+              context: { type: "string", description: "Context/background for the decision." },
+              decision: { type: "string", description: "The decision itself (required for record and supersede)." },
+              consequences: { type: "string", description: "Consequences of the decision." },
+              entityRefs: {
+                type: "array",
+                items: { type: "string" },
+                description: "Entity references the decision relates to.",
+              },
+              supersedesId: { type: "string", description: "Id of the record this decision supersedes (supersede only)." },
+            },
+            required: ["subcommand"],
+            additionalProperties: false,
+          },
+        },
+        this.emitLegacyTools,
+      );
+      this.tools = [...this.tools, ...codingDecisionTools];
+    }
   }
 
   /** Get clientInfo for a specific MCP session. Returns undefined for non-MCP requests. */

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>();