@bivelio/savings-layer 0.4.22 → 0.4.25

package/dist/index.d.ts

@@ -11,6 +11,20 @@
  * Where the baseline being compared against comes from.
  *
  * - `measured`   — reconstructed from this request's provider counter. Real money.
+ * - `reference`  — MEASURED BY REFERENCE: the call was avoided (a repeat served
+ *                  without calling the provider) and a byte-identical request had
+ *                  already run through the layer untouched. The baseline is the
+ *                  provider's own counter for that request, valued at the
+ *                  provider's cached-input rate. Output is credited only under
+ *                  deterministic sampling, on a model with a list price in the
+ *                  catalog that does not reason and honors that setting, when
+ *                  the call that ran carried no hidden reasoning (zero reasoning
+ *                  tokens reported, or no reasoning block where the provider
+ *                  does not break them out), and then at 95% of its counter.
+ *                  With an output schema, only when the schema traveled exactly
+ *                  as sent, in strict mode, in the provider's native
+ *                  response-format parameter. Valued low on purpose. Enters the
+ *                  commission base.
  * - `estimated`  — the call was AVOIDED: it never ran, so there is no provider
  *                  counter and the baseline comes from the local estimator. Still
  *                  the best figure available, but not measured.
@@ -24,7 +38,7 @@
  * exactly what a verify-don't-trust product cannot do — and adding `shadow` to
  * either would be making the savings up.
  */
-type CostBasis = "measured" | "estimated" | "unmeasured" | "shadow";
+type CostBasis = "measured" | "reference" | "estimated" | "unmeasured" | "shadow";
 interface CostModel {
     /** Cost per 1K input tokens, in the caller's currency unit. */
     inputPer1k: number;
@@ -33,6 +47,61 @@ interface CostModel {
     /** Optional discounted rate for provider-cached (prefix) input tokens. */
     cachedInputPer1k?: number;
 }
+/** Oldest provider counter a repeat can be valued against: one billing period. */
+declare const REFERENCE_MAX_AGE_MS: number;
+/** Share of the counted output credited to a repeat: only under deterministic sampling, on a catalog model that does not reason and honors it, when the call that ran carried no hidden reasoning. */
+declare const REFERENCE_OUTPUT_SHARE = 0.95;
+/** Input tokens deducted per piece the layer inserted in the call that ran: a message, the wrapper around a native output schema, or half of the empty parameters given to a tool that had none. */
+declare const REFERENCE_MESSAGE_ALLOWANCE = 8;
+/**
+ * Why an avoided call (a cache or coalesced hit) could not be valued by
+ * reference, and so stays `estimated`.
+ *
+ * - `absent`            — the stored answer carries no provider counter.
+ * - `malformed`         — it carries one, but not in a readable shape.
+ * - `witness`           — the counter is not bound to the answer being served.
+ * - `model-mismatch`    — the counter belongs to another model.
+ * - `expired`           — the counter is older than one billing period.
+ * - `different-request` — the request that ran was not byte-identical to this one.
+ * - `quality`           — the answer being served fails its output contract.
+ * - `no-cached-price`   — no documented cached-input rate for this exact model:
+ *                         its own catalogue row (or a dated snapshot of it) or
+ *                         `costModels`, never a row inherited from a sibling id.
+ * - `no-credit`         — nothing left to credit once the allowances are applied.
+ */
+type ReferenceRejection = "absent" | "malformed" | "witness" | "model-mismatch" | "expired" | "different-request" | "quality" | "no-cached-price" | "no-credit";
+/**
+ * The provider counter an avoided call is valued against, and every figure
+ * needed to recompute its baseline:
+ * `tierFactor * (creditedInputTokens / 1000 * cachedInputPer1k + creditedOutputTokens / 1000 * outputPer1k)`.
+ */
+interface ReferenceCredit {
+    /** Id of the report of the call that ran (its report.requestId). */
+    requestId: string;
+    /** Epoch ms when that call's provider counter was read. */
+    at: number;
+    /** Input tokens the provider billed for that call. */
+    inputTokens: number;
+    /** Output tokens the provider billed for that call (the smaller of the first answer and its repair). */
+    outputTokens: number;
+    /** Input tokens credited to this repeat: inputTokens minus the allowance for what the layer inserted (messages, the native schema wrapper, empty tool parameters). */
+    creditedInputTokens: number;
+    /**
+     * Output tokens credited: a share of outputTokens capped by this request's
+     * output limit. 0 unless this request asked for deterministic sampling
+     * (`temperature: 0`), the model has a list price in the catalog, does not
+     * reason and honors that setting, and the call that ran carried no hidden
+     * reasoning (zero reasoning tokens reported, or no reasoning block where the
+     * provider does not break them out).
+     */
+    creditedOutputTokens: number;
+    /** Rate applied to every credited input token, per 1K: the provider's cached-input rate. */
+    cachedInputPer1k: number;
+    /** Rate applied to credited output tokens, per 1K. */
+    outputPer1k: number;
+    /** Fraction of the standard price applied: 1, or the discounted tier the call ran on or this request declared. */
+    tierFactor: number;
+}
 declare class SavingsLedger {
     avoidedLlm: number;
     baselineLlm: number;
@@ -54,6 +123,8 @@ declare class SavingsLedger {
     cacheWriteInputTokens: number;
     /** The premium on those writes, already priced in USD. Adds to `actual` only. */
     cacheWritePremiumUsd: number;
+    /** Provider-initiated cache-write premium, priced in USD. Adds to baseline and `actual` alike. */
+    providerCacheWritePremiumUsd: 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. */
@@ -87,6 +158,13 @@ declare class SavingsLedger {
      * cost; work the layer does to fix its own output has no place in it.
      */
     repairInput: number;
+    /**
+     * Billed provider calls in this request that came back WITHOUT a complete
+     * usage counter (`usage.complete === false`). Any value above zero makes the
+     * request `unmeasured`: a figure built on a missing counter is not the
+     * provider's meter.
+     */
+    callsWithoutUsage: number;
     /**
      * INPUT of the schema-on-demand discovery probe. Held apart exactly like
      * {@link repairInput}, and for the same reason.
@@ -115,11 +193,15 @@ declare class SavingsLedger {
      *
      * The caller raises `actualLlm`, because the call happened and the report owes
      * the reader that count.
+     *
+     * @param providerWritePremium the multiplier the provider bills on its own
+     *   for the call's cache writes (`usage.cacheWriteInputTokens`); 1 = none.
      */
     cascadeAttempt(usage: {
         inputTokens: number;
         outputTokens: number;
-    }, cheapPrice: CostModel): void;
+        cacheWriteInputTokens?: number;
+    }, cheapPrice: CostModel, providerWritePremium?: number): void;
     /** Record the premium for `tokens` of cache write billed at `multiplicador`x. */
     cacheWritePremium(tokens: number, multiplicador: number, precioDelQueMarco: CostModel): void;
     /**
@@ -140,6 +222,14 @@ declare class SavingsLedger {
     compress(originalTokens: number, compressedTokens: number): void;
     /** Ledger 4: tokens still present but billed/processed as provider-cached. */
     providerCached(tokens: number): void;
+    /** Record the premium for `tokens` of cache write the provider bills at `multiplier`x on its own. */
+    providerCacheWritePremium(tokens: number, multiplier: number, price: CostModel): void;
+    /** Set when an avoided call is valued against the provider counter of an identical call that ran. */
+    reference: ReferenceCredit | null;
+    /** Set when an avoided cache or coalesced hit could not be valued by reference: why it stays estimated. */
+    referenceRejected: ReferenceRejection | null;
+    /** Record an avoided call valued by reference. */
+    avoidCallByReference(credit: ReferenceCredit): void;
     /** Record that a whole primary LLM call was avoided (cache / resolver hit). */
     avoidCall(baselineInput: number, baselineOutput: number): void;
     /**
@@ -182,20 +272,28 @@ declare class SavingsLedger {
  * catalogue stays out of the way.
  */
 /** When these prices were last checked against the providers' public rates. */
-declare const PRECIOS_AL_DIA = "2026-09-06";
+declare const PRECIOS_AL_DIA = "2026-09-27";
 /**
  * Key = the model id as the provider publishes it, without a vendor prefix.
  * Lookup tries the exact id, then the id without its provider prefix, then the
  * LONGEST matching prefix — so `gpt-4o-2024-08-06` inherits `gpt-4o` without
  * having to enumerate every dated snapshot.
+ *
+ * These are the rows in force on {@link PRECIOS_AL_DIA}. A price change a
+ * provider has already announced is applied by {@link precioDeLista} from its
+ * effective date, so a request is always priced at the rate of its own day.
  */
 declare const CATALOGO: Readonly<Record<string, CostModel>>;
 /**
- * The list price for a model, or `undefined` when it is not in the catalogue.
+ * The list price for a model on the day of the request, or `undefined` when
+ * the catalogue has no price for it in force that day.
  *
  * @param model the id as the caller passes it, with or without a vendor prefix.
+ * @param at when the request was made (epoch ms or a `Date`); defaults to now.
+ *   Prices resolve per UTC day, so a price change the provider has announced
+ *   applies from its effective date.
  */
-declare function precioDeLista(model: string): CostModel | undefined;
+declare function precioDeLista(model: string, at?: Date | number): CostModel | undefined;
 
 /**
  * The version the SDK reports for itself.
@@ -205,7 +303,7 @@ declare function precioDeLista(model: string): CostModel | undefined;
  * on the customer's machine. `test/version-declarada.test.ts` ties this
  * constant to package.json so the two can never drift.
  */
-declare const BV_SALA_VERSION = "0.4.22";
+declare const BV_SALA_VERSION = "0.4.25";
 
 /**
  * Environment-agnostic UUID generation.
@@ -217,6 +315,110 @@ declare const BV_SALA_VERSION = "0.4.22";
  */
 declare function randomId(): string;
 
+/** How the layer served a request that is eligible for a verification check. */
+type VerificationStratum = 
+/** Answered without calling the provider (cache, resolver, identical request in flight). */
+"avoided_call"
+/** Answered by a cheaper model than the one requested. */
+ | "cheaper_model"
+/** Sent with parts removed. */
+ | "tokens_removed"
+/** Sent re-encoded with fewer tokens. */
+ | "tokens_compressed"
+/** Sent without removing or re-encoding anything. */
+ | "unchanged";
+/** Why a request is never checked. */
+type VerificationExclusion = "fail_open" | "truncated" | "incomplete" | "contract_failed" | "unmeasured" | "no_price" | "over_cap" | "opted_out" | "retrieval";
+/** How a check ended. */
+type VerificationOutcome = "paired" | "check_failed" | "check_unmeasured" | "abandoned" | "dropped";
+/**
+ * Opt-in A/B verification on your own traffic. Off unless `sampleRate` is above 0.
+ *
+ * For the sampled share of eligible requests, after the answer has been returned,
+ * the layer sends the same request once more to your provider exactly as it would
+ * go without the layer (the requested model, all your tools, your data inline, no
+ * cache marks) and discards that second answer. Each pair (what the unoptimized
+ * copy cost and what the optimized request cost, both from your provider's usage
+ * counters) is reported to your dashboard and to `onCheck`.
+ *
+ * Every copy is a real provider call that you pay for: roughly `sampleRate` times
+ * what the eligible traffic would cost without the layer. Pairs are informational:
+ * they never enter measured savings, your statement or any commission.
+ */
+interface VerificationSettings {
+    /** Share of eligible requests to check, from 0 to 1. Any other value turns verification off. */
+    sampleRate: number;
+    /** Skip requests whose estimated unoptimized cost, in USD, is above this. An invalid value turns verification off. */
+    maxCheckCostUsd?: number;
+    /** Called once per sampled eligible request, when its check is settled. Errors thrown here are ignored. */
+    onCheck?: (check: VerificationCheck) => void;
+    /**
+     * Keeps a serverless runtime alive until a check is settled and reported, for
+     * example your platform's `waitUntil`. Receives one promise per copy actually
+     * sent (a check recorded as `dropped` is never sent and passes none); it never rejects.
+     */
+    waitUntil?: (promise: Promise<void>) => void;
+}
+/** Token counts and cost of one side of a pair, from the provider's usage counters. */
+interface VerificationSide {
+    cost: number;
+    inputTokens: number;
+    cachedInputTokens: number;
+    outputTokens: number;
+}
+/** One settled verification check. */
+interface VerificationCheck {
+    /** Id of the served request (its report.requestId). */
+    requestId: string;
+    /** Epoch ms when the served request was decided. */
+    at: number;
+    stratum: VerificationStratum;
+    /**
+     * - `paired`: both sides metered; `naive` is present.
+     * - `check_failed`: the provider returned an error for the copy, or it timed out.
+     * - `check_unmeasured`: the provider returned no usage counter for the copy.
+     * - `abandoned`: the copy was still running when `close()` was called.
+     * - `dropped`: not sent, because too many checks were already running.
+     */
+    outcome: VerificationOutcome;
+    requestedModel: string;
+    servedModel: string;
+    cacheResult: CacheOutcome;
+    /** The served request, as its report measured it. Zero on an avoided call. */
+    optimized: VerificationSide;
+    /**
+     * The unoptimized copy. Present only when `outcome` is `paired`. The dashboard
+     * compares a pair only when the copy finished the way a served request must to
+     * be checked: `finishReason` `stop`, `tool_calls` or absent, and a contract that
+     * was not `missed`. Other pairs are counted and exported, but left out of every figure.
+     */
+    naive?: VerificationSide & {
+        finishReason?: string;
+        /** Whether the copy met your output contract: `none` without a contract or on a tool-call turn. */
+        contract: "met" | "missed" | "none";
+    };
+    /** Rates used to price the copy, in USD per 1K tokens. */
+    prices: {
+        inputPer1k: number;
+        cachedInputPer1k?: number;
+        outputPer1k: number;
+    };
+}
+/**
+ * Whether this request was drawn for verification sampling, and how it counts.
+ * Present only when `verification` is enabled on the layer and its pairs have
+ * somewhere to go (your dashboard or `onCheck`). Absent after `close()`, and on
+ * the rare internal error of the sampler, which never affects the request itself.
+ */
+interface VerificationReport {
+    /** Drawn for a check. A copy is sent only when the request is also eligible. */
+    sampled: boolean;
+    /** How the layer served this request, when it is eligible for a check. */
+    stratum?: VerificationStratum;
+    /** Why this request is never checked. Present exactly when `stratum` is absent. */
+    excluded?: VerificationExclusion;
+}
+
 /**
  * Core contracts for BV-SALA (bivelio-savings-layer).
  *
@@ -317,7 +519,28 @@ interface RetrievalOptions {
 }
 interface SavingsToggles {
     exactCache?: boolean;
-    semanticCache?: boolean | "safe-only";
+    /**
+     * OPT-IN. Reuse the answer to an earlier, reworded version of this request.
+     * Needs a semantic cache on the layer (`createSavingsLayer({ semanticCache })`)
+     * and a license that includes it.
+     *
+     * - `true` and `"safe-only"` are the same setting: single-shot requests only.
+     * - `"include-agentic"` also admits agentic requests: those that declare tools
+     *   (read-only ones included), carry tool calls or tool results, or hold more
+     *   than one user turn.
+     *
+     * WHY AGENTIC TRAFFIC IS LEFT OUT BY DEFAULT. Two runs of an agent loop can
+     * differ only in what a tool returned. The deterministic guard under the
+     * similarity score compares figures and dates, negation and word overlap; it
+     * cannot tell that a tool said something else in words. Measure it on your own
+     * traffic before you include it.
+     *
+     * Whatever you set, requests with write or destructive tools, freshness-sensitive
+     * requests (including any freshness bucket other than `any`), personalized
+     * requests and stochastic sampling never use this cache. A hit is reported as
+     * `cache.result: "semantic"` and `qualityStatus: "task_equivalent"`.
+     */
+    semanticCache?: boolean | "safe-only" | "include-agentic";
     compression?: boolean | "auto";
     /**
      * OPT-IN. Elide old, large tool_results from a multi-turn context before the
@@ -469,6 +692,21 @@ interface SavingsToggles {
      * tier the request is sent unchanged and the report says so.
      */
     deferrable?: boolean;
+    /**
+     * Declare this request STANDALONE: nothing after its stable prefix will be sent again as
+     * the start of a later request (it is not a conversation turn you will continue).
+     * Defaults to false. Only acts on OpenAI models that bill prompt-cache writes above the
+     * input rate, on OpenAI's own API: the provider may then write its cache only at the
+     * stable prefix, or nowhere, instead of at the end of your message. Trade-off: repeats
+     * and continuations of this exact prompt lose the cache reads the provider default would
+     * give them. See report.cacheWrites. Never changes the answer.
+     */
+    standalone?: boolean;
+    /**
+     * Set to `false` to keep this request out of verification sampling: it is
+     * counted as excluded and never sent twice. No effect when verification is off.
+     */
+    verification?: boolean;
 }
 /**
  * What asking for a cheaper processing tier actually got you on this request.
@@ -503,32 +741,33 @@ interface DeferredExecutionReport {
      */
     credited: boolean;
     /**
-     * Fraction of the standard list price the served tier bills — `0.5` for a tier
-     * documented at half price. Present only when {@link credited}.
+     * The effective fraction of the standard rate card this call was billed at:
+     * `tierSaving.appliedCost / tierSaving.standardCost` on the one call whose tier
+     * was read. `0.5` when every component of the call bills at half price; higher
+     * when some component (typically cached input) is discounted less or not at
+     * all. Present only when {@link credited}.
      */
     discountRate?: number;
+    /** @deprecated Use `tierSaving.amount`; same value. Kept for compatibility. */
+    estimatedTierSaving?: number;
     /**
-     * What the tier was worth on this request, in your currency unit.
-     *
-     * A COUNTERFACTUAL priced from the standard rate card: this request was not
-     * also run at standard price, so it is `(1 - discountRate)` applied to the
-     * standard-rate cost of THE ONE CALL whose {@link servedTier} was read.
-     *
-     * ⚠️ IT IS NOT `cost.actual * (1 - discountRate)`, and the difference is not
-     * rounding. `cost.actual` is the whole request: it can also carry a repair
-     * retry, a tool-discovery probe, or a model-cascade attempt that was tried and
-     * thrown away. No tier was read back for any of those, so none of them is
-     * credited here even though they very likely got the discount too. Compute the
-     * product yourself and you will get a LARGER number than this field — this
-     * field is the part that was actually observed.
+     * What the served tier was worth on the one call whose tier was read: that call's
+     * provider-reported usage at the standard rate card minus the same usage at the rate
+     * card of the tier that served it, component by component. Present only when credited.
      *
-     * ⚠️ `cost.actual` prices this request at the STANDARD rate card, so when this
-     * field is present your invoice line will be LOWER than `cost.actual` by at
-     * least this amount. The bias is deliberate and it is the safe one: the layer
-     * under-reports the saving rather than promising one it cannot prove. The
-     * reason it is not folded in is {@link creditedLedger}.
+     * It is NOT `cost.actual` times a discount. `cost.actual` is the whole request and
+     * can also carry a repair retry, a tool-discovery probe or a model-cascade attempt;
+     * no tier was read back for those, so none of them is credited here. And
+     * `cost.actual` prices the request at the STANDARD rate card, so when this is
+     * present your invoice line is lower than `cost.actual` by at least this amount.
      */
-    estimatedTierSaving?: number;
+    tierSaving?: PriceLeverSaving;
+    /**
+     * True when the cheaper tier had no capacity and the request was repeated once at
+     * the standard tier (layer setting `priceLevers.onCapacityError: "standard"`).
+     * Nothing is credited then, and the refused attempt is not counted as a call.
+     */
+    capacityFallback?: boolean;
     /**
      * Which of the four ledgers this credits: none, and that is the honest answer.
      * Deferring avoids no call (ledger 1), removes no tokens (2), re-encodes
@@ -551,6 +790,44 @@ interface DeferredExecutionReport {
     /** Why it did what it did, in one sentence. Never empty. */
     reason: string;
 }
