@remnic/core 9.3.689 → 9.3.690

package/src/access-mcp.ts

@@ -110,6 +110,7 @@ const MCP_MIGRATED_OPERATIONS: Readonly<Record<string, OperationName>> = {
   "engram.memory_search": "memory_search",
   "engram.memory_store": "memory_store",
   "engram.coding_decision": "coding_decision",
+  "engram.coding_architecture": "coding_architecture",
 };
 
 function resolveChatGptInspectorRecallSessionKey(
@@ -324,6 +325,12 @@ export class EngramMcpServer {
    * pre-feature.
    */
   private readonly codingDecisionVisible: boolean;
+  /**
+   * Whether the `coding_architecture` tool should appear in `tools/list`.
+   * Gated on `codingKnowledge.enabled && codingKnowledge.architectureCard`
+   * (issue #1548 Track A PR 3, rule 39).
+   */
+  private readonly architectureCardVisible: boolean;
 
   constructor(
     private readonly service: EngramAccessService,
@@ -333,12 +340,14 @@ export class EngramMcpServer {
       citationsAutoDetect?: boolean;
       emitLegacyTools?: boolean;
       codingDecisionVisible?: boolean;
+      architectureCardVisible?: boolean;
     } = {},
   ) {
     this.citationsEnabled = options.citationsEnabled === true;
     this.citationsAutoDetect = options.citationsAutoDetect !== false;
     this.emitLegacyTools = options.emitLegacyTools !== false;
     this.codingDecisionVisible = options.codingDecisionVisible === true;
+    this.architectureCardVisible = options.architectureCardVisible === true;
     this.authenticatedPrincipal =
       options.principal?.trim() ||
       readEnvVar("OPENCLAW_ENGRAM_ACCESS_PRINCIPAL")?.trim() ||
@@ -1999,6 +2008,31 @@ export class EngramMcpServer {
       );
       this.tools = [...this.tools, ...codingDecisionTools];
     }
+    if (this.architectureCardVisible) {
+      const architectureTools = withToolAliases(
+        {
+          name: "engram.coding_architecture",
+          description:
+            "Get or refresh the architecture card for the session's coding namespace (issue #1548 Track A PR 3). Subcommands: get, refresh.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              subcommand: {
+                type: "string",
+                enum: ["get", "refresh"],
+                description: "Which architecture-card 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)." },
+            },
+            required: ["subcommand"],
+            additionalProperties: false,
+          },
+        },
+        this.emitLegacyTools,
+      );
+      this.tools = [...this.tools, ...architectureTools];
+    }
   }
 
   /** Get clientInfo for a specific MCP session. Returns undefined for non-MCP requests. */

package/src/access-operations.ts

@@ -25,6 +25,10 @@ import {
   type DecisionSurfaceRequest,
   type DecisionSurfaceResponse,
 } from "./coding/decision-surfaces.js";
+import {
+  type ArchitectureSurfaceRequest,
+  type ArchitectureSurfaceResponse,
+} from "./coding/architecture-surfaces.js";
 
 // ---------------------------------------------------------------------------
 // memory_get — fetch one memory by id
@@ -206,6 +210,46 @@ export const codingDecisionOperation = defineOperation<
   },
 });
 
+// ---------------------------------------------------------------------------
+// coding_architecture — architecture-card surfaces (issue #1548 Track A PR 3)
+// ---------------------------------------------------------------------------
+
+const codingArchitectureSchema = z.preprocess(
+  (data) => {
+    if (data !== null && typeof data === "object" && !Array.isArray(data)) {
+      const obj = data as Record<string, unknown>;
+      const cleaned: Record<string, unknown> = {};
+      for (const [key, value] of Object.entries(obj)) {
+        if (value !== null) cleaned[key] = value;
+      }
+      return cleaned;
+    }
+    return data;
+  },
+  z.object({
+    subcommand: z.enum(["get", "refresh"]),
+    sessionKey: z.string().optional(),
+    namespace: z.string().optional(),
+  }),
+);
+
+export type CodingArchitectureInput = ArchitectureSurfaceRequest;
+export type CodingArchitectureOutput = { result: ArchitectureSurfaceResponse };
+
+export const codingArchitectureOperation = defineOperation<
+  CodingArchitectureInput,
+  CodingArchitectureOutput
+>({
+  name: "coding_architecture",
+  description:
+    "Get or refresh the architecture card for the session's coding namespace (issue #1548 Track A PR 3).",
+  schema: codingArchitectureSchema as z.ZodType<CodingArchitectureInput>,
+  handler: async (input, ctx) => {
+    const result = await ctx.service.codingArchitecture(input, ctx.authenticatedPrincipal);
+    return { result };
+  },
+});
+
 // ---------------------------------------------------------------------------
 // Surface registration map — what each transport calls the pilot ops
 // ---------------------------------------------------------------------------
@@ -220,4 +264,5 @@ export const REGISTERED_OPERATIONS = [
   memorySearchOperation.spec.name,
   memoryStoreOperation.spec.name,
   codingDecisionOperation.spec.name,
+  codingArchitectureOperation.spec.name,
 ] as const;

package/src/access-service.ts

@@ -19,6 +19,16 @@ import {
   type DecisionSurfaceRequest,
   type DecisionSurfaceResponse,
 } from "./coding/decision-surfaces.js";
