@bivelio/savings-layer 0.4.0 → 0.4.2

package/README.md

@@ -1,31 +1,61 @@
-# @bivelio/savings-layer — BV‑SALA
+# BV‑SALA — the savings layer for your LLM bill
 
-**A provider‑neutral LLM execution optimizer.** BV‑SALA sits in front of any LLM
-provider and, for every request, picks the **cheapest execution that still meets
-your quality bar** — then hands you a full, auditable `SavingsReport`.
+<p align="center">
+  <img src="https://savings.bivelio.com/en/how-it-works/opengraph-image" alt="Your application → BV-SALA → provider API. The bill drops from $330 to $160 a month, measured." width="720">
+</p>
 
-It is **not** a prompt compressor. Compression is the *fourth* thing it tries, not
-the first.
+<p align="center">
+  <a href="https://www.npmjs.com/package/@bivelio/savings-layer"><img src="https://img.shields.io/npm/v/%40bivelio%2Fsavings-layer?color=2F63D8&label=npm" alt="npm version"></a>
+  <img src="https://img.shields.io/badge/node-%E2%89%A520-14A06F" alt="Node ≥ 20">
+  <img src="https://img.shields.io/badge/license-commercial-0F1218" alt="Commercial license">
+</p>
+
+**One layer inside your code, right where your app calls the OpenAI or Anthropic API.**
+For every request it picks the cheapest execution that still meets your quality bar —
+avoiding calls that don't need to happen and trimming what must be sent — and hands
+you an auditable `SavingsReport`. Your bill drops, and you can verify why.
 
 > **Commercial software — © 2026 BiVelio Inc.** Free to install, **paid to run**:
