@bivelio/savings-layer 0.4.31 → 0.4.33

package/LICENSE

@@ -10,18 +10,23 @@ not install or use the Software.
 
 1. LICENSE GRANT. Subject to your continuous compliance with this Agreement and to
    an active BiVelio subscription (paid, or granted by BiVelio at no charge, for
-   example through a promotional code or a pilot) with a valid license key
-   ("License Key"), BiVelio grants you a limited, non-exclusive, non-transferable,
-   non-sublicensable, revocable license to install and use the Software, as
-   published, solely for your own internal business purposes, and only for the
-   number of seats covered by your subscription. The Software is licensed, not sold.
+   example through a promotional code, a pilot, or the free Measure license) with a
+   valid license key ("License Key"), BiVelio grants you a limited, non-exclusive,
+   non-transferable, non-sublicensable, revocable license to install and use the
+   Software, as published, solely for your own internal business purposes, and only
+   for the number of seats covered by your subscription. The Software is licensed,
+   not sold. Under a Measure license the Software runs in shadow mode only: it
+   forwards your requests to your provider unchanged, applies no optimization, and
+   reports estimated savings that are never billed.
 
 2. LICENSE KEY; FAIL-CLOSED OPERATION. The Software requires a valid, active License
    Key and does not operate without one. Expiry, non-payment, revocation, suspension,
    or termination of your subscription immediately ends the license granted in
-   Section 1, and the Software will cease to function. You will not circumvent,
-   disable, remove, or tamper with the Software's licensing, metering, or revocation
-   mechanisms, nor use the Software after your license has ended.
+   Section 1, and the Software will cease to function; when a paid subscription
+   ends, BiVelio may instead grant you a Measure license, under which the Software
+   continues in shadow mode only. You will not circumvent, disable, remove, or tamper
+   with the Software's licensing, metering, or revocation mechanisms, nor use the
+   Software after your license has ended.
 
 3. RESTRICTIONS. Except as expressly permitted above, you will not: (a) distribute,
    publish, resell, rent, lease, lend, offer as a hosted or managed service, or
@@ -74,8 +79,11 @@ not install or use the Software.
      (iv) cost figures computed by the Software from its price catalogue (or from
          a cost model you supply): baseline cost, actual cost, the net-saving
          ratio, the basis of the figures (measured, reference, estimated, shadow,
-         or unmeasured), and the value, at the provider's cache-read price, of
-         input tokens your provider reported as cleared from context.
+         or unmeasured), the value, at the provider's cache-read price, of
+         input tokens your provider reported as cleared from context, and the
+         discount your provider's own prompt cache gave the request and the
+         cache-write premium it billed, which are shown apart and never used to
+         calculate the fees in Section 6.
    Each batch of records also carries the Software's surface and version (for
    example, "gateway/0.4.23"). BiVelio's ingest rejects any record that carries a
    field not listed above. Separately, the Software fetches from BiVelio its current
@@ -102,8 +110,10 @@ not install or use the Software.
 6. FEES. Your subscription is subject to BiVelio's pricing as published at
    https://savings.bivelio.com/pricing (the "Published Pricing") for each billing
    period:
-   (a) a subscription fee per seat, payable whether or not the Software produces any
-   saving; and (b) a commission, at tiered marginal rates, charged only on measured
+   (a) a subscription fee, per seat or for a plan that includes a number of seats,
+   payable whether or not the Software produces any saving; and (b) only if your
+   subscription is on a plan that the Published Pricing lists as carrying a
+   commission, a commission, at tiered marginal rates, charged only on measured
    savings, meaning savings whose basis is labelled "measured" or "reference" in
    your usage records (Section 5(b)(iv)). A "measured" saving is established from
    your LLM provider's own usage counter for that request; a "reference" saving, for

package/README.md

@@ -19,21 +19,19 @@
 Every request your app sends to an AI is paid for by the text going in and out.
 **Savings** sits on that path and lets through only what's needed — skipping calls
 that don't have to happen, and trimming what does — so you pay for less. It is not a
-promise you take on faith: **every saving we charge on is measured with your provider's
+promise you take on faith: **every saving we report is measured with your provider's
 own usage counter, the one your bill is built from** (for a repeat served without
 calling the provider, the counter of the identical call that ran), and every saving —
 measured or estimated, and labelled as such — is handed back to you request by request.
 
