Architecture Decision Records
This directory holds the architectural decisions that shape noyalib — the choices that would be expensive to reverse and that contributors should understand before proposing structural changes.
Format
Every ADR uses Michael Nygard’s format
— see TEMPLATE.md. Sections are:
- Status: proposed / accepted / superseded / deprecated
- Context: what forces are at play
- Decision: what we’re doing
- Consequences: what becomes easier and harder
ADRs are immutable once accepted — if a decision changes, the old ADR moves to “superseded” and a new ADR is added with a reference back. Nothing is silently rewritten.
Index
| # | Title | Status |
|---|---|---|
| 0001 | CST shape: parallel green tree, not unified | accepted |
| 0002 | YAML 1.2 strict semantics by default; 1.1 opt-in | accepted |
| 0003 | #![forbid(unsafe_code)] workspace-wide | accepted |
| 0004 | Opt in to lossless u64 integers | proposed |
| 0005 | Split workspace into 4 satellite repositories with strict-lockstep versioning | accepted |
| 0006 | Opt in to literal text for a String/char target reading a plain scalar | proposed |
| 0007 | Add prefer_single_quotes as an opt-in serializer config flag | accepted |
| 0008 | CompiledSchema: compile a JSON Schema once, validate many | accepted |
| 0009 | Document::set_path: parent-creating writes in the CST editor | accepted |
| 0010 | set_value accepts collections, emitted in the target node’s style | accepted |
| 0011 | Flow-collection inserts, flow renames, and one anchored-node policy | accepted |
| 0012 | Bracket-quoted key segments in the query-path grammar | accepted |
| 0013 | Located duplicate-key and key-collision errors as sibling variants | accepted |
| 0014 | Share one MSRV floor, 1.89.0, with the maintainer’s other crates | proposed |
When to add an ADR
Add one when you’re about to make a decision that:
- Is hard to reverse (changes the data model, public API surface, dependency floor, or core invariants like the unsafe policy)
- Will surprise a future contributor reading the code
- Has plausible alternatives that someone might propose later
Don’t add ADRs for routine implementation choices — those go in commit messages and code comments. The bar is “would I want a new contributor to read this before proposing the opposite?”
When not to add an ADR
- The decision is captured by the type system or a test
- The decision is implicit in well-known Rust idiom
- The decision is genuinely reversible without consequence