@aeye/core 0.5.3 → 0.6.0

package/dist/schema/descriptor.d.ts

@@ -0,0 +1,300 @@
+/**
+ * Provider family for a `FormatDescriptor`. The three known wire dialects
+ * (`'openai'`, `'anthropic'`, `'google'`) are autocomplete hints; any string
+ * is accepted so users can register custom descriptors via
+ * `registerDescriptor` and reference them by family name in
+ * `ModelInfo.strictFormat`. `'lenient'` is the no-rewrite catch-all and is
+ * not registerable as a custom family.
+ *
+ * Use this type wherever you need to talk about a descriptor family —
+ * registry functions, model declarations, etc.
+ */
+export type DescriptorFamily = 'openai' | 'anthropic' | 'google' | 'xai' | (string & {});
+/**
+ * Documented ceilings on how BIG one strict schema may be, as opposed to which
+ * keywords it may use. Every limit here is a SUM taken over a single schema —
+ * one tool's `parameters`, or one structured-output schema — not a per-request
+ * allowance shared between them (that is `maxStrictTools` and friends, which
+ * the `SchemaBudget` spends across the whole request).
+ *
+ * A schema that exceeds one of these is a guaranteed provider rejection under
+ * strict mode, so `SchemaBudget.allocate` treats it like any other
+ * infeasibility and degrades that ONE item to the family's non-strict
+ * descriptor, where no size rule applies. The rest of the request is
+ * unaffected.
+ *
+ * Declared as one object rather than six optional fields on purpose: a
+ * provider documents these together, and the object being present is what says
+ * "this dialect publishes size limits". Adding a rule here is then a compile
+ * error at every descriptor that declares the group, which is the point
+ * (a missed limit is invisible until a 400).
+ */
+export interface SchemaSizeLimits {
+    /** Maximum object properties in one schema, summed over every nesting level. */
+    readonly maxObjectProperties: number;
+    /** Maximum levels of nested containers below the schema root. */
+    readonly maxNestingDepth: number;
+    /**
+     * Maximum total characters over the schema's property names, `enum` values
+     * and `const` values together.
+     */
+    readonly maxTotalStringChars: number;
+    /** Maximum `enum` values summed across every enum property in one schema. */
+    readonly maxTotalEnumValues: number;
+    /**
+     * The single-enum value count above which `maxLargeEnumStringChars` starts
+     * to apply. A smaller enum is bounded only by the two totals above.
+     */
+    readonly largeEnumValueCount: number;
+    /**
+     * Maximum total characters of ONE enum's string values, applied only to an
+     * enum carrying more than `largeEnumValueCount` values.
+     */
+    readonly maxLargeEnumStringChars: number;
+}
+/**
+ * Format descriptor — describes the JSON Schema dialect of a target.
+ *
+ * Each provider/strict combination is represented by one descriptor. The
+ * descriptor controls both how `strictify` rewrites a Zod schema (preprocesses
+ * for record-as-array, tuple-as-object, etc.) and how `toJSONSchema` emits the
+ * matching JSON Schema. Every `if (strict)` decision in the conversion
+ * pipeline dispatches off a descriptor field, so adding a new dialect is a
+ * matter of declaring a new `FormatDescriptor` and registering it.
+ */
+export interface FormatDescriptor {
+    /** Stable id used as the cache key inside `strictify`. */
+    readonly id: string;
+    /**
+     * Provider family for this descriptor. The three built-in wire dialects
+     * are `'openai'` / `'anthropic'` / `'google'`; `'lenient'` is the
+     * no-rewrite catch-all. Custom descriptors registered via
+     * `registerDescriptor` may use any string here — the family is the
+     * lookup key used by `getDescriptor(family, strict)`.
+     */
+    readonly family: DescriptorFamily | 'lenient';
+    /** True if this descriptor represents the strict variant for its family. */
+    readonly strict: boolean;
+    /** When true, every object field appears in `required[]` (OpenAI strict). */
+    readonly objectAllFieldsRequired: boolean;
+    /** When true, every object emits `additionalProperties: false`. */
+    readonly objectClosedByDefault: boolean;
+    /** How to encode `z.record(K, V)`. */
+    readonly recordEncoding: 'array-of-pairs' | 'open-record';
+    /**
+     * How to encode `z.tuple([...])`.
+     * - `object-numeric-keys`: OpenAI-strict workaround (`{ "0": A, "1": B, ... }`)
+     * - `prefix-items`: standard JSON Schema `prefixItems` (Anthropic / Google)
+     * - `items-union`: collapse to homogeneous `items: { anyOf: [...] }` (last-resort)
+     */
+    readonly tupleEncoding: 'object-numeric-keys' | 'prefix-items' | 'items-union';
+    readonly allowAllOf: boolean;
+    readonly allowAnyOf: boolean;
+    readonly allowOneOf: boolean;
+    /** Whether `{ $ref: '#' }` self-reference is permitted. */
+    readonly allowRootRef: boolean;
+    readonly allowDefsRef: boolean;
+    /** Reserved: emit Google-style `propertyOrdering` hints. */
+    readonly emitPropertyOrdering: boolean;
+    /** Whitelist of `format:` values to emit, or `'all'` for every format JSON Schema defines. */
+    readonly supportedStringFormats: ReadonlySet<string> | 'all';
+    readonly allowPattern: boolean;
+    readonly allowMultiplePatterns: boolean;
+    readonly allowMinMaxLength: boolean;
+    readonly allowMinMaxItems: boolean;
+    readonly allowMinimumMaximum: boolean;
+    /** When true, `optional` becomes `T|null` (because every prop must be required). */
+    readonly optionalAsNullable: boolean;
+    /**
+     * How `z.any()` / `z.unknown()` is encoded.
+     * - `recursive-strict`: self-referencing $defs/Any with array-of-pairs records
+     *   (OpenAI strict has no open-object support). REQUIRES `allowAnyOf` and
+     *   `allowDefsRef`.
+     * - `recursive-open`: $defs/Any with `additionalProperties: <self>` records.
+     *   REQUIRES `allowAnyOf` and `allowDefsRef`.
+     * - `flat`: a non-recursive `anyOf` over the JSON value types
+     *   (`string`/`number`/`boolean`/`null`/`array`/open-`object`). Used by
+     *   descriptors that reject recursive `$defs/Any` definitions (xAI strict).
+     *   Equivalent to TypeScript `any` — accepts every JSON value without
+     *   imposing any structural constraints. REQUIRES `allowAnyOf` (no `$defs`
+     *   needed).
+     * - `unconstrained`: the empty schema `{}` (plus any `description`). Per
+     *   JSON Schema, a schema with no assertion keywords validates EVERY
+     *   instance — which is exactly what "any JSON value" means — and it
+     *   introduces no keyword a restrictive dialect could reject. REQUIRES
+     *   NOTHING, so it's the only encoding available to a dialect that forbids
+     *   both combinators and named `$defs`/`$ref` (Google — see `GOOGLE_STRICT`).
+     * - `none`: the dialect has no spelling for "any JSON value" (Anthropic
+     *   strict rejects `{}`, a typeless schema, an open object and a recursive
+     *   `$defs/Any`). A schema containing one — or a recursion cycle, whose
+     *   placeholder bottoms out at "any" — is not sendable, so the budget
+     *   degrades the tool and `canExpress` sends an output as prompt text.
+     *
+     * The `REQUIRES` notes above are enforced by `checkDescriptorConsistency`,
+     * which `registerDescriptor` runs so a self-contradictory descriptor is
+     * caught at declaration time rather than as a provider HTTP 400.
+     */
+    readonly anyEncoding: 'recursive-strict' | 'recursive-open' | 'flat' | 'unconstrained' | 'none';
+    /** Maximum number of tools that can carry `strict: true` in one request. */
+    readonly maxStrictTools?: number;
+    /** Maximum total optional parameters across all strict schemas in one request. */
+    readonly maxStrictOptionalParams?: number;
+    /** Maximum total union-type parameters across all strict schemas in one request. */
+    readonly maxStrictUnionTypes?: number;
+    /**
+     * Documented ceilings on the SIZE of one strict schema (properties, nesting,
+     * total string bytes, enum values), or `undefined` when the dialect
+     * publishes none. See {@link SchemaSizeLimits} for what each bound counts and
+     * why it is per-schema rather than per-request.
+     *
+     * Only a STRICT descriptor declares these: they are Structured-Outputs rules
+     * — the API compiles the schema into a decoder and rejects one it cannot —
+     * and a non-strict schema is a best-effort hint the API does not compile. So
+     * degrading the offending item to the family's non-strict descriptor is both
+     * the fix and the reason the limits stop applying to it
+     * (`SchemaBudget.allocate`, `checkSchemaSizeLimits`).
+     *
+     * The measurement is taken from the ZOD schema, not from the emitted JSON,
+     * so it is deliberately CONSERVATIVE where an encoding is descriptor-
+     * dependent (a record counts as its widest encoding, a tuple as its
+     * numeric-key one). Over-counting costs strictness on a schema that would
+     * have fit; under-counting costs an HTTP 400, so the round goes up.
+     */
+    readonly schemaSizeLimits?: SchemaSizeLimits;
+    /**
+     * Maximum number of values ONE emitted `enum` may carry, or `undefined`
+     * (the default) for no cap.
+     *
+     * This is deliberately NOT one of the per-request budget fields above. Those
+     * are strict-mode allowances the SchemaBudget spends across a whole request,
+     * degrading an item that no longer fits to the family's non-strict
+     * descriptor; this one is a property of the dialect itself — it fires whatever the strictness — so it is enforced
+     * structurally at the point an `enum` is emitted (`convertSchema`), where
+     * the cardinality is actually known.
+     *
+     * Over the cap the emitter **widens** rather than truncates: it drops the
+     * `enum` keyword entirely, emits the node's plain scalar `type`
+     * (`{type: 'string'}` for a string enum), and puts EVERY value into the
+     * node's `description`. Nothing becomes unreachable — the model still has
+     * the complete list and can name any member — and the cardinality the
+     * dialect could not compile is simply no longer on the wire.
+     *
+     * The trade this makes is enforcement: a widened node no longer rejects a
+     * value structurally, so whatever validates the model's output afterwards
+     * has to. `Tool.parse` does, against the ORIGINAL zod schema — the enum is
+     * still there, only the emitted JSON Schema widened — so a hallucinated
+     * member comes back as a normal, re-promptable validation error.
+     *
+     * **`GOOGLE_STRICT`/`GOOGLE_NON_STRICT` declare 40. Every other built-in
+     * declares no cap.** Two earlier rounds of live measurement against
+     * `google/gemini-3-flash-preview` through OpenRouter (2026-08-23) — single
+     * enums up to 2048 SYNTHETIC values, 20 tools each with a 96-value enum, and
+     * an eleven-tool roster modelled on a real kind-authoring agent — all
+     * returned HTTP 200 and concluded there was no reproducible limit. **That
+     * conclusion was wrong, because none of those enums used the CONTENT of a
+     * real session.** A third round replayed the exact wire bytes of a real
+     * product request — `fn_load`'s `names` array, enum-constrained to the
+     * session's actual 98 known component/fn names (`default_renderer`,
+     * `QueryWidget`, `ConfirmPrompt`, `list_widget_types`, …) — and it 400'd,
+     * reproducibly, twice, byte-for-byte identical to what the provider was
+     * actually sent. Bisecting that same real value list: 90 values passes, 93
+     * fails. Bisecting what changes between the passing synthetic probes and the
+     * failing real one: 98 SHORT synthetic values (`n0`..`n97`, 284 chars) pass;
+     * 206 short values matching the REAL list's total character count (714
+     * chars) also pass; only the REAL, longer, dictionary-like/identifier-shaped
+     * values fail, and only past ~92 of them. So the limit tracks neither raw
+     * member count nor total character/byte budget — most likely actual
+     * tokenized grammar-state count, which short repetitive synthetic strings
+     * compress far below what real identifier text does at the same count or
+     * character budget. This is why the first two rounds' synthetic and
+     * lightly-realistic probes never tripped it.
+     *
+     * **The widen-to-string fallback this field triggers was verified against
+     * the exact failing real schema**: dropping `enum` and putting the same 98
+     * values into the `description` of a plain string field returned HTTP 200
+     * with the expected tool call — confirming the fallback mechanism actually
+     * fixes the failure it exists for, not just a synthetic stand-in.
+     *
+     * **40 is not a measured edge — it is a conservative floor with roughly 2x
+     * margin under the real one (90 passes / 93 fails) measured on this one real
+     * value set.** Given the failure tracks content, not just count, a different
+     * session's actual name list could plausibly fail at a different count; 40
+     * was also the cap this exact product ran under in production for months
+     * before a since-reverted attempt to remove it, which is corroborating
+     * evidence it holds in practice, not just in this one measurement.
+     *
+     * The reliability comparison from the earlier rounds still stands and is
+     * why a cap is preferable to leaving every enum uncapped "to be safe" at a
+     * much lower number: `enum` vs plain-string-with-full-list, 10 trials each
+     * over confusable near-duplicate names at 96 and 512 values, scored 10/10
+     * on-target with zero off-list answers for BOTH encodings. So there is no
+     * reliability cost to raising this cap later if a higher safe value is
+     * measured — only downside risk to leaving it too high.
+     *
+     * One trap for whoever measures this next: with `max_tokens` at 64, a
+     * forced-tool probe can come back `finish_reason: 'length'` with no tool
+     * call and empty content, which reads exactly like a grammar that produced
+     * nothing. It usually is not — this model spends reasoning tokens first.
+     * Give a forced-tool probe room before calling an empty completion a
+     * failure.
+     *
+     * So: set this only where a provider is MEASURED to reject a large enum
+     * using the SESSION'S OWN real content, not synthetic stand-ins, and set it
+     * conservatively below the measured edge until more value sets are tested.
+     * An `enum` that fits is the more correct encoding, because it is the one
+     * the model cannot answer outside of.
+     */
+    readonly maxEnumValues?: number;
+    /**
+     * Whether the descriptor can express recursive `$ref` schemas (`$ref: '#'`
+     * to root, or any `$ref: '#/$defs/X'` whose target transitively references
+     * itself). OpenAI / Google strict / Lenient: true. Anthropic strict: false
+     * — Anthropic's tool `input_schema` validator explicitly rejects circular
+     * `$defs` graphs.
+     *
+     * When `false`, the JSON-Schema emitter detects cycles in the source
+     * schema and replaces the offending back-edge with the descriptor's flat
+     * "any" shape (see `anyEncoding`) carrying a description that names the
+     * `$defs` entry it would otherwise have referenced. Non-cyclic shared
+     * `$ref` reuse is unaffected — those still emit as a `$ref` to a `$defs`
+     * entry.
+     */
+    readonly supportsRecursion: boolean;
+    /**
+     * True when the family's structured output is always compiled to a grammar,
+     * so there is no non-strict `json_schema` to degrade an output to. Anthropic:
+     * `output_config.format` is strict by definition, and OpenRouter adds the
+     * structured-outputs flag to every `json_schema` bound for Claude — a
+     * "non-strict" output with 30 optional fields still earns "Schemas contains
+     * too many optional parameters (30) … (limit: 24)" (measured 2026-11-04).
+     *
+     * A schema over the strict limits then cannot go out as structured output at
+     * all: `canExpress` answers `false`, so it is delivered as prompt text, and
+     * `SchemaBudget` never degrades an output to the non-strict variant.
+     */
+    readonly structuredOutputAlwaysStrict?: boolean;
+    /**
+     * Instruction appended after the schema text when a Prompt's/Tool's schema
+     * can't be expressed as this descriptor's structured output and is instead
+     * delivered to the model as PROMPT TEXT (see `canExpress` and the ai-layer
+     * `applySchemaDeliveryFallback`). Steers the model to emit a single raw JSON
+     * object rather than echoing the schema or wrapping it in prose/fences.
+     *
+     * Optional — descriptors that omit it fall back to
+     * `DEFAULT_JSON_FALLBACK_INSTRUCTION` via `getJsonFallbackInstruction`.
+     */
+    readonly jsonFallbackInstruction?: string;
+}
+/**
+ * Default instruction used when a `FormatDescriptor` omits
+ * `jsonFallbackInstruction`. Appended after the schema text when a schema is
+ * delivered as prompt text instead of as structured output.
+ */
+export declare const DEFAULT_JSON_FALLBACK_INSTRUCTION = "Return ONLY a single raw JSON object conforming to the schema above \u2014 no markdown code fences, no prose, and do NOT echo the schema itself.";
+/**
+ * Resolve the prompt-text fallback instruction for a descriptor, falling back
+ * to `DEFAULT_JSON_FALLBACK_INSTRUCTION` when the descriptor doesn't declare
+ * one of its own.
+ */
+export declare function getJsonFallbackInstruction(descriptor: FormatDescriptor): string;
+//# sourceMappingURL=descriptor.d.ts.map

