Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Architecture decisions

The why behind the module boundaries and the contracts. Division of labor: this book's Reference states what the tool guarantees; an ADR records why a load-bearing decision was made, what it rejected, and what it constrains.

A decision earns an ADR only when it crosses module boundaries or constrains future work and it rejected a plausible alternative. Records are immutable once accepted; a change of mind produces a new record that supersedes the old.

The full records live under docs/adr/:

ADRDecisionStatus
0001An owned predicate AST between sqlparser and every consumeraccepted
0002Degrade conservatively instead of failing or guessingaccepted
0003Exhaustive capability matches over the kernel vocabulary, no catch-allsuperseded by 0008
0004The stable contracts are the CLI surface and the versioned JSON schemaaccepted
0005LIKE enters the AST as a structural node with a normalization rewriteaccepted
0006A partition-literal evaluator as a third interpreter over the same ASTaccepted
0007--explain-why is a deterministic diagnostic engine, not an ML modelaccepted
0008Owned predicate vocabulary is the pruning capability boundaryaccepted
0009Catalog names resolve to a location and the credentials to read itaccepted

The recurring theme: the value is a sound, explainable answer, so every decision protects that: one parse so interpreters cannot drift (0001), loud degradation over silent guessing (0002), an owned vocabulary as the capability boundary (0008, superseding the compile-time sentinel of 0003), a versioned contract as the only stable surface (0004), a diagnostic layer that is deterministic rather than predictive (0007), and one credential rule per mode when a catalog resolves the table (0009).