@remnic/core 10.0.50 → 10.0.52

package/dist/transfer/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/transfer/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAajC,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,eAAO,MAAM,0BAA0B;;;;;;;;;EAGrC,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAG/B,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAWlE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,QAAkE,CAAC;AA+BlG,eAAO,MAAM,4BAA4B;IACvC;;;;;OAKG;;IAKH;;;;OAIG;;;;;;;;EAEH,CAAC;AAEH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAElF,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;EAKhC,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB;;;IAG9B;;;;OAIG;;;;;;;;;;EAQH,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,eAAO,MAAM,kBAAkB;;;IAG7B;;;OAGG;;IAEH;;;;;;;OAOG;;IAEH;;;;;;;;;;;;;;OAcG;;;;QA/CH;;;;WAIG;;;;;;;;;;;;;QA/CH;;;;;WAKG;;QAKH;;;;WAIG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiFH,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;QArCjC;;;WAGG;;QAEH;;;;;;;WAOG;;QAEH;;;;;;;;;;;;;;WAcG;;;;YA/CH;;;;eAIG;;;;;;;;;;;;;YA/CH;;;;;eAKG;;YAKH;;;;eAIG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmGH,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;YAvD/B;;;eAGG;;YAEH;;;;;;;eAOG;;YAEH;;;;;;;;;;;;;;eAcG;;;;gBA/CH;;;;mBAIG;;;;;;;;;;;;;gBA/CH;;;;;mBAKG;;gBAKH;;;;mBAIG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA0GH,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAMlE,MAAM,MAAM,iBAAiB,GAAG,gBAAgB,GAAG,gBAAgB,CAAC;AACpE,MAAM,MAAM,eAAe,GAAG,cAAc,GAAG,cAAc,CAAC;AAE9D;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,cAAc,EAAE,CAAC,GAAG,CAAC,CAAC;IACtB,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,OAAO,EAAE,YAAY,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,wBAAwB,CAqC5E;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG;IACjD,cAAc,EAAE,CAAC,GAAG,CAAC,CAAC;IACtB,MAAM,EAAE,eAAe,CAAC;IACxB,OAAO,EAAE,YAAY,GAAG,IAAI,CAAC;CAC9B,CAcA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/transfer/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,sBAAsB;;;;;;;;;;;iBAajC,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,eAAO,MAAM,0BAA0B;;;iBAGrC,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;iBAG/B,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAWlE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,QAAkE,CAAC;AA+BlG,eAAO,MAAM,4BAA4B;;;iBAiBvC,CAAC;AAEH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAElF,eAAO,MAAM,qBAAqB;;;;;iBAKhC,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB;;;;iBAe9B,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;iBAoC7B,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAcjC,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAG/B,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAMlE,MAAM,MAAM,iBAAiB,GAAG,gBAAgB,GAAG,gBAAgB,CAAC;AACpE,MAAM,MAAM,eAAe,GAAG,cAAc,GAAG,cAAc,CAAC;AAE9D;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,cAAc,EAAE,CAAC,GAAG,CAAC,CAAC;IACtB,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,OAAO,EAAE,YAAY,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,wBAAwB,CAqC5E;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG;IACjD,cAAc,EAAE,CAAC,GAAG,CAAC,CAAC;IACtB,MAAM,EAAE,eAAe,CAAC;IACxB,OAAO,EAAE,YAAY,GAAG,IAAI,CAAC;CAC9B,CAcA"}

package/dist/verified-recall.js

@@ -1,12 +1,12 @@
 import {
   compareVerifiedEpisodeResults,
   searchVerifiedEpisodes
-} from "./chunk-WXJC2L66.js";
+} from "./chunk-ROAKLYOL.js";
 import "./chunk-B7RWBZXW.js";
-import "./chunk-GQIYL7OD.js";
+import "./chunk-JIJAWTRK.js";
 import "./chunk-UHVXE24Y.js";
 import "./chunk-DM5QZ3YU.js";
-import "./chunk-ZMO2S5RT.js";
+import "./chunk-G6A3SGCE.js";
 import "./chunk-G6OFEGUR.js";
 import "./chunk-LXXIV7Y2.js";
 import "./chunk-JS44PBCM.js";

