@remnic/core 9.3.680 → 9.3.682

package/src/access-mcp.ts

@@ -9,11 +9,15 @@ import {
   type CapsuleImportRequest,
   type CapsuleListRequest,
   type DaySummaryRequest,
-  type MemoryStoreRequest,
   type SchemaName,
   type SchemaTypeFor,
   type SuggestionSubmitRequest,
 } from "./access-schema.js";
+// Importing access-operations registers the pilot boundary operations
+// (memory_get / memory_search / memory_store) as a side effect; callTool
+// dispatches migrated tools through the registry (issue #1525).
+import { getOperation, type OperationName } from "./access-boundary.js";
+import "./access-operations.js";
 import { readEnvVar } from "./runtime/env.js";
 import type { RecallDisclosure, RecallPlanMode } from "./types.js";
 import { validateBriefingFormat } from "./briefing.js";
@@ -94,6 +98,19 @@ function withToolAliases(tool: McpTool, emitLegacyTools = true): McpTool[] {
   return emitLegacyTools ? [canonicalTool, tool] : [canonicalTool];
 }
 
+/**
+ * MCP tool name (legacy `engram.*` form, since {@link toLegacyToolName}
+ * canonicalizes incoming calls) → boundary operation it dispatches through.
+ * A tool appears here once its `access-operations.ts` registration lands and
+ * its surface-local validation is deleted. The fitness test
+ * (`access-surface-catalog.test.ts`) asserts this map and the catalog agree.
+ */
+const MCP_MIGRATED_OPERATIONS: Readonly<Record<string, OperationName>> = {
+  "engram.memory_get": "memory_get",
+  "engram.memory_search": "memory_search",
+  "engram.memory_store": "memory_store",
+};
+
 function resolveChatGptInspectorRecallSessionKey(
   explicitSessionKey: string | undefined,
   authenticatedPrincipal: string | undefined,
@@ -2278,6 +2295,29 @@ export class EngramMcpServer {
   }
 
   private async callTool(name: string, args: Record<string, unknown>, effectivePrincipal?: string, mcpSessionId?: string): Promise<unknown> {
+    // Migrated operations dispatch through the access boundary (issue #1525):
+    // one registry entry owns schema validation, normalization (rules
+    // 17/28/36/48/51), and error mapping for every surface. The switch
+    // below still serves the not-yet-migrated tools. memory_store keeps its
+    // parseMcpRequest strict-keys guard (MCP transport contract) before the
+    // boundary re-validates the cleaned body.
+    const migrated = MCP_MIGRATED_OPERATIONS[toLegacyToolName(name)];
+    if (migrated) {
+      const op = getOperation(migrated);
+      if (!op) {
+        throw new EngramAccessInputError(`access-boundary: operation not registered: ${migrated}`);
+      }
+      const envelope =
+        migrated === "memory_store" ? parseMcpRequest("memoryStore", args) : args;
+      // The registry erases In/Out at the Map boundary; the caller knows the
+      // concrete output shape ({ result: <service response> }) so the cast is
+      // the type-erasure seam, not a leap of faith.
+      const output = (await op.run(envelope, {
+        service: this.service,
+        authenticatedPrincipal: effectivePrincipal,
+      })) as { result: unknown };
+      return output.result;
+    }
     switch (toLegacyToolName(name)) {
       case "engram.recall": {
         // Forward `disclosure` only when the caller actually supplied it,
@@ -2744,12 +2784,6 @@ export class EngramMcpServer {
           },
           effectivePrincipal,
         );
-      case "engram.memory_get":
-        return this.service.memoryGet(
-          typeof args.memoryId === "string" ? args.memoryId : "",
-          typeof args.namespace === "string" ? args.namespace : undefined,
-          effectivePrincipal,
-        );
       case "engram.memory_timeline": {
         const limit = typeof args.limit === "number" && Number.isFinite(args.limit) ? args.limit : 200;
         return this.service.memoryTimeline(
@@ -2759,26 +2793,6 @@ export class EngramMcpServer {
           effectivePrincipal,
         );
       }
-      case "engram.memory_store": {
-        const body: MemoryStoreRequest = parseMcpRequest("memoryStore", args);
-        return this.service.memoryStore({
-          schemaVersion: body.schemaVersion,
-          idempotencyKey: body.idempotencyKey,
-          dryRun: body.dryRun,
-          sessionKey: body.sessionKey,
-          authenticatedPrincipal: effectivePrincipal,
-          content: body.content,
-          category: body.category,
-          confidence: body.confidence,
-          namespace: body.namespace,
-          tags: body.tags,
-          entityRef: body.entityRef,
-          ttl: body.ttl,
-          sourceReason: body.sourceReason,
-          cwd: body.cwd,
-          projectTag: body.projectTag,
-        });
-      }
       case "engram.suggestion_submit": {
         const body: SuggestionSubmitRequest = parseMcpRequest("suggestionSubmit", args);
         return this.service.suggestionSubmit({
@@ -3017,14 +3031,6 @@ export class EngramMcpServer {
           expectedGuidelineVersion: typeof args.expectedGuidelineVersion === "number" ? args.expectedGuidelineVersion : undefined,
         });
       // ── Memory search & debug tools ──────────────────────────────────
-      case "engram.memory_search":
-        return this.service.memorySearch({
-          query: typeof args.query === "string" ? args.query : "",
-          namespace: typeof args.namespace === "string" ? args.namespace : undefined,
-          maxResults: typeof args.maxResults === "number" && Number.isFinite(args.maxResults) ? args.maxResults : undefined,
-          collection: typeof args.collection === "string" ? args.collection : undefined,
-          principal: effectivePrincipal,
-        });
       case "engram.memory_profile":
         return this.service.memoryProfile(
           typeof args.namespace === "string" ? args.namespace : undefined,

package/src/access-operations.ts

@@ -0,0 +1,157 @@
+/**
+ * Pilot operation definitions for the access boundary (issue #1525).
+ *
+ * Three operations migrate through the registry in this PR — `memory_get`,
+ * `memory_search`, and the `memory_store` write op — so the boundary's
+ * normalization matrix (rules 17/28/36/48/51) and shared error mapping reach
+ * MCP, HTTP, and CLI from one place. Domain-group migrations (memory ops →
+ * connectors → namespaces …) land as follow-up PRs that add `defineOperation`
+ * calls here and delete the surface-local validation they replace.
+ *
+ * Importing this module for its side effects registers the pilot operations;
+ * surfaces then dispatch via {@link getOperation} from `./access-boundary.js`.
+ */
+
+import { z } from "zod";
+
+import { defineOperation } from "./access-boundary.js";
+import { memoryStoreRequestSchema, type MemoryStoreRequest } from "./access-schema.js";
+import type {
+  EngramAccessMemoryResponse,
+  EngramAccessWriteResponse,
+} from "./access-service.js";
+
+// ---------------------------------------------------------------------------
+// memory_get — fetch one memory by id
+// ---------------------------------------------------------------------------
+
+/**
+ * `memoryId` is required and non-empty (rule 51: the MCP dispatcher previously
+ * fell back to `typeof args.memoryId === "string" ? args.memoryId : ""`,
+ * silently passing an empty id into the service). `namespace` is
+ * `.nullable().optional()` because MCP clients send `null` (gotcha #2).
+ * `namespace` has no `.min(1)` because the pre-boundary handlers forwarded
+ * empty/whitespace strings, and `resolveNamespace` treats empty identically
+ * to absent (both trim to falsy → default namespace). Rejecting empty would
+ * break HTTP callers that send a bare `?namespace=` (Cursor review).
+ */
+const memoryGetSchema = z.object({
+  memoryId: z.string().trim().min(1, "memoryId is required").max(512),
+  namespace: z.string().trim().max(256).nullable().optional(),
+});
+
+export interface MemoryGetInput {
+  readonly memoryId: string;
+  readonly namespace?: string | null;
+}
+
+export interface MemoryGetOutput {
+  readonly result: EngramAccessMemoryResponse;
+}
+
+export const memoryGetOperation = defineOperation<MemoryGetInput, MemoryGetOutput>({
+  name: "memory_get",
+  description: "Fetch one memory by id.",
+  schema: memoryGetSchema,
+  handler: async (input, ctx) => {
+    const result = await ctx.service.memoryGet(
+      input.memoryId,
+      input.namespace ?? undefined,
+      ctx.authenticatedPrincipal,
+    );
+    return { result };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// memory_search — semantic search across memories
+// ---------------------------------------------------------------------------
+
+const memorySearchSchema = z.object({
+  query: z.string().trim().min(1, "query is required").max(2048),
+  namespace: z.string().trim().max(256).nullable().optional(),
+  // No upper cap: the pre-boundary MCP handler forwarded any finite number to
+  // memorySearch, and the QMD/search backends honor large limits. Capping at
+  // 100 would reject existing clients that request larger result sets.
+  maxResults: z.number().int().min(1).nullable().optional(),
+  collection: z.string().trim().min(1).max(256).nullable().optional(),
+});
+
+export interface MemorySearchInput {
+  readonly query: string;
+  readonly namespace?: string | null;
+  readonly maxResults?: number | null;
+  readonly collection?: string | null;
+}
+
+export interface MemorySearchOutput {
+  readonly result: {
+    readonly query: string;
+    readonly results: ReadonlyArray<{ path: string; score: number; snippet: string }>;
+    readonly count: number;
+  };
+}
+
+export const memorySearchOperation = defineOperation<MemorySearchInput, MemorySearchOutput>({
+  name: "memory_search",
+  description: "Search memories across readable namespaces.",
+  schema: memorySearchSchema,
+  handler: async (input, ctx) => {
+    const result = await ctx.service.memorySearch({
+      query: input.query,
+      namespace: input.namespace ?? undefined,
+      maxResults: input.maxResults ?? undefined,
+      collection: input.collection ?? undefined,
+      principal: ctx.authenticatedPrincipal,
+    });
+    return { result };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// memory_store — the pilot WRITE op
+// ---------------------------------------------------------------------------
+
+export type MemoryStoreInput = MemoryStoreRequest;
+
+export interface MemoryStoreOutput {
+  readonly result: EngramAccessWriteResponse;
+}
+
+export const memoryStoreOperation = defineOperation<MemoryStoreInput, MemoryStoreOutput>({
+  name: "memory_store",
+  description: "Store an explicit memory through the access layer.",
+  // Reuse the existing schema verbatim — the migration is behavior-preserving;
+  // the schema's external contract is NOT changing in this PR (per the issue's
+  // pitfall note).
+  schema: memoryStoreRequestSchema,
+  handler: async (input, ctx) => {
+    const result = await ctx.service.memoryStore(
+      {
+        ...input,
+        authenticatedPrincipal: ctx.authenticatedPrincipal,
+      },
+      // Forward transport-level hooks (e.g. HTTP's atomic write-quota gate)
+      // 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 };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Surface registration map — what each transport calls the pilot ops
+// ---------------------------------------------------------------------------
+
+/**
+ * The canonical short names (no `engram.`/`remnic.` prefix) of the operations
+ * the boundary owns today. The fitness test treats this set as the migrated
+ * set; everything else on a surface is unmigrated and counted by the ratchet.
+ */
+export const REGISTERED_OPERATIONS = [
+  memoryGetOperation.spec.name,
+  memorySearchOperation.spec.name,
+  memoryStoreOperation.spec.name,
+] as const;