+/**
+ * What a provider price lever was worth on one call, in your currency unit.
+ *
+ * It never enters `cost.*` and is never billed: it is reported next to the four
+ * ledgers, with its own basis.
+ */
+interface PriceLeverSaving {
+    /** In your currency unit. Never more than the difference between the two published rate cards on this usage. */
+    amount: number;
+    /**
+     * "measured": the provider's own counter for this call at two published rate cards,
+     * the tier read back from the provider's official API, and the counter reporting how
+     * much of the input was read from (or, where billed apart, written to) the prompt
+     * cache. "estimated": anything short of that; `basisReason` says what.
+     */
+    basis: Extract<CostBasis, "measured" | "estimated">;
+    /** This call's provider-reported usage at the standard rate card. */
+    standardCost: number;
+    /** The same usage at the rate card that applied. */
+    appliedCost: number;
+    /** YYYY-MM-DD: when these rate cards were last checked against the provider's published prices. */
+    pricesCheckedOn: string;
+    /** One sentence. Never empty. */
+    basisReason: string;
+}
+/** Present whenever `savings.standalone` is true, including when it did nothing. */
+interface CacheWriteReport {
+    mode: "explicit" | "provider-default";
+    /**
+     * Cache breakpoints the layer placed: 0 or 1. With 0 in explicit mode the provider
+     * neither reads nor writes its prefix cache.
+     */
+    breakpoints: number;
+    /** Always basis "estimated": the provider default was not run for this request. */
+    avoidedWritePremium?: PriceLeverSaving;
+    /** Why, in one sentence, including what it costs you. Never empty. */
+    reason: string;
+}
 /**
  * How much authority the model cascade has over your requests.
  *
@@ -740,6 +1017,79 @@ interface SavingsResult<T = unknown> {
     finishReason?: string;
     report: SavingsReport;
 }
+/** One event of a streamed answer. */
+type SavingsStreamEvent<T = unknown> = 
+/** A piece of the answer text, as the provider wrote it. Never empty. */
+{
+    type: "text";
+    delta: string;
+}
+/** One complete tool call the model requested, in the order of `result.toolCalls`. */
+ | {
+    type: "tool_call";
+    call: ToolCallRequest;
+}
+/** Always the last event, exactly once. `result` is the same object `SavingsStream.result` resolves to. */
+ | {
+    type: "done";
+    result: SavingsResult<T>;
+};
+/** Options for `generateStream`. */
+interface SavingsStreamOptions {
+    /** Aborting it has the same effect as calling `abort()` on the stream. */
+    signal?: AbortSignal;
+}
+/**
+ * The handle returned by `generateStream`. Iterate it (once) for the events, or
+ * await `result` for the final SavingsResult; both work on their own, because
+ * the request starts as soon as the handle is created.
+ *
+ * Invariants: the concatenation of every `text` delta equals `result.text`; the
+ * `tool_call` events, in order, equal `result.toolCalls`; `done` is the last
+ * event and `result` is already resolved when it arrives.
+ */
+interface SavingsStream<T = unknown> extends AsyncIterable<SavingsStreamEvent<T>> {
+    /**
+     * Resolves with the final SavingsResult (the same object the `done` event
+     * carries). Rejects with the provider or license error that ended the stream,
+     * or with StreamAbortedError when the stream was aborted before the provider
+     * finished its answer.
+     */
+    readonly result: Promise<SavingsResult<T>>;
+    /**
+     * Stops the stream. Iteration ends at once, without an error. While the
+     * provider is still writing a live answer, its request is cancelled: `result`
+     * rejects with StreamAbortedError, nothing is cached and nothing is reported.
+     * Once the provider's answer is complete, or when it is produced in one piece
+     * (output contract, deferrable request), nothing is cancelled: `result`
+     * resolves with the full report and it is recorded like any other request.
+     * Breaking out of a for-await loop calls abort(). No-op after `done`.
+     */
+    abort(reason?: unknown): void;
+}
+/** How a streamed request reached the caller. Present only on results of `generateStream`. */
+interface StreamingReport {
+    /**
+     * "live": the text was handed over as the provider produced it.
+     * "whole": the complete answer arrived as one `text` event.
+     */
+    delivery: "live" | "whole";
+    /**
+     * Why the answer arrived whole. Absent when `delivery` is "live".
+     * - "output-contract": the request carried `response.schema`; it was validated first.
+     * - "deferrable": the request was declared `deferrable`.
+     * - "provider-without-streaming": the provider has no `generateStream`.
+     * - "shortcut": answered without a provider call (cache, deterministic resolver, or an identical request in flight).
+     * - "fail-open": an internal error sent the request down the direct fallback path.
+     */
+    wholeReason?: "output-contract" | "deferrable" | "provider-without-streaming" | "shortcut" | "fail-open";
+    /**
+     * Milliseconds from the `generateStream` call to the first `text` or
+     * `tool_call` event handed to the caller. Present only when `delivery` is
+     * "live" and such an event exists.
+     */
+    firstEventMs?: number;
+}
 type CacheOutcome = "miss" | "exact" | "semantic" | "singleflight" | "deterministic";
 /**
  * The quality claims this layer is able to DEMONSTRATE for the answer it served.
@@ -785,6 +1135,155 @@ type CacheOutcome = "miss" | "exact" | "semantic" | "singleflight" | "determinis
  */
 declare const QUALITY_STATUSES: readonly ["exact", "task_equivalent", "not_verified", "bounded_degradation", "rejected"];
 type QualityStatus = (typeof QUALITY_STATUSES)[number];