package/dist/who-knows-cli.js

@@ -4,12 +4,12 @@ import {
   renderWhoKnows,
   renderWhoKnowsJson,
   renderWhoKnowsText
-} from "./chunk-IUYXCTA7.js";
-import "./chunk-HPNXS6W6.js";
-import "./chunk-GQIYL7OD.js";
+} from "./chunk-TC55M5PO.js";
+import "./chunk-2ONKXEC7.js";
+import "./chunk-JIJAWTRK.js";
 import "./chunk-UHVXE24Y.js";
 import "./chunk-DM5QZ3YU.js";
-import "./chunk-ZMO2S5RT.js";
+import "./chunk-G6A3SGCE.js";
 import "./chunk-G6OFEGUR.js";
 import "./chunk-LXXIV7Y2.js";
 import "./chunk-JS44PBCM.js";
@@ -104,7 +104,7 @@ import "./chunk-X4OZMANG.js";
 import "./chunk-ZEFVK7XC.js";
 import "./chunk-6KH5NLQS.js";
 import "./chunk-P2QRMMVQ.js";
-import "./chunk-3MUKQQ7A.js";
+import "./chunk-LGEH473S.js";
 import "./chunk-R2MBW2S4.js";
 import "./chunk-QUIRIG2P.js";
 import "./chunk-LDPPTPO5.js";

package/dist/who-knows.js

@@ -9,11 +9,11 @@ import {
   loadWhoKnowsEntities,
   tokenizeTopic,
   validateWhoKnowsInput
-} from "./chunk-HPNXS6W6.js";
-import "./chunk-GQIYL7OD.js";
+} from "./chunk-2ONKXEC7.js";
+import "./chunk-JIJAWTRK.js";
 import "./chunk-UHVXE24Y.js";
 import "./chunk-DM5QZ3YU.js";
-import "./chunk-ZMO2S5RT.js";
+import "./chunk-G6A3SGCE.js";
 import "./chunk-G6OFEGUR.js";
 import "./chunk-LXXIV7Y2.js";
 import "./chunk-JS44PBCM.js";
@@ -108,7 +108,7 @@ import "./chunk-X4OZMANG.js";
 import "./chunk-ZEFVK7XC.js";
 import "./chunk-6KH5NLQS.js";
 import "./chunk-P2QRMMVQ.js";
-import "./chunk-3MUKQQ7A.js";
+import "./chunk-LGEH473S.js";
 import "./chunk-R2MBW2S4.js";
 import "./chunk-QUIRIG2P.js";
 import "./chunk-LDPPTPO5.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remnic/core",
-  "version": "10.0.50",
+  "version": "10.0.52",
   "description": "Framework-agnostic Remnic memory engine — orchestrator, storage, extraction, search, trust zones",
   "type": "module",
   "main": "dist/index.js",
@@ -3318,8 +3318,7 @@
     "node-gyp": "^12.3.0",
     "openai": "^6.0.0",
     "undici": "^6.29.1",
