@juno-ai/bind 12.0.0 → 13.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juno-ai/bind",
-  "version": "12.0.0",
+  "version": "13.0.0",
   "description": "Agent harness: the tool-calling turn kernel, deterministic LLM provider routing with transport-error classification, the streaming-completion watchdog, run mechanics, sub-agent lineage and admission, transcript healing, tool-schema sanitization, the plugin/tool vocabulary, and the skill vocabulary (`./skills`) for progressive knowledge disclosure. MIT-licensed; published to npm from the canonical repo via scripts/publish-bind.ts (docs/bind.md).",
   "license": "MIT",
   "type": "module",

package/tools/sanitize-schema.d.ts

@@ -174,8 +174,11 @@
  *           `type: "object"` to such a root makes exactly those cases pass 9/9
  *           without touching the composition — so the un-flattenable root `allOf`
  *           that transform #5 deliberately preserves is RESCUED rather than
- *           discarded, and it stops being the silent 400 it is today. A `type` the
- *           schema declared for itself is never overridden.
+ *           discarded, and it stops being the silent 400 it is today. A non-object
+ *           `type` the root declared for itself IS rewritten to `"object"` and
+ *           recorded in the description — measured, such a root is rejected by
+ *           every model. Nested nodes keep their declared types unless transform
+ *           #12 applies.
  *
  *      Rule (a) is all-or-nothing per keyword, because ONE unusable branch
  *      poisons the whole union on xAI even when its siblings are good (0/3 with a
@@ -187,12 +190,34 @@
  *      callable and a wrong COMBINATION comes back from dispatch/the remote
  *      server as a recoverable tool error.
  *
- *      Two shapes are known losses, both measured and both unavoidable here:
- *      a root union of `$ref` branches (xAI does not resolve them — 0/3 even with
- *      an object root), and a root union whose branch is itself a composition
- *      (`{oneOf:[{anyOf:[…]}]}` — 0/3 even with `type:"object"` stamped on the
- *      root). Both drop to a root that is accepted but advertises no properties.
- *      Recovering the first means inlining same-document `$ref`s before rule (a).
+ *      A branch's OWN `anyOf`/`oneOf` disqualifies it too, whatever else it
+ *      declares: `{type:"object", anyOf:[…]}` as a root union branch is 0/3 on
+ *      Grok, as is a branch carrying both `allOf` and `anyOf` — the union is what
+ *      poisons it. Scope is the branch's own keys and never its subtree: a
+ *      composition on a branch's PROPERTY is accepted 9/9, one or two levels
+ *      down, so a subtree scan would destroy constraints every provider honours.
+ *      A branch's own `allOf` is likewise accepted 9/9 (even with a
+ *      bare-`required` sub-branch), the same intersection-vs-union asymmetry xAI
+ *      applies to the root — hence `ROOT_UNION_KEYS`, not `COMPOSITION_KEYS`.
+ *
+ *      A root union of `$ref` branches is no longer a loss — transform #14 below
+ *      inlines the targets so the union survives. What remains is the narrow
+ *      residue it cannot inline: a target that is not a plain object schema, one
+ *      whose expanded size exceeds the copy-down ceiling, and a self-referential
+ *      root pointer. Those branches stay unusable and still drop the keyword.
+ *
+ *      Rule (b) covers EVERY root, not only composition roots. A property sweep
+ *      over recursive shapes (`__tests__/tool-schema/property/`) found the
+ *      narrower gate emitting unusable roots for whole classes the fixtures
+ *      never reached: a scalar or array root (reachable from transform #1
+ *      collapsing `{type:["string","null"]}`), an annotation-only root, a
+ *      `$defs`-only root, and a root whose `type` contradicts its `properties` —
+ *      that last one rejected by all nine models, the only rule here with no
+ *      tolerant provider. Rule (b) also DROPS a `const` or `$ref` carried by the
+ *      root: measured `root schema is a const` / `root schema is a $ref`, 400
+ *      even alongside `type: "object"` and `properties`, and for `$ref` even
+ *      when the target resolves. Nested `const`/`$ref` are meaningful and
+ *      untouched.
  *
  *      A root `allOf`'s BRANCHES are deliberately not constrained by (a):
  *      measured, xAI accepts `$ref`, `not`, nested-`allOf` and even scalar
@@ -201,6 +226,71 @@
  *      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
  * node's `description` as prose ("Accepts string, number, or boolean.",

package/tools/sanitize-schema.js

