@remnic/core 9.3.684 → 9.3.686

package/src/coding/decision-surfaces.ts

@@ -0,0 +1,475 @@
+/**
+ * Decision-record surface contract + handler (issue #1548 Track A PR 2).
+ *
+ * Rule 39: one gate predicate, checked identically on every surface. Rule 22
+ * spirit: one implementation behind three thin wirings. The service holds
+ * only a thin delegate that builds a {@link DecisionSurfaceContext} and calls
+ * {@link handleCodingDecision}; the handler logic lives here so the
+ * access-service god file gains thin wiring only.
+ *
+ * No orchestrator imports (rule 11 — no shared mutable state). No circular
+ * dependency on access-service.ts: validation errors are thrown via
+ * `ctx.throwInputError`, which the service wires to EngramAccessInputError.
+ */
+import type { CodingKnowledgeConfig, CodingContext, MemoryFile, MemoryFrontmatter, MemoryStatus } from "../types.js";
+import {
+  ACTIVE_DECISION_STATUSES,
+  DEFAULT_DECISION_STATUS,
+  isDecisionStatus,
+  parseDecisionRecord,
+  serializeDecisionRecord,
+  type DecisionRecord,
+  type DecisionStatus,
+} from "./decision-records.js";
+import { log } from "../logger.js";
+
+// ──────────────────────────────────────────────────────────────────────────
+// Subcommands
+// ──────────────────────────────────────────────────────────────────────────
+
+export const DECISION_SUBCOMMANDS = [
+  "list",
+  "get",
+  "record",
+  "supersede",
+] as const;
+
+export type DecisionSubcommand = (typeof DECISION_SUBCOMMANDS)[number];
+
+const SUBCOMMAND_VALUES = DECISION_SUBCOMMANDS as readonly string[];
+
+/**
+ * Type guard — narrows an unknown subcommand string to the
+ * {@link DecisionSubcommand} union.
+ */
+export function isDecisionSubcommand(value: unknown): value is DecisionSubcommand {
+  return typeof value === "string" && SUBCOMMAND_VALUES.includes(value);
+}
+
+/**
+ * Human-readable subcommand list for error messages (rule 51 — list valid
+ * options so the caller can correct rather than guess).
+ */
+export function formatDecisionSubcommands(): string {
+  return DECISION_SUBCOMMANDS.join(", ");
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Gate predicate — rule 39: one predicate, identical on every surface
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * The single decision-record surface gate. Returns `true` only when:
+ *  1. `codingKnowledge.enabled` is on (the master Track A gate),
+ *  2. `codingKnowledge.decisionRecords` is on (the feature switch), AND
+ *  3. A coding context is attached (the session is project/branch scoped —
+ *     decision records live *in* the coding namespace, rule 42).
+ *
+ * Every surface — MCP `engram.coding_decision`, HTTP
+ * `POST /engram/v1/coding/decisions`, CLI `engram-access decision` — MUST call
+ * this predicate (or the handler that embeds it) before dispatching. The
+ * tool-visibility gate in the MCP constructor checks conditions 1–2 only
+ * (coding context is per-session and cannot be evaluated at construction
+ * time); the call-time gate checks all three.
+ */
+export function isDecisionRecordSurfaceEnabled(
+  config: CodingKnowledgeConfig,
+  codingContext: CodingContext | null | undefined,
+): boolean {
+  return (
+    config.enabled === true &&
+    config.decisionRecords === true &&
+    codingContext != null
+  );
+}
+
+/**
+ * Config-only visibility gate — used by the MCP constructor to decide whether
+ * to advertise `engram.coding_decision` in `tools/list`. When this returns
+ * `false` the tools array is byte-identical to pre-feature (rule 39).
+ */
+export function isDecisionRecordSurfaceVisible(
+  config: CodingKnowledgeConfig,
+): boolean {
+  return config.enabled === true && config.decisionRecords === true;
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Surface request / response shapes
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * Canonical surface request — one shape for all three transports. The
+ * `subcommand` field selects which operation runs; the remaining fields are
+ * optional depending on the subcommand.
+ *
+ * `sessionKey` identifies the session whose coding context scopes the
+ * operation. `namespace` overrides the coding-scoped namespace (same
+ * precedence as `memory_store` — explicit namespace wins).
+ */
+export interface DecisionSurfaceRequest {
+  subcommand: DecisionSubcommand;
+  sessionKey?: string;
+  namespace?: string;
+  // get / supersede
+  id?: string;
+  // record
+  title?: string;
+  status?: string;
+  context?: string;
+  decision?: string;
+  consequences?: string;
+  entityRefs?: string[];
+  // supersede
+  supersedesId?: string;
+}
+
+/**
+ * Surface response — a discriminated union on `subcommand`. Each surface
+ * serializes this to its transport-appropriate shape.
+ */
+export type DecisionSurfaceResponse =
+  | { subcommand: "list"; records: DecisionSurfaceRecord[]; count: number }
+  | { subcommand: "get"; found: boolean; record?: DecisionSurfaceRecord }
+  | { subcommand: "record"; memoryId: string; status: string }
+  | {
+      subcommand: "supersede";
+      supersededMemoryId: string;
+      replacementMemoryId: string;
+    };
+
+/**
+ * Flattened record projection surfaced to clients. Stored as markdown +
+ * frontmatter memory files (category `"decision"`) — this shape is the
+ * read-side projection, not the storage format.
+ */
+export interface DecisionSurfaceRecord {
+  id: string;
+  title: string;
+  status: string;
+  context?: string;
+  decision?: string;
+  consequences?: string;
+  entityRefs: string[];
+  supersedes?: string;
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Handler — the single implementation behind all three surfaces (rule 22)
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * Structural subset of StorageManager the decision handler reads or writes.
+ * Kept narrow so the module stays decoupled from storage.ts and is
+ * unit-testable with a stub.
+ */
+export interface DecisionSurfaceStorage {
+  readonly dir: string;
+  /** The resolved namespace — used for catalog write recording. */
+  readonly namespace: string;
+  readAllMemories(): Promise<readonly MemoryFile[]>;
+  getMemoryById(id: string): Promise<MemoryFile | null>;
+  writeMemory(
+    category: "decision",
+    content: string,
+    options: {
+      confidence?: number;
+      tags?: string[];
+      source?: string;
+      /** Outer memory lifecycle status — set to "archived" for inactive
+       *  decisions so generic recall/search/maintenance exclude them
+       *  (review P2: persist inactive decision statuses in frontmatter). */
+      status?: MemoryStatus;
+      /** Decision-specific lifecycle marker, mirrored from the serialized
+       *  body so the list/get projection has one authoritative source. */
+      structuredAttributes?: Record<string, string>;
+    },
+  ): Promise<string>;
+  writeMemoryFrontmatter(
+    memory: MemoryFile,
+    patch: Partial<MemoryFrontmatter>,
+  ): Promise<unknown>;
+}
+
+/**
+ * Dependencies the handler borrows from the service. The service constructs
+ * this context per call; the handler never touches the orchestrator directly.
+ * `throwInputError` lets the handler raise the surface-appropriate error
+ * class without importing access-service.ts (no circular dependency).
+ */
+export interface DecisionSurfaceContext {
+  readonly codingKnowledge: CodingKnowledgeConfig;
+  getCodingContext(sessionKey: string): CodingContext | null;
+  /** Resolve storage through the SAME namespace path as memory_store
+   *  (principal ACL + coding overlay + default fallback). The #1522 storage
+   *  chokepoint records the catalog write automatically on every
+   *  storage.writeMemory, so the handler does NOT touch the catalog itself. */
+  resolveStorage(request: DecisionSurfaceRequest): Promise<DecisionSurfaceStorage>;
+  /** Throw the surface-appropriate input-validation error. */
+  throwInputError(message: string): never;
+}
+
+/**
+ * The single shared implementation behind the MCP, HTTP, and CLI
+ * decision-record surfaces. All three transports dispatch through the
+ * `coding_decision` boundary operation, which calls this function via the
+ * service delegate.
+ *
+ * Gate (rule 39): `codingKnowledge.enabled + decisionRecords + coding
+ * context`. Persistence (rule 43): records are written through the storage
+ * manager's normal persist pipeline with category `"decision"` — no direct
+ * `fs` writes of memory content. Supersede (rule 25): the replacement is
+ * written BEFORE the old record's `structuredAttributes.decisionStatus` is
+ * set to `"superseded"` — the structuredAttribute is the authoritative
+ * lifecycle marker; content is never rewritten.
+ */
+export async function handleCodingDecision(
+  request: DecisionSurfaceRequest,
+  ctx: DecisionSurfaceContext,
+): Promise<DecisionSurfaceResponse> {
+  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: DecisionSurfaceRequest,
+  ctx: DecisionSurfaceContext,
+): Promise<DecisionSurfaceResponse> {
+  const storage = await ctx.resolveStorage(request);
+  const memories = await storage.readAllMemories();
+  const records: DecisionSurfaceRecord[] = [];
+  for (const m of memories) {
+    if (m.frontmatter.category !== "decision") continue;
+    // Exclude lifecycle-retired memories. Any outer frontmatter.status other
+    // than undefined/"active" (archived, superseded, forgotten, rejected,
+    // quarantined, pending_review) means the generic memory lifecycle has
+    // intervened — hide the decision until that resolves. The decision-specific
+    // lifecycle marker lives in structuredAttributes.decisionStatus (review:
+    // hide all non-active outer statuses from decisions).
+    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 as DecisionStatus),
+  );
+  return { subcommand: "list", records: visible, count: visible.length };
+}
+
+async function decisionGet(
+  request: DecisionSurfaceRequest,
+  ctx: DecisionSurfaceContext,
+): Promise<DecisionSurfaceResponse> {
+  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: DecisionSurfaceRequest,
+  ctx: DecisionSurfaceContext,
+): Promise<DecisionSurfaceResponse> {
+  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: DecisionStatus = request.status?.trim()
+    ? isDecisionStatus(request.status)
+      ? request.status
+      : raiseInvalidStatus(request.status, ctx)
+    : DEFAULT_DECISION_STATUS;
+  const record: DecisionRecord = {
+    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.0,
+    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 ? undefined : "archived",
+  });
+  log.info(
+    `access-write op=coding_decision/record memoryId=${memoryId} status=${status}`,
+  );
+  return { subcommand: "record", memoryId, status };
+}
+
+async function decisionSupersede(
+  request: DecisionSurfaceRequest,
+  ctx: DecisionSurfaceContext,
+): Promise<DecisionSurfaceResponse> {
+  // The schema advertises `supersedesId` for MCP/HTTP clients that name it
+  // explicitly; treat it as an alias for `id` when `id` is absent (review P2).
+  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}`,
+    );
+  }
+  // Rule 25: write the replacement BEFORE mutating the old record's status.
+  const replacement: DecisionRecord = {
+    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.0,
+      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" },
+    },
+  );
+  // Mark the old record superseded: set BOTH frontmatter.status (so
+  // recall/search/maintenance exclude it from the active corpus — review P2)
+  // AND structuredAttributes.decisionStatus (the decision-specific lifecycle
+  // marker used by list/get projection). The content body is not mutated.
+  // Rule 25: the replacement is written BEFORE the old record is mutated so
+  // a frontmatter-write failure leaves a harmless duplicate, not a missing
+  // record. Best-effort: log the failure but don't roll back the replacement
+  // (review: cursor partial-write thread).
+  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: 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 — 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,
+  };
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Local helpers
+// ──────────────────────────────────────────────────────────────────────────
+
+function safeParseDecisionRecord(content: string): DecisionRecord | null {
+  try {
+    return parseDecisionRecord(content);
+  } catch {
+    return null;
+  }
+}
+
+function raiseInvalidStatus(value: string, ctx: DecisionSurfaceContext): never {
+  ctx.throwInputError(
+    `invalid decision status "${value}". Valid options: proposed, accepted, superseded, rejected`,
+  );
+}

package/src/explicit-capture.ts

@@ -435,15 +435,8 @@ export async function persistExplicitCapture(
     expiresAt: candidate.expiresAt,
     source: source === "inline" ? "explicit-inline" : "explicit",
   });
-  // Record the catalog write touch (issue #1499, round 5 codex P2). Explicit
-  // captures bypass the extraction write path, so without this their namespace
-  // never updates `lastWriteAt`. An undefined namespace means the DEFAULT root
-  // (round 6, codex P2), which recordCatalogWrite resolves. The method is an
-  // optional best-effort hook — guard so Orchestrator-like callers without it
-  // don't break (rule #33). Best-effort and failure-tolerant.
-  if (typeof orchestrator.recordCatalogWrite === "function") {
-    orchestrator.recordCatalogWrite(resolvedNamespace, storage.dir);
-  }
+  // #1522: catalog touch handled at the storage chokepoint — the StorageManager's
+  // post-write hook records the namespace touch automatically.
 
   const created = new Date().toISOString();
   const event: MemoryLifecycleEvent = {
@@ -559,9 +552,7 @@ export async function queueExplicitCaptureForReview(
     // `writeMemory` returns an id. If the later pending-review frontmatter update
     // fails, the memory file is still durable and must not disappear from
     // writtenSince/maintenance scheduling. Guarded optional hook (rule #33).
-    if (typeof orchestrator.recordCatalogWrite === "function") {
-      orchestrator.recordCatalogWrite(queueNamespace, storage.dir);
-    }
+    // #1522: catalog touch handled at the storage chokepoint.
   }
   const event: MemoryLifecycleEvent = {
     eventId: `mle-${randomUUID()}`,

package/src/logger.ts

@@ -15,11 +15,20 @@ const NOOP_LOGGER: LoggerBackend = {
 let _backend: LoggerBackend = NOOP_LOGGER;
 let _debug = false;
 
+// Late-bind console.* rather than capturing references at module import
+// time. In production this is behaviour-identical to the pre-bound
+// `.bind(console)` form — `console.info(msg, ...)` resolves `this` to
+// `console` whether called directly or via an arrow wrapper — but it lets
+// harnesses that swap console methods (e.g. runCli in @remnic/cli) route
+// logger output through their capture sinks. With the old pre-bound form,
+// any command that called initLogger() pinned the logger to the original
+// console methods before the harness could swap them, so log.warn /
+// log.info output escaped the capture buffer.
 const CONSOLE_LOGGER: LoggerBackend = {
-  info: console.info.bind(console),
-  warn: console.warn.bind(console),
-  error: console.error.bind(console),
-  debug: console.debug.bind(console),
+  info: (msg, ...args) => console.info(msg, ...args),
+  warn: (msg, ...args) => console.warn(msg, ...args),
+  error: (msg, ...args) => console.error(msg, ...args),
+  debug: (msg, ...args) => console.debug(msg, ...args),
 };
 
 export function initLogger(backend?: LoggerBackend, debug?: boolean): void {

package/src/namespaces/catalog.test.ts

@@ -539,7 +539,7 @@ test("register does not overwrite prior discoveredBy on an existing record", asy
 
 // A record first PRE-REGISTERED via the router's onResolve hook (config) is
 // UPGRADED to "write" by a later real write touch (round 6, codex P2 — NBPmT):
-// `storageFor()` fires registerResolved (config) before recordCatalogWrite runs,
+// `storageFor()` fires registerResolved (config) before the storage chokepoint runs,
 // so without the upgrade `listNamespaces({ discoveredBy: "write" })` would miss a
 // genuinely-written namespace. A non-write touch (read/register) still preserves
 // provenance.
@@ -689,7 +689,7 @@ test("chunked write path contract: markWrite updates lastWriteAt for the namespa
     const ns = "project-origin-chunked";
     const storageDir = path.join(memoryDir, "namespaces", namespaceIdentityToken(ns));
     // This is exactly the call the orchestrator chunked branch now makes
-    // (markCatalogWrite -> markWrite with discoveredBy "write" + storageDir).
+    // (storage chokepoint -> markWrite with discoveredBy "write" + storageDir).
     await catalog.markWrite(ns, { discoveredBy: "write", storageDir });
     const record = await catalog.getNamespaceRecord(ns);
     assert.ok(record?.lastWriteAt, "chunked write must update lastWriteAt");

package/src/namespaces/storage.ts

@@ -5,6 +5,7 @@ import { StorageManager } from "../storage.js";
 import type { PluginConfig } from "../types.js";
 import { ALL_CATEGORY_DIRS } from "../utils/category-dir.js";
 import { namespaceIdentityToken, normalizeNamespaceIdentity } from "./identity.js";
+import type { NamespaceCatalog } from "./catalog.js";
 
 async function exists(p: string): Promise<boolean> {
   try {
@@ -228,6 +229,9 @@ export class NamespaceStorageRouter {
   // `whenResolveHooksSettled`). Entries are removed as each hook settles, so the
   // set holds at most one promise per concurrently-resolving namespace.
   private readonly pendingResolveHooks = new Set<Promise<unknown>>();
+  // Pending post-write catalog touch promises (#1522). Like pendingResolveHooks,
+  // lets tests await fire-and-forget write touches deterministically.
+  private readonly pendingWriteTouches = new Set<Promise<unknown>>();
 
   // Normalized (trimmed) default namespace identity (NH-FH). `storageFor`
   // normalizes its input, so default-namespace branches must compare against the
@@ -238,6 +242,8 @@ export class NamespaceStorageRouter {
   constructor(
     private readonly config: PluginConfig,
     private readonly hooks: NamespaceStorageRouterHooks = {},
+    /** Catalog reference for post-write/read touches (issue #1522 chokepoint). */
+    private readonly catalog?: NamespaceCatalog,
   ) {
     this.defaultNamespaceIdentity = normalizeNamespaceIdentity(config.defaultNamespace);
   }
@@ -288,6 +294,9 @@ export class NamespaceStorageRouter {
     // (used by extraction and shared-promotion paths) strip citations consistently,
     // matching the behaviour of the primary this.storage instance in the orchestrator.
     sm.citationTemplate = this.config.inlineSourceAttributionFormat;
+    // #1522: install the post-write catalog touch at the chokepoint — every
+    // successful write on this StorageManager records the namespace touch.
+    this.bindCatalogWriteHook(sm, ns);
     this.cache.set(ns, sm);
     this.notifyResolved(ns, root);
     return sm;
@@ -369,6 +378,78 @@ export class NamespaceStorageRouter {
     }
   }
 
+  /**
+   * Install the post-write catalog touch hook on an externally-constructed
+   * StorageManager (issue #1522). Used by the orchestrator for the legacy
+   * default-namespace storage (`this.storage`) that bypasses the router.
+   */
+  bindCatalogWriteHook(sm: StorageManager, namespace: string): void {
+    sm.onCatalogWrite = () => this.touchCatalogWrite(namespace, sm.dir);
+  }
+
+  /**
+   * Post-write catalog touch (issue #1522 chokepoint). Called by every
+   * StorageManager's post-write hook AFTER a successful write. Best-effort
+   * and failure-tolerant — a catalog error MUST NOT affect the primary write
+   * (gotcha #13, rule #40). Fire-and-forget by design.
+   */
+  private touchCatalogWrite(namespace: string, storageDir: string): void {
+    if (!this.catalog) return;
+    const touch = this.catalog
+      .markWrite(namespace, { discoveredBy: "write", storageDir })
+      .catch(() => undefined);
+    this.pendingWriteTouches.add(touch);
+    void touch.then(
+      () => { this.pendingWriteTouches.delete(touch); },
+      () => { this.pendingWriteTouches.delete(touch); },
+    );
+  }
+
+  /**
+   * Record a namespace read in the catalog (issue #1522 chokepoint move).
+   * Best-effort and failure-tolerant. Used by recall paths so the read touch
+   * lives in the storage layer, not at the caller.
+   */
+  recordRead(namespace: string, storageDir?: string): void {
+    if (!this.catalog) return;
+    const ns = normalizeNamespaceIdentity(namespace || this.config.defaultNamespace);
+    void this.catalog
+      .markRead(ns, { discoveredBy: "read", storageDir })
+      .catch(() => undefined);
+  }
+  /**
+   * Record a namespace write touch in the catalog (issue #1522). Best-effort
+   * and failure-tolerant. Used by consolidation/cleanup passes that may mutate
+   * the store via delete-only paths (e.g. entity-file merges, TTL cleanup) so
+   * the namespace's lastWriteAt stays fresh even when no explicit write went
+   * through the storage chokepoint. This is NOT a substitute for the chokepoint
+   * — it's a belt-and-suspenders for paths the chokepoint doesn't cover.
+   */
+  recordWrite(namespace: string, storageDir?: string): void {
+    if (!this.catalog) return;
+    const ns = normalizeNamespaceIdentity(namespace || this.config.defaultNamespace);
+    const touch = this.catalog
+      .markWrite(ns, { discoveredBy: "write", storageDir })
+      .catch(() => undefined);
+    this.pendingWriteTouches.add(touch);
+    void touch.then(
+      () => { this.pendingWriteTouches.delete(touch); },
+      () => { this.pendingWriteTouches.delete(touch); },
+    );
+  }
+
+  /**
+   * Resolve once every in-flight post-write catalog touch has settled (#1522).
+   * Mirrors `whenResolveHooksSettled()`: the StorageManager's post-write hook
+   * fires the catalog touch fire-and-forget, so tests asserting lastWriteAt
+   * moved should await this instead of racing a timer.
+   */
+  async whenWriteTouchesSettled(): Promise<void> {
+    while (this.pendingWriteTouches.size > 0) {
+      await Promise.allSettled([...this.pendingWriteTouches]);
+    }
+  }
+
   /**
    * Resolve once every in-flight `onResolve` registration has settled.
    *