package/dist/schema/descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"descriptor.d.ts","sourceRoot":"","sources":["../../src/schema/descriptor.ts"],"names":[],"mappings":"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"}

package/dist/schema/descriptor.js

@@ -0,0 +1,15 @@
+/**
+ * Default instruction used when a `FormatDescriptor` omits
+ * `jsonFallbackInstruction`. Appended after the schema text when a schema is
+ * delivered as prompt text instead of as structured output.
+ */
+export const DEFAULT_JSON_FALLBACK_INSTRUCTION = 'Return ONLY a single raw JSON object conforming to the schema above — no markdown code fences, no prose, and do NOT echo the schema itself.';
+/**
+ * Resolve the prompt-text fallback instruction for a descriptor, falling back
+ * to `DEFAULT_JSON_FALLBACK_INSTRUCTION` when the descriptor doesn't declare
+ * one of its own.
+ */
+export function getJsonFallbackInstruction(descriptor) {
+    return descriptor.jsonFallbackInstruction ?? DEFAULT_JSON_FALLBACK_INSTRUCTION;
+}
+//# sourceMappingURL=descriptor.js.map

package/dist/schema/descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"descriptor.js","sourceRoot":"","sources":["../../src/schema/descriptor.ts"],"names":[],"mappings":"AAmUA;;;;GAIG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAC5C,6IAA6I,CAAC;AAEhJ;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CAAC,UAA4B;IACrE,OAAO,UAAU,CAAC,uBAAuB,IAAI,iCAAiC,CAAC;AACjF,CAAC"}

