Architecture Decision Records

cortex/docs/adr/README.md

One page per load-bearing architectural decision in cortex: what was decided, why, and what it commits us to. These are the short, updateable form of the decisions captured in the long-form architecture record docs/arch/cortex-repo.md and the judgment calls in docs/plan/bootstrap-plan.md. When the code is ambiguous, the ADRs say what was intended.

Index

ADR	Decision	Status
0001	Third-party license compatibility (MIT core; permissive deps only)	Accepted (amended)
0002	No GPL code for any purpose; clean-room from papers; black-box benchmarking allowed	Accepted (amended)
0003	Hybrid SDK: header-only templated operators, compiled glue	Accepted
0004	The Resource Manager allocates; the DFA compiler schedules	Accepted
0005	Managed lifecycle; no dynamic reconfiguration	Accepted
0006	Clean-room CV stack with an OpenCV-shaped API; no OpenCV	Accepted
0007	Dual delivery: OCI containers (with CDI) and Yocto recipes	Accepted
0008	Host Broker + Thin Client runtime topology	Accepted
0009	Crash-only RM recovery by client replay (no checkpointing)	Accepted
0010	repr(C) tensor metadata across the Rust/C++ boundary (not Arrow)	Accepted
0011	C++ dependencies via FetchContent; no package manager	Accepted (amended)
0012	MSCKF first, behind a pluggable VIO backend interface	Accepted
0013	Analytical Jacobians only (no AD, for now)	Accepted
0014	Middleware-agnostic core; Zenoh daemons as the black-box surface	Accepted
0015	Arithmetic type is a first-class template parameter	Accepted
0016	SITL vs. KPU is one build flag, confined to the Rust HAL	Accepted

Planned: A/B-partition + pull-based OTA updates (issue #99, Phase 10).

By concern

• Licensing and provenance: 0001, 0002, 0006
• Runtime architecture (KPU, RM): 0004, 0008, 0009, 0010, 0016
• SDK and math design: 0003, 0012, 0013, 0015
• Integration and configuration: 0005, 0014
• Build and delivery: 0007, 0011

Writing an ADR

• Copy template.md to NNNN-short-kebab-title.md with the next free number, and add it to the index above.
• One decision per ADR, about one page. Link the source discussion (issue, PR, or section of the architecture record) instead of repeating it.
• ADRs are append-mostly. To change a decision, either amend the ADR and say so in its Status line (small refinements), or write a new ADR and mark the old one Superseded by NNNN (reversals). Never silently rewrite history.
• Keep the Current state line honest. An ADR records intent; say plainly what is implemented and which issue tracks the rest.