-**A small per‑seat fee, and a commission only on savings measured against your
-provider's counter.** The seat fee is paid whether or not you save. Your
-first month carries no commission at all — it is the first calendar month (UTC) in
-which your organization reports usage, so starting late in a month makes it a short one —
-and at its close you see the statement of what the commission would have been. After
-that, the commission is charged on the **measured** saving only — never from estimates:
-a tiered rate from 10 % down to 4 % of what you saved, so **you keep
-at least 90 % of every euro saved** (before the invoice is rounded to the cent; the
-seat fee is separate). A month with no measured saving is zero commission. And your
-prompts and completions **never reach BiVelio**: what BiVelio receives is per‑request
+**Measure for free, then pay per seat — with no commission on your savings.** The
+free **Measure** license (no card) runs the layer in shadow mode on your own traffic and
+shows what it would have saved, valued with your provider's counter. To turn the levers
+on, **Pro** is **€15 / seat / month** or **€150 / seat / year**, and **Team** is **€129 / month
+with 10 seats included** (€12 per extra seat; €1,290 / year, €120 per extra seat), EUR,
+VAT not included — a fixed fee, paid whether or not you save, and no commission on what
+you save. Enterprise (more seats, your own contract or invoicing terms) is by contract.
+And your prompts and completions **never reach BiVelio**: what BiVelio receives is per‑request
 usage — token counts, cost, the model id and opaque ids — never your content
 ([LICENSE](./LICENSE) §5 lists every field; [savings.bivelio.com/privacy](https://savings.bivelio.com/privacy)
 explains each one and how long it is kept).
@@ -46,14 +44,16 @@ picks the cheapest execution that still meets your quality bar and hands you an
 auditable `SavingsReport` — the same numbers your dashboard reads. Traffic still
 goes straight from your app to your provider; the SDK is never a middleman server.
 
-> **Commercial software — © 2026 BiVelio Inc.** Free to install, **paid to run**:
-> BV‑SALA is fail‑closed and executes only with an active BiVelio license key.
+> **Commercial software — © 2026 BiVelio Inc.** Free to install, **paid to save**:
+> BV‑SALA is fail‑closed and executes only with an active BiVelio license key. The
+> free **Measure** license (no card) runs it in shadow mode: nothing you send is
+> changed, nothing is served from cache, and you see what it would have saved.
 > The license signature is verified **offline**; with `licenseServerUrl` set, the SDK
 > also calls `savings.bivelio.com` for the revocation list, license renewal and usage
 > metering. **Your prompts, completions and provider keys never reach BiVelio** — what
 > travels is per‑request usage: token counts, cost, the model id, a request id and
 > opaque seat and session ids (the exact list is in [LICENSE](./LICENSE) §5). Use is
-> governed by the LICENSE, which also sets out the seat fee and the commission, and the
+> governed by the LICENSE, which also sets out the fees, and the
 > BiVelio Terms. Not a wrapper around any third‑party library.
 
 ## Where it installs
@@ -119,6 +119,12 @@ bvsala gateway --upstream openai --port 8403   # one gateway per upstream
 bvsala gateway                                 # Anthropic, the default, on 8402
 ```
 
+Flags and environment variables are in English (`--port`, `--project`, `--force`,
+`BVSALA_GATEWAY_EFFORT`, `BVSALA_GATEWAY_SIBLING_MODEL`). The Spanish spellings from
+earlier versions (`--puerto`, `--proyecto`, `--forzar`, `BVSALA_GATEWAY_ESFUERZO`,
+`BVSALA_GATEWAY_MODELO_HERMANO`) keep working until 0.5 and print a deprecation
+notice; `BVSALA_SILENCE_DEPRECATIONS=1` silences it. `bvsala --help` lists them all.
+
 ```python
 from openai import OpenAI
 client = OpenAI(base_url="http://127.0.0.1:8403/v1")   # WITH /v1
@@ -159,8 +165,8 @@ provider, and a request without it is not changed at all:
 What you can check before paying is what we have measured: the published benchmark,
 trial by trial, with the raw CSV linked, at
 **[savings.bivelio.com/en/how-it-works](https://savings.bivelio.com/en/how-it-works)**,
-and the commission calculator on the front page, which runs on the same price
-catalogue that bills you. The verifier that replays the optimizer on your own data
+and the free **Measure** license, which runs the layer in shadow mode on your own
+traffic and shows what it would have saved, valued with your provider's counter. The verifier that replays the optimizer on your own data
 lives in your dashboard once you sign in.
 
 ## Set it up in one command
@@ -195,7 +201,8 @@ saving where the layer removed something is reported as `estimated`, and estimat
 savings are never billed — the SDK warns once when the tokenizer is missing.
 
 **2 · The license** — from your [dashboard](https://savings.bivelio.com/dashboard/install)
-(**€4 / seat / month** or **€39 / seat / year**, EUR)
+(free **Measure** license, no card; **Pro** €15 / seat / month or €150 / seat / year;
+**Team** €129 / month with 10 seats included — EUR)
 
 ```bash
 export BIVELIO_LICENSE_KEY=…   # your license key
@@ -210,8 +217,10 @@ import { createSavingsLayer, OpenAICompatibleProvider } from "@bivelio/savings-l
 
 // Your provider. LLM traffic goes straight to it — the SDK never proxies it.
 // Any OpenAI-compatible endpoint works: OpenAI, Azure, vLLM, SGLang, a gateway.
+// For Gemini, use the native `GoogleProvider` instead (see "Gemini: the native adapter").
 // Model ids are qualified (`openai/gpt-4o-mini`); the prefix is stripped on the
-// wire for OpenAI and Azure and kept for gateways — see `stripProviderPrefix`.
+// wire for OpenAI, Azure and Google's Gemini API and kept for gateways — see
+// `stripProviderPrefix`.
 const provider = new OpenAICompatibleProvider({
   baseUrl: "https://api.openai.com/v1",
   apiKey: process.env.OPENAI_API_KEY,
@@ -231,8 +240,8 @@ const { text, report } = await layer.generate({
 
 console.log(text);                    // "8"  (computed locally — no LLM call)
 console.log(report.calls.avoidedLlm); // → 1: a whole call you never paid for
-console.log(report.cost.netSavings);  // → 0..1 ratio of the baseline you did not pay (1 here)
-console.log(report.cost.baselineEstimate - report.cost.actual); // → the same saving in USD
+console.log(report.cost.netSavingsRatio); // → 0..1 ratio of the baseline you did not pay (1 here)
+console.log(report.cost.netSavingsUsd);   // → the same saving in USD (baselineEstimate − actual)
 console.log(report.cost.basis);       // → "estimated": nothing ran, so there is no provider counter
 ```
 
@@ -259,8 +268,8 @@ never do.
 A repeat is valued by reference only when the call that ran reached the provider's
 own API (`https://api.openai.com`, `https://api.anthropic.com` or
 `https://generativelanguage.googleapis.com`), because the list price it is valued at
-is the invoice only there. When `OpenAICompatibleProvider` or `AnthropicProvider`
-points anywhere else — a proxy such as LiteLLM, a gateway, Azure, Bedrock, Vertex —
+is the invoice only there. When `OpenAICompatibleProvider`, `AnthropicProvider` or
+`GoogleProvider` points anywhere else — a proxy such as LiteLLM, a gateway, Azure, Bedrock, Vertex —
 or when the Anthropic SDK or LangChain adapter reads that its client does, that call
 leaves no reference: its repeats stay `estimated`, and the `reference` trace of the
 call that ran says `unofficial-origin`. When the layer cannot tell where the call
@@ -276,7 +285,7 @@ tokens) with `stop_details.category` set to `cyber`, `general_harms` or `null`.
 documents these as
 [not billed](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#how-refusals-are-billed).
 Its tokens still appear in `report.tokens`. `cost.actual`, `cost.baselineEstimate` and
-`cost.netSavings` are all 0, so the request credits no saving: not measured, not
+`cost.netSavingsRatio` are all 0, so the request credits no saving: not measured, not
 estimated and not by reference. A concurrent identical request served from it credits
 nothing either. The same rule applies in the gateway. Any other refusal is priced from
 its `usage` as usual. That covers `bio`, `frontier_llm` and `reasoning_extraction`, a
@@ -286,16 +295,41 @@ Most refusals carry no signal from the API: the model writes "I can't help with
 as ordinary text and ends with `end_turn` or `stop`. The layer also looks for these,
 with a conservative text heuristic. It checks only the opening of the answer, or the
 whole answer when it is short, and it needs a real refusal clause, such as "I'm sorry,
-but I can't help with that", "I cannot assist" or "As an AI, I cannot provide". A
-single word is not enough. It covers English, Spanish, Catalan, French, German,
-Italian and Portuguese. A match is measured and served as usual. It is not written to
-the exact or semantic cache, and it is not replayed by reference. A concurrent
-identical request served from it is `estimated`. The trace says why
-(`skipReason: "text_refusal"`). A refusal already stored by an earlier version is not
-served either. In the gateway, the coalesced twin of such a response is `estimated`
-(`primary-text-refusal`). A false positive costs one cache hit. A normal answer that
-starts with "Sorry for the delay, here is…", or has "I can't" later on, is cached as
-before.
+but I can't help with that", "I cannot assist", "I can't determine…" or "As an AI, I
+cannot provide". After an apology, any verb counts ("I'm sorry, but I can't
+determine…"), and so does a stated reason with no "I can't" ("I'm sorry, but
+accessing … is illegal", "… would be a violation of…"). When the answer opens with
+the refusal itself ("I can't", "I won't", "I'm not going to", "I'm unable to", and
+"No puedo", "Je ne peux pas", "Ich kann … nicht"…), any verb counts too ("I can't
+argue that…"), except for a tested list of idioms that are not refusals ("I can't
+wait", "I won't lie", "I can't find any issues", "I can't be sure, but…").
+A single word is not enough.
+An answer that opens with empathy and, in its first two sentences, sends the user to
+a mental health professional, a crisis line, emergency services or someone they
+trust, instead of answering, counts too (rule `redirection`). It covers English,
+Spanish, Catalan, French, German, Italian and Portuguese. A match is measured and
+served as usual. It is not written to the exact or semantic cache, and it is not
+replayed by reference. A concurrent identical request served from it is `estimated`.
+The trace says why (`skipReason: "text_refusal"`, with the `rule`). A refusal
+already stored by an earlier version is not served either. In the gateway, the
+coalesced twin of such a response is `estimated` (`primary-text-refusal`). A false
+positive costs one cache hit. A normal answer that starts with "Sorry for the delay,
+here is…", praises with "I can't recommend this enough", has "I can't" later on, or
+offers empathy with practical help and no referral ("I'm sorry to hear about your
+flight; here are three options…") is cached as before.
+
+**Sensitive topics.** A request whose user turns touch self-harm or suicide, a mental
+health crisis or a medical emergency ("How do I commit suicide?", "I'm having a panic
+attack", "my friend is not breathing") is never read from or written to the exact or
+semantic cache, even when the answer is useful, and leaves no reference record. It is
+measured and served as usual; a concurrent identical request served from it is
+`estimated`. The `policy` and `cache-write` traces say why
+(`skipReason: "sensitive_topic"`, with the `category`). The check is lexical and
+conservative: phrases, not single words ("kill a Python process", "Suicide Squad" and
+"cut my hair" do not count). It covers the same twelve languages as the freshness
+and personalization checks, with shorter lists outside English, Spanish, Catalan,
+French, German, Italian and Portuguese. In the gateway, the coalesced twin of such a
+request is `estimated` (`sensitive-topic`). A false positive costs one cache hit.
 
 **Streaming.** `generateStream()` takes the same request and hands you the answer as
 the provider writes it, then the same `SavingsReport`:
@@ -453,6 +487,45 @@ It runs once per HTTP attempt, inside the SDK's retries: an attempt the provider
 rejects reaches the SDK unchanged and is not recorded. Only message creation goes
 through the layer; `countTokens`, batches, models and files pass untouched.
 
+The middleware forwards your request body unchanged, history included, so it never
+edits a turn before a thinking block. It also does not remove parameters the model
+rejects. On Claude Sonnet 5.5, Opus 5.5, Fable 5.1 and Mythos 5.1 a forced
+`tool_choice` (`any` or `tool`) returns a 400. On those models, and on Opus 4.7/4.8,
+Opus 5, Sonnet 5 and Fable 5, so does a non-default `temperature`, `top_p` or `top_k`.
+The middleware warns once per model and cause (`silenceWarnings` turns it off) and
+the API's 400 reaches you unchanged.
+
+<details>
+<summary><b>Claude Sonnet 5.5, Opus 5.5, Fable 5.1: what <code>AnthropicProvider</code> sends instead</b></summary>
+
+These models reject some request parameters with a 400 ([forcing tool
+use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools#forcing-tool-use),
+[Sonnet 5.5](https://platform.claude.com/docs/en/models/sonnet-5-5/overview)).
+`AnthropicProvider` sends a request they accept instead of failing:
+
+- **Output contract.** A forced `tool_choice` returns a 400 on these models, with or
+  without thinking. When your schema meets `strict` mode, the contract travels as
+  structured output (`output_config.format`). Without your tools, the provider still
+  enforces the contract. With your tools, they stay callable with `tool_choice: auto`
+  and the final text answer comes back in the contract's shape. When your schema does
+  not meet `strict`, the contract travels as a tool the model is not forced to call,
+  with one sentence in the system prompt that tells it to answer through that tool.
+  Models that support forced tool use (Opus 5, Sonnet 5 and the 4.x models) get the
+  same request as before.
+- **`temperature`.** A non-default value is dropped, with one warning per model,
+  because it can only return a 400. The answer is then sampled, not deterministic.
+  `temperature: 1`, the API default, is sent as is.
+- **A model the table does not list** (a new model or a gateway alias): when the API
+  rejects either parameter, the provider repeats the request once without it and
+  remembers the model for later requests. A 400 is not billed, so the retry is not
+  counted in `retries`.
+- **Thinking blocks.** `ChatMessage` does not carry thinking blocks, so this adapter
+  never sends one. The preserved-thinking check, which returns a 400 when a turn
+  before a thinking block has been edited, has nothing to check on its requests, even
+  when the levers that rewrite history are on.
+
+</details>
+
 ## What you get on every request
 
 A `SavingsReport` with the numbers behind every claim, kept in **four separate
@@ -465,6 +538,32 @@ ledgers** that are never summed into one flattering figure:
 | `compressed_tokens` | information kept, but encoded with fewer tokens |
 | `provider_cached_tokens` | tokens still in the prompt, billed/processed more cheaply |
 
+**Your provider's own cache discount, shown apart and never billed.** With prompt
+caching, most of what you save often comes from your provider's prefix cache
+(Anthropic `cache_control`, OpenAI's automatic cache, Gemini's implicit cache), not
+from the layer. `cost` prices cached tokens at the cached rate on both sides, so that
+discount is never credited as the layer's saving. `report.nativeSavings` shows it on
+its own, from your provider's counter at list price, so the report adds up to your
+invoice:
+
+```ts
+report.nativeSavings;
+// {
+//   provider: "anthropic", mechanism: "explicit", layerMarked: true,
+//   cacheReadTokens: 40000, cacheWriteTokens: 3000, cacheWrite1hTokens: 0,
+//   inputPer1k: 0.003, cachedInputPer1k: 0.0003, writeMultiplier: 1.25, write1hMultiplier: 2,
+//   readDiscountUsd: 0.108,   // reads × (input − cached-input rate)
+//   writePremiumUsd: 0.00225, // writes × input × (multiplier − 1)
+//   netUsd: 0.10575,          // can be negative: a cold write pays before any read
+//   basis: "measured",
+// }
+```
+
+It is present only when a call ran and the provider reported cache reads or writes;
+a cache hit or a coalesced request never carries it. It is not in `cost.netSavings`,
+not in `cost.baselineEstimate`, and never in the commission base. Your dashboard shows
+it as its own card, **Native savings unlocked**, next to the credited savings.
+
 **Quality, kept apart from money.** `report.qualityLedger` records how the answer you
 received earned its place: whether it came from your provider, a replay, or the answer
 to a reworded question (with its similarity score); whether it was checked against your
@@ -551,7 +650,7 @@ changes the answer, and what they are worth is reported next to the four ledgers
 never folded into `cost.*`, never part of any commission.
 
 **`savings.deferrable`** asks for the provider's Flex tier: OpenAI, and Gemini through
-its OpenAI‑compatible endpoint. Anthropic has no cheaper synchronous tier: its
+`GoogleProvider` (`serviceTier: "flex"`) or its OpenAI‑compatible endpoint. Anthropic has no cheaper synchronous tier: its
 discount lives only in Message Batches, which `layer.batches` (below) sends to.
 Bedrock and DeepSeek off‑peak pricing are not supported.
 
@@ -681,7 +780,16 @@ const agentLayer = createSavingsLayer({
 
 By default the layer writes the provider's prompt cache at two fixed places: the end
 of the system header and the end of the history before your last user message, and
-stops marking a prefix whose measured hit rate does not pay the write premium.
+stops marking a prefix whose measured hit rate does not pay the write premium. On
+Anthropic, where a write costs 1.25x, the history and a tool catalogue sent without a
+system header are marked only when the request itself shows they will be sent again:
+a tool-loop step after your last user message, or a conversation already past its
+second turn. The first follow-up of a conversation (`[question, answer, question]`)
+marks only the system header, so two-turn chats pay no premium that nothing reads.
+In an agent loop with no system header, the end of the tool list is marked once the
+catalogue reaches the model's minimum cacheable size (512 tokens on Claude Sonnet 5.5
+and Opus 5.5, 1,024 on Sonnet 5, 4,096 on Haiku 4.5). That discount is the provider's
+cache on your bytes: it is never credited as the layer's saving.
 
 `cacheBreakpoints: "auto"` places them from what your traffic actually does. The layer
 compares each request's prefix with the ones it sent before, per model, tool set and
@@ -727,7 +835,7 @@ Calibrated reuse and `cacheBreakpoints: "auto"` learn from your traffic, and by
 what they learn lives in the process. On serverless platforms (Vercel Functions, AWS
 Lambda) an instance may serve one request or live a few minutes, so neither would ever
 get past its starting point. Give each one somewhere to keep it. Giving the layer a
-`semanticCache` only says where reworded questions are kept; `semanticCacheDefault: true`
+`semanticCacheStore` only says where reworded questions are kept; `semanticCacheDefault: true`
 is what switches reuse on for every request (a request's own `savings.semanticCache`
 still wins), and without it, or `savings.semanticCache` on each request, the cache
 stays empty and learns nothing:
@@ -749,7 +857,7 @@ async function serverlessLayer(kv: SharedKeyValue) {
   const layer = createSavingsLayer({
     provider,
     licenseKey: process.env.BIVELIO_LICENSE_KEY,
-    semanticCache,
+    semanticCacheStore: semanticCache,
     // Passing the cache does not switch it on; this asks for it on every request.
     semanticCacheDefault: true,
     cacheBreakpoints: "auto",
@@ -823,6 +931,60 @@ console.log(data.answer); // 8
 
 </details>
 
+<details>
+<summary><b>Gemini: the native adapter</b></summary>
+
+For Gemini, use `GoogleProvider`: it speaks Gemini's own API (`generateContent` and
+`streamGenerateContent`), where what the layer measures is documented. Keep
+`OpenAICompatibleProvider` for every other provider.
+
+```ts
+import { GoogleProvider } from "@bivelio/savings-layer";
+
+const gemini = createSavingsLayer({
+  provider: new GoogleProvider({ apiKey: process.env.GEMINI_API_KEY, requireUsage: true }),
+  licenseKey: process.env.BIVELIO_LICENSE_KEY,
+});
+
+const { text: answer, report: geminiReport } = await gemini.generate({
+  model: "google/gemini-3.8-flash", // the `google/` prefix never travels
+  messages: [
+    { role: "system", content: "Answer in one sentence." },
+    { role: "user", content: "Why is the sky blue?" },
+  ],
+  maxOutputTokens: 400,
+  reasoningEffort: "low", // → thinkingLevel "LOW" (Gemini 3) or a thinking budget (2.5)
+});
+console.log(answer, geminiReport.cost.actual);
+```
+
+What the native API gives the layer that the OpenAI-compatible endpoint hides:
+
+- **Thinking is billed output.** Output is `candidatesTokenCount + thoughtsTokenCount`
+  (Google bills thinking as output) and the thinking is reported as reasoning. Thought
+  summaries (`thinkingConfig: { includeThoughts: true }` on the adapter) are never part
+  of `text`.
+- **Refusals with their reason.** A blocked prompt (`promptFeedback.blockReason`) or a
+  filtered answer (`finishReason` `SAFETY`, `PROHIBITED_CONTENT`, `BLOCKLIST`, …) is
+  `finishReason: "content_filter"` with the native reason in `finishReasonDetail`:
+  measured from its usage, never cached, never credited.
+- **Tools.** Calls come back with their `id` and `thoughtSignature`; send the assistant
+  turn back with its `toolCalls` as they came (as in the tool loop above) and the
+  signature travels back untouched. The results of one turn go back together.
+- **Implicit caching.** Gemini 2.5 and later cache repeated prefixes on their own; the
+  cached part of the prompt (`cachedContentTokenCount`) is reported as provider-cached
+  tokens. Explicit context caching (`cachedContents`) is not used: it bills storage by
+  the hour, which a per-request report cannot price.
+- **Output contract.** Your schema travels as written in `responseJsonSchema`. Google
+  does not document that every JSON Schema feature is enforced, so a repeat of a request
+  with a schema is not valued by reference.
+- **Thinking level.** `reasoningEffort` follows Google's published mapping. A model that
+  rejects a level (`gemini-3.8-flash` answers 400 to `MINIMAL`) is asked again once at
+  `LOW`, and remembered; the rejected request was not billed. Thinking cannot be turned
+  off on Gemini 3 or 2.5 Pro, so `"none"` there is the lowest level, with a warning.
+
+</details>
+
 <details>
 <summary><b>Output cap — with or without a contract</b></summary>
 
@@ -846,6 +1008,26 @@ request is repeated once with the other one (nothing was generated, so nothing i
 billed twice) and the model is remembered. To choose the field yourself:
 `new OpenAICompatibleProvider({ baseUrl, maxTokensParam: "max_completion_tokens" })`.
 
+**OpenAI-compatible endpoints that are not OpenAI** (Gemini's
+`generativelanguage.googleapis.com/v1beta/openai`, LiteLLM, vLLM, Ollama, a router).
+`prompt_cache_key`, OpenAI's prefix-cache routing hint, goes only to OpenAI's own API:
+Gemini answers 400 to a field it does not know, and up to 0.4.31 every request with a
+cached prefix failed there. A proxy in front of OpenAI that forwards it can opt in with
+`sendPromptCacheKey: true`. Any optional field an endpoint still rejects by name
+(`prompt_cache_key`, `service_tier`, `seed`, `reasoning_effort`) is dropped, the request
+repeated once and the model remembered; `reasoning_effort` is never dropped on OpenAI's
+own API, where its 400 is the answer. Gemini leaves its thinking tokens out of
+`completion_tokens` and bills them as output, so the layer counts output as
+`total_tokens − prompt_tokens` whenever the total is larger (and reports the difference
+as reasoning); on OpenAI's API `completion_tokens` already include reasoning and nothing
+is added. Gemini stops a filtered answer with `finish_reason: "content_filter: OTHER"`
+(or another reason): it is `finishReason: "content_filter"` (the adapter keeps the
+reason, which reaches you as `result.finishReasonDetail` and is named in the report's
+cache trace; an Anthropic refusal brings its `stop_details.category` there too), and like every
+provider refusal it is measured, never
+cached and never credited. Google does not document that such refusals are free, so
+they are costed from their `usage` like any call.
+
 The cap is yours, not a saving: it is never credited as output avoided. An answer
 it cut (`finishReason: "length"`) is not cached, and
 `report.qualityLedger.truncation` says the limit was yours.
@@ -904,6 +1086,21 @@ console.log(res.text);
   the SDK warns once.
 - **Errors.** When a tool fails, put the error in `content` and set `isError: true`.
   Anthropic receives it as `is_error`; providers without such a flag get the text.
+- **Gemini 3's thought signature.** With `GoogleProvider` it travels in each call's
+  `thoughtSignature` and comes back in `call.extraContent` in the same shape as below,
+  so a conversation can move between the two Gemini adapters. Through its
+  OpenAI-compatible endpoint Gemini
+  returns each call with `extra_content.google.thought_signature` and rejects the next
+  turn with a 400 if the call comes back without it. It arrives in `call.extraContent`;
+  pushing `res.toolCalls` back as they came (as above) sends it back untouched. It is
+  opaque and not part of any cache key.
+- **gpt-5.6-sol, gpt-5.6-terra and gpt-5.6-luna with tools need `reasoningEffort: "none"`.**
+  On Chat Completions OpenAI rejects function tools for these models unless
+  `reasoning_effort` is `"none"` («Function tools with reasoning_effort are not supported for gpt-5.6-sol in
+  /v1/chat/completions»). Declare it on the request:
+  `layer.generate({ model: "openai/gpt-5.6-sol", messages, tools, reasoningEffort: "none" })`.
+  The layer never picks an effort itself: without the field nothing is sent. It is part
+  of the cache key, like `temperature` and `seed`.
 
 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 answer that follows a tool loop
@@ -915,10 +1112,11 @@ difference.
 **Which tools reach the model.** The layer never cuts a catalogue it cannot rank. If
 your tools declare no `intents` and no `risk` (the usual shape of MCP and OpenAI tool
 lists), or you pass `savings: { router: false }`, every tool goes to the provider
-exactly as you sent it, and the layer credits nothing for the tool block. Only when
-your tools declare `intents`/`risk` does the selector keep the relevant ones, up to
-`new ToolSelector({ maxTools })` (8 by default), and hold back write tools from a
-request that is not an action. Whatever it leaves out, the model cannot call in that
+exactly as you sent it, and the layer credits nothing for the tool block. When your
+tools declare `intents`/`risk`, the selector holds back write tools from a request
+that is not an action and, since 0.4.33, sends every other tool: it prunes by
+relevance only if you ask for it with `new ToolSelector({ maxTools })` (up to 0.4.32
+that was the default, with 8). Whatever it leaves out, the model cannot call in that
 request: the report's `tool-selector` trace lists it, the tokens count as eliminated
 input, and the SDK warns once per process (`silenceWarnings` turns the warning off).
 
@@ -998,7 +1196,7 @@ console.log(tracedReport.cost.basis); // the span carries the same figures
 - **Money is kept apart by basis.** The money saved is
   `com.bivelio.cost.saved.measured`, `.reference` or `.estimated` — one key per span,
   the one of its basis — so a sum over one key never mixes measured and estimated
-  money; `unmeasured` spans carry counts and no money. `report.cost.netSavings` is a
+  money; `unmeasured` spans carry counts and no money. `report.cost.netSavingsRatio` is a
   ratio and goes out as `com.bivelio.cost.net_savings_ratio`; the money is
   `baselineEstimate − actual`, and that is what `saved.*` holds.
 - **None of this talks to BiVelio.** Spans go to your exporter; files stay where you
@@ -1033,7 +1231,7 @@ console.log(tracedReport.cost.basis); // the span carries the same figures
 | `gen_ai.usage.input_tokens`, `.output_tokens`, `.cache_read.input_tokens` | your provider's counter; absent when it reported no usage |
 | `com.bivelio.cost.basis`, `.currency`, `.baseline`, `.actual` | where the money comes from, its currency (USD by default), and both sides |
 | `com.bivelio.cost.saved.measured` \| `.reference` \| `.estimated` | the money saved, in the key of its basis only |
-| `com.bivelio.cost.net_savings_ratio` | `cost.netSavings`, a 0..1 ratio — not money |
+| `com.bivelio.cost.net_savings_ratio` | `cost.netSavingsRatio`, a 0..1 ratio — not money |
 | `com.bivelio.calls.*`, `com.bivelio.tokens.*` | the four ledgers: avoided calls, eliminated, compressed and provider‑cached tokens |
 | `com.bivelio.request_id`, `.model.id`, `.cache.result`, `.quality.status` | ids and outcomes |
 
@@ -1148,12 +1346,30 @@ BVSALA_SEAT_ID=worker-03   # stable per replica; [A-Za-z0-9._:/-], max 128 chars
 
 ## Licensing & privacy
 
-BV‑SALA is commercial software: a per‑seat subscription (**€4 / seat / month** or
-**€39 / seat / year**, EUR; VAT not included), paid whether or not you save, plus a
-tiered commission on measured savings only, as described at the top of this page, in
-[LICENSE](./LICENSE) §6 and in the Published Pricing it refers to,
-**[savings.bivelio.com/pricing](https://savings.bivelio.com/pricing)**. No free tier and no trial: what you can check before
-paying is the published measurement. The license is a signed token your SDK and the
+BV‑SALA is commercial software. The plans are **Measure** (free), **Pro** (per seat),
+**Team** (a number of seats included, plus each extra seat) and **Enterprise** (by
+contract); Pro and Team are paid whether or not you save and carry **no commission** on
+your savings. The prices are at the top of this page, in [LICENSE](./LICENSE) §6 and in
+the Published Pricing it refers to,
+**[savings.bivelio.com/pricing](https://savings.bivelio.com/pricing)**. No trial. There is one free license,
+**Measure** — no card, one organization per verified account, up to 5 seats and 20,000
+requests a day: the layer runs in **shadow mode**. Every request goes to your provider
+exactly as you built it, nothing is served from any cache, no lever is applied, and
+`report.measure.wouldHaveSaved` (with `basis: "shadow"`) says what the exact cache and
+in‑flight coalescing would have saved on that request, valued with your provider's own
+counter — a lower bound, never part of any commission. The levers need a paid plan: once
+you upgrade, a layer with `serviceAccountKey` and `licenseServerUrl` picks up the paid
+license by itself and turns them on without a restart.
+
+The earlier plan — a lower per‑seat fee plus a tiered commission on measured savings
+only — is **closed to new customers**; a subscription already on it keeps it unchanged.
+On that plan your first month carries no commission (the first calendar month, UTC, in
+which your organization reports usage); after that the commission is charged on the
+measured saving only — never from estimates — at a tiered rate from 10 % down to 4 %, so
+you keep at least 90 % of every euro saved (before rounding to the cent; the seat fee is
+separate).
+
+The license is a signed token your SDK and the
 gateway verify **offline**; the managed control plane and the revocation kill‑switch
 are served from BiVelio. Your LLM traffic goes **straight to your provider** —
 BiVelio receives per‑request usage (counts, cost, the model id and opaque ids), never