@bivelio/savings-layer 0.5.2 → 1.1.0

package/dist/index.d.ts

@@ -1,161 +1,3 @@
-/**
- * The four-ledger savings accounting.
- *
- * These ledgers are kept strictly separate on purpose: each answers a different
- * question, and summing them would double-count.
- * The ledger is a pure accumulator: the pipeline records events into it, and it
- * produces the numbers that populate the SavingsReport. It never guesses — every
- * increment is driven by an explicit pipeline decision.
- */
-/**
- * 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.
- * - `unmeasured` — the provider reported no usage. Nothing is claimed.
- * - `shadow`     — HYPOTHETICAL: what would have happened with a lever turned on
- *                  (the shadow lane). Never enters the commission base, never
- *                  added to measured or to any total; shadow reports are built
- *                  separately and `estimateCost` must never produce this value.
- *
- * Summing `measured` and `estimated` into a single "money saved" figure is
- * exactly what a verify-don't-trust product cannot do — and adding `shadow` to
- * either would be making the savings up.
- */
-type CostBasis = "measured" | "reference" | "estimated" | "unmeasured" | "shadow";
-interface CostModel {
-    /** Cost per 1K input tokens, in the caller's currency unit. */
-    inputPer1k: number;
-    /** Cost per 1K output tokens. */
-    outputPer1k: number;
-    /** Optional discounted rate for provider-cached (prefix) input tokens. */
-    cachedInputPer1k?: number;
-}
-/**
- * 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;
-}
-
-/**
- * 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.
- */
-/**
- * Version of this price catalogue: the UTC day its content last changed (rows,
- * announced price steps, cache-write premiums, tier rates). Two computations
- * citing the same version were priced with the same content.
- */
-declare const PRECIOS_AL_DIA = "2026-09-29";
-/**
- * Key = the model id as the provider publishes it, without a vendor prefix.
- * Lookup tries the exact id, then the id without its provider prefix, then the
- * LONGEST matching prefix — so `gpt-4o-2024-08-06` inherits `gpt-4o` without
- * having to enumerate every dated snapshot.
- *
- * These are the rows in force on {@link PRECIOS_AL_DIA}. A price change a
- * provider has already announced is applied by {@link precioDeLista} from its
- * effective date, so a request is always priced at the rate of its own day.
- */
-declare const CATALOGO: Readonly<Record<string, CostModel>>;
-/**
- * The list price for a model on the day of the request, or `undefined` when
- * the catalogue has no price for it in force that day.
- *
- * @param model the id as the caller passes it, with or without a vendor prefix.
- * @param at when the request was made (epoch ms or a `Date`); defaults to now.
- *   Prices resolve per UTC day, so a price change the provider has announced
- *   applies from its effective date.
- */
-declare function precioDeLista(model: string, at?: Date | number): CostModel | undefined;
-
-/**
- * The version the SDK reports for itself.
- *
- * Written by hand and deliberately NOT read from package.json: the published
- * bundle does not ship package.json, so a `require` here would fail at runtime
- * 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.5.2";
-
 /** 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). */
@@ -1067,10 +909,28 @@ type SavingsStreamEvent<T = unknown> =
     type: "done";
     result: SavingsResult<T>;
 };
+/** Optional cancellation and total-deadline controls for one request. */
+interface SavingsRequestOptions {
+    /** Cancels this request without cancelling other users of the same layer. */
+    signal?: AbortSignal;
+    /**
+     * Total budget from the public entry point until the answer is delivered, in
+     * milliseconds. It must be a positive finite integer no greater than
+     * 2,147,483,647 (about 24.8 days), the largest portable `setTimeout` delay.
+     *
+     * Expiry aborts the provider signal and throws `RequestTimeoutError`. A custom
+     * provider that ignores that signal is awaited until its work stops; if it never
+     * stops, rejection is delayed indefinitely too. No late cache or learning write
+     * is started after the provider finally settles.
+     */
+    requestTimeoutMs?: number;
+}
 /** Options for `generateStream`. */
