@bivelio/savings-layer 0.4.22 → 0.4.24

package/docs/terminales/README.md

@@ -11,8 +11,12 @@ terminal). Cada afirmación va marcada **[V]** (verificada en fuente) o **[I]**
 cada petición **byte a byte** al proveedor (`https://api.anthropic.com` por
 defecto) y, una vez servida la respuesta, lee el `usage` del stream y lo
 convierte en coste. Tus prompts jamás salen de tu máquina hacia BiVelio — solo
-cuentas y coste. Nunca corta el tráfico: sin clave o con la ingesta caída,
-reenvía y avisa.
+cuentas y coste. Es fail-closed como el SDK: arranca solo con tu clave de
+servicio (`BIVELIO_SERVICE_KEY`) y una licencia BiVelio activa, que recoge con
+esa clave y cuya firma verifica en tu máquina. Una vez arrancado, jamás corta
+una petición en curso: si la licencia caduca o se revoca, solo las peticiones
+NUEVAS reciben un HTTP 402 hasta renovarla. La medición es best-effort: con la
+ingesta caída, reenvía y avisa.
 
 Mide cada petición. Con licencia PRO aplica por defecto **una sola palanca**:
 rebaja el TTL de escritura de caché mientras la sesión sigue caliente — cambia la
@@ -21,6 +25,11 @@ por turno) van apagadas hasta que las enciendes. Y mide **todo el tráfico de in
 que el terminal enruta por el base URL — no «todo el tráfico»: cada guía dice
 lo que su terminal manda por fuera.
 
+En suscripción (login de claude.ai en Claude Code, cuenta ChatGPT en Codex) no
+hay factura por tokens: ese tráfico se mide a precio de lista equivalente y
+nunca se le acredita ahorro ni comisión; la licencia por asiento hace falta
+igual.
+
 ## Índice
 
 | Guía | Base URL exacto | `/v1` | Enrutado [V] | Envoltorio | Estado |
@@ -34,6 +43,7 @@ lo que su terminal manda por fuera.
 | [Droid](droid.md) | `http://127.0.0.1:8402` | sin **[I]** | `~/.factory/settings.json` | — (config de usuario) | validar en mano |
 | [Cline](cline.md) | `http://127.0.0.1:8402/v1` | **con** | UI | — | [V] |
 | [Kilo Code](kilo.md) | `http://127.0.0.1:8402/v1` | con **[I]** | UI | — | validar en mano |
