stitchkit 0.24.0 → 0.25.0

package/dist/cli.js

@@ -4,7 +4,7 @@ import {
   emitResult,
   parseCliArgs,
   pollUntilDone
-} from "./index-x8m8e7dc.js";
+} from "./index-h9d1fm0p.js";
 import"./index-0ed3bx43.js";
 import"./index-4gawbm74.js";
 import"./index-c7nyw0yt.js";

package/dist/{index-x8m8e7dc.js → index-h9d1fm0p.js}

@@ -76,13 +76,66 @@ function coerceJsonArgs(args, schema) {
 }
 
 // src/tools/flatten.ts
+import { z as z3 } from "zod";
+
+// src/tools/schema.ts
 import { z as z2 } from "zod";
+function objectShapeKeys(schema) {
+  return schema instanceof z2.ZodObject ? Object.keys(schema.shape) : [];
+}
+function keyPolicyOf(schema) {
+  return schema.def.catchall;
+}
+function rebuildObject(source, shape) {
+  return withKeyPolicy(z2.object(shape), keyPolicyOf(source));
+}
+function withKeyPolicy(object, policy) {
+  if (policy === undefined)
+    return object;
+  return object.catchall(representable(policy));
+}
+function representable(policy) {
+  if (policy instanceof z2.ZodNever || policy instanceof z2.ZodUnknown)
+    return policy;
+  if (!(policy instanceof z2.ZodType))
+    return z2.unknown();
+  try {
+    toJsonSchema(policy, "input");
+    return policy;
+  } catch {
+    return z2.unknown();
+  }
+}
+function mergeSchemas(paramsSchema, inputSchema) {
+  if (paramsSchema && !(paramsSchema instanceof z2.ZodObject)) {
+    throw new Error("Tool params schema must be a z.object()");
+  }
+  const paramsObject = paramsSchema instanceof z2.ZodObject ? paramsSchema : undefined;
+  if (!inputSchema) {
+    return paramsObject ?? z2.object({});
+  }
+  if (inputSchema instanceof z2.ZodObject) {
+    if (paramsObject) {
+      const conflicts = Object.keys(paramsObject.shape).filter((key) => (key in inputSchema.shape));
+      if (conflicts.length > 0) {
+        throw new Error(`Schema merge conflict: ${conflicts.join(", ")} appear in both params and input`);
+      }
+    }
+    return rebuildObject(inputSchema, {
+      ...paramsObject?.shape ?? {},
+      ...inputSchema.shape
+    });
+  }
+  return paramsObject ? z2.intersection(paramsObject, inputSchema) : inputSchema;
+}
+
+// src/tools/flatten.ts
 function flattenDiscriminatedUnion(union) {
   const discriminator = union.def.discriminator;
   const allDiscValues = [];
   const perKey = new Map;
   for (const opt of union.def.options) {
-    if (!(opt instanceof z2.ZodObject)) {
+    if (!(opt instanceof z3.ZodObject)) {
       throw new Error(`flattenDiscriminatedUnion: variant for discriminator '${discriminator}' is not a ZodObject`);
     }
     const discValues = stringLiteralOrEnumValues(opt.shape[discriminator]);
@@ -95,7 +148,7 @@ function flattenDiscriminatedUnion(union) {
       if (key === discriminator)
         continue;
       const entry = perKey.get(key) ?? { schemas: [], variants: [] };
-      entry.schemas.push(field instanceof z2.ZodOptional ? field.unwrap() : field);
+      entry.schemas.push(unwrapField(field));
       entry.variants.push(label);
       perKey.set(key, entry);
     }
@@ -106,23 +159,44 @@ function flattenDiscriminatedUnion(union) {
     throw new Error("flattenDiscriminatedUnion: union has no options");
   }
   const shape = {
-    [discriminator]: z2.enum([firstLiteral, ...restLiterals])
+    [discriminator]: z3.enum([firstLiteral, ...restLiterals])
   };
   for (const [key, entry] of perKey) {
     const advertised = mergeCollidingFields(entry.schemas);
     const hint = `Required if ${discriminator} = ${[...new Set(entry.variants)].join(" | ")}`;
-    shape[key] = z2.optional(advertised).describe(hint);
+    shape[key] = z3.optional(advertised).describe(hint);
+  }
+  return withKeyPolicy(z3.object(shape), mergeVariantKeyPolicies(union.def.options));
+}
+function mergeVariantKeyPolicies(options) {
+  let strict = 0;
+  let counted = 0;
+  for (const option of options) {
+    const policy = option instanceof z3.ZodObject ? keyPolicyOf(option) : undefined;
+    if (policy !== undefined && !(policy instanceof z3.ZodNever))
+      return z3.unknown();
+    counted++;
+    if (policy instanceof z3.ZodNever)
+      strict++;
+  }
+  if (counted === 0 || strict === 0)
+    return;
+  return strict === counted ? z3.never() : z3.unknown();
+}
+function unwrapField(field) {
+  if (field instanceof z3.ZodOptional || field instanceof z3.ZodDefault) {
+    return unwrapField(field.unwrap());
   }
-  return z2.object(shape);
+  return field;
 }
 function preserveDescription(from, to) {
   return from.description === undefined ? to : to.describe(from.description);
 }
 function stringLiteralOrEnumValues(field) {
   let raw = null;
-  if (field instanceof z2.ZodLiteral)
+  if (field instanceof z3.ZodLiteral)
     raw = field.def.values;
-  else if (field instanceof z2.ZodEnum)
+  else if (field instanceof z3.ZodEnum)
     raw = field.options;
   if (raw === null)
     return null;
@@ -134,7 +208,7 @@ function isFlattenableDU(union) {
   if (union.def.options.length === 0)
     return false;
   for (const opt of union.def.options) {
-    if (!(opt instanceof z2.ZodObject))
+    if (!(opt instanceof z3.ZodObject))
       return false;
     if (stringLiteralOrEnumValues(opt.shape[disc]) === null)
       return false;
@@ -156,31 +230,31 @@ function stripAnnotations(node) {
   }
 }
 function hasChecks(schema) {
-  if (!(schema instanceof z2.ZodType))
+  if (!(schema instanceof z3.ZodType))
     return false;
   const def = schema.def;
   if (isRecord(def) && Array.isArray(def.checks) && def.checks.length > 0)
     return true;
-  if (schema instanceof z2.ZodOptional || schema instanceof z2.ZodNullable || schema instanceof z2.ZodDefault) {
+  if (schema instanceof z3.ZodOptional || schema instanceof z3.ZodNullable || schema instanceof z3.ZodDefault) {
     return hasChecks(schema.unwrap());
   }
-  if (schema instanceof z2.ZodPipe)
+  if (schema instanceof z3.ZodPipe)
     return hasChecks(schema.def.in) || hasChecks(schema.def.out);
-  if (schema instanceof z2.ZodObject)
+  if (schema instanceof z3.ZodObject)
     return Object.values(schema.shape).some(hasChecks);
-  if (schema instanceof z2.ZodArray)
+  if (schema instanceof z3.ZodArray)
     return hasChecks(schema.element);
-  if (schema instanceof z2.ZodUnion)
+  if (schema instanceof z3.ZodUnion)
     return schema.def.options.some(hasChecks);
-  if (schema instanceof z2.ZodRecord)
+  if (schema instanceof z3.ZodRecord)
     return hasChecks(schema.valueType);
-  if (schema instanceof z2.ZodIntersection) {
+  if (schema instanceof z3.ZodIntersection) {
     return hasChecks(schema.def.left) || hasChecks(schema.def.right);
   }
   return false;
 }
 function normalizedJson(schema) {
-  if (!(schema instanceof z2.ZodType))
+  if (!(schema instanceof z3.ZodType))
     return "{}";
   const json = toJsonSchema(schema, "input", "any");
   stripAnnotations(json);
@@ -197,8 +271,8 @@ function mergeCollidingFields(schemas) {
   const only = values[0];
   if (values.length <= 1) {
     if (only === undefined)
-      return z2.unknown();
-    return schemas.length > 1 && hasChecks(only) ? z2.unknown() : only;
+      return z3.unknown();
+    return schemas.length > 1 && hasChecks(only) ? z3.unknown() : only;
   }
   const merged = [];
   let allEnum = true;
@@ -214,47 +288,47 @@ function mergeCollidingFields(schemas) {
     const uniq = [...new Set(merged)];
     const [first, ...rest] = uniq;
     if (first !== undefined)
-      return z2.enum([first, ...rest]);
+      return z3.enum([first, ...rest]);
   }
-  return z2.unknown();
+  return z3.unknown();
 }
 function flattenUnionsDeep(schema) {
-  if (!(schema instanceof z2.ZodType))
-    return z2.unknown();
-  if (schema instanceof z2.ZodDiscriminatedUnion) {
+  if (!(schema instanceof z3.ZodType))
+    return z3.unknown();
+  if (schema instanceof z3.ZodDiscriminatedUnion) {
     if (!isFlattenableDU(schema))
       return schema;
     return preserveDescription(schema, flattenUnionsDeep(flattenDiscriminatedUnion(schema)));
   }
-  if (schema instanceof z2.ZodObject) {
+  if (schema instanceof z3.ZodObject) {
     const shape = {};
     for (const [key, field] of Object.entries(schema.shape)) {
       shape[key] = flattenUnionsDeep(field);
     }
-    return preserveDescription(schema, z2.object(shape));
+    return preserveDescription(schema, rebuildObject(schema, shape));
   }
-  if (schema instanceof z2.ZodArray) {
-    return preserveDescription(schema, z2.array(flattenUnionsDeep(schema.element)));
+  if (schema instanceof z3.ZodArray) {
+    return preserveDescription(schema, z3.array(flattenUnionsDeep(schema.element)));
   }
-  if (schema instanceof z2.ZodUnion) {
+  if (schema instanceof z3.ZodUnion) {
     const opts = schema.def.options.map((option) => flattenUnionsDeep(option));
     const [a, b, ...rest] = opts;
-    return a && b ? preserveDescription(schema, z2.union([a, b, ...rest])) : schema;
+    return a && b ? preserveDescription(schema, z3.union([a, b, ...rest])) : schema;
   }
-  if (schema instanceof z2.ZodRecord) {
-    return preserveDescription(schema, z2.record(schema.keyType, flattenUnionsDeep(schema.valueType)));
+  if (schema instanceof z3.ZodRecord) {
+    return preserveDescription(schema, z3.record(schema.keyType, flattenUnionsDeep(schema.valueType)));
   }
-  if (schema instanceof z2.ZodOptional) {
-    return preserveDescription(schema, z2.optional(flattenUnionsDeep(schema.unwrap())));
+  if (schema instanceof z3.ZodOptional) {
+    return preserveDescription(schema, z3.optional(flattenUnionsDeep(schema.unwrap())));
   }
-  if (schema instanceof z2.ZodNullable) {
-    return preserveDescription(schema, z2.nullable(flattenUnionsDeep(schema.unwrap())));
+  if (schema instanceof z3.ZodNullable) {
+    return preserveDescription(schema, z3.nullable(flattenUnionsDeep(schema.unwrap())));
   }
-  if (schema instanceof z2.ZodDefault) {
+  if (schema instanceof z3.ZodDefault) {
     return preserveDescription(schema, flattenUnionsDeep(schema.unwrap()).default(schema.def.defaultValue));
   }
-  if (schema instanceof z2.ZodIntersection) {
-    return preserveDescription(schema, z2.intersection(flattenUnionsDeep(schema.def.left), flattenUnionsDeep(schema.def.right)));
+  if (schema instanceof z3.ZodIntersection) {
+    return preserveDescription(schema, z3.intersection(flattenUnionsDeep(schema.def.left), flattenUnionsDeep(schema.def.right)));
   }
   return schema;
 }
@@ -262,31 +336,6 @@ function flattenUnionsDeep(schema) {
 // src/tools/mount.ts
 import { z as z4 } from "zod";
 
-// src/tools/schema.ts
-import { z as z3 } from "zod";
-function objectShapeKeys(schema) {
-  return schema instanceof z3.ZodObject ? Object.keys(schema.shape) : [];
-}
-function mergeSchemas(paramsSchema, inputSchema) {
-  if (paramsSchema && !(paramsSchema instanceof z3.ZodObject)) {
-    throw new Error("Tool params schema must be a z.object()");
-  }
-  const paramsObject = paramsSchema instanceof z3.ZodObject ? paramsSchema : undefined;
-  if (!inputSchema) {
-    return paramsObject ?? z3.object({});
-  }
-  if (inputSchema instanceof z3.ZodObject) {
-    if (paramsObject) {
-      const conflicts = Object.keys(paramsObject.shape).filter((key) => (key in inputSchema.shape));
-      if (conflicts.length > 0) {
-        throw new Error(`Schema merge conflict: ${conflicts.join(", ")} appear in both params and input`);
-      }
-    }
-    return z3.object({ ...paramsObject?.shape ?? {}, ...inputSchema.shape });
-  }
-  return paramsObject ? z3.intersection(paramsObject, inputSchema) : inputSchema;
-}
-
 // src/tools/execute.ts
 function toolResultFromError(err) {
   const appErr = normalizeError(err);
@@ -421,7 +470,7 @@ function applyExtend(base, extra) {
     if (conflicts.length > 0) {
       throw new Error(`Tool extend conflict: ${conflicts.join(", ")} already declared by the contract`);
     }
-    return z4.object({ ...extra, ...base.shape });
+    return rebuildObject(base, { ...extra, ...base.shape });
   }
   return z4.intersection(z4.object(extra), base);
 }

package/dist/tools/coerce.d.ts

@@ -6,7 +6,8 @@ import { z } from 'zod';
  * Operates recursively against the schema (object fields, array items, and the
  * matching variant of a discriminated union) so a stringified value at any depth
  * is repaired, not just a top-level field. The transform touches the **arguments**
- * only — the advertised tool schema stays exactly the contract schema.
+ * only — it never rebuilds a schema, so it cannot alter what an object does with
+ * an undeclared key (→ ADR 0034).
  */
 export declare function coerceJsonArgs(args: Record<string, unknown>, schema: z.ZodType | undefined): Record<string, unknown>;
 //# sourceMappingURL=coerce.d.ts.map

package/dist/tools/coerce.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"coerce.d.ts","sourceRoot":"","sources":["../../src/tools/coerce.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAoFxB;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,SAAS,GAC5B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAGzB"}
+{"version":3,"file":"coerce.d.ts","sourceRoot":"","sources":["../../src/tools/coerce.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAoFxB;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,SAAS,GAC5B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAGzB"}

package/dist/tools/flatten.d.ts

@@ -18,10 +18,18 @@ import { z } from 'zod';
  * 0033) **and** a superset of the original union, so a model can always produce a
  * value that passes both the transport SDK and validation.
  *
- * **Lossy and advertised-only:** the original union remains the validation schema
- * in `executeToolMethod`. `.strict()` / `.catchall()` / object-level refinements
- * on variants are dropped from the *advertised* hint (validation still enforces
- * them — see ADR 0033 on the strict-variant caveat).
+ * **Key policy is merged, not dropped.** The flat object stands in for every
+ * variant, so it takes the policy that cannot remove what any variant would have
+ * kept: every variant `.strict()` → strict (sound, because the flat shape is the
+ * union of all variant keys); any variant with a catchall → loose; otherwise
+ * plain. A *typed* catchall is never copied onto the flat object — it would
+ * reject a sibling variant's differently-typed extra key.
+ *
+ * **Still lossy:** per-variant strictness (a key legal in variant A and illegal
+ * in B) is unrepresentable in one flat object, as are object-level refinements.
+ * Those stay enforced only by the original union in `executeToolMethod`. What is
+ * *not* lossy any more is deletion — the advertised schema can no longer drop a
+ * key the contract would have seen. → ADR 0034.
  */
 export declare function flattenDiscriminatedUnion(union: z.ZodDiscriminatedUnion): z.ZodObject<z.ZodRawShape>;
 /**
@@ -30,8 +38,10 @@ export declare function flattenDiscriminatedUnion(union: z.ZodDiscriminatedUnion
  * and `optional` / `nullable` / `default` / intersection wrappers — so the
  * advertised JSON Schema carries no `oneOf` / `anyOf` at any depth. A union that
  * cannot be flattened (non-string discriminator, non-object variant) is left
- * untouched rather than crashing the mount (→ ADR 0033). Advertised-only; the
- * original schemas remain the validation schemas.
+ * untouched rather than crashing the mount (→ ADR 0033).
+ *
+ * Every object is rebuilt **with its key policy** (`rebuildObject`) — the walk
+ * changes union shape, never what an object does with an undeclared key. → ADR 0034.
  */
 export declare function flattenUnionsDeep(schema: z.core.$ZodType): z.ZodType;
 //# sourceMappingURL=flatten.d.ts.map

package/dist/tools/flatten.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flatten.d.ts","sourceRoot":"","sources":["../../src/tools/flatten.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,CAAC,CAAC,qBAAqB,GAC7B,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CA6C5B;AAmID;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC,OAAO,CAkDpE"}
+{"version":3,"file":"flatten.d.ts","sourceRoot":"","sources":["../../src/tools/flatten.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,CAAC,CAAC,qBAAqB,GAC7B,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAiD5B;AAsKD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC,OAAO,CAqDpE"}

package/dist/tools/mount.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mount.d.ts","sourceRoot":"","sources":["../../src/tools/mount.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EACL,KAAK,WAAW,EAEhB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,UAAU,EAChB,MAAM,WAAW,CAAC;AAKnB;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU,CACzB,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAElE,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;IAClC,qEAAqE;IACrE,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC3F,uEAAuE;IACvE,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC;CAC9D;AAED,2DAA2D;AAC3D,MAAM,WAAW,aAAa;IAC5B,2CAA2C;IAC3C,MAAM,EAAE,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAC7C,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,sFAAsF;IACtF,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC;IAClB,mDAAmD;IACnD,YAAY,EAAE,OAAO,CAAC;CACvB;AAkBD,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,uFAAuF;IACvF,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,UAAU,EACnB,SAAS,EAAE,SAAS,EACpB,MAAM,GAAE,kBAAuB,GAC9B,aAAa,EAAE,CAkCjB;AAED,kDAAkD;AAClD,MAAM,WAAW,gBAAgB;IAC/B,iDAAiD;IACjD,MAAM,EAAE,eAAe,CAAC;IACxB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,qCAAqC;IACrC,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,yEAAyE;IACzE,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,gEAAgE;IAChE,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,+EAA+E;IAC/E,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,gBAAgB,GACvB,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,UAAU,CAAC,CA4BhF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,OAAO,CAAC,UAAU,EAAE;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CAAC,EAC1C,QAAQ,CAAC,EAAE,MAAM,EACjB,SAAS,CAAC,EAAE,WAAW,GACtB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAazB"}
+{"version":3,"file":"mount.d.ts","sourceRoot":"","sources":["../../src/tools/mount.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EACL,KAAK,WAAW,EAEhB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,UAAU,EAChB,MAAM,WAAW,CAAC;AAKnB;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU,CACzB,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAElE,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;IAClC,qEAAqE;IACrE,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC3F,uEAAuE;IACvE,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC;CAC9D;AAED,2DAA2D;AAC3D,MAAM,WAAW,aAAa;IAC5B,2CAA2C;IAC3C,MAAM,EAAE,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAC7C,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,sFAAsF;IACtF,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC;IAClB,mDAAmD;IACnD,YAAY,EAAE,OAAO,CAAC;CACvB;AAyBD,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,uFAAuF;IACvF,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,UAAU,EACnB,SAAS,EAAE,SAAS,EACpB,MAAM,GAAE,kBAAuB,GAC9B,aAAa,EAAE,CAmCjB;AAED,kDAAkD;AAClD,MAAM,WAAW,gBAAgB;IAC/B,iDAAiD;IACjD,MAAM,EAAE,eAAe,CAAC;IACxB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,qCAAqC;IACrC,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,yEAAyE;IACzE,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,gEAAgE;IAChE,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,+EAA+E;IAC/E,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,gBAAgB,GACvB,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,UAAU,CAAC,CA4BhF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,OAAO,CAAC,UAAU,EAAE;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CAAC,EAC1C,QAAQ,CAAC,EAAE,MAAM,EACjB,SAAS,CAAC,EAAE,WAAW,GACtB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAazB"}

package/dist/tools/schema.d.ts

@@ -1,6 +1,39 @@
 import { z } from 'zod';
 /** Keys of a Zod object schema's shape — `[]` for a non-object or absent schema. */
 export declare function objectShapeKeys(schema?: z.ZodType): string[];
+/**
+ * An object schema's own key policy — what it does with a key its shape does not
+ * declare. Zod stores it in `def.catchall`: `ZodNever` for `.strict()` (reject),
+ * `ZodUnknown` for `.loose()` / `.passthrough()` (keep), a concrete type for
+ * `.catchall(T)` (keep and validate), `undefined` for a plain object (strip).
+ */
+export type KeyPolicy = z.core.$ZodType | undefined;
+/** The key policy of an object schema. */
+export declare function keyPolicyOf(schema: z.ZodObject): KeyPolicy;
+/**
+ * Rebuild an object schema with a new shape, **carrying the source object's key
+ * policy over**.
+ *
+ * Load-bearing, not cosmetic: the advertised tool schema is not
+ * advertised-only. Both transport SDKs parse the caller's arguments *with it* and
+ * hand the handler the parsed result (MCP `validateToolInput` →
+ * `parseResult.data`; the AI SDK's `doParseToolCall` → `parseResult.value`), so
+ * an object rebuilt as a bare `z.object()` silently **deletes** every key the
+ * contract schema would have rejected (`.strict()`) or kept (`.loose()` /
+ * `.catchall()`) — the caller gets a success and never learns its argument was
+ * wrong. → ADR 0034.
+ *
+ * A plain source (`undefined` policy) needs no special case: the rebuilt object
+ * strips exactly as the contract object would have.
+ *
+ * A policy JSON Schema cannot represent (`.catchall(z.date())`) degrades to
+ * `z.unknown()`: copying it verbatim would fail the mount's JSON Schema probe and
+ * take every tool down with it, while dropping it would silently delete data.
+ * Loose keeps the invariant — nothing the contract would have kept is removed.
+ */
+export declare function rebuildObject(source: z.ZodObject, shape: Record<string, z.core.$ZodType>): z.ZodObject;
+/** Apply a key policy to a freshly built object, degrading what JSON Schema cannot carry. */
+export declare function withKeyPolicy(object: z.ZodObject<z.ZodRawShape>, policy: KeyPolicy): z.ZodObject;
 /**
  * Merge an endpoint's `params` and `input` schemas into the single schema a
  * tool advertises.
@@ -10,12 +43,21 @@ export declare function objectShapeKeys(schema?: z.ZodType): string[];
  * - A non-object `input` (a union, a discriminated union, a refined / piped
  *   schema) is kept intact and intersected with `params` when present — the
  *   transport SDK converts it natively (a discriminated union becomes a clean
- *   `oneOf`).
+ *   `oneOf`). ⚠️ Zod drops both sides' key policy when it intersects objects, so
+ *   this branch still strips (MCP rejects a non-object merged schema at mount;
+ *   the agent surface does not). → ADR 0034, "Not covered".
  *
  * The merged schema is exactly the two source schemas side by side: nothing is
  * coerced, flattened or transformed, so the schema a tool advertises is the
  * schema its arguments are validated against (`executeToolMethod` parses each
  * source schema over its own slice of the args).
+ *
+ * The merged object takes the **input** schema's key policy, never the params
+ * one. `executeToolMethod` slices the flat args by the params shape's keys and
+ * routes *everything else* into the input slice, so a params catchall can never
+ * fire (its slice is built from its own shape) while an undeclared top-level key
+ * is judged by the input schema. A params-only tool returns the params object
+ * untouched, policy included.
  */
 export declare function mergeSchemas(paramsSchema?: z.ZodType<unknown>, inputSchema?: z.ZodType<unknown>): z.ZodType;
 //# sourceMappingURL=schema.d.ts.map

package/dist/tools/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/tools/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,oFAAoF;AACpF,wBAAgB,eAAe,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,OAAO,GAAG,MAAM,EAAE,CAE5D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAC1B,YAAY,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,EACjC,WAAW,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,GAC/B,CAAC,CAAC,OAAO,CA2BX"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/tools/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,oFAAoF;AACpF,wBAAgB,eAAe,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,OAAO,GAAG,MAAM,EAAE,CAE5D;AAED;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,IAAI,CAAC,QAAQ,GAAG,SAAS,CAAC;AAEpD,0CAA0C;AAC1C,wBAAgB,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC,SAAS,GAAG,SAAS,CAE1D;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,CAAC,CAAC,SAAS,EACnB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,GACrC,CAAC,CAAC,SAAS,CAEb;AAED,6FAA6F;AAC7F,wBAAgB,aAAa,CAC3B,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,EAClC,MAAM,EAAE,SAAS,GAChB,CAAC,CAAC,SAAS,CAGb;AAcD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,YAAY,CAC1B,YAAY,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,EACjC,WAAW,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,GAC/B,CAAC,CAAC,OAAO,CA8BX"}

package/dist/tools.js

@@ -18,7 +18,7 @@ import {
   pollUntil,
   readCapped,
   toolResultFromError
-} from "./index-x8m8e7dc.js";
+} from "./index-h9d1fm0p.js";
 import {
   toJsonSchema
 } from "./index-0ed3bx43.js";

package/llms-full.txt

@@ -1303,11 +1303,23 @@ each variant's fields become optional with a `Required if <disc> = …` hint.
 It is **deep**: unions are flattened at every depth — top level, object fields,
 array items, and through `optional` / `nullable` / `default` / intersection
 wrappers — so no `oneOf` survives anywhere (e.g. a `content.parts[]` that is an
-array of a discriminated union). It is **advertised-only and lossy**: the original
-schemas stay the validation schemas in `executeToolMethod`, so requests are still
-validated against the real union. Schemas a transform cannot safely rebuild
+array of a discriminated union). Schemas a transform cannot safely rebuild
 (refined / piped / lazy / plain non-discriminated unions) are left as-is.
 
+The flattened form is **lossy but never destructive**. Lossy: per-variant
+strictness and object-level refinements are not advertised — the original schemas
+enforce them in `executeToolMethod`. Not destructive: every object keeps its own
+**key policy** (`.strict()` stays strict, `.loose()` / `.catchall()` still keep
+extra keys), because the advertised schema is not advertised-only — the MCP and
+AI SDKs parse the caller's arguments *with it* and hand the handler the parsed
+result. An object advertised without its policy would silently delete keys the
+contract would have rejected. → [ADR 0034](../decisions/0034-advertised-schema-key-policy.md).
+
+A consequence worth knowing when you read logs: a `.strict()` violation is caught
+by the SDK **before** the tool callback runs, so it comes back as an MCP
+`InvalidParams` protocol error rather than a stitchkit `VALIDATION_ERROR`
+envelope, and `beforeToolCall` / `afterToolCall` do not fire for it.
+
 ## `mountMcp`
 
 If you already run an `McpServer` from the SDK, `mountMcp` adds contract tools
@@ -3529,7 +3541,7 @@ Advanced building blocks — the shared machinery the mounts are built on.
 | `TransportCounts` | _type_ | per-transport counts (`{ HTTP, MCP, AGENT, CLI }`) |
 | `coerceJsonArgs` | function | coerce JSON-stringified array/object tool arguments |
 | `flattenDiscriminatedUnion` | function | flatten one discriminated union into a single object schema |
-| `flattenUnionsDeep` | function | flatten discriminated unions at every depth (advertised schema only) |
+| `flattenUnionsDeep` | function | flatten discriminated unions at every depth — union shape only; each object keeps its own key policy (`.strict()` / `.loose()` / `.catchall()`) |
 | `MountableTool` | _type_ | one contract method resolved for mounting |
 | `ToolManifestEntry` | _type_ | one `buildToolManifest` row |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",