Architecture Decision Records

One file per decision. Format: Context → Decision → Consequences. Immutable once Accepted — a reversal is a new ADR that supersedes the old one, which is then marked Superseded by ADR-nnnn rather than edited. A later ADR that narrows part of an earlier one without reversing it is an amendment: the earlier ADR keeps its status and gains an Amended by pointer, so the record stays navigable without being rewritten.

Status values: Proposed · Accepted · Superseded by ADR-nnnn · Deprecated

ADR	Title	Status
0001	Ports and adapters (hexagonal) architecture	Accepted
0002	Async-first core on anyio; sync facade derived	Accepted
0003	No lowest common denominator: capabilities + .native	Accepted
0004	Thin core; adapters behind extras, lazily imported	Accepted
0005	Secure by default, enforced in v0.1	Accepted
0006	Isolation tier is a first-class, reported property	Accepted
0007	The contract suite is the adapter specification	Accepted
0008	Dual configuration: DSN strings and typed config objects	Accepted
0009	Library first; MCP is the first server; sandboxio-server is gated	Accepted
0010	Error codes are public, semver-covered API	Accepted
0011	OTel GenAI semconv isolated behind one mapping module	Accepted
0012	No telemetry, no import side effects	Accepted
0013	Complement OpenAI's SandboxClient, do not compete with it	Accepted
0014	Project name: sandboxio, short code SBX	Accepted
0015	Python floor 3.11; develop on 3.14	Accepted
0016	MIT license; DCO for contributions	Accepted
0017	SandboxTimeout does not inherit the builtin; timeouts split by phase	Accepted
0018	IsolationTier ordering via an explicit rank; UNKNOWN is the default	Accepted
0019	Streaming returns a Process context manager, not a bare iterator	Accepted
0020	Shielded teardown with a bounded grace; the mandatory timeout is the backstop	Accepted
0021	One operation record, three renderings; no inline cost	Accepted
0022	Hand-written sync facade over a per-sandbox portal, with a parity test	Accepted
0023	Docker cannot filter egress; dependencies come from images or wheelhouses	Accepted
0024	Docker declares STATEFUL_CODE off in v0.1	Accepted
0025	v0.1 ships Docker + E2B + Fake; Modal moves to v0.1.1	Accepted
0026	Documentation under CC BY 4.0; code stays MIT	Accepted
0027	Blocking adapters get their own thread budget, not anyio's	Accepted
0028	Docker containers ship hardened, minus the flags that break images	Accepted
0029	Docs site: MkDocs Material on GitHub Pages at docs.sandboxio.dev	Accepted

Decisions not yet made live in ../open-questions.md and graduate to an ADR here when settled.