Subscription¶

One provider account in the deployment's shared pool: a Skarbiec vault item that serves every caller, whose credential Brama redeems at final use and whose plan state Brama reads from the provider's own reports. No agent owns it; the brama:agent:<agent> tag only records who banked it and who may retire it. Who may spend it on which request is the entitlement model; this page is the object itself — discovery, states, the ledger, and the credential lifecycle.

Shape and discovery¶

A subscription is a vault item tagged brama:subscription, carrying its provider in brama:provider:<provider> and its subscription id in brama:id:<id>. Brama discovers those tags and Desktop consumes the returned accounts and errors; it does not keep a second list. Vault item ids stay opaque. The credential coordinate is provider:<provider>:<subscription> (src/gateway/broker.rs).

Every subscription in the vault serves every caller. best walks the whole pool, freest plan first; a plan a caller cannot use is one whose provider refuses the credential, never one a tag withheld. An item used to need one brama:agent:<agent> tag per caller allowed to spend it, and that gate cost more than it protected: subscriptions tagged for nobody and a consumer tagged on nothing left paid plans answering all bounded credentials unavailable. The tag remains as provenance of who banked an account and decides who may retire it; it gates no routing.

For both buffered and streaming requests, members with equal plan headroom are shuffled with equal probability before selection; vault listing order and names such as primary or secondary confer no preference. The stable plan sort preserves different headroom priorities. An existing usable caller pin still takes precedence for prompt-cache affinity, while an explicit billing target remains restricted to its selected member. Blocked members remain behind unblocked members. If operating-system randomness cannot be read, selection refuses before provider dispatch and reports the failed operation and its actual OS error through the normal response diagnostics.

Discovery shells the local entitlements router's list. Executable selection and invalid-declaration refusals follow the Skarbiec integration contract. Successful listings are shared by concurrent readers; subsequent reuse requires the age declared in BRAMA_SUBSCRIPTION_LISTING_AGE_SECONDS, not a built-in duration. User-facing discovery preserves process errors, exit status and stderr, and malformed output. A trusted startup catalog may support routing, but never hides a failed live lookup in the operator's report.

An item that loses its brama:subscription mark keeps a working credential and stops existing for every listing — the one failure the deployment had no way to see, which is why /readyz reports such accounts explicitly as unroutable_accounts (metadata only, recognised by tags or by the coordinate an unmarked item lives at).

States¶

brama subscription list and GET /v1/subscription-pool report one of four states per row (src/subscription_dispatch/pool.rs):

last_redeem_error reports the refusal standing in the way, in the words of whatever refused, with fixed precedence: the credential's own cause first (set only while the grant is refused; only a sign-in clears it), then a block still in force, then the newest failed check. A lapsed block is deliberately not reported.

The usage ledger¶

BRAMA_SUBSCRIPTION_USAGE_FILE (default ~/.config/brama/subscription-usage.json, owner-readable, written atomically) holds per-subscription state: measured counters, the newest plan reading per window with its instant and source, any rate-limit block, the credential state, completion checks and the independent newest free-usage attempt. It is not a cache. Older ledgers remain readable; malformed or unreadable history is reported with its path and actual reason rather than silently replaced with an empty file. Failed writes remain visible together with last-good in-memory readings.

A legacy window with no observation instant stays visible but stale. The ledger file's modification time may be from another account or a later credential update, so it is never presented as the time that provider usage was measured. Refresh usage obtains a new provider report without replacing the historical reading on failure.

Plan windows come from each provider's own free usage report (provider lists the three supported endpoints). Other providers are reported as unsupported by this free-report path with the current credential, not as successfully queried billing APIs. Observed traffic counters remain available. A background read is due when a subscription has no reading, a reading whose window has reset, a reading that names no reset, or a failed last read; due readings are read on each maintenance pass the serving process runs itself (and each brama maintain asks for), single-flighted per subscription. A failed read never blanks a row: the last good reading is served with stale: true until a newer one replaces it.

