@bivelio/savings-layer 0.4.21 → 0.4.24

package/dist/index.d.ts

@@ -11,6 +11,20 @@
  * Where the baseline being compared against comes from.
  *
  * - `measured`   — reconstructed from this request's provider counter. Real money.
+ * - `reference`  — MEASURED BY REFERENCE: the call was avoided (a repeat served
+ *                  without calling the provider) and a byte-identical request had
+ *                  already run through the layer untouched. The baseline is the
+ *                  provider's own counter for that request, valued at the
+ *                  provider's cached-input rate. Output is credited only under
+ *                  deterministic sampling, on a model with a list price in the
+ *                  catalog that does not reason and honors that setting, when
+ *                  the call that ran carried no hidden reasoning (zero reasoning
+ *                  tokens reported, or no reasoning block where the provider
+ *                  does not break them out), and then at 95% of its counter.
+ *                  With an output schema, only when the schema traveled exactly
+ *                  as sent, in strict mode, in the provider's native
+ *                  response-format parameter. Valued low on purpose. Enters the
+ *                  commission base.
  * - `estimated`  — the call was AVOIDED: it never ran, so there is no provider
  *                  counter and the baseline comes from the local estimator. Still
  *                  the best figure available, but not measured.
@@ -24,7 +38,7 @@
  * exactly what a verify-don't-trust product cannot do — and adding `shadow` to
  * either would be making the savings up.
  */
