Artemis Milestone 2e: virtual USB thumb-drive hotplug test + block-layout decisions

Verified live on amd64: booted with the xHCI controller present but no USB
device attached (no Port Status Change at ok>), then hotplug-attached a
virtual USB thumb drive via QMP (usb-storage on xhci0.0, backed by
disk/usb-thumbdrive-test.img) and got an immediate port status change
event -- the real connect trigger Milestone 2e's PORTSC handling will
consume next.

Confirmed blk_subsys_attach_device() (src/block_subsystem.c) is already
the correct integration point for USB -- it already appends a new device
to the end of the existing LBN chain, matching the intended design.
Documented the remaining gaps: no blkio_usb.c backend yet, no hot-detach
path in the device chain yet.

Decided the on-drive layout for USB thumb drives: GPT-partitioned (unlike
artemis.img's whole-device StarForth header), ~1GB metadata partition +
remainder for blocks, 16GB reference drive size, sizing tentative. No GPT
parser exists in kernel code yet -- new prerequisite work for Milestone
2h/3, not blocking current 2e work.

disk/usb-thumbdrive-test.img added as a tracked test fixture, per this
repo's standing convention that virtual disk/thumb-drive images used for
testing are committed, not left in scratchpad.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HZ8kNoTuP63pbQtro4qvrm

FABRIC-2.md

@@ -3271,12 +3271,46 @@ Closed that gap first as its own discriminating step:
       (today: attach-order-based, per Section V area A — item below in Milestone 3 changes
       this to identity-derived)
 
+**Confirmed with Captain Bob, 2026-08-22: `blk_subsys_attach_device()` is the right call, not
+`blk_subsys_add_raw_device()`.** Re-read the `block_subsystem.c` header comment
+(`src/block_subsystem.c:24-32`) during this discussion — it already documents the target
+architecture exactly: a unified LBN chain (RAM → RAMDRIVE → DISK IMG → "USB / future devices
+(chained, including hot-attach/detach)"), and `blk_subsys_attach_device()` already does the
+append-at-current-tail behavior verbatim (`slot->start_lbn = g.total_user_lbn`, `chain_append()`,
+`g.total_user_lbn += slot->user_blocks`) — this is existing, working code, not something 2h
+needs to build. What 2h actually needs to build: (1) a `blkio_usb.c` backend implementing the
+`blkio_dev` vtable (matching `blkio_file.c`/`blkio_ram.c`'s pattern) over BOT reads/writes —
+depends on 2f/2g; (2) the connect-time call site that hands a ready `blkio_dev*` to
+`blk_subsys_attach_device()` once PORTSC + enumeration confirm a Mass Storage/BOT device; (3) a
+hot-**detach** path — genuinely missing today, `chain_append()` only adds, there is no removal
+function. Detaching should be safe without renumbering other devices' LBNs as long as USB stays
+the tail of the chain (true today; would need reconsidering if a second hot-pluggable device
+class is ever added), but the function itself does not exist yet.
+
 ### Milestone 3 — Block subsystem extensions (Section U items 3-6, Section V area A)
 
 Depends on Milestone 2 existing (needs a real device to test against, though the
 identity→range derivation logic itself could be unit-tested against the existing RAM/
 RAMDRIVE/DISK devices first without waiting for USB).
 
+**Decided with Captain Bob, 2026-08-22 — USB thumb drives get GPT-partitioned, unlike
+`artemis.img`'s current whole-device STFR/v2 header (`blk_compute_fresh_geometry()`,
+`src/block_subsystem.c:405-429` — that layout writes the header directly at devblock 0 of the
+whole device, no partition table).** Reference/target physical drive size: **16GB**. Layout:
+one GPT partition ≈1GB for LithosAnanke metadata (identity/credential/ACL material — Section
+U/V's PKI work, not yet designed in detail), remainder (≈15GB) as a second partition holding
+the block-storage region that gets attached into the LBN chain via `blk_subsys_attach_device()`
+(pointed at that partition's start LBA, not devblock 0 of the raw device). Sizing explicitly
+tentative — "we'll figure it out" if 1GB proves too small once the metadata format is designed.
+**Not yet a punch-list item, and not yet built: this repo has no GPT parser anywhere in kernel
+code today** (the riscv64 boot disk's GPT layout, `Makefile.starkernel`'s `sgdisk` call, is
+host-side build tooling for the UEFI ESP, not kernel-read code) — reading/writing a real GPT
+partition table from `src/starkernel/` is new, unstarted work this decision now requires,
+before `blkio_usb.c` can hand `blk_subsys_attach_device()` a correctly-offset device view.
+`disk/usb-thumbdrive-test.img` stays a small 64MB test fixture regardless — a 16GB file isn't
+practical to commit to this repo; 16GB is the real-world design target the *layout math* is
+sized around, not the size of every test image.
+
 - [ ] Design the identity→block-range derivation function's exact input/output (Section V
       area A open point: currently zero decisions made, not even a function signature)
 - [ ] Decide what "identity" means concretely as an input — the Ed25519 public key itself,

capsules/BLOCK_MAP.md

@@ -1,5 +1,5 @@
 # Capsule Block Manifest — Auto-generated
-<!-- Generated by mkcapsule --manifest  2026-08-22T13:35:47Z -->
+<!-- Generated by mkcapsule --manifest  2026-08-22T13:40:29Z -->
 <!-- DO NOT EDIT — re-run mkcapsule --manifest to refresh.  -->
 <!-- Hand-written justifications and immutability notes live  -->
 <!-- in MANIFEST.md alongside this auto-generated index.      -->

disk/README.md

@@ -56,5 +56,20 @@ successfully recognized disk, which gets flushed at shutdown. This is
 expected bookkeeping, not a bug; revert it before committing rather than
 carrying timestamp noise in git history.
 
+- `usb-thumbdrive-test.img` — 64MB raw image backing a QEMU `usb-storage`
+  device attached to the xHCI controller's bus (`xhci0.0`) for Milestone 2e/
+  2h hotplug testing, added 2026-08-22. Not yet formatted with any
+  LithosAnanke/Artemis header — at this point in the driver's development
+  it only needs to exist as a backing store for a live Port Status Change
+  event; formatting comes once `blkio_usb.c` and `blk_subsys_attach_device()`
+  wiring exist (Milestone 2h).
+
+**Convention, standing as of 2026-08-22: every virtual disk/thumb-drive image
+used for testing — Artemis persistence disks above, and USB Mass Storage
+backing images alike — lives in this directory and is a tracked, committed
+file, never scratchpad.** This was already `artemis.img`'s convention;
+`usb-thumbdrive-test.img` and any future USB test images follow the same
+rule. Confirmed no `.gitignore` in this repo excludes `disk/*.img`.
+
 These are regenerable QEMU raw disk images, not source — see
 `.claude/ARTEMIS.md` for the storage model they exercise.