@bivelio/savings-layer 0.5.1 → 1.0.0

package/README.md

@@ -11,50 +11,119 @@
 <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">
+  <img src="https://img.shields.io/badge/license-Apache--2.0-2F63D8" alt="Apache-2.0">
+  <img src="https://img.shields.io/badge/runtime%20dependencies-0-14A06F" alt="0 runtime dependencies">
+  <img src="https://img.shields.io/badge/telemetry-off%20by%20default-0F1218" alt="Telemetry off by default">
 </p>
 
-### In plain words
-
-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 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.
-
-**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).
-
-### For engineers, in one line
-
-`@bivelio/savings-layer` (**BV‑SALA**) is one layer you add inside your code, right
-where your app calls the OpenAI‑compatible or Anthropic API. For every request it
-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 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 fees, and the
-> BiVelio Terms. Not a wrapper around any third‑party library.
+### Open core: install it and it saves. No key. No signup. No telemetry.
+
+`@bivelio/savings-layer` (**BV‑SALA**) sits between your app — or your coding agent —
+and the LLM provider, and lets through only what has to be paid for: it skips calls
+that don't have to happen (exact + semantic cache, deduplication), trims what does
+(prompt-cache placement, context and tool-output compaction, serialization), and
+routes each request to the cheapest execution that meets your quality bar (model
+cascade, sibling models, provider failover) — on OpenAI, Anthropic, Gemini,
+**DeepSeek, Qwen, GLM, Moonshot**, any OpenAI‑compatible endpoint, and local
+servers (Ollama, vLLM, LM Studio).
+
+It is not a promise you take on faith: **every saving is reported request by
+request, valued with your provider's own usage counter at versioned list prices**,
+split into four ledgers (`avoided_calls`, `eliminated_tokens`, `compressed_tokens`,
+`provider_cached_tokens`) and labelled `measured`, `reference` or `estimated`.
+Nothing is sent to BiVelio unless you choose to add a key: **zero telemetry by
+default**, and prompts, completions and provider keys never reach BiVelio
+(the exact per-request fields a cloud key sends are in [LICENSE-CLOUD.md](./LICENSE-CLOUD.md) §5).
+
+The free part is the whole savings layer. What a (paid, optional) BiVelio key adds
+is the cloud: the team dashboard, shared semantic caches across seats, org
+entitlements and license management. The cloud subscription is a fixed fee, paid
+whether or not you save — Pro €15 / seat / month or €150 / seat / year; Team
+€129 / month with 10 seats included (€12 per extra seat; €1,290 / year, €120 per
+extra seat), EUR, VAT not included — and there is never a commission on what you
+save (see [LICENSE-CLOUD.md](./LICENSE-CLOUD.md) §6).
+
+### Install anywhere, in 60 seconds
+
+```shell
+# 1 · Any OpenAI SDK, any language — point it at the local gateway (Python, Node, Cursor, Aider, Cline, OpenWebUI…)
+npx @bivelio/savings-layer gateway --upstream openai --port 8403     # or: deepseek | qwen | glm | moonshot | gemini | ollama | vllm | lmstudio
+#    python: OpenAI(base_url="http://127.0.0.1:8403/v1")
+
+# 2 · Coding agents, one command, zero configuration
+npx @bivelio/savings-layer claude      # Claude Code through the gateway
+npx @bivelio/savings-layer gemini      # Gemini CLI (native Gemini protocol)
+npx @bivelio/savings-layer codex       # Codex CLI (OpenAI or ChatGPT auth)
+npx @bivelio/savings-layer qwen        # Qwen Code
+npx @bivelio/savings-layer aider       # Aider
+
+# Claude Code with DeepSeek's Anthropic-format endpoint (cache reads at $0.003/1M):
+#   ANTHROPIC_BASE_URL=http://127.0.0.1:8402 ANTHROPIC_AUTH_TOKEN=<deepseek key> claude
+#   with: npx @bivelio/savings-layer gateway --upstream deepseek
+
+# 3 · Your app, TypeScript/JavaScript — the SDK in your code (zero runtime dependencies)
+npm i @bivelio/savings-layer
+```
+
+```ts
+// The imports come from the "Wrap the call" block below; this block compiles
+// together with it (the repo test concatenates every README block into one
+// program, as if you pasted them in order).
+const provider = new OpenAICompatibleProvider({
+  baseUrl: "https://api.openai.com/v1",
+  apiKey: process.env.OPENAI_API_KEY,
+});
+const layer = createSavingsLayer({
+  provider,
+  // OPEN CORE: nothing else is required — COMMUNITY mode, zero telemetry.
+  // For the cloud dashboard + team metering, add (all optional):
+  //   // licenseKey: process.env.BIVELIO_LICENSE_KEY,   (optional: cloud)
+  //   // licenseServerUrl: "https://savings.bivelio.com",
+  //   serviceAccountKey: process.env.BIVELIO_SERVICE_KEY,
+});
+
+const { text, report } = await layer.generate({
+  model: "openai/gpt-4o-mini",
+  messages: [{ role: "user", content: "What is 2 + 2 * 3?" }],
+});
+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.basis);               // "estimated": nothing ran, so there is no provider counter
+```
+
+`npx @bivelio/savings-layer init` prints the exact three steps for your stack
+(Next.js, Express, Vercel AI SDK, Mastra, LangChain.js, Anthropic/OpenAI SDK) and
+`npx @bivelio/savings-layer doctor` prints the exact configuration for every
+installed coding agent. The published benchmark, trial by trial, with the raw CSV,
+is at **[savings.bivelio.com/en/how-it-works](https://savings.bivelio.com/en/how-it-works)**.
+
+### Community vs Cloud
+
+| | Community (default, no keys) | Cloud (optional `BIVELIO_*` keys) |
+| --- | --- | --- |
+| Exact + semantic cache, deduplication of identical requests | ✅ | ✅ |
+| Model cascade, sibling routing, prompt-cache placement | ✅ | ✅ |
+| Compression, output contracts, four savings ledgers | ✅ | ✅ |
+| Gateway + `bvsala` CLI + MCP server | ✅ | ✅ |
+| Team dashboard, seat metering, shared caches | — | ✅ |
+| Anything sent to BiVelio | **Nothing** | Per-request usage only (counts, cost, model id, opaque ids — [LICENSE-CLOUD.md](./LICENSE-CLOUD.md) §5), never prompts or keys |
+
+A license key that **is** configured but invalid or expired still fails closed with
+`LicenseError` — only its absence is a working product.
+
+### Cloud pricing (the optional, paid part)
+
+The cloud subscription is a fixed fee, paid whether or not you save: **Pro
+€15 / seat / month** or **€150 / seat / year**; **Team €129 / month with 10 seats included** (**€12 per extra seat**; **€1,290 / year, €120 per extra seat**), EUR, VAT not included. The first month carries no commission, and the
+commission on measured savings runs from **10 % down to 4 %** by volume —
+keeping you **at least 90 % of every euro saved**, never from estimates, and
+shadow-mode usage is never part of any commission. No trial. The free
+**Measure** license (no card) still exists for the cloud: it runs the layer in
+**shadow mode** — nothing is served from any cache, nothing you send is
+changed — and shows what the levers would have saved, request by request. The
+older commission-only modality is **closed to new customers**. Your
+prompts, completions and provider keys never reach BiVelio: a cloud key sends
+only the per-request usage fields listed in [LICENSE-CLOUD.md](./LICENSE-CLOUD.md) §5.
 
 ## Where it installs
 
@@ -74,25 +143,22 @@ products charge a flat subscription, so there is no per‑token bill to cut. The
 story, in plain words:
 **[Where does the saving install?](https://savings.bivelio.com/en/how-it-works)**
 
-**A coding agent with an API key?** The package also ships a local measuring
-gateway: `bvsala claude` (or `bvsala codex`, `goose`, `qwen`, `opencode`, `kilo`,
-`copilot` with your own Anthropic key, `aider`) launches the agent through it and your real
-spend shows up in your dashboard, token by token — nothing to configure, nothing
-persisted. On exit it tells you how many requests it metered and which ones it
-could not, and why. For Crush, Droid, Cline, Continue or Copilot in VS Code,
-`bvsala doctor` prints the exact config block. Gemini CLI and Cursor cannot be
-metered today, and the doctor says so. Like the SDK, the gateway is
-fail‑closed: it starts only with your service key (`BIVELIO_SERVICE_KEY`) and an
-active BiVelio license, which it collects with that key and verifies against the
-key embedded in the package. Once running it never interrupts a request in flight:
-if the license lapses, only new requests are refused (HTTP 402) until it is
-renewed. It measures every request. With a PRO license it also applies one saving
-by default: it shortens the cache-write TTL while your session stays hot, which
-changes the price, never the content the model reads. The other levers (sibling
-model, per-turn effort) stay off until you switch them on. On a Claude or ChatGPT
-subscription there is no per-token invoice, so that traffic is metered at
-list-price equivalent and never carries commission; the per-seat license applies
-as for any other use.
+**A coding agent with an API key?** The package also ships a local gateway:
+`bvsala claude` (or `bvsala codex`, `goose`, `qwen`, `opencode`, `kilo`, `gemini`,
+`copilot` with your own Anthropic key, `aider`) launches the agent through it and
+your real spend is metered locally, token by token — nothing to configure,
+nothing persisted. On exit it tells you how many requests it metered and which
+ones it could not, and why. For Crush, Droid, Cline, Continue, Cursor or Copilot
+in VS Code, `bvsala doctor` prints the exact config block. The gateway starts
+with **no keys at all** (COMMUNITY mode: every local saving lever armed, zero
+telemetry); `BIVELIO_SERVICE_KEY` adds the cloud dashboard and org entitlements.
+Once running it never interrupts a request in flight: with a live license that
+lapses, only new requests are refused (HTTP 402) until it is renewed. The
+cache-write TTL lever (1h→5m, the saving that changes the rate, never the
+content the model reads) is armed by default; the other levers (sibling model,
+per-turn effort) switch on with their flags. On a Claude or ChatGPT subscription
+there is no per-token invoice, so that traffic is metered at list-price
+equivalent and never carries commission.
 
 **The gateway forwards what your terminal sends.** With no lever armed, your
 provider receives the request body byte for byte and every header your client
@@ -117,6 +183,8 @@ the language:
 ```bash
 bvsala gateway --upstream openai --port 8403   # one gateway per upstream
 bvsala gateway                                 # Anthropic, the default, on 8402
+bvsala gateway --upstream deepseek             # DeepSeek: /v1/messages → its /anthropic endpoint
+bvsala gateway --upstream gemini               # Gemini protocol (bvsala gemini wraps the CLI)
 ```
 
 Flags and environment variables are in English (`--port`, `--project`, `--force`,
@@ -142,13 +210,14 @@ claude = Anthropic(base_url="http://127.0.0.1:8402")    # NO /v1
 ```
 
 With `BIVELIO_SERVICE_KEY` set, the gateway measures every request whose usage the
-provider reports — Anthropic Messages, OpenAI Chat Completions and Responses, streamed
-or not — for models with a list price in its catalog, priced at that list price. A
+provider reports — Anthropic Messages, OpenAI Chat Completions and Responses, and
+the Gemini protocol (`:generateContent` / `:streamGenerateContent`), streamed or
+not — for models with a list price in its catalog, priced at that list price. A
 request it cannot meter (a model without a list price, a body it cannot read, a stream
-that never asked for usage) is still forwarded, and its log line says so and why. That
-is measurement, not savings: the saving levers of the SDK are TypeScript, and the
-gateway's own levers apply to Anthropic `/v1/messages` traffic with a PRO license.
-`bvsala doctor` prints the recipe for each SDK.
+that never asked for usage) is still forwarded, and its log line says so and why.
+Without a key (COMMUNITY mode) the metering numbers stay local: the local report
+routes below work the same, and nothing is sent to BiVelio.
+`bvsala doctor` prints the recipe for each SDK and agent.
 
 Each request can also bring its report back to your code. Send the header
 `x-bvsala-report: 1` (in Python, `default_headers={"x-bvsala-report": "1"}` on
@@ -163,12 +232,11 @@ provider, and a request without it is not changed at all:
 
 ## Check it before you install
 
-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 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.
+What you can check before installing 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)**.
+With no keys at all, the layer runs the full savings stack locally on your own
+traffic and reports per request — nothing leaves your machine.
 
 **Upgrading from 0.4?** Every breaking change of 0.5, with a before and after for
 each, is in [Migrating from 0.4 to 0.5](https://savings.bivelio.com/en/migrate-to-0.5).
@@ -204,13 +272,13 @@ to a built‑in estimate and the reconstructed savings are less accurate. Either
 saving where the layer removed something is reported as `estimated`, and estimated
 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)
-(free **Measure** license, no card; **Pro** €15 / seat / month or €150 / seat / year;
-**Team** €129 / month with 10 seats included — EUR)
+**2 · The cloud (optional)** — a [BiVelio key](https://savings.bivelio.com/dashboard/install)
+adds the team dashboard, shared caches and license management. Skip this step and
+nothing changes except the dashboard: the layer keeps working, fully, offline.
 
 ```bash
-export BIVELIO_LICENSE_KEY=…   # your license key
-export BIVELIO_SERVICE_KEY=…   # service-account key: auto-renewal + seat metering (required by the gateway)
+export BIVELIO_LICENSE_KEY=…   # optional: a key that IS set but invalid still fails closed
+export BIVELIO_SERVICE_KEY=…   # optional: cloud metering + license auto-renewal
 ```
 
 **3 · Wrap the call** — this is the entire code change. The package is ESM only:
@@ -232,9 +300,11 @@ const provider = new OpenAICompatibleProvider({
 
 const layer = createSavingsLayer({
   provider,
-  licenseKey: process.env.BIVELIO_LICENSE_KEY,        // required — from your savings.bivelio.com dashboard
-  licenseServerUrl: "https://savings.bivelio.com",    // revocation list, renewal + metering — omit it and the two lines below do nothing
-  serviceAccountKey: process.env.BIVELIO_SERVICE_KEY, // seat metering + AUTO-RENEWAL pickup
+  // OPEN CORE: nothing else is required — COMMUNITY mode, zero telemetry.
+  // For the cloud dashboard + team metering, add (all optional):
+  //   // licenseKey: process.env.BIVELIO_LICENSE_KEY,   (optional: cloud)
+  //   // licenseServerUrl: "https://savings.bivelio.com",
+  //   serviceAccountKey: process.env.BIVELIO_SERVICE_KEY,
 });
 
 const { text, report } = await layer.generate({
@@ -372,7 +442,7 @@ point, from a subpath of this same package. The four adapters behave alike:
 - **Tools are treated as having side effects** unless you list them in
   `readOnlyTools`: a request that offers any other tool is never answered from a
   cache, because the action has to run.
-- **Fail‑closed, like the SDK**: without an active license the call fails with
+- **Open core, like the SDK**: with no key the adapter runs in COMMUNITY mode; a key that is set but invalid fails closed with
   `LicenseError` (a framework may wrap it, keeping its name and message) and the
   model is not called. **Put the adapter last**, so nothing sits between it and the
   model.
@@ -392,8 +462,8 @@ import { openai } from "@ai-sdk/openai";
 import { savingsMiddleware, getSavingsReport } from "@bivelio/savings-layer/ai-sdk";
 
 const savings = savingsMiddleware({
-  licenseKey: process.env.BIVELIO_LICENSE_KEY,
-  licenseServerUrl: "https://savings.bivelio.com",
+  // licenseKey: process.env.BIVELIO_LICENSE_KEY,   (optional: cloud)
+  // licenseServerUrl: "https://savings.bivelio.com",
   serviceAccountKey: process.env.BIVELIO_SERVICE_KEY,
   readOnlyTools: ["get_weather"],
 });
@@ -419,8 +489,8 @@ import { Agent } from "@mastra/core/agent";
 import { savingsProcessor } from "@bivelio/savings-layer/mastra";
 
 const bivelio = savingsProcessor({
-  licenseKey: process.env.BIVELIO_LICENSE_KEY,
-  licenseServerUrl: "https://savings.bivelio.com",
+  // licenseKey: process.env.BIVELIO_LICENSE_KEY,   (optional: cloud)
+  // licenseServerUrl: "https://savings.bivelio.com",
   serviceAccountKey: process.env.BIVELIO_SERVICE_KEY,
   onReport: (r) => console.log(r.cost.basis),
 });
@@ -451,8 +521,8 @@ import { createAgent } from "langchain";
 import { savingsAgentMiddleware, getSavingsReportFromMessage } from "@bivelio/savings-layer/langchain";
 
 const agentSavings = savingsAgentMiddleware({
-  licenseKey: process.env.BIVELIO_LICENSE_KEY,
-  licenseServerUrl: "https://savings.bivelio.com",
+  // licenseKey: process.env.BIVELIO_LICENSE_KEY,   (optional: cloud)
+  // licenseServerUrl: "https://savings.bivelio.com",
   serviceAccountKey: process.env.BIVELIO_SERVICE_KEY,
 });
 const lcAgent = createAgent({ model: "openai:gpt-4o-mini", tools: [], middleware: [agentSavings] }); // last
@@ -474,8 +544,8 @@ import Anthropic from "@anthropic-ai/sdk";
 import { anthropicSavings } from "@bivelio/savings-layer/anthropic-sdk";
 
 const claudeSavings = anthropicSavings({
-  licenseKey: process.env.BIVELIO_LICENSE_KEY,
-  licenseServerUrl: "https://savings.bivelio.com",
+  // licenseKey: process.env.BIVELIO_LICENSE_KEY,   (optional: cloud)
+  // licenseServerUrl: "https://savings.bivelio.com",
   serviceAccountKey: process.env.BIVELIO_SERVICE_KEY,
 });
 const client = new Anthropic({ middleware: [claudeSavings.middleware] }); // last in the list
@@ -578,18 +648,20 @@ single-shot requests only: requests that declare tools, carry tool calls or resu
 hold more than one user turn are left out unless you set
 `savings.semanticCache: "include-agentic"`.
 
-**Calibrated reuse (opt-in).** A fixed similarity floor means something different for
-every embedder and every workload, so you can make the cache earn its floor on your own
-traffic instead: `new InMemorySemanticCache({ embed, calibration: { maxErrorRate: 0.02 } })`.
-It then serves no reworded answer until your labels show, at 95 % confidence, that at
-most 2 % of the answers it would reuse from some score up are wrong, and it re-tests that
-floor as labels accumulate. Until then every candidate goes to your provider, exactly as
-it would without the cache, and the fresh answer is compared with the stored one by your
-`judge` (by default only identical answers count, which suits classification and
-structured output; pass your own for free text). Each calibrated reuse carries its bound
-and the labels behind it in `report.qualityLedger.cacheMatch.calibration`. Calibration
-costs reuses, never an extra call, and it does not change how anything is billed. If you
-already have labeled pairs, `calibrateSemanticFloor()` runs the same test offline.
+**Calibrated reuse (required to serve).** A fixed similarity floor means something different
+for every embedder and every workload, so the cache must earn its floor on your own
+traffic: `new InMemorySemanticCache({ embed, calibration: { maxErrorRate: 0.02 } })`.
+Without `calibration`, it runs in shadow mode: it may store answers for future calibration,
+but `find()` and `lookup()` never return a hit. With calibration it serves no reworded answer
+until your labels show, at 95 % confidence, that at most 2 % of the answers it would reuse
+from some score up are wrong, and it re-tests that floor as labels accumulate. Until then
+every candidate goes to your provider, exactly as it would without the cache, and the fresh
+answer is compared with the stored one by your `judge` (by default only identical answers
+count, which suits classification and structured output; pass your own for free text). Each
+calibrated reuse carries its bound and the labels behind it in
+`report.qualityLedger.cacheMatch.calibration`. Calibration costs reuses, never an extra call,
+and it does not change how anything is billed. If you already have labeled pairs,
+`calibrateSemanticFloor()` runs the same test offline.
 
 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
@@ -606,8 +678,8 @@ your provider, turn on verification sampling:
 ```ts
 const checkedLayer = createSavingsLayer({
   provider,
-  licenseKey: process.env.BIVELIO_LICENSE_KEY,
-  licenseServerUrl: "https://savings.bivelio.com",
+  // licenseKey: process.env.BIVELIO_LICENSE_KEY,   (optional: cloud)
+  // licenseServerUrl: "https://savings.bivelio.com",
   serviceAccountKey: process.env.BIVELIO_SERVICE_KEY,
   verification: { sampleRate: 0.02 }, // about 2 in every 100 eligible requests
 });
@@ -640,9 +712,11 @@ and every pair as a CSV download.
 - **Only counts leave your infrastructure.** The copy goes to your own provider, like
   the original; BiVelio receives token counts, costs, model ids and outcomes — never
   prompts or answers.
-- **`close()` settles every copy still running:** it is recorded as abandoned, never
-  as a pair. On serverless platforms, pass your runtime's `waitUntil` as
-  `verification.waitUntil` so checks can finish.
+- **`await close()` settles every copy still running and drains usage:** an
+  unfinished copy is recorded as abandoned, never as a pair. Awaiting close makes
+  a bounded final delivery attempt; calling it without await remains safe. On
+  serverless platforms, pass your runtime's `waitUntil` as `verification.waitUntil`
+  so checks can finish.
 
 </details>
 
@@ -686,7 +760,7 @@ default was not run.
 ```ts
 const leveredLayer = createSavingsLayer({
   provider,
-  licenseKey: process.env.BIVELIO_LICENSE_KEY,
+  // licenseKey: process.env.BIVELIO_LICENSE_KEY,   (optional: cloud)
   priceLevers: { deferrable: true, onCapacityError: "standard" }, // layer-wide defaults
 });
 
@@ -757,7 +831,7 @@ verbatim, so an agent that edits by exact match still sees the file as it is.
 ```ts
 const agentLayer = createSavingsLayer({
   provider,
-  licenseKey: process.env.BIVELIO_LICENSE_KEY,
+  // licenseKey: process.env.BIVELIO_LICENSE_KEY,   (optional: cloud)
   toolOutputCompaction: true, // or { exceptTools: ["read_logs"], minSavedChars: 512 }
 });
 // or per request: savings: { toolOutputCompaction: true }
@@ -825,7 +899,7 @@ saving and never part of any commission.
 ```ts
 const placedLayer = createSavingsLayer({
   provider, // Anthropic, or OpenAI GPT-5.6+ on OpenAI's own API
-  licenseKey: process.env.BIVELIO_LICENSE_KEY,
+  // licenseKey: process.env.BIVELIO_LICENSE_KEY,   (optional: cloud)
   cacheBreakpoints: "auto",
 });
 ```
@@ -860,7 +934,7 @@ async function serverlessLayer(kv: SharedKeyValue) {
 
   const layer = createSavingsLayer({
     provider,
-    licenseKey: process.env.BIVELIO_LICENSE_KEY,
+    // licenseKey: process.env.BIVELIO_LICENSE_KEY,   (optional: cloud)
     semanticCacheStore: semanticCache,
     // Passing the cache does not switch it on; this asks for it on every request.
     semanticCacheDefault: true,
@@ -893,13 +967,14 @@ async function serverlessLayer(kv: SharedKeyValue) {
   verifier, judge or configuration is refused with `CalibrationStateError`. If you pass
   your own `embed`, `verify` or `judge`, name them (`embedderId`, `verifierId`,
   `calibration.judgeId`) so a state can say what it was recorded with.
-- **One line of history.** The bound holds along one line: restore the latest state and
-  save from where it went. Instances that continue the same state at the same time
-  each spend its remaining confidence again, and the last one to save overwrites the
-  others' labels. For one bound across many concurrent instances, calibrate in a single
-  long-lived process, or offline with `calibrateSemanticFloor()`, and give every
-  instance the certified floor as `acceptThreshold`. The cached answers themselves
-  still live in each instance's memory.
+- **One line of history for in-memory snapshots.** Restoring and saving the latest
+  state continues one line. Instances that manually continue the same snapshot at
+  the same time each spend its remaining confidence again, and the last save
+  overwrites the others. Use one long-lived process or offline calibration for that
+  manual model. For shared records and one coordinated history across instances,
+  use `PgSemanticCache`: its transactions and observation IDs prevent lost labels
+  and repeated confidence spending. The in-memory cached answers still live in
+  each instance unless you inject a persistent store.
 - **Why a predicted cache read did not happen** (Anthropic's own API). With
   `cacheMissDiagnostics: true`, the layer asks Anthropic to compare each marked request
   with the one whose cache entry it expected to read, and puts the provider's
@@ -909,6 +984,32 @@ async function serverlessLayer(kv: SharedKeyValue) {
 
 </details>
 
+<details>
+<summary><b>Customer-operated PostgreSQL for caches and learning</b></summary>
+
+The optional `@bivelio/persistence-postgres` package provides `PgExactCache`,
+`PgSemanticCache`, `PgCacheBreakpointStore` and `PgConstraintMemoryStore` without
+adding a database driver to the core SDK. You supply the `pg` pool, apply its
+versioned SQL migrations yourself, and inject the stores; nothing connects or
+changes your schema automatically. Exact and semantic entries contain customer
+queries, answers or derived embeddings and need the same access, retention and
+deletion controls as the original data. Breakpoints contain fingerprints,
+timestamps and counters, never prompt text. Constraint learning stores only a
+hash of tenant, scope, provider, served model and contract.
+
+The breakpoint adapter uses revisions and compare-and-set. Semantic calibration
+uses short transactions and idempotent observation IDs, so concurrent instances
+continue one history instead of spending the same confidence budget independently.
+Both use the same deterministic candidate guards and statistical journal as memory.
+The semantic backend requires the PostgreSQL vector extension and is opt-in; existing key-value stores
+and in-memory defaults keep their previous behavior. Removing `constraintMemoryStore`
+rolls constraint learning back to process memory without reading the new table.
+
+See [`packages/persistence-postgres/README.md`](packages/persistence-postgres/README.md)
+for setup, ownership, cleanup, benchmark evidence and shutdown.
+
+</details>
+
 <details>
 <summary><b>Structured output — validated <code>data</code>, not just text</b></summary>
 
@@ -933,10 +1034,11 @@ const { data, text } = await layer.generate<{ answer: number }>({
 console.log(data.answer); // 8
 ```
 
-A question the layer answers on its own (the arithmetic of the first example)
-never reaches the model, so its `data` is the resolver's `{ value: 8 }`, not
-your schema's shape: `report.qualityLedger` says the contract was not met.
-Ask the model for anything you want in your contract's shape.
+A question the layer can answer on its own (the arithmetic of the first
+example) is only served without the model when that answer meets your schema.
+The arithmetic resolver returns `{ value: 8 }`: with a `{ answer: number }`
+contract it steps aside and the request goes to the model, which answers in
+your contract's shape.
 
 </details>
 
@@ -952,7 +1054,7 @@ 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,
+  // licenseKey: process.env.BIVELIO_LICENSE_KEY,   (optional: cloud)
 });
 
 const { text: answer, report: geminiReport } = await gemini.generate({
@@ -1158,7 +1260,7 @@ import { AnthropicProvider } from "@bivelio/savings-layer";
 
 const claude = createSavingsLayer({
   provider: new AnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY }),
-  licenseKey: process.env.BIVELIO_LICENSE_KEY,
+  // licenseKey: process.env.BIVELIO_LICENSE_KEY,   (optional: cloud)
 });
 
 const mcpTools: ToolDescriptor[] = []; // every tool your MCP servers list
@@ -1358,7 +1460,7 @@ BVSALA_SEAT_ID=worker-03   # stable per replica; [A-Za-z0-9._:/-], max 128 chars
 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
+your savings. The prices are at the top of this page, in [LICENSE-CLOUD.md](./LICENSE-CLOUD.md) §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
@@ -1382,7 +1484,7 @@ 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
-prompts, completions or provider keys; [LICENSE](./LICENSE) §5 lists every field, and
+prompts, completions or provider keys; [LICENSE-CLOUD.md](./LICENSE-CLOUD.md) §5 lists every field, and
 **[savings.bivelio.com/privacy](https://savings.bivelio.com/privacy)** says how long
 each one is kept.