# Specification
- The library is a typed in-process Rust API with no Axum router, health
endpoint, model catalog endpoint, or generic JSON dispatcher.
- Provider clients are constructed inside the router from its configuration;
embedding applications do not construct parallel model clients.
- Every provider operation is bound to a non-empty stable user identifier and
an exact model identifier.
- Every attempted model call creates exactly one durable receipt. Successful
receipts separate uncached input, cached input, thinking/reasoning, and
visible output tokens when the provider reports them. Failed calls are
recorded with unavailable metering.
- Daily UTC usage is computed by opening all receipt files and grouping by
user and actual model. The store intentionally has no indexes or hierarchy.
- Media kind is explicit. Known Ogg audio is normalized to `audio/ogg` even
when its declared MIME type is `video/ogg`.
- Background systems use the same typed provider operations and receipt store
as interactive calls; they do not own separate provider clients.
- Direct agent turns resolve exact models to Codex, OpenAI, or Gemini and
expose one normalized event contract. Complete multi-round subagent policy
belongs to `kcode-agent-runtime`.
- Image creation and reference-image modification accept only `gpt-image-2`
and `gemini-3-pro-image`; cancellation, parent linkage, error normalization,
and accounting use the same operation registry and receipt store.
- Receipt creation and writes are internal to the router; callers can read
receipts and daily totals but cannot inject accounting records.