package/dist/schema/dialects/anthropic.d.ts

@@ -0,0 +1,34 @@
+import type { FormatDescriptor } from '../descriptor';
+/**
+ * Anthropic strict — Claude 4.5 and later (Opus 4.5–4.8, Sonnet 4.5/4.6,
+ * Haiku 4.5, and the 5.x Opus, Sonnet, Haiku, Fable, and Mythos models). Strict
+ * tools and `output_config.format` are GA with no beta header (re-read
+ * 2026-10-30). Per Anthropic's structured-outputs docs:
+ *
+ * - `additionalProperties` may **only** be `false` (no schema-valued open
+ *   records), so `z.record(...)` falls back to the OpenAI-style
+ *   array-of-pairs workaround.
+ * - Non-cyclic `$ref` / `$defs` reuse is supported and used freely — only
+ *   *circular* `$defs` graphs are rejected by the API
+ *   (`Circular reference detected in schema definitions: …`). The emitter
+ *   sets `supportsRecursion: false`; shared non-cyclic `$ref`s are emitted
+ *   normally, and a cycle makes the schema unsendable (see `anyEncoding`).
+ *   Root self-reference (`$ref: '#'`) is always cyclic by definition, so
+ *   `allowRootRef` stays `false`.
+ * - Numerical (`minimum`/`maximum`/`multipleOf`) and string-length
+ *   (`minLength`/`maxLength`) constraints are not supported and are dropped,
+ *   as are array sizes (only `minItems` of 0 or 1 is accepted).
+ * - `allOf` is supported except around a `$ref`.
+ * - `pattern` may not use backreferences, lookaround, `\b` or large `{n,m}`
+ *   ranges; a schema that compiles too big is rejected with "Schema is too
+ *   complex for compilation".
+ * - `prefixItems` and other positional tuple keywords are not in the
+ *   supported list, so tuples collapse to a homogeneous `items: anyOf`.
+ * - Formats are a closed list (re-read 2026-11-04): OpenAI strict's nine plus
+ *   `uri`. Anything else is dropped rather than risk a 400.
+ *
+ * See docs/plans/schema-dialects-2026.md for sources.
+ */
+export declare const ANTHROPIC_STRICT: FormatDescriptor;
+export declare const ANTHROPIC_NON_STRICT: FormatDescriptor;
+//# sourceMappingURL=anthropic.d.ts.map

