State and failures¶

Every workflow on the public workflows page ends in one of two things: a result, or one classified refusal. This page names who owns the state a request reads, what a refusal looks like, how many attempts precede it, and the resource ceilings that hold under load.

State and ownership¶

Journal credentials, encrypted secret overlays, and raw provider responses are prohibited. The journal schema is append-only; an incompatible interpretation requires a release migration contract. The registry document is rewritten only by an owner-only atomic replacement, whether the writer is PUT /v1/admin/routes, DELETE /v1/admin/routes, or brama routes migrate.

Brama's state directory is BRAMA_STATE_DIR, else .brama under the service account's home. When neither is declared and no home resolves, Brama still starts and serves, and every reader and writer of that state refuses with the home's cause instead of stopping the process: a request that asks for its one signed answer is answered HTTP 500 with this request's one signed answer has no place to be kept: <cause>; the journal, the donated-subscription overlay, the model metadata cache and onboarding progress refuse their operation naming the same cause; and performance telemetry logs one perf_stats_unplaced warning with the cause at the first dispatch, then keeps the numbers in memory only.

Failure contract¶

Public errors use this envelope, where attempts counts the provider calls this request actually made; a refusal Brama made before any dispatch asked no provider and carries no attempts key:

{
  "error": {
    "message": "bounded human-readable detail",
    "type": "stable_class",
    "code": "stable_code",
    "retryable": false,
    "attempts": <provider calls made>
  }
}

An alias the registry never declared is answered 404, and that body's details carry state and route as well, so one diagnosis reads the same whether the alias is unknown or known and unserviceable. In both cases the alias has exactly one route, and the refusal from it is what the caller receives.

A response states retryable explicitly. Error message text is diagnostic, not the machine contract. Credential rotation inside one route never exceeds the attempt count the envelope reports. The full code list, with examples, is in Errors.

Cancellation and retry¶

• Buffered and streaming requests run until the provider answers, refuses, or the connection fails. Brama adds no elapsed-time cutoff before the first streamed byte or between later reads.
• Catalogue reads, provider model discovery and OAuth refresh also have no Brama elapsed-time cutoff. Provider responses are read whole; the resource behavior below describes their handling.
• Inference and OAuth transport failures retain their underlying causes. Removing a gateway clock does not turn a refused connection, TLS failure, provider refusal or incomplete stream into a successful answer.
• An OAuth response read failure names the token endpoint, HTTP status and bytes received. Even a partial 401 or 403 remains a transport failure, not evidence that the provider disowned the grant; its recorded credential state stays unchanged. Only a complete response reaches refusal classification.
• Direct routes perform one provider attempt.
• Explicit subscription routes perform at most two provider attempts, both on the one route the request named.
• Selectors try every model candidate in order, each on at most two credentials, and skip the routes of a provider whose whole pool refused.
• Brama does not retry arbitrary 5xx or malformed results automatically.
• Dropping the client connection cancels the in-process future where the HTTP stack propagates cancellation; Brama has no durable job to resume.
• A stream that has committed is never retried, on any credential, for any failure class.
• A caller must treat an ambiguous provider outcome as potentially billable and must not replay it automatically unless the returned code is retryable.

Resource behavior¶

• provider answers, OAuth answers and credentials are read whole; a size limit is a provider's own and comes back as its refusal;
• max_tokens is the caller's or, when omitted, the model's own limit;
• model and credential attempts are finite;
• the perf registry keeps one entry per route that was ever served;
• catalogue and subscription caches have explicit TTLs;
• the provider usage report pass spends no plan quota: one read per active subscription that has no reading, a reset window, a reading naming no reset or a failed last read, single-flighted per subscription, no retry inside a pass, and it runs in each of the serving process's own maintenance passes (one at start, one at each moment the ledger states something becomes due, one after a refusal for want of a signed-in subscription) and when brama maintain asks;
• the completion probe is bounded to what an operator asks for: one attempt against one named subscription per request to POST /v1/admin/subscriptions/:agent_id/:subscription_id/probe, no retry, no rotation to another credential, refused outright for a subscription inside a recorded block, and never triggered by a timer — the shipped configuration performs no quota-consuming request on any schedule;
• the credential refresh pass makes one refresh attempt per active subscription per maintenance pass, single-flighted per subscription, no retry inside a pass, a definitively refused credential left alone until a sign-in through Weles replaces it; a pass starts at a moment the ledger states (a grant's stated expiry, a plan window's stated reset, a block's stated end), never on a period of Brama's own;
• no unbounded background retry, queue, or provider worker exists;
• append-only journal growth is operator-monitored until a versioned compaction contract exists.

Evolution and completion¶

Public changes follow RELEASE.md. Provider integrations follow INTEGRATIONS.md. Every supported outcome maps to examples/ and approved evidence in TESTING.md. Obsolete fields and aliases are removed once callers have moved; Brama keeps no hidden compatibility path and no second authority for the same decision. An operator whose registry document still carries retired top-level fields brings it to the current shape with brama routes migrate, which is idempotent and prints the document it committed.

Where to go next¶

• Authorization and observability — configuration rules, secret handling, and what a routing event records.
• Errors — the full public error reference.
• Runbook — operator procedures for the failures above.