Artemis genesis stamp: fix a BAM-corrupting offset before it ever ran (FABRIC-3.md §XXVI follow-on, Step 3)

Step 3: one-time artemis_sig_t genesis stamp, written once
kernel_main.c's virtio-blk path confirms Artemis's own disk, so the disk
image is later recognizable generically (repl.c's idle-loop USB-MSC scan,
built in the prior commit) regardless of which bus found it.

Correction made before this ever touched the real disk: the signature's
first design (committed in 29b6789) placed it at a fixed bottom-of-device
forth-block (4, devblock 1) -- copying homeblocks_sig_t's own convention,
which is safe for a raw identity thumbdrive but not for Artemis's own
disk. Artemis's disk is block_subsystem.c's own STFR/v2-formatted volume:
devblock 0 holds that format's header and devblock 1 is the FIRST
DEVBLOCK OF THE LIVE BAM (blk_compute_fresh_geometry(): bam_start = 1).
The original design would have overwritten Artemis's live allocation map
on the very first real boot. Caught via direct cross-reference against
block_subsystem.c before the genesis-stamp call site was ever run against
the real image -- no corruption occurred.

Fixed by moving the header to a fixed offset from the END of the device
instead (ARTEMIS_SIG_DEVBLOCK_FROM_TOP=64), the same top-of-device region
block_subsystem.c's own meta_fence_blocks reservation (128 devblocks)
already carves out for system metadata, and where Zuse's genesis marker/
eligibility list already live -- but computed independently via
blkio_info() rather than through blk_meta_zone_*(), since that accessor
needs an already-attached, format-detected slot, which is exactly the
state pre-attach generic discovery doesn't have yet. Picked well clear of
Zuse's two tenants (devblock_from_top 0 and 1+, open-ended) so the two
subsystems' independent math can never collide.

Also reordered kernel_main.c: rng_init() now runs before the Artemis
virtio-blk block (was after) -- the genesis stamp needs rng_get_bytes()
for disk_uuid, and the original order would have failed the stamp on
every boot.

Verified live: booted amd64 against the real disk/artemis.img twice --
first boot logs "Artemis: genesis signature stamped" (confirmed blank at
the target offset beforehand via a host-side read), second boot on the
now-stamped image logs no re-stamp (idempotent, CRC/read-back verified)
-- both boots and aarch64/riscv64 (against the same now-stamped image)
all still report "Artemis: 22998 data blocks" / "PASS: persist-read"
unchanged, confirming the BAM and data pool were never touched.

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

capsules/BLOCK_MAP.md

@@ -1,5 +1,5 @@
 # Capsule Block Manifest — Auto-generated
-<!-- Generated by mkcapsule --manifest  2026-09-13T11:14:42Z -->
+<!-- Generated by mkcapsule --manifest  2026-09-13T11:29:27Z -->
 <!-- DO NOT EDIT — re-run mkcapsule --manifest to refresh.  -->
 <!-- Hand-written justifications and immutability notes live  -->
 <!-- in MANIFEST.md alongside this auto-generated index.      -->

include/starkernel/artemis_sig.h

@@ -36,14 +36,49 @@
  * thumbdrive and Artemis's own disk could both be attached as USB-MSC
  * devices simultaneously) would have no way to tell them apart.
  *
