decisions

Architecture Decision Records

Every non-trivial architectural, security, or process decision in Tyrne is recorded here as an ADR (Architecture Decision Record) using a lightweight MADR (Markdown Architectural Decision Records) style.

Why ADRs

• They preserve the why, not just the what. This is the information that decays fastest and is most expensive to re-derive years later.
• They make the evolution of the project readable: you can follow the numbered history and see how the design language developed, including the options that were rejected.
• They give future contributors (human or AI) a way to disagree with a decision by writing a new ADR that supersedes an old one, rather than silently changing code.

Format

All ADRs live in this folder, named NNNN-short-kebab-slug.md, where NNNN is a zero-padded four-digit sequence number. Use template.md as the starting point for a new ADR.

Each ADR contains:

• Title (matches the filename, minus the number prefix).
• Status — Proposed, Accepted, Deprecated, or Superseded by NNNN.
• Date — ISO-8601.
• Deciders — who signed off.
• Context — the question the project was facing and the constraints that applied.
• Decision drivers — the forces that influenced the choice.
• Considered options — the alternatives examined.
• Decision outcome — the option chosen, with a short justification.
• Consequences — positive, negative, and neutral effects, with mitigations where relevant.
• References — prior art, literature, upstream discussions.

Index

#	Title	Status	Date
0001	Capability-based microkernel architecture	Accepted	2026-04-20
0002	Rust as the implementation language	Accepted	2026-04-20
0003	Apache-2.0 license	Accepted	2026-04-20
0004	Target hardware platforms and tiers	Accepted	2026-04-20
0005	English as the documentation and code language	Accepted	2026-04-20
0006	Workspace layout and initial crate boundaries	Accepted	2026-04-20
0007	Console HAL trait signature	Accepted	2026-04-20
0008	Cpu HAL trait signature (v1, single-core scope)	Accepted	2026-04-20
0009	Mmu HAL trait signature (v1)	Accepted	2026-04-20
0010	Timer HAL trait signature (v1)	Accepted	2026-04-20
0011	IrqController HAL trait signature (v1)	Accepted	2026-04-20
0012	Boot flow and memory layout for bsp-qemu-virt	Accepted	2026-04-20
0013	Roadmap and planning process	Accepted	2026-04-20
0014	Capability representation	Accepted	2026-04-20
0015	AI integration stance: userspace-only, kernel-neutral	Accepted	2026-04-20
0016	Kernel object storage	Accepted	2026-04-21
0017	IPC primitive set	Accepted	2026-04-21
0018	Badge scheme and reply_recv fastpath: formal deferral	Accepted	2026-04-21
0019	Scheduler shape	Accepted	2026-04-21
0020	ContextSwitch trait and Cpu v2	Accepted	2026-04-21
0021	Raw-pointer scheduler IPC-bridge API	Accepted	2026-04-22
0022	Idle task and typed scheduler deadlock error	Superseded by 0026 (idle-task-location axis only; typed-error axis stands)	2026-04-22
0023	Cross-table capability revocation policy	Deferred	2026-04-27
0024	EL drop to EL1 policy	Accepted	2026-04-27
0025	ADR governance amendments: forward-reference contract, rider hygiene	Accepted	2026-04-27
0026	Idle dispatch via separate fallback slot	Accepted	2026-05-06
0027	Kernel virtual memory layout (B2 — identity-mapped MMU activation)	Accepted	2026-05-08
0028	Address-space data structure (B3 — kernel-object + capability-gated Mmu::map wrappers + activation-on-context-switch)	Accepted	2026-05-11
0029	Initial userspace image format (B4 — raw flat binary)	Accepted	2026-05-14
0030	Syscall ABI and userspace error taxonomy (B5)	Accepted	2026-05-29
0031	Initial syscall set (B5 — send/recv/console_write/task_yield/task_exit)	Accepted	2026-05-29
0032	Endpoint state rollback on ipc_recv_and_yield Deadlock + ipc_cancel_recv primitive	Accepted	2026-05-07
0033	Kernel high-half migration (B6 — kernel → TTBR1_EL1, boot-time)	Accepted	2026-05-30
0035	Physical Memory Manager (B3 prerequisite — bitmap allocator)	Accepted	2026-05-09
0036	QEMU virt is GICv2 / no-IOMMU in v1; corrects GICv3/SMMUv3 in ADR-0004/0006/0012	Accepted	2026-05-22
0037	EL0 entry context (B6 — userspace register file + enter-EL0/ERET path + per-task SP_EL1)	Accepted	2026-05-31
0038	Mmu::translate read-only walk + per-task user-access translation (B6 gate #1)	Accepted	2026-05-31
0039	Userland build pipeline (B6 — userland/hello + tyrne-user + raw-flat embed orchestration)	Accepted	2026-05-31

Numbering gaps. Slot 0034 is intentionally reserved, not missing: 0034 (kernel-image section permissions — .text RX / .rodata R / .bss+.data RW at 4 KiB granularity) is a named-but-unallocated placeholder forward-flagged in ADR-0027. No file exists for it yet; it was deferred at B6 closure (B6 mapped everything as a coarse 2 MiB block; the hardening was not a functional blocker for userland/hello) and is now a Phase C carry-forward. It opens with the first C-phase task whose threat model makes kernel W+X a meaningful surface. (Slot 0033 (high-half migration) was filed Proposed on 2026-05-29 to open B6 and Accepted on 2026-05-30, and is no longer a gap; slots 0030/0031 were filed and Accepted on 2026-05-29 for B5.) ADR numbers are stable history and are never renumbered.

Creating a new ADR

The authoritative, step-by-step procedure is the write-adr skill (and supersede-adr when overriding an old ADR). Read it in full before drafting; the summary below is a reminder, not a substitute.

1. Copy template.md to the next available number: NNNN-your-slug.md.
2. Fill it in. Start with status Proposed.
3. For an ADR whose subject is a multi-step state machine (capability flows, IPC handshakes, scheduler dispatch, exception/IRQ entry, MMU/TLB transitions, syscall ABI handshakes), include a §Simulation table (3–5 rows walking the worst-case interaction) per ADR-0025 and the write-adr skill; other ADR subjects use the one-line "Not applicable" note. Every ADR's §Decision outcome must also include a §Dependency chain grounding each forward-reference in a real T-NNN (per ADR-0025 §Rule 1).
4. Open a PR (once the PR process is established) or, in the solo phase, commit directly with a descriptive commit message referencing the ADR number.
5. When the decision is settled, re-read end-to-end (per write-adr skill §10) and change the status to Accepted in a separate commit from the initial Proposed draft.
6. If a later ADR overrides this one, mark the old one Superseded by NNNN and link forward to the new record. Do not delete or rewrite the old ADR — the historical reasoning is the point.