+/** Where the answer you received came from on this request. */
+type AnswerSource = 
+/** Your provider generated it for this request. */
+"provider"
+/** A replay of the answer already produced for this very request. */
+ | "exact_cache"
+/** A reuse of the answer to a reworded version of this request. */
+ | "semantic_cache"
+/** Shared with an identical request that was running at the same time. */
+ | "coalesced"
+/** Computed locally; no model was involved. */
+ | "deterministic"
+/** A direct provider call after an internal error; nothing was optimized. */
+ | "fail_open";
+/** The output-contract check on the answer that was served. */
+interface QualitySchemaCheck {
+    /**
+     * `passed` or `failed`: the served answer was validated against
+     * `response.schema`. `not_applicable`: the model asked to run tools, so there
+     * is no final answer yet.
+     */
+    outcome: "passed" | "failed" | "not_applicable";
+    /**
+     * Whether the layer relied on a decode-time constraint for this answer (the
+     * backend named in `constraints.backend`). The answer is validated either way.
+     * Always false on cache and resolver answers. A coalesced answer carries the
+     * value of the request it joined, which is the one that generated it.
+     */
+    decodeTimeConstraint: boolean;
+    /** Validation errors in the served answer. 0 when it passed. */
+    errorCount: number;
+    /**
+     * The model wrapped valid JSON in prose or a code fence, and it was extracted
+     * locally instead of paying for a repair call.
+     */
+    unwrapped?: true;
+}
+/** What happened when the first answer failed its output contract. */
+interface QualityRepairCheck {
+    /**
+     * `repaired`: one repair call was made and its answer passed. `still_invalid`:
+     * one repair call was made and its answer failed too. `skipped`: no repair
+     * call was made; `skipReason` says why.
+     */
+    outcome: "repaired" | "still_invalid" | "skipped";
+    /**
+     * - `output_truncated`: the answer hit the output limit, and the same limit
+     *   would cut the repair off again.
+     * - `schema_defect`: no answer can satisfy the schema (for example, a pattern
+     *   that is not a valid regular expression).
+     * - `would_cost_more_than_no_layer`: repairing would have cost more than
+     *   sending the request without the layer (opt-in, `skipRepairAboveBaseline`).
+     * - `decode_time_constraint`: generation was already constrained, so a retry
+     *   would not change the outcome.
+     */
+    skipReason?: "output_truncated" | "schema_defect" | "would_cost_more_than_no_layer" | "decode_time_constraint";
+}
+/** Whether the provider stopped because it reached the output limit. */
+interface QualityTruncationCheck {
+    /** True when the provider reported `finishReason: "length"`. A truncated answer is never cached. */
+    truncated: boolean;
+    /** The stop reason exactly as the provider named it; absent when it reported none. */
+    finishReason?: string;
+    /**
+     * Whether you set the limit (`response.maxOutputTokens`). When false, any
+     * limit that applied was a provider or adapter default.
+     */
+    capSetByCaller: boolean;
+    /** The limit you set, in output tokens. Present only when `capSetByCaller`. */
+    outputLimit?: number;
+}
+/** How a cache hit matched this request. */
+type QualityCacheMatch = {
+    kind: "exact";
+    /** Age of the replayed answer, in milliseconds. */
+    ageMs?: number;
+} | {
+    kind: "semantic";
+    /** Age of the reused answer, in milliseconds. */
+    ageMs?: number;
+    /**
+     * Similarity between this request and the stored one. It is not evidence
+     * of equivalence: see {@link QualityStatus}.
+     */
+    similarity: number;
+    /** The similarity a candidate had to reach to be considered at all. */
+    similarityFloor: number;
+    /**
+     * The confidence the hit had to reach to be served. Confidence is the
+     * lower of `similarity` and `verifierScore` (`cache.confidence`).
+     */
+    acceptFloor: number;
+    /** Your verifier's score, present only when you configured one. */
+    verifierScore?: number;
+    /** `built_in`: the lexical embedder shipped with the SDK. `custom`: yours. */
+    embedder: "built_in" | "custom";
+    /**
+     * The deterministic guard passed, turn by turn: figures and dates,
+     * negation parity and content-word overlap. A hit is never served without it.
+     */
+    factGuard: "passed";
+};
+/** What the model cascade decided on this request. See {@link ModelCascadeReport}. */
+interface QualityCascadeCheck {
+    mode: "shadow" | "on";
+    /** What the deterministic gate was able to check (`modelCascade.verifier`). */
+    gate: "none" | "structural" | "value-constrained";
+    /**
+     * - `accepted`: a cheaper model answered and its answer cleared the gate.
+     * - `escalated`: the gate rejected the cheaper answer and the model you asked for answered.
+     * - `not_routed`: the cascade is on but this request was not routed (see `modelCascade.reason`).
+     * - `not_applied`: shadow mode. The cascade only evaluated this request and
+     *   the model you asked for answered. On a sampled request
+     *   (`modelCascade.sampled`) the cheaper model also ran, and its answer was
+     *   not served.
+     */
+    outcome: "accepted" | "escalated" | "not_routed" | "not_applied";
+    /**
+     * Shadow sampling only: both answers satisfied the contract and disagreed on
+     * a hard value. A hint, never proof.
+     */
+    sampleDiverged?: boolean;
+}
+/**
+ * What the layer checked on the answer it served, and what came of it.
+ *
+ * It holds no money and no token counts. It is never added to the four savings
+ * ledgers or to `cost`, and it never leaves your process: usage reporting does
+ * not carry it. `qualityStatus` is the one-word verdict; this is the evidence
+ * behind it. A block is present only when its check applies to this request.
+ * With `source: "coalesced"`, the blocks describe the shared answer as the
+ * request it joined produced it: nothing was run again. An absent ledger means
+ * unknown (an older SDK, or a report built elsewhere).
+ */
+interface QualityLedger {
+    source: AnswerSource;
+    /** Only with `source: "coalesced"`: where the shared answer came from for the request it joined. */
+    sharedFrom?: Exclude<AnswerSource, "coalesced">;
+    /** Present when the request carried `response.schema`. */
+    schema?: QualitySchemaCheck;
+    /** Present when a provider answer on this request failed its first validation. */
+    repair?: QualityRepairCheck;
+    /** Present when a provider generated the served answer. */
+    truncation?: QualityTruncationCheck;
+    /** Present when the answer came from the exact or the semantic cache. */
+    cacheMatch?: QualityCacheMatch;
+    /** Present when `savings.modelCascade` is not `"off"`. */
+    cascade?: QualityCascadeCheck;
+}
 interface SavingsReport {
     requestId: string;
     /**
@@ -837,6 +1336,10 @@ interface SavingsReport {
         result: CacheOutcome;
         confidence?: number;
         ageMs?: number;
+        /** Present when this avoided call is valued by reference; see ReferenceCredit. */
+        reference?: ReferenceCredit;
+        /** Present on an exact-cache or coalesced hit that stays estimated: why no reference applied. Semantic-cache hits never carry it. */
+        referenceRejected?: ReferenceRejection;
     };
     routing: {
         executionClass: ExecutionClass;
@@ -880,6 +1383,12 @@ interface SavingsReport {
      * the `exact` label.
      */
     qualityStatus?: QualityStatus;
+    /**
+     * The evidence behind `qualityStatus`: where the answer came from and which
+     * checks it went through, with no money in it. See {@link QualityLedger}.
+     * Optional and additive: absent means unknown.
+     */
+    qualityLedger?: QualityLedger;
     /**
      * What the model cascade did, or would have done. Present whenever
      * `savings.modelCascade` is not `"off"`. Read its docstring before turning the
@@ -891,6 +1400,18 @@ interface SavingsReport {
      * `savings.deferrable` is `true`, including when it got you nothing.
      */
     deferred?: DeferredExecutionReport;
+    /**
+     * Where the provider was allowed to write its prompt cache. Present whenever
+     * `savings.standalone` is `true`, including when it changed nothing.
+     */
+    cacheWrites?: CacheWriteReport;
+    /** How a streamed request was delivered. Present only on results of `generateStream`. */
+    streaming?: StreamingReport;
+    /**
+     * Whether this request was drawn for verification sampling, and how it counts.
+     * Present only when `verification` is enabled on the layer.
+     */
+    verification?: VerificationReport;
     quality: {
         taskPassed?: boolean;
         /**
@@ -914,6 +1435,22 @@ interface SavingsReport {
          *
          * - `measured`   — reconstructed from THIS request's provider counter. Real
          *                  money, checkable against the provider invoice.
+         * - `reference`  — MEASURED BY REFERENCE: the call was avoided (a repeat
+         *                  served without calling the provider) and a byte-identical
+         *                  request had already run through the layer untouched. The
+         *                  baseline is the provider's own counter for that request,
+         *                  valued at the provider's cached-input rate. Output is
+         *                  credited only under deterministic sampling, on a model
+         *                  with a list price in the catalog that does not reason and
+         *                  honors that setting, when the call that ran carried no
+         *                  hidden reasoning (zero reasoning tokens reported, or no
+         *                  reasoning block where the provider does not break them
+         *                  out), and then at 95% of its counter. With an output
+         *                  schema, only when the schema traveled exactly as sent, in
+         *                  strict mode, in the provider's native response-format
+         *                  parameter. Valued low on purpose.
+         *                  Enters the commission base; `cache.reference` carries the
+         *                  arithmetic and the id of the request that ran.
          * - `estimated`  — the call was AVOIDED, so there never was a provider
          *                  counter and the baseline comes from the local estimator.
          *                  The best figure available, but not measured.
@@ -1115,64 +1652,50 @@ declare class TokenizerRegistry {
 declare const defaultTokenizerRegistry: TokenizerRegistry;
 
 /**
- * Tokenizador EXACTO — la regla del proveedor, no una aproximación.
+ * Exact cache.
  *
- * 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
- * An estimator that is not calibrated for the destination model can miss by
- * enough to publish a baseline several times the real one, which would credit a
- * saving that never existed. That is why `basis` degrades instead of claiming.
+ * 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.
  */
-
-/** Lo que necesitamos de gpt-tokenizer. Tipado aquí para no depender de sus tipos. */
-interface BpeEncoder {
-    encode(text: string): number[] | {
-        length: number;
-    };
+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.reference` carries the provider counter of the call that produced this
+     * answer, when that call ran untouched; readers that do not know it ignore it.
+     */
+    meta?: Record<string, unknown>;
 }
-/**
- * Estimador exacto sobre una codificación BPE ya cargada.
- *
- * Se construye con el encoder 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 encoder;
-    readonly id: string;
-    readonly exact = true;
-    constructor(id: string, encoder: BpeEncoder);
-    count(text: string): number;
+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>;
 }
-/** Modelos que usan cada codificación. Sirve para mapear el registro de una vez. */
-declare const MODELS_BY_ENCODING: 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 registerExactTokenizer(registro: {
-    register(e: TokenEstimator): unknown;
-    mapModel(model: string, tokenizerId: string): unknown;
-}, opciones?: {
-    codificaciones?: readonly string[];
-}): Promise<boolean>;
 /**
- * @deprecated Spanish-named aliases kept for one minor version. Use
- * {@link MODELS_BY_ENCODING} and {@link registerExactTokenizer}. The public
- * surface of this package is English-only; these leaked and are on the way out.
+ * 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 const MODELOS_POR_CODIFICACION: Readonly<Record<string, readonly string[]>>;
-/** @deprecated Use {@link registerExactTokenizer}. */
-declare const registrarTokenizadorExacto: typeof registerExactTokenizer;
+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;
+}
 
 /**
  * Canonicalization turns a raw request into a normalized, hashable form. This
@@ -1239,188 +1762,14 @@ declare function modelFamilyOf(model: string): 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.
- *
- * `servedModel` CARRIES THE MODEL THAT WILL ACTUALLY ANSWER, not the one the
- * caller named, and that distinction is what stops the model cascade from
- * poisoning the cache. Routing to a cheap model and storing its answer under the
- * STRONG model's key would hand that answer to the next request — one with the
- * cascade off, or from another process entirely — while the report claims the
- * requested model served it. That is a silent model swap, deferred, which is the
- * worst kind of silent model swap.
+ * Semantic cache (safe-by-construction).
  *
- * `modelFamily` is derived from whichever id is used, for the same reason: it is
- * part of the identity of whoever answers.
- */
-declare function buildExactKey(c: CanonicalRequest, opciones?: {
-    servedModel?: string;
-}): 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.
- *
- * `schema` is REQUIRED here, even though `contract` is already part of the key:
- * two concurrent calls that differ only in `schemaVersion` are different
- * requests and must never coalesce. All three doors — exact key, in-flight key
- * and semantic filter — key on the same identity, by design.
- *
- * `servedModel` CARRIES THE MODEL THAT WILL ACTUALLY ANSWER, for the same reason
- * {@link buildExactKey} does, and this door is the one that leaks FIRST. The
- * exact key protects the answer AFTER it is stored; this one protects it while
- * it is still being written, and a follower does not re-run anything — it is
- * handed the leader's text verbatim.
- *
- * The leak it closes, measured: two concurrent requests for the same text, one
- * with `savings.modelCascade: "on"` and one with the cascade OFF, coalesced onto
- * one execution. The routed leader called the cheap model, and the caller who
- * never opted in — whose own decision was "do not route" — was served the cheap
- * model's answer. Same shape inside a single uniformly-configured deployment:
- * the automatic shut-off can latch between two concurrent requests, so one is
- * routed and the other is not, and coalescing hands one of them the other's
- * model. Whoever the layer decided must go to the strong model has to actually
- * go there.
- *
- * `deferrable` CLOSES THE SAME HOLE ON THE LATENCY AXIS, which is why it belongs
- * here and NOT in {@link buildExactKey}. The two doors do not risk the same
- * thing: the exact key hands out an answer that is ALREADY WRITTEN, where the
- * processing tier only picked a queue and changes neither the text nor the wait
- * of whoever receives it. This one binds a follower to a call that HAS NOT COME
- * BACK YET, so it imposes the leader's wait on them.
- *
- * A caller who never set `savings.deferrable` must not be made to wait for one
- * who did.
- */
-declare function buildInflightKey(c: CanonicalRequest, opciones?: {
-    servedModel?: string;
-    deferrable?: boolean;
-    toolDiscovery?: boolean;
-    maxOutputTokens?: number;
-}): 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;
-    /**
-     * May the SDK elide old, large tool_results before resending? Computed, not
-     * hardcoded like `allowCompression`: eliding drops whole tool outputs, so it
-     * honors the same vetoes as the semantic cache — write tools, freshness,
-     * personalization, stochastic sampling and `day`.
-     */
-    allowElision: 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;
-    /**
-     * Techo de antigüedad para una entrada de caché exacta, derivado del
-     * `freshnessBucket`. `null` = sin techo propio (manda el TTL por defecto).
-     * Existe porque el bucket NO particiona la clave —va crudo al hash y no rota—,
-     * así que sin esto "hour" y "day" no significaban nada operativamente.
-     */
-    maxCacheAgeMs: number | null;
-    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.
+ * 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[];
@@ -1452,10 +1801,14 @@ interface SemanticRecord {
     /**
      * The COMPLETE identity of the request that produced this answer.
      *
-     * Every field here is a hard filter, checked before similarity is scored, and
-     * the set is identical to the one the exact cache keys on. Two questions
-     * worded alike but carrying different attached data, a different model or a
-     * different system prompt are different questions, and never match.
+     * Every field here is a hard filter, checked before similarity is scored.
+     * Together with the isolation fields above they are the identity the exact
+     * cache keys on, except for the text itself, which is what similarity
+     * compares. Freshness is covered by construction: the semantic cache only
+     * runs on requests whose freshness bucket is `any`, the default. Two questions worded
+     * alike but carrying different attached data, a different model, a different
+     * system prompt, a different tool catalog or different sampling controls are
+     * different questions, and never match.
      */
     model: string;
     systemPromptHash: string;
@@ -1463,14 +1816,30 @@ interface SemanticRecord {
     locale: string;
     schemaVersion: string;
     safetyPolicyVersion: string;
+    /** Hash of the declared tool catalog (ids, risk and parameters). */
+    toolsetHash: string;
+    /** Sampling temperature of the request, or null when it set none. */
+    temperature: number | null;
+    /** Sampling seed of the request, or null when it set none. */
+    seed: number | null;
     storedAtMs: number;
 }
 interface SemanticHit {
     record: SemanticRecord;
     similarity: number;
+    /** Your verifier's score, or the similarity itself when no verifier is configured (see `verifierRan`). */
     verifierScore: number;
+    /** The lower of `similarity` and `verifierScore`; a hit is served only at or above `acceptFloor`. */
     confidence: number;
     ageMs: number;
+    /** Similarity a candidate had to reach to be considered at all. */
+    similarityFloor: number;
+    /** Confidence a candidate had to reach to be served. */
+    acceptFloor: number;
+    /** `built_in`: the lexical embedder shipped with the SDK. `custom`: the one you passed as `embed`. */
+    embedder: "built_in" | "custom";
+    /** Whether a verifier scored this hit. When false, `verifierScore` equals `similarity`. */
+    verifierRan: boolean;
 }
 interface SemanticCacheOptions {
     /**
@@ -1519,6 +1888,7 @@ declare class InMemorySemanticCache {
     private readonly ttlMs;
     private readonly maxRecords;
     private readonly now;
+    private readonly embebedorPropio;
     constructor(opts?: SemanticCacheOptions);
     /**
      * Find a safe hit for a canonical request, or null. Metadata filters run
@@ -1533,61 +1903,34 @@ declare class InMemorySemanticCache {
 }
 
 /**
- * A LOCAL EMBEDDING FUNCTION — no network, no API key, no per-call cost.
- *
- * The semantic cache needs a way to compare meaning. Wiring it to a hosted
- * embedding endpoint is the obvious answer and a bad default: it makes every
- * miss cost a network round-trip and money, and it forces a provider choice onto
- * a customer who never asked for one. So the cache shipped with no embedder at
- * all, which means it never matched anything.
- *
- * This is the third option: a deterministic bag-of-features vector computed in
- * microseconds from the text itself. It captures LEXICAL closeness — the same
- * question asked with different filler words — which is the overwhelming majority
- * of real repeat traffic. It does NOT capture deep semantics: "what is a CDN"
- * and "explain content delivery networks" share no tokens and will not match.
- *
- * WHY THAT IS SAFE, AND THIS IS THE PART THAT MATTERS. A semantic cache's one
- * unforgivable failure is confidently answering a NEARBY BUT DIFFERENT question.
- * This vector never gets the chance: the cache runs a deterministic precision
- * guard beneath the embedding — matching numbers and dates, negation parity and a
- * content-overlap floor — and every isolation field (tenant, principal, model,
- * schema, attached data) is a hard filter applied before similarity is scored.
- * A weak embedding can only cause a MISS, which costs one real call. It cannot
- * produce a wrong answer.
- *
- * Pass your own `embed` to {@link InMemorySemanticCache} to get true semantics.
- * This one exists so that the feature is worth something with zero setup.
- */
-/**
- * The vector for a piece of text.
- *
- * Features are unigrams plus adjacent bigrams: bigrams are what keep word ORDER
- * from being free. Without them "does A cause B" and "does B cause A" are the
- * same point in space.
- *
- * Term weight is sublinear (`1 + log tf`) so a word repeated forty times does not
- * dominate the direction of the vector, and the result is L2-normalised so cosine
- * similarity is a plain dot product.
- */
-declare function vectorLocal(texto: string): number[];
-/**
- * The default embedding function for {@link InMemorySemanticCache}.
- *
- * Synchronous by design — it returns the array, not a promise — so a cache lookup
- * adds no await and no latency to the request path.
- */
-declare function embebedorLocal(texto: string): number[];
-/**
- * The similarity floor this embedder is calibrated for.
+ * Singleflight (in-flight coalescing).
  *
- * A lexical vector sits lower than a sentence-transformer on genuine paraphrases,
- * so the 0.9 default that suits a hosted embedder would reject almost everything
- * here. This value was measured on paraphrase pairs against near-miss pairs, not
- * guessed — see `test/embebedor-local.test.ts`, which fails if the two
- * populations stop being separable.
+ * 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 const UMBRAL_LOCAL = 0.72;
+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;
+    }>;
+    /**
+     * The in-flight execution under `key`, if one is running, joined as a
+     * follower; `undefined` when nothing is in flight. Never starts one.
+     */
+    join<T>(key: string): Promise<T> | undefined;
+    get activeKeys(): number;
+}
 
 /**
  * Deterministic resolvers.
@@ -1759,106 +2102,9 @@ declare class ToolSelector {
 }
 
 /**
- * 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.
+ * 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;
@@ -1881,68 +2127,6 @@ interface Serializer {
     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
- * The compact encoder is only ever a challenger.
- */
-declare const jsonCompactSerializer: Serializer;
-
-/**
- * Compact row encoder.
- *
- * Its 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 it 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<->rows
- * round-trip is deterministic and testable.
- */
-interface CompactRowsOptions {
-    /** Field delimiter within tabular/inline rows. */
-    delimiter?: "," | "\t";
-    /** Indentation unit. */
-    indent?: string;
-}
-declare function encodeCompactRows(value: unknown, options?: CompactRowsOptions): 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 the compact encoder. Kept short on purpose — this text
- * is the per-request overhead the selector must amortize before it wins.
- */
-declare const COMPACT_ROWS_INSTRUCTION: string;
-declare function createCompactRowsSerializer(options?: CompactRowsOptions): Serializer;
-declare const compactRowsSerializer: Serializer;
-
-/**
- * Decoder for the subset emitted by {@link encodeCompactRows}.
- *
- * 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 it for, and makes the
- * JSON<->rows round-trip deterministic and testable. List-form arrays of nested
- * objects are intentionally out of scope for decoding (the selector never picks
- * it for those, since JSON wins there anyway).
- */
-interface CompactRowsDecodeOptions {
-    delimiter?: "," | "\t";
-    indent?: string;
-}
-declare function decodeCompactRows(text: string, options?: CompactRowsDecodeOptions): unknown;
-
-/**
- * CSV serializer — only valid for genuinely tabular data (a uniform array of
- * flat objects). CSV can be marginally smaller than the compact rows on pure tables, but it
- * does NOT preserve the JSON data model in general, so `supports()` is strict.
- */
-declare const csvSerializer: Serializer;
-
 /**
  * Format selector.
  *
@@ -1990,26 +2174,6 @@ declare class FormatSelector {
     }): 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.
  *
@@ -2197,6 +2361,61 @@ interface CompressionEconomics {
     minimumNetTokens?: number;
 }
 
+/**
+ * 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>;
+
 /**
  * Provider-neutral generation interface. Every provider (OpenAI-compatible,
  * Anthropic-compatible, Google-compatible, self-hosted) is adapted to this
@@ -2243,6 +2462,12 @@ interface ProviderRequest {
      * {@link ProviderResponse.servedServiceTier}.
      */
     deferrable?: boolean;
+    /**
+     * Adapters with explicit prompt-cache control write the provider's cache only
+     * at `stablePrefixMessages` (nowhere when it is undefined) instead of
+     * letting the provider choose. Others ignore it.
+     */
+    explicitCacheWrites?: boolean;
 }
 interface ProviderUsage {
     inputTokens: number;
@@ -2251,7 +2476,9 @@ interface ProviderUsage {
     cachedInputTokens?: number;
     /**
      * Input tokens billed at a PREMIUM to WRITE the provider's prefix cache
-     * (Anthropic `cache_creation_input_tokens`: 1.25x the normal rate).
+     * (Anthropic `cache_creation_input_tokens`, and OpenAI
+     * `prompt_tokens_details.cache_write_tokens` on GPT-5.6 and later: 1.25x the
+     * normal rate).
      *
      * This is a COST, not a discount, and it is reported separately for exactly
      * that reason: `cachedInputTokens` is a saving to publish in ledger 4, this
@@ -2259,6 +2486,27 @@ interface ProviderUsage {
      * bill INCREASE as a saving.
      */
     cacheWriteInputTokens?: number;
+    /**
+     * Output tokens the provider billed for hidden reasoning, already included in
+     * `outputTokens` (OpenAI `completion_tokens_details.reasoning_tokens`).
+     *
+     * `0` states that the answer carried no hidden reasoning. Where the provider
+     * does not break reasoning out (Anthropic's Messages API), the built-in
+     * adapter reports `0` only when the answer has no `thinking` or
+     * `redacted_thinking` block, and leaves this absent otherwise. Absent means
+     * nobody said, which is NOT the same as 0: a repeat served by reference only
+     * credits output when the call that ran reported exactly 0, because reasoning
+     * tokens are neither visible nor deterministic. A custom provider should set
+     * it only from its provider's own counter or an equally direct signal.
+     */
+    reasoningTokens?: number;
+    /**
+     * False when the provider did not report both counters for this call (for a
+     * stream: its final usage event never arrived), so the adapter filled the
+     * missing ones with 0. Absent means complete. A request with any such call is
+     * reported as `unmeasured`.
+     */
+    complete?: boolean;
 }
 interface ProviderResponse {
     text: string;
@@ -2318,1109 +2566,1605 @@ interface ProviderResponse {
      * would be describing a request some other adapter never made.
      */
     requestedServiceTier?: string;
+    /**
+     * Whether this answer can be handed to a later identical request (exact cache) or to a
+     * concurrent identical request. `false` when it carries content the layer keeps no copy of,
+     * such as generated files, cited sources, results of tools the provider ran itself, or
+     * reasoning the provider expects back: it is served to this caller only, it is not written
+     * to the exact cache, and a concurrent identical request makes its own call. Absent means
+     * replayable.
+     */
+    replayable?: boolean;
     raw?: unknown;
 }
+/** One event of a provider-level stream. */
+type ProviderStreamEvent = {
+    type: "text";
+    delta: string;
+} | {
+    type: "done";
+    response: ProviderResponse;
+};
+/** Options for {@link Provider.generate} and {@link Provider.generateStream}. */
+interface ProviderStreamOptions {
+    /** Cancels the HTTP request. */
+    signal?: AbortSignal;
+}
 interface Provider {
     readonly id: string;
-    generate(req: ProviderRequest): Promise<ProviderResponse>;
+    generate(req: ProviderRequest, options?: ProviderStreamOptions): Promise<ProviderResponse>;
+    /**
+     * Optional streaming variant of generate(). It must yield `text` events in
+     * order and end with exactly one `done` whose `response` is what generate()
+     * would have returned for the same answer: `response.text` equals the
+     * concatenated deltas, and tool calls travel only in `response.toolCalls`.
+     * When the provider's final usage event is missing, both counters are 0 and
+     * `usage.complete` is false. A body that ends before the provider signalled
+     * completion must throw, never yield `done`.
+     */
+    generateStream?(req: ProviderRequest, options?: ProviderStreamOptions): AsyncIterable<ProviderStreamEvent>;
 }
 
 /**
- * Deterministic mock provider.
+ * Offline license verification for the paid SDK.
  *
- * 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.
+ * A license is a compact signed token `base64url(header).base64url(payload).
+ * base64url(sig)`, the exact format BiVelio's licensing service mints. We verify
+ * the Ed25519 signature against BiVelio's public key, decode the payload, and
+ * apply the same grace policy the issuer applies. Verification is
+ * **browser-safe**: it uses
+ * `@noble/curves` (pure JS) + Web primitives (`atob`, `TextEncoder`) rather than
+ * `node:crypto`, so the shared entry point 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.
+ */
+/**
+ * `stale` NO es una licencia caducada: es una licencia PAGADA Y VIGENTE que no ha
+ * podido confirmar su estado contra el control plane dentro de la ventana de
+ * frescura — típicamente porque la salida de red está bloqueada.
  *
- * ⚠️ WHAT THIS PROVIDER CANNOT MEASURE, and it has already cost money once.
- * It fabricates the answer FROM THE SCHEMA it receives, so a smaller schema
- * always produces a smaller answer. Any lever that shrinks the contract sent to
- * the provider therefore appears to shrink the OUTPUT too — automatically, on
- * every run, whatever model id is being simulated. That is a property of this
- * file, not of any model.
+ * Existe porque antes ese caso reutilizaba `expired` "para que el union y todos
+ * los consumidores siguieran igual", y el ahorro de tipo se pagaba con el peor
+ * mensaje posible del producto: a un cliente al día, cuyo único problema era un
+ * cortafuegos, se le decía *"license is not active (expired). Renew your
+ * subscription"*. Le mandábamos a pagar otra vez algo que ya había pagado, y a
+ * mirar donde no estaba el problema.
  *
- * The output codebook is exactly that shape of lever, and against this provider
- * the benchmark reported it saving 24.8%. Measured live it saves 8.0% on
- * `gpt-4o` and COSTS 8.2% on `gpt-4o-mini`, because a real model decides how
- * much to WRITE and a smaller model writes more when the field names carry less
- * meaning. So: never take an output-token saving measured here as evidence of
- * anything. Prove those with the paired A/B in `benchmarks/ab-live.ts`, and
- * write tests for output-side effects against a provider that models the
- * behaviour you are claiming — see `test/codebook-de-salida.test.ts`.
+ * El comportamiento no cambia —sigue siendo fail-closed, `granted()` no lo
+ * concede— pero ahora el mensaje puede decir la verdad.
+ *
+ * `none` means "there is no key": what is left after `normalizeLicenseKey` is
+ * EMPTY. It is the same value `LicenseError.status` already carries when nothing
+ * was configured, because it is the same problem with the same fix: a
+ * `licenseKey: "   "` (an empty environment variable, a blank secret file) used
+ * to tell the customer their key "does not verify" — there was no key.
  */
-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;
+type LicenseStatus = "active" | "grace" | "expired" | "invalid" | "revoked" | "stale" | "none";
+/** 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;
 }
-declare class MockProvider implements Provider {
-    readonly id = "mock";
-    private readonly options;
-    constructor(options?: MockProviderOptions);
-    generate(req: ProviderRequest): Promise<ProviderResponse>;
+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;
 }
-declare function createMockProvider(options?: MockProviderOptions): Provider;
-
 /**
- * OpenAI-compatible provider adapter (chat/completions shape).
+ * 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;
+/**
+ * Normalize a license key the way it arrives from the real world — ONCE, at the
+ * entry point, never inside the verifier.
  *
- * 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.
+ * The README says `export BIVELIO_LICENSE_KEY=…` and dotenv trims, so that path
+ * never showed it. But anyone reading the key from a file (`readFileSync`), from
+ * a Docker/Kubernetes secret (mounted as a file, trailing newline included) or
+ * copying it out of an `Authorization` header handed over a CORRECT key with a
+ * `\n` after it, a space before it, quotes around it or a `Bearer ` in front —
+ * and the SDK answered "does not verify, check you pasted the WHOLE key". A
+ * wrong diagnosis on a good key is the worst possible hint: it sends the
+ * customer to look where the problem is not.
  *
- * Models that predate structured outputs reject `response_format` with a 400. The
- * adapter degrades for those: it repeats the request once with the schema carried
- * in the prompt instead, remembers the model so later requests skip the rejected
- * attempt, and reports `structuredNatively: false` so the savings report states
- * `constraints.backend: "none"` rather than claiming a guarantee the provider
- * never gave.
+ * Worse, it was INCONSISTENT: `tok + "\r\n"` passed and `tok + "\n"` did not,
+ * because `atob` ignores ASCII whitespace while the padding was computed from a
+ * length that included it, and two extra characters give the same remainder
+ * modulo 4 as zero. Behavior that depends on which editor saved the file is not
+ * behavior.
  *
- * Network calls use global `fetch` (Node >= 18) so there is no SDK dependency.
+ * Only OUTER wrapping is removed — whitespace, one pair of single or double
+ * quotes, a `Bearer` prefix in any capitalization — in that order, in one pass.
+ * Anything INSIDE the key is left alone: an interior space is not wrapping, it
+ * is a broken key, and {@link licenseKeyShape} reports it as `malformed`.
  */
-interface OpenAICompatibleOptions {
-    baseUrl: string;
-    apiKey?: string;
-    /**
-     * Strip the `provider/` prefix from model ids before sending (`openai/gpt-4o-mini`
-     * → `gpt-4o-mini`).
-     *
-     * Default (undefined): strip when `baseUrl` is OpenAI's own API or an Azure
-     * OpenAI endpoint, keep otherwise. OpenAI rejects a prefixed id with a 404
-     * ("model does not exist"), so the qualified ids the layer uses everywhere
-     * else — pricing, cache keys, the report — would break the very first call
-     * that reaches the provider. A gateway or a self-hosted server with a
-     * namespaced model name usually WANTS the prefix, so it is kept there. Set `true`/`false` to decide explicitly; an explicit value
-     * always wins.
-     */
-    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;
-}
+declare function normalizeLicenseKey(raw: string): string;
 /**
- * ¿Cumple este esquema las reglas del modo `strict` de OpenAI?
+ * The SHAPE of an already-normalized key, so the error message can tell apart
+ * three problems that used to get the same text:
  *
- * 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.
+ *   · `empty`     — there is no key (only whitespace, or nothing at all).
+ *   · `malformed` — not even the shape of a token: not three dot-separated
+ *                   base64url segments. This is where the `bvk_` service key
+ *                   pasted where the license goes lands, as does arbitrary text
+ *                   or a token with a line break in the middle.
+ *   · `token`     — has the shape; whether it verifies is up to the signature.
  *
- * 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.
+ * It is the SAME shape rule {@link verifyCompactSignature} enforces, so that "has
+ * the shape" and "verification was attempted" mean the same thing.
  */
-declare function isStrictCompatible(schema: unknown): boolean;
+type LicenseKeyShape = "empty" | "malformed" | "token";
+/** Classify a normalized key. See {@link LicenseKeyShape}. */
+declare function licenseKeyShape(normalizedKey: string): LicenseKeyShape;
 /**
- * Decides the id that travels on the wire. Explicit option wins; otherwise the
- * endpoint decides: OpenAI/Azure get the bare id, everything else keeps what
- * the caller wrote. Exported for the pipeline-level test that pins the README
- * snippet; not part of the public API.
+ * 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.
+ *
+ * Shape is checked SEGMENT by segment, not just by counting dots. Three parts
+ * used to be enough and the rest was left to `atob`, which ignores whitespace:
+ * that is how a token with `\r\n` after it verified while the same token with
+ * `\n` did not (see {@link normalizeLicenseKey}). The shared primitive must give
+ * the same answer to the same input, always; a caller that wants to tolerate
+ * wrapping normalizes BEFORE calling.
  */
-declare function quitarPrefijoDeProveedor(model: string, explicito: boolean | undefined, baseUrl: string): string;
-declare class OpenAICompatibleProvider implements Provider {
-    readonly id: string;
-    private readonly opts;
-    private readonly fetchImpl;
-    /** Models of this endpoint already known to reject `response_format`. */
-    private readonly sinResponseFormat;
-    constructor(opts: OpenAICompatibleOptions);
-    generate(req: ProviderRequest): Promise<ProviderResponse>;
-    /** Build the request body and post it. `nativo` selects the `response_format` path. */
-    private enviar;
-    /** Translate a 2xx endpoint response into the provider-neutral shape. */
-    private leer;
-}
-
+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;
+};
 /**
- * Anthropic Messages API adapter.
- *
- * Speaks `POST /v1/messages`: the system prompt travels in its own top-level
- * `system` field (not as a message), tools are `{name, description,
- * input_schema}` with no `function` wrapper, and prefix caching is requested
- * with EXPLICIT `cache_control` breakpoints — Anthropic does not cache on its
- * own. A cached read is billed at 0.1x the input rate, which is the largest
- * single lever on the input side of a customer's bill.
+ * 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 what the issuing
+ * control plane resolves for the same token. Bad signature / malformed
+ * → invalid; otherwise the status comes from {@link deriveStatus}.
  *
- * Network calls use global `fetch` (Node >= 18) so there is no SDK dependency.
+ * A public entry point, so it normalizes like the others (gate and refresher):
+ * the same key must resolve the same whichever way it comes in.
  */
-/** Render order of the request, which is also the order the cache prefix grows in. */
-interface AnthropicOptions {
-    apiKey?: string;
-    /** Defaults to the public API. Override for a gateway or a proxy. */
-    baseUrl?: string;
+declare function resolveLicense(token: string, publicKey: string | LicenseKeyset, opts?: {
+    nowSeconds?: number;
+    revoked?: ReadonlySet<string>;
+}): ResolvedLicense;
+
+/**
+ * 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 {
     /**
-     * Strip the `provider/` prefix from model ids before sending
-     * (`anthropic/claude-sonnet-4-5` → `claude-sonnet-4-5`). Default (undefined):
-     * strip when talking to `api.anthropic.com`, which rejects a prefixed id;
-     * keep for a gateway or proxy, which usually routes on it. An explicit value
-     * always wins.
+     * 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.
      */
-    stripProviderPrefix?: boolean;
-    /** Wire version pinned in the `anthropic-version` header. */
-    apiVersion?: string;
-    /** Extra headers (e.g. for a gateway). */
-    headers?: Record<string, string>;
-    /** Injectable fetch for testing. */
-    fetchImpl?: typeof fetch;
+    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;
     /**
-     * `max_tokens` is REQUIRED by this API — unlike the OpenAI shape, where it is
-     * optional. A request without one is a 400, so the adapter has to supply a
-     * value. It is deliberately generous: a low default would truncate answers
-     * and the truncation would look like a model failure rather than an adapter
-     * default.
+     * The numbers behind "compress only when it pays for itself" — in money, not
+     * in tokens.
+     *
+     * All optional, and the default never invents a saving: the layer compresses
+     * when the net token saving justifies it, and holds back when compressing
+     * would push the prompt below the provider's cacheable minimum — where fewer
+     * tokens can mean a larger bill. Declare {@link CompressionEconomics.prefix}
+     * with your own measurements to unlock the full decision in both directions.
      */
-    defaultMaxOutputTokens?: number;
+    compressionEconomics?: CompressionEconomics;
+    retriever?: Retriever;
+    reranker?: Reranker;
     /**
-     * When true (recommended for measurement), a response whose `usage` block is
-     * missing its counters is treated as a HARD ERROR instead of being coerced to
-     * 0 tokens. An absent usage payload otherwise becomes `actual cost = 0` → a
-     * fabricated 100% saving.
+     * Tuning for the model cascade (`savings.modelCascade`). All optional; the
+     * defaults measure and never spend.
      */
-    requireUsage?: boolean;
+    modelCascade?: ModelCascadeSettings;
     /**
-     * How many `cache_control` breakpoints the adapter may spend.
+     * Layer-wide defaults for the provider price levers (`savings.deferrable`,
+     * `savings.standalone`) and what to do when the cheaper tier has no capacity.
+     * All off by default; a request's own `savings` value always wins.
+     */
+    priceLevers?: PriceLeverSettings;
+    /**
+     * 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.
      *
-     * The API caps them at 4 per request. The adapter never needs more than 2
-     * (end of system, end of the stable message prefix) and the cap is exposed so
-     * a gateway with a stricter limit can lower it. Raising it above 4 is
-     * pointless: the extra breakpoints are rejected by the API, not ignored.
+     * Surrounding whitespace (the trailing newline of a file or mounted secret),
+     * wrapping quotes and a `Bearer ` prefix are stripped before verification, so
+     * a key read with `readFileSync` works as-is. Anything INSIDE the key is not
+     * touched: a key with a space in the middle is a broken key.
      */
-    maxCacheBreakpoints?: number;
+    licenseKey?: string;
     /**
-     * When true, requests that the pipeline decided to mark also carry the
-     * request-level `cache_control` (Anthropic's automatic caching): the provider
-     * places one extra breakpoint on the last cacheable block and moves it
-     * forward as the conversation grows, so the history beyond the declared
-     * stable prefix is cached incrementally too. It spends one of the four
-     * breakpoint slots and never fires when the economic gate declined to mark.
+     * 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. **Ignored in the published npm package**, where a
+     * {@link licenseKey} verified against the embedded BiVelio public key is the
+     * only accepted license — passing a gate there logs a warning and changes
+     * nothing. It exists for builds from source (this repo's own tests and
+     * benchmarks), where it takes precedence over {@link licenseKey}.
+     */
+    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.
      *
-     * Off by default, and deliberately so: the moving breakpoint writes the
-     * volatile tail of EVERY marked request at the 1.25x write premium. That
-     * pays for itself on conversational or agentic traffic — the next turn reads
-     * the whole history at 0.1x — and loses money on one-shot traffic where
-     * nothing ever reads it back. It is also rejected by legacy Bedrock
-     * deployments. Turn it on when your traffic is multi-turn.
+     * NON-BLOCKING: 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`.
      */
-    automaticCache?: boolean;
+    licenseServerUrl?: string;
     /**
-     * Whether a request carrying BOTH the caller's tools and an output contract
-     * may send `tool_choice: {type: "any"}`, which obliges the model to answer
-     * through SOME tool — its pick — instead of writing prose.
+     * 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 72h, `DEFAULT_MAX_STALENESS_SECONDS`). 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_…`) — your machine credential. It does TWO things,
+     * and the second one is why a long-running deployment needs it:
      *
-     * Defaults to `true`, and the default is the point: without it this exact
-     * combination measured 62% MORE expensive than sending no layer at all, every
-     * single time, because prose forces a second full call to repair. Turning it
-     * off restores the old behaviour for a caller who genuinely needs a plain-text
-     * turn to be reachable while a contract is attached.
+     *  1. **Licence renewal pickup.** Each billing period mints a NEW licence token;
+     *     the one you deployed expires at the end of the period (+ grace). With this
+     *     key the SDK fetches the renewed token from the control plane and swaps it
+     *     in without a restart. WITHOUT it there is no machine pickup, so somebody
+     *     must paste the new token by hand every cycle or the deployment stops with
+     *     `LicenseError` once the grace period ends — while the subscription is paid
+     *     and current. Disable with {@link licenseRefresh}`.enabled = false`.
+     *  2. **DETECTIVE usage metering.** Usage figures after each request —
+     *     request id, model id, cache outcome, token counts and cost figures, tagged
+     *     with an opaque machine seat id (section 5 of the LICENSE lists every field) —
+     *     NEVER prompts, completions or provider credentials. Disable with
+     *     {@link metering}`.enabled = false` (which does NOT disable renewal pickup).
+     *
+     * Both are best-effort and non-blocking: a slow or unreachable control plane
+     * never blocks or breaks `generate()`. Get the key from your dashboard.
      */
-    forceAnswerThroughTool?: boolean;
-}
-declare class AnthropicProvider implements Provider {
-    readonly id: string;
-    private readonly opts;
-    private readonly fetchImpl;
-    constructor(opts?: AnthropicOptions);
-    /** The id Anthropic's API sees: bare at `api.anthropic.com`, as written elsewhere. */
-    private modeloEnElCable;
-    generate(req: ProviderRequest): Promise<ProviderResponse>;
-    private construirCuerpo;
-    private marcarCache;
-    /** Traduce una respuesta 2xx a la forma neutra del layer. */
-    private leer;
-}
-
-/**
- * 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 {
+    serviceAccountKey?: string;
     /**
-     * Resolved license status — the stable handle for branching on the cause,
-     * since the message text is rewritten whenever it can be made clearer:
+     * Automatic licence-renewal pickup (on by default when {@link serviceAccountKey}
+     * and {@link licenseServerUrl} are both set).
      *
-     * - `none`    — nothing was configured (no `licenseKey`, no gate).
-     * - `invalid` — a key was configured but does not verify.
-     * - `expired` / `grace` — it verifies, but the term is over.
-     * - `revoked` — cancelled by the control plane.
-     * - `stale`   — paid and current, but unconfirmed: a connectivity problem.
+     * Turning it OFF means you take responsibility for deploying the renewed token
+     * each billing period; if nobody does, the SDK stops at the end of the grace
+     * period even though the subscription is paid.
+     */
+    licenseRefresh?: {
+        enabled?: boolean;
+        /** Check cadence in ms (default 3600000 = 1 h). */
+        intervalMs?: number;
+        /** How long before expiry to start looking, seconds (default 7 days). */
+        leadSeconds?: number;
+    };
+    /**
+     * 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 for USAGE REPORTING even when {@link serviceAccountKey} is set
+         * (default: on). It does NOT disable licence-renewal pickup — that has its
+         * own switch, {@link licenseRefresh}`.enabled`, because turning off telemetry
+         * must not silently stop your licence from renewing.
+         */
+        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;
+    };
+    /** Opt-in A/B verification on your own traffic. Off by default. See VerificationSettings. */
+    verification?: VerificationSettings;
+    /**
+     * 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.
      *
-     * The same value is repeated at the end of the message (`license status: X`)
-     * because an uncaught error prints nothing else.
+     * 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.
      */
-    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 BiVelio's licensing service mints. We verify
- * the Ed25519 signature against BiVelio's public key, decode the payload, and
- * apply the same grace policy the issuer applies. Verification is
- * **browser-safe**: it uses
- * `@noble/curves` (pure JS) + Web primitives (`atob`, `TextEncoder`) rather than
- * `node:crypto`, so the shared entry point 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.
- */
+    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;
+    /**
+     * Refuse the single repair retry when paying for it would push this request's
+     * cost above what it would have cost WITHOUT the layer. The invalid answer is
+     * then returned as-is with `constraints.structurallyValid: false`, plus a
+     * warning naming the three figures.
+     *
+     * OFF by default, and the default is a deliberate, measured choice rather than
+     * caution — read this before turning it on.
+     *
+     * The bound sounds narrow ("only the worst case") and is not. The baseline of
+     * a call that ran is reconstructed EXCLUDING the repair (see `estimateCost`:
+     * `actualInput - repairInput`), precisely so a retry cannot pay for itself in
+     * the report. That makes the threshold unreachable by construction: the repair
+     * only ever moves `actual`, never the baseline, so ANY repair breaches it
+     * whenever the layer's other books came out flat. On a request where nothing
+     * was compressed, cached or eliminated, `baseline === actual` exactly and the
+     * gate suppresses every repair, however cheap.
+     *
+     * So this is not "cap the tail", it is "stop repairing unless the layer has
+     * already banked more than the repair will cost". That is a real quality
+     * policy, not a rounding rule, and it is the caller's contract to decide on —
+     * hence opt-in.
+     *
+     * There is no threshold that fires on the pathological case and spares the
+     * flat one; they are the same arithmetic at different magnitudes. And there is
+     * a genuine argument on the other side: an answer that misses its contract is
+     * a MODEL failure, so the no-layer path would have had to pay for its own
+     * second call too — charging the whole retry against the layer compares one
+     * valid answer to one invalid answer.
+     *
+     * Turn it on when a hard per-request ceiling matters more than contract
+     * compliance — a batch backfill, a cost-capped tenant. Leave it off when the
+     * caller relies on the shape being right.
+     */
+    skipRepairAboveBaseline?: boolean;
+    /**
+     * 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;
+    /**
+     * Silence BV-SALA's console warnings. They are ON by default, and they only
+     * ever report a condition whose symptom is otherwise invisible: a saving knob
+     * asked for but not wired up, usage that stops reaching the control plane, a
+     * revocation list going stale. Nothing here throws and nothing here changes
+     * what the layer does — turning it on only removes the console noise, so set
+     * it when you have your own observability. Applies to the pipeline, the usage
+     * emitter and the revocation poller alike.
+     */
+    silenceWarnings?: boolean;
+    /**
+     * Load the exact OpenAI tokenizer (`gpt-tokenizer`, optional peer) into the
+     * default registry when it is installed. ON by default: without it, every
+     * saving where the layer removed something is reported as `estimated` and
+     * never billed, and the SDK warns once. Set to `false` to keep the built-in
+     * heuristic even when the package is present (tests calibrated on the
+     * heuristic, or a process that must not spend the encoding's memory). Ignored
+     * when you pass your own `tokenizer` registry: you decide what it contains.
+     */
+    exactTokenizer?: boolean;
+    /** Injectable clock for deterministic tests. */
+    now?: () => number;
+    /** Injectable id generator for deterministic tests. */
+    generateId?: () => string;
+}
 /**
- * `stale` NO es una licencia caducada: es una licencia PAGADA Y VIGENTE que no ha
- * podido confirmar su estado contra el control plane dentro de la ventana de
- * frescura — típicamente porque la salida de red está bloqueada.
- *
- * Existe porque antes ese caso reutilizaba `expired` "para que el union y todos
- * los consumidores siguieran igual", y el ahorro de tipo se pagaba con el peor
- * mensaje posible del producto: a un cliente al día, cuyo único problema era un
- * cortafuegos, se le decía *"license is not active (expired). Renew your
- * subscription"*. Le mandábamos a pagar otra vez algo que ya había pagado, y a
- * mirar donde no estaba el problema.
- *
- * El comportamiento no cambia —sigue siendo fail-closed, `granted()` no lo
- * concede— pero ahora el mensaje puede decir la verdad.
- *
- * `none` means "there is no key": what is left after `normalizeLicenseKey` is
- * EMPTY. It is the same value `LicenseError.status` already carries when nothing
- * was configured, because it is the same problem with the same fix: a
- * `licenseKey: "   "` (an empty environment variable, a blank secret file) used
- * to tell the customer their key "does not verify" — there was no key.
+ * Tuning for the model cascade. Everything here is optional, and the defaults
+ * cost nothing: with no settings at all, `modelCascade: "shadow"` measures what
+ * it can measure for free and makes no extra provider call.
  */
-type LicenseStatus = "active" | "grace" | "expired" | "invalid" | "revoked" | "stale" | "none";
-/** 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;
+interface ModelCascadeSettings {
+    /**
+     * Your own strong → cheap pairs, replacing the built-in table.
+     *
+     * Keys and values are model ids WITHOUT a vendor prefix (`"gpt-4o"`, not
+     * `"openai/gpt-4o"`); the caller's prefix is carried over automatically, and a
+     * dated snapshot inherits from its base id. A pair whose economics do not work
+     * out at your prices is refused with a reason in the report — declaring it here
+     * does not override the arithmetic.
+     */
+    pairs?: Record<string, string>;
+    /**
+     * How many requests of a workload are routed before the automatic shut-off
+     * judges the measured escalation rate (default 20).
+     *
+     * The rate is only observable on requests that were actually routed, so there
+     * is no way to know without spending a bounded amount to find out. Worst case
+     * (every one of them escalates) that exploration costs `n x r` requests'
+     * worth of extra spend, once per workload per process — with a ratio of 0.06
+     * and the default, about 1.2 requests.
+     */
+    exploration?: number;
+    /**
+     * PRICED OPT-IN, default 0 (off). Fraction of `"shadow"` requests on which the
+     * layer also calls the cheap model, purely to measure.
+     *
+     * Shadow mode is free precisely because it does not run the cheap model: it
+     * reports eligibility, the arithmetic, and what the swap would have been worth.
+     * What it cannot know for free is the one number that decides everything — how
+     * often the deterministic gate would have REJECTED the cheap answer. That
+     * answer does not exist until the cheap model writes one.
+     *
+     * So this buys it, and the price is exact: each sampled request costs one extra
+     * cheap call, i.e. `r` of what the request already cost — about 6% for
+     * gpt-4o → gpt-4o-mini. At `0.05` that is roughly 0.3% on top of your bill, and
+     * every sampled request reports its own `modelCascade.sampleCost`. It also
+     * DOUBLES that request's provider latency, because the extra call is sequential.
+     *
+     * The sampled request's tokens count as spend and are held out of the baseline,
+     * exactly like the repair retry: measurement must never pay for itself.
+     *
+     * Which requests get sampled is derived from the request's own cache key, so it
+     * is deterministic and stable — the same request is always sampled or always
+     * not, and no `Math.random` decides how your money is spent.
+     */
+    shadowSampleRate?: number;
 }
 /**
- * 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.
+ * Defaults for the provider price levers. Everything here is off unless you set it,
+ * and a request's own `savings` value always wins over it.
  */
