Architecture Decision Records

This project keeps no ADR log. There is no docs/adr/ directory and no numbered series of decision records to read.

The decisions themselves are written down — as prose rather than as a numbered series, in four places, each holding a different grain of “why”. This page says which one to reach for.

Where the “why” lives

Where	What it holds
Design decisions	The framework-level choices and what each one costs: Bun first, ts-pattern over switch, the single-threaded model, which CRDTs ship, HOCON over YAML, no Streams DSL, explicit replyTo refs, no cross-actor transactions.
JSDoc in src/	Why one specific constraint, bound or trade-off is what it is, next to the code it governs. The repo’s rule is that JSDoc explains the why — constraints, rationale, non-obvious trade-offs — never a restatement of the code.
CHANGELOG.md	What changed in each release and what prompted it. Breaking changes carry a BREAKING marker and a one-line migration note.
Commit bodies + the issue tracker	The working record: what was tried, what failed, and what moved a bound or a default after measuring.

For the stability commitment a decision implies, see Version policy.

Where a new decision goes

If you contribute something that changes a design choice, no separate ADR is expected. The repo’s AGENTS.md sets out where the reasoning belongs:

• Constraints and trade-offs → JSDoc, beside the code they govern.
• What changed and why → the commit body, referencing the issue as #NNN.
• A change of course → a comment on the issue, written as you find it rather than afterwards. A diagnosis that turned out wrong, an obvious fix that did not work, a bound that moved after measuring, or scope that belongs in another layer are each worth more written down than re-derived.
• Behaviour or API changes → a CHANGELOG.md entry, plus both documentation languages when docs are touched.

The bar is the one the issue guidance already uses: would whoever picks the thread up next — including you in six months — thank you for writing it down?

Where to next

• Design decisions — the long-form “why” behind the framework’s shape.
• Version policy — what’s stable + the upgrade story.
• FAQ — common questions about the framework.