@gajae-code/ai 0.1.1

package/src/utils/schema/spill.ts

@@ -0,0 +1,43 @@
+import type { JsonObject } from "./types";
+
+export type DescriptionSpillFormat = "spill" | "paren";
+
+function formatSpillValue(value: unknown): string {
+	return JSON.stringify(value);
+}
+
+function formatParenValue(value: unknown): string {
+	return typeof value === "string" ? value : JSON.stringify(value);
+}
+
+/**
+ * Demote stripped JSON Schema keywords into a node's `description` so the model
+ * still receives the constraint as natural-language context after the wire
+ * schema drops it.
+ */
+export function spillToDescription(
+	node: JsonObject,
+	entries: ReadonlyArray<readonly [string, unknown]>,
+	format: DescriptionSpillFormat = "spill",
+): void {
+	let spilled: Array<readonly [string, unknown]> | undefined;
+	for (const entry of entries) {
+		if (entry[1] === undefined) continue;
+		if (spilled === undefined) spilled = [];
+		spilled.push(entry);
+	}
+	if (spilled === undefined || spilled.length === 0) return;
+
+	const existing = typeof node.description === "string" ? node.description : "";
+	if (format === "paren") {
+		let suffix = "";
+		for (const [key, value] of spilled) {
+			suffix += ` (${key}: ${formatParenValue(value)})`;
+		}
+		node.description = `${existing}${suffix}`;
+		return;
+	}
+
+	const formatted = `{${spilled.map(([key, value]) => `${key}: ${formatSpillValue(value)}`).join(", ")}}`;
+	node.description = existing ? `${existing}\n\n${formatted}` : formatted;
+}

package/src/utils/schema/stamps.ts

@@ -0,0 +1,97 @@
+/**
+ * Symbol-keyed lazy memoization stamped directly onto the host object.
+ *
+ * Faster than a module-level `WeakMap` in V8/JSC because the symbol slot is
+ * resolved through the object's hidden class instead of a side-table hash
+ * lookup. The slot is defined as a non-enumerable property so the stamp
+ * does not leak through `{...spread}`, `Object.keys`, `JSON.stringify`, or
+ * `toEqual`-style deep equality.
+ *
+ * Caveats: the stamp lives as long as the host object, even after callers
+ * release their references to the cached value — only use this for caches
+ * whose lifetime should match the host. Frozen hosts will throw on write in
+ * strict mode; callers that may receive frozen input must handle that.
+ */
+
+function define<T extends object>(target: T, key: symbol, value: unknown): void {
+	Object.defineProperty(target, key, { value, writable: true, configurable: true });
+}
+
+export function stamp<T extends object, V>(target: T, key: symbol, compute: (target: T) => V): V {
+	const slot = target as Record<symbol, V | undefined>;
+	const existing = slot[key];
+	if (existing !== undefined) return existing;
+	const value = compute(target);
+	define(target, key, value);
+	return value;
+}
+
+/**
+ * Epoch-keyed cycle guard. Cheaper than `WeakSet` for recursive traversal
+ * because the marker is a single property slot on the host object, written
+ * once and overwritten in place on every subsequent traversal — the hidden
+ * class transitions once per object lifetime, not per traversal.
+ *
+ * Usage:
+ *   function walk(node, epoch = epochNext()) {
+ *     if (!once(node, epoch)) return; // cycle
+ *     for (const child of node.children) walk(child, epoch);
+ *   }
+ */
+const kEpoch = Symbol("pi.schema.epoch");
+let __epoch = 0;
+
+export function epochNext(): number {
+	return ++__epoch;
+}
+
+/**
+ * Marks `target` as visited for this `epoch`. Returns `true` the first time
+ * it is called for a given (target, epoch) pair and `false` on every
+ * subsequent call within the same epoch.
+ */
+export function once<T extends object>(target: T, epoch: number): boolean {
+	const slot = target as Record<symbol, number | undefined>;
+	const cur = slot[kEpoch];
+	if (cur !== undefined && cur >= epoch) return false;
+	if (cur === undefined) define(target, kEpoch, epoch);
+	else slot[kEpoch] = epoch;
+	return true;
+}
+
+/**
+ * Counter-based path tracker. Use when a traversal needs to distinguish
+ * "currently on the recursion path" from "previously visited" — i.e. cycle
+ * detection that throws while still allowing DAG sharing. Increment on
+ * entry, decrement on exit; the slot returns to 0 after a balanced walk so
+ * subsequent top-level calls see a fresh state without any reset.
+ *
+ * Unlike a `WeakSet` with `seen.delete(...)`, the property is never deleted
+ * — only incremented and decremented — so the host object's hidden class
+ * is never invalidated.
+ *
+ * Usage:
+ *   function walk(node) {
+ *     if (!enter(node)) throw new Error("cycle");
+ *     try { for (const c of node.children) walk(c); }
+ *     finally { exit(node); }
+ *   }
+ */
+const kDepth = Symbol("pi.schema.depth");
+
+/** Returns `true` on first entry, `false` if `target` is already on the current path. */
+export function enter<T extends object>(target: T): boolean {
+	const slot = target as Record<symbol, number | undefined>;
+	const cur = slot[kDepth];
+	if (cur === undefined) {
+		define(target, kDepth, 1);
+		return true;
+	}
+	slot[kDepth] = cur + 1;
+	return cur === 0;
+}
+
+export function exit<T extends object>(target: T): void {
+	const slot = target as Record<symbol, number>;
+	slot[kDepth]--;
+}

