@remnic/core 9.3.684 → 9.3.686

package/dist/{chunk-3MY4W5V4.js → chunk-FUCUR2OZ.js}

@@ -58,10 +58,10 @@ import {
   listMemoryGovernanceRuns,
   readMemoryGovernanceRunArtifact,
   runMemoryGovernance
-} from "./chunk-WI7JKV2T.js";
+} from "./chunk-4N3TFFPH.js";
 import {
   namespaceCollectionName
-} from "./chunk-DQY7NJ5L.js";
+} from "./chunk-CTOQEZSN.js";
 import {
   namespaceIdentityFromToken
 } from "./chunk-ZFXCQPNO.js";
@@ -70,18 +70,18 @@ import {
 } from "./chunk-EIR5VLIH.js";
 import {
   buildGraphSnapshot
-} from "./chunk-YXWAILM4.js";
+} from "./chunk-YOI3ELXF.js";
 import {
   persistExplicitCapture,
   queueExplicitCaptureForReview,
   validateExplicitCaptureInput
-} from "./chunk-GKKAXVAJ.js";
+} from "./chunk-U33LWTQQ.js";
 import {
   wrapWorkLayerContext
 } from "./chunk-EI6V5UXY.js";
 import {
   formatProfileTraceAscii
-} from "./chunk-QY7YA7OL.js";
+} from "./chunk-PNLCEFE4.js";
 import {
   buildProcedurePersistBody,
   normalizeProcedureSteps
@@ -95,16 +95,16 @@ import {
 import {
   filterTrajectoriesByLookbackDays,
   readCausalTrajectoryRecords
-} from "./chunk-JD4SCARD.js";
+} from "./chunk-YN4ZT4CW.js";
 import {
   FileCalendarSource,
   buildBriefing,
   parseBriefingFocus,
   parseBriefingWindow
-} from "./chunk-K6ZN34WC.js";
+} from "./chunk-OV4D5T7V.js";
 import {
   parseEntityFile
-} from "./chunk-53FDU4CE.js";
+} from "./chunk-BLIWOONZ.js";
 import {
   DEFAULT_RECALL_DISCLOSURE,
   isRecallDisclosure
@@ -151,7 +151,7 @@ import {
 } from "./chunk-UZYLX7M6.js";
 import {
   log
-} from "./chunk-2ODBA7MQ.js";
+} from "./chunk-NU3CSQ4H.js";
 import {
   AccessAuditAdapter
 } from "./chunk-TVVEYCNW.js";
@@ -167,6 +167,448 @@ import { constants as fsConstants } from "fs";
 import { createHash as createHash2 } from "crypto";
 import { ZodError } from "zod";
 