package/dist/schema/dialects/anthropic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anthropic.d.ts","sourceRoot":"","sources":["../../../src/schema/dialects/anthropic.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAOtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,gBAAgB,EAAE,gBAoC7B,CAAC;AAEH,eAAO,MAAM,oBAAoB,EAAE,gBAIjC,CAAC"}

package/dist/schema/dialects/anthropic.js

@@ -0,0 +1,77 @@
+import { LENIENT } from './lenient';
+const ANTHROPIC_STRICT_FORMATS = new Set([
+    'date-time', 'time', 'date', 'duration', 'email', 'hostname', 'uri', 'ipv4', 'ipv6', 'uuid',
+]);
+/**
+ * Anthropic strict — Claude 4.5 and later (Opus 4.5–4.8, Sonnet 4.5/4.6,
+ * Haiku 4.5, and the 5.x Opus, Sonnet, Haiku, Fable, and Mythos models). Strict
+ * tools and `output_config.format` are GA with no beta header (re-read
+ * 2026-10-30). Per Anthropic's structured-outputs docs:
+ *
+ * - `additionalProperties` may **only** be `false` (no schema-valued open
+ *   records), so `z.record(...)` falls back to the OpenAI-style
+ *   array-of-pairs workaround.
+ * - Non-cyclic `$ref` / `$defs` reuse is supported and used freely — only
+ *   *circular* `$defs` graphs are rejected by the API
+ *   (`Circular reference detected in schema definitions: …`). The emitter
+ *   sets `supportsRecursion: false`; shared non-cyclic `$ref`s are emitted
+ *   normally, and a cycle makes the schema unsendable (see `anyEncoding`).
+ *   Root self-reference (`$ref: '#'`) is always cyclic by definition, so
+ *   `allowRootRef` stays `false`.
+ * - Numerical (`minimum`/`maximum`/`multipleOf`) and string-length
+ *   (`minLength`/`maxLength`) constraints are not supported and are dropped,
+ *   as are array sizes (only `minItems` of 0 or 1 is accepted).
+ * - `allOf` is supported except around a `$ref`.
+ * - `pattern` may not use backreferences, lookaround, `\b` or large `{n,m}`
+ *   ranges; a schema that compiles too big is rejected with "Schema is too
+ *   complex for compilation".
+ * - `prefixItems` and other positional tuple keywords are not in the
+ *   supported list, so tuples collapse to a homogeneous `items: anyOf`.
+ * - Formats are a closed list (re-read 2026-11-04): OpenAI strict's nine plus
+ *   `uri`. Anything else is dropped rather than risk a 400.
+ *
+ * See docs/plans/schema-dialects-2026.md for sources.
+ */
+export const ANTHROPIC_STRICT = Object.freeze({
+    id: 'anthropic-strict',
+    family: 'anthropic',
+    strict: true,
+    objectAllFieldsRequired: false,
+    objectClosedByDefault: true,
+    recordEncoding: 'array-of-pairs',
+    tupleEncoding: 'items-union',
+    allowAllOf: true,
+    allowAnyOf: true,
+    allowOneOf: false,
+    allowRootRef: false,
+    allowDefsRef: true,
+    emitPropertyOrdering: false,
+    supportedStringFormats: ANTHROPIC_STRICT_FORMATS,
+    allowPattern: true,
+    allowMultiplePatterns: false,
+    allowMinMaxLength: false,
+    allowMinMaxItems: false,
+    allowMinimumMaximum: false,
+    optionalAsNullable: false,
+    // No spelling for "any JSON value": `{}` ("Empty schema … is not
+    // supported"), a typeless schema, `additionalProperties: true` and a
+    // recursive `$defs/Any` are all rejected (measured 2026-11-04).
+    anyEncoding: 'none',
+    // Anthropic-documented per-request limits (apply across ALL strict tool
+    // schemas + JSON output schemas in one request).
+    // Source: https://platform.claude.com/docs/en/build-with-claude/structured-outputs
+    maxStrictTools: 20,
+    maxStrictOptionalParams: 24,
+    maxStrictUnionTypes: 16,
+    // Recursive `$ref` graphs are rejected by Anthropic's tool input_schema
+    // validator, and the cycle-breaker's placeholder needs "any", so a cyclic
+    // schema is not sent strict.
+    supportsRecursion: false,
+    structuredOutputAlwaysStrict: true,
+});
+export const ANTHROPIC_NON_STRICT = Object.freeze({
+    ...LENIENT,
+    id: 'anthropic-non-strict',
+    family: 'anthropic',
+});
+//# sourceMappingURL=anthropic.js.map

