@bivelio/savings-layer 0.2.2 → 0.3.1

package/dist/index.d.ts

@@ -1,13 +1,3 @@
-/**
- * Environment-agnostic UUID generation.
- * ---------------------------------------------------------------------------
- * Trace IDs only need to be unique, not cryptographically unpredictable. We
- * prefer the platform `crypto.randomUUID` (present in modern Node, browsers,
- * Deno and edge runtimes) and fall back to a v4-shaped id when it is absent, so
- * BV-SALA runs everywhere without a `node:crypto` import that breaks bundlers.
- */
-declare function randomId(): string;
-
 /**
  * The four-ledger savings accounting.
  *
@@ -75,6 +65,39 @@ declare class SavingsLedger {
      * cost; work the layer does to fix its own output has no place in it.
      */
     repairInput: number;
+    /**
+     * INPUT of the schema-on-demand discovery probe. Held apart exactly like
+     * {@link repairInput}, and for the same reason.
+     *
+     * The layer ADDS this call; the naive path would never make it. Letting its
+     * tokens into the reconstructed baseline would make the probe pay for itself,
+     * and a request that cost MORE than going without the layer would publish a
+     * positive saving. It still counts in full towards `actualInput` — that is
+     * money genuinely spent — it just cannot inflate what that is compared against.
+     */
+    discoveryInput: number;
+    /** OUTPUT of the discovery probe. Our cost, kept out of the baseline. */
+    discoveryOutput: number;
+    /**
+     * Already-priced cost of a call the model cascade made to a cheaper model
+     * whose answer was NOT served. Added to `actual`, never to the baseline.
+     */
+    extraCostUsd: number;
+    /** Input tokens of that call. Published by the pipeline, not priced here. */
+    cascadeInput: number;
+    /** Output tokens of that call. Published by the pipeline, not priced here. */
+    cascadeOutput: number;
+    /**
+     * Record a call to the cheap model that did not produce the served answer:
+     * the one discarded on an escalation, or a shadow-mode sample.
+     *
+     * The caller raises `actualLlm`, because the call happened and the report owes
+     * the reader that count.
+     */
+    cascadeAttempt(usage: {
+        inputTokens: number;
+        outputTokens: number;
+    }, cheapPrice: CostModel): void;
     /**
      * Lo que de verdad hizo la compresión, para publicarlo en
      * `SavingsReport.compression`. El campo estaba declarado en el contrato y no lo
@@ -113,6 +136,53 @@ declare class SavingsLedger {
     };
 }
 
+/**
+ * LIST PRICES PER MODEL.
+ *
+ * The layer reports savings in money, and money needs a price. This is the
+ * built-in catalogue of published list prices, so the dollar figures mean
+ * something without any configuration.
+ *
+ * ⚠️ A WRONG PRICE HERE IS WORSE THAN NO CATALOGUE. A model that is ABSENT falls
+ * back to the illustrative default AND warns, so the customer knows that column
+ * is not their invoice. A model that is PRESENT with the wrong price silences
+ * that warning and hands over a confident, wrong number. So only models whose
+ * published price is known with certainty belong here, and {@link PRECIOS_AL_DIA}
+ * records when they were last checked.
+ *
+ * Prices are USD per 1,000 tokens — the unit of `CostModel` — even though
+ * providers publish per million: 1M to 1K is a division by a thousand.
+ *
+ * `costModels` on the layer config ALWAYS wins over this. A customer with volume
+ * discounts, negotiated rates or a different region sets their own and this
+ * catalogue stays out of the way.
+ */
+/** When these prices were last checked against the providers' public rates. */
+declare const PRECIOS_AL_DIA = "2026-08-13";
+/**
+ * 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.
+ */
+declare const CATALOGO: Readonly<Record<string, CostModel>>;
+/**
+ * The list price for a model, or `undefined` when it is not in the catalogue.
+ *
+ * @param model the id as the caller passes it, with or without a vendor prefix.
+ */
+declare function precioDeLista(model: string): CostModel | undefined;
+
+/**
+ * Environment-agnostic UUID generation.
+ * ---------------------------------------------------------------------------
+ * Trace IDs only need to be unique, not cryptographically unpredictable. We
+ * prefer the platform `crypto.randomUUID` (present in modern Node, browsers,
+ * Deno and edge runtimes) and fall back to a v4-shaped id when it is absent, so
+ * BV-SALA runs everywhere without a `node:crypto` import that breaks bundlers.
+ */
+declare function randomId(): string;
+
 /**
  * Core contracts for BV-SALA (bivelio-savings-layer).
  *
@@ -126,8 +196,8 @@ declare class SavingsLedger {
  *  - provider_cached_tokens tokens still in the prompt that the provider may
  *                           bill or process differently (prefix/KV caching).
  *
- * A cache hit eliminates a whole call. TOON re-encodes a structured payload.
- * LLMLingua removes redundant words. A provider prefix cache makes tokens
+ * A cache hit eliminates a whole call. A compact encoding re-encodes a structured payload.
+ * A context compressor removes redundant words. A provider prefix cache makes tokens
  * cheaper without removing them. Mixing these produces misleading metrics.
  */
 /** Roles understood by the provider-neutral chat interface. */
@@ -187,7 +257,7 @@ interface OutputContract {
     version?: string;
 }
 /** Serialization formats the format-selector can choose between. */