-interface LicenseKeyset {
-    /** kid → SPKI PEM. */
-    keys: Record<string, string>;
-    /** kid used for tokens without a `kid` header (the current/legacy key). */
-    defaultKid: string;
+interface PriceLeverSettings {
+    /** Default for `savings.deferrable` on every request of this layer. A request's own value wins. Defaults to false. */
+    deferrable?: boolean;
+    /** Default for `savings.standalone`. A request's own value wins. Defaults to false. */
+    standalone?: boolean;
+    /**
+     * When a deferrable request finds no capacity on the cheaper tier (HTTP 429 or 503):
+     * "throw" (default) surfaces the error unchanged; "standard" repeats it once at the
+     * standard tier and price.
+     */
+    onCapacityError?: "throw" | "standard";
 }
-/** Narrow a verification key to a {@link LicenseKeyset} (vs a bare SPKI PEM string). */
-declare function isKeyset(k: string | LicenseKeyset): k is LicenseKeyset;
+declare const DEFAULT_COST_MODEL: CostModel;
+
 /**
- * Normalize a license key the way it arrives from the real world — ONCE, at the
- * entry point, never inside the verifier.
- *
- * The README says `export BIVELIO_LICENSE_KEY=…` and dotenv trims, so that path
- * never showed it. But anyone reading the key from a file (`readFileSync`), from
- * a Docker/Kubernetes secret (mounted as a file, trailing newline included) or
- * copying it out of an `Authorization` header handed over a CORRECT key with a
- * `\n` after it, a space before it, quotes around it or a `Bearer ` in front —
- * and the SDK answered "does not verify, check you pasted the WHOLE key". A
- * wrong diagnosis on a good key is the worst possible hint: it sends the
- * customer to look where the problem is not.
- *
- * Worse, it was INCONSISTENT: `tok + "\r\n"` passed and `tok + "\n"` did not,
- * because `atob` ignores ASCII whitespace while the padding was computed from a
- * length that included it, and two extra characters give the same remainder
- * modulo 4 as zero. Behavior that depends on which editor saved the file is not
- * behavior.
- *
- * Only OUTER wrapping is removed — whitespace, one pair of single or double
- * quotes, a `Bearer` prefix in any capitalization — in that order, in one pass.
- * Anything INSIDE the key is left alone: an interior space is not wrapping, it
- * is a broken key, and {@link licenseKeyShape} reports it as `malformed`.
+ * Options shared by every framework adapter. Each one has the same meaning as in
+ * `createSavingsLayer`; the adapter supplies the provider itself, which is the
+ * framework's own model call, forwarded unchanged.
  */
-declare function normalizeLicenseKey(raw: string): string;
+type SavingsAdapterOptions = Pick<SavingsLayerConfig, "licenseKey" | "licenseServerUrl" | "serviceAccountKey" | "licenseRefresh" | "licenseRevocation" | "licensePollIntervalSeconds" | "licenseFetch" | "metering" | "meteringUrl" | "meteringFetch" | "costModels" | "defaultCostModel" | "exactCache" | "exactCacheTtlMs" | "resolvers" | "exactTokenizer" | "silenceWarnings" | "failOpen"> & {
+    /**
+     * Tools without side effects, by name, or a function that says whether a tool
+     * has none. Any other tool is treated as having side effects: a request that
+     * offers it is never answered from a cache and never shares an answer with an
+     * identical request in flight, because the action has to run.
+     */
+    readOnlyTools?: readonly string[] | ((toolName: string) => boolean);
+    /**
+     * Switch off, for every call, the levers that answer without calling the
+     * model. All three are on by default.
+     */
+    savings?: SavingsAdapterLevers;
+    /**
+     * Called once per model call with its report. An error thrown here is caught
+     * and never reaches the call.
+     */
+    onReport?: (report: SavingsReport) => void;
+};
 /**
- * The SHAPE of an already-normalized key, so the error message can tell apart
- * three problems that used to get the same text:
- *
- *   · `empty`     — there is no key (only whitespace, or nothing at all).
- *   · `malformed` — not even the shape of a token: not three dot-separated
- *                   base64url segments. This is where the `bvk_` service key
- *                   pasted where the license goes lands, as does arbitrary text
- *                   or a token with a line break in the middle.
- *   · `token`     — has the shape; whether it verifies is up to the signature.
- *
- * It is the SAME shape rule {@link verifyCompactSignature} enforces, so that "has
- * the shape" and "verification was attempted" mean the same thing.
+ * The levers an adapter can use, all of them answers given without calling the
+ * model: an exact repeat, an identical request already in flight, and a
+ * computed answer (arithmetic). They can only be switched off.
  */
-type LicenseKeyShape = "empty" | "malformed" | "token";
-/** Classify a normalized key. See {@link LicenseKeyShape}. */
-declare function licenseKeyShape(normalizedKey: string): LicenseKeyShape;
+type SavingsAdapterLevers = Pick<SavingsToggles, "exactCache" | "singleflight" | "deterministicResolvers">;
+/** Per-call options, where the framework has a place to pass them. */
+interface SavingsCallOptions {
+    /** Cache identity for this call (tenant, session…). It wins over the adapter's `context` option. */
+    context?: RequestContext;
+    /** Switch off levers for this call only. */
+    savings?: SavingsAdapterLevers;
+}
+
 /**
- * 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.
+ * Tokenizador EXACTO — la regla del proveedor, no una aproximación.
  *
- * Shape is checked SEGMENT by segment, not just by counting dots. Three parts
- * used to be enough and the rest was left to `atob`, which ignores whitespace:
- * that is how a token with `\r\n` after it verified while the same token with
- * `\n` did not (see {@link normalizeLicenseKey}). The shared primitive must give
- * the same answer to the same input, always; a caller that wants to tolerate
- * wrapping normalizes BEFORE calling.
+ * 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
+ * An estimator that is not calibrated for the destination model can miss by
+ * enough to publish a baseline several times the real one, which would credit a
+ * saving that never existed. That is why `basis` degrades instead of claiming.
  */
-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;
-};
+
+/** Lo que necesitamos de gpt-tokenizer. Tipado aquí para no depender de sus tipos. */
+interface BpeEncoder {
+    encode(text: string): number[] | {
+        length: number;
+    };
+}
 /**
- * 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
+ * Estimador exacto sobre una codificación BPE ya cargada.
+ *
+ * Se construye con el encoder 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 function deriveStatus(payload: {
-    jti: string;
-    expires_at: number;
-    grace_days: number;
-}, nowSeconds: number, revoked?: ReadonlySet<string>): LicenseStatus;
+declare class ExactTokenizer implements TokenEstimator {
+    private readonly encoder;
+    readonly id: string;
+    readonly exact = true;
+    constructor(id: string, encoder: BpeEncoder);
+    count(text: string): number;
+}
+/** Modelos que usan cada codificación. Sirve para mapear el registro de una vez. */
+declare const MODELS_BY_ENCODING: Readonly<Record<string, readonly string[]>>;
 /**
- * Verify + apply the grace policy → a resolved status. Mirrors what the issuing
- * control plane resolves for the same token. Bad signature / malformed
- * → invalid; otherwise the status comes from {@link deriveStatus}.
+ * 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.
  *
- * A public entry point, so it normalizes like the others (gate and refresher):
- * the same key must resolve the same whichever way it comes in.
+ * 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 resolveLicense(token: string, publicKey: string | LicenseKeyset, opts?: {
-    nowSeconds?: number;
-    revoked?: ReadonlySet<string>;
-}): ResolvedLicense;
+declare function registerExactTokenizer(registro: {
+    register(e: TokenEstimator): unknown;
+    mapModel(model: string, tokenizerId: string): unknown;
+}, opciones?: {
+    codificaciones?: readonly string[];
+}): Promise<boolean>;
+/**
+ * @deprecated Spanish-named aliases kept for one minor version. Use
+ * {@link MODELS_BY_ENCODING} and {@link registerExactTokenizer}. The public
+ * surface of this package is English-only; these leaked and are on the way out.
+ */
+declare const MODELOS_POR_CODIFICACION: Readonly<Record<string, readonly string[]>>;
+/** @deprecated Use {@link registerExactTokenizer}. */
+declare const registrarTokenizadorExacto: typeof registerExactTokenizer;
 