package/src/utils/schema/types.ts

@@ -0,0 +1,11 @@
+export type JsonObject = Record<string, unknown>;
+
+export function isJsonObject(value: unknown): value is JsonObject {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+/** True when `value` is a plain JSON object with no own enumerable keys. */
+export function isJsonObjectEmpty(value: JsonObject): boolean {
+	for (const _ in value) return false;
+	return true;
+}

package/src/utils/schema/wire.ts

@@ -0,0 +1,213 @@
+/**
+ * Compute the wire (JSON Schema) representation of a tool's parameters and
+ * convert TypeBox-style schemas into Zod for internal validation.
+ *
+ * Tools may author parameters in two shapes:
+ *   1. Zod (canonical going forward) — converted to JSON Schema on demand.
+ *   2. TypeBox / plain JSON Schema (legacy + extension compat) — upgraded to
+ *      draft 2020-12 without converting through Zod.
+ *
+ * Both are normalized at the boundary so providers and validators see the same
+ * JSON Schema dialect.
+ */
+
+// We import the Zod *value* (z) for runtime APIs. Marker checks rely on the
+// `_zod` symbol that every Zod v4 schema instance carries.
+import { type ZodType, z } from "zod/v4";
+import type { Tool, TSchema } from "../../types";
+import { upgradeJsonSchemaTo202012 } from "./draft";
+import { stamp } from "./stamps";
+
+/**
+ * True when `value` is a live Zod schema instance.
+ *
+ * The check is stricter than "has a `_zod` property" because a JSON
+ * round-trip preserves the `_zod` key as a plain object and would otherwise
+ * fool the predicate — see issue #1101, where MCP servers ship
+ * `JSON.stringify(zodSchemaInstance)` as a tool's `inputSchema` and the
+ * resulting plain object then explodes `z.toJSONSchema` because the prototype
+ * (and every Zod parsing method) is gone.
+ *
+ * Live Zod instances always carry a `.parse` function on the prototype;
+ * impostors do not.
+ */
+export function isZodSchema(value: unknown): value is ZodType {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		// Zod v4 instances expose a `_zod` internal property with a `def` object.
+		// Tagging on this marker keeps the check stable across Zod minor versions.
+		// (`_zod` is part of Zod's documented internal contract used by introspection.)
+		// We avoid checking constructor name because Zod ships multiple variants
+		// (`ZodObject`, `ZodOptional`, etc.) and a tagged-union style check would
+		// have to enumerate them all.
+		"_zod" in value &&
+		typeof (value as { _zod?: { def?: unknown } })._zod === "object" &&
+		// Reject JSON-roundtripped objects that kept the `_zod` key but lost the
+		// prototype. Real instances have `.parse` on the prototype chain.
+		typeof (value as { parse?: unknown }).parse === "function"
+	);
+}
+
+/** Symbol-stamped caches keyed by schema object identity. */
+const kZodWireSchema = Symbol("pi.schema.zod.wire");
+const kJsonWireSchema = Symbol("pi.schema.json.wire");
+
+/**
+ * Post-process Zod-emitted JSON Schema so it matches the wire shape providers
+ * already expect from TypeBox-authored tools:
+ *
+ *   - Drop the `$schema` URL (providers parse the body, not the metadata).
+ *   - Make fields with a `default` non-required (TypeBox/JSON-Schema semantics
+ *     treat defaulted fields as optional; Zod inverts this and keeps them
+ *     required at the input boundary, then materializes the default).
+ *   - Strip the noisy safe-integer bounds Zod injects for `z.number().int()`.
+ *
+ * The empty-schema normalization (`{}` → `true`, see `normalizeEmptySchemas`)
+ * runs separately from `toolWireSchema` so both Zod and TypeBox tools get it.
+ */
+function postProcess(schema: Record<string, unknown>): Record<string, unknown> {
+	delete schema.$schema;
+	walk(schema);
+	normalizeEmptySchemas(schema);
+	return schema;
+}
+
+const SAFE_INTEGER_MAX = Number.MAX_SAFE_INTEGER;
+const SAFE_INTEGER_MIN = Number.MIN_SAFE_INTEGER;
+
+/** Keys whose values are a single JSON Schema (not an array or map). */
+const SCHEMA_VALUE_KEYS = [
+	"additionalProperties",
+	"unevaluatedProperties",
+	"unevaluatedItems",
+	"items",
+	"contains",
+	"propertyNames",
+	"if",
+	"then",
+	"else",
+	"not",
+] as const;
+
+/** Keys whose values are a map of `{ key: Schema }` entries. */
+const SCHEMA_MAP_KEYS = ["properties", "patternProperties", "$defs", "definitions"] as const;
+
+/** Keys whose values are an array of schemas. */
+const SCHEMA_ARRAY_KEYS = ["anyOf", "oneOf", "allOf", "prefixItems"] as const;
+
+/** True when `val` is a plain empty object `{}`. */
+function isEmptyObject(val: unknown): val is Record<string, never> {
+	if (val === null || typeof val !== "object" || Array.isArray(val)) return false;
+	for (const _ in val as object) return false;
+	return true;
+}
+
+function walk(node: unknown): void {
+	if (Array.isArray(node)) {
+		for (const child of node) walk(child);
+		return;
+	}
+	if (!node || typeof node !== "object") return;
+	const obj = node as Record<string, unknown>;
+
+	// Drop noise injected for `z.number().int()`.
+	if (obj.type === "integer") {
+		if (obj.minimum === SAFE_INTEGER_MIN) delete obj.minimum;
+		if (obj.maximum === SAFE_INTEGER_MAX) delete obj.maximum;
+	}
+
+	// Make defaulted properties non-required.
+	if (Array.isArray(obj.required) && obj.properties && typeof obj.properties === "object") {
+		const properties = obj.properties as Record<string, unknown>;
+		const required = obj.required as string[];
+		const filtered = required.filter(name => {
+			const propertySchema = properties[name];
+			if (!propertySchema || typeof propertySchema !== "object") return true;
+			return !("default" in (propertySchema as Record<string, unknown>));
+		});
+		if (filtered.length !== required.length) {
+			if (filtered.length === 0) {
+				delete obj.required;
+			} else {
+				obj.required = filtered;
+			}
+		}
+	}
+
+	for (const k in obj) walk(obj[k]);
+}
+
+/**
+ * Normalize `{}` (empty JSON Schema = `z.unknown()` / unconstrained value) to
+ * boolean `true` in every schema-valued position. JSON Schema draft 2020-12
+ * §4.3.1: `{}` and `true` are semantically equivalent ("any JSON value").
+ * Grammar-constrained samplers (llama.cpp, etc.) treat the object form as
+ * "generate an empty object" rather than "any JSON value", causing open-typed
+ * fields like `extra.title` (from `z.record(z.string(), z.unknown())`) to
+ * always emit `{}` instead of the intended string/number/etc. (issue #1179).
+ *
+ * Mutates in place. Provider-agnostic — applied to every tool wire schema so
+ * Anthropic, Google, OpenAI, Ollama, Bedrock, and Cursor all see the
+ * normalized form, regardless of whether the source was Zod or TypeBox.
+ */
+export function normalizeEmptySchemas(node: unknown): void {
+	if (Array.isArray(node)) {
+		for (const child of node) normalizeEmptySchemas(child);
+		return;
+	}
+	if (!node || typeof node !== "object") return;
+	const obj = node as Record<string, unknown>;
+
+	for (const key of SCHEMA_VALUE_KEYS) {
+		if (Object.hasOwn(obj, key) && isEmptyObject(obj[key])) obj[key] = true;
+	}
+	for (const mapKey of SCHEMA_MAP_KEYS) {
+		const map = obj[mapKey];
+		if (map !== null && typeof map === "object" && !Array.isArray(map)) {
+			for (const k in map as Record<string, unknown>) {
+				if (isEmptyObject((map as Record<string, unknown>)[k])) (map as Record<string, unknown>)[k] = true;
+			}
+		}
+	}
+	for (const arrKey of SCHEMA_ARRAY_KEYS) {
+		const arr = obj[arrKey];
+		if (Array.isArray(arr)) {
+			for (let i = 0; i < arr.length; i++) {
+				if (isEmptyObject(arr[i])) arr[i] = true;
+			}
+		}
+	}
+
+	for (const k in obj) normalizeEmptySchemas(obj[k]);
+}
+
+/** Convert a Zod schema into the JSON Schema shape providers consume. */
+export function zodToWireSchema(schema: ZodType): Record<string, unknown> {
+	return stamp(schema, kZodWireSchema, s => {
+		// `target: "draft-2020-12"` matches what Anthropic's `input_schema` validator
+		// requires out of the box; our other provider sanitizers (OpenAI strict,
+		// Google, Anthropic CCA) already handle the superset structurally.
+		const raw = z.toJSONSchema(s, { target: "draft-2020-12" }) as Record<string, unknown>;
+		return postProcess(raw);
+	});
+}
+
+/**
+ * Resolve a tool's parameters to a JSON Schema object suitable for sending
+ * over the wire. Zod schemas are converted (and cached); legacy TypeBox / raw
+ * JSON Schema parameters are upgraded to draft 2020-12 (and cached).
+ *
+ * Both branches finish with `normalizeEmptySchemas` so every provider —
+ * OpenAI, Anthropic, Google, Ollama, Bedrock, Cursor — sees `{}` normalized
+ * to `true` in schema-valued positions (issue #1179).
+ */
+export function toolWireSchema(tool: Tool): Record<string, unknown> {
+	const params: TSchema = tool.parameters;
+	if (isZodSchema(params)) return zodToWireSchema(params);
+	return stamp(params as Record<string, unknown>, kJsonWireSchema, p => {
+		const upgraded = upgradeJsonSchemaTo202012(p) as Record<string, unknown>;
+		normalizeEmptySchemas(upgraded);
+		return upgraded;
+	});
+}

