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.

I.2 — Task 2: version correction — the v2.0.1 bump and v2.0.0 tag were premature

Direct instruction, 2026-09-04: the LITHOS_VERSION bump to 2.0.1 (and the branch name that followed it) got ahead of the real state — per Makefile.starkernel's own versioning policy (v2.0.0 = QEMU release, even major/LTS; v2.0.1 = the SER5 hardware-track line, RDRAND backend + thumbdrive image goal), claiming 2.0.1 implies hardware-track progress that was never actually verified on real hardware — that verification is precisely FABRIC-3.md's whole open topic (§I.6 in the closed FABRIC-2.md). The current master HEAD is, correctly, still a v2.0.0-class QEMU-only release. "Nothing harmful" — a version-label correction, not a functional rollback.

Found and fixed while correcting this, not left half-done:

• A real gap in the FABRIC-series rename from earlier today: Makefile.starkernel, Kconfig.kernel, scripts/bleach_zuse_img.sh, four proof/*.thy files, and src/starkernel/arch/amd64/isr.S all still had stale FABRIC.md/FABRIC-2.md/FABRIC-3.md citations — the original sweep's file-list only matched --include=*.md/*.c/*.h/*.4th, which silently skipped every file without one of those four extensions. Found by re-grepping with the extensions excluded instead of included. Fixed with the same safe placeholder-substitution technique the original rename used (each file, one pass, ordered FABRIC-3→2→1→0 placeholders then resolved) — verified no double-shifted or broken references remained afterward. .claude/settings.local.json's own historical Bash-permission-grant log (literal past command strings naming the file as it was called at the time) was deliberately left alone — rewriting it would falsify an audit trail, not fix a stale citation.
• ClaudeEXPORT/memories.json/conversations.json also still reference the old names — left untouched on purpose, same reasoning as the memory note on that archive: it's a frozen export, mining material, not live documentation to keep in sync.

Changes:

1. Makefile.starkernel: LITHOS_VERSION ?= 2.0.1 → 2.0.0.
2. The rename-gap fix above (7 files).
3. Verified 3-arch boot (clean qemu, amd64/aarch64/riscv64, each in the foreground): all three show LithosAnanke v2.0.0 in the boot banner (confirmed directly in each serial log, not assumed from the Makefile edit alone), zero build errors, zero unexpected warnings, clean shutdown.
4. Moved the existing v2.0.0 git tag (previously at 2efd7fe, the original QEMU-release milestone commit — that commit and its own message stay fully intact in history, only the tag pointer moves) to the current master/v2.0.1-branch HEAD, per explicit instruction — the prior tag placement was itself part of the same "got ahead of myself" correction, not a separate decision. No remote tag existed yet (git ls-remote --tags origin was empty for v2.0.0), so no destructive remote operation was needed, only a local move-and-push.