Publication and health¶

Publication and the host that runs Brama are boundaries owned by the release owner and the deployment operator. This page carries their contract, what the health and statistics surfaces actually prove about an integration, and the gate an integration change has to pass.

Publication and host installation¶

Outcome¶

Publish immutable per-platform archives and checksums on GitHub Releases. Deployment operators download one exact version, verify its digest, install it under a versioned host path, and control process activation with their own service manager.

Identity¶

GitHub publication, host installation, bearer verification, request-sign reading, and provider access are separate identities. Runtime credentials never enter GitHub, a release archive, or a command line.

Failure and removal¶

Build, checksum, publication, download, and host activation failures stop promotion. GitHub availability does not control an already installed service. Decommissioning stops the host process, revokes runtime grants separately, preserves the previous version until retention expires, and never deletes provider vault resources as a shortcut.

A version that changes the route registry's accepted shape is installed the same way, and the operator brings the existing document forward with brama routes migrate: it keeps only the known top-level fields, validates the result, commits it with the atomic owner-only replacement every registry write uses, and prints what it committed. Running it a second time commits the same document. Promotion rules are in RELEASE.md.

Integration health¶

Public /health proves only that ingress and static startup policy are ready. It returns status: "ok", build identity, and dependencies: "not_probed". It never redeems a credential, lists agent subscriptions, contacts a catalog or model provider, or performs a billable operation.

Protected /stats exposes bounded aggregate routing telemetry and configured direct-provider count without probing dependencies. Per-request structured errors and logs carry actual integration state:

• dependency_unavailable: the required broker, catalog, or provider seam could not serve that workflow, or the transport did not carry the provider request; inspect its recorded cause;
• provider_rate_limited or subscription_unavailable: bounded capacity was exhausted;
• provider_failure: a permanent or malformed provider result stopped replay and reached the caller;
• alias_unserviceable: the alias is declared but its one route cannot serve, and details carry the alias state and that route.

Logs identify the integration class, route, bounded attempt count, outcome, and remediation code without capability IDs, raw external payloads, prompts, or credentials. The four alias states an operator reads on /v1/aliases and brama aliases are serving, no_route, capability_absent and routes_file_invalid; the last one means the registry document was rejected whole, which happens when it carries a top-level field the deserializer does not know. Codes are catalogued in Errors and the recovery steps in Runbook.

Ownership and change gate¶

Brama maintainers own normalized protocols and routing. Provider-account owners own subscriptions, billing, quota, and revocation. Skarbiec owns secret authority; Brama release owners own GitHub publication; deployment operators own installation, process control, network, and host recovery.

An integration change is complete only when capability, configuration, data, completion, cancellation, errors, compatibility, observability, disablement, removal, examples, and approved evidence agree.