@@ -174,8 +174,11 @@
  *           `type: "object"` to such a root makes exactly those cases pass 9/9
  *           without touching the composition — so the un-flattenable root `allOf`
  *           that transform #5 deliberately preserves is RESCUED rather than
- *           discarded, and it stops being the silent 400 it is today. A `type` the
- *           schema declared for itself is never overridden.
+ *           discarded, and it stops being the silent 400 it is today. A non-object
+ *           `type` the root declared for itself IS rewritten to `"object"` and
+ *           recorded in the description — measured, such a root is rejected by
+ *           every model. Nested nodes keep their declared types unless transform
+ *           #12 applies.
  *
  *      Rule (a) is all-or-nothing per keyword, because ONE unusable branch
  *      poisons the whole union on xAI even when its siblings are good (0/3 with a
@@ -187,12 +190,34 @@
  *      callable and a wrong COMBINATION comes back from dispatch/the remote
  *      server as a recoverable tool error.
  *
- *      Two shapes are known losses, both measured and both unavoidable here:
- *      a root union of `$ref` branches (xAI does not resolve them — 0/3 even with
- *      an object root), and a root union whose branch is itself a composition
- *      (`{oneOf:[{anyOf:[…]}]}` — 0/3 even with `type:"object"` stamped on the
- *      root). Both drop to a root that is accepted but advertises no properties.
- *      Recovering the first means inlining same-document `$ref`s before rule (a).
+ *      A branch's OWN `anyOf`/`oneOf` disqualifies it too, whatever else it
+ *      declares: `{type:"object", anyOf:[…]}` as a root union branch is 0/3 on
+ *      Grok, as is a branch carrying both `allOf` and `anyOf` — the union is what
+ *      poisons it. Scope is the branch's own keys and never its subtree: a
+ *      composition on a branch's PROPERTY is accepted 9/9, one or two levels
+ *      down, so a subtree scan would destroy constraints every provider honours.
+ *      A branch's own `allOf` is likewise accepted 9/9 (even with a
+ *      bare-`required` sub-branch), the same intersection-vs-union asymmetry xAI
+ *      applies to the root — hence `ROOT_UNION_KEYS`, not `COMPOSITION_KEYS`.
+ *
+ *      A root union of `$ref` branches is no longer a loss — transform #14 below
+ *      inlines the targets so the union survives. What remains is the narrow
+ *      residue it cannot inline: a target that is not a plain object schema, one
+ *      whose expanded size exceeds the copy-down ceiling, and a self-referential
+ *      root pointer. Those branches stay unusable and still drop the keyword.
+ *
+ *      Rule (b) covers EVERY root, not only composition roots. A property sweep
+ *      over recursive shapes (`__tests__/tool-schema/property/`) found the
+ *      narrower gate emitting unusable roots for whole classes the fixtures
+ *      never reached: a scalar or array root (reachable from transform #1
+ *      collapsing `{type:["string","null"]}`), an annotation-only root, a
+ *      `$defs`-only root, and a root whose `type` contradicts its `properties` —
+ *      that last one rejected by all nine models, the only rule here with no
+ *      tolerant provider. Rule (b) also DROPS a `const` or `$ref` carried by the
+ *      root: measured `root schema is a const` / `root schema is a $ref`, 400
+ *      even alongside `type: "object"` and `properties`, and for `$ref` even
+ *      when the target resolves. Nested `const`/`$ref` are meaningful and
+ *      untouched.
  *
  *      A root `allOf`'s BRANCHES are deliberately not constrained by (a):
  *      measured, xAI accepts `$ref`, `not`, nested-`allOf` and even scalar
@@ -201,6 +226,71 @@
  *      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
  * node's `description` as prose ("Accepts string, number, or boolean.",
@@ -300,6 +390,109 @@ const COMPOSITION_KEYS = new Set(["allOf", "anyOf", "oneOf"]);
  * branches with a handful of `required` names each).
  */
 const MAX_ROOT_COPY_DOWN = 512;
