# 0001. Record architecture decisions

- **Status:** Accepted
- **Date:** 2026-06-27

## Context

The engine makes a number of architectural choices that are hard to reverse and non-obvious from the code alone: the crate boundaries, the determinism stance for worldgen, the server-authoritative simulation model, the content-ID namespacing scheme, and similar. The reasoning behind such choices is valuable to future contributors but does not belong inline in the source, where it would either be lost or bloat a single guidance file.

A durable, low-ceremony place is required to record *why* significant choices were made, kept separate from the cross-cutting rules in `AGENTS.md` (which records *what* to follow) and from subsystem implementation docs (which record *how* a system works).

## Decision

Architecture Decision Records (ADRs), in the lightweight format popularised by Michael Nygard, are used to capture significant, hard-to-reverse decisions.

- Each ADR is a single Markdown file in `docs/adr/`, numbered sequentially (`0001-…`, `0002-…`).
- Each record carries a status (`Proposed`, `Accepted`, `Deprecated`, or `Superseded by …`) and a date.
- Records are **append-only**: once accepted, an ADR is not edited to reflect a later change of mind. A new ADR is written instead and the old one is marked `Superseded`.
- New records are started from [`template.md`](template.md).

## Consequences

- The rationale behind significant choices is preserved with its historical context, independent of how the code later evolves.
- `AGENTS.md` stays lean: it can state a rule and link to the ADR that explains it, rather than carrying the justification inline.
- A small, ongoing discipline is required — a contributor making a significant architectural choice is expected to add an ADR for it. Trivial or easily reversible choices do not warrant one.
- Because records are numbered and append-only, the directory grows monotonically without any single file becoming a bottleneck.