Architecture Decision Records (ADRs)

Phase 0 of the nirs4all integration roadmap closes the load-bearing decisions before any broad workstream can start. Each decision lives here as a numbered, frozen ADR; ADR-01 through ADR-18 form the frozen Phase-0 baseline, and ADR-19 onward extends it for later feature roadmaps.

#	Title	Status	Blocks
01	Compatibility ledger semantics	accepted	B, E, F
02	Schema evolution SLA	accepted	B
03	Separation-branch semantics	accepted	E
04	Tag / exclude mask materialization	accepted	E, G
05	Repetition-aware CV invariant	accepted	B, E, F
06	Signal-type ownership	accepted	B, E
07	Aggregation reducers in contract	accepted	B, E
08	Session / workspace persistence	accepted	E
09	Docs stack	accepted	C
10	Cross-repo release train	accepted	C, D
11	Unified error taxonomy	accepted	A, D, E, G
12	Observability hooks	accepted	A, G
13	Process-adapter security boundary	accepted	A, G
14	Public-API deprecation policy	accepted	C, E
15	Python GIL / async	accepted	D, E
16	Artifact serialization security	accepted	A, E
17	Feature flag / cutover / rollback	accepted	E, F
18	Licensing	proposed	C, D, all releases
19	Multi-source unit vocabulary & derived-combo decision	accepted	multi-source roadmap

ADR-19 onward extends the registry for feature roadmaps that build on this Phase-0 baseline; ADR-19 freezes the unit vocabulary and migration posture for the heterogeneous multi-source repetitions roadmap (docs/HETEROGENEOUS_MULTISOURCE_REPETITIONS_ROADMAP.md).

Format: each ADR is one page max, structured Status / Context / Decision / Consequences / Blocks. Changing a decision requires a new ADR that supersedes the old one (and explicitly says so).

The dag-ml-data sibling repo carries copies of ADRs 01, 02, 05, 06, 07 — the ones where the data layer is the primary enforcement site — under dag-ml-data/docs/adr/. The two ADR sets must stay byte-identical for the shared ADRs; CI validates this drift via scripts/validate_contracts.py.