Shared packages
Three public shared packages support the stack: JSON-Schema contracts, the provider price catalog, and stateless Go platform libraries. The price rule is the important one: unknown model means zero price plus an unpriced: tag, never a guessed cost.
The three carry mixed licensing. The data packages are open and permissive; the Go platform is the BSL core the services run on.
Wire-shape JSON Schemas.
MITThe price source of truth.
MITStateless Go libraries.
BSLcontracts MIT
shared/contracts holds JSON Schemas for wire shapes. Today it contains policy.schema.json.
The policy is small and deliberate:
runtime_mode∈record|recommend|shadow|canary|activefail_policy∈fail_open|fail_closedlimits.monthly_usd— a{ soft, hard }budget bandtelemetry.sample_rate— a number from 0 to 1
fail_policy: fail_closed aligns with the honesty rule that unknown enum cases fail closed rather than passing through. runtime_mode: record is always pass-through — byte-safe by definition. Adding a new required field is a breaking change: bump the version and coordinate the control plane, the SDKs, and the web app.
provider-catalog MIT
shared/provider-catalog is the single source of truth for provider and model token prices. It is consumed by the gateway and the optimizer for cost accounting and savings math — which is exactly why it has to be right.
It is data, not code: a YAML catalog plus a JSON Schema.
catalog/current.yaml— the live catalog.catalog/YYYY-MM-DD.yaml— dated snapshots kept alongside it, never deleted.schemas/provider-catalog.schema.json— the JSON Schema (draft 2020-12) every entry validates against.
Each entry carries provider, model, region, currency, pricing, capabilities, sources, and verified_at. Pricing covers input, output, cache-read, cache-write, reasoning, and batch rates.
A few rules keep the prices honest:
- Inapplicable pricing fields must be
null, not omitted.cache_write_input_per_millionisnullfor OpenAI and Gemini (no separate write fee); Anthropic charges both. batch_discount_fraction: 0.50means 50% off, not 50% of the rate.
An unknown model gets a zero price, not a guess
Prices feed the Cave Plan headline, so a wrong price is a wrong inferred saving. The catalog never borrows. When a model is unknown, the lookup returns an honest zero price plus an unpriced:<provider>/<model> tag — and callers must check that tag rather than silently trusting the zero. Always verify a new entry against the provider's own cited pricing page before committing it.
platform BSL 1.1
shared/platform is a set of stateless Go libraries used by public Go packages and services. No product workflow belongs here; only shared primitives for cost, safety, HTTP, IDs, redaction, env handling, and security.
| Sub-package | What it provides |
|---|---|
catalog | Price lookup over the provider catalog; unknown model → zero + unpriced: tag |
cost | Price + Usage structs; EstimateUSD (rounds to 6 decimals) |
ssrf | ValidateURL / ValidateHost pre-flight + dial-time DialContext |
redact | String / Error / ScrubHeaders — scrubs sk- keys, bearer tokens, DSNs, PEM blocks |
security | GenerateProjectKey (cave_live_<…>), HMAC-SHA256 hash, Argon2id password hash/verify |
env | typed env helpers; RefuseProductionDefaults hard-fails on prod with empty/default secrets |
httpx | JSON response helpers, ErrorEnvelope, RequestID, DecodeJSON (max-bytes + unknown-field rejection) |
id | NewUUIDv7, NewTraceID, NewSpanID (crypto/rand; panics with no entropy) |
The catalog sub-package carries the same honest-zero rule as the data catalog above: an unknown model returns a zero cost.Price{} and an unpriced:<provider>/<model> version string. Silently trusting that zero violates no-fake-savings, so callers check the string. Two more invariants matter at runtime: env.RefuseProductionDefaults must run at prod startup, and ssrf.DialContext must be wired into every upstream HTTP client — pre-flight validation alone leaves the DNS-rebinding window open.