package/dist/schema/dialects/anthropic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"anthropic.js","sourceRoot":"","sources":["../../../src/schema/dialects/anthropic.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,MAAM,wBAAwB,GAAG,IAAI,GAAG,CAAC;IACvC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAC5F,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAqB,MAAM,CAAC,MAAM,CAAC;IAC9D,EAAE,EAAE,kBAAkB;IACtB,MAAM,EAAE,WAAW;IACnB,MAAM,EAAE,IAAI;IACZ,uBAAuB,EAAE,KAAK;IAC9B,qBAAqB,EAAE,IAAI;IAC3B,cAAc,EAAE,gBAAgB;IAChC,aAAa,EAAE,aAAa;IAC5B,UAAU,EAAE,IAAI;IAChB,UAAU,EAAE,IAAI;IAChB,UAAU,EAAE,KAAK;IACjB,YAAY,EAAE,KAAK;IACnB,YAAY,EAAE,IAAI;IAClB,oBAAoB,EAAE,KAAK;IAC3B,sBAAsB,EAAE,wBAAwB;IAChD,YAAY,EAAE,IAAI;IAClB,qBAAqB,EAAE,KAAK;IAC5B,iBAAiB,EAAE,KAAK;IACxB,gBAAgB,EAAE,KAAK;IACvB,mBAAmB,EAAE,KAAK;IAC1B,kBAAkB,EAAE,KAAK;IACzB,iEAAiE;IACjE,qEAAqE;IACrE,gEAAgE;IAChE,WAAW,EAAE,MAAM;IACnB,wEAAwE;IACxE,iDAAiD;IACjD,mFAAmF;IACnF,cAAc,EAAE,EAAE;IAClB,uBAAuB,EAAE,EAAE;IAC3B,mBAAmB,EAAE,EAAE;IACvB,wEAAwE;IACxE,0EAA0E;IAC1E,6BAA6B;IAC7B,iBAAiB,EAAE,KAAK;IACxB,4BAA4B,EAAE,IAAI;CACnC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,oBAAoB,GAAqB,MAAM,CAAC,MAAM,CAAC;IAClE,GAAG,OAAO;IACV,EAAE,EAAE,sBAAsB;IAC1B,MAAM,EAAE,WAAW;CACpB,CAAC,CAAC"}