-/** 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.
+ * 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.
+ *
+ * `servedModel` CARRIES THE MODEL THAT WILL ACTUALLY ANSWER, not the one the
+ * caller named, and that distinction is what stops the model cascade from
+ * poisoning the cache. Routing to a cheap model and storing its answer under the
+ * STRONG model's key would hand that answer to the next request — one with the
+ * cascade off, or from another process entirely — while the report claims the
+ * requested model served it. That is a silent model swap, deferred, which is the
+ * worst kind of silent model swap.
+ *
+ * `modelFamily` is derived from whichever id is used, for the same reason: it is
+ * part of the identity of whoever answers.
  */
-declare function verifyRevocationList(token: string, publicKey: string | LicenseKeyset, opts?: {
-    minSeq?: number;
-    nowSeconds?: number;
-    maxSkewSeconds?: number;
-}): RevocationListVerification;
+declare function buildExactKey(c: CanonicalRequest, opciones?: {
+    servedModel?: string;
+}): string;
 /**
- * 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}.
+ * 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.
+ *
+ * `schema` is REQUIRED here, even though `contract` is already part of the key:
+ * two concurrent calls that differ only in `schemaVersion` are different
+ * requests and must never coalesce. All three doors — exact key, in-flight key
+ * and semantic filter — key on the same identity, by design.
+ *
+ * `servedModel` CARRIES THE MODEL THAT WILL ACTUALLY ANSWER, for the same reason
+ * {@link buildExactKey} does, and this door is the one that leaks FIRST. The
+ * exact key protects the answer AFTER it is stored; this one protects it while
+ * it is still being written, and a follower does not re-run anything — it is
+ * handed the leader's text verbatim.
+ *
+ * The leak it closes, measured: two concurrent requests for the same text, one
+ * with `savings.modelCascade: "on"` and one with the cascade OFF, coalesced onto
+ * one execution. The routed leader called the cheap model, and the caller who
+ * never opted in — whose own decision was "do not route" — was served the cheap
+ * model's answer. Same shape inside a single uniformly-configured deployment:
+ * the automatic shut-off can latch between two concurrent requests, so one is
+ * routed and the other is not, and coalescing hands one of them the other's
+ * model. Whoever the layer decided must go to the strong model has to actually
+ * go there.
+ *
+ * `deferrable` CLOSES THE SAME HOLE ON THE LATENCY AXIS, which is why it belongs
+ * here and NOT in {@link buildExactKey}. The two doors do not risk the same
+ * thing: the exact key hands out an answer that is ALREADY WRITTEN, where the
+ * processing tier only picked a queue and changes neither the text nor the wait
+ * of whoever receives it. This one binds a follower to a call that HAS NOT COME
+ * BACK YET, so it imposes the leader's wait on them.
+ *
+ * A caller who never set `savings.deferrable` must not be made to wait for one
+ * who did.
  */
-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>;
+declare function buildInflightKey(c: CanonicalRequest, opciones?: {
+    servedModel?: string;
+    deferrable?: boolean;
+    toolDiscovery?: boolean;
+    maxOutputTokens?: number;
+}): 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;
     /**
-     * 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.
+     * May the SDK elide old, large tool_results before resending? Computed, not
+     * hardcoded like `allowCompression`: eliding drops whole tool outputs, so it
+     * honors the same vetoes as the semantic cache — write tools, freshness,
+     * personalization, stochastic sampling and `day`.
      */
-    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;
+    allowElision: 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;
     /**
-     * Why the key does not open, when it does not; `undefined` when it verified.
-     * Under `status() === "invalid"` it tells a key that does NOT EVEN HAVE THE
-     * SHAPE of a token (`"malformed"`: the `bvk_` pasted where the license goes,
-     * arbitrary text) from a well-formed one whose signature fails (the verifier's
-     * reason, e.g. `"bad signature"`). Both are `invalid` — the stable handle for
-     * branching does not change — but the advice given to the customer differs.
+     * Is this agentic traffic? True when the request declares tools (read-only
+     * ones included), carries tool calls or tool results, or holds more than one
+     * user turn.
+     *
+     * Agentic traffic is kept out of the semantic cache by default, and only by
+     * default: `savings.semanticCache: "include-agentic"` lets it in. Two runs of
+     * an agent loop can differ only in what a tool returned, and the
+     * deterministic guard compares figures, negation and word overlap, not
+     * whether a tool said something else in words. The exact cache and elision
+     * are not affected by this flag.
      */
-    reason(): string | undefined;
-    /** Unix seconds after which the online status should be re-checked (poller anchor). */
-    refreshAfter?(): number | undefined;
+    isAgentic: boolean;
+    /**
+     * Techo de antigüedad para una entrada de caché exacta, derivado del
+     * `freshnessBucket`. `null` = sin techo propio (manda el TTL por defecto).
+     * Existe porque el bucket NO particiona la clave —va crudo al hash y no rota—,
+     * así que sin esto "hour" y "day" no significaban nada operativamente.
+     */
+    maxCacheAgeMs: number | null;
+    reasons: string[];
 }
+declare function evaluatePolicy(c: CanonicalRequest): Policy;
+
 /**
- * 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).
+ * A LOCAL EMBEDDING FUNCTION — no network, no API key, no per-call cost.
  *
- * 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;
+ * The semantic cache needs a way to compare meaning. Wiring it to a hosted
+ * embedding endpoint is the obvious answer and a bad default: it makes every
+ * miss cost a network round-trip and money, and it forces a provider choice onto
+ * a customer who never asked for one. So the cache shipped with no embedder at
+ * all, which means it never matched anything.
+ *
+ * This is the third option: a deterministic bag-of-features vector computed in
+ * microseconds from the text itself. It captures LEXICAL closeness — the same
+ * question asked with different filler words — which is the overwhelming majority
+ * of real repeat traffic. It does NOT capture deep semantics: "what is a CDN"
+ * and "explain content delivery networks" share no tokens and will not match.
+ *
+ * WHY THAT IS SAFE, AND THIS IS THE PART THAT MATTERS. A semantic cache's one
+ * unforgivable failure is confidently answering a NEARBY BUT DIFFERENT question.
+ * This vector never gets the chance: the cache runs a deterministic precision
+ * guard beneath the embedding — matching numbers and dates, negation parity and a
+ * content-overlap floor — and every isolation field (tenant, principal, model,
+ * schema, attached data) is a hard filter applied before similarity is scored.
+ * A weak embedding can only cause a MISS, which costs one real call. It cannot
+ * produce a wrong answer.
+ *
+ * Pass your own `embed` to {@link InMemorySemanticCache} to get true semantics.
+ * This one exists so that the feature is worth something with zero setup.
+ */
+/**
+ * The vector for a piece of text.
+ *
+ * Features are unigrams plus adjacent bigrams: bigrams are what keep word ORDER
+ * from being free. Without them "does A cause B" and "does B cause A" are the
+ * same point in space.
+ *
+ * Term weight is sublinear (`1 + log tf`) so a word repeated forty times does not
+ * dominate the direction of the vector, and the result is L2-normalised so cosine
+ * similarity is a plain dot product.
+ */
+declare function vectorLocal(texto: string): number[];
+/**
+ * The default embedding function for {@link InMemorySemanticCache}.
+ *
+ * Synchronous by design — it returns the array, not a promise — so a cache lookup
+ * adds no await and no latency to the request path.
+ */
+declare function embebedorLocal(texto: string): number[];
+/**
+ * The similarity floor this embedder is calibrated for.
+ *
+ * A lexical vector sits lower than a sentence-transformer on genuine paraphrases,
+ * so the 0.9 default that suits a hosted embedder would reject almost everything
+ * here. This value was measured on paraphrase pairs against near-miss pairs, not
+ * guessed — see `test/embebedor-local.test.ts`, which fails if the two
+ * populations stop being separable.
+ */
+declare const UMBRAL_LOCAL = 0.72;
 
 /**
- * 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`).
+ * Conversational memory by deltas.
  *
- * 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, which `createSavingsLayer` wires up for you.
+ * 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.
  */
-declare function gateFromKey(licenseKey: string, publicKey: string | LicenseKeyset, now?: () => number): ResolvedGate;
+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;
 
