@sembl/core 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,1165 @@
+/**
+ * Bounds a field's value beyond its type.
+ *
+ * Which keys apply depends on the value being checked, not on the declared
+ * field type: string bounds apply to strings, numeric bounds to numbers, and
+ * item bounds to arrays. On an array field the string/number bounds apply to
+ * each element, so `string[]` can carry both `maxItems` and `maxLength`.
+ */
+interface FieldConstraints {
+    /** Maximum string length, inclusive */
+    maxLength?: number;
+    /** Minimum string length, inclusive */
+    minLength?: number;
+    /** Minimum numeric value, inclusive */
+    minimum?: number;
+    /** Maximum numeric value, inclusive */
+    maximum?: number;
+    /** Minimum number of array entries, inclusive */
+    minItems?: number;
+    /** Maximum number of array entries, inclusive */
+    maxItems?: number;
+    /** Regular expression source a string value must match */
+    pattern?: string;
+}
+/**
+ * Describes the type of a schema field.
+ *
+ * `enum` values are fixed when the schema is compiled. `dynamicEnum` defers
+ * them to coercion time, naming a source the caller resolves — for value sets
+ * that live in a database or CMS rather than in the source tree.
+ */
+type FieldType = {
+    kind: "string";
+} | {
+    kind: "number";
+} | {
+    kind: "boolean";
+} | {
+    kind: "array";
+    items: FieldType;
+} | {
+    kind: "object";
+    nestedSchemaId: string;
+} | {
+    kind: "enum";
+    values: string[];
+} | {
+    kind: "dynamicEnum";
+    sourceId: string;
+};
+/**
+ * Describes a single field in a schema.
+ */
+interface FieldDescriptor {
+    /** Property name as it appears in the class */
+    name: string;
+    /** Semantic description from @Describe decorator */
+    description: string;
+    /** The resolved type of this field */
+    type: FieldType;
+    /** Whether this field is required (definite assignment) */
+    required: boolean;
+    /** Value bounds from the @Constrain decorator, if any */
+    constraints?: FieldConstraints;
+}
+/**
+ * A compiled runtime schema representing a decorated class.
+ */
+interface RuntimeSchema {
+    /** Unique identifier, typically the class name */
+    id: string;
+    /** Semantic description from @Schema decorator */
+    description: string;
+    /** All fields extracted from the class */
+    fields: FieldDescriptor[];
+}
+/**
+ * A bundle of all schemas extracted from a set of source files.
+ */
+interface SchemaBundle {
+    /** Map of schema ID to RuntimeSchema */
+    schemas: Record<string, RuntimeSchema>;
+}
+
+/**
+ * Supplies the legal values for a `dynamicEnum` source at coercion time.
+ *
+ * Sources are opaque to SEMBL: the id is whatever the schema author wrote in
+ * `@ValuesFrom("...")`, and the caller decides how to turn it into values (a
+ * CMS fetch, a database query, a static map). Called at most once per distinct
+ * source id per coercion; the caller owns any caching across coercions.
+ *
+ * ```ts
+ * const enumResolver: EnumResolver = async (sourceId) => {
+ *   const docs = await cms.taxonomy(sourceId);
+ *   return docs.map((d) => d.slug);
+ * };
+ * ```
+ */
+type EnumResolver = (sourceId: string) => readonly string[] | Promise<readonly string[]>;
+/**
+ * The legal values for every enum source that resolved successfully,
+ * keyed by source id.
+ *
+ * A source id absent from this map is *unresolved* — the field it backs falls
+ * back to a free-form string. Successful resolution always yields a non-empty
+ * array; an empty result is treated as a failure, not as "no legal values",
+ * because a field with zero legal values is unsatisfiable.
+ */
+type ResolvedEnums = Readonly<Record<string, readonly string[]>>;
+
+type JsonSchema = Record<string, unknown>;
+/**
+ * Which flavour of JSON Schema to emit.
+ *
+ * - `"openai-strict"` — the subset OpenAI structured outputs accepts.
+ * - `"standard"` — ordinary JSON Schema, for validators and other providers.
+ */
+type JsonSchemaDialect = "openai-strict" | "standard";
+/**
+ * Options for JSON Schema generation.
+ */
+interface JsonSchemaOptions {
+    /** Legal values for dynamic enum sources, from `resolveEnumSources` */
+    resolvedEnums?: ResolvedEnums;
+    /** Target dialect. Defaults to `"openai-strict"`. */
+    dialect?: JsonSchemaDialect;
+}
+/**
+ * Convert a RuntimeSchema to a JSON Schema object.
+ *
+ * Under `"openai-strict"`, every property is listed in `required` and an
+ * optional field becomes `anyOf: [T, null]`, as structured outputs demand.
+ * Under `"standard"`, only genuinely required fields are listed and optional
+ * ones are simply absent — which is what keeps an unmentioned field
+ * distinguishable from one the model explicitly nulled.
+ *
+ * Both dialects inline nested schemas (no `$ref`) and set
+ * `additionalProperties: false`. Dynamic enum fields become a string `enum`
+ * when their source resolved, and a plain string otherwise. FieldConstraints
+ * are emitted only in `"standard"` — see {@link CONSTRAINT_KEYWORDS}.
+ */
+declare function runtimeSchemaToJsonSchema(schema: RuntimeSchema, bundle?: SchemaBundle, options?: JsonSchemaOptions): JsonSchema;
+/**
+ * Wrap a RuntimeSchema as a top-level JSON Schema suitable for
+ * OpenAI's response_format.json_schema.schema parameter.
+ */
+declare function toOpenAIJsonSchema(schema: RuntimeSchema, bundle?: SchemaBundle, options?: Omit<JsonSchemaOptions, "dialect">): JsonSchema;
+
+/**
+ * An enum source that could not be turned into a usable set of legal values.
+ */
+interface EnumSourceFailure {
+    /** The source id that failed */
+    sourceId: string;
+    /** Why it failed: the resolver threw, or it produced no values */
+    reason: "threw" | "empty";
+    /** The thrown value, when `reason` is "threw" */
+    cause?: unknown;
+    /**
+     * Whether a required field depends on this source. A field counts as
+     * required only if every object on the path to it is also required — an
+     * unreachable field cannot make a coercion fail.
+     */
+    required: boolean;
+    /** Field paths that reference this source, for error messages */
+    paths: string[];
+}
+/**
+ * The outcome of resolving every enum source a schema reaches.
+ */
+interface EnumResolution {
+    /** Legal values for each source that resolved successfully */
+    enums: ResolvedEnums;
+    /** Sources that threw or produced nothing */
+    failures: EnumSourceFailure[];
+}
+/** How a single enum source is reached from the root schema. */
+interface EnumSourceUsage {
+    /** Whether the source is reachable through an unbroken chain of required fields */
+    required: boolean;
+    /** Field paths that reference this source */
+    paths: string[];
+}
+/**
+ * Collect the distinct dynamic enum source ids a schema reaches, directly or
+ * through its bundle, along with whether each is reachable through a chain of
+ * required fields.
+ */
+declare function collectEnumSources(schema: RuntimeSchema, bundle?: SchemaBundle): Map<string, EnumSourceUsage>;
+/**
+ * Resolve every dynamic enum source a schema reaches, calling `resolver` once
+ * per distinct source id and awaiting all of them concurrently.
+ *
+ * Resolution never throws on the caller's behalf. A source whose resolver
+ * throws, or which yields no values, is reported in `failures` and left out of
+ * `enums` — downstream that means the field widens to a free-form string.
+ * Widening a *required* field is a silent correctness hole, so callers are
+ * expected to treat a failure with `required: true` as fatal; `coerce` and
+ * `partialCoerce` do exactly that.
+ */
+declare function resolveEnumSources(schema: RuntimeSchema, resolver: EnumResolver, bundle?: SchemaBundle): Promise<EnumResolution>;
+
+/**
+ * Registry for looking up compiled RuntimeSchemas by ID.
+ */
+declare class SchemaRegistry {
+    private schemas;
+    /**
+     * Register a single schema.
+     */
+    register(schema: RuntimeSchema): void;
+    /**
+     * Register all schemas from a bundle.
+     */
+    registerBundle(bundle: SchemaBundle): void;
+    /**
+     * Look up a schema by ID.
+     */
+    get(id: string): RuntimeSchema | undefined;
+    /**
+     * Get a schema by ID, throwing if not found.
+     */
+    require(id: string): RuntimeSchema;
+    /**
+     * Get a SchemaBundle of all registered schemas.
+     */
+    toBundle(): SchemaBundle;
+    /**
+     * Get all registered schema IDs.
+     */
+    ids(): string[];
+}
+
+/**
+ * A field under construction. `T` is the TypeScript type a coerced value
+ * will have; `Required` is whether the model must supply it.
+ *
+ * Builders are immutable: every method returns a new one, so a builder can be
+ * reused across schemas.
+ */
+interface FieldBuilder<T, Required extends boolean = true> {
+    /** Phantom carrier for `T`; never set at runtime. */
+    readonly __type?: T;
+    readonly type: FieldType;
+    readonly description: string;
+    readonly required: Required;
+    readonly constraints?: FieldConstraints;
+    /** Nested schemas this field's type refers to, keyed by id. */
+    readonly schemas: Readonly<Record<string, RuntimeSchema>>;
+    /** The model may leave this field out. */
+    optional(): FieldBuilder<T, false>;
+    /**
+     * Wrap the type in an array. String and number bounds already on the
+     * builder apply to each element, exactly as they do for a decorated
+     * `string[]`; item-count bounds go here.
+     */
+    array(constraints?: FieldConstraints): FieldBuilder<T[], Required>;
+    /** Replace the description. */
+    describe(description: string): FieldBuilder<T, Required>;
+    /** Add bounds, merged over any already set. */
+    constrain(constraints: FieldConstraints): FieldBuilder<T, Required>;
+    /** The descriptor this builder produces under a given name. */
+    toDescriptor(name: string): FieldDescriptor;
+}
+/**
+ * A schema built at runtime. It *is* a `RuntimeSchema`, so it goes anywhere
+ * one is accepted, and it also carries the bundle of every schema it refers
+ * to (itself included), which the coercion functions use when no bundle is
+ * passed explicitly.
+ */
+interface DefinedSchema<T> extends RuntimeSchema {
+    /** Phantom carrier for `T`; never set at runtime. */
+    readonly __type?: T;
+    readonly bundle: SchemaBundle;
+}
+/** The TypeScript type of a defined schema or a field builder. */
+type Infer<S> = S extends DefinedSchema<infer T> ? T : S extends FieldBuilder<infer T, boolean> ? T : never;
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type FieldValue<B> = B extends FieldBuilder<infer T, boolean> ? T : never;
+type RequiredKeys<F> = {
+    [K in keyof F]: F[K] extends FieldBuilder<unknown, true> ? K : never;
+}[keyof F];
+type OptionalKeys<F> = {
+    [K in keyof F]: F[K] extends FieldBuilder<unknown, false> ? K : never;
+}[keyof F];
+/** The object type a set of field builders describes. */
+type InferFields<F> = Simplify<{
+    [K in RequiredKeys<F>]: FieldValue<F[K]>;
+} & {
+    [K in OptionalKeys<F>]?: FieldValue<F[K]>;
+}>;
+/**
+ * Field builders. Each takes the field's description first — the semantics
+ * are the point — and returns a required field; call `.optional()` to let
+ * the model leave it out.
+ */
+declare const field: {
+    string(description: string, constraints?: FieldConstraints): FieldBuilder<string, true>;
+    number(description: string, constraints?: FieldConstraints): FieldBuilder<number, true>;
+    boolean(description: string): FieldBuilder<boolean, true>;
+    /** A closed set of string values known at build time. */
+    enum<const V extends string>(values: readonly V[], description: string): FieldBuilder<V, true>;
+    /**
+     * A closed set of string values resolved at coercion time from a named
+     * source — the runtime equivalent of `@ValuesFrom`.
+     */
+    valuesFrom(sourceId: string, description: string, constraints?: FieldConstraints): FieldBuilder<string, true>;
+    /** A nested object shaped by another defined schema. */
+    object<S extends DefinedSchema<unknown>>(schema: S, description: string): FieldBuilder<Infer<S>, true>;
+    /** An array of whatever another builder describes; same as `item.array()`. */
+    array<T, R extends boolean>(item: FieldBuilder<T, R>, constraints?: FieldConstraints): FieldBuilder<T[], R>;
+};
+/**
+ * Define a schema at runtime, without decorators or a compile step.
+ *
+ * Produces exactly what `sembl extract` would emit for the equivalent
+ * decorated class — the same descriptors in the same order — so the two ways
+ * of defining a schema are interchangeable. The result carries a bundle of
+ * every schema it refers to, so nested objects work without assembling one
+ * by hand.
+ *
+ * ```ts
+ * const Address = defineSchema("Address", "Where a property is.", {
+ *   city: field.string("City or municipality."),
+ *   zip: field.string("Postal code.").optional(),
+ * });
+ * const Listing = defineSchema("Listing", "A short-term rental listing.", {
+ *   name: field.string("Display name.", { maxLength: 40 }),
+ *   amenities: field.valuesFrom("amenities", "What the property offers.").array({ maxItems: 5 }),
+ *   address: field.object(Address, "Where the property is.").optional(),
+ * });
+ * type Listing = Infer<typeof Listing>;
+ * ```
+ */
+declare function defineSchema<F extends Record<string, FieldBuilder<unknown, boolean>>>(id: string, description: string, fields: F): DefinedSchema<InferFields<F>>;
+/** The bundle a schema carries, when it was made by {@link defineSchema}. */
+declare function bundleOf(schema: RuntimeSchema): SchemaBundle | undefined;
+
+/**
+ * Class decorator marking a schema class with a semantic description.
+ * No-op at runtime — parsed by the compiler from source AST.
+ */
+declare function Schema(description: string): ClassDecorator;
+/**
+ * Property decorator providing a field-level semantic description.
+ * No-op at runtime — parsed by the compiler from source AST.
+ */
+declare function Describe(description: string): PropertyDecorator;
+/**
+ * Property decorator bounding a field's legal values — lengths, numeric
+ * ranges, array sizes, a pattern.
+ *
+ * Takes an object literal of compile-time constants; the compiler reads it
+ * from source, so computed expressions are not supported.
+ *
+ * ```ts
+ * @Describe("Display name for the listing.")
+ * @Constrain({ maxLength: 40 })
+ * name!: string;
+ * ```
+ *
+ * No-op at runtime — parsed by the compiler from source AST.
+ */
+declare function Constrain(constraints: FieldConstraints): PropertyDecorator;
+/**
+ * Property decorator declaring that a field's legal values come from a named
+ * source resolved at coercion time rather than from the source tree — a CMS
+ * taxonomy, a database enum table.
+ *
+ * Applies to a string field or to the element type of a string array. The
+ * caller supplies an `EnumResolver` that maps `sourceId` to the legal values.
+ *
+ * ```ts
+ * @Describe("Amenities the property offers.")
+ * @ValuesFrom("amenities")
+ * amenities!: string[];
+ * ```
+ *
+ * No-op at runtime — parsed by the compiler from source AST.
+ */
+declare function ValuesFrom(sourceId: string): PropertyDecorator;
+
+/**
+ * Recursively makes all properties optional, including nested objects.
+ */
+type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends (infer U)[] ? DeepPartial<U>[] : T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+
+/**
+ * Describes a single validation issue on a field.
+ */
+interface FieldValidationIssue {
+    /** Dot-separated path to the field, e.g. "address.city" */
+    path: string;
+    /** What went wrong */
+    message: string;
+    /** The value that was received, if any */
+    received?: unknown;
+}
+/**
+ * Error thrown when coercion validation fails.
+ */
+declare class CoerceError extends Error {
+    readonly issues: FieldValidationIssue[];
+    constructor(issues: FieldValidationIssue[]);
+}
+
+/**
+ * Error thrown when an enum source backing a required field could not be
+ * resolved.
+ *
+ * Falling back to a free-form string here would let the model invent values
+ * that pass coercion and fail downstream, so a required field with a dead
+ * taxonomy is a hard failure rather than a widening.
+ */
+declare class EnumResolutionError extends Error {
+    readonly failures: EnumSourceFailure[];
+    constructor(failures: EnumSourceFailure[]);
+}
+
+/**
+ * Configuration for a provider.
+ */
+interface ProviderConfig {
+    /** Model identifier, e.g. "gpt-4o" */
+    model: string;
+    /** Optional temperature override (0-2) */
+    temperature?: number;
+    /** Optional max tokens for the response */
+    maxTokens?: number;
+}
+/**
+ * Request sent to a provider for structured output.
+ */
+interface ProviderRequest {
+    /** System prompt with semantic context */
+    systemPrompt: string;
+    /** User input to coerce */
+    userInput: string;
+    /** JSON Schema for structured output */
+    jsonSchema: Record<string, unknown>;
+    /** The runtime schema being targeted */
+    schema: RuntimeSchema;
+    /**
+     * Bundle used to resolve nested schemas, when one was supplied.
+     *
+     * `jsonSchema` above is already built against this bundle in the
+     * OpenAI-strict dialect. Providers whose API wants a different dialect
+     * should re-derive from `schema` + `bundle` rather than reaching for
+     * `schema` alone — dropping the bundle silently emits nested objects with
+     * no properties.
+     */
+    bundle?: SchemaBundle;
+    /**
+     * Legal values for the schema's `dynamicEnum` sources, already resolved.
+     * A provider that re-derives its own JSON Schema must pass these along —
+     * dropping them silently widens those fields back to free-form strings.
+     */
+    resolvedEnums?: ResolvedEnums;
+}
+/**
+ * Token accounting for a single provider call.
+ *
+ * The cache fields are reported as the provider reports them, and providers
+ * disagree about whether cached tokens also appear in `promptTokens` — so read
+ * them as an effectiveness signal, not as terms to add up. Each provider's
+ * README states which convention it follows.
+ */
+interface ProviderUsage {
+    /** Input tokens, as the provider counts them. */
+    promptTokens: number;
+    /** Output tokens generated. */
+    completionTokens: number;
+    /** `promptTokens + completionTokens`. */
+    totalTokens: number;
+    /**
+     * Input tokens served from a prompt cache, when the provider reports it.
+     * Growing to cover the stable prefix across a batch is the signal that
+     * caching is working; a run of zeroes means it is not.
+     */
+    cacheReadTokens?: number;
+    /**
+     * Input tokens written to a prompt cache, when the provider reports it.
+     * Expect this on the first call of a batch and near zero afterwards; a
+     * write on every call means the cached prefix is being invalidated.
+     */
+    cacheWriteTokens?: number;
+}
+/**
+ * Response from a provider.
+ */
+interface ProviderResponse {
+    /** The parsed structured output */
+    data: Record<string, unknown>;
+    /** Raw response metadata for tracing */
+    usage?: ProviderUsage;
+}
+/**
+ * Interface that LLM providers must implement.
+ */
+interface Provider {
+    /**
+     * Send a structured output request to the LLM.
+     */
+    complete(request: ProviderRequest): Promise<ProviderResponse>;
+}
+
+/**
+ * A discrete event within a trace span.
+ */
+interface TraceEvent {
+    /** Event name */
+    name: string;
+    /** Timestamp */
+    timestamp: number;
+    /** Arbitrary attributes */
+    attributes?: Record<string, unknown>;
+}
+/**
+ * A span representing a unit of work in the coercion pipeline.
+ */
+interface TraceSpan {
+    /** Unique span ID */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Start timestamp */
+    startTime: number;
+    /** End timestamp (set when span completes) */
+    endTime?: number;
+    /** Events recorded during this span */
+    events: TraceEvent[];
+    /** Arbitrary attributes */
+    attributes?: Record<string, unknown>;
+    /** Parent span ID, if nested */
+    parentId?: string;
+}
+/**
+ * Sink that receives completed trace spans.
+ */
+interface TraceSink {
+    /** Called when a span is completed */
+    write(span: TraceSpan): void;
+}
+/**
+ * Context for tracing within a coercion call.
+ */
+interface TraceContext {
+    /** Start a new span */
+    startSpan(name: string, attributes?: Record<string, unknown>): TraceSpan;
+    /** End a span and dispatch to sinks */
+    endSpan(span: TraceSpan): void;
+    /** Add an event to the current span */
+    addEvent(span: TraceSpan, name: string, attributes?: Record<string, unknown>): void;
+}
+
+/**
+ * One piece of input to extract from.
+ *
+ * A label names where the text came from — "Airbnb listing", "Broker email" —
+ * so the model can tell sources apart and provenance can say which one a
+ * value was read from. Labels are optional for a single source and are filled
+ * in as "Source 1", "Source 2", … when several are given without them.
+ */
+interface Source {
+    /** Where the text came from, for the model and for provenance. */
+    label?: string;
+    /** The text itself. */
+    text: string;
+}
+/**
+ * What a coercion accepts as input: a plain string, one labelled source, or
+ * several. Everything is normalised to a `Source[]` before it reaches the
+ * prompt, so the three forms behave identically.
+ */
+type CoerceInput = string | Source | readonly Source[];
+/** Whether a value has the shape of a {@link Source}. */
+declare function isSource(value: unknown): value is Source;
+/** Whether a value is any of the accepted input forms. */
+declare function isCoerceInput(value: unknown): value is CoerceInput;
+/**
+ * Normalise input to a list of sources, labelling every entry when there is
+ * more than one so each can be referred to unambiguously.
+ *
+ * Throws for an empty list: there is nothing to extract from, and a silent
+ * empty prompt would only produce a confident hallucination.
+ */
+declare function toSources(input: CoerceInput): Source[];
+/**
+ * Render sources as the user message: each one inside its own delimited
+ * block, with its label as an attribute when it has one.
+ *
+ * The delimiters are the whole point. They let the system prompt say "what
+ * is inside these tags is data, not instructions", which is what makes a
+ * scraped page reading "ignore previous instructions" inert.
+ */
+declare function renderSources(sources: readonly Source[]): string;
+/**
+ * How the system prompt explains the framing to the model.
+ *
+ * Stated as a rule about where instructions can come from rather than as a
+ * list of attacks to watch for: the model does not need to recognise an
+ * injection, only to know that nothing inside a source block can be one.
+ */
+declare const SOURCE_INSTRUCTIONS: string;
+
+/**
+ * Which part of an over-budget source to cut.
+ *
+ * - `"tail"` keeps the beginning. The default: most documents lead with what
+ *   matters, and structured front-matter (a title, JSON-LD) sits there.
+ * - `"head"` keeps the end, for logs and transcripts where the latest text
+ *   is the relevant part.
+ * - `"middle"` keeps both ends and cuts the middle, for pages that open with
+ *   a summary and close with the details.
+ */
+type TruncatePolicy = "tail" | "head" | "middle";
+/** What was cut from one source. */
+interface TruncationRecord {
+    /** The source's label, when it had one. */
+    label?: string;
+    /** Characters before the cut. */
+    originalLength: number;
+    /** Characters after it, marker included. */
+    keptLength: number;
+}
+/** The sources after budgeting, and what happened to them. */
+interface BudgetResult {
+    sources: Source[];
+    /** One record per source that was cut. Empty when everything fit. */
+    truncated: TruncationRecord[];
+}
+/**
+ * Fit a set of sources into a character budget.
+ *
+ * The budget covers the sources' text as a whole. When they exceed it, it is
+ * shared out so that every source that fits within an equal share keeps all
+ * of its text, and what those leave unused goes to the longer ones. A short
+ * email next to a long scraped page is therefore never touched; the page
+ * takes the whole cut. A cut is marked in place with how much was omitted,
+ * so the model knows the text is incomplete rather than reading a
+ * mid-sentence stop as the end.
+ */
+declare function budgetSources(sources: readonly Source[], maxChars: number, policy?: TruncatePolicy): BudgetResult;
+
+/**
+ * What to do with a present field that fails validation.
+ *
+ * - `"throw"` — the whole coercion fails with a `CoerceError`. The default.
+ * - `"drop"` — remove the offending value and carry on. What gets removed is
+ *   the smallest thing that can go: an array element, an optional field, or
+ *   (in a partial coercion) any top-level field. A violation that only a
+ *   required field can absorb is not droppable and still throws.
+ * - `"clamp"` — where a bound makes a clamp meaningful (`maxLength`,
+ *   `minimum`, `maximum`, `maxItems`), cut the value down to the bound; where
+ *   it does not (a type mismatch, a bad enum value, `minLength`, `pattern`),
+ *   fall back to dropping.
+ *
+ * A form pre-fill usually wants `"drop"` or `"clamp"`: losing twenty good
+ * fields because one came back out of range is the wrong failure unit when a
+ * person is about to review the result anyway.
+ */
+type InvalidFieldPolicy = "throw" | "drop" | "clamp";
+/** What was done about a validation issue. */
+type IssueResolution = "dropped" | "clamped";
+/** A validation issue and how it was resolved without a repair round. */
+interface ResolvedIssue extends FieldValidationIssue {
+    /** What was done about it. */
+    resolution: IssueResolution;
+    /**
+     * The path that was actually changed. For a drop this can be an ancestor of
+     * `path` — the nearest array element or optional field that could absorb
+     * the removal.
+     */
+    resolvedPath: string;
+    /** The value now at `resolvedPath`, for a clamp. */
+    replacement?: unknown;
+}
+/** Options for {@link resolveIssues}. */
+interface ResolveIssuesOptions {
+    /** Bundle for nested schemas, the same one the validator was given. */
+    bundle?: SchemaBundle;
+    /** Legal values for dynamic enum sources, the same ones the validator used. */
+    resolvedEnums?: ResolvedEnums;
+    /**
+     * Which validator judged the data. In a partial coercion every top-level
+     * field is optional by definition, so any of them can be dropped.
+     */
+    mode: "coerce" | "partialCoerce";
+    /** The policy to apply. `"throw"` resolves nothing. */
+    policy: InvalidFieldPolicy;
+}
+/** The outcome of resolving a set of issues. */
+interface ResolveIssuesResult {
+    /** The data after every drop and clamp. The input is never mutated. */
+    data: Record<string, unknown>;
+    /** Issues the policy could act on, in the order they were handled. */
+    resolved: ResolvedIssue[];
+    /** Issues nothing could absorb — a required field, at every level. */
+    unresolved: FieldValidationIssue[];
+}
+/**
+ * Apply an {@link InvalidFieldPolicy} to a validated response.
+ *
+ * Works one action at a time and re-validates after each, so a clamp that
+ * leaves a value still invalid (too long *and* failing its pattern, say) falls
+ * through to a drop, and removing an array element never leaves a stale
+ * index behind. Each action strictly shrinks the data, so the loop ends.
+ *
+ * Pure: the input data is cloned, never mutated.
+ */
+declare function resolveIssues(data: Record<string, unknown>, issues: readonly FieldValidationIssue[], schema: RuntimeSchema, options: ResolveIssuesOptions): ResolveIssuesResult;
+
+/**
+ * How well the input supported a value.
+ *
+ * A three-level scale rather than a number: models are poorly calibrated at
+ * producing a 0–1 score, and a review UI only ever needs to decide whether to
+ * flag a field for a human anyway.
+ */
+type FieldConfidence = "high" | "medium" | "low";
+/** Where a coerced field's value came from. */
+interface FieldProvenance {
+    /** How well the input supported this value. */
+    confidence: FieldConfidence;
+    /**
+     * The span of input the value was read from, quoted. Absent when the value
+     * was inferred rather than read — which is itself the signal worth showing.
+     */
+    evidence?: string;
+    /**
+     * The label of the source the value was read from. Only present when the
+     * coercion was given more than one source.
+     */
+    source?: string;
+}
+/** A coercion result paired with per-field provenance. */
+interface ProvenanceResult<T> {
+    /** The coerced data, in the shape of the target schema. */
+    data: T;
+    /** Provenance for each top-level field the model returned, keyed by name. */
+    provenance: Record<string, FieldProvenance>;
+    /**
+     * Validation issues the `onInvalidField` policy absorbed instead of
+     * throwing — each with what was dropped or clamped. Empty under the
+     * default `"throw"` policy, or when the response validated cleanly.
+     */
+    issues: ResolvedIssue[];
+}
+/**
+ * Extra prompt guidance for a provenance run.
+ *
+ * The JSON Schema already forces the shape; what it cannot convey is how to
+ * judge confidence, which is the whole point of asking.
+ */
+declare const PROVENANCE_INSTRUCTIONS: string;
+/** Options for {@link toProvenanceSchema} and {@link provenanceInstructions}. */
+interface ProvenanceOptions {
+    /**
+     * Labels of the sources the coercion was given, when there are several.
+     * Each annotation then also asks which source the value was read from.
+     */
+    sourceLabels?: readonly string[];
+}
+/**
+ * The provenance guidance for a run, extended with the source rule when the
+ * run has several sources to choose between.
+ */
+declare function provenanceInstructions(options?: ProvenanceOptions): string;
+/**
+ * Derive the schema to actually request when provenance is wanted: the same
+ * fields, each wrapped in `{ value, confidence, evidence }`.
+ *
+ * Only top-level fields are annotated. A nested object keeps its ordinary
+ * shape inside `value`, so provenance is reported for the object as a whole
+ * rather than per leaf — annotating every leaf multiplies both the schema and
+ * the output for detail a review UI rarely acts on.
+ *
+ * Returns a bundle carrying the wrapper, the per-field annotation schemas, and
+ * everything the original bundle held, so nested types still inline.
+ */
+declare function toProvenanceSchema(schema: RuntimeSchema, bundle?: SchemaBundle, options?: ProvenanceOptions): {
+    schema: RuntimeSchema;
+    bundle: SchemaBundle;
+};
+/**
+ * Split a provenance-shaped response back into plain data and per-field
+ * provenance.
+ *
+ * A field the model returned unwrapped — or wrapped without a usable
+ * `confidence` — still yields its value; the provenance is simply not
+ * recorded. Losing an annotation is not a reason to lose the extraction, and
+ * the missing key is visible to the caller.
+ */
+declare function splitProvenance(response: Record<string, unknown>, schema: RuntimeSchema): {
+    data: Record<string, unknown>;
+    provenance: Record<string, FieldProvenance>;
+};
+
+/**
+ * Options for coerce and partialCoerce.
+ */
+interface CoerceOptions {
+    /** The LLM provider to use */
+    provider: Provider;
+    /** The target schema */
+    schema: RuntimeSchema;
+    /** Optional bundle for resolving nested schemas */
+    bundle?: SchemaBundle;
+    /** Optional resolver for @ValuesFrom enum sources */
+    enumResolver?: EnumResolver;
+    /** Optional trace sinks */
+    traceSinks?: TraceSink[];
+    /**
+     * How many times to send validation failures back to the model for
+     * correction before giving up. Defaults to 0 — no repair.
+     *
+     * A repair costs an extra call only when validation actually failed, so the
+     * happy path is unaffected. It is off by default because it also multiplies
+     * worst-case latency, which a caller should opt into knowingly. For
+     * extraction from messy input — scraped HTML, third-party payloads — 1 is
+     * usually the right setting.
+     */
+    maxRepairAttempts?: number;
+    /**
+     * What to do with a present field that fails validation: `"throw"` (the
+     * default), `"drop"` it, or `"clamp"` it to its bounds where that is
+     * meaningful and drop it otherwise. Required fields are never dropped.
+     *
+     * Issues the policy can absorb never trigger a repair round; the provenance
+     * variants report them in `issues`, and every run records them in a trace
+     * event.
+     */
+    onInvalidField?: InvalidFieldPolicy;
+    /**
+     * Cap on the total characters of source text sent to the model, applied
+     * after `preprocess`. Sources over the cap are cut per `truncate`, each
+     * losing a share proportional to its length, and the cut is marked in
+     * place with how much was omitted. Unbounded by default.
+     *
+     * Tokens vary by model and tokenizer; as a rule of thumb English prose runs
+     * about four characters per token.
+     */
+    maxInputChars?: number;
+    /** Which part of an over-budget source to cut. Default `"tail"`. */
+    truncate?: TruncatePolicy;
+    /**
+     * Transform each source before budgeting and rendering: strip HTML down to
+     * text, redact, normalise. Returning a string keeps the source's label.
+     */
+    preprocess?: PreprocessSource;
+}
+/** A hook applied to each source before it is budgeted and rendered. */
+type PreprocessSource = (source: Source, index: number) => Source | string | Promise<Source | string>;
+/**
+ * Coerce user input into a fully validated instance of the target schema.
+ * Throws CoerceError if validation fails (required fields missing, type
+ * mismatches, constraint violations, values outside a resolved taxonomy).
+ * Throws EnumResolutionError if a required field's enum source cannot be resolved.
+ */
+declare function coerce<T>(input: CoerceInput, options: CoerceOptions): Promise<T>;
+/**
+ * Coerce user input into a partial instance of the target schema.
+ * Only validates types of fields that are present; never throws for missing fields.
+ * Throws CoerceError only if present fields have type mismatches or violate
+ * their constraints, and EnumResolutionError if a required field's enum source
+ * cannot be resolved.
+ */
+declare function partialCoerce<T>(input: CoerceInput, options: CoerceOptions): Promise<Partial<T>>;
+/**
+ * Like {@link coerce}, but each field also comes back with how well the input
+ * supported it and the text it was read from.
+ *
+ * Costs a larger schema and a longer response, so reach for it where a human
+ * reviews the result — a pre-filled form that should flag its guesses — rather
+ * than on a hot path.
+ */
+declare function coerceWithProvenance<T>(input: CoerceInput, options: CoerceOptions): Promise<ProvenanceResult<T>>;
+/**
+ * Like {@link partialCoerce}, but each field also comes back with how well the
+ * input supported it and the text it was read from.
+ *
+ * This is the one a form pre-fill usually wants: fields the input never
+ * mentioned are simply absent, and the ones that are present say how much to
+ * trust them.
+ */
+declare function partialCoerceWithProvenance<T>(input: CoerceInput, options: CoerceOptions): Promise<ProvenanceResult<Partial<T>>>;
+
+/** Options for {@link coerceMany}. Everything in `CoerceOptions` applies to each item. */
+interface CoerceManyOptions extends CoerceOptions {
+    /** How many items may be in flight at once. Default 4. */
+    concurrency?: number;
+    /** Which coercion to run per item. Default `"coerce"`. */
+    mode?: "coerce" | "partialCoerce";
+    /** Ask for per-field provenance on every item. Default false. */
+    provenance?: boolean;
+    /**
+     * Run the first item alone before fanning out, so a provider that caches
+     * the prompt prefix writes it once and every later item reads it. Costs
+     * one item's latency up front; saves a cache write per concurrent worker.
+     * Default true.
+     */
+    primeCache?: boolean;
+    /** How the batch backs off when the provider pushes back. */
+    retry?: RetryOptions;
+    /** Called as each item settles, in completion order, for progress. */
+    onItem?: (result: CoerceManyResult<unknown>) => void;
+    /** Stop starting new items; those not yet started fail with the reason. */
+    signal?: AbortSignal;
+}
+/**
+ * Backoff for provider errors that are worth another try — `kind: "api"`
+ * with `retryable: true`, as both bundled providers report a 429, an
+ * overloaded 529 or a dropped connection.
+ *
+ * The pause is shared: one rate-limit answer holds every worker, rather than
+ * each item discovering the limit for itself and multiplying the pressure.
+ * The delay doubles with each consecutive retryable failure across the batch
+ * and resets on any success.
+ */
+interface RetryOptions {
+    /** Extra attempts per item after the first. Default 2. */
+    attempts?: number;
+    /** First pause, in milliseconds. Default 1000. */
+    baseDelayMs?: number;
+    /** Longest pause, in milliseconds. Default 30000. */
+    maxDelayMs?: number;
+}
+/** One item's outcome. `index` is its position in the input list. */
+type CoerceManyResult<T> = {
+    ok: true;
+    index: number;
+    data: T;
+    /** Per-field provenance when `provenance` was requested, else empty. */
+    provenance: Record<string, FieldProvenance>;
+    /** Issues the `onInvalidField` policy absorbed for this item. */
+    issues: ResolvedIssue[];
+    /** How many provider calls it took, repairs excluded. */
+    attempts: number;
+} | {
+    ok: false;
+    index: number;
+    error: unknown;
+    attempts: number;
+};
+/**
+ * Coerce many inputs against one schema.
+ *
+ * Runs at most `concurrency` items at a time, keeps results in input order,
+ * and never rejects as a whole: each item settles to an `ok` or an error of
+ * its own, so one bad listing cannot take down an import. Retryable provider
+ * errors pause the whole batch and try the item again; anything else, a
+ * `CoerceError` included, is that item's final answer.
+ */
+declare function coerceMany<T>(inputs: readonly CoerceInput[], options: CoerceManyOptions): Promise<CoerceManyResult<T>[]>;
+
+/**
+ * Build the input for a repair attempt: the original input (already rendered
+ * as delimited source blocks), the output that was rejected, and what was
+ * wrong with it. The correction sits outside the source blocks, where the
+ * system prompt says instructions live.
+ *
+ * The `Provider` interface is single-turn, so the correction has to travel as
+ * user text rather than as a real assistant turn. In practice that reads to
+ * the model the same way, and it keeps repair working on every provider
+ * without widening the provider contract. Exported so a caller who wants
+ * different wording can build their own and call the provider directly.
+ */
+declare function buildRepairInput(originalInput: string, rejected: Record<string, unknown>, issues: FieldValidationIssue[]): string;
+
+/**
+ * Configuration options shared by global and per-call config.
+ */
+interface SemblGlobalConfig {
+    /** The LLM provider to use */
+    provider?: Provider;
+    /** Optional bundle for resolving nested schemas */
+    bundle?: SchemaBundle;
+    /** Optional resolver for @ValuesFrom enum sources */
+    enumResolver?: EnumResolver;
+    /** Optional trace sinks */
+    traceSinks?: TraceSink[];
+    /** How many times to send validation failures back for correction. Default 0. */
+    maxRepairAttempts?: number;
+    /** What to do with a present field that fails validation. Default "throw". */
+    onInvalidField?: InvalidFieldPolicy;
+    /** Cap on total source characters sent to the model. Unbounded by default. */
+    maxInputChars?: number;
+    /** Which part of an over-budget source to cut. Default "tail". */
+    truncate?: TruncatePolicy;
+    /** Transform each source before budgeting and rendering. */
+    preprocess?: PreprocessSource;
+}
+/**
+ * Per-call configuration overrides passed to `sembl()`.
+ */
+interface SemblCallConfig {
+    /** Override the LLM provider for this call */
+    provider?: Provider;
+    /** Override the bundle for this call */
+    bundle?: SchemaBundle;
+    /** Override the enum source resolver for this call */
+    enumResolver?: EnumResolver;
+    /** Override trace sinks for this call */
+    traceSinks?: TraceSink[];
+    /** Override the repair attempt budget for this call */
+    maxRepairAttempts?: number;
+    /** Override the invalid-field policy for this call */
+    onInvalidField?: InvalidFieldPolicy;
+    /** Override the input character budget for this call */
+    maxInputChars?: number;
+    /** Override the truncation policy for this call */
+    truncate?: TruncatePolicy;
+    /** Override the source preprocessor for this call */
+    preprocess?: PreprocessSource;
+}
+/**
+ * Resolved configuration with a guaranteed provider.
+ */
+interface ResolvedConfig {
+    provider: Provider;
+    bundle?: SchemaBundle;
+    enumResolver?: EnumResolver;
+    traceSinks?: TraceSink[];
+    maxRepairAttempts?: number;
+    onInvalidField?: InvalidFieldPolicy;
+    maxInputChars?: number;
+    truncate?: TruncatePolicy;
+    preprocess?: PreprocessSource;
+}
+/**
+ * Global configuration singleton for SEMBL.
+ */
+declare class SemblConfig {
+    private static _config;
+    /** Set global defaults. */
+    static configure(config: SemblGlobalConfig): void;
+    /** Reset global config to empty (useful in tests). */
+    static reset(): void;
+    /** Read-only access to the current global config. */
+    static get current(): Readonly<SemblGlobalConfig>;
+}
+
+/**
+ * A chainable, thenable wrapper around coercion results.
+ *
+ * Each `.coerceTo()` / `.partialCoerceTo()` call eagerly triggers an LLM call,
+ * serializing the previous result as the input string for the next step.
+ *
+ * Implements `PromiseLike<T>` so it can be `await`ed directly.
+ *
+ * There is no provenance variant here: an intermediate link's annotations
+ * would be serialized into the next call's input and lost, and a terminal one
+ * would have to return a different shape than every other link. Use
+ * `coerceWithProvenance` / `partialCoerceWithProvenance` directly instead.
+ */
+declare class Coercible<T> implements PromiseLike<T> {
+    private readonly _promise;
+    private readonly _config;
+    /**
+     * Whether the promise holds the caller's original input rather than a
+     * coerced result. Only the first link does: it passes labelled sources
+     * through untouched, whereas every later link serializes the previous
+     * result — a result that merely looks like a source is still a result.
+     */
+    private readonly _holdsInput;
+    constructor(_promise: Promise<T>, _config: ResolvedConfig, 
+    /**
+     * Whether the promise holds the caller's original input rather than a
+     * coerced result. Only the first link does: it passes labelled sources
+     * through untouched, whereas every later link serializes the previous
+     * result — a result that merely looks like a source is still a result.
+     */
+    _holdsInput?: boolean);
+    /** What the next link should send as its input. */
+    private _inputFrom;
+    /** The per-call options every link in the chain shares. */
+    private _optionsFor;
+    /**
+     * Chain a full coercion to a new schema.
+     * The current value is serialized and used as input for the next LLM call.
+     */
+    coerceTo<U>(schema: RuntimeSchema): Coercible<U>;
+    /**
+     * Chain a partial coercion to a new schema.
+     * The current value is serialized and used as input for the next LLM call.
+     */
+    partialCoerceTo<U>(schema: RuntimeSchema): Coercible<Partial<U>>;
+    then<TResult1 = T, TResult2 = never>(onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    catch<TResult = never>(onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | null): Promise<T | TResult>;
+    finally(onfinally?: (() => void) | null): Promise<T>;
+}
+/**
+ * Entry point for the fluent coercion API.
+ *
+ * Accepts a string or object as input. Objects are JSON-serialized.
+ * Returns a `Coercible<string>` that can be chained with `.coerceTo()` / `.partialCoerceTo()`.
+ *
+ * @example
+ * ```ts
+ * SemblConfig.configure({ provider, bundle });
+ * const result = await sembl("some user input")
+ *   .partialCoerceTo(ProfileSchema)
+ *   .coerceTo(IntentSchema);
+ * ```
+ */
+declare function sembl(input: CoerceInput | Record<string, unknown>, config?: SemblCallConfig): Coercible<CoerceInput>;
+
+/**
+ * Options for prompt generation.
+ */
+interface PromptOptions {
+    /** Legal values for dynamic enum sources, from `resolveEnumSources` */
+    resolvedEnums?: ResolvedEnums;
+}
+/**
+ * Build a system prompt that provides semantic context for the target schema.
+ * This assembles the semantic hierarchy so the LLM understands the meaning
+ * of each field in context.
+ */
+declare function buildPrompt(schema: RuntimeSchema, bundle?: SchemaBundle, options?: PromptOptions): string;
+
+/**
+ * Options shared by both validation modes.
+ */
+interface ValidationOptions {
+    /** Legal values for dynamic enum sources, from `resolveEnumSources` */
+    resolvedEnums?: ResolvedEnums;
+}
+/**
+ * Validate data against a RuntimeSchema in strict mode.
+ * All required fields must be present and correctly typed.
+ * Returns validation issues (empty array means valid).
+ */
+declare function validateStrict(data: Record<string, unknown>, schema: RuntimeSchema, bundle?: SchemaBundle, options?: ValidationOptions): FieldValidationIssue[];
+/**
+ * Validate data against a RuntimeSchema in partial mode.
+ * Only validates types of fields that ARE present; never fails for missing fields.
+ * Returns validation issues (empty array means valid).
+ */
+declare function validatePartial(data: Record<string, unknown>, schema: RuntimeSchema, bundle?: SchemaBundle, options?: ValidationOptions): FieldValidationIssue[];
+
+/**
+ * Tracer implementation that creates spans, records events, and dispatches to sinks.
+ */
+declare class Tracer implements TraceContext {
+    private sinks;
+    constructor(sinks?: TraceSink[]);
+    startSpan(name: string, attributes?: Record<string, unknown>, parent?: TraceSpan): TraceSpan;
+    endSpan(span: TraceSpan): void;
+    addEvent(span: TraceSpan, name: string, attributes?: Record<string, unknown>): void;
+}
+
+/**
+ * Default trace sink that writes spans to the console.
+ */
+declare class ConsoleSink implements TraceSink {
+    write(span: TraceSpan): void;
+}
+
+export { type BudgetResult, CoerceError, type CoerceInput, type CoerceManyOptions, type CoerceManyResult, type CoerceOptions, Coercible, ConsoleSink, Constrain, type DeepPartial, type DefinedSchema, Describe, type EnumResolution, EnumResolutionError, type EnumResolver, type EnumSourceFailure, type EnumSourceUsage, type FieldBuilder, type FieldConfidence, type FieldConstraints, type FieldDescriptor, type FieldProvenance, type FieldType, type FieldValidationIssue, type Infer, type InferFields, type InvalidFieldPolicy, type IssueResolution, type JsonSchemaDialect, type JsonSchemaOptions, PROVENANCE_INSTRUCTIONS, type PreprocessSource, type PromptOptions, type ProvenanceOptions, type ProvenanceResult, type Provider, type ProviderConfig, type ProviderRequest, type ProviderResponse, type ProviderUsage, type ResolveIssuesOptions, type ResolveIssuesResult, type ResolvedEnums, type ResolvedIssue, type RetryOptions, type RuntimeSchema, SOURCE_INSTRUCTIONS, Schema, type SchemaBundle, SchemaRegistry, type SemblCallConfig, SemblConfig, type SemblGlobalConfig, type Source, type TraceContext, type TraceEvent, type TraceSink, type TraceSpan, Tracer, type TruncatePolicy, type TruncationRecord, type ValidationOptions, ValuesFrom, budgetSources, buildPrompt, buildRepairInput, bundleOf, coerce, coerceMany, coerceWithProvenance, collectEnumSources, defineSchema, field, isCoerceInput, isSource, partialCoerce, partialCoerceWithProvenance, provenanceInstructions, renderSources, resolveEnumSources, resolveIssues, runtimeSchemaToJsonSchema, sembl, splitProvenance, toOpenAIJsonSchema, toProvenanceSchema, toSources, validatePartial, validateStrict };