@bivelio/savings-layer 0.2.2 → 0.3.0

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,19 @@ 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;
     /**
      * 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 +116,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 +176,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 +237,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 +251,61 @@ interface SavingsToggles {
     singleflight?: boolean;
     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.
+     *
+     * 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.
+     */
+    outputCodebook?: boolean;
+    /**
+     * 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;
 }
 interface RequestContext {
     tenantId?: string;
@@ -266,6 +371,42 @@ 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.
+ * - `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", "rejected"];
+type QualityStatus = (typeof QUALITY_STATUSES)[number];
 interface SavingsReport {
     requestId: string;
     model: string;
@@ -328,8 +469,27 @@ 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;
     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;
     };
@@ -410,7 +570,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 +620,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 +677,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 +739,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,6 +771,14 @@ 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. */
@@ -821,7 +984,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 +1099,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 +1246,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 +1264,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 +1325,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 +1344,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 +1448,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 +1517,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 +1587,52 @@ 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;
 }
 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
@@ -1436,6 +1696,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 +1742,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;
 }
 
 /**
@@ -1874,6 +2207,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 +2233,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 +2255,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,6 +2313,17 @@ 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;
     /**
@@ -2106,6 +2477,16 @@ 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. */
@@ -2147,7 +2528,7 @@ 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.).
  *
  * @example
@@ -2185,6 +2566,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.0";
+
+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 };