brama subscription list --refresh-usage, Brama Desktop's Refresh usage and POST /v1/plan-usage are one capability: they explicitly request new reports through that same bounded operation, and the route narrows its answer to the accounts the caller proved it owns. Neither starts a sign-in nor sends a model request. Concurrent attempts for one subscription cannot silently skip their result. A failed attempt or an elapsed reset marks the reading stale immediately; one fresh window does not make older windows current.

In listings, usage_source names which statement the newest window is — provider (the provider's report, no quota), traffic (response headers), probe (the operator's on-demand check) or harness (the provider's report as a coding harness signed into the account relays it through its public usage command, omp usage --json, read by account discovery: the same statement as provider, obtained without a grant Brama holds, which is how a discovered account that Brama has not signed in still states what it has left; each relayed window is read at the harness's fetchedAt and only a newer reading replaces one). usage_check holds the latest free-report attempt's time, success and detail independently of completion checks. An empty limits array can mean an unread account, a failed read, expired history or an unsupported report; none means zero usage. Missing or malformed metrics from a publishing provider are errors, not unsupported reports.

Every list and refresh includes ok, observed_at_ms and errors. A partial report retains successful accounts and returns ok: false, including on HTTP 200. CLI exits non-zero; Desktop shows each failed operation beside retained stale data. If Brama itself cannot answer, the client reports the connection or decoding failure.

Blocks¶

A rate-limited provider answer records a block until the reset the provider named for the exhausted window; an answer that names no reset records no block, and the next request asks the account again. A credential awaiting re-authorization is blocked for 30 minutes (src/subscription_dispatch/usage/). A blocked credential is skipped by ordering, refused by the probe (409), and the block stands until its own expiry or the account's next successful answer.

Credential lifecycle¶

A grant carrying legacy brama_borrowed_from provenance is refused before provider authorization or refresh, even while its access token is unexpired. Its presence is not erased by manual admission or treated as an unchanged independent grant. Brama must obtain its own grant through Weles; metadata attribution and reconciliation may still read the existing record without spending or rotating it. CLI pool reports and Desktop's existing credential-refusal details retain the member and cause.

Qualify the refusal with cargo test --test subscription-capacity borrowed_grant_is_refused_before_usage_refresh -- --ignored --nocapture on the isolated gateway's vault host. Supply BRAMA, CLI_SOURCE_REVISION, GATEWAY_SOURCE_REVISION, CONSUMER, BEARER_ROLE, SKARBIEC_BIN, BORROWED_MEMBER, EXPECTED_PROVIDER and EXPECTED_ACCOUNT. Use an already-existing marked legacy fixture, never a newly copied harness grant. The real CLI journey requests usage refresh, requires the persisted refusal and unchanged account, provenance, reset journal and vault inventory, then reads the refusal again. It retains revisions, executable digest, command output and exit statuses under target/real-tests/subscriptions. This refusal case does not qualify independent sign-in success or native rendering.

An account a harness on the discovering machine reports, whose only pool member holds a borrowed grant, joins the pool as a member of its own: brama subscription discover (and every maintenance pass, which runs the same discovery) removes the borrowed member with the reason borrowed grant membership and registers a member for the account with no borrowed grant, which the gateway then signs in through Weles by itself. Qualify it with cargo test --test subscription-capacity a_borrowed_member_is_replaced_by_a_member_of_its_own_account -- --ignored --nocapture on the isolated gateway's vault host, with the same variables and BORROWED_MEMBER naming the existing borrowed member, while a harness on that host reports its account.

OAuth subscription credentials (claude-code, codex, kimi — token endpoints in src/gateway/oauth_refresh.rs) are refreshed once their stated expiry has passed: on each brama maintain pass the gateway refreshes every active expired credential, single-flighted per subscription, and a request the provider rejects forces a refresh on the request path. Refreshing costs no plan quota. API keys have no refresh path and no invented expiry.

A provider refusal such as invalid_grant, invalid_token, revoked or HTTP 401/403 records needs_reauthorization. A stored OAuth document with no refresh token also requires authentication; waiting cannot add a missing token. Transport failures remain separate from provider refusals.

When reading a stored grant fails, explicit brama subscription refresh <provider> --reason <reason> retains the subscription, provider, failed UTF-8 or JSON operation and decoder cause. A malformed document is not a provider rejection, and this diagnostic does not change refresh classification. Failure to serialize a rotated grant also retains the actual cause rather than reporting an unexplained storage failure.

