@juno-ai/bind 11.0.0 → 13.0.0

package/tools/sanitize-schema.js

@@ -100,6 +100,196 @@
  *      `properties` is an open per-database map with no fixed sub-schema), and the
  *      key name is never changed so the model still emits the right argument key.
  *      Confirmed live: `x-ai/grok-4.3` 400→200, Gemini/Claude unaffected.
+ *   8. Resolve a COMPOSITION BRANCH's `required` against the branch's own
+ *      `properties` UNIONED with the enclosing node's `properties`, and — at the
+ *      parameters ROOT only — make the surviving branch self-sufficient by copying
+ *      the referenced property subschemas down into it and setting
+ *      `type: "object"`. This is the narrow, measured exception to transform #3.
+ *      The ordinary way to say "pass exactly one of these" puts the properties on
+ *      the parent and only `required` in each branch:
+ *
+ *        { type: "object", properties: { query: …, memoryItemId: … },
+ *          oneOf: [ { required: ["query"] }, { required: ["memoryItemId"] } ] }
+ *
+ *      which is how JSON Schema composition works, and which transform #3 alone
+ *      sanitized to `oneOf: [{}, {}]` — a root xAI (Grok) hard-rejects
+ *      (`tool parameter root must be an object type (root schema is an
+ *      anyOf/oneOf union with a non-object branch)`, failing EVERY tool in the
+ *      request), and which Gemini/OpenAI accept while silently losing the
+ *      constraint, letting the model send both parameters or neither. Measured on
+ *      xAI for branches of a ROOT union: `{type:"object", …}` or `{properties:…}`
+ *      is accepted with EITHER alone sufficing; a bare `{required:[…]}` or `{}` is
+ *      a 400. Hence the copy-down, which also makes the branch idempotent under
+ *      this sanitizer (a second pass finds every `required` name in the branch's
+ *      OWN `properties` and changes nothing).
+ *
+ *      Two limits are load-bearing, both measured:
+ *        - The parent scope is the ENCLOSING node only, and only for
+ *          `allOf`/`anyOf`/`oneOf` elements. Widening transform #3 to resolve
+ *          `required` against ALL ancestors at every node reintroduces the hard
+ *          Gemini 400 that transform #3 exists to prevent ("required fields
+ *          ['value'] are not defined in the schema properties" — still true on
+ *          gemini-3.5/3.6/3.7-flash). Every non-branch node keeps transform #3
+ *          exactly as it is, and so do `if`/`then`/`else` and `dependentSchemas`,
+ *          which are not composition arrays.
+ *        - The copy-down is ROOT-ONLY. The identical bare-`required` union nested
+ *          under a property is accepted by all nine measured models including
+ *          every Grok version, so a nested composition keeps its `required` (that
+ *          is the fix) and is otherwise left alone — no provider constrains it,
+ *          and churning it risks the transform-#5 `allOf` flatten.
+ *      Only the names in the branch's own `required` are copied, so a branch does
+ *      not inherit the parent's whole property set — and a single ceiling
+ *      (`MAX_ROOT_COPY_DOWN`) bounds the copy-down across ALL branches of one
+ *      root composition, because the per-branch bound does not bound N branches
+ *      × P names. Past the ceiling the repair is skipped, leaving the branches
+ *      bare for rule (a) below to drop.
+ *   9. Guarantee the parameters ROOT is one xAI will accept, as a final pass.
+ *      xAI rejects a root that is not an object type, and the rejection takes the
+ *      whole request (every tool) with it. Two distinct rules, each measured
+ *      against grok-4.3/4.5/4.6 (and confirmed inert on the six Gemini/OpenAI
+ *      models) through OpenRouter with `provider.allow_fallbacks: false` and one
+ *      tool per request:
+ *
+ *        a. Every element of a root `anyOf`/`oneOf` must be a plain object that
+ *           is object-shaped, and must not be `{}`. A branch that declares a
+ *           `type` is judged on that alone (`type: "object"` passes, anything
+ *           else fails even when the branch also carries `properties` — measured
+ *           0/3, identical to a bare `{type:"string"}`); a branch with no `type`
+ *           passes on `properties`. This holds even when the root ITSELF declares
+ *           `type: "object"` and `properties` — an object root does not excuse a
+ *           non-object branch. Rule (a) runs BEFORE the transform-#5 flatten,
+ *           since that flatten refuses to merge an `allOf` while a union sibling
+ *           is present; dropping the union afterwards would strand an `allOf`
+ *           that the next pass would merge, breaking idempotence. A
+ *           branch that still fails after #8 cannot be repaired (its `required`
+ *           names something no `properties` map declares — the parent supplies it
+ *           only via `patternProperties`/`additionalProperties`, or not at all —
+ *           or it is a `$ref`/scalar/boolean branch), so the whole keyword is
+ *           dropped. Losing one tool's constraint is strictly better than losing
+ *           every tool in the request.
+ *        b. A root carrying a composition keyword but declaring neither `type`
+ *           nor `properties` is rejected on its OWN account, whatever the branches
+ *           look like: `{allOf:[{$ref:…}], $defs:…}` and
+ *           `{allOf:[{type:"object",…}, {not:…}]}` are both 0/3 on Grok. Adding
+ *           `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 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
+ *      `{type:"string"}` sibling next to a valid object branch). Filtering the bad
+ *      branches out instead is accepted by xAI (3/3) but is NOT what we do — it
+ *      advertises a narrower tool, telling the model an arm is invalid so it never
+ *      calls that shape, with nothing to surface the loss. Dropping the keyword
+ *      leaves the parent's `properties` fully visible, so every shape stays
+ *      callable and a wrong COMBINATION comes back from dispatch/the remote
+ *      server as a recoverable tool error.
+ *
+ *      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, 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
+ *      branches under an `allOf` as long as (b) holds — only `anyOf`/`oneOf`
+ *      branches are validated individually. A bare union root whose branches are
+ *      all object-carrying is accepted too (xAI infers object-ness from them), so
+ *      (b) leaves it alone. Compositions nested below the root are untouched.
+ *
+ *  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 (1) or (2) discards information the model could use — a collapsed
  * union type, or a wholly-dropped `enum` — that constraint is folded into the
@@ -174,6 +364,135 @@ const SUBSCHEMA_ARRAY_KEYS = new Set([
     "oneOf",
     "prefixItems",
 ]);
+/** The three keywords whose array elements are COMPOSITION BRANCHES — branches
+ * that JSON Schema evaluates against the enclosing node, so their `required` may
+ * legitimately name a property the enclosing node declares (transform #8).
+ * `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"]);
+/**
+ * Ceiling on how many property subschemas transform #8 may copy down across ALL
+ * branches of one root composition.
+ *
+ * The per-branch bound (a branch's own `required`) does NOT bound the total: a
+ * root `oneOf` of N branches each requiring P parent properties copies N × P
+ * subschemas from an input that is only O(N + P). Both counts are
+ * attacker-controlled for a third-party MCP `rawJsonSchema`, and the references
+ * are shared in memory but EXPAND on `JSON.stringify` when the schema is written
+ * into the request — measured at N=2000, P=100, a 1.2 MB input sanitizes to a
+ * 17.5 MB request body, a 14x amplification paid on every model call. That is
+ * the same class of hazard `flattenRootAllOf` guards against below.
+ *
+ * Past the ceiling the repair is skipped, which leaves the branch bare and lets
+ * transform #9 rule (a) drop the keyword — the module's usual tiebreak, losing
+ * one tool's constraint rather than degrading every request. The cap is far
+ * above any legitimate tool schema (a large discriminated union is tens of
+ * 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
@@ -190,6 +509,13 @@ const SUBSCHEMA_MAP_KEYS = new Set([
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+/** Own-property test. `hasOwnProperty.call`, never `name in map`: the latter
+ * answers `true` for a prototype member ("toString", "valueOf"), which would let
+ * a `required: ["toString"]` survive against a `properties` map that never
+ * declared it — the exact dangling `required` transform #3 exists to prune. */
+function hasOwn(map, name) {
+    return Object.prototype.hasOwnProperty.call(map, name);
+}
 /** Join words as a human list: ["a"]→"a", ["a","b"]→"a or b", ["a","b","c"]→"a, b, or c". */
 function humanJoin(items) {
     if (items.length <= 1)
@@ -316,7 +642,164 @@ function sanitizeSchemaMap(value, depth) {
     }
     return out;
 }
