Architecture decision records
Decisions that shape Halos. New ADRs use MADR: context, drivers, options, outcome, consequences. Load-bearing changes get an ADR before code.
| ADR | Decision |
|---|---|
| 0001 | Environment as policy is the primary delivery path |
| 0002 | Rings point at immutable releases |
| 0003 | Experiments run on the traffic plane first |
| 0004 | Shadow traffic is single-turn only (amended by 0014) |
| 0005 | Releases are signed OCI bundles |
| 0006 | Go, with the Kong Go PDK |
| 0007 | Guardrails in Go, Rego pluggable later |
| 0008 | Signed ring pointers and verified artifacts (refines 0005) |
| 0009 | Signed, poll-based kill switch for experiments |
| 0010 | Release channels for client-axis experiments (extends 0008) |
| 0011 | Gateway-enforced device posture and CLI version |
| 0012 | halos.dev/v1 is the stable policy API |
| 0013 | Halos manages clients behind a gateway it does not run |
| 0014 | Step-level shadowing of multi-turn agent sessions (amends 0004) |
| 0015 | RBAC roles for halo-server |
| 0016 | Audit export to SIEM, with rotation across a continuous hash chain |
| 0017 | Cost budgets and quotas enforced at the gateway |
| 0018 | Org hierarchy: units with delegated owners that can only tighten the baseline |
| 0019 | Harness coverage beyond the big four: OpenCode and Cursor CLI |
| 0020 | Harvesting shadow sessions into replay evals (builds on 0014) |
| 0021 | HA control plane on Postgres: shared state, leader lease, fencing |
| 0022 | SCIM 2.0 provisioning: immediate deprovisioning, authoritative directory groups |
| 0023 | Workload identity federation for headless CI and cloud agents |
| 0024 | Agent identity and delegation: RFC 8693 act chains, root-principal routing, remote A2A agent allowlist |
| 0025 | Vendor admin sync: one policy drives the vendors’ cloud admin consoles, with drift detection (amended after security review) |
| 0026 | Per-credential revocation: jti and per-subject epochs for agent and workload credentials, enforced by halo-server and gateways |
| 0027 | Randomized delivery ROI: PR outcomes joined to experiment arms for causal effects; ring comparisons labelled observational |
| 0028 | Agent supply chain and AI-BOM: digest-pinned, scanned and signed extensions; CycloneDX 1.6 AI-BOM with SLSA provenance |
| 0029 | MCP registry and authorization: approved, pinned servers rendered into every harness, drift from halod, audience-bound tokens from halo-server |
| 0030 | Change governance: freeze windows and an incident freeze (never holding rollbacks), approver quorums with separation of duties, and an impact preview |
| 0031 | Agent session ledger: one identity-linked, redacted record per agent session, stored in the audit chain |
| 0032 | Egress and sandbox policy: one harness-neutral policy rendered into each harness’s native sandbox and egress controls, warned where a harness cannot hold it, verified on the device |
| 0033 | Data-loss prevention and prompt-injection defense at the gateway: secrets monitored, redacted or blocked per ring and unit, injection signals on tool results, audited to the SIEM |
| 0034 | Cloud agent governance: SHA-pinned rendered workflows, an identity-mapped task inventory from HMAC-verified webhooks and vendor APIs, kill fan-out and reversible over-limit pauses |
| 0035 | Policy copilot: the model drafts, Halos’ validator, plan, impact and stats verify, a human approves; schema-checked output, capped spend, offline mode |
The canonical files live in docs/adr/ in the repository; the docs build copies them into the site.