@aeye/core 0.5.1 → 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;
 }
 // ============================================================================
@@ -404,6 +499,37 @@ export function resolveDescriptor(input) {
     const opts = input;
     return getDescriptor(opts.format ?? 'openai', opts.strict);
 }
+/**
+ * The key an EAGER walk's cycle guard must use for `s`.
+ *
+ * Object identity alone is a broken guard, because a `z.lazy` is only required
+ * to return *a* schema — not the *same* schema object — from its getter. A
+ * codegen layer that derives zod from a live type registry rebuilds the subtree
+ * on every call (`@aeye/gin`'s `buildSchemas` does), so each re-entry into a
+ * recursive node is a FRESH object: an identity guard never fires, the walk
+ * descends forever, and because every level allocates a whole new subtree
+ * (measured ~9.4 KB/level) the process dies of heap exhaustion —
+ * `FATAL ERROR: Ineffective mark-compacts near heap limit` — rather than
+ * overflowing the stack. `convert()` already survives this by matching a cached
+ * definition on the `aid` such a layer stamps on the node (see its `ZodLazy`
+ * branch), so the eager walkers key on the SAME identity: a declared
+ * `aid`/`id` names the definition, and only an unnamed node falls back to
+ * object identity.
+ *
+ * The two IDs are read in `convert()`'s own precedence (`aid` then `id`), and
+ * carry the same meaning here that they do there: two nodes sharing one
+ * declared id ARE one definition.
+ */
+function walkKey(s) {
+    if (!(s instanceof z.ZodType))
+        return s;
+    const meta = s.meta();
+    const declared = meta?.aid ?? meta?.id;
+    // Prefixed so a declared id can never be mistaken for anything else in the
+    // guard's key space (the alternative member is an object, so this is belt +
+    // braces against a future string-keyed member).
+    return typeof declared === 'string' ? `id:${declared}` : s;
+}
 /**
  * Decide whether `schema` can be expressed as structured output under
  * `descriptor`'s JSON-Schema dialect. Returns `false` when the schema uses a
@@ -427,26 +553,58 @@ export function resolveDescriptor(input) {
  * feasibility checks are easy to add.
  */
 export function canExpress(schema, descriptor) {
-    const root = schema;
+    return expressible(schema, descriptor, /* cycleBreakerCounts */ false);
+}
+/**
+ * `canExpress`, except that a cycle counts as EXPRESSIBLE whatever the
+ * descriptor's ref flags say, because `emitCachedRef` replaces any back-edge
+ * the descriptor cannot spell with the bounded `buildCycleBreakerSchema`
+ * placeholder. The emitted schema is therefore always *sendable*; it is only
+ * *looser* than the source at the back-edge.
+ *
+ * That distinction is the whole reason there are two predicates:
+ * - `canExpress` answers "will the model be properly CONSTRAINED by this?",
+ *   which is what a structured-OUTPUT delivery decision needs — a back-edge
+ *   silently widened to "any" is a good reason to deliver the schema as prompt
+ *   text instead (`applySchemaDeliveryFallback`), and
+ *   `ANTHROPIC_STRICT`'s `supportsRecursion: false` is exactly that case.
+ * - this one answers "will the provider REJECT this?", which is what a TOOL's
+ *   strict allocation needs. A tool has no prompt-text fallback, so degrading a
+ *   merely-loose schema to LENIENT would trade a real strict guarantee for
+ *   nothing.
+ *
+ * The combinator half is shared and is the half that actually bites: nothing
+ * rewrites a forbidden `anyOf`/`allOf` away, so a schema carrying one is a
+ * provider 400 under a descriptor that forbids it.
+ */
+function sendableUnder(schema, descriptor) {
+    return expressible(schema, descriptor, /* cycleBreakerCounts */ true);
+}
+function expressible(schema, descriptor, cycleBreakerCounts) {
+    // Keys, not objects — a rebuilt `z.lazy` getter defeats identity (see `walkKey`).
+    const rootKey = walkKey(schema);
     // Nodes currently on the DFS stack — a re-encounter is a recursion cycle.
     const inProgress = new Set();
     // Completed nodes with their result, so shared (non-cyclic) sub-schemas
     // aren't re-walked (guards against exponential blow-up on DAG-shaped schemas).
     const completed = new Map();
     const walk = (s) => {
-        if (inProgress.has(s)) {
+        const key = walkKey(s);
+        if (inProgress.has(key)) {
             // Recursion cycle detected at `s`.
-            if (s === root)
+            if (cycleBreakerCounts)
+                return true;
+            if (key === rootKey)
                 return descriptor.allowRootRef && descriptor.supportsRecursion;
             return descriptor.allowDefsRef && descriptor.supportsRecursion;
         }
-        const cached = completed.get(s);
+        const cached = completed.get(key);
         if (cached !== undefined)
             return cached;
-        inProgress.add(s);
+        inProgress.add(key);
         const result = walkNode(s);
-        inProgress.delete(s);
-        completed.set(s, result);
+        inProgress.delete(key);
+        completed.set(key, result);
         return result;
     };
     const walkNode = (s) => {
@@ -1045,9 +1203,16 @@ function convert(schema, context) {
     // If the schema has an 'aid' or 'id' in meta, promote it to a definition.
     // A cache-bypassed "any" node is never promoted — naming a schema that
     // asserts nothing buys nothing, and the `$defs` entry is precisely what the
-    // inline encoding is avoiding.
+    // inline encoding is avoiding. A descriptor that forbids `$defs` outright
+    // (`allowDefsRef: false` — Google strict) is never promoted to either: the id
+    // is still computed, because the cycle-breaker's description names it, but
+    // the definition is inlined at each use site, which is the only spelling that
+    // dialect has for a shared node.
     const id = (metadata.aid ? String(metadata.aid) : 0) || metadata.id || `__schema${context.refCounter++}`;
-    const save = !bypassCache && !!(metadata.aid || metadata.id) && context.root !== schema;
+    const save = !bypassCache
+        && !!(metadata.aid || metadata.id)
+        && context.root !== schema
+        && context.descriptor.allowDefsRef;
     // A schema target - will hold either the converted schema or a $ref
     const target = {};
     // Before converting, register this schema to handle recursion
@@ -1063,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)) {
@@ -1083,11 +1258,21 @@ function convert(schema, context) {
  *
  * Three cases:
  * 1. Re-encounter while still on the conversion stack (`inProgress.has(id)`)
- *    AND the descriptor rejects recursive `$ref`s — emit a shape-aware
- *    placeholder via `buildCycleBreakerSchema()` (number stays number, array
- *    stays array, etc.) with a description naming the `$defs` entry it would
- *    have referenced. This breaks the cycle inline so providers like
- *    Anthropic don't reject the schema.
+ *    AND the descriptor cannot express the `$ref` this back-edge would need —
+ *    emit a shape-aware placeholder via `buildCycleBreakerSchema()` (number
+ *    stays number, array stays array, etc.) with a description naming the
+ *    `$defs` entry it would have referenced. This breaks the cycle inline so
+ *    providers like Anthropic don't reject the schema.
+ *
+ *    "Cannot express" is TWO flags, not one, because a back-edge is only ever
+ *    spelled one of two ways: `{$ref: '#'}` at the root, or `{$ref:
+ *    '#/$defs/X'}` anywhere else. `!supportsRecursion` rules out both.
+ *    `!allowDefsRef` rules out the second — so a NON-ROOT cycle under a
+ *    descriptor that forbids `$defs` (Google strict is exactly that:
+ *    `supportsRecursion: true`, `allowRootRef: true`, `allowDefsRef: false`)
+ *    must take the same bounded placeholder. Checking only `supportsRecursion`
+ *    silently emitted the `$defs`/`$ref` pair the descriptor declares it cannot
+ *    send — a schema the provider answers with HTTP 400.
  * 2. Re-encounter at root with `allowRootRef` — emit `{$ref: '#'}`.
  * 3. Otherwise — emit `{$ref: '#/$defs/<id>'}`, promoting the original
  *    target to a `$defs` entry on first share.
@@ -1095,7 +1280,10 @@ function convert(schema, context) {
 function emitCachedRef(schema, cachedJs, cachedId, context) {
     const descriptor = context.descriptor;
     const isCycle = context.inProgress.has(cachedId);
-    if (isCycle && !descriptor.supportsRecursion) {
+    const isRoot = schema === context.root;
+    // The spelling this back-edge would need, and whether the descriptor has it.
+    const backEdgeExpressible = isRoot ? descriptor.allowRootRef : descriptor.allowDefsRef;
+    if (isCycle && (!descriptor.supportsRecursion || !backEdgeExpressible)) {
         // Replace the back-edge with a placeholder whose top-level shape matches
         // the recursive zod schema. The original `cachedJs` target keeps filling
         // in normally — once conversion completes the `$defs` entry exists; we
@@ -1103,9 +1291,30 @@ function emitCachedRef(schema, cachedJs, cachedId, context) {
         // the provider rejects.
         return buildCycleBreakerSchema(schema, cachedId, descriptor);
     }
-    if (schema === context.root && descriptor.allowRootRef) {
+    if (isRoot && descriptor.allowRootRef) {
         return { $ref: `#` };
     }
+    // A non-cyclic re-encounter under a descriptor with no `$defs`: INLINE the
+    // already-converted shape instead of naming it. There is no third spelling in
+    // that dialect — a shared node is either repeated or it is a `$ref` the
+    // provider rejects. Safe and finite: `!isCycle` means this node's conversion
+    // already completed, and any cycle BELOW it was replaced by the bounded
+    // placeholder above, so the inlined value is a finite tree. The cost is
+    // duplication in the emitted schema, which is what that dialect charges for
+    // shared structure.
+    //
+    // On a schema the dialect can actually SEND that cost is negligible (measured
+    // on the cases in `schema-google-defs.test.ts`: 497→435, 627→565, 280→322
+    // bytes — inlining a leaf is often smaller than naming it). It is only large
+    // on a heavily-shared recursive DAG — a gin `buildSchemas().Expr` renders
+    // 44 KB with `$defs` and 1.36 MB without — and such a schema carries 1646
+    // `anyOf`s, so `canExpress` already answers `false` for it and no provider
+    // path reaches here. Paying size on a schema that must not be sent anyway is
+    // the right side of the trade against emitting `$defs` the descriptor
+    // declares it cannot send.
+    if (!descriptor.allowDefsRef) {
+        return { ...cachedJs };
+    }
     if (!context.definitionSchemas.has(cachedId)) {
         context.definitionSchemas.set(cachedId, { ...cachedJs });
         for (const prop in cachedJs) {
@@ -1126,10 +1335,14 @@ function emitCachedRef(schema, cachedJs, cachedId, context) {
  */
 function buildCycleBreakerSchema(schema, refId, descriptor) {
     const placeholder = genericize(schema, descriptor, 1);
-    return {
-        ...placeholder,
-        description: `Would recursively reference #/$defs/${refId}`,
-    };
+    // The description is MODEL-FACING, so it must not point at a `$defs` entry
+    // this dialect never emits — under `allowDefsRef: false` there is no `$defs`
+    // section at all, and telling the model to look at one is a lie about the
+    // document it was handed. Name the recursion instead.
+    const description = descriptor.allowDefsRef
+        ? `Would recursively reference #/$defs/${refId}`
+        : `Recursive reference to '${refId}' — repeat this shape here`;
+    return { ...placeholder, description };
 }
 /**
  * Reduce a zod schema to a JSON-Schema node carrying its top-level shape
@@ -1265,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
  */
@@ -1450,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
@@ -1783,12 +2058,23 @@ const ZERO_FEATURES = Object.freeze({
     unionTypeCount: 0,
     recordCount: 0,
     tupleCount: 0,
+    enums: Object.freeze([]),
+    objectPropertyCount: 0,
+    maxNestingDepth: 0,
+    stringSizeChars: 0,
 });
 const featuresCache = new WeakMap();
 /**
  * Walk a Zod schema once and count its structural features. Result is
  * cached per schema in a WeakMap — second-and-subsequent calls are O(1) and
  * the entry is GC'd with the schema (same OOM-safe pattern as `strictify`).
+ *
+ * The walk is EAGER (it has to descend to count), so its cycle guard keys on
+ * `walkKey`, not on object identity: a `z.lazy` that rebuilds its inner schema
+ * per call would otherwise never re-enter the same object and the walk would
+ * never terminate. That is not hypothetical — it is a measured, reproducible
+ * heap-death, and this function is on the hot path of EVERY tool of EVERY
+ * request to a strict-family model (`SchemaBudget.allocate`).
  */
 export function analyzeSchema(schema) {
     const cached = featuresCache.get(schema);
@@ -1796,98 +2082,202 @@ 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;
-        if (visiting.has(s))
+        const key = walkKey(s);
+        if (visiting.has(key))
             return;
-        visiting.add(s);
+        visiting.add(key);
         try {
             // Recursion is detected via z.lazy: peek at the inner schema (but only
             // once — the visiting set bounds the walk).
             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.
         }
         finally {
-            visiting.delete(s);
+            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
@@ -1901,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;
@@ -1914,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.
      */
@@ -1944,31 +2363,56 @@ 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;
-        const features = analyzeSchema(schema);
+            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.
-            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 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 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
         // them — if there are too many, that's a request-construction bug we
         // 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)
@@ -1984,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.