- * Mirrors homeblocks_sig_t's own structural convention exactly (magic +
+ * Mirrors homeblocks_sig_t's own structural convention (magic + version +
- * version + CRC, one 4KiB devblock, same devblock-1 fixed location) --
+ * CRC, one 4KiB header) -- a sibling format, not a field bolted onto
- * a sibling format, not a field bolted onto homeblocks_sig_t itself:
+ * homeblocks_sig_t itself: homeblocks_sig_t's own header comment already
- * homeblocks_sig_t's own header comment already states it's "deliberately
+ * states it's "deliberately narrow in scope" (identity-drive fields only,
- * narrow in scope" (identity-drive fields only, no spare room -- its
+ * no spare room), and Artemis's disk is conceptually a different kind of
- * padding is computed to fill exactly 4096 bytes), and Artemis's disk is
+ * thing (one dedicated fleet-owned device, not one of many candidate
- * conceptually a different kind of thing (one dedicated fleet-owned device,
+ * identity drives), not a variant of the same one.
- * not one of many candidate identity drives), not a variant of the same one.
+ *
+ * CORRECTION, same day: the first version of this format placed the header
+ * at a fixed bottom-of-device forth-block (4, i.e. devblock 1), copying
+ * homeblocks_sig_t's own devblock-1 convention. That convention is safe for
+ * an identity thumbdrive (raw, dedicated storage -- capsule_mint.c writes
+ * directly, no block-subsystem format involved), but Artemis's disk is
+ * block_subsystem.c's own STFR/v2-formatted volume: devblock 0 holds that
+ * format's header (read_header_4k()/write_header_4k(), block_subsystem.c)
+ * and devblock 1 is the FIRST DEVBLOCK OF THE LIVE BAM
+ * (blk_compute_fresh_geometry(): bam_start = 1). Writing artemis_sig_t
+ * there would have overwritten Artemis's own live allocation map on the
+ * very first real boot this ran against -- caught (via `git status`/`grep`
+ * cross-reference against block_subsystem.c, not against a live disk)
+ * before the genesis-stamp call site ever executed against the real image.
+ *
+ * The header now lives at a fixed offset from the END of the device
+ * instead (ARTEMIS_SIG_DEVBLOCK_FROM_TOP, see below) -- the same
+ * "top-of-device, outside the user-addressable LBN pool" region
+ * block_subsystem.c's own meta_fence_blocks reservation (128 devblocks by
+ * default, BLK_META_FENCE_INIT) already carves out for exactly this kind
+ * of system metadata, and where Zuse's own genesis marker/eligibility list
+ * already live (blk_meta_zone_read()/write(), devblock_from_top 0 and 1+
+ * respectively). This format deliberately does NOT go through
+ * blk_meta_zone_*, though: that accessor requires the device to already be
+ * blk_subsys_attach_device()'d and format-detected (first_disk_slot()) --
+ * exactly the state generic pre-attach discovery (repl.c's idle-loop
+ * USB-MSC scan) doesn't have yet, which is the entire reason this format
+ * exists. artemis_sig_check()/artemis_sig_genesis_stamp() instead compute
+ * the same top-of-device arithmetic independently via blkio_info(), so
+ * they work on a raw, not-yet-attached device exactly like
+ * homeblocks_sig_check() already does. ARTEMIS_SIG_DEVBLOCK_FROM_TOP is
+ * fixed well clear of Zuse's two tenants (0 and 1+, open-ended but
+ * realistically small -- 127 pubkeys per chained devblock) so the two
+ * subsystems' independent top-of-device math can never collide, without
+ * this format needing to know how far the eligibility chain has actually
+ * grown on any given boot.
  *
  * Reserves offset/size pointers to the growable per-VM log-persistence
  * region (FABRIC-3.md §XXVI follow-on's own log-record work), the same way
@@ -81,13 +116,20 @@ extern "C" {
 #define ARTEMIS_SIG_GET_MAGIC(m)   ((uint32_t)((m) & 0xFFFFFFFFULL))
 #define ARTEMIS_SIG_GET_VERSION(m) ((uint8_t)(((m) >> 32) & 0xFF))
 
-/* Same devblock-1 (forth-block 4) convention as HOMEBLOCKS_SIG_START_FBLOCK
+/* Fence-relative top-of-device index -- see this header's own CORRECTION
- * -- devblock 0 stays reserved for the block-subsystem's own generic
+ * comment above for why this replaced a fixed bottom-of-device forth-block.
- * 'STFR'/v2 volume header (block_subsystem.h), same reasoning as
+ * Same "distance from the very last physical devblock" convention
- * homeblocks_sig.h's own comment on this. No collision risk with an
+ * block_subsystem.c's blk_meta_zone_read()/write() use internally (0 =
- * identity thumbdrive's own homeblocks_sig_t at the same devblock offset --
+ * last devblock, 1 = second-to-last, ...), computed independently here via
- * they are different physical/virtual devices entirely. */
+ * blkio_info() rather than through that accessor (which needs an already-
-#define ARTEMIS_SIG_START_FBLOCK 4u
+ * attached, format-detected slot this code runs before). Fixed well past
+ * Zuse's genesis marker (devblock_from_top 0) and eligibility list
+ * (devblock_from_top 1, chained upward as needed) -- see
+ * zuse_eligibility_list.h -- so the two subsystems' independent top-of-
+ * device math can never collide regardless of how large the eligibility
+ * chain grows in practice. Well inside BLK_META_FENCE_INIT (128 devblocks,
+ * block_subsystem.h) on any real Artemis disk. */
+#define ARTEMIS_SIG_DEVBLOCK_FROM_TOP 64u
 
 /*===========================================================================
  * artemis_sig_t - Artemis disk signature header (exactly one 4KiB devblock)
@@ -157,21 +199,18 @@ typedef enum {
 struct blkio_dev;
 
 /*
- * artemis_sig_check - Read and verify the Artemis disk signature header.
+ * artemis_sig_check - Read and verify the Artemis disk signature header, at
- * Mirrors homeblocks_sig_check()'s own contract exactly (same forth-block
+ * the fixed ARTEMIS_SIG_DEVBLOCK_FROM_TOP offset from whatever `dev`
- * read pattern, same "starting block is a caller-supplied parameter"
+ * reports as its own total size (blkio_info()) -- no attach or format
- * separation of concerns).
+ * detection required, same "works on a raw, not-yet-attached device"
+ * contract homeblocks_sig_check() already has.
  *
  * @param dev              Open block device to read from.
- * @param sig_start_fblock First of 4 consecutive forth-blocks holding the
- *                         4KB header -- ARTEMIS_SIG_START_FBLOCK for every
- *                         real caller today.
  * @param out_sig          On ARTEMIS_SIG_OK, populated with the verified
  *                         header. Left unspecified on any other result.
  * @return ARTEMIS_SIG_OK, or the specific reason for refusal.
  */
 artemis_sig_result_t artemis_sig_check(struct blkio_dev *dev,
-                                        uint32_t sig_start_fblock,
                                         artemis_sig_t *out_sig);
 
 /*
@@ -185,6 +224,37 @@ artemis_sig_result_t artemis_sig_check(struct blkio_dev *dev,
  */
 uint64_t artemis_sig_compute_crc(const artemis_sig_t *sig);
 
+/*
+ * artemis_sig_genesis_stamp - One-time write of a fresh artemis_sig_t onto
+ * a disk already confirmed to be Artemis's own (never called speculatively
+ * on an unidentified/blank device -- see the call site in kernel_main.c for
+ * why that's always safe there: virtio_blk_find_artemis() only ever
+ * succeeds against the one dedicated PCI device, so a BLANK read at this
+ * fblock unambiguously means "this disk has never been stamped," not
+ * "this might be some other blank drive"). log_region_offset/devblocks are
+ * written as 0 (not yet allocated) -- step 4's own log-persistence design
+ * allocates them later via a normal artemis_sig_t rewrite, same one-header
+ * location.
+ *
+ * disk_uuid is drawn from rng_get_bytes(), same entropy source
+ * capsule_mint.c already uses for an identity thumbdrive's drive_uuid.
+ * genesis_time_ns is written as 0 -- no monotonic-ns source exists
+ * anywhere in this codebase yet, same open item homeblocks_sig_t's own
+ * minted_time_ns field already carries.
+ *
+ * Idempotent by construction: a caller must check artemis_sig_check()
+ * returns ARTEMIS_SIG_BLANK first (this function does not re-check, to
+ * avoid a second redundant read the caller already just performed).
+ *
+ * @param dev  Open block device to write to. Must already be confirmed as
+ *              Artemis's own disk.
+ * @return 0 on success (including read-back verification), -1 on any
+ *         entropy, write, or verify failure -- the disk is left however
+ *         the failed write left it, same as capsule_mint.c's own
+ *         write-then-verify discipline.
+ */
+int artemis_sig_genesis_stamp(struct blkio_dev *dev);
+
 #ifdef __cplusplus
 }
 #endif

src/starkernel/artemis_sig.c

@@ -34,6 +34,9 @@
 #include "block_subsystem.h" /* compute_crc64() -- same CRC-64/ISO
                               * homeblocks_sig.c's own check reuses,
                               * not duplicated here either */
+#include "starkernel/rng.h"  /* rng_get_bytes() -- same entropy source
+                              * capsule_mint.c already uses for an
+                              * identity thumbdrive's own drive_uuid */
 
 uint64_t artemis_sig_compute_crc(const artemis_sig_t *sig) {
     /* Covers every field up to but not including hdr_crc itself (and never
@@ -43,15 +46,42 @@ uint64_t artemis_sig_compute_crc(const artemis_sig_t *sig) {
     return compute_crc64((const uint8_t *)sig, crc_span);
 }
 
+/* Resolve ARTEMIS_SIG_DEVBLOCK_FROM_TOP (a distance from the last physical
+ * devblock) to an absolute starting forth-block on `dev`, using only
+ * blkio_info() -- no attach or format-detection required, matching
+ * block_subsystem.c's own devblock_from_top arithmetic
+ * (total_devblocks - 1 - devblock_from_top) exactly, but computed
+ * independently since blk_meta_zone_*() isn't reachable pre-attach. The
+ * floor division (total forth-blocks / 4) matches block_subsystem.c's own
+ * udiv_floor(total_blkio_blocks_1k, 4) -- plain unsigned integer division
+ * already floors, so no separate helper is needed here.
+ *
+ * @return 0 and *out_fblock set on success; -1 if the device is too small
+ *         to hold the reserved offset at all (couldn't happen on a real
+ *         Artemis disk, but a foreign/tiny device must never underflow
+ *         into a wild block). */
+static int artemis_sig_start_fblock(struct blkio_dev *dev, uint32_t *out_fblock) {
+    blkio_info_t info;
+    if (blkio_info((blkio_dev_t *)dev, &info) != BLKIO_OK) return -1;
+
+    uint32_t total_devblocks = info.total_blocks / 4u;
+    if (total_devblocks < ARTEMIS_SIG_DEVBLOCK_FROM_TOP + 1u) return -1;
+
+    uint32_t devblock_idx = total_devblocks - 1u - ARTEMIS_SIG_DEVBLOCK_FROM_TOP;
+    *out_fblock = devblock_idx * 4u;
+    return 0;
+}
+
 artemis_sig_result_t artemis_sig_check(struct blkio_dev *dev,
-                                        uint32_t sig_start_fblock,
                                         artemis_sig_t *out_sig) {
     uint8_t          buf[4096];
     uint32_t         i;
+    uint32_t         sig_start_fblock;
     artemis_sig_t    local;
     uint64_t         expected_crc;
 
     if (!dev) return ARTEMIS_SIG_READ_ERROR;
+    if (artemis_sig_start_fblock(dev, &sig_start_fblock) != 0) return ARTEMIS_SIG_READ_ERROR;
 
     /* artemis_sig_t is exactly one 4KiB devblock; blkio's own unit is a
      * 1KiB "forth block" (BLKIO_FORTH_BLOCK_SIZE), so the header spans 4
@@ -85,3 +115,47 @@ artemis_sig_result_t artemis_sig_check(struct blkio_dev *dev,
     if (out_sig) *out_sig = local;
     return ARTEMIS_SIG_OK;
 }
+
+int artemis_sig_genesis_stamp(struct blkio_dev *dev) {
+    if (!dev) return -1;
+
+    uint32_t sig_start_fblock;
+    if (artemis_sig_start_fblock(dev, &sig_start_fblock) != 0) return -1;
+
+    artemis_sig_t sig;
+    memset(&sig, 0, sizeof(sig));
+    sig.magic = ARTEMIS_SIG_PACK(ARTEMIS_SIG_VERSION_0);
+    if (rng_get_bytes(sig.disk_uuid, sizeof(sig.disk_uuid)) != 0) return -1;
+    sig.genesis_time_ns    = 0; /* no monotonic-ns source yet, same open
+                                 * item as homeblocks_sig_t's own
+                                 * minted_time_ns field */
+    sig.metadata_devblocks = 1; /* just this header devblock for now --
+                                 * grows to cover the log region once
+                                 * step 4 allocates it (a normal rewrite
+                                 * of this same one-header location) */
+    sig.log_region_offset    = 0; /* not yet allocated */
+    sig.log_region_devblocks = 0;
+    sig.hdr_crc = artemis_sig_compute_crc(&sig);
+
+    uint8_t buf[4096];
+    memcpy(buf, &sig, sizeof(sig));
+
+    uint32_t i;
+    for (i = 0; i < 4; i++) {
+        if (blkio_write((blkio_dev_t *)dev, sig_start_fblock + i,
+                         buf + (size_t)i * BLKIO_FORTH_BLOCK_SIZE) != BLKIO_OK) {
+            return -1;
+        }
+    }
+    (void)blkio_flush((blkio_dev_t *)dev);
+
+    /* Read-back verification, same discipline as capsule_mint.c's own
+     * verify_mint() -- a successful blkio_write() return only means the
+     * command chain completed, not that the bytes survive to be read
+     * back correctly. */
+    artemis_sig_t verify;
+    if (artemis_sig_check(dev, &verify) != ARTEMIS_SIG_OK) return -1;
+    if (memcmp(&verify, &sig, sizeof(sig)) != 0) return -1;
+
+    return 0;
+}

src/starkernel/kernel_main.c

@@ -63,6 +63,7 @@ EFI_RUNTIME_SERVICES *g_sk_runtime_services = NULL;
 #include "starkernel/capsule_loader.h"
 #include "starkernel/capsule_birth.h"  /* capsule_birth_mama, capsule_find_mama_init */
 #include "starkernel/capsule_zuse_boot.h" /* capsule_zuse_boot_load_root_pubkey */
+#include "starkernel/artemis_sig.h" /* artemis_sig_check/genesis_stamp */
 #include "starkernel/kmalloc.h"
 #include "starkernel/repl.h"
 #include "starkernel/pci.h"
@@ -589,6 +590,30 @@ static void kernel_main_deep(BootInfo *boot_info) {
     console_println("PCI: init...");
     pci_init(boot_info->acpi_table);
 
+    /* Phase 8: entropy. Real per-arch RNG doesn't cover all three
+     * architectures (amd64 RDRAND, riscv64 Zkr, but aarch64 has neither in
+     * QEMU's CPU models -- see vm_uuid.h's identical finding), so signing/
+     * keygen entropy comes from the unified rng_get_bytes() layer, whose
+     * v2.0.0 backend is the paravirtualized virtio-rng device. Unconditional
+     * call site, same graceful-noop precedent as virtio_blk_find_artemis()
+     * below -- boot proceeds either way, the device is only required once
+     * something actually calls rng_get_bytes().
+     *
+     * FABRIC-3.md §XXVI follow-on, 2026-09-13: moved ahead of the Artemis
+     * virtio-blk block below (was after it) -- artemis_sig_genesis_stamp()
+     * needs rng_get_bytes() for disk_uuid, and calling it before rng_init()
+     * ran would have failed the stamp on every single boot forever. Both
+     * calls only need pci_init() above; this reordering has no other
+     * dependency either way. */
+    {
+        int rrc = rng_init();
+        if (rrc == 0) {
+            console_println("entropy: ready");
+        } else {
+            console_println("entropy: not available (continuing without)");
+        }
+    }
+
     {
         static blkio_dev_t artemis_dev;
         int vrc = virtio_blk_find_artemis(&artemis_dev);
@@ -603,28 +628,40 @@ static void kernel_main_deep(BootInfo *boot_info) {
              * capsule_zuse_boot_load_root_pubkey()'s own doc comment for
              * why this is safe and separate from her live-session cert. */
             capsule_zuse_boot_load_root_pubkey((VM *)mama_vm);
+
+            /* FABRIC-3.md §XXVI follow-on, 2026-09-13: one-time
+             * artemis_sig_t genesis stamp, so this exact disk image can
+             * later be recognized generically (by content, not by which
+             * bus/vendor-ID scan happened to find it -- see repl.c's own
+             * idle-loop USB-MSC discovery, the reason this signature
+             * format exists at all). Safe to attempt unconditionally
+             * every boot: virtio_blk_find_artemis() only ever succeeds
+             * against the one dedicated PCI device, so a BLANK read here
+             * unambiguously means "never stamped," not "might be some
+             * other blank drive" -- and artemis_sig_check() returning
+             * anything other than BLANK (already stamped, or a version/
+             * CRC mismatch worth leaving alone rather than overwriting)
+             * skips the stamp. See artemis_sig.h's own doc comment for why
+             * this lands at a fence-relative top-of-device offset now,
+             * not a fixed bottom-of-device forth-block (that first attempt
+             * would have overwritten Artemis's own live BAM -- caught
+             * before ever being run against the real disk). */
+            {
+                artemis_sig_t asig;
+                artemis_sig_result_t art_rc = artemis_sig_check(&artemis_dev, &asig);
+                if (art_rc == ARTEMIS_SIG_BLANK) {
+                    if (artemis_sig_genesis_stamp(&artemis_dev) == 0) {
+                        console_println("Artemis: genesis signature stamped");
+                    } else {
+                        console_println("Artemis: genesis signature stamp FAILED");
+                    }
+                }
+            }
         } else {
             console_println("Artemis: no virtio-blk disk (continuing without)");
         }
     }
 
-    /* Phase 8: entropy. Real per-arch RNG doesn't cover all three
-     * architectures (amd64 RDRAND, riscv64 Zkr, but aarch64 has neither in
-     * QEMU's CPU models -- see vm_uuid.h's identical finding), so signing/
-     * keygen entropy comes from the unified rng_get_bytes() layer, whose
-     * v2.0.0 backend is the paravirtualized virtio-rng device. Unconditional
-     * call site, same graceful-noop precedent as virtio_blk_find_artemis()
-     * above -- boot proceeds either way, the device is only required once
-     * something actually calls rng_get_bytes(). */
-    {
-        int rrc = rng_init();
-        if (rrc == 0) {
-            console_println("entropy: ready");
-        } else {
-            console_println("entropy: not available (continuing without)");
-        }
-    }
-
     /* Zuse identity: SUPERSEDED 2026-08-28 (FABRIC-2.md §F.20/§F.21).
      * The one-shot block-fence mint-or-load that used to run here is
      * gone -- Zuse is thumbdrive-resident now (her seed never touches

src/starkernel/repl.c

@@ -496,8 +496,7 @@ static void sk_repl_idle(VM *active_vm)
             int is_artemis_disk = 0;
             if (sig_rc == HOMEBLOCKS_SIG_BLANK) {
                 artemis_sig_t asig;
-                artemis_sig_result_t art_rc =
+                artemis_sig_result_t art_rc = artemis_sig_check(usb_blk_dev, &asig);
-                    artemis_sig_check(usb_blk_dev, ARTEMIS_SIG_START_FBLOCK, &asig);
                 if (art_rc == ARTEMIS_SIG_OK) {
                     log_message(LOG_DEBUG, "xhci: USB drive recognized as Artemis's own disk");
                     is_artemis_disk = 1;