import type { Tag, VariableType } from "../types.js";
import type { ObjectType } from "../types/typeHints.js";
/**
 * The registry of ALL built-in generic types — the container forms
 * (`Array`, `Schema`, `Record`) and the utility types (`Partial`,
 * `Required`, `Pick`, `Omit`, `NonNullable`, modeled on TypeScript and
 * adapted to Agency null-based optionality: `p?: V` desugars to
 * `p: V | null` at parse time; there is no undefined).
 *
 * Every form is evaluated EAGERLY: `evalBuiltinGeneric` runs during type
 * resolution (`resolveTypeWithGuard` in assignability.ts) and returns a
 * plain type — except `Record`, which keeps its `genericType` wrapper so
 * codegen can lower it to `z.record(...)`. Nothing downstream knows the
 * other forms exist. See
 * docs/superpowers/specs/2026-07-09-utility-types-design.md.
 *
 * Adding a built-in generic is one entry here: `BUILTIN_GENERIC_ARITY`
 * (consumed by validate.ts) and `RESERVED_GENERIC_NAMES` (consumed by
 * index.ts) are derived from the table.
 *
 * `reserved` controls whether users may declare a type alias with the
 * name. The five utility types are reserved (a user alias is a hard
 * error); `Array`/`Schema`/`Record` keep their historical behavior — a
 * user alias with those names is silently shadowed by the builtin, not
 * rejected. Flipping them to reserved would be a breaking change beyond
 * this feature.
 *
 * CYCLE RULE: this module must not import assignability.ts — the resolver
 * is injected as the `resolve` callback so alias arguments resolve with the
 * caller's in-progress guard (recursion degrades gracefully, see #470).
 */
type Resolve = (t: VariableType) => VariableType;
/**
 * Merge the use-site tags of a `Partial<...>` / `Pick<...>` occurrence onto
 * a transform's result. The result's own tags came from resolving the
 * ARGUMENT (alias-side per the `mergeTagSets` contract); the occurrence's
 * tags are the use-site layer and override on `@jsonSchema` key conflicts.
 */
export declare function withUseSiteTags(t: VariableType, useSiteTags: Tag[] | undefined): VariableType;
export declare function resolveObjectArg(name: string, arg: VariableType, resolve: Resolve): ObjectType;
/** K must resolve to a string literal or a union of string literals. */
export declare function resolveKeysArg(name: string, arg: VariableType, resolve: Resolve): string[];
/**
 * Derived view for validate.ts arity diagnostics. Null-prototype so bare
 * indexing with a user-controlled name ("toString", "constructor", ...)
 * misses instead of finding Object.prototype members — validate.ts indexes
 * this table directly.
 */
export declare const BUILTIN_GENERIC_ARITY: Record<string, number>;
/** The names users may not declare type aliases for (index.ts). */
export declare const RESERVED_GENERIC_NAMES: string[];
export declare function isBuiltinGenericName(name: string): boolean;
/**
 * Evaluate one built-in generic application. Throws TypeError on invalid
 * input. VERIFIED surfacing (same for all forms): at typecheck time
 * safeResolveType SWALLOWS the throw and the annotation degrades to `any`
 * with no diagnostic; the error becomes fatal at codegen when
 * resolveTypeDeep re-runs the resolver unwrapped. A pipeline test pins
 * this; located diagnostics are a spec follow-up. Arity is ALSO validated
 * as a located diagnostic via BUILTIN_GENERIC_ARITY (validate.ts); the
 * throw here is the resolver-level backstop.
 */
export declare function evalBuiltinGeneric(name: string, typeArgs: VariableType[], resolve: Resolve, useSiteTags?: Tag[]): VariableType;
export {};