Principles

Runne is built on three commitments. They originate in the Runne Engine runtime philosophy and carry through to the managed API.

Contracts over claims

Clients request work; the platform decides what is allowed and records what actually happened. Nothing is trusted on the caller's word alone:

Every API contract is validated (Zod) before it touches state.
Money moves only through explicit, auditable ledger operations — never through an implicit side effect.
Billing is derived from measured usage, not from what a caller declares.

"Done" is a claim until it carries evidence. The platform keeps the proof:

Every balance change writes a transactions row with a balance_after snapshot — the ledger is the evidence trail.
Every request writes a usage_record linking tokens to cost.
Every financial operation writes an audit_log entry (credit, debit, reserve, refund, settle, adjust, suspend).

The same standard applies to the product itself: features ship with tests and typecheck evidence, not plausibility.

Dangerous actions require an explicit grant, never ambient authority:

API keys carry scopes — a key can only call what it was granted (chat:write, balance:read).
Workspaces are isolated — every query re-checks ownership; there is no cross-tenant access by ID.
Admin actions require an explicit platform-admin role, read from the database, not a self-asserted claim.

Request the minimum scope you need, and rotate keys rather than widening them.
Treat the ledger as the source of truth for billing disputes — the balance is derived from it.
Expect "403 insufficient scope" and "402 insufficient balance" to be enforced boundaries, not bugs.