+/**
+ * Recursive size of a subtree, in nodes and keys, stopping as soon as it exceeds
+ * `cap`. Used to price transform #14's inlining: counting only a target's
+ * TOP-LEVEL keys is no bound at all, because `{type, properties}` costs 2 no
+ * matter how large `properties` is — measured, that let a 0.11 MB schema with
+ * 256 `$ref` branches expand to 26 MB of request body, a 242x amplification on
+ * attacker-controlled input. Early exit keeps the pricing itself cheap and
+ * bounded, and the depth guard mirrors the walk's.
+ */
+function subtreeWeight(value, cap, depth = 0) {
+    if (depth > MAX_DEPTH)
+        return cap + 1;
+    if (Array.isArray(value)) {
+        let total = 1;
+        for (const item of value) {
+            total += subtreeWeight(item, cap - total, depth + 1);
+            if (total > cap)
+                return total;
+        }
+        return total;
+    }
+    if (!isPlainObject(value))
+        return 1;
+    let total = 1;
+    for (const item of Object.values(value)) {
+        total += 1 + subtreeWeight(item, cap - total, depth + 1);
+        if (total > cap)
+            return total;
+    }
+    return total;
+}
+/** Longest `pattern` echoed into a description when transform #13 drops it.
+ *  A regex is guidance at that point, and an unbounded one would crowd out the
+ *  rest of the tool's description in the model's context. */
+const MAX_PATTERN_IN_PROSE = 120;
+/**
+ * True if a `pattern` uses a regex construct some provider's validator refuses.
+ * Measured, one tool per request, `provider.allow_fallbacks: false`:
+ *
+ *   - `(?=`, `(?!`, `(?<=`, `(?<!` and NAMED GROUPS `(?<name>` are all rejected
+ *     by gpt-5.6-sol and gpt-5.6-terra (`Invalid JSON schema: regex lookaround
+ *     is not supported`), and accepted by Gemini and Grok. The error says
+ *     "lookaround", but a named group fails identically — the giveaway is the
+ *     `(?<` prefix, not the semantics — so all of `(?<` goes.
+ *   - A BACKREFERENCE (`\1`…`\9`) is rejected by grok-4.5 and accepted by the
+ *     others.
+ *   - Non-capturing `(?:` is accepted everywhere and must not be caught here.
+ *
+ * The scan tracks backslash escaping and character classes so a LITERAL `\(?=`
+ * or a `[(?=]` class is not mistaken for the construct — dropping a pattern
+ * that would have been accepted costs a real constraint on every provider.
+ * Inside a class, `\1` is an octal escape rather than a backreference, so
+ * backreference detection is suppressed there too.
+ */
+function usesUnsupportedRegexConstruct(pattern) {
+    // A deliberately NAIVE character-class scan: `[` opens, the next `]` closes.
+    // RFC-correct regex treats a `]` in first position as a literal (`[]a]` is the
+    // two-member class `]`,`a`), and an earlier revision of this function did too
+    // — but the providers do not, and they are what we are modelling. Measured:
+    // `^[(?=]+$` is accepted 5/5 (the `(?=` reads as class content under BOTH
+    // parses), while `^[](?=)]+$` is REJECTED by gpt-5.6-sol/terra and accepted by
+    // Grok and Gemini. That split is only explicable if OpenAI closes the class at
+    // the first `]`, leaving `(?=` outside — i.e. the naive parse. Matching the
+    // strict spec here would keep a pattern OpenAI 400s the whole request over.
+    let inClass = false;
+    for (let i = 0; i < pattern.length; i++) {
+        const char = pattern[i];
+        if (char === "\\") {
+            const next = pattern[i + 1];
+            if (!inClass && next !== undefined) {
+                // `\1`–`\9` is a backreference (`\0` is NUL), rejected by grok-4.5.
+                if (next >= "1" && next <= "9")
+                    return true;
+                // `\k<name>` is a NAMED backreference, rejected by grok-4.5 AND
+                // gpt-5.6-sol.
+                if (next === "k" && pattern[i + 2] === "<")
+                    return true;
+            }
+            i++; // skip the escaped character
+            continue;
+        }
+        if (inClass) {
+            if (char === "]")
+                inClass = false;
+            continue;
+        }
+        if (char === "[") {
+            inClass = true;
+            continue;
+        }
+        if (char === "(" && pattern[i + 1] === "?") {
+            const kind = pattern[i + 2];
+            // `=`/`!` lookahead and `<` (lookbehind OR named group) are rejected by
+            // the OpenAI models; `>` (atomic group) is rejected by grok-4.5. Inline
+            // flags `(?i)` and non-capturing `(?:` are accepted everywhere and must
+            // NOT be caught.
+            if (kind === "=" || kind === "!" || kind === "<" || kind === ">") {
+                return true;
+            }
+        }
+    }
+    return false;
+}
 /** Name → subschema maps. `properties` is listed here for completeness, but a
  * dedicated `key === "properties"` branch in `sanitizeSchemaNode` intercepts it
  * first (to apply transform #7) and `continue`s — so the generic map handler
@@ -648,6 +841,7 @@ function sanitizeSchemaNode(node, depth, parentProperties) {
     // 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;
@@ -665,6 +859,30 @@ function sanitizeSchemaNode(node, depth, parentProperties) {
     else if (typeof node.type === "string") {
         singleType = node.type;
     }
+    // Transform #12: a node carrying `properties` IS an object, and Gemini
+    // requires it to say so — "For schema with properties, schema type should be
+    // OBJECT" on all of gemini-3.5/3.6/3.7-flash, both when the `type` is missing
+    // and when it contradicts (`{type:"string", properties:{…}}` fails the same
+    // way). Not composition-specific: a plain property subschema and an `items`
+    // schema fail identically. xAI and OpenAI accept every one of those forms,
+    // which is why it survived until a property sweep against live inference went
+    // looking.
+    //
+    // Resolved HERE rather than patched onto the finished node so the rest of the
+    // walk sees the real type: `dropEnum` below keys off it, and an `enum` left
+    // behind on a node that has just become an object would be dropped by the
+    // NEXT pass instead of this one — an idempotence break.
+    const retypedFromProperties = isPlainObject(sanitizedProperties) && singleType !== "object";
+    if (retypedFromProperties) {
+        if (singleType !== undefined) {
+            // A contradictory declared type is discarded; record it like transform #1
+            // records a collapsed union.
+            notesFromRetype.push(`Declared as ${singleType}, but carries properties, so it is treated as an object.`);
+        }
+        typeToEmit = "object";
+        emitType = true;
+        singleType = "object";
+    }
     // Gemini accepts `enum` only on string-typed properties. Drop it outright
     // when the node has an explicit NON-string type (boolean/number/integer/
     // array/object/null); when the type is "string" or absent, the enum is
@@ -675,7 +893,7 @@ function sanitizeSchemaNode(node, depth, parentProperties) {
     // could use. Fold that information into the node's `description` (as prose,
     // which every provider accepts) so the model still sees it. Computed up
     // front so it can be appended wherever `description` appears in key order.
-    const notes = [];
+    const notes = [...notesFromRetype];
     if (Array.isArray(node.type)) {
         const typeNames = node.type.filter((t) => typeof t === "string");
         if (typeNames.length > 1) {
@@ -700,6 +918,17 @@ function sanitizeSchemaNode(node, depth, parentProperties) {
             notes.push(`May also be ${humanJoin(dropped.map(describeEnumValue))}.`);
         }
     }
+    // Transform #13, decided up front so its note joins the others before
+    // `descNote` is frozen and the loop below can simply skip the keyword.
+    const dropPattern = 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 = {};
@@ -752,6 +981,17 @@ function sanitizeSchemaNode(node, depth, parentProperties) {
             // trip a strict validator) — drop it.
             continue;
         }
+        if (key === "pattern") {
+            // Transform #13: a regex construct some provider refuses takes the WHOLE
+            // request down, so the pattern is dropped and echoed as prose instead —
+            // the model still sees the intent, and arguments are validated at
+            // dispatch and by the remote server regardless. A supported pattern is a
+            // real constraint every provider honours and is kept verbatim.
+            if (dropPattern)
+                continue;
+            out.pattern = value;
+            continue;
+        }
         if (key === "dependencies") {
             // draft-07: name → (subschema | string[]). Subschema values are
             // sanitized (and self-prune their own `required`); string[] values are
@@ -795,6 +1035,14 @@ function sanitizeSchemaNode(node, depth, parentProperties) {
             continue;
         }
         if (COMPOSITION_KEYS.has(key)) {
+            // Transform #10: an EMPTY array-valued keyword is a hard 400 on xAI at
+            // any depth — `/properties/a/oneOf: [] has less than 1 item` — for all
+            // three composition keywords and for `prefixItems` below. It carries no
+            // constraint anyway (an `allOf` of nothing is satisfied by everything), so
+            // it is omitted rather than emitted. Empty OBJECTS (`properties: {}`,
+            // `$defs: {}`) and an empty `required: []` are accepted and unaffected.
+            if (Array.isArray(value) && value.length === 0)
+                continue;
             // Transform #8: each element is evaluated against THIS node, so it is
             // handed this node's property scope. The self-sufficiency repair is
             // applied at the parameters root only (`depth === 0`) — nested
@@ -808,6 +1056,9 @@ function sanitizeSchemaNode(node, depth, parentProperties) {
             continue;
         }
         if (SUBSCHEMA_ARRAY_KEYS.has(key)) {
+            // `prefixItems: []` — same empty-array rejection as the compositions above.
+            if (Array.isArray(value) && value.length === 0)
+                continue;
             out[key] = Array.isArray(value)
                 ? value.map((v) => sanitizeSubschema(v, childDepth))
                 : value;
@@ -824,6 +1075,11 @@ function sanitizeSchemaNode(node, depth, parentProperties) {
     // them to, add one so the dropped information still reaches the model.
     if (descNote && !descriptionEmitted)
         out.description = descNote;
+    // Transform #12, emission half. A node that DECLARED a `type` had it rewritten
+    // in the key loop above; one that declared none needs the key appended, since
+    // the loop only ever emits keys the node actually had.
+    if (retypedFromProperties && !hasOwn(node, "type"))
+        out.type = "object";
     return out;
 }
 /**
@@ -1003,11 +1259,34 @@ function isUsableRootBranch(branch) {
         return false;
     if (Object.keys(branch).length === 0)
         return false;
-    // Deliberately NOT recursive: a branch carrying only a nested composition
-    // (`{oneOf: [{anyOf: [{type:"object",…}, …]}]}`) is rejected 0/3 on Grok even
-    // with `type: "object"` stamped on the root, so counting it usable because its
-    // own elements are object-shaped would reintroduce the 400. Such a root drops
-    // to `{}`, which every model accepts — see the known-loss list in the header.
+    // A branch carrying its OWN `anyOf`/`oneOf` is unusable however object-shaped
+    // it otherwise looks: `{type:"object", anyOf:[…]}` as a root union branch is
+    // 0/3 on grok-4.3/4.5/4.6 (and a branch carrying BOTH `allOf` and `anyOf` is
+    // 0/3 too — the union is what poisons it), while every Gemini and GPT model
+    // accepts it. The `type` is not the problem, so the checks below never see it.
+    //
+    // This is NOT the recursion that was rejected earlier. Making such a branch
+    // *usable* is impossible — that was the right call. But "cannot be made
+    // usable" means it must be REPORTED unusable, which routes it into the drop
+    // path that already handles the other unrepairable branch shapes correctly.
+    //
+    // Scope is the branch's OWN keys, never its subtree. A composition on a
+    // branch's PROPERTY is accepted 9/9 (`{type:"object", properties:{a:{anyOf:
+    // […]}}}`), as is one two levels down, so a subtree scan would destroy
+    // constraints every provider honours. `ROOT_UNION_KEYS`, not
+    // `COMPOSITION_KEYS`: a branch's own `allOf` is accepted 9/9 — including with
+    // a bare-`required` sub-branch — which is the same intersection-vs-union
+    // asymmetry xAI applies to the root itself.
+    if (ROOT_UNION_KEYS.some((key) => hasOwn(branch, key)))
+        return false;
+    // A `$ref` disqualifies a branch too, and NOT only when it stands alone:
+    // `{$ref, type:"object"}` and `{$ref, properties}` are both 0/3 on
+    // grok-4.3/4.5/4.6 (accepted by Gemini and OpenAI). xAI does not resolve a
+    // union branch's `$ref` at all, so sibling object keywords do not redeem it.
+    // Transform #14 gets first refusal on these — it inlines the target and keeps
+    // the siblings — so only an un-inlinable one reaches the drop.
+    if (hasOwn(branch, "$ref"))
+        return false;
     // A declared `type` decides on its own: `properties` alongside an explicit
     // NON-object type is a self-contradictory branch (object keywords on a
     // non-object schema), and measured, xAI rejects it exactly as it rejects a
@@ -1027,7 +1306,14 @@ function isUsableRootBranch(branch) {
  * branches) — but a root carrying only `$defs`, or only an `allOf`, is a 400.
  */
 function isObjectRoot(root) {
-    if (root.type === "object" || isPlainObject(root.properties))
+    // A declared `type` decides first, and it is the strictest rule measured
+    // anywhere in this module: a root whose `type` is not "object" is rejected by
+    // grok-4.3/4.5/4.6, gpt-5.6-sol AND gemini-3.7-flash — 0/5 — with or without
+    // a `properties` map alongside it. Every other root rule has at least one
+    // tolerant provider; this one has none.
+    if (hasOwn(root, "type"))
+        return root.type === "object";
+    if (isPlainObject(root.properties))
         return true;
     if (Object.keys(root).length === 0)
         return true;
@@ -1059,6 +1345,74 @@ function isObjectRoot(root) {
  * Runs after `flattenRootAllOf`, so a root `allOf` that flattened losslessly is
  * already gone and only an un-flattenable one reaches rule (b).
  */
+/**
+ * Transform #14: inline a ROOT union branch that is a local `$ref`, so the union
+ * survives rule (a) instead of being dropped whole.
+ *
+ * `z.union([A, B])` renders as `{anyOf: [{$ref}, {$ref}], $defs}`, and xAI does
+ * not resolve a `$ref` union branch — 0/3 even with `type: "object"` on the
+ * root. Rule (a) therefore dropped the keyword and, with the properties living
+ * in `$defs`, the tool was left advertising no parameters at all. Inlining the
+ * target makes the branch an ordinary object branch, which is accepted 9/9, and
+ * keeps the constraint the union was expressing.
+ *
+ * Only branches that are NOT already usable are inlined, so a well-formed union
+ * is untouched and the emitted schema does not grow for no reason. One level
+ * only: a `$ref` inside the inlined target is left to resolve on its own, which
+ * is both what providers accept and what makes a recursive definition
+ * terminate here rather than loop. Sibling keywords on the branch are kept and
+ * win over the target's, matching 2020-12 `$ref` semantics. The branch count is
+ * capped for the same reason the copy-down is — both counts are
+ * attacker-controlled, and the inlined objects are shared references that expand
+ * on `JSON.stringify`.
+ */
+function inlineRootUnionRefs(root) {
+    let changed = false;
+    const out = {};
+    // ONE budget for the whole root, not one per keyword: a root carrying both an
+    // `anyOf` and a `oneOf` would otherwise get twice the ceiling, which
+    // contradicts the "single ceiling across one root composition" invariant that
+    // transform #8's copy-down also states.
+    let budget = MAX_ROOT_COPY_DOWN;
+    for (const [key, value] of Object.entries(root)) {
+        if (!ROOT_UNION_KEYS.includes(key) || !Array.isArray(value)) {
+            safeSet(out, key, value);
+            continue;
+        }
+        const branches = value.map((branch) => {
+            if (isUsableRootBranch(branch))
+                return branch;
+            if (!isPlainObject(branch) || typeof branch.$ref !== "string")
+                return branch;
+            const ref = branch.$ref;
+            if (ref !== "#" && !ref.startsWith("#/"))
+                return branch;
+            const target = resolveLocalPointer(root, ref);
+            // A self-referential root pointer would inline the whole document into
+            // one of its own branches; nothing useful, and unbounded.
+            if (!isPlainObject(target) || target === root)
+                return branch;
+            // Priced by EXPANDED size — the whole subtree that will be duplicated
+            // into the request body — not by the target's top-level key count.
+            const size = subtreeWeight(target, budget);
+            if (size > budget)
+                return branch;
+            budget -= size;
+            const inlined = {};
+            for (const [k, v] of Object.entries(target))
+                safeSet(inlined, k, v);
+            for (const [k, v] of Object.entries(branch)) {
+                if (k === "$ref")
+                    continue;
+                safeSet(inlined, k, v);
+            }
+            changed = true;
+            return inlined;
+        });
+        out[key] = branches;
+    }
+    return changed ? out : root;
+}
 function dropUnusableRootUnions(root) {
     // All-or-nothing, and deliberately so. ONE unusable branch poisons the whole
     // keyword on xAI — `{type:"object", properties:{…}, oneOf:[{type:"object",
@@ -1094,25 +1448,204 @@ function dropUnusableRootUnions(root) {
     }
     return out;
 }
+/**
+ * Keywords that make xAI classify the parameters ROOT as something other than an
+ * object schema, whatever else it declares. Measured on grok-4.5: a root
+ * carrying `const` is `root schema is a const` and a root carrying `$ref` is
+ * `root schema is a $ref` — both 400, both even when the root also declares
+ * `type: "object"` AND `properties`, and the `$ref` case even when the target
+ * resolves. Neither can describe a callable argument object, so both are dropped
+ * at the root and their information folded into the description. Nested `const`
+ * and `$ref` are meaningful and untouched.
+ */
+const ROOT_REJECTED_KEYWORDS = ["const", "$ref"];
 /**
  * Transform #9, rule (b). Runs AFTER `flattenRootAllOf`, so a root `allOf` that
  * merged losslessly is already gone and only a composition that survived — or a
- * root left bare by rule (a) — reaches this check.
- *
- * `carriedComposition` is evaluated on the pre-drop root: a root reduced to
- * `{$defs: …}` by rule (a) still needs typing, even though it no longer carries
- * a composition keyword to point at.
+ * root left bare by rule (a) — reaches this check. Applies to EVERY root, not
+ * just composition roots.
  */
-function ensureObjectRoot(root, carriedComposition) {
-    // Scoped to composition roots — the roots transforms #5/#8/#9 own — and never
-    // overrides a `type` the schema declared for itself.
-    if (!carriedComposition || hasOwn(root, "type") || isObjectRoot(root)) {
+function ensureObjectRoot(root) {
+    const rejected = ROOT_REJECTED_KEYWORDS.filter((key) => hasOwn(root, key));
+    if (rejected.length > 0) {
+        const stripped = {};
+        for (const [key, value] of Object.entries(root)) {
+            if (rejected.includes(key))
+                continue;
+            safeSet(stripped, key, value);
+        }
+        const note = rejected
+            .map((key) => key === "const"
+            ? `Pinned to a single value (${describeEnumValue(root.const)}) at the schema root.`
+            : `Declared as a reference (${describeEnumValue(root.$ref)}) at the schema root.`)
+            .join(" ");
+        stripped.description =
+            typeof stripped.description === "string" && stripped.description.length > 0
+                ? `${stripped.description} ${note}`
+                : note;
+        return ensureObjectRoot(stripped);
+    }
+    if (isObjectRoot(root))
+        return root;
+    // Applies to EVERY root, not just composition roots. A property-based sweep
+    // over recursive schema shapes found the narrower gate emitting unusable
+    // roots for whole classes the example fixtures never covered: a scalar or
+    // array root (`{type:"string"}`, reachable from transform #1 collapsing
+    // `{type:["string","null"]}`), an annotation-only root (`{description}`), a
+    // `$defs`-only root, and a root whose `type` contradicts its `properties`.
+    // Measured, all of them fail Grok, the scalar ones also fail gpt-5.6-sol, and
+    // the contradictory-type one fails all nine. `{type:"object"}` plus whatever
+    // else the root carried is accepted 9/9 in every case.
+    //
+    // Forcing `type: "object"` over a declared scalar type is a rewrite, not a
+    // repair, and it is the right one: function-call arguments are always a named
+    // object on the wire, so a scalar parameters root cannot describe a callable
+    // tool no matter which provider reads it. Sibling keywords are left as they
+    // are — an `items` stranded on an object root is inert, and every model
+    // accepts it, so removing it would be surgery with no measured benefit.
+    const declaredType = typeof root.type === "string" ? root.type : undefined;
+    const notes = [];
+    const out = { type: "object" };
+    for (const [key, value] of Object.entries(root)) {
+        if (key === "type")
+            continue;
+        // `enum` is the ONE keyword whose treatment depends on the node's type
+        // (transform #2 accepts it only on a string-typed or type-less node), so
+        // retyping the root to "object" while keeping it would leave a root the
+        // node walk would sanitize differently on a second pass — i.e. break
+        // idempotence, which the property sweep catches immediately. Drop it here
+        // and surface the values as prose, exactly as transform #2 does.
+        if (key === "enum") {
+            if (Array.isArray(value) && value.length > 0) {
+                notes.push(`Allowed values: ${value.map(describeEnumValue).join(", ")}.`);
+            }
+            continue;
+        }
+        safeSet(out, key, value);
+    }
+    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];
     }
-    const typed = { type: "object" };
-    for (const [key, value] of Object.entries(root))
-        safeSet(typed, key, value);
-    return typed;
+    return current;
+}
+/**
+ * Transform #11: drop a `$ref` whose LOCAL target does not resolve.
+ *
+ * xAI resolves `#/...` pointers itself and 400s the whole request when one
+ * dangles — `unresolvable $ref '#/$defs/Nope': key 'Nope' not found under
+ * '#/$defs'`, and `key '$defs' not found in schema` when the document has no
+ * `$defs` at all. This is easy to produce in practice: a third-party MCP server
+ * that ships a subschema without its definitions, or one whose `$defs` sits on a
+ * nested node (a `#/$defs/X` pointer is anchored at the document ROOT, so a
+ * nested `$defs` is genuinely unaddressable that way).
+ *
+ * Only local pointers are checked. An external `$ref` (`https://…`) is accepted
+ * by xAI and left alone, as is a resolvable non-`$defs` pointer such as
+ * `#/properties/a` — both measured. Dropping only the `$ref` keyword leaves the
+ * rest of the node intact; a node that was nothing but a dangling `$ref` becomes
+ * the unconstrained `{}`, which every model accepts. This runs after the node
+ * walk, so it resolves against the SANITIZED document — the one actually sent.
+ */
+function pruneUnresolvableRefs(node, root, depth, state = { changed: false }) {
+    // `{}` rather than `true`, matching `sanitizeSchemaNode`'s guard: a boolean
+    // schema is not a plain object, so `canLosslesslyFlattenAllOf` would refuse a
+    // branch it would otherwise merge.
+    if (depth > MAX_DEPTH)
+        return {};
+    if (Array.isArray(node)) {
+        return node.map((item) => pruneUnresolvableRefs(item, root, depth + 1, state));
+    }
+    if (!isPlainObject(node))
+        return node;
+    const out = {};
+    for (const [key, value] of Object.entries(node)) {
+        if (key === "$ref" &&
+            typeof value === "string" &&
+            (value === "#" || value.startsWith("#/")) &&
+            resolveLocalPointer(root, value) === undefined) {
+            state.changed = true;
+            continue;
+        }
+        // Opaque data keywords may legitimately contain a `$ref`-named key that is
+        // not a reference (the walk treats them as data for the same reason), so
+        // they are copied rather than descended into.
+        if (key === "enum" || key === "const" || key === "default" || key === "examples") {
+            safeSet(out, key, value);
+            continue;
+        }
+        safeSet(out, key, pruneUnresolvableRefs(value, root, depth + 1, state));
+    }
+    return out;
+}
+/** Prune against `root`, returning the ORIGINAL reference when nothing was
+ *  dropped so the pipeline can detect a fixed point without a deep compare
+ *  (this module deliberately never hands an untrusted value to
+ *  `JSON.stringify`, whose own recursion would outrun the depth guard). */
+function prunedOrSame(root) {
+    const state = { changed: false };
+    const pruned = pruneUnresolvableRefs(root, root, 0, state);
+    if (!state.changed)
+        return root;
+    return isPlainObject(pruned) ? pruned : {};
 }
 /**
  * Return a sanitized, non-mutating copy of a tool parameter JSON Schema (see
@@ -1129,12 +1662,37 @@ export function sanitizeToolSchema(schema) {
     if (!isPlainObject(schema))
         return {};
     const walked = sanitizeSchemaNode(schema, 0);
-    const carriedComposition = [...COMPOSITION_KEYS].some((key) => Array.isArray(walked[key]));
     // Rule (a) runs BEFORE the flatten, not after. `canLosslesslyFlattenAllOf`
     // refuses to merge an `allOf` while a `oneOf`/`anyOf` sibling is present (the
     // root is then not a pure intersection) — so dropping an unusable union
     // afterwards would leave behind an `allOf` that the NEXT pass would flatten,
     // breaking idempotence. Removing the union first makes the root a genuine
     // intersection, which is exactly when flattening it is correct.
-    return ensureObjectRoot(flattenRootAllOf(dropUnusableRootUnions(walked)), carriedComposition);
+    // The root passes are run to a FIXED POINT rather than once.
+    //
+    // Ordering alone cannot satisfy both constraints. Transform #11 has to run
+    // BEFORE the flatten, because dropping a dangling `$ref` can empty the node
+    // that carried it and an emptied `allOf` branch is merge-safe — pruning after
+    // would strand a composition for the NEXT pass to merge. But it also has to
+    // run AFTER the root rewrites, because those remove root keywords a nested
+    // `$ref` may point at: `{properties:{x:{$ref:"#/const"}}, const:{}}` loses its
+    // `const` to transform #9 and is left with exactly the dangling reference #11
+    // exists to prevent, and a flatten can invalidate `#/allOf/0` the same way.
+    //
+    // Iterating settles it: each pass returns its INPUT REFERENCE when it changes
+    // nothing, so a round that touches nothing ends the loop, and the bound keeps
+    // a pathological schema from spinning. Two rounds cover every shape the
+    // property sweep generates; the third is there so the bound is a backstop
+    // rather than the mechanism.
+    let doc = walked;
+    for (let round = 0; round < 3; round++) {
+        const before = doc;
+        // #14 precedes rule (a): an inlinable `$ref` branch becomes an ordinary
+        // object branch, so the union is kept rather than dropped. Anything still
+        // unusable falls through to the drop.
+        doc = ensureObjectRoot(flattenRootAllOf(dropUnusableRootUnions(inlineRootUnionRefs(prunedOrSame(doc)))));
+        if (doc === before)
+            break;
+    }
+    return doc;
 }