package/dist/schema/dialects/google.d.ts

@@ -0,0 +1,47 @@
+import type { FormatDescriptor } from '../descriptor';
+/**
+ * Google Gemini strict — per `ai.google.dev/gemini-api/docs/structured-output`
+ * (re-read 2026-10-30, after Google's November 2025 JSON Schema expansion):
+ *
+ * - Supported keywords: types (including `["T", "null"]` arrays),
+ *   `properties`, `required`, `additionalProperties`, `enum`, `format`
+ *   (date-time/date/time), `minimum`, `maximum`, `items`, `prefixItems`,
+ *   `minItems`, `maxItems`, `anyOf` (`oneOf` is read as `anyOf`), `$defs`,
+ *   `$ref`, `title`, `description`, `propertyOrdering`.
+ * - `allOf` is not supported and `pattern` is not listed; both stay off.
+ *   Live on `google/gemini-3-flash-preview` via OpenRouter (2026-10-30) an
+ *   `allOf` tool was accepted but not enforced and a `pattern` tool timed out,
+ *   while `anyOf`, shared `$defs`, `prefixItems`, nullable type arrays, closed
+ *   objects, and recursion through array items or optional properties all
+ *   answered with valid tool calls.
+ * - `minLength`/`maxLength` are stripped by the API, so they are not emitted.
+ * - Key order is preserved from the schema on Gemini 2.5+, so
+ *   `propertyOrdering` is only needed by older models; it is still emitted.
+ * - `z.any()` / `z.unknown()` uses the `unconstrained` encoding. Gemini
+ *   rejects ref loops through REQUIRED values: a self-referencing `$defs/Any`
+ *   that recurses through `additionalProperties` fails with "ref loops are
+ *   only supported if they include optional or nullable property values, or
+ *   a potentially-zero-length array items" (reproduced 2026-10-30 after an
+ *   interval in August 2026 when it was accepted), so the empty schema stays.
+ *   Ordinary recursive models recurse through optional fields or arrays,
+ *   which Gemini accepts.
+ */
+export declare const GOOGLE_STRICT: FormatDescriptor;
+/**
+ * Google Gemini non-strict — LENIENT's permissive rules EXCEPT for the "any"
+ * encoding.
+ *
+ * Gemini rejects a self-referencing `$defs/Any` when it has to build a
+ * decoding grammar, and it builds one whenever a tool call is forced —
+ * independent of any per-tool `strict` flag, which Google's function-calling
+ * API doesn't even have. So the `unconstrained` encoding is a property of the
+ * DIALECT, not of strict mode, and belongs on both Google descriptors.
+ *
+ * Everything else stays LENIENT deliberately: the restrictions on
+ * `GOOGLE_STRICT` come from the documented structured-output keyword list,
+ * which is a grammar-mode concern, and tightening them here would push
+ * ordinary Gemini schemas onto the prompt-text delivery fallback for no
+ * measured reason.
+ */
+export declare const GOOGLE_NON_STRICT: FormatDescriptor;
+//# sourceMappingURL=google.d.ts.map