-> BV‑SALA is **fail‑closed** and executes only with a valid, active BiVelio license
-> key. Verification is **offline** (no phone‑home to answer a request) and **your
-> prompts never leave your infrastructure** — only counts and cost are ever reported.
-> Use is governed by the [LICENSE](./LICENSE) and the BiVelio Terms. Not affiliated
-> with, and not a wrapper around, any third‑party library.
+> BV‑SALA is fail‑closed and executes only with an active BiVelio license key.
+> License checks are **offline** and **your prompts never leave your infrastructure** —
+> only counts and cost are ever reported. Use is governed by the [LICENSE](./LICENSE)
+> and the BiVelio Terms. Not a wrapper around any third‑party library.
+
+## Where it installs
+
+Your application → **BV‑SALA** → provider API. Traffic always goes straight from
+your app to your provider — BV‑SALA is a library inside your code, never a
+middleman server, and it works with any OpenAI‑compatible endpoint (OpenAI, Azure,
+vLLM, SGLang, a gateway) as well as Anthropic.
+
+**Only use ChatGPT or Claude?** Then there is nothing to install: those products
+charge a flat subscription, so there is no per‑token bill to cut. BV‑SALA is for
+applications that call the API with their own key. The whole story, in plain words:
+**[Where does the saving install?](https://savings.bivelio.com/en/how-it-works)**
+
+## Try it before you install
+
+Run the real optimizer **free in your browser** — pick an example or paste your own
+data and watch the meter — at **[savings.bivelio.com](https://savings.bivelio.com)**.
 
-## Install
+## Install in three steps
+
+**1 · The package**
 
 ```bash
 pnpm add @bivelio/savings-layer
 # or: npm i @bivelio/savings-layer  ·  yarn add @bivelio/savings-layer
 ```
 
-You also need a **license key**. Try the optimizer **free in your browser** — paste
-your own data and watch the meter — at **[savings.bivelio.com](https://savings.bivelio.com)**,
-then subscribe (**€4 / seat / month** or **€39 / seat / year**, EUR) to get your key.
+**2 · The license** — from your [dashboard](https://savings.bivelio.com/dashboard/install)
+(**€4 / seat / month** or **€39 / seat / year**, EUR)
+
+```bash
+export BIVELIO_LICENSE_KEY=…   # your license key
+export BIVELIO_SERVICE_KEY=…   # service-account key: auto-renewal + seat metering
+```
 
-## Quick start
+**3 · Wrap the call** — this is the entire code change:
 
 ```ts
 import { createSavingsLayer, OpenAICompatibleProvider } from "@bivelio/savings-layer";
@@ -54,8 +84,30 @@ console.log(report.calls.avoidedLlm); // → whole calls you never paid for
 console.log(report.cost.netSavings);  // → verified savings, per request
 ```
 
-Ask for a **structured contract** and you also get `data`, validated against your
-schema — the JSON-repair and output contracts levers switch on here:
+That's it. From the first request, `report` carries the saving — measured, not
+estimated.
+
+## What you get on every request
+
+A `SavingsReport` with the numbers behind every claim, kept in **four separate
+ledgers** that are never summed into one flattering figure:
+
+| Ledger | Meaning |
+| --- | --- |
+| `avoided_calls` | LLM / retrieval / tool calls that never executed |
+| `eliminated_tokens` | information dropped because it was not needed |
+| `compressed_tokens` | information kept, but encoded with fewer tokens |
+| `provider_cached_tokens` | tokens still in the prompt, billed/processed more cheaply |
+
+And a promise you can hold it to: **never worse than your JSON.** Payload encodings
+are chosen by counting real tokens with the destination model's own tokenizer, and
+BV‑SALA only moves away from plain JSON when the saving clearly clears the bar —
+`report.serialization` shows what was chosen and what each candidate would have cost.
+
+<details>
+<summary><b>Structured output — validated <code>data</code>, not just text</b></summary>
+
+Ask for a response contract and you also get `data`, validated against your schema:
 
 ```ts
 const { data, text } = await layer.generate<{ answer: number }>({
@@ -76,42 +128,10 @@ const { data, text } = await layer.generate<{ answer: number }>({
 console.log(data.answer); // 8
 ```
 
-The hard requirements are a `provider` and a valid `licenseKey`: BV‑SALA is a paid
-product and **refuses to run unlicensed, expired, or tampered** (it throws
-`LicenseError` at the `generate()` entry, carrying a `status` of `none`,
-`invalid`, `expired`, `grace`, `revoked` or `stale`). Your key — and this snippet
-with the key already filled in — is at
-[savings.bivelio.com/dashboard/install](https://savings.bivelio.com/dashboard/install).
-
-> **Set `serviceAccountKey` on every long‑running deployment.** Your licence token
-> expires at the end of the billing period; each renewal mints a **new** token. With
-> a service‑account key (`bvk_…`, same dashboard) the SDK picks the renewed token up
-> by itself and swaps it in without a restart. **Without it there is no machine
-> pickup**, so somebody has to paste the new token by hand every cycle — and if
-> nobody does, the deployment stops with `LicenseError` once the grace period ends,
-> while the subscription is paid and current. The key also enables seat metering
-> (counts only — never prompts or completions).
-
-### Seats (how you are billed)
-
-A **seat is a machine**, never a person. The SDK derives a stable, opaque id per
-machine + service-account key and reports it with the counts; the control plane
-bills a seat only once it has been seen on **3 separate days**.
-
-**Set `BVSALA_SEAT_ID` (one value per replica or service) whenever the machine
-identity can't be deduced** — Kubernetes, or any fleet where the hostname is
-assigned dynamically. Without it, every pod of a deployment shares one fingerprint
-and the whole deployment counts as a **single** seat. It is also the way to keep
-seat ids stable across an SDK upgrade: the fingerprint changed in v0.1.x, so a
-fleet that never set it may be counted twice in the month it upgrades.
-
-```bash
-BVSALA_SEAT_ID=worker-03   # stable per replica; [A-Za-z0-9._:/-], max 128 chars
-```
-
-CI runners are auto-detected and excluded from billable seats.
+</details>
 
-### Tool calls
+<details>
+<summary><b>Tool calls</b></summary>
 
 When you pass `tools` and the model asks to invoke one, the reply is not the final
 answer: `text` is empty by design and the request is in `toolCalls`. Execute it,
@@ -155,92 +175,45 @@ if (res.toolCalls?.length) {
 A tool‑call turn is never served from cache and never counted as an avoided call:
 an action that has not run yet cannot be a saving.
 
-> The `devUnlicensed` flag and `BVSALA_DEV_OPEN=1` are development‑only, honored
-> **only when building from source** (this repo's tests and benchmarks). They are
-> **disabled in this published package** — a valid `licenseKey` is the only way to
-> run it. They are not a way to use the product for free.
-
-Every component ships with an in‑memory default and is independently swappable:
-plug in your own cache, vector store, tokenizer, compressor or constraint backend
-behind the same interfaces.
-
-## The optimization order (cheapest first)
+</details>
 
-1. **Avoid the call entirely** when the answer can be produced or reused safely.
-2. **Avoid auxiliary calls** — the retrievals, tool hops and retries around it.
-3. **Eliminate unnecessary context** before trying to shrink what remains.
-4. **Shrink** the tokens that genuinely must be sent.
-5. **Constrain generation** to emit only the structure and length required.
+<details>
+<summary><b>Running a fleet? Seats and renewals</b></summary>
 
-The order is the point: work removed at step 1 costs nothing to compress at step 4.
+- **A seat is a machine, never a person.** A seat is billed only once it has been
+  seen on 3 separate days, and CI runners are auto‑detected and excluded.
+- **Set `serviceAccountKey` on every long‑running deployment.** Renewals mint a new
+  license token each billing period; with the service‑account key (`bvk_…`, same
+  dashboard) the SDK picks the renewed token up by itself, without a restart.
+- **Set `BVSALA_SEAT_ID` (one stable value per replica) on Kubernetes or any fleet
+  with dynamic hostnames**, so each replica counts as what it is:
 
-Provider prompt/KV caching is treated as a cost/latency saving — **never** as a
-reduction of the logical prompt size.
-
-## Four separate ledgers (never summed)
-
-Mixing these produces misleading metrics, so BV‑SALA keeps them apart:
-
-| Ledger | Meaning |
-| --- | --- |
-| `avoided_calls` | LLM / retrieval / tool calls that never executed |
-| `eliminated_tokens` | information dropped because it was not needed |
-| `compressed_tokens` | information kept, but encoded with fewer tokens |
-| `provider_cached_tokens` | tokens still in the prompt, billed/processed more cheaply |
-
-A cache hit removes a whole call. A re‑encode makes a payload smaller. Compression
-drops redundant words. A prefix cache makes tokens cheaper without removing them.
-Four different things — summing them would lie to you, so the report never does.
-
-## The decision cascade
-
-```
-Request
-  → Canonicalize + Policy (risk & freshness)
-  → Deterministic resolvers ─────────────► answer (0 calls)
-  → Exact cache ─────────────────────────► answer (0 calls)
-  → Concurrent duplicates coalesced ─────► answer (0 calls)
-      → Near-duplicate reuse ────────────► answer (0 calls)
-      → Execution planning (how much work this really needs)
-      → Context reduction (only when it pays for itself)
-      → Payload encoding chosen by measurement, not by default
-      → Output contract enforced
-      → ONE primary LLM call
-      → Structural + semantic validation (+ ≤1 repair)
-      → Local render / transcode / cache write
-  → SavingsReport + traces
+```bash
+BVSALA_SEAT_ID=worker-03   # stable per replica; [A-Za-z0-9._:/-], max 128 chars
 ```
 
-## Why formats are chosen, not assumed
-
-A compact encoding can be *larger* than plain JSON on nested or non‑uniform data,
-so BV‑SALA never assumes one. It counts the candidates with the destination
-model's own tokenizer — including the cost of explaining the encoding to the
-model — and only moves away from JSON when the saving clears a margin worth the
-change.
-
-On a wide, uniform table that is a large reduction. On a small nested object it
-leaves JSON alone. Whichever it picks, `report.serialization` tells you what was
-chosen and what each candidate would have cost, so the decision is auditable
-rather than promised.
+</details>
 
-## What's inside
+<details>
+<summary><b>Requirements</b></summary>
 
-Safe cache keys and a risk/freshness policy · several independent ways to answer
-without spending a call · execution planning · context reduction that must pay for
-itself · measured payload encoding · output contracts with validation · a
-provider‑neutral adapter · and a trace collector that builds the `SavingsReport`.
+- **Node ≥ 20.** The package is **ESM‑only** (`"type": "module"`); from CommonJS,
+  `require()` works on Node ≥ 22.
+- Optional peer `gpt-tokenizer` for exact OpenAI token counts — without it a
+  built‑in estimator is used, so it is not required to get started.
+- Every component (cache, vector store, tokenizer, compressor, constraint backend)
+  ships with an in‑memory default and is independently swappable behind the same
+  interfaces.
 
-Every piece is pluggable, and every saving it claims is reported per request with
-the token counts behind it.
+</details>
 
 ## Licensing & privacy
 
 BV‑SALA is commercial, per‑seat software (**€4 / seat / month** or **€39 / seat /
 year**, EUR). The license is a signed token your SDK verifies **offline**; the
-managed control plane (semantic cache, learned thresholds, dashboards) and the
-revocation kill‑switch are served from BiVelio. Your LLM traffic goes **straight to
-your provider** — BiVelio sees counts and cost, never prompts or completions.
+managed control plane and the revocation kill‑switch are served from BiVelio. Your
+LLM traffic goes **straight to your provider** — BiVelio sees counts and cost,
+never prompts or completions.
 
 Get a key and read the terms at **[savings.bivelio.com](https://savings.bivelio.com)**.
 Onboarding & general questions: **support@bivelio.com** · licensing & compliance:

package/dist/gateway/bin.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/gateway/bin.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import {spawn}from'child_process';import {createServer}from'http';import {randomUUID,createHash}from'crypto';var te=new Set;function v(t,e){te.has(t)||(te.add(t),console.warn(e));}var w=class{options;now;flushIntervalMs;maxBatch;maxBuffer;buffer=[];seatId;ci;timer;inflight=null;fallosSeguidos=0;constructor(e){this.options=e,this.now=e.now??(()=>Date.now()),this.flushIntervalMs=e.flushIntervalMs??15e3,this.maxBatch=e.maxBatch??50,this.maxBuffer=e.maxBuffer??1e3,this.ci=e.ci??false;}setSeat(e,n){e&&(this.seatId=e),this.ci=n;}record(e){this.buffer.push({report:e,at:this.now()}),this.buffer.length>this.maxBuffer&&this.buffer.splice(0,this.buffer.length-this.maxBuffer),this.buffer.length>=this.maxBatch&&this.flush();}start(){this.timer||(this.timer=setInterval(()=>{this.flush();},this.flushIntervalMs),this.timer.unref?.());}stop(){this.timer&&(clearInterval(this.timer),this.timer=void 0),this.flush();}async stopAndDrain(e){this.timer&&(clearInterval(this.timer),this.timer=void 0);let n=e??Math.ceil(this.maxBuffer/this.maxBatch)+4,r=0;for(let o=0;o<n&&this.buffer.length>0;o++){let s=this.buffer.length;if(await this.flush(),r=this.buffer.length>=s?r+1:0,r>=2)break}}async flush(){if(this.inflight)return this.inflight;if(this.buffer.length!==0){this.inflight=this.hacerFlush();try{await this.inflight;}finally{this.inflight=null;}}}async hacerFlush(){let e=this.options.fetchImpl??globalThis.fetch;if(!e)return;let n=this.buffer.splice(0,this.maxBatch);try{let r=n.map(s=>this.toWire(s)),o=await e(this.options.url,{method:"POST",headers:{"content-type":"application/json",authorization:`Bearer ${this.options.serviceAccountKey}`},body:JSON.stringify(r)});o.ok?this.fallosSeguidos=0:o.status>=500?(this.fallosSeguidos++,this.requeue(n),this.avisarDeFallo(`el servidor respondi\xF3 ${o.status}`)):o.status===401||o.status===403?(v(`metering-auth-${o.status}`,`[bv-sala] el env\xEDo de uso est\xE1 siendo rechazado con HTTP ${o.status} en ${this.options.url}. Revisa 'serviceAccountKey' (\xBFrotada? \xBFrevocada? \xBFde otra organizaci\xF3n?). Mientras no funcione NO se reporta uso: el panel dir\xE1 que no ve tr\xE1fico y los asientos facturables saldr\xE1n a cero.`),this.options.onAuthError?.(o.status)):(this.fallosSeguidos++,this.avisarDeFallo(o.status===404||o.status===405?`HTTP ${o.status}: la URL de env\xEDo parece equivocada`:`el servidor rechaz\xF3 el lote con HTTP ${o.status}`));}catch(r){this.fallosSeguidos++,this.requeue(n),this.avisarDeFallo(r instanceof Error?r.message:"error de red");}}avisarDeFallo(e){if(this.options.silenceWarnings)return;let n=this.fallosSeguidos;n<3||(n-3)%12!==0||console.warn(`[bv-sala] el env\xEDo de uso lleva ${n} intentos seguidos fallando contra ${this.options.url} (${e}). Las peticiones SIGUEN funcionando, pero el uso no est\xE1 llegando: el panel dir\xE1 que no ve tr\xE1fico y los asientos facturables saldr\xE1n a cero. Comprueba 'meteringUrl' \u2014 por defecto es \`\${licenseServerUrl}/api/metering/usage\`.`);}requeue(e){this.buffer=[...e,...this.buffer],this.buffer.length>this.maxBuffer&&(this.buffer.length=this.maxBuffer);}toWire(e){let n=e.report;return {orgId:this.options.orgId??"self",...this.seatId?{seatId:this.seatId}:{},...this.ci?{ci:true}:{},requestId:n.requestId,model:n.model,at:e.at,avoidedLlm:n.calls.avoidedLlm,actualLlm:n.calls.actualLlm,baselineInputTokens:n.tokens.baselineInput,actualInputTokens:n.tokens.actualInput,eliminatedInputTokens:n.tokens.eliminatedInput,compressedInputTokens:n.tokens.compressedInput,baselineOutputTokens:n.tokens.baselineOutput,actualOutputTokens:n.tokens.actualOutput,providerCachedInputTokens:n.tokens.providerCachedInput??0,cacheResult:n.cache.result,baselineCost:n.cost.baselineEstimate,actualCost:n.cost.actual,netSavings:n.cost.netSavings,...n.cost.basis?{basis:n.cost.basis}:{}}}};function O(){return globalThis.process}function be(t){if(/^[0-9a-f]{12}$/.test(t)||/^\d{1,3}(\.\d{1,3}){3}$/.test(t)||/^ip-\d{1,3}(-\d{1,3}){3}$/i.test(t))return  true;let e="[bcdfghjklmnpqrstvwxz2456789]";return new RegExp(`-${e}{8,10}-${e}{5}$`).test(t)}function ve(t){return !!(t.AWS_LAMBDA_FUNCTION_NAME??t.LAMBDA_TASK_ROOT??t.VERCEL??t.VERCEL_ENV??t.K_SERVICE??t.FUNCTION_TARGET??t.FUNCTIONS_WORKER_RUNTIME??t.NETLIFY)}async function ye(){if(O()?.execPath)try{let e=await import(["node","os"].join(":")),n=typeof e.hostname=="function"?e.hostname():"";return n.length>0?n:void 0}catch{return}}async function ke(t,e=ye){if(t.KUBERNETES_SERVICE_HOST||ve(t))return;let n=t.HOSTNAME??t.COMPUTERNAME??await e();if(!(!n||be(n)))return n}async function xe(){let t=O();if(!t||!t.env)return;let e=t.env,n=await ke(e),r=[t.platform,t.arch,t.execPath,n,e.USER??e.USERNAME??e.LOGNAME,e.HOME??e.USERPROFILE].filter(o=>typeof o=="string"&&o.length>0);return r.length?r.join("|"):void 0}var we=["CI","CONTINUOUS_INTEGRATION","GITHUB_ACTIONS","GITLAB_CI","CIRCLECI","TRAVIS","JENKINS_URL","BUILDKITE","TF_BUILD","TEAMCITY_VERSION","BITBUCKET_BUILD_NUMBER","CODEBUILD_BUILD_ID","HEROKU_TEST_RUN_ID","DRONE"];function A(){let t=O()?.env;if(!t)return  false;for(let e of we){let n=t[e];if(n&&n!=="false"&&n!=="0")return  true}return  false}async function Se(t,e){let n=globalThis.crypto,r=new TextEncoder;if(n?.subtle)try{let i=await n.subtle.importKey("raw",r.encode(t),{name:"HMAC",hash:"SHA-256"},!1,["sign"]),l=await n.subtle.sign("HMAC",i,r.encode(e));return [...new Uint8Array(l)].map(u=>u.toString(16).padStart(2,"0")).join("")}catch{}let o=2166136261,s=`${t}|${e}`;for(let i=0;i<s.length;i++)o^=s.charCodeAt(i),o=Math.imul(o,16777619);return (o>>>0).toString(16).padStart(8,"0")}async function _(t){let n=O()?.env?.BVSALA_SEAT_ID;if(n&&Te.test(n))return n;let r=await xe();if(!r)return;let o=await Se(t,r);if(o)return `m-${o.slice(0,32)}`}var Te=/^[A-Za-z0-9._:/-]{1,128}$/;var F={"gpt-4.1":{inputPer1k:.002,outputPer1k:.008,cachedInputPer1k:5e-4},"gpt-4.1-mini":{inputPer1k:4e-4,outputPer1k:.0016,cachedInputPer1k:1e-4},"gpt-4.1-nano":{inputPer1k:1e-4,outputPer1k:4e-4,cachedInputPer1k:25e-6},"gpt-4o":{inputPer1k:.0025,outputPer1k:.01,cachedInputPer1k:.00125},"gpt-4o-mini":{inputPer1k:15e-5,outputPer1k:6e-4,cachedInputPer1k:75e-6},"gpt-4-turbo":{inputPer1k:.01,outputPer1k:.03},"gpt-4":{inputPer1k:.03,outputPer1k:.06},"gpt-3.5-turbo":{inputPer1k:5e-4,outputPer1k:.0015},"gpt-5":{inputPer1k:.00125,outputPer1k:.01,cachedInputPer1k:125e-6},"gpt-5-codex":{inputPer1k:.00125,outputPer1k:.01,cachedInputPer1k:125e-6},"gpt-5-mini":{inputPer1k:25e-5,outputPer1k:.002,cachedInputPer1k:25e-6},"gpt-5-nano":{inputPer1k:5e-5,outputPer1k:4e-4,cachedInputPer1k:5e-6},"gpt-5.1-codex":{inputPer1k:.00125,outputPer1k:.01,cachedInputPer1k:125e-6},"gpt-5.1-codex-max":{inputPer1k:.00125,outputPer1k:.01,cachedInputPer1k:125e-6},"gpt-5.1-codex-mini":{inputPer1k:25e-5,outputPer1k:.002,cachedInputPer1k:25e-6},"gpt-5.1-thinking":{inputPer1k:.00125,outputPer1k:.01,cachedInputPer1k:125e-6},"gpt-5.2":{inputPer1k:.00175,outputPer1k:.014,cachedInputPer1k:175e-6},"gpt-5.2-codex":{inputPer1k:.00175,outputPer1k:.014,cachedInputPer1k:175e-6},"gpt-5.3-codex":{inputPer1k:.00175,outputPer1k:.014,cachedInputPer1k:175e-6},"gpt-5.4":{inputPer1k:.0025,outputPer1k:.015,cachedInputPer1k:25e-5},"gpt-5.4-mini":{inputPer1k:75e-5,outputPer1k:.0045,cachedInputPer1k:75e-6},"gpt-5.4-nano":{inputPer1k:2e-4,outputPer1k:.00125,cachedInputPer1k:2e-5},"gpt-5.5":{inputPer1k:.005,outputPer1k:.03,cachedInputPer1k:5e-4},"gpt-5.6-luna":{inputPer1k:2e-4,outputPer1k:.0012,cachedInputPer1k:2e-5},"gpt-5.6-sol":{inputPer1k:.004,outputPer1k:.02,cachedInputPer1k:4e-4},"gpt-5.6-terra":{inputPer1k:.002,outputPer1k:.012,cachedInputPer1k:2e-4},"claude-opus-4-5":{inputPer1k:.005,outputPer1k:.025,cachedInputPer1k:5e-4},"claude-opus-4-6":{inputPer1k:.005,outputPer1k:.025,cachedInputPer1k:5e-4},"claude-opus-4-7":{inputPer1k:.005,outputPer1k:.025,cachedInputPer1k:5e-4},"claude-opus-4-8":{inputPer1k:.005,outputPer1k:.025,cachedInputPer1k:5e-4},"claude-opus-5":{inputPer1k:.005,outputPer1k:.025,cachedInputPer1k:5e-4},"claude-opus-4":{inputPer1k:.015,outputPer1k:.075,cachedInputPer1k:.0015},"claude-sonnet-4-5":{inputPer1k:.003,outputPer1k:.015,cachedInputPer1k:3e-4},"claude-sonnet-4-6":{inputPer1k:.003,outputPer1k:.015,cachedInputPer1k:3e-4},"claude-sonnet-5":{inputPer1k:.002,outputPer1k:.01,cachedInputPer1k:2e-4},"claude-fable-5":{inputPer1k:.01,outputPer1k:.05,cachedInputPer1k:.001},"claude-sonnet-4":{inputPer1k:.003,outputPer1k:.015,cachedInputPer1k:3e-4},"claude-haiku-4-5":{inputPer1k:.001,outputPer1k:.005,cachedInputPer1k:1e-4},"claude-3-5-sonnet":{inputPer1k:.003,outputPer1k:.015,cachedInputPer1k:3e-4},"claude-3-5-haiku":{inputPer1k:8e-4,outputPer1k:.004,cachedInputPer1k:8e-5},"claude-3-opus":{inputPer1k:.015,outputPer1k:.075,cachedInputPer1k:.0015},"claude-3-haiku":{inputPer1k:25e-5,outputPer1k:.00125,cachedInputPer1k:3e-5},"gemini-3.7-flash":{inputPer1k:75e-5,outputPer1k:.00375,cachedInputPer1k:75e-6},"gemini-3.5-flash":{inputPer1k:.0015,outputPer1k:.009,cachedInputPer1k:15e-5},"gemini-3.5-flash-lite":{inputPer1k:3e-4,outputPer1k:.0025,cachedInputPer1k:3e-5},"gemini-3.1-pro-preview":{inputPer1k:.002,outputPer1k:.012,cachedInputPer1k:2e-4},"gemini-2.5-pro":{inputPer1k:.00125,outputPer1k:.01,cachedInputPer1k:125e-6},"gemini-2.5-flash":{inputPer1k:3e-4,outputPer1k:.0025,cachedInputPer1k:3e-5}};function ne(t,e,n){if(!n)return;let r=t[n];if(r)return r;let o=n.lastIndexOf("/"),s=o>=0?n.slice(o+1):n,i=t[s];if(i)return i;for(let l of e)if(s.startsWith(l)){let u=s.charAt(l.length);if(u===""||u==="-"||u==="."||u==="_")return t[l]}}function V(t){return Object.keys(t).sort((e,n)=>n.length-e.length)}var Ce=V(F);function E(t){return ne(F,Ce,t)}var I=class{resto="";uso=null;eventos={};observar(e){this.resto+=typeof e=="string"?e:e.toString("utf8");let n;for(;(n=this.resto.indexOf(`
+
+`))>=0;){let r=this.resto.slice(0,n);this.resto=this.resto.slice(n+2);let o=/^event: (.+)$/m.exec(r)?.[1];if(o&&(this.eventos[o]=(this.eventos[o]??0)+1),o!=="message_start"&&o!=="message_delta")continue;let s=/^data: (.+)$/m.exec(r)?.[1];if(s)try{let i=JSON.parse(s),l=i.usage??i.message?.usage;l&&(this.uso={...this.uso,...l});}catch{}}}usage(){return this.uso}},Re=1.25;function oe(t,e){let n=E(t);if(!n)return null;let r=e.input_tokens??0,o=e.output_tokens??0,s=e.cache_read_input_tokens??0,i=e.cache_creation_input_tokens??0,l=n.cachedInputPer1k??n.inputPer1k;return {costeUsd:r/1e3*n.inputPer1k+s/1e3*l+i/1e3*n.inputPer1k*Re+o/1e3*n.outputPer1k,precio:n,tokens:{entrada:r,salida:o,cacheLeida:s,cacheEscrita:i}}}function re(t,e,n){return ie(t,e,n,false)}function se(t,e,n){return ie(t,e,n,true)}function ie(t,e,n,r){let o=n.tokens.entrada+n.tokens.cacheLeida+n.tokens.cacheEscrita;return {requestId:t,model:e,calls:r?{avoidedLlm:1,actualLlm:0}:{avoidedLlm:0,actualLlm:1},tokens:{baselineInput:o,actualInput:r?0:o,eliminatedInput:0,compressedInput:0,baselineOutput:n.tokens.salida,actualOutput:r?0:n.tokens.salida,providerCachedInput:r?0:n.tokens.cacheLeida},cache:{result:r?"singleflight":"miss"},cost:r?{baselineEstimate:n.costeUsd,actual:0,netSavings:1,basis:"estimated"}:{baselineEstimate:n.costeUsd,actual:n.costeUsd,netSavings:0,basis:"measured"}}}var Ie=5*1024*1024,Pe=["authorization","x-api-key","anthropic-version","anthropic-beta"];function ae(t,e,n,r=""){return createHash("sha256").update(t).update(`
+`).update(e).update(`
+`).update(r).update(`
+`).update(n).digest("hex")}function ce(t){return Pe.map(e=>`${e}=${t(e)??""}`).join(`
+`)}var D=class{enVuelo=new Map;primarias=0;gemelas=0;registrar(e){if(this.enVuelo.has(e))return null;this.primarias+=1;let n,r=new Promise(l=>n=l);this.enVuelo.set(e,{promesa:r,resolver:n});let o=[],s=0,i=false;return {capturar:l=>{if(!i){if(s+=l.length,s>Ie){i=true,o.length=0;return}o.push(l);}},terminar:(l,u)=>{let a=!i&&l>=200&&l<300;this.enVuelo.get(e)?.resolver(a?{status:l,headers:u,chunks:o}:null),this.enVuelo.delete(e);},abortar:()=>{this.enVuelo.get(e)?.resolver(null),this.enVuelo.delete(e);}}}async esperar(e){let n=this.enVuelo.get(e);if(!n)return null;let r=await n.promesa;return r&&(this.gemelas+=1),r}tieneEnVuelo(e){return this.enVuelo.has(e)}};var _e=["content-encoding","content-length","transfer-encoding"];async function le(t={}){let e=(t.upstream??"https://api.anthropic.com").replace(/\/+$/,""),n=t.fetchImpl??fetch,r=t.log??(a=>console.log(a)),o;if(t.serviceAccountKey){o=new w({url:t.meteringUrl??"https://savings.bivelio.com/api/metering/usage",serviceAccountKey:t.serviceAccountKey,...t.fetchImpl?{fetchImpl:t.fetchImpl}:{},onAuthError:c=>v("gateway-ingest-auth",`[bvsala gateway] la ingesta de uso rechaza la credencial (${c}). El tr\xE1fico sigue fluyendo (avisar, nunca romper), pero este uso no est\xE1 llegando al panel. Revisa BIVELIO_SERVICE_KEY y el estado de la suscripci\xF3n en savings.bivelio.com.`)});let a=A();t.seatId?o.setSeat(t.seatId,a):_(t.serviceAccountKey).then(c=>o?.setSeat(c,a)).catch(()=>{}),o.start();}else v("gateway-sin-clave","[bvsala gateway] sin BIVELIO_SERVICE_KEY: el gateway reenv\xEDa el tr\xE1fico pero NO mide. Consigue tu clave en savings.bivelio.com/dashboard/install para ver el gasto en tu panel.");let s=t.coalescer?new D:null,i=(a,c,m,f,g)=>{if(!o||!m)return;let d="";try{d=JSON.parse(c.toString("utf8")).model??"";}catch{}let p=d?oe(d,m):null;p?(o.record(f?se(a,d,p):re(a,d,p)),r(`[gateway] POST ${g} ${f?"\xB7 COALESCIDA (llamada evitada)":""} \xB7 ${d} \xB7 $${p.costeUsd.toFixed(6)} (in ${p.tokens.entrada}, cache\u2191${p.tokens.cacheEscrita} cache\u2193${p.tokens.cacheLeida}, out ${p.tokens.salida})`)):d&&v(`gateway-sin-precio:${d}`,`[bvsala gateway] el modelo "${d}" no est\xE1 en el cat\xE1logo de precios; su uso se reenv\xEDa pero no se mide.`);},l=createServer(async(a,c)=>{let m=randomUUID(),f=new AbortController;c.on("close",()=>{c.writableEnded||f.abort();});let g=null,d=new URL(a.url??"/",e);try{let p=[];for await(let h of a)p.push(h);let y=Buffer.concat(p);d=new URL(a.url??"/",e);let C=s!==null&&a.method==="POST"&&y.length>0,N=ce(h=>{let b=a.headers[h];return Array.isArray(b)?b.join(", "):b}),R=C?ae("POST",d.pathname+d.search,y,N):"";if(C)if(s.tieneEnVuelo(R)){let h=await s.esperar(R);if(h){c.writeHead(h.status,h.headers);let b=new I;for(let ee of h.chunks)c.write(ee),b.observar(ee);c.end(),i(m,y,b.usage(),!0,d.pathname);return}}else g=s.registrar(R);let X={};for(let[h,b]of Object.entries(a.headers))h==="host"||h==="content-length"||b===void 0||(X[h]=Array.isArray(b)?b.join(", "):b);let k;try{k=await n(d,{method:a.method,headers:X,body:["GET","HEAD"].includes(a.method??"")?void 0:y,redirect:"manual",signal:f.signal});}catch(h){g?.abortar(),c.headersSent||(c.writeHead(502,{"content-type":"application/json"}),c.end(JSON.stringify({error:"bvsala gateway: upstream unreachable",detail:String(h)}))),r(`[gateway] ${a.method} ${d.pathname} \u2192 upstream inalcanzable: ${String(h)}`);return}let z=Object.fromEntries(k.headers.entries());for(let h of _e)delete z[h];c.writeHead(k.status,z);let Z=(k.headers.get("content-type")??"").includes("text/event-stream"),B=Z?new I:null;if(k.body)for await(let h of k.body){let b=Buffer.from(h);c.write(b),B?.observar(b),g?.capturar(b);}c.end(),g?.terminar(k.status,z),B&&k.ok?i(m,y,B.usage(),!1,d.pathname):Z||r(`[gateway] ${a.method} ${d.pathname} \u2192 ${k.status}`);}catch(p){if(g?.abortar(),f.signal.aborted)r(`[gateway] ${a.method} ${d.pathname} \u2192 el cliente abort\xF3; upstream cancelado`);else if(r(`[gateway] ${a.method} ${d.pathname} \u2192 error sirviendo: ${String(p)}`),!c.headersSent){c.writeHead(502,{"content-type":"application/json"}),c.end(JSON.stringify({error:"bvsala gateway: stream interrupted",detail:String(p)}));return}c.writableEnded||c.end();}});return await new Promise((a,c)=>{l.once("error",c),l.listen(t.puerto??8402,"127.0.0.1",()=>a());}),{puerto:l.address().port,cerrar:async()=>{await o?.stopAndDrain(),await new Promise(a=>l.close(()=>a()));}}}var U=class{id;exact=false;constructor(e="heuristic"){this.id=e;}count(e){if(e.length===0)return 0;let n=e.match(/[A-Za-z]+|\d+|\s+|[^\sA-Za-z\d]/g)??[],r=0;for(let o of n){let s=o[0];if(/\s/.test(s)){let i=(o.match(/\n/g)??[]).length;r+=i+Math.floor(Math.max(0,o.length-1)/2);}else /[A-Za-z]/.test(s)?r+=Math.max(1,Math.ceil(o.length/4)):/\d/.test(s)?r+=Math.max(1,Math.ceil(o.length/2)):r+=1;}return Math.max(r,Math.ceil(e.length/4))}},q=new U;var K=class{estimators=new Map;modelToTokenizer=new Map;fallbackId;constructor(e=q){this.fallbackId=e.id,this.estimators.set(e.id,e);}register(e){return this.estimators.set(e.id,e),this}mapModel(e,n){return this.modelToTokenizer.set(e,n),this}resolve(e){let n=e.tokenizer?this.estimators.get(e.tokenizer):void 0;if(n)return n;if(e.model){let r=this.modelToTokenizer.get(e.model);if(r){let o=this.estimators.get(r);if(o)return o}}return this.estimators.get(this.fallbackId)}count(e,n){return this.resolve(n).count(e)}};new K;new TextEncoder;new TextDecoder;new TextDecoder;var We={"gpt-4o-mini":{deltaTokens:-16,salidaDelBrazoA:72,contrato:"triage (6 fields, long enums)",pares:8},"gpt-4o":{deltaTokens:3,salidaDelBrazoA:75,contrato:"triage (6 fields, long enums)",pares:8}};V(We);var G="0.4.2";var[,,x,...j]=process.argv;function Ye(){console.log(`bvsala ${G} \u2014 BiVelio Savings Layer
+
+Comandos:
+  gateway [--puerto N]   Proxy local medidor para Claude Code (ANTHROPIC_BASE_URL).
+  claude [args\u2026]         Lanza Claude Code a trav\xE9s del gateway, sin configurar nada.
+
+Entorno:
+  BIVELIO_SERVICE_KEY    Clave de servicio (bvk_\u2026): habilita metering + asiento.
+  BVSALA_SEAT_ID         Identidad de asiento estable por r\xE9plica (opcional).
+  BVSALA_GATEWAY_UPSTREAM  Upstream alternativo (por defecto https://api.anthropic.com).
+  BVSALA_GATEWAY_COALESCE  =1 enciende la coalescencia de duplicados (F2, experimental).
+
+El gateway nunca corta el tr\xE1fico: sin clave o con la ingesta ca\xEDda, reenv\xEDa y avisa.
+Tus prompts jam\xE1s salen de tu m\xE1quina \u2014 solo cuentas y coste. M\xE1s: savings.bivelio.com`);}x!=="gateway"&&x!=="claude"&&(Ye(),process.exit(x===void 0||x==="help"||x==="--help"?0:1));var Y=j.indexOf("--puerto"),$=x==="claude"?0:Y>=0?Number(j[Y+1]):8402;(!Number.isInteger($)||$<0||$>65535)&&(console.error(`[bvsala gateway] puerto inv\xE1lido: ${j[Y+1]}`),process.exit(1));var Q=process.env.BIVELIO_SERVICE_KEY,T=await le({puerto:$,...Q?{serviceAccountKey:Q}:{},...process.env.BVSALA_SEAT_ID?{seatId:process.env.BVSALA_SEAT_ID}:{},...process.env.BVSALA_GATEWAY_UPSTREAM?{upstream:process.env.BVSALA_GATEWAY_UPSTREAM}:{},...process.env.BVSALA_GATEWAY_COALESCE==="1"?{coalescer:true}:{},...process.env.BVSALA_METERING_URL?{meteringUrl:process.env.BVSALA_METERING_URL}:{}});console.log(`[bvsala gateway] v${G} escuchando en http://127.0.0.1:${T.puerto}`);console.log(`[bvsala gateway] medici\xF3n: ${Q?"ACTIVA (clave de servicio presente)":"APAGADA (falta BIVELIO_SERVICE_KEY)"}`);if(x==="claude"){let t=spawn("claude",j,{stdio:"inherit",env:{...process.env,ANTHROPIC_BASE_URL:`http://127.0.0.1:${T.puerto}`}});t.on("error",e=>{console.error(`[bvsala claude] no se pudo lanzar \`claude\`: ${String(e)}. \xBFEst\xE1 instalado y en el PATH?`),T.cerrar().then(()=>process.exit(127));}),t.on("exit",(e,n)=>{T.cerrar().then(()=>process.exit(e??(n?1:0)));});}else console.log(`[bvsala gateway] apunta tu herramienta:  ANTHROPIC_BASE_URL=http://127.0.0.1:${T.puerto} claude`);var ge=async()=>{await T.cerrar(),process.exit(0);};process.on("SIGINT",()=>{ge();});process.on("SIGTERM",()=>{ge();});

package/dist/index.d.ts

@@ -158,7 +158,7 @@ declare class SavingsLedger {
  * catalogue stays out of the way.
  */
 /** When these prices were last checked against the providers' public rates. */
-declare const PRECIOS_AL_DIA = "2026-08-13";
+declare const PRECIOS_AL_DIA = "2026-08-24";
 /**
  * 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
@@ -2759,7 +2759,7 @@ declare class UsageEmitter {
     private seatId;
     private ci;
     private timer;
-    private flushing;
+    private inflight;
     /**
      * 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
@@ -2774,14 +2774,22 @@ declare class UsageEmitter {
     /** Record one request's usage. Never blocks; O(1). */
     record(report: SavingsReport): void;
     start(): void;
-    /** Stop the timer and attempt a final flush. Safe to call more than once. */
+    /** Stop the timer and attempt a final flush. Safe to call more than once.
+     *  Fire-and-forget: for a CLEAN shutdown that must not lose the last batch,
+     *  use `stopAndDrain` and await it. */
     stop(): void;
+    /** Clean shutdown: stop the timer and DRAIN the buffer, awaiting each POST.
+     *  Unlike `stop()` (fire-and-forget), this resolves only once the final batch
+     *  has actually been sent, so a graceful exit doesn't lose the last session's
+     *  usage. Bounded, so an unreachable control plane can't block shutdown. */
+    stopAndDrain(maxIntentos?: number): Promise<void>;
     /**
      * Flush one batch. Never throws. A transient server error (5xx) or network
      * failure re-queues the batch (capped); a 4xx (bad request / bad key) drops it,
      * since retrying a rejected payload would loop forever.
      */
     flush(): Promise<void>;
+    private hacerFlush;
     /**
      * THE INGEST HAS BEEN FAILING FOR A WHILE AND NOBODY NOTICED.
      *
@@ -3193,6 +3201,6 @@ declare function createSavingsLayer(config: Omit<SavingsLayerConfig, "tokenizer"
  * constant to package.json so the two can never drift.
  */
 
-declare const BV_SALA_VERSION = "0.4.0";
+declare const BV_SALA_VERSION = "0.4.2";
 
 export { type AnthropicOptions, AnthropicProvider, BV_SALA_VERSION, type BivelioHandoff, CATALOGO, COMPACT_ROWS_INSTRUCTION, type CacheOutcome, type CacheTier, type CachedAnswer, type CanonicalRequest, type ChatMessage, type CompactRowsDecodeOptions, type CompactRowsOptions, type CompactVerification, type CompressionEconomics, type CompressionPolicyInput, type CompressionRequest, type CompressionResult, type Compressor, type ConstraintBackend, type ConstraintBackendId, type ConstraintPlan, type ConversationState, type CostBasis, type CostModel, DEFAULT_COST_MODEL, type DeferredExecutionReport, type DeterministicResolver, EMBEDDED_PUBLIC_KEY, type EmbeddingFn, type EvidenceDoc, type ExactCache, ExactTokenizer, type ExecutionClass, ExecutionRouter, type FormatChoice, FormatSelector, type FormatSelectorOptions, type HandoffFact, HeuristicEstimator, InMemoryExactCache, InMemorySemanticCache, type JsonSchema, LicenseError, type LicenseGate, type LicenseKeyset, type LicenseStatus, type LicenseTokenPayload, type LocalClassifier, MODELOS_POR_CODIFICACION, MODELS_BY_ENCODING, type MemoryDelta, type MessageRole, MockProvider, type MockProviderOptions, type ModelCascadeMode, type ModelCascadeReport, type ModelCascadeSettings, type OpenAICompatibleOptions, OpenAICompatibleProvider, type OutputContract, PRECIOS_AL_DIA, type Policy, type ProtectedSpan, type Provider, type ProviderRequest, type ProviderResponse, type ProviderUsage, QUALITY_STATUSES, type QualityStatus, type RequestContext, type Reranker, type ResolvedDeps, type ResolvedGate, type ResolvedLicense, ResolverRegistry, type ResolverResult, type RetrievalOptions, type RetrievalOutcome, type RetrievalPlan, type Retriever, type RevocationListBody, type RevocationListVerification, type RevocationPollEvent, RevocationPoller, type RevocationPollerOptions, RevocationSnapshot, type RouteDecision, type SavingsLayer, type SavingsLayerConfig, SavingsLedger, type SavingsReport, type SavingsRequest, type SavingsResult, type SavingsToggles, SchemaRegistry, type SemanticCacheOptions, type SemanticHit, type SemanticRecord, type SemanticVerifier, type SerializationFormat, type Serializer, Singleflight, type TokenEstimator, TokenizerRegistry, type ToolCallRequest, type ToolDescriptor, type ToolRisk, type ToolSelection, ToolSelector, type ToolSelectorOptions, TraceCollector, type TraceEvent, UMBRAL_LOCAL, 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, embebedorLocal, emptyState, encodeCompactRows, evalArithmetic, evaluatePolicy, executeRetrievalPlan, gateFromKey, heuristicEstimator, isKeyset, isStrictCompatible, jsonCompactSerializer, keyTokensMatch, liveGateFromKey, mergeDelta, modelFamilyOf, noopCompressor, normalizeText, precioDeLista, projectContext, providerNativeBackend, randomId, registerExactTokenizer, registrarTokenizadorExacto, renderState, resolveConstraintBackend, resolveDependencies, resolveLicense, sha256, shouldCompress, stableStringify, uniformColumns, validateAgainstSchema, vectorLocal, verifyCompactSignature, verifyLicenseToken, verifyRevocationList, withProtectedSpans };