ctos (ctsOS)

ctos is a small operating-system kernel you can study. It is written in Rust for 64-bit ARM (AArch64). You run it in the QEMU emulator, not as a desktop or phone OS. The nickname ctsOS is only for display; the repo and crate stay ctos. Why Rust (and what it does not buy): Advantages — Why Rust.

This book is the website. The same markdown lives under docs/ in the GitHub repo. There is no second marketing copy.

It is not a product site. Do not say “secure OS” or “production ready.” Say “EL0 isolated” only as the accepted ADR-091 sentence, with its limits (one core, TCG default smoke machine; not speculative-execution / side-channel, not real hardware, not a certification). Status words need a probe.

What it is

ctos boots under QEMU’s virt machine and prints on a serial port (the PL011 UART). After that it grows one honest mile at a time: exceptions, paging, a heap, a tiny scheduler, then measured security and performance cuts.

Core principles drive. Roadmap tracks (A = freestanding hosting, B = Linux-compat research, N = network foundation — N1 first-frame ADR-066, N2 ICMP ping ADR-067, N3 UDP ADR-070, N3.x EL0 UDP SVC ADR-071, N4 EL0 net sample ADR-068, N5 thin TCP ADR-074, scope ADR-063) are subordinate. A track does not outrank a principle.

Primary path: QEMU virt + UART (ADR-003). Frozen requirement IDs: FR-01–FR-15 and NFR-01–NFR-14.

Driving principles

Everyday meaning first; frozen IDs second. Same list as the pillars hub. This landing is the visitor-facing source. docs/framework/ stays for deep links — do not keep a second marketing copy.

flowchart TD
  P["Core principles<br/>honesty · antifragility · security<br/>performance · document-first"]
  L["Three pillars<br/>antifragility · security · performance"]
  T["Tracks A / B / N<br/>hosting · Linux research · net first-frame<br/>subordinate — not the driver"]
  P --> L --> T

Principles sit above pillars. Tracks sit below both. A1–A4 are ABI + CRT + loader + standing-task miles only. Not a claim that Track A hosting is built.

What runs today

Rebuild recipes for samples that already have probes. Details: What can run today. In-tree index: user/README.md.

1. Two kernel tasks that take turns — they print on the serial port and yield. Not preemptive. Not two CPUs.
2. A serial echo gadget — one byte in, a line out. No terminal, no line editor.
3. A short lower-privilege stub — a few instructions in the CPU’s user mode, including the A1 SVC ABI trip, an A2 libctos hello, an A3 guest PT_LOAD of that same hello, and an A4 standing task until exit (exit / uart_write / yield), then a call back into the kernel. Not a process. No libc. Freestanding catalog on FAT: /hello, /fsdemo (memfs VFS), /fatdemo (FAT /probe), /yldemo (yield rounds). Optional recipes: memfs named buffers and FAT16 on virtio-blk (read + write depth).

Cannot run: Linux programs, a shell, Python, network servers (Track N has virtio-net ARP + ICMP + minimal UDP + thin TCP plus tiny EL0 net/UDP SVC samples — ADR-066 / ADR-067 / ADR-070 / ADR-071 / ADR-068 / ADR-074; not BSD sockets / TCP product), POSIX filesystem apps, extra CPUs, or containers (guest OCI/Docker is a non-goal). An OS slot vs a separate app slot has an A9 first cut (FAT /hello) plus leftover cross-update on ba6541c (Verified miles); catalog also has /fsdemo / /fatdemo / /yldemo / /netdemo / /udpdemo. Product freestanding app hosting is Verified under ADR-048 / ADR-052 (not Linux/POSIX). Umbrella “EL0 isolated” is Verified only as the accepted ADR-091 sentence (M6, 2026-09-28; closure table ADR-060).

flowchart LR
  subgraph today ["Verified today"]
    W["Two UART workers"]
    E["Serial echo gadget"]
    S["Short user-mode stub"]
  end
  subgraph no ["Cannot run"]
    L["Linux binaries / shell / Python"]
    N["Network / files / extra CPUs"]
    C["Containers"]
  end
  today -.-> no

Left side matches existing smoke markers. Right side is out of scope. Do not say “apps run.”

How to build

You need nightly Rust and QEMU. Pages is not required for kernel work. Full list: Prerequisites.

rustup toolchain install nightly
rustup component add rust-src llvm-tools-preview
cargo build                 # ELF at target/aarch64-ctos/debug/ctos
./scripts/qemu-smoke.sh     # fail-closed serial + tests

flowchart LR
  R["rustup nightly"] --> B["cargo build"] --> Q["qemu-smoke"]

That rebuilds the kernel, including any in-tree code you add. It is not “port an app.”

Read next

Kernel build notes also live in the GitHub README.

URLs

Publish mechanics: Docs website + DNS.

What can run today

Plain English. These are rebuild recipes for in-tree samples that already have probes. They are not third-party applications and not a product runtime.