-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;
-    /**
-     * Silencia los avisos por consola. Por defecto están ENCENDIDOS, y ese defecto
-     * es la corrección: el sondeo es fail-open, así que un call-home roto no rompe
-     * nada visible — la lista de revocaciones simplemente se queda vieja, en
-     * silencio, durante días. Quien tenga observabilidad propia puede apagarlos;
-     * quien no la tenga, que es casi todo el mundo, se entera igual.
-     */
-    silenceWarnings?: boolean;
-    /**
-     * @deprecated Spanish name that leaked into the public options. Use
-     * {@link RevocationPollerOptions.silenceWarnings}. Honoured for one minor
-     * version so nobody gets their warnings back by surprise.
+/**
+ * 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
+ * The compact encoder is only ever a challenger.
+ */
+declare const jsonCompactSerializer: Serializer;
+
+/**
+ * Compact row encoder.
+ *
+ * Its 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 it 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<->rows
+ * round-trip is deterministic and testable.
+ */
+interface CompactRowsOptions {
+    /** Field delimiter within tabular/inline rows. */
+    delimiter?: "," | "\t";
+    /** Indentation unit. */
+    indent?: string;
+}
+declare function encodeCompactRows(value: unknown, options?: CompactRowsOptions): 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 the compact encoder. Kept short on purpose — this text
+ * is the per-request overhead the selector must amortize before it wins.
+ */
+declare const COMPACT_ROWS_INSTRUCTION: string;
+declare function createCompactRowsSerializer(options?: CompactRowsOptions): Serializer;
+declare const compactRowsSerializer: Serializer;
+
+/**
+ * Decoder for the subset emitted by {@link encodeCompactRows}.
+ *
+ * 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 it for, and makes the
+ * JSON<->rows round-trip deterministic and testable. List-form arrays of nested
+ * objects are intentionally out of scope for decoding (the selector never picks
+ * it for those, since JSON wins there anyway).
+ */
+interface CompactRowsDecodeOptions {
+    delimiter?: "," | "\t";
+    indent?: string;
+}
+declare function decodeCompactRows(text: string, options?: CompactRowsDecodeOptions): unknown;
+
+/**
+ * CSV serializer — only valid for genuinely tabular data (a uniform array of
+ * flat objects). CSV can be marginally smaller than the compact rows on pure tables, but it
+ * does NOT preserve the JSON data model in general, so `supports()` is strict.
+ */
+declare const csvSerializer: Serializer;
+
+/**
+ * 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;
+
+/**
+ * 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.
+ *
+ * ⚠️ WHAT THIS PROVIDER CANNOT MEASURE, and it has already cost money once.
+ * It fabricates the answer FROM THE SCHEMA it receives, so a smaller schema
+ * always produces a smaller answer. Any lever that shrinks the contract sent to
+ * the provider therefore appears to shrink the OUTPUT too — automatically, on
+ * every run, whatever model id is being simulated. That is a property of this
+ * file, not of any model.
+ *
+ * The output codebook is exactly that shape of lever, and against this provider
+ * the benchmark reported it saving 24.8%. Measured live it saves 8.0% on
+ * `gpt-4o` and COSTS 8.2% on `gpt-4o-mini`, because a real model decides how
+ * much to WRITE and a smaller model writes more when the field names carry less
+ * meaning. So: never take an output-token saving measured here as evidence of
+ * anything. Prove those with the paired A/B in `benchmarks/ab-live.ts`, and
+ * write tests for output-side effects against a provider that models the
+ * behaviour you are claiming — see `test/codebook-de-salida.test.ts`.
+ */
+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;
+    /** Characters per text event in generateStream (default 8). */
+    streamChunkChars?: number;
+}
+declare class MockProvider implements Provider {
+    readonly id = "mock";
+    private readonly options;
+    constructor(options?: MockProviderOptions);
+    generate(req: ProviderRequest, _options?: ProviderStreamOptions): Promise<ProviderResponse>;
+    /**
+     * Streaming variant of generate(): the same answer, cut into text events of
+     * `streamChunkChars` characters, then one `done` with the generate() response.
      */
-    silenciarAvisos?: boolean;
+    generateStream(req: ProviderRequest): AsyncGenerator<ProviderStreamEvent, void, undefined>;
 }
+declare function createMockProvider(options?: MockProviderOptions): Provider;
+
 /**
- * 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.
+ * 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.
+ *
+ * Models that predate structured outputs reject `response_format` with a 400. The
+ * adapter degrades for those: it repeats the request once with the schema carried
+ * in the prompt instead, remembers the model so later requests skip the rejected
+ * attempt, and reports `structuredNatively: false` so the savings report states
+ * `constraints.backend: "none"` rather than claiming a guarantee the provider
+ * never gave.
+ *
+ * Network calls use global `fetch` (Node >= 18) so there is no SDK dependency.
  */
-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>;
-    /** El interruptor, aceptando todavía el nombre viejo. */
-    private callado;
-    /** Un aviso por causa y por proceso, respetando el interruptor. */
-    private avisar;
+interface OpenAICompatibleOptions {
+    baseUrl: string;
+    apiKey?: string;
     /**
-     * THE CONTROL PLANE HAS BEEN UNREACHABLE FOR A WHILE.
-     *
-     * Polling is fail-open by design: a network outage must never take down the
-     * customer's production traffic. The trade-off is that an unreachable control
-     * plane has no visible symptom — the license keeps working and requests keep
-     * flowing while the revocation list quietly goes stale.
+     * Strip the `provider/` prefix from model ids before sending (`openai/gpt-4o-mini`
+     * → `gpt-4o-mini`).
      *
-     * So the warning goes to the console BY DEFAULT, not only through the optional
-     * `onEvent` observer. It fires on the third consecutive failure and then every
-     * twelfth: a lost request is normal, a week-long outage must keep reminding.
-     * Silence it with `silenceWarnings` if you have your own observability.
+     * Default (undefined): strip when `baseUrl` is OpenAI's own API or an Azure
+     * OpenAI endpoint, keep otherwise. OpenAI rejects a prefixed id with a 404
+     * ("model does not exist"), so the qualified ids the layer uses everywhere
+     * else — pricing, cache keys, the report — would break the very first call
+     * that reaches the provider. A gateway or a self-hosted server with a
+     * namespaced model name usually WANTS the prefix, so it is kept there. Set `true`/`false` to decide explicitly; an explicit value
+     * always wins.
      */
-    private avisarFalloDeRed;
-    /** 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). */
+    stripProviderPrefix?: boolean;
+    /** Extra headers (e.g. for a gateway). */
+    headers?: Record<string, string>;
+    /** Injectable fetch for testing. */
     fetchImpl?: typeof fetch;
-    /** Injectable clock. */
-    now?: () => number;
-    /** Whether this process is a CI/ephemeral runner (excluded from billable seats). */
-    ci?: boolean;
-    /**
-     * Which surface owns this process: the local gateway (`bvsala claude` and
-     * friends) or the in-process SDK. Sent with the version in the batch's
-     * `x-bvsala-version` header (`gateway/0.4.16`, `sdk/0.4.16`) so the control
-     * plane can tell a gateway that lacks a lever from an SDK that never had it.
-     * Defaults to `"sdk"`; the gateway sets `"gateway"`.
-     */
-    surface?: "gateway" | "sdk";
-    /**
-     * Se llama cuando el ingest rechaza la credencial (401/403). Existe para que un
-     * despliegue con observabilidad pueda ENTERARSE: el aviso por consola sirve en
-     * un portátil, pero en producción los `console.warn` no despiertan a nadie, y
-     * este fallo concreto es invisible por definición —deja de llegar uso, que es
-     * exactamente lo mismo que se ve cuando no hay tráfico—.
-     */
-    onAuthError?: (status: number) => void;
     /**
-     * Silence the console warnings. They are ON by default, exactly as in the
-     * revocation poller: metering is best-effort, so a broken ingest breaks
-     * nothing visible — usage simply stops arriving, silently, and the customer's
-     * dashboard stays empty forever.
+     * 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.
      */
-    silenceWarnings?: boolean;
+    requireUsage?: 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.
+ * ¿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 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 inflight;
-    /**
-     * CONSECUTIVE failed flushes. Warn on the third and then every twelfth: one
-     * lost batch is normal, a whole hour is not. Same cadence as the revocation
-     * poller on purpose — two different rhythms for the same class of failure
-     * only confuse whoever reads the logs.
-     */
-    private fallosSeguidos;
-    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.
-     *  Fire-and-forget: for a CLEAN shutdown that must not lose the last batch,
-     *  use `stopAndDrain` and await it. */
-    stop(): void;
-    /** Clean shutdown: stop the timer and DRAIN the buffer, awaiting each POST.
-     *  Unlike `stop()` (fire-and-forget), this resolves only once the final batch
-     *  has actually been sent, so a graceful exit doesn't lose the last session's
-     *  usage. Bounded, so an unreachable control plane can't block shutdown. */
-    stopAndDrain(maxIntentos?: number): Promise<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 hacerFlush;
+declare function isStrictCompatible(schema: unknown): boolean;
+/**
+ * Decides the id that travels on the wire. Explicit option wins; otherwise the
+ * endpoint decides: OpenAI/Azure get the bare id, everything else keeps what
+ * the caller wrote. Exported for the pipeline-level test that pins the README
+ * snippet; not part of the public API.
+ */
+declare function quitarPrefijoDeProveedor(model: string, explicito: boolean | undefined, baseUrl: string): string;
+declare class OpenAICompatibleProvider implements Provider {
+    readonly id: string;
+    private readonly opts;
+    private readonly fetchImpl;
+    /** Models of this endpoint already known to reject `response_format`. */
+    private readonly sinResponseFormat;
+    private streamOptionsRejected;
+    private readonly origen;
+    constructor(opts: OpenAICompatibleOptions);
+    generate(req: ProviderRequest, options?: ProviderStreamOptions): Promise<ProviderResponse>;
     /**
-     * THE INGEST HAS BEEN FAILING FOR A WHILE AND NOBODY NOTICED.
-     *
-     * Metering is best-effort by design — it must never take down the customer's
-     * request — and that turns every failure into SILENT data loss. Without this,
-     * the only symptom is an empty dashboard, which is indistinguishable from
-     * "you haven't sent anything yet": the symptom points the opposite way from
-     * the cause.
-     *
-     * Warns on the third consecutive failure and then every twelfth. Not the
-     * first — a lost request is normal — and not every one, which becomes noise.
+     * Streaming variant of generate() over Chat Completions. It always asks for
+     * the final usage chunk (`stream_options.include_usage`); an endpoint that
+     * rejects that option is retried once without it and remembered, and its
+     * streamed answers then report `usage.complete: false`. With `requireUsage`,
+     * that rejection throws instead. Requests with an output contract or a
+     * deferrable tier are not streamed: they are served by generate() and yielded
+     * as one text event.
      */
-    private avisarDeFallo;
-    private requeue;
-    private toWire;
+    generateStream(req: ProviderRequest, options?: ProviderStreamOptions): AsyncGenerator<ProviderStreamEvent, void, undefined>;
+    private enviar;
+    /** Translate a 2xx endpoint response into the provider-neutral shape. */
+    private leer;
 }
 
-/** 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.
+ * Anthropic Messages API adapter.
+ *
+ * Speaks `POST /v1/messages`: the system prompt travels in its own top-level
+ * `system` field (not as a message), tools are `{name, description,
+ * input_schema}` with no `function` wrapper, and prefix caching is requested
+ * with EXPLICIT `cache_control` breakpoints — Anthropic does not cache on its
+ * own. A cached read is billed at 0.1x the input rate, which is the largest
+ * single lever on the input side of a customer's bill.
+ *
+ * Network calls use global `fetch` (Node >= 18) so there is no SDK dependency.
  */
-interface SavingsLayerConfig {
+/** Render order of the request, which is also the order the cache prefix grows in. */
+interface AnthropicOptions {
+    apiKey?: string;
+    /** Defaults to the public API. Override for a gateway or a proxy. */
+    baseUrl?: string;
     /**
-     * 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.
+     * Strip the `provider/` prefix from model ids before sending
+     * (`anthropic/claude-sonnet-4-5` → `claude-sonnet-4-5`). Default (undefined):
+     * strip when talking to `api.anthropic.com`, which rejects a prefixed id;
+     * keep for a gateway or proxy, which usually routes on it. An explicit value
+     * always wins.
      */
-    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;
+    stripProviderPrefix?: boolean;
+    /** Wire version pinned in the `anthropic-version` header. */
+    apiVersion?: string;
+    /** Extra headers (e.g. for a gateway). */
+    headers?: Record<string, string>;
+    /** Injectable fetch for testing. */
+    fetchImpl?: typeof fetch;
     /**
-     * The numbers behind "compress only when it pays for itself" — in money, not
-     * in tokens.
-     *
-     * All optional, and the default never invents a saving: the layer compresses
-     * when the net token saving justifies it, and holds back when compressing
-     * would push the prompt below the provider's cacheable minimum — where fewer
-     * tokens can mean a larger bill. Declare {@link CompressionEconomics.prefix}
-     * with your own measurements to unlock the full decision in both directions.
+     * `max_tokens` is REQUIRED by this API — unlike the OpenAI shape, where it is
+     * optional. A request without one is a 400, so the adapter has to supply a
+     * value. It is deliberately generous: a low default would truncate answers
+     * and the truncation would look like a model failure rather than an adapter
+     * default.
      */
-    compressionEconomics?: CompressionEconomics;
-    retriever?: Retriever;
-    reranker?: Reranker;
+    defaultMaxOutputTokens?: number;
     /**
-     * Tuning for the model cascade (`savings.modelCascade`). All optional; the
-     * defaults measure and never spend.
+     * When true (recommended for measurement), a response whose `usage` block is
+     * missing its counters is treated as a HARD ERROR instead of being coerced to
+     * 0 tokens. An absent usage payload otherwise becomes `actual cost = 0` → a
+     * fabricated 100% saving.
      */
-    modelCascade?: ModelCascadeSettings;
+    requireUsage?: boolean;
     /**
-     * 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.
+     * How many `cache_control` breakpoints the adapter may spend.
      *
-     * Surrounding whitespace (the trailing newline of a file or mounted secret),
-     * wrapping quotes and a `Bearer ` prefix are stripped before verification, so
-     * a key read with `readFileSync` works as-is. Anything INSIDE the key is not
-     * touched: a key with a space in the middle is a broken key.
+     * The API caps them at 4 per request. The adapter never needs more than 2
+     * (end of system, end of the stable message prefix) and the cap is exposed so
+     * a gateway with a stricter limit can lower it. Raising it above 4 is
+     * pointless: the extra breakpoints are rejected by the API, not ignored.
      */
-    licenseKey?: string;
+    maxCacheBreakpoints?: number;
     /**
-     * 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.
+     * When true, requests that the pipeline decided to mark also carry the
+     * request-level `cache_control` (Anthropic's automatic caching): the provider
+     * places one extra breakpoint on the last cacheable block and moves it
+     * forward as the conversation grows, so the history beyond the declared
+     * stable prefix is cached incrementally too. It spends one of the four
+     * breakpoint slots and never fires when the economic gate declined to mark.
+     *
+     * Off by default, and deliberately so: the moving breakpoint writes the
+     * volatile tail of EVERY marked request at the 1.25x write premium. That
+     * pays for itself on conversational or agentic traffic — the next turn reads
+     * the whole history at 0.1x — and loses money on one-shot traffic where
+     * nothing ever reads it back. It is also rejected by legacy Bedrock
+     * deployments. Turn it on when your traffic is multi-turn.
      */
-    licensePublicKey?: string | LicenseKeyset;
+    automaticCache?: boolean;
     /**
-     * Pre-built license gate. **Ignored in the published npm package**, where a
-     * {@link licenseKey} verified against the embedded BiVelio public key is the
-     * only accepted license — passing a gate there logs a warning and changes
-     * nothing. It exists for builds from source (this repo's own tests and
-     * benchmarks), where it takes precedence over {@link licenseKey}.
+     * Whether a request carrying BOTH the caller's tools and an output contract
+     * may send `tool_choice: {type: "any"}`, which obliges the model to answer
+     * through SOME tool — its pick — instead of writing prose.
+     *
+     * Defaults to `true`, and the default is the point: without it this exact
+     * combination measured 62% MORE expensive than sending no layer at all, every
+     * single time, because prose forces a second full call to repair. Turning it
+     * off restores the old behaviour for a caller who genuinely needs a plain-text
+     * turn to be reachable while a contract is attached.
      */
-    licenseGate?: LicenseGate;
+    forceAnswerThroughTool?: boolean;
+}
+declare class AnthropicProvider implements Provider {
+    readonly id: string;
+    private readonly opts;
+    private readonly fetchImpl;
+    constructor(opts?: AnthropicOptions);
+    /** The id Anthropic's API sees: bare at `api.anthropic.com`, as written elsewhere. */
+    private modeloEnElCable;
+    generate(req: ProviderRequest, options?: ProviderStreamOptions): Promise<ProviderResponse>;
     /**
-     * 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.
+     * Streaming variant of generate() over the Messages API. The final usage is
+     * read from the closing `message_delta` event (the output counter in
+     * `message_start` is provisional); a stream without it reports
+     * `usage.complete: false`, and with `requireUsage` it throws instead. A body
+     * that ends before the provider signalled completion throws. Requests with an
+     * output contract or declared deferrable are served by generate() and yielded
+     * as one text event.
+     */
+    generateStream(req: ProviderRequest, options?: ProviderStreamOptions): AsyncGenerator<ProviderStreamEvent, void, undefined>;
+    private enviar;
+    private construirCuerpo;
+    private marcarCache;
+    private leer;
+}
+
+/**
+ * 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 — the stable handle for branching on the cause,
+     * since the message text is rewritten whenever it can be made clearer:
      *
-     * 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`.
+     * - `none`    — nothing was configured (no `licenseKey`, no gate).
+     * - `invalid` — a key was configured but does not verify.
+     * - `expired` / `grace` — it verifies, but the term is over.
+     * - `revoked` — cancelled by the control plane.
+     * - `stale`   — paid and current, but unconfirmed: a connectivity problem.
+     *
+     * The same value is repeated at the end of the message (`license status: X`)
+     * because an uncaught error prints nothing else.
      */
-    licenseServerUrl?: string;
+    readonly status?: string;
+    constructor(message: string, status?: string);
+}
+
+/** 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>;
     /**
-     * Steady-state ceiling between revocation polls, in seconds (default 900 = 15 min).
-     * The effective cadence tightens near license expiry and has a hard floor.
+     * 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.
      */
-    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;
-    };
+    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;
     /**
-     * Service-account key (`bvk_…`) — your machine credential. It does TWO things,
-     * and the second one is why a long-running deployment needs it:
-     *
-     *  1. **Licence renewal pickup.** Each billing period mints a NEW licence token;
-     *     the one you deployed expires at the end of the period (+ grace). With this
-     *     key the SDK fetches the renewed token from the control plane and swaps it
-     *     in without a restart. WITHOUT it there is no machine pickup, so somebody
-     *     must paste the new token by hand every cycle or the deployment stops with
-     *     `LicenseError` once the grace period ends — while the subscription is paid
-     *     and current. Disable with {@link licenseRefresh}`.enabled = false`.
-     *  2. **DETECTIVE usage metering.** 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. Disable with
-     *     {@link metering}`.enabled = false` (which does NOT disable renewal pickup).
-     *
-     * Both are best-effort and non-blocking: a slow or unreachable control plane
-     * never blocks or breaks `generate()`. Get the key from your dashboard.
+     * Why the key does not open, when it does not; `undefined` when it verified.
+     * Under `status() === "invalid"` it tells a key that does NOT EVEN HAVE THE
+     * SHAPE of a token (`"malformed"`: the `bvk_` pasted where the license goes,
+     * arbitrary text) from a well-formed one whose signature fails (the verifier's
+     * reason, e.g. `"bad signature"`). Both are `invalid` — the stable handle for
+     * branching does not change — but the advice given to the customer differs.
      */
-    serviceAccountKey?: string;
+    reason(): string | undefined;
+    /** 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, which `createSavingsLayer` wires up for you.
+ */
+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;
     /**
-     * Automatic licence-renewal pickup (on by default when {@link serviceAccountKey}
-     * and {@link licenseServerUrl} are both set).
-     *
-     * Turning it OFF means you take responsibility for deploying the renewed token
-     * each billing period; if nobody does, the SDK stops at the end of the grace
-     * period even though the subscription is paid.
+     * Silencia los avisos por consola. Por defecto están ENCENDIDOS, y ese defecto
+     * es la corrección: el sondeo es fail-open, así que un call-home roto no rompe
+     * nada visible — la lista de revocaciones simplemente se queda vieja, en
+     * silencio, durante días. Quien tenga observabilidad propia puede apagarlos;
+     * quien no la tenga, que es casi todo el mundo, se entera igual.
      */
