@juno-ai/bind 10.0.0 → 12.0.0

package/tools/sanitize-schema.js

@@ -100,6 +100,106 @@
  *      `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 `type` the
+ *           schema declared for itself is never overridden.
+ *
+ *      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.
+ *
+ *      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 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.
  *
  * 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 +274,32 @@ 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;
 /** 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 +316,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 +449,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,12 +616,32 @@ 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
@@ -433,7 +743,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;
@@ -459,19 +769,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,6 +794,19 @@ function sanitizeSchemaNode(node, depth) {
             out[key] = sanitizeSubschema(value, childDepth);
             continue;
         }
+        if (COMPOSITION_KEYS.has(key)) {
+            // 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)) {
             out[key] = Array.isArray(value)
                 ? value.map((v) => sanitizeSubschema(v, childDepth))
@@ -658,10 +971,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 +982,159 @@ 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;
+    // 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 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) {
+    if (root.type === "object" || 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).
+ */
+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;
+}
+/**
+ * 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.
+ */
+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)) {
+        return root;
+    }
+    const typed = { type: "object" };
+    for (const [key, value] of Object.entries(root))
+        safeSet(typed, key, value);
+    return typed;
+}
 /**
  * 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);
+    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);
 }