@aeye/core 0.5.4 → 0.6.0

package/dist/schema.d.ts

@@ -1,840 +0,0 @@
-import z from 'zod';
-/**
- * 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' | (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'` to pass through. */
-    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 (Anthropic
-     *   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`).
-     *
-     * 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';
-    /** 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;
-    /**
-     * 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;
-/** Lenient descriptor — no rewrites, no closure, formats pass through. Default for unsupported models. */
-export declare const LENIENT: FormatDescriptor;
-/**
- * OpenAI strict — current behavior verbatim. Records→pairs,
- * 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` 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 declare const OPENAI_STRICT: FormatDescriptor;
-/** OpenAI non-strict — alias of LENIENT but tagged with the openai family. */
-export declare const OPENAI_NON_STRICT: FormatDescriptor;
-/**
- * Anthropic strict — Claude 4.5+ only (Opus 4.7/4.6/4.5, Sonnet 4.6/4.5,
- * Haiku 4.5). 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` so the cycle-breaker replaces the
- *   offending back-edge with the flat "any" shape (see `anyEncoding`) and
- *   leaves shared non-cyclic `$ref`s alone. 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.
- * - `prefixItems` and other positional tuple keywords are not in the
- *   supported list, so tuples collapse to a homogeneous `items: anyOf`.
- * - Supported formats include `uri` (unlike OpenAI strict). We pass all
- *   formats through and let Anthropic ignore unknowns.
- */
-export declare const ANTHROPIC_STRICT: FormatDescriptor;
-export declare const ANTHROPIC_NON_STRICT: FormatDescriptor;
-/**
- * Google Gemini strict — per `ai.google.dev/gemini-api/docs/structured-output`:
- *
- * - Supported keywords: types, `properties`, `required`, `additionalProperties`,
- *   `enum`, `format` (date-time/date/time only), `minimum`, `maximum`, `items`,
- *   `prefixItems`, `minItems`, `maxItems`, `title`, `description`,
- *   `propertyOrdering`. Recursion via `$ref: "#"` (root self-ref).
- * - Combinators (`allOf`, `anyOf`, `oneOf`) are NOT in the supported list;
- *   we conservatively flag them off so unions degrade to a representable form
- *   rather than emit something Gemini ignores.
- * - String constraints (`minLength`, `maxLength`, `pattern` formats beyond the
- *   three documented) are not supported.
- * - `propertyOrdering` is REQUIRED for Gemini 2.0 strict; we always emit it
- *   on object schemas under this descriptor.
- * - `z.any()` / `z.unknown()` uses the `unconstrained` encoding. Every other
- *   "any" encoding needs `anyOf` and/or a named `$defs/Any` — both of which
- *   this descriptor forbids two lines below — so the recursive `$defs/Any`
- *   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` 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 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 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;
-/**
- * Report the ways a `FormatDescriptor` contradicts itself — settings that ask
- * 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.
- *
- * This exists because a contradiction here is invisible until a provider
- * answers HTTP 400: `GOOGLE_STRICT` shipped with `allowAnyOf: false` +
- * `allowDefsRef: false` AND `anyEncoding: 'recursive-open'` (which needs
- * both), so every `z.any()` in a Gemini tool schema emitted exactly the
- * `anyOf` + `$defs/Any` shape the descriptor declared unrepresentable.
- * Nothing checked, so nothing caught it.
- *
- * Called by `registerDescriptor` (which warns) and asserted over every
- * built-in by the test suite.
- *
- * @example
- * ```ts
- * checkDescriptorConsistency(GOOGLE_STRICT);   // → []
- * checkDescriptorConsistency({ ...GOOGLE_STRICT, anyEncoding: 'flat' });
- * //  → ["anyEncoding 'flat' emits `anyOf`, but allowAnyOf is false"]
- * ```
- */
-export declare function checkDescriptorConsistency(descriptor: FormatDescriptor): string[];
-/**
- * Register a custom `FormatDescriptor` so it can be looked up by `id` or
- * by `(family, strict)`. Useful for adding support for a new provider
- * dialect or for registering a tweaked variant of an existing family.
- *
- * The descriptor's `id` and `family` become the lookup keys. If a
- * descriptor with the same id is already registered, the new one
- * replaces it. The family slot tracks one strict and one lenient
- * variant; registering a third variant overwrites the matching slot.
- *
- * Built-in descriptors (`OPENAI_STRICT`, `LENIENT`, etc.) are seeded at
- * module load — you don't need to register them manually. They CAN be
- * overridden by registering a same-id descriptor afterwards, but doing
- * so is generally a sign that you should pick a different id.
- *
- * @example
- * ```ts
- * import { registerDescriptor, OPENAI_STRICT } from '@aeye/core';
- *
- * // A tighter OpenAI-flavored descriptor: same wire shape but with
- * // pattern support disabled (some downstream tools choke on regex).
- * registerDescriptor({
- *   ...OPENAI_STRICT,
- *   id: 'openai-no-regex',
- *   family: 'openai-no-regex',
- *   allowPattern: false,
- *   allowMultiplePatterns: false,
- * });
- *
- * // Now resolvable:
- * getDescriptor('openai-no-regex', true);   // → the registered descriptor
- * getDescriptorById('openai-no-regex');     // → same
- * ```
- *
- * A descriptor that contradicts itself (see `checkDescriptorConsistency`) is
- * still registered — the caller may know something we don't — but each
- * problem is warned once at registration, because the alternative is finding
- * out from a provider's HTTP 400.
- */
-export declare function registerDescriptor(descriptor: FormatDescriptor): void;
-/**
- * Resolve a descriptor by family + strictness.
- *
- * Built-in families (`'openai'`, `'anthropic'`, `'google'`) always
- * resolve. Custom families registered via `registerDescriptor` resolve
- * once they're registered. Unknown families fall back to `LENIENT`
- * (safe default — strict mode silently degrades for unrecognized models).
- *
- * @param family - provider family (built-in or registered)
- * @param strict - whether the strict variant is wanted
- */
-export declare function getDescriptor(family: DescriptorFamily, strict: boolean): FormatDescriptor;
-/**
- * Look up a descriptor by id. Returns LENIENT for unknown ids (safe default).
- * Custom descriptors registered via `registerDescriptor` are reachable here
- * by their `id`.
- */
-export declare function getDescriptorById(id: string | undefined): FormatDescriptor;
-/**
- * True if `family` has at least one registered descriptor (strict or
- * lenient). Used by `@aeye/ai`'s `resolveStrictFormat` fallback chain to
- * decide whether a model id prefix or provider name is a recognized
- * dialect.
- */
-export declare function hasDescriptorFamily(family: string | undefined): boolean;
-/**
- * Resolve descriptor from various input shapes (boolean, options object, or descriptor).
- * Used by `toJSONSchema` to support its overloaded signature.
- */
-export declare function resolveDescriptor(input: FormatDescriptor | ToJSONSchemaOptions | boolean | undefined): FormatDescriptor;
-/**
- * Decide whether `schema` can be expressed as structured output under
- * `descriptor`'s JSON-Schema dialect. Returns `false` when the schema uses a
- * construct the descriptor forbids, so the caller can DROP the wire schema and
- * deliver it as prompt text instead (see the ai-layer
- * `applySchemaDeliveryFallback`).
- *
- * Walks the Zod schema in the same style as `strictify`/`convert`, honoring:
- * - **unions** (`z.union` / `z.discriminatedUnion` → `anyOf`) when
- *   `!descriptor.allowAnyOf` (e.g. Gemini strict rejects `anyOf`);
- * - **intersections** (`z.intersection` → `allOf`) when `!descriptor.allowAllOf`;
- * - **recursion** (a self-referential `z.lazy` cycle → `$ref`): a cycle back to
- *   the ROOT is fine when `descriptor.allowRootRef && descriptor.supportsRecursion`
- *   (Gemini supports `$ref: '#'`); a non-root cycle needs
- *   `descriptor.allowDefsRef && descriptor.supportsRecursion`.
- *
- * `ZodNullable` / `ZodOptional` are transparent wrappers here (nullability is
- * NOT treated as a union), so only genuine `z.union(...)` trips `allowAnyOf`.
- * Non-combinator, non-recursive schemas (plain objects, arrays, primitives)
- * are always expressible. The structure mirrors the descriptor flags so more
- * feasibility checks are easy to add.
- */
-export declare function canExpress(schema: z.ZodType | z.core.$ZodType, descriptor: FormatDescriptor): boolean;
-/**
- * Recursively transforms a Zod schema to a target dialect.
- *
- * For LENIENT, returns the input schema unchanged (no rewrites). For strict
- * descriptors, installs preprocesses that accept the dialect's wire shape
- * (e.g. array-of-pairs records, numeric-key tuple objects) and normalize them
- * back to the natural Zod shape before validation.
- *
- * Repeated calls with the same `(schema, descriptor)` return the cached
- * transformed schema. Different descriptors share the same outer entry but
- * map to different inner values — bounded by the small descriptor count.
- *
- * @param schema - input Zod schema
- * @param descriptor - target dialect descriptor (defaults to OPENAI_STRICT)
- */
-export declare function strictify<S extends z.ZodType>(schema: S, descriptor?: FormatDescriptor): S;
-/**
- * Produce a NON-FAILING variant of `schema` that keeps every transform
- * (`preprocess`, `codec`, `pipe`, `transform`) but drops validation. Parsing
- * a wire value through the result runs the decode preprocesses installed by
- * `strictify` (array-of-pairs → record, numeric-key object → tuple, null →
- * undefined) and yields the conceptual value, without ever rejecting.
- *
- * Recursion (`z.lazy` self-reference) is handled with a per-call memo map: an
- * in-flight node is recorded as a thunk and re-encounters resolve to
- * `z.lazy(thunk)`, so a self-referential schema relaxes in finite time and
- * never infinite-loops.
- */
-export declare function relaxValidation(schema: z.ZodType): z.ZodType;
-/**
- * DECODE a model's wire `value` back to the conceptual shape a custom parser
- * expects — symmetric with how `strictify` ENCODEs the request for the wire.
- *
- * Runs the descriptor's decode transforms (via `relaxValidation(strictify(...))`)
- * without imposing validation, so array-of-pairs records, numeric-key tuples,
- * and null-for-optional fields are normalized before a provider-agnostic
- * custom parser sees them. Best-effort: NEVER throws — if the relaxed decoder
- * can't parse the value it is returned unchanged.
- *
- * @param schema - the PRE-strictify conceptual schema (strictify runs internally)
- * @param value - the model's raw wire value (already `JSON.parse`d)
- * @param descriptor - the wire dialect the request was encoded with
- */
-export declare function decodeWire(schema: z.ZodType, value: unknown, descriptor: FormatDescriptor): unknown;
-/**
- * Format specification for JSON Schema generation
- */
-/**
- * Family name for `ToJSONSchemaOptions.format`. Alias of `DescriptorFamily`
- * — the three built-in dialects (`'openai'`, `'anthropic'`, `'google'`)
- * plus any string registered via `registerDescriptor`.
- *
- * @deprecated Prefer `DescriptorFamily`. Both refer to the same widened type.
- */
-export type JSONSchemaFormat = DescriptorFamily;
-/**
- * Options for toJSONSchema
- */
-export interface ToJSONSchemaOptions {
-    /**
-     * Whether to use strict mode (all fields required, additionalProperties: false)
-     */
-    strict: boolean;
-    /**
-     * The target format for the JSON Schema. Resolves to a named FormatDescriptor.
-     * Built-in (`'openai'` / `'anthropic'` / `'google'`) or any string
-     * registered via `registerDescriptor`.
-     */
-    format?: DescriptorFamily;
-}
-export type JSONSchemaType = 'string' | 'number' | 'boolean' | 'array' | 'object' | 'null' | 'integer';
-/**
- * JSON Schema type definition
- */
-export interface JSONSchema {
-    type?: JSONSchemaType | JSONSchemaType[];
-    properties?: Record<string, JSONSchema>;
-    items?: JSONSchema;
-    prefixItems?: JSONSchema[];
-    required?: string[];
-    additionalProperties?: boolean | JSONSchema;
-    propertyNames?: JSONSchema;
-    enum?: any[];
-    anyOf?: JSONSchema[];
-    allOf?: JSONSchema[];
-    additionalItems?: boolean | JSONSchema;
-    not?: JSONSchema;
-    $ref?: string;
-    description?: string;
-    default?: any;
-    pattern?: string;
-    format?: string;
-    minimum?: number;
-    maximum?: number;
-    exclusiveMinimum?: number;
-    exclusiveMaximum?: number;
-    multipleOf?: number;
-    minItems?: number;
-    maxItems?: number;
-    const?: any;
-    title?: string;
-    $defs?: Record<string, JSONSchema>;
-    /** Gemini-specific: deterministic property emission order for strict mode. */
-    propertyOrdering?: string[];
-    [metadata: string]: unknown;
-}
-/**
- * Converts a Zod schema to JSON Schema with support for different provider dialects.
- *
- * Accepts either a boolean (legacy: true = OPENAI_STRICT, false = LENIENT),
- * an options object `{ strict, format? }`, or a `FormatDescriptor` directly.
- *
- * @param schema - The Zod schema to convert
- * @param options - Configuration options for the conversion
- * @returns JSON Schema object compatible with the resolved dialect
- *
- * @example
- * ```typescript
- * const schema = z.object({
- *   name: z.string(),
- *   age: z.number().optional(),
- * });
- *
- * // For OpenAI strict mode
- * const jsonSchema = toJSONSchema(schema, { strict: true, format: 'openai' });
- *
- * // For Anthropic strict mode
- * const anthropic = toJSONSchema(schema, ANTHROPIC_STRICT);
- * ```
- */
-export declare function toJSONSchema(schema: z.ZodType, options: ToJSONSchemaOptions | boolean | FormatDescriptor): JSONSchema;
-/**
- * One emitted `enum` node's contribution to a dialect's size limits. A dialect
- * bounds the TOTAL number of enum values in a schema and, separately, the
- * character length of a SINGLE large enum — so the per-enum breakdown has to
- * survive the walk; a pair of totals cannot answer the second question
- * (two enums, one long-valued and one many-valued, would answer it wrongly).
- */
-export interface EnumFeature {
-    /** How many members the enum emits. */
-    readonly valueCount: number;
-    /**
-     * Total character length of its STRING members. Non-string members
-     * contribute nothing: the character rules are written for string values.
-     */
-    readonly stringValueChars: number;
-}
-/**
- * Structural feature counts for a Zod schema, used by the SchemaBudget to
- * decide whether an item fits a descriptor's per-request budget, whether it
- * fits the dialect's per-schema size limits, and whether the descriptor can
- * express it at all.
- */
-export interface SchemaFeatures {
-    /** True if the schema (or any subschema) uses `z.lazy` / self-recursion. */
-    hasRecursion: boolean;
-    /** Count of `z.optional()` leaves anywhere in the schema. */
-    optionalParameterCount: number;
-    /**
-     * Count of union-shaped nodes — `z.union`, `z.discriminatedUnion`, plus
-     * `z.nullable` (which on the wire under OpenAI strict becomes a type
-     * array `[T, "null"]`, also counts toward Anthropic's union-type budget).
-     */
-    unionTypeCount: number;
-    /** Count of `z.record` nodes. */
-    recordCount: number;
-    /** Count of `z.tuple` nodes. */
-    tupleCount: number;
-    /** One entry per emitted `enum` node, in walk order. */
-    enums: readonly EnumFeature[];
-    /**
-     * Object properties the schema emits, summed over every nesting level. A
-     * record counts as the 2 properties its widest encoding emits
-     * (`{key, value}` pairs) and a tuple as one per item (numeric-key
-     * encoding) — the count is descriptor-independent, so it takes the largest
-     * encoding any dialect could choose (see `schemaSizeLimits`).
-     */
-    objectPropertyCount: number;
-    /** Deepest container nesting below the root (an object of scalars is 1). */
-    maxNestingDepth: number;
-    /**
-     * Total characters over property names plus `enum` and `const` string
-     * values — the "total string size" a dialect bounds. `$defs` entry names are
-     * NOT included: they are generated at emit time, are few, and are short
-     * relative to a 120,000-character budget.
-     */
-    stringSizeChars: number;
-}
-/**
- * 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 declare function analyzeSchema(schema: z.ZodType | z.core.$ZodType): SchemaFeatures;
-/**
- * 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 declare function checkSchemaSizeLimits(schema: z.ZodType | z.core.$ZodType, descriptor: FormatDescriptor): readonly string[];
-/**
- * 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 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
- * strict for `requested === true` (subject only to feasibility, not budget;
- * if `true` items overflow the budget the API call will fail, which is the
- * correct behavior for hard requirements).
- *
- * Numeric `strict: <priority>` items are allocated greedily after `true`
- * items have consumed their share of the budget. Caller is expected to
- * pre-sort by descending priority before iterating.
- */
-export declare class SchemaBudget {
-    private readonly 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`.
-     */
-    private readonly degraded;
-    private remainingTools;
-    private remainingOptionalParams;
-    private remainingUnionTypes;
-    constructor(descriptor: FormatDescriptor);
-    /**
-     * 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 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 and size)
-     *
-     * Returns the strict descriptor (and decrements the budget) otherwise.
-     */
-    allocateTool(schema: z.ZodType | z.core.$ZodType, requested: boolean | number | undefined): FormatDescriptor;
-    /**
-     * Same as `allocateTool` but for the request's structured-output schema.
-     * The output schema doesn't consume a tool slot but it does count toward
-     * the optional-parameter and union-type budgets — descriptors document
-     * those limits as "across all strict schemas in one request".
-     */
-    allocateOutput(schema: z.ZodType | z.core.$ZodType, requested: boolean | number | undefined): FormatDescriptor;
-    /** Snapshot of remaining budget. Useful for telemetry / debug logs. */
-    remaining(): {
-        strictTools: number;
-        optionalParams: number;
-        unionTypes: number;
-    };
-    private allocate;
-}
-/**
- * Compare two descriptors and return the one with the tighter per-request
- * budget. Used by providers to pick a single descriptor for a 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 declare function strictestOf(a: FormatDescriptor, b: FormatDescriptor): FormatDescriptor;
-/**
- * Convert a `boolean | number | undefined` strict request into a numeric
- * priority for sorting. Used by providers to allocate strict slots in
- * descending priority order.
- *
- * - `true` → `+Infinity` (hard requirement; always first in line)
- * - `false` → `-Infinity` (always lenient; never wants strict)
- * - `number > 0` → the number itself
- * - `number <= 0` or `undefined` → `0` (no preference)
- */
-export declare function strictPriority(requested: boolean | number | undefined): number;
-//# sourceMappingURL=schema.d.ts.map