From 7cbf92ac8f42b918b552c99db39c688e3d5e0cac Mon Sep 17 00:00:00 2001
From: Robert Allan James <robert.allan.james@gmail.com>
Date: Wed, 26 Aug 2026 06:47:52 -0400
Subject: [PATCH] FABRIC-3.md: design the home-blocks drive signature format
 (Phase 8 kickoff)

Mirrors CAPSULE_MAGIC_PACK's bit-packed magic and blk_volume_meta_t's
magic+version+fields+pad-to-4096 structural convention exactly, per
the punch-list item's own direction. Lives at the first 4KiB devblock
of the ~1GB GPT metadata partition -- format doesn't depend on the
still-missing GPT parser.

Deliberately narrow: identifies/authenticates the drive only, does not
invent the block-map or credential/cert formats -- reserves offset/
size pointers to where they'll live instead of embedding them, since
neither format is designed yet (block-map is Milestone 3, cert format
needs Milestone 6's still-ungenerated real CA). hdr_crc is real from
day one, unlike blk_volume_meta_t's unused placeholder, since this
header's whole job is gating the warn-and-refuse security check.

Design only, not yet implemented as a header file -- presented for
confirmation first.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CXjAPTEKrgY2Mrk25KoLDn
---
 FABRIC-3.md | 52 +++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 49 insertions(+), 3 deletions(-)

diff --git a/FABRIC-3.md b/FABRIC-3.md
index 0de520b..c590114 100644
--- a/FABRIC-3.md
+++ b/FABRIC-3.md
@@ -155,9 +155,55 @@ decisions get added here, not to `FABRIC-2.md`. Follow the same discipline `FABR
 
 ### From FABRIC-2.md §X, Milestone 4 — Drive/credential security
 
-- [ ] Design the home-blocks drive signature format (Section U item 7) — reusing
-  `CAPSULE_MAGIC_PACK`'s pattern (magic + version in a fixed header field) as the confirmed
-  precedent, applied to a drive's reserved header block instead of a capsule.
+- [x] **Designed (2026-08-26), not yet implemented — Phase 8 kickoff.** Mirrors two existing
+  precedents exactly: `CAPSULE_MAGIC_PACK`'s bit-packed magic (`include/starkernel/capsule.h`)
+  and `blk_volume_meta_t`'s magic+version+fields+pad-to-4096 structural convention
+  (`include/block_subsystem.h`). Lives at the first 4KiB devblock of the GPT metadata
+  partition (the ~1GB partition decided 2026-08-22) — the header format doesn't depend on the
+  still-missing GPT parser; it's just what gets written starting at that partition's first
+  devblock once something can locate it. Deliberately narrow: identifies/authenticates the
+  drive only, does **not** invent the block-map or credential/cert formats (both separate,
+  still-open items below) — reserves offset/size pointers to where they'll live instead of
+  embedding them.
+
+  ```c
+  #define HOMEBLOCKS_SIG_MAGIC   0x4248414CULL /* 'LAHB' -- LithosAnanke Home Blocks,
+                                                  * same little-endian ASCII packing as
+                                                  * CAPSULE_DESC_MAGIC's 'CAPS' */
+  #define HOMEBLOCKS_SIG_VERSION_0 0
+
+  #define HOMEBLOCKS_SIG_PACK(ver) \
+      (HOMEBLOCKS_SIG_MAGIC | ((uint64_t)(ver) << 32))
+  #define HOMEBLOCKS_SIG_GET_MAGIC(m)   ((uint32_t)((m) & 0xFFFFFFFFULL))
+  #define HOMEBLOCKS_SIG_GET_VERSION(m) ((uint8_t)(((m) >> 32) & 0xFF))
+
+  typedef struct {
+      uint64_t magic;              /* HOMEBLOCKS_SIG_PACK(...) */
+      uint8_t  drive_uuid[16];     /* unique per-mint instance id -- Phase 8 mints multiple
+                                    * distinct drives, needs something to tell them apart */
+      uint64_t minted_time_ns;
+      uint64_t metadata_devblocks; /* size of this GPT metadata partition, in 4KiB devblocks
+                                    * -- sanity/bounds check against the GPT entry once a
+                                    * parser exists */
+      uint32_t cert_offset;        /* devblock offset within this partition where the
+                                    * CA-signed cert blob starts; 0 = not yet minted */
+      uint32_t cert_devblocks;
+      uint32_t blockmap_offset;    /* devblock offset where the block-map (Milestone 3,
+                                    * format still undesigned) starts */
+      uint32_t blockmap_devblocks;
+      uint64_t hdr_crc;            /* REAL from day one, not a placeholder like
+                                    * blk_volume_meta_t's "unused yet" hdr_crc -- this
+                                    * header's whole job is gating a warn-and-refuse
+                                    * security check below, so the crc has to actually work */
+      uint8_t  _pad[4096 - 64];    /* pad to one devblock; 64 = sum of the fields above */
+  } homeblocks_sig_t;
+  ```
+
+  `cert_offset`/`cert_devblocks` are 0 on first design pass — the real CA hasn't been
+  generated yet (Milestone 6), so this reserves the *shape* of where a cert will attach
+  without committing to a cert format that doesn't exist. Same reasoning for
+  `blockmap_offset`/`blockmap_devblocks` against Milestone 3's still-open block-map design.
+  Not yet written to a header file — presented for confirmation before implementation.
 
 - [ ] Implement the signature check, called before any write path touches a newly-inserted
   drive.