+import {
+  handleCodingArchitecture,
+  type ArchitectureSurfaceRequest,
+  type ArchitectureSurfaceResponse,
+  type ArchitectureSurfaceStorage,
+  createArchitectureVersioningHook,
+  ARCHITECTURE_CARD_TAG,
+} from "./coding/architecture-surfaces.js";
+import { buildArchitectureCard, createArchitectureCardSummariser } from "./coding/architecture-card.js";
+import { createVersion } from "./page-versioning.js";
 import { WorkStorage } from "./work/storage.js";
 import {
   exportWorkBoardMarkdown,
@@ -4485,6 +4495,56 @@ export class EngramAccessService {
     });
   }
 
+  /** Whether the coding_architecture tool should appear in tools/list (rule 39). */
+  get architectureCardSurfaceVisible(): boolean {
+    return this.orchestrator.config.codingKnowledge?.enabled === true
+      && this.orchestrator.config.codingKnowledge?.architectureCard === true;
+  }
+  /**
+   * Thin delegate — handler logic in coding/architecture-surfaces.ts (#1548 PR3).
+   * All three surfaces (MCP/HTTP/CLI) arrive here via the boundary operation.
+   * Namespace resolution uses the SAME coding-scoped path as decision records.
+   */
+  async codingArchitecture(
+    request: ArchitectureSurfaceRequest,
+    authenticatedPrincipal?: string,
+  ): Promise<ArchitectureSurfaceResponse> {
+    const resolvedConfig = this.orchestrator.config;
+    return handleCodingArchitecture(request, {
+      codingKnowledge: this.orchestrator.config.codingKnowledge,
+      getCodingContext: (sk) => this.orchestrator.getCodingContextForSession(sk),
+      resolveStorage: async (req) => {
+        const isWrite = req.subcommand === "refresh";
+        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 }) as ArchitectureSurfaceStorage;
+      },
+      buildCard: async (repoRoot) => buildArchitectureCard(repoRoot, {
+        llmSummary: this.orchestrator.config.codingKnowledge?.architectureCardLlmSummary === true,
+        summariser: createArchitectureCardSummariser(this.fallbackLlmRef ?? this.localLlmRef),
+      }),
+      versioning: createArchitectureVersioningHook(
+        resolvedConfig.versioningEnabled === true,
+        resolvedConfig.versioningMaxPerPage,
+        resolvedConfig.versioningSidecarDir,
+        resolvedConfig.memoryDir,
+        (p) => nodeFs.readFile(p, "utf-8"),
+        createVersion,
+      ),
+      throwInputError: (msg) => { throw new EngramAccessInputError(msg); },
+    });
+  }
+
   async memoryBrowse(
     request: EngramAccessMemoryBrowseRequest = {},
   ): Promise<EngramAccessMemoryBrowseResponse> {

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, codingDecisionVisible: true });
+  const server = new EngramMcpServer(stub, { emitLegacyTools: true, codingDecisionVisible: true, architectureCardVisible: 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

@@ -73,6 +73,7 @@ export const MCP_TOOLS: readonly McpToolEntry[] = [
   { tool: "memory_timeline", operation: null },
   { tool: "memory_store", operation: "memory_store" },
   { tool: "coding_decision", operation: "coding_decision" },
+  { tool: "coding_architecture", operation: "coding_architecture" },
   { tool: "suggestion_submit", operation: null },
   { tool: "entity_get", operation: null },
   { tool: "review_queue_list", operation: null },
@@ -170,6 +171,7 @@ export const HTTP_ROUTES: readonly HttpRouteEntry[] = [
   { 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/coding/architecture", operation: "coding_architecture" },
   { 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

@@ -57,6 +57,7 @@ import {
 } from "./maintenance/rebuild-memory-projection.js";
 import { rebuildObservations } from "./maintenance/rebuild-observations.js";
 import { migrateObservations } from "./maintenance/migrate-observations.js";
+import { formatNamespaceMaintenanceHealthText } from "./maintenance/namespace-maintenance-fanout.js";
 import {
   listNamespaces,
   runNamespaceMigration,
@@ -2801,6 +2802,7 @@ export async function runAccessMcpServeCliCommand(
       principal: options.principal,
       emitLegacyTools: options.emitLegacyTools,
       codingDecisionVisible: service.decisionRecordSurfaceVisible,
+      architectureCardVisible: service.architectureCardSurfaceVisible,
     });
   await server.runStdio(options.stdin ?? process.stdin, options.stdout ?? process.stdout);
   return { ok: true };
@@ -4292,6 +4294,22 @@ export function registerCli(
           }
         });
 
+      namespacesCmd
+        .command("maintenance")
+        .description(
+          "Show per-namespace maintenance status (issue #1500). Reports which namespaces were maintained, skipped, or failed for each standard job.",
+        )
+        .option("--json", "Emit machine-readable JSON only")
+        .action(async (...args: unknown[]) => {
+          const options = (args[0] ?? {}) as Record<string, unknown>;
+          const summary = await orchestrator.readNamespaceMaintenanceHealth();
+          if (reportHasMachineReadableOutput(options)) {
+            console.log(JSON.stringify(summary, null, 2));
+          } else {
+            console.log(formatNamespaceMaintenanceHealthText(summary));
+          }
+        });
+
       cmd
         .command("export")
         .description("Export Remnic memory to JSON, Markdown bundle, or SQLite")