@juno-ai/bind 13.0.0 → 14.0.0

package/README.md

@@ -56,6 +56,27 @@ constraints that will fail CI if you break them.
 
 **Breaking**
 
+- **`sanitizeToolSchema` now emits a union for a nullable property** instead of
+  collapsing it. `{type:["string","null"], minLength:1}` comes out as
+  `{anyOf:[{type:"string",minLength:1},{type:"null"}]}`, with the node's
+  type-bearing keywords on the typed branch and its annotations left outside;
+  the old output was `{type:"string", minLength:1}` plus an "Accepts string or
+  null." note on the description. Nothing in the API changed, but the emitted
+  schema did — a consumer asserting on sanitizer output, or reading `.type` off
+  a sanitized node, needs updating.
+
+  The collapse was lossy in a way that broke callers. A model handed a
+  type-satisfying schema and a description that says "or send null" cannot
+  express "none" in the half of the declaration it treats as binding, so it
+  invents a value: one tool parameter authored `type:["string","null"],
+  minLength:1` received `"/"`, `". "` and `".000001"` for thousands of calls,
+  each refused by the downstream API and each retried. The union shape is
+  measured accepted on grok-4.3/4.5/4.6, gemini-3.5/3.6/3.7-flash and
+  gpt-5.6-terra/sol/luna. A genuine multi-type union
+  (`["string","number","boolean"]`) still collapses — no single shape is
+  accepted by every provider — and so does a nullable type at the parameters root, in
+  a branch of a root `anyOf`/`oneOf`, or in a composition branch whose
+  `required` resolves against the enclosing node.
 - `runToolLoop` now returns `ToolLoopResult` (`{ stopReason, stats }`) instead
   of `void`. A caller that ignores the return value is unchanged, but a
   wrapper *annotated* `Promise<void>` no longer typechecks — widen it to
@@ -1048,6 +1069,15 @@ property; a boolean `additionalProperties: false` on a nested object; and a
 parameter literally named `properties`. Run it on third-party (e.g. MCP) tool
 schemas too — those are where the violations usually come from.
 
+One transform is worth knowing about even if no provider forced it. A **nullable
+property** — `{type:["string","null"], minLength:1}` — is rewritten to
+`{anyOf:[{type:"string",minLength:1},{type:"null"}]}` rather than reduced to its
+non-null type with a note on the description. Reducing it is what a strict
+provider needs, but it leaves the model unable to say "none" in the part of the
+declaration it treats as binding, so it invents a value that satisfies the type:
+`"/"`, `" "`, `"null"`, `"undefined"`. If you author nullable parameters, you do
+not need to hand-write the union — the sanitizer produces it.
+
 ### How to repair a transcript before sending it
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juno-ai/bind",
-  "version": "13.0.0",
+  "version": "14.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

@@ -32,13 +32,64 @@
  * The transforms only remove or normalize constructs that carry no real
  * constraint for a model's tool call. Each was verified against live Gemini:
  *