+// src/coding/decision-records.ts
+var DECISION_STATUSES = [
+  "proposed",
+  "accepted",
+  "superseded",
+  "rejected"
+];
+var ACTIVE_DECISION_STATUSES = /* @__PURE__ */ new Set([
+  "proposed",
+  "accepted"
+]);
+var DEFAULT_DECISION_STATUS = "proposed";
+var DECISION_STATUS_BY_VALUE = Object.freeze({
+  proposed: "proposed",
+  accepted: "accepted",
+  superseded: "superseded",
+  rejected: "rejected"
+});
+function isDecisionStatus(value) {
+  return typeof value === "string" && Object.prototype.hasOwnProperty.call(DECISION_STATUS_BY_VALUE, value);
+}
+var FRONTMATTER_KEYS = Object.freeze([
+  "id",
+  "title",
+  "status",
+  "context",
+  "decision",
+  "consequences",
+  "entityRefs",
+  "supersedes"
+]);
+function serializeDecisionRecord(record) {
+  const lines = ["---"];
+  for (const key of FRONTMATTER_KEYS) {
+    const present = key === "supersedes" ? record.supersedes !== void 0 : key === "consequences" ? record.consequences !== void 0 : true;
+    if (!present) continue;
+    lines.push(`${key}: ${encodeFrontmatterValue(key, record)}`);
+  }
+  lines.push("---", "");
+  if (record.context) lines.push(record.context);
+  lines.push("");
+  lines.push("# Decision");
+  lines.push("");
+  if (record.decision) lines.push(record.decision);
+  if (record.consequences !== void 0 && record.consequences.length > 0) {
+    lines.push("");
+    lines.push("# Consequences");
+    lines.push("");
+    lines.push(record.consequences);
+  }
+  if (record.entityRefs.length > 0) {
+    lines.push("");
+    lines.push("# Entity references");
+    for (const ref of record.entityRefs) lines.push(`- ${ref}`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+function encodeFrontmatterValue(key, record) {
+  if (key === "entityRefs") {
+    const refs = record.entityRefs;
+    if (refs.length === 0) return "[]";
+    const inner = refs.map((ref) => `"${escapeYamlString(ref)}"`).join(", ");
+    return `[${inner}]`;
+  }
+  if (key === "status") return `"${record.status}"`;
+  if (key === "supersedes") return `"${record.supersedes ?? ""}"`;
+  if (key === "consequences") return `"${escapeYamlString(record.consequences ?? "")}"`;
+  const value = record[key];
+  return `"${escapeYamlString(typeof value === "string" ? value : String(value))}"`;
+}
+function escapeYamlString(value) {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n");
+}
+function parseDecisionRecord(raw) {
+  const { fields, body } = extractFrontmatter(raw);
+  for (const fieldKey of Object.keys(fields)) {
+    if (!FRONTMATTER_KEYS.includes(fieldKey)) {
+      throw new Error(
+        `decision record frontmatter contains unknown key '${fieldKey}'; valid keys are ${FRONTMATTER_KEYS.join(", ")}.`
+      );
+    }
+  }
+  const id = requireString(fields.id, "id");
+  const title = requireString(fields.title, "title");
+  const context = requireString(fields.context, "context");
+  const decision = requireString(fields.decision, "decision");
+  const consequences = fields.consequences === void 0 ? void 0 : requireString(fields.consequences, "consequences");
+  let status = DEFAULT_DECISION_STATUS;
+  if (fields.status !== void 0 && fields.status !== null) {
+    if (!isDecisionStatus(fields.status)) {
+      throw new Error(
+        `decision '${id}' has invalid status '${JSON.stringify(fields.status)}'; valid statuses are ${DECISION_STATUSES.join(", ")}.`
+      );
+    }
+    status = fields.status;
+  }
+  const entityRefs = parseEntityRefs(fields.entityRefs);
+  const supersedes = fields.supersedes === void 0 ? void 0 : requireString(fields.supersedes, "supersedes");
+  const record = {
+    id,
+    title,
+    status,
+    context,
+    decision,
+    consequences,
+    entityRefs,
+    ...supersedes !== void 0 ? { supersedes } : {}
+  };
+  void body;
+  return record;
+}
+function requireString(field, key) {
+  if (field === void 0 || field === null) {
+    throw new Error(`decision record frontmatter is missing required field '${key}'.`);
+  }
+  if (typeof field !== "string") {
+    throw new Error(
+      `decision record frontmatter field '${key}' must be a string; got ${JSON.stringify(field)}.`
+    );
+  }
+  return field;
+}
+function parseEntityRefs(field) {
+  if (field === void 0) return [];
+  if (!Array.isArray(field)) {
+    throw new Error(
+      `decision record frontmatter field 'entityRefs' must be an array of strings; got ${JSON.stringify(field)}.`
+    );
+  }
+  for (const entry of field) {
+    if (typeof entry !== "string") {
+      throw new Error(
+        `decision record frontmatter 'entityRefs' entries must be strings; got ${JSON.stringify(entry)}.`
+      );
+    }
+  }
+  return [...field];
+}
+function extractFrontmatter(raw) {
+  const text = raw.charCodeAt(0) === 65279 ? raw.slice(1) : raw;
+  if (!text.startsWith("---\n")) {
+    throw new Error(
+      "decision record must start with a YAML frontmatter fence (`---\\n`); got a document with no leading fence."
+    );
+  }
+  const closeAt = text.indexOf("\n---", 4);
+  if (closeAt === -1) {
+    throw new Error(
+      "decision record frontmatter is missing its closing fence (`\\n---`); the document is truncated."
+    );
+  }
+  const yamlBody = text.slice(4, closeAt);
+  const after = text.slice(closeAt + 4);
+  const body = after.startsWith("\n") ? after.slice(1) : after;
+  return { fields: parseYamlMapping(yamlBody), body };
+}
+function parseYamlMapping(input) {
+  const fields = {};
+  for (const rawLine of input.split("\n")) {
+    const line = rawLine.trimEnd();
+    if (line.length === 0 || line.startsWith("#")) continue;
+    const colonAt = line.indexOf(":");
+    if (colonAt === -1) {
+      throw new Error(`decision record frontmatter line is not a key:value pair: "${line}".`);
+    }
+    const key = line.slice(0, colonAt).trim();
+    const valueText = line.slice(colonAt + 1).trim();
+    if (key.length === 0) {
+      throw new Error(`decision record frontmatter has an empty key in line: "${line}".`);
+    }
+    fields[key] = decodeScalar(valueText);
+  }
+  return fields;
+}
+function decodeScalar(valueText) {
+  if (valueText.length === 0) return "";
+  const lower = valueText.toLowerCase();
+  if (lower === "true") return true;
+  if (lower === "false") return false;
+  if (lower === "null" || lower === "~") return null;
+  if (/^-?\d+$/.test(valueText)) return Number(valueText);
+  if (/^".*"$/.test(valueText)) {
+    return valueText.slice(1, -1).replace(/\\\\/g, "\0").replace(/\\n/g, "\n").replace(/\\"/g, '"').replace(/\u0000/g, "\\");
+  }
+  if (/^\[.*\]$/.test(valueText)) return parseFlowList(valueText);
+  return valueText;
+}
+function parseFlowList(valueText) {
+  const inner = valueText.slice(1, -1).trim();
+  if (inner.length === 0) return [];
+  const out = [];
+  let buf = "";
+  let inQuotes = false;
+  let escaped = false;
+  for (let i = 0; i < inner.length; i += 1) {
+    const c = inner[i];
+    if (escaped) {
+      buf += c;
+      escaped = false;
+      continue;
+    }
+    if (c === "\\") {
+      buf += c;
+      escaped = true;
+      continue;
+    }
+    if (c === '"') {
+      inQuotes = !inQuotes;
+      buf += c;
+      continue;
+    }
+    if (c === "," && !inQuotes) {
+      out.push(stripFlowStringQuotes(buf.trim()));
+      buf = "";
+      continue;
+    }
+    buf += c;
+  }
+  if (buf.length > 0) out.push(stripFlowStringQuotes(buf.trim()));
+  return out;
+}
+function stripFlowStringQuotes(value) {
+  if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
+    return value.slice(1, -1).replace(/\\\\/g, "\0").replace(/\\n/g, "\n").replace(/\\"/g, '"').replace(/\u0000/g, "\\");
+  }
+  return value;
+}
+
+// src/coding/decision-surfaces.ts
+var DECISION_SUBCOMMANDS = [
+  "list",
+  "get",
+  "record",
+  "supersede"
+];
+function isDecisionRecordSurfaceEnabled(config, codingContext) {
+  return config.enabled === true && config.decisionRecords === true && codingContext != null;
+}
+async function handleCodingDecision(request, ctx) {
+  const codingContext = request.sessionKey ? ctx.getCodingContext(request.sessionKey) : null;
+  if (!isDecisionRecordSurfaceEnabled(ctx.codingKnowledge, codingContext)) {
+    ctx.throwInputError(
+      "coding_decision requires codingKnowledge.enabled, codingKnowledge.decisionRecords, and an attached coding context"
+    );
+  }
+  switch (request.subcommand) {
+    case "list":
+      return decisionList(request, ctx);
+    case "get":
+      return decisionGet(request, ctx);
+    case "record":
+      return decisionRecord(request, ctx);
+    case "supersede":
+      return decisionSupersede(request, ctx);
+  }
+}
+async function decisionList(request, ctx) {
+  const storage = await ctx.resolveStorage(request);
+  const memories = await storage.readAllMemories();
+  const records = [];
+  for (const m of memories) {
+    if (m.frontmatter.category !== "decision") continue;
+    const memStatus = m.frontmatter.status;
+    if (memStatus && memStatus !== "active") continue;
+    const parsed = safeParseDecisionRecord(m.content);
+    if (!parsed) continue;
+    const structStatus = m.frontmatter.structuredAttributes?.decisionStatus;
+    const effectiveStatus = structStatus ?? parsed.status;
+    records.push({
+      id: m.frontmatter.id,
+      title: parsed.title,
+      status: effectiveStatus,
+      entityRefs: parsed.entityRefs,
+      supersedes: parsed.supersedes
+    });
+  }
+  const visible = records.filter(
+    (r) => ACTIVE_DECISION_STATUSES.has(r.status)
+  );
+  return { subcommand: "list", records: visible, count: visible.length };
+}
+async function decisionGet(request, ctx) {
+  if (!request.id?.trim()) {
+    ctx.throwInputError("id is required for the 'get' subcommand");
+  }
+  const storage = await ctx.resolveStorage(request);
+  const memory = await storage.getMemoryById(request.id);
+  if (!memory || memory.frontmatter.category !== "decision") {
+    return { subcommand: "get", found: false };
+  }
+  const parsed = safeParseDecisionRecord(memory.content);
+  if (!parsed) {
+    return { subcommand: "get", found: false };
+  }
+  const structStatus = memory.frontmatter.structuredAttributes?.decisionStatus;
+  return {
+    subcommand: "get",
+    found: true,
+    record: {
+      id: memory.frontmatter.id,
+      title: parsed.title,
+      status: structStatus ?? parsed.status,
+      context: parsed.context,
+      decision: parsed.decision,
+      consequences: parsed.consequences,
+      entityRefs: parsed.entityRefs,
+      supersedes: parsed.supersedes
+    }
+  };
+}
+async function decisionRecord(request, ctx) {
+  if (!request.title?.trim()) {
+    ctx.throwInputError("title is required for the 'record' subcommand");
+  }
+  if (!request.decision?.trim()) {
+    ctx.throwInputError("decision is required for the 'record' subcommand");
+  }
+  const status = request.status?.trim() ? isDecisionStatus(request.status) ? request.status : raiseInvalidStatus(request.status, ctx) : DEFAULT_DECISION_STATUS;
+  const record = {
+    id: "",
+    title: request.title.trim(),
+    status,
+    context: request.context?.trim() ?? "",
+    decision: request.decision.trim(),
+    consequences: request.consequences?.trim() ?? "",
+    entityRefs: request.entityRefs ?? []
+  };
+  const content = serializeDecisionRecord(record);
+  const storage = await ctx.resolveStorage(request);
+  const isActive = ACTIVE_DECISION_STATUSES.has(status);
+  const memoryId = await storage.writeMemory("decision", content, {
+    confidence: 1,
+    tags: ["decision-record"],
+    source: "coding-decision",
+    // Persist the decision lifecycle in BOTH places so generic
+    // recall/search/maintenance (which read frontmatter.status) and the
+    // decision list/get projection (which reads structuredAttributes) agree:
+    //   - structuredAttributes.decisionStatus is the authoritative decision
+    //     marker, mirrored from the serialized body (one source of truth);
+    //   - frontmatter.status is set to "archived" for inactive decisions
+    //     (rejected/superseded) so the outer memory pipeline excludes them
+    //     from the active corpus exactly like a supersede does (review P2:
+    //     persist inactive decision statuses in frontmatter).
+    structuredAttributes: { decisionStatus: status },
+    status: isActive ? void 0 : "archived"
+  });
+  log.info(
+    `access-write op=coding_decision/record memoryId=${memoryId} status=${status}`
+  );
+  return { subcommand: "record", memoryId, status };
+}
+async function decisionSupersede(request, ctx) {
+  const targetId = request.id?.trim() || request.supersedesId?.trim();
+  if (!targetId) {
+    ctx.throwInputError(
+      "id (or supersedesId) is required for the 'supersede' subcommand (the record being superseded)"
+    );
+  }
+  if (!request.title?.trim()) {
+    ctx.throwInputError(
+      "title is required for the 'supersede' subcommand (the replacement record)"
+    );
+  }
+  if (!request.decision?.trim()) {
+    ctx.throwInputError("decision is required for the 'supersede' subcommand");
+  }
+  const storage = await ctx.resolveStorage(request);
+  const oldMemory = await storage.getMemoryById(targetId);
+  if (!oldMemory || oldMemory.frontmatter.category !== "decision") {
+    ctx.throwInputError(`decision record not found: ${targetId}`);
+  }
+  const oldParsed = safeParseDecisionRecord(oldMemory.content);
+  if (!oldParsed) {
+    ctx.throwInputError(
+      `decision record is corrupted and cannot be superseded: ${targetId}`
+    );
+  }
+  const replacement = {
+    id: "",
+    title: request.title.trim(),
+    status: "accepted",
+    context: request.context?.trim() ?? "",
+    decision: request.decision.trim(),
+    consequences: request.consequences?.trim() ?? "",
+    entityRefs: request.entityRefs ?? [],
+    supersedes: targetId
+  };
+  const replacementContent = serializeDecisionRecord(replacement);
+  const replacementId = await storage.writeMemory(
+    "decision",
+    replacementContent,
+    {
+      confidence: 1,
+      tags: ["decision-record"],
+      source: "coding-decision",
+      // Mirror decisionRecord: persist structuredAttributes.decisionStatus on
+      // the replacement so list/get projection and QMD indexing see the
+      // authoritative marker (review: supersede omits decisionStatus attrs).
+      structuredAttributes: { decisionStatus: "accepted" }
+    }
+  );
+  try {
+    await storage.writeMemoryFrontmatter(oldMemory, {
+      status: "archived",
+      // Refresh the updated timestamp so the archive/supersede lifecycle event
+      // and browse/maintenance sort key reflect when the decision was retired,
+      // not when it was originally recorded (review: set updated timestamp when
+      // retiring old decisions).
+      updated: (/* @__PURE__ */ new Date()).toISOString(),
+      structuredAttributes: {
+        ...oldMemory.frontmatter.structuredAttributes ?? {},
+        decisionStatus: "superseded"
+      }
+    });
+  } catch (err) {
+    log.warn(
+      `coding_decision/supersede: replacement ${replacementId} written but old record ${targetId} status update failed \u2014 old record will still appear until retried: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  log.info(
+    `access-write op=coding_decision/supersede superseded=${targetId} replacement=${replacementId}`
+  );
+  return {
+    subcommand: "supersede",
+    supersededMemoryId: targetId,
+    replacementMemoryId: replacementId
+  };
+}
+function safeParseDecisionRecord(content) {
+  try {
+    return parseDecisionRecord(content);
+  } catch {
+    return null;
+  }
+}
+function raiseInvalidStatus(value, ctx) {
+  ctx.throwInputError(
+    `invalid decision status "${value}". Valid options: proposed, accepted, superseded, rejected`
+  );
+}
+
 // src/procedural/procedure-miner.ts
 import { createHash } from "crypto";
 import { mkdir, rm, stat } from "fs/promises";
@@ -748,48 +1190,13 @@ var EngramAccessService = class {
     }
     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".
-   */
-  async resolveCodingScopedWriteNamespace(request) {
-    const hasExplicitNamespace = typeof request.namespace === "string" && request.namespace.trim().length > 0;
-    if (hasExplicitNamespace) {
-      return this.resolveWritableNamespace(
-        request.namespace,
-        request.sessionKey,
-        request.authenticatedPrincipal
-      );
-    }
+  /** 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. */
+  async resolveCodingScopeInputs(request) {
     const hasSession = typeof request.sessionKey === "string" && request.sessionKey.length > 0;
     const codingContext = hasSession && this.orchestrator.config.namespacesEnabled && this.orchestrator.config.codingMode?.projectScope ? this.orchestrator.getCodingContextForSession(request.sessionKey) ?? await this.resolveCodingContextFromOptions(request) : null;
     const overlay = hasSession && this.orchestrator.config.namespacesEnabled && this.orchestrator.config.codingMode?.projectScope ? resolveCodingNamespaceOverlay(
@@ -807,6 +1214,27 @@ var EngramAccessService = class {
       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.
+   */
+  async resolveCodingScopedWriteNamespace(request) {
+    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 = profilePlan.writeNamespace.length > 0 && profilePlan.readNamespaces.includes(profilePlan.writeNamespace);
@@ -830,6 +1258,40 @@ var EngramAccessService = class {
     }
     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). */
+  async resolveCodingScopedReadableNamespace(request) {
+    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) {
+      const target = profilePlan.writeNamespace;
+      if (!profilePlan.readNamespaces.includes(target)) {
+        throw new EngramAccessInputError(`namespace is not readable: ${target}`);
+      }
+      return target;
+    }
+    if (!overlay) {
+      return this.resolveReadableNamespace(void 0, resolvedPrincipal);
+    }
+    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
@@ -2759,6 +3221,40 @@ var EngramAccessService = class {
       memory: this.serializeMemory(memory)
     };
   }
+  /** Whether the coding_decision tool should appear in tools/list (rule 39). */
+  get decisionRecordSurfaceVisible() {
+    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, authenticatedPrincipal) {
+    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 = {}) {
     const resolvedNamespace = this.resolveReadableNamespace(
       request.namespace,
@@ -5094,17 +5590,7 @@ ${next}`);
   get storageRef() {
     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, storageDir) {
-    this.orchestrator.recordCatalogWrite(namespace, storageDir);
-  }
+  // #1522: recordCatalogWrite removed — catalog touch handled at the storage chokepoint.
   get configRef() {
     return this.orchestrator.config;
   }
@@ -5572,6 +6058,7 @@ ${next}`);
 };
 
 export {
+  DECISION_SUBCOMMANDS,
   computeProcedureStats,
   formatProcedureStatsText,
   EngramAccessInputError,
@@ -5579,4 +6066,4 @@ export {
   shapeMemorySummary,
   EngramAccessService
 };
-//# sourceMappingURL=chunk-3MY4W5V4.js.map
+//# sourceMappingURL=chunk-FUCUR2OZ.js.map