@aeye/core 0.5.2 → 0.5.3

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,9 @@ 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, and NO `maxEnumValues` — a large
+    // `enum` was suspected of causing `400 INVALID_ARGUMENT` here and did not
+    // survive measurement. See `FormatDescriptor.maxEnumValues` for the numbers.
     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
@@ -238,7 +280,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 +318,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 +1228,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 +1478,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 +1718,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 +2058,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 +2082,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 +2109,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 +2211,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 +2291,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 +2330,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 +2363,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 +2408,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 +2428,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.