@juno-ai/bind 12.0.0 → 14.0.0

package/tools/sanitize-schema.js

@@ -32,13 +32,64 @@
  * The transforms only remove or normalize constructs that carry no real
  * constraint for a model's tool call. Each was verified against live Gemini:
  *
- *   1. Collapse a `type` ARRAY to a single `type`. Gemini requires a scalar
- *      `type` and rejects a union array. We keep the first non-`"null"`
- *      member (e.g. `["string","number","boolean"]` → `"string"`,
- *      `["string","null"]` → `"string"`); an array of only `"null"` drops
- *      the `type`. The lost alternatives are advisory — arguments are still
- *      validated at dispatch against the tool's zod schema and by the remote
- *      MCP server.
+ *   1. Resolve a `type` ARRAY, which Gemini rejects outright (it requires a
+ *      scalar `type`). Two cases, and they are not the same kind of loss:
+ *
+ *      a. NULLABLE single type — exactly one non-`"null"` member plus `"null"`,
+ *         in either order, duplicates tolerated. Rewritten to
+ *         `anyOf: [ <T branch>, {type:"null"} ]`, where the T branch carries
+ *         the node's type-bearing keywords (`minLength`, `enum`, `properties`,
+ *         `items`, bounds, …) under `type: T` and the node keeps its
+ *         annotations. The branch is re-entered through this same walk, so
+ *         every per-node transform applies to it — #12 retypes it to `"object"`
+ *         when it carries `properties`, #13 drops an unsupported `pattern` into
+ *         prose ON the branch, #2 filters its `enum`, #3 resolves its
+ *         `required` against its own `properties`.
+ *
+ *         Collapsing this case instead was lossy in a way that broke callers in
+ *         production. A model handed `{type:"string", minLength:1,
+ *         description:"… or send null …"}` cannot express "none" in the half of
+ *         the declaration it treats as binding, so it INVENTS a value that
+ *         satisfies the type: `slack_send_message.thread_ts` (authored
+ *         `type:["string","null"], minLength:1`) received `"/"`, `". "`,
+ *         `".000001"` and the like for thousands of calls, each refused by
+ *         Slack and each retried; a Drive pagination cursor had already been
+ *         seen taking `"x"`, `" "`, `"undefined"`, `"null"` and `"/"`. Prose
+ *         loses to the schema every time. The `anyOf` shape is not a guess: it
+ *         passes under `properties` on grok-4.3/4.5/4.6,
+ *         gemini-3.5/3.6/3.7-flash and gpt-5.6-terra/sol/luna, and it ships
+ *         today on every pagination cursor of six connectors. No "Accepts T or
+ *         null." note is added — the schema now says it — and an `enum` that
+ *         listed `null` contributes only its non-null members to the branch,
+ *         with no "May also be null." note, since the null branch carries that.
+ *         A sibling `enum`/`const` that EXCLUDES one arm keeps case (b)
+ *         instead: those keywords are AND-ed with `type`, so
+ *         `{type:["string","null"], enum:["x"]}` means "must be \"x\"", and a
+ *         union whose null branch the enum never reaches would admit a value
+ *         the node forbade.
+ *
+ *         Four shapes opt out. The parameters ROOT, which has to be an object
+ *         for every provider (transform #9 owns it). A branch of a ROOT
+ *         `anyOf`/`oneOf`, because a root union branch carrying its OWN `anyOf`
+ *         is 0/3 on Grok — rewriting there would turn a usable branch into one
+ *         rule (a) drops, taking the whole keyword and every shape it
+ *         advertised with it. And a COMPOSITION BRANCH whose `required` reaches
+ *         the ENCLOSING node's `properties` — the extra scope transform #8
+ *         gives it — because nesting such a name inside an `anyOf` puts it two
+ *         levels from that scope, where transform #3 prunes it away entirely
+ *         (a branch whose `required` its own `properties` cover needs no
+ *         exception). All three keep case (b). (One residue is known and accepted: a `$defs` target
+ *         rewritten this way, then inlined into a root union branch by
+ *         transform #14, is unusable for the same 0/3 reason and still drops
+ *         the keyword — the same narrow class #14 already documents.)
+ *
+ *      b. Everything else — a genuine MULTI-type union, which has no shape
+ *         every provider accepts. Collapsed to the first non-`"null"` member
+ *         (`["string","number","boolean"]` → `"string"`) with the alternatives
+ *         folded into `description`; an array of only `"null"` drops the
+ *         `type`. The lost alternatives are advisory — arguments are still
+ *         validated at dispatch against the tool's zod schema and by the remote
+ *         MCP server.
  *   2. Constrain `enum` to Gemini's rule: it is accepted ONLY as a list of
  *      strings on a string-typed (or type-less) property. So drop `enum`
  *      entirely when the node has an explicit non-string type (boolean,
@@ -174,8 +225,11 @@
  *           `type: "object"` to such a root makes exactly those cases pass 9/9
  *           without touching the composition — so the un-flattenable root `allOf`
  *           that transform #5 deliberately preserves is RESCUED rather than
- *           discarded, and it stops being the silent 400 it is today. A `type` the
- *           schema declared for itself is never overridden.
+ *           discarded, and it stops being the silent 400 it is today. A non-object
+ *           `type` the root declared for itself IS rewritten to `"object"` and
+ *           recorded in the description — measured, such a root is rejected by
+ *           every model. Nested nodes keep their declared types unless transform
+ *           #12 applies.
  *
  *      Rule (a) is all-or-nothing per keyword, because ONE unusable branch
  *      poisons the whole union on xAI even when its siblings are good (0/3 with a
@@ -187,12 +241,36 @@
  *      callable and a wrong COMBINATION comes back from dispatch/the remote
  *      server as a recoverable tool error.
  *
- *      Two shapes are known losses, both measured and both unavoidable here:
- *      a root union of `$ref` branches (xAI does not resolve them — 0/3 even with
- *      an object root), and a root union whose branch is itself a composition
- *      (`{oneOf:[{anyOf:[…]}]}` — 0/3 even with `type:"object"` stamped on the
- *      root). Both drop to a root that is accepted but advertises no properties.
- *      Recovering the first means inlining same-document `$ref`s before rule (a).
+ *      A branch's OWN `anyOf`/`oneOf` disqualifies it too, whatever else it
+ *      declares: `{type:"object", anyOf:[…]}` as a root union branch is 0/3 on
+ *      Grok, as is a branch carrying both `allOf` and `anyOf` — the union is what
+ *      poisons it. Scope is the branch's own keys and never its subtree: a
+ *      composition on a branch's PROPERTY is accepted 9/9, one or two levels
+ *      down, so a subtree scan would destroy constraints every provider honours.
+ *      A branch's own `allOf` is likewise accepted 9/9 (even with a
+ *      bare-`required` sub-branch), the same intersection-vs-union asymmetry xAI
+ *      applies to the root — hence `ROOT_UNION_KEYS`, not `COMPOSITION_KEYS`.
+ *
+ *      A root union of `$ref` branches is no longer a loss — transform #14 below
+ *      inlines the targets so the union survives. What remains is the narrow
+ *      residue it cannot inline: a target that is not a plain object schema
+ *      (a union of its own included, which is what a `$defs` entry transform
+ *      #1a rewrote becomes), one whose expanded size exceeds the copy-down
+ *      ceiling, and a self-referential root pointer. Those branches stay
+ *      unusable and still drop the keyword.
+ *
+ *      Rule (b) covers EVERY root, not only composition roots. A property sweep
+ *      over recursive shapes (`__tests__/tool-schema/property/`) found the
+ *      narrower gate emitting unusable roots for whole classes the fixtures
+ *      never reached: a scalar or array root (reachable from transform #1
+ *      collapsing `{type:["string","null"]}`), an annotation-only root, a
+ *      `$defs`-only root, and a root whose `type` contradicts its `properties` —
+ *      that last one rejected by all nine models, the only rule here with no
+ *      tolerant provider. Rule (b) also DROPS a `const` or `$ref` carried by the
+ *      root: measured `root schema is a const` / `root schema is a $ref`, 400
+ *      even alongside `type: "object"` and `properties`, and for `$ref` even
+ *      when the target resolves. Nested `const`/`$ref` are meaningful and
+ *      untouched.
  *
  *      A root `allOf`'s BRANCHES are deliberately not constrained by (a):
  *      measured, xAI accepts `$ref`, `not`, nested-`allOf` and even scalar
@@ -201,11 +279,78 @@
  *      all object-carrying is accepted too (xAI infers object-ness from them), so
  *      (b) leaves it alone. Compositions nested below the root are untouched.
  *
- * When (1) or (2) discards information the model could use — a collapsed
- * union type, or a wholly-dropped `enum` — that constraint is folded into the
- * node's `description` as prose ("Accepts string, number, or boolean.",
+ *  10. Drop an EMPTY array-valued keyword (`allOf`/`anyOf`/`oneOf`/`prefixItems`)
+ *      at any depth. xAI rejects one anywhere in the tree — `/properties/a/oneOf:
+ *      [] has less than 1 item` — and it carries no constraint (an `allOf` of
+ *      nothing is satisfied by everything). Empty OBJECTS (`properties: {}`,
+ *      `$defs: {}`) and an empty `required: []` are accepted and left alone;
+ *      `enum: []` and `required: []` were already omitted by transforms #2/#3.
+ *  11. Drop a `$ref` whose LOCAL target does not resolve. xAI resolves `#/…`
+ *      pointers itself and 400s the whole request on a dangling one
+ *      (`unresolvable $ref '#/$defs/Nope'`), which a third-party MCP server
+ *      produces easily by shipping a subschema without its definitions — or by
+ *      putting `$defs` on a nested node, since `#/$defs/X` is anchored at the
+ *      document ROOT and a nested `$defs` is unaddressable that way. External
+ *      refs (`https://…`) and resolvable non-`$defs` pointers (`#/properties/a`)
+ *      are both accepted by xAI and left alone. Only the `$ref` keyword is
+ *      dropped, so the rest of the node survives.
+ *
+ *  12. Give any node carrying `properties` an explicit `type: "object"`. Gemini
+ *      rejects the type-less form outright — "Unable to submit request because
+ *      `t` functionDeclaration `parameters.b` schema specified incorrect schema
+ *      type field. For schema with properties, schema type should be OBJECT" —
+ *      on gemini-3.5/3.6/3.7-flash, and rejects a CONTRADICTORY declared type
+ *      (`{type:"string", properties:{…}}`) the same way, so the type is
+ *      overwritten rather than merely defaulted. It is not composition-specific:
+ *      a plain property subschema and an `items` schema fail identically. xAI
+ *      and OpenAI accept every one of those forms, which is why this survived
+ *      until a property sweep over recursive shapes went looking for it. The
+ *      root is exempt in Gemini's own validator, but the rule is applied
+ *      uniformly because it costs nothing and one rule beats two.
+ *
+ *      It is resolved during the node's type resolution, not patched onto the
+ *      finished node, so `dropEnum` sees the real type — an `enum` left on a
+ *      node that has just become an object would otherwise be dropped by the
+ *      NEXT pass instead of this one, breaking idempotence. A discarded
+ *      contradictory type is folded into the description like transform #1's.
+ *      This also makes a contradictory root-union BRANCH repairable: it arrives
+ *      at transform #9 already retyped, so the constraint survives instead of
+ *      the whole keyword being dropped.
+ *
+ *  13. Drop a `pattern` that uses a regex construct a provider's validator
+ *      refuses, echoing it into the description instead. Measured: `(?=`, `(?!`,
+ *      `(?<=`, `(?<!` AND named groups `(?<name>` are rejected by gpt-5.6-sol
+ *      and gpt-5.6-terra (`Invalid JSON schema: regex lookaround is not
+ *      supported` — the message says lookaround, but a named group fails
+ *      identically, so the giveaway is the `(?<` prefix); a BACKREFERENCE
+ *      (`\1`–`\9`) is rejected by grok-4.5. Non-capturing `(?:` is accepted
+ *      everywhere and is deliberately NOT caught. This is the defect that broke
+ *      Monad's own `spaces__invite_member` on every OpenAI model — a whole-
+ *      request 400 from one tool's email pattern. The scan tracks backslash
+ *      escaping and character classes, so a literal `\(\?=` or a `[(?=]` class
+ *      keeps its pattern: dropping a pattern that would have been accepted
+ *      costs a real constraint on every provider.
+ *  14. Inline a ROOT union branch that is a local `$ref`, so the union survives
+ *      rule (a) instead of being dropped whole. `z.union([A, B])` renders as
+ *      `{anyOf:[{$ref},{$ref}], $defs}` and xAI does not resolve a `$ref` union
+ *      branch (0/3 even with `type: "object"` on the root) — so rule (a) used to
+ *      drop the keyword, which for a root whose properties live entirely in
+ *      `$defs` left the tool advertising NO parameters. Inlining produces
+ *      ordinary object branches, accepted 9/9. Only branches that are not
+ *      already usable are inlined, one level deep (a `$ref` inside the target
+ *      resolves on its own, which is what makes a recursive definition
+ *      terminate here), with branch keywords winning over the target's per
+ *      2020-12 `$ref` semantics and a cap for the same reason the copy-down has
+ *      one. A branch whose target is not a plain object schema stays unusable
+ *      and still falls through to the drop.
+ *
+ * When (1b) or (2) discards information the model could use — a collapsed
+ * multi-type union, or a wholly-dropped `enum` — that constraint is folded into
+ * the node's `description` as prose ("Accepts string, number, or boolean.",
  * "Allowed values: true.") so the model still sees it. `description` is a free
- * string every provider accepts, so this is always safe.
+ * string every provider accepts, so this is always safe. Prose is the fallback,
+ * never the first choice: where a shape every provider accepts exists, the
+ * schema says it instead — which is the whole of (1a).
  *
  * It deliberately leaves meaningful validation keywords (`format`,
  * `pattern`, object- or `true`-valued `additionalProperties`, `const`, string
@@ -280,6 +425,93 @@ const SUBSCHEMA_ARRAY_KEYS = new Set([
  * `prefixItems` is in `SUBSCHEMA_ARRAY_KEYS` but NOT here: its elements are the
  * item schemas of a tuple, a fresh scope, not branches of the enclosing object. */
 const COMPOSITION_KEYS = new Set(["allOf", "anyOf", "oneOf"]);
+/**
+ * Transform #1, nullable case: the JSON Schema type names that may stand
+ * opposite `"null"` in a `type` array for the `anyOf` rewrite to fire. An
+ * unrecognized name is left to the collapse — rewriting `{type:["foo","null"]}`
+ * into a two-branch union would emit an unmeasured shape built around a type no
+ * provider knows, where the collapse at least degrades to prose.
+ */
+const NULLABLE_UNION_TYPES = new Set([
+    "string",
+    "number",
+    "integer",
+    "boolean",
+    "object",
+    "array",
+]);
+/**
+ * Keywords whose presence on a node disqualifies it from the nullable rewrite.
+ * Each is a construct the emitted `anyOf` would have to be evaluated ALONGSIDE
+ * (an `anyOf` sibling to an `oneOf`, an `if`/`then` keyed off the node's type,
+ * …), and no such combination has been measured against a provider. A node
+ * carrying one keeps transform #1's collapse.
+ */
+const NULLABLE_REWRITE_BLOCKERS = [
+    "anyOf",
+    "oneOf",
+    "allOf",
+    "not",
+    "if",
+    "then",
+    "else",
+];
+/**
+ * The type-bearing keywords that move from a nullable node onto its typed
+ * branch, where they constrain the non-null value they were written for. Every
+ * one of them is meaningless against `null`, so leaving them on the outer node
+ * beside the union would say something the author never meant.
+ *
+ * The object-structure keywords move as a GROUP, and that is load-bearing
+ * rather than tidy. `additionalProperties` is defined against the keys that
+ * `properties` and `patternProperties` did NOT match *in the same schema
+ * object*, so moving two of the three and stranding the third silently changes
+ * what the schema says: for `{properties:{a}, patternProperties:{"^x":…},
+ * additionalProperties:{…}}`, a key `x1` was exempt from
+ * `additionalProperties` and, split across the union boundary, stops being
+ * exempt. `dependencies` / `dependentRequired` / `dependentSchemas` travel with
+ * them because they describe the same object form.
+ *
+ * Two groups deliberately stay OUTSIDE. Annotations (`description`, `title`,
+ * `default`, `examples`, `deprecated`, `readOnly`, `writeOnly`, `$comment`)
+ * describe the property as a whole, including its null case, and duplicating a
+ * description into the branch would show the model the same sentence twice. And
+ * `unevaluatedProperties` / `unevaluatedItems` are defined over the annotations
+ * every applicable schema produced — the `anyOf` branches included — so the
+ * outer node is exactly where they belong; moving one inside would narrow it to
+ * the branch's own keywords. Anything else the node carries (`$defs`, `$id`, an
+ * unknown keyword) stays outside too, keeping the treatment it has today.
+ */
+const NULLABLE_BRANCH_KEYS = new Set([
+    "minLength",
+    "maxLength",
+    "pattern",
+    "format",
+    "enum",
+    "const",
+    "minimum",
+    "maximum",
+    "exclusiveMinimum",
+    "exclusiveMaximum",
+    "multipleOf",
+    "items",
+    "prefixItems",
+    "minItems",
+    "maxItems",
+    "uniqueItems",
+    "properties",
+    "patternProperties",
+    "required",
+    "additionalProperties",
+    "propertyNames",
+    "minProperties",
+    "maxProperties",
+    "dependencies",
+    "dependentRequired",
+    "dependentSchemas",
+    "contentMediaType",
+    "contentEncoding",
+]);
 /**
  * Ceiling on how many property subschemas transform #8 may copy down across ALL
  * branches of one root composition.
@@ -300,6 +532,109 @@ const COMPOSITION_KEYS = new Set(["allOf", "anyOf", "oneOf"]);
  * branches with a handful of `required` names each).
  */
 const MAX_ROOT_COPY_DOWN = 512;
+/**
+ * Recursive size of a subtree, in nodes and keys, stopping as soon as it exceeds
+ * `cap`. Used to price transform #14's inlining: counting only a target's
+ * TOP-LEVEL keys is no bound at all, because `{type, properties}` costs 2 no
+ * matter how large `properties` is — measured, that let a 0.11 MB schema with
+ * 256 `$ref` branches expand to 26 MB of request body, a 242x amplification on
+ * attacker-controlled input. Early exit keeps the pricing itself cheap and
+ * bounded, and the depth guard mirrors the walk's.
+ */
+function subtreeWeight(value, cap, depth = 0) {
+    if (depth > MAX_DEPTH)
+        return cap + 1;
+    if (Array.isArray(value)) {
+        let total = 1;
+        for (const item of value) {
+            total += subtreeWeight(item, cap - total, depth + 1);
+            if (total > cap)
+                return total;
+        }
+        return total;
+    }
+    if (!isPlainObject(value))
+        return 1;
+    let total = 1;
+    for (const item of Object.values(value)) {
+        total += 1 + subtreeWeight(item, cap - total, depth + 1);
+        if (total > cap)
+            return total;
+    }
+    return total;
+}
+/** Longest `pattern` echoed into a description when transform #13 drops it.
+ *  A regex is guidance at that point, and an unbounded one would crowd out the
+ *  rest of the tool's description in the model's context. */
+const MAX_PATTERN_IN_PROSE = 120;
+/**
+ * True if a `pattern` uses a regex construct some provider's validator refuses.
+ * Measured, one tool per request, `provider.allow_fallbacks: false`:
+ *
+ *   - `(?=`, `(?!`, `(?<=`, `(?<!` and NAMED GROUPS `(?<name>` are all rejected
+ *     by gpt-5.6-sol and gpt-5.6-terra (`Invalid JSON schema: regex lookaround
+ *     is not supported`), and accepted by Gemini and Grok. The error says
+ *     "lookaround", but a named group fails identically — the giveaway is the
+ *     `(?<` prefix, not the semantics — so all of `(?<` goes.
+ *   - A BACKREFERENCE (`\1`…`\9`) is rejected by grok-4.5 and accepted by the
+ *     others.
+ *   - Non-capturing `(?:` is accepted everywhere and must not be caught here.
+ *
+ * The scan tracks backslash escaping and character classes so a LITERAL `\(?=`
+ * or a `[(?=]` class is not mistaken for the construct — dropping a pattern
+ * that would have been accepted costs a real constraint on every provider.
+ * Inside a class, `\1` is an octal escape rather than a backreference, so
+ * backreference detection is suppressed there too.
+ */
+function usesUnsupportedRegexConstruct(pattern) {
+    // A deliberately NAIVE character-class scan: `[` opens, the next `]` closes.
+    // RFC-correct regex treats a `]` in first position as a literal (`[]a]` is the
+    // two-member class `]`,`a`), and an earlier revision of this function did too
+    // — but the providers do not, and they are what we are modelling. Measured:
+    // `^[(?=]+$` is accepted 5/5 (the `(?=` reads as class content under BOTH
+    // parses), while `^[](?=)]+$` is REJECTED by gpt-5.6-sol/terra and accepted by
+    // Grok and Gemini. That split is only explicable if OpenAI closes the class at
+    // the first `]`, leaving `(?=` outside — i.e. the naive parse. Matching the
+    // strict spec here would keep a pattern OpenAI 400s the whole request over.
+    let inClass = false;
+    for (let i = 0; i < pattern.length; i++) {
+        const char = pattern[i];
+        if (char === "\\") {
+            const next = pattern[i + 1];
+            if (!inClass && next !== undefined) {
+                // `\1`–`\9` is a backreference (`\0` is NUL), rejected by grok-4.5.
+                if (next >= "1" && next <= "9")
+                    return true;
+                // `\k<name>` is a NAMED backreference, rejected by grok-4.5 AND
+                // gpt-5.6-sol.
+                if (next === "k" && pattern[i + 2] === "<")
+                    return true;
+            }
+            i++; // skip the escaped character
+            continue;
+        }
+        if (inClass) {
+            if (char === "]")
+                inClass = false;
+            continue;
+        }
+        if (char === "[") {
+            inClass = true;
+            continue;
+        }
+        if (char === "(" && pattern[i + 1] === "?") {
+            const kind = pattern[i + 2];
+            // `=`/`!` lookahead and `<` (lookbehind OR named group) are rejected by
+            // the OpenAI models; `>` (atomic group) is rejected by grok-4.5. Inline
+            // flags `(?i)` and non-capturing `(?:` are accepted everywhere and must
+            // NOT be caught.
+            if (kind === "=" || kind === "!" || kind === "<" || kind === ">") {
+                return true;
+            }
+        }
+    }
+    return false;
+}
 /** Name → subschema maps. `properties` is listed here for completeness, but a
  * dedicated `key === "properties"` branch in `sanitizeSchemaNode` intercepts it
  * first (to apply transform #7) and `continue`s — so the generic map handler
@@ -593,20 +928,154 @@ function sanitizeCompositionBranch(branch, depth, parentProperties, budget) {
     // Arrays and boolean/primitive schemas carry no `required` to resolve.
     if (!isPlainObject(branch))
         return sanitizeSubschema(branch, depth);
-    const sanitized = sanitizeSchemaNode(branch, depth, parentProperties);
     // A non-null budget marks a ROOT composition — the only place the
-    // self-sufficiency repair applies (see the module header).
+    // self-sufficiency repair applies, and the only place transform #1's nullable
+    // rewrite stands down (see the module header).
+    const sanitized = sanitizeSchemaNode(branch, depth, parentProperties, budget !== null);
     return budget
         ? makeBranchSelfSufficient(sanitized, parentProperties, budget)
         : sanitized;
 }
+/**
+ * Transform #1, nullable case: decide whether this node is a nullable single
+ * type — `["string","null"]` and friends — that should be REWRITTEN to an
+ * `anyOf` union instead of collapsed. Returns the non-null type name, or `null`
+ * when the node keeps today's collapse.
+ *
+ * Order of the members does not matter and duplicates are tolerated
+ * (`["null","string"]`, `["string","null","null"]`); what must hold is that
+ * exactly one distinct non-`"null"` type is present, alongside at least one
+ * `"null"`.
+ *
+ * Four shapes opt out, each for a measured or structural reason:
+ *   - The ROOT and a branch of a ROOT composition (`isRootCompositionBranch`).
+ *     The root must be an object for every provider, and a root union branch
+ *     carrying its OWN `anyOf` is 0/3 on Grok — so rewriting there would turn a
+ *     usable branch into one transform #9 rule (a) drops, taking the whole
+ *     keyword (and with it every shape the union advertised) with it.
+ *   - A sibling `enum`/`const` that excludes one of the two arms. These are
+ *     AND-ed with `type`, so `{type:["string","null"], enum:["x"]}` means "must
+ *     be \"x\"" and `{…, enum:[null]}` means "must be null". The rewrite moves
+ *     the keyword onto the TYPED branch, leaving `{type:"null"}` unconstrained
+ *     by it — so emitting the union would admit a value the node forbade. Both
+ *     directions keep the collapse; `const: null` is the exception that still
+ *     rewrites, because there the typed branch is unsatisfiable and the union
+ *     reduces to "must be null", which is what the node says (collapsing it
+ *     would give the unsatisfiable `{type:"string", const:null}` instead).
+ *   - A COMPOSITION BRANCH whose `required` reaches the ENCLOSING node's
+ *     `properties` — the extra scope transform #8 gives it. Moving such a name
+ *     inside a nested `anyOf` puts it two levels from that scope, which is
+ *     exactly the dangling `required` transform #3 exists to prevent on Gemini.
+ *     A branch whose `required` is covered by its OWN `properties` needs no
+ *     exception and is rewritten normally.
+ */
+function nullableUnionType(node, parentProperties, isRootCompositionBranch) {
+    if (isRootCompositionBranch)
+        return null;
+    const declared = node.type;
+    if (!Array.isArray(declared))
+        return null;
+    let typed = null;
+    let sawNull = false;
+    for (const member of declared) {
+        if (typeof member !== "string")
+            return null;
+        if (member === "null") {
+            sawNull = true;
+            continue;
+        }
+        if (!NULLABLE_UNION_TYPES.has(member))
+            return null;
+        if (typed !== null && typed !== member)
+            return null;
+        typed = member;
+    }
+    if (!sawNull || typed === null)
+        return null;
+    if (NULLABLE_REWRITE_BLOCKERS.some((key) => hasOwn(node, key)))
+        return null;
+    // A sibling `enum`/`const` is AND-ed with `type`, so it decides whether the
+    // two arms the `type` array advertises are BOTH actually reachable — and the
+    // rewrite may only emit an arm the input really allows. Moving the keyword
+    // onto the typed branch leaves the `{type:"null"}` branch unconstrained by
+    // it, so emitting that branch when the enum excludes `null` would admit a
+    // value the author forbade (`{type:["string","null"], enum:["x"]}` means
+    // "must be \"x\""), and emitting the typed branch when only `null` is allowed
+    // would admit every string. Either way the union would say more than the node
+    // did, so both keep the collapse.
+    //
+    // `const: null` is the one shape that still rewrites: the typed branch is
+    // then unsatisfiable and the union reduces to "must be null", exactly what
+    // the node means — where collapsing it would produce the unsatisfiable
+    // `{type:"string", const:null}` instead, which is strictly worse.
+    if (hasOwn(node, "const") && node.const !== null)
+        return null;
+    if (hasOwn(node, "enum")) {
+        if (!Array.isArray(node.enum))
+            return null;
+        const permitsNull = node.enum.some((member) => member === null);
+        const permitsNonNull = node.enum.some((member) => member !== null);
+        if (!permitsNull || !permitsNonNull)
+            return null;
+    }
+    // Only a `required` name that actually REACHES the parent scope forces the
+    // collapse. A branch whose `required` is satisfied by its own `properties`
+    // loses nothing by being rewritten, and declining there would keep the
+    // invented-value failure for a node that has no need of the exception. Key
+    // names survive sanitization unchanged, so the raw map answers this.
+    if (parentProperties != null && Array.isArray(node.required)) {
+        const own = isPlainObject(node.properties) ? node.properties : null;
+        const reachesParentScope = node.required.some((name) => typeof name === "string" && !(own !== null && hasOwn(own, name)));
+        if (reachesParentScope)
+            return null;
+    }
+    return typed;
+}
+/**
+ * Build the typed branch of a nullable rewrite: the node's own type-bearing
+ * keywords (`NULLABLE_BRANCH_KEYS`) under a scalar `type`, with `null` removed
+ * from an `enum` because the sibling `{type:"null"}` branch already carries
+ * that fact — and leaving it would make transform #2 emit a "May also be null."
+ * note the schema no longer needs.
+ *
+ * The branch is run back through `sanitizeSchemaNode` rather than assembled by
+ * hand so every per-node transform applies to it exactly as it would to any
+ * scalar-typed node: transform #12 retypes it to `"object"` when it carries
+ * `properties`, transform #13 drops an unsupported `pattern` into prose on the
+ * branch, transform #3 resolves its `required` against its own `properties`,
+ * and transform #2 filters its `enum`.
+ *
+ * Sanitized at THIS node's depth, not one deeper. The branch is a
+ * re-expression of the node, so its children sit exactly where they sat before
+ * the rewrite, and the depth budget they are charged is unchanged. No
+ * `parentProperties` is passed: the only branch that could have used one — a
+ * composition branch carrying `required` — is excluded by `nullableUnionType`.
+ */
+function buildNullableBranch(node, typeName, depth) {
+    const branch = { type: typeName };
+    for (const [key, value] of Object.entries(node)) {
+        if (!NULLABLE_BRANCH_KEYS.has(key))
+            continue;
+        if (key === "enum" && Array.isArray(value)) {
+            branch.enum = value.filter((member) => member !== null);
+            continue;
+        }
+        safeSet(branch, key, value);
+    }
+    return sanitizeSchemaNode(branch, depth);
+}
 /**
  * @param parentProperties When this node is a composition branch, the enclosing
  *   node's SANITIZED `properties` map — the extra scope its `required` may name
  *   (transform #8). `undefined`/`null` for every other node, which keeps
  *   transform #3's own-properties-only rule exactly as it was.
+ * @param isRootCompositionBranch True when this node is an element of a
+ *   composition on the parameters ROOT. Only transform #1's nullable rewrite
+ *   reads it, and only to decline: such a branch is judged individually by
+ *   transform #9 rule (a), which rejects any branch carrying its own
+ *   `anyOf`/`oneOf`.
  */
-function sanitizeSchemaNode(node, depth, parentProperties) {
+function sanitizeSchemaNode(node, depth, parentProperties, isRootCompositionBranch = false) {
     // Depth guard: stop walking absurdly nested input rather than overflowing
     // the stack. Real tool schemas are a few levels deep; anything past
     // MAX_DEPTH is adversarial, so the subtree is replaced with the
@@ -616,10 +1085,27 @@ function sanitizeSchemaNode(node, depth, parentProperties) {
     if (depth > MAX_DEPTH)
         return {};
     const childDepth = depth + 1;
+    // Transform #1, nullable case. A NON-root `{type:["T","null"], …}` is emitted
+    // as `anyOf: [<T branch>, {type:"null"}]` rather than collapsed to `T` with a
+    // prose note, because prose loses to the schema: a model reading
+    // `{type:"string", minLength:1}` cannot express "none" in the half of the
+    // declaration it treats as binding, so it invents a value that satisfies the
+    // type instead (see the module header). Decided first because everything
+    // below — the `properties` pre-pass, the type resolution, the enum rule, the
+    // notes — belongs to the BRANCH when the rewrite fires, not to the node that
+    // now carries only the union and its annotations.
+    const nullableType = depth > 0
+        ? nullableUnionType(node, parentProperties, isRootCompositionBranch)
+        : null;
+    const nullableBranch = nullableType === null
+        ? null
+        : buildNullableBranch(node, nullableType, depth);
     // Sanitized `properties`, computed ahead of the key walk because transform #8
     // needs it before the walk reaches whichever of `properties` / `oneOf` comes
     // first in key order. Emitted verbatim when the walk reaches `properties`.
-    const sanitizedProperties = hasOwn(node, "properties")
+    // Skipped entirely under a nullable rewrite, where `properties` has moved
+    // onto the typed branch and was sanitized there.
+    const sanitizedProperties = nullableType === null && hasOwn(node, "properties")
         ? sanitizePropertiesKeyword(node.properties, childDepth)
         : undefined;
     const ownProperties = isPlainObject(sanitizedProperties)
@@ -643,15 +1129,25 @@ function sanitizeSchemaNode(node, depth, parentProperties) {
     const declaresProperty = (name) => (ownProperties !== null && hasOwn(ownProperties, name)) ||
         (parentProperties != null && hasOwn(parentProperties, name));
     // Resolve the node's effective single `type`, collapsing a JSON Schema
-    // `type` ARRAY (a union, e.g. `["string","number","boolean"]` or a nullable
-    // `["string","null"]`) to the first non-"null" member. Gemini's
-    // function-declaration schema requires a single `type` and hard-rejects a
-    // type array, which manifests as a misleading downstream error. Computed up
-    // front (not in key order) because the `enum` decision below depends on it.
+    // `type` ARRAY (a MULTI-type union, e.g. `["string","number","boolean"]`) to
+    // the first non-"null" member. Gemini's function-declaration schema requires
+    // a single `type` and hard-rejects a type array, which manifests as a
+    // misleading downstream error. Computed up front (not in key order) because
+    // the `enum` decision below depends on it. The nullable case
+    // (`["string","null"]`) took the `anyOf` rewrite above and never gets here —
+    // except at the root and the two branch positions that decline it, which
+    // collapse like any other union.
+    const notesFromRetype = [];
     let typeToEmit = node.type;
     let emitType = "type" in node;
     let singleType;
-    if (Array.isArray(node.type)) {
+    if (nullableType !== null) {
+        // The `type` key's slot is taken by the `anyOf` emitted in the walk below,
+        // so nothing resolves a scalar type here and no note is manufactured: the
+        // union states the nullability the note used to approximate.
+        emitType = false;
+    }
+    else if (Array.isArray(node.type)) {
         const nonNull = node.type.filter((t) => t !== "null");
         if (nonNull.length > 0) {
             typeToEmit = nonNull[0];
@@ -665,6 +1161,30 @@ function sanitizeSchemaNode(node, depth, parentProperties) {
     else if (typeof node.type === "string") {
         singleType = node.type;
     }
+    // Transform #12: a node carrying `properties` IS an object, and Gemini
+    // requires it to say so — "For schema with properties, schema type should be
+    // OBJECT" on all of gemini-3.5/3.6/3.7-flash, both when the `type` is missing
+    // and when it contradicts (`{type:"string", properties:{…}}` fails the same
+    // way). Not composition-specific: a plain property subschema and an `items`
+    // schema fail identically. xAI and OpenAI accept every one of those forms,
+    // which is why it survived until a property sweep against live inference went
+    // looking.
+    //
+    // Resolved HERE rather than patched onto the finished node so the rest of the
+    // walk sees the real type: `dropEnum` below keys off it, and an `enum` left
+    // behind on a node that has just become an object would be dropped by the
+    // NEXT pass instead of this one — an idempotence break.
+    const retypedFromProperties = isPlainObject(sanitizedProperties) && singleType !== "object";
+    if (retypedFromProperties) {
+        if (singleType !== undefined) {
+            // A contradictory declared type is discarded; record it like transform #1
+            // records a collapsed union.
+            notesFromRetype.push(`Declared as ${singleType}, but carries properties, so it is treated as an object.`);
+        }
+        typeToEmit = "object";
+        emitType = true;
+        singleType = "object";
+    }
     // Gemini accepts `enum` only on string-typed properties. Drop it outright
     // when the node has an explicit NON-string type (boolean/number/integer/
     // array/object/null); when the type is "string" or absent, the enum is
@@ -675,8 +1195,8 @@ function sanitizeSchemaNode(node, depth, parentProperties) {
     // could use. Fold that information into the node's `description` (as prose,
     // which every provider accepts) so the model still sees it. Computed up
     // front so it can be appended wherever `description` appears in key order.
-    const notes = [];
-    if (Array.isArray(node.type)) {
+    const notes = [...notesFromRetype];
+    if (nullableType === null && Array.isArray(node.type)) {
         const typeNames = node.type.filter((t) => typeof t === "string");
         if (typeNames.length > 1) {
             notes.push(`Accepts ${humanJoin(typeNames)}.`);
@@ -686,7 +1206,7 @@ function sanitizeSchemaNode(node, depth, parentProperties) {
             notes.push("Must be null.");
         }
     }
-    if (Array.isArray(node.enum)) {
+    if (nullableType === null && Array.isArray(node.enum)) {
         const stringMembers = node.enum.filter((v) => typeof v === "string");
         if (dropEnum || stringMembers.length === 0) {
             // The whole enum is dropped (non-string type, or no string members
@@ -700,6 +1220,18 @@ function sanitizeSchemaNode(node, depth, parentProperties) {
             notes.push(`May also be ${humanJoin(dropped.map(describeEnumValue))}.`);
         }
     }
+    // Transform #13, decided up front so its note joins the others before
+    // `descNote` is frozen and the loop below can simply skip the keyword.
+    const dropPattern = nullableType === null &&
+        typeof node.pattern === "string" &&
+        usesUnsupportedRegexConstruct(node.pattern);
+    if (dropPattern) {
+        const pattern = node.pattern;
+        const shown = pattern.length > MAX_PATTERN_IN_PROSE
+            ? `${pattern.slice(0, MAX_PATTERN_IN_PROSE)}…`
+            : pattern;
+        notes.push(`Should match the pattern ${shown}.`);
+    }
     const descNote = notes.join(" ");
     let descriptionEmitted = false;
     const out = {};
@@ -711,7 +1243,19 @@ function sanitizeSchemaNode(node, depth, parentProperties) {
         // by those names are handled safely inside `sanitizeSchemaMap`.)
         if (PROTO_KEYS.has(key))
             continue;
+        // Transform #1, nullable case: every type-bearing keyword has moved onto
+        // the typed branch, which was sanitized as a node in its own right. Only
+        // the node's annotations (and any keyword outside both sets) stay here.
+        if (nullableType !== null && NULLABLE_BRANCH_KEYS.has(key))
+            continue;
         if (key === "type") {
+            if (nullableBranch !== null) {
+                // Emitted in the `type` key's own position so key order stays
+                // deterministic — which is what lets a second pass, finding an `anyOf`
+                // it leaves alone, reproduce this object exactly.
+                out.anyOf = [nullableBranch, { type: "null" }];
+                continue;
+            }
             if (emitType)
                 out.type = typeToEmit;
             continue;
@@ -752,6 +1296,17 @@ function sanitizeSchemaNode(node, depth, parentProperties) {
             // trip a strict validator) — drop it.
             continue;
         }
+        if (key === "pattern") {
+            // Transform #13: a regex construct some provider refuses takes the WHOLE
+            // request down, so the pattern is dropped and echoed as prose instead —
+            // the model still sees the intent, and arguments are validated at
+            // dispatch and by the remote server regardless. A supported pattern is a
+            // real constraint every provider honours and is kept verbatim.
+            if (dropPattern)
+                continue;
+            out.pattern = value;
+            continue;
+        }
         if (key === "dependencies") {
             // draft-07: name → (subschema | string[]). Subschema values are
             // sanitized (and self-prune their own `required`); string[] values are
@@ -795,6 +1350,14 @@ function sanitizeSchemaNode(node, depth, parentProperties) {
             continue;
         }
         if (COMPOSITION_KEYS.has(key)) {
+            // Transform #10: an EMPTY array-valued keyword is a hard 400 on xAI at
+            // any depth — `/properties/a/oneOf: [] has less than 1 item` — for all
+            // three composition keywords and for `prefixItems` below. It carries no
+            // constraint anyway (an `allOf` of nothing is satisfied by everything), so
+            // it is omitted rather than emitted. Empty OBJECTS (`properties: {}`,
+            // `$defs: {}`) and an empty `required: []` are accepted and unaffected.
+            if (Array.isArray(value) && value.length === 0)
+                continue;
             // Transform #8: each element is evaluated against THIS node, so it is
             // handed this node's property scope. The self-sufficiency repair is
             // applied at the parameters root only (`depth === 0`) — nested
@@ -808,6 +1371,9 @@ function sanitizeSchemaNode(node, depth, parentProperties) {
             continue;
         }
         if (SUBSCHEMA_ARRAY_KEYS.has(key)) {
+            // `prefixItems: []` — same empty-array rejection as the compositions above.
+            if (Array.isArray(value) && value.length === 0)
+                continue;
             out[key] = Array.isArray(value)
                 ? value.map((v) => sanitizeSubschema(v, childDepth))
                 : value;
@@ -824,6 +1390,11 @@ function sanitizeSchemaNode(node, depth, parentProperties) {
     // them to, add one so the dropped information still reaches the model.
     if (descNote && !descriptionEmitted)
         out.description = descNote;
+    // Transform #12, emission half. A node that DECLARED a `type` had it rewritten
+    // in the key loop above; one that declared none needs the key appended, since
+    // the loop only ever emits keys the node actually had.
+    if (retypedFromProperties && !hasOwn(node, "type"))
+        out.type = "object";
     return out;
 }
 /**
@@ -1003,11 +1574,34 @@ function isUsableRootBranch(branch) {
         return false;
     if (Object.keys(branch).length === 0)
         return false;
-    // Deliberately NOT recursive: a branch carrying only a nested composition
-    // (`{oneOf: [{anyOf: [{type:"object",…}, …]}]}`) is rejected 0/3 on Grok even
-    // with `type: "object"` stamped on the root, so counting it usable because its
-    // own elements are object-shaped would reintroduce the 400. Such a root drops
-    // to `{}`, which every model accepts — see the known-loss list in the header.
+    // A branch carrying its OWN `anyOf`/`oneOf` is unusable however object-shaped
+    // it otherwise looks: `{type:"object", anyOf:[…]}` as a root union branch is
+    // 0/3 on grok-4.3/4.5/4.6 (and a branch carrying BOTH `allOf` and `anyOf` is
+    // 0/3 too — the union is what poisons it), while every Gemini and GPT model
+    // accepts it. The `type` is not the problem, so the checks below never see it.
+    //
+    // This is NOT the recursion that was rejected earlier. Making such a branch
+    // *usable* is impossible — that was the right call. But "cannot be made
+    // usable" means it must be REPORTED unusable, which routes it into the drop
+    // path that already handles the other unrepairable branch shapes correctly.
+    //
+    // Scope is the branch's OWN keys, never its subtree. A composition on a
+    // branch's PROPERTY is accepted 9/9 (`{type:"object", properties:{a:{anyOf:
+    // […]}}}`), as is one two levels down, so a subtree scan would destroy
+    // constraints every provider honours. `ROOT_UNION_KEYS`, not
+    // `COMPOSITION_KEYS`: a branch's own `allOf` is accepted 9/9 — including with
+    // a bare-`required` sub-branch — which is the same intersection-vs-union
+    // asymmetry xAI applies to the root itself.
+    if (ROOT_UNION_KEYS.some((key) => hasOwn(branch, key)))
+        return false;
+    // A `$ref` disqualifies a branch too, and NOT only when it stands alone:
+    // `{$ref, type:"object"}` and `{$ref, properties}` are both 0/3 on
+    // grok-4.3/4.5/4.6 (accepted by Gemini and OpenAI). xAI does not resolve a
+    // union branch's `$ref` at all, so sibling object keywords do not redeem it.
+    // Transform #14 gets first refusal on these — it inlines the target and keeps
+    // the siblings — so only an un-inlinable one reaches the drop.
+    if (hasOwn(branch, "$ref"))
+        return false;
     // A declared `type` decides on its own: `properties` alongside an explicit
     // NON-object type is a self-contradictory branch (object keywords on a
     // non-object schema), and measured, xAI rejects it exactly as it rejects a
@@ -1027,7 +1621,14 @@ function isUsableRootBranch(branch) {
  * branches) — but a root carrying only `$defs`, or only an `allOf`, is a 400.
  */
 function isObjectRoot(root) {
-    if (root.type === "object" || isPlainObject(root.properties))
+    // A declared `type` decides first, and it is the strictest rule measured
+    // anywhere in this module: a root whose `type` is not "object" is rejected by
+    // grok-4.3/4.5/4.6, gpt-5.6-sol AND gemini-3.7-flash — 0/5 — with or without
+    // a `properties` map alongside it. Every other root rule has at least one
+    // tolerant provider; this one has none.
+    if (hasOwn(root, "type"))
+        return root.type === "object";
+    if (isPlainObject(root.properties))
         return true;
     if (Object.keys(root).length === 0)
         return true;
@@ -1059,6 +1660,74 @@ function isObjectRoot(root) {
  * Runs after `flattenRootAllOf`, so a root `allOf` that flattened losslessly is
  * already gone and only an un-flattenable one reaches rule (b).
  */
+/**
+ * Transform #14: inline a ROOT union branch that is a local `$ref`, so the union
+ * survives rule (a) instead of being dropped whole.
+ *
+ * `z.union([A, B])` renders as `{anyOf: [{$ref}, {$ref}], $defs}`, and xAI does
+ * not resolve a `$ref` union branch — 0/3 even with `type: "object"` on the
+ * root. Rule (a) therefore dropped the keyword and, with the properties living
+ * in `$defs`, the tool was left advertising no parameters at all. Inlining the
+ * target makes the branch an ordinary object branch, which is accepted 9/9, and
+ * keeps the constraint the union was expressing.
+ *
+ * Only branches that are NOT already usable are inlined, so a well-formed union
+ * is untouched and the emitted schema does not grow for no reason. One level
+ * only: a `$ref` inside the inlined target is left to resolve on its own, which
+ * is both what providers accept and what makes a recursive definition
+ * terminate here rather than loop. Sibling keywords on the branch are kept and
+ * win over the target's, matching 2020-12 `$ref` semantics. The branch count is
+ * capped for the same reason the copy-down is — both counts are
+ * attacker-controlled, and the inlined objects are shared references that expand
+ * on `JSON.stringify`.
+ */
+function inlineRootUnionRefs(root) {
+    let changed = false;
+    const out = {};
+    // ONE budget for the whole root, not one per keyword: a root carrying both an
+    // `anyOf` and a `oneOf` would otherwise get twice the ceiling, which
+    // contradicts the "single ceiling across one root composition" invariant that
+    // transform #8's copy-down also states.
+    let budget = MAX_ROOT_COPY_DOWN;
+    for (const [key, value] of Object.entries(root)) {
+        if (!ROOT_UNION_KEYS.includes(key) || !Array.isArray(value)) {
+            safeSet(out, key, value);
+            continue;
+        }
+        const branches = value.map((branch) => {
+            if (isUsableRootBranch(branch))
+                return branch;
+            if (!isPlainObject(branch) || typeof branch.$ref !== "string")
+                return branch;
+            const ref = branch.$ref;
+            if (ref !== "#" && !ref.startsWith("#/"))
+                return branch;
+            const target = resolveLocalPointer(root, ref);
+            // A self-referential root pointer would inline the whole document into
+            // one of its own branches; nothing useful, and unbounded.
+            if (!isPlainObject(target) || target === root)
+                return branch;
+            // Priced by EXPANDED size — the whole subtree that will be duplicated
+            // into the request body — not by the target's top-level key count.
+            const size = subtreeWeight(target, budget);
+            if (size > budget)
+                return branch;
+            budget -= size;
+            const inlined = {};
+            for (const [k, v] of Object.entries(target))
+                safeSet(inlined, k, v);
+            for (const [k, v] of Object.entries(branch)) {
+                if (k === "$ref")
+                    continue;
+                safeSet(inlined, k, v);
+            }
+            changed = true;
+            return inlined;
+        });
+        out[key] = branches;
+    }
+    return changed ? out : root;
+}
 function dropUnusableRootUnions(root) {
     // All-or-nothing, and deliberately so. ONE unusable branch poisons the whole
     // keyword on xAI — `{type:"object", properties:{…}, oneOf:[{type:"object",
@@ -1094,25 +1763,204 @@ function dropUnusableRootUnions(root) {
     }
     return out;
 }
+/**
+ * Keywords that make xAI classify the parameters ROOT as something other than an
+ * object schema, whatever else it declares. Measured on grok-4.5: a root
+ * carrying `const` is `root schema is a const` and a root carrying `$ref` is
+ * `root schema is a $ref` — both 400, both even when the root also declares
+ * `type: "object"` AND `properties`, and the `$ref` case even when the target
+ * resolves. Neither can describe a callable argument object, so both are dropped
+ * at the root and their information folded into the description. Nested `const`
+ * and `$ref` are meaningful and untouched.
+ */
+const ROOT_REJECTED_KEYWORDS = ["const", "$ref"];
 /**
  * Transform #9, rule (b). Runs AFTER `flattenRootAllOf`, so a root `allOf` that
  * merged losslessly is already gone and only a composition that survived — or a
- * root left bare by rule (a) — reaches this check.
- *
- * `carriedComposition` is evaluated on the pre-drop root: a root reduced to
- * `{$defs: …}` by rule (a) still needs typing, even though it no longer carries
- * a composition keyword to point at.
+ * root left bare by rule (a) — reaches this check. Applies to EVERY root, not
+ * just composition roots.
  */
-function ensureObjectRoot(root, carriedComposition) {
-    // Scoped to composition roots — the roots transforms #5/#8/#9 own — and never
-    // overrides a `type` the schema declared for itself.
-    if (!carriedComposition || hasOwn(root, "type") || isObjectRoot(root)) {
+function ensureObjectRoot(root) {
+    const rejected = ROOT_REJECTED_KEYWORDS.filter((key) => hasOwn(root, key));
+    if (rejected.length > 0) {
+        const stripped = {};
+        for (const [key, value] of Object.entries(root)) {
+            if (rejected.includes(key))
+                continue;
+            safeSet(stripped, key, value);
+        }
+        const note = rejected
+            .map((key) => key === "const"
+            ? `Pinned to a single value (${describeEnumValue(root.const)}) at the schema root.`
+            : `Declared as a reference (${describeEnumValue(root.$ref)}) at the schema root.`)
+            .join(" ");
+        stripped.description =
+            typeof stripped.description === "string" && stripped.description.length > 0
+                ? `${stripped.description} ${note}`
+                : note;
+        return ensureObjectRoot(stripped);
+    }
+    if (isObjectRoot(root))
         return root;
+    // Applies to EVERY root, not just composition roots. A property-based sweep
+    // over recursive schema shapes found the narrower gate emitting unusable
+    // roots for whole classes the example fixtures never covered: a scalar or
+    // array root (`{type:"string"}`, reachable from transform #1 collapsing
+    // `{type:["string","null"]}`), an annotation-only root (`{description}`), a
+    // `$defs`-only root, and a root whose `type` contradicts its `properties`.
+    // Measured, all of them fail Grok, the scalar ones also fail gpt-5.6-sol, and
+    // the contradictory-type one fails all nine. `{type:"object"}` plus whatever
+    // else the root carried is accepted 9/9 in every case.
+    //
+    // Forcing `type: "object"` over a declared scalar type is a rewrite, not a
+    // repair, and it is the right one: function-call arguments are always a named
+    // object on the wire, so a scalar parameters root cannot describe a callable
+    // tool no matter which provider reads it. Sibling keywords are left as they
+    // are — an `items` stranded on an object root is inert, and every model
+    // accepts it, so removing it would be surgery with no measured benefit.
+    const declaredType = typeof root.type === "string" ? root.type : undefined;
+    const notes = [];
+    const out = { type: "object" };
+    for (const [key, value] of Object.entries(root)) {
+        if (key === "type")
+            continue;
+        // `enum` is the ONE keyword whose treatment depends on the node's type
+        // (transform #2 accepts it only on a string-typed or type-less node), so
+        // retyping the root to "object" while keeping it would leave a root the
+        // node walk would sanitize differently on a second pass — i.e. break
+        // idempotence, which the property sweep catches immediately. Drop it here
+        // and surface the values as prose, exactly as transform #2 does.
+        if (key === "enum") {
+            if (Array.isArray(value) && value.length > 0) {
+                notes.push(`Allowed values: ${value.map(describeEnumValue).join(", ")}.`);
+            }
+            continue;
+        }
+        safeSet(out, key, value);
     }
-    const typed = { type: "object" };
-    for (const [key, value] of Object.entries(root))
-        safeSet(typed, key, value);
-    return typed;
+    if (declaredType !== undefined) {
+        // Fold the discarded type into the description, as transforms #1 and #2 do
+        // for the constraints they drop.
+        notes.push(`Declared as ${declaredType} at the schema root; arguments are passed as an object.`);
+    }
+    // `enum` is dropped above whenever the root is retyped, INCLUDING when it
+    // declared no type at all (`{enum:["a"]}`). Keying that on a declared scalar
+    // type left an `enum` sitting on a now-object root, which the next pass would
+    // drop under transform #2 — an idempotence break the generator never reached
+    // because it emitted no type-less `enum` root.
+    if (notes.length > 0) {
+        const note = notes.join(" ");
+        out.description =
+            typeof out.description === "string" && out.description.length > 0
+                ? `${out.description} ${note}`
+                : note;
+    }
+    return out;
+}
+/**
+ * Resolve a local JSON Pointer (`#/a/b`) against the document root, returning
+ * `undefined` when any segment is missing. Segment unescaping is the RFC 6901
+ * order — `~1` before `~0` — because doing it the other way turns a literal
+ * `~01` into `/` instead of `~1`.
+ */
+function resolveLocalPointer(root, ref) {
+    if (ref === "#")
+        return root;
+    const path = ref.slice(2);
+    // `#/` and `#//`-style paths carry no real segments; RFC 6901 makes an empty
+    // path the document root, and treating "" as a property name would prune a
+    // reference that is technically valid.
+    if (path === "")
+        return root;
+    const segments = path.split("/");
+    let current = root;
+    for (const raw of segments) {
+        // A `$ref` is a URI, so its fragment is percent-encoded: `#/$defs/a%20b`
+        // addresses the key `"a b"`. Decode that layer FIRST, then the pointer
+        // layer's `~1`/`~0`. Skipping the decode strips a perfectly valid reference
+        // as unresolvable and silently loses the constraint it carried. A malformed
+        // escape (`%zz`) throws, and the raw text is the right fallback there.
+        let decoded;
+        try {
+            decoded = decodeURIComponent(raw);
+        }
+        catch {
+            decoded = raw;
+        }
+        const segment = decoded.replace(/~1/g, "/").replace(/~0/g, "~");
+        if (Array.isArray(current)) {
+            const index = Number(segment);
+            if (!Number.isInteger(index) || index < 0 || index >= current.length) {
+                return undefined;
+            }
+            current = current[index];
+            continue;
+        }
+        if (!isPlainObject(current) || !hasOwn(current, segment))
+            return undefined;
+        current = current[segment];
+    }
+    return current;
+}
+/**
+ * Transform #11: drop a `$ref` whose LOCAL target does not resolve.
+ *
+ * xAI resolves `#/...` pointers itself and 400s the whole request when one
+ * dangles — `unresolvable $ref '#/$defs/Nope': key 'Nope' not found under
+ * '#/$defs'`, and `key '$defs' not found in schema` when the document has no
+ * `$defs` at all. This is easy to produce in practice: a third-party MCP server
+ * that ships a subschema without its definitions, or one whose `$defs` sits on a
+ * nested node (a `#/$defs/X` pointer is anchored at the document ROOT, so a
+ * nested `$defs` is genuinely unaddressable that way).
+ *
+ * Only local pointers are checked. An external `$ref` (`https://…`) is accepted
+ * by xAI and left alone, as is a resolvable non-`$defs` pointer such as
+ * `#/properties/a` — both measured. Dropping only the `$ref` keyword leaves the
+ * rest of the node intact; a node that was nothing but a dangling `$ref` becomes
+ * the unconstrained `{}`, which every model accepts. This runs after the node
+ * walk, so it resolves against the SANITIZED document — the one actually sent.
+ */
+function pruneUnresolvableRefs(node, root, depth, state = { changed: false }) {
+    // `{}` rather than `true`, matching `sanitizeSchemaNode`'s guard: a boolean
+    // schema is not a plain object, so `canLosslesslyFlattenAllOf` would refuse a
+    // branch it would otherwise merge.
+    if (depth > MAX_DEPTH)
+        return {};
+    if (Array.isArray(node)) {
+        return node.map((item) => pruneUnresolvableRefs(item, root, depth + 1, state));
+    }
+    if (!isPlainObject(node))
+        return node;
+    const out = {};
+    for (const [key, value] of Object.entries(node)) {
+        if (key === "$ref" &&
+            typeof value === "string" &&
+            (value === "#" || value.startsWith("#/")) &&
+            resolveLocalPointer(root, value) === undefined) {
+            state.changed = true;
+            continue;
+        }
+        // Opaque data keywords may legitimately contain a `$ref`-named key that is
+        // not a reference (the walk treats them as data for the same reason), so
+        // they are copied rather than descended into.
+        if (key === "enum" || key === "const" || key === "default" || key === "examples") {
+            safeSet(out, key, value);
+            continue;
+        }
+        safeSet(out, key, pruneUnresolvableRefs(value, root, depth + 1, state));
+    }
+    return out;
+}
+/** Prune against `root`, returning the ORIGINAL reference when nothing was
+ *  dropped so the pipeline can detect a fixed point without a deep compare
+ *  (this module deliberately never hands an untrusted value to
+ *  `JSON.stringify`, whose own recursion would outrun the depth guard). */
+function prunedOrSame(root) {
+    const state = { changed: false };
+    const pruned = pruneUnresolvableRefs(root, root, 0, state);
+    if (!state.changed)
+        return root;
+    return isPlainObject(pruned) ? pruned : {};
 }
 /**
  * Return a sanitized, non-mutating copy of a tool parameter JSON Schema (see
@@ -1129,12 +1977,37 @@ export function sanitizeToolSchema(schema) {
     if (!isPlainObject(schema))
         return {};
     const walked = sanitizeSchemaNode(schema, 0);
-    const carriedComposition = [...COMPOSITION_KEYS].some((key) => Array.isArray(walked[key]));
     // Rule (a) runs BEFORE the flatten, not after. `canLosslesslyFlattenAllOf`
     // refuses to merge an `allOf` while a `oneOf`/`anyOf` sibling is present (the
     // root is then not a pure intersection) — so dropping an unusable union
     // afterwards would leave behind an `allOf` that the NEXT pass would flatten,
     // breaking idempotence. Removing the union first makes the root a genuine
     // intersection, which is exactly when flattening it is correct.
-    return ensureObjectRoot(flattenRootAllOf(dropUnusableRootUnions(walked)), carriedComposition);
+    // The root passes are run to a FIXED POINT rather than once.
+    //
+    // Ordering alone cannot satisfy both constraints. Transform #11 has to run
+    // BEFORE the flatten, because dropping a dangling `$ref` can empty the node
+    // that carried it and an emptied `allOf` branch is merge-safe — pruning after
+    // would strand a composition for the NEXT pass to merge. But it also has to
+    // run AFTER the root rewrites, because those remove root keywords a nested
+    // `$ref` may point at: `{properties:{x:{$ref:"#/const"}}, const:{}}` loses its
+    // `const` to transform #9 and is left with exactly the dangling reference #11
+    // exists to prevent, and a flatten can invalidate `#/allOf/0` the same way.
+    //
+    // Iterating settles it: each pass returns its INPUT REFERENCE when it changes
+    // nothing, so a round that touches nothing ends the loop, and the bound keeps
+    // a pathological schema from spinning. Two rounds cover every shape the
+    // property sweep generates; the third is there so the bound is a backstop
+    // rather than the mechanism.
+    let doc = walked;
+    for (let round = 0; round < 3; round++) {
+        const before = doc;
+        // #14 precedes rule (a): an inlinable `$ref` branch becomes an ordinary
+        // object branch, so the union is kept rather than dropped. Anything still
+        // unusable falls through to the drop.
+        doc = ensureObjectRoot(flattenRootAllOf(dropUnusableRootUnions(inlineRootUnionRefs(prunedOrSame(doc)))));
+        if (doc === before)
+            break;
+    }
+    return doc;
 }