Architectural Decisions#
This folder records architectural decisions for Kleidos — one Markdown file
per decision, numbered in the order they were taken
(NNNN-short-title.md).
IMPORTANT
These are living decisions. They capture the best trade-off we knew at the time, not eternal law. Hardware, constraints, and the codebase evolve, and so may these records. If you are reading one and a better approach comes to mind — a simpler design, a cheaper data layout, a clearer API — please propose it (open an issue, a PR, or just a new "Superseded by …" record). Disagreement that improves the system is the point of writing these down.
How to read a record#
Each file follows a light structure:
- Status — Accepted / Superseded / Proposed, plus the date.
- Context — the problem and the constraints that shaped it.
- Naïve / textbook approach — how this is usually done, and why the obvious version was not enough here.
- Decision — what we actually do, and the mechanism that makes it work.
- Consequences — what we gained, what we paid, and what to watch out for.
- Alternatives considered — paths we rejected, so we don't relitigate them blindly (but see the "living decisions" note above).
Index#
| # | Decision | Status |
|---|---|---|
| 0001 | Packed, tail-merged i18n string pool instead of a pointer table | Accepted (2026-06) |
| 0002 | Vault envelope context binding + freshness anti-rollback | Accepted (2026-06) |