LithosAnanake/FABRIC-3.md

FABRIC-3.md — bare metal boot

Status: Living working document, opened 2026-09-04 as the successor to FABRIC-2.md (now closed/archival — see its own header). Topic for this document, per direct instruction: bare metal boot — getting LithosAnanke to actually boot on real hardware, not just QEMU. FABRIC-2.md §I.6 (Milestone 8) already named this as the one item that pass couldn't close from a coding session at all, for exactly this reason — it needs a real machine and a human physically present. This document is where that work, and everything downstream of it, gets tracked.

How to use this document going forward. New findings, new punch-list items, and new decisions for bare-metal-boot work get added here, not to FABRIC-2.md. Same discipline every prior document in this series used: write the decision and its reasoning down before building, close items with a dated note citing real evidence, never silently drop a stale claim.

---

I.1 — Task 1: merge v2.0.1 into master, verify build/function equivalence

Written up before executing, per direct instruction and this series' own standing discipline.

Why this is task 1. FABRIC-2.md's entire 7-step closure pass (§I.1–§I.5, §I.7, plus today's FABRIC-series rename) happened on the v2.0.1 branch, not master. Before any real bare-metal-boot work starts, that work needs to land where .claude/CLAUDE.md says the project's sole production line actually lives: master. Doing this first, cleanly, before starting new work avoids ever having two divergent lines to reconcile later.

Investigated before writing this up, not assumed:

• git merge-base --is-ancestor master v2.0.1 — true. master (local HEAD d2a0305) is a strict ancestor of v2.0.1 (HEAD b031b80) — v2.0.1 is exactly master plus 47 commits forward, no divergent history on either side. This means the "merge" is a pure fast-forward, not a real three-way merge — nothing to resolve, no conflict possible.
• origin/master carries exactly one commit beyond local master (58c59e8, "Initial commit") that local master hadn't fetched yet — confirmed already contained in v2.0.1's own history (git merge-base --is-ancestor 58c59e8 v2.0.1 — true), so it introduces no discrepancy either.
• master's own tree still has the old FABRIC.md/FABRIC-2.md/FABRIC-3.md naming (unrenamed) — expected, since today's rename commit (b031b80) only exists on v2.0.1 so far. The fast-forward brings the rename to master along with everything else; nothing separate needs doing for it.

Plan:

1. Fast-forward master to v2.0.1's tip (git checkout master && git merge --ff-only v2.0.1) — refuses loudly instead of silently doing a real merge if the ancestor relationship somehow isn't what the investigation above found, so this step re-verifies its own precondition.
2. Push master to origin.
3. Verify build/function equivalence on a genuinely clean tree, not by inference: git clean (after confirming nothing untracked-but-wanted is present), then the full acceptance sequence .claude/CLAUDE.md already mandates for any kernel change — clean qemu on all three architectures, in the foreground, one at a time, each reaching ok> and shutting down cleanly. Since the tree is byte-identical to v2.0.1's post-fast-forward, this is expected to reproduce exactly what v2.0.1's own last acceptance pass already showed — the point of re-running it here is to confirm that expectation holds on master itself, not to assume it from the fast-forward alone.
4. Return to v2.0.1 as the working branch afterward (.claude/CLAUDE.md's own rule: always return to the correct working branch after any out-of-branch work), unless told otherwise.

DONE 2026-09-04, exactly as planned:

1. Committed the write-up above on v2.0.1 first (72c14cb), pushed. This became v2.0.1's new tip.
2. git checkout master && git merge --ff-only v2.0.1 — Fast-forward, d2a0305..72c14cb, confirming the investigated ancestor relationship held exactly as expected; no conflict, no merge commit.
3. git push origin master — origin/master moved 58c59e8..72c14cb.
4. Verified on a genuinely clean master tree, not inferred from the fast-forward:
   • Hosted build (make clean && make): clean compile, zero warnings, same as v2.0.1.
   • Full 3-arch kernel acceptance (clean qemu, amd64/aarch64/riscv64, each in the foreground): all three reached (zuse) ok>/ok> and shut down cleanly, zero build errors, zero unexpected warnings — identical outcome to v2.0.1's own last acceptance pass, confirmed directly rather than assumed. Logs: logs/20260904-113208/amd64/, logs/20260904-113320/aarch64/, logs/20260904-113552/riscv64/.
5. master and v2.0.1 are now identical (72c14cb on both, origin and local). Returned to v2.0.1 as the working branch per plan step 4.

Task 1 closed. master genuinely is the production line again, current through today's FABRIC-series rename and the full FABRIC-2.md §I closure. Bare-metal-boot work (this document's actual topic) starts from here.