@remnic/core 9.3.684 → 9.3.686

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> {
@@ -7646,17 +7730,7 @@ export class EngramAccessService {
     return this.orchestrator.storage;
   }
 
-  /**
-   * Best-effort catalog write touch delegate (issue #1499 sweep). HTTP/MCP
-   * surfaces resolve a per-namespace storage and write through it directly (e.g.
-   * a contradiction merge), bypassing the extraction write path that owns
-   * `markCatalogWrite`. They call this to record the write so a (possibly
-   * dynamic) namespace's `lastWriteAt` stays accurate and QMD maintenance does
-   * not miss it. Fire-and-forget and failure-tolerant on the orchestrator side.
-   */
-  recordCatalogWrite(namespace?: string, storageDir?: string): void {
-    this.orchestrator.recordCatalogWrite(namespace, storageDir);
-  }
+// #1522: recordCatalogWrite removed — catalog touch handled at the storage chokepoint.
 
   get configRef(): PluginConfig {
     return this.orchestrator.config;
@@ -8274,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 };
@@ -8999,7 +9000,7 @@ export function registerCli(
             // bypassing the extraction write path. Record it so QMD maintenance /
             // writtenSince don't miss the write. Best-effort and failure-tolerant.
             onMergedMemoryWritten: (namespace, storageDir) => {
-              orchestrator.recordCatalogWrite(namespace, storageDir);
+              // #1522: catalog touch handled at the storage chokepoint.
             },
           });
           console.log(result.message);