-    licenseRefresh?: {
-        enabled?: boolean;
-        /** Check cadence in ms (default 3600000 = 1 h). */
-        intervalMs?: number;
-        /** How long before expiry to start looking, seconds (default 7 days). */
-        leadSeconds?: number;
-    };
+    silenceWarnings?: boolean;
     /**
-     * Usage-ingest URL. Defaults to `${licenseServerUrl}/api/metering/usage`. Set
-     * explicitly to point metering at a different host than the revocation poller.
+     * @deprecated Spanish name that leaked into the public options. Use
+     * {@link RevocationPollerOptions.silenceWarnings}. Honoured for one minor
+     * version so nobody gets their warnings back by surprise.
      */
-    meteringUrl?: string;
-    /** Injectable `fetch` for metering (defaults to {@link licenseFetch}, then global). */
-    meteringFetch?: typeof fetch;
-    /** DETECTIVE metering tuning (all optional). */
-    metering?: {
-        /**
-         * Off switch for USAGE REPORTING even when {@link serviceAccountKey} is set
-         * (default: on). It does NOT disable licence-renewal pickup — that has its
-         * own switch, {@link licenseRefresh}`.enabled`, because turning off telemetry
-         * must not silently stop your licence from renewing.
-         */
-        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;
-    };
+    silenciarAvisos?: boolean;
+}
+/**
+ * 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;
     /**
-     * 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.
+     * 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.
      */
-    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;
+    pollOnce(): Promise<void>;
+    /** El interruptor, aceptando todavía el nombre viejo. */
+    private callado;
+    /** Un aviso por causa y por proceso, respetando el interruptor. */
+    private avisar;
     /**
-     * Refuse the single repair retry when paying for it would push this request's
-     * cost above what it would have cost WITHOUT the layer. The invalid answer is
-     * then returned as-is with `constraints.structurallyValid: false`, plus a
-     * warning naming the three figures.
-     *
-     * OFF by default, and the default is a deliberate, measured choice rather than
-     * caution — read this before turning it on.
-     *
-     * The bound sounds narrow ("only the worst case") and is not. The baseline of
-     * a call that ran is reconstructed EXCLUDING the repair (see `estimateCost`:
-     * `actualInput - repairInput`), precisely so a retry cannot pay for itself in
-     * the report. That makes the threshold unreachable by construction: the repair
-     * only ever moves `actual`, never the baseline, so ANY repair breaches it
-     * whenever the layer's other books came out flat. On a request where nothing
-     * was compressed, cached or eliminated, `baseline === actual` exactly and the
-     * gate suppresses every repair, however cheap.
-     *
-     * So this is not "cap the tail", it is "stop repairing unless the layer has
-     * already banked more than the repair will cost". That is a real quality
-     * policy, not a rounding rule, and it is the caller's contract to decide on —
-     * hence opt-in.
+     * THE CONTROL PLANE HAS BEEN UNREACHABLE FOR A WHILE.
      *
-     * There is no threshold that fires on the pathological case and spares the
-     * flat one; they are the same arithmetic at different magnitudes. And there is
-     * a genuine argument on the other side: an answer that misses its contract is
-     * a MODEL failure, so the no-layer path would have had to pay for its own
-     * second call too — charging the whole retry against the layer compares one
-     * valid answer to one invalid answer.
+     * Polling is fail-open by design: a network outage must never take down the
+     * customer's production traffic. The trade-off is that an unreachable control
+     * plane has no visible symptom — the license keeps working and requests keep
+     * flowing while the revocation list quietly goes stale.
      *
-     * Turn it on when a hard per-request ceiling matters more than contract
-     * compliance — a batch backfill, a cost-capped tenant. Leave it off when the
-     * caller relies on the shape being right.
+     * So the warning goes to the console BY DEFAULT, not only through the optional
+     * `onEvent` observer. It fires on the third consecutive failure and then every
+     * twelfth: a lost request is normal, a week-long outage must keep reminding.
+     * Silence it with `silenceWarnings` if you have your own observability.
+     */
+    private avisarFalloDeRed;
+    /** 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;
+    /**
+     * Which surface owns this process: the local gateway (`bvsala claude` and
+     * friends) or the in-process SDK. Sent with the version in the batch's
+     * `x-bvsala-version` header (`gateway/0.4.16`, `sdk/0.4.16`) so the control
+     * plane can tell a gateway that lacks a lever from an SDK that never had it.
+     * Defaults to `"sdk"`; the gateway sets `"gateway"`.
      */
-    skipRepairAboveBaseline?: boolean;
+    surface?: "gateway" | "sdk";
     /**
-     * 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.
+     * Se llama cuando el ingest rechaza la credencial (401/403). Existe para que un
+     * despliegue con observabilidad pueda ENTERARSE: el aviso por consola sirve en
+     * un portátil, pero en producción los `console.warn` no despiertan a nadie, y
+     * este fallo concreto es invisible por definición —deja de llegar uso, que es
+     * exactamente lo mismo que se ve cuando no hay tráfico—.
      */
-    failOpen?: boolean;
+    onAuthError?: (status: number) => void;
     /**
-     * Silence BV-SALA's console warnings. They are ON by default, and they only
-     * ever report a condition whose symptom is otherwise invisible: a saving knob
-     * asked for but not wired up, usage that stops reaching the control plane, a
-     * revocation list going stale. Nothing here throws and nothing here changes
-     * what the layer does — turning it on only removes the console noise, so set
-     * it when you have your own observability. Applies to the pipeline, the usage
-     * emitter and the revocation poller alike.
+     * Silence the console warnings. They are ON by default, exactly as in the
+     * revocation poller: metering is best-effort, so a broken ingest breaks
+     * nothing visible — usage simply stops arriving, silently, and the customer's
+     * dashboard stays empty forever.
      */
     silenceWarnings?: boolean;
-    /** Injectable clock for deterministic tests. */
-    now?: () => number;
-    /** Injectable id generator for deterministic tests. */
-    generateId?: () => string;
 }
 /**
- * Tuning for the model cascade. Everything here is optional, and the defaults
- * cost nothing: with no settings at all, `modelCascade: "shadow"` measures what
- * it can measure for free and makes no extra provider call.
+ * Buffers usage records (counts, cost figures and opaque identifiers, never
+ * content) and flushes them 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.
  */
-interface ModelCascadeSettings {
+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 inflight;
     /**
-     * Your own strong → cheap pairs, replacing the built-in table.
-     *
-     * Keys and values are model ids WITHOUT a vendor prefix (`"gpt-4o"`, not
-     * `"openai/gpt-4o"`); the caller's prefix is carried over automatically, and a
-     * dated snapshot inherits from its base id. A pair whose economics do not work
-     * out at your prices is refused with a reason in the report — declaring it here
-     * does not override the arithmetic.
+     * CONSECUTIVE failed flushes. Warn on the third and then every twelfth: one
+     * lost batch is normal, a whole hour is not. Same cadence as the revocation
+     * poller on purpose — two different rhythms for the same class of failure
+     * only confuse whoever reads the logs.
      */
-    pairs?: Record<string, string>;
+    private fallosSeguidos;
+    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.
+     *  Fire-and-forget: for a CLEAN shutdown that must not lose the last batch,
+     *  use `stopAndDrain` and await it. */
+    stop(): void;
+    /** Clean shutdown: stop the timer and DRAIN the buffer, awaiting each POST.
+     *  Unlike `stop()` (fire-and-forget), this resolves only once the final batch
+     *  has actually been sent, so a graceful exit doesn't lose the last session's
+     *  usage. Bounded, so an unreachable control plane can't block shutdown. */
+    stopAndDrain(maxIntentos?: number): Promise<void>;
     /**
-     * How many requests of a workload are routed before the automatic shut-off
-     * judges the measured escalation rate (default 20).
-     *
-     * The rate is only observable on requests that were actually routed, so there
-     * is no way to know without spending a bounded amount to find out. Worst case
-     * (every one of them escalates) that exploration costs `n x r` requests'
-     * worth of extra spend, once per workload per process — with a ratio of 0.06
-     * and the default, about 1.2 requests.
+     * 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.
      */
-    exploration?: number;
+    flush(): Promise<void>;
+    private hacerFlush;
     /**
-     * PRICED OPT-IN, default 0 (off). Fraction of `"shadow"` requests on which the
-     * layer also calls the cheap model, purely to measure.
-     *
-     * Shadow mode is free precisely because it does not run the cheap model: it
-     * reports eligibility, the arithmetic, and what the swap would have been worth.
-     * What it cannot know for free is the one number that decides everything — how
-     * often the deterministic gate would have REJECTED the cheap answer. That
-     * answer does not exist until the cheap model writes one.
-     *
-     * So this buys it, and the price is exact: each sampled request costs one extra
-     * cheap call, i.e. `r` of what the request already cost — about 6% for
-     * gpt-4o → gpt-4o-mini. At `0.05` that is roughly 0.3% on top of your bill, and
-     * every sampled request reports its own `modelCascade.sampleCost`. It also
-     * DOUBLES that request's provider latency, because the extra call is sequential.
+     * THE INGEST HAS BEEN FAILING FOR A WHILE AND NOBODY NOTICED.
      *
-     * The sampled request's tokens count as spend and are held out of the baseline,
-     * exactly like the repair retry: measurement must never pay for itself.
+     * Metering is best-effort by design — it must never take down the customer's
+     * request — and that turns every failure into SILENT data loss. Without this,
+     * the only symptom is an empty dashboard, which is indistinguishable from
+     * "you haven't sent anything yet": the symptom points the opposite way from
+     * the cause.
      *
-     * Which requests get sampled is derived from the request's own cache key, so it
-     * is deterministic and stable — the same request is always sampled or always
-     * not, and no `Math.random` decides how your money is spent.
+     * Warns on the third consecutive failure and then every twelfth. Not the
+     * first — a lost request is normal — and not every one, which becomes noise.
      */
-    shadowSampleRate?: number;
+    private avisarDeFallo;
+    private requeue;
+    private toWire;
 }
-declare const DEFAULT_COST_MODEL: CostModel;
+
+/** 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>;
 
 /** Fully-resolved, non-optional dependency set the pipeline runs against. */
 interface ResolvedDeps {
@@ -3445,11 +4189,33 @@ declare const DEFAULT_MAX_STALENESS_SECONDS: number;
 /** The public handle returned by {@link createSavingsLayer}. */
 interface SavingsLayer {
     generate<T = unknown>(request: SavingsRequest): Promise<SavingsResult<T>>;
+    /**
+     * Same request as generate(), delivered as a stream of events.
+     *
+     * Iterate the returned object for `text` deltas as the provider writes them,
+     * then one `tool_call` event per requested tool call, then exactly one `done`
+     * event carrying the same SavingsResult that `result` resolves to. The report
+     * follows the same basis rules as generate(): the provider's final usage is
+     * read at the end of the stream, and a stream that ends without it is
+     * reported as `unmeasured`.
+     *
+     * Requests with an output contract (`response.schema`) or declared
+     * `deferrable`, and providers without streaming support, are produced exactly
+     * as generate() would and delivered in one piece; `report.streaming` says how
+     * the answer was delivered and why.
+     *
+     * Work starts immediately, so awaiting `result` without iterating is valid.
+     * Concurrent identical streamed requests each call the provider; a streamed
+     * request can still reuse an identical generate() call already in flight.
+     * Await `result` before calling close(), or its usage record may be lost.
+     */
+    generateStream<T = unknown>(request: SavingsRequest, options?: SavingsStreamOptions): SavingsStream<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.
+     * via `licenseServerUrl`) and abort any in-flight request, and settle every
+     * verification check still in flight (recorded as abandoned). 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;
 }