-    "zod": "^3.25.28",
-    "zod-to-json-schema": "^3.25.2"
+    "zod": "^4.6.6"
   },
   "optionalDependencies": {
     "@lancedb/lancedb-darwin-arm64": "^0.26.2",
@@ -3347,7 +3346,7 @@
     "core"
   ],
   "peerDependencies": {
-    "@remnic/coding-graph": "^10.0.50"
+    "@remnic/coding-graph": "^10.0.52"
   },
   "peerDependenciesMeta": {
     "@remnic/coding-graph": {

package/src/access-boundary.test.ts

@@ -153,6 +153,20 @@ test("formatZodIssues: includes the (root) path for top-level errors", async ()
   assert.ok(message.length > 0);
 });
 
+test("formatZodIssues: a missing required field keeps the zod message, a wrong type says must be a type", async () => {
+  const { z } = await import("zod");
+  const schema = z.object({ memoryId: z.string() });
+  const missing = schema.safeParse({});
+  assert.ok(!missing.success);
+  const missingMessage = formatZodIssues(missing.error);
+  assert.doesNotMatch(missingMessage, /must be a string/, "an absent field is not a type mismatch");
+  assert.match(missingMessage, /memoryId/);
+  assert.match(missingMessage, /received undefined/);
+  const wrong = schema.safeParse({ memoryId: 5 });
+  assert.ok(!wrong.success);
+  assert.match(formatZodIssues(wrong.error), /memoryId must be a string/);
+});
+
 // ---------------------------------------------------------------------------
 // defineOperation / getOperation — registry contract
 // ---------------------------------------------------------------------------

package/src/access-boundary.ts

@@ -306,7 +306,7 @@ export interface OperationSpec<In, Out> {
    * #2829 category aliases) are first-class, declared truthfully instead of
    * cast into an input-equals-output shape.
    */
-  readonly schema: z.ZodType<In, z.ZodTypeDef, unknown>;
+  readonly schema: z.ZodType<In, unknown>;
   /** Handler invoked with the parsed input; throws EngramAccessInputError for domain faults. */
   readonly handler: (input: In, ctx: OperationContext) => Promise<Out>;
   /**
@@ -427,24 +427,47 @@ export function formatZodIssues(error: z.ZodError): string {
       : issue.path.length > 0 ? issue.path.join(".") : "(root)";
     const options = enumOptionsFromIssue(issue);
     const suffix = options ? `. Valid: ${options.join(", ")}` : "";
-    parts.push(`${path}: ${issue.message}${suffix}`);
+    parts.push(`${path}: ${humanReadableIssueMessage(issue, path, hasNumeric)}${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
+function enumOptionsFromIssue(issue: z.core.$ZodIssue): readonly string[] | undefined {
+  // zod 4 exposes accepted enum values on invalid_value issues as `values`
+  // (the v3 `options` spelling is kept as a fallback). 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));
-    }
+  if (issue.code !== "invalid_value") return undefined;
+  const rawValues = "values" in issue ? issue.values : undefined;
+  return Array.isArray(rawValues) ? rawValues.map((opt) => String(opt)) : undefined;
+}
+
+/**
+ * Human-readable "must be a <type>" message for generic type mismatches
+ * (rule 51). zod 4 removed parse-time error maps, so the boundary applies
+ * this post-parse in formatZodIssues instead — same messages, one place.
+ * The caller supplies the collapsed path label and its numeric-segment
+ * verdict so this helper runs no representation checks of its own.
+ */
+function humanReadableIssueMessage(issue: z.core.$ZodIssue, pathLabel: string, hasNumericPath: boolean): string {
+  if (issue.code !== "invalid_type") return issue.message;
+  const expected = issue.expected;
+  // zod 4 issues carry no `received` field; its message ends "received undefined"
+  // for an absent value, which is a missing field, not a type mismatch.
+  if (issue.message.endsWith("received undefined")) return issue.message;
+  if (hasNumericPath && expected) {
+    return `${pathLabel} must be an array of ${expected}s`;
+  }
+  const fieldName = issue.path.length > 0 ? String(issue.path[issue.path.length - 1]) : "value";
+  switch (expected) {
+    case "string": return `${fieldName} must be a string`;
+    case "boolean": return `${fieldName} must be a boolean`;
+    case "number": return `${fieldName} must be a number`;
+    case "array": return `${fieldName} must be an array`;
+    case "object": return `${fieldName} must be an object`;
+    default: return issue.message;
   }
-  return undefined;
 }
 
 // ---------------------------------------------------------------------------
@@ -458,33 +481,6 @@ const registry = new Map<OperationName, BoundOperation>();
  * 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).
  */
-/**
- * Error map that converts Zod's generic type-mismatch messages into
- * human-readable "must be a <type>" messages (rule 51).  Applied at the
- * boundary chokepoint so every operation gets consistent messaging
- * without per-handler boilerplate.
- */
-const humanReadableErrorMap: z.ZodErrorMap = (issue, ctx) => {
-  if (issue.code === z.ZodIssueCode.invalid_type) {
-    if (issue.received === "undefined") return { message: ctx.defaultError };
-    // Array-element type errors — collapse to field-level message.
-    if (issue.path.some((p) => typeof p === "number")) {
-      const arrField = issue.path.filter((p) => typeof p === "string").join(".");
-      return { message: `${arrField} must be an array of ${issue.expected}s` };
-    }
-    const fieldName = issue.path.length > 0 ? String(issue.path[issue.path.length - 1]) : "value";
-    switch (issue.expected) {
-      case "string": return { message: `${fieldName} must be a string` };
-      case "boolean": return { message: `${fieldName} must be a boolean` };
-      case "number": return { message: `${fieldName} must be a number` };
-      case "array": return { message: `${fieldName} must be an array` };
-      case "object": return { message: `${fieldName} must be an object` };
-      default: return { message: ctx.defaultError };
-    }
-  }
-  return { message: ctx.defaultError };
-};
-
 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}`);
@@ -492,7 +488,7 @@ export function defineOperation<In, Out>(spec: OperationSpec<In, Out>): BoundOpe
   const bound: BoundOperation<In, Out> = {
     spec,
     run: async (rawInput, ctx) => {
-      const parseResult = spec.schema.safeParse(rawInput, { errorMap: humanReadableErrorMap });
+      const parseResult = spec.schema.safeParse(rawInput);
       if (!parseResult.success) {
         throw new EngramAccessInputError(formatZodIssues(parseResult.error));
       }
@@ -516,9 +512,19 @@ export function operationRequiresAuthorizedNamespace(name: OperationName): boole
   if (name === "namespace_writable") return false;
   if (IMPLICIT_HTTP_NAMESPACE_OPERATIONS.has(name)) return true;
   let schema: unknown = registry.get(name)?.spec.schema;
-  // preprocess/transform/refine each wrap ZodEffects. One unwrap left
-  // suggestion_submit looking namespace-free after the category transform.
-  while (schema instanceof z.ZodEffects) schema = schema.innerType();
+  // zod 4 has no ZodEffects. Transforms and preprocessors wrap as pipes with
+  // the base schema on the side opposite the ZodTransform. Unwrap until the
+  // base object appears — one unwrap left suggestion_submit looking
+  // namespace-free after the category transform, so the loop stays.
+  while (schema instanceof z.ZodType && !(schema instanceof z.ZodObject)) {
+    // SAFETY: pipe wrappers expose their two sides as `in` / `out`.
+    const wrapper = schema as { in?: unknown; out?: unknown };
+    const sides = [wrapper.in, wrapper.out].filter(
+      (side) => side instanceof z.ZodType && !(side instanceof z.ZodTransform),
+    );
+    if (sides.length !== 1) break;
+    schema = sides[0];
+  }
   return schema instanceof z.ZodObject && Object.hasOwn(schema.shape, "namespace");
 }
 

package/src/access-category-alias.test.ts

@@ -662,24 +662,26 @@ test("project-shaped category aliases store as fact and the response reports the
 // ---------------------------------------------------------------------------
 
 test("#2829/#2866 transformed write schemas still require an authorized namespace", () => {
+  // zod 4 replaced ZodEffects with ZodPipe/ZodPreprocess (both expose .out).
   assert.equal(
-    memoryStoreRequestSchema instanceof z.ZodEffects,
-    true,
+    memoryStoreRequestSchema instanceof z.ZodObject,
+    false,
     "memory_store schema is a category transform",
   );
   const suggestion = getOperation("suggestion_submit");
   assert.ok(suggestion);
+  const wrapper: unknown = suggestion.spec.schema;
   assert.ok(
-    suggestion.spec.schema instanceof z.ZodEffects,
+    wrapper instanceof Object && "in" in wrapper,
     "suggestion_submit wraps preprocess around the transform",
   );
-  const inner = suggestion.spec.schema.innerType();
+  // SAFETY: the assertion above established `in` exists on this object.
+  const inner = (wrapper as { in: unknown }).in;
   assert.equal(
-    inner instanceof z.ZodEffects,
-    true,
+    inner instanceof z.ZodObject,
+    false,
     "one unwrap still lands on the category transform, not the object",
   );
-  assert.equal(inner instanceof z.ZodObject, false);
 
   for (const operation of ["memory_store", "suggestion_submit"] as const) {
     assert.equal(

package/src/access-errors.test.ts

@@ -104,7 +104,7 @@ test("invalidArgsError: names the failing field path", () => {
   assert.equal(parse.success, false);
   const msg = invalidArgsError("engram.memory_get", parse.error, MEMORY_GET_SCHEMA);
   assert.match(msg, /memory_id/);
-  assert.match(msg, /required/i);
+  assert.match(msg, /received undefined/i);
 });
 
 test("invalidArgsError: the shown example actually parses against the schema", () => {
@@ -133,16 +133,28 @@ test("invalidArgsError: the shown example actually parses against the schema", (
 });
 
 test("invalidArgsError: an example that cannot round-trip is withheld, not shown", () => {
-  // A schema whose safeParse always fails must produce no example section
-  // rather than an example the caller cannot use.
-  const alwaysFails = {
-    _def: { typeName: "ZodObject", shape: () => ({ field: { _def: { typeName: "ZodString" } } }) },
-    safeParse: () => ({ success: false }),
-  };
-  const parse = MEMORY_GET_SCHEMA.safeParse({});
+  // Real zod 4 object: exampleFromSchema emits { field: "<string>" }, but the
+  // refine rejects that placeholder so safeParse fails. The round-trip guard
+  // must then withhold the example rather than advertise unusable args.
+  const neverRoundTrips = z
+    .object({
+      field: z.string().refine((value) => value !== "<string>", {
+        message: "placeholder example is rejected",
+      }),
+    })
+    .strict();
+
+  const againstPlaceholder = neverRoundTrips.safeParse({ field: "<string>" });
+  assert.equal(
+    againstPlaceholder.success,
+    false,
+    "the synthetic placeholder must fail the refine so the round-trip guard is reachable",
+  );
+
+  const parse = neverRoundTrips.safeParse({});
   assert.equal(parse.success, false);
   if (parse.success) return;
-  const msg = invalidArgsError("engram.memory_get", parse.error, alwaysFails);
+  const msg = invalidArgsError("engram.memory_get", parse.error, neverRoundTrips);
   assert.doesNotMatch(msg, /Example arguments/, "a non-parsing example must be withheld");
 });
 

package/src/access-errors.ts

@@ -141,53 +141,67 @@ function buildSuggestion(
  * `undefined` instead of a fabricated read.
  */
 function zodTypeName(schema: unknown): string | undefined {
-  if (typeof schema !== "object" || schema === null || !("_def" in schema)) return undefined;
-  const def = schema._def;
-  if (typeof def !== "object" || def === null || !("typeName" in def)) return undefined;
-  return typeof def.typeName === "string" ? def.typeName : undefined;
+  // zod 4: schema internals live on `_zod.def.type` (v3 read `_def.typeName`).
+  if (!(schema instanceof Object) || !("_zod" in schema)) return undefined;
+  // SAFETY: the guard above established `_zod` exists; its `.def` carries the
+  // discriminator string under `type`.
+  const def = (schema as { _zod?: { def?: { type?: unknown } } })._zod?.def;
+  // SAFETY: zod's `_zod.def.type` discriminator is always a string literal.
+  const discriminator = def?.type;
+  return discriminator === undefined ? undefined : String(discriminator);
 }
 
-/** Read `_def.<key>` with the same narrowing discipline. */
-function zodDefField(schema: unknown, key: string): unknown {
-  if (typeof schema !== "object" || schema === null || !("_def" in schema)) return undefined;
-  const def = schema._def;
-  if (typeof def !== "object" || def === null) return undefined;
-  return Object.hasOwn(def, key) ? (def as Record<string, unknown>)[key] : undefined;
-}
+/**
+ * A zod schema node this module reflects over — any object the library
+ * exposes as a schema (v4 marks them with `_zod`).
+ */
+/** Structural marker: every zod schema carries `_zod`. */
+type ZodSchemaLike = { _zod?: unknown };
+
+/**
+ * A synthetic example value derived from a schema: a placeholder the SAME
+ * schema accepts, so the error message can show a valid argument shape.
+ */
+type SchemaExample = string | number | boolean | null | readonly SchemaExample[] | { [key: string]: SchemaExample };
 
 /**
  * Reverse-engineer ONE synthetic example value from a Zod schema type.
  * Returns a deterministic placeholder intended to round-trip through parse().
  */
-function exampleFromSchema(schema: unknown): unknown {
+function exampleFromSchema(schema: ZodSchemaLike): SchemaExample | undefined {
   switch (zodTypeName(schema)) {
-    case "ZodString":
+    case "string":
       return "<string>";
-    case "ZodNumber":
+    case "number":
       return 42;
-    case "ZodBoolean":
+    case "boolean":
       return true;
-    case "ZodNullable":
+    case "nullable":
       return null;
-    case "ZodArray":
+    case "array":
       return [];
-    case "ZodOptional":
+    case "optional":
       // Optional fields are omitted from the example rather than sent as null.
       return undefined;
-    case "ZodEnum": {
-      const values = zodDefField(schema, "values");
-      return Array.isArray(values) && values.length > 0 ? values[0] : "<value>";
+    case "enum": {
+      // v4 exposes accepted values as the public `.enum` record.
+      if (!(schema instanceof Object) || !("enum" in schema)) return "<value>";
+      // SAFETY: the guard established `.enum`; zod types it as a value record.
+      const values = Object.values((schema as { enum: Record<string, string> }).enum);
+      return values.length > 0 ? values[0] : "<value>";
     }
-    case "ZodObject": {
-      const shapeFn = zodDefField(schema, "shape");
-      const shape = typeof shapeFn === "function" ? shapeFn() : undefined;
-      if (typeof shape !== "object" || shape === null) return {};
-      const result: Record<string, unknown> = {};
-      for (const key of Object.getOwnPropertyNames(shape)) {
-        if (!Object.hasOwn(shape, key)) continue;
-        const field = (shape as Record<string, unknown>)[key];
-        const value = exampleFromSchema(field);
-        if (value !== undefined) result[key] = value;
+    case "object": {
+      // v4 exposes `.shape` as a plain property on the object schema.
+      if (!(schema instanceof Object) || !("shape" in schema)) return {};
+      // SAFETY: object schemas expose their field schemas keyed by name.
+      const fieldsByName = (schema as { shape: { [field: string]: ZodSchemaLike } }).shape;
+      if (!(fieldsByName instanceof Object)) return {};
+      const result: { [key: string]: SchemaExample } = {};
+      for (const field of Object.getOwnPropertyNames(fieldsByName)) {
+        if (!Object.hasOwn(fieldsByName, field)) continue;
+        const schemaNode = fieldsByName[field];
+        const value = exampleFromSchema(schemaNode);
+        if (value !== undefined) result[field] = value;
       }
       return result;
     }

package/src/access-http.test.ts

@@ -2165,7 +2165,7 @@ test("HTTP offline snapshot rejects out-of-range baseline mtimes as validation e
     assert.equal(response.status, 400);
     assert.equal(body.code, "validation_error");
     assert.equal(body.details?.[0]?.field, "baseFiles.0.mtimeMs");
-    assert.match(body.details?.[0]?.message ?? "", /less than or equal/);
+    assert.match(body.details?.[0]?.message ?? "", /<=8640000000000000/);
     assert.equal(calls, 0);
   } finally {
     await server.stop();

package/src/access-schema.ts

@@ -369,11 +369,7 @@ export function reapplyCategoryCoercion<T extends object>(
 const categoryWireSchema = z.enum(
   [...MEMORY_CATEGORY_CANONICAL_INPUT, ...MEMORY_CATEGORY_ALIAS_INPUT],
   {
-    errorMap: () => ({
-      message:
-        `category must be one of: ${[...MEMORY_CATEGORY_CANONICAL_INPUT, ...MEMORY_CATEGORY_ALIAS_INPUT].join(", ")}; ` +
-        'for project state/facts use "fact"',
-    }),
+    error: `category must be one of: ${[...MEMORY_CATEGORY_CANONICAL_INPUT, ...MEMORY_CATEGORY_ALIAS_INPUT].join(", ")}; for project state/facts use "fact"`,
   },
 );
 
@@ -454,7 +450,7 @@ export const reviewDispositionRequestSchema = z.object({
 export const trustZonePromoteRequestSchema = z.object({
   recordId: z.string().trim().min(1, "recordId is required"),
   targetZone: z.enum(["working", "trusted"], {
-    errorMap: () => ({ message: "targetZone must be 'working' or 'trusted'" }),
+    error: "targetZone must be 'working' or 'trusted'",
   }),
   promotionReason: z.string().trim().min(1, "promotionReason is required"),
   recordedAt: z.string().trim().optional(),
@@ -662,16 +658,13 @@ export const offlineSyncSnapshotRequestSchema = z.object({
     .optional(),
 });
 
-export const offlineSyncApplyRequestSchema = z
-  .object({
-    namespace: namespaceSchema,
-    changeset: z.unknown(),
-    returnCurrentFiles: z.boolean().optional(),
-  })
-  .refine((value) => value.changeset !== undefined && value.changeset !== null, {
-    message: "changeset is required",
-    path: ["changeset"],
-  });
+export const offlineSyncApplyRequestSchema = z.object({
+  namespace: namespaceSchema,
+  // zod 4: refine messages cannot override its synthesized nonoptional check,
+  // so presence is enforced on the field itself.
+  changeset: z.custom<unknown>((value) => value !== undefined && value !== null, "changeset is required"),
+  returnCurrentFiles: z.boolean().optional(),
+});
 
 export const offlineSyncFilesRequestSchema = z.object({
   namespace: namespaceSchema,
@@ -693,8 +686,11 @@ export const offlineSyncFileContentRequestSchema = z.object({
 // Action confidence
 // ---------------------------------------------------------------------------
 
+// Outer .optional() keeps the inferred property optional: a transform-typed
+// property becomes required-with-undefined under zod 4 inference, breaking
+// object literals that legitimately omit the key.
 const nullableOptional = <T extends z.ZodTypeAny>(schema: T) =>
-  schema.optional().nullable().transform((value) => value ?? undefined);
+  schema.nullable().transform((value) => value ?? undefined).optional();
 
 const actionConfidenceRuleSchema = z
   .object({

package/src/extraction-scope-source-agent.test.ts

@@ -92,13 +92,13 @@ test("scope prompt qualifies tool knowledge as project, requires naming the agen
   assert.match(captured.system, /"`git status --short` emits compact output" -> "global"/);
 });
 
-// ExtractedFactSchema is z.object(...).superRefine(...); unwrap the ZodEffects
-// to reach the scope field's describe text (named const, not an inline cast).
+// zod 4: superRefine attaches checks to the object itself — the schema stays
+// a ZodObject, so the scope field's describe text is on `.shape` directly.
 function scopeDescribe(): string {
-  const unwrapped = ExtractedFactSchema as unknown as {
-    innerType(): { shape: Record<string, { description?: string }> };
-  };
-  return unwrapped.innerType().shape.scope?.description ?? "";
+  // SAFETY: ExtractedFactSchema is a ZodObject in zod 4 (superRefine attaches
+  // checks in place); its `.shape` maps field names to schema nodes.
+  const schema = ExtractedFactSchema as { shape: Record<string, { description?: string }> };
+  return schema.shape.scope?.description ?? "";
 }
 
 test("scope field schema describe no longer lists tool configs and qualifies by agent", () => {

package/src/extraction-span-wire.test.ts

@@ -34,3 +34,31 @@ test("provider schema omits span in off mode and keeps it in on/shadow (issue #2
   assert.deepEqual(extractionProviderJsonSchema("on"), extractionProviderJsonSchema("shadow"));
   assert.notEqual(extractionProviderJsonSchema("off"), extractionProviderJsonSchema("on"));
 });
+
+// Providers receive this as the extraction response_format. zod 3 advertised
+// additionalProperties:false on every object; the zod 4 port must too.
+type SchemaNode = {
+  type?: string;
+  properties?: Record<string, SchemaNode>;
+  items?: SchemaNode;
+  anyOf?: SchemaNode[];
+  additionalProperties?: boolean | SchemaNode;
+};
+
+function openObjectSchemas(node: SchemaNode, path: string, found: string[]): void {
+  if (node.type === "object" && node.properties && node.additionalProperties !== false) found.push(path);
+  for (const [name, child] of Object.entries(node.properties ?? {})) {
+    openObjectSchemas(child, `${path}.${name}`, found);
+  }
+  if (node.items) openObjectSchemas(node.items, `${path}[]`, found);
+  node.anyOf?.forEach((child, index) => openObjectSchemas(child, `${path}|${index}`, found));
+}
+
+test("provider schema closes every object schema with additionalProperties false", () => {
+  for (const mode of ["off", "on"] as const) {
+    const open: string[] = [];
+    // SAFETY: extractionProviderJsonSchema returns a JSON Schema document; SchemaNode names the keys walked here.
+    openObjectSchemas(extractionProviderJsonSchema(mode) as SchemaNode, "$", open);
+    assert.deepEqual(open, [], `spanMode=${mode}: objects that let a provider emit extra keys`);
+  }
+});

package/src/extraction-span-wire.ts

@@ -5,7 +5,7 @@
  * schema is mode-aware so off-mode structured output cannot advertise `span`.
  */
 
-import { zodToJsonSchema } from "zod-to-json-schema";
+import { z } from "zod";
 import type { ExtractionSpanConfig } from "./extraction-span-config.js";
 import { parseSpanOffsets, type ParsedSpan } from "./extraction-span.js";
 import { ExtractionProviderOutputSchema } from "./schemas.js";
@@ -19,13 +19,41 @@ export function applySpanMode(opts: {
   return parseSpanOffsets(opts.text, { start: opts.start, end: opts.end }, opts.enabled);
 }
 
-const JSON_SCHEMA_OPTS = { $refStrategy: "none" as const, effectStrategy: "input" as const };
+/** The parts of a JSON Schema node the extraction schema uses. */
+type SchemaNode = {
+  type?: string;
+  properties?: Record<string, SchemaNode>;
+  items?: SchemaNode;
+  anyOf?: SchemaNode[];
+  additionalProperties?: boolean | SchemaNode;
+};
 
-const EXTRACTION_PROVIDER_JSON_SCHEMA_WITH_SPAN = zodToJsonSchema(
-  ExtractionProviderOutputSchema,
-  JSON_SCHEMA_OPTS,
-) as Record<string, unknown>;
+/**
+ * `io: "input"` leaves objects open (zod accepts extra input keys), but providers
+ * must be told to emit no extra keys: zod-to-json-schema advertised
+ * additionalProperties:false on every object. Close any object schema that
+ * does not already state its own.
+ */
+function closeObjectSchemas(node: SchemaNode): SchemaNode {
+  if (node.type === "object" && node.properties && node.additionalProperties === undefined) {
+    node.additionalProperties = false;
+  }
+  Object.values(node.properties ?? {}).forEach(closeObjectSchemas);
+  if (node.items) closeObjectSchemas(node.items);
+  node.anyOf?.forEach(closeObjectSchemas);
+  return node;
+}
 
+// zod 4 ships toJSONSchema natively; zod-to-json-schema emits an empty
+// document for v4 schemas, so the dependency is dropped here. `io: "input"`
+// matches the old effectStrategy: "input" (advertise the input shape of
+// transforms/preprocess to providers).
+// SAFETY: z.toJSONSchema returns a JSON-Schema document — always an object at
+// the root; the record shape is what omitFactSpan walks.
+const EXTRACTION_PROVIDER_JSON_SCHEMA_WITH_SPAN: SchemaNode = closeObjectSchemas(
+  // SAFETY: z.toJSONSchema returns a JSON Schema document; SchemaNode names the keys this file reads.
+  z.toJSONSchema(ExtractionProviderOutputSchema, { target: "draft-7", io: "input" }) as SchemaNode,
+);
 type FactItems = {
   properties?: Record<string, unknown>;
   required?: string[];

package/src/orchestration/extraction-persist-deps.ts

@@ -106,4 +106,7 @@ export interface ExtractionPersistDeps {
    */
   invalidateGraphEdgeCache?: (storage: StorageManager) => void;
   updateTemporalTagIndexes: (storage: StorageManager, persistedIds: string[]) => Promise<void>;
+  /** Schedule QMD reindex after partial durable writes that throw out of persist. */
+  requestQmdMaintenance: () => void;
+
 }