Status: Living index Last updated: 2026-06-24 Related: ../standards/adr-template.md, ../standards/documentation-style.md, ../architecture/build-vs-consume.md
This directory holds the load-bearing decisions that define what Provna is, what it deliberately is not, and where its real engineering effort goes. An ADR (Architecture Decision Record) captures a single decision: the Context that forced a choice, the Decision itself (with the alternatives we considered and rejected written inline), and the Consequences we accept as a result. ADRs are append-only history: we do not delete a decision, we supersede it with a newer one and update the status.
We use a condensed MADR format. Each record leads with the same three sections so a reader can scan Context to Decision in seconds. Alternatives are not a separate section: they are written inline in the Decision as Considered: A (rejected: ...), B (...); chose X because .... Consequences split into ### Positive and ### Negative because every real decision costs us something, and naming the cost is how we keep ourselves honest. See ../standards/adr-template.md for the exact shape.
Write one when a decision is (a) hard to reverse, (b) cross-cutting (it constrains more than one component), or (c) likely to be questioned later ("why didn't you just use OPA / undo everything / go horizontal?"). A decision that only affects one file's internals does not need an ADR; a decision that shapes the moat does.
- Proposed - decision drafted, not yet ratified (often blocked on an external dependency such as trademark clearance).
- Accepted - ratified; the codebase and plan must be consistent with it.
- Superseded by NNNN - replaced by a later ADR.
- Deprecated - no longer applies and not replaced.
| # | Title | Status |
|---|---|---|
| 0001 | Atomic unit is the guarded saga step | Accepted |
| 0002 | Vertical FS back-office beachhead | Accepted |
| 0003 | Build-vs-consume boundary | Accepted |
| 0004 | S1: CaMeL P/Q isolation + runtime-taint fusion | Accepted |
| 0005 | S2: DBOS substrate, BUILD the compensation library | Accepted |
| 0006 | S3: AND-gate + attenuation + behavioral admission | Accepted |
| 0007 | S4: Merkle + external anchor + JCS | Accepted |
| 0008 | Polyglot data-plane / control-plane split | Accepted |
| 0009 | ActionGuard seam, vendor-neutral surfaces | Accepted |
| 0010 | Fail-closed everywhere | Accepted |
| 0011 | Open-source boundary, proprietary core | Accepted |
| 0012 | Pricing: metered governed-action, no per-seat | Accepted |
| 0013 | Deployment: customer VPC / air-gapped, K8s/Helm | Accepted |
| 0014 | Name "Provna" + trademark clearance | Proposed |
ADRs 0006 through 0014 are authored in adjacent clusters; this index is the canonical home for the full list. Each row links to the record; the records never restate this table.