@@ -3475,4 +4241,386 @@ interface SavingsLayer {
  */
 declare function createSavingsLayer(config: Omit<SavingsLayerConfig, "tokenizer"> & Partial<Pick<SavingsLayerConfig, "tokenizer">>): SavingsLayer;
 
-export { type AnthropicOptions, AnthropicProvider, BV_SALA_VERSION, type BivelioHandoff, CATALOGO, COMPACT_ROWS_INSTRUCTION, type CacheOutcome, type CacheTier, type CachedAnswer, type CanonicalRequest, type ChatMessage, type CompactRowsDecodeOptions, type CompactRowsOptions, type CompactVerification, type CompressionEconomics, type CompressionPolicyInput, type CompressionRequest, type CompressionResult, type Compressor, type ConstraintBackend, type ConstraintBackendId, type ConstraintPlan, type ConversationState, type CostBasis, type CostModel, DEFAULT_COST_MODEL, DEFAULT_MAX_STALENESS_SECONDS, type DeferredExecutionReport, 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, InMemoryToolSetFreezer, type JsonSchema, LicenseError, type LicenseGate, type LicenseKeyShape, type LicenseKeyset, type LicenseStatus, type LicenseTokenPayload, type LocalClassifier, MODELOS_POR_CODIFICACION, MODELS_BY_ENCODING, type MemoryDelta, type MessageRole, MockProvider, type MockProviderOptions, type ModelCascadeMode, type ModelCascadeReport, type ModelCascadeSettings, type OpenAICompatibleOptions, OpenAICompatibleProvider, type OutputContract, PRECIOS_AL_DIA, type Policy, type ProtectedSpan, type Provider, type ProviderRequest, type ProviderResponse, type ProviderUsage, QUALITY_STATUSES, type QualityStatus, 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, type TokenEstimator, TokenizerRegistry, type ToolCallRequest, type ToolDescriptor, type ToolRisk, type ToolSelection, ToolSelector, type ToolSelectorOptions, type ToolSetFreezer, TraceCollector, type TraceEvent, UMBRAL_LOCAL, UsageEmitter, type UsageEmitterOptions, type ValidationError, type ValidationResult, adaptiveK, arithmeticResolver, buildExactKey, buildInflightKey, canonicalize, compactRowsSerializer, compresionFiel, computeNextDelay, cosine, createCompactRowsSerializer, createDefaultResolvers, createHandoff, createMockProvider, createSavingsLayer, csvSerializer, decodeCompactRows, dedupe, defaultTokenizerRegistry, deriveSeatId, deriveStatus, detectCi, embebedorLocal, emptyState, encodeCompactRows, evalArithmetic, evaluatePolicy, executeRetrievalPlan, gateFromKey, heuristicEstimator, isKeyset, isStrictCompatible, jsonCompactSerializer, keyTokensMatch, licenseKeyShape, liveGateFromKey, mergeDelta, modelFamilyOf, multisetEqual, negationCount, noopCompressor, normalizeLicenseKey, normalizeText, numericTokens, precioDeLista, projectContext, providerNativeBackend, quitarPrefijoDeProveedor, randomId, registerExactTokenizer, registrarTokenizadorExacto, renderState, resolveConstraintBackend, resolveDependencies, resolveLicense, sha256, shouldCompress, stableStringify, uniformColumns, validateAgainstSchema, vectorLocal, verifyCompactSignature, verifyLicenseToken, verifyRevocationList, withProtectedSpans, words };
+/**
+ * Rejection of `SavingsStream.result` when the stream was aborted before the
+ * provider finished its answer. Nothing was cached and no usage was recorded.
+ */
+declare class StreamAbortedError extends Error {
+    /**
+     * True when a request had already been sent to the provider: the provider may
+     * bill the tokens it generated before the cancel, and that cost is in no report.
+     */
+    readonly requestSent: boolean;
+    constructor(requestSent: boolean);
+}
+
+/**
+ * The parts of a SavingsReport the exporters read. A full SavingsReport
+ * satisfies it, and so does a stored copy without `traces`: the exporters never
+ * read `traces`, messages, answers or tool arguments.
+ */
+type SavingsReportForExport = Pick<SavingsReport, "requestId" | "model" | "calls" | "tokens" | "cache" | "cost"> & Partial<Pick<SavingsReport, "qualityStatus" | "modelCascade" | "latencyMs" | "streaming">>;
+/**
+ * One report and when its request was made: an ISO 8601 string, epoch
+ * milliseconds or a Date. A SavingsReport carries no timestamp of its own, so
+ * record `at` when the report comes back (`Date.now()` is fine).
+ */
+interface SavingsRecord {
+    at: string | number | Date;
+    report: SavingsReportForExport;
+}
+/** An attribute value these exporters write: never null, never an object. */
+type SpanAttributeValue = string | number | boolean | string[];
+/** The attributes these exporters write on a span. */
+type SavingsSpanAttributes = Record<string, SpanAttributeValue>;
+/**
+ * The part of an OpenTelemetry `Span` these exporters use. A `Span` from
+ * `@opentelemetry/api` satisfies it.
+ */
+interface SpanLike {
+    setAttributes(attributes: SavingsSpanAttributes): unknown;
+    setStatus?(status: {
+        code: number;
+        message?: string;
+    }): unknown;
+    end(): void;
+    isRecording?(): boolean;
+}
+/** The part of OpenTelemetry's `SpanOptions` these exporters pass. */
+interface SpanStartOptionsLike {
+    kind?: number;
+    attributes?: SavingsSpanAttributes;
+}
+/** The part of an OpenTelemetry `Tracer` these exporters use. */
+interface TracerLike {
+    startActiveSpan<T>(name: string, options: SpanStartOptionsLike, fn: (span: SpanLike) => T): T;
+}
+/** `trace` from @opentelemetry/api, or any TracerProvider. */
+interface TracerProviderLike {
+    getTracer(name: string, version?: string): TracerLike;
+}
+/** Options shared by every function that writes span attributes. */
+interface SavingsAttributeOptions {
+    /**
+     * ISO 4217 code of the report's money. Default "USD", the unit of the
+     * built-in price catalog. If you configured `costModels` in another unit, say
+     * so here: the report itself does not carry a currency.
+     */
+    currency?: string;
+    /**
+     * Mirror the figures as filterable Langfuse metadata
+     * (`langfuse.observation.metadata.bivelio_*`, string values). `cost` also sets
+     * `langfuse.observation.cost_details` to the report's actual cost, which
+     * Langfuse then prefers over its own estimate; Langfuse reads that figure as
+     * USD, so it is only written when `currency` is "USD". Both off by default.
+     */
+    langfuse?: {
+        metadata?: boolean;
+        cost?: boolean;
+    };
+    /**
+     * Mirror the figures in `_dd.ml_obs.metadata` for Datadog LLM Observability,
+     * as a JSON object under the key `bivelio`. Off by default: without it the
+     * `com.bivelio.*` attributes still arrive in Datadog as tags.
+     */
+    datadog?: {
+        metadata?: boolean;
+    };
+}
+/** Options for {@link recordSavingsOnSpan}. */
+interface SavingsSpanOptions extends SavingsAttributeOptions {
+    /**
+     * Also write the GenAI usage attributes and `gen_ai.response.model`.
+     * Default false: the span you pass may be an HTTP or job span, and marking it
+     * as an LLM call would misclassify it in tools that key on `gen_ai.*`.
+     */
+    genAi?: boolean;
+}
+/** Options for {@link instrumentSavingsLayer}. */
+interface SavingsTracingOptions extends SavingsAttributeOptions {
+    /** `trace` from @opentelemetry/api, a TracerProvider, or a Tracer. */
+    tracer: TracerLike | TracerProviderLike;
+    /**
+     * The `gen_ai.provider.name` value. Default: derived from the model id prefix
+     * (`openai/` gives "openai"); omitted when the model id has no prefix.
+     */
+    providerName?: string;
+}
+/**
+ * What to pass to a Langfuse generation's `update()`. `usageDetails` uses
+ * Langfuse's exclusive buckets: `input` does not include
+ * `cache_read_input_tokens`.
+ */
+interface LangfuseGenerationUpdate {
+    model: string;
+    usageDetails?: Record<string, number>;
+    costDetails?: Record<string, number>;
+    metadata: Record<string, string | number>;
+}
+/** Options for {@link toSavingsSeries}. */
+interface SavingsSeriesOptions {
+    /** Length of each period, in UTC. Default "day". */
+    granularity?: "hour" | "day";
+    /** ISO 4217 code of the reports' money. Default "USD". */
+    currency?: string;
+    /**
+     * Extra grouping labels for each record (team, feature, environment). Keys
+     * must not repeat a column of {@link SavingsSeriesRow}.
+     */
+    dimensions?: (record: SavingsRecord) => Record<string, string> | undefined;
+}
+/**
+ * One period, model and basis of the savings series. Money is in `currency`;
+ * each saving column holds money of its own basis only, so summing one column
+ * never mixes measured and estimated figures.
+ */
+type SavingsSeriesRow = {
+    /** Start of the period, inclusive (`YYYY-MM-DDTHH:mm:ssZ`, UTC). */
+    periodStart: string;
+    /** End of the period, exclusive (`YYYY-MM-DDTHH:mm:ssZ`, UTC). */
+    periodEnd: string;
+    /** The UTC date of `periodStart` (`YYYY-MM-DD`). */
+    date: string;
+    /** The model id as the report names it (the model that served the answer). */
+    model: string;
+    /** Where the money in this row comes from. `shadow` reports are never exported. */
+    basis: Exclude<CostBasis, "shadow">;
+    currency: string;
+    /** Reports in this row. */
+    requests: number;
+    /** LLM calls that reached the provider. */
+    providerCalls: number;
+    /** LLM calls that never executed. */
+    avoidedCalls: number;
+    /** Sum of `cost.baselineEstimate`; null when basis is "unmeasured". */
+    baselineCost: number | null;
+    /** Sum of `cost.actual`; null when basis is "unmeasured". */
+    actualCost: number | null;
+    /** Sum of `baselineEstimate - actual` on "measured" rows; null on every other row. */
+    measuredSavings: number | null;
+    /** Sum of `baselineEstimate - actual` on "reference" rows; null on every other row. */
+    referenceSavings: number | null;
+    /** Sum of `baselineEstimate - actual` on "estimated" rows; null on every other row. */
+    estimatedSavings: number | null;
+    /** Sum of `cost.eliminatedInputFloorCost`, a separate lane; null when no report carried it or basis is "unmeasured". */
+    eliminatedInputFloorCost: number | null;
+    baselineInputTokens: number;
+    actualInputTokens: number;
+    eliminatedInputTokens: number;
+    compressedInputTokens: number;
+    /** Sum of `tokens.providerCachedInput`; null when no report in the row carried it. */
+    providerCachedInputTokens: number | null;
+    baselineOutputTokens: number;
+    actualOutputTokens: number;
+    eliminatedOutputTokens: number;
+    /** The labels returned by `options.dimensions`, empty without it. */
+    dimensions: Readonly<Record<string, string>>;
+};
+/** Options for {@link toFocusRows}. */
+interface FocusExportOptions {
+    /**
+     * Your billing account id with the LLM provider (for example your OpenAI
+     * organization id), so these rows join the provider's own cost rows.
+     * Required: the SDK does not know it.
+     */
+    billingAccountId: string | ((record: SavingsRecord) => string);
+    /** Display name of that billing account, when the provider has one. */
+    billingAccountName?: string | ((record: SavingsRecord) => string | undefined);
+    /** The provider sub account (project, workspace) a record belongs to. */
+    subAccount?: (record: SavingsRecord) => {
+        id: string;
+        name: string;
+    } | undefined;
+    /**
+     * FOCUS `ServiceProviderName`. Default: derived from the model id prefix
+     * (`openai/` gives "OpenAI"). A model id whose provider cannot be derived
+     * throws, because FOCUS does not allow a placeholder here.
+     */
+    serviceProviderName?: string | ((model: string) => string);
+    /** FOCUS `InvoiceIssuerName` (a cloud marketplace or gateway that bills you). Default: the service provider. */
+    invoiceIssuerName?: string | ((model: string) => string);
+    /** FOCUS `HostProviderName` (the cloud hosting the model). Default: the service provider. */
+    hostProviderName?: string | ((model: string) => string);
+    /** FOCUS `ServiceName`. Default "BV-SALA savings ledger". */
+    serviceName?: string;
+    /**
+     * The billing period a charge period belongs to. Default: the calendar month
+     * in UTC. Set it if your provider invoices on another cycle.
+     */
+    billingPeriod?: (chargePeriodStart: Date) => {
+        start: Date;
+        end: Date;
+    };
+    /** Your own tags for a record, added to `Tags`. Keys starting with "bivelio/" are reserved. */
+    tags?: (record: SavingsRecord) => Record<string, string> | undefined;
+    /** Length of each charge period, in UTC. Default "day". */
+    granularity?: "hour" | "day";
+    /** ISO 4217 code of the reports' money. Default "USD". */
+    currency?: string;
+}
+/**
+ * A FOCUS 1.4 Cost and Usage row. Never a charge: every cost column is 0, so
+ * joining these rows with your provider's bill adds savings columns and never
+ * adds spend. The savings live in the `x_BiVelio*` columns, one per basis.
+ */
+type FocusRow = {
+    BilledCost: 0;
+    EffectiveCost: 0;
+    ListCost: 0;
+    ContractedCost: 0;
+    BillingCurrency: string;
+    BillingAccountId: string;
+    BillingAccountName: string | null;
+    BillingPeriodStart: string;
+    BillingPeriodEnd: string;
+    ChargePeriodStart: string;
+    ChargePeriodEnd: string;
+    ChargeCategory: "Adjustment";
+    ChargeClass: null;
+    ChargeDescription: string;
+    ChargeFrequency: "Usage-Based";
+    InvoiceIssuerName: string;
+    ServiceProviderName: string;
+    HostProviderName: string;
+    ServiceName: string;
+    ServiceCategory: "AI and Machine Learning";
+    ServiceSubcategory: "Generative AI";
+    PricingQuantity: null;
+    PricingUnit: null;
+    SubAccountId: string | null;
+    SubAccountName: string | null;
+    /** JSON object: `bivelio/basis`, `bivelio/model` and your own tags. */
+    Tags: string;
+    x_BiVelioBasis: Exclude<CostBasis, "shadow">;
+    x_BiVelioModelId: string;
+    x_BiVelioRequestCount: number;
+    x_BiVelioProviderCallCount: number;
+    x_BiVelioAvoidedCallCount: number;
+    x_BiVelioBaselineCost: number | null;
+    x_BiVelioActualCost: number | null;
+    x_BiVelioMeasuredSavings: number | null;
+    x_BiVelioReferenceSavings: number | null;
+    x_BiVelioEstimatedSavings: number | null;
+    x_BiVelioEliminatedInputFloorCost: number | null;
+    x_BiVelioBaselineInputTokens: number;
+    x_BiVelioActualInputTokens: number;
+    x_BiVelioEliminatedInputTokens: number;
+    x_BiVelioCompressedInputTokens: number;
+    x_BiVelioProviderCachedInputTokens: number | null;
+    x_BiVelioBaselineOutputTokens: number;
+    x_BiVelioActualOutputTokens: number;
+    x_BiVelioEliminatedOutputTokens: number;
+};
+/** A value {@link toCsv} can write. null and undefined become an empty field. */
+type CsvValue = string | number | boolean | null | undefined;
+
+/**
+ * The `com.bivelio.*` attributes for one report: the four ledgers, the basis,
+ * the cost and the ids. Money is in `options.currency` (default "USD"), and the
+ * money saved goes in one key per basis (`com.bivelio.cost.saved.measured`,
+ * `.reference`, `.estimated`), so a sum over one key never mixes measured and
+ * estimated money. `unmeasured` and `shadow` reports carry their counters and
+ * no money. Nothing here is content: only ids, counts, money and enums.
+ */
+declare function savingsSpanAttributes(report: SavingsReportForExport, options?: SavingsAttributeOptions): SavingsSpanAttributes;
+
+/**
+ * Write the savings figures of one report on a span you already have (for
+ * example `trace.getActiveSpan()`), as `com.bivelio.*` attributes. It does not
+ * end the span, never throws and does nothing on a span that is not recording.
+ *
+ * It writes no `gen_ai.*` attribute unless `genAi: true`, and then only the
+ * usage and `gen_ai.response.model`. Tools that key on `gen_ai.*` (Datadog LLM
+ * Observability drops spans without one) need the span from
+ * {@link instrumentSavingsLayer} instead.
+ */
+declare function recordSavingsOnSpan(span: SpanLike, report: SavingsReportForExport, options?: SavingsSpanOptions): void;
+/**
+ * Returns a SavingsLayer that opens one OpenTelemetry span per request, with
+ * the same results and the same errors: `generate()` resolves to the very
+ * result object, `generateStream()` returns the very stream.
+ *
+ * The span is named `chat {model}`, has kind CLIENT and is active while the
+ * request runs, so HTTP spans of your provider call nest under it. It carries
+ * the GenAI semantic conventions (as published in OpenTelemetry semantic
+ * conventions v1.41.1: operation, provider, request model and parameters,
+ * response model, usage) and the `com.bivelio.*` savings attributes of
+ * {@link savingsSpanAttributes}. An avoided call is still a span, with zero
+ * usage: no token was billed.
+ *
+ * Nothing is sent anywhere by this function: spans go to the exporters you
+ * configured in your OpenTelemetry SDK. No prompt, answer, tool argument or
+ * error message is written; a failed request records only `error.type`.
+ *
+ * Telemetry never changes a request: if the tracer fails, the request runs
+ * without a span. An invalid `tracer` throws a TypeError here, at startup.
+ */
+declare function instrumentSavingsLayer(layer: SavingsLayer, options: SavingsTracingOptions): SavingsLayer;
+
+/**
+ * The fields to pass to a Langfuse generation's `update()` when you trace with
+ * `@langfuse/tracing` by hand: `generation.update(toLangfuseGeneration(report))`.
+ *
+ * - `model` drops a known provider prefix (`openai/gpt-4o-mini` becomes
+ *   `gpt-4o-mini`), so Langfuse can match it to its price table.
+ * - `usageDetails` uses exclusive buckets: `input` excludes
+ *   `cache_read_input_tokens`. Cache writes are not broken out in the report, so
+ *   they stay inside `input`. Left out when the provider reported no usage.
+ * - `costDetails` is `{ total: report.cost.actual }` only with
+ *   `includeCost: true`, when `currency` is "USD" (Langfuse reads it as USD) and
+ *   the basis has money. It includes the cache-write premium; Langfuse then
+ *   uses it instead of its own estimate.
+ * - `metadata` holds the savings figures (`bivelio_*`), one saving key per basis.
+ */
+declare function toLangfuseGeneration(report: SavingsReportForExport, options?: {
+    currency?: string;
+    includeCost?: boolean;
+}): LangfuseGenerationUpdate;
+
+/**
+ * Savings per period (UTC day by default), model, basis and your own
+ * dimensions: the series to load as a business metric or telemetry stream in a
+ * FinOps tool. Same aggregation as {@link toFocusRows}.
+ *
+ * Each saving column holds money of its own basis only, and `shadow` reports
+ * are left out. For a metric that should match your provider invoice, use
+ * `measuredSavings` and `referenceSavings`; `estimatedSavings` has its own
+ * column on purpose. Throws a TypeError on an invalid `at`, currency or
+ * dimension.
+ */
+declare function toSavingsSeries(records: Iterable<SavingsRecord>, options?: SavingsSeriesOptions): SavingsSeriesRow[];
+
+/**
+ * Your SavingsReports as FOCUS 1.4 Cost and Usage rows, one per charge period
+ * (UTC day by default), model, basis, billing account, sub account and tag set.
+ *
+ * Every cost column (`BilledCost`, `EffectiveCost`, `ListCost`,
+ * `ContractedCost`) is 0 by design: your provider's bill already carries the
+ * spend, so joining these rows with it adds savings and never adds cost.
+ * `ChargeCategory` is "Adjustment" and nothing here invents a SKU or a price.
+ *
+ * The savings are in custom columns, one per basis: `x_BiVelioMeasuredSavings`,
+ * `x_BiVelioReferenceSavings` and `x_BiVelioEstimatedSavings`; only the column
+ * of the row's basis holds a value. `unmeasured` rows carry counts and null
+ * money, and `shadow` reports are left out. `Tags` carries `bivelio/basis` and
+ * `bivelio/model` plus your own tags.
+ *
+ * Throws a TypeError on an invalid `at`, currency or option, on a user tag
+ * starting with "bivelio/", and when the provider of a model cannot be
+ * derived and `serviceProviderName` is not given.
+ */
+declare function toFocusRows(records: Iterable<SavingsRecord>, options: FocusExportOptions): FocusRow[];
+
+/**
+ * Rows to RFC 4180 CSV: CRLF line breaks, quoted fields where needed, null as
+ * an empty field and numbers as plain decimals (no exponent, at most 10
+ * decimal places). The header is `options.columns` or the keys of the rows in
+ * first-seen order. `toCsv([])` is an empty string; with `columns` it is the
+ * header alone. A value that is not a string, number, boolean or null throws a
+ * TypeError: map each row to flat columns first.
+ */
+declare function toCsv(rows: readonly Readonly<Record<string, CsvValue>>[], options?: {
+    columns?: readonly string[];
+}): string;
+
+export { type AnswerSource, type AnthropicOptions, AnthropicProvider, BV_SALA_VERSION, type BivelioHandoff, CATALOGO, COMPACT_ROWS_INSTRUCTION, type CacheOutcome, type CacheTier, type CacheWriteReport, type CachedAnswer, type CanonicalRequest, type ChatMessage, type CompactRowsDecodeOptions, type CompactRowsOptions, type CompactVerification, type CompressionEconomics, type CompressionPolicyInput, type CompressionRequest, type CompressionResult, type Compressor, type ConstraintBackend, type ConstraintBackendId, type ConstraintPlan, type ConversationState, type CostBasis, type CostModel, type CsvValue, DEFAULT_COST_MODEL, DEFAULT_MAX_STALENESS_SECONDS, type DeferredExecutionReport, type DeterministicResolver, EMBEDDED_PUBLIC_KEY, type EmbeddingFn, type EvidenceDoc, type ExactCache, ExactTokenizer, type ExecutionClass, ExecutionRouter, type FocusExportOptions, type FocusRow, type FormatChoice, FormatSelector, type FormatSelectorOptions, type HandoffFact, HeuristicEstimator, InMemoryExactCache, InMemorySemanticCache, InMemoryToolSetFreezer, type JsonSchema, type LangfuseGenerationUpdate, LicenseError, type LicenseGate, type LicenseKeyShape, type LicenseKeyset, type LicenseStatus, type LicenseTokenPayload, type LocalClassifier, MODELOS_POR_CODIFICACION, MODELS_BY_ENCODING, type MemoryDelta, type MessageRole, MockProvider, type MockProviderOptions, type ModelCascadeMode, type ModelCascadeReport, type ModelCascadeSettings, type OpenAICompatibleOptions, OpenAICompatibleProvider, type OutputContract, PRECIOS_AL_DIA, type Policy, type PriceLeverSaving, type PriceLeverSettings, type ProtectedSpan, type Provider, type ProviderRequest, type ProviderResponse, type ProviderStreamEvent, type ProviderStreamOptions, type ProviderUsage, QUALITY_STATUSES, type QualityCacheMatch, type QualityCascadeCheck, type QualityLedger, type QualityRepairCheck, type QualitySchemaCheck, type QualityStatus, type QualityTruncationCheck, REFERENCE_MAX_AGE_MS, REFERENCE_MESSAGE_ALLOWANCE, REFERENCE_OUTPUT_SHARE, type ReferenceCredit, type ReferenceRejection, 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 SavingsAdapterLevers, type SavingsAdapterOptions, type SavingsAttributeOptions, type SavingsCallOptions, type SavingsLayer, type SavingsLayerConfig, SavingsLedger, type SavingsRecord, type SavingsReport, type SavingsReportForExport, type SavingsRequest, type SavingsResult, type SavingsSeriesOptions, type SavingsSeriesRow, type SavingsSpanAttributes, type SavingsSpanOptions, type SavingsStream, type SavingsStreamEvent, type SavingsStreamOptions, type SavingsToggles, type SavingsTracingOptions, SchemaRegistry, type SemanticCacheOptions, type SemanticHit, type SemanticRecord, type SemanticVerifier, type SerializationFormat, type Serializer, Singleflight, type SpanAttributeValue, type SpanLike, type SpanStartOptionsLike, StreamAbortedError, type StreamingReport, type TokenEstimator, TokenizerRegistry, type ToolCallRequest, type ToolDescriptor, type ToolRisk, type ToolSelection, ToolSelector, type ToolSelectorOptions, type ToolSetFreezer, TraceCollector, type TraceEvent, type TracerLike, type TracerProviderLike, UMBRAL_LOCAL, UsageEmitter, type UsageEmitterOptions, type ValidationError, type ValidationResult, type VerificationCheck, type VerificationExclusion, type VerificationOutcome, type VerificationReport, type VerificationSettings, type VerificationSide, type VerificationStratum, adaptiveK, arithmeticResolver, buildExactKey, buildInflightKey, canonicalize, compactRowsSerializer, compresionFiel, computeNextDelay, cosine, createCompactRowsSerializer, createDefaultResolvers, createHandoff, createMockProvider, createSavingsLayer, csvSerializer, decodeCompactRows, dedupe, defaultTokenizerRegistry, deriveSeatId, deriveStatus, detectCi, embebedorLocal, emptyState, encodeCompactRows, evalArithmetic, evaluatePolicy, executeRetrievalPlan, gateFromKey, heuristicEstimator, instrumentSavingsLayer, isKeyset, isStrictCompatible, jsonCompactSerializer, keyTokensMatch, licenseKeyShape, liveGateFromKey, mergeDelta, modelFamilyOf, multisetEqual, negationCount, noopCompressor, normalizeLicenseKey, normalizeText, numericTokens, precioDeLista, projectContext, providerNativeBackend, quitarPrefijoDeProveedor, randomId, recordSavingsOnSpan, registerExactTokenizer, registrarTokenizadorExacto, renderState, resolveConstraintBackend, resolveDependencies, resolveLicense, savingsSpanAttributes, sha256, shouldCompress, stableStringify, toCsv, toFocusRows, toLangfuseGeneration, toSavingsSeries, uniformColumns, validateAgainstSchema, vectorLocal, verifyCompactSignature, verifyLicenseToken, verifyRevocationList, withProtectedSpans, words };