-type SerializationFormat = "json-compact" | "toon" | "csv";
+type SerializationFormat = "json-compact" | "compact-rows" | "csv";
 interface RetrievalOptions {
     mode: "off" | "auto" | "single" | "multi";
     maxRounds?: number;
@@ -201,6 +271,338 @@ interface SavingsToggles {
     singleflight?: boolean;
     deterministicResolvers?: boolean;
     router?: boolean;
+    /**
+     * OPT-IN, AND WHETHER IT SAVES OR COSTS DEPENDS ON THE MODEL. Read this whole
+     * entry before switching it on.
+     *
+     * It sends the provider a compacted form of your output contract — short
+     * property keys, short enum codes — and expands the reply back to YOUR shape
+     * before it is validated, cached or returned. What you receive in `data`,
+     * `text` and `rendered` is identical either way, and the layer proves that
+     * round trip is exact before it applies anything.
+     *
+     * WHAT LIVE A/Bs MEASURED, same triage contract, same prompts, 8 paired
+     * repetitions each. Input fell identically on both models, from 184 to 158
+     * tokens — that part is deterministic, it is the smaller contract. Output did
+     * not: `gpt-4o` wrote 3 tokens FEWER and the request came out 8.0% cheaper,
+     * while `gpt-4o-mini` wrote 16 tokens MORE and the request came out 8.2% more
+     * expensive. Short field names appear to give a smaller model less to go on,
+     * so it fills in more, and output is billed around 4x input on that family.
+     *
+     * SO THE LEVER APPLIES ONLY WHERE THAT DELTA HAS BEEN MEASURED. It cannot be
+     * read off a schema — the schema was identical in both runs — so the layer
+     * does not guess. It uses, in order: the delta you measured and passed in
+     * {@link SavingsToggles.outputCodebookMeasuredOutputDeltaTokens}; the same
+     * delta remembered from an earlier request for that contract and model; the
+     * delta BiVelio has published for that model. With none of those it skips and
+     * says so in `report.traces`, including the exact break-even for your contract
+     * so you know what a measurement would have to beat.
+     */
+    outputCodebook?: boolean;
+    /**
+     * The output-token delta you MEASURED for the contract on this request, with
+     * {@link SavingsToggles.outputCodebook} on versus off, against the model you
+     * are sending it to. POSITIVE means the compact contract made the model write
+     * FEWER output tokens; negative means it wrote more.
+     *
+     * This is what lets the layer apply the codebook on a model it has not
+     * published a figure for, and it overrides the published one when it has —
+     * your traffic beats our benchmark. A negative delta switches the lever off
+     * for that model: the input win is capped by the size of your schema while the
+     * output loss grows with the answer, so no schema is large enough to buy it
+     * back.
+     *
+     * It belongs to ONE contract against ONE model, which is why it travels on the
+     * request rather than the layer config: a delta measured on your triage
+     * contract says nothing about your extraction contract, and one measured on
+     * `gpt-4o` says nothing about `gpt-4o-mini` — those two came out with opposite
+     * signs. Measure it with a paired A/B over the same prompts, which is what
+     * `benchmarks/ab-live.ts` in this package does, and measure it again when you
+     * change model, contract or prompt.
+     */
+    outputCodebookMeasuredOutputDeltaTokens?: number;
+    /**
+     * OPT-IN, and it changes the latency contract: where it applies, one request
+     * becomes TWO provider calls, one after the other.
+     *
+     * With a large tool catalogue the full JSON schema of every candidate travels
+     * on every request, even though the model will use one tool or none. With this
+     * on, the layer may first send lightweight descriptors (name + one line, no
+     * `parameters`), read which tools the model asks for, and only then send those
+     * full schemas.
+     *
+     * It is applied only when the token arithmetic for THIS request, priced with
+     * your cost model, says the second call pays for itself with margin — so a
+     * small catalogue silently keeps the single-call path.
+     *
+     * THE MARGIN IS NOT A GUARANTEE THAT EVERY REQUEST GETS CHEAPER. When the
+     * model names no tool in the first call, the request still goes out with every
+     * schema and the first call is pure added cost: that request costs MORE, and
+     * the report says so (`cost.netSavings` goes negative). The margin required is
+     * exactly the cost of that outcome, so the pattern breaks even while it
+     * happens on at most one request in two. If your traffic asks for a tool less
+     * often than that — a chat assistant with a big catalogue answers most turns
+     * directly — leave this off. Only an A/B against your own traffic settles it.
+     *
+     * IT ALSO GIVES UP THE PROVIDER'S PREFIX CACHE, on every request, not just the
+     * ones where it applies. Tools render FIRST in a provider request, and with
+     * this on, which schemas travel is decided by a probe whose answer is not
+     * deterministic — so the front of the prompt varies between requests that
+     * would otherwise share a cacheable prefix. Marking one would pay the write
+     * premium (1.25x on Anthropic) for a prefix that cannot hit. If your prompts
+     * carry a long fixed system header and your traffic repeats it, that discount
+     * is very likely worth more than this lever: measure both before choosing.
+     * `report.traces` says which one is off and why.
+     *
+     * When the second call happened, `report.calls.actualLlm` is 2. The extra
+     * call's tokens are counted as spend and never credited to your baseline.
+     * Write and destructive tools always travel with their full schema, so no
+     * action can be lost to a discovery step.
+     */
+    toolDiscovery?: boolean;
+    /**
+     * Send the request to a CHEAPER model of the same family, check the answer
+     * with a deterministic gate, and fall back to the model you asked for only
+     * when that gate rejects it. Defaults to `"off"`.
+     *
+     * It is the only lever here that changes the price of the WHOLE bill — input
+     * and output — instead of one axis of it. Read {@link ModelCascadeMode} for
+     * what each mode does, and {@link ModelCascadeReport} for the failure this
+     * cannot protect you from. Start at `"shadow"`.
+     */
+    modelCascade?: ModelCascadeMode;
+    /**
+     * Declare that this answer is NOT needed immediately, so the layer may ask the
+     * provider for a cheaper, slower processing tier. Defaults to `false`.
+     *
+     * YOU DECLARE IT; THE LAYER NEVER GUESSES. Whether a request can wait is a
+     * property of your business, not of the text: the same prompt is deferrable in
+     * a nightly enrichment job and not deferrable behind a user's cursor. There is
+     * no heuristic that can tell those apart, so there is no default that could be
+     * right.
+     *
+     * IT CHANGES YOUR LATENCY, AND THAT IS THE WHOLE POINT. Where a cheaper tier
+     * exists it is slower and its latency is variable, so a request on a
+     * user-facing path must not carry this. `report.deferred.latency` states what
+     * the provider documents. Nothing else about the request changes: same model,
+     * same prompt, same sampling controls, so the answer is the answer you would
+     * have got.
+     *
+     * WHAT IT IS WORTH IS READ BACK, NEVER ASSUMED. A provider short on capacity
+     * may serve the standard tier and bill the standard rate without saying so in
+     * the response body's shape. The layer therefore reads the tier the provider
+     * reports having SERVED and credits only that — see
+     * {@link DeferredExecutionReport}. On a provider with no cheaper synchronous
+     * tier the request is sent unchanged and the report says so.
+     */
+    deferrable?: boolean;
+}
+/**
+ * What asking for a cheaper processing tier actually got you on this request.
+ *
+ * Present whenever `savings.deferrable` is `true`, INCLUDING when it earned
+ * nothing — "we asked and did not get it" is the answer you need most often, and
+ * it is the one a report that only spoke on success would hide.
+ *
+ * ⚠️ THE FAILURE THIS EXISTS TO PREVENT. Asking for a discounted tier is not
+ * getting one. Providers document that a request may be served at a different
+ * tier from the one it asked for and billed at that tier's rate, and the
+ * downgrade is silent: the answer comes back looking exactly the same. A layer
+ * that credited the tier it REQUESTED would publish a discount your invoice does
+ * not carry, on every request the provider quietly downgraded.
+ *
+ * So {@link servedTier} is read from the provider's response and it is the only
+ * thing {@link credited} is allowed to depend on. When the provider reports no
+ * tier at all, nothing is credited: an absent value means "cannot be known", not
+ * "standard".
+ */
+interface DeferredExecutionReport {
+    /** The tier the layer asked the provider for, absent if it asked for none. */
+    requestedTier?: string;
+    /**
+     * The tier the provider reports having SERVED, exactly as it named it. Absent
+     * when the provider reported none.
+     */
+    servedTier?: string;
+    /**
+     * Whether the served tier bills BELOW the standard rate card, which is the
+     * only condition under which a discount is claimed here.
+     */
+    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}.
+     */
+    discountRate?: 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.
+     *
+     * ⚠️ `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}.
+     */
+    estimatedTierSaving?: number;
+    /**
+     * 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
+     * nothing (3) and is not provider caching (4). It changes the PRICE of the
+     * tokens, exactly as the model cascade does, and there is no ledger for that.
+     *
+     * `cost.netSavings` therefore does not move: it is a ratio of baseline to
+     * actual priced from a SINGLE rate card, and a discount that scales both sides
+     * cannot change it. Folding this in would require a baseline priced from the
+     * other card — a request nobody ran.
+     */
+    creditedLedger: "none";
+    /**
+     * What the provider documents about this tier's latency, in one sentence.
+     *
+     * It is a quotation of what is published, not an estimate. Where a provider
+     * commits to no latency figure, this says so rather than inventing one.
+     */
+    latency: string;
+    /** Why it did what it did, in one sentence. Never empty. */
+    reason: string;
+}
+/**
+ * How much authority the model cascade has over your requests.
+ *
+ * - `"off"`     (default) it neither measures nor decides. Nothing changes.
+ * - `"shadow"`  it MEASURES and reports, and never changes your model. Every
+ *               request still goes to the model you asked for. The report gains
+ *               a {@link ModelCascadeReport} saying which cheaper model was
+ *               eligible, what the arithmetic says about it, and what the swap
+ *               would have been worth on THIS request. Costs nothing extra
+ *               unless you also set `modelCascade.shadowSampleRate` on the
+ *               layer, which is a separate, priced opt-in.
+ * - `"on"`      it routes for real. Opt-in, never silent: the report always
+ *               declares the model that served the answer, and a request served
+ *               by a cheaper model is labelled `bounded_degradation`.
+ *
+ * `"on"` carries a gate: when a workload's measured escalation rate reaches the
+ * break-even, the cascade turns ITSELF off for that workload and says so. That
+ * gate protects your BILL. It cannot protect quality — see
+ * {@link ModelCascadeReport}.
+ */
+type ModelCascadeMode = "off" | "shadow" | "on";
+/**
+ * What the model cascade did, or would have done, on this request.
+ *
+ * Present whenever `savings.modelCascade` is not `"off"` — including when the
+ * request was not eligible, because "we did not route this and here is why" is
+ * the answer you need most often.
+ *
+ * ⚠️ READ THIS BEFORE YOU TURN THE CASCADE ON.
+ *
+ * The gate that decides whether a cheap answer is good enough is DETERMINISTIC,
+ * which is what makes the saving real: an LLM judge would cost the very money
+ * this lever exists to save. But a deterministic gate measures FORM, not
+ * MEANING. An answer with impeccable JSON and the wrong content passes it.
+ *
+ * That failure is invisible by construction. It lowers the escalation rate, it
+ * raises the reported saving, and the automatic shut-off never fires — because
+ * the shut-off watches the escalation rate, and the escalation rate looks
+ * excellent. It has the same signature as success, and it surfaces weeks later
+ * as customer complaints.
+ *
+ * So: `escalationRate` is a MONEY figure. Its complement is not a quality score,
+ * and this report deliberately does not publish one. If you need evidence about
+ * quality, run an A/B on your own traffic. `divergedOnSample` (from shadow
+ * sampling) is a hint that something is wrong, never proof that nothing is.
+ */
+interface ModelCascadeReport {
+    mode: ModelCascadeMode;
+    /** The model the caller asked for. */
+    requestedModel: string;
+    /**
+     * The model that actually produced the answer. In `"shadow"` this always
+     * equals {@link requestedModel}; in `"on"` it is the cheap model when its
+     * answer was accepted, and the requested one when it was escalated.
+     */
+    servedModel: string;
+    /** The cheaper model this request was (or would have been) routed to. */
+    candidateModel?: string;
+    /** Whether the cascade was allowed to consider this request at all. */
+    eligible: boolean;
+    /** Why it did what it did, in one sentence. Never empty. */
+    reason: string;
+    /** What the deterministic gate is able to check here. */
+    verifier: "none" | "structural" | "value-constrained";
+    /**
+     * cost(cheap) / cost(strong), worst case over any token mix. The saving on
+     * routed traffic is `1 - r - escalationRate`.
+     */
+    costRatio?: number;
+    /** Escalation rate above which routing costs MORE than not routing (`1 - r`). */
+    breakEvenEscalationRate?: number;
+    /** Escalation rate above which routing stops hitting the target capture. */
+    targetEscalationRate?: number;
+    /** Opaque, stable id of the workload these rates are measured over. */
+    workload?: string;
+    /** Measured escalation rate for this workload, or absent if nothing measured yet. */
+    escalationRate?: number;
+    /** How many requests that rate is measured over. */
+    escalationSamples?: number;
+    /** Whether THIS request was escalated to the requested model after the gate rejected it. */
+    escalated?: boolean;
+    /**
+     * What swapping the model was worth on this request, in your currency unit.
+     *
+     * A COUNTERFACTUAL: the strong model was not run, so this is priced from the
+     * measured token counts at both list prices. It is deliberately NOT part of
+     * `cost.netSavings` — that number stays a comparison at a single price, and
+     * this one would inflate it with a call nobody made. Negative on an escalated
+     * request, which is exactly what an escalation costs you.
+     */
+    estimatedSwapSaving?: number;
+    /**
+     * Which of the four ledgers this credits: none, and that is the honest answer.
+     * Routing avoids no call (ledger 1), removes no tokens (2), re-encodes nothing
+     * (3) and is not provider caching (4). It changes the PRICE of the tokens, and
+     * there is no ledger for that.
+     */
+    creditedLedger: "none";
+    /**
+     * Input tokens of the cheap call whose answer was NOT served — the attempt
+     * discarded on an escalation, or a shadow-mode sample.
+     *
+     * They are deliberately absent from `tokens.actualInput`: another model billed
+     * them at another price, and that block is priced with a single cost model, so
+     * folding them in would price them wrong. Their MONEY is in `cost.actual`.
+     * These two fields are what closes the gap, so
+     * `tokens.actualInput * inputPer1k + tokens.actualOutput * outputPer1k` plus
+     * the cheap model's price applied here accounts for `cost.actual` in full.
+     */
+    cascadeInputTokens?: number;
+    /** Output tokens of that same unserved call. See {@link cascadeInputTokens}. */
+    cascadeOutputTokens?: number;
+    /** Whether this shadow request paid for an extra cheap call to measure the rate. */
+    sampled?: boolean;
+    /** What that extra call cost, in your currency unit. */
+    sampleCost?: number;
+    /**
+     * On a sampled request where BOTH answers satisfied the contract: whether they
+     * disagree on a hard value (a number, a boolean, a short code).
+     *
+     * A hint about false valids, and nothing more. It only covers sampled traffic,
+     * disagreement is not proof the cheap answer is the wrong one, and agreement
+     * is not proof either answer is right.
+     */
+    divergedOnSample?: boolean;
 }
 interface RequestContext {
     tenantId?: string;
@@ -266,8 +668,61 @@ interface SavingsResult<T = unknown> {
     report: SavingsReport;
 }
 type CacheOutcome = "miss" | "exact" | "semantic" | "singleflight" | "deterministic";
+/**
+ * The quality claims this layer is able to DEMONSTRATE for the answer it served.
+ *
+ * A boolean cannot carry this. `constraints.structurallyValid` puts an answer
+ * computed by a deterministic resolver — exact by construction — in the same box
+ * as one the model wrote while nobody checked anything but its shape. Those two
+ * are the difference between "this is the result" and "this is what the model
+ * said", and a product that claims savings owes the reader that distinction.
+ *
+ * THE RULE BEHIND THIS VOCABULARY: never report "no loss" on the strength of
+ * cosine similarity, BLEU, ROUGE or another model's judgement. Those scores stay
+ * high while a figure, a negation or an exception quietly disappears — precisely
+ * the fields that decide a legal or financial document. A claim of equivalence
+ * rests on a deterministic gate, or it is not made.
+ *
+ * - `exact`            exact by construction: a deterministic resolver computed
+ *                      the answer, or an exact-cache hit replayed the answer
+ *                      already produced for this very same request.
+ * - `task_equivalent`  not byte-identical, but it cleared a deterministic gate
+ *                      before being served — numbers and dates as a multiset,
+ *                      negation parity and a key-entity floor all had to agree,
+ *                      on top of any similarity score.
+ * - `not_verified`     the model was called and nothing beyond the shape of the
+ *                      answer was checked. The honest default, and the common case.
+ * - `bounded_degradation`
+ *                      the answer was produced by a model CHEAPER than the one
+ *                      you asked for, and it cleared the deterministic gate for
+ *                      its output contract before being served. The bound is
+ *                      exactly what that gate checks — shape, and whatever value
+ *                      constraints your contract declares. NOT meaning: a
+ *                      well-formed answer with wrong content earns this label
+ *                      too. See {@link ModelCascadeReport}.
+ * - `rejected`         what was served does not satisfy its output contract, and
+ *                      a repair either failed or would have been a wasted call.
+ *                      The answer is still returned: this is the layer's verdict
+ *                      on it, not a refusal to hand it over.
+ *
+ * The list is deliberately short. A status nobody produces is a promise the
+ * reader cannot check, so levers that do not exist yet bring their own status
+ * the day they can demonstrate it. Read this as an OPEN set — keep a default
+ * branch, exactly as with a licence status.
+ */
+declare const QUALITY_STATUSES: readonly ["exact", "task_equivalent", "not_verified", "bounded_degradation", "rejected"];
+type QualityStatus = (typeof QUALITY_STATUSES)[number];
 interface SavingsReport {
     requestId: string;
+    /**
+     * The model that produced this answer.
+     *
+     * Equal to the model you asked for, EXCEPT when `savings.modelCascade` is
+     * `"on"` and a cheaper model's answer cleared the deterministic gate — then
+     * this names the cheaper model, because that is what ran and what your bill
+     * will show. `report.modelCascade.requestedModel` always holds what you asked
+     * for. Changing your model is never silent.
+     */
     model: string;
     calls: {
         baselineLlm: number;
@@ -328,8 +783,38 @@ interface SavingsReport {
          */
         structurallyValid?: boolean;
     };
+    /**
+     * How the served answer earned its place, in one word. Optional and additive:
+     * a report built by an older SDK simply does not carry it, so treat an absent
+     * value as "unknown", never as a pass.
+     *
+     * It only ever DEGRADES what the rest of the report claims. An answer that
+     * fails its output contract is `rejected` however it was produced — a resolver
+     * that computes the right number for the wrong contract does not get to keep
+     * the `exact` label.
+     */
+    qualityStatus?: QualityStatus;
+    /**
+     * What the model cascade did, or would have done. Present whenever
+     * `savings.modelCascade` is not `"off"`. Read its docstring before turning the
+     * cascade on: it documents a failure mode no gate in this layer can catch.
+     */
+    modelCascade?: ModelCascadeReport;
+    /**
+     * What asking for a cheaper processing tier got you. Present whenever
+     * `savings.deferrable` is `true`, including when it got you nothing.
+     */
+    deferred?: DeferredExecutionReport;
     quality: {
         taskPassed?: boolean;
+        /**
+         * Similarity score of the retained answer, when one was computed.
+         *
+         * A number here is NOT evidence of equivalence: see {@link QualityStatus}.
+         * Cosine (and BLEU, ROUGE, or an LLM judge) can sit above 0.95 across a
+         * changed figure or a dropped negation, so it informs a decision — it never
+         * licenses a "no loss" claim.
+         */
         semanticScore?: number;
         freshnessPassed?: boolean;
     };
@@ -364,10 +849,14 @@ interface SavingsReport {
  * Structural license gate the pipeline consults before enabling a managed
  * feature (semantic cache, learned thresholds, long-context compression, …).
  *
- * It is intentionally a bare shape — the SDK never imports the license package.
- * `@bivelio/license-client`'s `createLicenseGate()` returns a compatible object,
- * but any implementation of this interface works. When no gate is configured the
- * pipeline behaves as an ungated self-managed deployment (backwards compatible).
+ * It is intentionally a bare shape, so any object with these methods works and
+ * the SDK never has to import a licensing package.
+ *
+ * There is no ungated mode: with no gate and no `licenseKey`, `generate()`
+ * throws {@link LicenseError} on entry. In the published npm package an injected
+ * gate is ignored entirely — a `licenseKey` verified against BiVelio's embedded
+ * public key is the only accepted license there, and this interface is what that
+ * key is turned into internally.
  */
 interface LicenseGate {
     isEntitled(feature: string): boolean;
@@ -410,7 +899,7 @@ interface TraceEvent {
  * be re-explained in free-form natural language at every hop. BV-SALA replaces
  * that with a compact, typed handoff object. Each consumer receives a
  * projection of the state, not the whole conversation. The serializer then
- * decides whether to send it as compact JSON or TOON.
+ * decides whether to send it as compact JSON or compact rows.
  */
 interface HandoffFact {
     id: string;
@@ -460,7 +949,7 @@ interface TokenEstimator {
      * El heurístico vale para RANKEAR formatos candidatos (le basta con acertar el
      * orden). No vale para restar tokens entre formatos distintos: cobra cada
      * símbolo suelto como un token entero, así que infla el JSON denso en símbolos
-     * mucho más que el TOON, y la diferencia se acredita como ahorro inexistente.
+     * mucho más que el the compact encoder, y la diferencia se acredita como ahorro inexistente.
      */
     readonly exact: boolean;
     /** Estimate the number of tokens in a string. */
@@ -517,18 +1006,9 @@ declare const defaultTokenizerRegistry: TokenizerRegistry;
  * contamos aquí. Con el estimador heurístico esos dos sumandos vienen de reglas
  * distintas, y la diferencia NO es ruido: el heurístico cobra cada símbolo suelto
  * como un token entero, así que infla el JSON (40% de símbolos) mucho más que el
- * TOON (16%). Medido en el escenario de la tabla: publicaba un baseline 3,68x el
- * naive real, o sea un +47,4% de ahorro donde el proveedor midió −49,6%.
- *
- * Cómo se instala. `gpt-tokenizer` son ~53 MB desempaquetados, así que NO es
- * dependencia dura: imponérsela a todo el que instale el SDK, cuando la mayoría
- * no necesita contabilidad medida, sería abusivo. Es peerDependency opcional:
- *
- *   pnpm add gpt-tokenizer
- *
- * Sin ella el layer sigue funcionando con el heurístico, y el `basis` de cada
- * informe lo dice — "estimated" en vez de "measured". Esa es la diferencia
- * importante: el producto no deja de funcionar, deja de AFIRMAR de más.
+ * 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.
  */
 
 /** Lo que necesitamos de gpt-tokenizer. Tipado aquí para no depender de sus tipos. */
@@ -588,7 +1068,11 @@ interface CanonicalRequest {
     model: string;
     modelFamily: string;
     messages: ChatMessage[];
-    /** Whitespace/case-normalized text of the user-visible turns. */
+    /**
+     * Text of the user-visible turns, normalized so that trivial near-duplicates
+     * collide: Unicode form, case, whitespace, typographic marks and sentence
+     * punctuation. Numbers, dates, quantities and negations are preserved exactly.
+     */
     normalizedText: string;
     systemPromptHash: string;
     toolsetHash: string;
@@ -616,10 +1100,26 @@ interface CanonicalRequest {
     tokenizer: string | undefined;
     original: SavingsRequest;
 }
+/**
+ * Normalized form of a turn's text, as it enters the cache key.
+ *
+ * Folded away: Unicode form, case, whitespace, typographic marks, Latin
+ * diacritics and sentence punctuation. Preserved exactly: numbers, decimal and
+ * thousands separators, times, dates, units, negations, math operators and any
+ * combining mark outside the Latin alphabet.
+ */
 declare function normalizeText(text: string): string;
 declare function sha256(input: string): string;
 /** Stable JSON stringify with sorted keys so hashes are order-independent. */
 declare function stableStringify(value: unknown): string;
+/**
+ * The version-and-size-independent family of a model id.
+ *
+ * Exported because the cache key is now built for the model that will actually
+ * ANSWER, which is not always the one the caller named. Deriving the family a
+ * second time somewhere else is how two rulers start to disagree.
+ */
+declare function modelFamilyOf(model: string): string;
 declare function canonicalize(request: SavingsRequest): CanonicalRequest;
 
 /**
@@ -629,8 +1129,21 @@ declare function canonicalize(request: SavingsRequest): CanonicalRequest;
  * 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 buildExactKey(c: CanonicalRequest): string;
+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
@@ -641,8 +1154,37 @@ declare function buildExactKey(c: CanonicalRequest): string;
  * 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): string;
+declare function buildInflightKey(c: CanonicalRequest, opciones?: {
+    servedModel?: string;
+    deferrable?: boolean;
+}): string;
 
 /**
  * Policy engine: risk and freshness.
@@ -821,7 +1363,7 @@ declare function cosine(a: number[], b: number[]): number;
 declare function keyTokensMatch(a: string, b: string): boolean;
 /**
  * In-memory reference implementation. A production build would back this with a
- * real vector store (pgvector, Qdrant, etc.) and metadata filters pushed down
+ * real vector store and metadata filters pushed down
  * to the store. The verification logic — the part that makes it *safe* — stays
  * identical regardless of the backend.
  */
@@ -936,6 +1478,17 @@ interface ToolSelection {
     tools: ToolDescriptor[];
     droppedIds: string[];
     reason: string;
+    /**
+     * Whether the SET of tools is determined by something stable across requests,
+     * rather than by this request's text.
+     *
+     * It is not cosmetic. Tools render FIRST in a provider request (tools ->
+     * system -> messages), so a tool set that changes with the question moves the
+     * very front of the prompt and invalidates the whole prefix cache behind it.
+     * A caller whose prompt caching silently never hits, on traffic with tools, is
+     * usually looking at this.
+     */
+    setIsStable: boolean;
 }
 interface ToolSelectorOptions {
     /** Max tools to include (schema-token budget guard). */
@@ -1072,7 +1625,7 @@ interface Serializer {
     encode(value: unknown): string;
     /**
      * The instruction text a model needs to interpret this format. For JSON this
-     * is empty; for TOON/CSV it is the per-request cost that must be amortized
+     * is empty; for row/CSV it is the per-request cost that must be amortized
      * before the format is worthwhile.
      */
     instruction(value: unknown): string;
@@ -1090,60 +1643,60 @@ interface Serializer {
  * Compact JSON: the lossless baseline every other format is measured against.
  * No indentation, no incidental whitespace. This is frequently the *winner* for
  * deeply nested or non-uniform data, which is exactly why it is the baseline and
- * TOON is only ever a challenger.
+ * The compact encoder is only ever a challenger.
  */
 declare const jsonCompactSerializer: Serializer;
 
 /**
- * TOON (Token-Oriented Object Notation) adapter.
+ * Compact row encoder.
  *
- * TOON's strength is UNIFORM ARRAYS OF FLAT OBJECTS: it declares the column
+ * 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 TOON can be *larger* than compact JSON — so this is only ever a candidate
+ * 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<->TOON
+ * It emits a well-defined subset and ships a matching decoder so the JSON<->rows
  * round-trip is deterministic and testable.
  */
-interface ToonOptions {
+interface CompactRowsOptions {
     /** Field delimiter within tabular/inline rows. */
     delimiter?: "," | "\t";
     /** Indentation unit. */
     indent?: string;
 }
-declare function encodeToon(value: unknown, options?: ToonOptions): 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 TOON. Kept short on purpose — this text
- * is the per-request overhead the selector must amortize before TOON wins.
+ * 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 TOON_INSTRUCTION: string;
-declare function createToonSerializer(options?: ToonOptions): Serializer;
-declare const toonSerializer: Serializer;
+declare const COMPACT_ROWS_INSTRUCTION: string;
+declare function createCompactRowsSerializer(options?: CompactRowsOptions): Serializer;
+declare const compactRowsSerializer: Serializer;
 
 /**
- * TOON decoder for the subset emitted by {@link encodeToon}.
+ * 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 TOON for, and makes the
- * JSON<->TOON round-trip deterministic and testable. List-form arrays of nested
+ * 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
- * TOON for those, since JSON wins there anyway).
+ * it for those, since JSON wins there anyway).
  */
-interface ToonDecodeOptions {
+interface CompactRowsDecodeOptions {
     delimiter?: "," | "\t";
     indent?: string;
 }
-declare function decodeToon(text: string, options?: ToonDecodeOptions): unknown;
+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 TOON on pure tables, but it
+ * 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;
@@ -1151,7 +1704,7 @@ declare const csvSerializer: Serializer;
 /**
  * Format selector.
  *
- * TOON is a candidate, never a default. For each request we count, USING THE
+ * It is a candidate, never a default. For each request we count, USING THE
  * DESTINATION MODEL'S TOKENIZER:
  *
  *   tokens(encoded payload) + tokens(instruction to understand it)
@@ -1170,7 +1723,7 @@ interface FormatSelectorOptions {
     minimumSavingsRatio?: number;
     /**
      * Per-(model,format) quality penalty in tokens. Encodes "this model is worse
-     * at reading TOON" as an additive cost, learned from production traces.
+     * at reading the compact rows" as an additive cost, learned from production traces.
      */
     qualityPenalty?: (model: string, format: SerializationFormat) => number;
 }
@@ -1274,7 +1827,7 @@ declare function resolveConstraintBackend(model: string, schema: JsonSchema, bac
 declare function providerNativeBackend(isSupported?: (model: string, schema: JsonSchema) => boolean): ConstraintBackend;
 
 /**
- * Context compression (LLMLingua-style), as an OPTIONAL sidecar.
+ * Context compression, as an OPTIONAL sidecar.
  *
  * Two rules make this safe and worthwhile:
  *
@@ -1343,9 +1896,60 @@ declare function shouldCompress(input: CompressionPolicyInput): {
  * worse than no compressor at all.
  */
 declare function withProtectedSpans(inner: Compressor): Compressor;
-/** No-op compressor: the safe default until a real LLMLingua sidecar is wired in. */
+/** No-op compressor: the safe default until a real compressor sidecar is wired in. */
 declare const noopCompressor: Compressor;
 
+/** What the layer needs to know about a provider's prefix cache to price a decision. */
+interface CacheTier {
+    /**
+     * Minimum prompt tokens before the provider caches the prefix at all;
+     * `null` means it never does.
+     *
+     * The built-in tiers assume 1024 for every model. That is an ASSUMPTION, not a
+     * verified figure: real minimums differ per model and family. Set your model's
+     * own minimum here when you know it.
+     */
+    minimumCacheTokens: number | null;
+    /** Price of a cache-read token as a fraction of a normal one (e.g. 0.5, 0.1). */
+    cacheReadMultiplier: number;
+    /** Surcharge for WRITING the cache the first time; some providers bill above 1. */
+    cacheWriteMultiplier: number;
+}
+
+/** Tunes when compression is worth its money. Every field is optional. */
+interface CompressionEconomics {
+    /**
+     * The provider's prefix-cache tier. Derived from the request's model when
+     * omitted; set it to state your model's real cache minimum and multipliers.
+     */
+    cacheTier?: CacheTier;
+    /**
+     * YOUR MEASURED prefix-cache economics: how many prompt tokens are a stable
+     * prefix across requests, and how often that prefix arrives already warm
+     * (`report.tokens.providerCachedInput` is the numerator for the rate).
+     *
+     * Both are required together — a hit rate over an unknown prefix says nothing
+     * about how much money is at stake. Declaring them unlocks the full decision,
+     * including knowingly trading the prefix cache for a smaller prompt when that
+     * is the cheaper side. Left out, the layer refuses to compress a prompt out of
+     * a cacheable tier rather than assume a rate on your behalf.
+     */
+    prefix?: {
+        stableTokens: number;
+        hitRate: number;
+    };
+    /**
+     * What running the compressor costs, in equivalent tokens (default 0, which
+     * fits a local deterministic compressor). A compressor that is itself another
+     * model call is not free, and unaccounted spend shows up nowhere else.
+     */
+    compressorCostTokens?: number;
+    /** Do not compress contexts below this many tokens (default 2000). */
+    minimumContextTokens?: number;
+    /** Do not apply a compression that saves fewer net tokens than this (default 200). */
+    minimumNetTokens?: number;
+}
+
 /**
  * Provider-neutral generation interface. Every provider (OpenAI-compatible,
  * Anthropic-compatible, Google-compatible, self-hosted) is adapted to this
@@ -1362,17 +1966,65 @@ interface ProviderRequest {
     seed?: number;
     /** Backend id selected by the constraints layer, for observability. */
     constraintBackend?: string;
+    /**
+     * How many LEADING messages form the stable, cacheable prefix — the part the
+     * provider may reuse across requests. `undefined` claims nothing and adapters
+     * mark no cache breakpoint.
+     *
+     * Adapters that need EXPLICIT breakpoints (Anthropic) place them at this
+     * boundary; adapters that cache automatically (OpenAI) may ignore it. The
+     * count is a claim about byte-for-byte stability, so a caller that rewrites an
+     * earlier turn must lower it.
+     */
+    stablePrefixMessages?: number;
+    /**
+     * Routing hint so requests sharing a prefix land on the same cache shard
+     * (OpenAI `prompt_cache_key`). It is a hint, never an identity: it must not
+     * carry tenant or user data, because it does not isolate anything.
+     */
+    promptCacheKey?: string;
+    /**
+     * The caller declares this answer is not needed immediately, so the adapter
+     * may ask for a cheaper, slower processing tier.
+     *
+     * It is DECLARED, never inferred: whether a request can wait is a property of
+     * the business, not of the text. An adapter whose provider has no cheaper
+     * synchronous tier leaves the request unchanged.
+     *
+     * Asking is not getting. A provider may serve a downgraded tier and bill it at
+     * the standard rate, so the discount is only ever read back from
+     * {@link ProviderResponse.servedServiceTier}.
+     */
+    deferrable?: boolean;
 }
 interface ProviderUsage {
     inputTokens: number;
     outputTokens: number;
     /** Provider-reported prefix/KV-cached input tokens (ledger 4), if any. */
     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).
+     *
+     * 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
+     * is the price paid to obtain it. Folding the two together would report a
+     * bill INCREASE as a saving.
+     */
+    cacheWriteInputTokens?: number;
 }
 interface ProviderResponse {
     text: string;
     usage: ProviderUsage;
-    /** Whether the provider enforced the schema natively. */
+    /**
+     * Whether the provider enforced the schema natively.
+     *
+     * An explicit `false` is a claim about the guarantee that was obtained, not a
+     * detail: the pipeline reads it and reports `constraints.backend: "none"`, so
+     * an adapter that had to ask for JSON in the prompt (for instance because the
+     * model rejects `response_format`) must set it. Leaving it undefined asserts
+     * nothing and keeps the planned backend.
+     */
     structuredNatively?: boolean;
     /**
      * Por qué paró de generar el modelo. `"length"` significa que se quedó sin
@@ -1395,6 +2047,30 @@ interface ProviderResponse {
      * all the way to the caller.
      */
     toolCalls?: ToolCallRequest[];
+    /**
+     * The processing tier the provider reports having SERVED this request, exactly
+     * as it named it (OpenAI `service_tier`, Anthropic `usage.service_tier`).
+     *
+     * This is the only field a discount may be credited from, and the reason is
+     * that it is not always what was asked for: a provider short on capacity may
+     * serve the standard tier and bill the standard rate while the request said
+     * otherwise. Crediting the REQUESTED tier would publish a saving the invoice
+     * does not carry.
+     *
+     * Absent means the provider said nothing, which is NOT the same as "standard":
+     * it means the tier cannot be known, so nothing is credited.
+     */
+    servedServiceTier?: string;
+    /**
+     * The processing tier this adapter ASKED the provider for, when it asked for
+     * one. Absent means it asked for nothing — which is the honest answer for a
+     * provider that has no cheaper synchronous tier to ask for.
+     *
+     * Reported by the adapter rather than assumed by the caller: only the adapter
+     * knows its provider's vocabulary, and a caller that hardcoded a tier name
+     * would be describing a request some other adapter never made.
+     */
+    requestedServiceTier?: string;
     raw?: unknown;
 }
 interface Provider {
@@ -1410,6 +2086,22 @@ interface Provider {
  * 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. */
@@ -1436,6 +2128,13 @@ declare function createMockProvider(options?: MockProviderOptions): Provider;
  * 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.
  */
 interface OpenAICompatibleOptions {
@@ -1475,8 +2174,74 @@ 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;
+}
+
+/**
+ * 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.
+ */
+/** 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;
+    /** 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;
+    /**
+     * `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.
+     */
+    defaultMaxOutputTokens?: number;
+    /**
+     * 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.
+     */
+    requireUsage?: boolean;
+    /**
+     * How many `cache_control` breakpoints the adapter may spend.
+     *
+     * 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.
+     */
+    maxCacheBreakpoints?: number;
+}
+declare class AnthropicProvider implements Provider {
+    readonly id: string;
+    private readonly opts;
+    private readonly fetchImpl;
+    constructor(opts?: AnthropicOptions);
+    generate(req: ProviderRequest): Promise<ProviderResponse>;
+    private construirCuerpo;
+    private marcarCache;
+    /** Traduce una respuesta 2xx a la forma neutra del layer. */
+    private leer;
 }
 
 /**
@@ -1500,7 +2265,19 @@ declare class TraceCollector {
  * unlicensed, rather than silently serving requests for free.
  */
 declare class LicenseError extends Error {
-    /** Resolved license status, when known: expired | invalid | revoked | none. */
+    /**
+     * Resolved license status — the stable handle for branching on the cause,
+     * since the message text is rewritten whenever it can be made clearer:
+     *
+     * - `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.
+     */
     readonly status?: string;
     constructor(message: string, status?: string);
 }
