Architecture decision records

Note

Reference: accepted. The index of every architecture decision in the project.

An architecture decision record (ADR) captures one significant decision: the context, the options considered, the choice, and its consequences. ADRs are never deleted. A decision that changes is superseded by a new ADR that links back to it.

When to write an ADR

Write an ADR when a decision:

constrains how several components or future contributors work,
is expensive to reverse,
chooses between credible alternatives, or
changes a previous ADR.

Changes to accepted specifications, new action-type namespaces, and policy-language features go through the RFC process, and the RFC produces the ADR.

Statuses

Status	Meaning
`proposed`	A recommendation is written but not yet ratified, or its confirmation step is still pending
`accepted`	The decision is in effect
`deferred`	The question is recognized but intentionally postponed to a named milestone
`superseded`	Replaced by a later ADR, which is linked
`deprecated`	No longer relevant, with no replacement

Process

Copy the template to NNNN-short-title.md using the next free number.
Open a pull request with status proposed, and add the record to the index below.
A maintainer accepts the decision by changing its status when the pull request merges, following GOVERNANCE.md.
To change a decision, write a new ADR that supersedes the old one, and update both records.

Index

Project

ADR	Title	Status
0001	Record architecture decisions	accepted
0002	Rust for product and tooling	accepted
0003	Project name: Shiin	accepted
0004	Apache-2.0 license and DCO	accepted
0005	Governance model	accepted
0006	Vulnerability reporting	accepted
0007	No telemetry	accepted
0008	mdBook documentation	accepted

Engine semantics

ADR	Title	Status
0009	Deterministic enforcement	accepted
0010	Pure synchronous engine	accepted
0011	Decision values and combining	accepted
0012	Evaluation stage order	accepted
0013	Fail-closed failure semantics	accepted
0014	Cedar policy engine with TOML front-end	accepted

Policy, classification, intent, and risk

ADR	Title	Status
0015	Policy layering and trust	accepted
0016	Built-in protected resources	accepted
0017	JSON wire format and schemas	accepted
0018	Conservative action classification	accepted
0019	Path canonicalization	accepted
0020	Structured intent binding	accepted
0021	Discrete risk signals	accepted

Deployment, API, adapters, and approvals

ADR	Title	Status
0022	Local-first, daemonless deployment	accepted
0023	JSON-RPC local API	accepted
0024	Tokio, confined	accepted
0025	Adapter roadmap	accepted
0026	Adapter extensibility	accepted
0027	Approval resolutions and grants	accepted
0028	Deny-with-ticket for hosts that cannot wait	accepted

Evidence

ADR	Title	Status
0029	Hash-chained JSON Lines audit log	accepted
0030	Audit durability	accepted
0031	DSSE and Ed25519 receipts	accepted
0032	Signing key storage	accepted
0033	Enforcement levels	accepted

Rust engineering

ADR	Title	Status
0034	Edition, MSRV, and toolchain	accepted
0035	Workspace layout	accepted
0036	Error handling	accepted
0037	Unsafe code policy	accepted
0038	Supply chain policy	accepted
0039	Release tooling	accepted
0040	Platform support tiers	accepted

Deferred

ADR	Title	Status
0041	Remote approver transport	deferred to v0.6
0042	Language bindings	deferred until after 1.0

Keyboard shortcuts

Shiin