@remnic/core 9.63.10 → 9.63.12

package/src/access-http.ts

@@ -16,6 +16,7 @@ import {
   type WearablesMeetingsScope,
   type EngramAccessMemoryResponse,
   type EngramAccessWriteResponse,
+  type EngramAccessRecallResponse,
 } from "./access-service.js";
 import { maybeHandleLifecycleFlush, type LifecycleFlushHttpDeps } from "./access-http-lifecycle-flush.js";
 import {
@@ -32,7 +33,7 @@ import {
   OFFLINE_SYNC_FILE_CONTENT_MAX_CHUNK_BYTES,
   OFFLINE_SYNC_SNAPSHOT_BASE_MAX_BODY_BYTES,
 } from "./offline-sync.js";
-import type { RecallDisclosure, RecallPlanMode } from "./types.js";
+import type { RecallDisclosure } from "./types.js";
 import { isRecallDisclosure } from "./types.js";
 import { isTrustZoneName, type TrustZoneName, type TrustZoneRecordKind, type TrustZoneSourceClass } from "./trust-zones.js";
 import { AdapterRegistry, type ResolvedIdentity } from "./adapters/index.js";
@@ -1020,13 +1021,8 @@ export class EngramAccessHttpServer extends SupportPassportAccessHttpBase {
     if (req.method === "POST" && pathname === "/engram/v1/recall") {
       this.enforceTokenOp("recall"); // boundary dispatch (issue #1525)
       const body = await this.readValidatedBody(req, "recall");
-      // Preserve the distinction between `codingContext: null` (explicit
-      // clear) and `codingContext` missing from the JSON payload
-      // (untouched). The previous `?? undefined` collapsed both into
-      // undefined, so callers lost the ability to clear the session's
-      // attached context through the recall endpoint.
-      const codingContext =
-        "codingContext" in body ? body.codingContext : undefined;
+      // `codingContext` presence (null = explicit clear vs absent = untouched)
+      // is preserved by spreading the parsed body into the boundary envelope.
       // Disclosure resolution (issue #677 PR 2/4): accept the value from
       // the validated body OR the `?disclosure=` query parameter, with
       // the body taking precedence so an explicit JSON payload is never
@@ -1109,31 +1105,31 @@ export class EngramAccessHttpServer extends SupportPassportAccessHttpBase {
         bodyIncludeLowConfidence === true ||
         (bodyIncludeLowConfidence === undefined &&
           queryIncludeLowConfidence === "true");
-      const response = await this.service.recall({
-        query: body.query ?? "",
-        sessionKey: body.sessionKey,
-        authenticatedPrincipal: this.resolveRequestPrincipal(req),
-        sourceConnector: this.resolveConnector(req),
-        idempotencyKey: body.idempotencyKey,
-        namespace: this.resolveNamespace(req, body.namespace),
-        topK: body.topK,
-        mode: body.mode as RecallPlanMode | "auto" | undefined,
-        includeDebug: body.includeDebug === true,
-        // Forward the validated disclosure depth to the service layer
-        // (issue #677).  The zod schema accepts/rejects body values;
-        // `resolveRecallDisclosure()` validates the query-param fallback.
-        disclosure,
-        codingContext,
-        // Forward cwd/projectTag for auto git-context resolution (issue #569).
-        cwd: body.cwd,
-        projectTag: body.projectTag,
-        ...(asOf !== undefined ? { asOf } : {}),
-        ...(tags !== undefined ? { tags } : {}),
-        ...(tagMatch !== undefined ? { tagMatch } : {}),
-        ...(includeLowConfidence ? { includeLowConfidence: true } : {}),
-        abortSignal,
-      });
-      this.respondJson(res, 200, response);
+      // Boundary dispatch (issue #2482): same registry path as memory_store —
+      // the canonical recallRequestSchema re-validates the envelope the
+      // transport assembled (resolved namespace + query-param overlays).
+      const op = getOperation("recall");
+      if (!op) {
+        throw new EngramAccessInputError("access-boundary: operation not registered: recall");
+      }
+      const output = (await op.run(
+        {
+          ...body,
+          namespace: this.resolveNamespace(req, body.namespace),
+          ...(disclosure !== undefined ? { disclosure } : {}),
+          ...(asOf !== undefined ? { asOf } : {}),
+          ...(tags !== undefined ? { tags } : {}),
+          ...(tagMatch !== undefined ? { tagMatch } : {}),
+          ...(includeLowConfidence ? { includeLowConfidence: true } : {}),
+        },
+        {
+          service: this.service,
+          authenticatedPrincipal: this.resolveRequestPrincipal(req),
+          sourceConnector: this.resolveConnector(req),
+          ...(abortSignal ? { abortSignal } : {}),
+        },
+      )) as { result: EngramAccessRecallResponse };
+      this.respondJson(res, 200, output.result);
       return;
     }
 
@@ -1745,43 +1741,34 @@ export class EngramAccessHttpServer extends SupportPassportAccessHttpBase {
     if (req.method === "POST" && pathname === "/engram/v1/observe") {
       this.enforceTokenOp("observe"); // boundary dispatch (issue #1525)
       const body = await this.readValidatedBody(req, "observe");
-      const response = await this.service.observe(
+      // Boundary dispatch (issue #2482): same registry path as memory_store.
+      // The write-quota hook is forwarded via ctx.hooks so it fires INSIDE
+      // the service's idempotency lock (beforeExecute, only on a real miss).
+      // A retried observe that hits the replay path must NOT be rejected with
+      // 429 — the original attempt may have consumed the last quota slot; the
+      // retry returns the cached response without requiring another (#1434
+      // invariant, preserved by the boundary migration).
+      const op = getOperation("observe");
+      if (!op) {
+        throw new EngramAccessInputError("access-boundary: operation not registered: observe");
+      }
+      const output = (await op.run(
+        { ...body, namespace: this.resolveNamespace(req, body.namespace) },
         {
-          sessionKey: body.sessionKey,
-          messages: body.messages.map((message) => ({
-            role: message.role,
-            content: message.content,
-            sourceFormat: message.sourceFormat ?? undefined,
-            rawContent: message.rawContent ?? undefined,
-            parts: message.parts ?? undefined,
-          })),
-          namespace: this.resolveNamespace(req, body.namespace),
+          service: this.service,
           authenticatedPrincipal: this.resolveRequestPrincipal(req),
-          skipExtraction: body.skipExtraction === true,
-          // Issue #1649: optional server-side dedup key for retried POSTs.
-          idempotencyKey: body.idempotencyKey,
-          // Forward cwd/projectTag for auto git-context resolution (issue #569).
-          cwd: body.cwd,
-          projectTag: body.projectTag,
+          hooks: { enforceWriteQuota: () => this.ensureWriteRateLimitAvailable(req) },
           // Phase 1 provenance: server-resolved connector identity from the
           // bearer token (REST path, mirroring the MCP tools/call dispatch).
           sourceConnector: this.resolveConnector(req),
         },
-        // Enforce the write-quota INSIDE the service's idempotency lock
-        // (beforeExecute, only on a real miss). A retried observe that hits the
-        // replay path must NOT be rejected with 429 — that is exactly the
-        // response-lost-after-process case the dedup exists for. The original
-        // attempt may have consumed the last quota slot; the retry returns the
-        // cached response without requiring another. Matches memory_store's
-        // hook-in-the-lock pattern (#1434 invariant).
-        { enforceWriteQuota: () => this.ensureWriteRateLimitAvailable(req) },
-      );
+      )) as { result: { dryRun?: boolean; idempotencyReplay?: boolean } };
       // A replayed (deduplicated) observe must not consume a second write-quota
       // slot — same invariant as memory_store/suggestion_submit (#1434).
-      if (this.shouldCountWriteRateLimit(response as { dryRun?: boolean; idempotencyReplay?: boolean })) {
+      if (this.shouldCountWriteRateLimit(output.result)) {
         this.recordWriteRateLimitHit(req);
       }
-      this.respondJson(res, 202, response);
+      this.respondJson(res, 202, output.result);
       return;
     }
 

package/src/access-mcp.test.ts

@@ -472,16 +472,12 @@ test("MCP session override is injected only into tools that accept sessionKey",
     namespace: undefined,
     principal: "adapter-agent",
   });
-  assert.deepEqual(observeArgs, {
-    sessionKey: "adapter-session",
-    messages: [{ role: "user", content: "hello", parts: undefined, rawContent: undefined, sourceFormat: undefined }],
-    namespace: undefined,
-    authenticatedPrincipal: undefined,
-    skipExtraction: false,
-    idempotencyKey: undefined,
-    cwd: undefined,
-    projectTag: undefined,
-  });
+  assert.equal(observeArgs?.sessionKey, "adapter-session");
+  assert.equal(observeArgs?.skipExtraction, false);
+  const observeMessages = observeArgs?.messages as Array<{ role: string; content: string }>;
+  assert.equal(observeMessages?.length, 1);
+  assert.equal(observeMessages?.[0]?.role, "user");
+  assert.equal(observeMessages?.[0]?.content, "hello");
   assert.equal((capsuleResponse as Record<string, unknown> & { result?: { isError?: boolean } }).result?.isError, false);
   assert.equal((observeResponse as Record<string, unknown> & { result?: { isError?: boolean } }).result?.isError, false);
 });

package/src/access-mcp.ts

@@ -326,6 +326,24 @@ const STRICT_MCP_SCHEMA_KEYS: Partial<Record<SchemaName, readonly string[]>> = {
   capsuleList: ["namespace", "sessionKey", "cwd", "projectTag"],
 };
 
+// Tools whose envelope parses through the canonical zod wire schema (issue
+// #2482) — the SAME validation the HTTP transport runs. Every other migrated
+// tool passes raw args; its boundary op schema validates them.
+const MCP_WIRE_SCHEMAS: Partial<Record<string, SchemaName>> = {
+  memory_store: "memoryStore",
+  suggestion_submit: "suggestionSubmit",
+  action_confidence: "actionConfidence",
+  day_summary: "daySummary",
+  capsule_export: "capsuleExport",
+  capsule_import: "capsuleImport",
+  capsule_list: "capsuleList",
+  observe: "observe",
+  recall: "recall",
+  lcm_compaction_flush: "lcmCompactionFlush",
+  extraction_force_flush: "extractionForceFlush",
+  lcm_compaction_record: "lcmCompactionRecord",
+};
+
 // Shared JSON-schema fragments for the client-injected git/project context
 // fields (#1434). Declared once to avoid drift across tool definitions.
 // `_SCOPED` is for write tools that resolve a project namespace from these
@@ -2669,28 +2687,9 @@ export class EngramMcpServer {
       throw new EngramAccessInputError(`access-boundary: operation not registered: ${migrated}`);
     }
     let envelope: Record<string, unknown>;
-    if (migrated === "memory_store") {
-      envelope = parseMcpRequest("memoryStore", args);
-    } else if (migrated === "suggestion_submit") {
-      envelope = parseMcpRequest("suggestionSubmit", args);
-    } else if (migrated === "action_confidence") {
-      envelope = parseMcpRequest("actionConfidence", args);
-    } else if (migrated === "day_summary") {
-      envelope = parseMcpRequest("daySummary", args);
-    } else if (migrated === "capsule_export") {
-      envelope = parseMcpRequest("capsuleExport", args);
-    } else if (migrated === "capsule_import") {
-      envelope = parseMcpRequest("capsuleImport", args);
-    } else if (migrated === "capsule_list") {
-      envelope = parseMcpRequest("capsuleList", args);
-    } else if (migrated === "observe") {
-      envelope = parseMcpRequest("observe", args);
-    } else if (migrated === "lcm_compaction_flush") {
-      envelope = parseMcpRequest("lcmCompactionFlush", args);
-    } else if (migrated === "extraction_force_flush") {
-      envelope = parseMcpRequest("extractionForceFlush", args);
-    } else if (migrated === "lcm_compaction_record") {
-      envelope = parseMcpRequest("lcmCompactionRecord", args);
+    const wireSchema = MCP_WIRE_SCHEMAS[migrated];
+    if (wireSchema) {
+      envelope = parseMcpRequest(wireSchema, args) as Record<string, unknown>;
     } else if (migrated.startsWith("codegraph_")) {
       envelope = { ...args, tool: migrated.slice("codegraph_".length) };
     } else if (migrated === "chat_message") {

package/src/access-operations-batch.ts

@@ -15,6 +15,7 @@ import type { DreamsPhase, RecallDisclosure, RecallPlanMode } from "./types.js";
 import type { RemnicChatGptMemoryInspectorInput } from "./mcp-memory-inspector-app.js";
 import { defineOperation } from "./access-boundary.js";
 import { EngramAccessForbiddenError } from "./access-errors.js";
+import { type ObserveRequest, observeRequestSchema, type RecallRequest, recallRequestSchema } from "./access-schema.js";
 import { EngramAccessInputError, type EngramAccessService } from "./access-service.js";
 import { enforceNamespaceAllowList, tokenCapabilityStore } from "./access-token-capabilities.js";
 import { projectTagProjectId } from "./coding/coding-namespace.js";
@@ -57,6 +58,24 @@ function strictSchema<T extends z.ZodRawShape>(shape: T): z.ZodType<Record<strin
   return z.preprocess(stripNulls, z.object(shape).passthrough()) as unknown as z.ZodType<Record<string, unknown>>;
 }
 
+/**
+ * stripNulls, but keys listed in `preserve` keep their null values. Used by
+ * boundary schemas whose wire contract treats an explicit `null` as a
+ * meaningful value (e.g. recall `codingContext: null` clears the session
+ * context — it must not be collapsed into "absent").
+ */
+function stripNullsExcept(data: unknown, preserve: readonly string[]): unknown {
+  if (data !== null && typeof data === "object" && !Array.isArray(data)) {
+    const cleaned: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(data as Record<string, unknown>)) {
+      if (value !== null || preserve.includes(key)) cleaned[key] = value;
+    }
+    return cleaned;
+  }
+  return data;
+}
+
+
 function optStr(v: unknown): string | undefined { return typeof v === "string" ? v : undefined; }
 function reqStr(v: unknown, field: string): string {
   if (typeof v !== "string" || v.length === 0) throw new EngramAccessInputError(field + " is required and must be a non-empty string");
@@ -77,24 +96,26 @@ const S = {
 };
 
 // === RECALL ===
-defineOperation({ name: "recall", description: "Semantic recall.", schema: strictSchema({ query: S.str, sessionKey: S.str, namespace: S.str, topK: S.num, mode: S.str, includeDebug: S.bool, disclosure: S.str, cwd: S.str, projectTag: S.str, asOf: S.str, tags: S.strArr, tagMatch: S.str }),
-  handler: async (input, ctx) => {
-    let disclosure: RecallDisclosure | undefined;
-    if (input.disclosure !== undefined) { if (typeof input.disclosure !== "string") throw new EngramAccessInputError("disclosure must be a string"); disclosure = input.disclosure as RecallDisclosure; }
-    if (input.cwd !== undefined && typeof input.cwd !== "string") throw new EngramAccessInputError("cwd must be a string");
-    if (input.projectTag !== undefined && typeof input.projectTag !== "string") throw new EngramAccessInputError("projectTag must be a string");
-    if (input.asOf !== undefined && typeof input.asOf !== "string") throw new EngramAccessInputError("asOf must be a string");
-    let tags: string[] | undefined;
-    if (input.tags !== undefined) { if (!Array.isArray(input.tags) || !input.tags.every((t) => typeof t === "string")) throw new EngramAccessInputError("tags must be an array of strings"); tags = input.tags; }
-    let tagMatch: "any" | "all" | undefined;
-    if (input.tagMatch !== undefined) { if (input.tagMatch !== "any" && input.tagMatch !== "all") throw new EngramAccessInputError("tagMatch must be one of: any, all"); tagMatch = input.tagMatch; }
-    const result = await ctx.service.recall({ query: typeof input.query === "string" ? input.query : "", sessionKey: optStr(input.sessionKey), authenticatedPrincipal: ctx.authenticatedPrincipal, sourceConnector: ctx.sourceConnector, namespace: optStr(input.namespace), topK: optNum(input.topK), mode: optStr(input.mode) as RecallPlanMode | "auto" | undefined, includeDebug: input.includeDebug === true, disclosure, cwd: optStr(input.cwd), projectTag: optStr(input.projectTag), asOf: optStr(input.asOf), ...(tags ? { tags } : {}), ...(tagMatch ? { tagMatch } : {}), ...(ctx.abortSignal ? { abortSignal: ctx.abortSignal } : {}) });
-    return { result };
-  },
+// Issue #2482: the boundary validates against the SAME canonical zod schema
+// the HTTP transport uses (recallRequestSchema). No parallel field list, no
+// silent defaults — a missing `query` or a bad enum is a 400 at the boundary.
+// `codingContext: null` survives the null-strip (explicit session-context
+// clear); every other null is the MCP null-for-absent idiom.
+defineOperation({
+  name: "recall",
+  description: "Semantic recall.",
+  schema: z.preprocess((data) => stripNullsExcept(data, ["codingContext"]), recallRequestSchema) as unknown as z.ZodType<RecallRequest>,
+  handler: async (input, ctx) => ({
+    result: await ctx.service.recall({
+      ...input,
+      authenticatedPrincipal: ctx.authenticatedPrincipal,
+      ...(ctx.sourceConnector ? { sourceConnector: ctx.sourceConnector } : {}),
+      ...(ctx.abortSignal ? { abortSignal: ctx.abortSignal } : {}),
+    }),
+  }),
 });
 defineOperation({ name: "recall_explain", description: "Explain recall plan.", schema: strictSchema({ sessionKey: S.str, namespace: S.str }), handler: async (input, ctx) => ({ result: await ctx.service.recallExplain({ sessionKey: optStr(input.sessionKey), namespace: optStr(input.namespace), authenticatedPrincipal: ctx.authenticatedPrincipal }) }) });
-defineOperation({ name: "set_coding_context", description: "Set coding context.", schema: z.preprocess((data) => { // Strip null from all fields EXCEPT codingContext (null = clear context).
-    if (data !== null && typeof data === "object" && !Array.isArray(data)) { const o = data as Record<string, unknown>; const c: Record<string, unknown> = {}; for (const [k, v] of Object.entries(o)) { if (v !== null || k === "codingContext") c[k] = v; } return c; } return data; }, z.object({ sessionKey: S.str, codingContext: z.union([z.null(), z.object({ projectId: S.str, branch: z.union([z.string(), z.null()]).optional(), rootPath: S.str, defaultBranch: z.union([z.string(), z.null()]).optional() }).passthrough()]).optional(), projectTag: S.str }).passthrough()) as unknown as z.ZodType<Record<string, unknown>>,
+defineOperation({ name: "set_coding_context", description: "Set coding context.", schema: z.preprocess((data) => stripNullsExcept(data, ["codingContext"]), z.object({ sessionKey: S.str, codingContext: z.union([z.null(), z.object({ projectId: S.str, branch: z.union([z.string(), z.null()]).optional(), rootPath: S.str, defaultBranch: z.union([z.string(), z.null()]).optional() }).passthrough()]).optional(), projectTag: S.str }).passthrough()) as unknown as z.ZodType<Record<string, unknown>>, // codingContext: null = clear context (preserved).
   handler: async (input, ctx) => {
     const sessionKey = defStr(input.sessionKey, "");
     const projectTag = optStr(input.projectTag);
@@ -190,8 +211,35 @@ defineOperation({ name: "memory_timeline", description: "Memory timeline.", sche
 defineOperation({ name: "suggestion_submit", description: "Submit suggestion.", schema: strictSchema({ schemaVersion: S.num, idempotencyKey: S.str, dryRun: S.bool, sessionKey: S.str, content: S.str, category: S.str, confidence: S.num, namespace: S.str, tags: S.strArr, entityRef: S.str, ttl: S.str, sourceReason: S.str, cwd: S.str, projectTag: S.str }), handler: async (input, ctx) => ({ result: await ctx.service.suggestionSubmit({ schemaVersion: optNum(input.schemaVersion), idempotencyKey: optStr(input.idempotencyKey), dryRun: input.dryRun === true, sessionKey: optStr(input.sessionKey), authenticatedPrincipal: ctx.authenticatedPrincipal, ...(ctx.sourceConnector ? { sourceConnector: ctx.sourceConnector } : {}), content: optStr(input.content) ?? "", category: optStr(input.category), confidence: optNum(input.confidence), namespace: optStr(input.namespace), tags: optStrArr(input.tags), entityRef: optStr(input.entityRef), ttl: optStr(input.ttl), sourceReason: optStr(input.sourceReason), cwd: optStr(input.cwd), projectTag: optStr(input.projectTag) }) }) });
 defineOperation({ name: "entity_get", description: "Get entity.", schema: strictSchema({ name: S.str, namespace: S.str }), handler: async (input, ctx) => ({ result: await ctx.service.entityGet(optStr(input.name) ?? "", optStr(input.namespace)) }) });
 defineOperation({ name: "review_queue_list", description: "List review queue.", schema: strictSchema({ runId: S.str, namespace: S.str }), handler: async (input, ctx) => ({ result: await ctx.service.reviewQueue(optStr(input.runId) ?? "", optStr(input.namespace), ctx.authenticatedPrincipal) }) });
-defineOperation({ name: "observe", description: "Observe messages.", schema: strictSchema({ sessionKey: S.str, messages: z.array(z.object({ role: z.string(), content: z.string(), parts: z.array(z.unknown()).optional(), rawContent: z.unknown().optional(), sourceFormat: z.string().optional() }).passthrough()), skipExtraction: S.bool, idempotencyKey: S.str, namespace: S.str, cwd: S.str, projectTag: S.str }),
-  handler: async (input, ctx) => ({ result: await ctx.service.observe({ sessionKey: defStr(input.sessionKey, ""), messages: (input.messages as unknown[]).map((m: unknown) => { const r = m as Record<string, unknown>; return { role: String(r.role), content: String(r.content), parts: r.parts as unknown[], rawContent: r.rawContent as string | undefined, sourceFormat: r.sourceFormat as string | undefined }; }) as never, skipExtraction: input.skipExtraction === true, idempotencyKey: optStr(input.idempotencyKey), namespace: optStr(input.namespace), authenticatedPrincipal: ctx.authenticatedPrincipal, cwd: optStr(input.cwd), projectTag: optStr(input.projectTag), ...(ctx.sourceConnector ? { sourceConnector: ctx.sourceConnector } : {}) }, ctx.hooks?.enforceWriteQuota ? { enforceWriteQuota: ctx.hooks.enforceWriteQuota } : undefined) }),
+// Issue #2482: observe validates through the canonical observeRequestSchema
+// (same as HTTP/MCP wire validation). Nullable wire fields (parts /
+// sourceFormat) map to undefined for the service's cleaned message form.
+defineOperation({
+  name: "observe",
+  description: "Observe messages.",
+  schema: z.preprocess(stripNulls, observeRequestSchema) as unknown as z.ZodType<ObserveRequest>,
+  handler: async (input, ctx) => ({
+    result: await ctx.service.observe(
+      {
+        sessionKey: input.sessionKey,
+        messages: input.messages.map((message) => ({
+          role: message.role,
+          content: message.content,
+          ...(message.parts ? { parts: message.parts } : {}),
+          ...(message.rawContent !== undefined ? { rawContent: message.rawContent } : {}),
+          ...(message.sourceFormat ? { sourceFormat: message.sourceFormat } : {}),
+        })),
+        skipExtraction: input.skipExtraction === true,
+        idempotencyKey: input.idempotencyKey,
+        namespace: input.namespace,
+        authenticatedPrincipal: ctx.authenticatedPrincipal,
+        cwd: input.cwd,
+        projectTag: input.projectTag,
+        ...(ctx.sourceConnector ? { sourceConnector: ctx.sourceConnector } : {}),
+      },
+      ctx.hooks?.enforceWriteQuota ? { enforceWriteQuota: ctx.hooks.enforceWriteQuota } : undefined,
+    ),
+  }),
 });
 defineOperation({ name: "lcm_search", description: "Search LCM.", schema: strictSchema({ query: S.str, sessionKey: S.str, sessionPrefix: S.str, namespace: S.str, limit: S.num }), handler: async (input, ctx) => ({ result: await ctx.service.lcmSearch({ query: defStr(input.query, ""), sessionKey: optStr(input.sessionKey), sessionPrefix: optStr(input.sessionPrefix), namespace: optStr(input.namespace), limit: optNum(input.limit), authenticatedPrincipal: ctx.authenticatedPrincipal }) }) });
 defineOperation({ name: "lcm_compaction_flush", description: "Flush LCM compaction.", schema: strictSchema({ sessionKey: S.str, namespace: S.str, cwd: S.str, projectTag: S.str }), handler: async (input, ctx) => ({ result: await ctx.service.lcmCompactionFlush({ sessionKey: optStr(input.sessionKey) ?? "", namespace: optStr(input.namespace), cwd: optStr(input.cwd), projectTag: optStr(input.projectTag), authenticatedPrincipal: ctx.authenticatedPrincipal }) }) });

package/src/access-schema.ts

@@ -706,9 +706,20 @@ export function validateRequest<T = unknown>(
       },
     };
   }
-  const result = schema.safeParse(body);
+  const result = schema.safeParse(stripNullsExceptCodingContext(body));
   if (result.success) {
     return { success: true, data: result.data as T };
   }
   return { success: false, error: formatZodError(result.error) };
 }
+
+function stripNullsExceptCodingContext(data: unknown): unknown {
+  if (!data || typeof data !== "object" || Array.isArray(data)) return data;
+  const cleaned: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(data as Record<string, unknown>)) {
+    if (value === null && key !== "codingContext") continue;
+    cleaned[key] = value;
+  }
+  return cleaned;
+}
+

package/src/access-service.ts

@@ -278,6 +278,7 @@ import {
   recordMemoryOutcome,
 } from "./memory-worth-outcomes.js";
 import type { LcmMessagePartInput, MessagePartSourceFormat } from "./message-parts/index.js";
+import type { ObserveRequest, RecallRequest } from "./access-schema.js";
 import { recordObjectiveStateSnapshotsFromObservedMessages } from "./objective-state-writers.js";
 import { objectiveStateStoreOverrideForNamespace } from "./objective-state.js";
 import { offlineSyncStorageForSnapshot } from "./offline-sync-impression-drain.js";
@@ -373,17 +374,16 @@ function normalizeTrustZoneInputError(error: unknown): EngramAccessInputError |
 
 export const ENGRAM_ACCESS_WRITE_SCHEMA_VERSION = 1;
 
-export interface EngramAccessRecallRequest {
-  query: string;
-  sessionKey?: string;
-  namespace?: string;
+/**
+ * Recall request. Wire fields derive from the canonical zod schema
+ * (`recallRequestSchema`, access-schema.ts — issue #2482) so the HTTP body,
+ * the MCP args, and the service share ONE model. The overlay below carries
+ * server-resolved transport fields no client may set.
+ */
+export interface EngramAccessRecallRequest extends RecallRequest {
   authenticatedPrincipal?: string;
   /** Trusted connector identity resolved at the transport boundary. */
   sourceConnector?: string;
-  idempotencyKey?: string;
-  topK?: number;
-  mode?: RecallPlanMode | "auto";
-  includeDebug?: boolean;
   abortSignal?: AbortSignal;
   /**
    * Internal, server-set field (issue #1906): wall-clock ms the caller
@@ -393,70 +393,6 @@ export interface EngramAccessRecallRequest {
    * (same pattern as `abortSignal`).
    */
   queueWaitMs?: number;
-  /**
-   * Recall disclosure depth. Omitting it preserves the `"chunk"` default.
-   * Other accepted values are `"section"` and `"raw"`.
-   */
-  disclosure?: RecallDisclosure;
-  /**
-   * Coding-agent context (issue #569). When a connector resolves a git
-   * context for the session's cwd, it passes it here and the access service
-   * attaches it to the orchestrator before recall so project- / branch-
-   * scoped namespace overlays apply.
-   *
-   * Keyed by `sessionKey`; ignored when `sessionKey` is absent.
-   */
-  codingContext?: {
-    projectId: string;
-    branch: string | null;
-    rootPath: string;
-    defaultBranch: string | null;
-  } | null;
-  /**
-   * Working directory of the calling agent session. When provided and no
-   * `codingContext` is already attached to the session, the service resolves
-   * git context from this path and attaches it automatically. This enables
-   * Claude Code hooks (and any connector that knows its cwd) to get
-   * project-scoped memory without explicitly constructing a `codingContext`.
-   */
-  cwd?: string;
-  /**
-   * Arbitrary project tag for non-git-based project scoping. When provided,
-   * creates a `CodingContext` with `projectId: "tag:<projectTag>"`.
-   * Useful for OpenClaw sessions where the whole workspace is one git repo
-   * but different conversations correspond to different client projects.
-   * Takes precedence over `cwd`-based git resolution but NOT over an
-   * explicit `codingContext`.
-   */
-  projectTag?: string;
-  /**
-   * Historical recall pin (issue #680).  ISO 8601 timestamp.  When set,
-   * the orchestrator filters out memories whose `valid_at` is after this
-   * instant OR whose `invalid_at` is at-or-before this instant, so the
-   * caller sees the corpus as it existed at `asOf`.  Invalid values are
-   * rejected here with `EngramAccessInputError` (CLAUDE.md rule 51).
-   */
-  asOf?: string;
-  /**
-   * Free-form recall tag filter (issue #689). When non-empty, recall results
-   * whose frontmatter `tags` do not match are removed from the response.
-   * Comparison is case-sensitive exact match against tags stored on each
-   * memory's frontmatter (see `storage.ts` and `docs/tags.md`).
-   */
-  tags?: string[];
-  /**
-   * Match mode for `tags` (issue #689). `"any"` (default when omitted)
-   * admits results that carry at least one filter tag. `"all"` requires
-   * every filter tag to be present. Ignored when `tags` is absent or empty.
-   */
-  tagMatch?: "any" | "all";
-  /**
-   * Issue #681 — when `true`, bypasses the configured
-   * `graphTraversalConfidenceFloor` for this recall and includes graph edges
-   * below the floor in traversal.  Useful for diagnostic queries that need to
-   * surface results pruned by confidence decay.  Default `false`.
-   */
-  includeLowConfidence?: boolean;
 }
 
 /**
@@ -1033,27 +969,18 @@ export interface EngramAccessObserveMessage {
   sourceFormat?: MessagePartSourceFormat;
 }
 
-export interface EngramAccessObserveRequest extends SourceConnectorProvenance {
-  sessionKey: string;
+/**
+ * Observe request. Wire fields derive from the canonical zod schema
+ * (`observeRequestSchema`, access-schema.ts — issue #2482); the service
+ * consumes the transport-cleaned message form (the wire schema tolerates
+ * nullable `parts`/`sourceFormat`, the service maps them to `undefined`).
+ */
+export interface EngramAccessObserveRequest
+  extends Omit<ObserveRequest, "messages">,
+    SourceConnectorProvenance {
   messages: EngramAccessObserveMessage[];
-  namespace?: string;
   authenticatedPrincipal?: string;
-  skipExtraction?: boolean;
-  /** Optional idempotency key (issue #1649): a retried POST with the same key is deduplicated server-side; divergent reuse is a conflict. */
-  idempotencyKey?: string;
-  /**
-   * Working directory of the calling agent session (issue #569 wiring).
-   * When provided and no `codingContext` is attached for this session,
-   * resolves git context from the path and attaches it so writes route to
-   * the correct project namespace.
-   */
-  cwd?: string;
-  /**
-   * Arbitrary project tag for non-git-based project scoping (issue #569).
-   * Creates a `CodingContext` with `projectId: "tag:<projectTag>"`.
-   */
-  projectTag?: string;
-  readonly suppressQuarantine?: boolean; // #1888: mirrors EngramAccessWriteEnvelope.suppressQuarantine (replay re-submit skips dead-lettering).
+  readonly suppressQuarantine?: boolean; // #1888: replay re-submit skips dead-lettering.
 }
 
 /**

package/src/recall-disclosure.test.ts

@@ -191,7 +191,7 @@ test("MCP engram.recall rejects non-string disclosure with a structured error",
   const result = (response as { result?: { isError?: boolean; content?: Array<{ text?: string }> } } | undefined)?.result;
   assert.strictEqual(result?.isError, true);
   const text = result?.content?.[0]?.text ?? "";
-  assert.match(text, /disclosure must be a string/i);
+  assert.match(text, /disclosure/i);
 });
 
 test("MCP engram.recall treats explicit `null` disclosure as absent (service applies default)", async () => {