package/dist/schema/dialects/google.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"google.d.ts","sourceRoot":"","sources":["../../../src/schema/dialects/google.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAGtD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,aAAa,EAAE,gBAmC1B,CAAC;AAEH;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,iBAAiB,EAAE,gBAW9B,CAAC"}

package/dist/schema/dialects/google.js

@@ -0,0 +1,91 @@
+import { LENIENT } from './lenient';
+/**
+ * Google Gemini strict — per `ai.google.dev/gemini-api/docs/structured-output`
+ * (re-read 2026-10-30, after Google's November 2025 JSON Schema expansion):
+ *
+ * - Supported keywords: types (including `["T", "null"]` arrays),
+ *   `properties`, `required`, `additionalProperties`, `enum`, `format`
+ *   (date-time/date/time), `minimum`, `maximum`, `items`, `prefixItems`,
+ *   `minItems`, `maxItems`, `anyOf` (`oneOf` is read as `anyOf`), `$defs`,
+ *   `$ref`, `title`, `description`, `propertyOrdering`.
+ * - `allOf` is not supported and `pattern` is not listed; both stay off.
+ *   Live on `google/gemini-3-flash-preview` via OpenRouter (2026-10-30) an
+ *   `allOf` tool was accepted but not enforced and a `pattern` tool timed out,
+ *   while `anyOf`, shared `$defs`, `prefixItems`, nullable type arrays, closed
+ *   objects, and recursion through array items or optional properties all
+ *   answered with valid tool calls.
+ * - `minLength`/`maxLength` are stripped by the API, so they are not emitted.
+ * - Key order is preserved from the schema on Gemini 2.5+, so
+ *   `propertyOrdering` is only needed by older models; it is still emitted.
+ * - `z.any()` / `z.unknown()` uses the `unconstrained` encoding. Gemini
+ *   rejects ref loops through REQUIRED values: a self-referencing `$defs/Any`
+ *   that recurses through `additionalProperties` fails with "ref loops are
+ *   only supported if they include optional or nullable property values, or
+ *   a potentially-zero-length array items" (reproduced 2026-10-30 after an
+ *   interval in August 2026 when it was accepted), so the empty schema stays.
+ *   Ordinary recursive models recurse through optional fields or arrays,
+ *   which Gemini accepts.
+ */
+export const GOOGLE_STRICT = Object.freeze({
+    id: 'google-strict',
+    family: 'google',
+    strict: true,
+    objectAllFieldsRequired: false,
+    objectClosedByDefault: false,
+    recordEncoding: 'open-record',
+    tupleEncoding: 'prefix-items',
+    allowAllOf: false,
+    allowAnyOf: true,
+    allowOneOf: false,
+    allowRootRef: true,
+    allowDefsRef: true,
+    emitPropertyOrdering: true,
+    supportedStringFormats: new Set(['date-time', 'date', 'time']),
+    allowPattern: false,
+    allowMultiplePatterns: false,
+    allowMinMaxLength: false,
+    allowMinMaxItems: true,
+    allowMinimumMaximum: true,
+    optionalAsNullable: false,
+    // Not a recursive $defs/Any: Gemini rejects ref loops through required
+    // values — see the descriptor doc above.
+    anyEncoding: 'unconstrained',
+    // 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,
+    // When a schema can't be expressed here (e.g. it needs `allOf`) it's
+    // delivered as prompt text instead; this hint keeps the reply a single raw
+    // JSON object.
+    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.',
+});
+/**
+ * Google Gemini non-strict — LENIENT's permissive rules EXCEPT for the "any"
+ * encoding.
+ *
+ * Gemini rejects a self-referencing `$defs/Any` when it has to build a
+ * decoding grammar, and it builds one whenever a tool call is forced —
+ * independent of any per-tool `strict` flag, which Google's function-calling
+ * API doesn't even have. So the `unconstrained` encoding is a property of the
+ * DIALECT, not of strict mode, and belongs on both Google descriptors.
+ *
+ * Everything else stays LENIENT deliberately: the restrictions on
+ * `GOOGLE_STRICT` come from the documented structured-output keyword list,
+ * which is a grammar-mode concern, and tightening them here would push
+ * ordinary Gemini schemas onto the prompt-text delivery fallback for no
+ * measured reason.
+ */
+export const GOOGLE_NON_STRICT = Object.freeze({
+    ...LENIENT,
+    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.',
+});
+//# sourceMappingURL=google.js.map