-function sanitizeSchemaNode(node, depth) {
+/**
+ * Sanitize a `properties` MAP and apply transform #7 to it: a child property
+ * literally named `properties` whose schema is object-shaped trips xAI's parser,
+ * so it is collapsed to annotations only. (Only the `properties` map triggers the
+ * `/properties/properties` collision — `patternProperties`/`$defs` keys are
+ * patterns and definition names, not property names, so they go through the
+ * generic map handler.)
+ *
+ * Computed once per node, ahead of the key walk, because two things need the
+ * SANITIZED map rather than the raw one: the `properties` keyword itself, and
+ * transform #8, which resolves a composition branch's `required` against it and
+ * copies subschemas down from it. Copying the sanitized form is what makes
+ * transform #8 idempotent — a raw subschema copied into a branch would still be
+ * awaiting collapse, so a second pass would not be a no-op.
+ */
+function sanitizePropertiesKeyword(value, depth) {
+    const mapped = sanitizeSchemaMap(value, depth);
+    if (isPlainObject(mapped) &&
+        isPlainObject(mapped.properties) &&
+        looksObjectShapedToXai(mapped.properties)) {
+        mapped.properties = neutralizeXaiPropertiesField(mapped.properties);
+    }
+    return mapped;
+}
+/**
+ * Transform #8, second half (ROOT branches only): make a composition branch
+ * self-sufficient so it stands on its own as an object schema.
+ *
+ * A branch whose `required` survived the parent-scope resolution but whose names
+ * live in the PARENT's `properties` gets those subschemas copied down and, if it
+ * declared no `type`, `type: "object"`. Only the names in this branch's own
+ * `required` are copied — a branch does not inherit the parent's whole property
+ * set. A branch that needs no repair is returned unchanged (same reference), so
+ * the common case of an already-object branch costs nothing and re-sanitizing is
+ * a no-op.
+ *
+ * `parentProperties` is the parent's SANITIZED map, so the copied subschemas are
+ * shared by reference with the parent's — consistent with the module's
+ * read-only-result contract, and cheaper than a second sanitize of the same
+ * subtree.
+ *
+ * A branch naming something the parent supplies only via `patternProperties` /
+ * `additionalProperties` cannot be made self-sufficient. It cannot reach here
+ * with such a name (the first half of transform #8 resolves `required` against
+ * explicit `properties` only, so the name was already pruned), leaving an
+ * unrepairable branch for transform #9 to catch.
+ */
+function makeBranchSelfSufficient(branch, parentProperties, budget) {
+    if (!parentProperties)
+        return branch;
+    if (!Array.isArray(branch.required) || branch.required.length === 0) {
+        return branch;
+    }
+    // `required`/`properties` are object-only keywords, so repairing a branch that
+    // declares a non-object `type` would emit a self-contradictory schema — and an
+    // unmeasured one, in a function whose whole justification is emitting only
+    // shapes measured to pass. Leave it alone; transform #9 rule (a) drops the
+    // keyword, since a non-object-typed branch is unusable at a root union anyway.
+    if (hasOwn(branch, "type") && branch.type !== "object")
+        return branch;
+    const ownProperties = isPlainObject(branch.properties)
+        ? branch.properties
+        : null;
+    // `missing` — declared by the parent, to be copied down. `unsatisfiable` —
+    // declared by NEITHER map. The latter is unreachable through the walk (the
+    // parent-scope resolution has already pruned any such name), but it is
+    // handled rather than trusted: the invariant this function must not break is
+    // that every emitted `required` name is a declared property, so an
+    // unsatisfiable name is dropped from `required` instead of being carried
+    // through on an unchanged branch. A future refactor that makes this reachable
+    // then degrades to transform #3's behavior rather than emitting the dangling
+    // `required` transform #3 exists to prevent.
+    const missing = [];
+    const unsatisfiable = new Set();
+    for (const name of branch.required) {
+        if (typeof name !== "string")
+            continue;
+        if (ownProperties && hasOwn(ownProperties, name))
+            continue;
+        if (hasOwn(parentProperties, name))
+            missing.push(name);
+        else
+            unsatisfiable.add(name);
+    }
+    if (missing.length === 0 && unsatisfiable.size === 0)
+        return branch;
+    // Global copy-down ceiling (see MAX_ROOT_COPY_DOWN). Skipping the repair
+    // leaves the branch bare, so rule (a) drops the keyword rather than emitting a
+    // request body inflated by an adversarial schema.
+    if (missing.length > budget.remaining)
+        return branch;
+    budget.remaining -= missing.length;
+    const mergedProperties = {};
+    if (ownProperties) {
+        for (const [name, sub] of Object.entries(ownProperties)) {
+            safeSet(mergedProperties, name, sub);
+        }
+    }
+    // The branch's OWN declaration of a name wins over the parent's — only names
+    // it does not declare are copied down. `?? {}` because a hand-built (non-JSON)
+    // schema can carry an explicitly `undefined` property value, which `hasOwn`
+    // accepts but `JSON.stringify` drops on the wire — leaving a `required` naming
+    // a property the provider never sees. The empty schema accepts anything, so it
+    // is the neutral stand-in.
+    for (const name of missing) {
+        safeSet(mergedProperties, name, parentProperties[name] ?? {});
+    }
+    // Key order is deterministic — injected keys go in fixed positions around the
+    // branch's existing keys — so a second pass, which finds both already present
+    // and returns the branch untouched, produces the identical object.
+    const out = {};
+    if (!hasOwn(branch, "type"))
+        out.type = "object";
+    for (const [key, value] of Object.entries(branch)) {
+        if (key === "properties") {
+            out.properties = mergedProperties;
+        }
+        else if (key === "required" && unsatisfiable.size > 0) {
+            const kept = branch.required.filter((name) => typeof name === "string" && !unsatisfiable.has(name));
+            // An empty `required: []` is valid but noise; omit it, as transform #3 does.
+            if (kept.length > 0)
+                out.required = kept;
+        }
+        else {
+            safeSet(out, key, value);
+        }
+    }
+    if (!hasOwn(branch, "properties"))
+        out.properties = mergedProperties;
+    return out;
+}
+/**
+ * Recurse into one element of an `allOf`/`anyOf`/`oneOf` array (transform #8).
+ * Differs from `sanitizeSubschema` only in that the branch is told its parent's
+ * property names, so its `required` resolves against the composition scope JSON
+ * Schema actually gives it. `makeSelfSufficient` is set for the parameters ROOT
+ * only (see the module header).
+ */
+function sanitizeCompositionBranch(branch, depth, parentProperties, budget) {
+    if (depth > MAX_DEPTH)
+        return true;
+    // 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).
+    return budget
+        ? makeBranchSelfSufficient(sanitized, parentProperties, budget)
+        : sanitized;
+}
+/**
+ * @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.
+ */
+function sanitizeSchemaNode(node, depth, parentProperties) {
     // 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
@@ -326,18 +809,39 @@ function sanitizeSchemaNode(node, depth) {
     if (depth > MAX_DEPTH)
         return {};
     const childDepth = depth + 1;
-    // Property names a `required` on THIS node may reference — the node's OWN
-    // `properties` only (see module header: matches Gemini's validator, which
-    // does not resolve composition or parent scope).
-    const propertyNames = isPlainObject(node.properties)
-        ? new Set(Object.keys(node.properties))
+    // 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")
+        ? sanitizePropertiesKeyword(node.properties, childDepth)
+        : undefined;
+    const ownProperties = isPlainObject(sanitizedProperties)
+        ? sanitizedProperties
         : null;
+    // Property names a `required` on THIS node may reference — the node's OWN
+    // `properties` (see module header: transform #3 matches Gemini's validator,
+    // which does not resolve parent scope), PLUS, when this node is a composition
+    // branch, the enclosing node's `properties` (transform #8: a branch of an
+    // `allOf`/`anyOf`/`oneOf` IS evaluated against the enclosing node, so naming
+    // its properties is correct JSON Schema, not a dangling reference).
+    //
+    // Probed against the two maps directly rather than unioned into a `Set`.
+    // Building that set per node costs O(parent properties) for EVERY branch, so
+    // a schema with P parent properties and B branches is O(P × B) — and both are
+    // attacker-controlled for a third-party MCP `rawJsonSchema`. At P = B = 3000
+    // that measured ~1.1s of synchronously blocked event loop, which is a denial
+    // of service for every tenant on the process, not just the one whose
+    // connector served the schema (the same hazard `flattenRootAllOf` guards
+    // against below). Two `hasOwn` probes per `required` entry make it O(P + B).
+    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.
+    const notesFromRetype = [];
     let typeToEmit = node.type;
     let emitType = "type" in node;
     let singleType;
@@ -355,6 +859,30 @@ function sanitizeSchemaNode(node, depth) {
     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
@@ -365,7 +893,7 @@ function sanitizeSchemaNode(node, depth) {
     // 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 = [];
+    const notes = [...notesFromRetype];
     if (Array.isArray(node.type)) {
         const typeNames = node.type.filter((t) => typeof t === "string");
         if (typeNames.length > 1) {
@@ -390,6 +918,17 @@ function sanitizeSchemaNode(node, depth) {
             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 = 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 = {};
@@ -433,7 +972,7 @@ function sanitizeSchemaNode(node, depth) {
         }
         if (key === "required") {
             if (Array.isArray(value)) {
-                const pruned = value.filter((name) => typeof name === "string" && (propertyNames?.has(name) ?? false));
+                const pruned = value.filter((name) => typeof name === "string" && declaresProperty(name));
                 // An empty `required: []` is valid but noise; omit it entirely.
                 if (pruned.length > 0)
                     out.required = pruned;
@@ -442,6 +981,17 @@ function sanitizeSchemaNode(node, depth) {
             // 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
@@ -459,19 +1009,9 @@ function sanitizeSchemaNode(node, depth) {
             continue;
         }
         if (key === "properties") {
-            // Recurse normally, then apply transform #7: a child property literally
-            // named `properties` whose schema is object-shaped trips xAI's parser, so
-            // collapse it to annotations only. (Only the `properties` MAP triggers the
-            // `/properties/properties` collision — `patternProperties`/`$defs` keys are
-            // patterns/definition names, not property names, so they go through the
-            // generic map handler below.)
-            const mapped = sanitizeSchemaMap(value, childDepth);
-            if (isPlainObject(mapped) &&
-                isPlainObject(mapped.properties) &&
-                looksObjectShapedToXai(mapped.properties)) {
-                mapped.properties = neutralizeXaiPropertiesField(mapped.properties);
-            }
-            out.properties = mapped;
+            // Already sanitized (with transform #7 applied) ahead of this walk, since
+            // transform #8 below may need it first. Emit it in its original position.
+            out.properties = sanitizedProperties;
             continue;
         }
         if (SUBSCHEMA_MAP_KEYS.has(key)) {
@@ -494,7 +1034,31 @@ function sanitizeSchemaNode(node, depth) {
             out[key] = sanitizeSubschema(value, childDepth);
             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
+            // compositions are accepted as-is by every measured provider.
+            // One budget per root composition keyword, shared across its branches so
+            // the ceiling bounds the TOTAL copy-down, not each branch individually.
+            const budget = depth === 0 ? { remaining: MAX_ROOT_COPY_DOWN } : null;
+            out[key] = Array.isArray(value)
+                ? value.map((v) => sanitizeCompositionBranch(v, childDepth, ownProperties, budget))
+                : value;
+            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;
@@ -511,6 +1075,11 @@ function sanitizeSchemaNode(node, depth) {
     // 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;
 }
 /**
@@ -658,10 +1227,10 @@ function flattenRootAllOf(root) {
     const uniqueDescriptions = [...new Set(descriptions)];
     if (uniqueDescriptions.length > 0)
         out.description = uniqueDescriptions.join(" ");
-    // `hasOwnProperty.call`, not `name in mergedProps`: the latter would treat a
-    // required entry named after a prototype member ("toString", "constructor")
-    // as present and fail to prune a genuinely-undeclared property.
-    const required = [...requiredSet].filter((name) => Object.prototype.hasOwnProperty.call(mergedProps, name));
+    // `hasOwn`, not `name in mergedProps`: the latter would treat a required
+    // entry named after a prototype member ("toString", "constructor") as present
+    // and fail to prune a genuinely-undeclared property.
+    const required = [...requiredSet].filter((name) => hasOwn(mergedProps, name));
     if (required.length > 0)
         out.required = required;
     if (additionalProperties !== undefined) {
@@ -669,15 +1238,461 @@ function flattenRootAllOf(root) {
     }
     return out;
 }
+/** The two composition keywords whose ROOT branches xAI validates individually.
+ * `allOf` is deliberately absent: measured, its branches are unconstrained (a
+ * `$ref`, `not`, nested-`allOf` or scalar branch all pass) — for `allOf` it is
+ * the ROOT's own object-ness that matters, which is the second half of
+ * transform #9. */
+const ROOT_UNION_KEYS = ["anyOf", "oneOf"];
+/**
+ * True if a sanitized branch of a ROOT `anyOf`/`oneOf` is one xAI accepts.
+ * Measured on grok-4.3/4.5/4.6: `{type:"object", properties:…, required:…}`,
+ * `{properties:…, required:…}` and `{type:"object", required:…}` all pass —
+ * `type: "object"` OR `properties`, either alone, suffices — while a bare
+ * `{required:[…]}`, a `{}`, and a `{type:"string"}` are a 400 that fails every
+ * tool in the request. The rule holds even when the root itself declares
+ * `type: "object"` and `properties`, so an object root does not excuse a
+ * non-object branch.
+ */
+function isUsableRootBranch(branch) {
+    if (!isPlainObject(branch))
+        return false;
+    if (Object.keys(branch).length === 0)
+        return false;
+    // 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
+    // bare `{type:"string"}` — `{type:"string", properties:{…}, required:[…]}` is
+    // 0/3 on grok-4.3/4.5/4.6 while the same branch without the `type` is 3/3. So
+    // `properties` suffices only when the branch declares no type at all.
+    // (Transform #1 has already collapsed any `type` ARRAY to a scalar by now.)
+    if (hasOwn(branch, "type"))
+        return branch.type === "object";
+    return isPlainObject(branch.properties);
+}
+/**
+ * True if the sanitized root reads as an object root to xAI, which rejects a
+ * parameters root that is not one. Measured: `{type:"object", …}` and
+ * `{properties:…}` pass, an entirely empty `{}` passes, and a union root whose
+ * branches are all object-carrying passes (xAI infers object-ness from the
+ * branches) — but a root carrying only `$defs`, or only an `allOf`, is a 400.
+ */
+function isObjectRoot(root) {
+    // 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;
+    // Only ever called after `dropUnusableRootUnions`, so a union still present
+    // here is one whose branches are all usable.
+    return ROOT_UNION_KEYS.some((key) => Array.isArray(root[key]) && root[key].length > 0);
+}
+/**
+ * Transform #9 — the root-usability pass (see the module header). Two rules,
+ * both measured against grok-4.3/4.5/4.6 through OpenRouter with
+ * `provider.allow_fallbacks: false` and one tool per request:
+ *
+ *  a. A branch of a root `anyOf`/`oneOf` that transform #8 could not make
+ *     object-carrying cannot be repaired at all — its `required` names something
+ *     no `properties` map declares, or it is a `$ref`/scalar/boolean branch. Drop
+ *     the whole keyword rather than emit a root that 400s every tool in the
+ *     request: losing one tool's constraint beats losing every tool. (An empty
+ *     composition array constrains nothing and goes the same way.)
+ *  b. A composition root that declares neither `type` nor `properties` is
+ *     rejected on its own account, whatever its branches look like — `{allOf:
+ *     [{$ref:…}]}` and `{allOf:[…, {not:…}]}` are 0/3 on Grok. Adding
+ *     `type: "object"` makes exactly those roots pass (9/9) while changing
+ *     nothing about the composition, so the un-flattenable `allOf` that
+ *     transform #5 deliberately preserves is rescued rather than discarded.
+ *     Nothing is added when the root already declares a `type`.
+ *
+ * Applies to the parameters root only — no provider constrains a nested
+ * composition, and every measured model accepts the nested forms handled here.
+ * 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",
+    // required:[…]}, {type:"string"}]}` is 0/3 on Grok despite the first branch
+    // being perfectly good — so a mixed union cannot simply be left alone.
+    //
+    // Filtering the bad branches out instead of dropping the keyword IS accepted
+    // (a lone surviving usable branch measures 3/3), and it is not what we do:
+    // filtering ADVERTISES A NARROWER TOOL. `oneOf: [A, B]` filtered to
+    // `oneOf: [A]` tells the model the B-shaped call is invalid, so it will never
+    // make one, and nothing surfaces that the arm went missing. Dropping the
+    // keyword instead leaves the parent's `properties` fully visible: the model
+    // can still call the tool either way, and a wrong COMBINATION is caught at
+    // dispatch by the zod schema and by the remote MCP server, where it comes back
+    // as a recoverable tool error the model can retry. That matches every other
+    // transform here — they discard advisory constraints, never callable shapes.
+    const dropped = new Set();
+    for (const key of ROOT_UNION_KEYS) {
+        const branches = root[key];
+        if (!Array.isArray(branches))
+            continue;
+        if (branches.length === 0 || !branches.every(isUsableRootBranch)) {
+            dropped.add(key);
+        }
+    }
+    if (dropped.size === 0)
+        return root;
+    const out = {};
+    for (const [key, value] of Object.entries(root)) {
+        if (dropped.has(key))
+            continue;
+        safeSet(out, key, value);
+    }
+    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. Applies to EVERY root, not
+ * just composition roots.
+ */
+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);
+    }
+    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
  * the module header for the immutability caveat — opaque leaf values are
  * shared by reference, so treat the result as read-only). A non-object root
  * (boolean schema, or malformed third-party payload) yields an empty object
  * rather than throwing.
+ *
+ * Idempotent: `sanitizeToolSchema(sanitizeToolSchema(x))` deep-equals
+ * `sanitizeToolSchema(x)`. Transform #8's copy-down depends on that — a repaired
+ * branch that a second pass re-emptied would be no repair at all.
  */
 export function sanitizeToolSchema(schema) {
     if (!isPlainObject(schema))
         return {};
-    return flattenRootAllOf(sanitizeSchemaNode(schema, 0));
+    const walked = sanitizeSchemaNode(schema, 0);
+    // 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.
+    // 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;
 }