package/src/utils/schema/zod-decontaminate.ts

@@ -0,0 +1,331 @@
+/**
+ * Defensive rewrite for nodes that look like `JSON.stringify(zodSchemaInstance)`
+ * output rather than JSON Schema. MCP servers using Zod 4 sometimes ship a
+ * serialised schema instance directly as a tool's `inputSchema`, because the
+ * fields Zod surfaces on its instances (`type`, `enum`, `options`, `def`) shadow
+ * (and clash with) JSON Schema keywords. The resulting payload is neither valid
+ * Zod nor valid JSON Schema 2020-12 and Anthropic's strict validator rejects
+ * the whole tool list.
+ *
+ * Symptoms we've observed (gitnexus_impact.direction):
+ *   {
+ *     def:   { type: "enum", entries: { upstream: "upstream", ... } },
+ *     type:  "enum",                       // <- invalid `type` value
+ *     enum:  { upstream: "upstream", ... }, // <- `enum` MUST be an array
+ *     options: ["upstream", "downstream"],
+ *   }
+ *
+ * This module recognises the shape (`def.type === node.type` and `def.type` is
+ * a known Zod kind) and rewrites it to clean JSON Schema where deterministic.
+ * For Zod kinds we don't fully model, we strip the toxic siblings (`def`,
+ * `options`, object-shaped `enum`) and drop an invalid `type` so the remainder
+ * passes meta-schema validation as a permissive node.
+ *
+ * Pure / identity-preserving: returns the input reference when nothing changes.
+ */
+
+import { isJsonObject, type JsonObject } from "./types";
+
+const VALID_JSON_SCHEMA_TYPES: Record<string, true> = {
+	string: true,
+	number: true,
+	integer: true,
+	boolean: true,
+	object: true,
+	array: true,
+	null: true,
+};
+
+/**
+ * Known Zod 4 schema kinds as surfaced on `_def.type` / `.type`. Matching this
+ * set (rather than just "has `def`") is what keeps us from rewriting legitimate
+ * JSON Schemas that happen to use `def` as a property name.
+ */
+const ZOD_KINDS: Record<string, true> = {
+	string: true,
+	number: true,
+	int: true,
+	boolean: true,
+	bigint: true,
+	null: true,
+	undefined: true,
+	void: true,
+	any: true,
+	unknown: true,
+	never: true,
+	date: true,
+	symbol: true,
+	nan: true,
+	enum: true,
+	literal: true,
+	object: true,
+	array: true,
+	tuple: true,
+	record: true,
+	map: true,
+	set: true,
+	union: true,
+	discriminatedUnion: true,
+	intersection: true,
+	lazy: true,
+	promise: true,
+	function: true,
+	file: true,
+	custom: true,
+	template_literal: true,
+	optional: true,
+	nullable: true,
+	default: true,
+	prefault: true,
+	catch: true,
+	pipe: true,
+	transform: true,
+	brand: true,
+	readonly: true,
+	success: true,
+	nonoptional: true,
+};
+
+const ZOD_SCALAR_TO_JSON_TYPE: Record<string, string> = {
+	string: "string",
+	number: "number",
+	int: "integer",
+	boolean: "boolean",
+	null: "null",
+	bigint: "string",
+	date: "string",
+	nan: "number",
+};
+
+const ZOD_NOISE_KEYS: Record<string, true> = {
+	def: true,
+	options: true,
+	_zod: true,
+	checks: true,
+};
+
+/**
+ * JSON Schema keywords where `null` is a legal value (literal payload positions).
+ * Anywhere else, a `null`-valued key is a meta-schema violation — Zod scalars
+ * leak `format: null`, `minLength: null`, etc. that we have to scrub.
+ */
+const KEYS_THAT_ACCEPT_NULL: Record<string, true> = {
+	default: true,
+	const: true,
+	examples: true,
+};
+
+function isZodLeak(node: JsonObject): boolean {
+	const def = node.def;
+	if (!isJsonObject(def)) return false;
+	const defType = def.type;
+	if (typeof defType !== "string" || !ZOD_KINDS[defType]) return false;
+	// Both surface and inner `.type` must agree — Zod always mirrors `_def.type`
+	// onto the instance, so this is a near-zero false-positive guard.
+	return node.type === defType;
+}
+
+function inferTypeFromValues(values: readonly unknown[]): string {
+	if (values.length === 0) return "string";
+	const first = values[0];
+	if (typeof first === "number") return Number.isInteger(first) ? "integer" : "number";
+	if (typeof first === "boolean") return "boolean";
+	if (first === null) return "null";
+	return "string";
+}
+
+function unwrapInnerSchema(def: JsonObject): unknown {
+	// Zod uses different fields depending on the wrapper:
+	//   optional/nullable/readonly/brand/default → `innerType`
+	//   pipe → `in` (or `out`)
+	//   lazy → `getter` (a function — gone after JSON.stringify); fall back to {}
+	return def.innerType ?? def.in ?? def.out ?? def.schema ?? def.element ?? {};
+}
+
+function copyWithoutNoise(node: JsonObject): JsonObject {
+	const out: JsonObject = {};
+	for (const key in node) {
+		if (ZOD_NOISE_KEYS[key]) continue;
+		const value = node[key];
+		if (value === null && !KEYS_THAT_ACCEPT_NULL[key]) continue;
+		out[key] = value;
+	}
+	return out;
+}
+
+function rewriteZodNode(node: JsonObject, seen: WeakSet<object>): unknown {
+	const def = node.def as JsonObject;
+	const kind = def.type as string;
+
+	switch (kind) {
+		case "enum": {
+			// Prefer node.options (array form Zod exposes) → def.entries values →
+			// object-shaped node.enum values. All three carry the same data.
+			const optionsArray = Array.isArray(node.options) ? (node.options as unknown[]) : null;
+			const entries = isJsonObject(def.entries) ? Object.values(def.entries) : null;
+			const enumObj = isJsonObject(node.enum) ? Object.values(node.enum) : null;
+			const values = optionsArray ?? entries ?? enumObj ?? [];
+			return { type: inferTypeFromValues(values), enum: values };
+		}
+
+		case "literal": {
+			const values = Array.isArray(def.values) ? (def.values as unknown[]) : [];
+			if (values.length === 1) {
+				return { const: values[0] };
+			}
+			if (values.length > 1) {
+				return { type: inferTypeFromValues(values), enum: values };
+			}
+			return {};
+		}
+
+		case "union":
+		case "discriminatedUnion": {
+			const arms = Array.isArray(def.options)
+				? (def.options as unknown[])
+				: Array.isArray(node.options)
+					? (node.options as unknown[])
+					: [];
+			return { anyOf: arms.map(x => walk(x, seen)) };
+		}
+
+		case "intersection": {
+			return {
+				allOf: [walk(def.left, seen), walk(def.right, seen)],
+			};
+		}
+
+		case "array": {
+			return { type: "array", items: walk(def.element, seen) };
+		}
+
+		case "set": {
+			const element = def.valueType ?? def.element;
+			return { type: "array", uniqueItems: true, items: walk(element, seen) };
+		}
+
+		case "tuple": {
+			const items = Array.isArray(def.items) ? (def.items as unknown[]) : [];
+			const out: JsonObject = { type: "array", prefixItems: items.map(x => walk(x, seen)) };
+			const rest = def.rest;
+			if (rest != null) out.items = walk(rest, seen);
+			return out;
+		}
+
+		case "record":
+		case "map": {
+			return { type: "object", additionalProperties: walk(def.valueType, seen) };
+		}
+
+		case "object": {
+			const shape = isJsonObject(def.shape) ? def.shape : ({} as JsonObject);
+			const properties: JsonObject = {};
+			const required: string[] = [];
+			for (const key in shape) {
+				const inner = walk(shape[key], seen);
+				properties[key] = inner;
+				if (!isOptionalEntry(shape[key])) required.push(key);
+			}
+			const out: JsonObject = { type: "object", properties };
+			if (required.length > 0) out.required = required;
+			return out;
+		}
+
+		case "nonoptional":
+		case "optional":
+		case "nullable":
+		case "default":
+		case "prefault":
+		case "catch":
+		case "readonly":
+		case "brand":
+		case "lazy":
+		case "pipe":
+		case "transform": {
+			const inner = walk(unwrapInnerSchema(def), seen);
+			if (kind === "nullable" && isJsonObject(inner)) {
+				if (typeof inner.type === "string") {
+					return { ...inner, type: [inner.type, "null"] };
+				}
+				if (Array.isArray(inner.type)) {
+					return (inner.type as string[]).includes("null")
+						? inner
+						: { ...inner, type: [...(inner.type as string[]), "null"] };
+				}
+				// anyOf / allOf / $ref shapes — no scalar `type` field
+				return { anyOf: [inner, { type: "null" }] };
+			}
+			return inner;
+		}
+
+		default: {
+			// Best-effort: drop the noise, map the kind to a JSON Schema type if
+			// we know one, otherwise drop `type` so the node validates as
+			// permissive.
+			const cleaned = copyWithoutNoise(node);
+			const mapped = ZOD_SCALAR_TO_JSON_TYPE[kind];
+			if (mapped) {
+				cleaned.type = mapped;
+			} else if (typeof cleaned.type === "string" && !VALID_JSON_SCHEMA_TYPES[cleaned.type]) {
+				delete cleaned.type;
+			}
+			// Object-shaped `enum` survives as a noise field — remove if present.
+			if (cleaned.enum !== undefined && !Array.isArray(cleaned.enum)) {
+				delete cleaned.enum;
+			}
+			return cleaned;
+		}
+	}
+}
+
+function isOptionalEntry(value: unknown): boolean {
+	if (!isJsonObject(value)) return false;
+	if (!isZodLeak(value)) return false;
+	const kind = (value.def as JsonObject).type;
+	return kind === "optional" || kind === "default" || kind === "prefault";
+}
+
+/**
+ * Walks a JSON value and rewrites every Zod-instance-shaped node into clean
+ * JSON Schema 2020-12. Identity-preserving when no rewrite fires. Tolerates
+ * self-referential graphs — a revisited node returns as-is.
+ */
+export function decontaminateZodInstance(value: unknown): unknown {
+	return walk(value, new WeakSet());
+}
+
+function walk(value: unknown, seen: WeakSet<object>): unknown {
+	if (Array.isArray(value)) {
+		if (seen.has(value)) return value;
+		seen.add(value);
+		let changed = false;
+		const out = value.map(entry => {
+			const rewritten = walk(entry, seen);
+			if (rewritten !== entry) changed = true;
+			return rewritten;
+		});
+		return changed ? out : value;
+	}
+	if (!isJsonObject(value)) return value;
+	if (seen.has(value)) return value;
+	seen.add(value);
+
+	if (isZodLeak(value)) {
+		// Rewrite the node itself, then recurse into the rewrite so any nested
+		// Zod-instance children get cleaned in the same pass.
+		const rewritten = rewriteZodNode(value, seen);
+		return rewritten === value ? value : walk(rewritten, seen);
+	}
+
+	// Plain JSON Schema node: recurse into children, preserving identity when
+	// nothing under us changed.
+	let changed = false;
+	const out: JsonObject = {};
+	for (const key in value) {
+		const child = value[key];
+		const rewritten = walk(child, seen);
+		if (rewritten !== child) changed = true;
+		out[key] = rewritten;
+	}
+	return changed ? out : value;
+}