-interface SavingsStreamOptions {
+interface SavingsStreamOptions extends SavingsRequestOptions {
     /** Aborting it has the same effect as calling `abort()` on the stream. */
     signal?: AbortSignal;
+    /** Total budget for this stream; see `SavingsRequestOptions.requestTimeoutMs`. */
+    requestTimeoutMs?: number;
 }
 /**
  * The handle returned by `generateStream`. Iterate it (once) for the events, or
@@ -1487,6 +1347,34 @@ interface SavingsReport {
         protectedSpans: number;
         fidelityPassed: boolean;
     };
+    /**
+     * Present only when tool-output compaction ran with `profile:
+     * "lossless-data"`: one explained decision per tool output in the request,
+     * applied or bypassed, in message order. Token counts come from the
+     * estimator named in `estimator` and are estimates, never a verified saving.
+     */
+    toolOutputCompaction?: {
+        profile: "lossless-data";
+        /** Always `"estimated"`: these counts are not the provider's. */
+        tokenBasis: "estimated";
+        /** Id of the token estimator that counted, and whether it uses the provider's rule. */
+        estimator: {
+            id: string;
+            exact: boolean;
+        };
+        decisions: Array<{
+            /** The tool call this output answers, unchanged. Absent when the message had none. */
+            toolCallId?: string;
+            status: "applied" | "bypassed";
+            reason: "applied" | "not_json" | "invalid_json" | "duplicate_keys" | "invalid_unicode" | "not_smaller" | "below_threshold" | "protected";
+            transformId: string;
+            version: string;
+            tokensBefore: number;
+            /** What is sent: the compacted text when applied, the original otherwise. */
+            tokensAfter: number;
+            candidateTokens?: number;
+        }>;
+    };
     constraints: {
         backend: string;
         schemaVersion: string;
@@ -1569,6 +1457,16 @@ interface SavingsReport {
     cost: {
         baselineEstimate: number;
         actual: number;
+        /**
+         * Present, and `true`, only when a billed call of this request reached the
+         * layer without its full provider counter (a stream cut before its final
+         * usage event, an endpoint that omitted a counter). `actual` then prices
+         * only the counters that did arrive, with the missing ones at 0: it is a
+         * FLOOR of what the provider billed, possibly 0, never the spend. The
+         * request is also `basis: "unmeasured"`. Do not add such an `actual` to
+         * measured spend. Absent whenever every counter arrived.
+         */
+        actualIsLowerBound?: true;
         /**
          * The saving as a RATIO of the baseline: `1 - actual / baselineEstimate`,
          * rounded to six decimals (0 when nothing was saved or there is no baseline,
@@ -1745,6 +1643,164 @@ interface TraceEvent {
     atMs: number;
 }
 
+/**
+ * The four-ledger savings accounting.
+ *
+ * These ledgers are kept strictly separate on purpose: each answers a different
+ * question, and summing them would double-count.
+ * The ledger is a pure accumulator: the pipeline records events into it, and it
+ * produces the numbers that populate the SavingsReport. It never guesses — every
+ * increment is driven by an explicit pipeline decision.
+ */
+/**
+ * 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.
+ * - `unmeasured` — the provider reported no usage. Nothing is claimed.
+ * - `shadow`     — HYPOTHETICAL: what would have happened with a lever turned on
+ *                  (the shadow lane). Never enters the commission base, never
+ *                  added to measured or to any total; shadow reports are built
+ *                  separately and `estimateCost` must never produce this value.
+ *
+ * Summing `measured` and `estimated` into a single "money saved" figure is
+ * exactly what a verify-don't-trust product cannot do — and adding `shadow` to
+ * either would be making the savings up.
+ */
+type CostBasis = "measured" | "reference" | "estimated" | "unmeasured" | "shadow";
+interface CostModel {
+    /** Cost per 1K input tokens, in the caller's currency unit. */
+    inputPer1k: number;
+    /** Cost per 1K output tokens. */
+    outputPer1k: number;
+    /** Optional discounted rate for provider-cached (prefix) input tokens. */
+    cachedInputPer1k?: number;
+}
+/**
+ * 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;
+}
+
+/**
+ * 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.
+ */
+/**
+ * Version of this price catalogue: the UTC day its content last changed (rows,
+ * announced price steps, cache-write premiums, tier rates). Two computations
+ * citing the same version were priced with the same content.
+ */
+declare const PRECIOS_AL_DIA = "2026-11-03";
+/**
+ * Key = the model id as the provider publishes it, without a vendor prefix.
+ * Lookup tries the exact id, then the id without its provider prefix, then the
+ * LONGEST matching prefix — so `gpt-4o-2024-08-06` inherits `gpt-4o` without
+ * having to enumerate every dated snapshot.
+ *
+ * These are the rows in force on {@link PRECIOS_AL_DIA}. A price change a
+ * provider has already announced is applied by {@link precioDeLista} from its
+ * effective date, so a request is always priced at the rate of its own day.
+ */
+declare const CATALOGO: Readonly<Record<string, CostModel>>;
+/**
+ * The list price for a model on the day of the request, or `undefined` when
+ * the catalogue has no price for it in force that day.
+ *
+ * @param model the id as the caller passes it, with or without a vendor prefix.
+ * @param at when the request was made (epoch ms or a `Date`); defaults to now.
+ *   Prices resolve per UTC day, so a price change the provider has announced
+ *   applies from its effective date.
+ */
+declare function precioDeLista(model: string, at?: Date | number): CostModel | undefined;
+
+/**
+ * The version the SDK reports for itself.
+ *
+ * Written by hand and deliberately NOT read from package.json: the published
+ * bundle does not ship package.json, so a `require` here would fail at runtime
+ * 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 = "1.1.0";
+
 /**
  * Typed intermediate representation for LLM -> LLM handoffs.
  *
@@ -1981,8 +2037,8 @@ declare class CalibrationStateError extends Error {
  */
 type AnswerJudge = (stored: CachedAnswer, fresh: CachedAnswer) => boolean | Promise<boolean>;
 /**
- * Opt-in calibration of the semantic cache: instead of a fixed acceptance floor,
- * the cache serves a reworded request only at or above a floor that labeled
+ * Calibration required for semantic reuse: the cache serves a reworded request
+ * only at or above a floor that labeled
  * traffic has certified, so that at most `maxErrorRate` of the reuses served
  * from that floor up are wrong, at the stated `confidence`.
  *
@@ -2053,6 +2109,8 @@ interface SemanticCalibrationState {
     verifier: string | null;
     /** `built_in:<version>` for {@link sameAnswer}, `custom:<judgeId>` for yours. */
     judge: string;
+    /** Storage backend whose observations produced this state; absent in states written before backend identities. */
+    backend?: string;
     config: {
         maxErrorRate: number;
         confidence: number;
@@ -2137,7 +2195,8 @@ declare function calibrateSemanticFloor(observations: readonly CalibrationObserv
  * question. Therefore the headline metric here is NOT hit ratio — it is the
  * PRECISION of hits. Every candidate must pass: tenant/permission filter,
  * knowledge-epoch filter, a similarity threshold, a stronger local verifier, a
- * freshness check, and an output-contract compatibility check.
+ * freshness check, an output-contract compatibility check, and a certified
+ * calibration floor. Without calibration the cache is shadow-only and serves nothing.
  */
 interface EmbeddingFn {
     (text: string): Promise<number[]> | number[];
@@ -2151,6 +2210,8 @@ interface SemanticVerifier {
     (query: string, candidateQuery: string): Promise<number> | number;
 }
 interface SemanticRecord {
+    /** Stable backend identifier, when the store assigns one. */
+    recordId?: string;
     embedding: number[];
     query: string;
     answer: CachedAnswer;
@@ -2237,6 +2298,8 @@ interface SemanticHit {
  */
 interface SemanticProbe {
     reason: "calibrating" | "below_floor" | "record_floor" | "audit";
+    /** Stable backend identifier for this observation, when the store assigns one. */
+    observationId?: string;
     /** The score the decision was made on: the lower of similarity and your verifier's score. */
     score: number;
     segment: "single_shot" | "agentic";
@@ -2247,6 +2310,15 @@ interface SemanticLookup {
     hit: SemanticHit | null;
     probe: SemanticProbe | null;
 }
+/** Structural contract required by the pipeline; backends may add persistence and lifecycle methods. */
+interface SemanticCacheStore {
+    readonly calibrated: boolean;
+    lookup(c: CanonicalRequest, opts?: {
+        agentic?: boolean;
+    }): Promise<SemanticLookup>;
+    store(c: CanonicalRequest, answer: CachedAnswer): Promise<void>;
+    observe(probe: SemanticProbe, fresh: CachedAnswer): Promise<boolean | null>;
+}
 interface SemanticCacheOptions {
     /**
      * How text becomes a vector. OPTIONAL: omit it and {@link localEmbedding} is
@@ -2280,15 +2352,16 @@ interface SemanticCacheOptions {
     verifierId?: string;
     /** Cosine similarity floor for a candidate to be considered at all. */
     similarityThreshold?: number;
-    /** Verifier score floor for acceptance. */
+    /** Explicit verifier score floor applied in addition to the certified floor. */
     acceptThreshold?: number;
     ttlMs?: number;
     maxRecords?: number;
     now?: () => number;
     /**
-     * Opt-in: replace the fixed acceptance floor with one your own labeled
-     * traffic certifies for a wrong-reuse rate you choose. Off by default. See
-     * {@link SemanticCalibrationOptions}.
+     * Required to serve semantic hits: your own labeled traffic certifies a floor
+     * for a wrong-reuse rate you choose. Without it the cache is shadow-only and
+     * may store answers, but {@link find} and {@link lookup} never return a hit.
+     * See {@link SemanticCalibrationOptions}.
      */
     calibration?: SemanticCalibrationOptions;
 }
@@ -2298,7 +2371,7 @@ interface SemanticCacheOptions {
  * to the store. The verification logic — the part that makes it *safe* — stays
  * identical regardless of the backend.
  */
-declare class InMemorySemanticCache {
+declare class InMemorySemanticCache implements SemanticCacheStore {
     private readonly records;
     private readonly embed;
     private readonly verify;
@@ -2309,7 +2382,7 @@ declare class InMemorySemanticCache {
     private readonly now;
     private readonly embebedorPropio;
     private readonly calibracion;
-    private readonly estados;
+    private readonly diario;
     private readonly nombres;
     private readonly pendientes;
     private readonly aceptacionExplicita;
@@ -2321,21 +2394,22 @@ declare class InMemorySemanticCache {
      * FIRST and hard — a candidate from another tenant, scope, or knowledge epoch
      * is never even scored.
      *
-     * With calibration on, it returns only a hit served under a certified floor
-     * and labels nothing: without {@link lookup} and {@link observe} (the layer
-     * calls both) the calibration never gets a label and never certifies.
+     * Only a certified calibration floor can authorize a hit. Without calibration
+     * this always returns null, including for direct callers. It labels nothing:
+     * without {@link lookup} and {@link observe} (the layer calls both) the
+     * calibration never gets a label and never certifies.
      */
     find(c: CanonicalRequest): Promise<SemanticHit | null>;
     /**
      * The best candidate that passes every hard filter, the similarity floor and
-     * the fact guard. With `conAceptacion`, also the confidence floor (the path
-     * without calibration, unchanged); without it, calibration decides.
+     * the fact guard. Calibration decides whether it can be served.
      */
     private mejorCandidata;
     /**
      * Like {@link find}, and with calibration on it also returns the candidate it
      * did not serve, so the caller can label it with {@link observe} once the
-     * provider has answered. Without calibration, `probe` is always null.
+     * provider has answered. Without calibration, both `hit` and `probe` are null:
+     * stored answers remain available for future calibration but are never served.
      *
      * `agentic` picks the traffic segment: calibrations are kept apart for
      * single-shot and agentic requests.
@@ -2387,7 +2461,6 @@ declare class InMemorySemanticCache {
      */
     importCalibration(state: SemanticCalibrationState | string | unknown): void;
     private identidad;
-    private estadoDe;
     store(c: CanonicalRequest, answer: CachedAnswer): Promise<void>;
     /** Drop every record for a knowledge epoch (invalidation on re-index). */
     invalidateEpoch(knowledgeEpoch: string): number;
@@ -2774,6 +2847,12 @@ interface ConstraintPlan {
 /** A permissive backend used when the provider validates structured output natively. */
 declare function providerNativeBackend(isSupported?: (model: string, schema: JsonSchema) => boolean): ConstraintBackend;
 
+/** Durable, asynchronous memory for value constraints learned from prior responses. */
+interface ConstraintMemoryStore {
+    has(key: string): Promise<boolean>;
+    remember(key: string): Promise<void>;
+}
+
 /**
  * Context compression, as an OPTIONAL sidecar.
  *
@@ -2861,6 +2940,17 @@ interface ToolOutputCompactionSettings {
      * would not match the file on disk.
      */
     compactFileViews?: boolean;
+    /**
+     * `"lossless-data"`: run only the JSON transformation, under a strict check.
+     * The output must be strict JSON (RFC 8259) with no duplicate key at any
+     * depth, and the compacted text must have exactly the same lexemes as the
+     * original — same strings with the same escapes, same number literals, same
+     * key order — with only insignificant whitespace removed. It is applied only
+     * when it is also strictly smaller in estimated tokens. `transforms` is
+     * ignored. Every tool output gets an explained decision. Default: unset (the
+     * four transformations, as before).
+     */
+    profile?: "lossless-data";
 }
 /** The outcome of compacting one tool output. */
 interface ToolOutputCompaction {
@@ -2873,7 +2963,39 @@ interface ToolOutputCompaction {
     compactChars: number;
     /** Why the output was, or was not, compacted. */
     reason: string;
+    /**
+     * Only with `profile: "lossless-data"`: the explained decision, with a stable
+     * reason code. Token counts are estimates from the estimator in use, never a
+     * verified saving.
+     */
+    decision?: ToolOutputDecision;
 }
+/**
+ * Why a `lossless-data` decision went the way it did. `applied`: whitespace
+ * removed. Bypass codes: `not_json` (the output is not a JSON object or array),
+ * `invalid_json` (it looks like one but is not strict JSON), `duplicate_keys`,
+ * `invalid_unicode` (an unpaired surrogate), `not_smaller` (no fewer tokens),
+ * `below_threshold` (fewer than `minSavedChars` removed), `protected` (a file
+ * view or an excepted tool).
+ */
+type ToolOutputDecisionReason = "applied" | "not_json" | "invalid_json" | "duplicate_keys" | "invalid_unicode" | "not_smaller" | "below_threshold" | "protected";
+/** One explained decision of the `lossless-data` profile. */
+interface ToolOutputDecision {
+    status: "applied" | "bypassed";
+    reason: ToolOutputDecisionReason;
+    transformId: typeof LOSSLESS_JSON_TRANSFORM_ID;
+    version: typeof LOSSLESS_JSON_VERSION;
+    /** Estimated tokens of the original output. */
+    tokensBefore: number;
+    /** Estimated tokens of what is sent: the compacted text when applied, the original otherwise. */
+    tokensAfter: number;
+    /** Estimated tokens of the compacted candidate, when one was built (also when bypassed). */
+    candidateTokens?: number;
+}
+/** Id of the `lossless-data` transformation, as it appears in a decision. */
+declare const LOSSLESS_JSON_TRANSFORM_ID = "json-lossless";
+/** Version of that transformation. A change of output for the same input bumps it. */
+declare const LOSSLESS_JSON_VERSION = "1";
 /** Default minimum saving, in characters, for an output to be compacted. */
 declare const DEFAULT_MIN_SAVED_CHARS = 256;
 /**
@@ -2889,8 +3011,11 @@ declare const DEFAULT_MIN_SAVED_CHARS = 256;
  * is produced, before you append it to your conversation history, and the
  * history itself holds the compacted text — the provider's prefix cache is
  * never disturbed.
+ *
+ * `countTokens` is used only by the `lossless-data` profile, for its token
+ * gate; without it the built-in heuristic estimator counts.
  */
-declare function compactToolOutput(text: string, settings?: ToolOutputCompactionSettings): ToolOutputCompaction;
+declare function compactToolOutput(text: string, settings?: ToolOutputCompactionSettings, countTokens?: (text: string) => number): ToolOutputCompaction;
 
 /** What the layer needs to know about a provider's prefix cache to price a decision. */
 interface CacheTier {
@@ -3348,6 +3473,12 @@ interface SavingsLayerConfig {
      * Solo guarda identificadores de contrato, nunca contenido de peticiones.
      */
     constraintMemory?: Set<string>;
+    /**
+     * Optional durable backend. The local Set remains a write-through cache, so
+     * both options compose. Durable keys also include tenant, scope, provider and
+     * served model; store failures never repeat a provider call.
+     */
+    constraintMemoryStore?: ConstraintMemoryStore;
     provider: Provider;
     tokenizer: TokenizerRegistry;
     exactCache?: ExactCache;
@@ -3363,7 +3494,7 @@ interface SavingsLayerConfig {
      * the per-request switch (`savings.semanticCache`) no longer share a name.
      * See the 0.5 migration guide.
      */
-    semanticCacheStore?: InMemorySemanticCache;
+    semanticCacheStore?: SemanticCacheStore;
     /**
      * Default for `savings.semanticCache` on every request of this layer. A
      * request's own value always wins, `false` included. Unset, the semantic cache
@@ -3814,6 +3945,16 @@ interface BatchSubmitOptions {
      * OpenAI, by model).
      */
     maxRequestsPerBatch?: number;
+    /**
+     * Deduplicate requests whose final provider body is byte-identical within THIS
+     * submission: the first is sent and the rest are replayed from its result, so the
+     * provider bills each unique request once. Defaults to false. Only turn it on when
+     * identical bodies imply identical answers — deterministic sampling (temperature 0 or
+     * unset), or a seed you control. With temperature > 0 and no seed the provider would
+     * have sampled each copy independently, and deduplication hands every copy the first
+     * one's answer.
+     */
+    deduplicate?: boolean;
     /** Cancels the HTTP calls of this submission. Batches already created stay created. */
     signal?: AbortSignal;
 }
@@ -3843,6 +3984,17 @@ interface BatchJob {
         batch: number;
         schema?: number;
     }[];
+    /**
+     * Requests that were NOT sent because an identical one (same final provider body) was
+     * already in this submission. Each entry names its own id, the id it duplicates, and
+     * its model. `results()` replays the duplicate from the source's result; nothing about
+     * the answer is stored here. Present only when at least one request was deduplicated.
+     */
+    duplicates?: {
+        customId: string;
+        sameAs: string;
+        model: string;
+    }[];
     /** The distinct output schemas of the job, stored once each. */
     schemas: JsonSchema[];
 }
@@ -3932,6 +4084,8 @@ interface BatchSummary {
     missing: number;
     /** Requests whose provider batch has not ended yet: not in `items`. */
     pending: number;
+    /** Requests dropped at submit() because an identical one was already in the job. */
+    deduplicated?: number;
     /** Succeeded requests with a `tierSaving`. */
     credited: number;
     /** Sum of every `tierSaving.amount`. Never more than the sum of each request's published difference. */
@@ -4118,6 +4272,35 @@ declare function localEmbedding(text: string): number[];
  */
 declare const LOCAL_EMBEDDING_THRESHOLD = 0.72;
 
+interface SemanticCalibrationIdentity {
+    embedder: string;
+    verifier: string | null;
+    judge: string;
+    maxErrorRate: number;
+    confidence: number;
+    similarityThreshold: number;
+    backend?: string;
+}
+/** Pure, shared online calibration state, without storage or I/O. */
+declare class SemanticCalibrationJournal {
+    private readonly identity;
+    private readonly estados;
+    constructor(identity: SemanticCalibrationIdentity);
+    floorIndex(segment: SemanticProbe["segment"]): number | null;
+    record(segment: SemanticProbe["segment"], score: number, correct: boolean): void;
+    status(segment: SemanticProbe["segment"]): SemanticCalibrationStatus;
+    export(): SemanticCalibrationState;
+    import(state: unknown): void;
+    private estadoDe;
+}
+
+/** Shared deterministic safety operations for semantic-cache backends. */
+declare class SemanticCacheSafety {
+    static cosine(a: number[], b: number[]): number;
+    static keyTokensMatch(query: string, candidateQuery: string): boolean;
+    static sameAnswer(stored: CachedAnswer, fresh: CachedAnswer): boolean;
+}
+
 /**
  * Conversational memory by deltas.
  *
@@ -4647,7 +4830,7 @@ declare class LicenseError extends Error {
 
 /** The public handle returned by {@link createSavingsLayer}. */
 interface SavingsLayer {
-    generate<T = unknown>(request: SavingsRequest): Promise<SavingsResult<T>>;
+    generate<T = unknown>(request: SavingsRequest, options?: SavingsRequestOptions): Promise<SavingsResult<T>>;
     /**
      * Same request as generate(), delivered as a stream of events.
      *
@@ -4679,13 +4862,13 @@ interface SavingsLayer {
      */
     readonly batches: SavingsBatches;
     /**
-     * Stop the background revocation poller (when the online call-home was enabled
-     * 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.
+     * Stop background work, drain usage batches and await a semantic store's
+     * optional `settled()` method last. Backends should handle their own expected
+     * observation failures; an unexpected `settled()` rejection is propagated
+     * after the other components have closed rather than silently discarded.
+     * Calling close() without await preserves fire-and-forget shutdown behavior.
      */
-    close(): void;
+    close(): void | Promise<void>;
 }
 /**
  * Create a savings layer. The only hard requirement is a `provider`; a default
@@ -4694,14 +4877,16 @@ 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.
+ * Open core: no `licenseKey` is needed. Without one the layer runs on the
+ * COMMUNITY gate — every local saving lever on, zero telemetry, zero network.
+ * A `licenseKey` (from savings.bivelio.com) turns on the paid surfaces: cloud
+ * metering, license renewal/revocation and org entitlements. An INVALID or
+ * EXPIRED key still fails closed with {@link LicenseError}; only its absence is
+ * a working product.
  *
  * @example
- * // `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 });
+ * // No license: full savings, no telemetry.
+ * const layer = createSavingsLayer({ provider });
  * const { text, report } = await layer.generate({
  *   model: "openai/gpt-4o-mini",
  *   messages: [{ role: "user", content: "What is 2 + 2 * 3?" }],
@@ -4709,6 +4894,17 @@ interface SavingsLayer {
  */
 declare function createSavingsLayer(configPublica: Omit<SavingsLayerConfig, "tokenizer"> & Partial<Pick<SavingsLayerConfig, "tokenizer">>): SavingsLayer;
 
+/**
+ * The total request deadline expired. No partial result or zero-cost report is
+ * returned: tokens already sent to the provider may still appear on its invoice.
+ */
+declare class RequestTimeoutError extends Error {
+    readonly code = "REQUEST_TIMEOUT";
+    /** True when at least one provider request had already been sent. */
+    readonly requestSent: boolean;
+    readonly timeoutMs: number;
+    constructor(requestSent: boolean, timeoutMs: number);
+}
 /**
  * Rejection of `SavingsStream.result` when the stream was aborted before the
  * provider finished its answer. Nothing was cached and no usage was recorded.
@@ -5108,9 +5304,12 @@ declare function toCsv(rows: readonly Readonly<Record<string, CsvValue>>[], opti
 /**
  * bivelio-savings-layer (BV-SALA)
  * ---------------------------------------------------------------------------
- * PROPRIETARY AND CONFIDENTIAL. Copyright (c) 2026 BiVelio Inc.
- * All Rights Reserved. Unauthorized copying, distribution, or use of this
- * software, in whole or in part, is strictly prohibited. See LICENSE.
+ * Copyright (c) 2026 BiVelio Inc.
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ * use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0 — the full
+ * text ships in this repository's LICENSE file. The optional BiVelio cloud
+ * services keep their own terms in LICENSE-CLOUD.md.
  * ---------------------------------------------------------------------------
  *
  * A provider-neutral LLM execution optimizer. For every request it answers, in
@@ -5137,4 +5336,4 @@ declare const listPrice: typeof precioDeLista;
 /** When the catalogue prices were last checked against the providers' public rates (YYYY-MM-DD). */
 declare const PRICES_AS_OF: typeof PRECIOS_AL_DIA;
 
-export { type AnswerJudge, type AnswerSource, type AnthropicOptions, AnthropicProvider, BV_SALA_VERSION, type BatchCounts, type BatchItemResult, type BatchJob, type BatchJobStatus, type BatchRequest, type BatchResults, BatchSubmitError, type BatchSubmitOptions, type BatchSummary, type BivelioHandoff, COMPACTION_TRANSFORMS, COMPACT_ROWS_INSTRUCTION, type CacheBreakpointStore, type CacheOutcome, type CachePlacement, type CacheTier, type CacheWriteReport, type CachedAnswer, type CalibrationObservation, CalibrationStateError, type ChatMessage, type CompactRowsDecodeOptions, type CompactRowsOptions, type CompactionTransform, type CompressionEconomics, type CompressionPolicyInput, type CompressionRequest, type CompressionResult, type Compressor, type ConstraintBackend, type ConstraintBackendId, type ConstraintPlan, type ConversationState, type CostBasis, type CostModel, type CsvValue, DEFAULT_COST_MODEL, DEFAULT_MIN_SAVED_CHARS, type DeferredExecutionReport, type DeterministicResolver, type EmbeddingFn, type EvidenceDoc, type ExactCache, ExactTokenizer, type ExecutionClass, ExecutionRouter, type FocusExportOptions, type FocusRow, type FormatChoice, FormatSelector, type FormatSelectorOptions, type GoogleOptions, GoogleProvider, type GoogleThinkingConfig, type HandoffFact, HeuristicEstimator, InMemoryCacheBreakpointStore, InMemoryExactCache, InMemorySemanticCache, InMemoryToolSetFreezer, type JsonSchema, LOCAL_EMBEDDING_THRESHOLD, type LangfuseGenerationUpdate, LicenseError, type LicenseGate, type LicenseKeyset, type LocalClassifier, MODELS_BY_ENCODING, type MeasureReport, type MemoryDelta, type MessageRole, MockProvider, type MockProviderOptions, type ModelCascadeMode, type ModelCascadeReport, type ModelCascadeSettings, type NativeSavingsReport, type OpenAICompatibleOptions, OpenAICompatibleProvider, type OutputContract, PRICES_AS_OF, PRICE_CATALOG, type Policy, type PriceLeverSaving, type PriceLeverSettings, type ProtectedSpan, type Provider, type ProviderRequest, type ProviderResponse, type ProviderStreamEvent, type ProviderStreamOptions, type ProviderToolSearch, type ProviderToolSearchUsage, type ProviderUsage, QUALITY_STATUSES, type QualityCacheMatch, type QualityCascadeCheck, type QualityLedger, type QualityRepairCheck, type QualitySchemaCheck, type QualityStatus, type QualityTruncationCheck, type ReasoningEffort, type ReferenceCredit, type ReferenceRejection, type RequestContext, type Reranker, ResolverRegistry, type ResolverResult, type RetrievalOptions, type RetrievalOutcome, type RetrievalPlan, type Retriever, type RouteDecision, type SavingsAdapterLevers, type SavingsAdapterOptions, type SavingsAttributeOptions, type SavingsBatches, type SavingsCallOptions, type SavingsLayer, type SavingsLayerConfig, type SavingsRecord, type SavingsReport, type SavingsReportForExport, type SavingsRequest, type SavingsResult, type SavingsSeriesOptions, type SavingsSeriesRow, type SavingsSpanAttributes, type SavingsSpanOptions, type SavingsStream, type SavingsStreamEvent, type SavingsStreamOptions, type SavingsToggles, type SavingsTracingOptions, SchemaRegistry, type SemanticCacheOptions, type SemanticCalibrationBound, type SemanticCalibrationOptions, type SemanticCalibrationSegmentState, type SemanticCalibrationState, type SemanticCalibrationStatus, type SemanticHit, type SemanticLookup, type SemanticProbe, type SemanticRecord, type SemanticVerifier, type SerializationFormat, type Serializer, Singleflight, type SpanAttributeValue, type SpanLike, type SpanStartOptionsLike, StreamAbortedError, type StreamingReport, type TokenEstimator, TokenizerRegistry, type ToolCallRequest, type ToolDescriptor, type ToolOutputCompaction, type ToolOutputCompactionSettings, type ToolRisk, type ToolSearchMode, type ToolSearchOptions, type ToolSelection, ToolSelector, type ToolSelectorOptions, type ToolSetFreezer, type TraceEvent, type TracerLike, type TracerProviderLike, type ValidationError, type ValidationResult, type VerificationCheck, type VerificationExclusion, type VerificationOutcome, type VerificationReport, type VerificationSettings, type VerificationSide, type VerificationStratum, arithmeticResolver, calibrateSemanticFloor, compactRowsSerializer, compactToolOutput, createCompactRowsSerializer, createDefaultResolvers, createHandoff, createMockProvider, createSavingsLayer, csvSerializer, decodeCompactRows, defaultTokenizerRegistry, emptyState, encodeCompactRows, heuristicEstimator, instrumentSavingsLayer, jsonCompactSerializer, listPrice, localEmbedding, mergeDelta, noopCompressor, providerNativeBackend, recordSavingsOnSpan, registerExactTokenizer, renderState, savingsSpanAttributes, toCsv, toFocusRows, toLangfuseGeneration, toSavingsSeries, validateAgainstSchema };
+export { type AnswerJudge, type AnswerSource, type AnthropicOptions, AnthropicProvider, BV_SALA_VERSION, type BatchCounts, type BatchItemResult, type BatchJob, type BatchJobStatus, type BatchRequest, type BatchResults, BatchSubmitError, type BatchSubmitOptions, type BatchSummary, type BivelioHandoff, COMPACTION_TRANSFORMS, COMPACT_ROWS_INSTRUCTION, type CacheBreakpointStore, type CacheOutcome, type CachePlacement, type CacheTier, type CacheWriteReport, type CachedAnswer, type CalibrationObservation, CalibrationStateError, type ChatMessage, type CompactRowsDecodeOptions, type CompactRowsOptions, type CompactionTransform, type CompressionEconomics, type CompressionPolicyInput, type CompressionRequest, type CompressionResult, type Compressor, type ConstraintBackend, type ConstraintBackendId, type ConstraintMemoryStore, type ConstraintPlan, type ConversationState, type CostBasis, type CostModel, type CsvValue, DEFAULT_COST_MODEL, DEFAULT_MIN_SAVED_CHARS, type DeferredExecutionReport, type DeterministicResolver, type EmbeddingFn, type EvidenceDoc, type ExactCache, ExactTokenizer, type ExecutionClass, ExecutionRouter, type FocusExportOptions, type FocusRow, type FormatChoice, FormatSelector, type FormatSelectorOptions, type GoogleOptions, GoogleProvider, type GoogleThinkingConfig, type HandoffFact, HeuristicEstimator, InMemoryCacheBreakpointStore, InMemoryExactCache, InMemorySemanticCache, InMemoryToolSetFreezer, type JsonSchema, LOCAL_EMBEDDING_THRESHOLD, type LangfuseGenerationUpdate, LicenseError, type LicenseGate, type LicenseKeyset, type LocalClassifier, MODELS_BY_ENCODING, type MeasureReport, type MemoryDelta, type MessageRole, MockProvider, type MockProviderOptions, type ModelCascadeMode, type ModelCascadeReport, type ModelCascadeSettings, type NativeSavingsReport, type OpenAICompatibleOptions, OpenAICompatibleProvider, type OutputContract, PRICES_AS_OF, PRICE_CATALOG, type Policy, type PriceLeverSaving, type PriceLeverSettings, type ProtectedSpan, type Provider, type ProviderRequest, type ProviderResponse, type ProviderStreamEvent, type ProviderStreamOptions, type ProviderToolSearch, type ProviderToolSearchUsage, type ProviderUsage, QUALITY_STATUSES, type QualityCacheMatch, type QualityCascadeCheck, type QualityLedger, type QualityRepairCheck, type QualitySchemaCheck, type QualityStatus, type QualityTruncationCheck, type ReasoningEffort, type ReferenceCredit, type ReferenceRejection, type RequestContext, RequestTimeoutError, type Reranker, ResolverRegistry, type ResolverResult, type RetrievalOptions, type RetrievalOutcome, type RetrievalPlan, type Retriever, type RouteDecision, type SavingsAdapterLevers, type SavingsAdapterOptions, type SavingsAttributeOptions, type SavingsBatches, type SavingsCallOptions, type SavingsLayer, type SavingsLayerConfig, type SavingsRecord, type SavingsReport, type SavingsReportForExport, type SavingsRequest, type SavingsRequestOptions, type SavingsResult, type SavingsSeriesOptions, type SavingsSeriesRow, type SavingsSpanAttributes, type SavingsSpanOptions, type SavingsStream, type SavingsStreamEvent, type SavingsStreamOptions, type SavingsToggles, type SavingsTracingOptions, SchemaRegistry, type SemanticCacheOptions, SemanticCacheSafety, type SemanticCacheStore, type SemanticCalibrationBound, type SemanticCalibrationIdentity, SemanticCalibrationJournal, type SemanticCalibrationOptions, type SemanticCalibrationSegmentState, type SemanticCalibrationState, type SemanticCalibrationStatus, type SemanticHit, type SemanticLookup, type SemanticProbe, type SemanticRecord, type SemanticVerifier, type SerializationFormat, type Serializer, Singleflight, type SpanAttributeValue, type SpanLike, type SpanStartOptionsLike, StreamAbortedError, type StreamingReport, type TokenEstimator, TokenizerRegistry, type ToolCallRequest, type ToolDescriptor, type ToolOutputCompaction, type ToolOutputCompactionSettings, type ToolRisk, type ToolSearchMode, type ToolSearchOptions, type ToolSelection, ToolSelector, type ToolSelectorOptions, type ToolSetFreezer, type TraceEvent, type TracerLike, type TracerProviderLike, type ValidationError, type ValidationResult, type VerificationCheck, type VerificationExclusion, type VerificationOutcome, type VerificationReport, type VerificationSettings, type VerificationSide, type VerificationStratum, arithmeticResolver, calibrateSemanticFloor, compactRowsSerializer, compactToolOutput, createCompactRowsSerializer, createDefaultResolvers, createHandoff, createMockProvider, createSavingsLayer, csvSerializer, decodeCompactRows, defaultTokenizerRegistry, emptyState, encodeCompactRows, heuristicEstimator, instrumentSavingsLayer, jsonCompactSerializer, listPrice, localEmbedding, mergeDelta, noopCompressor, providerNativeBackend, recordSavingsOnSpan, registerExactTokenizer, renderState, savingsSpanAttributes, toCsv, toFocusRows, toLangfuseGeneration, toSavingsSeries, validateAgainstSchema };