+| [Python y cualquier SDK](../../README.md#python-and-any-other-language-the-local-gateway) (OpenAI · Anthropic) | OpenAI: `http://127.0.0.1:8403/v1` · Anthropic: `http://127.0.0.1:8402` | OpenAI **con**, Anthropic **sin** | `base_url` del SDK | `bvsala gateway --upstream openai` | [V] en test (upstream falso) |
 
 Reglas de la columna «Base URL»: **nunca barra final**, **nunca redirecciones**
 (un 3xx en el base URL es fallo por diseño del cliente, y el gateway lo reenvía
@@ -52,25 +62,43 @@ receta manual de cada guía hace exactamente lo mismo. Para el resto,
 
 ```bash
 npm i -g @bivelio/savings-layer      # trae el binario `bvsala`
-export BIVELIO_SERVICE_KEY=bvk_…     # clave de servicio, desde tu panel. Sin ella: reenvía, NO mide
+export BIVELIO_SERVICE_KEY=bvk_…     # clave de servicio, desde tu panel. Obligatoria: sin ella el gateway no arranca
 bvsala gateway                        # escucha en http://127.0.0.1:8402
-bvsala gateway --puerto 8500          # otro puerto si el 8402 está ocupado
+bvsala gateway --port 8500            # otro puerto si el 8402 está ocupado
 ```
 
-Al arrancar imprime dos líneas; la segunda te dice si estás midiendo:
+Al arrancar imprime, entre otras, estas líneas:
 
 ```
-[bvsala gateway] v0.4.4 escuchando en http://127.0.0.1:8402
-[bvsala gateway] medición: ACTIVA (clave de servicio presente)
+[bvsala gateway] v0.4.x listening on http://127.0.0.1:8402 → https://api.anthropic.com
+[bvsala gateway] license: PRO, active until 2026-10-24 (+14 days grace), collected with your service key and verified on this machine
+[bvsala gateway] metering: ON (service key present)
 ```
 
-`medición: APAGADA (falta BIVELIO_SERVICE_KEY)` = el terminal funciona igual,
-pero nada llega a tu panel.
+Si no arranca (sale con código 1), el mensaje dice exactamente qué falta:
+
+| Mensaje | Qué pasa | Arreglo |
+|---|---|---|
+| `BIVELIO_SERVICE_KEY is not set` | falta la clave de servicio | créala en el panel (Instalar, paso 2), expórtala y relanza |
+| `BIVELIO_SERVICE_KEY is not recognised` | clave borrada, rotada o copiada a medias | crea otra |
+| `your organization has no active BiVelio license` | no hay suscripción | suscríbete en Cuenta y relanza |
+| `your BiVelio license expired on …` | licencia caducada y sin gracia | renueva en Cuenta |
+| `could not collect your license from savings.bivelio.com` | sin acceso a savings.bivelio.com | revisa la conexión; como respaldo, `BIVELIO_LICENSE_KEY` (se verifica sin red y se sustituye a mano cada período) |
+| un HTTP 402 en el terminal a mitad de sesión | la licencia caducó o se revocó con la sesión abierta | renueva; las peticiones que ya estaban en curso no se cortaron |
+
+Si lanzas `bvsala gateway` como servicio (launchd/systemd), un fallo de licencia
+queda en el log del servicio con código 1 y el terminal solo verá «connection
+refused»: mira ese log.
 
 Un gateway habla con **un** upstream (`BVSALA_GATEWAY_UPSTREAM`, por defecto
 `https://api.anthropic.com`). Los terminales del dialecto Anthropic comparten
 instancia; Codex necesita la suya contra OpenAI — `bvsala codex` la arranca
-sola con el upstream correcto según tu modo de auth (ver su guía).
+sola con el upstream correcto según tu modo de auth (ver su guía). Desde la
+próxima versión, `bvsala gateway --upstream openai|anthropic|<origen>` lo elige
+sin variable de entorno (el flag manda sobre `BVSALA_GATEWAY_UPSTREAM`). Para un
+SDK de OpenAI (Python, Node…) arranca uno con `--upstream openai` en otro puerto;
+en streaming, la petición tiene que llevar `stream_options.include_usage` o el
+gateway la reenvía sin medirla y lo dice en el log.
 
 ### 2 · Comprobar que mide: el log del gateway
 
@@ -88,13 +116,56 @@ las otras líneas:
 |---|---|---|
 | `[gateway] POST /v1/v1/messages → 404` | el base URL lleva `/v1` **de más** para ese terminal | quita el `/v1` |
 | `[gateway] POST /messages → 404` | al base URL le **falta** `/v1` (el SDK solo añade `/messages`) | añade el `/v1` |
-| `[bvsala gateway] el modelo "…" no está en el catálogo de precios; su uso se reenvía pero no se mide.` | modelo fuera de catálogo (a propósito: presente-y-mal es peor que ausente) | nada; se reenvía sin medir |
+| `[gateway] POST /v1/messages → 402 (license expired)` | la licencia caducó, se revocó o la org está bloqueada: las peticiones NUEVAS se rechazan (las que estaban en curso terminaron) | renueva en Cuenta; el terminal enseña el motivo |
 | nada de nada | el terminal no está apuntando al gateway (config no leída, env pisado por config, otro puerto) | revisa la trampa de su guía |
 
+Cada petición que el gateway reenvía **sin medir** deja su propia línea con
+`· not metered: <motivo>`, y en su lugar no se estima nada. Los motivos, tal y
+como salen hoy:
+
+| `· not metered: …` | Qué pasa | Arreglo |
+|---|---|---|
+| `no BIVELIO_SERVICE_KEY` | un gateway arrancado desde código sin clave de servicio: reenvía, no mide (el CLI `bvsala` ni arranca sin ella) | exporta `BIVELIO_SERVICE_KEY` |
+| `model "…" has no list price in the catalog` | modelo fuera del catálogo de precios, a propósito: un precio presente y equivocado es peor que ninguno (la consola lo avisa una vez por modelo) | nada; se reenvía sin medir |
+| `could not read the model from the request body (content-encoding: …)` | el cuerpo no se pudo leer: JSON ilegible o una compresión que este Node no abre (zstd, el de Codex, necesita Node ≥ 22.15) | actualiza Node |
+| `the request did not ask for usage (stream_options.include_usage)` | Chat Completions en stream sin `include_usage`: el proveedor no manda contador | añade `stream_options={"include_usage": True}` a la llamada, o arranca con `BVSALA_GATEWAY_USAGE_INJECT=1` |
+| `…; usage injection skips compressed request bodies` | la inyección está puesta, pero solo añade la opción a cuerpos sin comprimir | pídelo en la llamada |
+| `…, and the upstream rejects that option` | el upstream rechazó `stream_options` y la inyección quedó apagada para el resto del proceso | en stream no hay arreglo desde el gateway; con `stream: false` sí se mide |
+| `the stream ended without the provider's final usage event` | el stream se cortó antes de su evento final (`message_delta`, `response.completed`/`incomplete`/`failed`, el chunk de uso o `[DONE]`): sin él no hay contador | nada |
+| `the response ended as response.failed without usage` | la Responses API cerró con `response.failed` sin `usage`. Si lo trae, sí se mide | nada |
+| `the response ended as response.incomplete without usage` | la Responses API cerró con `response.incomplete` sin `usage`. Si lo trae, sí se mide: un `response.incomplete` por `max_output_tokens` o por el filtro de contenido lo factura el proveedor | nada |
+| `the response carried no usage` | respuesta JSON (`stream: false`) sin `usage` | nada |
+| `the response was too large to read its usage` | respuesta JSON de más de 5 MB: el gateway no la guarda entera para leerla | nada |
+| `the response is neither JSON nor an event stream (content-type: …)` | el upstream contestó con otro tipo de contenido en una ruta que sí sabe medir | revisa el upstream |
+| `no usage dialect for this route` | ruta sin contador que el gateway sepa leer (embeddings, imágenes, audio…): solo mide `/v1/messages`, `…/chat/completions` y `…/responses` | nada |
+
+Con `BVSALA_GATEWAY_COALESCE=1` (apagada por defecto), una petición idéntica a
+otra que sigue en vuelo no viaja: recibe la réplica y su línea lleva
+`· COALESCED (call avoided)`. Detrás va `· by reference: floor $… (cache read
+price, …)` cuando se valora con el contador de la petición que sí viajó —a
+precio de lectura de caché, sin primas y con la salida solo si el cuerpo trae
+`temperature: 0` y el modelo no razona (la misma guarda de modelo que el SDK)—,
+o `· estimated, not by reference: <motivo>` cuando no. Esa línea es la
+valoración local: el panel todavía recibe estas peticiones como `estimated`, y
+no entran en la base de la comisión, porque el gateway aún no lee los tokens de
+razonamiento que declara el proveedor y la regla `reference-v2` los exige.
+
+| `· estimated, not by reference: …` | Por qué no |
+|---|---|
+| `no-primary-record` | la petición que viajó no dejó su contador final (ni evento final del stream ni `usage` en el JSON) |
+| `subscription` | tráfico de suscripción (Claude o ChatGPT): no hay factura por token |
+| `unofficial-upstream` | el gateway no habla con `api.anthropic.com` ni `api.openai.com` (un mock, un proxy, Azure, un revendedor): el precio de lista no está en ninguna factura |
+| `layer-changed-request` | una palanca cambió lo que viajó (modelo, cuerpo, cabeceras; también la rebaja de TTL de la caché): ya no es la petición del cliente byte a byte |
+| `primary-failed` | la petición que viajó cerró con `response.failed` |
+| `client-disconnected` | el cliente de esta petición se fue antes de recibir la réplica entera |
+| `service-tier` | el `service_tier` pedido o el servido no tiene precio por token publicado (`scale`, uno nuevo) |
+| `no-cached-price` | el modelo no tiene precio de lectura de caché en su propia fila del catálogo |
+| `no-credit` | el contador no deja nada que acreditar |
+
 Claude Code manda además un `HEAD /api/hello` antes de la primera llamada: es
 la sonda de vida, no una inferencia.
 
-`bvsala doctor [--puerto N]`: sondea el PATH y la existencia de las configs de
+`bvsala doctor [--port N]`: sondea el PATH y la existencia de las configs de
 usuario (nunca lee su contenido) e imprime el bloque exacto por terminal con el
 puerto indicado. Solo imprime: no escribe ninguna configuración.
 

package/docs/terminales/claude-code.md

@@ -12,8 +12,10 @@ construcción, con test.
   `apiKeyHelper`): es el segmento que BV-SALA mide y factura. Con login de
   claude.ai el enrutado también funciona — la doc oficial lo sanciona: el login
   sigue siendo la credencial activa y «its usage limits and billing apply» [V] —
-  pero ahí no hay factura por token que recortar.
-- `bvsala` instalado y `BIVELIO_SERVICE_KEY` exportada (ver [README](README.md)).
+  pero ahí no hay factura por token: el gateway lo mide a precio de lista
+  equivalente y nunca le acredita ahorro ni comisión (la licencia por asiento
+  hace falta igual).
+- `bvsala` instalado, `BIVELIO_SERVICE_KEY` exportada y una licencia BiVelio activa (la recoge el gateway con la clave; ver [README](README.md)).
 
 ## Envoltorio: `bvsala claude` (recomendado)
 

package/docs/terminales/cline.md

@@ -14,7 +14,7 @@ que se usa.
 
 - Cline instalado en VS Code.
 - Tu **API key** de Anthropic.
-- `bvsala gateway` corriendo en `http://127.0.0.1:8402` (ver [README](README.md)).
+- `bvsala gateway` corriendo en `http://127.0.0.1:8402` (necesita `BIVELIO_SERVICE_KEY` y una licencia BiVelio activa; ver [README](README.md)).
 
 ## Pasos en la UI
 

package/docs/terminales/codex.md

@@ -11,9 +11,10 @@ cifras.
 
 - `codex` en el PATH.
 - Login en Codex: **API key de OpenAI** (el caso que se monetiza) o
-  suscripción ChatGPT (se enruta y se mide, pero **no se monetiza**: no hay
-  factura por tokens; ver más abajo).
-- `bvsala` instalado y `BIVELIO_SERVICE_KEY` exportada (ver [README](README.md)).
+  suscripción ChatGPT (se enruta y se mide a precio de lista equivalente, **sin
+  comisión**: no hay factura por tokens; la licencia por asiento hace falta
+  igual; ver más abajo).
+- `bvsala` instalado, `BIVELIO_SERVICE_KEY` exportada y una licencia BiVelio activa (la recoge el gateway con la clave; ver [README](README.md)).
 
 ## Envoltorio: `bvsala codex [args…]`
 
@@ -92,26 +93,26 @@ que el tráfico real enseñó y el gateway ya contempla:
    de Codex frente a su backend: aparece igual **sin** gateway (comprobado).
 4. **Barra final.** `…/v1/` no.
 
-## Modo suscripción ChatGPT — validado, medido, NO monetizado
+## Modo suscripción ChatGPT — validado, medido, sin comisión
 
 Validado en mano el 30-08 (prefijo `/backend-api/codex`, upstream
 `https://chatgpt.com`): 200, stream íntegro, `usage` presente en
 `response.completed` y registro `measured` en la ingesta. **Pero un suscriptor
 no paga por tokens**: la cifra que ve es el equivalente a precio de lista por
 API key, no una factura; y como la comisión de BV-SALA solo toca ahorro medido
-sobre gasto real, este tráfico **no se monetiza** — igual que el OAuth de
+sobre gasto real, este tráfico **no genera comisión** — igual que el OAuth de
 suscripción en Claude Code (`docs/PASARELA-F0.md`: «el caso que NO
 facturamos»). OpenAI ni bendice ni prohíbe el proxy de suscripción (silencio
 del staff, a diferencia de Anthropic, que lo documenta). Postura idéntica a
 Claude Code: cero persistencia de `Authorization` / `ChatGPT-Account-ID`,
 binario sin modificar, y no se promociona como modo de ahorro.
 
-**Laguna conocida:** el registro que emite el gateway para un suscriptor es hoy
-**idéntico** al de una API key (`basis: measured`, coste a precio de lista) —
-el panel no puede distinguirlos. Mientras la comisión sea 0 no hay efecto; antes
-de que S4 calcule comisión sobre ahorro medido, S2 etiquetará la auth de
-suscripción en el wire para que ese tráfico jamás entre en la base. Está en el
-plan (`docs/PLAN-PASARELA-API-KEY.md`, S3).
+**Comisión 0 por diseño (desde la versión en que el gateway exige licencia):**
+el gateway clasifica como suscripción el tráfico de `/backend-api/…` o con
+upstream chatgpt.com (y el de Claude Code con `anthropic-beta: oauth-*`) y no le
+acredita ahorro: `baseline == actual`. Laguna que queda: el registro no lleva
+etiqueta propia en el wire, así que el panel no distingue suscripción de API key
+(exige migración; fuera de este frente).
 
 ## Validaciones en mano
 

package/docs/terminales/crush.md

@@ -10,7 +10,7 @@ relativa, y eso dicta la forma del URL: **con `/v1`, sin barra final**.
 - `crush` instalado.
 - `ANTHROPIC_API_KEY` exportada (Crush retiró su OAuth de Claude en ene-2026:
   solo API key).
-- `bvsala` instalado y `BIVELIO_SERVICE_KEY` exportada (ver [README](README.md)).
+- `bvsala` instalado, `BIVELIO_SERVICE_KEY` exportada y una licencia BiVelio activa (la recoge el gateway con la clave; ver [README](README.md)).
 
 ## Config de usuario: `~/.config/crush/crushrc`
 

package/docs/terminales/droid.md

@@ -9,7 +9,7 @@ lo dice tal cual; no hay validación hecha.
 ## Qué necesitas
 
 - `droid` instalado, en modo BYOK con tu **API key** de Anthropic.
-- `bvsala` instalado y `BIVELIO_SERVICE_KEY` exportada (ver [README](README.md)).
+- `bvsala` instalado, `BIVELIO_SERVICE_KEY` exportada y una licencia BiVelio activa (la recoge el gateway con la clave; ver [README](README.md)).
 
 ## Config de usuario: `~/.factory/settings.json`
 

package/docs/terminales/goose.md

@@ -9,7 +9,7 @@ forma del URL.
 
 - `goose` en el PATH, con el proveedor Anthropic elegido.
 - `ANTHROPIC_API_KEY` exportada (Goose es solo BYOK).
-- `bvsala` instalado y `BIVELIO_SERVICE_KEY` exportada (ver [README](README.md)).
+- `bvsala` instalado, `BIVELIO_SERVICE_KEY` exportada y una licencia BiVelio activa (la recoge el gateway con la clave; ver [README](README.md)).
 
 ## Envoltorio: `bvsala goose`
 

package/docs/terminales/kilo.md

@@ -10,7 +10,7 @@ gateway.** No hay validación hecha; esta guía lo dice tal cual.
 
 - Kilo Code instalado en VS Code.
 - Tu **API key** de Anthropic.
-- `bvsala gateway` corriendo en `http://127.0.0.1:8402` (ver [README](README.md)).
+- `bvsala gateway` corriendo en `http://127.0.0.1:8402` (necesita `BIVELIO_SERVICE_KEY` y una licencia BiVelio activa; ver [README](README.md)).
 
 ## Pasos en la UI
 

package/docs/terminales/opencode.md

@@ -7,7 +7,7 @@
 ## Qué necesitas
 
 - `opencode` instalado, proveedor `anthropic` con tu **API key** de Anthropic.
-- `bvsala` instalado y `BIVELIO_SERVICE_KEY` exportada (ver [README](README.md)).
+- `bvsala` instalado, `BIVELIO_SERVICE_KEY` exportada y una licencia BiVelio activa (la recoge el gateway con la clave; ver [README](README.md)).
 
 ## Config de usuario: `~/.config/opencode/opencode.json`
 

package/docs/terminales/qwen-code.md

@@ -10,7 +10,7 @@ catálogo a propósito (más abajo).
 - `qwen` en el PATH.
 - **Una API key de Anthropic** (`ANTHROPIC_API_KEY`), con Qwen Code configurado
   para usar el proveedor Anthropic.
-- `bvsala` instalado y `BIVELIO_SERVICE_KEY` exportada (ver [README](README.md)).
+- `bvsala` instalado, `BIVELIO_SERVICE_KEY` exportada y una licencia BiVelio activa (la recoge el gateway con la clave; ver [README](README.md)).
 
 ## Config de usuario: `~/.qwen/settings.json`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bivelio/savings-layer",
-  "version": "0.4.22",
+  "version": "0.4.24",
   "description": "The savings layer for your LLM bill: a library inside your code that lets through only what has to be paid for and returns a SavingsReport per call, measured with your provider's own meter and kept apart from estimates. Commercial license, paid per seat, commission only on measured savings. Your prompts never leave your infrastructure.",
   "keywords": [
     "llm",