Skip to content

Architecture Decision Records (ADRs)

Historical index and governance registry of Architectural Decision Records for cordanaLLM/nucleus.

1. Overview & ADR Lifecycle

An Architecture Decision Record (ADR) documents a significant software architecture decision made for cordanaLLM/nucleus, along with its context, rationale, consequences, and automated compliance enforcement.

Once an ADR is reviewed, approved, and merged, its status is marked Accepted, and its text becomes an immutable historical document. If future technical requirements necessitate reversing or modifying an accepted architectural decision, a new ADR must be drafted that explicitly supersedes the earlier decision.

stateDiagram-v2
    [*] --> Proposed: Drafted in PR
    Proposed --> Accepted: Reviewed & Merged
    Proposed --> Rejected: Consensus against
    Accepted --> Superseded: Replaced by newer ADR
    Rejected --> [*]
    Superseded --> [*]

2. ADR Index

The following table indexes all architectural decision records governing cordanaLLM/nucleus:

ADR Number Title Status Date Primary Focus Area
ADR-0001 Declarative Version Manifest as Single Source of Truth Accepted; stream sources and architecture data: see ADR-0008 2026-09-10 Architecture SSOT & Versioning
ADR-0002 Modular KConfig Fragment Architecture Accepted; base configuration and resolution: see ADR-0008 2026-09-10 Kernel Configuration & Maintenance
ADR-0003 sched-ext & Realtime (PREEMPT_RT) Coexistence & Containment Accepted 2026-09-10 CPU Scheduling & eBPF Security
ADR-0004 Native Debian (bindeb-pkg) & UKI (systemd-ukify) Dual Packaging Accepted; OCI destination: see ADR-0006; localversion and headers packages: see ADR-0009; APT archive: see ADR-0014 2026-09-10 Packaging & Release Distribution
ADR-0005 Bidirectional Downstream Image Forge Synchronization Accepted; requirement verification: see ADR-0007 2026-09-10 Cross-Repo CI/CD Automation
ADR-0006 OCI Registry Namespace for UKI Artifacts (supersedes the OCI destination of ADR-0004) Accepted 2026-09-29 Packaging & Release Distribution
ADR-0007 Document-Driven Kernel Requirement Verification with Per-Consumer Stream Binding (supersedes section 2 of ADR-0005) Accepted; owner schema check: see ADR-0010; module ABI verification: see ADR-0015 2026-09-29 Cross-Repo Requirement Contract
ADR-0008 Signed Kernel Sources and a Resolved, Survival-Checked Kernel Configuration (supersedes decision item 1 of ADR-0001 and items 1 and 2 of ADR-0002; amends section 4 of ADR-0007) Accepted 2026-09-29 Kernel Sources & Configuration
ADR-0009 Kernel Compilation, the Artifact Gate and the Boot Smoke Test (supersedes bullets 2 and 3 of section 1 of ADR-0004) Accepted; release revisions above 1: see ADR-0011; riscv64 BTF: see ADR-0013; module signing: see ADR-0016 2026-09-29 Kernel Build & Release Integrity
ADR-0010 Requirement Documents Are Read Through the Owner's JSON Schema, Pinned by Commit and Digest (adds a check to ADR-0007) Accepted 2026-09-29 Cross-Repo Requirement Contract
ADR-0011 Function Tracing in the Baseline for BPF Trampolines, and Release Revisions Above 1 (supersedes the single-revision clause of section 2 of ADR-0009) Accepted 2026-09-29 Kernel Configuration & Release Integrity
ADR-0012 SLSA Build Level 3 via Reusable Release Build Workflow Accepted 2026-10-16 Release Pipeline & Supply Chain
ADR-0013 BTF on Every Architecture (supersedes the riscv64 BTF consequence of ADR-0009) Accepted 2026-10-16 Kernel Configuration & Artifact Gate
ADR-0014 GitHub Release Assets as the Debian Channel (supersedes the APT archive of ADR-0004) Accepted 2026-10-16 Packaging & Release Distribution
ADR-0015 Module ABI Verification from the Kernel Build Record (supersedes module-abi sentence of ADR-0007) Accepted 2026-10-16 Cross-Repo Requirement Contract
ADR-0016 Kernel Modules Are Signed After the Build, by a Recorded Step (supersedes the module-signing consequence of ADR-0009) Accepted 2026-10-17 Kernel Build & Release Integrity

3. ADR Authoring Standards

All future ADRs must adhere to the standardized structure:

  1. Title & Number: Sequential identifier (ADR-000X: Title).
  2. Date: ISO 8601 creation date (YYYY-MM-DD).
  3. Status: Proposed, Accepted, Rejected, or Superseded.
  4. Context: Technical problem statement, forces, trade-offs, and invariants.
  5. Decision: Concrete architectural choice and detailed implementation strategy.
  6. Consequences: Explicit positive, negative, and neutral trade-offs.
  7. Compliance: Automated test suites, CI quality gates, or linters that verify ongoing conformity.