@aeye/core 0.5.2 → 0.5.4

package/dist/schema.js

@@ -46,10 +46,28 @@ export const LENIENT = Object.freeze({
  * tuples→numeric-keys, optional→nullable.
  *
  * No documented per-request slot limit (max strict tools / optional params /
- * union types). The SchemaBudget treats those caps as `undefined` (no limit)
- * for OpenAI; OpenAI's own ~5000-property and ~5-level-depth schema caps
- * aren't enforced here either — they're rare in practice and produce a
- * server-side rejection that the user can react to.
+ * union types) — the SchemaBudget treats those caps as `undefined` for OpenAI.
+ *
+ * OpenAI DOES document per-SCHEMA size limits for Structured Outputs, and they
+ * are declared below (`schemaSizeLimits`). Verified against
+ * developers.openai.com/api/docs/guides/structured-outputs on 2026-08-23,
+ * section "Supported schemas": *"A schema may have up to 5000 object
+ * properties total, with up to 10 levels of nesting"*, *"total string length of
+ * all property names, definition names, enum values, and const values cannot
+ * exceed 120,000 characters"*, *"A schema may have up to 1000 enum values
+ * across all enum properties"*, and *"For a single enum property with string
+ * values, the total string length of all enum values cannot exceed 15,000
+ * characters when there are more than 250 enum values"*. Every one of those
+ * numbers was raised in July 2025 (100→5000 properties, 15,000→120,000
+ * characters, 500→1000 enum values, 7,500→15,000 for the >250-value enum) —
+ * the pre-raise figures are still widely quoted secondhand, so they are named
+ * here to keep a future reader from "correcting" these downward.
+ *
+ * Scope is Structured Outputs, i.e. a tool carrying `strict: true` or a
+ * `json_schema` response format — the function-calling guide defines strict
+ * mode as "leveraging our structured outputs feature", and non-strict function
+ * calling is best-effort with no compiled decoder. That is exactly why
+ * degrading the over-size item to `OPENAI_NON_STRICT` is a complete answer.
  */
 export const OPENAI_STRICT = Object.freeze({
     id: 'openai-strict',
@@ -74,6 +92,17 @@ export const OPENAI_STRICT = Object.freeze({
     optionalAsNullable: true,
     anyEncoding: 'recursive-strict',
     supportsRecursion: true,
+    // Every number is quoted from OpenAI's own "Supported schemas" section — see
+    // the descriptor doc above for the exact sentences and the date they were
+    // read. Frozen because `Object.freeze` on the descriptor is shallow.
+    schemaSizeLimits: Object.freeze({
+        maxObjectProperties: 5000,
+        maxNestingDepth: 10,
+        maxTotalStringChars: 120_000,
+        maxTotalEnumValues: 1000,
+        largeEnumValueCount: 250,
+        maxLargeEnumStringChars: 15_000,
+    }),
 });
 /** OpenAI non-strict — alias of LENIENT but tagged with the openai family. */
 export const OPENAI_NON_STRICT = Object.freeze({
@@ -163,10 +192,21 @@ export const ANTHROPIC_NON_STRICT = Object.freeze({
  *   this descriptor used to declare was a schema it says it cannot emit.
  *   Gemini compiles the tool schemas into a decoding grammar whenever the
  *   caller forces a tool call (`toolChoice: 'required'` → Google's function
- *   calling mode `ANY`), and a self-referencing `$defs/Any` fails that
- *   compile with `400 INVALID_ARGUMENT` — the same request succeeds under
+ *   calling mode `ANY`), and a self-referencing `$defs/Any` failed that
+ *   compile with `400 INVALID_ARGUMENT` — the same request succeeded under
  *   `toolChoice: 'auto'`, where no grammar is built. Reported against
- *   `google/gemini-3-flash-preview` via OpenRouter, 100% reproducible.
+ *   `google/gemini-3-flash-preview` via OpenRouter as 100% reproducible.
+ *
+ *   **That 400 no longer reproduces (re-measured 2026-08-23)** and the
+ *   encoding stays anyway. Same model, same route, upstream pinned to Google
+ *   AI Studio with fallbacks off, `tool_choice` forced to one named tool: the
+ *   hand-built recursive `$defs/Any` tool, and the product's real 32 KB gin
+ *   `api_set` schema carrying nine `#/$defs/Any` references, both answered
+ *   HTTP 200 with a valid tool call. So the upstream either fixed or now
+ *   sanitizes it. The descriptor still declares what this dialect's own
+ *   documented keyword list supports; depending on a provider's current
+ *   leniency for a shape we say it cannot express is how the first version of
+ *   this descriptor shipped a guaranteed 400 in the first place.
  */
 export const GOOGLE_STRICT = Object.freeze({
     id: 'google-strict',
@@ -192,7 +232,11 @@ export const GOOGLE_STRICT = Object.freeze({
     // The ONLY encoding expressible under `allowAnyOf: false` +
     // `allowDefsRef: false` — see the descriptor doc above.
     anyEncoding: 'unconstrained',
-    // No documented per-request slot limits.
+    // No documented per-request slot limits. `maxEnumValues: 40` IS a measured
+    // response to a real `400 INVALID_ARGUMENT` on this exact product's live
+    // fn-catalog enum — see `FormatDescriptor.maxEnumValues` for the numbers,
+    // the bisection, and why 40 is conservative rather than the measured edge.
+    maxEnumValues: 40,
     supportsRecursion: true,
     // Gemini's structured-output endpoint rejects `anyOf`/`$defs` schemas
     // (HTTP 400). When a schema can't be expressed here it's delivered as
@@ -220,6 +264,10 @@ export const GOOGLE_NON_STRICT = Object.freeze({
     id: 'google-non-strict',
     family: 'google',
     anyEncoding: 'unconstrained',
+    // Same measured enum-cardinality limit as GOOGLE_STRICT — it fires whatever
+    // the strictness (see FormatDescriptor.maxEnumValues), so a tool degraded
+    // to this descriptor still needs it.
+    maxEnumValues: 40,
     jsonFallbackInstruction: 'Return ONLY a single raw JSON object that conforms to the schema above. Do NOT wrap it in markdown code fences, do NOT add any prose before or after it, and do NOT echo the schema itself — emit only the JSON instance.',
 });
 // ============================================================================
@@ -238,7 +286,8 @@ const ANY_ENCODING_REQUIREMENTS = Object.freeze({
 });
 /**
  * Report the ways a `FormatDescriptor` contradicts itself — settings that ask
- * the emitter to produce a keyword the same descriptor forbids. Returns one
+ * the emitter to produce a keyword the same descriptor forbids, or a limit
+ * that would quietly strip every constraint it governs. Returns one
  * human-readable line per problem; an empty array means the descriptor is
  * internally consistent.
  *
@@ -275,6 +324,58 @@ export function checkDescriptorConsistency(descriptor) {
     if (needs.defsRef && !descriptor.supportsRecursion) {
         problems.push(`anyEncoding '${descriptor.anyEncoding}' emits a self-referencing \`$defs/Any\`, but supportsRecursion is false`);
     }
+    // `maxEnumValues` is an independent scalar — there is no other field it can
+    // contradict — but a cap below 1 widens EVERY enum the dialect ever emits
+    // (including a two-member one), and a fractional cap reads as a threshold
+    // nobody intended. Both are silent: the schema stays valid, it just stops
+    // constraining anything, which is the "invisible until you read the wire"
+    // class this function exists to catch. Only reachable through
+    // `registerDescriptor`; the built-ins are asserted clean by the test suite.
+    const cap = descriptor.maxEnumValues;
+    if (cap !== undefined && (!Number.isInteger(cap) || cap < 1)) {
+        problems.push(`maxEnumValues must be a positive integer, got ${cap}`);
+    }
+    problems.push(...schemaSizeLimitProblems(descriptor));
+    return problems;
+}
+/**
+ * The ways a `schemaSizeLimits` group contradicts itself or the descriptor
+ * carrying it. Split out only to keep `checkDescriptorConsistency` readable;
+ * it is part of the same contract.
+ *
+ * The failures below are all SILENT: a non-positive bound degrades every
+ * schema to lenient (strict mode simply stops happening, with no error
+ * anywhere), a threshold above the total makes the large-enum rule
+ * unreachable, and limits on a non-strict descriptor describe a rule the API
+ * does not apply — each one is a rule that reads as enforced and is not.
+ */
+function schemaSizeLimitProblems(descriptor) {
+    const limits = descriptor.schemaSizeLimits;
+    if (limits === undefined)
+        return [];
+    const problems = [];
+    if (!descriptor.strict) {
+        problems.push('schemaSizeLimits is declared on a non-strict descriptor, but the size rules bound Structured Outputs only');
+    }
+    // Keyed off the interface, so a bound added to `SchemaSizeLimits` is checked
+    // here without an edit — `satisfies` makes a missed key a compile error.
+    const bounds = {
+        maxObjectProperties: limits.maxObjectProperties,
+        maxNestingDepth: limits.maxNestingDepth,
+        maxTotalStringChars: limits.maxTotalStringChars,
+        maxTotalEnumValues: limits.maxTotalEnumValues,
+        largeEnumValueCount: limits.largeEnumValueCount,
+        maxLargeEnumStringChars: limits.maxLargeEnumStringChars,
+    };
+    for (const [name, value] of Object.entries(bounds)) {
+        if (!Number.isInteger(value) || value < 1) {
+            problems.push(`schemaSizeLimits.${name} must be a positive integer, got ${value}`);
+        }
+    }
+    if (limits.largeEnumValueCount >= limits.maxTotalEnumValues) {
+        problems.push(`schemaSizeLimits.largeEnumValueCount (${limits.largeEnumValueCount}) is not below maxTotalEnumValues ` +
+            `(${limits.maxTotalEnumValues}), so the large-enum character rule can never apply`);
+    }
     return problems;
 }
 // ============================================================================
@@ -1133,7 +1234,17 @@ function convert(schema, context) {
     finally {
         context.inProgress.delete(id);
     }
+    // A description the CONVERTER produced describes the EMITTED node, not the
+    // source schema — today that is only the `maxEnumValues` widening, whose
+    // description IS the value list that replaced the `enum` keyword. The source's
+    // own `.describe()` must not silently replace it, or a model handed a widened
+    // `{type:'string'}` is told nothing about which strings are legal. Keep both,
+    // converter note last.
+    const emittedNote = result.description;
     Object.assign(result, metadata);
+    if (emittedNote !== undefined && metadata.description !== undefined && metadata.description !== emittedNote) {
+        result.description = `${metadata.description} ${emittedNote}`;
+    }
     delete result.aid;
     // Promote it because user requested it or it's recursive
     if (save || context.definitionSchemas.has(id)) {
@@ -1373,6 +1484,61 @@ function uniqueByJSON(nodes) {
     }
     return out;
 }
+/**
+ * The values a `z.enum` actually EMITS as JSON-Schema `enum` members.
+ *
+ * A numeric TypeScript enum compiles to a two-way map (`{A: 0, 0: 'A'}`), so
+ * the reverse-mapping keys have to be dropped or every value appears twice.
+ * Shared with `analyzeSchema` deliberately: the size budget counts what goes on
+ * the wire, and "what goes on the wire" must have ONE definition (a second
+ * copy of this filter would drift from the emitter it is supposed to measure).
+ */
+function enumEmittedValues(schema) {
+    const numericValues = Object.values(schema.def.entries).filter((v) => typeof v === 'number');
+    return Object.entries(schema.def.entries)
+        .filter(([k]) => numericValues.indexOf(+k) === -1)
+        .map(([, v]) => v);
+}
+/**
+ * The values a `z.literal` emits — one for the `const` form, several for the
+ * multi-value form that emits `enum`. Types JSON Schema cannot carry
+ * (functions, symbols, bigints, `undefined`) are dropped, matching the
+ * emitter. Shared with `analyzeSchema` for the same reason as above.
+ */
+function literalEmittedValues(schema) {
+    return Array.from(schema.values).filter((v) => v !== undefined && typeof v !== 'function' && typeof v !== 'symbol' && typeof v !== 'bigint');
+}
+/**
+ * Decide whether a set of values may be emitted as a JSON-Schema `enum` under
+ * this descriptor, per `maxEnumValues`.
+ *
+ * Under the cap (or with no cap declared) the caller emits its `enum` as
+ * normal. Over it, the caller emits NO `enum` — just the widened `type` — and
+ * attaches `note`, which lists EVERY value in prose.
+ *
+ * Widening rather than truncating is the deliberate choice, and the two differ
+ * in what the model can still say. A truncated `enum` makes the values past the
+ * cap **unreachable**: the wire schema constrains them away, so a caller whose
+ * 96 values are all legitimately selectable loses 56 of them. Widening removes
+ * the wire-level constraint that the dialect can't compile in the first place
+ * and moves the full list into the `description`, so the model retains complete
+ * information and can name any of the 96. Nothing is hidden — it is described
+ * instead of enforced, and enforcement moves to whatever validates the value
+ * afterwards (`Tool.parse` against the ORIGINAL zod schema still rejects a name
+ * that was never in the enum, with a message the model can act on).
+ *
+ * The note is deliberately DOMAIN-NEUTRAL. This library has no idea what the
+ * values mean; whichever caller relies on the cap (a session's known-name enum,
+ * a country list, anything) reads its own semantics into them.
+ */
+function describeOversizeEnum(values, descriptor) {
+    const cap = descriptor.maxEnumValues;
+    if (cap === undefined || values.length <= cap)
+        return undefined;
+    // A flat comma-separated list: it is how an enum reads in prose anyway, and
+    // the values are single tokens by construction (they were `enum` members).
+    return `One of these ${values.length} values: ${values.map((v) => String(v)).join(', ')}`;
+}
 /**
  * Main conversion function
  */
@@ -1558,26 +1724,33 @@ function convertSchema(schema, context) {
     }
     // Handle ZodEnum
     if (schema instanceof z.ZodEnum) {
-        const numericValues = Object.values(schema.def.entries).filter((v) => typeof v === "number");
-        const values = Object.entries(schema.def.entries)
-            .filter(([k, _]) => numericValues.indexOf(+k) === -1)
-            .map(([_, v]) => v);
+        const values = enumEmittedValues(schema);
+        // Over the dialect's cap the `enum` keyword is DROPPED and the node widens
+        // to its plain scalar type, with every value listed in the description —
+        // see `describeOversizeEnum` for why widening beats truncating.
+        const oversize = describeOversizeEnum(values, descriptor);
         return {
             type: values.every((v) => typeof v === 'number')
                 ? 'number'
                 : values.every((v) => typeof v === 'string')
                     ? 'string'
                     : undefined,
-            enum: values,
+            ...(oversize === undefined ? { enum: values } : { description: oversize }),
         };
     }
     // Handle ZodLiteral
     if (schema instanceof z.ZodLiteral) {
-        const values = Array.from(schema.values).filter(v => v !== undefined && typeof v !== 'function' && typeof v !== 'symbol' && typeof v !== 'bigint');
+        const values = literalEmittedValues(schema);
         const types = Array.from(new Set(values.map(v => v === null ? 'null' : typeof v)));
+        // A multi-value literal emits the SAME `enum` keyword as ZodEnum, so the
+        // dialect cap applies identically — the provider sees no difference. The
+        // single-value form emits `const`, which no cap can be exceeded by.
+        const oversize = values.length === 1 ? undefined : describeOversizeEnum(values, descriptor);
         return {
             ...(types.length === 1 ? { type: types[0] } : {}),
-            ...(values.length === 1 ? { const: values[0] } : { enum: values }),
+            ...(values.length === 1
+                ? { const: values[0] }
+                : oversize === undefined ? { enum: values } : { description: oversize }),
         };
     }
     // Handle ZodDefault
@@ -1891,6 +2064,10 @@ const ZERO_FEATURES = Object.freeze({
     unionTypeCount: 0,
     recordCount: 0,
     tupleCount: 0,
+    enums: Object.freeze([]),
+    objectPropertyCount: 0,
+    maxNestingDepth: 0,
+    stringSizeChars: 0,
 });
 const featuresCache = new WeakMap();
 /**
@@ -1911,7 +2088,21 @@ export function analyzeSchema(schema) {
         return cached;
     const visiting = new Set();
     const features = { ...ZERO_FEATURES };
-    function walk(s) {
+    // Collected mutably and frozen onto `features` at the end — `ZERO_FEATURES`
+    // is a frozen singleton, so spreading it must not hand out its array.
+    const enums = [];
+    /** Total characters of the string members of an emitted enum/const value set. */
+    const stringChars = (values) => values.reduce((n, v) => n + (typeof v === 'string' ? v.length : 0), 0);
+    /** Record the deepest container nesting reached. `depth` is the level of `s` itself. */
+    const noteDepth = (depth) => {
+        if (depth > features.maxNestingDepth)
+            features.maxNestingDepth = depth;
+    };
+    // `depth` counts CONTAINERS entered (an object of scalars is depth 1). Wrapper
+    // nodes — optional, nullable, default, lazy, union arms — are transparent on
+    // the wire and pass their own depth through, so `{a?: {b: string}}` is 2, the
+    // same as `{a: {b: string}}`.
+    function walk(s, depth) {
         if (!s)
             return;
         const key = walkKey(s);
@@ -1924,65 +2115,100 @@ export function analyzeSchema(schema) {
             if (s instanceof z.ZodLazy) {
                 features.hasRecursion = true;
                 try {
-                    walk(s.def.getter());
+                    walk(s.def.getter(), depth);
                 }
                 catch { /* lazy getter may throw at analyze time; ignore */ }
                 return;
             }
             if (s instanceof z.ZodOptional) {
                 features.optionalParameterCount += 1;
-                walk(s.unwrap());
+                walk(s.unwrap(), depth);
                 return;
             }
             if (s instanceof z.ZodNullable) {
                 features.unionTypeCount += 1; // T|null counts as a union on the wire
-                walk(s.unwrap());
+                walk(s.unwrap(), depth);
                 return;
             }
             if (s instanceof z.ZodUnion || s instanceof z.ZodDiscriminatedUnion) {
                 features.unionTypeCount += 1;
                 for (const opt of s.options)
-                    walk(opt);
+                    walk(opt, depth);
                 return;
             }
             if (s instanceof z.ZodIntersection) {
-                walk(s.def.left);
-                walk(s.def.right);
+                walk(s.def.left, depth);
+                walk(s.def.right, depth);
                 return;
             }
             if (s instanceof z.ZodObject) {
-                for (const key in s.shape)
-                    walk(s.shape[key]);
+                noteDepth(depth + 1);
+                for (const key in s.shape) {
+                    features.objectPropertyCount += 1;
+                    features.stringSizeChars += key.length;
+                    walk(s.shape[key], depth + 1);
+                }
                 if (s.def.catchall)
-                    walk(s.def.catchall);
+                    walk(s.def.catchall, depth + 1);
                 return;
             }
             if (s instanceof z.ZodArray) {
-                walk(s.element);
+                noteDepth(depth + 1);
+                walk(s.element, depth + 1);
                 return;
             }
             if (s instanceof z.ZodRecord) {
                 features.recordCount += 1;
+                // Widest encoding wins (see `SchemaFeatures.objectPropertyCount`): the
+                // array-of-pairs form is an array of `{key, value}` objects, so two
+                // properties, two property names, and two levels of container.
+                features.objectPropertyCount += 2;
+                features.stringSizeChars += 'key'.length + 'value'.length;
+                noteDepth(depth + 2);
                 if (s.keyType)
-                    walk(s.keyType);
-                walk(s.valueType);
+                    walk(s.keyType, depth + 2);
+                walk(s.valueType, depth + 2);
                 return;
             }
             if (s instanceof z.ZodTuple) {
                 features.tupleCount += 1;
+                // The numeric-key object encoding emits one property per item, named
+                // "0", "1", … — one character each until there are ten of them, which
+                // is close enough for a 120,000-character budget.
+                features.objectPropertyCount += s.def.items.length;
+                features.stringSizeChars += s.def.items.length;
+                noteDepth(depth + 1);
                 for (const item of s.def.items)
-                    walk(item);
+                    walk(item, depth + 1);
                 if (s.def.rest)
-                    walk(s.def.rest);
+                    walk(s.def.rest, depth + 1);
                 return;
             }
             if (s instanceof z.ZodDefault) {
-                walk(s.def.innerType);
+                walk(s.def.innerType, depth);
                 return;
             }
             if (s instanceof z.ZodCodec || s instanceof z.ZodPipe) {
-                walk(s.def.in);
-                walk(s.def.out);
+                walk(s.def.in, depth);
+                walk(s.def.out, depth);
+                return;
+            }
+            if (s instanceof z.ZodEnum) {
+                const values = enumEmittedValues(s);
+                const chars = stringChars(values);
+                enums.push({ valueCount: values.length, stringValueChars: chars });
+                features.stringSizeChars += chars;
+                return;
+            }
+            if (s instanceof z.ZodLiteral) {
+                const values = literalEmittedValues(s);
+                const chars = stringChars(values);
+                // One value emits `const`, several emit `enum` — only the latter is an
+                // enum for the purpose of a dialect's enum-value budget, but both count
+                // toward the total string size.
+                if (values.length > 1)
+                    enums.push({ valueCount: values.length, stringValueChars: chars });
+                features.stringSizeChars += chars;
                 return;
             }
             // Primitives and unknown leaves contribute nothing.
@@ -1991,19 +2217,73 @@ export function analyzeSchema(schema) {
             visiting.delete(key);
         }
     }
-    walk(schema);
+    walk(schema, 0);
+    features.enums = Object.freeze(enums);
     Object.freeze(features);
     featuresCache.set(schema, features);
     return features;
 }
+/** Shared empty result, so the common "dialect publishes no size limits" path allocates nothing. */
+const NO_SIZE_PROBLEMS = Object.freeze([]);
+/**
+ * Report the ways ONE schema exceeds the descriptor's documented per-schema
+ * size limits (`FormatDescriptor.schemaSizeLimits`). Empty means it fits, or
+ * that the dialect publishes no limits.
+ *
+ * This is a FEASIBILITY question, not a budget one: the numbers bound a single
+ * schema, so no other tool in the request can change the answer, and
+ * `SchemaBudget.allocate` therefore treats a hit exactly like an
+ * unrepresentable keyword — that item degrades to the family's non-strict
+ * descriptor and the rest of the request is untouched.
+ *
+ * Exported because "why did my tool silently stop being strict?" needs an
+ * answer a caller can print; each line names the bound and the measurement.
+ *
+ * @example
+ * ```ts
+ * checkSchemaSizeLimits(z.object({ pick: z.enum(tenThousandNames) }), OPENAI_STRICT);
+ * //  → ['enum values 10000 exceed maxTotalEnumValues 1000']
+ * ```
+ */
+export function checkSchemaSizeLimits(schema, descriptor) {
+    const limits = descriptor.schemaSizeLimits;
+    if (limits === undefined)
+        return NO_SIZE_PROBLEMS;
+    const features = analyzeSchema(schema);
+    const problems = [];
+    if (features.objectPropertyCount > limits.maxObjectProperties) {
+        problems.push(`object properties ${features.objectPropertyCount} exceed maxObjectProperties ${limits.maxObjectProperties}`);
+    }
+    if (features.maxNestingDepth > limits.maxNestingDepth) {
+        problems.push(`nesting depth ${features.maxNestingDepth} exceeds maxNestingDepth ${limits.maxNestingDepth}`);
+    }
+    if (features.stringSizeChars > limits.maxTotalStringChars) {
+        problems.push(`total string characters ${features.stringSizeChars} exceed maxTotalStringChars ${limits.maxTotalStringChars}`);
+    }
+    const totalEnumValues = features.enums.reduce((n, e) => n + e.valueCount, 0);
+    if (totalEnumValues > limits.maxTotalEnumValues) {
+        problems.push(`enum values ${totalEnumValues} exceed maxTotalEnumValues ${limits.maxTotalEnumValues}`);
+    }
+    // The large-enum character rule is per-enum and conditional on that SAME
+    // enum's value count, which is why the walk keeps the breakdown instead of
+    // two totals.
+    for (const e of features.enums) {
+        if (e.valueCount > limits.largeEnumValueCount && e.stringValueChars > limits.maxLargeEnumStringChars) {
+            problems.push(`an enum of ${e.valueCount} values (over largeEnumValueCount ${limits.largeEnumValueCount}) spends ` +
+                `${e.stringValueChars} characters, over maxLargeEnumStringChars ${limits.maxLargeEnumStringChars}`);
+        }
+    }
+    return problems;
+}
 /**
  * Per-request strict-mode allocator.
  *
  * Constructed once per outgoing request with the chosen model's strictest
  * descriptor. Tracks remaining slots (strict tools, optional parameters,
  * union types) against the descriptor's documented per-request limits and
- * decides per-tool / per-output whether to emit strict or fall back to
- * LENIENT.
+ * decides per-tool / per-output whether to emit strict or fall back to the
+ * SAME FAMILY's non-strict descriptor (`degraded` — never the family-blind
+ * `LENIENT`, which would undo dialect rules that outlive strict mode).
  *
  * Selection guarantees that any tool with `strict: true` (hard requirement)
  * has a model that supports the family — `allocate` therefore always grants
@@ -2017,11 +2297,37 @@ export function analyzeSchema(schema) {
  */
 export class SchemaBudget {
     descriptor;
+    /**
+     * What an item that does NOT get strict is emitted through: the descriptor's
+     * own family, non-strict.
+     *
+     * It is deliberately NOT the family-blind `LENIENT`. A dialect restriction
+     * can belong to the DIALECT rather than to strict mode — `GOOGLE_NON_STRICT`
+     * exists for exactly one such rule, the `unconstrained` encoding of
+     * `z.any()`, because Gemini builds a decoding grammar whenever a tool call is
+     * forced, with no per-tool strict flag involved. Degrading to `LENIENT` put
+     * the self-referencing `$defs/Any` that encoding was created to avoid back on
+     * the Google wire — and it did so for every gin/query-style recursive `anyOf`
+     * schema, i.e. the schemas that ALWAYS degrade, since `GOOGLE_STRICT` cannot
+     * express `anyOf` at all (measured: the product's real `api_set` tool schema
+     * allocates to `lenient` under `GOOGLE_STRICT`, and its emitted JSON carries
+     * nine `#/$defs/Any` references).
+     *
+     * For the other families this is behaviour-neutral by construction:
+     * `OPENAI_NON_STRICT` and `ANTHROPIC_NON_STRICT` are `LENIENT` with a family
+     * tag, and a family with no registered non-strict variant resolves to
+     * `LENIENT` (`getDescriptor`). Only the pinned `descriptor` id on the tool
+     * changes, which round-trips through `getDescriptorById`.
+     */
+    degraded;
     remainingTools;
     remainingOptionalParams;
     remainingUnionTypes;
     constructor(descriptor) {
         this.descriptor = descriptor;
+        // An already-non-strict budget degrades to itself: there is nothing looser
+        // in its family, and `LENIENT`'s own family has no other variant.
+        this.degraded = descriptor.strict ? getDescriptor(descriptor.family, false) : descriptor;
         this.remainingTools = descriptor.maxStrictTools ?? Infinity;
         this.remainingOptionalParams = descriptor.maxStrictOptionalParams ?? Infinity;
         this.remainingUnionTypes = descriptor.maxStrictUnionTypes ?? Infinity;
@@ -2030,12 +2336,15 @@ export class SchemaBudget {
      * Decide the effective descriptor for a tool's parameter schema given the
      * dev's strict request, the schema's features, and the remaining budget.
      *
-     * Returns `LENIENT` when:
+     * Returns the family's NON-STRICT descriptor (`LENIENT` for a family that
+     * registers none) when:
      * - `requested === false`
      * - the schema uses a feature the descriptor can't represent
+     * - the schema exceeds the dialect's per-schema size limits
+     *   (`checkSchemaSizeLimits`)
      * - the descriptor has slot limits and the budget is exhausted (only
      *   applies to `requested` being a positive number; `true` always wins
-     *   subject to feasibility)
+     *   subject to feasibility and size)
      *
      * Returns the strict descriptor (and decrements the budget) otherwise.
      */
@@ -2060,37 +2369,44 @@ export class SchemaBudget {
         };
     }
     allocate(schema, requested, isTool) {
-        // strict: false → always lenient, no budget movement.
+        // strict: false → always non-strict, no budget movement.
         if (requested === false)
-            return LENIENT;
+            return this.degraded;
         // Descriptor itself is lenient → nothing to allocate.
         if (!this.descriptor.strict)
-            return LENIENT;
+            return this.degraded;
         const isHardRequired = requested === true;
         const isPreferredNumeric = typeof requested === 'number' && requested > 0;
         if (!isHardRequired && !isPreferredNumeric) {
             // requested is undefined or 0 — treat as no preference; default to
-            // lenient so callers explicitly opt into strict. Decided BEFORE any walk
-            // of `schema`: analysing a schema whose verdict is already LENIENT is
-            // pure waste on the hot path of every tool of every request.
-            return LENIENT;
+            // non-strict so callers explicitly opt into strict. Decided BEFORE any
+            // walk of `schema`: analysing a schema whose verdict is already
+            // non-strict is pure waste on the hot path of every tool of every request.
+            return this.degraded;
         }
         // FEASIBILITY, before budget — the second clause of this method's contract,
         // and the one that was documented but never implemented. Emitting a strict
         // schema carrying a combinator the descriptor forbids is a guaranteed
         // provider 400, not a degradation: `GOOGLE_STRICT` forbids `anyOf`, and the
         // recursive union a gin/query codegen layer produces is nothing but.
-        // Degrading to LENIENT is the documented answer for a TOOL (unlike a
-        // structured OUTPUT, a tool schema has no prompt-text delivery to fall back
-        // to — `applySchemaDeliveryFallback` covers `responseFormat` only), and it
-        // is also what keeps the API-level `strict: true` flag off the wire, since
-        // providers set it from `descriptor.strict`.
+        // Degrading to the family's non-strict descriptor is the documented answer
+        // for a TOOL (unlike a structured OUTPUT, a tool schema has no prompt-text
+        // delivery to fall back to — `applySchemaDeliveryFallback` covers
+        // `responseFormat` only), and it is also what keeps the API-level
+        // `strict: true` flag off the wire, since providers set it from
+        // `descriptor.strict`.
         //
         // `sendableUnder`, not `canExpress`: a cycle is always sendable (the
         // emitter's bounded placeholder), only looser — see that function's note on
         // why the two questions are different.
         if (!sendableUnder(schema, this.descriptor))
-            return LENIENT;
+            return this.degraded;
+        // SIZE, still before budget and still regardless of priority: these bounds
+        // are per-SCHEMA (see `checkSchemaSizeLimits`), so no other item in the
+        // request can make this one fit, and a hard `strict: true` cannot force a
+        // schema the API will refuse to compile.
+        if (checkSchemaSizeLimits(schema, this.descriptor).length > 0)
+            return this.degraded;
         const features = analyzeSchema(schema);
         // Soft-priority items must fit the budget. Hard-required items skip
         // budget checks because selection already promised the model can take
@@ -2098,11 +2414,11 @@ export class SchemaBudget {
         // surface via API error rather than degrading silently.
         if (isPreferredNumeric) {
             if (isTool && this.remainingTools <= 0)
-                return LENIENT;
+                return this.degraded;
             if (this.remainingOptionalParams - features.optionalParameterCount < 0)
-                return LENIENT;
+                return this.degraded;
             if (this.remainingUnionTypes - features.unionTypeCount < 0)
-                return LENIENT;
+                return this.degraded;
         }
         // Allocation succeeded — decrement.
         if (isTool)
@@ -2118,6 +2434,13 @@ export class SchemaBudget {
  * shared between `convertTools` and `convertResponseFormat` — Anthropic's
  * documented limits apply across the whole request, so the strictest
  * descriptor wins.
+ *
+ * `schemaSizeLimits` deliberately does NOT participate. Those bounds are
+ * per-schema, so they are evaluated against whichever descriptor this returns
+ * rather than shared between the two — and every provider here passes two
+ * descriptors resolved from the SAME family, so there is nothing to break the
+ * tie on. Ranking six size bounds against three slot budgets would be an
+ * invented ordering, not a documented one.
  */
 export function strictestOf(a, b) {
     // LENIENT is the loosest — pick the strict side if either is strict.