@bivelio/savings-layer 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,2005 @@
+/**
+ * Environment-agnostic UUID generation.
+ * ---------------------------------------------------------------------------
+ * Trace IDs only need to be unique, not cryptographically unpredictable. We
+ * prefer the platform `crypto.randomUUID` (present in modern Node, browsers,
+ * Deno and edge runtimes) and fall back to a v4-shaped id when it is absent, so
+ * BV-SALA runs everywhere without a `node:crypto` import that breaks bundlers.
+ */
+declare function randomId(): string;
+
+/**
+ * The four-ledger savings accounting.
+ *
+ * These ledgers are kept strictly separate on purpose (see contracts/types.ts).
+ * The ledger is a pure accumulator: the pipeline records events into it, and it
+ * produces the numbers that populate the SavingsReport. It never guesses — every
+ * increment is driven by an explicit pipeline decision.
+ */
+/**
+ * De dónde sale el baseline con el que se compara el coste.
+ *
+ * - `measured`   — reconstruido desde el contador del proveedor. Es dinero.
+ * - `estimated`  — llamada EVITADA: nunca se ejecutó, así que no hay contador
+ *                  del proveedor y el baseline es del estimador local. Sigue
+ *                  siendo la mejor cifra disponible, pero no está medida.
+ * - `unmeasured` — el proveedor no reportó uso. No se reclama nada.
+ *
+ * Sumar `measured` y `estimated` en una misma cifra de "dinero ahorrado" es
+ * exactamente lo que un producto verify-don't-trust no puede hacer.
+ */
+type CostBasis = "measured" | "estimated" | "unmeasured";
+interface CostModel {
+    /** Cost per 1K input tokens, in the caller's currency unit. */
+    inputPer1k: number;
+    /** Cost per 1K output tokens. */
+    outputPer1k: number;
+    /** Optional discounted rate for provider-cached (prefix) input tokens. */
+    cachedInputPer1k?: number;
+}
+declare class SavingsLedger {
+    avoidedLlm: number;
+    baselineLlm: number;
+    actualLlm: number;
+    baselineRetrieval: number;
+    actualRetrieval: number;
+    baselineTools: number;
+    actualTools: number;
+    retries: number;
+    baselineInput: number;
+    actualInput: number;
+    eliminatedInput: number;
+    compressedInput: number;
+    baselineOutput: number;
+    actualOutput: number;
+    eliminatedOutput: number;
+    providerCachedInput: number;
+    /** Cuenta LOCAL del prompt que de verdad se envió al proveedor. */
+    sentInputLocal: number;
+    /** Tokens que la capa quitó de ese prompt, en cuenta LOCAL. */
+    removedInputLocal: number;
+    /**
+     * ¿El estimador que produjo las dos cifras anteriores cuenta con la regla del
+     * proveedor? Lo fija el pipeline al resolver el tokenizador del modelo.
+     * Por defecto NO: asumir exactitud sin comprobarla es el fallo que esto cierra.
+     */
+    estimatorExact: boolean;
+    /** Salida del reintento de reparación. Es coste NUESTRO, nunca del baseline. */
+    repairOutput: number;
+    /** Ledger 2: tokens removed because they were not needed. */
+    eliminate(tokens: number): void;
+    /** Ledger 3: delta between an original encoding and a cheaper one. */
+    compress(originalTokens: number, compressedTokens: number): void;
+    /** Ledger 4: tokens still present but billed/processed as provider-cached. */
+    providerCached(tokens: number): void;
+    /** Record that a whole primary LLM call was avoided (cache / resolver hit). */
+    avoidCall(baselineInput: number, baselineOutput: number): void;
+    /**
+     * Baseline de salida publicable.
+     *
+     * En una llamada EVITADA es el de la respuesta que se habría generado. En una
+     * que se EJECUTÓ es la salida medida menos la de la reparación — nunca el techo
+     * `maxOutputTokens ?? 256`. estimateCost ya lo hacía por dentro, pero el
+     * informe publicaba el techo crudo, y el proyector público lo convertía en
+     * dólares: se anunciaba un ahorro de salida que nunca existió.
+     */
+    get publishedBaselineOutput(): number;
+    estimateCost(model: CostModel): {
+        baselineEstimate: number;
+        actual: number;
+        netSavings: number;
+        basis: CostBasis;
+    };
+}
+
+/**
+ * Core contracts for BV-SALA (bivelio-savings-layer).
+ *
+ * The layer keeps FOUR separate ledgers of savings. They must never be summed
+ * into a single "tokens saved" number, because each one means something
+ * different:
+ *
+ *  - avoided_calls          LLM / RAG / tool calls that never executed.
+ *  - eliminated_tokens      information dropped because it was not needed.
+ *  - compressed_tokens      information kept, but encoded with fewer tokens.
+ *  - provider_cached_tokens tokens still in the prompt that the provider may
+ *                           bill or process differently (prefix/KV caching).
+ *
+ * A cache hit eliminates a whole call. TOON re-encodes a structured payload.
+ * LLMLingua removes redundant words. A provider prefix cache makes tokens
+ * cheaper without removing them. Mixing these produces misleading metrics.
+ */
+/** Roles understood by the provider-neutral chat interface. */
+type MessageRole = "system" | "user" | "assistant" | "tool";
+interface ChatMessage {
+    role: MessageRole;
+    content: string;
+    /** Optional name (e.g. tool name for role: "tool"). */
+    name?: string;
+    /** Opaque provider metadata; never used for the exact-cache key. */
+    metadata?: Record<string, unknown>;
+}
+/** How a request is classified by the execution router. */
+type ExecutionClass = "NO_RETRIEVAL" | "SINGLE_RETRIEVAL" | "MULTI_HOP_RETRIEVAL" | "TOOL_ACTION" | "NON_CACHEABLE";
+/** Risk profile of a tool. Write/destructive tools are never cached. */
+type ToolRisk = "read" | "write" | "destructive";
+interface ToolDescriptor {
+    id: string;
+    /** Human/agent intents this tool can satisfy — used by the tool selector. */
+    intents: string[];
+    risk: ToolRisk;
+    /** JSON-schema-like description of the tool's arguments. */
+    parameters?: JsonSchema;
+    description?: string;
+    /** Whether the tool's result is stable enough to cache. */
+    freshness?: "static" | "dynamic";
+    /** Estimated schema token cost per tokenizer id (optional, filled lazily). */
+    schemaTokens?: Record<string, number>;
+}
+/** Minimal structural JSON-Schema subset the layer reasons about. */
+interface JsonSchema {
+    type?: "object" | "array" | "string" | "number" | "integer" | "boolean" | "null";
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    items?: JsonSchema;
+    enum?: unknown[];
+    additionalProperties?: boolean | JsonSchema;
+    maxItems?: number;
+    minItems?: number;
+    maxLength?: number;
+    minLength?: number;
+    maximum?: number;
+    minimum?: number;
+    pattern?: string;
+    format?: string;
+    description?: string;
+    /** Non-standard: opaque identifier used to reference a registered contract. */
+    $id?: string;
+}
+interface OutputContract {
+    /** Stable identifier, e.g. "research-answer:v3". */
+    contractId: string;
+    schema: JsonSchema;
+    /** Hard ceiling on generated tokens. */
+    maxOutputTokens?: number;
+    /** Version marker included in the exact-cache key. */
+    version?: string;
+}
+/** Serialization formats the format-selector can choose between. */
+type SerializationFormat = "json-compact" | "toon" | "csv";
+interface RetrievalOptions {
+    mode: "off" | "auto" | "single" | "multi";
+    maxRounds?: number;
+    maxDocuments?: number;
+}
+interface SavingsToggles {
+    exactCache?: boolean;
+    semanticCache?: boolean | "safe-only";
+    compression?: boolean | "auto";
+    serialization?: boolean | "auto";
+    singleflight?: boolean;
+    deterministicResolvers?: boolean;
+    router?: boolean;
+}
+interface RequestContext {
+    tenantId?: string;
+    authorizationScope?: string;
+    locale?: string;
+    /** Epoch marker of the knowledge base; part of cache keys / freshness. */
+    knowledgeEpoch?: string;
+    /** Session identifier for conversational memory. */
+    sessionId?: string;
+    /** Bucket describing how fresh the answer must be. */
+    freshnessBucket?: "any" | "day" | "hour" | "live";
+    safetyPolicyVersion?: string;
+}
+interface SavingsRequest {
+    /** Provider-qualified model id, e.g. "openai/gpt-4o-mini". */
+    model: string;
+    messages: ChatMessage[];
+    tools?: ToolDescriptor[];
+    response?: OutputContract;
+    retrieval?: RetrievalOptions;
+    savings?: SavingsToggles;
+    context?: RequestContext;
+    /** Sampling controls that participate in the exact-cache key. */
+    temperature?: number;
+    seed?: number;
+    /** Tokenizer id to cost against; defaults to a model-derived estimate. */
+    tokenizer?: string;
+    /** Arbitrary structured payload to be serialized into the prompt. */
+    structuredData?: unknown;
+}
+/** Result returned to the caller. */
+interface SavingsResult<T = unknown> {
+    requestId: string;
+    /** Validated, structured output (when a contract was supplied). */
+    data: T;
+    /** Raw text output from the provider (or the resolver). */
+    text: string;
+    /** Locally-rendered, human-facing representation, when produced. */
+    rendered?: string;
+    report: SavingsReport;
+}
+type CacheOutcome = "miss" | "exact" | "semantic" | "singleflight" | "deterministic";
+interface SavingsReport {
+    requestId: string;
+    model: string;
+    calls: {
+        baselineLlm: number;
+        actualLlm: number;
+        avoidedLlm: number;
+        baselineRetrieval: number;
+        actualRetrieval: number;
+        baselineTools: number;
+        actualTools: number;
+        retries: number;
+    };
+    tokens: {
+        baselineInput: number;
+        actualInput: number;
+        /** Ledger 2: dropped because unnecessary. */
+        eliminatedInput: number;
+        /** Ledger 3: kept but re-encoded with fewer tokens. */
+        compressedInput: number;
+        baselineOutput: number;
+        actualOutput: number;
+        eliminatedOutput: number;
+        /** Ledger 4: still present, but provider-cached (cheaper, not removed). */
+        providerCachedInput?: number;
+    };
+    cache: {
+        result: CacheOutcome;
+        confidence?: number;
+        ageMs?: number;
+    };
+    routing: {
+        executionClass: ExecutionClass;
+        confidence: number;
+        rounds: number;
+        reason?: string;
+    };
+    serialization: {
+        chosen: SerializationFormat;
+        candidateTokens: Partial<Record<SerializationFormat, number>>;
+        instructionOverheadTokens: number;
+    };
+    compression?: {
+        originalTokens: number;
+        compressedTokens: number;
+        protectedSpans: number;
+        fidelityPassed: boolean;
+    };
+    constraints: {
+        backend: string;
+        schemaVersion: string;
+        structurallyValid: boolean;
+    };
+    quality: {
+        taskPassed?: boolean;
+        semanticScore?: number;
+        freshnessPassed?: boolean;
+    };
+    cost: {
+        baselineEstimate: number;
+        actual: number;
+        netSavings: number;
+        /**
+         * De dónde sale el baseline. Es lo que separa el dinero medido del estimado.
+         *
+         * - `measured`   — reconstruido desde el contador del proveedor de ESTA
+         *                  petición. Es dinero, y se puede contrastar con la factura.
+         * - `estimated`  — la llamada se EVITÓ, así que nunca hubo contador del
+         *                  proveedor y el baseline sale del estimador local. Es la
+         *                  mejor cifra disponible, pero no está medida.
+         * - `unmeasured` — el proveedor no reportó uso. No se reclama nada.
+         *
+         * Un panel que sume `measured` y `estimated` en una sola cifra de "dinero
+         * ahorrado" está haciendo justo lo que este producto promete no hacer.
+         */
+        basis: CostBasis;
+    };
+    latencyMs: {
+        total: number;
+        preprocessing: number;
+        provider: number;
+    };
+    /** Ordered pipeline decision breadcrumbs, for debugging and audit. */
+    traces: TraceEvent[];
+}
+/**
+ * Structural license gate the pipeline consults before enabling a managed
+ * feature (semantic cache, learned thresholds, long-context compression, …).
+ *
+ * It is intentionally a bare shape — the SDK never imports the license package.
+ * `@bivelio/license-client`'s `createLicenseGate()` returns a compatible object,
+ * but any implementation of this interface works. When no gate is configured the
+ * pipeline behaves as an ungated self-managed deployment (backwards compatible).
+ */
+interface LicenseGate {
+    isEntitled(feature: string): boolean;
+    /**
+     * Whether there is an overall active (or in-grace) license. La consulta la
+     * puerta de entrada fail-closed del pipeline.
+     *
+     * OBLIGATORIO. Fue opcional "por compatibilidad", y esa opcionalidad era el
+     * bypass: un gate al que le faltara el método dejaba pasar todas las
+     * peticiones con solo un aviso por consola. Para desarrollo local está
+     * `devUnlicensed: true`, que es explícito y no se cuela sin querer.
+     */
+    isActive(): boolean;
+    /** Resolved status (active|grace|expired|invalid|revoked), for error messages. */
+    status?(): string;
+}
+interface TraceEvent {
+    stage: string;
+    outcome: string;
+    detail?: Record<string, unknown>;
+    /** Monotonic elapsed ms from the start of the request. */
+    atMs: number;
+}
+
+/**
+ * Typed intermediate representation for LLM -> LLM handoffs.
+ *
+ * In multi-agent systems the same system prompt, tool list and context tend to
+ * be re-explained in free-form natural language at every hop. BV-SALA replaces
+ * that with a compact, typed handoff object. Each consumer receives a
+ * projection of the state, not the whole conversation. The serializer then
+ * decides whether to send it as compact JSON or TOON.
+ */
+interface HandoffFact {
+    id: string;
+    value: unknown;
+    source?: string;
+}
+interface BivelioHandoff {
+    /** Schema version of the handoff envelope itself. */
+    v: 1;
+    task: string;
+    goal: string;
+    rules: string[];
+    facts: HandoffFact[];
+    /** References to large documents kept out of the prompt (id/hash pointers). */
+    refs: string[];
+    /** Only the delta since the previous turn, not the whole state. */
+    delta?: Record<string, unknown>;
+    /** Identifier of the output contract; not the full schema. */
+    outputContract: string;
+}
+declare function createHandoff(init: Omit<BivelioHandoff, "v"> & Partial<Pick<BivelioHandoff, "v">>): BivelioHandoff;
+
+/**
+ * Token estimation.
+ *
+ * A production deployment should register a real tokenizer (tiktoken /
+ * o200k_base, the provider's own tokenizer, etc.) via {@link TokenizerRegistry}.
+ * BV-SALA never hard-codes savings; every format / compression decision is made
+ * against the tokenizer of the *destination* model. This module ships a
+ * dependency-free heuristic estimator so the layer works out of the box and so
+ * tests are deterministic — but it is explicitly an *estimate*, and the whole
+ * point of the registry is that you can swap in an exact counter.
+ */
+interface TokenEstimator {
+    /** Stable id, e.g. "o200k_base" or "heuristic". */
+    readonly id: string;
+    /**
+     * ¿Cuenta este estimador con la MISMA regla que factura el proveedor?
+     *
+     * No es un detalle de calidad: decide si una cifra derivada puede llamarse
+     * MEDIDA. El baseline de una llamada que se ejecutó se reconstruye como
+     * "lo enviado (medido por el proveedor) + lo quitado (contado aquí)". Si lo
+     * quitado se cuenta con otra regla, el resultado es una estimación aunque uno
+     * de los dos sumandos venga del proveedor — y publicarlo como medido es
+     * exactamente la clase de mentira que este producto existe para no contar.
+     *
+     * El heurístico vale para RANKEAR formatos candidatos (le basta con acertar el
+     * orden). No vale para restar tokens entre formatos distintos: cobra cada
+     * símbolo suelto como un token entero, así que infla el JSON denso en símbolos
+     * mucho más que el TOON, y la diferencia se acredita como ahorro inexistente.
+     */
+    readonly exact: boolean;
+    /** Estimate the number of tokens in a string. */
+    count(text: string): number;
+}
+/**
+ * Heuristic estimator. Modern BPE tokenizers (cl100k/o200k) average roughly
+ * ~3.7-4 characters per token on English/code, with whitespace, digits and
+ * punctuation costing relatively more. This estimator approximates that by
+ * combining a word-boundary pass with a character-based floor, which tracks
+ * real tokenizers well enough to *rank* candidate encodings — which is all the
+ * format selector needs. It is intentionally conservative and stable.
+ */
+declare class HeuristicEstimator implements TokenEstimator {
+    readonly id: string;
+    /** Aproxima; no comparte regla con ningún proveedor. Ver {@link TokenEstimator.exact}. */
+    readonly exact = false;
+    constructor(id?: string);
+    count(text: string): number;
+}
+declare const heuristicEstimator: HeuristicEstimator;
+
+/**
+ * Registry of token estimators keyed by tokenizer id, plus a mapping from model
+ * ids to the tokenizer they use. All cost/format/compression decisions in the
+ * pipeline resolve a tokenizer through this registry, so swapping in an exact
+ * tokenizer is a one-line registration and never a code change in the pipeline.
+ */
+declare class TokenizerRegistry {
+    private readonly estimators;
+    private readonly modelToTokenizer;
+    private readonly fallbackId;
+    constructor(fallback?: TokenEstimator);
+    register(estimator: TokenEstimator): this;
+    /** Associate a model id (e.g. "openai/gpt-4o-mini") with a tokenizer id. */
+    mapModel(model: string, tokenizerId: string): this;
+    /** Resolve an estimator by explicit tokenizer id, else by model, else fallback. */
+    resolve(opts: {
+        tokenizer?: string;
+        model?: string;
+    }): TokenEstimator;
+    count(text: string, opts: {
+        tokenizer?: string;
+        model?: string;
+    }): number;
+}
+declare const defaultTokenizerRegistry: TokenizerRegistry;
+
+/**
+ * Tokenizador EXACTO — la regla del proveedor, no una aproximación.
+ *
+ * Por qué existe. El baseline de una llamada que se ejecutó se reconstruye como
+ * "lo enviado + lo quitado". Lo enviado lo mide el proveedor; lo quitado lo
+ * contamos aquí. Con el estimador heurístico esos dos sumandos vienen de reglas
+ * distintas, y la diferencia NO es ruido: el heurístico cobra cada símbolo suelto
+ * como un token entero, así que infla el JSON (40% de símbolos) mucho más que el
+ * TOON (16%). Medido en el escenario de la tabla: publicaba un baseline 3,68x el
+ * naive real, o sea un +47,4% de ahorro donde el proveedor midió −49,6%.
+ *
+ * Cómo se instala. `gpt-tokenizer` son ~53 MB desempaquetados, así que NO es
+ * dependencia dura: imponérsela a todo el que instale el SDK, cuando la mayoría
+ * no necesita contabilidad medida, sería abusivo. Es peerDependency opcional:
+ *
+ *   pnpm add gpt-tokenizer
+ *
+ * Sin ella el layer sigue funcionando con el heurístico, y el `basis` de cada
+ * informe lo dice — "estimated" en vez de "measured". Esa es la diferencia
+ * importante: el producto no deja de funcionar, deja de AFIRMAR de más.
+ */
+
+/** Lo que necesitamos de gpt-tokenizer. Tipado aquí para no depender de sus tipos. */
+interface CodificadorBpe {
+    encode(text: string): number[] | {
+        length: number;
+    };
+}
+/**
+ * Estimador exacto sobre una codificación BPE ya cargada.
+ *
+ * Se construye con el codificador ya resuelto en vez de importarlo dentro: así
+ * este módulo no obliga a nadie a tener el paquete, y quien lo tiene decide qué
+ * codificación carga (o200k_base para gpt-4o/4.1/5, cl100k_base para 3.5/4).
+ */
+declare class ExactTokenizer implements TokenEstimator {
+    private readonly codificador;
+    readonly id: string;
+    readonly exact = true;
+    constructor(id: string, codificador: CodificadorBpe);
+    count(text: string): number;
+}
+/** Modelos que usan cada codificación. Sirve para mapear el registro de una vez. */
+declare const MODELOS_POR_CODIFICACION: Readonly<Record<string, readonly string[]>>;
+/**
+ * Carga `gpt-tokenizer` si está instalado y registra el tokenizador exacto para
+ * los modelos de OpenAI. Devuelve `false` —sin lanzar— cuando no está: la
+ * ausencia del paquete opcional no es un error, solo significa que la
+ * contabilidad se publicará como estimada.
+ *
+ * Se importa solo la codificación pedida, no el paquete entero: `gpt-tokenizer`
+ * expone un punto de entrada por codificación y cargarlas todas serían decenas
+ * de MB en memoria sin motivo.
+ */
+declare function registrarTokenizadorExacto(registro: {
+    register(e: TokenEstimator): unknown;
+    mapModel(model: string, tokenizerId: string): unknown;
+}, opciones?: {
+    codificaciones?: readonly string[];
+}): Promise<boolean>;
+
+/**
+ * Canonicalization turns a raw request into a normalized, hashable form. This
+ * is what makes the exact cache safe and the singleflight key correct: two
+ * requests that mean the same thing must canonicalize identically, and two
+ * requests that differ in any way that could change the answer must not.
+ */
+interface CanonicalRequest {
+    model: string;
+    modelFamily: string;
+    messages: ChatMessage[];
+    /** Whitespace/case-normalized text of the user-visible turns. */
+    normalizedText: string;
+    systemPromptHash: string;
+    toolsetHash: string;
+    /** Hash of the structured payload; part of the cache key so different data never collides. */
+    structuredDataHash: string;
+    schemaVersion: string;
+    contractId: string | null;
+    temperature: number | null;
+    seed: number | null;
+    tenantId: string;
+    authorizationScope: string;
+    /**
+     * Quién pregunta, dentro del tenant. Sale de `context.sessionId`.
+     *
+     * Es lo que permite cachear una respuesta PERSONALIZADA sin servírsela a otro:
+     * tenant y scope son compartidos por defecto, así que sin esto dos usuarios de
+     * la misma organización comparten entrada de caché. `null` cuando no se
+     * aporta, y entonces la política apaga la caché exacta para ese tráfico.
+     */
+    principal: string | null;
+    locale: string;
+    knowledgeEpoch: string;
+    freshnessBucket: string;
+    safetyPolicyVersion: string;
+    tokenizer: string | undefined;
+    original: SavingsRequest;
+}
+declare function normalizeText(text: string): string;
+declare function sha256(input: string): string;
+/** Stable JSON stringify with sorted keys so hashes are order-independent. */
+declare function stableStringify(value: unknown): string;
+declare function canonicalize(request: SavingsRequest): CanonicalRequest;
+
+/**
+ * Exact-cache key.
+ *
+ * A hash of the user text alone is NOT a safe cache key. Two requests may share
+ * text but differ in tenant, permission scope, model version, system prompt,
+ * schema, toolset, locale, sampling, knowledge epoch or safety policy — any of
+ * which can change the correct answer. The exact key includes all of them.
+ */
+declare function buildExactKey(c: CanonicalRequest): string;
+/**
+ * In-flight (singleflight) key. Coalesces concurrent, equivalent requests onto
+ * a single execution. It can be slightly looser than the exact key (it does not
+ * need freshness bucketing, since the work is happening *now*), but must still
+ * isolate tenants and permissions.
+ */
+declare function buildInflightKey(c: CanonicalRequest): string;
+
+/**
+ * Policy engine: risk and freshness.
+ *
+ * This is the gate that decides which savings are *safe* for a given request.
+ * The most dangerous failure of a savings layer is not a cache miss — it is
+ * confidently returning a wrong answer (a stale price, another tenant's data, a
+ * reused answer for a side-effecting action). The policy engine exists to make
+ * those outcomes structurally impossible, not merely unlikely.
+ */
+interface Policy {
+    /** May the exact cache be read/written for this request? */
+    allowExactCache: boolean;
+    /** May the semantic cache even be *considered*? (still verified later) */
+    allowSemanticCache: boolean;
+    /** May concurrent equivalent requests be coalesced? */
+    allowSingleflight: boolean;
+    /** May we run natural-language compression on the context? */
+    allowCompression: boolean;
+    /** Does the request demand current/live data? */
+    requiresFreshData: boolean;
+    /** Does the request have (or request) side effects? */
+    hasSideEffects: boolean;
+    /** Is the response personalized to a user/account? */
+    isPersonalized: boolean;
+    reasons: string[];
+}
+declare function evaluatePolicy(c: CanonicalRequest): Policy;
+
+/**
+ * Exact cache.
+ *
+ * When the canonical key represents the request completely, a hit removes 100%
+ * of input tokens, 100% of output tokens, and the whole provider call. This is
+ * the single highest-value, lowest-risk saving in the layer. The interface is
+ * deliberately minimal (get/set with TTL) so any store — Redis, a KV, an LRU —
+ * can back it.
+ */
+interface CachedAnswer<T = unknown> {
+    text: string;
+    data?: T;
+    rendered?: string;
+    /** Epoch ms when stored; used to compute age and honor TTL. */
+    storedAtMs: number;
+    /** Optional metadata carried alongside the answer. */
+    meta?: Record<string, unknown>;
+}
+interface ExactCache {
+    get<T = unknown>(key: string): Promise<CachedAnswer<T> | null>;
+    set<T = unknown>(key: string, value: CachedAnswer<T>, ttlMs?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+/**
+ * In-memory exact cache with TTL and a size bound (LRU-ish by insertion order).
+ * Suitable for tests and single-process deployments; swap for Redis in prod.
+ */
+declare class InMemoryExactCache implements ExactCache {
+    private readonly store;
+    private readonly maxEntries;
+    private readonly now;
+    constructor(opts?: {
+        maxEntries?: number;
+        now?: () => number;
+    });
+    get<T = unknown>(key: string): Promise<CachedAnswer<T> | null>;
+    set<T = unknown>(key: string, value: CachedAnswer<T>, ttlMs?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    get size(): number;
+}
+
+/**
+ * Singleflight (in-flight coalescing).
+ *
+ * When N equivalent requests arrive at once, exactly one executes the work and
+ * the other N-1 await the same promise. This is NOT a historical cache — it is
+ * de-duplication of concurrent work, so it carries no staleness risk and needs
+ * no TTL. On traffic spikes it can eliminate a large fraction of duplicate
+ * provider calls for free.
+ */
+declare class Singleflight {
+    private readonly inflight;
+    /** How many callers are currently sharing an in-flight execution. */
+    private readonly waiters;
+    /**
+     * Run `fn` under `key`. If a call with the same key is already running, share
+     * its result instead of starting a new one. Returns the shared result plus
+     * whether this caller was a coalesced follower (a "hit").
+     */
+    run<T>(key: string, fn: () => Promise<T>): Promise<{
+        value: T;
+        coalesced: boolean;
+    }>;
+    get activeKeys(): number;
+}
+
+/**
+ * Semantic cache (safe-by-construction).
+ *
+ * A semantic cache reuses a previous answer for a *similar* query. Its danger is
+ * the false positive: confidently returning a valid answer to a nearby-but-wrong
+ * question. Therefore the headline metric here is NOT hit ratio — it is the
+ * PRECISION of hits. Every candidate must pass: tenant/permission filter,
+ * knowledge-epoch filter, a similarity threshold, a stronger local verifier, a
+ * freshness check, and an output-contract compatibility check.
+ */
+interface EmbeddingFn {
+    (text: string): Promise<number[]> | number[];
+}
+interface SemanticVerifier {
+    /**
+     * Second-stage check (ideally a small cross-encoder). Returns a confidence in
+     * [0,1] that the candidate answer genuinely answers the query. The pipeline
+     * only accepts a hit above the configured acceptance threshold.
+     */
+    (query: string, candidateQuery: string): Promise<number> | number;
+}
+interface SemanticRecord {
+    embedding: number[];
+    query: string;
+    answer: CachedAnswer;
+    tenantId: string;
+    authorizationScope: string;
+    knowledgeEpoch: string;
+    contractId: string | null;
+    /**
+     * QUIÉN hizo la petición (sessionId/principal), o null si es anónima.
+     *
+     * Faltaba, y era la fuga más cara: la caché exacta aísla por principal pero la
+     * semántica no lo miraba, así que dos usuarios distintos del MISMO tenant con
+     * la misma pregunta casaban por embedding y el segundo recibía la respuesta
+     * calculada para el primero. `tenantId` separa organizaciones, no personas.
+     */
+    principal: string | null;
+    /**
+     * Identidad COMPLETA de la petición que produjo esta respuesta.
+     *
+     * Antes solo se guardaban tenant, scope, epoch y contrato: la clave exacta
+     * declara necesarios otros cinco campos, y la semántica los ignoraba. El peor
+     * era `structuredDataHash` — dos preguntas redactadas igual pero con datos
+     * ADJUNTOS distintos casan por embedding, así que se servía la respuesta
+     * calculada sobre la tabla de otro. `model` y `systemPromptHash` van detrás:
+     * un modelo o un system prompt distintos son otra respuesta.
+     */
+    model: string;
+    systemPromptHash: string;
+    structuredDataHash: string;
+    locale: string;
+    schemaVersion: string;
+    safetyPolicyVersion: string;
+    storedAtMs: number;
+}
+interface SemanticHit {
+    record: SemanticRecord;
+    similarity: number;
+    verifierScore: number;
+    confidence: number;
+    ageMs: number;
+}
+interface SemanticCacheOptions {
+    embed: EmbeddingFn;
+    verify?: SemanticVerifier;
+    /** Cosine similarity floor for a candidate to be considered at all. */
+    similarityThreshold?: number;
+    /** Verifier score floor for acceptance. */
+    acceptThreshold?: number;
+    ttlMs?: number;
+    maxRecords?: number;
+    now?: () => number;
+}
+declare function cosine(a: number[], b: number[]): number;
+/** True when two normalized queries agree on the facts an embedding tends to blur. */
+declare function keyTokensMatch(a: string, b: string): boolean;
+/**
+ * In-memory reference implementation. A production build would back this with a
+ * real vector store (pgvector, Qdrant, etc.) and metadata filters pushed down
+ * to the store. The verification logic — the part that makes it *safe* — stays
+ * identical regardless of the backend.
+ */
+declare class InMemorySemanticCache {
+    private readonly records;
+    private readonly embed;
+    private readonly verify;
+    private readonly similarityThreshold;
+    private readonly acceptThreshold;
+    private readonly ttlMs;
+    private readonly maxRecords;
+    private readonly now;
+    constructor(opts: SemanticCacheOptions);
+    /**
+     * Find a safe hit for a canonical request, or null. Metadata filters run
+     * FIRST and hard — a candidate from another tenant, scope, or knowledge epoch
+     * is never even scored.
+     */
+    find(c: CanonicalRequest): Promise<SemanticHit | null>;
+    store(c: CanonicalRequest, answer: CachedAnswer): Promise<void>;
+    /** Drop every record for a knowledge epoch (invalidation on re-index). */
+    invalidateEpoch(knowledgeEpoch: string): number;
+    get size(): number;
+}
+
+/**
+ * Deterministic resolvers.
+ *
+ * The cheapest LLM call is the one that never happens because the answer can be
+ * *computed* locally. Arithmetic, unit conversions, deterministic string
+ * transforms, lookups in a local table — none of these need a model. A resolver
+ * inspects the canonical request and either produces an answer or declines.
+ * The first resolver to produce a result wins; the pipeline then skips the
+ * entire provider path.
+ */
+interface ResolverResult {
+    text: string;
+    data?: unknown;
+    /** Which resolver produced this, for the trace. */
+    resolver: string;
+}
+interface DeterministicResolver {
+    readonly name: string;
+    try(c: CanonicalRequest): ResolverResult | null;
+}
+declare class ResolverRegistry {
+    private readonly resolvers;
+    register(resolver: DeterministicResolver): this;
+    try(c: CanonicalRequest): ResolverResult | null;
+    get size(): number;
+}
+/**
+ * Safe arithmetic resolver: answers "what is 2 + 2 * 3" style questions using a
+ * tiny, dependency-free shunting-yard evaluator over +, -, *, /, %, parens and
+ * decimals. It never uses eval, and declines anything it does not fully parse.
+ */
+declare const arithmeticResolver: DeterministicResolver;
+/** Shunting-yard evaluation of a numeric expression. Returns null on any parse issue. */
+declare function evalArithmetic(expr: string): number | null;
+/** A registry seeded with the built-in safe resolvers. */
+declare function createDefaultResolvers(): ResolverRegistry;
+
+/**
+ * Execution router (inspired by Adaptive-RAG).
+ *
+ * The single most impactful decision is often not "how do I compress this
+ * prompt" but "does this request need retrieval / tools at all". We do NOT use
+ * a large LLM to decide whether to call a large LLM. The router is:
+ *   deterministic rules  +  a small local classifier hook  +  confidence.
+ *
+ * It is designed to be deployed in SHADOW MODE first: it produces a decision
+ * and a confidence, and you compare its choices against realized cost/quality
+ * before letting it gate execution.
+ *
+ * Robustness note: small paraphrases can flip retrieval decisions. The router
+ * classifies over the *normalized* text and exposes its reasoning so a
+ * paraphrase-stability suite can measure decision drift.
+ */
+interface RouteDecision {
+    executionClass: ExecutionClass;
+    confidence: number;
+    reason: string;
+    /** Suggested number of retrieval rounds (0 for NO_RETRIEVAL). */
+    rounds: number;
+}
+/** Optional local classifier that can override/augment the rules. */
+interface LocalClassifier {
+    classify(text: string): {
+        executionClass: ExecutionClass;
+        confidence: number;
+    } | null;
+}
+declare class ExecutionRouter {
+    private readonly classifier;
+    private readonly maxRounds;
+    constructor(opts?: {
+        classifier?: LocalClassifier;
+        maxRounds?: number;
+    });
+    classify(c: CanonicalRequest): RouteDecision;
+}
+
+/**
+ * Tool selector.
+ *
+ * Full tool schemas can dominate a prompt even when most tools are irrelevant.
+ * The selector picks only the tools whose declared intents match the request,
+ * and — critically — gates write/destructive tools behind explicit rules so a
+ * read-only request can never be handed a mutating capability.
+ */
+interface ToolSelection {
+    tools: ToolDescriptor[];
+    droppedIds: string[];
+    reason: string;
+}
+interface ToolSelectorOptions {
+    /** Max tools to include (schema-token budget guard). */
+    maxTools?: number;
+    /** Tokenizer-aware scorer for tie-breaking (optional). */
+    scoreIntentMatch?: (text: string, tool: ToolDescriptor) => number;
+}
+declare class ToolSelector {
+    private readonly maxTools;
+    private readonly scoreIntentMatch;
+    constructor(opts?: ToolSelectorOptions);
+    select(text: string, tools: ToolDescriptor[] | undefined, execution: ExecutionClass): ToolSelection;
+}
+
+/**
+ * Retrieval planning: retrieve -> dedupe -> rerank -> adaptive-k.
+ *
+ * Eliminating irrelevant context is cheaper and safer than compressing it, so
+ * retrieval prunes aggressively BEFORE anything reaches the prompt. Documents
+ * are kept out of the prompt where possible and passed as references/hashes;
+ * only the selected, trimmed evidence is projected in.
+ */
+interface EvidenceDoc {
+    id: string;
+    text: string;
+    /** Optional pre-computed relevance score from the retriever. */
+    score?: number;
+    source?: string;
+    /** Content hash, so large docs can be referenced instead of inlined. */
+    hash?: string;
+}
+interface Retriever {
+    retrieve(query: string, k: number): Promise<EvidenceDoc[]>;
+}
+interface Reranker {
+    rerank(query: string, docs: EvidenceDoc[]): Promise<EvidenceDoc[]>;
+}
+interface RetrievalPlan {
+    execution: ExecutionClass;
+    query: string;
+    maxRounds: number;
+    maxDocuments: number;
+}
+interface RetrievalOutcome {
+    docs: EvidenceDoc[];
+    rounds: number;
+    retrievedCount: number;
+    keptCount: number;
+}
+/** Remove exact and near-duplicate docs by normalized text / hash. */
+declare function dedupe(docs: EvidenceDoc[]): EvidenceDoc[];
+/**
+ * Adaptive-k: choose how many documents to keep based on the score distribution
+ * rather than a fixed cutoff. When the top document dominates, keep fewer; when
+ * scores are flat, keep up to the cap. This directly trims input tokens.
+ */
+declare function adaptiveK(docs: EvidenceDoc[], opts?: {
+    maxDocuments: number;
+    minDocuments?: number;
+}): EvidenceDoc[];
+/**
+ * Execute a retrieval plan. NO_RETRIEVAL / TOOL_ACTION classes retrieve nothing.
+ * Otherwise: retrieve -> dedupe -> rerank -> adaptive-k, bounded by maxRounds.
+ */
+declare function executeRetrievalPlan(plan: RetrievalPlan, deps: {
+    retriever?: Retriever;
+    reranker?: Reranker;
+}): Promise<RetrievalOutcome>;
+
+/**
+ * Conversational memory by deltas.
+ *
+ * A major source of wasted input tokens is resending the entire chat history
+ * every turn. Instead we keep a compact structured state and, each turn, apply a
+ * small delta produced BY THE MAIN GENERATION (not a separate summarization
+ * call). The next prompt receives: compact relevant state + the last 1-3 raw
+ * turns + the current message — never the whole conversation.
+ */
+interface ConversationState {
+    goals: string[];
+    confirmedFacts: Record<string, unknown>;
+    userPreferences: Record<string, unknown>;
+    decisions: string[];
+    openItems: string[];
+    evidenceRefs: string[];
+}
+interface MemoryDelta {
+    set?: Record<string, unknown>;
+    append?: Record<string, unknown[]>;
+    remove?: string[];
+}
+declare function emptyState(): ConversationState;
+/**
+ * Merge a delta into state locally. `set` updates confirmedFacts/preferences,
+ * `append` pushes onto list fields, `remove` deletes fact keys or list entries.
+ * The merge is deterministic and side-effect-free (returns a new object).
+ */
+declare function mergeDelta(state: ConversationState, delta: MemoryDelta): ConversationState;
+/**
+ * Project the state + recent turns into the minimal message set to send. Only
+ * relevant, non-empty state is serialized, then the last `rawTurns` messages,
+ * then the current message.
+ */
+declare function projectContext(opts: {
+    state: ConversationState;
+    history: ChatMessage[];
+    current: ChatMessage;
+    rawTurns?: number;
+}): ChatMessage[];
+declare function renderState(state: ConversationState): string;
+
+/**
+ * A serializer encodes a structured payload into prompt text, and reports the
+ * instruction overhead a model needs to *understand* that encoding. The format
+ * selector compares `tokens(encode) + tokens(instruction)` across serializers.
+ */
+interface Serializer {
+    readonly format: SerializationFormat;
+    /** Whether this serializer can represent the given value at all. */
+    supports(value: unknown): boolean;
+    encode(value: unknown): string;
+    /**
+     * The instruction text a model needs to interpret this format. For JSON this
+     * is empty; for TOON/CSV it is the per-request cost that must be amortized
+     * before the format is worthwhile.
+     */
+    instruction(value: unknown): string;
+    /**
+     * Decode encoded text back to a value, used ONLY for the selector's round-trip
+     * fidelity check. A serializer without a faithful decoder is treated as
+     * UNVERIFIABLE: the selector will not choose it (fail-closed), so we never ship
+     * — or bill savings for — an encoding we can't prove reproduces the payload.
+     * JSON-compact is inherently lossless and is exempt from the check.
+     */
+    decode?(text: string): unknown;
+}
+
+/**
+ * Compact JSON: the lossless baseline every other format is measured against.
+ * No indentation, no incidental whitespace. This is frequently the *winner* for
+ * deeply nested or non-uniform data, which is exactly why it is the baseline and
+ * TOON is only ever a challenger.
+ */
+declare const jsonCompactSerializer: Serializer;
+
+/**
+ * TOON (Token-Oriented Object Notation) adapter.
+ *
+ * TOON's strength is UNIFORM ARRAYS OF FLAT OBJECTS: it declares the column
+ * names once and then emits one row per object, which removes the repeated keys
+ * that make JSON expensive for tabular data. On deeply nested or non-uniform
+ * data TOON can be *larger* than compact JSON — so this is only ever a candidate
+ * the selector may pick, never a default.
+ *
+ * This is an in-house, pinned encoder placed behind the {@link Serializer}
+ * interface (as recommended: do not couple the system to an upstream `main`).
+ * It emits a well-defined subset and ships a matching decoder so the JSON<->TOON
+ * round-trip is deterministic and testable.
+ */
+interface ToonOptions {
+    /** Field delimiter within tabular/inline rows. */
+    delimiter?: "," | "\t";
+    /** Indentation unit. */
+    indent?: string;
+}
+declare function encodeToon(value: unknown, options?: ToonOptions): string;
+/** Return shared column names iff every element is a flat, scalar-valued object with identical keys. */
+declare function uniformColumns(arr: unknown[]): string[] | null;
+/**
+ * The instruction a model needs to read TOON. Kept short on purpose — this text
+ * is the per-request overhead the selector must amortize before TOON wins.
+ */
+declare const TOON_INSTRUCTION: string;
+declare function createToonSerializer(options?: ToonOptions): Serializer;
+declare const toonSerializer: Serializer;
+
+/**
+ * TOON decoder for the subset emitted by {@link encodeToon}.
+ *
+ * Supports: scalar fields, nested objects, empty arrays, inline scalar arrays
+ * (`key[N]: a,b,c`) and tabular object arrays (`key[N]{c1,c2}:` + rows). This
+ * covers the cases the format selector actually chooses TOON for, and makes the
+ * JSON<->TOON round-trip deterministic and testable. List-form arrays of nested
+ * objects are intentionally out of scope for decoding (the selector never picks
+ * TOON for those, since JSON wins there anyway).
+ */
+interface ToonDecodeOptions {
+    delimiter?: "," | "\t";
+    indent?: string;
+}
+declare function decodeToon(text: string, options?: ToonDecodeOptions): unknown;
+
+/**
+ * CSV serializer — only valid for genuinely tabular data (a uniform array of
+ * flat objects). CSV can be marginally smaller than TOON on pure tables, but it
+ * does NOT preserve the JSON data model in general, so `supports()` is strict.
+ */
+declare const csvSerializer: Serializer;
+
+/**
+ * Format selector.
+ *
+ * TOON is a candidate, never a default. For each request we count, USING THE
+ * DESTINATION MODEL'S TOKENIZER:
+ *
+ *   tokens(encoded payload) + tokens(instruction to understand it)
+ *
+ * ...and pick the cheapest, subject to activation thresholds so we do not switch
+ * formats to save a trivial amount (which risks quality for no real benefit).
+ * JSON-compact is the baseline and the fallback; a format only wins if it beats
+ * JSON by both an absolute and a relative margin.
+ */
+interface FormatSelectorOptions {
+    tokenizer: TokenizerRegistry;
+    serializers?: Serializer[];
+    /** Minimum absolute token saving vs JSON to switch away from JSON. */
+    minimumSavingsTokens?: number;
+    /** Minimum relative saving vs JSON (0..1) to switch away from JSON. */
+    minimumSavingsRatio?: number;
+    /**
+     * Per-(model,format) quality penalty in tokens. Encodes "this model is worse
+     * at reading TOON" as an additive cost, learned from production traces.
+     */
+    qualityPenalty?: (model: string, format: SerializationFormat) => number;
+}
+interface FormatChoice {
+    chosen: SerializationFormat;
+    encoded: string;
+    instruction: string;
+    candidateTokens: Partial<Record<SerializationFormat, number>>;
+    instructionOverheadTokens: number;
+    reason: string;
+}
+declare class FormatSelector {
+    private readonly tokenizer;
+    private readonly serializers;
+    private readonly minSavingsTokens;
+    private readonly minSavingsRatio;
+    private readonly qualityPenalty;
+    constructor(opts: FormatSelectorOptions);
+    choose(payload: unknown, opts: {
+        model?: string;
+        tokenizer?: string;
+    }): FormatChoice;
+}
+
+/**
+ * Structural validation against the JsonSchema subset the layer uses.
+ *
+ * Constrained decoding should prevent invalid structures at generation time,
+ * but a provider without native support can still return free text. This
+ * validator is the deterministic gate that decides whether a response satisfies
+ * its output contract — and, when it does not, whether a single repair is
+ * warranted. NOTE: structural validity is NOT semantic validity; risky tasks
+ * still need a semantic check on top.
+ */
+interface ValidationError {
+    path: string;
+    message: string;
+}
+interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+}
+declare function validateAgainstSchema(value: unknown, schema: JsonSchema, path?: string): ValidationResult;
+
+/**
+ * Schema registry.
+ *
+ * Output contracts are referenced by id (e.g. "research-answer:v3") so they do
+ * not have to be re-transmitted in every prompt once the server knows them.
+ * The registry also enforces "minimal contract" hygiene — arrays should be
+ * bounded, strings length-capped, `additionalProperties` closed — which is how
+ * we keep OUTPUT tokens down, not just input tokens.
+ */
+declare class SchemaRegistry {
+    private readonly contracts;
+    register(contract: OutputContract): this;
+    resolve(contractId: string): OutputContract | undefined;
+    has(contractId: string): boolean;
+    /**
+     * Lint a schema for output-token hygiene. These are warnings, not errors: an
+     * unbounded array or uncapped string is legal JSON Schema but tends to blow up
+     * generation cost, so the layer surfaces them.
+     */
+    static lint(schema: JsonSchema, path?: string): string[];
+}
+
+/**
+ * Constrained-decoding backends.
+ *
+ * The point of these libraries is NOT to compress input — it is to make an
+ * invalid structure impossible to emit, which eliminates the "your JSON is
+ * broken, try again" repair round-trip and lets generation stop exactly when
+ * the object is complete. BV-SALA treats them as interchangeable backends
+ * selected by preference order:
+ *
+ *   provider-native  ->  xgrammar  ->  llguidance  ->  outlines
+ *
+ * They must never all run at once. This module resolves which backend applies
+ * for a given (provider, schema) and exposes a stable descriptor; the actual
+ * runtime binding lives in the provider adapters.
+ */
+type ConstraintBackendId = "provider-native" | "xgrammar" | "llguidance" | "outlines" | "none";
+interface ConstraintBackend {
+    readonly id: ConstraintBackendId;
+    /** Can this backend enforce the given schema for the given model? */
+    supports(model: string, schema: JsonSchema): boolean;
+}
+interface ConstraintPlan {
+    backend: ConstraintBackendId;
+    reason: string;
+}
+/**
+ * Resolve a constraint backend from an ordered preference list. Each candidate
+ * declares whether it supports the (model, schema) pair; the first supporting
+ * backend wins. A conformance suite (see benchmarks/) must confirm that a
+ * backend which *claims* support actually enforces every constraint — declared
+ * support and empirical coverage are not the same thing.
+ */
+declare function resolveConstraintBackend(model: string, schema: JsonSchema, backends: ConstraintBackend[]): ConstraintPlan;
+/** A permissive backend used when the provider validates structured output natively. */
+declare function providerNativeBackend(isSupported?: (model: string, schema: JsonSchema) => boolean): ConstraintBackend;
+
+/**
+ * Context compression (LLMLingua-style), as an OPTIONAL sidecar.
+ *
+ * Two rules make this safe and worthwhile:
+ *
+ *  1. ORDER: eliminate context before compressing it. Dedupe -> rerank ->
+ *     select top-k -> extract relevant spans -> only THEN compress what remains.
+ *     Compressing 20 retrieved docs is worse than dropping 15 of them first.
+ *
+ *  2. PROTECTED SPANS: compression must never touch system instructions, safety
+ *     policies, schemas, grammars, exact code, identifiers, URLs, quantities,
+ *     dates, negations, legal clauses, quoted text, or structured tool results.
+ *     Those are marked and passed through verbatim; the sidecar returns a map so
+ *     we can verify every protected span survived (fidelity check).
+ *
+ * Activation is dynamic: compression adds latency and local compute, so it only
+ * runs when the projected NET saving is positive.
+ */
+interface ProtectedSpan {
+    id: string;
+    text: string;
+}
+interface CompressionRequest {
+    text: string;
+    protectedSpans?: ProtectedSpan[];
+    /** Target compression ratio in (0,1]; 0.5 => aim for ~half the tokens. */
+    targetRatio?: number;
+}
+interface CompressionResult {
+    compressed: string;
+    originalTokens: number;
+    compressedTokens: number;
+    protectedSpans: number;
+    fidelityPassed: boolean;
+    /** True when the sidecar was skipped and the original was returned. */
+    skipped: boolean;
+    reason: string;
+}
+interface Compressor {
+    compress(req: CompressionRequest): Promise<CompressionResult>;
+}
+interface CompressionPolicyInput {
+    contextTokens: number;
+    /** Estimated tokens the compressor could remove. */
+    projectedEliminable: number;
+    /** Estimated local compute cost expressed in equivalent tokens. */
+    compressorCostTokens: number;
+    /** Minimum net token saving required to bother. */
+    minimumNetTokens?: number;
+    /** Do not compress contexts smaller than this. */
+    minimumContextTokens?: number;
+}
+/**
+ * Decide whether compression is net-positive:
+ *   benefit = eliminable - compressorCost - latencyPenalty - qualityRisk
+ * Here we model the token side; latency/quality penalties are folded into
+ * `compressorCostTokens` and `minimumNetTokens` by the caller.
+ */
+declare function shouldCompress(input: CompressionPolicyInput): {
+    compress: boolean;
+    reason: string;
+};
+/**
+ * Protected-span aware wrapper. Extracts protected spans (replacing them with
+ * stable placeholders), runs the inner compressor on the remainder, restores
+ * the spans, and verifies every one survived. On any fidelity failure it falls
+ * back to the ORIGINAL text — a compressor that drops a negation or a number is
+ * worse than no compressor at all.
+ */
+declare function withProtectedSpans(inner: Compressor): Compressor;
+/** No-op compressor: the safe default until a real LLMLingua sidecar is wired in. */
+declare const noopCompressor: Compressor;
+
+/**
+ * Provider-neutral generation interface. Every provider (OpenAI-compatible,
+ * Anthropic-compatible, Google-compatible, self-hosted) is adapted to this
+ * shape so the pipeline never depends on a specific vendor SDK.
+ */
+interface ProviderRequest {
+    model: string;
+    messages: ChatMessage[];
+    tools?: ToolDescriptor[];
+    /** Output contract to enforce via constrained decoding, when available. */
+    schema?: JsonSchema;
+    maxOutputTokens?: number;
+    temperature?: number;
+    seed?: number;
+    /** Backend id selected by the constraints layer, for observability. */
+    constraintBackend?: string;
+}
+interface ProviderUsage {
+    inputTokens: number;
+    outputTokens: number;
+    /** Provider-reported prefix/KV-cached input tokens (ledger 4), if any. */
+    cachedInputTokens?: number;
+}
+interface ProviderResponse {
+    text: string;
+    usage: ProviderUsage;
+    /** Whether the provider enforced the schema natively. */
+    structuredNatively?: boolean;
+    /**
+     * Por qué paró de generar el modelo. `"length"` significa que se quedó sin
+     * presupuesto de salida, no que terminara.
+     *
+     * No es un dato decorativo: distingue una respuesta MALA de una respuesta
+     * CORTADA, y esas dos no se arreglan igual. Un JSON truncado a media cadena no
+     * valida, y reintentar con el MISMO tope vuelve a truncarlo — se paga una
+     * segunda llamada para obtener el mismo fallo. Sin este campo el layer no
+     * podía distinguirlo y hacía exactamente eso.
+     */
+    finishReason?: "stop" | "length" | "content_filter" | "tool_calls" | (string & {});
+    raw?: unknown;
+}
+interface Provider {
+    readonly id: string;
+    generate(req: ProviderRequest): Promise<ProviderResponse>;
+}
+
+/**
+ * Deterministic mock provider.
+ *
+ * Lets the whole layer run — and be tested — with no network and no
+ * credentials. When a schema is supplied it fabricates a schema-valid object,
+ * demonstrating the constrained-decoding contract end to end. Token usage is
+ * derived from the heuristic estimator so SavingsReport numbers are meaningful
+ * in examples and tests.
+ */
+interface MockProviderOptions {
+    /** Fixed text to return when no schema is present. */
+    answer?: string;
+    /** Override the fabricated structured object. */
+    data?: unknown;
+    /** Simulated provider-cached input tokens (ledger 4). */
+    cachedInputTokens?: number;
+}
+declare class MockProvider implements Provider {
+    readonly id = "mock";
+    private readonly options;
+    constructor(options?: MockProviderOptions);
+    generate(req: ProviderRequest): Promise<ProviderResponse>;
+}
+declare function createMockProvider(options?: MockProviderOptions): Provider;
+
+/**
+ * OpenAI-compatible provider adapter (chat/completions shape).
+ *
+ * Works with any endpoint that speaks the OpenAI Chat Completions API — OpenAI,
+ * Azure, vLLM, SGLang, TGI, a local gateway, or Vercel AI Gateway with a
+ * "provider/model" string. Structured output is requested via `response_format`
+ * with a JSON schema when a contract is present, which is the provider-native
+ * constrained-decoding path preferred by the layer.
+ *
+ * Network calls use global `fetch` (Node >= 18) so there is no SDK dependency.
+ */
+interface OpenAICompatibleOptions {
+    baseUrl: string;
+    apiKey?: string;
+    /** Strip the "provider/" prefix from model ids before sending. */
+    stripProviderPrefix?: boolean;
+    /** Extra headers (e.g. for a gateway). */
+    headers?: Record<string, string>;
+    /** Injectable fetch for testing. */
+    fetchImpl?: typeof fetch;
+    /**
+     * When true (recommended for measurement), a response whose `usage` block is
+     * missing or reports zero prompt/completion tokens for a call that actually
+     * ran is treated as a HARD ERROR instead of being silently coerced to
+     * 0 tokens. This closes the single most dishonest failure mode: an absent
+     * usage payload otherwise becomes `actual cost = 0` → a fabricated 100%
+     * saving. Benchmarks that make real cost claims must set this.
+     */
+    requireUsage?: boolean;
+}
+/**
+ * ¿Cumple este esquema las reglas del modo `strict` de OpenAI?
+ *
+ * Son dos, y aplican a TODO objeto anidado:
+ *   1. `additionalProperties: false`.
+ *   2. `required` tiene que listar TODAS las claves de `properties` — no solo
+ *      las obligatorias. En modo strict no existe el campo opcional.
+ *
+ * Un esquema perfectamente válido como
+ *   { properties: { answer, refs }, required: ["answer"] }
+ * incumple la segunda y el proveedor responde 400. No es un fallo del cliente:
+ * es una restricción de OpenAI que JSON Schema no tiene.
+ */
+declare function isStrictCompatible(schema: unknown): boolean;
+declare class OpenAICompatibleProvider implements Provider {
+    readonly id: string;
+    private readonly opts;
+    private readonly fetchImpl;
+    constructor(opts: OpenAICompatibleOptions);
+    generate(req: ProviderRequest): Promise<ProviderResponse>;
+}
+
+/**
+ * Trace collector: an ordered log of pipeline decisions with elapsed timings.
+ * Every stage records why it did what it did, so a SavingsReport can be audited
+ * and so ablations can attribute savings to a specific module.
+ */
+declare class TraceCollector {
+    private readonly events;
+    private readonly start;
+    private readonly now;
+    constructor(now?: () => number);
+    record(stage: string, outcome: string, detail?: Record<string, unknown>): void;
+    elapsed(): number;
+    all(): TraceEvent[];
+}
+
+/**
+ * Thrown when the pipeline is asked to run without a valid, active BiVelio
+ * license. This is the fail-closed contract: a paid SDK must refuse to operate
+ * unlicensed, rather than silently serving requests for free.
+ */
+declare class LicenseError extends Error {
+    /** Resolved license status, when known: expired | invalid | revoked | none. */
+    readonly status?: string;
+    constructor(message: string, status?: string);
+}
+
+/**
+ * Offline license verification for the paid SDK.
+ *
+ * A license is a compact signed token `base64url(header).base64url(payload).
+ * base64url(sig)` (the exact format the licensing service mints in
+ * `@bivelio/license-client`'s `signLicense`). We verify the Ed25519 signature
+ * against BiVelio's public key, decode the payload, and apply the same grace
+ * policy the license-client uses. Verification is **browser-safe**: it uses
+ * `@noble/curves` (pure JS) + Web primitives (`atob`, `TextEncoder`) rather than
+ * `node:crypto`, so the shared `src/index.ts` still compiles into the browser
+ * demo bundle. The private signing key never leaves the control plane; only the
+ * public key is embedded here, so a token cannot be forged or tampered with.
+ */
+type LicenseStatus = "active" | "grace" | "expired" | "invalid" | "revoked";
+/** Decoded license token body (mirror of `@bivelio/protocol`'s LicensePayload,
+ *  declared locally so the SDK stays free of a control-plane dependency). */
+interface LicenseTokenPayload {
+    jti: string;
+    org_id: string;
+    plan: string;
+    seats: number;
+    features: string[];
+    issued_at: number;
+    expires_at: number;
+    grace_days: number;
+    iss?: string;
+}
+interface ResolvedLicense {
+    status: LicenseStatus;
+    payload?: LicenseTokenPayload;
+    reason?: string;
+}
+declare const EMBEDDED_PUBLIC_KEY: string;
+/** Result of verifying a compact `head.body.sig` token's signature. */
+interface CompactVerification {
+    /** True only if the signature is valid for the given public key. */
+    ok: boolean;
+    /** Decoded header (present when `ok`), e.g. `{ alg, typ, v }`. */
+    header?: Record<string, unknown>;
+    /** Raw payload bytes (present when `ok`); the caller decodes/parses them. */
+    payloadBytes?: Uint8Array;
+    reason?: string;
+}
+/**
+ * A pinned set of Ed25519 public keys addressed by key-id (`kid`), enabling signing
+ * key ROTATION without breaking already-deployed SDKs: new keys are added as extra
+ * map entries, and tokens carry the `kid` they were signed with. `defaultKid` is the
+ * key used for legacy tokens that carry NO `kid` (so today's single-key tokens keep
+ * verifying unchanged). Verification FAILS CLOSED on a `kid` not in the map.
+ */
+interface LicenseKeyset {
+    /** kid → SPKI PEM. */
+    keys: Record<string, string>;
+    /** kid used for tokens without a `kid` header (the current/legacy key). */
+    defaultKid: string;
+}
+/** Narrow a verification key to a {@link LicenseKeyset} (vs a bare SPKI PEM string). */
+declare function isKeyset(k: string | LicenseKeyset): k is LicenseKeyset;
+/**
+ * Verify the Ed25519 signature of any BV-SALA compact token
+ * (`base64url(header).base64url(body).base64url(sig)`, sig over `${head}.${body}`)
+ * and return the decoded header + raw payload bytes. This is the single shared
+ * crypto primitive: license tokens AND signed revocation lists both go through it,
+ * so the browser (`@noble/curves`) and node (`node:crypto`) sides agree byte-for-byte
+ * and there is no bespoke per-message verification path to keep in sync. It does NOT
+ * interpret the payload or the header `typ` — callers do that.
+ */
+declare function verifyCompactSignature(token: string, publicKey: string | LicenseKeyset): CompactVerification;
+/** Verify a token's signature and decode its payload. Does not check expiry. */
+declare function verifyLicenseToken(token: string, publicKey: string | LicenseKeyset): {
+    signatureValid: boolean;
+    payload?: LicenseTokenPayload;
+    reason?: string;
+};
+/**
+ * Apply the grace + revocation policy to an already-decoded payload → a status.
+ * Pure and clock-injected, so a LIVE gate can call it on every request to pick up
+ * both revocation (jti in the set) AND expiry transitions without re-verifying the
+ * signature. Revocation takes precedence over the time-based status.
+ *   jti on the revocation set            → revoked
+ *   now <= expires_at                    → active
+ *   expires_at < now <= +grace_days      → grace (still entitled)
+ *   now > expires_at + grace_days        → expired
+ */
+declare function deriveStatus(payload: {
+    jti: string;
+    expires_at: number;
+    grace_days: number;
+}, nowSeconds: number, revoked?: ReadonlySet<string>): LicenseStatus;
+/**
+ * Verify + apply the grace policy → a resolved status. Mirrors
+ * `@bivelio/license-client`'s `LicenseClient.resolve`. Bad signature / malformed
+ * → invalid; otherwise the status comes from {@link deriveStatus}.
+ */
+declare function resolveLicense(token: string, publicKey: string | LicenseKeyset, opts?: {
+    nowSeconds?: number;
+    revoked?: ReadonlySet<string>;
+}): ResolvedLicense;
+
+/** Decoded revocation-list body (mirror of @bivelio/protocol's RevocationListPayload). */
+interface RevocationListBody {
+    v: number;
+    asOf: number;
+    seq: number;
+    revoked: string[];
+    iss?: string;
+}
+interface RevocationListVerification {
+    /** True only if signature + typ + monotonic-seq + skew all pass. */
+    ok: boolean;
+    /** List revision (monotonic). -1 when not ok. */
+    seq: number;
+    /** Unix seconds the list was minted. 0 when not ok. */
+    asOf: number;
+    /** Revoked jti in this list (empty when not ok). */
+    revoked: Set<string>;
+    reason?: string;
+}
+/**
+ * Verify a signed revocation-list token offline and enforce the client-side
+ * policy: (1) valid Ed25519 signature, (2) header `typ` is a revocation list
+ * (a license token can't be replayed here), (3) `seq >= minSeq` — reject a
+ * stale/rolled-back list, (4) `asOf <= now + maxSkew` — reject a future-dated list.
+ * ANY failure returns `ok:false` with an empty set; the poller then keeps its
+ * sticky last-known-good (fail-open), never dropping known revocations.
+ */
+declare function verifyRevocationList(token: string, publicKey: string | LicenseKeyset, opts?: {
+    minSeq?: number;
+    nowSeconds?: number;
+    maxSkewSeconds?: number;
+}): RevocationListVerification;
+/**
+ * The SDK's live, sticky, monotonic view of the revocation set. It only ever
+ * GROWS (a jti, once seen revoked, stays revoked for the process lifetime) and
+ * only advances on a higher-or-equal `seq` — so a stale, rolled-back, or empty
+ * list can never un-revoke a license. The live gate reads {@link snapshot} on
+ * every request; the poller feeds it via {@link apply}.
+ */
+declare class RevocationSnapshot {
+    private _seq;
+    private _asOf;
+    private _lastContactAt;
+    private readonly set;
+    get seq(): number;
+    get asOf(): number;
+    /** Unix seconds of the last CONFIRMED authorized heartbeat (a 304 or a verified
+     *  list). Feeds the live gate's online staleness check; 0 until the first one. */
+    get lastContactAt(): number;
+    /** Record a confirmed authorized heartbeat from the control plane (monotonic). */
+    markContact(nowSeconds: number): void;
+    has(jti: string): boolean;
+    /** Live view of the revoked set (the same Set instance — read-only to callers). */
+    snapshot(): ReadonlySet<string>;
+    /**
+     * Merge an already-verified list. Accepts only `seq >= current seq`; UNIONS the
+     * jti (never removes); advances seq/asOf monotonically. Returns whether the
+     * revoked set grew or the revision advanced.
+     */
+    apply(list: {
+        seq: number;
+        asOf: number;
+        revoked: Iterable<string>;
+    }): boolean;
+}
+
+/** A resolved gate that also exposes overall status + a refresh horizon. */
+interface ResolvedGate extends LicenseGate {
+    isActive(): boolean;
+    status(): LicenseStatus;
+    /** Unix seconds after which the online status should be re-checked (poller anchor). */
+    refreshAfter?(): number | undefined;
+}
+/**
+ * Build a LIVE license gate from a signed key. The token is verified + decoded
+ * ONCE (no per-request Ed25519 verify — hot-path safe); each `isActive()` /
+ * `status()` / `isEntitled()` then re-derives the status from the cached payload +
+ * the LIVE clock + the (mutable, sticky) {@link RevocationSnapshot}. This is what
+ * lets a revocation — or an expiry crossed mid-process — take effect without a
+ * restart, while the customer request path never touches the network (it reads an
+ * in-memory Set).
+ *
+ * The offline path passes a fresh, never-updated snapshot (live clock, zero
+ * network); the online path passes a snapshot a {@link RevocationPoller} feeds.
+ */
+declare function liveGateFromKey(licenseKey: string, publicKey: string | LicenseKeyset, opts: {
+    revocation: RevocationSnapshot;
+    now?: () => number;
+    /** Online staleness ceiling, seconds. If the gate goes this long without a
+     *  confirmed authorized heartbeat, it stops granting (closes the block-egress
+     *  fail-open). Undefined = check disabled (the offline path never sets it). */
+    maxStalenessSeconds?: number;
+    /** Freshness anchor (unix seconds); defaults to construction time (boot). */
+    startedAt?: number;
+}): ResolvedGate;
+
+/**
+ * Build the SDK's structural {@link import("../contracts/types.js").LicenseGate}
+ * from a signed license key — the object `createSavingsLayer({ licenseKey })`
+ * injects on the OFFLINE path (no `licenseServerUrl`).
+ *
+ * It is a LIVE gate over an EMPTY, never-updated revocation snapshot: zero network,
+ * but the clock is LIVE, so a license that crosses its expiry (past grace) stops
+ * working mid-process instead of only after a restart — closing the frozen-clock
+ * hole the old one-shot resolution left open. `isActive()` is true while active or
+ * in grace; `isEntitled` additionally requires the feature in the token's grant.
+ * Online revocation is added by pairing {@link liveGateFromKey} with a
+ * poller-fed snapshot (see src/pipeline/create.ts + poller.ts).
+ */
+declare function gateFromKey(licenseKey: string, publicKey: string | LicenseKeyset, now?: () => number): ResolvedGate;
+
+type RevocationPollEvent = {
+    type: "applied";
+    seq: number;
+    size: number;
+} | {
+    type: "unchanged";
+    seq: number;
+} | {
+    type: "rejected";
+    reason: string;
+} | {
+    type: "error";
+    error: unknown;
+} | {
+    type: "no-fetch";
+};
+interface RevocationPollerOptions {
+    /** Absolute URL of GET /licenses/revocations. */
+    url: string;
+    /** SPKI PEM (or a kid-addressed {@link LicenseKeyset}) used to verify the signed
+     *  list — the same key/keyset that verifies license tokens. */
+    publicKeyPem: string | LicenseKeyset;
+    /** The sticky snapshot to feed. */
+    snapshot: RevocationSnapshot;
+    /** Anchor cadence to the license refresh horizon (unix seconds). */
+    getRefreshAfter?: () => number | undefined;
+    /** Injectable clock (unix seconds). */
+    nowSeconds?: () => number;
+    /** Injectable fetch (defaults to the global). */
+    fetchImpl?: typeof fetch;
+    pollIntervalSeconds?: number;
+    floorSeconds?: number;
+    maxIntervalSeconds?: number;
+    jitterRatio?: number;
+    maxSkewSeconds?: number;
+    requestTimeoutMs?: number;
+    /** Injectable RNG in [0,1) for jitter. Default Math.random. */
+    random?: () => number;
+    /** Optional observer (telemetry/tests). */
+    onEvent?: (e: RevocationPollEvent) => void;
+}
+/**
+ * PURE, unit-testable next-delay policy (seconds). Steady state anchors to the
+ * license refresh horizon, clamped to [floor, ceiling] and jittered. After a
+ * failure it backs off exponentially (a revocation can't land during an outage
+ * anyway), capped, still jittered, never below the floor.
+ */
+declare function computeNextDelay(opts: {
+    refreshAfter?: number;
+    nowSeconds: number;
+    consecutiveFailures: number;
+    floorSeconds: number;
+    pollIntervalSeconds: number;
+    maxIntervalSeconds: number;
+    jitterRatio: number;
+    random?: () => number;
+}): number;
+declare class RevocationPoller {
+    private readonly opts;
+    private timer;
+    private controller;
+    private consecutiveFailures;
+    private stopped;
+    private started;
+    private warnedNoFetch;
+    /** ETag of the last 200; sent as If-None-Match so an unchanged list 304s (cheap no-op). */
+    private lastEtag;
+    /** 304 seguidos; al llegar al tope se fuerza una descarga firmada. */
+    private consecutive304;
+    constructor(opts: RevocationPollerOptions);
+    private now;
+    private resolveFetch;
+    /**
+     * One poll cycle: fetch → verify → apply. NEVER throws (fail-open). A reachable
+     * CP resets the failure backoff even if the returned list is rejected — we keep
+     * last-known-good. Only a transport/abort/parse error counts as a failure.
+     */
+    pollOnce(): Promise<void>;
+    /** Fire one non-blocking warm poll, then self-schedule. Idempotent. */
+    start(): void;
+    private schedule;
+    /** Stop polling and abort any in-flight request. Idempotent. */
+    stop(): void;
+}
+
+interface UsageEmitterOptions {
+    /** Full ingest URL, e.g. `https://savings.bivelio.com/api/metering/usage`. */
+    url: string;
+    /** Service-account key (`bvk_…`) sent as a Bearer token; the server derives the org from it. */
+    serviceAccountKey: string;
+    /** Optional org hint; the server always derives the authoritative org from the key. */
+    orgId?: string;
+    /** Flush cadence in ms (default 15000). */
+    flushIntervalMs?: number;
+    /** Records per POST (default 50). */
+    maxBatch?: number;
+    /** Hard in-memory cap; oldest records are dropped past it (default 1000). */
+    maxBuffer?: number;
+    /** Injectable fetch (defaults to the global). */
+    fetchImpl?: typeof fetch;
+    /** Injectable clock. */
+    now?: () => number;
+    /** Whether this process is a CI/ephemeral runner (excluded from billable seats). */
+    ci?: boolean;
+}
+/**
+ * Buffers counts-only usage and flushes it to the control plane. DETECTIVE
+ * metering: strictly best-effort and NON-BLOCKING. `record()` is O(1) and
+ * `flush()` never throws, so a slow, unreachable, or erroring control plane can
+ * neither block nor crash the customer's request path. The buffer is hard-capped
+ * so a sustained outage can never grow memory without bound.
+ */
+declare class UsageEmitter {
+    private readonly options;
+    private readonly now;
+    private readonly flushIntervalMs;
+    private readonly maxBatch;
+    private readonly maxBuffer;
+    private buffer;
+    private seatId;
+    private ci;
+    private timer;
+    private flushing;
+    constructor(options: UsageEmitterOptions);
+    /** Set the resolved seat identity (derivation is async; records emitted before
+     *  it resolves are stamped at flush time, so none are lost). */
+    setSeat(seatId: string | undefined, ci: boolean): void;
+    /** Record one request's usage. Never blocks; O(1). */
+    record(report: SavingsReport): void;
+    start(): void;
+    /** Stop the timer and attempt a final flush. Safe to call more than once. */
+    stop(): void;
+    /**
+     * Flush one batch. Never throws. A transient server error (5xx) or network
+     * failure re-queues the batch (capped); a 4xx (bad request / bad key) drops it,
+     * since retrying a rejected payload would loop forever.
+     */
+    flush(): Promise<void>;
+    private requeue;
+    private toWire;
+}
+
+/**
+ * DETECTIVE seat identity for usage metering. A "seat" is a distinct MACHINE /
+ * service identity — NEVER a human. `deriveSeatId` produces a stable, opaque,
+ * per-account id by HMAC-ing a machine fingerprint with the service-account key:
+ *   - stable across restarts on the same machine (same billable seat),
+ *   - never reveals the fingerprint (HMAC keyed by the secret SA key),
+ *   - different accounts on the same machine get different ids.
+ *
+ * Universal + dependency-free: uses only WebCrypto (`globalThis.crypto.subtle`)
+ * and ambient `process` env, both guarded — so this module carries NO Node builtin
+ * import and is safe in the browser bundle (where it simply yields no seat id).
+ */
+/** True when running in a CI / ephemeral environment. */
+declare function detectCi(): boolean;
+/**
+ * Derive the machine seat id for a service-account key. Resolves to `undefined`
+ * when no machine fingerprint is available (e.g. a browser) — the caller then
+ * reports no seatId and the server counts the request under an "unknown" seat.
+ * The id (`m-<32 hex>`) matches the control plane's identity charset.
+ */
+declare function deriveSeatId(serviceAccountKey: string): Promise<string | undefined>;
+
+/**
+ * Everything the pipeline depends on. All fields except `provider` and
+ * `tokenizer` are optional; sensible in-memory defaults are wired by
+ * {@link createSavingsLayer} so the layer works out of the box and every
+ * component is independently swappable.
+ */
+interface SavingsLayerConfig {
+    /**
+     * Contratos a los que ya se les incumplió una restricción de valor.
+     *
+     * La capa lo aprende sola, pero lo aprendido muere con la instancia. En
+     * serverless —una instancia por petición— eso significa no aprender NUNCA:
+     * cada llamada estrena y paga su reparación. Pasar aquí un conjunto
+     * compartido (o respaldado por Redis, con la API de Set) hace que se aprenda
+     * una vez para todo el despliegue.
+     *
+     * Solo guarda identificadores de contrato, nunca contenido de peticiones.
+     */
+    constraintMemory?: Set<string>;
+    provider: Provider;
+    tokenizer: TokenizerRegistry;
+    exactCache?: ExactCache;
+    semanticCache?: InMemorySemanticCache;
+    singleflight?: Singleflight;
+    resolvers?: ResolverRegistry;
+    router?: ExecutionRouter;
+    toolSelector?: ToolSelector;
+    formatSelector?: FormatSelector;
+    schemaRegistry?: SchemaRegistry;
+    constraintBackends?: ConstraintBackend[];
+    compressor?: Compressor;
+    retriever?: Retriever;
+    reranker?: Reranker;
+    /**
+     * Signed BiVelio license token (from your paid subscription). This is the
+     * primary way to license the SDK: `createSavingsLayer` verifies it offline
+     * against the embedded public key and builds a {@link licenseGate} from it.
+     * Without a valid, active license (and without {@link devUnlicensed}), the
+     * pipeline refuses to run — get a key at https://savings.bivelio.com.
+     */
+    licenseKey?: string;
+    /**
+     * Override the public key used to verify {@link licenseKey}. An SPKI PEM string,
+     * or a kid-addressed {@link LicenseKeyset} (`{ keys: {kid: pem}, defaultKid }`)
+     * to support signing-key rotation — legacy no-kid tokens use `defaultKid`, and
+     * an unknown kid fails closed. For self-hosting/self-testing; defaults to the
+     * build-embedded BiVelio key.
+     */
+    licensePublicKey?: string | LicenseKeyset;
+    /**
+     * Pre-built license gate. Usually you pass {@link licenseKey} instead and let
+     * the SDK construct this. Advanced/self-managed callers can inject their own
+     * gate (e.g. `@bivelio/license-client`'s `createLicenseGate()`). When both are
+     * given, `licenseGate` wins.
+     */
+    licenseGate?: LicenseGate;
+    /**
+     * OPT-IN online revocation call-home. When set (alongside {@link licenseKey} and
+     * with no explicit {@link licenseGate}), the SDK polls this base's
+     * `GET /licenses/revocations` for a signed revocation list and enforces it via a
+     * LIVE gate — a license cancelled mid-term stops working without a restart.
+     *
+     * NEVER-BRICK: the customer request path never blocks on the fetch; the warm poll
+     * is fired but not awaited, and any failed/unreachable poll is a no-op that keeps
+     * the last-known-good snapshot. Leaving this unset keeps the fully-offline,
+     * zero-network default path. Pass the base URL of the licensing service, e.g.
+     * `https://savings.bivelio.com`.
+     */
+    licenseServerUrl?: string;
+    /**
+     * Steady-state ceiling between revocation polls, in seconds (default 900 = 15 min).
+     * The effective cadence tightens near license expiry and has a hard floor.
+     */
+    licensePollIntervalSeconds?: number;
+    /** Injectable `fetch` for the revocation poller (defaults to the global). Testing/proxy. */
+    licenseFetch?: typeof fetch;
+    /** Advanced tuning of the revocation poller cadence + skew tolerance. */
+    licenseRevocation?: {
+        /** Hard floor between polls, seconds (default 300). */
+        floorSeconds?: number;
+        /** Backoff ceiling during a control-plane outage, seconds (default 3600). */
+        maxIntervalSeconds?: number;
+        /** Jitter fraction ± (default 0.1). */
+        jitterRatio?: number;
+        /** Reject a signed list whose `asOf` is more than this far in the future, seconds (default 300). */
+        maxSkewSeconds?: number;
+        /**
+         * ONLINE staleness ceiling, seconds (default ~6h). If the SDK goes this long
+         * without a CONFIRMED authorized heartbeat (a 304 or a verified list), the LIVE
+         * gate stops granting — closing the fail-open window where blocking egress keeps
+         * a revoked license alive until natural expiry. Must exceed the poll cadence
+         * with margin. Applies ONLY on the online path ({@link licenseServerUrl} set);
+         * it is NOT a zero-network opt-out — use the offline path for that.
+         */
+        maxStalenessSeconds?: number;
+    };
+    /**
+     * Service-account key (`bvk_…`) that authenticates DETECTIVE usage metering to
+     * the control plane. When set (alongside {@link licenseServerUrl} or an explicit
+     * {@link meteringUrl}), the SDK reports COUNTS-ONLY usage after each request —
+     * request id, model, cache outcome, and token/cost counts, tagged with an
+     * auto-derived machine seat id — NEVER prompts or completions. Best-effort and
+     * non-blocking: a slow or unreachable control plane never blocks or breaks
+     * `generate()`. Get the key from your dashboard.
+     */
+    serviceAccountKey?: string;
+    /**
+     * Usage-ingest URL. Defaults to `${licenseServerUrl}/api/metering/usage`. Set
+     * explicitly to point metering at a different host than the revocation poller.
+     */
+    meteringUrl?: string;
+    /** Injectable `fetch` for metering (defaults to {@link licenseFetch}, then global). */
+    meteringFetch?: typeof fetch;
+    /** DETECTIVE metering tuning (all optional). */
+    metering?: {
+        /** Off switch even when {@link serviceAccountKey} is set (default: on). */
+        enabled?: boolean;
+        /** Flush cadence in ms (default 15000). */
+        flushIntervalMs?: number;
+        /** Records per POST (default 50). */
+        maxBatch?: number;
+        /** Hard in-memory cap; oldest records dropped past it (default 1000). */
+        maxBuffer?: number;
+        /** Override the auto-derived machine seat id. */
+        seatId?: string;
+        /** Override CI auto-detection (CI/ephemeral seats are excluded from billable seats). */
+        ci?: boolean;
+        /** Optional org hint; the server derives the authoritative org from the key. */
+        orgId?: string;
+    };
+    /**
+     * Development-only escape hatch to run ungated, honored ONLY when building from
+     * source (local dev, CI, benchmarks) — also via the `BVSALA_DEV_OPEN=1`
+     * environment variable.
+     *
+     * IMPORTANT: this flag is **disabled in the published npm package**. The
+     * distributed build hard-codes the licensing check on, so setting
+     * `devUnlicensed` (or `BVSALA_DEV_OPEN`) there has NO effect — the layer still
+     * requires a valid `licenseKey`. It is not a way to run the product for free.
+     */
+    devUnlicensed?: boolean;
+    /** Per-model cost models; falls back to `defaultCostModel`. */
+    costModels?: Record<string, CostModel>;
+    defaultCostModel?: CostModel;
+    /** TTL for exact-cache writes, in ms. */
+    exactCacheTtlMs?: number;
+    /**
+     * Reliability contract. When true (the default), ANY internal optimizer error
+     * (a resolver, cache, format selector, compressor, or accounting bug) is
+     * caught and the request falls open to a plain provider call — BV-SALA must
+     * never add a crash point to the customer's request path. Set to `false` only
+     * in tests/benchmarks that want internal errors to surface.
+     */
+    failOpen?: boolean;
+    /** Injectable clock for deterministic tests. */
+    now?: () => number;
+    /** Injectable id generator for deterministic tests. */
+    generateId?: () => string;
+}
+declare const DEFAULT_COST_MODEL: CostModel;
+
+/** Fully-resolved, non-optional dependency set the pipeline runs against. */
+interface ResolvedDeps {
+    exactCache: ExactCache;
+    semanticCache: InMemorySemanticCache | undefined;
+    singleflight: Singleflight;
+    resolvers: ResolverRegistry;
+    router: ExecutionRouter;
+    toolSelector: ToolSelector;
+    formatSelector: FormatSelector;
+    schemaRegistry: SchemaRegistry;
+    constraintBackends: ConstraintBackend[];
+}
+/**
+ * Wire defaults for anything the caller did not supply. Every default is an
+ * in-memory, dependency-free implementation, so `createSavingsLayer({ provider,
+ * tokenizer })` is a working layer, and each piece can be replaced à la carte.
+ */
+declare function resolveDependencies(config: SavingsLayerConfig): ResolvedDeps;
+
+/** The public handle returned by {@link createSavingsLayer}. */
+interface SavingsLayer {
+    generate<T = unknown>(request: SavingsRequest): Promise<SavingsResult<T>>;
+    /**
+     * Stop the background revocation poller (when the online call-home was enabled
+     * via `licenseServerUrl`) and abort any in-flight request. Always safe to call —
+     * a no-op when there is no poller. Call it when shutting down a long-running
+     * process so the interval timer and any pending fetch are released.
+     */
+    close(): void;
+}
+/**
+ * Create a savings layer. The only hard requirement is a `provider`; a default
+ * heuristic tokenizer and in-memory implementations of every other component
+ * are wired automatically. Replace any of them for production (Redis exact
+ * cache, pgvector/Qdrant semantic cache, a real tokenizer, an LLMLingua sidecar,
+ * XGrammar/llguidance backends, etc.).
+ *
+ * @example
+ * const layer = createSavingsLayer({ provider: createMockProvider() });
+ * const { data, report } = await layer.generate({
+ *   model: "openai/gpt-4o-mini",
+ *   messages: [{ role: "user", content: "What is 2 + 2 * 3?" }],
+ * });
+ */
+declare function createSavingsLayer(config: Omit<SavingsLayerConfig, "tokenizer"> & Partial<Pick<SavingsLayerConfig, "tokenizer">>): SavingsLayer;
+
+/**
+ * bivelio-savings-layer (BV-SALA)
+ * ---------------------------------------------------------------------------
+ * PROPRIETARY AND CONFIDENTIAL. Copyright (c) 2026 BiVelio Inc.
+ * All Rights Reserved. Unauthorized copying, distribution, or use of this
+ * software, in whole or in part, is strictly prohibited. See LICENSE.
+ * ---------------------------------------------------------------------------
+ *
+ * A provider-neutral LLM execution optimizer. For every request it answers, in
+ * order: Can I avoid this call? Can I avoid retrieval? Can I send fewer tools?
+ * What context is actually needed? Should I compress it? Which format costs
+ * least for this tokenizer? What is the minimal output contract? Is the saving
+ * still positive after all infrastructure is counted?
+ *
+ * It keeps FOUR separate ledgers — avoided_calls, eliminated_tokens,
+ * compressed_tokens, provider_cached_tokens — because mixing them produces
+ * misleading metrics.
+ */
+declare const BV_SALA_VERSION = "0.1.0";
+
+export { BV_SALA_VERSION, type BivelioHandoff, type CacheOutcome, type CachedAnswer, type CanonicalRequest, type ChatMessage, type CompactVerification, type CompressionPolicyInput, type CompressionRequest, type CompressionResult, type Compressor, type ConstraintBackend, type ConstraintBackendId, type ConstraintPlan, type ConversationState, type CostBasis, type CostModel, DEFAULT_COST_MODEL, type DeterministicResolver, EMBEDDED_PUBLIC_KEY, type EmbeddingFn, type EvidenceDoc, type ExactCache, ExactTokenizer, type ExecutionClass, ExecutionRouter, type FormatChoice, FormatSelector, type FormatSelectorOptions, type HandoffFact, HeuristicEstimator, InMemoryExactCache, InMemorySemanticCache, type JsonSchema, LicenseError, type LicenseGate, type LicenseKeyset, type LicenseStatus, type LicenseTokenPayload, type LocalClassifier, MODELOS_POR_CODIFICACION, type MemoryDelta, type MessageRole, MockProvider, type MockProviderOptions, type OpenAICompatibleOptions, OpenAICompatibleProvider, type OutputContract, type Policy, type ProtectedSpan, type Provider, type ProviderRequest, type ProviderResponse, type ProviderUsage, type RequestContext, type Reranker, type ResolvedDeps, type ResolvedGate, type ResolvedLicense, ResolverRegistry, type ResolverResult, type RetrievalOptions, type RetrievalOutcome, type RetrievalPlan, type Retriever, type RevocationListBody, type RevocationListVerification, type RevocationPollEvent, RevocationPoller, type RevocationPollerOptions, RevocationSnapshot, type RouteDecision, type SavingsLayer, type SavingsLayerConfig, SavingsLedger, type SavingsReport, type SavingsRequest, type SavingsResult, type SavingsToggles, SchemaRegistry, type SemanticCacheOptions, type SemanticHit, type SemanticRecord, type SemanticVerifier, type SerializationFormat, type Serializer, Singleflight, TOON_INSTRUCTION, type TokenEstimator, TokenizerRegistry, type ToolDescriptor, type ToolRisk, type ToolSelection, ToolSelector, type ToolSelectorOptions, type ToonDecodeOptions, type ToonOptions, TraceCollector, type TraceEvent, UsageEmitter, type UsageEmitterOptions, type ValidationError, type ValidationResult, adaptiveK, arithmeticResolver, buildExactKey, buildInflightKey, canonicalize, computeNextDelay, cosine, createDefaultResolvers, createHandoff, createMockProvider, createSavingsLayer, createToonSerializer, csvSerializer, decodeToon, dedupe, defaultTokenizerRegistry, deriveSeatId, deriveStatus, detectCi, emptyState, encodeToon, evalArithmetic, evaluatePolicy, executeRetrievalPlan, gateFromKey, heuristicEstimator, isKeyset, isStrictCompatible, jsonCompactSerializer, keyTokensMatch, liveGateFromKey, mergeDelta, noopCompressor, normalizeText, projectContext, providerNativeBackend, randomId, registrarTokenizadorExacto, renderState, resolveConstraintBackend, resolveDependencies, resolveLicense, sha256, shouldCompress, stableStringify, toonSerializer, uniformColumns, validateAgainstSchema, verifyCompactSignature, verifyLicenseToken, verifyRevocationList, withProtectedSpans };