Qualify decoding refusals with cargo test --test subscription-capacity credential_decode_refusal_retains_operation_and_cause -- --ignored --nocapture. Supply BRAMA, CLI_SOURCE_REVISION, GATEWAY_SOURCE_REVISION, CONSUMER, BEARER_ROLE, SKARBIEC_BIN, UNREADABLE_MEMBER, EXPECTED_PROVIDER, EXPECTED_ACCOUNT, EXPECTED_DECODE_OPERATION and EXPECTED_DECODE_CAUSE. Run separately against an existing invalid-UTF-8 fixture and an existing malformed-JSON fixture; expected operation and decoder cause must come from that fixture, not from the command under test. The provider must have only that member on the isolated gateway because refresh is provider-wide. The journey never creates or replaces a grant; it requires refusal, preserved account/reset state and unchanged vault inventory, retaining the real commands, exit statuses and revision-bound report. It does not qualify successful OAuth exchange or serialization failure.

The gateway reads the live subscription inventory from Skarbiec. For a subscription requiring authentication it asks Weles to resolve the same subscription id against Skarbiec, then execute the provider OAuth flow on its Stado-selected host. Account identity, login method and login material come from Skarbiec; Weles has no independently maintained account catalogue. The account is the subscription item's own account_ref, or else its brama:account:<address> tag, which brama subscription attribute writes from the member's own grant; Weles then signs in through the login row whose username is that address and which declares a login_method (google_sso, email_password, or email_code for an account an acquisition bought, whose sign-in code Weles reads from its inbound mailbox). An optional existing login reference may identify the item, but no additional brama:login: tag is required to make an account eligible.

Weles performs OAuth without launching provider CLIs or copying their local sessions. The captured grant is persisted for the same subscription and Brama checks the persisted grant through its refresh path. Credential writes preserve the item's context and other fields, rather than replacing its account identity.

automatic_sign_in reports not_observed, failed, succeeded or not_applicable. Its last_attempt retains the actual failed operation, HTTP status, Weles run id, account-data revision and returned detail. No authentication failure is inferred from an inventory tag. A non-retryable provider challenge is not repeated against unchanged account data; changed Skarbiec data is resolved again automatically. Readiness exposes these same observations under automatic_sign_in.blocked; unknown host placement is null, not a claim that the host is correct. See the credentials runbook.

Acquisition¶

When every claude-code account in the pool has spent its plan and the pool holds fewer accounts than the operator allows (claude_code_accounts_max in src/subscription_dispatch/acquire/numeric-provenance.json, with his words), a brama maintain pass has Weles buy one on the plan tier the pool's accounts hold, records it as claude-code-acquired-<UTC time> and proves its grant. Each account's plan is read fresh from the provider at that moment; an account whose plan cannot be read stops the purchase instead of counting as spent. After an automatic purchase that failed, passes buy nothing until an operator runs brama subscription acquire. brama subscription handover then signs the account into a harness on the operator's machine through that harness's own login, so no grant is shared.

Donation and retirement¶

POST /v1/subscription-pool (and the account/admin variants) banks a credential onto the coordinate the operator's routes table already names for that subscription. A donation is refused unless the document reduces to a bearer — the same reduction the request path applies — so a non-credential document can never overwrite the one copy of a working account. The plaintext crosses only the request body and the entitlements-router stdin pipe; the overlay file (BRAMA_DONATED_SUBSCRIPTIONS_FILE, default ~/.stado/var/brama/donated-subscriptions.json, atomic 0600 rewrite) holds metadata only.

DELETE retires: an append-only journal record ({"kind":"retire","id", "at"} in BRAMA_STATE_DIR/journal.jsonl) that outranks whatever the last refresh concluded, never a vault deletion. A retired subscription is never refreshed, because rotating its grant would put back what somebody removed.

Not to be confused with¶

• A capability. The capability is the deployment's direct spend; a subscription is an agent's delegated account.
• An entitlement. Owning the item is not the decision about who may spend it on which request — that is entitlement.