Track A / A8 (issue #39) is this page: document the sample classes and how to rebuild them. A9 (ADR-030) adds two host artifacts + FAT /hello. Leftover (ADR-032): A2–A4 load that file (no production embed); same ELF on this OS and ba6541c (cross-update Verified). Product freestanding app hosting is Verified under ADR-048 / ADR-052 (checklist: hosting-apps.md). Not Linux/POSIX/containers.

Status of each probe: honesty ledger. Walkthroughs: apps-today.md. In-tree index: user/README.md. Umbrella “EL0 isolated” is Verified only as the accepted ADR-091 sentence (M6; one core, TCG default smoke machine; not speculative-execution / side-channel, not real hardware, not a certification). Do not say “apps,” “userspace,” or “secure OS” as if a general-purpose OS existed.

Freestanding sample catalog (glance)

Six published EL0 ELFs on one FAT16 volume. Same rebuild path. Not Linux/POSIX.

flowchart LR
  FAT["FAT16 volume"] --> H["/hello<br/>UART + one yield"]
  FAT --> F["/fsdemo<br/>memfs VFS"]
  FAT --> D["/fatdemo<br/>FAT /probe"]
  FAT --> Y["/yldemo<br/>yield rounds"]
  FAT --> N["/netdemo<br/>net SVCs"]
  FAT --> U["/udpdemo<br/>UDP DNS SVC"]
  FAT --> M["/mkdemo<br/>fs_mkdir SVC"]
  FAT --> T["/tcpdemo<br/>net_tcp_echo SVC"]
  H --> EL0["Standing EL0<br/>libctos"]
  F --> EL0
  D --> EL0
  Y --> EL0
  N --> EL0
  U --> EL0

/hello is the A9 product-slot sample. /fsdemo (ADR-059), /fatdemo (ADR-061), /yldemo (ADR-062), /netdemo (ADR-068), /udpdemo (ADR-071), /mkdemo (ADR-075), and /tcpdemo (ADR-076) deepen the catalog. Umbrella “EL0 isolated”: only the accepted ADR-091 sentence.

Privilege — where code runs

The CPU has privilege levels. EL1 is kernel privilege (where ctos runs). EL0 is lower privilege (user mode). A process would be a loaded program with its own address space, files, and a public ABI. That process does not exist yet.

flowchart TD
  EL1["EL1 — kernel privilege<br/>Verified: this is where ctos runs"]
  EL0["EL0 — lower privilege<br/>Verified: a short standing stub only"]
  PROC["A process / application<br/>Planned: not built"]
  EL1 --> EL0
  EL0 -.-> PROC

The stub is not a process. “EL0 isolated” means only the ADR-091 sentence.

A supervisor call (SVC) is the instruction the stub uses to ask the kernel for something. Reserved SVC #0–#2 stay test miles. A1 documented exit / uart_write / yield (syscall.md). A2 wraps those in libctos. That is not a process ABI.

One rebuild for every recipe

Every sample below rides the same hello path. There is no separate “run this app” command. You rebuild the kernel (and, for freestanding EL0 samples, build.rs publishes target/hello-libctos.elf + target/fs-libctos.elf + target/fat-libctos.elf + target/yield-libctos.elf + target/net-libctos.elf + target/udp-libctos.elf + target/mkdir-libctos.elf + target/tcp-libctos.elf; A2–A4 and A9 read FAT /hello; ADR-059 loads FAT /fsdemo; ADR-061 loads FAT /fatdemo; ADR-062 loads FAT /yldemo; ADR-068 loads FAT /netdemo; ADR-071 loads FAT /udpdemo; ADR-075 loads FAT /mkdemo; ADR-076 loads FAT /tcpdemo).

cargo build                 # aarch64-ctos.json; also builds user/hello-libctos + user/fs-libctos + user/fat-libctos + user/yield-libctos + user/net-libctos + user/udp-libctos
./scripts/qemu-smoke.sh     # fail-closed serial greps + cargo test + force-fail

qemu-smoke attaches the A7 FAT16 image (target/fat16.img) and injects UART 0x41. A machine that has not run that script (or Docker / GHA equivalent) stays Unknown for boot. File presence is not the probe.

flowchart LR
  R["edit in-tree source"] --> C["cargo build"] --> S["qemu-smoke"]
  S --> M["existing serial markers"]

Rebuild the guest. Do not drop in a foreign ELF.

Recipe 1 — Cooperative UART workers (EL1)

Two tasks on heap stacks that print a line and yield to each other. Same class as sched: task a / sched: task b / sched: ok (ADR-010, FR-11).

Rebuild: edit those functions, then the one-rebuild commands above. A heartbeat / counter variant (print, yield, loop) is the natural next in-tree exercise. It is not in the tree and has no sched: beat marker — Planned until a probe greps one.

Not preemptive. Not two CPUs. Not EL0.

Recipe 2 — UART RX echo gadget

Read a byte from PL011 RX and print it. Same class as input: rx 0x41 (ADR-007, FR-08).

Rebuild: same cargo build + ./scripts/qemu-smoke.sh. The smoke host injects one byte. IRQs stay masked on this path. Do not wfi waiting for RX.

That is a byte in, a line out. No TTY, no line editor, no canonical mode, no virtio-keyboard.

Recipe 3 — Standing EL0 / libctos-loaded hello

A short payload in user mode (EL0) that uses the documented ABI, then returns. Miles stacked on FAT /hello:

Rebuild the hello (optional, standalone):

cargo build --release \
  --manifest-path user/hello-libctos/Cargo.toml \
  --target user/hello-libctos/aarch64-ctos-user.json

A kernel cargo build already does that via build.rs and publishes the result. Then ./scripts/qemu-smoke.sh. There is no exec of a file on disk. The kernel ELF no longer embeds the hello bytes.

This is not a process. No libc, no argv, no loader for a foreign ELF. “EL0 isolated” means only the accepted ADR-091 sentence.

libctos wraps fs_create / fs_open / fs_read / fs_write / fs_close (SVC 19–23). The hello payload does not call them (UART + one yield). A second freestanding sample does: see Recipe 3b (fs-libctos, ADR-059). A third reads FAT via the same wrappers: see Recipe 3c (fat-libctos, ADR-061). A fourth exercises several cooperative yields: see Recipe 3d (yield-libctos, ADR-062). A fifth exercises EL0 net SVCs: see Recipe 3e (net-libctos, ADR-068). A sixth exercises EL0 UDP DNS SVC: see Recipe 3f (udp-libctos, ADR-071). The kernel /eprobe trampoline (fs: el0) remains a separate Verified EL0 VFS trip.

Recipe 3b — Standing EL0 / libctos VFS sample (fs-libctos)

Second freestanding EL0 payload that calls the VFS wrappers (ADR-059). Same class as libctos: fs-hi / libctos: fs-ok / fsdemo: ok.

Rebuild: same one-rebuild commands. Keep /hello + slot: ok. Not POSIX. Not getdents. Not a reopen of product app hosting (ADR-048/052).

Recipe 3c — Standing EL0 / libctos FAT sample (fat-libctos)

Third freestanding EL0 payload that opens/reads a FAT path through thin VFS (ADR-061). Same class as libctos: fat-hi / libctos: fat-ok / fatdemo: ok. Deeper than Recipe 3b (memfs only).

Rebuild: same one-rebuild commands. Keep /hello + /fsdemo + slot: ok + fsdemo: ok. Not POSIX. Not getdents. Not a reopen of product app hosting (ADR-048/052).

Recipe 3d — Standing EL0 / libctos yield rounds (yield-libctos)

Fourth freestanding EL0 payload that issues several cooperative yield_now() rounds (ADR-062). Same class as libctos: yld-hi / libctos: beat / libctos: yld-ok / yldemo: ok. Deeper than hello’s single yield. Not preemption. Not multi-task EL0. Not a process table.

Rebuild: same one-rebuild commands. Keep /hello + /fsdemo + /fatdemo + slot: ok + fsdemo: ok + fatdemo: ok. Not POSIX. Not preemption. Not a reopen of product app hosting (ADR-048/052).

Recipe 3e — Standing EL0 / libctos net SVCs (net-libctos)

Fifth freestanding EL0 payload that exercises EL0 net SVCs (ADR-068). Same class as libctos: net-hi / libctos: net-mac / libctos: net-ok / netdemo: ok. Kernel owns virtio-net.

Rebuild: same one-rebuild commands. Keep prior samples + N1/N2 markers. Not TCP product. Not sockets. Not “has networking.” Not a reopen of product app hosting (ADR-048/052).

Recipe 3f — Standing EL0 / libctos UDP DNS SVC (udp-libctos)

Sixth freestanding EL0 payload that exercises EL0 net_udp_dns (ADR-071). Same class as libctos: udp-hi / libctos: udp-ok / udpdemo: ok. DNS is probe bait only.

Rebuild: same one-rebuild commands. Keep /hello + /fsdemo + /fatdemo + /yldemo + /netdemo + N1/N2/N3 markers. Not TCP product. Not sockets. Not a DNS product. Not “has networking.” Not a reopen of product app hosting (ADR-048/052).

Standing EL0 / libctos fs_mkdir sample

Seventh freestanding EL0 payload that exercises EL0 fs_mkdir (ADR-075). Same class as libctos: mkdir-hi / libctos: mkdir-ok / mkdemo: ok. Creates FAT root /edir only — not POSIX mkdir. One-level nested mkdir is a kernel/VFS mile (ADR-077), not this sample.

Standing EL0 / libctos TCP echo sample

Eighth freestanding EL0 payload that exercises EL0 net_tcp_echo (ADR-076). Same class as libctos: tcp-hi / libctos: tcp-ok / tcpdemo: ok. Quiet thin TCP guestfwd echo — not BSD sockets, not listen/accept.

Recipe 4 — memfs named-buffer probe (optional)

In-RAM named buffers behind the thin VFS (ADR-027). Same class as fs: create / fs: write / fs: read / fs: el0 / fs: ok.

Rebuild: same one-rebuild commands. Not POSIX. Not a volume. Not app hosting.

Recipe 5 — FAT16 /probe on virtio-blk (optional)

FAT16 on QEMU virtio-mmio block (ADR-028, write depth ADR-050, multi-cluster grow ADR-064). Same VFS open / write as memfs. Same class as blk: ok / fat: mount / fat: read / fat: write / fat: ok. Guest /probe must read fat-hi; write probe restores it; /fwr holds fat-nw.

qemu-smoke builds the image and attaches:

-drive if=none,file=target/fat16.img,format=raw,id=hd0 -device virtio-blk-device,drive=hd0

Host -drive without the guest serial is not the probe. Not POSIX. Not FAT32. Do not say “supports FAT” as a product; say the guest wrote FAT16 bytes when fat: write / fat: create pass, and grew across a cluster boundary when fat: grow / libctos: fat-grow pass. Same-boot CNTPCT pairs vs memfs: write ADR-051 (perf: fat-write / perf: memfs-write / perf: fs-write-delta) and read ADR-065 (perf: fat-read / perf: memfs-read / perf: fs-read-delta) — KPIs; measurement only, not a latency SLA.

Recipe 6 — OS image vs app slot (A9 first cut)

Two host artifacts and a FAT load path (ADR-030). Same class as slot: fat / slot: mapped / slot: ok / perf: app-load.

A2–A4 load the same FAT file (no embed). Cross-update (same ELF on this OS and ba6541c) is the leftover host smoke, not this recipe. Not OTA. Product freestanding claim is Verified under ADR-048/052 (this recipe page is not that claim by itself).

What cannot run

flowchart TD
  Q{"Want to run it on ctos today?"}
  Q -->|UART worker / echo / stub / memfs / FAT probe| Y["Yes — extend the kernel in-tree"]
  Q -->|Linux binary, shell, Python| N1["No"]
  Q -->|Network server or Linux disk apps| N2["No — ARP/ICMP/UDP probe only, no sockets / no POSIX FS"]
  Q -->|Docker / OCI container| N3["No — not a goal"]

“Yes” means rebuild the kernel. It does not mean drop in an app.

Do not imply these work:

• Linux binaries (no Linux ABI, no ELF loader for third-party programs)
• A shell
• Python (or any hosted language runtime)
• Network servers (virtio-net ARP + ICMP + minimal UDP + thin TCP probe + EL0 UDP DNS SVC + EL0 TCP echo SVC samples only — ADR-066 / ADR-067 / ADR-070 / ADR-071 / ADR-074 / ADR-076; no BSD sockets / TCP product)
• POSIX / Linux filesystem apps (memfs + FAT16 read/write miles are not that — Filesystem)
• Extra-CPU workloads (one CPU, cooperative yield only)
• Product freestanding app hosting (Verified under ADR-048 / ADR-052; not Linux/POSIX/containers/OTA — issue #48)

Also not claimed: POSIX, GPU, Raspberry Pi, certified security, “production ready,” or containers (non-goal, ADR-029; Hosting apps / containers).

How you would add something in-tree (and why Linux apps do not port): Building or porting.

Prerequisites

What you need to build and run the kernel. Publishing this docs site is optional. GitHub Pages is not required for kernel work.

Kernel (required)

rustup toolchain install nightly
rustup component add rust-src llvm-tools-preview
# Debian/Ubuntu: sudo apt-get install qemu-system-arm

cargo build          # ELF at target/aarch64-ctos/debug/ctos
cargo run            # qemu-system-aarch64 -machine virt
./scripts/qemu-smoke.sh

flowchart LR
  R["rustup nightly + rust-src"] --> B["cargo build"]
  B --> Q["qemu-smoke / cargo run"]

That rebuilds the kernel, including any in-tree no_std code you add. It is not a port of a Linux app. See Building or porting.

Commands and honesty notes: GitHub README. A successful cargo build on your machine is not a copied Verified boot from another host.

Optional

Not required

• GitHub Pages, a custom domain, or ctos.artof.link (the site is live; you still do not need it to hack the kernel)
• Raspberry Pi hardware, an x86_64 boot path, or VGA
• Obsidian (.obsidian/ is gitignored)
• AWS / Route 53 credentials (DNS is a publish concern, not a kernel build concern)

Building or porting something to ctos

Plain English. There is no easy POSIX port today. ctos is a kernel you extend in-tree, not a host you drop apps onto.

What already runs (rebuild recipes): What can run today. In-tree index: user/README.md. How to build the kernel: prerequisites. Probes: honesty ledger.

Do not claim an “easy port” path that does not exist.

Today (honest)

Nothing POSIX ports easily.

There is no C library (libc), no dynamic linker, and no POSIX filesystem. Thin VFS + memfs + FAT16 are not Linux open. A1 documented a kernel SVC ABI (exit / uart_write / yield — syscall.md, ADR-021). A2 adds a freestanding libctos CRT you can link in-tree (ADR-022). A3 parses that in-tree ELF on the guest and maps PT_LOAD (ADR-023). That is not an application porting target for Linux binaries. There is no PT_INTERP / glibc path that would run a foreign user-mode binary if you built one elsewhere.

A Linux, musl, or glibc program is a different contract. Recompiling it “for AArch64” does not make it a ctos program.

Easiest today

Write in-tree no_std Rust and ship it as part of the kernel image. Language discipline notes: Why Rust.

Typical shape (A8 recipes — what-can-run.md):

• A cooperative kernel task (same class as sched: task a/b) or a small kernel module
• Use UART / println! for output; yield to other tasks
• Optional: serial receive for a byte-in gadget
• Optional: link libctos like user/hello-libctos (published + FAT /hello; not a second -kernel)

Rebuild the whole guest with the existing target:

cargo build                 # aarch64-ctos.json
./scripts/qemu-smoke.sh     # or ./scripts/docker-smoke.sh on linux/arm64

That is rebuild the kernel, not “port an app.” The new code lives in src/ and links into target/aarch64-ctos/debug/ctos.

flowchart LR
  R["rustup nightly"] --> C["cargo build"] --> S["qemu-smoke"]
  S --> E["OS ELF + published app ELF<br/>A9 first cut"]

Two host artifacts. QEMU still -kernels the OS ELF. FAT /hello is the app slot. A2–A4 load that file. Cross-update is the leftover two-boot smoke.

Not easy

• Recompile Linux / C / Rust apps against glibc or musl
• Drop in a userspace ELF (ET_DYN or a Linux ET_EXEC)
• Expect std, files, sockets, threads, or a process table

Those need a loader and a userspace that ctos does not have. The standing user-mode stub is a test mile plus an A1 ABI trip and an A2 libctos hello, not that runtime (el0.md, syscall.md).

Track A miles that already have recipes

A1–A7 are probed. A8 is docs: the recipes on what-can-run.md. Still not “applications port to ctos.” You extend the kernel or link libctos in-tree.

1. A stable SVC ABI — A1 (exit / uart_write / yield).
2. A freestanding CRT / libctos — A2.
3. Guest PT_LOAD of that in-tree ELF — A3. Image is FAT /hello.
4. Standing EL0 as normal until exit — A4 / ADR-024.
5. Isolation cut (identity .rodata + PAN ID-field) — A5. PAN is enabled on the default -cpu cortex-a76 (ADR-080; PAN enable was a non-goal on the historical -cpu cortex-a57, ADR-047). Leftover identity RAM after the heap is torn (ADR-049); _start stays.
6. Thin VFS + memfs — A6. Recipe 4.
7. virtio-blk + FAT16 read — A7. Recipe 5. FAT16 write depth — ADR-050.
8. OS/app slot first cut — A9 / ADR-030. Recipe 6. Leftover cross-update — ADR-032 (Verified host smoke).

A real userspace stays Planned. “EL0 isolated” is Verified only as the accepted ADR-091 sentence (one core, TCG default smoke machine; limits there). Gaps before hosting, and why containers are a non-goal: Hosting apps / containers.

A POSIX filesystem is the same story: not present. Thin VFS + memfs + FAT16 are not Linux open. Direction: Filesystem: new vs extend.

Product hosting still Planned (ADR-048)

An OS image vs app payload first cut and leftover cross-update already exist (A9 #48, ADR-030, ADR-032): same hello-libctos.elf on this OS and documented prior OS ba6541c. Product freestanding “hosting done” is Verified under ADR-048 / ADR-052 (not Linux/POSIX). See hosting-apps.md, overview.md, and immutability.md.

Filesystem: new vs extend

Today: thin VFS with two backends and a prefix mount table. In-RAM memfs (A6 / ADR-027) and FAT16 on virtio-blk (A7 / ADR-028). Same open / read / write / close. Path prefixes route to a backend (ADR-058): /mem (+ A6 probe names) → memfs; / → FAT16 (/probe, plus freestanding samples /hello / /fsdemo / /fatdemo / /yldemo). FAT16 write is a depth mile (ADR-050). Multi-cluster grow is a depth mile (ADR-064). FAT16 root listing is a depth mile (ADR-056). FAT16 root delete is a depth mile (ADR-057). Not POSIX open / mount / getdents / unlink, not Linux VFS, not FAT32, not xv6. Track B B5 compares the concepts: ADR-034. Not claiming a Linux filesystem.

Do not say “supports FAT” as a product. Say the guest read a known FAT16 file when the ledger has fat: ok, wrote FAT16 bytes when it has fat: write / fat: create, grew a file across a cluster boundary when it has fat: grow, listed root entries when it has fat: readdir / fat: entries, deleted a root file when it has fat: delete, created a root directory when it has fat: mkdir, created a one-level nested directory when it has fat: nested, and removed an empty directory when it has fat: rmdir. Hub: honesty ledger, What can run today. Extra stance: filesystem.md.

flowchart TD
  CALL["EL0 / EL1 callers"] --> VFS["Thin VFS<br/>open · read · write · close · readdir · unlink"]
  VFS --> MT["Prefix mount table<br/>ADR-058"]
  MT -->|"/mem · A6 names"| MEM["memfs<br/>in-RAM buffers"]
  MT -->|"/"| FAT["FAT16<br/>read · write · root readdir · unlink"]
  FAT --> BLK["virtio-blk<br/>host fat16.img"]

Same thin API, two backends, prefix mounts. Not POSIX open / mount / getdents / unlink. Do not say “supports FAT” as a product.

New vs extend

Prefer implementing a known small filesystem behind this thin VFS over inventing a novel on-disk format.

Avoid early

Do not start with ext4, btrfs, ZFS, or NTFS. Those are large, journaled or feature-heavy, and hide the block mile. They are not a first cut.

Host QEMU -drive without guest virtio + a VFS read is not a filesystem.

Roadmap order

One milestone → one branch → one PR.

flowchart LR
  V["1. VFS ADR<br/>ADR-027"] --> M["2. memfs<br/>A6"]
  M --> B["3. virtio-blk<br/>A7"]
  B --> F["4. FAT16 read<br/>A7"]
  F --> H["5. host image + guest read<br/>A7/A9"]
  H --> W["6. FAT16 write<br/>ADR-050"]
  W --> P["7. FAT vs memfs write CNTPCT<br/>ADR-051"]
  P --> PR["7b. FAT vs memfs read CNTPCT<br/>ADR-065"]
  PR --> R["8. FAT16 readdir<br/>ADR-056"]
  R --> D["9. FAT16 delete<br/>ADR-057"]
  D --> V2["10. Prefix mounts<br/>ADR-058"]

A7 is virtio-blk + FAT16 read. ADR-050 is FAT16 write depth. ADR-051 / ADR-065 are same-boot measurement pairs (not benches). ADR-056 is FAT16 root listing. ADR-057 is FAT16 root delete. ADR-058 is prefix mounts. A8 is documented recipes. A9 / ADR-059 / ADR-061 / ADR-062 use the same volume for /hello / /fsdemo / /fatdemo / /yldemo. Do not say “supports FAT” as a product.

1. VFS ADR — thin interface (create / open / read / write / close of a path).
2. memfs — in-RAM named buffers; serial fs: ok.
3. virtio-blk — virtqueues + sector I/O on QEMU virt. Serial blk: ok.
4. On-disk FS — FAT16 (ADR-028). Serial fat: ok.
5. Host-checkable image — scripts/mkfat16.py writes target/fat16.img; smoke attaches -drive if=none,file=…,id=hd0 -device virtio-blk-device,drive=hd0. Guest vfs::open("/probe") must read fat-hi. A9 adds --app so /hello is the published app ELF; ADR-059/061/062 add --app2 / --app3 / --app4 for /fsdemo / /fatdemo / /yldemo.
6. FAT16 write — guest vfs::write on an open FAT handle + backend create of /fwr (ADR-050). Serial fat: write / fat: create; host --check-write.
7. FAT vs memfs write CNTPCT — same-boot pair perf: fat-write / perf: memfs-write / perf: fs-write-delta (ADR-051). QEMU TCG lab — not a percent or latency SLA. 7b. FAT vs memfs read CNTPCT — same-boot pair perf: fat-read / perf: memfs-read / perf: fs-read-delta (ADR-065). QEMU TCG lab — not a percent or latency SLA.
8. FAT16 readdir — guest vfs::readdir lists root thin-VFS paths (ADR-056). Serial fat: readdir / fat: entries. Not POSIX getdents.
9. FAT16 delete — guest vfs::unlink deletes a root file (ADR-057). Serial fat: delete. Not POSIX unlink.
10. Prefix mounts — mount table routes path prefixes to memfs or FAT16 (ADR-058). Serial vfs: mount / vfs: mounts. Not POSIX mount(2).

Honesty

Do not claim compatibility with anyone’s existing disk.

Hosting applications — gaps, and containers

What ctos can host today under the scoped Track A product claim (a loaded freestanding user-mode binary with a stable ABI on an OS/app slot), what is still missing for stronger isolation, and whether it can host containers.

Today you also extend the kernel (Building or porting). Samples that exist: What can run today. Isolation notes: el0.md. Kernel SVC numbers: syscall.md.

Do not say ctos hosts Linux programs, POSIX apps, or containers. The scoped freestanding slot-hosting claim is Verified under ADR-048 / ADR-052.

Today vs the slot split (A9 + product claim)

Today (Verified miles + product claim): QEMU -kernel still loads one OS ELF. Published freestanding samples live on FAT /hello (A9), /fsdemo (ADR-059), /fatdemo (ADR-061), and /yldemo (ADR-062). A2–A4 load /hello (no production embed). The same hello ELF boots on this OS and on ba6541c (ADR-032). Under ADR-048 criteria Met×5 (ADR-052), the product sentence “apps run independently of the OS” / “app hosting is done” is Verified for that freestanding slot path. It is not containers, not OTA, and not Linux/POSIX.

Product claim (Verified): “apps run independently / hosting done” is Verified under ADR-048 (checklist below). Scope stays freestanding slots — not Linux userspace.

flowchart LR
  OS["OS ELF<br/>QEMU -kernel"] --> FAT["FAT16 volume"]
  H["/hello"] --> FAT
  F["/fsdemo"] --> FAT
  D["/fatdemo"] --> FAT
  Y["/yldemo"] --> FAT
  FAT --> LOAD["Guest PT_LOAD<br/>standing EL0"]
  LOAD --> CLAIM["Product hosting<br/>Verified — ADR-048/052"]

Freestanding slot-hosting is Verified (Met×5). Catalog samples deepen recipes; they do not reopen the claim. Do not say Linux hosting, containers or OTA. Say “EL0 isolated” only as the accepted ADR-091 sentence. Runtime cost vs embed is a lab measurement pair (ADR-046), not a marketing delta.

Gaps before hosting applications

These are missing pieces for richer hosting / isolation, not a schedule. Rows without a probe stay Planned or unbuilt. “Later” is not a promise.

A supervisor call (SVC) is how user-mode code asks the kernel for help. Reserved SVC #0–#2 stay test miles. A1 documented exit / uart_write / yield (syscall.md). That is not a CRT or loader.

“Host an application independently of the OS” / “app hosting is done” is Verified under ADR-048 (documented recipes + slot cross-update + no production embed + honesty about missing Linux/POSIX/containers + sponsor accept / ADR-052). That block is Track A. A1–A9 first cuts alone were never enough; the checklist Met×5 is. A5: PAN ID-field Verified; enable is non-goal on default cortex-a57 (ADR-047). A8 documented rebuild recipes (what-can-run.md). A9 + leftover: FAT /hello, no production embed, cross-update on ba6541c. See Immutability.

Containers

Non-goal. ctos cannot host OCI / Docker / Kubernetes workloads, and it is not aiming to.

Those need Linux kernel features (namespaces, cgroups, a Linux ABI, usually overlay or equivalent, a rich syscall surface) that this learning kernel does not have. Decision: ADR-029. Track B B7 (#47).

Today the arrow is the other way: Docker on a host (arm64 workstation linux/arm64) runs the ctos smoke image. That is “Docker hosts ctos,” not “ctos hosts containers.” See the README Docker notes and the Docker rows in the ledger.

flowchart LR
  HOST["Linux host + Docker"] -->|"builds and QEMU-smokes"| CTOS["ctos guest"]
  CTOS -.->|"does not host"| OCI["OCI / Docker / k8s"]

Host harness ≠ guest runtime. File presence of this page is not a container probe.

Container support is not Planned on this page. Do not add a Planned row. Reopen only with a new GitHub epic plus a new ADR — not a Track B win, and not a new FR/NFR ID.

Claim criteria (ADR-048)

Product “apps run independently / hosting done” is Verified when all of the following are ledger-Verified and sponsor-accepted (ADR-048 / ADR-052):

1. Documented freestanding-app recipes (existing markers only).
2. Slot cross-update (same published ELF on this OS and a documented prior OS).
3. No production hello embed (slot: embed never appears on the production path).
4. Docs still refuse Linux ABI / POSIX / guest containers (ADR-029).
5. Explicit sponsor accept on the flip PR (no self-merge).

Progress vs tip main (honesty checklist)

Tip audited: 190ef5a (Merge #106 / docs polish; or newer main with ADR-062). Product row Verified — criteria 1–5 Met. Catalog samples /fsdemo / /fatdemo / /yldemo deepen recipes; they do not reopen ADR-048/052.

A1–A9 first cuts alone remain insufficient without the checklist. Matching ledger section: honesty-ledger.md — ADR-048 progress.

Honesty

KPIs / how we measure

Plain English. These are the probes this repo actually runs. They are not a product dashboard, a latency promise, or invented KPIs. Numbers live in the honesty ledger as one environment and one revision.

The three first-class pillars are antifragility (NFR-05), security (NFR-10), and performance (NFR-07). “Application support” below is an honest scope statement, not a new requirement ID.

Performance

What we measure today on QEMU virt (serial markers + tests, fail-closed in scripts/qemu-smoke.sh).

CNTPCT is the CPU’s physical cycle counter — a hardware clock we read to see that time moved, not a published bench.

QEMU virt is one guest. It is not Raspberry Pi, not real silicon, and not SPEC. Optimize only after a probe shows a cost. Details: performance.md.

OS slot vs app slot (performance)

ADR-030 first cut exists: FAT /hello + perf: app-load. ADR-032 removes the A2–A4 production embed. ADR-046 adds a probe-only linked-in trip and perf: slot-delta app=<a> embed=<b> on the same boot. Immutability means disconnect OS update from apps. That can cost at runtime or be neutral. We do not invent a percentage, a budget, or “faster than linking the app into the kernel.” The pair is a QEMU TCG lab measurement.

FAT write vs memfs write (performance)

ADR-050 is the write mile. ADR-051 adds a same-boot CNTPCT pair: perf: fat-write vs perf: memfs-write plus perf: fs-write-delta fat=<a> memfs=<b>. That can show a cost shape for going through virtio-blk/FAT versus in-RAM memfs — or be noisy under TCG. We do not invent a percentage, a budget, or “FAT write is X× slower.”

Measure first (NFR-07). Do not tune a loader “for speed” on a hunch. Do not copy QEMU ticks into a product slide.

FAT read vs memfs read (performance)

ADR-065 adds the symmetric same-boot CNTPCT pair for read: perf: fat-read vs perf: memfs-read plus perf: fs-read-delta fat=<a> memfs=<b>. Same honesty rules as the write pair — measurement only, not a latency SLA.

Net-ping path (performance)

ADR-069 times the EL0 net_ping quiet path: perf: net-ping ticks=<n>. Smoke checks the prefix only — tick values vary under QEMU TCG. Optional N2 crumbs perf: net-icmp-tx / perf: net-icmp-rx remain lab-only (ADR-067).

UDP DNS path (performance)

ADR-072 times the EL0 net_udp_dns quiet path: perf: udp-dns ticks=<n>. Smoke checks the prefix only — tick values vary under QEMU TCG. Window = quiet ARP + UDP DNS as SYS_NET_UDP_DNS / el0_udp_dns (same pattern as ADR-069).

Thin TCP echo path (performance)

ADR-078 times the EL0 net_tcp_echo quiet path: perf: tcp-echo ticks=<n>. Smoke checks the prefix only — tick values vary under QEMU TCG. Window = quiet ARP + thin TCP guestfwd echo as SYS_NET_TCP_ECHO / el0_tcp_echo (same pattern as ADR-069/072). Kernel N5 net: tcp-ok stays untimed this mile.

Stability / antifragility

We do not publish an uptime KPI. We measure whether sensors stay fail-closed and whether a repeated miss becomes a ratchet (NFR-05, antifragility.md).

A green GitHub Actions run is one pair of runners. It is not “every host.” Docker on the arm64 workstation is a separate row.

Application support

Scope only — not a new requirement ID. Concrete examples and the cannot-run list: What can run today.

Security work is probed (heap not-executable, stack guards, read-only code / not-executable data, user-mode miles) — that is not a product security KPI. See security.md. Do not say “production ready.”

Advantages

These are properties of how the repo is run, not a product pitch. They are useful if you want a small AArch64 kernel you can study without inflated status.

The landing Driving principles block (honesty, antifragility, security, performance, document-first) is the force; Track A/B stay subordinate. Visitor-facing source: landing. Deep pillar notes: pillars.md.

Document-first

Vision → architecture → ADR → roadmap stay ahead of code for each loop (document-first — FR-14, NFR-13). Frozen IDs are FR-01–FR-15 and NFR-01–NFR-14. New IDs are not invented in chat.

Probed claims

Status words need a command, a serial capture, a gh run URL, or a file read that matches the claim (honesty — NFR-06, honesty ledger). Unprobed stays Unknown. That is slower to write and harder to game than a green README badge.

QEMU virt learning scope

Primary ISA is AArch64 on QEMU virt + serial UART (ADR-003). The scope is small on purpose: UART, exceptions, paging, heap, a cooperative scheduler, then pillar cuts. It is not a distro and not a board bring-up until a board probe exists.

Why Rust (for this kernel)

Rust is the language of this kernel on purpose. It is not a slogan. It is a tools-and-rules choice for a small AArch64 guest you can study.

1. Memory safety by default. Ownership and borrowing catch many C-class bugs (use-after-free, double-free, many buffer overruns) at compile time, before the guest boots.
2. No garbage collector, still systems-friendly. You keep control of layout and when things free. There is no stop-the-world collector in the way of a freestanding kernel.
3. Safer concurrency relative to unchecked shared mutable state. In safe Rust, Send / Sync make “who can share this across threads” a type-system question. That does not invent a scheduler; it reduces a class of data races in safe code.
4. Zero-cost abstractions and fail-closed paths. You can keep thin wrappers without paying for them at runtime. Result / Option push “did this fail?” into the type, which fits probed, fail-closed sensors better than silent null.
5. Modern freestanding tooling. cargo, no_std, and crates like in-tree libctos are the everyday build path (prerequisites, porting).

flowchart LR
  S["Safe Rust"] --> M["Ownership / borrowing"]
  S --> C["Send / Sync"]
  S --> F["Result / Option"]
  U["unsafe still required"] --> H["page tables · MMIO · asm"]

Safe Rust helps discipline. unsafe is still how you talk to the machine.

Honesty caveats

• unsafe still exists for page tables, MMIO, and assembly. The type system does not cover those edges.
• Rust does not invent a correct architecture by itself. Wrong maps, wrong EL, and wrong ABI stay wrong.
• This does not mean “secure OS.” “EL0 isolated” is Verified only as the accepted ADR-091 sentence: one core, TCG default smoke machine; not speculative-execution / side-channel, not real hardware, not a certification. Its clauses (PAN, taken SError, …) each have their own probe rows (limits, honesty ledger).
• Status words still need probes / the honesty ledger. Language choice is not a substitute for a serial capture or a gh run URL.

Pair with Drawbacks / limits: Rust helps discipline; it does not remove those limits.

Three pillars as requirements

After the cooperative scheduler (M9), antifragility, security, and performance are first-class (ADR-011, pillars.md). They still need probes. “Secure” and “fast” are not default adjectives.

Author ≠ merger

ADR-002: the author does not merge their own PR. artofdream vs cursor[bot]. Same-login Approve is still self-review.

Fail-closed sensors

scripts/qemu-smoke.sh and force-fail are meant to break when a marker disappears. Repeated host misses become ratchets, not extra paragraphs of advice (antifragility.md).

Immutability

Scoped yes. Absolute no. Two different sentences:

Page-table scope (probed today). Some kernel memory is read-only and executable, other memory is writable and not executable (W^X on that image slice — write or execute, not both). Smoke markers: ro: ok (ADR-015), identity .text / .rodata / .data / heap tears, and leftover identity frame RAM after the heap (ident: ram*, ADR-049) on this QEMU virt guest. _start stays (ident: start-stay). Not “the kernel is immutable,” “W^X everywhere,” or full identity teardown. Claim only with a ledger probe.

OS slot vs app slot (first cut + leftover cross-update). The useful product meaning is: apps run independently of the OS on a separate OS slot (the kernel image you -kernel) and app slot (a loaded freestanding user-mode binary). ADR-030 is the first cut: host ctos ELF + hello-libctos.elf, guest FAT /hello, A3 PT_LOAD map. ADR-032 loads A2–A4 from that FAT file (no embed) and boots the same published ELF on this OS and on ba6541c. Product freestanding hosting is Verified under ADR-048 / ADR-052. Do not say OTA / “immutable OS” marketing / Linux hosting.

This is not containers (ADR-029 — non-goal, not later), and not OTA / A-B firmware updates (later and unclaimed). Do not say “immutable OS updates.”

Runtime cost vs neutral is unmeasured. Measure first; no invented numbers. KPIs — OS slot vs app slot.

Limits of this shape: Drawbacks / limits.

Drawbacks / limits

What this project is not, and what is still unfinished. Pair with KPIs / how we measure and product vision.

Learning kernel, not a product

ctos is a research / teaching AArch64 kernel. It is not production-ready, not a desktop, not POSIX, not a container host (non-goal, ADR-029), and not a “secure OS.” Do not treat a green QEMU smoke as certification. Rust helps discipline; it does not remove these limits (Why Rust).

Boot contract still starts at 0x4008_0000

QEMU -kernel and _start stay at 0x4008_0000. High-address work (kernel page-table alias, live code / .rodata / .data / heap / leftover frame-RAM tears) does not mean the kernel moved. Leftover identity RAM after the heap is unmapped (ident: ram*, ADR-049); smoke rejects ident: ram-stay. _start stays mapped by decision (ident: start-stay, ADR-047). Do not claim full identity teardown. See el0.md.

Privileged Access Never — enable Verified on cortex-a76 (ADR-080)

PAN stops the kernel from casually reading user-accessible pages when PSTATE.PAN is set. Default smoke CPU is -cpu cortex-a76 (ADR-079 / #125): ID-field Verified (pan: present) and enable + EL1-vs-EL0 fault Verified (pan: enabled / pan: el1-fault, ADR-080). Historical -cpu cortex-a57 remains pan: absent (ADR-026). Say “EL0 isolated” only as the accepted ADR-091 sentence (below). Do not silent -cpu.

Network is virtio-net ARP + ICMP + minimal UDP + thin TCP (+ tiny EL0 net/UDP SVCs); disk is virtio-blk + FAT16

N1 programs virtio-mmio virtio-net enough to TX/RX one raw Ethernet frame (ARP vs QEMU SLIRP gateway) — ADR-066. N2 adds a kernel-path ICMP echo to 10.0.2.2 (net: ping-ok) — ADR-067. N3 adds a kernel-path UDP datagram to SLIRP DNS 10.0.2.3:53 (net: udp-ok) — ADR-070 (DNS is probe bait, not a DNS product). N5 adds a kernel-path thin TCP active-open + one payload echo via QEMU guestfwd 10.0.2.4:7 (net: tcp-ok) — ADR-074 (not a sockets product). N4 adds a tiny EL0 net SVC (net_mac / net_ping) and freestanding /netdemo — ADR-068. N3.x adds EL0 net_udp_dns and /udpdemo — ADR-071 / track-n.md. That is not BSD sockets, TCP product, DHCP/DNS product, Wi‑Fi, or “has networking / sockets OS.” A7 programs virtio-mmio block and reads a host-built FAT16 image through the thin VFS; ADR-050 adds a guest FAT16 write / small create mile; ADR-051 / ADR-065 add same-boot FAT vs memfs write and read CNTPCT pairs (lab measurements, not benches) (Filesystem, KPIs). That is not a general DMA API, not virtio-pci, not POSIX, and not a Linux rootfs. Input on virt is serial receive. Timer is the virt interrupt controller plus the generic timer.

No real userspace apps

The standing user-mode stub is a mile, not an application runtime. No ELF loader for third-party programs, no libc, no extra CPUs, no GPU. Rebuild recipes: What can run today — four freestanding samples on FAT (/hello, /fsdemo, /fatdemo, /yldemo). How to extend the kernel (not port POSIX): Building or porting. OS vs app slot has an A9 first cut (FAT /hello) plus leftover cross-update on ba6541c (Verified miles). Product freestanding app hosting is Verified under ADR-048 / ADR-052 (not Linux/POSIX). Umbrella “EL0 isolated” is Verified only as the accepted ADR-091 sentence (M6); the other isolation locks stay (ADR-060).

Docs URL

https://ctos.artof.link serves this book (HTTPS Verified after #30 — website.md). A trailing-slash github.io/ctos/ path 404’d on the 2026-09-11 probe; use the custom domain. Publishing mechanics can still lag a new commit until the next main Pages deploy.

Immutability is not absolute

Read-only code / not-executable data, and torn identity ranges (including leftover frame RAM), are scoped probes. Do not upgrade them to “immutable kernel,” “W^X everywhere,” or “OS updates without touching apps.” The A9 OS vs app slot first cut exists; the freestanding product hosting claim is Verified (ADR-048 / ADR-052). Not OTA or containers. Details: Advantages — Immutability.

Other honest gaps

• Umbrella user-mode isolation: Verified only as the accepted ADR-091 sentence (M6, 2026-09-28; checklist ADR-055 all Met; sponsor closure ADR-060). The sentence, verbatim (revision 4, accepted 2026-10-02):

  “On the ctos default smoke machine (QEMU virt, -cpu cortex-a76, TCG, one core), EL0 is isolated from the kernel at the architectural page-table / exception-level boundary: each EL0 task runs on its own TTBR0 with its own ASID; EL0 faults when it reads, writes or executes kernel memory; in every translation table (kernel, user and ASID-B TTBR0, and TTBR1) the only EL0-reachable pages are five allowlisted user slots backed by non-kernel frames, checked fail-closed while a user app runs and at rest; PAN is enabled, including while the kernel handles exceptions from EL0, and EL1 faults on EL0-readable memory (the execute-only app text page is not covered: this CPU has no FEAT_EPAN); lower-EL IRQ and FIQ are taken while EL0 stands; taken lower-EL SError is evidenced by the ADR-090 evidence class; the only identity (VA = PA) mapping left in any TTBR0 is the documented EL1-only _start stub page (ADR-089); and a system call copies from or to an EL0 pointer only if EL0 itself may read (for a copy from EL0) or write (for a copy to EL0) every page in the range. It is not a speculative-execution or side-channel claim, not a real-hardware claim, and not a certification.” Limits that stay with it: one core; the TCG default smoke machine; not speculative-execution / side-channel; not real hardware; not a certification; app text is EL0 execute-only; EL1 can still read it (no FEAT_EPAN) (ADR-097, accepted as ADR-091 revision 4 on 2026-10-02; before that EL0 could read its own code bytes, ADR-094); no multi-core race story. Also outside it: task-vs-task isolation beyond ASIDs, DMA / IOMMU / EL2, and taken SError on stock QEMU (still parks, ADR-053). _start stays (ADR-089).

• x86_64 is not a primary path.
• Raspberry Pi / other boards: unprobed.
• CI on GitHub is a separate ledger row from a cloud-VM qemu-smoke.

Archify diagrams

Same-origin views on this site (Documented aid — not Live product status; snapshot from before M6; for “EL0 isolated” see the accepted ADR-091 sentence).

Honesty

• Taken el0: serror is Verified opt-in (CTOS_QEMU + CTOS_REQUIRE_TAKEN_SERROR=1); see ADR-083.
• Stock distro QEMU still parks (el0: serror-park).
• Not FEAT_NMI / FIQ / BRK as SError. The pin alone is not the umbrella; since M6, “EL0 isolated” is only the accepted ADR-091 sentence.

Source folder: docs/archify/ (copied into the published book/archify/ on Pages). Generated with Archify v3.2.0; the former guided chapters are now cards under each drawing, and the viewer’s Route and Lens controls replace guided views. Regenerate steps (pinned to v3.2.0, ARCHIFY_UPDATE_CHECK_DISABLED=1) are in the folder README.

Related

• Chronify evolution rail — dated milestones (Documented until Pages probe).

Chronify — evolution rail

Dated milestones for ctos (ctsOS). Sister to Archify diagrams.

Artifact	Open
Pages rail (SVG)
Interactive HTML	ctos-evolution.timeline.html
IR (source of truth)	ctos-evolution.timeline.json

Honesty

Documented aid until ctos.artof.link Pages probe this session. Not Live product status. Snapshot from before M6; for “EL0 isolated” see the accepted ADR-091 sentence.

Regenerate with chronify v0.1.0:

node bin/chronify.mjs deliver timeline docs/chronify/ctos-evolution.timeline.json \
  docs/chronify/ctos-evolution-rail.svg --surface pages-rail

Product vision

Core principles are the driving force for ctos. Tracks and nicknames are subordinate. Non-negotiable: honesty ledger, antifragility (fail-closed + ratchets), security (threat model, probed mitigations only), performance (measure first), document-first / one-PR loops. principles.md.

What ctos is

ctos is a learning and research bare-metal OS kernel written in Rust for AArch64 (arm64 primary; ADR-003). The near-term product is a QEMU virt guest that owns the machine after -kernel load: UART text, then exceptions, paging, a heap, and a tiny scheduler — in that order.

It exists so we can study kernel mechanics with a document-first harness: claims stay honest, failures become sensors, and agents do not merge their own work. After M9 that harness sits on three first-class pillars — antifragility, security, and performance (ADR-011). Security and speed are not afterthoughts; they still need probes before anyone writes “secure” or “fast.”

What ctos is not

• Not a production operating system, desktop, or app runtime. Probed guest samples: apps-today.md.
• Not a Linux distro, not POSIX, not a container host (non-goal, ADR-029). Linux-compat is a research frame (ADR-031); not claiming Linux userspace yet. Porting stance: building-or-porting.md. No filesystem today: filesystem.md. Gaps to host apps: host-apps.md.
• Not a florist / commerce platform and not a clone of any shop case study.
• Not a Raspberry Pi (or other board) port until a board probe exists.
• Not a claim that QEMU boot, CI, hardware bring-up, a “secure OS,” an “immutable OS,” or a published bench is finished until a probe says so. Scoped immutability: immutability.md.
• Not an x86_64-primary kernel. x86_64 may become a secondary target later; it is not implemented now.

Success (current horizon)

A new session can read the vision, principles, overview, what can run today, building or porting, host-app gaps, architecture, honesty ledger, and latest daily brief, then take one roadmap milestone to a GitHub PR without inventing status.

ctos — Functional & Non-Functional Requirements

Learning/research AArch64 (arm64) Rust bare-metal kernel (not a general-purpose desktop OS).

ISA revision: ADR-003 (2026-09-08) replaced x86_64 / VGA / bootimage wording with AArch64 / UART / QEMU virt. IDs are unchanged. Sponsor authorized the text revision; do not mint new FR/NFR IDs here. The sponsor brief called this “ADR-002”; that number was already the identity-split ADR on the harness tip.

FR-06 stage note (2026-09-09): Stage moved Next → Now when M3 landed VBAR_EL1 + resumable BRK (ADR-004). ID unchanged.

FR-07 stage note (2026-09-09): Stage moved Next → Now when M4 landed the dedicated exception / fatal stacks (ADR-005). ID unchanged.

FR-08 stage note (2026-09-09): Stage moved Next → Now when M5 landed GICv2 + the EL1 physical timer (ADR-006). ID unchanged. FR-08 “later input” is M6 / ADR-007 (PL011 RX on virt). No new FR ID.

FR-09 stage note (2026-09-09): Stage moved Next → Now when M7 landed the EL1 identity map + bump frame allocator (ADR-008). ID unchanged. DTB parse remains staged (Unknown). Heap is M8 / FR-10.

FR-10 stage note (2026-09-09): Stage moved Next → Now when M8 landed GlobalAlloc on a first-fit heap backed by identity-mapped frames (ADR-009). ID unchanged. Growing / slab heaps remain later.

FR-11 stage note (2026-09-09): Stage moved Later → Now when M9 landed cooperative round-robin yield on EL1 (ADR-010). ID unchanged. Preemption / SMP remain later. A documented EL0 SVC ABI is ADR-021 / Track A A1 — not a new FR and not app hosting.

NFR-10 note (2026-09-17, ADR-078): EL0 net_tcp_echo quiet-path CNTPCT (perf: tcp-echo ticks=<n>, ADR-078). Threat-model v1.53. Measure-first only — not a latency SLA. Not BSD sockets. Not listen/accept. Keep net: tcp-ok / libctos: tcp-ok. IDs unchanged.

NFR-10 note (2026-09-17, ADR-077): FAT16 one-level nested mkdir + empty rmdir behind the thin VFS (fat: nested / fat: rmdir, ADR-077). Threat-model v1.52. Not POSIX mkdir/rmdir. Not arbitrary-depth trees. No new SVC. Not TCP CNTPCT. Keep fat: mkdir. IDs unchanged.

NFR-10 note (2026-09-17, ADR-075): EL0 fs_mkdir (SVC 27) + freestanding /mkdemo (libctos: mkdir-ok / mkdemo: ok, ADR-075). Threat-model v1.50. Not POSIX mkdir. Not a directory tree. Not EL0 TCP. Keep fat: mkdir. IDs unchanged.

NFR-10 note (2026-09-16, ADR-073): FAT16 root mkdir behind the thin VFS (fat: mkdir, ADR-073). Threat-model v1.48. Not POSIX mkdir. Not a directory tree. No new SVC this mile. Track N / TCP untouched. IDs unchanged.

NFR-10 note (2026-09-16, ADR-064): FAT16 multi-cluster grow behind the thin VFS (fat: grow / libctos: fat-grow, ADR-064). Threat-model v1.39. Not POSIX write API. Not exFAT. Track N untouched. IDs unchanged.

NFR pillars note (2026-09-09): ADR-011 revises NFR-05, NFR-07, and NFR-10 text in place (antifragility, performance, security as first-class pillars). IDs unchanged. Do not mint NFR-15+.

NFR-10 W^X note (2026-09-10): ADR-012 revises NFR-10 text in place for the heap / coop-stack NX cut. ADR-013 records EL0 direction; the first mile is enter/return + UXN fetch, not isolation. ADR-014 adds unmapped linker-stack guards. IDs unchanged.

NFR-10 / NFR-08 note (2026-09-11): ADR-015 revises NFR-10 text in place for the RO+NX text/data cut (SCTLR.WXN on). ADR-013 adds a user-TTBR0 read mile, an ASID-tagged TLB mile, and a standing EL0 context; ADR-016 adds a TTBR1 private-page first cut; ADR-017 adds EL1 fetch from the TTBR1 RAM alias; ADR-018 adds the first identity-tear cut (split tables + one torn text page); ADR-019 jumps the post-MMU continuation to high VA and unmaps a 16 KiB dedicated identity text range; ADR-020 rewrites rustc vtables to high aliases and unmaps live identity .text after the boot stub (.rodata/.data/heap stay). ADR-021 adds a documented EL0 SVC ABI (exit / uart_write / yield). ADR-022 adds a freestanding libctos CRT that wraps those numbers. ADR-023 adds a guest ELF64 PT_LOAD loader into user TTBR0. ADR-024 promotes standing EL0 so a loaded image runs until exit with fail-closed restore. Those are ABI + CRT + loader + standing-task miles, not app hosting. ADR-025 unmaps identity .rodata after a pointer rewrite (.data/heap stay). ADR-026 reads ID_AA64MMFR1_EL1.PAN on -cpu cortex-a57 (enable stays Planned). ADR-027 adds a thin VFS + in-RAM memfs (create / open / read / write / close; public SVC 19–23). ADR-028 adds virtio-mmio block + FAT16 behind that same VFS (/probe read). ADR-050 deepens FAT16 with guest write + small create. Those are memfs / block-FS miles, not POSIX and not app hosting. The umbrella isolation row stays Planned/non-claim (ADR-047). NFR-08 boot-to-ready CNTPCT is a measurement, not a budget. IDs unchanged.

Status legend: Now = hello-UART / QEMU virt / smoke sensors · Next = near roadmap · Later = aspirational.

Tracker is GitHub (gh). New IDs go through a GitHub issue plus an ADR/docs change — not chat.

Scope

In: freestanding no_std Rust, QEMU -kernel → _start, UART/earlycon output, exceptions/interrupts, paging, heap, basic multitasking, reproducible build/QEMU probes, docs-first harness (honesty, three pillars — antifragility / security / performance — second brain, thin multi-agent).

Out (for now): userspace processes, POSIX, networking stack, GPU, SMP, real-hardware certification, secure-boot productization, Raspberry Pi or other board bring-up (unprobed), x86_64 as a primary path.

IDs below are frozen. Do not invent new FR/NFR IDs in chat; add via issue + ADR/docs change.

Functional requirements

NFR-10 note (2026-09-12): ADR-039 revises NFR-10 text in place for the EL0 trampoline without TLBI VMALLE1 cut (after ADR-037/038). Threat-model v1.19. IDs unchanged.

NFR-10 note (2026-09-13): ADR-040 revises NFR-10 text in place for taken lower-EL IRQ while standing. Threat-model v1.20. FIQ/SError lower-EL still park. IDs unchanged.

NFR-10 note (2026-09-13, ADR-041): ADR-041 revises NFR-10 text in place for IRQ-unmasked default standing/task ERET. Threat-model v1.21. Short non-standing trampoline probes stay masked. FIQ/SError lower-EL still park. IDs unchanged.

NFR-10 note (2026-09-13, ADR-049): ADR-049 revises NFR-10 text in place for leftover identity RAM tear (ident: ram / ident: ram-fault / ident: ram-high; ident: ram-stay superseded). Threat-model v1.27. Umbrella isolation / PAN enable / taken SError / yank _start stay decided as in ADR-047. IDs unchanged.

NFR-10 note (2026-09-13, ADR-042): ADR-042 revises NFR-10 text in place for the isolation leftover honesty wrap (ident: start-stay / ident: ram-stay). Threat-model v1.22. Umbrella isolation / PAN enable / FIQ-SError / full _start teardown stay Planned. IDs unchanged.

NFR-10 note (2026-09-13, ADR-043): ADR-043 revises NFR-10 text in place for taken lower-EL FIQ while standing (el0: fiq) and SError park honesty (el0: serror-park). Threat-model v1.23. Taken SError / PAN enable / umbrella isolation stay Planned. IDs unchanged.

NFR-10 note (2026-09-13, ADR-047 / ADR-048): ADR-047 decides isolation leftovers (taken SError deferred/non-goal on this smoke machine; PAN enable non-goal on default cortex-a57; never yank _start; leftover RAM optional Planned; umbrella Planned/non-claim). ADR-048 writes product app-hosting claim criteria (still Planned at that note). Threat-model v1.26. IDs unchanged.

NFR-10 note (2026-09-13, ADR-048 / ADR-052): Product app-hosting claim is Verified under ADR-048 criteria Met×5; sponsor accept recorded in ADR-052. Threat-model v1.29. Still not Linux/POSIX/containers/“EL0 isolated.” IDs unchanged.

NFR-10 note (2026-09-14, ADR-053 / ADR-054 / ADR-055): Isolation-gap locks — taken SError hard-stopped (ADR-053); PAN enable locked non-goal on default cortex-a57 (ADR-054); umbrella “EL0 isolated” non-claim until checklist (ADR-055). Threat-model v1.30. IDs unchanged.

NFR-10 note (2026-09-14, ADR-056): FAT16 root listing behind the thin VFS (fat: readdir / fat: entries, ADR-056). Threat-model v1.31. Not POSIX getdents. IDs unchanged.

NFR-10 note (2026-09-14, ADR-057): FAT16 root delete behind the thin VFS (fat: delete, ADR-057). Threat-model v1.32. Not POSIX unlink. IDs unchanged.

NFR-10 note (2026-09-14, ADR-058): Thin VFS prefix mounts (vfs: mount / vfs: mounts, ADR-058). Threat-model v1.33. Not POSIX mount(2). IDs unchanged.

NFR-10 note (2026-09-28, ADR-091 / M6): the sponsor accepted the ADR-091 revision-3 sentence and scope in writing (B3, 2026-09-28 16:41 CEST). Umbrella “EL0 isolated” (P-SEC-3l) is Verified, only as that sentence: one core, the TCG default smoke machine; not a speculative-execution or side-channel claim, not a real-hardware claim, not a certification; EL0 can read its own code bytes; no multi-core race story. Checklist ADR-055 all Met. Threat-model v1.70. Earlier notes that say the umbrella is Planned / non-claim are as of their dates. IDs unchanged.

NFR-10 note (2026-10-02, ADR-091 revision 4): the sponsor accepted ADR-091 revision 4 in writing (“I accept ADR-091 rev 4”). Only the PAN clause and the code-bytes limit changed: the limit is now “app text is EL0 execute-only; EL1 can still read it (no FEAT_EPAN)” (was “EL0 can read its own code bytes”). The umbrella “EL0 isolated” (P-SEC-3l) stays Verified, only as the revision-4 sentence in ADR-091. Threat-model v1.74. The 2026-09-28 note above records revision 3 as of its date. IDs unchanged.

Non-functional requirements

Acceptance sketch (Now)

• cargo build succeeds with pinned nightly for aarch64-ctos.json.
• qemu-system-aarch64 -machine virt shows the hello line on serial or honesty ledger says Unknown until probed.
• scripts/qemu-smoke.sh fails closed if the hello string is missing or cargo test does not exit 0.
• cargo test uses ARM semihosting so QEMU exits 0 on pass and 1 on panic (force-fail).
• Current-EL BRK is handled via VBAR_EL1 (serial string and/or #[test_case]) or the honesty ledger says Unknown until probed.
• Nested / fatal exception prints a serial marker from a dedicated stack (FR-07) or the honesty ledger says Unknown until probed.
• A timer tick is observable on serial and/or #[test_case] via the virt GIC (FR-08 / M5) or the honesty ledger says Unknown until probed.
• A received PL011 byte is observable on serial (FR-08 input / M6) or the honesty ledger says Unknown until probed.
• MMU-on + allocate-frame / map-unmap is observable on serial and/or #[test_case] (FR-09 / M7) or the honesty ledger says Unknown until probed.
• Box / Vec on the kernel heap is observable on serial and/or #[test_case] (FR-10 / M8) or the honesty ledger says Unknown until probed.
• Two cooperative tasks are observable on serial and/or #[test_case] (FR-11 / M9) or the honesty ledger says Unknown until probed.
• A CNTPCT baseline delta is observable on serial and/or #[test_case] (NFR-07) or the honesty ledger says Unknown / Planned until probed.
• An IRQ-to-handler CNTPCT delta (min/max/spread) is observable on serial and/or #[test_case] (NFR-07) or the honesty ledger says Unknown until probed.
• Threat-model v1.1 exists under docs/framework/security.md; “secure OS” stays unclaimed (NFR-10).
• Heap NX / execute-from-heap caught is observable on serial and/or #[test_case] (NFR-10 / ADR-012) or the honesty ledger says Unknown until probed.
• Linker-stack guard store faults observably (NFR-10 / ADR-014) or the honesty ledger says Unknown until probed.
• EL0 first mile (SVC return and/or UXN IABORT) is observable on serial and/or #[test_case] (NFR-10 / ADR-013) or the honesty ledger says Unknown / Planned until probed.
• Host debug ELF size is printed by scripts/qemu-smoke.sh (NFR-08) or the honesty ledger says Unknown until probed.
• Boot-to-ready CNTPCT (perf: boot-delta) is observable on serial and/or #[test_case] (NFR-08) or the honesty ledger says Unknown until probed.
• RO+NX text/data (execute-from-.data and write-to-RO-text) is observable on serial and/or #[test_case] (NFR-10 / ADR-015) or the honesty ledger says Unknown until probed.
• EL0 cannot-read-kernel-data (user TTBR0) is observable on serial and/or #[test_case] (NFR-10 / ADR-013) or the honesty ledger says Unknown / Planned until probed.
• ASID isolation (dual ASID without TLBI VMALLE1 + conflict/stale-entry probe) is observable on serial and/or #[test_case] (NFR-10 / ADR-013) or the honesty ledger says Unknown / Planned until probed.
• Standing EL0 (el0: standing / el0: restored, is_active() flips) is observable on serial and/or #[test_case] (NFR-10 / ADR-013) or the honesty ledger says Unknown / Planned until probed.
• TTBR1 private page (ttbr1: el1 / ttbr1: no el0 / ttbr1: ok) is observable on serial and/or #[test_case] (NFR-10 / ADR-016) or the honesty ledger says Unknown / Planned until probed.
• EL1 fetch from the TTBR1 RAM alias (ttbr1: el1 exec / ttbr1: vbar) is observable on serial and/or #[test_case] (NFR-10 / ADR-017) or the honesty ledger says Unknown / Planned until probed. Identity -kernel stub at 0x40080000 stays.
• Identity-tear first cut (ident: split / ident: fault / ident: high / ident: no el0 / ident: ok) is observable on serial and/or #[test_case] (NFR-10 / ADR-018) or the honesty ledger says Unknown / Planned until probed. High-VA continuation plus a 16 KiB dedicated identity text range (ident: jump / ident: range / ident: text) is observable on serial and/or #[test_case] (NFR-10 / ADR-019) or the honesty ledger says Unknown / Planned until probed. High-VA vtable rewrite plus live identity .text tear (ident: reloc / ident: live) is observable on serial and/or #[test_case] (NFR-10 / ADR-020) or the honesty ledger says Unknown / Planned until probed. Identity .rodata tear (ident: rodata / ident: rodata-fault / ident: rodata-high) is observable on serial and/or #[test_case] (NFR-10 / ADR-025) or the honesty ledger says Unknown / Planned until probed. PAN ID field (pan: id= / pan: absent) is observable on serial and/or #[test_case] (NFR-10 / ADR-026) or the honesty ledger says Unknown / Planned until probed. Identity .data/stacks tear (ident: data / ident: data-fault / ident: data-high) is observable (NFR-10 / ADR-037) or the honesty ledger says Unknown / Planned until probed. Identity heap tear (ident: heap-reloc / ident: heap / ident: heap-fault / ident: heap-high) is observable (NFR-10 / ADR-038) or the honesty ledger says Unknown / Planned until probed. EL0 entry without TLBI VMALLE1 (el0: no-vmalle1) is observable (NFR-10 / ADR-039) or the honesty ledger says Unknown / Planned until probed. Lower-EL IRQ while standing (el0: irq) is observable (NFR-10 / ADR-040) or the honesty ledger says Unknown / Planned until probed. Lower-EL FIQ while standing (el0: fiq) and SError park honesty (el0: serror-park) are observable (NFR-10 / ADR-043 / ADR-045) or the honesty ledger says Unknown / Planned until probed. Yank _start decided never; leftover identity RAM after the heap is torn (ADR-049). Taken lower-EL SError is deferred/non-goal on this smoke machine. PAN is enabled on default cortex-a76 (ADR-080; was a non-goal on the historical cortex-a57). Umbrella “EL0 isolated”: see the M6 note above (ADR-091 sentence only). Do not claim PAN.
• EL0 SVC ABI (svc: yield / svc: user-hi / svc: uart / svc: exit / svc: ok) is observable on serial and/or #[test_case] (NFR-10 / ADR-021 / Track A A1) or the honesty ledger says Unknown / Planned until probed. This mile alone ≠ the ADR-048 product claim (Verified separately under ADR-048/052). Not a Linux ABI.
• libctos CRT (libctos: hi / libctos: ok / libctos: linked) is observable on serial and/or #[test_case] (NFR-10 / ADR-022 / Track A A2) or the honesty ledger says Unknown / Planned until probed. This mile alone ≠ the ADR-048 product claim (Verified separately under ADR-048/052).
• Guest ELF PT_LOAD loader (loader: mapped / loader: ok) is observable on serial and/or #[test_case] (NFR-10 / ADR-023 / Track A A3) or the honesty ledger says Unknown / Planned until probed. Not a Linux ABI. This mile alone ≠ the ADR-048 product claim (Verified separately under ADR-048/052).
• Standing EL0 as normal mode (el0: task-enter / el0: task-active / el0: task-exit / el0: task-restored / el0: restore-fail / el0: task-ok) is observable on serial and/or #[test_case] (NFR-10 / ADR-024 / Track A A4) or the honesty ledger says Unknown / Planned until probed. Not isolation. This mile alone ≠ the ADR-048 product claim (Verified separately under ADR-048/052).
• Thin VFS + memfs (fs: create / fs: write / fs: read / fs: el0 / fs: ok) is observable on serial and/or #[test_case] (NFR-10 / ADR-027 / Track A A6) or the honesty ledger says Unknown / Planned until probed. Not POSIX. This mile alone ≠ the ADR-048 product claim (Verified separately under ADR-048/052).
• virtio-blk + FAT16 (blk: virtio / blk: cap / blk: rw / blk: ok / fat: mount / fat: read / fat: ok) is observable on serial and/or #[test_case] (NFR-10 / ADR-028 / Track A A7) or the honesty ledger says Unknown / Planned until probed. Same VFS open. Not POSIX. Not FAT32. This mile alone ≠ the ADR-048 product claim (Verified separately under ADR-048/052).
• FAT16 write depth (fat: write / fat: rewrite / fat: create / host --check-write) is observable on serial and/or #[test_case] (NFR-10 / ADR-050) or the honesty ledger says Unknown / Planned until probed. Same VFS write. Not POSIX. Not FAT32. This mile alone ≠ the ADR-048 product claim (Verified separately under ADR-048/052).
• FAT16 root readdir (fat: readdir / fat: entries) is observable on serial and/or #[test_case] (NFR-10 / ADR-056) or the honesty ledger says Unknown / Planned until probed. Same thin VFS. Not POSIX getdents. Not FAT32. This mile alone ≠ the ADR-048 product claim (Verified separately under ADR-048/052).
• FAT16 root delete (fat: delete) is observable on serial and/or #[test_case] (NFR-10 / ADR-057) or the honesty ledger says Unknown / Planned until probed. Same thin VFS. Not POSIX unlink. Not FAT32. This mile alone ≠ the ADR-048 product claim (Verified separately under ADR-048/052).
• Thin VFS prefix mounts (vfs: mount / vfs: mounts) are observable on serial and/or #[test_case] (NFR-10 / ADR-058) or the honesty ledger says Unknown / Planned until probed. Same thin VFS. Not POSIX mount(2). Not a new disk FS. This mile alone ≠ the ADR-048 product claim (Verified separately under ADR-048/052).
• Panic path compiles and is reachable in principle.
• This FR/NFR file + honesty ledger live under docs/.

Traceability

Map roadmap milestones and PRs to FR/NFR IDs in PR descriptions when touching behavior.

Taken lower-EL SError on this smoke machine is deferred / non-goal (hard-stopped) (ADR-053 / ADR-047); research ADR-044; attempt ADR-045. Park honesty stays ADR-043. Product app hosting claim gate: ADR-048.

Technical architecture

ctos is a #![no_std] #![no_main] binary. There is no Rust standard library and no OS underneath. The crate builds for a custom target (aarch64-ctos.json): os: none, panic abort, red zone off, static relocation, soft-float (no early SIMD/FP). See ADR-003. Guest samples (not “apps”): apps-today.md. Porting stance: building-or-porting.md.

Boot path

1. qemu-system-aarch64 -machine virt -cpu cortex-a57 (or max; gic-version=3 is allowed).
2. -kernel loads the kernel ELF into virt RAM (linker base 0x40080000).
3. Entry is _start (assembly in src/main.rs): set SP, zero BSS, call kernel_main.
4. Early output is the virt PL011 UART at 0x0900_0000 (src/uart.rs).
5. kernel_main installs VBAR_EL1 (src/exception.rs, ADR-004) after UART init, then the EL1 identity map plus a TTBR1 private page and a cloned TTBR1 RAM alias (ADR-008, W^X split ADR-012, stack guards ADR-014, RO+NX ADR-015, TTBR1 first cut ADR-016, EL1 fetch mile ADR-017, identity-tear first cut ADR-018, identity .text range tear ADR-019, live .text tear ADR-020, identity .rodata tear ADR-025), then the frame pool after MMU + SCTLR.C (pre-MMU .bss stores can vanish), then the first-fit heap (ADR-009), then the cooperative scheduler (ADR-010), then GICv2 + CNTP (ADR-006). After Hello World! it proves map/unmap, Box/Vec, two tasks, heap NX, linker-stack guards, the EL0 first mile + standing context, ASID isolation, the TTBR1 private page and high-VA EL1 fetch, torn identity .text and .rodata, the PAN ID field, CNTPCT + IRQ-delta, several timer ticks, and polls PL011 RX (ADR-007).

flowchart LR
  Q["QEMU virt<br/>cortex-a57"] --> K["-kernel ELF<br/>@ 0x40080000"]
  K --> S["_start<br/>SP + BSS"]
  S --> U["PL011 UART"]
  U --> M["kernel_main"]

QEMU loads one OS ELF. Early print is UART; everything else starts in kernel_main. No bootloader crate, no VGA.

There is no bootloader 0.9 crate and no VGA buffer. The x86_64 phil-opp path was deleted when this ADR landed.

.cargo/config.toml still needs json-target-spec = true on rustc 1.100 nightly. The AArch64 JSON is taken from aarch64-unknown-none-softfloat plus os: none / numeric widths. That nightly rejected the file until both "abi": "softfloat" and "rustc-abi": "softfloat" were set. Behavior is bare-metal AArch64, abort, rust-lld.

This architecture does not claim Raspberry Pi or other SoC support.

Privilege: EL1 kernel vs standing EL0

The kernel runs at EL1. A freestanding image can stand at EL0 and ask the kernel for help with SVC (exit / uart_write / yield / thin-VFS numbers). That is the ctos process model (ADR-035) — not Linux fork / execve. Many isolation miles are Verified; the umbrella “EL0 isolated” is Verified only as the accepted ADR-091 sentence (M6, 2026-09-28; one core, TCG default smoke machine; not speculative-execution / side-channel, not real hardware, not a certification) (ADR-055; sponsor leftovers closure ADR-060). Details: el0.md.

flowchart TD
  EL1["EL1 — kernel<br/>page tables · SVC handler · VFS"]
  EL0["EL0 — standing task<br/>loaded freestanding image"]
  SVC["SVC<br/>exit · uart_write · yield · fs_*"]
  UMB["Umbrella “EL0 isolated”<br/>Verified: ADR-091 sentence only — M6"]
  EL0 -->|"asks"| SVC --> EL1
  EL1 -->|"ERET back"| EL0
  EL0 -.-> UMB

Standing EL0 + SVC is real. “EL0 isolated” is claimed only as the accepted ADR-091 sentence (one core, TCG; not side-channel, not real hardware, not a certification). Stock-QEMU taken SError still parks, and _start is never yanked (ADR-089 exception).

Memory sketch (identity / TTBR0 / TTBR1)

Simplified view of what the guest maps after bring-up. Live identity .text / .rodata / .data / heap / leftover RAM tears are Verified miles; the QEMU -kernel stub at _start stays mapped (ident: start-stay). High twins live under TTBR1. User TTBR0 is what standing EL0 walks.

flowchart TD
  subgraph ttbr0k ["TTBR0 kernel (EL1)"]
    ID["Identity map<br/>torn live ranges"]
    ST["_start stub stays<br/>0x40080000"]
  end
  subgraph ttbr0u ["TTBR0 user (EL0)"]
    UW["User window<br/>text/rodata + trampoline<br/>omits kernel .data/heap"]
  end
  subgraph ttbr1 ["TTBR1 high"]
    HI["High RAM alias + VBAR<br/>EL1 fetch twin"]
    PRIV["TTBR1_PRIV<br/>EL1-only page"]
  end
  ID --> ST
  ID -.->|"high twin"| HI
  UW -->|"SVC / ERET"| ID

_start stays while live identity ranges are torn. User TTBR0 is not a full process mm. Do not say “the kernel moved.”

OS vs app slots

QEMU still -kernels one OS ELF. Published freestanding EL0 samples live on the same FAT16 volume: /hello (A9 / UART+one yield), /fsdemo (ADR-059 / memfs via libctos), /fatdemo (ADR-061 / FAT /probe via libctos), /yldemo (ADR-062 / cooperative yield rounds). A2–A4 load /hello (no production embed). Cross-update is the same hello ELF on this OS and prior OS ba6541c. Product freestanding “app hosting done” is Verified under ADR-048 / ADR-052 — not Linux/POSIX/containers/OTA. Recipes: what-can-run.md. Companion: hosting-apps.md.

flowchart LR
  OS["OS ELF<br/>QEMU -kernel"] --> FAT["FAT16 volume<br/>virtio-blk"]
  H["/hello<br/>UART + yield"] --> FAT
  F["/fsdemo<br/>memfs VFS"] --> FAT
  D["/fatdemo<br/>FAT /probe"] --> FAT
  Y["/yldemo<br/>yield rounds"] --> FAT
  FAT --> LOAD["Guest PT_LOAD<br/>→ standing EL0"]

One guest volume, three freestanding samples. Slots disconnect OS rebuilds from the published ELFs. Not a container runtime. Not POSIX.

Thin VFS stack

One thin VFS surface (open / read / write / close / readdir / unlink) with two backends and a prefix mount table: in-RAM memfs and FAT16 on virtio-blk. /mem (+ A6 names) → memfs; / → FAT16. Read, write, root listing, delete, and mounts are depth miles — not POSIX. Stance: filesystem.md. ADR-058.

flowchart TD
  APP2["Standing EL0 / EL1 callers"] --> VFS["Thin VFS<br/>open · read · write · close · readdir · unlink"]
  VFS --> MT["Prefix mount table<br/>ADR-058"]
  MT -->|"/mem · A6 names"| MEM["memfs<br/>in-RAM named buffers"]
  MT -->|"/"| FAT2["FAT16<br/>read · write · root readdir · unlink"]
  FAT2 --> BLK["virtio-blk<br/>host fat16.img"]

Same API, two backends, prefix mounts. Say “routed path prefixes through a mount table” when vfs: mounts passes — not mount(2) or “supports FAT” as a product.

Track N — virtio-net path (ARP + ICMP + UDP + EL0 net/UDP SVC)

QEMU user netdev (SLIRP) plus guest virtio-net-mmio. N1 exchanges one ARP request/reply with gateway 10.0.2.2 (ADR-066). N2 sends an ICMP echo and expects a reply (ADR-067). N3 sends one UDP datagram to SLIRP DNS 10.0.2.3:53 and expects a UDP reply (ADR-070) — DNS is probe bait, not a DNS product. N4 exposes tiny EL0 SVCs (net_mac / net_ping) and FAT /netdemo (ADR-068). N3.x adds net_udp_dns and FAT /udpdemo (ADR-071) — kernel still owns virtio-net. No BSD sockets / TCP product. Spec/ADR wins on conflict with this sketch.

flowchart LR
  QN["QEMU user netdev<br/>SLIRP 10.0.2.2 / 10.0.2.3"] --> VN["virtio-net-device<br/>mmio"]
  VN --> GTX["Guest TX<br/>ARP / ICMP / UDP"]
  VN --> GRX["Guest RX<br/>ARP / ICMP / UDP reply"]
  GTX --> VN
  GRX --> OK["Markers<br/>net: ok · net: ping-ok · net: udp-ok"]
  OK --> EL0["EL0 SVCs<br/>net_mac / net_ping<br/>/netdemo"]
  OK --> EL0U["EL0 SVC<br/>net_udp_dns<br/>/udpdemo"]

Host flags alone are not a probe. Do not say “has networking” or “has sockets.” Cite ADR-063 / ADR-066 / ADR-067 / ADR-070 / ADR-071 / ADR-068 / ADR-071.

Current stage (UART hello + M2–M9 + ADR-011 pillars)

• Pl011 writer with TX-full wait and \n → \r\n; try_recv on UARTFR.RXFE / UARTDR
• print! / println! via spin::Mutex; fatal / unhandled / IRQ paths write the PL011 without the mutex
• After EL1 + VBAR, a bump frame allocator (src/frame.rs) and identity map (src/paging.rs) turn the MMU on (ADR-008); RAM after __kernel_end is PXN (ADR-012); 4 KiB holes sit under the linker stacks (ADR-014)
• First-fit GlobalAlloc (src/heap.rs) on a 64 KiB identity-mapped frame run (ADR-009); build-std includes alloc
• Cooperative round-robin (src/sched.rs): idle on the linker thread stack, two heap-backed workers, AAPCS64 callee-saved yield (ADR-010)
• kernel_main prints Hello World!, proves map/unmap (serial paging: ok), proves Box/Vec (serial heap: ok), proves two tasks (serial sched: task a / sched: task b / sched: ok), proves heap NX (serial wx: ok), proves linker-stack guards (serial guard: ok), proves the EL0 first mile + standing context (serial el0: ok / el0: standing / el0: restored), proves the SVC ABI (serial svc: yield / svc: user-hi / svc: uart / svc: exit / svc: ok), proves the libctos CRT (serial libctos: hi / libctos: ok / libctos: linked), proves the guest ELF PT_LOAD loader (serial loader: mapped / loader: ok), proves standing EL0 as a loaded task until exit (serial el0: task-enter / el0: task-active / el0: task-exit / el0: task-restored / el0: restore-fail / el0: task-ok), proves ASID isolation (serial asid: ok), proves the TTBR1 private page and high-VA EL1 fetch (serial ttbr1: ok / ttbr1: el1 exec / ttbr1: vbar), proves the identity-tear first cut, .text range tear, vtable rewrite, live .text tear, and identity .rodata tear (serial ident: ok / ident: jump / ident: reloc / ident: range / ident: live / ident: rodata / ident: rodata-fault / ident: rodata-high / ident: text / ident: split / ident: fault / ident: high / ident: no el0), proves the PAN ID field (serial pan: id= / pan: absent), proves CNTPCT advances (serial perf: cntpct delta=…), observes CNTP ticks (serial timer: tick) plus IRQ-to-handler deltas (serial perf: irq-delta), polls one host-injected RX byte (serial input: rx 0x41), fires one healthy-stack BRK #0 (serial exception: sync BRK), then the FR-07 nest probe (serial exception: fatal nested)
• VBAR_EL1 vector table (high alias after MMU, ADR-017); kernel runs on SP_EL0; first-level current-EL sync (SP_EL0 bank) handles AArch64 BRK, heap NX, guard-page data aborts, and the identity-tear IABORT; first-level IRQ handles GICv2 PPI 30; lower-EL AArch64 sync handles the EL0 SVC / UXN IABORT / standing dual-SVC / public SVC ABI / TTBR1 DABORT / torn-page DABORT; nested current-EL (SP_ELx bank) switches to the fatal stack (ADR-004, ADR-005, ADR-006, ADR-007, ADR-013, ADR-016, ADR-017, ADR-018, ADR-019, ADR-020, ADR-021)
• cargo test uses #![feature(custom_test_frameworks)] and #[test_case] (including VBAR, BRK, SPSel, stack ranges, guards, GIC TYPER, CNTFRQ, timer tick, IRQ-delta samples, empty UART RX FIFO, MMU on, frames, map/unmap, heap Box/Vec, two-task yield, CNTPCT loop, W^X flags + execute-from-heap, EL0 first mile + standing enter/leave, SVC ABI yield/uart/exit + kernel-.data / TTBR1-alias reject, libctos hello trip, guest ELF loader trip, standing-task until exit + fail-closed fault restore, ASID isolation, TTBR1 private page + high-VA EL1 fetch, identity-tear first cut + .text range tear + vtable rewrite + live .text tear; is_active() is false at rest)
• QEMU exit is ARM semihosting SYS_EXIT / hlt #0xf000 (src/qemu.rs), not isa-debug-exit. Needs -semihosting on the QEMU line (scripts/qemu-aarch64.sh).
• Host smoke: scripts/qemu-smoke.sh (hello + paging + heap + two-task sched + W^X + guards + EL0 first mile + standing + SVC ABI + libctos CRT + guest ELF loader + standing-task (A4) + ASID isolation + TTBR1 private page + high-VA EL1 fetch + identity-tear first cut + identity .text range tear + vtable rewrite + live .text tear + CNTPCT baseline + IRQ-delta + host ELF size + timer tick + injected UART RX + BRK + fatal nested strings + tests + force-fail must be non-zero)
• Docker: Dockerfile / scripts/docker-smoke.sh (linux/arm64-friendly; do not pin amd64)
• GHA: .github/workflows/smoke.yml (ubuntu-24.04-arm and ubuntu-24.04)

Source + local smoke were first probed on 2026-09-08 (see the honesty ledger). Current idle tip is main ≈ 190ef5a (Merge PR #106 / docs polish after ADR-061). Recent docs/miles: ADR-058–061 plus ADR-062 yield-libctos (this PR when merged). Earlier Docker Verified on tip e80dc93 (Merge PR #28 / ADR-020; 50 tests, ident: reloc n=12, live pages=37, force-fail ok) and prior SHAs 24d94e6 (ADR-019), b0f0ee5 (#24–#26), 71ee15f (layout L3). Keep the b2bbb99 Failed row. GHA merge-commit 34651404108 on e80dc93 grepped that ADR-020 class of markers. A Route 53 CNAME ctos.artof.link → artofdream.github.io. exists; https://ctos.artof.link HTTPS is Verified (2026-09-11 after #30). Do not claim “secure OS” or “the kernel moved”; say “EL0 isolated” only as the ADR-091 sentence. Tip smoke / Docker / GHA on 97a8559 itself: see the honesty ledger (do not invent Verified from this docs edit).

Planned stages

Each stage is one loop unit on the roadmap.

x86_64 remains a possible future secondary ISA. It is not a current tree.

Harness mapping (short)

Hardware and QEMU are the domain. Docs, ADRs, and this architecture note are shared understanding. Guides, sensors, the one-PR loop, second-brain vaults, merge permissions, and the honesty ledger are the outer harness. Details: formula.md.

ADR-001 — Apply a honesty/harness practice to ctos

• Status: Accepted
• Date: 2026-09-08

Context

ctos is a bare-metal kernel. Agents and humans will extend it across sessions. Status words drift: “it boots” gets written because source exists, or because a README says cargo run. Without a probe, that is fiction.

Harness-engineering practice (guides, sensors, a tight loop, persistent memory, no self-merge, observability of claims) is useful here. Prior art: architecture.artof.link. This ADR does not adopt that site’s product, florist domain, or stakeholder roster.

Decision

Apply a ctos-native honesty/harness practice:

1. Honesty — every status word is a claim; the honesty ledger records the probe. Unprobed = Unknown. Never round Unknown up to Verified.
2. Document-first — vision, architecture, ADRs, and roadmap land before more kernel features.
3. Second brain — four vaults under research/ (procedure via skills, correction via constraints/rules, relationship via doc links, daily brief / session memory).
4. Thin roles — Knowledge Guardian, Coherence Guardian, Kernel Engineer, MR Coordinator (ctos-* skills only).
5. Loop — one milestone → one branch → one GitHub PR. The author does not self-approve or merge (see ADR-002).
6. Sensors over vibes — when a failure repeats, strengthen a sensor or gate (see antifragility.md).

Tracker and reviews stay on GitHub (gh). No GitLab workflow is part of this repo.

Consequences

• README and docs may teach cargo run without claiming QEMU boot is Verified.
• New kernel work cites a roadmap milestone and updates the ledger when something is actually probed.
• Role names stay ctos-*. Do not introduce aea-* hats or shop case-study content.

ADR-002 — PR author ≠ merger (two GitHub identities)

• Status: Accepted
• Date: 2026-09-08
• Amended: 2026-09-12 (Track A historical exception + going-forward restatement)

Context

NFR-12 says implementer ≠ merge approver. On a solo GitHub login, a second Cursor agent cannot APPROVE a PR that login opened (GitHub self-APPROVE rule). Enabling “authors can approve their own PRs” would count same-login review as a gate. That is theater.

Café Fausse (artofdream/aea-interactive-design, .cursor/skills/pr-coordinator/SKILL.md) already probed this: cursor[bot] is the distinct second identity. Same principle applies here. This ADR does not import that repo’s restaurant/SRS content.

Cloud / Cursor agents on this repo often open PRs as artofdream. Commits commonly list cursoragent plus Co-authored-by: artofdream. That is still an owner-opened PR. A trailer does not change the GitHub author login and does not authorize a same-login merge.

Decision

Reuse that split on ctos:

1. Do not enable GitHub author self-APPROVE. Do not add a required-approval ruleset until a second human exists.
2. Author does not merge their own PR.
3. Identities: artofdream (owner) and cursor[bot] (Cursor GitHub App, already used for cloud PRs). Do not install another App or mint a second personal account for this.
4. Written MRC (ctos-mr-coordinator) is the review-in-the-room. Prefer COMMENT / REQUEST_CHANGES. Record who authored / who reviewed / who merges on the PR. Name those logins from gh pr view --json author,mergedBy (or the GitHub PR header), not from a daily-brief guess.
5. If cursor[bot] REST APPROVE returns 403 (probed on Café Fausse #27; unprobed on ctos), do not block a valid cursor[bot] merge of an artofdream-authored PR after this-run green checks (when CI exists) and Bugbot resolved-or-declined. Missing Approve is not a reason to treat that merge as invalid.
6. Owner PAT / artofdream still must not APPROVE or merge an artofdream-authored PR.

Going-forward (2026-09-12 restatement)

The GitHub PR author login is the identity that matters.

No self-merge. Owner-opened → bot merges. Bot-opened → owner merges.

Historical exception — Track A (A1–A9)

Named exception. Do not rewrite those PR pages. Sponsor directed this cleanup after Track A closed its first cuts.

• When: 2026-09-11–2026-09-12
• Scope: Track A first-cut PRs A1–A9: #49 (A1), #52 (A2), #53 (A3), #54 (A4), #55 (A5), #56 (A6), #57 (A7), #59 (A8), #60 (A9)
• What gh showed (2026-09-12): each of those PRs had author=artofdream and mergedBy=artofdream. Commits were typically cursoragent with Co-authored-by: artofdream. That is same-login merge. It does not satisfy this ADR.
• What this is not: not a claim those kernel or docs miles are invalid (their probes stay on their own ledger rows); not a rewrite of git history; not permission to repeat the pattern.
• Earlier miles: many pre-Track-A merged PRs show the same GitHub author/mergedBy pair. This note names Track A as the sponsor-directed exception. It does not relitigate those older PR pages.

After this amendment, a same-login merge is a process miss, not an undocumented habit.

Consequences

• Probe the GitHub author field before naming the merge hat. Chat “expected cursor[bot]” is not a probe.
• #2: gh on 2026-09-12 shows author=artofdream, mergedBy=artofdream. The 2026-09-08 sentence that called it cursor[bot]-authored is withdrawn.
• Smoke CI exists and has been probed on this repo (honesty ledger CI rows). “Green checks” on a new PR still need that PR’s run. Missing this-run green is not green.
• cursor[bot] merge and App APPROVE on this repo stay Unknown until a distinct-identity merge is probed here. Do not copy Café Fausse #16/#27 as a ctos probe. Track A same-login merges are not that probe.

ADR-003 — Primary ISA is AArch64

• Status: Accepted
• Date: 2026-09-08

The sponsor brief named this decision “ADR-002.” On the harness tip, ADR-002 is already the author ≠ merger identity split. This file is ADR-003 so that accepted decision stays intact. Frozen FR/NFR IDs are unchanged; ISA-specific text is revised under this ADR.

Context

The sponsor host (arm64 workstation) is Windows ARM64 with Docker linux/arm64. Native AArch64 QEMU is the right guest. Keeping x86_64 as primary would mean a translated or foreign ISA on that machine.

The previous primary path (phil-opp VGA text at 0xb8000, bootloader 0.9, bootimage, qemu-system-x86_64) is superseded. It was a tutorial-era lift, not a host-ISA decision.

x86_64 may be noted later as a secondary target. It is not implemented in the change that lands this ADR.

Decision

1. Primary ISA is AArch64 (arm64). The checked-in custom target is aarch64-ctos.json (aarch64-unknown-none style: os: none, panic abort, static relocation, soft-float so early boot does not require enabling SIMD/FP in CPACR_EL1).
2. Boot path is QEMU -kernel of the kernel ELF on -machine virt (or virt,gic-version=3) with -cpu cortex-a57 or max. Entry is _start at a linker-script address in virt RAM. No bootloader 0.9 crate and no bootimage disk as the primary path.
3. Console is the virt PL011 UART (MMIO 0x0900_0000) via print! / println!. Not VGA 0xb8000. earlycon remains an allowed later probe; this ADR does not claim it.
4. Do not claim Raspberry Pi or other board support until a board-specific probe exists. virt is the supported guest.
5. Delete the x86-only primary tree (x86_64-ctos.json, src/vga_buffer.rs) rather than leave a broken dual tree.

Consequences

• New target JSON, linker script, and UART writer replace the VGA / bootloader 0.9 stack.
• .cargo/config.toml default target is aarch64-ctos.json. json-target-spec stays for current nightly.
• Roadmap M0/M1 probes are UART + qemu-system-aarch64, not a VGA dump at 0xb8e60.
• FR-01, FR-02, FR-03, FR-05 (and other x86-specific wording) are revised in place. No new FR/NFR IDs.
• Later exception/interrupt work is VBAR / GIC, not IDT / PIC / TSS. M3 / ADR-004 is the VBAR_EL1 + BRK path.
• Honesty ledger rows for the x86 VGA path are historical. They do not verify the AArch64 path.

ADR-004 — EL1 VBAR and resumable BRK

• Status: Accepted
• Date: 2026-09-09

Context

FR-06 requires synchronous exceptions via VBAR_EL1 (at least a breakpoint / fault path). Roadmap M3 is that path. M4 (FR-07) is a dedicated fatal stack. M5 (FR-08) is GIC IRQs.

QEMU virt -kernel usually starts the guest at EL1. -machine virt,virtualization=on starts at EL2. Exceptions taken to the current EL use that EL’s VBAR_*. Staying at EL2 and programming only VBAR_EL2 would not satisfy FR-06.

Decision

1. Live at EL1. exception::init calls ensure_el1: if CurrentEL is EL2, set HCR_EL2.RW, copy SP to SP_EL1, and ERET to EL1h (DAIF masked). If the EL is not 1 after that, print and park. Do not treat VBAR_EL2 as the primary table.
2. One 2 KiB-aligned table at exception_vectors, written to VBAR_EL1. All sixteen AArch64 slots exist. Current EL / SP_EL0 / synchronous saves a frame and may ERET. Current EL / SP_EL0 / IRQ is live as of ADR-006. Every other slot parks (UART line + wfe, or semihosting fail under cargo test / force-fail).
3. Context format (current-EL sync only): x0–x29, x30, ELR_EL1, SPSR_EL1, ESR_EL1. No SIMD/FP save (soft-float, ADR-003).
4. BRK is resumable. ESR exception class 0x3C (AArch64 BRK) increments a counter, prints exception: sync BRK, adds 4 to ELR_EL1, and returns. Other synchronous exceptions are fatal for this milestone (print + park). That is not FR-07’s dedicated overflow stack.

Consequences

• #[test_case] can execute brk #0 and continue. The hello kernel fires one BRK so scripts/qemu-smoke.sh can require the handler string on serial.
• Lower-EL and FIQ/SError stubs are parks. Current-EL IRQ is M5 / ADR-006, not a syscall ABI.
• A nested fault while println! holds the UART mutex can deadlock. ADR-005 (M4 / FR-07) splits SP_EL0 / SP_EL1, adds a fatal stack, and uses a raw UART write on that path.
• This ADR does not claim Raspberry Pi, EL0, or a taken lower-EL exception.

ADR-005 — Dedicated exception and fatal stacks

• Status: Accepted
• Date: 2026-09-09

Context

FR-07 requires a fatal exception to use a dedicated stack so overflow does not silently lock the VM. Roadmap M4 is that path. ADR-004 already notes that a nested fault while println! holds the UART mutex can deadlock.

M3 ran the kernel and first-level current-EL exceptions on the same SP_EL1 (SPSel = 1). A nested sync exception would store another 272-byte frame on that stack. Without paging a downward overflow is not a hardware fault on QEMU virt — it smashes .bss / code with no serial evidence. M7 identity-maps RAM as one Normal block, so this is still true (no guard pages).

A data abort to an unused physical hole is QEMU-map-dependent. A nested BRK from the first-level handler is a real current-EL exception we already know how to take (FR-06).

Decision

1. Thread stack on SP_EL0. After VBAR_EL1 is installed, copy the _start stack into SP_EL0 (MSR SP_EL0 is legal at EL1), write __exc_stack_top into SP while SPSel is still 1 (that is SP_EL1 — MSR SP_EL1 at EL1 is UNDEF), then msr spsel, #0. Normal kernel code uses the 64 KiB thread stack.
2. Exception stack on SP_EL1. First-level current-EL exceptions (vector bank “Current EL, SP_EL0”) use the 16 KiB __exc_stack_* region automatically. The live sync slot moves from offset 0x200 (M3 / SP_ELx) to 0x000.
3. Fatal stack before any nested store. Current-EL / SP_ELx slots (0x200–0x380) load SP from __fatal_stack_top (8 KiB) in asm, then call handle_fatal_exception. Do not push a frame on the exception stack that may already be exhausted.
4. Raw UART on fatal / unhandled paths. Write the PL011 without spin::Mutex so a nest during println! still produces serial.
5. Probe is nested BRK after a near-empty thread SP. The hello kernel fires a healthy-stack BRK (M3 string), then sets a flag, moves SP_EL0 to __stack_bottom + 64 (less than the 272-byte frame), and BRKs again. The first-level handler prints exception: sync BRK from SP_EL1, then BRKs while SPSel = 1. That nest must print exception: fatal nested and park. This is not an MMU stack-overflow fault and not a GIC path (M5 / FR-08).

Consequences

• #[test_case] can still brk #0 and return. Tests do not set the nest flag.
• scripts/qemu-smoke.sh requires the fatal marker in addition to hello + BRK. A fatal probe missed line is fail-closed.
• Lower-EL and first-level FIQ/SError stubs still park. First-level IRQ is M5 / ADR-006. Nested IRQ/FIQ/SError still use the fatal stack. Taking a nested IRQ remains unprobed.
• This ADR does not claim Raspberry Pi or x86. Unmapped linker-stack guard pages are ADR-014 (a later cut; the nested-BRK probe here still stands).

ADR-006 — GICv2 and the EL1 physical timer

• Status: Accepted
• Date: 2026-09-09

Context

FR-08 requires hardware interrupts via the virt GIC, with a timer tick observable. Roadmap M5 is that path. ADR-004 installed VBAR_EL1; ADR-005 split stacks. First-level IRQ was still a park.

QEMU -machine virt can expose GICv2 or GICv3 (gic-version=2|3|4|host|max). The current smoke line is -machine virt with no gic-version override. QEMU 8.2’s virt default is GICv2 (distributor at 0x0800_0000, CPU interface at 0x0801_0000). GICv3 uses a redistributor at 0x080A_0000 instead of that CPU interface.

The ARM generic timer is already in the core (CNTP_*_EL0 / CNTV_*_EL0). No extra virtio device is required.

Decision

1. Program GICv2, matching default -machine virt. Do not add a GICv3 redistributor driver in this milestone. If a later QEMU default flips to v3, pin gic-version=2 on the smoke line or add a v3 driver in a new ADR.
2. Use the non-secure EL1 physical timer (CNTP_CTL_EL0 / CNTP_TVAL_EL0 / CNTPCT_EL0) and PPI 30. If ensure_el1 drops from EL2, set CNTHCTL_EL2.EL1PCTEN|EL1PCEN and zero CNTVOFF_EL2 so EL1 can use the counter and physical timer.
3. Take IRQs on the current-EL / SP_EL0 bank (vector offset 0x080). The kernel runs with SPSel = 0, so first-level IRQs use SP_EL1 (the M4 exception stack). Save the same GPR + ELR/SPSR/ESR frame as sync, then EOI.
4. Keep DAIF.I masked except for an observe window. Hello and #[test_case] unmask, wait for one tick (or a CNTPCT timeout), then remask and stop the timer so M3 BRK / M4 nested fatal are not interrupted.
5. Raw UART on the IRQ path. The handler must not take spin::Mutex (same reason as ADR-005). First tick prints timer: tick.

Consequences

• scripts/qemu-smoke.sh requires timer: tick and rejects timer: tick missed, then still requires the M3/M4 strings.
• #[test_case] can wait for a tick with IRQs unmasked and continue.
• FIQ, SError, lower-EL, and unexpected IRQ IDs stay parks / raw markers. UART input is M6 / ADR-007.
• This ADR does not claim Raspberry Pi, GICv3, virtualization=on as the primary path, or a taken FIQ.

ADR-007 — PL011 UART RX as virt input

• Status: Accepted
• Date: 2026-09-09

Context

FR-08 already covers hardware interrupts (timer via the virt GIC, M5 / ADR-006) and named “later input” as the rest of that ID. Roadmap M6 is that input path. The x86-era reading of FR-08 was a keyboard. Frozen IDs stay; the arm64 text is revised here.

Options on QEMU virt:

1. PL011 UART RX at 0x0900_0000 (already the console).
2. virtio-input / virtio-keyboard (virtio-mmio, virtqueues, DMA). No paging or heap yet (M7/M8). Too much device stack for one milestone.
3. PL011 UARTCR.LBE loopback as a self-test. QEMU 8.2 (Ubuntu 24.04 / this repo’s GHA and cloud probe) does not implement LBE — hw/char/pl011.c still says the loopback bit is unimplemented. LBE landed in later QEMU. A loopback-only probe would be a false pass on newer hosts and a false fail on 8.2.

Host stdin on -serial stdio does reach pl011_receive → the RX FIFO. UARTLCR_H.FEN toggles reset that FIFO, so a byte sent before uart::init is lost. Inject after Hello World! (init already ran).

Decision

1. M6 input is PL011 RX poll, not virtio-keyboard and not a UART RX IRQ. FR-08’s “via the virt GIC” remains the M5 timer. Input does not take a new FR ID.
2. Prove a received byte with a host inject: scripts/qemu-serial-inject.py writes 0x41 ('A') to QEMU stdin after it sees Hello World!. The hello kernel polls UARTFR.RXFE / UARTDR (DAIF.I still masked after the timer window) and prints input: rx 0x41.
3. Fail closed. Missing marker or input: rx missed fails scripts/qemu-smoke.sh. #[test_case] only asserts the FIFO is empty when cargo test does not inject — the character proof is the serial smoke.
4. Do not claim Raspberry Pi UART, virtio-input, GICv3 UART SPI, or QEMU LBE.

Consequences

• scripts/qemu-smoke.sh needs python3 to drive the inject (Dockerfile installs it).
• cargo test / scripts/qemu-aarch64.sh stay inject-free so M2–M5 cases do not wait on stdin.
• A later virtio-keyboard or UART-RX-via-GIC path needs a new ADR; it is not this milestone.

ADR-008 — Identity map and bump frame allocator

• Status: Accepted
• Date: 2026-09-09

Context

FR-09 requires the kernel to read a firmware/QEMU memory map (DTB when probed) and establish paging / virtual memory. Roadmap M7 is that path. Heap GlobalAlloc is M8; the scheduler is M9.

QEMU -machine virt memory (see hw/arm/virt.c):

_start currently overwrites x0 (the firmware DTB pointer) to set SP. A full FDT memory-node walk is extra surface for one milestone and is not required to prove MMU-on + allocate-frame on this machine.

Options:

1. 1 GiB L1 identity blocks (39-bit VA, T0SZ=25, 4 KiB granule) plus a dedicated 4 KiB map window.
2. Fine-grained 4 KiB identity of every used page (more tables, same probe).
3. Higher-half kernel (breaks the current linker / VBAR / UART absolute addresses).
4. Parse the DTB before enabling the MMU (correct long-term; not the M7 fail-closed proof).

Decision

1. Enable the MMU at EL1 after exception::init (ensure_el1). Program MAIR_EL1 (Attr0 Device-nGnRnE, Attr1 Normal WB), TCR_EL1 (TTBR0 only, 40-bit IPS, inner-shareable WB), TTBR0_EL1, then set SCTLR_EL1.M|C|I|SA. Identity: VA == PA for everything the kernel already touches.
2. L1 blocks, not a full 4 KiB identity. Entry 0 (0x0–1 GiB) is Device-nGnRnE + XN (UART, GIC, flash). Entry 1 (0x4000_0000–0x7FFF_FFFF) was a Normal WB executable 1 GiB RAM block in M7. ADR-012 supersedes that RAM block: L1 slot 1 is now an L2 table, only 128 MiB is mapped, and __kernel_end…RAM-end is PXN. The allocator still must not hand out frames past RAM_BASE + 128 MiB.
3. Frame pool from linker + virt convention. __kernel_end (after image + stacks, 4 KiB-aligned) through 0x4000_0000 + 128 MiB. Bump cursor plus a 16-entry free stack. Do not allocate 0x4000_0000–0x4008_0000 (DTB / TEXT_OFFSET hole). Smoke pins -m 128M so the pool matches the VM.
4. Map/unmap probe uses a third GiB window (0x8000_0000) via one L2 + L3 table, not by splitting the RAM block. Serial marker paging: ok. Do not load an unmapped VA (that would take an unhandled data abort).
5. DTB parse is staged. M7 does not walk FDT. FR-09’s “DTB when probed” stays Unknown until a later ADR. The probed map is the virt table above plus __kernel_end.
6. No GlobalAlloc. Frames are physical pages only.

Consequences

• scripts/qemu-smoke.sh requires paging: ok and rejects paging: probe missed, then still requires M2–M6 strings.
• #[test_case] can assert SCTLR_EL1.M, distinct aligned frames, and a map/unmap write-through.
• Stack overflow was not a translation fault in M7 (RAM was one Normal block). Guard pages are ADR-014, not this milestone.
• A later DTB walker or higher-half map needs a new ADR; it is not M8’s heap.
• This ADR does not claim Raspberry Pi, GICv3, EL0 user maps, or ASID isolation. Heap NX is ADR-012, not M7.

ADR-009 — First-fit heap on identity-mapped frames

• Status: Accepted
• Date: 2026-09-09

Context

FR-10 requires a GlobalAlloc heap so alloc types (Box, Vec) work in the kernel. Roadmap M8 is that path. The scheduler is M9.

M7 already identity-maps virt RAM and hands out 4 KiB frames from __kernel_end through 128 MiB (ADR-008). Frames are physical pages, not a byte allocator.

Options:

1. Bump-only heap (no dealloc). Box/Vec construct, but drop leaks. Reuse is unproved.
2. linked_list_allocator crate. Common rust-osdev choice; extra dependency for one milestone.
3. First-fit free list on a fixed contiguous frame run taken from the bump pool after the MMU is on.
4. Grow-on-demand via the M7 map window (0x8000_0000). Extra paging surface; not needed to prove FR-10.
5. Buddy / slab. Overkill for a Box/Vec smoke.

Decision

1. Fixed 64 KiB heap (16 frames) via frame::alloc_contiguous after paging::init. Identity VA == PA. Do not map through the M7 probe window.
2. First-fit + address-sorted coalesce in src/heap.rs. dealloc is real; the hello probe requires a freed Box pointer to be reused.
3. #[global_allocator] + extern crate alloc. .cargo/config.toml build-std includes alloc. OOM returns a null pointer; #[alloc_error_handler] prints heap: oom on the raw UART and parks (or SYS_EXIT 1 under test). The handler must not format — formatting an OOM can allocate again.
4. Serial marker heap: ok. Fail closed on heap: probe missed. #[test_case] covers pool bounds, Box reuse, and Vec growth.
5. Not a growing heap, not userspace, not the scheduler. A later slab / grow-on-demand / higher-half heap needs a new ADR.

Consequences

• scripts/qemu-smoke.sh requires heap: ok after paging: ok, then still requires M2–M7 strings.
• The frame pool shrinks by 64 KiB at boot. M7 frame/map tests still have the rest of the 128 MiB guest.
• This ADR does not claim Raspberry Pi or a production allocator. M9 task stacks on this heap are ADR-010.
• ADR-038 keeps the first-fit algorithm and moves the pool VAs to the TTBR1 alias, then unmaps identity heap. The 64 KiB size is unchanged.

ADR-010 — Cooperative round-robin on EL1

• Status: Accepted
• Date: 2026-09-09

Context

FR-11 requires cooperative or simple round-robin task switching. Roadmap M9 is that path. The heap already exists (ADR-009); paging is an identity map (ADR-008). The kernel runs at EL1 with SPSel = 0 so SP is SP_EL0 (ADR-005).

Options:

1. Async/await executor. Extra Future infrastructure for two markers.
2. Timer preemption. Would steal the M5 CNTP path and needs IRQ-safe yield. Not required to prove FR-11.
3. Cooperative yield that saves AAPCS64 callee-saved GPRs on a per-task stack and switches SP.
4. SMP / EL0 processes. Out of scope (vision Out list).

The callee-saved layout is not obvious next to the exception frame in ADR-004 (that frame is x0–x30 + ELR/SPSR/ESR on SP_EL1). A yield must not touch the exception stacks.

Decision

1. Cooperative only. Tasks call sched::yield_now(). No timer slice. DAIF.I stays masked during the hello/test probe (M5 still remasks after its own tick).
2. AAPCS64 callee-saved switch in context_switch: save/restore x19–x28, x29, x30 on the task stack; store SP in the task slot; load the next SP. No SIMD/FP (ADR-003 soft-float). Not the exception context.
3. Idle slot 0 is kernel_main / the test runner on the linker thread stack. Two workers get 8 KiB stacks from the M8 heap (Vec<u8>, not a stack-allocated [u8; N] that would overflow SP_EL0 during Box::new). Identity VA == PA.
4. Round-robin among Ready slots. A worker that returns is Done (trampoline). Idle stays Ready so control returns to the caller of yield_now. Unlock the scheduler mutex before context_switch.
5. Serial markers sched: task a, sched: task b, then sched: ok after both SPs land on distinct heap stacks. Fail closed on sched: probe missed.
6. Not preemptive, not SMP, not EL0, not async. A later preemptive or process ADR is a new file.

Consequences

• scripts/qemu-smoke.sh requires the three sched: strings after heap: ok, then still requires M2–M8 strings.
• Two 8 KiB worker stacks come out of the 64 KiB heap. M8 Box/Vec probes drop before spawn.
• Exception / fatal stacks are unchanged. A yield never runs from an IRQ handler.
• This ADR does not claim Raspberry Pi, preemption, or userspace.

ADR-011 — Three pillars: antifragility, security, performance

• Status: Accepted
• Date: 2026-09-09

Frozen FR/NFR IDs are unchanged. This ADR revises NFR-05, NFR-07, and NFR-10 text in place. Do not mint FR-16+ or NFR-15+.

Context

Bring-up M0–M9 is on main (UART through a cooperative EL1 scheduler). The first-class practice so far was the honesty/harness loop (ADR-001): probes, ratchets, fail-closed CI, no self-merge.

Sponsor direction after M9: antifragility is not enough by itself. Security and performance are first-class pillars too — not afterthoughts bolted on when the kernel “feels done.”

Risks if we leave the NFR text as-is:

• NFR-07 is still “Could / Later / learning-only.” That invites fake benches or silent “it’s fast enough” claims.
• NFR-10 is mostly “no secrets in repo.” That is necessary and not a threat model.
• NFR-05 already names ratchets, but it reads like a Next-stage SOP rather than a standing pillar.

This ADR does not clone florist / AEA vocabulary. The three pillars are ctos-native names for existing IDs.

Decision

1. Three first-class pillars, same weight, different sensors:

   • Antifragility — keep the existing harness: honesty ledger, fail-closed scripts/qemu-smoke.sh, GHA smoke.yml, Docker smoke, #[test_case]. Repeated failures become ratchets, not README-only advice (antifragility.md).
   • Security — no “secure OS” / “hardened” / “W^X done” claim without a written threat model and a probe. Prefer minimize unsafe (already NFR-01). Prefer W^X / NX stacks and heap when paging can express it. No execute-from-writable heap by default once maps can mark NX. Least privilege on IRQ paths (no heap alloc, no sched::yield_now from an IRQ). Future EL0 isolation is Planned.
   • Performance — no fake benches and no invented latency numbers. Add honest measurable probes (CNTPCT delta around a known path; later timer-tick jitter). Optimize only after a probe shows a cost.

2. Revise frozen NFR text in place (IDs stay NFR-05 / NFR-07 / NFR-10):

   • NFR-05: Must / Now. Ratchets stay the mechanism.
   • NFR-07: Should / Now. Probe language; not a hard latency budget.
   • NFR-10: Must / Now. Threat-model stub + claim gate, not only “no secrets.”

3. W^X is Planned on this identity map. ADR-008 maps virt RAM as one executable 1 GiB L1 Normal block. The heap (ADR-009) and cooperative stacks (ADR-010) live in that block, so they are W+X today. Forbidding execute-from-heap needs an L2/L3 split (or a later higher-half map). Device MMIO is already XN. Do not claim heap NX because the L3 map window can set PXN — that window is not the heap.

4. One small code ratchet may land with this docs PR. This change lands a baseline CNTPCT loop delta (serial perf: cntpct + #[test_case]). It does not split the L1 RAM block to fake W^X. Honesty over heroics.

5. Post-M9 work is a pillars section, not a second bring-up stack on an open PR. Threat-model v1, W^X / NX heap+stacks, and further perf probes were listed as later loop units. The sponsor later asked for one coherent follow-up (ADR-012, ADR-013, irq-delta) rather than conflicting parallel branches.

Consequences

• README, AGENTS.md, the roadmap, and the honesty ledger point at pillars.md.
• A PR that says “secure” or “faster” without a ledger row is a coherence fail (NFR-06 / NFR-13).
• The CNTPCT probe (when landed) is a baseline that the counter advances. It is not a published benchmark and not a comparison to other kernels.
• PAN, full higher-half identity teardown, and preemption remain later. Standing EL0 and the ASID-tagged TLB mile are ADR-013. TTBR1 private page is ADR-016. EL1 high-VA fetch is ADR-017. The first identity-tear cut is ADR-018. The identity .text range tear is ADR-019. The live .text tear after a high-VA vtable rewrite is ADR-020. The SVC ABI mile is ADR-021. The libctos CRT mile is ADR-022. The guest ELF loader mile is ADR-023. Standing EL0 as normal mode is ADR-024 (app hosting Planned). Umbrella isolation still Planned. RO+NX text/data is ADR-015. Stack guard pages are ADR-014. EL0 first mile + user-TTBR0 read mile are also ADR-013.

ADR-012 — W^X: NX heap and cooperative stacks

• Status: Accepted
• Date: 2026-09-10

Context

NFR-10 and ADR-011 require a probe before any W^X claim. ADR-008 mapped virt RAM as one executable 1 GiB L1 Normal block. The heap (ADR-009) and cooperative stacks (ADR-010) live in that block, so they were W+X. Setting PXN only on the M7 map window (0x8000_0000) would have been a fake “NX heap” claim.

Device MMIO (L1 block 0) was already XN. The missing cut is: heap and heap-backed stacks NX, kernel text still executable.

SCTLR_EL1.WXN is not usable while kernel text pages are writable — it would make text NX too.

Decision

1. Replace the RAM L1 block with an L2 table (still 39-bit / 4 KiB / TTBR0). Map only the 128 MiB guest (0x4000_0000…+128 MiB). The rest of that GiB stays invalid.
2. 2 MiB L2 blocks where a block is entirely kernel-image or entirely frame-pool. One L3 table per mixed 2 MiB (originally the single block that straddled __kernel_end; ADR-015 splits on __data_start and KERNEL_TEXT, which can be two blocks).
3. Executable: pages in [0x4008_0000, align_4k(__kernel_end)) (text, rodata, data, BSS, linker stacks). PXN+UXN: [__kernel_end, RAM end) (frame pool, heap, cooperative stacks) and the DTB hole below 0x4008_0000 when that hole is in the straddling L3. Device L1 stays XN. The M7 map window L3 pages are PXN (data-only).
4. Do not claim the linker stacks NX. SP_EL0 / SP_EL1 / fatal stacks sit in the executable image. Overflow there is still not a translation fault (ADR-005).
5. Fail-closed probe: walk PXN on kernel text (clear) and heap (set), then write RET on the heap, blr to it, and catch a current-EL permission instruction abort. Serial wx: nx heap + wx: ok. scripts/qemu-smoke.sh greps wx: ok and rejects wx: probe missed.
6. NFR-10 text is revised in place (ID unchanged): heap + coop-stack NX is the scoped W^X claim, not “the kernel is W^X.”

Consequences

• src/paging.rs grows L2_RAM and a kernel L3 pool (one table per mixed 2 MiB). Identity VA == PA is unchanged.
• Linker-stack guard pages are ADR-014. The RO+NX text/data split and SCTLR.WXN are ADR-015.
• EL0 isolation is ADR-013 (Planned). UXN is already set on RAM so a future EL0 cannot fetch kernel or heap by accident; that is not an EL0 probe.
• This ADR does not claim a secure OS, Raspberry Pi, or side-channel resistance.

ADR-013 — EL0 isolation direction (first mile)

• Status: Accepted (direction + first mile + user-TTBR0 read mile + ASID isolation mile + standing EL0; umbrella isolation still Planned)
• Follow-on (2026-09-28, M6): B3 met: the sponsor accepted the ADR-091 revision-3 sentence and scope in writing (2026-09-28 16:41 CEST). ADR-091 is Accepted. “EL0 isolated” is Verified only as that sentence, with its limits. Text in this ADR that says the umbrella is Planned / non-claim is as of this ADR’s date.
• Date: 2026-09-10
• Updated: 2026-09-11 (standing EL0 dual-SVC; TTBR1 first cut is ADR-016; isolation still Planned)

Context

Vision and FR-11 leave userspace / EL0 as later work. NFR-10 names EL0 isolation as Planned. ADR-011 and the threat model (security.md) treat “malicious EL0” as a named adversary, not a standing userspace.

The first revision of this ADR recorded direction only (is_active() == false, lower-EL slots parked). The post-#18 deepen implements the smallest honest mile toward the closing probe. It does not invent a POSIX process model.

Decision

1. First mile (this tree). Deliberate ERET to EL0t (DAIF masked) on one map-window page that is UXN-clear and PXN (EL1 must not fetch it). Two paths:
   • SVC #0 taken on the lower-EL AArch64 sync slot; handler prints el0: svc and ERETs back to EL1t.
   • BR X0 to a kernel .data bait; UXN on the identity image must take a lower-EL permission IABORT; handler prints el0: nx kernel and returns to EL1t. Serial el0: ok after the first-mile pair and the later miles on this path. The first mile itself does not install a standing context.
2. Closing probe for “cannot execute kernel data.” The UXN / translation IABORT is that instruction-fetch probe. Mark that mile Verified when the serial / #[test_case] pass.
3. User TTBR0 window (this tree, post-#19). A second L1 (L1_USER) is installed on ERET to EL0 (ASID=1 in TTBR0[63:48]). It maps kernel .text/.rodata and the exception stack so the lower-EL handler can restore kernel TTBR0 (kept in TPIDR_EL1), plus the shared map-window L2 for the trampoline. Coverage is every 2 MiB that holds those ranges, not only the first RAM 2 MiB. It omits .data / .bss / heap. An EL0 LDR from kernel .data is a lower-EL translation (or permission) DABORT (el0: no kernel read). Historically the EL0 trampoline still TLBI VMALLE1 because kernel .data leaves were global (nG=0); dropping that flush while identity .data stayed mapped would leak a cached .data translation into the user ASID. After ADR-037 / ADR-038, ADR-039 drops trampoline VMALLE1 (el0: no-vmalle1). Programming ASID=1 on that path is still not the isolation mile.
4. ASID isolation mile (this tree). Two EL1 TTBR0 values (kernel L1 + ASID 1 vs a clone L1 + ASID 2) map one window VA to different PAs with nG=1, and a second VA only under ASID 1. The switch is MSR TTBR0 + ISB — no TLBI VMALLE1. Dual read must see the active ASID’s magic (asid: dual). The ASID-1-only VA must take a current-EL translation DABORT under ASID 2 (asid: conflict). Seeing ASID 1’s magic under ASID 2 is Failed (asid: stale). This is TLB ASID isolation on this virt guest, not “EL0 isolated.”
5. Standing EL0 (this tree). A bounded user context on the user TTBR0: SVC #1 prints el0: standing and ERETs back to EL0; the user MOVZ must run; SVC #2 prints el0: restored and returns to EL1t. is_active() is true only between install and teardown (saved user PC / SP / TTBR0). A trampoline-only flag is not this mile. Lower-EL IRQ / FIQ / SError still park (not exercised). Not a POSIX process. Not preemption.
6. Isolation remains Planned. Missing: PAN enable (typically unimplemented on -cpu cortex-a57 / ARMv8.0 — ADR-026 reads ID_AA64MMFR1_EL1.PAN and records absent; do not silent -cpu switch), full TTBR1 / higher-half identity teardown (ADR-016 is the private-page cut; ADR-017 is the EL1-fetch cut; ADR-018 is the first identity-tear cut; ADR-019 jumps the post-MMU continuation high and unmaps a 16 KiB dedicated text range; ADR-020 rewrites rustc vtables and unmaps live identity .text; ADR-025 unmaps identity .rodata; ADR-037 / ADR-038 unmap .data/stacks/heap — leftover identity frames / _start stay), EL0 entry without a full TLBI (superseded by ADR-039). A documented SVC ABI is ADR-021 (not isolation, not app hosting). The libctos CRT is ADR-022 (not isolation, not app hosting). Do not move FR IDs. Do not mint FR-16+. Do not claim PAN.
7. Lower-EL slots. AArch64 sync is live for SVC / IABORT / DABORT (including standing dual-SVC, the public ABI numbers 16–18, and the TTBR1 private-page load). Lower-EL IRQ / FIQ / SError and all AArch32 slots stay parks (ADR-004).
8. Honesty. Docs and PRs may say “EL0 entered and returned,” “EL0 cannot execute kernel data,” “EL0 cannot read kernel .data,” “user TTBR0 omits kernel data,” “standing EL0 context,” or “ASID isolation” when those probes pass. The TTBR1 private-page mile is ADR-016. The EL1 high-VA fetch mile is ADR-017. The identity-tear first cut is ADR-018. The identity .text range tear is ADR-019. The live .text tear after a high-VA vtable rewrite is ADR-020. The SVC ABI mile is ADR-021. The libctos CRT mile is ADR-022. The guest ELF loader mile is ADR-023. Standing EL0 as normal mode (loaded task until exit, fail-closed restore) is ADR-024. The identity .rodata tear is ADR-025. The PAN ID-field probe is ADR-026. They may not say “EL0 works,” “userspace,” “EL0 isolated,” “app hosting,” or “the kernel moved.”

Consequences

• el0.md splits first-mile vs isolation rows.
• Preemption and SMP remain separate later ADRs (ADR-010).
• This ADR does not claim Raspberry Pi or a POSIX process model.

ADR-014 — Unmapped guard pages under linker stacks

• Status: Accepted
• Date: 2026-09-10

Context

ADR-012 made the heap and heap-backed cooperative stacks PXN. It explicitly left SP_EL0 / SP_EL1 / fatal stacks in the executable kernel image and named stack guard pages as a later ADR. ADR-005 still mitigates overflow with a dedicated fatal stack and a nested-BRK probe — that is not a translation fault.

A downward overflow of a linker stack today smashes the previous image bytes (.bss or the stack above). QEMU virt will not notice.

Options:

1. Unmapped 4 KiB guard page(s) below each linker stack. Overflow becomes a current-EL data abort (translation). Observable serial + #[test_case].
2. PXN on stack pages after splitting them from text. Stops execute-from-stack; overflow still smashes mapped data unless we also unmap something.
3. SCTLR_EL1.WXN — still unusable while kernel text pages are writable.

Decision

1. Option 1. Insert a 4 KiB linker hole below the thread, exception, and fatal stacks (__stack_guard, __exc_stack_guard, __fatal_stack_guard). After fill_ram_wx, split any 2 MiB L2 block that contains a guard into L3 and clear that L3 slot (invalid). Identity VA == PA is unchanged.
2. Fail-closed probe: arm a current-EL translation data-abort catch, store to the thread-stack guard, resume at LR. Serial guard: fault + guard: ok. scripts/qemu-smoke.sh greps guard: ok and rejects guard: probe missed.
3. Guard pages are holes, not NX stacks. This ADR does not by itself make live stack pages NX. ADR-015 maps those live pages RW+NX with .data. Do not claim “the kernel is W^X” from guard holes alone.
4. NFR-10 text is revised in place (ID unchanged): mention the guard-page overflow cut. Do not mint NFR-15+.
5. The ADR-005 nested-BRK fatal probe stays. It does not write below __stack_bottom.

Consequences

• src/paging.rs may add one or two extra L3 tables to split an executable L2 block that is not the __kernel_end straddle.
• Overflow of a heap-backed cooperative stack is still not this probe (those stacks live in PXN frame-pool RAM with no guard holes).
• This ADR does not claim a secure OS, Raspberry Pi, or ASAN-quality stack checking.

ADR-015 — RO+NX text / data split

• Status: Accepted
• Date: 2026-09-11

Context

ADR-012 made the heap and heap-backed cooperative stacks PXN. ADR-014 punched unmapped holes under the linker stacks. Both left .text / .rodata / .data / .bss / live linker-stack pages in one executable, writable image mapping. SCTLR_EL1.WXN was unusable while text was writable.

NFR-10 still forbids saying “the kernel is W^X” without a scoped probe. This ADR is the next cut: split RO+X from RW+NX.

Decision

1. Page-align __data_start in linker.ld so .text/.rodata never share a 4 KiB page with .data.
2. Identity flags (still 39-bit / 4 KiB / TTBR0):
   • [KERNEL_TEXT, __data_start) — RO+X (AP[2]=1, PXN clear, UXN set)
   • [__data_start, RAM end) — RW+NX (including .data, .bss, live linker stacks, frame pool / heap)
   • Device L1 stays XN. Guard holes stay invalid (ADR-014).
3. SCTLR_EL1.WXN on once text is RO. Writable pages are treated as XN even if a descriptor forgets PXN.
4. Fail-closed probe: execute-from-.data (blr to a RET bait) is a current-EL permission IABORT (ro: nx data). Store to RO text is a current-EL permission DABORT (ro: write fault). Serial ro: ok. scripts/qemu-smoke.sh greps those strings and rejects ro: probe missed. #[test_case] covers flags + both faults.
5. NFR-10 text is revised in place (ID unchanged): mention the RO+NX image cut. Do not mint NFR-15+.
6. One L3 per mixed 2 MiB (2026-09-11 follow-up). ADR-012 assumed a single L3 for the 2 MiB that straddles __kernel_end. After this ADR the mixed block is the one that contains __data_start and the first RAM 2 MiB that contains KERNEL_TEXT (0x4008_0000). Those are different blocks once .text/.rodata (or a linker ratchet) crosses 0x4020_0000. Reusing one L3_RAM overwrites the kernel-text walk. The kernel L3 pool hands out a fresh table per straddle / guard split. The user TTBR0 maps every 2 MiB that holds text or the exception stack, not only the first RAM block.
7. Post-MMU .bss publishes (same follow-up). USER_MAP_OK and frame::init run after SCTLR.C. A pre-MMU store to .bss can be invisible to a later cached read (boot-delta on the PR #20 test image; arm64 workstation Docker hello on b2bbb99 lost the frame pool / user-map ready flag while guard/ro still passed). Do not pin an old nightly for this.

Honesty — is this “the kernel is W^X”?

On this QEMU virt guest, the identity image plus heap is W^X: text/rodata are RO+X, data/bss/live linker stacks/heap are RW+NX, WXN is on. That is not:

• a “secure OS” / “hardened” claim
• a promise that every future mapping (DMA, new windows) stays W^X
• Raspberry Pi or a second ISA
• a reason to drop the heap / guard probes

Say “identity image is W^X on this virt guest (ADR-015 probe)” only when the serial / tests pass. Do not say “the kernel is W^X” as a product sentence.

Consequences

• src/paging.rs sets AP[2] on text and PXN on data/stacks. src/ro.rs owns the two faults.
• Live linker stacks are NX here. If a later change must execute from a linker stack, this ADR is the one to revisit.
• EL0 user TTBR0 (ADR-013 mile) still maps kernel text so the lower-EL handler can restore kernel TTBR0; it omits .data. Coverage follows the image across L2 blocks. That is isolation-adjacent, not this ADR.
• linker.ld parks __data_start at 0x4020_1000 so GHA / Docker / this cloud always exercise two kernel L3s. File presence of that address is not a boot probe.
• This ADR does not claim PAN, ASID isolation, or a higher-half kernel.

ADR-016 — TTBR1 kernel-private page (first cut)

• Status: Accepted (first cut; identity teardown Planned)
• Date: 2026-09-11

Context

ADR-013 left TTBR1 / higher-half as a missing isolation mile. The kernel still runs from the QEMU virt identity map at 0x4008_0000 (TTBR0, T0SZ=25). TCR.EPD1 was set, so TTBR1 walks were disabled. EL0 and EL1 share the same translation regime: a high mapping is not automatically invisible to EL0 — access is an AP / UXN question.

A full higher-half relocate (kernel fetch, VBAR_EL1, stacks, UART MMIO, then tearing down the identity image) is too large for one honest PR. This ADR is the smallest Verified cut: enable TTBR1 and prove one kernel-private high page.

Decision

1. Enable TTBR1 walks. Clear TCR.EPD1. Set T1SZ=25 (same 39-bit window as T0SZ) with WBWA / inner-shareable attrs on TTBR1. ASID still comes from TTBR0 (TCR.A1 = 0).
2. High-half base. The TTBR1 region is 0xFFFF_FF80_0000_0000…0xFFFF_FFFF_FFFF_FFFF. One private page lives at TTBR1_PRIV = 0xFFFF_FF80_0000_0000 (src/paging.rs).
3. EL1-only leaf. The page is Normal, RW, PXN, UXN, AP[2:1]=00 (EL1 RW, EL0 no data access). Backing store is a frame-pool page, also identity-mapped for EL1. User TTBR0 does not describe this VA.
4. Fail-closed probe. EL1 store/load via the high VA prints ttbr1: el1. An EL0 LDR of TTBR1_PRIV is a lower-EL permission (or translation) DABORT (ttbr1: no el0). Serial ttbr1: ok. scripts/qemu-smoke.sh greps those strings and rejects ttbr1: probe missed / ttbr1: leaked. #[test_case] covers the same path.
5. Identity map stays. _start, vectors, linker stacks, PL011 0x0900_0000, and the multi-L3 / layout ratchets from #21 keep using TTBR0 identity VAs. Full higher-half + identity teardown is Planned.
6. NFR-10 text is revised in place (ID unchanged). Do not mint NFR-15+. Do not claim “the kernel runs in the high half” or “EL0 isolated.”

Honesty

Say “TTBR1 maps a kernel-private page EL0 cannot access” only when the serial / tests pass. Do not say:

• the kernel has moved to a high VA
• identity mappings were torn down
• “secure OS” / “hardened” / “EL0 isolated”
• PAN (still unclaimed on -cpu cortex-a57)

Consequences

• paging::init programs TTBR1_EL1 and leaves EPD1 clear. src/ttbr1.rs owns the probe.
• Standing EL0 (ADR-013) is a separate mile. Umbrella isolation stays Planned while PAN is unclaimed.
• ADR-017 aliases identity RAM in TTBR1 and fetches a real EL1 path (plus high VBAR_EL1). ADR-018 splits those tables and unmaps one identity text page. ADR-019 unmaps a 16 KiB dedicated text range after a high-VA jump. ADR-020 unmaps live identity .text after a vtable rewrite. Full identity teardown (.rodata/.data/heap) is still Planned.

ADR-017 — EL1 fetch from the TTBR1 RAM alias

• Status: Accepted (exec mile; first identity-tear cut is ADR-018)
• Date: 2026-09-11

Context

ADR-016 enabled TTBR1 walks and proved one EL1-only data page at TTBR1_PRIV. The kernel still fetched instructions from the QEMU virt identity map at 0x4008_0000. Full higher-half relocate (every pointer, every fn item, then tearing down identity) is still too large for one honest PR: rustc emits link-time identity addresses (relocation-model: static), and -kernel loads _start at TEXT_OFFSET.

This ADR is the largest Verified cut that still keeps the boot stub: alias identity RAM in TTBR1 and run a real EL1 code path (instruction fetch, not a private store) at high VA.

Decision

1. RAM alias. L1_HIGH[1] points at the same L2_RAM used by identity TTBR0. High VA is identity + TTBR1_BASE (0x4008_0000 → 0xFFFF_FF80_4008_0000). Permissions match the identity image (text RO+X, data/stacks/heap RW+NX, guards unmapped).
2. Shared tables (superseded for the tear mile). This ADR reused L2_RAM. ADR-018 clones RAM tables so one identity text page can be unmapped without dropping the high twin. Full identity teardown is still Planned.
3. EL1 exec probe. ttbr1_high_el1_path is invoked through its high VA (BLR / fn pointer). It captures PC with ADR, prints ttbr1: el1 exec from that path, and returns the PC. The caller checks PC is in the TTBR1 window and near the high entry. UART MMIO stays the absolute identity 0x0900_0000.
4. VBAR_EL1 high. After the MMU is on, VBAR_EL1 is programmed to the high alias of exception_vectors (ttbr1: vbar). Later BRK / IRQ / EL0 sync fetch the table via TTBR1. Identity exception::init still installs the link address first (pre-MMU).
5. Identity boot stub stays. _start, QEMU -kernel load, and link-time fn items remain at 0x4008_0000. Most EL1 data access still uses identity VAs. Do not say the kernel moved.
6. Still Planned. Full identity teardown (unmap all low .text/.data/heap after a complete high-VA jump); PAN on -cpu cortex-a57; umbrella EL0 isolation. ADR-018 is the first cut (one torn text page). User TTBR0 still maps most kernel text so a missed high-VBAR path can fetch. Do not change default -cpu.
7. NFR-10 text is revised in place (ID unchanged). Do not mint NFR-15+.
8. ADRP is not a PA. After VBAR is high, handler code that does addr_of!(table) / user_ttbr0() must mask to the 39-bit identity VA before programming TTBR0 or comparing FAR_EL1. First attempts Failed: guard FAR compared to a high __stack_guard, then standing stay_at_el0 programmed a high L1_USER as TTBR0. paging::identity_pa / linker_sym are the ratchet.

Honesty

Say “EL1 fetched a real path from a TTBR1 high VA” or “VBAR lives at the high alias” only when the serial / tests pass. Do not say:

• the kernel has moved to the high half
• identity mappings were torn down
• “secure OS” / “hardened” / “EL0 isolated”
• PAN (still unclaimed on -cpu cortex-a57)

Consequences

• paging::init installs the RAM alias and relocates VBAR. src/ttbr1.rs owns both the private-page probe and the exec probe.
• ADR-016 remains the private-page first cut. This ADR is the exec mile.
• ADR-018 splits TTBR1 RAM tables and unmaps one identity text page. ADR-019 jumps the post-MMU continuation to high VA and unmaps a 16 KiB dedicated text range. ADR-020 unmaps live identity .text after a vtable rewrite. Unmapping .rodata/.data/heap is still later.

ADR-018 — Identity teardown first cut (split tables + one torn text page)

• Status: Accepted (partial tear; full identity teardown still Planned)
• Date: 2026-09-11

Context

ADR-017 proved EL1 can fetch a real path from the TTBR1 RAM alias and moved VBAR_EL1 there. The alias reused identity L2_RAM, so unmapping a low page also dropped the high twin. _start / QEMU -kernel still load at 0x4008_0000. rustc emits link-time identity addresses (relocation-model: static), so a complete high-VA jump of kernel_main plus unmap of all identity .text/.data/heap is still too large for one honest PR.

This ADR is the largest Verified cut that still boots on virt: split the RAM tables, then unmap one defined identity text page that EL1 no longer needs for fetch.

Decision

1. Split RAM tables. After identity W^X + stack guards, clone L2_RAM (and every L3 it points at) into L2_HIGH_RAM / L3_HIGH_RAM. L1_HIGH[1] points at the clone. L2 block descriptors are copied; L3 tables are duplicated. Unmapping an identity page no longer unmaps the high twin.
2. Dedicated tear page. The linker keeps a 4 KiB ident_tear section (__ident_tear_start … __ident_tear_end) in the RO+X image, after .rodata and before __data_start. It is not the 0x4008_0000 _start page.
3. Unmap after MMU + high VBAR. paging::init turns the MMU on, programs the high VBAR, then clears the identity and user-TTBR0 L3 slots for that page and TLBI VAAE1s the low VA. The high twin stays PXN-clear.
4. Fail-closed probe. Serial ident: split (clone + torn low / live high walks). EL1 BLR of the low VA is a current-EL translation IABORT (ident: fault). EL1 BLR of the high twin still runs ident_tear_el1_path (ident: high). EL0 LDR of the low VA is a lower-EL translation DABORT (ident: no el0). Serial ident: ok. scripts/qemu-smoke.sh greps those strings and rejects ident: probe missed / ident: leaked.
5. Identity boot stub stays. _start, QEMU -kernel load, remaining identity .text/.data/heap, PL011 0x0900_0000, and later probes keep using TTBR0 identity VAs. Do not say the kernel moved.
6. Still Planned. Full identity teardown (unmap all low .text/.data/heap after a complete high-VA jump); PAN on -cpu cortex-a57; umbrella EL0 isolation. Do not change default -cpu.
7. NFR-10 text is revised in place (ID unchanged). Do not mint NFR-15+.

Honesty

Say “TTBR1 RAM tables are independent of identity” or “one identity text page was unmapped while EL1 still fetched the high twin” only when the serial / tests pass. Do not say:

• the kernel has moved to the high half
• identity mappings were fully torn down
• “secure OS” / “hardened” / “EL0 isolated”
• PAN (still unclaimed on -cpu cortex-a57)

Consequences

• paging::init clones RAM tables and unmaps __ident_tear_*. src/teardown.rs owns the serial probe.
• ADR-017 remains the exec mile. This ADR is the first identity-teardown cut.
• ADR-019 jumps the post-MMU continuation to high VA and expands the dedicated tear to 16 KiB. ADR-020 rewrites rustc vtables and unmaps live identity .text. .rodata/.data/heap stay.

ADR-019 — High-VA continuation + dedicated identity text range

• Status: Accepted (partial tear; live .text / .rodata / .data / heap still identity-mapped)
• Date: 2026-09-11

Context

ADR-018 cloned TTBR1 RAM tables and unmapped one dedicated identity text page. rustc still emits link-time identity addresses (relocation-model: static). _start / QEMU -kernel still load at 0x4008_0000.

The preferred next cut was to unmap contiguous live identity .text after the boot stub once EL1 fetched from the high alias. A first attempt on this cloud VM Failed: after unmapping [0x4008_1000, __text_end), the first writeln! / println! took an unhandled current-EL sync. core::fmt::write takes &mut dyn Write; those vtable methods are identity fn pointers. Unmapping live .text is therefore blocked until fmt / dyn dispatch is proven high-only.

This ADR is the largest Verified cut that still boots: jump the post-MMU continuation to its TTBR1 alias, then unmap a 16 KiB dedicated identity text range (four pages), not one probe page.

Decision

1. High-VA continuation. After paging::init (MMU on, high VBAR_EL1, ADR-018 first tear page), kernel_main BRs to the TTBR1 alias of kernel_main_high. Serial ident: jump. Direct BL stays in the high window (PC-relative). UART MMIO stays the absolute identity 0x0900_0000. Stacks / heap / .data stay identity VAs.
2. Boot stub stays mapped. The 0x4008_0000 page (_start + exception_vectors) stays identity-mapped. Live .text after that page also stays — rustc fmt / dyn still needs those identity fn pointers.
3. Dedicated 16 KiB tear range. Linker __ident_tear_start … __ident_tear_end is four pages: page 0 holds ident_tear_el1_path (ADR-018), page 1 holds ident_range_el1_path, pages 2–3 are aligned pad. After the high jump, unmap the whole range from kernel and user TTBR0 and TLBI VAAE1 each low VA. High twins stay PXN-clear.
4. Keep live .text / .rodata / .data identity-mapped. Do not yank them here. A botched full .text yank is worse than a smaller Verified slice.
5. Identity fn pointers used after the jump go high where we control them (scheduler trampoline / task entries; custom test runner dyn Testable method). That is preparation, not a claim that rustc fmt is high-only.
6. Fail-closed probe. Serial ident: jump. ident: range lo=… hi=… pages=N with N >= 4. Existing ident: split / fault / high / no el0 / ok stay. ident: text is EL1 fetch of the second torn page via the high twin. scripts/qemu-smoke.sh greps those strings and rejects ident: probe missed / ident: leaked / ident: range missed.
7. Identity boot stub stays. _start, QEMU -kernel load, live identity .text/.rodata/.data/heap, PL011 0x0900_0000. Do not say the kernel moved.
8. Still Planned. Unmap live identity .text after fmt / dyn calls are proven high-only; then .rodata/.data/heap; PAN on -cpu cortex-a57; umbrella EL0 isolation. Do not change default -cpu.
9. NFR-10 text is revised in place (ID unchanged). Do not mint NFR-15+.

Honesty

Say “the post-MMU continuation ran at a high VA” or “a 16 KiB dedicated identity text range was unmapped while EL1 still fetched the high twins” only when the serial / tests pass. Do not say:

• the kernel has moved to the high half
• identity .text after _start was fully torn down
• identity mappings were fully torn down
• “secure OS” / “hardened” / “EL0 isolated”
• PAN (still unclaimed on -cpu cortex-a57)

Consequences

• paging::jump_high / tear_identity_text_range own the cut. src/teardown.rs extends the serial probe.
• ADR-018 remains the split-tables + first dedicated page cut.
• ADR-020 rewrites rustc vtables to high aliases and unmaps live identity .text after the boot stub. .rodata / .data / heap stay.

ADR-020 — High-VA fn-pointer rewrite + live identity .text tear

• Status: Accepted (live .text after the boot stub; .rodata / .data / heap still identity-mapped)
• Date: 2026-09-11

Context

ADR-019 jumps the post-MMU continuation to its TTBR1 alias and unmaps a 16 KiB dedicated identity text range. A first attempt to unmap live .text after _start Failed: the first writeln! / println! took an unhandled current-EL sync.

This ADR investigates that failure and takes the largest honest Verified cut toward tearing live identity .text.

Probed root cause (this cloud VM, main 24d94e6 hello ELF, then this branch):

• rustc dyn Write vtables live in .rodata. The Pl011 table is drop=0 / size=8 / align=8 / write_str / write_char / write_fmt with identity method addresses (write_char at 0x4008_1084, immediately after the vectors page).
• The hello .rodata held a handful of other identity .text words (Debug::fmt, PadAdapter as Write). .data had none. .text had no 8-byte identity literal pools.
• AArch64 codegen used ADRP (PC-relative), not MOVZ/MOVK of 0x4008. After the high-VA jump, new fn() values are already high; tables linked as R_AARCH64_ABS64 stay identity until rewritten. The ELF is ET_EXEC / relocation-model: static — no leftover reloc records to apply.
• .text and .rodata shared page 0x400a4000 on the ADR-019 layout (vtable at 0x400a4338). Unmapping “all of .text” without a page split would also drop the vtable.

relocation-model: pic was considered and not taken: static + a post-jump patcher matches the existing -kernel / 0x4008_0000 contract and does not need a dynamic linker.

Decision

1. Page-split .text / .rodata. Linker __text_end / __rodata_start are 4 KiB aligned so live .text and fmt tables do not share a page.
2. High-VA fn-pointer rewrite. After ident: jump, walk .rodata (through __ident_tear_start) and .data. Every 8-byte word that is an identity address in .text or __ident_tear_* is rewritten to its TTBR1 alias. RO pages are made writable only for that store, then restored (SCTLR.WXN makes a writable page XN — they are not fetched). Serial ident: reloc n=N with N >= 1. A Pl011 as dyn Write fat-pointer read must see a high write_str.
3. Live identity .text tear. Unmap [0x4008_1000, __text_end) from kernel and user TTBR0 (TLBI VAAE1 each low VA). High twins stay PXN-clear. The 0x4008_0000 page (_start + exception_vectors) stays identity-mapped. Serial ident: live lo=… hi=… pages=N with N >= 8.
4. Keep .rodata / .data / heap identity-mapped. String literals and rewritten vtables still live there. Do not yank them here.
5. Keep _start / QEMU -kernel at 0x4008_0000. Do not change default -cpu. Do not claim PAN.
6. Fail-closed probe. Existing ident: jump / range / split / fault / high / text / no el0 / ok stay. New ident: reloc / ident: live. scripts/qemu-smoke.sh greps those strings and rejects ident: reloc missed / ident: live missed. #[test_case] covers the rewrite and the live unmap.
7. Still Planned (this ADR). Unmap identity .rodata / .data / heap after those accesses are proven high-only; PAN on -cpu cortex-a57; umbrella EL0 isolation. ADR-025 takes the .rodata cut. ADR-026 probes the PAN ID field (enable stays Planned).
8. NFR-10 text is revised in place (ID unchanged). Do not mint NFR-15+.

Honesty

Say “rustc vtable / fn-pointer words were rewritten to high aliases” or “live identity .text after the boot stub was unmapped while println! still ran” only when the serial / tests pass. Do not say:

• the kernel has moved to the high half
• identity mappings were fully torn down (.rodata / .data / heap stay)
• “secure OS” / “hardened” / “EL0 isolated”
• PAN (still unclaimed on -cpu cortex-a57)

Consequences

• paging::rewrite_identity_fn_ptrs / paging::tear_live_identity_text own the cut. ADR-019 remains the high-VA jump + dedicated 16 KiB range.
• A later ADR may unmap .rodata once string / table accesses are high-only, then .data / heap. That work is not this cut.

ADR-021 — Minimal EL0 SVC syscall ABI

• Status: Accepted (ABI mile Verified when the serial / tests pass; Track A / app hosting still Planned)
• Date: 2026-09-11

Context

Track A (issue #31) wants freestanding apps to call the kernel. Issue #32 is the first mile: a documented, probed SVC contract.

ADR-013 already takes lower-EL AArch64 SVC for probe immediates #0 (first-mile return), #1 (standing announce), and #2 (standing restore). Those numbers stay reserved. This ADR adds a tiny public set so a later CRT / libctos (A2) has numbers to call. It does not load ELF, host apps, or claim Linux/POSIX.

Options:

1. Linux AArch64 (svc #0, x8 = number). Collides with the first-mile SVC #0 probe and invites a Linux-ABI claim.
2. SVC immediate is the number, public set starts at 16. Leaves 0–2 for ADR-013 probes. Arguments in x0–x2, return in x0.
3. Wait for a loader. Would block Track A on A3.

Decision

1. Calling convention. AArch64 SVC #<n> where n is the syscall number. Arguments in x0, x1, x2. Return value in x0. DAIF stays masked on the existing EL0 path. Not Linux. Not POSIX.

2. Reserved 0–2. Probe-only (ADR-013). Not part of the public ABI. A later CRT must not issue them.

3. Public numbers (this tree).

   Number	Name	Args	Effect	Return
   16	exit	x0 = status (recorded; not a process model)	End the EL0 trip; ERET to the EL1 caller	(does not return to EL0)
   17	uart_write	x0 = user pointer, x1 = length	Copy up to 64 bytes from a user-mapped and kernel-mapped range; write to PL011 (\n → \r\n, same as the kernel console)	bytes written, or 0 if rejected
   18	yield	none	Record the call; ERET back to EL0 (next insn)	0

4. yield is dispatch-only. It does not call sched::yield_now (ADR-010: that switch is EL1-only and must not run from an exception frame). A later ADR may connect the two.

5. uart_write is fail-closed. Length 0 or > 64, overflow, a non-canonical or TTBR1 alias, or a range that is not user-mapped or not kernel-mapped returns 0 and writes nothing. Kernel .data is rejected. Table walks mask to 39 bits — the pointer itself must already be a TTBR0 identity VA, or copy_user would load a tagged address. This is not a VFS.

6. Unknown immediates stay unhandled (park). Do not silently succeed.

7. Fail-closed probe. Hello serial svc: yield + user buffer svc: user-hi + svc: uart + svc: exit + svc: ok. scripts/qemu-smoke.sh greps those and rejects svc: probe missed. #[test_case] covers the success trip, a kernel-.data reject, and a TTBR1-alias reject. Existing el0: markers stay.

8. Honesty. Say “EL0 issued the documented SVC ABI and the kernel performed the documented effect” only when the serial / tests pass. Do not say: app hosting is done, Linux ABI, POSIX, userspace, “EL0 isolated,” or “secure OS.” Standing-as-normal is ADR-024. Thin VFS numbers 19–23 are ADR-027. Track A A7–A9 stay Planned.

9. NFR-10 text is revised in place (ID unchanged) to name this ABI mile. Do not mint FR-16+ or NFR-15+.

Consequences

• Code: src/syscall.rs. Dispatch is hooked from handle_sync_lower_el after the ADR-013 probe immediates.
• Docs: syscall.md, el0.md. Roadmap cites #32 / Track A #31.
• A2 (libctos) wraps these three numbers (ADR-022). A3 (loader) is not that PR.

ADR-022 — Freestanding CRT / libctos

• Status: Accepted (CRT mile Verified when the serial / tests pass; Track A / app hosting still Planned)
• Date: 2026-09-12

Context

Track A (issue #31) wants a freestanding program to call the A1 ABI without glibc or POSIX. Issue #33 is this mile: a documented, probed CRT + libctos that wraps ADR-021 numbers 16–18.

A1 already proved the kernel performs exit / uart_write / yield for a hand-encoded trampoline. That is not a library a program can link. A3 (ELF loader) must not start until something exists to link against.

Options:

1. Wait for a loader. Would block A2 on A3.
2. C/asm static lib only. Fine later; this tree is Rust-first and already uses aarch64-ctos.
3. no_std crate + asm stubs + a hello payload copied onto today’s standing EL0 page. Proves link + run without a guest ELF loader.

Decision

1. libctos crate (libctos/). no_std wrappers exit / uart_write / yield_now over asm stubs (sys.S: ctos_exit / ctos_uart_write / ctos_yield). SVC immediates are 16 / 17 / 18. Reserved 0–2 stay ADR-013 probes — the CRT must not issue them.
2. CRT is _start in libctos/src/crt0.S: kernel ERET already set SP_EL0; _start calls main, then ctos_exit. No argv, no environ, no libc init. Not glibc/musl crt0.
3. Hello payload (user/hello-libctos). A no_std / no_main program links libctos, prints libctos: hi via uart_write, yields, prints libctos: ok, returns 0. Linked at paging::EL0_PAGE (0x80002000) with user/hello-libctos/linker.ld.
4. Not a guest loader. build.rs compiles that program on the host and extracts PT_LOAD bytes at/after EL0_PAGE (size metadata + publish). The kernel copies a flatten of FAT /hello onto the standing EL0 page and ERETs — same style as A1. Host flatten in build.rs is not A3. Guest flatten of the FAT ELF (ADR-032) is still A2 memcpy, not the A3 map.
5. Code page + stack page. The image must fit in 3584 bytes on EL0_PAGE (EL0-exec, no EL0 data — same AP as A1). Rust main saves x30 on SP; that store cannot land on the code page (SCTLR.WXN forbids making it W+X). A second map-window page is EL0-RW NX. rust-lld’s extra ELF-header PT_LOAD at 0x80000000 is discarded at extract time.
6. Fail-closed probe. Hello serial libctos: hi + libctos: ok (from the payload via uart_write) + kernel libctos: linked. scripts/qemu-smoke.sh greps those and rejects libctos: probe missed. #[test_case] covers the trip and that the blob encodes SVC #16/#17/#18 and not #0/#1/#2. Existing svc: / el0: markers stay.
7. Honesty. Say “a program linked against libctos issued the A1 ABI and the kernel performed the documented effect” only when the serial / tests pass. Do not say: app hosting is done, Linux ABI, POSIX, userspace, “EL0 isolated,” or “secure OS.” Track A A3–A9 stay Planned.
8. NFR-10 text is revised in place (ID unchanged) to name this CRT mile. Do not mint FR-16+ or NFR-15+. Guest ELF load is ADR-023, not this ADR.

Consequences

• Code: libctos/, user/hello-libctos/, build.rs, src/libctos.rs.
• Docs: syscall.md, el0.md, building-or-porting.md. Roadmap cites #33 / Track A #31.
• A3 (ELF / raw loader into user TTBR0) may load a separate image. It is not this PR.

ADR-023 — Guest ELF64 PT_LOAD loader into user TTBR0

• Status: Accepted (loader mile Verified when the serial / tests pass; Track A / app hosting still Planned)
• Date: 2026-09-12

Context

Track A (issue #31) wants a freestanding image loaded into user maps and entered with ERET. Issue #34 is this mile.

ADR-022 already links user/hello-libctos against libctos. That hello is host-built. build.rs extracts PT_LOAD and the kernel memcpys the blob onto paging::EL0_PAGE. That is not a guest loader.

A3 must parse and map on the guest. The bytes may still be embedded (no VFS yet — A6/A7). The point is map + load + ERET, not host flatten-and-copy onto a fixed probe page alone.

Existing A1 svc:* and A2 libctos:* markers stay. A4–A9 stay out of this PR.

Hypotheses

Decision

1. Guest parser in src/loader.rs. Accept ELF64 little-endian AArch64 ET_EXEC. Walk program headers. Load PT_LOAD only. Ignore PT_PHDR / PT_GNU_STACK / notes. Reject PT_INTERP. Reject a PT_LOAD that is W+X (segment flags or two segments that union to W+X on one page). SCTLR.WXN is already on (ADR-015); do not map a writable executable leaf.
2. User TTBR0 maps. Each page of a PT_LOAD is a freshly allocated frame mapped in the shared map-window L3 (paging::MAP_WINDOW … + MAP_WINDOW_SIZE). That L3 is already in L1_USER, so EL0 and EL1 both see it. Permissions: PF_X → map_el0_exec (EL0 fetch, no EL0 data; EL1 may write the identity PA before / while mapping); PF_W → map_el0_rw; R-only → map_el0_ro. Page-granular union: .text RX and .rodata R on one 4 KiB page become Exec. Not a new user address space.
3. Copy + BSS. File bytes are written to the frame’s identity PA. p_memsz > p_filesz is zeroed. I-cache is synced on executable pages. e_entry must land in an Exec page.
4. Stack. A separate EL0-RW NX page at paging::LOADER_STACK_VA (0x80007000), not the A2 code page. Rust main still saves x30 on SP_EL0.
5. Image source. First cut embedded the ELF (include_bytes!). ADR-032 reads the same bytes from FAT /hello. build.rs still compiles and publishes target/hello-libctos.elf. Not a second QEMU -kernel.
6. ERET. el0::install_standing(e_entry, stack_top, user_ttbr0) then exception::eret_to_el0. SYS_EXIT returns to EL1 as today. A2’s memcpy path stays so libctos:* markers remain.
7. Fail-closed probe. Hello serial loader: mapped + loader: ok after a successful trip. The loaded payload still prints libctos: hi / libctos: ok via uart_write. scripts/qemu-smoke.sh greps those and rejects loader: probe missed. #[test_case] covers parse, PT_INTERP reject, W+X reject (flags and overlapping pages), RX+R union on the hello page, and the full map + ERET trip. Existing svc: / libctos: / el0: markers stay.
8. Honesty. Say “the guest parsed a freestanding ELF64, mapped PT_LOAD into user TTBR0, and ERETed to e_entry” only when the serial / tests pass. Do not say: Linux ELF ABI, PT_INTERP, glibc, app hosting is done, POSIX, userspace, “EL0 isolated,” or “secure OS.” Standing-as-normal is ADR-024. Track A A5–A9 stay Planned.
9. NFR-10 text is revised in place (ID unchanged) to name this loader mile. Do not mint FR-16+ or NFR-15+.

Consequences

• Code: src/loader.rs, paging::map_el0_ro / window_range_ok / LOADER_STACK_VA, build.rs emits the ELF, scripts/qemu-smoke.sh.
• Docs: el0.md, syscall.md, building-or-porting.md. Roadmap cites #34 / Track A #31.
• A4 (standing EL0 as normal mode) keeps this loader as the way a payload appears (ADR-024).

ADR-024 — Standing EL0 as normal mode

• Status: Accepted (standing-task mile Verified when the serial / tests pass; Track A / app hosting still Planned)
• Date: 2026-09-12

Context

Track A (issue #31) wants a loaded freestanding image to run at EL0, not only enter and leave. Issue #35 is this mile.

ADR-013 already has a bounded standing context: SVC #1 stays at EL0, a user MOVZ runs, SVC #2 restores EL1. is_active() is true only for that lifetime. That is a smoke probe, not the supported path for a loaded app.

ADR-021 / ADR-022 / ADR-023 already ERET to a payload and come back on SYS_EXIT. They reuse install_standing as a flag. A leftover is_active() after ERET fails the probe. That is still a one-shot trip, not “standing EL0 is how a loaded image runs.”

A4 keeps the A3 loader as the way a payload appears. It does not add VFS, slots, PAN, or a Linux exec. Existing svc:* / libctos:* / loader:* / el0: standing / el0: restored markers stay.

Hypotheses

Decision

1. Two standing kinds. install_standing remains the ADR-013 / A1–A3 probe (dual-SVC or ABI trampoline). install_task is the A4 task. is_active() is true for both. is_task() is true only for a task. Saved user PC / SP / TTBR0 live only while is_active().
2. Supported path. The A3 guest ELF loader maps PT_LOAD from FAT /hello (ADR-032), then install_task(e_entry, stack_top, user_ttbr0) and ERET. The loaded image runs at EL0 until SYS_EXIT. SYS_YIELD / SYS_UART_WRITE stay at EL0 and must observe is_active() (el0: task-active). A2’s memcpy path stays so libctos:* markers remain (same FAT file; no embed).
3. Fail-closed restore. SYS_EXIT on a task prints el0: task-exit / el0: task-restored and clears is_active(). An unexpected lower-EL sync (unhandled SVC, translation/permission abort, and anything that would otherwise park) while a task is standing prints el0: restore-fail, clears is_active(), and returns to the EL1 caller. It does not park. Probe standing still parks on unexpected sync (A1–A3 unchanged). After ERET returns, leftover is_active() is Failed (caller force-clears and fails the probe).
4. Fail-closed probe. Hello serial el0: task-enter + el0: task-active + el0: task-exit + el0: task-restored + el0: restore-fail + el0: task-ok. scripts/qemu-smoke.sh greps those and rejects el0: task missed. #[test_case] covers the loaded-hello task trip and the fault-restore trip. Existing svc: / libctos: / loader: / el0: standing / el0: restored markers stay.
5. Honesty. Say “a loaded freestanding image stood at EL0 until exit, and an unexpected fault restored fail-closed” only when the serial / tests pass. Do not say: app hosting is done, POSIX, userspace, “EL0 isolated,” Linux exec, or “secure OS.” Track A A5–A9 stay Planned.
6. NFR-10 text is revised in place (ID unchanged) to name this standing-task mile. Do not mint FR-16+ or NFR-15+.

Consequences

• Code: src/el0.rs (install_task, restore_exit, restore_fault), src/loader.rs (run_hello_as_task), src/exception.rs (task restore instead of park), src/syscall.rs (note_active_while_standing), scripts/qemu-smoke.sh.
• Docs: el0.md, syscall.md, track-a.md. Roadmap cites #35 / Track A #31.
• A5 (isolation completion — remaining identity .rodata / .data / heap tear; PAN only if the probe CPU implements it and an ADR says so) is not this PR.

ADR-025 — Identity .rodata tear after pointer rewrite

• Status: Accepted (identity .rodata unmapped; .data / heap still identity-mapped)
• Date: 2026-09-12

Context

Track A / A5 (issue #36, parent #31) continues identity teardown where safe. ADR-020 rewrote rustc vtables and unmapped live identity .text after the boot stub. .rodata / .data / heap stayed mapped: string literals and rewritten tables still lived there.

After the ADR-019 high-VA jump, new PC-relative accesses (ADRP) already reach the TTBR1 alias. R_AARCH64_ABS64 words that point at .rodata stay identity until rewritten — the same class as the ADR-020 fn-pointer tables.

.data / .bss / linker stacks / heap are not safe to unmap here. SP is still the identity __stack_top. GlobalAlloc still returns identity frame VAs. Those stay Planned.

Hypotheses

Decision

1. Rewrite identity .rodata pointers. After the live .text tear, walk .rodata and .data. Every 8-byte word that is an identity address in [__rodata_start, __ident_tear_start) is rewritten to its TTBR1 alias. RO pages are writable only for that store, then restored. Serial ident: ro-reloc n=N. N == 0 is allowed (no ABS64 hits); the tear still has to prove high-only access.
2. Unmap identity .rodata. Unmap [__rodata_start, __ident_tear_start) from kernel and user TTBR0 (TLBI VAAE1 each low VA). High twins stay. Serial ident: rodata lo=… hi=… pages=N with N >= 1.
3. Keep .data / heap / linker stacks identity-mapped. SP and the first-fit heap still use those VAs. Do not yank them here.
4. Keep _start / QEMU -kernel at 0x4008_0000. Do not change default -cpu. Do not claim PAN.
5. Fail-closed probe. Existing ident:* markers stay. New ident: ro-reloc / ident: rodata / ident: rodata-fault / ident: rodata-high. EL1 LDR of a torn identity .rodata VA is a current-EL translation DABORT. EL1 LDR of the high twin still returns a known .rodata magic. scripts/qemu-smoke.sh greps those strings and rejects ident: rodata missed / ident: ro-reloc missed. #[test_case] covers the unmap.
6. Still Planned (at accept time). Identity .data / heap tear. Superseded in part by ADR-037 (.data/stacks) and ADR-038 (heap). PAN enable on -cpu cortex-a57; EL0 entry without TLBI VMALLE1; lower-EL IRQ while standing; umbrella EL0 isolation.
7. NFR-10 text is revised in place (ID unchanged). Do not mint NFR-15+.

Honesty

Say “identity .rodata was unmapped while println! still ran from the high twin” only when the serial / tests pass. Do not say:

• the kernel has moved to the high half
• identity mappings were fully torn down (.data / heap stay)
• “secure OS” / “hardened” / “EL0 isolated”
• PAN (see ADR-026; unimplemented on -cpu cortex-a57)

Consequences

• paging::rewrite_identity_rodata_ptrs / paging::tear_identity_rodata own the cut. ADR-020 remains the live .text tear.
• A later ADR may relocate SP and return high heap VAs, then unmap identity .data / heap. That work is not this cut.

ADR-026 — PAN capability: probe the ID field, do not invent the CPU

• Status: Accepted (capability probe). Historical a57: pan: absent. Default smoke CPU since ADR-079: -cpu cortex-a76 → pan: present. PAN enable + EL1-vs-EL0 fault: ADR-080 (ADR-054 gate items 3–4).
• Date: 2026-09-12

Context

Track A / A5 (issue #36) may take Privileged Access Never only if ID_AA64MMFR1_EL1.PAN != 0 on the probe CPU and an ADR says so. The documented QEMU line is -cpu cortex-a57 (ARMv8.0). PAN is typically unimplemented there. Silently switching -cpu (for example to max) to make the field non-zero is not an honest probe.

ADR-013 already named PAN as a closing isolation probe: an EL1 access to an EL0-accessible page must fault when PSTATE.PAN is set. That enable + fault mile is not this ADR.

Hypotheses

Decision

1. Probe the ID field. src/pan.rs reads ID_AA64MMFR1_EL1 bits [23:20] and prints pan: id=<n>. It does not execute MSR PAN. An unimplemented MSR PAN is UNDEF on ARMv8.0.
2. Default CPU at accept time was cortex-a57. Superseded for the default probe by ADR-079 (-cpu cortex-a76). Do not silent-edit without an ADR.
3. When n == 0 (expected). Serial pan: absent. Ledger: “PAN enable on virt cortex-a57” stays Planned, with this ID-field print as the CPU evidence. scripts/qemu-smoke.sh greps pan: id= / pan: absent and rejects pan: enabled / pan: probe missed.
4. When n != 0. Serial pan: present. ADR-080 enables PSTATE.PAN and proves EL1-vs-EL0 fault. Smoke expects pan: present + pan: enabled + pan: el1-fault on -cpu cortex-a76.
5. Still Planned. PAN enable + EL1-vs-EL0 access fault; lower-EL IRQ while standing; EL0 entry without TLBI VMALLE1; umbrella EL0 isolation. ADR-032 re-states that leftover: do not MSR PAN while the ID field is 0. ADR-025 is the identity .rodata cut, not this.
6. NFR-10 text is revised in place (ID unchanged). Do not mint NFR-15+.

Honesty

Say “ID_AA64MMFR1_EL1.PAN is 0 on -cpu cortex-a57” only when the serial / tests pass. Do not say:

• PAN is enabled
• EL1 cannot access EL0 pages
• “secure OS” / “hardened” / “EL0 isolated”
• the probe used a different -cpu than the scripts

Consequences

• src/pan.rs owns the ID-field probe. Isolation docs cite this ADR as Planned for the enable mile.
• ADR-047 records: PAN enable is a non-goal on the default probe CPU; ID-field probe stays Verified.
• A future CPU change needs its own ADR + sponsor and must not be a silent script edit.
• Enable lock: ADR-054 (2026-09-14) locks PAN enable as non-goal on default cortex-a57 and documents the reopen gate (sponsor CPU + FEAT_PAN + enable+fault ADR).

ADR-027 — Thin VFS + in-RAM memfs

• Status: Accepted (memfs mile Verified when the serial / tests pass; Track A / app hosting still Planned)
• Date: 2026-09-12

Context

Track A (issue #31) wants a freestanding app to read and write named buffers. Issue #37 is this mile: a thin VFS with one backend, an in-RAM memfs, plus a fail-closed create / write / read / close probe.

ADR-021 already has exit / uart_write / yield (16–18). There is no path, no handle, and no store. A later virtio-blk + on-disk FS (A7 / issue #38) must not invent a second “open” story. The VFS ADR lands first.

This is not Linux VFS. Not POSIX open / stat / mount. Not a disk. Not app hosting.

Hypotheses

Decision

1. Thin VFS. src/vfs.rs defines VfsOps: create / open / read / write / close on a path + handle. One global backend this mile: MemFs. Later A7 may add a block FS behind the same trait. Not a superblock. Not a dentry cache.

2. memfs. Flat namespace. Paths are / plus 1–15 bytes of [a-z0-9_-] (no extra /, no .). At most 8 files, 256 bytes each, 4 handles. File bytes live on the first-fit heap (Vec<u8>, ADR-009). Handles are 1..=4. Offset is per handle. create fails if the name exists. open fails if missing. write stores at the handle offset and grows up to FILE_MAX. read copies from the offset. close drops the handle; the file stays. Not a directory tree.

3. Public SVC numbers (extends ADR-021). Same calling convention (SVC #<n>, x0–x2, return x0). Reserved 0–2 stay ADR-013 probes.

   Number	Name	Args	Effect	Return
   19	fs_create	x0 = user path, x1 = length	Create an empty named file and a handle	fd >= 1, or 0
   20	fs_open	x0 = user path, x1 = length	Open an existing name	fd >= 1, or 0
   21	fs_read	x0 = fd, x1 = user buf, x2 = length	Copy from the handle offset into a user-mapped and kernel-mapped range	bytes, or u64::MAX on reject (0 is a valid empty read)
   22	fs_write	x0 = fd, x1 = user buf, x2 = length	Copy into the file at the handle offset	bytes, or 0
   23	fs_close	x0 = fd	Drop the handle	0 on success, u64::MAX on reject

   Path / I/O length is capped (path 16, I/O 64). Fail-closed: empty length, overflow, non-canonical / TTBR1 alias, or a range that is not user-mapped or not kernel-mapped returns the reject value and does not mutate the file. Kernel .data is rejected. Unknown immediates still park.

4. libctos wrappers. fs_create / fs_open / fs_read / fs_write / fs_close over svc #19–#23. The A2 hello payload stays exit / uart_write / yield only so A2–A4 markers do not change.

5. Fail-closed probe. Kernel create / write / read / close of /kprobe prints fs: create / fs: write / fs: read. An EL0 trampoline does the same for /eprobe and prints fs: el0. Then fs: ok. scripts/qemu-smoke.sh greps those and rejects fs: probe missed. #[test_case] covers the kernel round-trip, a missing open, the EL0 trip, and a kernel-.data write reject. Existing svc: / libctos: / loader: / el0: task-* / A5 ident: rodata* / pan:* markers stay.

6. Honesty. Say “the guest created, wrote, and read a named in-RAM file behind a thin VFS” only when the serial / tests pass. Do not say: app hosting is done, POSIX, Linux VFS, FAT, virtio-blk, on-disk FS, userspace, “EL0 isolated,” or “secure OS.” Track A A7–A9 stay Planned.

7. NFR-10 text is revised in place (ID unchanged) to name this memfs mile. Do not mint FR-16+ or NFR-15+.

Consequences

• Code: src/vfs.rs, src/syscall.rs (19–23), libctos/ wrappers, scripts/qemu-smoke.sh.
• Docs: filesystem.md, overview/filesystem.md, syscall.md, track-a.md. Roadmap cites #37 / Track A #31.
• A7 (virtio-blk + FAT or xv6-like on that block device) is not this PR. Choose the on-disk format in that ADR.

ADR-028 — virtio-blk + FAT16 behind the thin VFS

• Status: Accepted (block + FAT read mile Verified when the serial / tests pass; Track A / app hosting still Planned). Write depth: ADR-050.
• Date: 2026-09-12

Context

Track A (issue #31) wants a freestanding app to read a named file on a disk, not only an in-RAM buffer. Issue #38 is this mile: QEMU virt virtio-mmio block (virtqueues, DMA, sector R/W) plus one on-disk FS, mounted through the A6 thin VFS (ADR-027).

Host QEMU -drive without guest code is not a probe. memfs stays one backend. This mile must not invent a second open story. Not POSIX. Not ext4. Not app hosting. A8–A9 stay Planned.

Hypotheses

Decision

1. On-disk format is FAT16. Chosen because the smoke host can build and inspect a raw image without a ctos-specific decoder. xv6-like and FAT32 stay unchosen. Do not say “supports FAT” as a product; say “the guest read a known FAT16 file from a virtio-blk image.”
2. virtio-mmio on QEMU virt. Scan transports at 0x0a000000 + n×0x200 (32 slots) for Device ID 2. QEMU 8.2 virt ships legacy version 1 on those transports (page-aligned QueuePFN); modern version 2 is also accepted. One split virtqueue. DMA addresses are identity PAs of a 4 KiB-aligned .bss buffer (.data/heap stay identity-mapped; ADR-025). Poll used.idx after QueueNotify. Cache maintenance (dc civac) covers the whole DMA object (desc/avail and used/req/status/data) — a page-0-only sync leaves a stale request on write-back D-cache. No virtio IRQ this mile. Device MMIO already sits in the Device-nGnRnE L1 block.
3. Thin VFS, two backends. vfs::open / read / write / close stay the only story. memfs is tried first. If the name is missing there, FAT16 root (8.3, no extension → /probe for PROBE) is tried. create stays memfs and fails with Exists if FAT already has the name. FAT write / create return ReadOnly. Same path grammar as A6. No extra /. No new SVC numbers.
4. Host image. scripts/mkfat16.py writes a 4 MiB raw FAT16 volume (cluster count ≥ 4085 so the type is FAT16, not FAT12) with one file PROBE / contents fat-hi. scripts/qemu-smoke.sh, scripts/qemu-aarch64.sh, and scripts/qemu-serial-inject.py attach it as: -drive if=none,file=<img>,format=raw,id=hd0 -device virtio-blk-device,drive=hd0
5. Fail-closed probe. virtio capacity + last-sector write/read prints blk: virtio / blk: cap / blk: rw / blk: ok. VFS open/read of /probe prints fat: mount / fat: read / fat: ok. scripts/qemu-smoke.sh greps those and rejects blk: probe missed / fat: probe missed. Host --check of the image is extra, not a substitute for the guest. #[test_case] covers sector R/W, VFS /probe, and a missing FAT name. Existing svc:* / libctos:* / loader:* / el0: task-* / ident:* / pan:* / fs:* markers stay.
6. Honesty. Say “the guest programmed virtio-blk and read a known FAT16 file through the thin VFS” only when the serial / tests pass. First hello on a modern-only (Version==2) scan was blk: probe missed — QEMU 8.2 virt exposes legacy version 1. After accepting v1 + QueuePFN, this cloud VM printed blk: ok and fat: ok. Do not say: app hosting is done, POSIX, Linux VFS, FAT32, xv6, writeable volumes, virtio-net, “EL0 isolated,” or “secure OS.” Track A A8–A9 stay Planned. Host -drive without guest virtio + VFS read is not a probe.
7. NFR-10 text is revised in place (ID unchanged) to name this virtio-blk + FAT16 mile. Do not mint FR-16+ or NFR-15+.

Consequences

• Code: src/virtio.rs, src/fat.rs, src/vfs.rs (dispatch + ReadOnly), scripts/mkfat16.py, QEMU -drive in the smoke / runner scripts.
• Docs: filesystem.md, overview/filesystem.md, track-a.md, threat-model v1.15. Roadmap cites #38 / Track A #31.
• A8 (documented sample apps, issue #39) is not this PR. Follow-up A8 documented rebuild recipes (what-can-run.md); it did not add a new libctos hello that calls fs_open. The Verified EL0 VFS trip stays /eprobe. Not a new ABI and not a second FS.

ADR-029 — Guest OCI/Docker containers are a non-goal

• Status: Accepted (docs decision; no guest runtime)
• Date: 2026-09-12

Context

Track B (issue #40) is Linux-compat research. Child B7 / #47 asks for an explicit claim: ctos does not host Docker/OCI; today Docker on a Linux host runs the ctos smoke image.

Site pages already said no (hosting-apps.md, extra host-apps.md). Track B still listed B7 as Planned and said containers “stay out or far-later.” That is an honesty gap: far-later reads like a later Planned feature.

OCI / Docker / Kubernetes guests need a Linux host: namespaces, cgroups, a Linux ABI, usually overlay or equivalent, and a rich syscall surface. This learning kernel does not have those. Host docker-smoke.sh is a harness (NFR-04 / NFR-05), not a guest runtime.

This ADR does not implement a container runtime. It does not mint FR-16+ or NFR-15+. B1 (Linux-compat goals) may cite it and must not reopen containers as Planned.

Decision

1. Non-goal. The ctos guest is not a container host. OCI / Docker / Kubernetes workloads on the guest are not Planned. Do not write a container roadmap on Track B.
2. Arrow today. Docker (or Podman) on a Linux host may build and QEMU-smoke this kernel. That is “Docker hosts ctos,” not “ctos hosts containers.” Ledger Docker rows stay host-harness probes.
3. Reopen gate. Far-later only with a new GitHub epic plus a new ADR that names the missing Linux-host features and a probe. Track B B1–B6 must not treat containers as a win or a silent Planned row. Do not mint a new FR/NFR ID for this.
4. Principles drive. Honesty (NFR-06): absence of OCI/runc/cgroup/namespace code in src/ is the probe. Antifragility keeps the host Docker ratchet. Security / performance claims about “container isolation” stay unwritten.

Consequences

• Docs: track-b.md B7 becomes Documented. Site SoT: hosting-apps.md. Extra: host-apps.md. Ledger row stays Verified absence + non-goal.
• Track A A8 (sample apps) is unrelated. Do not add an in-tree “container” sample.
• “Run Alpine on ctos” / “k8s node” stays the same class of claim as “POSIX port is easy.” It is not.

ADR-030 — OS image vs app payload slots

• Status: Accepted (first-cut two-artifact + FAT load path). Cross-update is ADR-032 (same published ELF on this OS and ba6541c).
• Date: 2026-09-12

Context

Track A (issue #31) wants a freestanding app that is not rebuilt every time the kernel is. Issue #48 is this mile: disconnect OS image updates from app payloads.

The sponsor goal is scoped immutability, not an “immutable OS” product sentence (immutability.md). A1–A8 already landed ABI, libctos, a guest PT_LOAD loader, standing EL0, memfs, virtio-blk + FAT16, and sample recipes. Today the hello ELF is still include_bytes! into the kernel. That is one linked image.

This mile must not invent OTA, A-B flash, or OCI containers (ADR-029). No new FR/NFR IDs.

Hypotheses

Decision

1. Slots. The OS image is the kernel ELF QEMU -kernels (target/aarch64-ctos/debug/ctos). The app payload is a separate host ELF (target/hello-libctos.elf) built from user/hello-libctos. The guest app slot is FAT16 /hello (8.3 HELLO) on the existing virtio-blk volume. /probe stays the A7 known file. Same VFS open / read / close. No new SVC numbers.
2. Build. build.rs compiles the hello and publishes the ELF to target/hello-libctos.elf (and still writes host flatten metadata). After ADR-032 the kernel does not include_bytes! that file. scripts/mkfat16.py --app writes that ELF as /hello (cluster chain; cap 64 KiB). Smoke and the QEMU runner fail closed if the app artifact is missing.
3. Boot/load. Hello path: OS boots, A1–A8 probes run. After ADR-032, A2–A4 also read FAT /hello (no include_bytes!). Then A9 reads /hello through the thin VFS, parses ELF64 PT_LOAD with the A3 loader, and ERETs. No embed fallback on this path. Missing /hello prints slot: probe missed.
4. Fail-closed probe. Serial slot: fat + slot: mapped + slot: ok after a successful FAT load + ERET. perf: app-load ticks=<n> is a CNTPCT measurement around that path (NFR-07) — not a bench and not a delta vs the embed. scripts/qemu-smoke.sh greps those and rejects slot: probe missed / slot: embed. Host smoke requires both artifacts and mkfat16.py --check --require-app. #[test_case] covers FAT /hello ELF magic + parse + the FAT load trip.
5. Honesty. Say “the guest loaded a separate app ELF from the FAT slot into user TTBR0” only when the serial / tests pass. Do not say: apps update independently of the OS, immutable OS, OTA, A-B, containers, “EL0 isolated,” or “secure OS.” Cross-update is a host two-boot probe (ADR-032): same published hello-libctos.elf on this OS and on ba6541c. File presence of this ADR is not that probe. A kernel rebuild still compiles the payload (build.rs); it no longer embeds the bytes.
6. Performance. Expected costs stay the documented shape (boot/load, SVC, ASID/TTBR). The new marker proves the path is measurable. A compared CNTPCT pair vs a probe-only linked-in trip is ADR-046. Do not invent a bench.
7. NFR-10 text is revised in place (ID unchanged) to name this slot first cut. Do not mint FR-16+ or NFR-15+.

Consequences

• Code: src/slot.rs, src/loader.rs (run_image), build.rs publish path, scripts/mkfat16.py --app, QEMU runner / smoke.
• Docs: immutability.md, advantages.md, track-a.md, threat-model v1.16. Roadmap cites #48 / Track A #31.
• Track A children A1–A9 now have a first cut. ADR-032 takes cross-update + embed-off + isolation honesty. Slot-load CNTPCT pair is ADR-046 (Verified measurement, not a percent). Remaining Planned / decided: PAN enable non-goal on default a57, never yank _start, leftover identity RAM optional, umbrella isolation Planned/non-claim (ADR-047); product “app hosting is done” (ADR-048).

ADR-031 — Linux-compat goals, non-goals, keep ctos specificity

• Status: Accepted (docs frame; no Linux userspace claim)
• Date: 2026-09-12

Context

Track B (issue #40) is Linux-compat research. Child B1 / #41 asks for the frame: what “Linux-compat” means here (ABI subset vs a full Linux kernel), what stays out, and which ctos invariants must not move.

B7 / ADR-029 already records that guest OCI / Docker / Kubernetes is a non-goal. This ADR cites that decision. It does not reopen containers as Planned or “far-later on this track.”

Track A (issue #31) has first cuts A1–A9: a tiny SVC ABI (ADR-021), libctos (ADR-022), a freestanding ELF64 PT_LOAD loader that rejects PT_INTERP (ADR-023), standing EL0 (ADR-024), thin VFS + memfs (ADR-027), virtio-blk + FAT16 (ADR-028), sample recipes, and an OS/app slot first cut (ADR-030). Those miles are freestanding. They are not a Linux ABI and not Linux userspace.

Issue #40’s reality check stands: a full Linux ABI (and containers) is a multi-year kernel project. Track B is an ADR / research ladder, not a promise to become Linux.

This ADR does not implement B2–B6. It does not mint FR-16+ or NFR-15+. File presence of this page is not a Linux userspace probe.

Hypotheses

Decision

1. What Linux-compat means. On ctos it means: research whether a subset of the Linux AArch64 ABI could ever be useful for a named, probed workload, without dropping ctos specificity. It is not a promise to run a Linux distro, glibc, musl, a shell, Python, or “Linux userspace.” Full Linux ABI is out of scope for this track’s promise. B6 may later choose “never.”

2. Goals (research ladder only). Later children stay document-first. This PR does not write them.

   Later	Job	Must not do in that child
   B2 (#42)	Map Linux aarch64 syscalls vs today’s ctos SVC (16–23 + reserved 0–2)	Do not add Linux syscall numbers to src/
   B3 (#43, ADR-035)	Process model vs Linux fork / exec / wait	Do not add those syscalls. Standing EL0 stays the ctos model.
   B4 (#44)	Linux ELF / auxv / PT_INTERP vs the freestanding loader	Do not accept PT_INTERP. Gap ADR: ADR-033.
   B5 (#45)	Linux VFS concepts vs the thin ctos VFS	Do not grow POSIX open flags / dentries
   B6 (#46)	Decision: compat layer vs reimplement vs never	Do not treat “compat layer” as already chosen

   Implementation, if any, comes after B6 names a path, in a later epic, with a probe. “Never” is a valid B6 outcome.

3. Non-goals.

   • Full Linux ABI / POSIX product / glibc or musl ports.
   • Guest OCI / Docker / Kubernetes — already ADR-029. Not Planned on Track B.
   • “Run Alpine on ctos,” “k8s node,” “Linux userspace works.”
   • Replacing the freestanding Track A path (A1–A9 first cuts stay).
   • Widening off QEMU virt / AArch64 without a new ISA ADR (ADR-003).
   • New FR/NFR IDs. Frozen set stays fr-nfr.md.
   • Author self-merge (ADR-002).

4. Keep (ctos specificity). Track B is subordinate to principles.md. Linux-compat research must not override:

   Invariant	Why it stays
   Honesty (NFR-06 / ADR-001)	Status words need a probe. Unprobed stays Unknown. This ADR is not Verified Linux.
   Antifragility (NFR-05)	Fail-closed qemu-smoke and host Docker/arm64 workstation ratchets stay. Host docker-smoke.sh is still “Docker hosts ctos,” not a guest Linux ABI.
   Security (NFR-10)	No “secure OS,” “Linux-compat isolation,” or “the kernel is W^X” from a research frame.
   Performance (NFR-07)	No invented benches for a compat layer that does not exist. Measure first if a later mile adds a path.
   Document-first / one-PR loops	One child → one branch → one GitHub PR.
   Freestanding Track A path	In-tree apps keep SVC #n, libctos, PT_LOAD without interpreter, thin VFS. A research map must not silently retarget those numbers to Linux x8.
   Virt learning scope	QEMU virt + PL011 until an ADR widens it.
   ADR-gated memory / EL0	Isolation, PAN enable, remaining identity RAM / _start stay their own rows.

5. Relationship to ADR-029. Guest containers remain a non-goal. B1–B6 must not treat containers as a win, a silent Planned row, or a reason to grow namespaces / cgroups / overlay. Reopen only with a new GitHub epic plus a new ADR that names the missing Linux-host features and a probe. Do not mint an FR/NFR ID for that.

6. Not claiming Linux userspace yet. Say that sentence in the roadmap and on the Track B page. Today:

   • A3 maps freestanding ELF64 ET_EXEC PT_LOAD and rejects PT_INTERP.
   • Standing EL0 is not a Linux process table.
   • Thin VFS + memfs / read-only FAT16 is not Linux VFS.
   • A9 FAT /hello is not execve.
   • The ledger row “Guest runs host apps (Linux ELF / shell / Python)” stays Planned. This ADR does not change that row to Verified.

7. Principles drive. Do not override honesty, fail-closed sensors, or the three pillars for a “runs Linux” headline.

Consequences

• Docs: track-b.md B1 becomes Documented. SUMMARY.md and roadmap.md link here. Site extra: hosting-apps.md / host-apps.md point at the frame without a userspace claim.
• B2 is Documented (syscall gap note). B3 is Documented (ADR-035). B4 is Documented (ADR-033). B5 / B6 stay Planned research. No src/ change in this PR.
• Track A remains the product path for in-tree freestanding apps. Cross-update and “app hosting is done” stay unclaimed.
• Honesty: document inspection only. Do not add a Verified Linux-userspace ledger row because this file exists.

ADR-032 — Track A leftovers: cross-update, FAT-only hello, isolation honesty

• Status: Accepted (leftover mile when the serial / host smoke / tests pass)
• Date: 2026-09-12

Context

Track A children A1–A9 have first cuts. After ADR-030 merged on main ba6541c, three honesty gaps remained:

1. A9 cross-update. Same published hello-libctos.elf on this OS and a documented prior OS. ABI stability is not that probe.
2. Embed honesty. A2–A4 still include_bytes! a hello copy while A9 loaded FAT /hello. Dual path or remove the embed.
3. Isolation leftovers. After A5: identity .data / heap tear if safe; PAN enable only if ID_AA64MMFR1_EL1.PAN != 0 on default -cpu cortex-a57. Do not claim “EL0 isolated.”

No new FR/NFR IDs. Author does not merge (ADR-002). The number is 032 because open #62 already claimed ADR-031 for Linux-compat goals.

Hypotheses

Decision

1. Prior OS is ba6541c. That is the A9 merge commit (A9: Disconnect OS image from app payloads (ADR-030) (#60)). No earlier main SHA has the slot/FAT path. Do not store a prior kernel ELF in git. scripts/qemu-smoke.sh builds that commit in a git worktree and QEMU -kernels it with the same app bytes this tip published (sha256 pin via sha256sum, shasum -a 256, or openssl dgst -sha256). Docker smoke needs git in the image and .git objects in the build context (not host .git/worktrees registrations). Smoke prunes stale worktrees before add. Do not invent a stored kernel blob. Both boots must print slot: fat / slot: mapped / slot: ok and must not print slot: embed / slot: probe missed. This OS SHA must differ from ba6541c.
2. No hello embed. src/libctos.rs and src/loader.rs read FAT /hello through fat::read_file (same VFS open as A7). A2 still memcpy-flattens PT_LOAD at/after EL0_PAGE (not a guest ELF map). A3/A4 still parse and ERET. Size must match HELLO_ELF_LEN / HELLO_LEN from this build.rs so a swapped slot cannot silently satisfy those miles. Host smoke rejects include_bytes!.*hello-libctos under src/.
3. Isolation honesty. Serial ident: data-stay / ident: heap-stay after walking those identity pages. #[test_case] identity_data_and_heap_still_mapped. PAN enable stays Planned (pan: id=0 / pan: absent; smoke still rejects pan: enabled). Do not claim “EL0 isolated.”
4. Still Planned (at accept time). Identity .data / heap tear (needs SP relocate + high allocator VAs). Superseded in part by ADR-037 and ADR-038. PAN enable on -cpu cortex-a57; lower-EL IRQ while standing; EL0 entry without TLBI VMALLE1; umbrella isolation; A9 slot-disconnect delta vs the old embed (later ADR-046); product “app hosting is done.”
5. NFR-10 text is revised in place (ID unchanged). Threat-model v1.17. Do not mint FR-16+ or NFR-15+.

Honesty

Say “the same published hello-libctos.elf loaded on this OS and on ba6541c” only when host smoke printed both cross-update … slot:ok lines and the app sha256 pin. Say “A2–A4 no longer embed the hello” only when src/ has no hello include_bytes! and the FAT markers still pass. Say “identity .data / heap are still mapped” when ident: data-stay / ident: heap-stay print. Do not say:

• apps update independently / app hosting is done / OTA / A-B / containers
• EL0 isolated / PAN enabled / the kernel moved / identity mappings fully torn down
• a prior OS that does not exist in git
• Verified without this cloud (or GHA) qemu-smoke

Consequences

• ADR-037 supersedes the .data stay marker. ADR-038 supersedes ident: heap-stay with an honest heap tear (ident: heap-reloc / ident: heap).

• Code: fat::read_file, loader/libctos FAT path, teardown stay markers, scripts/qemu-smoke.sh embed + cross-update + stay greps.

• Docs: this ADR, ADR-030, A2–A4 ADRs (payload source), ADR-025 / ADR-026 (still Planned), ledger, Track A, threat-model v1.17.

ADR-033 — Linux ELF / auxv / PT_INTERP vs the freestanding loader

• Status: Accepted (gap ADR; no Linux ELF / dynamic-linker claim)
• Date: 2026-09-12

Context

Track B child B4 / #44 (parent #40) asks what would be needed to load a musl-linked binary versus today’s freestanding image, and to keep the Track A loader reusable.

Frame: ADR-031. That frame says B4 must not accept PT_INTERP, must not claim Linux userspace, and must not replace the freestanding Track A path. Syscall convention is already a gap (linux-aarch64-syscall-gap.md / B2). Process execve is B3 / #43. This ADR does not write B3, B5, or B6.

Track A A3 (ADR-023) already parses ELF64 little-endian AArch64 ET_EXEC, maps PT_LOAD only, rejects PT_INTERP, rejects W+X, and ERETs to e_entry. A2–A4 and A9 reuse that parser on FAT /hello (ADR-030, ADR-032). The in-tree payload is libctos, not musl or glibc.

This mile is docs only. It does not change src/loader.rs. File presence of this page is not a Linux ELF probe and not dynamic-linker support.

Probe (what Verified means here)

A later kernel qemu-smoke is a different row. This mile did not edit src/.

Hypotheses

Decision

1. What Linux exec of an ELF does (inspection). Linux fs/binfmt_elf.c (not copied here) loads ET_EXEC or ET_DYN (PIE). If a PT_INTERP string is present, it also maps that interpreter (typically glibc ld-linux-aarch64.so.1 or musl ld-musl-aarch64.so.1) and transfers control to the interpreter entry, not the binary e_entry. The kernel builds a user stack:

   argc → argv[] → NULL → envp[] → NULL → auxv[] (AT_* key/value pairs) → AT_NULL.

   The auxiliary vector (Linux v6.10 auxvec.h) is how the dynamic linker and libc CRT find program headers, page size, interpreter base, the real entry, and entropy. Typical keys a musl/glibc _start reads: AT_PHDR / AT_PHENT / AT_PHNUM, AT_PAGESZ, AT_BASE, AT_ENTRY, AT_UID/AT_EUID/AT_GID/AT_EGID, AT_SECURE, AT_RANDOM (16 bytes), AT_HWCAP / AT_HWCAP2, AT_CLKTCK, AT_PLATFORM, AT_EXECFN, often AT_SYSINFO_EHDR (vDSO) and AT_MINSIGSTKSZ.

   After that, the interpreter walks PT_DYNAMIC (DT_NEEDED, DT_SYMTAB, DT_RELA / DT_REL, DT_INIT_ARRAY), maps shared objects, applies relocations, sets up PT_TLS, then jumps to AT_ENTRY. That is dynamic linking. It is not PT_LOAD copy.

2. What the ctos loader does (inspection). src/loader.rs / ADR-023:

   Item	ctos today
   File type	ELF64 LE AArch64 ET_EXEC only (NotExec on anything else, including ET_DYN)
   Segments	PT_LOAD only. PT_PHDR / PT_GNU_STACK / notes ignored.
   PT_INTERP	ParseError::Interp. Fail-closed. Smoke/tests require the reject.
   W+X	Reject (segment flags or page-union). SCTLR.WXN is on (ADR-015).
   VA window	paging::MAP_WINDOW 0x8000_0000 … + MAP_WINDOW_SIZE (512 × 4 KiB). Caps: 8 PT_LOADs, 8 pages.
   Stack	One zeroed EL0-RW NX page at LOADER_STACK_VA (0x80007000). No argc / argv / envp / auxv.
   Entry	ERET to the binary e_entry. No interpreter.
   CRT	libctos wrappers + _start. Does not read auxv. Calls SVC #<n> (ADR-021).
   Image source	FAT /hello (A9 / ADR-032). Not execve.

   No Linux ELF feature in the gap table below is present. PT_LOAD of a freestanding ET_EXEC is partial (related map, different contract).

3. Status words (same idea as B2).

   Status	Means
   present	Same Linux ELF/auxv/PT_INTERP meaning, so a musl/glibc AArch64 binary could start with no translation.
   partial	Track A has a related PT_LOAD / stack / entry behavior. Type, stack, or control flow still differ.
   absent	No analog. B6 may still discuss a named subset. Not a promise to implement.
   stay-rejected	A3 fail-closed reject. This ADR does not flip it. Reopen only after B6 names a path, in a later epic.
   never-per-ADR-031	Would imply a Linux distro / glibc-musl product / guest interpreter that ADR-031 already ruled out as a Track B promise.

4. Gap table.

   Image type and program headers

   Linux / ELF item	ctos status	Notes
   ELF64 LE AArch64 magic	partial	Same header walk. Not a Linux ABI.
   ET_EXEC PT_LOAD map + BSS zero	partial	A3 does this inside the 2 MiB window, 8 segments / 8 pages.
   ET_DYN / PIE / loader-chosen base	absent	parse_elf64 returns NotExec. Linux PIE is ET_DYN.
   PT_INTERP	stay-rejected	A3 tests require Interp. ADR-031: do not accept it in this child.
   Load the interpreter ELF	absent	No second image, no AT_BASE.
   Transfer to interpreter entry	absent	ERET is always binary e_entry.
   PT_DYNAMIC / DT_NEEDED	absent	Ignored (not PT_LOAD). No shared-object search.
   Relocations (DT_RELA / REL / RELR / IFUNC)	absent	Freestanding image is already linked.
   PT_TLS / TPIDR_EL0	absent
   PT_GNU_STACK exec-stack	absent	Ignored. Stack is NX. A Linux exec-stack request would fight W^X.
   PT_GNU_RELRO	absent
   PT_PHDR usable at runtime	absent	No AT_PHDR. Headers are not guaranteed mapped at a libc-known VA.

   Stack and auxv (Linux v6.10 auxvec.h)

   Item	ctos status	Notes
   argc / argv[] / envp[]	absent	Stack page is zeros. libctos does not read SP.
   AT_NULL terminator + key/value pairs	absent
   AT_PHDR / AT_PHENT / AT_PHNUM	absent	musl/glibc ldso needs these.
   AT_PAGESZ	absent	Guest pages are 4 KiB; nothing publishes that to EL0.
   AT_BASE	absent	Interpreter load base.
   AT_ENTRY	absent	Real program entry after ldso init.
   AT_RANDOM (16 bytes)	absent	Typical stack canary / SSP. No getrandom either (B2).
   AT_UID / AT_EUID / AT_GID / AT_EGID / AT_SECURE	absent	No uid model.
   AT_HWCAP / AT_HWCAP2 / AT_PLATFORM	absent
   AT_EXECFN	absent	A9 path is FAT /hello, not a Linux pathname.
   AT_SYSINFO_EHDR (vDSO)	absent	No vDSO mapping.
   AT_MINSIGSTKSZ	absent	No POSIX signals (B2).

   musl-linked vs freestanding (the #44 question)

   Workload	What it still needs on ctos	Honesty
   In-tree libctos ET_EXEC	Already the A3/A9 path. Keep it.	Not Linux.
   Static musl (-static, often no PT_INTERP)	Linux stack + auxv; Linux svc #0/x8 (exit_group, set_tid_address, brk/mmap, write on fd 1 — B2); often ET_DYN static-PIE; VAs usually not in 0x8000_0000…+2 MiB; image larger than 8 pages.	Not a small subset. ADR-031 rejected “runs musl” as a promise.
   Dynamic musl (PT_INTERP → ld-musl-aarch64.so.1)	Everything static needs, plus accept PT_INTERP, load the interpreter, AT_BASE/AT_PHDR/AT_ENTRY, PT_DYNAMIC + DT_NEEDED files on a real FS, relocations, TLS.	stay-rejected + absent. Do not claim dynamic Linux ELF.
   glibc dynamic	Same class as dynamic musl, usually heavier (ld-linux, vDSO, more CRT syscalls).	Same non-claim.

5. Keep the Track A loader reusable. A2 flatten, A3 map+ERET, A4 standing task, and A9 FAT /hello all call parse_elf64 / run_image. This ADR does not widen that function. A later Linux ELF path — only if B6 / #46 chooses a compat layer, and only with a probe — would be a new module that may reuse page-map helpers. It must not silently retarget parse_elf64 to accept PT_INTERP or ET_DYN. Track A tests that reject Interp stay.

6. Not claiming dynamic Linux ELF support. Say that sentence on the Track B page. Today:

   • A3 maps freestanding ELF64 ET_EXEC PT_LOAD and rejects PT_INTERP.
   • The stack has no auxv.
   • ERET is not interpreter start.
   • A9 FAT /hello is not execve.
   • The ledger row “Guest runs host apps (Linux ELF / shell / Python)” stays Planned.

7. If a subset is ever useful (not a decision). Research hint for B6, not a backlog:

   1. In-tree libctos apps need no Linux ELF features. Keep ADR-023.
   2. Static musl is already a libc-shaped surface (B2) plus auxv/stack/ET_DYN/VA-window work. That is not a B4 implementation item.
   3. Dynamic musl/glibc starts with accepting PT_INTERP. This track’s frame forbids that in B4. B6 may choose never.
   4. Do not start with relocations, TLS, or a guest ld.so.

8. Non-goals. Full Linux ELF ABI; glibc/musl ports; accepting PT_INTERP in src/; rewriting Track A probes; guest containers (ADR-029); new FR/NFR IDs; author self-merge (ADR-002).