package/dist/schema/dialects/google.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"google.js","sourceRoot":"","sources":["../../../src/schema/dialects/google.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,MAAM,aAAa,GAAqB,MAAM,CAAC,MAAM,CAAC;IAC3D,EAAE,EAAE,eAAe;IACnB,MAAM,EAAE,QAAQ;IAChB,MAAM,EAAE,IAAI;IACZ,uBAAuB,EAAE,KAAK;IAC9B,qBAAqB,EAAE,KAAK;IAC5B,cAAc,EAAE,aAAa;IAC7B,aAAa,EAAE,cAAc;IAC7B,UAAU,EAAE,KAAK;IACjB,UAAU,EAAE,IAAI;IAChB,UAAU,EAAE,KAAK;IACjB,YAAY,EAAE,IAAI;IAClB,YAAY,EAAE,IAAI;IAClB,oBAAoB,EAAE,IAAI;IAC1B,sBAAsB,EAAE,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9D,YAAY,EAAE,KAAK;IACnB,qBAAqB,EAAE,KAAK;IAC5B,iBAAiB,EAAE,KAAK;IACxB,gBAAgB,EAAE,IAAI;IACtB,mBAAmB,EAAE,IAAI;IACzB,kBAAkB,EAAE,KAAK;IACzB,uEAAuE;IACvE,yCAAyC;IACzC,WAAW,EAAE,eAAe;IAC5B,2EAA2E;IAC3E,yEAAyE;IACzE,0EAA0E;IAC1E,2EAA2E;IAC3E,aAAa,EAAE,EAAE;IACjB,iBAAiB,EAAE,IAAI;IACvB,qEAAqE;IACrE,2EAA2E;IAC3E,eAAe;IACf,uBAAuB,EACrB,2NAA2N;CAC9N,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAqB,MAAM,CAAC,MAAM,CAAC;IAC/D,GAAG,OAAO;IACV,EAAE,EAAE,mBAAmB;IACvB,MAAM,EAAE,QAAQ;IAChB,WAAW,EAAE,eAAe;IAC5B,4EAA4E;IAC5E,0EAA0E;IAC1E,qCAAqC;IACrC,aAAa,EAAE,EAAE;IACjB,uBAAuB,EACrB,2NAA2N;CAC9N,CAAC,CAAC"}

package/dist/schema/dialects/lenient.d.ts

@@ -0,0 +1,4 @@
+import type { FormatDescriptor } from '../descriptor';
+/** Lenient descriptor — no rewrites, no closure, formats pass through. Default for unsupported models. */
+export declare const LENIENT: FormatDescriptor;
+//# sourceMappingURL=lenient.d.ts.map

package/dist/schema/dialects/lenient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lenient.d.ts","sourceRoot":"","sources":["../../../src/schema/dialects/lenient.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD,0GAA0G;AAC1G,eAAO,MAAM,OAAO,EAAE,gBAuBpB,CAAC"}

package/dist/schema/dialects/lenient.js

@@ -0,0 +1,26 @@
+/** Lenient descriptor — no rewrites, no closure, formats pass through. Default for unsupported models. */
+export const LENIENT = Object.freeze({
+    id: 'lenient',
+    family: 'lenient',
+    strict: false,
+    objectAllFieldsRequired: false,
+    objectClosedByDefault: false,
+    recordEncoding: 'open-record',
+    tupleEncoding: 'prefix-items',
+    allowAllOf: true,
+    allowAnyOf: true,
+    allowOneOf: true,
+    allowRootRef: true,
+    allowDefsRef: true,
+    emitPropertyOrdering: false,
+    supportedStringFormats: 'all',
+    allowPattern: true,
+    allowMultiplePatterns: true,
+    allowMinMaxLength: true,
+    allowMinMaxItems: true,
+    allowMinimumMaximum: true,
+    optionalAsNullable: false,
+    anyEncoding: 'recursive-open',
+    supportsRecursion: true,
+});
+//# sourceMappingURL=lenient.js.map

package/dist/schema/dialects/lenient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lenient.js","sourceRoot":"","sources":["../../../src/schema/dialects/lenient.ts"],"names":[],"mappings":"AAEA,0GAA0G;AAC1G,MAAM,CAAC,MAAM,OAAO,GAAqB,MAAM,CAAC,MAAM,CAAC;IACrD,EAAE,EAAE,SAAS;IACb,MAAM,EAAE,SAAS;IACjB,MAAM,EAAE,KAAK;IACb,uBAAuB,EAAE,KAAK;IAC9B,qBAAqB,EAAE,KAAK;IAC5B,cAAc,EAAE,aAAa;IAC7B,aAAa,EAAE,cAAc;IAC7B,UAAU,EAAE,IAAI;IAChB,UAAU,EAAE,IAAI;IAChB,UAAU,EAAE,IAAI;IAChB,YAAY,EAAE,IAAI;IAClB,YAAY,EAAE,IAAI;IAClB,oBAAoB,EAAE,KAAK;IAC3B,sBAAsB,EAAE,KAAK;IAC7B,YAAY,EAAE,IAAI;IAClB,qBAAqB,EAAE,IAAI;IAC3B,iBAAiB,EAAE,IAAI;IACvB,gBAAgB,EAAE,IAAI;IACtB,mBAAmB,EAAE,IAAI;IACzB,kBAAkB,EAAE,KAAK;IACzB,WAAW,EAAE,gBAAgB;IAC7B,iBAAiB,EAAE,IAAI;CACxB,CAAC,CAAC"}