@bivelio/savings-layer 0.3.0 → 0.3.1

package/dist/index.d.ts

@@ -78,6 +78,26 @@ declare class SavingsLedger {
     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
@@ -252,21 +272,55 @@ interface SavingsToggles {
     deterministicResolvers?: boolean;
     router?: boolean;
     /**
-     * OPT-IN. Send the provider a compacted form of your output contract — short
-     * property keys, short enum codes — so the model spends fewer tokens saying
-     * the same thing, and expand 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.
+     * 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.
      *
-     * It is applied only when the layer can prove the expansion is exact for that
-     * schema and only when it counts as a net token win on both sides (the
-     * compact contract itself travels as input). Otherwise your schema is sent
-     * unchanged. Off by default because it changes what the provider sees, and
-     * whether a model answers as WELL from a compact contract is a question only
-     * an A/B on your own traffic can settle. Check `report.traces` for what it
-     * decided and why.
+     * 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.
@@ -306,6 +360,249 @@ interface SavingsToggles {
      * 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;
@@ -395,6 +692,14 @@ type CacheOutcome = "miss" | "exact" | "semantic" | "singleflight" | "determinis
  *                      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
@@ -405,10 +710,19 @@ type CacheOutcome = "miss" | "exact" | "semantic" | "singleflight" | "determinis
  * 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", "rejected"];
+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;
@@ -480,6 +794,17 @@ interface SavingsReport {
      * 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;
         /**
@@ -524,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;
@@ -783,6 +1112,14 @@ 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;
 
 /**
@@ -792,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
@@ -804,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.
- */
-declare function buildInflightKey(c: CanonicalRequest): string;
+ *
+ * `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;
+}): string;
 
 /**
  * Policy engine: risk and freshness.
@@ -1604,6 +1983,19 @@ interface ProviderRequest {
      * 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;
@@ -1655,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 {
@@ -1670,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. */
@@ -1833,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);
 }
@@ -1842,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
@@ -1943,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?: {
@@ -2326,6 +2770,11 @@ interface SavingsLayerConfig {
     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
@@ -2343,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;
     /**
@@ -2492,6 +2942,58 @@ interface SavingsLayerConfig {
     /** 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. */
@@ -2531,9 +3033,15 @@ interface SavingsLayer {
  * 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?" }],
  * });
@@ -2567,6 +3075,6 @@ declare function createSavingsLayer(config: Omit<SavingsLayerConfig, "tokenizer"
  * constant to package.json so the two can never drift.
  */
 
-declare const BV_SALA_VERSION = "0.3.0";
+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 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, 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, noopCompressor, normalizeText, precioDeLista, projectContext, providerNativeBackend, randomId, registerExactTokenizer, registrarTokenizadorExacto, renderState, resolveConstraintBackend, resolveDependencies, resolveLicense, sha256, shouldCompress, stableStringify, uniformColumns, validateAgainstSchema, verifyCompactSignature, verifyLicenseToken, verifyRevocationList, withProtectedSpans };
+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 };