Entitlement¶

Which account pays for which request. An entitlement is the decision — made per request, from the caller's proven identity and the request's shape — about the one pool that may fund it. No other provider, agent, account, or credential is quietly put in its place: a refusal is returned as a refusal.

The signed identity¶

Spending a subscription requires the caller's own signed HMAC identity: the trio x-agent-id, x-agent-timestamp, x-agent-signature, where the signature is HMAC-SHA256 over {agent_id}:{timestamp}:{body_sha256_hex} (body_sha256_hex is the SHA-256 hex of the exact raw body, or the empty string when there is no body), with no clock window, a refusal of any signature already accepted or signed earlier than the newest one accepted for that agent (src/crypto/replay.rs, kept in $BRAMA_STATE_DIR/agent-replay.json), and constant-time comparison (src/crypto/hmac_auth.rs). The per-agent secret is resolved immediately before verification; echo, content-platform, oko, weles, lem, probierz, and wisent-app are strict central-item projections through BRAMA_REQUEST_SIGN_IDENTITIES / BRAMA_REQUEST_SIGN_CAPABILITY_IDS and never read another product's secret in its place (src/gateway/broker.rs).

Where present, three identities must agree: the bearer-bound agent, the signed agent, and the path agent — any contradiction is 403 forbidden. A missing trio on a route that needs one is 401:

$ model="best" without HMAC headers → 401
{"error":{"code":"unauthenticated","message":"missing x-agent-id header", ...}}

Which pool pays¶

billingTarget (providerId, accountId, subscriptionId) names an exact target: providerId must match the route's provider, and subscriptionId must resolve to an active, non-retired resource in the shared subscription pool. The signed identity authenticates and attributes the request; provenance tags do not partition routing. Selectors never authorize a direct provider credential.

Bounds¶

Candidate and credential selection follow the core request contract:

• a direct route: one attempt;
• an explicit subscription route walks its finite eligible credential list until a provider serves the request or a non-rotatable refusal stops it;
• a selector walks its ordered model candidates and each route's eligible credentials; a recorded block spends no provider attempt, but contributes its actual cause to the final refusal;
• a provider whose whole pool emptied is skipped for its remaining candidates and named once, not twice;
• elapsed time alone does not stop a request.

Once a stream commits, nothing is retried on any credential — a second attempt would double both the bill and the text. Only authentication, quota, and rate-limit failures rotate credentials; permanent or malformed provider failures stop replay.

Ordering and pinning¶

Candidates are ordered by what their plans have left — the maximum used fraction the provider itself reported across current windows, freest first, read from the ledger at no provider cost. A window past its own reset instant counts as empty; a subscription with no reading counts as free, because its first call writes the reading that corrects the placement. Exact ties are randomized so equal accounts stay decorrelated.

The credential that served an agent is remembered per provider and tried first on that agent's next request, until the tightest window it reported resets (five hours when the provider named none, capped at 24 hours). The pin reorders eligible candidates and nothing else: it never adds a credential, never survives a block, retirement, or a fully used window, never overrides billingTarget, and cannot outlive the process. Two things depend on it: provider prompt caches live behind one account, and one conversation's spend belongs in one account's ledger.

Selectors¶

• any — active subscription-backed stateless routes, ranked as above.
• any-vision-capable — the any contract after filtering to catalog models whose input modalities include image.
• task:<task-name> — the latest active quality observation per active model, sorted score-first then newest, plan headroom inside one score. Evidence comes only from brama collect-task-quality (cli); Brama never infers task names from prompt text.

Refusal sentences¶

Each layer refuses in its own words (all verbatim from src/subscription_dispatch/dispatch.rs; the summary sentences are shared by the buffered and streaming walks so the two cannot drift):

At the HTTP edge these surface as 429 subscription_unavailable (at least one credential was actually tried, or none exists), 503 subscription_reauthorization_required, or 503 credential_unauthorized (errors).

Not to be confused with¶

• Authentication. A valid bearer (client identity) proves transport, not spend.
• Ownership. A subscription's provenance records who banked it and governs retirement authority. It does not restrict which authenticated caller may route through the shared subscription pool.