- *   1. Collapse a `type` ARRAY to a single `type`. Gemini requires a scalar
- *      `type` and rejects a union array. We keep the first non-`"null"`
- *      member (e.g. `["string","number","boolean"]` → `"string"`,
- *      `["string","null"]` → `"string"`); an array of only `"null"` drops
- *      the `type`. The lost alternatives are advisory — arguments are still
- *      validated at dispatch against the tool's zod schema and by the remote
- *      MCP server.
+ *   1. Resolve a `type` ARRAY, which Gemini rejects outright (it requires a
+ *      scalar `type`). Two cases, and they are not the same kind of loss:
+ *
+ *      a. NULLABLE single type — exactly one non-`"null"` member plus `"null"`,
+ *         in either order, duplicates tolerated. Rewritten to
+ *         `anyOf: [ <T branch>, {type:"null"} ]`, where the T branch carries
+ *         the node's type-bearing keywords (`minLength`, `enum`, `properties`,
+ *         `items`, bounds, …) under `type: T` and the node keeps its
+ *         annotations. The branch is re-entered through this same walk, so
+ *         every per-node transform applies to it — #12 retypes it to `"object"`
+ *         when it carries `properties`, #13 drops an unsupported `pattern` into
+ *         prose ON the branch, #2 filters its `enum`, #3 resolves its
+ *         `required` against its own `properties`.
+ *
+ *         Collapsing this case instead was lossy in a way that broke callers in
+ *         production. A model handed `{type:"string", minLength:1,
+ *         description:"… or send null …"}` cannot express "none" in the half of
+ *         the declaration it treats as binding, so it INVENTS a value that
+ *         satisfies the type: `slack_send_message.thread_ts` (authored
+ *         `type:["string","null"], minLength:1`) received `"/"`, `". "`,
+ *         `".000001"` and the like for thousands of calls, each refused by
+ *         Slack and each retried; a Drive pagination cursor had already been
+ *         seen taking `"x"`, `" "`, `"undefined"`, `"null"` and `"/"`. Prose
+ *         loses to the schema every time. The `anyOf` shape is not a guess: it
+ *         passes under `properties` on grok-4.3/4.5/4.6,
+ *         gemini-3.5/3.6/3.7-flash and gpt-5.6-terra/sol/luna, and it ships
+ *         today on every pagination cursor of six connectors. No "Accepts T or
+ *         null." note is added — the schema now says it — and an `enum` that
+ *         listed `null` contributes only its non-null members to the branch,
+ *         with no "May also be null." note, since the null branch carries that.
+ *         A sibling `enum`/`const` that EXCLUDES one arm keeps case (b)
+ *         instead: those keywords are AND-ed with `type`, so
+ *         `{type:["string","null"], enum:["x"]}` means "must be \"x\"", and a
+ *         union whose null branch the enum never reaches would admit a value
+ *         the node forbade.
+ *
+ *         Four shapes opt out. The parameters ROOT, which has to be an object
+ *         for every provider (transform #9 owns it). A branch of a ROOT
+ *         `anyOf`/`oneOf`, because a root union branch carrying its OWN `anyOf`
+ *         is 0/3 on Grok — rewriting there would turn a usable branch into one
+ *         rule (a) drops, taking the whole keyword and every shape it
+ *         advertised with it. And a COMPOSITION BRANCH whose `required` reaches
+ *         the ENCLOSING node's `properties` — the extra scope transform #8
+ *         gives it — because nesting such a name inside an `anyOf` puts it two
+ *         levels from that scope, where transform #3 prunes it away entirely
+ *         (a branch whose `required` its own `properties` cover needs no
+ *         exception). All three keep case (b). (One residue is known and accepted: a `$defs` target
+ *         rewritten this way, then inlined into a root union branch by
+ *         transform #14, is unusable for the same 0/3 reason and still drops
+ *         the keyword — the same narrow class #14 already documents.)
+ *
+ *      b. Everything else — a genuine MULTI-type union, which has no shape
+ *         every provider accepts. Collapsed to the first non-`"null"` member
+ *         (`["string","number","boolean"]` → `"string"`) with the alternatives
+ *         folded into `description`; an array of only `"null"` drops the
+ *         `type`. The lost alternatives are advisory — arguments are still
+ *         validated at dispatch against the tool's zod schema and by the remote
+ *         MCP server.
  *   2. Constrain `enum` to Gemini's rule: it is accepted ONLY as a list of
  *      strings on a string-typed (or type-less) property. So drop `enum`
  *      entirely when the node has an explicit non-string type (boolean,
@@ -202,9 +253,11 @@
  *
  *      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.
+ *      residue it cannot inline: a target that is not a plain object schema
+ *      (a union of its own included, which is what a `$defs` entry transform
+ *      #1a rewrote becomes), one whose expanded size exceeds the copy-down
+ *      ceiling, and a self-referential root pointer. Those branches stay
+ *      unusable and still drop the keyword.
  *
  *      Rule (b) covers EVERY root, not only composition roots. A property sweep
  *      over recursive shapes (`__tests__/tool-schema/property/`) found the
@@ -291,11 +344,13 @@
  *      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.",
+ * When (1b) or (2) discards information the model could use — a collapsed
+ * multi-type union, or a wholly-dropped `enum` — that constraint is folded into
+ * the node's `description` as prose ("Accepts string, number, or boolean.",
  * "Allowed values: true.") so the model still sees it. `description` is a free
- * string every provider accepts, so this is always safe.
+ * string every provider accepts, so this is always safe. Prose is the fallback,
+ * never the first choice: where a shape every provider accepts exists, the
+ * schema says it instead — which is the whole of (1a).
  *
  * It deliberately leaves meaningful validation keywords (`format`,
  * `pattern`, object- or `true`-valued `additionalProperties`, `const`, string

package/tools/sanitize-schema.js

@@ -32,13 +32,64 @@
  * The transforms only remove or normalize constructs that carry no real
  * constraint for a model's tool call. Each was verified against live Gemini:
  *
- *   1. Collapse a `type` ARRAY to a single `type`. Gemini requires a scalar
- *      `type` and rejects a union array. We keep the first non-`"null"`
- *      member (e.g. `["string","number","boolean"]` → `"string"`,
- *      `["string","null"]` → `"string"`); an array of only `"null"` drops
- *      the `type`. The lost alternatives are advisory — arguments are still
- *      validated at dispatch against the tool's zod schema and by the remote
- *      MCP server.
+ *   1. Resolve a `type` ARRAY, which Gemini rejects outright (it requires a
+ *      scalar `type`). Two cases, and they are not the same kind of loss:
+ *
+ *      a. NULLABLE single type — exactly one non-`"null"` member plus `"null"`,
+ *         in either order, duplicates tolerated. Rewritten to
+ *         `anyOf: [ <T branch>, {type:"null"} ]`, where the T branch carries
+ *         the node's type-bearing keywords (`minLength`, `enum`, `properties`,
+ *         `items`, bounds, …) under `type: T` and the node keeps its
+ *         annotations. The branch is re-entered through this same walk, so
+ *         every per-node transform applies to it — #12 retypes it to `"object"`
+ *         when it carries `properties`, #13 drops an unsupported `pattern` into
+ *         prose ON the branch, #2 filters its `enum`, #3 resolves its
+ *         `required` against its own `properties`.
+ *
+ *         Collapsing this case instead was lossy in a way that broke callers in
+ *         production. A model handed `{type:"string", minLength:1,
+ *         description:"… or send null …"}` cannot express "none" in the half of
+ *         the declaration it treats as binding, so it INVENTS a value that
+ *         satisfies the type: `slack_send_message.thread_ts` (authored
+ *         `type:["string","null"], minLength:1`) received `"/"`, `". "`,
+ *         `".000001"` and the like for thousands of calls, each refused by
+ *         Slack and each retried; a Drive pagination cursor had already been
+ *         seen taking `"x"`, `" "`, `"undefined"`, `"null"` and `"/"`. Prose
+ *         loses to the schema every time. The `anyOf` shape is not a guess: it
+ *         passes under `properties` on grok-4.3/4.5/4.6,
+ *         gemini-3.5/3.6/3.7-flash and gpt-5.6-terra/sol/luna, and it ships
+ *         today on every pagination cursor of six connectors. No "Accepts T or
+ *         null." note is added — the schema now says it — and an `enum` that
+ *         listed `null` contributes only its non-null members to the branch,
+ *         with no "May also be null." note, since the null branch carries that.
+ *         A sibling `enum`/`const` that EXCLUDES one arm keeps case (b)
+ *         instead: those keywords are AND-ed with `type`, so
+ *         `{type:["string","null"], enum:["x"]}` means "must be \"x\"", and a
+ *         union whose null branch the enum never reaches would admit a value
+ *         the node forbade.
+ *
+ *         Four shapes opt out. The parameters ROOT, which has to be an object
+ *         for every provider (transform #9 owns it). A branch of a ROOT
+ *         `anyOf`/`oneOf`, because a root union branch carrying its OWN `anyOf`
+ *         is 0/3 on Grok — rewriting there would turn a usable branch into one
+ *         rule (a) drops, taking the whole keyword and every shape it
+ *         advertised with it. And a COMPOSITION BRANCH whose `required` reaches
+ *         the ENCLOSING node's `properties` — the extra scope transform #8
+ *         gives it — because nesting such a name inside an `anyOf` puts it two
+ *         levels from that scope, where transform #3 prunes it away entirely
+ *         (a branch whose `required` its own `properties` cover needs no
+ *         exception). All three keep case (b). (One residue is known and accepted: a `$defs` target
+ *         rewritten this way, then inlined into a root union branch by
+ *         transform #14, is unusable for the same 0/3 reason and still drops
+ *         the keyword — the same narrow class #14 already documents.)
+ *
+ *      b. Everything else — a genuine MULTI-type union, which has no shape
+ *         every provider accepts. Collapsed to the first non-`"null"` member
+ *         (`["string","number","boolean"]` → `"string"`) with the alternatives
+ *         folded into `description`; an array of only `"null"` drops the
+ *         `type`. The lost alternatives are advisory — arguments are still
+ *         validated at dispatch against the tool's zod schema and by the remote
+ *         MCP server.
  *   2. Constrain `enum` to Gemini's rule: it is accepted ONLY as a list of
  *      strings on a string-typed (or type-less) property. So drop `enum`
  *      entirely when the node has an explicit non-string type (boolean,
@@ -202,9 +253,11 @@
  *
  *      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.
+ *      residue it cannot inline: a target that is not a plain object schema
+ *      (a union of its own included, which is what a `$defs` entry transform
+ *      #1a rewrote becomes), one whose expanded size exceeds the copy-down
+ *      ceiling, and a self-referential root pointer. Those branches stay
+ *      unusable and still drop the keyword.
  *
  *      Rule (b) covers EVERY root, not only composition roots. A property sweep
  *      over recursive shapes (`__tests__/tool-schema/property/`) found the
@@ -291,11 +344,13 @@
  *      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.",
+ * When (1b) or (2) discards information the model could use — a collapsed
+ * multi-type union, or a wholly-dropped `enum` — that constraint is folded into
+ * the node's `description` as prose ("Accepts string, number, or boolean.",
  * "Allowed values: true.") so the model still sees it. `description` is a free
- * string every provider accepts, so this is always safe.
+ * string every provider accepts, so this is always safe. Prose is the fallback,
+ * never the first choice: where a shape every provider accepts exists, the
+ * schema says it instead — which is the whole of (1a).
  *
  * It deliberately leaves meaningful validation keywords (`format`,
  * `pattern`, object- or `true`-valued `additionalProperties`, `const`, string
@@ -370,6 +425,93 @@ const SUBSCHEMA_ARRAY_KEYS = new Set([
  * `prefixItems` is in `SUBSCHEMA_ARRAY_KEYS` but NOT here: its elements are the
  * item schemas of a tuple, a fresh scope, not branches of the enclosing object. */
 const COMPOSITION_KEYS = new Set(["allOf", "anyOf", "oneOf"]);
+/**
+ * Transform #1, nullable case: the JSON Schema type names that may stand
+ * opposite `"null"` in a `type` array for the `anyOf` rewrite to fire. An
+ * unrecognized name is left to the collapse — rewriting `{type:["foo","null"]}`
+ * into a two-branch union would emit an unmeasured shape built around a type no
+ * provider knows, where the collapse at least degrades to prose.
+ */
+const NULLABLE_UNION_TYPES = new Set([
+    "string",
+    "number",
+    "integer",
+    "boolean",
+    "object",
+    "array",
+]);
+/**
+ * Keywords whose presence on a node disqualifies it from the nullable rewrite.
+ * Each is a construct the emitted `anyOf` would have to be evaluated ALONGSIDE
+ * (an `anyOf` sibling to an `oneOf`, an `if`/`then` keyed off the node's type,
+ * …), and no such combination has been measured against a provider. A node
+ * carrying one keeps transform #1's collapse.
+ */
+const NULLABLE_REWRITE_BLOCKERS = [
+    "anyOf",
+    "oneOf",
+    "allOf",
+    "not",
+    "if",
+    "then",
+    "else",
+];
+/**
+ * The type-bearing keywords that move from a nullable node onto its typed
+ * branch, where they constrain the non-null value they were written for. Every
+ * one of them is meaningless against `null`, so leaving them on the outer node
+ * beside the union would say something the author never meant.
+ *
+ * The object-structure keywords move as a GROUP, and that is load-bearing
+ * rather than tidy. `additionalProperties` is defined against the keys that
+ * `properties` and `patternProperties` did NOT match *in the same schema
+ * object*, so moving two of the three and stranding the third silently changes
+ * what the schema says: for `{properties:{a}, patternProperties:{"^x":…},
+ * additionalProperties:{…}}`, a key `x1` was exempt from
+ * `additionalProperties` and, split across the union boundary, stops being
+ * exempt. `dependencies` / `dependentRequired` / `dependentSchemas` travel with
+ * them because they describe the same object form.
+ *
+ * Two groups deliberately stay OUTSIDE. Annotations (`description`, `title`,
+ * `default`, `examples`, `deprecated`, `readOnly`, `writeOnly`, `$comment`)
+ * describe the property as a whole, including its null case, and duplicating a
+ * description into the branch would show the model the same sentence twice. And
+ * `unevaluatedProperties` / `unevaluatedItems` are defined over the annotations
+ * every applicable schema produced — the `anyOf` branches included — so the
+ * outer node is exactly where they belong; moving one inside would narrow it to
+ * the branch's own keywords. Anything else the node carries (`$defs`, `$id`, an
+ * unknown keyword) stays outside too, keeping the treatment it has today.
+ */
+const NULLABLE_BRANCH_KEYS = new Set([
+    "minLength",
+    "maxLength",
+    "pattern",
+    "format",
+    "enum",
+    "const",
+    "minimum",
+    "maximum",
+    "exclusiveMinimum",
+    "exclusiveMaximum",
+    "multipleOf",
+    "items",
+    "prefixItems",
+    "minItems",
+    "maxItems",
+    "uniqueItems",
+    "properties",
+    "patternProperties",
+    "required",
+    "additionalProperties",
+    "propertyNames",
+    "minProperties",
+    "maxProperties",
+    "dependencies",
+    "dependentRequired",
+    "dependentSchemas",
+    "contentMediaType",
+    "contentEncoding",
+]);
 /**
  * Ceiling on how many property subschemas transform #8 may copy down across ALL
  * branches of one root composition.
@@ -786,20 +928,154 @@ function sanitizeCompositionBranch(branch, depth, parentProperties, budget) {
     // Arrays and boolean/primitive schemas carry no `required` to resolve.
     if (!isPlainObject(branch))
         return sanitizeSubschema(branch, depth);
-    const sanitized = sanitizeSchemaNode(branch, depth, parentProperties);
     // A non-null budget marks a ROOT composition — the only place the
-    // self-sufficiency repair applies (see the module header).
+    // self-sufficiency repair applies, and the only place transform #1's nullable
+    // rewrite stands down (see the module header).
+    const sanitized = sanitizeSchemaNode(branch, depth, parentProperties, budget !== null);
     return budget
         ? makeBranchSelfSufficient(sanitized, parentProperties, budget)
         : sanitized;
 }
+/**
+ * Transform #1, nullable case: decide whether this node is a nullable single
+ * type — `["string","null"]` and friends — that should be REWRITTEN to an
+ * `anyOf` union instead of collapsed. Returns the non-null type name, or `null`
+ * when the node keeps today's collapse.
+ *
+ * Order of the members does not matter and duplicates are tolerated
+ * (`["null","string"]`, `["string","null","null"]`); what must hold is that
+ * exactly one distinct non-`"null"` type is present, alongside at least one
+ * `"null"`.
+ *
+ * Four shapes opt out, each for a measured or structural reason:
+ *   - The ROOT and a branch of a ROOT composition (`isRootCompositionBranch`).
+ *     The root must be an object for every provider, and a root union branch
+ *     carrying its OWN `anyOf` is 0/3 on Grok — so rewriting there would turn a
+ *     usable branch into one transform #9 rule (a) drops, taking the whole
+ *     keyword (and with it every shape the union advertised) with it.
+ *   - A sibling `enum`/`const` that excludes one of the two arms. These are
+ *     AND-ed with `type`, so `{type:["string","null"], enum:["x"]}` means "must
+ *     be \"x\"" and `{…, enum:[null]}` means "must be null". The rewrite moves
+ *     the keyword onto the TYPED branch, leaving `{type:"null"}` unconstrained
+ *     by it — so emitting the union would admit a value the node forbade. Both
+ *     directions keep the collapse; `const: null` is the exception that still
+ *     rewrites, because there the typed branch is unsatisfiable and the union
+ *     reduces to "must be null", which is what the node says (collapsing it
+ *     would give the unsatisfiable `{type:"string", const:null}` instead).
+ *   - A COMPOSITION BRANCH whose `required` reaches the ENCLOSING node's
+ *     `properties` — the extra scope transform #8 gives it. Moving such a name
+ *     inside a nested `anyOf` puts it two levels from that scope, which is
+ *     exactly the dangling `required` transform #3 exists to prevent on Gemini.
+ *     A branch whose `required` is covered by its OWN `properties` needs no
+ *     exception and is rewritten normally.
+ */
+function nullableUnionType(node, parentProperties, isRootCompositionBranch) {
+    if (isRootCompositionBranch)
+        return null;
+    const declared = node.type;
+    if (!Array.isArray(declared))
+        return null;
+    let typed = null;
+    let sawNull = false;
+    for (const member of declared) {
+        if (typeof member !== "string")
+            return null;
+        if (member === "null") {
+            sawNull = true;
+            continue;
+        }
+        if (!NULLABLE_UNION_TYPES.has(member))
+            return null;
+        if (typed !== null && typed !== member)
+            return null;
+        typed = member;
+    }
+    if (!sawNull || typed === null)
+        return null;
+    if (NULLABLE_REWRITE_BLOCKERS.some((key) => hasOwn(node, key)))
+        return null;
+    // A sibling `enum`/`const` is AND-ed with `type`, so it decides whether the
+    // two arms the `type` array advertises are BOTH actually reachable — and the
+    // rewrite may only emit an arm the input really allows. Moving the keyword
+    // onto the typed branch leaves the `{type:"null"}` branch unconstrained by
+    // it, so emitting that branch when the enum excludes `null` would admit a
+    // value the author forbade (`{type:["string","null"], enum:["x"]}` means
+    // "must be \"x\""), and emitting the typed branch when only `null` is allowed
+    // would admit every string. Either way the union would say more than the node
+    // did, so both keep the collapse.
+    //
+    // `const: null` is the one shape that still rewrites: the typed branch is
+    // then unsatisfiable and the union reduces to "must be null", exactly what
+    // the node means — where collapsing it would produce the unsatisfiable
+    // `{type:"string", const:null}` instead, which is strictly worse.
+    if (hasOwn(node, "const") && node.const !== null)
+        return null;
+    if (hasOwn(node, "enum")) {
+        if (!Array.isArray(node.enum))
+            return null;
+        const permitsNull = node.enum.some((member) => member === null);
+        const permitsNonNull = node.enum.some((member) => member !== null);
+        if (!permitsNull || !permitsNonNull)
+            return null;
+    }
+    // Only a `required` name that actually REACHES the parent scope forces the
+    // collapse. A branch whose `required` is satisfied by its own `properties`
+    // loses nothing by being rewritten, and declining there would keep the
+    // invented-value failure for a node that has no need of the exception. Key
+    // names survive sanitization unchanged, so the raw map answers this.
+    if (parentProperties != null && Array.isArray(node.required)) {
+        const own = isPlainObject(node.properties) ? node.properties : null;
+        const reachesParentScope = node.required.some((name) => typeof name === "string" && !(own !== null && hasOwn(own, name)));
+        if (reachesParentScope)
+            return null;
+    }
+    return typed;
+}
+/**
+ * Build the typed branch of a nullable rewrite: the node's own type-bearing
+ * keywords (`NULLABLE_BRANCH_KEYS`) under a scalar `type`, with `null` removed
+ * from an `enum` because the sibling `{type:"null"}` branch already carries
+ * that fact — and leaving it would make transform #2 emit a "May also be null."
+ * note the schema no longer needs.
+ *
+ * The branch is run back through `sanitizeSchemaNode` rather than assembled by
+ * hand so every per-node transform applies to it exactly as it would to any
+ * scalar-typed node: transform #12 retypes it to `"object"` when it carries
+ * `properties`, transform #13 drops an unsupported `pattern` into prose on the
+ * branch, transform #3 resolves its `required` against its own `properties`,
+ * and transform #2 filters its `enum`.
+ *
+ * Sanitized at THIS node's depth, not one deeper. The branch is a
+ * re-expression of the node, so its children sit exactly where they sat before
+ * the rewrite, and the depth budget they are charged is unchanged. No
+ * `parentProperties` is passed: the only branch that could have used one — a
+ * composition branch carrying `required` — is excluded by `nullableUnionType`.
+ */
+function buildNullableBranch(node, typeName, depth) {
+    const branch = { type: typeName };
+    for (const [key, value] of Object.entries(node)) {
+        if (!NULLABLE_BRANCH_KEYS.has(key))
+            continue;
+        if (key === "enum" && Array.isArray(value)) {
+            branch.enum = value.filter((member) => member !== null);
+            continue;
+        }
+        safeSet(branch, key, value);
+    }
+    return sanitizeSchemaNode(branch, depth);
+}
 /**
  * @param parentProperties When this node is a composition branch, the enclosing
  *   node's SANITIZED `properties` map — the extra scope its `required` may name
  *   (transform #8). `undefined`/`null` for every other node, which keeps
  *   transform #3's own-properties-only rule exactly as it was.
+ * @param isRootCompositionBranch True when this node is an element of a
+ *   composition on the parameters ROOT. Only transform #1's nullable rewrite
+ *   reads it, and only to decline: such a branch is judged individually by
+ *   transform #9 rule (a), which rejects any branch carrying its own
+ *   `anyOf`/`oneOf`.
  */
-function sanitizeSchemaNode(node, depth, parentProperties) {
+function sanitizeSchemaNode(node, depth, parentProperties, isRootCompositionBranch = false) {
     // Depth guard: stop walking absurdly nested input rather than overflowing
     // the stack. Real tool schemas are a few levels deep; anything past
     // MAX_DEPTH is adversarial, so the subtree is replaced with the
@@ -809,10 +1085,27 @@ function sanitizeSchemaNode(node, depth, parentProperties) {
     if (depth > MAX_DEPTH)
         return {};
     const childDepth = depth + 1;
+    // Transform #1, nullable case. A NON-root `{type:["T","null"], …}` is emitted
+    // as `anyOf: [<T branch>, {type:"null"}]` rather than collapsed to `T` with a
+    // prose note, because prose loses to the schema: a model reading
+    // `{type:"string", minLength:1}` cannot express "none" in the half of the
+    // declaration it treats as binding, so it invents a value that satisfies the
+    // type instead (see the module header). Decided first because everything
+    // below — the `properties` pre-pass, the type resolution, the enum rule, the
+    // notes — belongs to the BRANCH when the rewrite fires, not to the node that
+    // now carries only the union and its annotations.
+    const nullableType = depth > 0
+        ? nullableUnionType(node, parentProperties, isRootCompositionBranch)
+        : null;
+    const nullableBranch = nullableType === null
+        ? null
+        : buildNullableBranch(node, nullableType, depth);
     // Sanitized `properties`, computed ahead of the key walk because transform #8
     // needs it before the walk reaches whichever of `properties` / `oneOf` comes
     // first in key order. Emitted verbatim when the walk reaches `properties`.
-    const sanitizedProperties = hasOwn(node, "properties")
+    // Skipped entirely under a nullable rewrite, where `properties` has moved
+    // onto the typed branch and was sanitized there.
+    const sanitizedProperties = nullableType === null && hasOwn(node, "properties")
         ? sanitizePropertiesKeyword(node.properties, childDepth)
         : undefined;
     const ownProperties = isPlainObject(sanitizedProperties)
@@ -836,16 +1129,25 @@ function sanitizeSchemaNode(node, depth, parentProperties) {
     const declaresProperty = (name) => (ownProperties !== null && hasOwn(ownProperties, name)) ||
         (parentProperties != null && hasOwn(parentProperties, name));
     // Resolve the node's effective single `type`, collapsing a JSON Schema
-    // `type` ARRAY (a union, e.g. `["string","number","boolean"]` or a nullable
-    // `["string","null"]`) to the first non-"null" member. Gemini's
-    // function-declaration schema requires a single `type` and hard-rejects a
-    // type array, which manifests as a misleading downstream error. Computed up
-    // front (not in key order) because the `enum` decision below depends on it.
+    // `type` ARRAY (a MULTI-type union, e.g. `["string","number","boolean"]`) to
+    // the first non-"null" member. Gemini's function-declaration schema requires
+    // a single `type` and hard-rejects a type array, which manifests as a
+    // misleading downstream error. Computed up front (not in key order) because
+    // the `enum` decision below depends on it. The nullable case
+    // (`["string","null"]`) took the `anyOf` rewrite above and never gets here —
+    // except at the root and the two branch positions that decline it, which
+    // collapse like any other union.
     const notesFromRetype = [];
     let typeToEmit = node.type;
     let emitType = "type" in node;
     let singleType;
-    if (Array.isArray(node.type)) {
+    if (nullableType !== null) {
+        // The `type` key's slot is taken by the `anyOf` emitted in the walk below,
+        // so nothing resolves a scalar type here and no note is manufactured: the
+        // union states the nullability the note used to approximate.
+        emitType = false;
+    }
+    else if (Array.isArray(node.type)) {
         const nonNull = node.type.filter((t) => t !== "null");
         if (nonNull.length > 0) {
             typeToEmit = nonNull[0];
@@ -894,7 +1196,7 @@ function sanitizeSchemaNode(node, depth, parentProperties) {
     // 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 = [...notesFromRetype];
-    if (Array.isArray(node.type)) {
+    if (nullableType === null && Array.isArray(node.type)) {
         const typeNames = node.type.filter((t) => typeof t === "string");
         if (typeNames.length > 1) {
             notes.push(`Accepts ${humanJoin(typeNames)}.`);
@@ -904,7 +1206,7 @@ function sanitizeSchemaNode(node, depth, parentProperties) {
             notes.push("Must be null.");
         }
     }
-    if (Array.isArray(node.enum)) {
+    if (nullableType === null && Array.isArray(node.enum)) {
         const stringMembers = node.enum.filter((v) => typeof v === "string");
         if (dropEnum || stringMembers.length === 0) {
             // The whole enum is dropped (non-string type, or no string members
@@ -920,7 +1222,8 @@ function sanitizeSchemaNode(node, depth, parentProperties) {
     }
     // 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" &&
+    const dropPattern = nullableType === null &&
+        typeof node.pattern === "string" &&
         usesUnsupportedRegexConstruct(node.pattern);
     if (dropPattern) {
         const pattern = node.pattern;
@@ -940,7 +1243,19 @@ function sanitizeSchemaNode(node, depth, parentProperties) {
         // by those names are handled safely inside `sanitizeSchemaMap`.)
         if (PROTO_KEYS.has(key))
             continue;
+        // Transform #1, nullable case: every type-bearing keyword has moved onto
+        // the typed branch, which was sanitized as a node in its own right. Only
+        // the node's annotations (and any keyword outside both sets) stay here.
+        if (nullableType !== null && NULLABLE_BRANCH_KEYS.has(key))
+            continue;
         if (key === "type") {
+            if (nullableBranch !== null) {
+                // Emitted in the `type` key's own position so key order stays
+                // deterministic — which is what lets a second pass, finding an `anyOf`
+                // it leaves alone, reproduce this object exactly.
+                out.anyOf = [nullableBranch, { type: "null" }];
+                continue;
+            }
             if (emitType)
                 out.type = typeToEmit;
             continue;