@remnic/core 9.3.679 → 9.3.681

package/src/access-boundary.ts

@@ -0,0 +1,235 @@
+/**
+ * Single input-validation and error boundary for the CLI/MCP/HTTP access
+ * surfaces (issue #1525, epic #1520 Phase 1).
+ *
+ * Every operation that crosses the access-service facade passes through ONE
+ * registry entry: a zod-validated request envelope, a shared error mapper,
+ * and the "reject invalid input and list valid options" behavior that
+ * CLAUDE.md rules 14/17/24/28/36/48/51 previously had to be re-implemented
+ * per handler. The three surfaces become thin adapters — one operation
+ * definition, three transports — so a validation fix lands everywhere at
+ * once.
+ *
+ * Host-agnostic (rule 31): operation names carry no `openclaw-*`/`engram-*`
+ * prefix. Session/namespace tenancy stays in the handler layer (resolved via
+ * ScopePlan #1521); the boundary validates SHAPE, not tenancy.
+ */
+
+import { z } from "zod";
+import { EngramAccessInputError, type EngramAccessService } from "./access-service.js";
+import { expandTildePath } from "./utils/path.js";
+
+// ---------------------------------------------------------------------------
+// Canonical operation names — host-agnostic (rule 31)
+// ---------------------------------------------------------------------------
+
+/**
+ * Canonical operation ids. One id is shared by the MCP tool, the HTTP route,
+ * and the CLI command that expose the same operation. Add to this union as
+ * each domain-group migration PR (memory ops → connectors → namespaces …)
+ * lands; the fitness test in `access-surface-catalog.test.ts` treats the
+ * registered set as the migration state.
+ */
+export type OperationName =
+  | "memory_get"
+  | "memory_search"
+  | "memory_store";
+
+// ---------------------------------------------------------------------------
+// Operation context — what every handler receives
+// ---------------------------------------------------------------------------
+
+/**
+ * Per-call context. `service` is the facade the handler delegates to; the
+ * boundary never reaches past it. `authenticatedPrincipal` is resolved by
+ * the SURFACE (MCP header / HTTP identity / CLI flag) before the boundary
+ * runs, so handlers stay principal-source-agnostic. `hooks` carries
+ * transport-level callbacks (e.g. HTTP write-quota enforcement) that must
+ * fire atomically inside the service call; surfaces that have no such hook
+ * leave it undefined.
+ */
+export interface OperationContext {
+  readonly service: EngramAccessService;
+  readonly authenticatedPrincipal?: string;
+  readonly hooks?: OperationHooks;
+}
+
+/**
+ * Transport-level callbacks a handler forwards into the service call. Kept
+ * narrow on purpose: the boundary owns validation + dispatch shape, not
+ * transport policy. Add fields here only when a surface genuinely needs a
+ * callback the service itself consumes.
+ */
+export interface OperationHooks {
+  /** HTTP write-quota gate; throws to reject the write when exhausted. */
+  readonly enforceWriteQuota?: () => void | Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Operation spec + bound operation
+// ---------------------------------------------------------------------------
+
+export interface OperationSpec<In, Out> {
+  /** Canonical operation id; matches an {@link OperationName}. */
+  readonly name: OperationName;
+  readonly description: string;
+  /** Zod schema validating the raw request envelope. */
+  readonly schema: z.ZodType<In>;
+  /** Handler invoked with the parsed input; throws EngramAccessInputError for domain faults. */
+  readonly handler: (input: In, ctx: OperationContext) => Promise<Out>;
+}
+
+export interface BoundOperation<In = unknown, Out = unknown> {
+  readonly spec: OperationSpec<In, Out>;
+  /** Validate the raw envelope, then invoke the handler. Throws EngramAccessInputError on any validation failure. */
+  readonly run: (rawInput: unknown, ctx: OperationContext) => Promise<Out>;
+}
+
+// ---------------------------------------------------------------------------
+// Shared normalizers the boundary owns (rules 17, 28, 36, 48, 51)
+// ---------------------------------------------------------------------------
+
+/**
+ * Coerce boolean-like strings at the edge (rule 36). Accepts actual booleans
+ * and the string spellings clients send ("true"/"false"/"1"/"0"/"yes"/"no"/
+ * "on"/"off", case-insensitive). Rejects anything else loudly — `Boolean("false")`
+ * would silently be `true`, which is the bug rule 36 exists to prevent.
+ *
+ * `undefined`/`null`/`""` → `undefined`, so callers can keep treating an
+ * absent flag as "use the default" without a separate presence check.
+ */
+export function coerceBooleanLike(value: unknown): boolean | undefined {
+  if (value === undefined || value === null || value === "") return undefined;
+  if (typeof value === "boolean") return value;
+  if (typeof value === "string") {
+    const lower = value.trim().toLowerCase();
+    if (lower === "true" || lower === "1" || lower === "yes" || lower === "on") return true;
+    if (lower === "false" || lower === "0" || lower === "no" || lower === "off") return false;
+  }
+  throw new EngramAccessInputError(
+    `expected a boolean-like value (true|false|1|0|yes|no|on|off); got ${JSON.stringify(value)}`,
+  );
+}
+
+/**
+ * Coerce + validate a positive integer from a numeric string or number
+ * (rule 28). Loosely-typed MCP/CLI clients send `"5"`; `typeof saved === "number"`
+ * on read-back would reject it later, so we coerce at the edge and reject
+ * booleans/objects loudly (`Number(true) === 1` would silently pass otherwise).
+ *
+ * `undefined`/`null`/`""` → `undefined`.
+ */
+export function coercePositiveInteger(value: unknown, label: string): number | undefined {
+  if (value === undefined || value === null || value === "") return undefined;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value) || value <= 0 || !Number.isInteger(value)) {
+      throw new EngramAccessInputError(`${label} expects a positive integer; got ${JSON.stringify(value)}`);
+    }
+    return value;
+  }
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    if (!/^[+-]?\d+$/.test(trimmed)) {
+      throw new EngramAccessInputError(`${label} expects a positive integer; got ${JSON.stringify(value)}`);
+    }
+    const parsed = Number(trimmed);
+    if (!Number.isSafeInteger(parsed) || parsed <= 0) {
+      throw new EngramAccessInputError(`${label} expects a positive integer; got ${JSON.stringify(value)}`);
+    }
+    return parsed;
+  }
+  throw new EngramAccessInputError(`${label} expects a positive integer; got ${JSON.stringify(value)}`);
+}
+
+/**
+ * Expand `~` in a path-shaped input (rule 17). Node `fs` does NOT expand `~`;
+ * ad-hoc regex drifts. `undefined`/`null`/`""` → `undefined`.
+ */
+export function normalizeOptionalPath(value: unknown): string | undefined {
+  if (value === undefined || value === null || value === "") return undefined;
+  if (typeof value !== "string") {
+    throw new EngramAccessInputError(`expected a path string; got ${JSON.stringify(value)}`);
+  }
+  return expandTildePath(value);
+}
+
+// ---------------------------------------------------------------------------
+// Error formatting — rule 51: list valid options, never silently default
+// ---------------------------------------------------------------------------
+
+/**
+ * Turn a zod failure into an {@link EngramAccessInputError} whose message
+ * names the offending field and — for enum/union issues — lists the valid
+ * options, so the caller can correct rather than guess (rule 51).
+ */
+export function formatZodIssues(error: z.ZodError): string {
+  const parts: string[] = [];
+  for (const issue of error.issues) {
+    const path = issue.path.length > 0 ? issue.path.join(".") : "(root)";
+    const options = enumOptionsFromIssue(issue);
+    const suffix = options ? `. Valid: ${options.join(", ")}` : "";
+    parts.push(`${path}: ${issue.message}${suffix}`);
+  }
+  return parts.length > 0
+    ? `request validation failed: ${parts.join("; ")}`
+    : "request validation failed";
+}
+
+function enumOptionsFromIssue(issue: z.ZodIssue): readonly string[] | undefined {
+  // zod exposes accepted enum values on the issue for ZodEnum / ZodNativeEnum
+  // and on the options of invalid_union discriminators. Reading them here
+  // keeps "list valid options" in ONE place rather than per handler.
+  if (issue.code === z.ZodIssueCode.invalid_enum_value) {
+    const rawOptions = (issue as { options?: unknown }).options;
+    if (Array.isArray(rawOptions)) {
+      return rawOptions.map((opt) => String(opt));
+    }
+  }
+  return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+
+const registry = new Map<OperationName, BoundOperation>();
+
+/**
+ * Register an operation. Throws if the name is already registered — duplicate
+ * registration is a programming error, not a runtime input fault, so it throws
+ * a plain Error (not the input-error class surfaces translate for clients).
+ */
+export function defineOperation<In, Out>(spec: OperationSpec<In, Out>): BoundOperation<In, Out> {
+  if (registry.has(spec.name)) {
+    throw new Error(`access-boundary: operation already registered: ${spec.name}`);
+  }
+  const bound: BoundOperation<In, Out> = {
+    spec,
+    run: async (rawInput, ctx) => {
+      const parseResult = spec.schema.safeParse(rawInput);
+      if (!parseResult.success) {
+        throw new EngramAccessInputError(formatZodIssues(parseResult.error));
+      }
+      return spec.handler(parseResult.data, ctx);
+    },
+  };
+  // Store under the canonical name; the cast is safe because In/Out are
+  // erased at the registry boundary and recovered by callers via getOperation.
+  registry.set(spec.name, bound as unknown as BoundOperation);
+  return bound;
+}
+
+/** Look up a registered operation by canonical name. */
+export function getOperation(name: OperationName): BoundOperation | undefined {
+  return registry.get(name);
+}
+
+/** All registered operation names. */
+export function listRegisteredOperations(): readonly OperationName[] {
+  return [...registry.keys()];
+}
+
+/** Test-only: clear the registry so pilot definitions can be re-registered. */
+export function __resetRegistryForTest(): void {
+  registry.clear();
+}

package/src/access-cli.ts

@@ -7,6 +7,10 @@ import { EngramAccessService } from "./access-service.js";
 import { readEnvVar, resolveHomeDir } from "./runtime/env.js";
 import { resolvePluginEntry } from "./plugin-entry-resolver.js";
 import { expandTildePath } from "./utils/path.js";
+import { getOperation } from "./access-boundary.js";
+// Importing access-operations registers the pilot boundary operations as a
+// side effect; the store command dispatches through the registry (issue #1525).
+import "./access-operations.js";
 
 const OPENCLAW_REMNIC_PLUGIN_IDS = ["openclaw-remnic", "openclaw-engram"] as const;
 
@@ -428,21 +432,34 @@ async function runStore(args: ParsedArgs, preferredId?: string): Promise<void> {
   };
 
   const { config, service } = buildRuntime(preferredId);
-  const result = await service.memoryStore({
-    namespace: storeArgs.namespace,
-    sessionKey: storeArgs.sessionKey,
-    authenticatedPrincipal: getLastOption(args, "principal") ?? config.agentAccessHttp.principal,
-    content: storeArgs.content,
-    category: storeArgs.category,
-    confidence: storeArgs.confidence,
-    tags: storeArgs.tags,
-    entityRef: storeArgs.entityRef,
-    ttl: storeArgs.ttl,
-    sourceReason: storeArgs.sourceReason,
-    idempotencyKey: storeArgs.idempotencyKey,
-    dryRun: storeArgs.dryRun,
-  });
-  console.log(JSON.stringify(result, null, 2));
+  // Migrated through the access boundary (issue #1525): the store command
+  // dispatches through the same registry entry as the MCP tool and HTTP
+  // route, so validation/normalization is owned in ONE place. The CLI has no
+  // write-quota hook (it is a one-shot process), so no hooks are forwarded.
+  const op = getOperation("memory_store");
+  if (!op) {
+    throw new Error("access-boundary: operation not registered: memory_store");
+  }
+  const output = (await op.run(
+    {
+      namespace: storeArgs.namespace,
+      sessionKey: storeArgs.sessionKey,
+      content: storeArgs.content,
+      category: storeArgs.category,
+      confidence: storeArgs.confidence,
+      tags: storeArgs.tags,
+      entityRef: storeArgs.entityRef,
+      ttl: storeArgs.ttl,
+      sourceReason: storeArgs.sourceReason,
+      idempotencyKey: storeArgs.idempotencyKey,
+      dryRun: storeArgs.dryRun,
+    },
+    {
+      service,
+      authenticatedPrincipal: getLastOption(args, "principal") ?? config.agentAccessHttp.principal,
+    },
+  )) as { result: unknown };
+  console.log(JSON.stringify(output.result, null, 2));
 }
 
 function expandOptionalPath(value: string | undefined): string | undefined {

package/src/access-http.ts

@@ -7,7 +7,7 @@ import path from "node:path";
 import { fileURLToPath, URL } from "node:url";
 import { gunzipSync } from "node:zlib";
 import { log } from "./logger.js";
-import { EngramAccessInputError, type EngramAccessService } from "./access-service.js";
+import { EngramAccessInputError, type EngramAccessService, type EngramAccessMemoryResponse, type EngramAccessWriteResponse } from "./access-service.js";
 import { WearablesInputError } from "./wearables/errors.js";
 import { EngramMcpServer } from "./access-mcp.js";
 import { validateRequest, type SchemaName, type SchemaTypeFor } from "./access-schema.js";
@@ -27,6 +27,11 @@ import {
 } from "./graph-events.js";
 import { expandTildePath } from "./utils/path.js";
 import { projectTagProjectId } from "./coding/coding-namespace.js";
+import { getOperation } from "./access-boundary.js";
+// Importing access-operations registers the pilot boundary operations
+// (memory_get / memory_store) as a side effect; the HTTP handlers below
+// dispatch the migrated routes through the registry (issue #1525).
+import "./access-operations.js";
 
 export interface EngramAccessHttpServerOptions {
   service: EngramAccessService;
@@ -1297,35 +1302,28 @@ export class EngramAccessHttpServer {
     }
 
     if (req.method === "POST" && pathname === "/engram/v1/memories") {
+      // Migrated through the access boundary (issue #1525): the registry
+      // entry owns schema validation, normalization, and service dispatch.
+      // The HTTP transport resolves the request-scoped namespace and principal
+      // BEFORE the boundary re-validates the cleaned envelope. The write-quota
+      // hook is forwarded via ctx.hooks so it still fires atomically inside
+      // the service's idempotent-write lock — never before, never on a replay
+      // (#1434 invariant preserved by the boundary migration).
       const body = await this.readValidatedBody(req, "memoryStore");
-      const request = {
-        schemaVersion: body.schemaVersion,
-        idempotencyKey: body.idempotencyKey,
-        dryRun: body.dryRun === true,
-        sessionKey: body.sessionKey,
-        authenticatedPrincipal: this.resolveRequestPrincipal(req),
-        content: body.content,
-        category: body.category,
-        confidence: body.confidence,
+      const envelope = {
+        ...body,
         namespace: this.resolveNamespace(req, body.namespace),
-        tags: body.tags,
-        entityRef: body.entityRef,
-        ttl: body.ttl,
-        sourceReason: body.sourceReason,
-        cwd: body.cwd,
-        projectTag: body.projectTag,
       };
-      // Rate-limit enforcement is SOLELY authoritative inside memoryStore via
-      // enforceWriteQuota: it runs atomically with the real idempotency-miss
-      // determination (and the real resolved namespace), and is never invoked
-      // for a replay. We deliberately do NOT pre-check here: the write namespace
-      // is resolved from mutable session/git context, so a stale peek could
-      // report "miss" for a request that is actually an idempotent replay in the
-      // now-scoped namespace and hard-reject a safe replay with 429 (#1434 Codex
-      // review). Letting the in-lock hook be the only hard gate avoids that.
-      const response = await this.service.memoryStore(request, {
-        enforceWriteQuota: () => this.ensureWriteRateLimitAvailable(),
-      });
+      const op = getOperation("memory_store");
+      if (!op) {
+        throw new EngramAccessInputError("access-boundary: operation not registered: memory_store");
+      }
+      const output = (await op.run(envelope, {
+        service: this.service,
+        authenticatedPrincipal: this.resolveRequestPrincipal(req),
+        hooks: { enforceWriteQuota: () => this.ensureWriteRateLimitAvailable() },
+      })) as { result: EngramAccessWriteResponse };
+      const response = output.result;
       if (this.shouldCountWriteRateLimit(response as { dryRun?: boolean; idempotencyReplay?: boolean })) {
         this.recordWriteRateLimitHit();
       }
@@ -1387,7 +1385,19 @@ export class EngramAccessHttpServer {
     if (req.method === "GET" && memoryMatch) {
       const memoryId = decodeURIComponent(memoryMatch[1] ?? "");
       const namespace = parsed.searchParams.get("namespace") ?? undefined;
-      const response = await this.service.memoryGet(memoryId, namespace, this.resolveRequestPrincipal(req));
+      // Migrated through the access boundary (issue #1525): the registry
+      // entry owns memoryId presence/shape validation (rule 51: reject empty
+      // ids loudly instead of silently passing "" into the service) and the
+      // service dispatch.
+      const op = getOperation("memory_get");
+      if (!op) {
+        throw new EngramAccessInputError("access-boundary: operation not registered: memory_get");
+      }
+      const output = (await op.run(
+        { memoryId, namespace: namespace ?? null },
+        { service: this.service, authenticatedPrincipal: this.resolveRequestPrincipal(req) },
+      )) as { result: EngramAccessMemoryResponse };
+      const response = output.result;
       this.respondJson(res, response.found ? 200 : 404, response);
       return;
     }

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;