@raybase/core 0.0.2 → 0.3.4

package/dist/json-schema.js

@@ -0,0 +1,884 @@
+import { z } from "zod";
+import { stableJson } from "./internal.js";
+export function isZodSchema(schema) {
+    return typeof schema.parse === "function";
+}
+export function jsonSchemaFor(schema, options = {}) {
+    if (isZodSchema(schema))
+        return z.toJSONSchema(schema, options);
+    return schema;
+}
+export function parseWithSchema(schema, value, path) {
+    if (isZodSchema(schema))
+        return schema.parse(value);
+    return validateJsonSchema(schema, value, path);
+}
+export function validateJsonSchema(schema, value, path) {
+    if (!schema.type)
+        return value;
+    if (Array.isArray(schema.enum) && !schema.enum.some((candidate) => jsonSchemaValuesEqual(candidate, value))) {
+        throw new Error(`${path} must be one of ${schema.enum.map(String).join(", ")}`);
+    }
+    switch (schema.type) {
+        case "object": {
+            if (!value || typeof value !== "object" || Array.isArray(value))
+                throw new Error(`${path} must be an object`);
+            const object = value;
+            const properties = schema.properties ?? {};
+            for (const required of schema.required ?? []) {
+                if (object[required] === undefined)
+                    throw new Error(`${path}.${required} is required`);
+            }
+            if (schema.additionalProperties === false) {
+                for (const key of Object.keys(object)) {
+                    if (!properties[key])
+                        throw new Error(`${path}.${key} is not allowed`);
+                }
+            }
+            return Object.fromEntries(Object.entries(object).map(([key, item]) => [key, properties[key] ? validateJsonSchema(properties[key], item, `${path}.${key}`) : item]));
+        }
+        case "array": {
+            if (!Array.isArray(value))
+                throw new Error(`${path} must be an array`);
+            if (typeof schema.minItems === "number" && value.length < schema.minItems)
+                throw new Error(`${path} must contain at least ${schema.minItems} items`);
+            if (typeof schema.maxItems === "number" && value.length > schema.maxItems)
+                throw new Error(`${path} must contain at most ${schema.maxItems} items`);
+            return schema.items ? value.map((item, index) => validateJsonSchema(schema.items, item, `${path}[${index}]`)) : value;
+        }
+        case "string":
+            if (typeof value !== "string")
+                throw new Error(`${path} must be a string`);
+            if (typeof schema.minLength === "number" && value.length < schema.minLength)
+                throw new Error(`${path} must be at least ${schema.minLength} characters`);
+            if (typeof schema.maxLength === "number" && value.length > schema.maxLength)
+                throw new Error(`${path} must be at most ${schema.maxLength} characters`);
+            return value;
+        case "number":
+        case "integer":
+            if (typeof value !== "number" || !Number.isFinite(value))
+                throw new Error(`${path} must be a number`);
+            if (schema.type === "integer" && !Number.isInteger(value))
+                throw new Error(`${path} must be an integer`);
+            if (typeof schema.minimum === "number" && value < schema.minimum)
+                throw new Error(`${path} must be at least ${schema.minimum}`);
+            if (typeof schema.maximum === "number" && value > schema.maximum)
+                throw new Error(`${path} must be at most ${schema.maximum}`);
+            return value;
+        case "boolean":
+            if (typeof value !== "boolean")
+                throw new Error(`${path} must be a boolean`);
+            return value;
+        case "null":
+            if (value !== null)
+                throw new Error(`${path} must be null`);
+            return value;
+        default:
+            return value;
+    }
+}
+/**
+ * Keywords a strict tool-parameter schema may not carry.
+ *
+ * They are validation, not shape, and the provider rejects them outright — the
+ * whole request, not the one tool. Dropping them from what is published loosens
+ * nothing: the action still validates its input with its own schema when the
+ * call arrives, so a discarded `maxLength` is enforced a moment later by the
+ * thing that always enforced it.
+ */
+const NON_STRUCTURAL_JSON_SCHEMA_KEYWORDS = new Set([
+    "minLength", "maxLength", "pattern", "format",
+    "minimum", "maximum", "exclusiveMinimum", "exclusiveMaximum", "multipleOf",
+    "minItems", "maxItems", "uniqueItems",
+    "minProperties", "maxProperties",
+    "default", "examples", "contentEncoding", "contentMediaType",
+    "$schema", "$id", "$comment"
+]);
+/**
+ * The strict-subset form of a schema, for publishing to a model.
+ *
+ * Providers in the OpenAI family validate every tool's `parameters` against a
+ * narrow subset and fail the entire request when one tool falls outside it —
+ * so an app whose schemas are ordinary, valid JSON Schema gets no reply at all,
+ * and nothing says which tool was at fault. This makes the published form
+ * conform without touching what the action validates with.
+ *
+ * Objects are closed. Property *requiredness* is left exactly as it was: an
+ * optional property could only be made strict by declaring a null union, and a
+ * schema derived from `.optional()` without `.nullable()` would then invite a
+ * `null` its own validator rejects. Where that matters, an action declares its
+ * tool schema itself.
+ *
+ * A reused or recursive subschema arrives as a root-relative `$ref` into
+ * `$defs`, and the reference is what gets published — that is the point of it.
+ * But every judgment about a child's *shape* — whether it permits null, whether
+ * it constrains anything — resolves the reference first, because a nullable
+ * shape lifted into `$defs` is otherwise read as one that refuses null and the
+ * property stays optional in a schema that must have none. `root` is the
+ * document those references point into; it defaults to the schema itself, which
+ * is right for every call that starts at a root.
+ */
+export function strictJsonSchema(schema, root = schema) {
+    if (!schema || typeof schema !== "object" || Array.isArray(schema))
+        return schema;
+    // `oneOf` and `anyOf` at one path are two different claims about the same
+    // value, and the subset has only `anyOf`. Merging them would publish a union
+    // neither of them asked for, so this refuses instead of guessing: the schema
+    // is a mistake a person has to resolve, not a shape to invent.
+    if (Array.isArray(schema.oneOf) && Array.isArray(schema.anyOf)) {
+        throw new Error("A strict tool schema cannot combine oneOf and anyOf at the same path.");
+    }
+    const next = {};
+    for (const [key, value] of Object.entries(schema)) {
+        // Reused and recursive subschemas live in `$defs` and are reached by
+        // `$ref`. They are published verbatim, so a validation keyword left inside
+        // one refuses the request exactly like a keyword at the top level.
+        if ((key === "$defs" || key === "definitions") && value && typeof value === "object" && !Array.isArray(value)) {
+            next[key] = Object.fromEntries(Object.entries(value).map(([name, child]) => [name, strictJsonSchema(child, root)]));
+            continue;
+        }
+        if (NON_STRUCTURAL_JSON_SCHEMA_KEYWORDS.has(key))
+            continue;
+        if (key === "properties" && value && typeof value === "object") {
+            // A property whose schema constrains nothing — `{}`, from `z.unknown()`
+            // or a hand-written open field — has no strict form at all, and one of
+            // them refuses the entire request. It cannot be given a shape, so it is
+            // offered as a string holding JSON, which the subset does have a rule
+            // for. `restoreStrictActionInput` parses it back before the action's own
+            // schema sees it. Leaving the property out instead would publish a tool
+            // that quietly cannot carry the field at all.
+            next.properties = Object.fromEntries(Object.entries(value)
+                .map(([name, child]) => {
+                const normalized = strictJsonSchema(child, root);
+                return [name, isUnconstrainedJsonSchema(normalized, root) ? jsonEncodedSchema(normalized, "value") : normalized];
+            }));
+            continue;
+        }
+        if ((key === "items" || key === "not") && value && typeof value === "object") {
+            next[key] = strictJsonSchema(value, root);
+            continue;
+        }
+        // The subset has `anyOf` and no `oneOf`. Publishing the union as `anyOf`
+        // drops only the exclusivity claim, which the action's own schema still
+        // enforces when the call arrives — a value matching two branches is refused
+        // there, with a message, rather than here by a provider naming no tool.
+        if ((key === "anyOf" || key === "oneOf") && Array.isArray(value)) {
+            next.anyOf = value.map((entry) => strictJsonSchema(entry, root));
+            continue;
+        }
+        if (key === "allOf" && Array.isArray(value)) {
+            next[key] = value.map((entry) => strictJsonSchema(entry, root));
+            continue;
+        }
+        // `const` is how a literal — a discriminator, a schema version — arrives
+        // from every Zod-shaped schema, and the strict subset has no such keyword.
+        // A one-value `enum` is supported and says exactly the same thing, so this
+        // is a rename rather than a loosening.
+        if (key === "const") {
+            if (next.enum === undefined && typeof value === "string")
+                next.enum = [value];
+            continue;
+        }
+        // `enum` in the strict subset is a set of strings. A boolean or numeric
+        // literal — `z.literal(true)`, a schema version — publishes as its plain
+        // type; the action's own schema still refuses any other value.
+        if (key === "enum" && Array.isArray(value)) {
+            if (value.every((entry) => typeof entry === "string"))
+                next.enum = value;
+            continue;
+        }
+        next[key] = value;
+    }
+    // A union branch often carries `properties` with no `type`, and an unclosed
+    // object anywhere in the tree fails the whole request just the same.
+    const isObject = next.type === "object" || (next.type === undefined && next.properties !== undefined);
+    if (isObject && next.additionalProperties === undefined)
+        next.additionalProperties = false;
+    // A property whose own schema already permits null can be published as
+    // required without changing what anything accepts: the model may send null,
+    // and a validator that made the property optional-and-nullable takes null.
+    // This is the safe half of "derive `required` automatically" — a property
+    // that is merely optional keeps its optionality, because inviting a null its
+    // validator would reject is the one way this could bite.
+    if (isObject && next.properties) {
+        const required = new Set(next.required ?? []);
+        for (const [name, child] of Object.entries(next.properties)) {
+            if (!required.has(name) && permitsNull(child, root))
+                required.add(name);
+        }
+        if (required.size)
+            next.required = [...Object.keys(next.properties)].filter((name) => required.has(name));
+    }
+    return next;
+}
+/**
+ * The strict form of a *tool's* `parameters`, which has one rule beyond the
+ * rest: the root must be a single object. A discriminated union — the natural
+ * way to write an action that takes several shapes — publishes `anyOf` at the
+ * root, which is ordinary valid JSON Schema and refused outright, taking every
+ * other tool in the request down with it.
+ *
+ * So a union root is merged into one object: every branch's properties, each
+ * nullable because it belongs to only some branches, and the discriminator's
+ * enums unioned so the model still sees which values pair with which shape.
+ * This widens only what is *published*. The action still validates with its own
+ * union, so a call mixing two branches is refused by `parseWithSchema` with a
+ * real message rather than by the provider with none.
+ */
+export function strictToolParameters(schema) {
+    // Normalise first so the branches are already in subset form when they merge:
+    // a discriminator arrives as `const`, and only once that is an `enum` can the
+    // branches collapse into one field offering the set of operations. Merging
+    // raw would leave eleven single-value unions where one enum belongs.
+    const normalized = strictJsonSchema(schema);
+    return inlineDefinitions(strictJsonSchema(flattenRootUnion(normalized, normalized)));
+}
+/**
+ * Shapes lifted into `$defs`, put back where a reader needs them.
+ *
+ * `reused: "ref"` dedupes repeated subschemas to keep a large tool list small,
+ * and for an object shape used many times the reference pays its way. Two
+ * kinds of definition cost more than they save, and each took a feature down
+ * in production:
+ *
+ * - A leaf — a primitive, an enum, a union of those. On 2026-08-28 a
+ *   `.nullish()` number published as `{"$ref": "#/$defs/__schema1"}`, the live
+ *   model never chased the pointer, guessed the field was a string, and the
+ *   action refused the call every time.
+ * - A definition used exactly once. It dedupes nothing, so the reference is
+ *   pure cost — and Zod lifts *every* property of an object carrying a root
+ *   `.superRefine()` into `$defs` whether or not anything else uses it. On
+ *   2026-09-01 a union of two closed objects (a homework failure price) was
+ *   published that way; across twenty calls the model sent the object as a
+ *   string of JSON, and the work was never set.
+ *
+ * A model reads a published schema as text; a field's *type* has to be visible
+ * at the field. So a leaf, or a definition with a single use, is inlined at
+ * that use — under the use's own annotations, which win — and whatever no
+ * longer has a reference reaching it from the root is dropped from `$defs`.
+ * Object and array shapes with several uses keep their references, which is
+ * the dedupe's real value, and a definition that reaches itself while being
+ * inlined keeps the reference at that point, so recursion terminates.
+ */
+function inlineDefinitions(schema) {
+    const defsKey = ["$defs", "definitions"].find((key) => jsonSchemaObject(schema[key]));
+    if (!defsKey)
+        return schema;
+    const definitions = schema[defsKey];
+    // Everything below is keyed by definition *name*, decoded from each `$ref`
+    // as a JSON Pointer: a definition called `order/line` is referenced as
+    // `#/$defs/order~1line`, and a key built by pasting the name into a pointer
+    // would never meet its own references.
+    const definitionName = (ref) => {
+        const target = typeof ref === "string" ? jsonSchemaDefinitionRef(ref) : null;
+        return target && target.key === defsKey ? target.name : null;
+    };
+    // Every reference to a definition under a node, once per occurrence.
+    const eachReference = (node, visit) => {
+        if (Array.isArray(node)) {
+            node.forEach((item) => eachReference(item, visit));
+            return;
+        }
+        const object = jsonSchemaObject(node);
+        if (!object)
+            return;
+        const name = definitionName(object.$ref);
+        if (name !== null)
+            visit(name);
+        Object.values(object).forEach((value) => eachReference(value, visit));
+    };
+    const bodies = new Map();
+    for (const [name, definition] of Object.entries(definitions)) {
+        const body = jsonSchemaObject(definition);
+        if (body)
+            bodies.set(name, body);
+    }
+    const uses = new Map();
+    eachReference(schema, (name) => uses.set(name, (uses.get(name) ?? 0) + 1));
+    const inlinable = new Set();
+    for (const [name, body] of bodies) {
+        if (isLeafJsonSchema(body) || (uses.get(name) ?? 0) <= 1)
+            inlinable.add(name);
+    }
+    if (!inlinable.size)
+        return schema;
+    const substitute = (node, stack) => {
+        if (Array.isArray(node))
+            return node.map((item) => substitute(item, stack));
+        const object = jsonSchemaObject(node);
+        if (!object)
+            return node;
+        const name = definitionName(object.$ref);
+        if (name !== null && inlinable.has(name) && !stack.has(name)) {
+            const { $ref: _ref, ...annotations } = object;
+            const deeper = new Set(stack).add(name);
+            return {
+                ...substitute(bodies.get(name), deeper),
+                ...substitute(annotations, deeper),
+            };
+        }
+        return Object.fromEntries(Object.entries(object).map(([key, value]) => [key, substitute(value, stack)]));
+    };
+    const { [defsKey]: _definitions, ...rest } = schema;
+    const inlined = substitute(rest, new Set());
+    const rewritten = new Map();
+    for (const [name, body] of bodies)
+        rewritten.set(name, substitute(body, new Set([name])));
+    // Only what the root still reaches survives: a definition inlined at its one
+    // use, or one nothing ever pointed at, has no reader left.
+    const reachable = new Set();
+    const frontier = new Set();
+    eachReference(inlined, (name) => frontier.add(name));
+    while (frontier.size) {
+        const name = frontier.values().next().value;
+        frontier.delete(name);
+        if (reachable.has(name) || !rewritten.has(name))
+            continue;
+        reachable.add(name);
+        eachReference(rewritten.get(name), (onward) => {
+            if (!reachable.has(onward))
+                frontier.add(onward);
+        });
+    }
+    const surviving = Object.fromEntries(Object.entries(definitions)
+        .filter(([name]) => reachable.has(name))
+        .map(([name]) => [name, rewritten.get(name) ?? definitions[name]]));
+    return Object.keys(surviving).length ? { ...inlined, [defsKey]: surviving } : inlined;
+}
+/**
+ * A shape that is finished where it stands: a primitive, an enum, or a union
+ * of those. No properties or items to walk into, no reference to chase — which
+ * is also what makes inlining one always terminate.
+ */
+function isLeafJsonSchema(schema) {
+    if (!schema)
+        return false;
+    if (schema.$ref !== undefined || schema.properties !== undefined || schema.items !== undefined
+        || schema.additionalProperties !== undefined || schema.$defs !== undefined || schema.definitions !== undefined
+        || schema.type === "object" || schema.type === "array")
+        return false;
+    for (const key of ["anyOf", "oneOf", "allOf"]) {
+        const branches = schema[key];
+        if (Array.isArray(branches) && !branches.every((branch) => isLeafJsonSchema(jsonSchemaObject(branch))))
+            return false;
+    }
+    if (schema.not !== undefined && !isLeafJsonSchema(jsonSchemaObject(schema.not)))
+        return false;
+    return true;
+}
+function flattenRootUnion(schema, root = schema) {
+    if (!schema || typeof schema !== "object" || Array.isArray(schema))
+        return schema;
+    const key = ["anyOf", "oneOf"].find((candidate) => Array.isArray(schema[candidate]));
+    if (!key)
+        return schema;
+    // A branch shape used elsewhere too is lifted into `$defs` and stands here as
+    // a bare `$ref`, which carries no `properties` of its own. Merging needs the
+    // branch's real shape, so the reference is followed before the check below —
+    // the alternative is bailing out and publishing `anyOf` at the root, which is
+    // the shape a strict provider refuses.
+    const branches = schema[key]
+        .map((branch) => resolveJsonSchemaRef(jsonSchemaObject(branch), root) ?? branch)
+        .map((branch) => flattenRootUnion(branch, root));
+    if (!branches.length || !branches.every((branch) => branch && typeof branch === "object" && branch.properties && typeof branch.properties === "object")) {
+        return schema;
+    }
+    const names = [];
+    const variants = new Map();
+    for (const branch of branches) {
+        for (const [name, child] of Object.entries(branch.properties)) {
+            if (!variants.has(name)) {
+                variants.set(name, []);
+                names.push(name);
+            }
+            variants.get(name).push(child);
+        }
+    }
+    const properties = {};
+    for (const name of names) {
+        const shapes = variants.get(name);
+        const distinct = [];
+        for (const shape of shapes.flatMap(unionBranches)) {
+            if (!distinct.some((seen) => jsonSchemaValuesEqual(seen, shape)))
+                distinct.push(shape);
+        }
+        // The discriminator: one string enum per branch, which merges into the set
+        // of values the model may choose between rather than an opaque union.
+        const merged = distinct.length === 1
+            ? distinct[0]
+            : distinct.every((shape) => shape.type === "string" && Array.isArray(shape.enum))
+                ? { ...distinct[0], type: "string", enum: [...new Set(distinct.flatMap((shape) => shape.enum))] }
+                : { anyOf: distinct };
+        // A property carried by only some branches, or optional within its own, is
+        // absent on the calls that take another shape.
+        const universal = shapes.length === branches.length
+            && branches.every((branch) => Array.isArray(branch.required) && branch.required.includes(name));
+        properties[name] = universal || permitsNull(merged, root) ? merged : nullableJsonSchema(merged, root);
+    }
+    const { anyOf: _anyOf, oneOf: _oneOf, ...rest } = schema;
+    return { ...rest, type: "object", properties, required: names, additionalProperties: false };
+}
+/** The same schema, also accepting `null`, without nesting a union in a union. */
+function nullableJsonSchema(schema, root) {
+    if (Array.isArray(schema.anyOf)) {
+        const branches = schema.anyOf;
+        return branches.some((branch) => permitsNull(branch, root))
+            ? schema
+            : { ...schema, anyOf: [...branches, { type: "null" }] };
+    }
+    // A `$ref` is wrapped rather than followed: the reference is what gets
+    // published, and a union around it says the same thing about the value.
+    return { anyOf: [schema, { type: "null" }] };
+}
+/** One flat list of branches, so merging a union with a union does not nest one. */
+function unionBranches(schema) {
+    return Array.isArray(schema.anyOf) && Object.keys(schema).length === 1
+        ? schema.anyOf.flatMap(unionBranches)
+        : [schema];
+}
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+// Keywords that only constrain one JSON type, so a schema carrying one with no
+// `type` of its own is read as that type — the way a reader of the published
+// schema reads `{"pattern": …}` as a string field.
+const JSON_TYPE_IMPLYING_KEYWORDS = {
+    minLength: "string", maxLength: "string", pattern: "string", format: "string",
+    contentEncoding: "string", contentMediaType: "string",
+    minimum: "number", maximum: "number", exclusiveMinimum: "number", exclusiveMaximum: "number", multipleOf: "number",
+    properties: "object", additionalProperties: "object", patternProperties: "object", propertyNames: "object",
+    required: "object", minProperties: "object", maxProperties: "object", dependentRequired: "object",
+    dependentSchemas: "object", unevaluatedProperties: "object",
+    items: "array", prefixItems: "array", contains: "array", minItems: "array", maxItems: "array",
+    uniqueItems: "array", minContains: "array", maxContains: "array", unevaluatedItems: "array"
+};
+/**
+ * Whether a value of the given JSON type could satisfy the schema. Reads the
+ * declared `type` — or, without one, the type its type-specific keywords
+ * imply — the literal keywords (`enum`, `const`), and every union and `allOf`
+ * branch; a schema that names no type at all admits every type. Used to tell
+ * an encoding from an answer when a model hands back a string, so where it
+ * cannot tell (a `not`, an unresolved `$ref`) it answers that the type is
+ * admitted, and the string is left as it arrived.
+ *
+ * `path` holds the schemas being judged above this one, so a recursive
+ * reference ends instead of looping. It is a path, not a visited set: two
+ * `allOf` branches reaching the same definition are two judgments of it, and a
+ * branch that leads back to a schema already being judged says nothing new
+ * about it, so it is left out rather than counted either way.
+ */
+function admitsJsonType(schema, type, root, path = new Set()) {
+    const resolved = resolveJsonSchemaRef(jsonSchemaObject(schema), root);
+    if (!resolved)
+        return true;
+    if (isUnconstrainedJsonSchema(resolved, root))
+        return true;
+    const literalType = (literal) => literal === null ? "null" : Array.isArray(literal) ? "array" : typeof literal === "object" ? "object"
+        : typeof literal === "number" ? "number" : typeof literal === "boolean" ? "boolean" : "string";
+    if (Array.isArray(resolved.enum))
+        return resolved.enum.some((literal) => literalType(literal) === type);
+    if (Object.prototype.hasOwnProperty.call(resolved, "const"))
+        return literalType(resolved.const) === type;
+    const declared = Array.isArray(resolved.type) ? resolved.type : resolved.type !== undefined ? [resolved.type] : [];
+    const named = declared.length
+        ? declared
+        : [...new Set(Object.keys(resolved).flatMap((key) => JSON_TYPE_IMPLYING_KEYWORDS[key] ?? []))];
+    if (named.length && !named.includes(type)
+        && !(type === "integer" && named.includes("number"))
+        && !(type === "number" && named.includes("integer"))) {
+        return false;
+    }
+    const inner = new Set(path).add(resolved);
+    const branches = (key) => (Array.isArray(resolved[key]) ? resolved[key] : []).filter((branch) => {
+        const target = resolveJsonSchemaRef(jsonSchemaObject(branch), root);
+        return !target || !inner.has(target);
+    });
+    const admits = (branch) => admitsJsonType(branch, type, root, inner);
+    for (const key of ["anyOf", "oneOf"]) {
+        const union = branches(key);
+        if (union.length && !union.some(admits))
+            return false;
+    }
+    return branches("allOf").every(admits);
+}
+/**
+ * Whether the schema spells this exact string out as one of its values — an
+ * `enum` member or a `const`, here or in any union or `allOf` branch. A
+ * literal the app named is an answer even when it looks like padding.
+ */
+function namesStringLiteral(schema, literal, root, path = new Set()) {
+    const resolved = resolveJsonSchemaRef(jsonSchemaObject(schema), root);
+    if (!resolved || path.has(resolved))
+        return false;
+    if (Array.isArray(resolved.enum) && resolved.enum.includes(literal))
+        return true;
+    if (resolved.const === literal)
+        return true;
+    const inner = new Set(path).add(resolved);
+    return ["anyOf", "oneOf", "allOf"].some((key) => Array.isArray(resolved[key])
+        && resolved[key].some((branch) => namesStringLiteral(branch, literal, root, inner)));
+}
+/**
+ * Whether a schema accepts `null` outright, by type or through a union branch.
+ *
+ * With a `root` in hand a reference into that root's `$defs` is followed first,
+ * because the whole reason a shape is in `$defs` is that it is used twice, and
+ * a nullable shape read as non-nullable is what leaves a property optional in a
+ * schema that must have none. `seen` terminates a recursive schema, which is
+ * exactly the other thing `$defs` exists for.
+ */
+function permitsNull(schema, root, seen = new Set()) {
+    const resolved = resolveJsonSchemaRef(jsonSchemaObject(schema), root);
+    if (!resolved || seen.has(resolved))
+        return false;
+    seen.add(resolved);
+    if (resolved.type === "null")
+        return true;
+    if (Array.isArray(resolved.type) && resolved.type.includes("null"))
+        return true;
+    for (const key of ["anyOf", "oneOf"]) {
+        const branches = resolved[key];
+        if (Array.isArray(branches) && branches.some((branch) => permitsNull(branch, root, seen)))
+            return true;
+    }
+    return false;
+}
+function jsonSchemaObject(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+/**
+ * A `$ref` into the schema's own `$defs`, followed so a judgment about a shape
+ * sees the shape rather than the reference. Only root-relative pointers into
+ * `$defs`/`definitions` resolve; any other form — a remote `$ref`, a pointer at
+ * the document root — is left as it arrived. Nothing here rewrites what is
+ * published: resolution informs the judgments, and the reference survives them.
+ */
+function resolveJsonSchemaRef(schema, root, seen = new Set()) {
+    if (!schema || typeof schema.$ref !== "string" || !root || seen.has(schema))
+        return schema;
+    seen.add(schema);
+    const reference = jsonSchemaDefinitionRef(schema.$ref);
+    const defs = reference ? jsonSchemaObject(root[reference.key]) : null;
+    const target = defs && reference ? jsonSchemaObject(defs[reference.name]) : null;
+    // A chain of references ends at a shape or at a cycle, and `seen` is what
+    // makes the second one end.
+    return target ? resolveJsonSchemaRef(target, root, seen) : schema;
+}
+/**
+ * The definition a root-relative `$ref` names, decoded as RFC 6901 reads a
+ * pointer in a URI fragment: percent-decoding first, then `~1` → `/` and
+ * `~0` → `~` within each segment. A pointer reaching inside a definition
+ * (`#/$defs/a/properties/b`), or anywhere but `$defs`/`definitions`, names no
+ * definition.
+ */
+function jsonSchemaDefinitionRef(ref) {
+    if (!ref.startsWith("#/"))
+        return null;
+    let pointer;
+    try {
+        pointer = decodeURIComponent(ref.slice(1));
+    }
+    catch {
+        return null;
+    }
+    const segments = pointer.slice(1).split("/").map((segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~"));
+    const [key, name] = segments;
+    if (segments.length !== 2 || (key !== "$defs" && key !== "definitions") || !name)
+        return null;
+    return { key, name };
+}
+function jsonSchemaValuesEqual(left, right) {
+    if (Object.is(left, right))
+        return true;
+    try {
+        return stableJson(left) === stableJson(right);
+    }
+    catch {
+        return false;
+    }
+}
+/* ------------------------------------------------------------------------- *
+ * The wire form, and its inverse.
+ *
+ * `strictJsonSchema` above is the *advertised* form: it removes what the strict
+ * subset has no rule for and leaves everything a reader would rely on — an
+ * optional property is still optional, an open record is still a record. That
+ * form is what an action publishes to documentation, to a manifest, and to any
+ * caller asking what it accepts.
+ *
+ * Two more rewrites are needed before a strict provider will take it, and both
+ * change the shape of the *value* the model then sends back:
+ *
+ *   - optionality has to be spelled as a null union with every property
+ *     required, because the subset has no notion of an omitted key;
+ *   - a record with open keys, or a value with no shape at all, has no strict
+ *     form, so it travels as a string holding JSON.
+ *
+ * Neither is safe on its own: padded nulls and encoded strings reach a handler
+ * whose own validator refuses both. So they live here, paired with the inverse
+ * that undoes them before anything parses the arguments, and the pair is
+ * applied together at the one seam where both halves are in reach — Core's own
+ * chat request serialization (`strictChatTools` / `restoreStrictToolCalls` in
+ * ai.ts). A custom inference provider that hands tools to a strict API itself
+ * reuses these instead of rebuilding them.
+ * ------------------------------------------------------------------------- */
+/** Keywords that describe a schema to a reader without constraining any value. */
+const JSON_SCHEMA_ANNOTATION_KEYWORDS = new Set(["title", "description", "$comment", "deprecated", "readOnly", "writeOnly"]);
+/**
+ * A schema that constrains nothing — `{}`, from `z.unknown()` or `z.any()`, or
+ * one carrying only annotations and validation keywords the subset drops. It
+ * reads as harmless and refuses every request, so it travels as JSON in a
+ * string and comes back parsed.
+ *
+ * An unconstrained shape reached through a `$ref` is the same shape, so the
+ * reference is followed before the keys are read; without a `root` a `$ref` is
+ * its own key and constrains nothing that can be seen from here.
+ */
+function isUnconstrainedJsonSchema(schema, root) {
+    const resolved = resolveJsonSchemaRef(schema, root) ?? schema;
+    return Object.keys(resolved).every((key) => JSON_SCHEMA_ANNOTATION_KEYWORDS.has(key) || NON_STRUCTURAL_JSON_SCHEMA_KEYWORDS.has(key));
+}
+/** An object whose keys are open — `z.record(...)`, or a hand-written map. */
+function isOpenRecordJsonSchema(schema) {
+    return schema.type === "object"
+        && (schema.propertyNames !== undefined || jsonSchemaObject(schema.additionalProperties) !== null);
+}
+function jsonEncodedSchema(schema, subject) {
+    const instruction = subject === "object"
+        ? "Encode this object as a JSON string."
+        : "Encode this value as JSON in a string.";
+    const description = typeof schema.description === "string" && schema.description
+        ? `${schema.description} ${instruction}`
+        : subject === "object" ? "A JSON object encoded as a string." : "A JSON value encoded as a string.";
+    return { type: "string", description };
+}
+/**
+ * The same schema, also accepting `null`, written the way each shape allows —
+ * widening a `type`, extending an existing union, or wrapping in a new one.
+ * A one-value `enum` gains `null` alongside so the enum keeps describing the
+ * whole set of permitted values rather than contradicting the type.
+ */
+function nullPaddedJsonSchema(schema) {
+    const enumClosed = Array.isArray(schema.enum) && !schema.enum.includes(null);
+    // An `enum` that lists no `null` refuses one whatever the type says, so a
+    // schema that already permits null is only finished if its enum agrees.
+    if (permitsNull(schema) && !enumClosed)
+        return schema;
+    const enumValues = enumClosed ? [...schema.enum, null] : schema.enum;
+    if (Object.prototype.hasOwnProperty.call(schema, "const")) {
+        return { anyOf: [schema, { type: "null" }] };
+    }
+    if (typeof schema.type === "string") {
+        return { ...schema, type: [schema.type, "null"], ...(enumValues ? { enum: enumValues } : {}) };
+    }
+    if (Array.isArray(schema.type)) {
+        const types = schema.type;
+        return {
+            ...schema,
+            type: (types.includes("null") ? types : [...types, "null"]),
+            ...(enumValues ? { enum: enumValues } : {})
+        };
+    }
+    if (Array.isArray(schema.anyOf)) {
+        const branches = schema.anyOf;
+        return {
+            ...schema,
+            anyOf: branches.some((branch) => permitsNull(branch)) ? branches : [...branches, { type: "null" }],
+            ...(enumValues ? { enum: enumValues } : {})
+        };
+    }
+    return { anyOf: [schema, { type: "null" }] };
+}
+/**
+ * The wire form of a tool's parameters or a structured response schema: the
+ * advertised strict subset, plus the two rewrites that need
+ * `restoreStrictModelValue` on the way back.
+ *
+ * Applying it twice changes nothing — a padded property already permits null,
+ * and an encoded record is a string rather than a record — so a schema that has
+ * already been through `strictToolParameters` may pass through here safely.
+ */
+export function strictModelSchema(schema) {
+    return padStrictJsonSchema(strictToolParameters(schema));
+}
+function padStrictJsonSchema(value, optional = false) {
+    const schema = jsonSchemaObject(value);
+    if (!schema)
+        return value;
+    if (isUnconstrainedJsonSchema(schema)) {
+        const encoded = jsonEncodedSchema(schema, "value");
+        return optional ? nullPaddedJsonSchema(encoded) : encoded;
+    }
+    if (isOpenRecordJsonSchema(schema)) {
+        const encoded = jsonEncodedSchema(schema, "object");
+        return optional ? nullPaddedJsonSchema(encoded) : encoded;
+    }
+    let next = { ...schema };
+    const properties = jsonSchemaObject(schema.properties);
+    if (properties) {
+        const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+        const padded = Object.fromEntries(Object.entries(properties).map(([name, child]) => [name, padStrictJsonSchema(child, !required.has(name))]));
+        next = { ...next, properties: padded, required: Object.keys(padded), additionalProperties: false };
+    }
+    if (schema.items !== undefined)
+        next.items = padStrictJsonSchema(schema.items);
+    for (const key of ["anyOf", "allOf"]) {
+        if (Array.isArray(schema[key])) {
+            next[key] = schema[key].map((branch) => padStrictJsonSchema(branch));
+        }
+    }
+    for (const key of ["$defs", "definitions"]) {
+        const defs = jsonSchemaObject(schema[key]);
+        if (defs) {
+            next[key] = Object.fromEntries(Object.entries(defs).map(([name, child]) => [name, padStrictJsonSchema(child)]));
+        }
+    }
+    return optional ? nullPaddedJsonSchema(next) : next;
+}
+/**
+ * The inverse of `strictModelSchema`, run against the schema as it was *before*
+ * the wire form: null padding is stripped where the original left the property
+ * optional, JSON-encoded records are parsed back into objects, and a union is
+ * followed into the branch the value actually took so the same is done inside
+ * it.
+ *
+ * A value that was never padded passes through unchanged, so running this over
+ * arguments from a provider that needed none is safe.
+ */
+export function restoreStrictModelValue(value, schema) {
+    return restoreStrictValue(value, schema, schema);
+}
+function restoreStrictValue(value, schemaValue, root) {
+    const schema = resolveJsonSchemaRef(jsonSchemaObject(schemaValue), root);
+    if (!schema)
+        return value;
+    if (typeof value === "string" && isUnconstrainedJsonSchema(schema)) {
+        try {
+            return JSON.parse(value);
+        }
+        catch {
+            return value;
+        }
+    }
+    if (typeof value === "string" && isOpenRecordJsonSchema(schema)) {
+        try {
+            return jsonSchemaObject(JSON.parse(value)) ?? value;
+        }
+        catch {
+            return value;
+        }
+    }
+    // The strict subset makes every nullable property required, so a model must
+    // send *something* for a field it has nothing for — and a weak one sends the
+    // four letters "null". On a field that admits null, that is the padding gone
+    // wrong, not a value: seen live 2026-09-01 on a nullable text field meant
+    // for her verbatim words, where it would have filed "null" as her sentence,
+    // and on a nullable permission id, where it would have read as one cited.
+    // An app that lists the string "null" itself — an enum member, a const —
+    // meant it, so only a field that does not name it is read this way.
+    if (value === "null" && permitsNull(schema, root) && !namesStringLiteral(schema, "null", root))
+        return null;
+    if (typeof value === "string" && !admitsJsonType(schema, "string", root)) {
+        // A closed object or an array handed over as a string of JSON. The schema
+        // offers no string at this field, so the string is an encoding, not an
+        // answer; it is read and restored as the value it encodes. Twenty live
+        // calls on 2026-09-01 sent a failure price this way and every one was
+        // refused at the door, with the model unable to tell what was wrong.
+        const parsed = parseJson(value);
+        if ((jsonSchemaObject(parsed) && admitsJsonType(schema, "object", root))
+            || (Array.isArray(parsed) && admitsJsonType(schema, "array", root))) {
+            return restoreStrictValue(parsed, schema, root);
+        }
+    }
+    const branch = matchingUnionBranch(schema, value, root);
+    if (branch)
+        return restoreStrictValue(value, branch, root);
+    if (Array.isArray(value))
+        return value.map((item) => restoreStrictValue(item, schema.items, root));
+    const object = jsonSchemaObject(value);
+    const properties = jsonSchemaObject(schema.properties);
+    if (!object || !properties)
+        return value;
+    const required = new Set(Array.isArray(schema.required) ? schema.required.filter((name) => typeof name === "string") : []);
+    return Object.fromEntries(Object.entries(object).flatMap(([key, item]) => {
+        // The padding, undone: a key the original schema did not require was only
+        // sent because the strict subset has no way to leave it out.
+        if (item === null && !required.has(key))
+            return [];
+        return [[key, restoreStrictValue(item, properties[key], root)]];
+    }));
+}
+/**
+ * The branch of a union a value actually took.
+ *
+ * A discriminated union is matched by its discriminator first — the literal
+ * property that names the shape — because two branches of one union routinely
+ * share a type, and picking the wrong one would strip the wrong keys. Anything
+ * else falls back to the first branch whose type the value could satisfy.
+ */
+function matchingUnionBranch(schema, value, root) {
+    const union = Array.isArray(schema.oneOf) ? schema.oneOf : Array.isArray(schema.anyOf) ? schema.anyOf : [];
+    const candidates = union
+        .map((candidate) => resolveJsonSchemaRef(jsonSchemaObject(candidate), root))
+        .filter((candidate) => Boolean(candidate));
+    if (!candidates.length)
+        return null;
+    const object = jsonSchemaObject(value);
+    if (object) {
+        const discriminated = candidates.find((candidate) => {
+            const properties = jsonSchemaObject(candidate.properties);
+            if (!properties)
+                return false;
+            return Object.entries(properties).some(([key, propertyValue]) => {
+                const property = jsonSchemaObject(propertyValue);
+                if (!property || object[key] === undefined)
+                    return false;
+                if (Object.prototype.hasOwnProperty.call(property, "const"))
+                    return Object.is(property.const, object[key]);
+                return Array.isArray(property.enum) && property.enum.length === 1 && Object.is(property.enum[0], object[key]);
+            });
+        });
+        if (discriminated)
+            return discriminated;
+    }
+    // Before settling for any object branch, prefer one whose declared
+    // properties cover every key the value actually carries. A strict transform
+    // that merges a discriminated union hoists the discriminator away from its
+    // siblings, so a nested union of bodies reaches here with no discriminator
+    // at all — and "first object branch" then restores the value against a
+    // stranger's `required`, deleting every explicit null the right branch
+    // required. Found live 2026-08-26: a maintenance card's `standingSlot: null`
+    // was stripped against a sibling body's schema, making null unsendable and
+    // teaching the model that only an invented value could pass.
+    if (object) {
+        const covering = candidates.find((candidate) => {
+            if (candidate.type !== "object" || isOpenRecordJsonSchema(candidate))
+                return false;
+            const properties = jsonSchemaObject(candidate.properties);
+            if (!properties)
+                return false;
+            return Object.keys(object).every((key) => properties[key] !== undefined);
+        });
+        if (covering)
+            return covering;
+    }
+    return candidates.find((candidate) => {
+        if (candidate.type === "null")
+            return value === null;
+        if (isOpenRecordJsonSchema(candidate))
+            return typeof value === "string" || Boolean(object);
+        if (candidate.type === "object")
+            return Boolean(object);
+        if (candidate.type === "array")
+            return Array.isArray(value);
+        if (candidate.type === "integer")
+            return typeof value === "number";
+        return typeof candidate.type === "string" && typeof value === candidate.type;
+    }) ?? null;
+}
+//# sourceMappingURL=json-schema.js.map