-type CostBasis = "measured" | "estimated" | "unmeasured" | "shadow";
+type CostBasis = "measured" | "reference" | "estimated" | "unmeasured" | "shadow";
 interface CostModel {
     /** Cost per 1K input tokens, in the caller's currency unit. */
     inputPer1k: number;
@@ -33,6 +47,61 @@ interface CostModel {
     /** Optional discounted rate for provider-cached (prefix) input tokens. */
     cachedInputPer1k?: number;
 }
+/** Oldest provider counter a repeat can be valued against: one billing period. */
+declare const REFERENCE_MAX_AGE_MS: number;
+/** Share of the counted output credited to a repeat: only under deterministic sampling, on a catalog model that does not reason and honors it, when the call that ran carried no hidden reasoning. */
+declare const REFERENCE_OUTPUT_SHARE = 0.95;
+/** Input tokens deducted per piece the layer inserted in the call that ran: a message, the wrapper around a native output schema, or half of the empty parameters given to a tool that had none. */
+declare const REFERENCE_MESSAGE_ALLOWANCE = 8;
+/**
+ * Why an avoided call (a cache or coalesced hit) could not be valued by
+ * reference, and so stays `estimated`.
+ *
+ * - `absent`            — the stored answer carries no provider counter.
+ * - `malformed`         — it carries one, but not in a readable shape.
+ * - `witness`           — the counter is not bound to the answer being served.
+ * - `model-mismatch`    — the counter belongs to another model.
+ * - `expired`           — the counter is older than one billing period.
+ * - `different-request` — the request that ran was not byte-identical to this one.
+ * - `quality`           — the answer being served fails its output contract.
+ * - `no-cached-price`   — no documented cached-input rate for this exact model:
+ *                         its own catalogue row (or a dated snapshot of it) or
+ *                         `costModels`, never a row inherited from a sibling id.
+ * - `no-credit`         — nothing left to credit once the allowances are applied.
+ */
+type ReferenceRejection = "absent" | "malformed" | "witness" | "model-mismatch" | "expired" | "different-request" | "quality" | "no-cached-price" | "no-credit";
+/**
+ * The provider counter an avoided call is valued against, and every figure
+ * needed to recompute its baseline:
+ * `tierFactor * (creditedInputTokens / 1000 * cachedInputPer1k + creditedOutputTokens / 1000 * outputPer1k)`.
+ */
+interface ReferenceCredit {
+    /** Id of the report of the call that ran (its report.requestId). */
+    requestId: string;
+    /** Epoch ms when that call's provider counter was read. */
+    at: number;
+    /** Input tokens the provider billed for that call. */
+    inputTokens: number;
+    /** Output tokens the provider billed for that call (the smaller of the first answer and its repair). */
+    outputTokens: number;
+    /** Input tokens credited to this repeat: inputTokens minus the allowance for what the layer inserted (messages, the native schema wrapper, empty tool parameters). */
+    creditedInputTokens: number;
+    /**
+     * Output tokens credited: a share of outputTokens capped by this request's
+     * output limit. 0 unless this request asked for deterministic sampling
+     * (`temperature: 0`), the model has a list price in the catalog, does not
+     * reason and honors that setting, and the call that ran carried no hidden
+     * reasoning (zero reasoning tokens reported, or no reasoning block where the
+     * provider does not break them out).
+     */
+    creditedOutputTokens: number;
+    /** Rate applied to every credited input token, per 1K: the provider's cached-input rate. */
+    cachedInputPer1k: number;
+    /** Rate applied to credited output tokens, per 1K. */
+    outputPer1k: number;
+    /** Fraction of the standard price applied: 1, or the discounted tier the call ran on or this request declared. */
+    tierFactor: number;
+}
 declare class SavingsLedger {
     avoidedLlm: number;
     baselineLlm: number;
@@ -87,6 +156,13 @@ declare class SavingsLedger {
      * cost; work the layer does to fix its own output has no place in it.
      */
     repairInput: number;
+    /**
+     * Billed provider calls in this request that came back WITHOUT a complete
+     * usage counter (`usage.complete === false`). Any value above zero makes the
+     * request `unmeasured`: a figure built on a missing counter is not the
+     * provider's meter.
+     */
+    callsWithoutUsage: number;
     /**
      * INPUT of the schema-on-demand discovery probe. Held apart exactly like
      * {@link repairInput}, and for the same reason.
@@ -140,6 +216,12 @@ declare class SavingsLedger {
     compress(originalTokens: number, compressedTokens: number): void;
     /** Ledger 4: tokens still present but billed/processed as provider-cached. */
     providerCached(tokens: number): void;
+    /** Set when an avoided call is valued against the provider counter of an identical call that ran. */
+    reference: ReferenceCredit | null;
+    /** Set when an avoided cache or coalesced hit could not be valued by reference: why it stays estimated. */
+    referenceRejected: ReferenceRejection | null;
+    /** Record an avoided call valued by reference. */
+    avoidCallByReference(credit: ReferenceCredit): void;
     /** Record that a whole primary LLM call was avoided (cache / resolver hit). */
     avoidCall(baselineInput: number, baselineOutput: number): void;
     /**
@@ -182,7 +264,7 @@ declare class SavingsLedger {
  * catalogue stays out of the way.
  */
 /** When these prices were last checked against the providers' public rates. */
-declare const PRECIOS_AL_DIA = "2026-09-06";
+declare const PRECIOS_AL_DIA = "2026-09-25";
 /**
  * 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
@@ -205,7 +287,7 @@ declare function precioDeLista(model: string): CostModel | undefined;
  * on the customer's machine. `test/version-declarada.test.ts` ties this
  * constant to package.json so the two can never drift.
  */
-declare const BV_SALA_VERSION = "0.4.21";
+declare const BV_SALA_VERSION = "0.4.24";
 
 /**
  * Environment-agnostic UUID generation.
@@ -217,6 +299,110 @@ declare const BV_SALA_VERSION = "0.4.21";
  */
 declare function randomId(): string;
 
+/** How the layer served a request that is eligible for a verification check. */
+type VerificationStratum = 
+/** Answered without calling the provider (cache, resolver, identical request in flight). */
+"avoided_call"
+/** Answered by a cheaper model than the one requested. */
+ | "cheaper_model"
+/** Sent with parts removed. */
+ | "tokens_removed"
+/** Sent re-encoded with fewer tokens. */
+ | "tokens_compressed"
+/** Sent without removing or re-encoding anything. */
+ | "unchanged";
+/** Why a request is never checked. */
+type VerificationExclusion = "fail_open" | "truncated" | "incomplete" | "contract_failed" | "unmeasured" | "no_price" | "over_cap" | "opted_out" | "retrieval";
+/** How a check ended. */
+type VerificationOutcome = "paired" | "check_failed" | "check_unmeasured" | "abandoned" | "dropped";
+/**
+ * Opt-in A/B verification on your own traffic. Off unless `sampleRate` is above 0.
+ *
+ * For the sampled share of eligible requests, after the answer has been returned,
+ * the layer sends the same request once more to your provider exactly as it would
+ * go without the layer (the requested model, all your tools, your data inline, no
+ * cache marks) and discards that second answer. Each pair (what the unoptimized
+ * copy cost and what the optimized request cost, both from your provider's usage
+ * counters) is reported to your dashboard and to `onCheck`.
+ *
+ * Every copy is a real provider call that you pay for: roughly `sampleRate` times
+ * what the eligible traffic would cost without the layer. Pairs are informational:
+ * they never enter measured savings, your statement or any commission.
+ */
+interface VerificationSettings {
+    /** Share of eligible requests to check, from 0 to 1. Any other value turns verification off. */
+    sampleRate: number;
+    /** Skip requests whose estimated unoptimized cost, in USD, is above this. An invalid value turns verification off. */
+    maxCheckCostUsd?: number;
+    /** Called once per sampled eligible request, when its check is settled. Errors thrown here are ignored. */
+    onCheck?: (check: VerificationCheck) => void;
+    /**
+     * Keeps a serverless runtime alive until a check is settled and reported, for
+     * example your platform's `waitUntil`. Receives one promise per copy actually
+     * sent (a check recorded as `dropped` is never sent and passes none); it never rejects.
+     */
+    waitUntil?: (promise: Promise<void>) => void;
+}
+/** Token counts and cost of one side of a pair, from the provider's usage counters. */
+interface VerificationSide {
+    cost: number;
+    inputTokens: number;
+    cachedInputTokens: number;
+    outputTokens: number;
+}
+/** One settled verification check. */
+interface VerificationCheck {
+    /** Id of the served request (its report.requestId). */
+    requestId: string;
+    /** Epoch ms when the served request was decided. */
+    at: number;
+    stratum: VerificationStratum;
+    /**
+     * - `paired`: both sides metered; `naive` is present.
+     * - `check_failed`: the provider returned an error for the copy, or it timed out.
+     * - `check_unmeasured`: the provider returned no usage counter for the copy.
+     * - `abandoned`: the copy was still running when `close()` was called.
+     * - `dropped`: not sent, because too many checks were already running.
+     */
+    outcome: VerificationOutcome;
+    requestedModel: string;
+    servedModel: string;
+    cacheResult: CacheOutcome;
+    /** The served request, as its report measured it. Zero on an avoided call. */
+    optimized: VerificationSide;
+    /**
+     * The unoptimized copy. Present only when `outcome` is `paired`. The dashboard
+     * compares a pair only when the copy finished the way a served request must to
+     * be checked: `finishReason` `stop`, `tool_calls` or absent, and a contract that
+     * was not `missed`. Other pairs are counted and exported, but left out of every figure.
+     */
+    naive?: VerificationSide & {
+        finishReason?: string;
+        /** Whether the copy met your output contract: `none` without a contract or on a tool-call turn. */
+        contract: "met" | "missed" | "none";
+    };
+    /** Rates used to price the copy, in USD per 1K tokens. */
+    prices: {
+        inputPer1k: number;
+        cachedInputPer1k?: number;
+        outputPer1k: number;
+    };
+}
+/**
+ * Whether this request was drawn for verification sampling, and how it counts.
+ * Present only when `verification` is enabled on the layer and its pairs have
+ * somewhere to go (your dashboard or `onCheck`). Absent after `close()`, and on
+ * the rare internal error of the sampler, which never affects the request itself.
+ */
+interface VerificationReport {
+    /** Drawn for a check. A copy is sent only when the request is also eligible. */
+    sampled: boolean;
+    /** How the layer served this request, when it is eligible for a check. */
+    stratum?: VerificationStratum;
+    /** Why this request is never checked. Present exactly when `stratum` is absent. */
+    excluded?: VerificationExclusion;
+}
+
 /**
  * Core contracts for BV-SALA (bivelio-savings-layer).
  *
@@ -469,6 +655,11 @@ interface SavingsToggles {
      * tier the request is sent unchanged and the report says so.
      */
     deferrable?: boolean;
+    /**
+     * Set to `false` to keep this request out of verification sampling: it is
+     * counted as excluded and never sent twice. No effect when verification is off.
+     */
+    verification?: boolean;
 }
 /**
  * What asking for a cheaper processing tier actually got you on this request.
@@ -740,6 +931,79 @@ interface SavingsResult<T = unknown> {
     finishReason?: string;
     report: SavingsReport;
 }
+/** One event of a streamed answer. */
+type SavingsStreamEvent<T = unknown> = 
+/** A piece of the answer text, as the provider wrote it. Never empty. */
+{
+    type: "text";
+    delta: string;
+}
+/** One complete tool call the model requested, in the order of `result.toolCalls`. */
+ | {
+    type: "tool_call";
+    call: ToolCallRequest;
+}
+/** Always the last event, exactly once. `result` is the same object `SavingsStream.result` resolves to. */
+ | {
+    type: "done";
+    result: SavingsResult<T>;
+};
+/** Options for `generateStream`. */
+interface SavingsStreamOptions {
+    /** Aborting it has the same effect as calling `abort()` on the stream. */
+    signal?: AbortSignal;
+}
+/**
+ * The handle returned by `generateStream`. Iterate it (once) for the events, or
+ * await `result` for the final SavingsResult; both work on their own, because
+ * the request starts as soon as the handle is created.
+ *
+ * Invariants: the concatenation of every `text` delta equals `result.text`; the
+ * `tool_call` events, in order, equal `result.toolCalls`; `done` is the last
+ * event and `result` is already resolved when it arrives.
+ */
+interface SavingsStream<T = unknown> extends AsyncIterable<SavingsStreamEvent<T>> {
+    /**
+     * Resolves with the final SavingsResult (the same object the `done` event
+     * carries). Rejects with the provider or license error that ended the stream,
+     * or with StreamAbortedError when the stream was aborted before the provider
+     * finished its answer.
+     */
+    readonly result: Promise<SavingsResult<T>>;
+    /**
+     * Stops the stream. Iteration ends at once, without an error. While the
+     * provider is still writing a live answer, its request is cancelled: `result`
+     * rejects with StreamAbortedError, nothing is cached and nothing is reported.
+     * Once the provider's answer is complete, or when it is produced in one piece
+     * (output contract, deferrable request), nothing is cancelled: `result`
+     * resolves with the full report and it is recorded like any other request.
+     * Breaking out of a for-await loop calls abort(). No-op after `done`.
+     */
+    abort(reason?: unknown): void;
+}
+/** How a streamed request reached the caller. Present only on results of `generateStream`. */
+interface StreamingReport {
+    /**
+     * "live": the text was handed over as the provider produced it.
+     * "whole": the complete answer arrived as one `text` event.
+     */
+    delivery: "live" | "whole";
+    /**
+     * Why the answer arrived whole. Absent when `delivery` is "live".
+     * - "output-contract": the request carried `response.schema`; it was validated first.
+     * - "deferrable": the request was declared `deferrable`.
+     * - "provider-without-streaming": the provider has no `generateStream`.
+     * - "shortcut": answered without a provider call (cache, deterministic resolver, or an identical request in flight).
+     * - "fail-open": an internal error sent the request down the direct fallback path.
+     */
+    wholeReason?: "output-contract" | "deferrable" | "provider-without-streaming" | "shortcut" | "fail-open";
+    /**
+     * Milliseconds from the `generateStream` call to the first `text` or
+     * `tool_call` event handed to the caller. Present only when `delivery` is
+     * "live" and such an event exists.
+     */
+    firstEventMs?: number;
+}
 type CacheOutcome = "miss" | "exact" | "semantic" | "singleflight" | "deterministic";
 /**
  * The quality claims this layer is able to DEMONSTRATE for the answer it served.
@@ -837,6 +1101,10 @@ interface SavingsReport {
         result: CacheOutcome;
         confidence?: number;
         ageMs?: number;
+        /** Present when this avoided call is valued by reference; see ReferenceCredit. */
+        reference?: ReferenceCredit;
+        /** Present on an exact-cache or coalesced hit that stays estimated: why no reference applied. Semantic-cache hits never carry it. */
+        referenceRejected?: ReferenceRejection;
     };
     routing: {
         executionClass: ExecutionClass;
@@ -891,6 +1159,13 @@ interface SavingsReport {
      * `savings.deferrable` is `true`, including when it got you nothing.
      */
     deferred?: DeferredExecutionReport;
+    /** How a streamed request was delivered. Present only on results of `generateStream`. */
+    streaming?: StreamingReport;
+    /**
+     * Whether this request was drawn for verification sampling, and how it counts.
+     * Present only when `verification` is enabled on the layer.
+     */
+    verification?: VerificationReport;
     quality: {
         taskPassed?: boolean;
         /**
@@ -914,6 +1189,22 @@ interface SavingsReport {
          *
          * - `measured`   — reconstructed from THIS request's provider counter. Real
          *                  money, checkable against the provider invoice.
+         * - `reference`  — MEASURED BY REFERENCE: the call was avoided (a repeat
+         *                  served without calling the provider) and a byte-identical
+         *                  request had already run through the layer untouched. The
+         *                  baseline is the provider's own counter for that request,
+         *                  valued at the provider's cached-input rate. Output is
+         *                  credited only under deterministic sampling, on a model
+         *                  with a list price in the catalog that does not reason and
+         *                  honors that setting, when the call that ran carried no
+         *                  hidden reasoning (zero reasoning tokens reported, or no
+         *                  reasoning block where the provider does not break them
+         *                  out), and then at 95% of its counter. With an output
+         *                  schema, only when the schema traveled exactly as sent, in
+         *                  strict mode, in the provider's native response-format
+         *                  parameter. Valued low on purpose.
+         *                  Enters the commission base; `cache.reference` carries the
+         *                  arithmetic and the id of the request that ran.
          * - `estimated`  — the call was AVOIDED, so there never was a provider
          *                  counter and the baseline comes from the local estimator.
          *                  The best figure available, but not measured.
@@ -1361,7 +1652,12 @@ interface CachedAnswer<T = unknown> {
     rendered?: string;
     /** Epoch ms when stored; used to compute age and honor TTL. */
     storedAtMs: number;
-    /** Optional metadata carried alongside the answer. */
+    /**
+     * Optional metadata carried alongside the answer.
+     *
+     * `meta.reference` carries the provider counter of the call that produced this
+     * answer, when that call ran untouched; readers that do not know it ignore it.
+     */
     meta?: Record<string, unknown>;
 }
 interface ExactCache {
@@ -1409,6 +1705,11 @@ declare class Singleflight {
         value: T;
         coalesced: boolean;
     }>;
+    /**
+     * The in-flight execution under `key`, if one is running, joined as a
+     * follower; `undefined` when nothing is in flight. Never starts one.
+     */
+    join<T>(key: string): Promise<T> | undefined;
     get activeKeys(): number;
 }
 
@@ -2259,6 +2560,27 @@ interface ProviderUsage {
      * bill INCREASE as a saving.
      */
     cacheWriteInputTokens?: number;
+    /**
+     * Output tokens the provider billed for hidden reasoning, already included in
+     * `outputTokens` (OpenAI `completion_tokens_details.reasoning_tokens`).
+     *
+     * `0` states that the answer carried no hidden reasoning. Where the provider
+     * does not break reasoning out (Anthropic's Messages API), the built-in
+     * adapter reports `0` only when the answer has no `thinking` or
+     * `redacted_thinking` block, and leaves this absent otherwise. Absent means
+     * nobody said, which is NOT the same as 0: a repeat served by reference only
+     * credits output when the call that ran reported exactly 0, because reasoning
+     * tokens are neither visible nor deterministic. A custom provider should set
+     * it only from its provider's own counter or an equally direct signal.
+     */
+    reasoningTokens?: number;
+    /**
+     * False when the provider did not report both counters for this call (for a
+     * stream: its final usage event never arrived), so the adapter filled the
+     * missing ones with 0. Absent means complete. A request with any such call is
+     * reported as `unmeasured`.
+     */
+    complete?: boolean;
 }
 interface ProviderResponse {
     text: string;
@@ -2320,9 +2642,32 @@ interface ProviderResponse {
     requestedServiceTier?: string;
     raw?: unknown;
 }
+/** One event of a provider-level stream. */
+type ProviderStreamEvent = {
+    type: "text";
+    delta: string;
+} | {
+    type: "done";
+    response: ProviderResponse;
+};
+/** Options for {@link Provider.generate} and {@link Provider.generateStream}. */
+interface ProviderStreamOptions {
+    /** Cancels the HTTP request. */
+    signal?: AbortSignal;
+}
 interface Provider {
     readonly id: string;
-    generate(req: ProviderRequest): Promise<ProviderResponse>;
+    generate(req: ProviderRequest, options?: ProviderStreamOptions): Promise<ProviderResponse>;
+    /**
+     * Optional streaming variant of generate(). It must yield `text` events in
+     * order and end with exactly one `done` whose `response` is what generate()
+     * would have returned for the same answer: `response.text` equals the
+     * concatenated deltas, and tool calls travel only in `response.toolCalls`.
+     * When the provider's final usage event is missing, both counters are 0 and
+     * `usage.complete` is false. A body that ends before the provider signalled
+     * completion must throw, never yield `done`.
+     */
+    generateStream?(req: ProviderRequest, options?: ProviderStreamOptions): AsyncIterable<ProviderStreamEvent>;
 }
 
 /**
@@ -2357,12 +2702,19 @@ interface MockProviderOptions {
     data?: unknown;
     /** Simulated provider-cached input tokens (ledger 4). */
     cachedInputTokens?: number;
+    /** Characters per text event in generateStream (default 8). */
+    streamChunkChars?: number;
 }
 declare class MockProvider implements Provider {
     readonly id = "mock";
     private readonly options;
     constructor(options?: MockProviderOptions);
-    generate(req: ProviderRequest): Promise<ProviderResponse>;
+    generate(req: ProviderRequest, _options?: ProviderStreamOptions): Promise<ProviderResponse>;
+    /**
+     * Streaming variant of generate(): the same answer, cut into text events of
+     * `streamChunkChars` characters, then one `done` with the generate() response.
+     */
+    generateStream(req: ProviderRequest): AsyncGenerator<ProviderStreamEvent, void, undefined>;
 }
 declare function createMockProvider(options?: MockProviderOptions): Provider;
 
@@ -2387,7 +2739,18 @@ declare function createMockProvider(options?: MockProviderOptions): Provider;
 interface OpenAICompatibleOptions {
     baseUrl: string;
     apiKey?: string;
-    /** Strip the "provider/" prefix from model ids before sending. */
+    /**
+     * Strip the `provider/` prefix from model ids before sending (`openai/gpt-4o-mini`
+     * → `gpt-4o-mini`).
+     *
+     * Default (undefined): strip when `baseUrl` is OpenAI's own API or an Azure
+     * OpenAI endpoint, keep otherwise. OpenAI rejects a prefixed id with a 404
+     * ("model does not exist"), so the qualified ids the layer uses everywhere
+     * else — pricing, cache keys, the report — would break the very first call
+     * that reaches the provider. A gateway or a self-hosted server with a
+     * namespaced model name usually WANTS the prefix, so it is kept there. Set `true`/`false` to decide explicitly; an explicit value
+     * always wins.
+     */
     stripProviderPrefix?: boolean;
     /** Extra headers (e.g. for a gateway). */
     headers?: Record<string, string>;
@@ -2417,15 +2780,32 @@ interface OpenAICompatibleOptions {
  * es una restricción de OpenAI que JSON Schema no tiene.
  */
 declare function isStrictCompatible(schema: unknown): boolean;
+/**
+ * Decides the id that travels on the wire. Explicit option wins; otherwise the
+ * endpoint decides: OpenAI/Azure get the bare id, everything else keeps what
+ * the caller wrote. Exported for the pipeline-level test that pins the README
+ * snippet; not part of the public API.
+ */
+declare function quitarPrefijoDeProveedor(model: string, explicito: boolean | undefined, baseUrl: string): string;
 declare class OpenAICompatibleProvider implements Provider {
     readonly id: string;
     private readonly opts;
     private readonly fetchImpl;
     /** Models of this endpoint already known to reject `response_format`. */
     private readonly sinResponseFormat;
+    private streamOptionsRejected;
     constructor(opts: OpenAICompatibleOptions);
-    generate(req: ProviderRequest): Promise<ProviderResponse>;
-    /** Build the request body and post it. `nativo` selects the `response_format` path. */
+    generate(req: ProviderRequest, options?: ProviderStreamOptions): Promise<ProviderResponse>;
+    /**
+     * Streaming variant of generate() over Chat Completions. It always asks for
+     * the final usage chunk (`stream_options.include_usage`); an endpoint that
+     * rejects that option is retried once without it and remembered, and its
+     * streamed answers then report `usage.complete: false`. With `requireUsage`,
+     * that rejection throws instead. Requests with an output contract or a
+     * deferrable tier are not streamed: they are served by generate() and yielded
+     * as one text event.
+     */
+    generateStream(req: ProviderRequest, options?: ProviderStreamOptions): AsyncGenerator<ProviderStreamEvent, void, undefined>;
     private enviar;
     /** Translate a 2xx endpoint response into the provider-neutral shape. */
     private leer;
@@ -2448,6 +2828,14 @@ interface AnthropicOptions {
     apiKey?: string;
     /** Defaults to the public API. Override for a gateway or a proxy. */
     baseUrl?: string;
+    /**
+     * Strip the `provider/` prefix from model ids before sending
+     * (`anthropic/claude-sonnet-4-5` → `claude-sonnet-4-5`). Default (undefined):
+     * strip when talking to `api.anthropic.com`, which rejects a prefixed id;
+     * keep for a gateway or proxy, which usually routes on it. An explicit value
+     * always wins.
+     */
+    stripProviderPrefix?: boolean;
     /** Wire version pinned in the `anthropic-version` header. */
     apiVersion?: string;
     /** Extra headers (e.g. for a gateway). */
@@ -2512,10 +2900,22 @@ declare class AnthropicProvider implements Provider {
     private readonly opts;
     private readonly fetchImpl;
     constructor(opts?: AnthropicOptions);
-    generate(req: ProviderRequest): Promise<ProviderResponse>;
+    /** The id Anthropic's API sees: bare at `api.anthropic.com`, as written elsewhere. */
+    private modeloEnElCable;
+    generate(req: ProviderRequest, options?: ProviderStreamOptions): Promise<ProviderResponse>;
+    /**
+     * Streaming variant of generate() over the Messages API. The final usage is
+     * read from the closing `message_delta` event (the output counter in
+     * `message_start` is provisional); a stream without it reports
+     * `usage.complete: false`, and with `requireUsage` it throws instead. A body
+     * that ends before the provider signalled completion throws. Requests with an
+     * output contract or declared deferrable are served by generate() and yielded
+     * as one text event.
+     */
+    generateStream(req: ProviderRequest, options?: ProviderStreamOptions): AsyncGenerator<ProviderStreamEvent, void, undefined>;
+    private enviar;
     private construirCuerpo;
     private marcarCache;
-    /** Traduce una respuesta 2xx a la forma neutra del layer. */
     private leer;
 }
 
@@ -3193,7 +3593,7 @@ interface SavingsLayerConfig {
         /** Reject a signed list whose `asOf` is more than this far in the future, seconds (default 300). */
         maxSkewSeconds?: number;
         /**
-         * ONLINE staleness ceiling, seconds (default ~6h). If the SDK goes this long
+         * ONLINE staleness ceiling, seconds (default 72h, `DEFAULT_MAX_STALENESS_SECONDS`). If the SDK goes this long
          * without a CONFIRMED authorized heartbeat (a 304 or a verified list), the LIVE
          * gate stops granting — closing the fail-open window where blocking egress keeps
          * a revoked license alive until natural expiry. Must exceed the poll cadence
@@ -3266,6 +3666,8 @@ interface SavingsLayerConfig {
         /** Optional org hint; the server derives the authoritative org from the key. */
         orgId?: string;
     };
+    /** Opt-in A/B verification on your own traffic. Off by default. See VerificationSettings. */
+    verification?: VerificationSettings;
     /**
      * Development-only escape hatch to run ungated, honored ONLY when building from
      * source (local dev, CI, benchmarks) — also via the `BVSALA_DEV_OPEN=1`
@@ -3335,6 +3737,16 @@ interface SavingsLayerConfig {
      * emitter and the revocation poller alike.
      */
     silenceWarnings?: boolean;
+    /**
+     * Load the exact OpenAI tokenizer (`gpt-tokenizer`, optional peer) into the
+     * default registry when it is installed. ON by default: without it, every
+     * saving where the layer removed something is reported as `estimated` and
+     * never billed, and the SDK warns once. Set to `false` to keep the built-in
+     * heuristic even when the package is present (tests calibrated on the
+     * heuristic, or a process that must not spend the encoding's memory). Ignored
+     * when you pass your own `tokenizer` registry: you decide what it contains.
+     */
+    exactTokenizer?: boolean;
     /** Injectable clock for deterministic tests. */
     now?: () => number;
     /** Injectable id generator for deterministic tests. */
@@ -3417,11 +3829,33 @@ declare const DEFAULT_MAX_STALENESS_SECONDS: number;
 /** The public handle returned by {@link createSavingsLayer}. */
 interface SavingsLayer {
     generate<T = unknown>(request: SavingsRequest): Promise<SavingsResult<T>>;
+    /**
+     * Same request as generate(), delivered as a stream of events.
+     *
+     * Iterate the returned object for `text` deltas as the provider writes them,
+     * then one `tool_call` event per requested tool call, then exactly one `done`
+     * event carrying the same SavingsResult that `result` resolves to. The report
+     * follows the same basis rules as generate(): the provider's final usage is
+     * read at the end of the stream, and a stream that ends without it is
+     * reported as `unmeasured`.
+     *
+     * Requests with an output contract (`response.schema`) or declared
+     * `deferrable`, and providers without streaming support, are produced exactly
+     * as generate() would and delivered in one piece; `report.streaming` says how
+     * the answer was delivered and why.
+     *
+     * Work starts immediately, so awaiting `result` without iterating is valid.
+     * Concurrent identical streamed requests each call the provider; a streamed
+     * request can still reuse an identical generate() call already in flight.
+     * Await `result` before calling close(), or its usage record may be lost.
+     */
+    generateStream<T = unknown>(request: SavingsRequest, options?: SavingsStreamOptions): SavingsStream<T>;
     /**
      * Stop the background revocation poller (when the online call-home was enabled
-     * via `licenseServerUrl`) and abort any in-flight request. Always safe to call —
-     * a no-op when there is no poller. Call it when shutting down a long-running
-     * process so the interval timer and any pending fetch are released.
+     * via `licenseServerUrl`) and abort any in-flight request, and settle every
+     * verification check still in flight (recorded as abandoned). Always safe to
+     * call — a no-op when there is no poller. Call it when shutting down a
+     * long-running process so the interval timer and any pending fetch are released.
      */
     close(): void;
 }
@@ -3447,4 +3881,17 @@ interface SavingsLayer {
  */
 declare function createSavingsLayer(config: Omit<SavingsLayerConfig, "tokenizer"> & Partial<Pick<SavingsLayerConfig, "tokenizer">>): SavingsLayer;
 
-export { type AnthropicOptions, AnthropicProvider, BV_SALA_VERSION, type BivelioHandoff, CATALOGO, COMPACT_ROWS_INSTRUCTION, type CacheOutcome, type CacheTier, type CachedAnswer, type CanonicalRequest, type ChatMessage, type CompactRowsDecodeOptions, type CompactRowsOptions, type CompactVerification, type CompressionEconomics, type CompressionPolicyInput, type CompressionRequest, type CompressionResult, type Compressor, type ConstraintBackend, type ConstraintBackendId, type ConstraintPlan, type ConversationState, type CostBasis, type CostModel, DEFAULT_COST_MODEL, DEFAULT_MAX_STALENESS_SECONDS, type DeferredExecutionReport, type DeterministicResolver, EMBEDDED_PUBLIC_KEY, type EmbeddingFn, type EvidenceDoc, type ExactCache, ExactTokenizer, type ExecutionClass, ExecutionRouter, type FormatChoice, FormatSelector, type FormatSelectorOptions, type HandoffFact, HeuristicEstimator, InMemoryExactCache, InMemorySemanticCache, InMemoryToolSetFreezer, type JsonSchema, LicenseError, type LicenseGate, type LicenseKeyShape, type LicenseKeyset, type LicenseStatus, type LicenseTokenPayload, type LocalClassifier, MODELOS_POR_CODIFICACION, MODELS_BY_ENCODING, type MemoryDelta, type MessageRole, MockProvider, type MockProviderOptions, type ModelCascadeMode, type ModelCascadeReport, type ModelCascadeSettings, type OpenAICompatibleOptions, OpenAICompatibleProvider, type OutputContract, PRECIOS_AL_DIA, type Policy, type ProtectedSpan, type Provider, type ProviderRequest, type ProviderResponse, type ProviderUsage, QUALITY_STATUSES, type QualityStatus, type RequestContext, type Reranker, type ResolvedDeps, type ResolvedGate, type ResolvedLicense, ResolverRegistry, type ResolverResult, type RetrievalOptions, type RetrievalOutcome, type RetrievalPlan, type Retriever, type RevocationListBody, type RevocationListVerification, type RevocationPollEvent, RevocationPoller, type RevocationPollerOptions, RevocationSnapshot, type RouteDecision, type SavingsLayer, type SavingsLayerConfig, SavingsLedger, type SavingsReport, type SavingsRequest, type SavingsResult, type SavingsToggles, SchemaRegistry, type SemanticCacheOptions, type SemanticHit, type SemanticRecord, type SemanticVerifier, type SerializationFormat, type Serializer, Singleflight, type TokenEstimator, TokenizerRegistry, type ToolCallRequest, type ToolDescriptor, type ToolRisk, type ToolSelection, ToolSelector, type ToolSelectorOptions, type ToolSetFreezer, TraceCollector, type TraceEvent, UMBRAL_LOCAL, UsageEmitter, type UsageEmitterOptions, type ValidationError, type ValidationResult, adaptiveK, arithmeticResolver, buildExactKey, buildInflightKey, canonicalize, compactRowsSerializer, compresionFiel, computeNextDelay, cosine, createCompactRowsSerializer, createDefaultResolvers, createHandoff, createMockProvider, createSavingsLayer, csvSerializer, decodeCompactRows, dedupe, defaultTokenizerRegistry, deriveSeatId, deriveStatus, detectCi, embebedorLocal, emptyState, encodeCompactRows, evalArithmetic, evaluatePolicy, executeRetrievalPlan, gateFromKey, heuristicEstimator, isKeyset, isStrictCompatible, jsonCompactSerializer, keyTokensMatch, licenseKeyShape, liveGateFromKey, mergeDelta, modelFamilyOf, multisetEqual, negationCount, noopCompressor, normalizeLicenseKey, normalizeText, numericTokens, precioDeLista, projectContext, providerNativeBackend, randomId, registerExactTokenizer, registrarTokenizadorExacto, renderState, resolveConstraintBackend, resolveDependencies, resolveLicense, sha256, shouldCompress, stableStringify, uniformColumns, validateAgainstSchema, vectorLocal, verifyCompactSignature, verifyLicenseToken, verifyRevocationList, withProtectedSpans, words };
+/**
+ * Rejection of `SavingsStream.result` when the stream was aborted before the
+ * provider finished its answer. Nothing was cached and no usage was recorded.
+ */
+declare class StreamAbortedError extends Error {
+    /**
+     * True when a request had already been sent to the provider: the provider may
+     * bill the tokens it generated before the cancel, and that cost is in no report.
+     */
+    readonly requestSent: boolean;
+    constructor(requestSent: boolean);
+}
+
+export { type AnthropicOptions, AnthropicProvider, BV_SALA_VERSION, type BivelioHandoff, CATALOGO, COMPACT_ROWS_INSTRUCTION, type CacheOutcome, type CacheTier, type CachedAnswer, type CanonicalRequest, type ChatMessage, type CompactRowsDecodeOptions, type CompactRowsOptions, type CompactVerification, type CompressionEconomics, type CompressionPolicyInput, type CompressionRequest, type CompressionResult, type Compressor, type ConstraintBackend, type ConstraintBackendId, type ConstraintPlan, type ConversationState, type CostBasis, type CostModel, DEFAULT_COST_MODEL, DEFAULT_MAX_STALENESS_SECONDS, type DeferredExecutionReport, type DeterministicResolver, EMBEDDED_PUBLIC_KEY, type EmbeddingFn, type EvidenceDoc, type ExactCache, ExactTokenizer, type ExecutionClass, ExecutionRouter, type FormatChoice, FormatSelector, type FormatSelectorOptions, type HandoffFact, HeuristicEstimator, InMemoryExactCache, InMemorySemanticCache, InMemoryToolSetFreezer, type JsonSchema, LicenseError, type LicenseGate, type LicenseKeyShape, type LicenseKeyset, type LicenseStatus, type LicenseTokenPayload, type LocalClassifier, MODELOS_POR_CODIFICACION, MODELS_BY_ENCODING, type MemoryDelta, type MessageRole, MockProvider, type MockProviderOptions, type ModelCascadeMode, type ModelCascadeReport, type ModelCascadeSettings, type OpenAICompatibleOptions, OpenAICompatibleProvider, type OutputContract, PRECIOS_AL_DIA, type Policy, type ProtectedSpan, type Provider, type ProviderRequest, type ProviderResponse, type ProviderStreamEvent, type ProviderStreamOptions, type ProviderUsage, QUALITY_STATUSES, type QualityStatus, REFERENCE_MAX_AGE_MS, REFERENCE_MESSAGE_ALLOWANCE, REFERENCE_OUTPUT_SHARE, type ReferenceCredit, type ReferenceRejection, type RequestContext, type Reranker, type ResolvedDeps, type ResolvedGate, type ResolvedLicense, ResolverRegistry, type ResolverResult, type RetrievalOptions, type RetrievalOutcome, type RetrievalPlan, type Retriever, type RevocationListBody, type RevocationListVerification, type RevocationPollEvent, RevocationPoller, type RevocationPollerOptions, RevocationSnapshot, type RouteDecision, type SavingsLayer, type SavingsLayerConfig, SavingsLedger, type SavingsReport, type SavingsRequest, type SavingsResult, type SavingsStream, type SavingsStreamEvent, type SavingsStreamOptions, type SavingsToggles, SchemaRegistry, type SemanticCacheOptions, type SemanticHit, type SemanticRecord, type SemanticVerifier, type SerializationFormat, type Serializer, Singleflight, StreamAbortedError, type StreamingReport, type TokenEstimator, TokenizerRegistry, type ToolCallRequest, type ToolDescriptor, type ToolRisk, type ToolSelection, ToolSelector, type ToolSelectorOptions, type ToolSetFreezer, TraceCollector, type TraceEvent, UMBRAL_LOCAL, UsageEmitter, type UsageEmitterOptions, type ValidationError, type ValidationResult, type VerificationCheck, type VerificationExclusion, type VerificationOutcome, type VerificationReport, type VerificationSettings, type VerificationSide, type VerificationStratum, adaptiveK, arithmeticResolver, buildExactKey, buildInflightKey, canonicalize, compactRowsSerializer, compresionFiel, computeNextDelay, cosine, createCompactRowsSerializer, createDefaultResolvers, createHandoff, createMockProvider, createSavingsLayer, csvSerializer, decodeCompactRows, dedupe, defaultTokenizerRegistry, deriveSeatId, deriveStatus, detectCi, embebedorLocal, emptyState, encodeCompactRows, evalArithmetic, evaluatePolicy, executeRetrievalPlan, gateFromKey, heuristicEstimator, isKeyset, isStrictCompatible, jsonCompactSerializer, keyTokensMatch, licenseKeyShape, liveGateFromKey, mergeDelta, modelFamilyOf, multisetEqual, negationCount, noopCompressor, normalizeLicenseKey, normalizeText, numericTokens, precioDeLista, projectContext, providerNativeBackend, quitarPrefijoDeProveedor, randomId, registerExactTokenizer, registrarTokenizadorExacto, renderState, resolveConstraintBackend, resolveDependencies, resolveLicense, sha256, shouldCompress, stableStringify, uniformColumns, validateAgainstSchema, vectorLocal, verifyCompactSignature, verifyLicenseToken, verifyRevocationList, withProtectedSpans, words };