@@ -1509,10 +2286,10 @@ declare class LicenseError extends Error {
  * Offline license verification for the paid SDK.
  *
  * A license is a compact signed token `base64url(header).base64url(payload).
- * base64url(sig)` (the exact format the licensing service mints in
- * `@bivelio/license-client`'s `signLicense`). We verify the Ed25519 signature
- * against BiVelio's public key, decode the payload, and apply the same grace
- * policy the license-client uses. Verification is **browser-safe**: it uses
+ * 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
@@ -1610,8 +2387,8 @@ declare function deriveStatus(payload: {
     grace_days: number;
 }, nowSeconds: number, revoked?: ReadonlySet<string>): LicenseStatus;
 /**
- * Verify + apply the grace policy → a resolved status. Mirrors
- * `@bivelio/license-client`'s `LicenseClient.resolve`. Bad signature / malformed
+ * 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}.
  */
 declare function resolveLicense(token: string, publicKey: string | LicenseKeyset, opts?: {
@@ -1874,6 +2651,13 @@ interface UsageEmitterOptions {
      * 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.
+     */
+    silenceWarnings?: boolean;
 }
 /**
  * Buffers counts-only usage and flushes it to the control plane. DETECTIVE
@@ -1893,6 +2677,13 @@ declare class UsageEmitter {
     private ci;
     private timer;
     private flushing;
+    /**
+     * 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). */
@@ -1908,6 +2699,19 @@ declare class UsageEmitter {
      * since retrying a rejected payload would loop forever.
      */
     flush(): Promise<void>;
+    /**
+     * 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.
+     */
+    private avisarDeFallo;
     private requeue;
     private toWire;
 }
@@ -1953,8 +2757,24 @@ interface SavingsLayerConfig {
     schemaRegistry?: SchemaRegistry;
     constraintBackends?: ConstraintBackend[];
     compressor?: Compressor;
+    /**
+     * 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.
+     */
+    compressionEconomics?: CompressionEconomics;
     retriever?: Retriever;
     reranker?: Reranker;
+    /**
+     * Tuning for the model cascade (`savings.modelCascade`). All optional; the
+     * defaults measure and never spend.
+     */
+    modelCascade?: ModelCascadeSettings;
     /**
      * Signed BiVelio license token (from your paid subscription). This is the
      * primary way to license the SDK: `createSavingsLayer` verifies it offline
@@ -1972,10 +2792,11 @@ interface SavingsLayerConfig {
      */
     licensePublicKey?: string | LicenseKeyset;
     /**
-     * Pre-built license gate. Usually you pass {@link licenseKey} instead and let
-     * the SDK construct this. Advanced/self-managed callers can inject their own
-     * gate (e.g. `@bivelio/license-client`'s `createLicenseGate()`). When both are
-     * given, `licenseGate` wins.
+     * 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;
     /**
@@ -2106,11 +2927,73 @@ interface SavingsLayerConfig {
      * 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;
     /** 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.
+ */
+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;
+}
 declare const DEFAULT_COST_MODEL: CostModel;
 
 /** Fully-resolved, non-optional dependency set the pipeline runs against. */
@@ -2147,12 +3030,18 @@ interface SavingsLayer {
  * Create a savings layer. The only hard requirement is a `provider`; a default
  * heuristic tokenizer and in-memory implementations of every other component
  * are wired automatically. Replace any of them for production (Redis exact
- * cache, pgvector/Qdrant semantic cache, a real tokenizer, an LLMLingua sidecar,
+ * cache, a vector-backed semantic cache, a real tokenizer, a compressor sidecar,
  * XGrammar/llguidance backends, etc.).
  *
+ * A `licenseKey` is not optional in practice: `generate()` is fail-closed and
+ * throws {@link LicenseError} without one, so it belongs in the smallest example
+ * there is.
+ *
  * @example
- * const layer = createSavingsLayer({ provider: createMockProvider() });
- * const { data, report } = await layer.generate({
+ * // `licenseKey` is the signed token from savings.bivelio.com/dashboard/install,
+ * // read from wherever you keep secrets (BIVELIO_LICENSE_KEY in the README).
+ * const layer = createSavingsLayer({ provider, licenseKey });
+ * const { text, report } = await layer.generate({
  *   model: "openai/gpt-4o-mini",
  *   messages: [{ role: "user", content: "What is 2 + 2 * 3?" }],
  * });
@@ -2185,6 +3074,7 @@ declare function createSavingsLayer(config: Omit<SavingsLayerConfig, "tokenizer"
  * 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.2.2";
 
-export { BV_SALA_VERSION, type BivelioHandoff, type CacheOutcome, type CachedAnswer, type CanonicalRequest, type ChatMessage, type CompactVerification, type CompressionPolicyInput, type CompressionRequest, type CompressionResult, type Compressor, type ConstraintBackend, type ConstraintBackendId, type ConstraintPlan, type ConversationState, type CostBasis, type CostModel, DEFAULT_COST_MODEL, type DeterministicResolver, EMBEDDED_PUBLIC_KEY, type EmbeddingFn, type EvidenceDoc, type ExactCache, ExactTokenizer, type ExecutionClass, ExecutionRouter, type FormatChoice, FormatSelector, type FormatSelectorOptions, type HandoffFact, HeuristicEstimator, InMemoryExactCache, InMemorySemanticCache, type JsonSchema, LicenseError, type LicenseGate, type LicenseKeyset, type LicenseStatus, type LicenseTokenPayload, type LocalClassifier, MODELOS_POR_CODIFICACION, MODELS_BY_ENCODING, type MemoryDelta, type MessageRole, MockProvider, type MockProviderOptions, type OpenAICompatibleOptions, OpenAICompatibleProvider, type OutputContract, type Policy, type ProtectedSpan, type Provider, type ProviderRequest, type ProviderResponse, type ProviderUsage, type RequestContext, type Reranker, type ResolvedDeps, type ResolvedGate, type ResolvedLicense, ResolverRegistry, type ResolverResult, type RetrievalOptions, type RetrievalOutcome, type RetrievalPlan, type Retriever, type RevocationListBody, type RevocationListVerification, type RevocationPollEvent, RevocationPoller, type RevocationPollerOptions, RevocationSnapshot, type RouteDecision, type SavingsLayer, type SavingsLayerConfig, SavingsLedger, type SavingsReport, type SavingsRequest, type SavingsResult, type SavingsToggles, SchemaRegistry, type SemanticCacheOptions, type SemanticHit, type SemanticRecord, type SemanticVerifier, type SerializationFormat, type Serializer, Singleflight, TOON_INSTRUCTION, type TokenEstimator, TokenizerRegistry, type ToolCallRequest, type ToolDescriptor, type ToolRisk, type ToolSelection, ToolSelector, type ToolSelectorOptions, type ToonDecodeOptions, type ToonOptions, TraceCollector, type TraceEvent, UsageEmitter, type UsageEmitterOptions, type ValidationError, type ValidationResult, adaptiveK, arithmeticResolver, buildExactKey, buildInflightKey, canonicalize, computeNextDelay, cosine, createDefaultResolvers, createHandoff, createMockProvider, createSavingsLayer, createToonSerializer, csvSerializer, decodeToon, dedupe, defaultTokenizerRegistry, deriveSeatId, deriveStatus, detectCi, emptyState, encodeToon, evalArithmetic, evaluatePolicy, executeRetrievalPlan, gateFromKey, heuristicEstimator, isKeyset, isStrictCompatible, jsonCompactSerializer, keyTokensMatch, liveGateFromKey, mergeDelta, noopCompressor, normalizeText, projectContext, providerNativeBackend, randomId, registerExactTokenizer, registrarTokenizadorExacto, renderState, resolveConstraintBackend, resolveDependencies, resolveLicense, sha256, shouldCompress, stableStringify, toonSerializer, uniformColumns, validateAgainstSchema, verifyCompactSignature, verifyLicenseToken, verifyRevocationList, withProtectedSpans };
+declare const BV_SALA_VERSION = "0.3.1";
+
+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, 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, type JsonSchema, LicenseError, type LicenseGate, 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, TraceCollector, type TraceEvent, UsageEmitter, type UsageEmitterOptions, type ValidationError, type ValidationResult, adaptiveK, arithmeticResolver, buildExactKey, buildInflightKey, canonicalize, compactRowsSerializer, computeNextDelay, cosine, createCompactRowsSerializer, createDefaultResolvers, createHandoff, createMockProvider, createSavingsLayer, csvSerializer, decodeCompactRows, dedupe, defaultTokenizerRegistry, deriveSeatId, deriveStatus, detectCi, emptyState, encodeCompactRows, evalArithmetic, evaluatePolicy, executeRetrievalPlan, gateFromKey, heuristicEstimator, isKeyset, isStrictCompatible, jsonCompactSerializer, keyTokensMatch, liveGateFromKey, mergeDelta, modelFamilyOf, noopCompressor, normalizeText, precioDeLista, projectContext, providerNativeBackend, randomId, registerExactTokenizer, registrarTokenizadorExacto, renderState, resolveConstraintBackend, resolveDependencies, resolveLicense, sha256, shouldCompress, stableStringify, uniformColumns, validateAgainstSchema, verifyCompactSignature, verifyLicenseToken, verifyRevocationList, withProtectedSpans };