Traced the actual Hermes mechanism before scoping: MSG-DELIVER already executes arbitrary FORTH source text on the destination VM via VM-EXEC, not a structured RPC -- migrating an interaction needs no new dispatch machinery, only a routing decision. Noted that every "VM" lives in one kernel address space, not a separate process, so messaging WIREBIND/BINDSTEP/CERTVERIFY is an architectural-discipline choice (uniform heat/audit participation in Compudynamics via Hermes), not a correctness requirement.
Decisions: real target is the Console VM (already real hardware: serial+framebuffer+PS2, not waiting on D.2b), a two-hop flow (Hera->Console reports attach outcome, Console->Hera requests the privileged operation), payload arguments encoded as literals directly in the FORTH text.
Captured a substantial new vision detail surfaced live while scoping this (D.6): blank-media minting is meant to be an interactive Console-driven onboarding form (Full Name/Address/City/State/Country/Metadata), not a bare programmatic MINT call -- connects forward into RUNCAP's deferred "default personality content" question and MINT's own scope. Capture only, not designed in detail, per this arc's own capture-first discipline.
Traced the completion-code handling before designing anything: every transfer completion (control or bulk) shares one gate that logs and bails on any non-success code -- STALL isn't distinguished from any other failure, and no recovery exists (no xHCI Reset Endpoint, no CLEAR_FEATURE(ENDPOINT_HALT)). A bounded-timeout safety net in xhci_bot_wait_for_idle() prevents a hang, but the endpoint stays wedged for everything after it. Per direct instruction, designed full recovery now rather than deferring to Milestone 8: new STALL_ERROR completion code, new xHCI Reset Endpoint + Set TR Dequeue Pointer command TRB types (neither exists today), CLEAR_FEATURE(ENDPOINT_HALT) reusing the existing control-transfer plumbing, escalating to a full Bulk-Only Mass Storage Reset on a second stall, bounded via a new retry counter mirroring the existing bot_tur_retries/XHCI_BOT_TUR_MAX_RETRIES precedent exactly. This closes the last open Milestone 2 item.
Confirmed the F.12 handoff: cache_load_devblock() already unpacks/validates metadata on load, same "already built" story as BMAPWRITE. But tracing "validate on insertion" surfaced a real, load-bearing conflict unrelated to blk_meta_t: blk_subsys_attach_device() always runs the generic block-subsystem's own STFR/v2 header check at devblock 0, which would always read a home-blocks drive's 'LAHB' magic as "unrecognized" and leave it permanently write-refused (BLK_FMT_PROVISIONAL) -- or, if force-formatted via blk_subsys_confirm_format(), overwrite homeblocks_sig_t outright, since both want the same devblock 0. This was invisible to CERTVERIFY/WIREBIND/RUNCAP/MINT because none of them traced the generic attach path alongside homeblocks_sig_check(). Fixed: homeblocks_sig_t relocates to devblock 1 (a call-site change only, sig_start_fblock was already a plain parameter); MINT must also run the ordinary format-confirm path at devblock 0 so the drive is writable through the normal block-buffer path.
Traced blk_set_meta()/cache_writeback()/blk_flush() before assuming a new write path was needed. BMAPWRITE is already done: BMAPFMT's decision to repurpose the existing blk_meta_t accessors instead of a new table means the flush path that already exists for ordinary block data already covers metadata identically -- real, unstubbed, all the way to dev->write(). The only blocker is WRITE(10) itself, already modeled in the graph. Handoff note for BMAPREAD's own pass: the read side looks like it closes the same way but wasn't confirmed here.
Also corrects a self-inconsistency from the previous commit: UNCLEAN was marked with a "done" checkmark even though its wiring code isn't written yet, unlike BMAPWRITE which really is working code today. Moved UNCLEAN back to the "scoped, not built" bucket alongside BMAPFMT/CERTVERIFY/etc.
Traced g.total_user_lbn and blk_meta_t's chain fields before scoping: the M3 punch-list wording ("claim at g.total_user_lbn") predates BMAPFMT's distributed-ownership decision and doesn't describe a workable mechanism -- total_user_lbn only grows when a whole new device attaches, not when claiming space within one already attached. Real job is scanning Artemis's already-attached device's own blk_meta_t records for unowned devblocks. Also found blk_meta_t already has real, unused prev_block/next_block/chain_length linkage fields, untouched by BMAPFMT's redesign. Decisions: claims are a scattered chain via those fields (fragmentation-immune, free), discovered via full linear scan every time (no cached index, matches BMAPFMT's own no-centralized-table philosophy), fail outright with no partial-claim fallback if the device can't satisfy a request.
Traced capsule_vm_kill() fully -- it's real and complete, so DETACH needs only a caller plus flush/bookkeeping, not new teardown machinery. Found that D.3's "flush before eject" only makes sense as a deliberate pre-removal step, splitting this into a graceful path (new EJECT word) and the abrupt hot-unplug signal already wired -- per direct instruction, scoped both, closing the previously-separate UNCLEAN (M3) node as "same kill path, no flush attempt." Needs one small new piece of state (which VMUuid is attached via the home-blocks path) since BINDSTEP's live-reverify approach doesn't work once the device is already gone. Reports, without fixing, a separate pre-existing bug found while tracing this: capsule_vm_kill() never resets g_repl_active_vm, so plain KILL on a USE'd VM leaves a dangling pointer today.
Traced the actual retarget path before assuming new plumbing: USE (mama_forth_words.c:430-480) already looks up a VM by name and calls sk_repl_set_active_vm() directly, completely unguarded. BINDSTEP is concretely "add the ACLKEY comparison to this one call site." Found one real gap: usb_blk_dev/xdev are function-static inside sk_repl_idle(), invisible to USE -- needs a small new accessor mirroring sk_repl_get_active_vm()'s own precedent. Decisions: re-verify the attached drive live on every USE call rather than trust a cached pubkey; VMs with no VMIdentity installed yet (Hera/Hermes/Artemis today) stay freely targetable, no regression; installed=1 targets refuse on no-drive-attached or pubkey mismatch, matching USE's existing refusal style. Zuse's override UX stays deferred per direct instruction.
Traced two hidden dependencies before scoping: (1) no GPT parser/writer exists anywhere in kernel code, and per direct instruction GPT is dropped entirely rather than deferred -- the raw homeblocks_sig_t-at-devblock-0 layout every other node (CERTVERIFY/WIREBIND/RUNCAP/HOTPLUG) already treated as interim becomes the permanent format. (2) xhci_dev_t's BOT/MSC state is singular, not per-slot, raising a concern about the vision's "mint a second thumb while Zuse is active" implying two simultaneous USB devices -- resolved: Zuse's identity is system-resident (loaded from Artemis's own block-fence at boot), never thumbdrive-based, so MINT only ever needs one attached target drive. Decisions: minted identities get a real keypair (virtio_rng + ed25519_keygen), stored via a new user_identity_seed_t record occupying RUNCAP's identity_src region's first devblock; drive_uuid is a separate random draw; cert construction reuses CERTVERIFY's exact format, signed with Zuse's own seed -- first confirmed need for DER encoding, not just decoding.
Traced x509_ed25519.h and zuse_cert_devblock.h before scoping: a regular user's cert has a fully separate trust root from the capsule-PKI chain (signed by Zuse's own on-device key, not the offline root CA/snakeoil intermediate), so verification is a single ed25519_verify() call, no chain walk. Corrects D.4's earlier "no new crypto work needed" claim -- x509_extract_ed25519_pubkey() deliberately stops at SubjectPublicKeyInfo, so verifying (not just reading) a cert needs new DER-walking code to capture the TBSCertificate byte range and signature. Decisions: X.509/DER format, drive_uuid bound via the cert's serialNumber field (avoids needing extension parsing), revocation deferred, cert lives in homeblocks_sig_t's already-reserved cert_offset/cert_devblocks.
WIREBIND traced against live capsule_birth_baby()/dispatch_init_forth() and found to have no real mechanism behind it yet -- depends on CERTVERIFY (identity-authentication) and a new RUNCAP mechanism for per-identity VM content, neither shown in the §E graph before now. Followed the thread into RUNCAP: capsule_birth_baby() is already generic, so RUNCAP needs only a heap-built single-entry capsule directory, not new birth machinery. Repurposes homeblocks_sig_t's now-dead blockmap_offset/blockmap_devblocks fields (per BMAPFMT, §F.4) to point at the identity's init source instead. Also captures a user-pool scope clarification: a thumbdrive is a user's pool by default, uncontested; FIRSTTOUCH's claim logic applies only to system-device extension.
Fourth node in the iterative Q&A pass, worked conversationally step by
step: state field justified against blk_bam_entry_t precedent and the
MIGSM/UNCLEAN nodes' own needs; ACL ownership tied to the same VMIdentity
pubkey representation decided for ACLKEY; ACL check ordering grounded in
vm.c's live fast-deny word-execution pattern.
Biggest finding: BLK_META_PER_BLOCK's existing 341x3-into-1KiB packing is
exactly the "3-block cluster + 1KiB metadata" shape raised in discussion --
it's blk_meta_t, with real wired accessors (blk_get_meta/blk_set_meta) but
confirmed zero callers anywhere in the codebase, and stale POSIX-flavored
ownership fields (owner_id/permissions/acl_block) that predate the
anti-POSIX principle and the pubkey-based identity model.
Decided: BMAPFMT is not a new structure, it's repurposing blk_meta_t
(distributed ownership/ACL/state per block, not a separate centralized
table) -- flagged that this makes homeblocks_sig_t's reserved
blockmap_offset/blockmap_devblocks fields unnecessary. New field layout
for the 40-byte security/ownership block: an 8-byte owner pubkey
fingerprint, a fast-deny acl_allow bit, and deliberate reserved slack
per "flexibility until we understand the recipe."
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U14ET9CWAtbQMbYqomKgXd
Third node in the iterative Q&A pass: re-checked sk_repl_idle() and the
bot_msc_attach_pending/detach_pending doc comments directly against the
original Milestone 2 punch-list wording. The flag-set-by-xHCI,
flag-consumed-by-sk_repl_idle() pattern isn't literally a registered
callback but achieves the same documented decoupling goal
("keeps xhci.c decoupled from block_subsystem.c"), confirmed live on all
three arches. Closed as written.
Recorded a handoff note for WIREBIND's own future scoping: reuse the
existing homeblocks_sig_check() result as the branch point (recognized
drive -> cert-verify+birth, blank/foreign -> stays plain block storage)
rather than inventing new hotplug detection. Updated the §E graph's
HOTPLUG node from partial to done.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U14ET9CWAtbQMbYqomKgXd
Second node in the iterative Q&A pass: traced acl_mode/acl_allow/acl_pinned
to DictEntry (per-word, not per-VM) before proposing anything, confirming
"reuse ACL" could only ever mean reuse the pattern, not the data. Decided:
a new VMIdentity type in its own header (mirroring the existing VMUuid
precedent, not another inline VM struct field), Zuse keeps an always-allowed
but explicit-acknowledgment override, and console/VM binding stays freely
retargetable (no one-way pin).
Also captured a scope expansion surfaced during this pass: identity is a
general per-VM primitive needed by Hera/Hermes/Artemis/Console too, not
just user thumbdrives, plus two new standing items (a full codebase
scavenging audit, and v2.0.0 as the eventual release target) in new §D.5.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U14ET9CWAtbQMbYqomKgXd
First pass of the iterative Q&A planning loop over §E's dependency graph:
traced the existing READ(10) implementation in xhci.c to establish that
WRITE(10) is a direct mirror (data direction, new SCSI opcode, new BOT
state) rather than new protocol work, then recorded the three scoping
decisions made (read_only flip timing, QEMU disposable-image validation
target, scope boundary excluding MINT/DETACH) in new §F.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U14ET9CWAtbQMbYqomKgXd
No code changes -- per direct request to represent the accumulated
Milestone 2/3/5 punch-list items plus D's Tripod-vision gaps as a graph
rather than flat lists, since several items turn out to be the exact
same open question asked in different places, and several converge on
the same blocker.
Mermaid dependency graph in FABRIC-3.md §E, cross-referencing:
- WRITE(10) (Milestone 2) as a true hub: independently gates the
block-map write path, the ongoing MINT word, detach/flush-back, and
all real-hardware testing -- landing it once unblocks four
separate-looking fronts.
- Milestone 5's "key/lock data shape" and D.4's "ACL bumps and holes"
gap are literally the same open question, not two separate ones.
- Runtime capsule construction (a D.4 detail) sits on the critical path
to the MINT word, not a side note.
- Message-bus migration has three currently-unbuilt hardwired
prerequisites, confirming it's correctly last in this whole area.
- Only 4 of the ~20 nodes are genuinely standalone; everything else
connects to at least one other open item.
No ordered plan yet -- this is the graph itself, not a sequence.
Documented as the input to the next iterative planning pass.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U14ET9CWAtbQMbYqomKgXd
No code changes -- continued design capture, per direct request to
link today's vision into the existing FABRIC.md/FABRIC-2.md material
("the existing pile of dirt") before planning.
Mined FABRIC.md's original Stadium theory (§17.1, §20, §24) and found
the EXPIRE-as-TTL correction wasn't just cleaner once "session=VM"
landed -- it was required from the start: the foundational
patron/departure table already says VMs depart via heat decay (COOL),
never TTL (TTL only ever governed messages/ACLs). §20's outer/inner
Stadium nesting already anticipated "attach = admit a VM" as a case,
so no new Stadium theory is needed, only a new admission trigger.
§24's identity-stability rules don't block session-state round-
tripping across separate attaches either way.
Mined FABRIC-2.md and found real grounding for two more decisions: the
acl_pinned one-way-ratchet was already identified as the right shape
for both Zuse's "burn" and console-session ownership, just never built
past word-execution gating -- and the real Hermes message shape
(MSG-CELLS, 9 fields, out-of-line payload, MSG-ALLOC/CH-ALLOC/
MSG-DELIVER) gives message-bus migration a concrete target instead of
an abstract goal. Confirmed empirically that today's xHCI hotplug
attach chain is 100% hardwired, zero messaging anywhere in it -- the
real baseline to migrate from.
Captured the pentagon topology: "just to get a user, 5 VMs are needed"
-- Hera, Hermes, Artemis, the user's own VM, and the Console, fully
interconnected (K5, a pentagon with every diagonal drawn). Flagged the
Console as a full peer node, not the passive relay D.3's flow
description implied -- reconciling that phrasing against the five-node
picture is new open work.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U14ET9CWAtbQMbYqomKgXd
No code changes -- pure design capture, per direct request ("capture
EVERYTHING first then we'll build a plan").
Core correction: a session IS a VM (Zuse is a player in the Stadium
fabric like any other, not a special boolean flag on Hera). This
supersedes an in-progress plan this session to implement EXPIRE as a
Stadium-TTL sweep on the zuse_session boolean -- caught mid-research,
before any code was written. Session end = VM detach, much closer to
the existing COOL/capsule_vm_kill() path than a new TTL mechanism.
Captured the full attach/mint flow: idle-loop thumbdrive watch,
cert-only auth (no password/username, no central user directory),
runtime capsule construction from drive content, ACL-based console/VM
binding (resolves Milestone 5's "reuse ACL-PIN vs. new primitive"
question in favor of reuse), ongoing MINT, and deferred detach/flush-
back. Standing completion criterion: nothing here is done until
hardwired calls are replaced by real Hermes messages.
Sorted the resulting gaps into answered (chain-of-trust mechanism,
ACL-reuse decision, no-central-directory) vs. genuinely deferred
(runtime capsule construction, exact ACL comparison semantics,
message-bus migration scope, polymorphic block-boundary behavior,
SSD-store scope, session state round-tripping, and the underlying
WRITE(10) hard blocker). Also flagged a small unrelated bug: the
prompt should read (Zuse)ok>, not zuse)ok>.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U14ET9CWAtbQMbYqomKgXd
Before flipping, found CAPSULE_SIG_MISSING (no signature at all) is the
normal state everywhere except this machine -- CI and any other
checkout have no access to the offline key, by design. Refusing on
MISSING the same as INVALID would brick boot everywhere but here.
Decided (on request): enforce ONLY on CAPSULE_SIG_INVALID (a signature
that IS present but doesn't verify -- unambiguous tampering/corruption
evidence). MISSING/NO_ROOT_KEY stay WARN-only permanently.
All three capsule_birth.c call sites now return CAPSULE_RUN_ERR_INVALID
on CAPSULE_SIG_INVALID, after logging the same WARN as before.
Verified on all three architectures, both directions, per the original
rollout commitment: positive case (real signed capsules) reboots clean
with zero warnings on amd64/aarch64/riscv64. Negative case (same
one-byte signature corruption used for the WARN-only proof, on Mama's
own init.4th) now genuinely refuses identically on all three:
"capsule sig: init.4th: INVALID" then "Init: Mama birth FAILED". The
feared "no ok> at all" blast radius didn't materialize -- kernel_main.c
already had graceful error handling for a failed Mama birth (log and
continue, pre-existing code); the kernel reaches a degraded ok> rather
than crashing, on all three architectures. Final acceptance pass (real
signed capsules, tampering reverted) clean on all three.
Milestone 6 is now fully closed except magic-number content-type
detection (shared with Milestone 4, separate scope, not started).
Documented in FABRIC-3.md.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U14ET9CWAtbQMbYqomKgXd
--manifest mode's file scan is a completely separate code path from
build mode (only ever walks .4th files, never the embedded PKI cert or
font capsule) -- extended it to accept the same optional --sign-key
<path> prefix build mode already has, factoring the key-loading code
into a shared load_sign_key(), so the manifest can report real
per-capsule signing status without touching or requiring a rebuild of
capsule_generated.c.
New "Signed" column on the capsule summary table: yes/no when
--sign-key was given, n/a (with an explanatory footnote) when it
wasn't -- never a bare blank that could be misread as "unsigned".
Makefile.starkernel's manifest-generation call site now passes the same
SIGN_KEY_ARGS the real build uses, so capsules/BLOCK_MAP.md reflects
this machine's actual signed state by default.
Verified: clean compile, BLOCK_MAP.md correctly shows "yes" for all 31
tracked capsules on a real signed build; a quick amd64 boot (no kernel
code touched, host tooling only) confirmed no regression.
This closes every open Milestone 6 item except magic-number
content-type detection (shared with Milestone 4, not started) and the
hard-refuse flip (deliberately deferred). Documented in FABRIC-3.md.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U14ET9CWAtbQMbYqomKgXd
First attempt shelled out to `openssl pkeyutl -sign` (fork/execlp, not
system() -- avoided shell string interpolation of the key path).
Corrected on request: no new external host binary dependency when the
repo's own code can do the job -- same standing preference as the
earlier anti-file correction. Rewritten to link ed25519_sign() (already
verified against OpenSSL in Phase B) directly into mkcapsule.
New tools/pkcs8_ed25519.c: a narrow DER walker (same shape as
x509_ed25519.c, deliberately not shared -- small enough that
duplicating a few TLV-walking lines beat threading a header between the
kernel crypto tree and host tooling) extracting the raw seed from the
intermediate's PKCS#8 private key, plus a minimal self-written base64
decoder (PEM is openssl genpkey's default output; no decoder existed
anywhere in the repo). Verified end-to-end before wiring anything in:
the extracted seed's derived pubkey matches the cert's exactly, and a
full self-contained sign+verify round-trip (zero openssl) passes.
CapsuleDesc had no spare bytes, so signatures live in a new parallel
CapsuleSigEntry array, emitted by a new `mkcapsule --sign-key <path>`
flag (omitted/missing key -> has_sig=0 everywhere, graceful, not a
build failure -- CI has no access to the offline key).
New capsule_sig.c/.h: capsule_verify_signature(), a separate function,
not folded into the already-tested capsule_validate(). Finds and caches
the embedded intermediate cert's pubkey once per boot, then verifies
against it. Wired into all three capsule_validate() call sites in
capsule_birth.c via log_message(LOG_WARN, ...) -- never refuses yet,
per the earlier staged-rollout decision.
Verified independently, both directions, live in the real kernel: a
full clean build (38 signed capsules) boots clean on all three
architectures with zero warnings. Separately, hand-corrupted one byte
of Mama's own init.4th capsule's stored signature (not its payload/hash,
which capsule_validate() already catches and would have masked the
test) and rebuilt just the changed object: produced exactly "capsule
sig: init.4th: INVALID -- signature does not verify" on boot, and the
kernel still reached ok> -- proving warn-only doesn't refuse anything
yet. Reverted before the final, untampered 3-arch acceptance pass.
Still open: flipping WARN to hard-refuse (separate, deliberate step)
and the BLOCK_MAP.md signature-status column. Documented in FABRIC-3.md.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U14ET9CWAtbQMbYqomKgXd
Root CA + snakeoil intermediate generated entirely offline
(/home/rajames/CLionProjects/lithosananke-ca/, outside this repo,
private keys chmod 600) per this milestone's own requirement: Ed25519,
root self-signed 20-year validity, intermediate real-CA-signed
(CA:TRUE, pathlen:0), chain verified via openssl.
Snakeoil intermediate embedded as a capsule (capsules/pki/
snakeoil-intermediate.der) -- confirmed the font-capsule precedent
needed zero new infrastructure, any non-.4th file under capsules/
embeds verbatim already.
New x509_ed25519.c: a from-scratch, narrow DER walker (not general
ASN.1/X.509, per this milestone's design decision) extracting the raw
Ed25519 pubkey from a cert's SubjectPublicKeyInfo -- handles the
optional v3 version field, verifies the AlgorithmIdentifier OID is
Ed25519 rather than assuming, handles both DER length forms. Verified
against ground truth: the extracted key from the real embedded cert
matches openssl's own reported pubkey byte-for-byte; refusal path
checked against truncated/garbage/empty/wrong-algorithm (real RSA cert)
input. Compiles clean on all three architectures.
Still open: mkcapsule signing step, wiring ed25519_verify() into
capsule_birth.c's three validate call sites (landing warn-only first,
per decision -- a bug here could stop every capsule from birthing,
including Mama's own, on all three arches), and the BLOCK_MAP.md
signature-status column. Documented in FABRIC-3.md.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U14ET9CWAtbQMbYqomKgXd
Replaces the crashed NVRAM approach entirely. New
include/starkernel/zuse_cert_devblock.h: a standalone on-disk record
(magic + version + 32-byte seed + 32-byte pubkey + a real CRC-64/ISO
from day one, same discipline homeblocks_sig_t established) occupying
devblock_from_top=0 of the fence. Its own header, not inlined at the
boot call site, since the still-open MINT word will be a second
consumer of this exact format.
kernel_main.c's mint-or-load logic now reads the fence, installs an
existing valid cert, or mints fresh via virtio_rng+ed25519_keygen and
writes it. Runs right after virtio_rng_init(), before
capsule_birth_mama() -- unlike the crashed NVRAM attempt, raw block I/O
against Artemis's already-proven device has no boot-timing risk, so the
earlier "re-invoke ACL-ZUSE-BOOT after Mama birth" workaround is gone;
ACL.4th's self-activating ACL-ZUSE-BOOT sees a correct cert on its one
ordinary pass.
Verified independently across every real scenario, never trusting the
kernel's own report: fresh mint decodes correctly on disk with a CRC
confirmed by a from-scratch Python re-implementation of the algorithm;
a reboot without reformatting loads back byte-for-byte identical
seed/pubkey (genuinely "mint once, ever"); a pre-fence volume refuses
cleanly (no crash, no silent data loss, honest "not persistent"
reporting); the real, untouched disk/artemis.img exercises the same
graceful-refusal path identically on all three architectures.
Phase 8's core arc is now functionally complete: real entropy -> real
signing -> real anti-file block-native persistence -> a first-boot mint
that survives reboots. Still open: the ongoing MINT word for minting
additional regular users. Documented in FABRIC-3.md.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U14ET9CWAtbQMbYqomKgXd
Corrected meta_fence_blocks units from "Forth 1 KiB blocks" to 4 KiB
devblocks (matching bam_devblocks/reloc_devblocks) before anything
depended on the original meaning -- a clean fix, not a migration. This
let the fence fold directly into compute_totals_from_B()'s existing
payload4k formula (total_devblocks - 1 - B - R - F) instead of a
separate user_blocks subtraction: total_blocks/user_blocks/free_blocks
all shrink correctly for free, in both the fresh-format and reload
paths, from one formula change.
New blk_meta_zone_read()/blk_meta_zone_write() -- raw, unpacked 4 KiB
devblock I/O, same shape as the header/BAM/reloc-table regions,
addressed by devblock_from_top counting down from the device's last
physical devblock. Refuses rather than clamps if the index exceeds the
on-disk meta_fence_blocks. C-only, no FORTH word wraps either -- same
discipline as vm_zuse_cert_install(), which will be this zone's first
real tenant.
Verified independently at every step, never trusting the kernel's own
report: capacity math cross-checked against a from-scratch Python
recomputation of the same formula (exact match); accessor correctness
via a temporary probe (written/run/captured/reverted) that wrote a
known pattern and read it back, then independently confirmed via a raw
read of the disk image at the exact expected physical byte offset.
Full 3-arch acceptance boot against the real, untouched disk/artemis.img,
probe code fully reverted -- clean, conservation intact.
Still open: wiring vm_zuse_cert_install() to actually persist through
these accessors, and the MINT word itself. Documented in FABRIC-3.md.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U14ET9CWAtbQMbYqomKgXd
Corrected substrate: this OS is anti-POSIX, anti-file by design -- the
prior "dedicated system-identity disk" framing was wrong vocabulary,
caught before any code was written (saved as
feedback_no_files_anti_posix.md). The real primitives are
content-addressed capsules and raw LBN blocks, never a filesystem.
Design (agreed on request): a growable metadata fence at the TOP of a
device's block space, mirroring block_subsystem.c's existing bottom BAM
reservation from the opposite end -- the two grow toward each other,
never colliding, same shape as a stack/heap. Starts at
BLK_META_FENCE_INIT (128 blocks), explicitly never RAM-backed. Reuses
Artemis's already-attached, already-proven virtio-blk device -- no new
device. Rejected reusing BAM's own reserved zone directly: those blocks
are fully claimed by BAM bookkeeping, not free space.
Step 1 only: new meta_fence_blocks field in blk_volume_meta_t, appended
after reloc_devblocks and carved from _pad[] -- identical graceful-
default technique reloc_devblocks already established (a pre-existing
volume reads it back as 0, not a format break). Added a compile-time
_Static_assert on the struct's total size, same discipline
homeblocks_sig.h uses -- caught a real bug immediately: the hand-summed
_pad[] formula was off by 4 bytes (a compiler alignment gap the manual
count missed), found via offsetof() rather than re-deriving by hand.
Worked against disposable clones throughout, never the real
disk/artemis.img (ARTDISK is ?=-overridable) -- artemis-metafence-fresh.img
(blank, fresh-format path) and artemis-metafence-test.img (copy of the
pre-existing artemis.img, graceful-default-on-reload path), kept as
regression fixtures matching disk/README.md's existing convention.
Verified independently via direct byte reads of the disk image, not the
kernel's own log output (log_message(LOG_INFO,...) doesn't reach serial
in this build -- unrelated pre-existing gap): fresh format writes 128 at
header offset 184, a reboot without reformatting preserves it, the old
pre-fence image reads back 0. Full 3-arch acceptance boot against the
real, untouched disk/artemis.img also clean.
Allocator (user_blocks math) and zone read/write accessors both still
open -- next steps, documented in FABRIC-3.md.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U14ET9CWAtbQMbYqomKgXd
Cert storage expanded from the old 16-byte placeholder to a real
32-byte seed + 32-byte pubkey. vm_zuse_cert_install() now has a
kernel-side duplicate in src/starkernel/vm/vm_core.c -- the kernel
build's VM_EXCLUDE list drops src/vm.c entirely (same reason
vm_set_base() already has two independent copies), so the hosted-only
version added earlier this session was never actually linked into the
kernel. FORTH-side ZUSE-CERT-LO@/HI@ replaced with ZUSE-PUBKEY@ (i -- u)
over the public half only; ACL-ZUSE-BOOT now checks
ZUSE-CERT-INSTALLED? before authenticating instead of unconditionally.
Attempted NVRAM-based persistence (GetVariable/SetVariable) for the
first-boot mint flow: page-faulted inside OVMF's variable service
(CR2 in the flash MMIO window). Moving the call site to match the one
proven-safe existing SetVariable call site in this codebase produced
the identical crash -- not a timing issue. Localized with debug
markers (one boot): GetVariable works; SetVariable with real data
never returns. The existing "working" precedent call is actually a
delete-of-nonexistent-variable (size=0, data=NULL), a cheaper path
that never touches flash, so it proved nothing about real writes.
Root cause: this kernel's VMM never maps the region OVMF's variable
service needs for real flash writes -- a genuine gap in UEFI runtime-
services support, not Zuse-specific, and not obviously fixable in a
3-arch-uniform way (flash window location is firmware/arch-specific).
Independently, storing the raw seed in RUNTIME_ACCESS NVRAM would have
been a real security defect regardless of the crash -- readable by any
later-loaded UEFI app or the booted OS.
Reverted to a known-safe state: all NVRAM/mint code removed from
kernel_main.c, init.4th's ACL.4th line back to its documented
commented-out default. Verified clean compile and clean boot on all
three architectures. Cert storage expansion (the part that works)
stays. A dedicated system-identity disk (virtio-blk, already proven
for writes via Artemis) is the recommended next substrate -- not yet
decided or built. Full investigation documented in FABRIC-3.md.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U14ET9CWAtbQMbYqomKgXd
Scoping Phase C (the MINT word) surfaced a real blocker: "mint one
Zuse, ever" needs the cert to survive reboots, but the qemu target
copied a fresh, pristine OVMF_VARS.fd on every invocation -- a
UEFI-NVRAM-based cert would never persist under this project's own
normal test workflow. Digging further, aarch64 had no persistent NVRAM
store at all (single -bios arg, no split VARS pflash like amd64/riscv64).
Fixed rather than switching storage substrates: amd64/riscv64 now only
copy the VARS template if the destination doesn't already exist, so
`clean` (which deletes the whole build tree) is the bleach step and a
bare `make qemu` preserves NVRAM -- matching the existing "always clean
before qemu" acceptance convention exactly. aarch64 restructured to
split CODE(ro)/VARS(rw) pflash drives matching the other two, with a
graceful fallback to the old -bios mode on hosts without split firmware.
Also resolves two design questions before any cert code: Zuse doesn't
need Milestone 6's CA (that's the capsule-signing chain, a separate
trust domain -- Zuse is a self-sovereign instance-local root of trust),
and flags that this session's own earlier vm_zuse_cert_install() storage
(16 bytes) is too small for a real Ed25519 keypair.
Verified: all three architectures boot clean to ok> with the new pflash
arrangement, Stadium conservation intact, no panics or guest errors.
Infrastructure-only -- no cert code yet. Documented in FABRIC-3.md.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U14ET9CWAtbQMbYqomKgXd
Extends the previously verify-only ed25519.c with ed25519_keygen() and
ed25519_sign() per RFC 8032 5.1.5/5.1.6, reusing every point-arithmetic
primitive verify already had -- only seed expansion/clamping and
per-message nonce derivation are new. Signing is deterministic; only
keygen ever touches entropy, via a caller-supplied seed (virtio_rng,
Phase A) -- keygen still generates nothing itself.
New scalar_muladd() (scalar25519.c) for signing's S = (k*a + r) mod L,
the one scalar op verify never needed. Schoolbook multiply into a u128
wide accumulator with one final carry pass -- deliberately the same
shape as fe25519.c's existing multiply, which has a documented history
of a real bug from carrying mid-accumulation instead of in one pass.
Verified against an independent implementation, not self-consistency:
a throwaway host harness against Python's cryptography library (OpenSSL-
backed) across 6 trials (5 random seed/message pairs + the empty-message
case) produced byte-for-byte identical pubkeys and signatures every
time. Clean compile on all three architectures and a full 3-arch QEMU
acceptance boot, conservation intact, no panics or guest errors.
Nothing calls the new functions from the live kernel path yet -- that's
Phase C (the MINT word itself), still open, documented in FABRIC-3.md.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U14ET9CWAtbQMbYqomKgXd
The kernel's ed25519_verify() is deliberately verify-only -- no signing,
no keygen, no entropy source. That conflicts with the on-device MINT
word vision (Zuse signing new user certs live at runtime), so this
reopens that constraint on request rather than reshaping MINT around
verify-only.
vm_uuid.h already found the real gap: amd64 has RDRAND, riscv64 has Zkr,
but QEMU's aarch64 CPU models have neither -- confirmed against QEMU
10.2.1. A deterministic PRNG (fine for VM UUIDs) is not safe for key
generation, so this adds a virtio-rng device instead of a per-arch split:
real host entropy, identical guest-side protocol on all three arches.
New src/starkernel/virtio/virtio_rng.c + include/starkernel/virtio_rng.h,
transport plumbing mirroring the existing virtio_blk.c driver exactly.
Wired into kernel_main.c boot, -device virtio-rng-pci added to all three
QEMU targets.
Verified live (temp probe, written/run/captured/reverted): 16 real bytes
pulled through the full request/notify/poll round trip on all three
arches, three different values confirming real entropy. Final boot
against the reverted, permanent code: clean compile, clean boot to ok>
on amd64/aarch64/riscv64, Stadium conservation intact, no panics or
guest errors.
Ed25519 keygen/signing itself (Phase B) and the MINT word design
(Phase C) remain open, documented in FABRIC-3.md.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U14ET9CWAtbQMbYqomKgXd
Found that a pinned CONSTANT is not actually tamper-proof: ACL-PIN only
blocks redefinition, not a >BODY-then-store on the word's existing data
field. Moves the Zuse cert value into C-only VM struct fields
(zuse_cert_lo/hi + zuse_cert_installed fuse bit) with a one-time
vm_zuse_cert_install() and read-only ZUSE-CERT-LO@/HI@/INSTALLED? FORTH
accessors, closing the tamper path structurally instead of by convention.
Deletes the now-insecure ZUSE-CERT-LO/HI CONSTANT words from zuse.4th.
vm_zuse_cert_install() has no caller yet -- the real mint flow (Milestone
6 CA, the MINT word) is still open; this is storage + accessors only, not
a stand-in mint. Documented in FABRIC-3.md. Verified: hosted build clean,
mkcapsule --lint clean (31/31), clean boot to ok> on amd64/aarch64/riscv64
with Stadium conservation intact and no panics.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U14ET9CWAtbQMbYqomKgXd
Captain Bob's correction. 64MB (disk/zuse.img, usb-thumbdrive-test.img)
was always just an arbitrary QEMU-test convenience size, never a
real-world constraint -- but the docs and script didn't say so
explicitly, and an earlier memory's "16GB reference size" phrasing
(already hedged as tentative) risked reading as a decided target.
Audited the actual format for hardcoded size assumptions: none found.
homeblocks_sig_t already carries its own metadata_devblocks field,
recording whatever size a real drive's partition actually is.
Changes: scripts/bleach_zuse_img.sh gains a --size-mb override (tested
both the override and the unchanged default); disk/README.md's
zuse.img entry and FABRIC-3.md both now state the point explicitly;
the memory file and its MEMORY.md index line corrected to match (the
GPT layout's design point is the *proportions* -- small metadata
partition, everything else block storage -- not any absolute size).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CXjAPTEKrgY2Mrk25KoLDn
Resolves the acl_pinned punch-list item's open question: credential
data (ZUSE-CERT-LO/HI, ACL-CA-KEY-LO/HI) are CONSTANT words, i.e. real
DictEntrys, and acl_pinned's enforcement (vm_create_word()'s
unconditional shadow-refusal for any pinned name) already covers this
generally -- no new flag needed, zuse.4th's ACL-ZUSE-BOOT already pins
both cert constants today.
That investigation surfaced a real gap: ACL-ZUSE-BOOT pins the cert
constants unconditionally on every boot, before any legitimate mint
could ever run, permanently locking in the 0 placeholder on the very
first boot. This directly shaped Captain Bob's next design pass: a
dedicated zuse.img test thumbdrive, "bleachable" back to pristine
state for repeated first-boot testing; a one-time mint-then-pin flow
(fixing the gap above); a separate ongoing S" name" MINT word for
minting additional regular users; and an explicitly-deferred Zuse
recovery path question.
This commit is the first piece: disk/zuse.img (64MB blank, matching
the existing USB-fixture convention) + scripts/bleach_zuse_img.sh
(idempotent reset). Verified live via QMP hotplug -- reads back as
HOMEBLOCKS_SIG_BLANK, correctly simulating a genuine first boot.
Deliberately flat/raw, not GPT-partitioned, matching
homeblocks_sig_check()'s current sig_start_fblock=0 assumption; both
move to a real GPT-relative offset together once a parser exists. No
kernel code touched -- host-side test tooling only, no 3-arch
acceptance boot needed.
Still open: the mint-then-pin boot fix, the MINT word, Zuse recovery.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CXjAPTEKrgY2Mrk25KoLDn
Wired into sk_repl_idle()'s USB hotplug attach handler, right between
blkio_usb_open_msc() succeeding and blk_subsys_attach_device() -- logs
a distinct message per outcome (recognized / blank-or-foreign /
bad-version / bad-crc / read-error).
The "refuse" half is deliberately not implemented -- there is nothing
real to gate yet. blkio_usb.c has no SCSI WRITE(10) support at all, so
there is no write path today to refuse; attach currently only enables
read-only access, which is also the general-purpose USB block I/O
path this repo already relies on for unrelated testing, not
exclusively a home-blocks identity workflow. Refusing attach on blank
media would break that legitimate use without protecting anything
real -- same "don't build ahead of a real caller" reasoning EXPIRE's
deferral used. Refuse belongs on the write path once WRITE(10) exists.
sig_start_fblock is hardcoded to 0 at the call site -- correct for
today's unpartitioned raw test/real media (no GPT parser exists yet),
flagged in the comment as the one place that changes once a real
GPT-partition-relative lookup exists, isolated from
homeblocks_sig.c's own location-agnostic check logic.
Verified live: hot-attached disk/usb-thumbdrive-test.img (blank media)
through a running amd64 instance's QMP socket (blockdev-add +
device_add usb-storage) -- captured exactly 4 real TUR+READ10 BOT
cycles (matching the header's 4 forth-block span) followed by the
correct "not recognized" warning, then normal attach completing
successfully afterward (no regression). Conservation intact, no
panic. Clean zero-warning compile and clean boot on all three
architectures.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CXjAPTEKrgY2Mrk25KoLDn
Real, complete verification logic -- not yet wired to any write path.
homeblocks_sig_check(dev, sig_start_fblock, out_sig) reads the 4
consecutive 1KB blkio forth-blocks the 4KB header spans, verifies
magic -> version -> CRC-64 in order, returns HOMEBLOCKS_SIG_OK/_BLANK/
_BAD_VERSION/_BAD_CRC/_READ_ERROR. Reuses block_subsystem.c's existing
CRC-64/ISO (compute_crc64, previously static/file-local, now exposed
via block_subsystem.h) rather than a second CRC implementation --
same algorithm already proven via per-block checksums. Takes the
header's starting block as a plain parameter rather than resolving it
internally: verifies a signature given a location, finding that
location (GPT-partition-relative) stays the caller's job.
Verified against the actual shipped code, not a reimplementation: a
standalone host test links the real homeblocks_sig.c against a fake
in-memory blkio_dev and exercises all four outcomes -- blank media,
a correctly-minted header (round-trips drive_uuid/minted_time_ns), a
flipped CRC, an unrecognized version. All four pass. A full
QEMU-hotplug live test isn't proportionate yet since nothing calls
this function from the live kernel path -- wiring it into the attach
path is the next punch-list item. Clean zero-warning compile and
clean boot on all three architectures confirms no build/link
regression from exposing compute_crc64 and adding the new source
file to every kernel build.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CXjAPTEKrgY2Mrk25KoLDn
Implements the design from the previous commit as-is: homeblocks_sig_t
(4096 bytes, magic+version+drive_uuid+timestamp+cert/blockmap offset
reservations+real hdr_crc), HOMEBLOCKS_SIG_PACK/_GET_MAGIC/_GET_VERSION
macros mirroring CAPSULE_MAGIC_PACK's bit layout, and a C99
compile-time size assertion matching stadium.h's own discipline.
Verified standalone (sizeof == 4096, clean under -std=c99 -Wall
-Wextra -Werror) -- nothing consumes this header yet, so no
functional kernel change and no 3-arch acceptance boot needed for this
step.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CXjAPTEKrgY2Mrk25KoLDn
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
The June 2026 campaign's +0.0054%-0.0088% number was cited as current,
but it measured the wrong thing under the wrong name -- the
Rolling-Window-of-Truth mechanism it was named after was dead code,
never reachable, and the measurement itself predates real compiler
optimization. Kept the original entry for historical record, added a
correction pointing to the actual current figure: +0.0603% ACL-TTL
enforcement overhead (FABRIC-2.md SS T), the same closure just applied
to FABRIC-3.md's stale re-measurement punch-list item.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CXjAPTEKrgY2Mrk25KoLDn
Corrects bookkeeping, not measurement. FABRIC-2.md Sections M-T
(2026-08-19/21) already re-ran this and found the original "ACL-RWT"
name was itself wrong -- the Rolling-Window-of-Truth mechanism it
named was dead code removed 2026-07-08, never reachable. What the
campaign actually measured was the live ACL-TTL mechanism. Final
accepted result: +0.0603% ACL-TTL enforcement overhead,
architecture-independent, CV=0.000% (FABRIC-2.md SS T,
project_acl_ttl_overhead_final.md). The checkbox was simply never
marked done when that work concluded -- no new campaign run.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CXjAPTEKrgY2Mrk25KoLDn
- docs/lithosananke/ROADMAP.md + M7.1.md: fixed stale "Branch: lithosananke"
(no such branch post-split), M7.1's "Design Complete" status (shipped
and live, redirected to FABRIC*.md), the M8/success-criteria
self-contradiction (OBSOLETE marking vs. unqualified live criterion),
and the stale AHCI/SATA claim for M9 (real implementation is
virtio_blk.c) -- also corrected BLOCK/BUFFER/UPDATE/FLUSH and block
device abstraction to [x] since both are confirmed live in
src/word_source/block_words.c and block_subsystem.c.
- Top-level ROADMAP.md: marked OBSOLETE (Captain Bob's call -- more than
"stale," the architecture/branch topology/terminology it describes no
longer exist), pointing to docs/lithosananke/ROADMAP.md and
FABRIC*.md for current status.
- docs/03-architecture/word-acl/DESIGN.md: fixed the ACL Phase 7
contradiction -- Phase 7 (LithosAnanke kernel parity) is independently
verified complete per .claude/CLAUDE.md, not "remaining"; removed the
stale lithosananke-branch-parity framing.
- VM-FLEET-ATTRACTOR-DESIGN-20260705.md's doe-campaign.4th "broken" claim:
investigated, ran SMOKE-CAMPAIGN live (completes clean, fleet heat
conserved) -- initially read as contradicting the claim, corrected
directly by Captain Bob: a clean execution trace doesn't disprove the
doc's actual argument (no real controlled-experimental-factor
mechanism). Confirmed accurate, left untouched.
- Isabelle/HOL pipeline-metrics model/C-struct mismatch: confirmed a real
proof-modeling gap (pm_last_accuracy_num/den has no analogue in the
real PipelineGlobalMetrics struct), not stale prose -- tracked here
rather than fixed, matching the .thy file's own scope boundary and
this project's standing caution that each Isabelle gap needs its own
subsystem model.
ACL-RWT DoE overhead re-measurement (the 6th item) intentionally not
started -- a full multi-architecture DoE campaign, not a doc-text fix,
holding for explicit confirmation given the scale.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CXjAPTEKrgY2Mrk25KoLDn
Decided directly on request, no code written. "ACLs -> EXPIRE" isn't
wrong in spirit but was aimed at the wrong unit: acl_ttl-hits-zero
always renews (never revokes), so it can't carry EXPIRE's
residency-ending meaning. The unit that actually has a real lifetime
and should be revoked is a zuse superuser session (Phase 8, not yet
built) -- authenticate, hold elevated privilege for a bounded time,
then actually drop back to non-zuse.
Resolves to: admit the session (not a per-word ACL entry, which would
be redundant with item 4.1's existing word patrons) as the Stadium
patron, once Phase 8 exists. Not in scope now -- there is no session
to admit regardless of any other choice, and building Stadium's
missing generic ttl-decrement/reap mechanism ahead of its only real
consumer would be speculative infrastructure, the same shape of
premature build the no-stubs standard exists to prevent, just
inverted. EXPIRE stays explicitly deferred until Phase 8 lands, with
a concrete trigger for revisiting it -- not abandoned, not left
ambiguous.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CXjAPTEKrgY2Mrk25KoLDn
Same fix as DELIVER, on request. COOL is real and live for both words
(item 4.1) and VMs (this session) -- stadium_evict()'s own universal
reservoir credit is the whole of what "cooling off the floor" means
for both, no extra payload action needed. stadium_dispatch()'s COOL
case now prints the departing patron's identity (word_id for a word,
0 -- the patron-zero convention -- for a VM) instead of "(stub)".
Verified live: both shapes fired correctly on the same boot --
"COOL identity=0" at Hermes's/Artemis's own explicit channel-eviction
self-test and again at their VM-patron eviction at PARITY:KILL,
"COOL identity=1" at a second channel eviction -- conservation intact
throughout. Clean zero-warning compile and clean boot with
conservation intact on all three architectures.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CXjAPTEKrgY2Mrk25KoLDn
Investigated on request. acl_ttl (DictEntry, per-word ACL-RECHECK
amortization) and StadiumPatronHeader.ttl (residency countdown) are
different mechanisms wearing the same name -- ACL-RECHECK always
renews (allow=1, fresh ttl), never revokes, so it doesn't resemble a
reap event at all. Separately, StadiumPatronHeader.ttl is completely
inert across the whole codebase: every candidate constructor sets it
to 0, nothing ever reads or decrements it -- the generic TTL-expiry
mechanism EXPIRE would fire from doesn't exist in Stadium's own engine
yet, a gap one level deeper than "ACL isn't wired to Stadium."
Recorded four open questions that need a real decision before any
code: whether "ACL patron" is even the right model, what unit would
be admitted (redundant per-word vs. a session-scoped patron once
Phase 8 PKI/zuse work lands), whether building Stadium's missing
generic ttl-reap mechanism is in scope here, and what the reap action
should actually do given ACL policy never revokes today.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CXjAPTEKrgY2Mrk25KoLDn
Words have been fully migrated and live via stadium_word_dispatch()
since item 4.1 -- this line just never got updated. Small, independent
doc fix flagged in FABRIC-3.md's punch list, addressed on request.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CXjAPTEKrgY2Mrk25KoLDn
Re-scoped on request. capsules/hermes/init.4th's MSG-ALLOC already
admits every message onto Stadium with SB-DELIVER, and MSG-FREE-NODE
(called from both MSG-ACK-LAST and heat-driven MSG-REAP) already
evicts it -- "behaviour=DELIVER (stub)" has been printing on boot logs
since at least 2026-08-05. The earlier "zero consumer, needs
substantial Hermes lifecycle mapping work" framing was wrong,
carried over unverified from FABRIC.md's old "open, not resolved" note
about which Hermes event maps to DELIVER vs. EXPIRE -- item 4.2
already answered that in code without the prose catching up. Same
documentation-drift class as the stale ONTOLOGY.md words note and the
earlier glibc misattribution.
Checked whether the dispatch body needed a real payload action the way
MIGRATE did: MSG-DELIVER (the FORTH word) already runs the actual
delivery (VM-EXEC of the payload) before eviction, decoupled from
Stadium reap -- so by dispatch time delivery is already done, same
shape as COOL, which needs no extra action beyond stadium_evict()'s
own universal reservoir credit.
Fix: stadium_dispatch()'s DELIVER case now prints the departing
message's real identity (DELIVER msg_idx=N, same shape as MIGRATE's
lbn= print) instead of a misleading (stub) label. COOL is in the
identical situation (real for both words and VMs) but left as-is --
out of scope for this pass, noted in stadium.c's own comment.
Also confirmed EXPIRE (ACL) is genuinely unscoped, not stale docs like
DELIVER turned out to be -- zero Stadium involvement anywhere in
ACL.4th/acl_recheck()/the ACL design doc. Stays open pending real
design decisions.
Verified live via a forced MSG-SEND/MSG-DELIVER-ALL/MSG-ACK-LAST
sequence from Hermes's own REPL context ("USE" now works after the
previous fix): "Stadium: dispatch cell=73653 behaviour=DELIVER
msg_idx=1". Clean zero-warning compile and clean boot with
conservation intact on all three architectures.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CXjAPTEKrgY2Mrk25KoLDn
capsule_vm_kill() had zero Stadium involvement (vm_cleanup()/sf_free()
only), and child-VM birth only ever called stadium_grant_quota() -- a
resource pool for the VM's own future word/block patrons, never
stadium_admit() for the VM itself. stadium_birth_hera() looked like a
precedent but admits Hera into her own quota as a permanently pinned
cell 0, which can never reach stadium_evict() -- not a working example
of COOL firing for a VM.
Adds size_t stadium_patron_cell to VMRegistryEntry. At birth, right
after the existing stadium_grant_quota() call, admits a candidate into
the new VM's own quota mirroring stadium_birth_hera()'s shape
(identity=0, mass=1, behaviour=COOL) but deliberately unpinned --
pinning would need a new "unpin" primitive (none exists) to ever evict
it later, and unpinned costs nothing since nothing wires COOL's
dispatch body to kill anything; the worst case of an unrelated natural
eviction is stale bookkeeping, tolerated the same way
stadium_word_forget() already tolerates staleness elsewhere. At
capsule_vm_kill() and capsule_vm_kill_all_nonmama(): stadium_evict()
the tracked cell if still resident, silently tolerating refusal
(already gone). stadium_dispatch()'s COOL case needed no new payload
body -- same as it already is for words, where COOL has no defined
extra action beyond stadium_evict()'s own universal reservoir credit.
On investigation this turned out not to be entangled with the
still-iterating Tripod/Zuse/messaging vision after all -- birth and
kill already funnel through two single choke points, so the earlier
deferral (previous commit) was overcautious.
Verified live: a second, new "Stadium: dispatch cell=... behaviour=
COOL" now fires immediately before every PARITY:KILL line, for both
Hermes and Artemis, distinct from the pre-existing COMMON-CH
word-eviction self-test's own COOL print. Conservation
(resident_sum + reservoir == Q48_ONE) intact throughout. Clean
zero-warning compile and clean boot on all three architectures.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CXjAPTEKrgY2Mrk25KoLDn
capsules/lib.4th:13-14 defined ": USE ( addr u -- ) EXEC ;" and the
same for RUN, shadowing the C-registered mama_word_use()/RUN primitives
(CLAUDE.md names both, with BIRTH, as untouchable C primitives) with an
unrelated "load/exec a capsule" meaning. This broke the interactive
USE-based VM-redirect (S" Artemis" USE printed "EXEC: failed: Artemis"
instead of redirecting), discovered while chasing FABRIC-3.md's
live-MIGRATE verification.
Traced every real caller before touching anything: RUN's alias was
dead code, never called anywhere as bare RUN. USE's alias had exactly
one real caller -- capsules/hermes/init.4th:397, intentionally
exploiting the shadow to load common:msg.4th right after lib.4th
itself loaded. Both aliases were pure EXEC wrappers with zero added
behavior, so this deletes both definitions outright and switches the
one real call site (plus its matching doc comment in
capsules/common/msg.4th) to call EXEC directly. No new names invented,
the C primitives untouched.
Verified live: Hermes still births and her COMMON-CH-eviction
self-test (depends on common:msg.4th having loaded) still passes;
interactively, S" Artemis" USE now correctly redirects the REPL and
prints "USE: now using Artemis". mkcapsule --lint clean (31/31).
Clean compile and clean boot with Stadium conservation intact
(resident_sum + reservoir == Q48_ONE) on all three architectures.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CXjAPTEKrgY2Mrk25KoLDn
Confirmed the real MIGRATE dispatch fires live: a temporary boot probe
(STADIUM-ADMIT + STADIUM-EVICT against the live Artemis VM, inserted
into the existing 4.6 self-test and reverted immediately after capture)
produced "Stadium: dispatch cell=63257 behaviour=MIGRATE lbn=100" with
blk_flush(100) firing and zero error -- closes the honest gap left open
in the previous commit. Interactive flooding alone couldn't reach this:
Hera's reservoir sits at the Q48_ONE/3 floor from boot self-tests, so
block-touch candidates pull 0 heat and can never out-density an
existing resident, a pre-existing reservoir-floor/eviction interaction
unrelated to this pass.
Also reports (not fixes, per CLAUDE.md) a real dictionary-shadowing bug
found while chasing this: capsules/lib.4th:13 redefines USE as EXEC,
shadowing the C primitive mama_word_use() (REPL VM-redirect) with an
unrelated capsule-loading meaning -- same for RUN at lib.4th:14. Same
bug class as the K-PUSH dictionary-shadowing issue.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CXjAPTEKrgY2Mrk25KoLDn
stadium_admit()'s mass==1 refusal looked like a hard blocker for 1024-byte
blocks, but stadium_word_dispatch()'s real candidate construction proves
Stadium cells carry pure identity/heat/bookkeeping, never the resident's
actual content -- a block patron follows the same shape (identity=LBN,
payload unused), so this was real, scoped work, not a case for stubbing.
New stadium_blocks.h/.c mirror stadium_words.c's admission/cooling shape,
keyed by (quota_slot, lbn) in a fixed-capacity open-addressing hash table
(tombstone deletion) instead of a dense array, since LBN space isn't
densely bounded like word_id. Wired into block_word_block()/buffer()/
update() (block_words.c), __STARKERNEL__-guarded. stadium_dispatch()'s
MIGRATE case now calls blk_flush(lbn) for real instead of printing
"(stub)". Three new Kconfig constants (STADIUM_BLOCK_HEAT_QUANTUM/
STADIUM_BLOCK_COOL_RATE_Q48/STADIUM_BLOCK_TRACK_CAP_MULT) mirror the
word-patron ones, same three-layer wiring.
VM-COOL/DELIVER/EXPIRE stay explicit punch-list items -- VM-COOL
deferred pending the still-iterating Tripod/Zuse/messaging vision,
DELIVER/EXPIRE are their own future subsystem integrations per
FABRIC.md's own "open, not resolved" notes.
Verified clean compile (zero warnings) and clean boot to REPL with
conservation intact (resident_sum + reservoir == Q48_ONE) on all three
architectures (amd64/aarch64/riscv64); BLOCK/BUFFER touches exercised
live from the REPL with no crash; a 22,000-distinct-block flood loop
against an artificially shrunk Stadium ran clean under heavy admission
load. A live MIGRATE console fire was not directly observed this
session (root-caused to a pre-existing reservoir-floor/density-eviction
interaction unrelated to this change, documented in FABRIC-3.md) --
flagged as an honest follow-up, not silently claimed.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CXjAPTEKrgY2Mrk25KoLDn
Investigated whether stadium_admit()'s mass==1 refusal blocks block-patron
Stadium admission -- it doesn't: stadium_word_dispatch()'s real candidate
construction confirms Stadium cells carry identity/heat/bookkeeping only,
never the resident's actual content, so a block patron (identity=LBN,
payload unused) fits the same pattern words already use. The real gap is
just that no LBN->cell_index residency map or touch-on-access hook exists
yet -- real, scoped, buildable work, not a blocker.
Deferred VM-COOL pending the Tripod final-shape vision Captain Bob laid
out (thumbdrive minting, one-time Zuse fuse-blow, messaging-only inter-VM
interaction, polymorphic block-boundary behavior) -- recorded in a new
§D so near-term Stadium work doesn't ignore it, without treating a
one-sentence vision as a ready-to-implement spec.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CXjAPTEKrgY2Mrk25KoLDn
FABRIC-2.md closed archival at ~4,400 lines / 51 open items, same reasoning
FABRIC.md itself was closed for at 7,595 lines -- continuing to append made
still-open work hard to find. All 51 open items carried forward into
FABRIC-3.md's new Section A, verified complete via programmatic diff against
the source (49 unique + 2 confirmed pure duplicates from FABRIC-2.md's own
F.3 cross-reference section, not dropped content). .claude/CLAUDE.md's
pointer note updated to name FABRIC-3.md as current.
New Section B: full audit of stadium_dispatch()'s four behaviour stubs
(MIGRATE/DELIVER/EXPIRE/COOL), triggered by investigating "words/VMs/blocks/
messages should all be on the same engine". Found the picture is more
nuanced than "everything's a stub" -- words are already fully live via a
separate bespoke mechanism (stadium_word_dispatch(), wired into vm_core.c's
real word-execution path, item 4.1), contradicting ONTOLOGY.md's stale
"not yet migrated" claim (flagged for a follow-up fix). MIGRATE (blocks)
and VM-COOL are genuinely stub with zero consumers; DELIVER (Hermes) and
EXPIRE (ACL) are substantial, undecided subsystem integrations FABRIC.md
itself already flagged as open, not touched here.
New standing rule, saved as memory feedback_no_stubs_or_todos.md: stub
implementations and TODO placeholders are never acceptable in this
workflow, in any language, ever -- triggered by finding stadium_dispatch()'s
stub handlers during this investigation.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CXjAPTEKrgY2Mrk25KoLDn
Implements the full design from the prior commit in one pass. resolve_lbn()
is the single choke point threaded through the ten public LBN-consuming
entry points (blk_get_buffer, blk_update, blk_flush, blk_is_allocated,
blk_mark_allocated, blk_mark_free, blk_is_valid, blk_get_meta, blk_set_meta,
plus blk_get_empty_buffer covered via delegation) -- an LBN->LBN redirect,
not a new storage allocator, since the LBN space is already unified across
every attached blkio_dev backend. VM window cache staleness across a
relocation reuses the existing blk_vm_check_epoch() mechanism from
Milestone 2h's hot-detach fix for free -- g.epoch bumps on relocation too.
Persistence lands in the same pass: two new uint32_t fields
(reloc_start/reloc_devblocks) appended after hdr_crc in blk_volume_meta_t,
carved from existing padding without moving any earlier field's byte
offset -- an old formatted volume's zeroed padding reads back as
reloc_devblocks=0 ("no reloc capacity"), gracefully, not a format-breaking
change. compute_totals_from_B() generalized to account for the new
reserved region. reloc_flush_to_disk()/reloc_load_from_disk() mirror the
BAM I/O functions' own absolute-devblock-addressing shape; the persisted
copy's owner is first_disk_slot() (already existed, already used for this
exact "which device is canonical" question by blk_get_volume_meta()).
blk_subsys_relocate_block() is a mechanical primitive only -- copies
content (staged through a local buffer, since obtaining the target's
blk_get_buffer() result can evict and invalidate the source's cache
pointer if they share a device), frees the source BAM entry, appends the
exception entry, bumps the epoch, flushes to disk. RELOCATE-BLOCK exposes
it to FORTH, no policy of its own (ACL's job, per this session's direction).
A first live-test attempt gave a false negative against disk/artemis.img
(predates reloc capacity, so relocation only ever existed in memory that
boot) -- traced to the test's own setup before being mistaken for a bug,
then re-verified correctly against a fresh volume (new fixture,
disk/artemis-reloc-test.img): relocated a RAMDRIVE block to the fresh
disk, confirmed live resolution through the redirect, then confirmed both
the redirect and the relocated content survived an abrupt QEMU kill and
full reboot. Also fixed three lingering "glibc" doc-comment
misattributions from Milestone 2h (the actual allocator is this kernel's
own kmalloc) that survived an earlier FABRIC-2.md-only correction. All
three architectures re-verified clean.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CXjAPTEKrgY2Mrk25KoLDn
Complete design, not just the earlier flag: resolve_lbn() as the single
choke point threaded through ten public entry points, LBN->LBN redirect
mechanism (no new storage allocator needed, the LBN space is already
unified across all backend-agnostic blkio_dev devices), VM window
staleness solved for free by reusing the existing epoch mechanism from
Milestone 2h's hot-detach fix, in-memory table shape, and on-disk
persistence via two new fields carved from blk_volume_meta_t's existing
padding (byte-compatible with old formatted volumes) using the same
absolute-devblock I/O pattern the BAM already uses. Ownership of the
persisted copy assigned to first_disk_slot() (already exists, already
used for this exact "which device is canonical" question), with the
multi-primary-device question for a future multi-SSD/cloud world
explicitly punted rather than hand-waved. Noted the known, separate
limitation: USB relocation targets aren't exercisable until WRITE(10)
exists in the xHCI driver -- verification will use two already-writable
devices instead. Policy (when to relocate, whether a target is validly
owned) stays ACL's job, not this primitive's.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CXjAPTEKrgY2Mrk25KoLDn
Milestone 3 direction from this session: ACL decides when to relocate
(capacity pressure or a compudynamics heat/cold signal), migration
expected rare not routine. Flagging only, not designing yet: current
lbn_to_slot() is pure contiguous-range routing, one device owns one
unbroken range -- incompatible with relocating an individual block to a
different device while its LBN stays fixed. Direction sketched (a sparse
LBN-to-actual-device exception table, consulted before the range walk,
zero cost for the common never-relocated case) but the actual structure
is still open. Block-migration implementation now explicitly depends on
this revision landing first.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CXjAPTEKrgY2Mrk25KoLDn
Dropped the hash-modulo-MAX_IDENTITIES approach: there is no way to bound
how many identities might ever exist, so no population size can be
pre-divided into slots regardless of hash function. Resolution: first
time an identity is seen, claim a range at the SSD's existing free-space
frontier (g.total_user_lbn, already used by every device attach) sized
to whatever it needs, write the assignment into the drive's own map;
every later visit just reads it back. No central directory, no quota,
matches Section U's existing requirements exactly.
Identity itself is a certificate signed by this project's own (not yet
created) CA root, extending Milestone 6's PKI design to users instead of
inventing a separate mechanism. Derivation-relevant value is the cert's
embedded pubkey, not its raw bytes -- a renewal shouldn't relocate an
already-allocated range.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CXjAPTEKrgY2Mrk25KoLDn
Checked the math with Captain Bob: a PBAM for ~15GB of user blocks needs
only ~1.92MB (15M blocks / 32768 per 4KB page), fitting easily alongside
identity/credential/PKI material in a 1GB reserved region. No partition
table needed -- same whole-device pattern artemis.img already uses today,
just with a generously fixed ~1GB reserved region instead of tight
bam_start+bam_devblocks packing. Eliminates the GPT-parser work item
entirely (no GPT code exists in src/starkernel/ today). Confirmed no
conflict with Milestone 8's USB boot drive, which is a separate physical
drive (flashed starkernel.iso) with its own independent GPT/ESP need.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CXjAPTEKrgY2Mrk25KoLDn
Makes blk_vm_flush_all() (block_words.c) non-static and declares it in
block_words.h -- it's already the entire implementation behind
SAVE-BUFFERS (block_word_save_buffers() is a one-line wrapper), so
sk_repl_idle() can call the exact same flush path outside word dispatch
without duplicating any logic. Cheap every idle tick regardless of dirty
state: every check inside is a small fixed-size scan, so no separate
pre-check was needed on top of it.
Caught a real bug via a live persistence test before trusting the
feature: the first version gated the flush on sk_repl_get_active_vm()
returning non-NULL, but NULL is that accessor's documented default
(Tripod's own USE-redirect override, "restore default dispatch") --
without an active USE redirect, the flush silently no-op'd for the
entire session. Confirmed live: wrote a byte via BUFFER (no
UPDATE/SAVE-BUFFERS), waited past the idle cadence, killed QEMU abruptly,
rebooted with the same disk image, read back 0 instead of the written
65. Fixed by threading the VM sk_repl_run()'s own loop already resolves
each iteration (g_repl_active_vm ? g_repl_active_vm : vm) down as a
parameter through sk_readline() into sk_repl_idle(), rather than trying
to re-derive it from an accessor with the wrong default. Re-ran the same
test after the fix: read back 65, matching the written byte -- the write
survived an abrupt kill with no explicit flush call anywhere in the
test, proving the idle-tick auto-flush genuinely ran.
All three architectures re-verified clean. FABRIC-2.md Section V item 6
and the corresponding Milestone 3 punch-list item marked done.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CXjAPTEKrgY2Mrk25KoLDn
block_subsystem.c is shared/vendored source -- its calloc()/free() calls
resolve to real glibc in the hosted build, but to this kernel's own
freestanding shims (src/starkernel/vm/host/shim.c, backed by kmalloc()/
kfree() in src/starkernel/memory/kmalloc.c) in the kernel build, which is
where the address-reuse bug was actually diagnosed live. The previous
writeup said "glibc's allocator" -- wrong environment entirely. Verified
kmalloc_aligned() is a plain first-fit walk from heap_head with no
coalescing, confirming the same free-then-immediate-same-size-alloc reuse
behavior originally observed, just attributed to the right allocator.
Caught by the user asking directly whether this project has any glibc
dependency, given .claude/CLAUDE.md's strict ANSI C99/no-GNU-extensions
requirement (confirmed -std=c99 throughout both Makefiles). Documentation
correction only -- no code changed.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CXjAPTEKrgY2Mrk25KoLDn
blk_subsys_detach_device() (block_subsystem.c) walks the device chain,
refuses removal of anything but the current tail (a mid-chain removal
would corrupt every later slot's start_lbn -- this architecture's own doc
already argues USB stays last specifically to avoid that), unlinks,
shrinks total_user_lbn, closes and frees the slot. Discards rather than
flushes dirty state -- the device is physically gone by the time this
runs (PORTSC disconnect only). Trigger wiring mirrors the attach path:
bot_msc_attached (set only once attach actually succeeds) gates a new
bot_msc_detach_pending flag set at PORTSC disconnect (not Disable Slot
completion, which is conditionally skipped and would miss concurrent
connect/disconnect pairs), consumed in sk_repl_idle().
Advisor flagged the real hazard ahead of time: block_words.c's VM block
window (blk_vm_lbn[]/blk_vm_cbuf[]) can go stale across a detach then a
same-LBN re-attach, and suggested a pointer-identity re-check in
blk_vm_load() as a minimal fix. That fix was implemented, then directly
falsified by its own designed-for-this test: attach a blank device, read
a block (populating the cache), detach, re-attach a device with distinct
content at the identical LBN, read again -- served stale content from
the first device. Root cause, confirmed live: glibc's allocator hands
free(slot) straight back to the very next same-size calloc(), so the
"fresh" and stale pointers were bitwise identical despite being two
different devices. Fixed properly with a monotonic blk_subsys_epoch()
counter (bumped on every attach/detach) checked by a new
blk_vm_check_epoch() helper at the one choke point (blk_vm_find(), plus
blk_vm_flush_all() which reads the same arrays directly) that covers
every path touching the window cache -- unfooled by address reuse.
Verified live with a new disk/usb-thumbdrive-test2.img fixture (distinct
content from the existing blank test image): attach A, read (cache hit
populated), detach, re-attach B at the same LBN, read again -- correctly
ran a fresh device read and returned B's real content, not A's stale
cached zeros. The failing pointer-comparison attempt's own capture log
kept as evidence, not deleted. All three architectures re-verified clean.
FABRIC-2.md Section X 2h marked complete -- enumeration through
hot-detach all live and verified; only WRITE(10) (2g's own still-open
item) remains unimplemented in the driver, not blocking anything here.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CXjAPTEKrgY2Mrk25KoLDn
Wires a hot-plugged USB Mass Storage device into the block subsystem's
unified LBN chain. blkio_usb.c/blkio_usb.h mirror virtio_blk.c/
virtio_blk.h's established shape exactly (singleton state, blkio_vtable_t,
a blkio_usb_open_msc() "find" function playing virtio_blk_find_artemis()'s
role): read() translates a Forth block into a SCSI LBA/count pair and
calls xhci_bot_read_block() + xhci_bot_wait_for_idle(); write() returns
BLKIO_ENOSUP (no SCSI WRITE(10) exists yet, and blk_format_or_load_disk()
never writes at attach time, so read-only is sufficient -- confirmed by
reading that function first, not assumed). Refuses (-2) if the reported
SCSI block size doesn't evenly divide the 1024-byte Forth block size.
Connect-time wiring reuses the bot_msc_attach_pending/consume-in-
sk_repl_idle() shape the prior increment's temp probe already validated,
now made permanent: SET_CONFIGURATION sets the flag, sk_repl_idle()
(strictly after its own xhci_poll_events() call returns) calls
blkio_usb_open_msc() then blk_subsys_attach_device().
Verified live via hot-attach: full chain from USB connect through
'blkio_usb: MSC device ready' to 'blk: disk 'StarForth Volume' v2 LBN
26074..75184 (49111 user blocks)' -- real attachment, disk image confirmed
byte-for-byte untouched after. Chased a real debugging detour along the
way: the attach initially appeared silent (no blk: log line) -- traced to
LOG_INFO filtering at the default LOG_WARN boot level, not a functional
bug (settled via a temporary log-level bump, reverted after capture; also
found and reported, but did not fix, a pre-existing unrelated
Makefile.starkernel bug where --log-level=info via KERNEL_ARGS breaks
printf parsing). All three architectures re-verified clean. FABRIC-2.md
Section X 2h updated -- only hot-detach remains for 2h.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CXjAPTEKrgY2Mrk25KoLDn
Closes the gap block_subsystem.c needs before any of 2h's real work
(blkio_usb.c, attach wiring, hot-detach) can start: this driver is fully
async/polled with no way for a synchronous caller (blkio_read()/
blkio_info() etc.) to get a result back. xhci_bot_wait_for_idle() is a
bounded busy-wait over xhci_poll_events() -- MUST be called only from
outside xhci_poll_events()'s own call frame, never from within it or a
next_action dispatch (recursion into live Event Ring/ERDP processing,
same class of hazard already documented for doorbell rings in this
driver). xhci_get_dev() exposes the module-static device handle to
outside callers that didn't observe the original hotplug event.
SCSI READ CAPACITY(10) (opcode 0x25) is the other half -- nothing could
learn a device's block size/capacity before this. First attempt sent it
bare and hit the classic first-command UNIT ATTENTION (CSW FAILED); fixed
with the same TUR-guard pattern READ(10) already used, generalized via a
new bot_tur_chain_target field so TEST UNIT READY's PASS handling can
chain into either command. bot_data_buf grown 512->1024 bytes (one Forth
block = two 512-byte SCSI blocks, per block_subsystem.c's own 1KiB-unit
convention).
Verified live via a temporary probe (hot-attached disk/usb-thumbdrive-
test.img via QMP, reverted after capture): TUR-guarded READ CAPACITY10
correctly reported last LBA=0x1ffff, block size=0x200 -- exactly 64MiB,
matching the test image byte for byte -- followed by a TUR-guarded
1024-byte/2-block READ10, both PASS. All three architectures re-verified
clean, probe-free boot to ok> on the reverted tree. FABRIC-2.md Section X
2h updated with the writeup; the blkio_usb.c backend itself is next.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CXjAPTEKrgY2Mrk25KoLDn
Roots out the CSW status FAILED left unexplained in the prior increment: a
freshly attached SCSI target's standing UNIT ATTENTION condition, which a
bare READ(10) with no retry can never clear. xhci_bot_send_test_unit_ready()
sends SCSI TEST UNIT READY (SPC-4 6.33) ahead of the real command; the CSW
handler now tags command kind (bot_cmd_kind) to distinguish a TUR completion
from a READ10 completion, chains TUR PASS into the real READ(10), and
bounded-retries TUR on FAILED/PHASE ERROR (bot_tur_retries, capped at
XHCI_BOT_TUR_MAX_RETRIES). xhci_bot_read_block() is the new intended entry
point tying lba/num_blocks/block_size + the TUR-first sequencing together.
Verified live via a temporary probe (hot-attached disk/usb-thumbdrive-test.img
through the running instance's QMP socket), captured on amd64: full chain
CBW(TUR) -> FAILED -> retry -> PASS -> CBW(READ10) -> Data-In -> CSW PASS.
Probe reverted after capture; all three architectures re-verified clean,
probe-free boot to ok>. FABRIC-2.md Section X 2g updated with the writeup.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CXjAPTEKrgY2Mrk25KoLDn
Completes the CBW -> Data-In -> CSW chain for READ(10) started last
commit. xhci_bot_read_data_in() and xhci_bot_receive_csw(), each a
single Normal TRB on the bulk IN Transfer Ring via a new
xhci_bulk_in_enqueue_and_ring() helper (mirrors the OUT-side helper
from CBW send). All three stages now chain automatically via the
existing deferred next_action pattern: CBW completion defers into
Data-In, Data-In completion defers into CSW receive, CSW completion is
where signature/tag/status validation happens.
Data-In reads into a new fixed 512-byte bot_data_buf -- single-block
scope for this increment, matches QEMU's usb-storage reported block
size; xhci_bot_send_read10() now refuses rather than overflow/truncate
if a request exceeds it. CSW validation (BOT spec section 5.2) checks
dCSWSignature and dCSWTag (a new bot_last_tag field, latched from the
CBW) before trusting bCSWStatus at all, so a garbled/misaligned CSW
read can't be misread as a clean pass. usb_bot_csw_t follows the same
struct-with-explicit-length-not-sizeof discipline as usb_bot_cbw_t.
Verified live via a temporary probe (written, run once, log captured,
reverted per this project's own probe convention), all three
architectures, byte-identical: the full CBW -> Data-In -> CSW exchange
completes cleanly, well-formed CSW with correct signature and echoed
tag, no wedge, clean disconnect immediately after. The SCSI command
itself reports CSW status FAILED against the current test fixture --
expected at this stage (no TEST UNIT READY / UNIT ATTENTION handling
implemented yet, consistent with a fresh-attach unit-attention
condition, not a transport-layer defect) and not root-caused further
here; the BOT mechanism itself is confirmed correct end to end.
Probe-free re-verification afterward on all three architectures.
FABRIC-2.md Section X Milestone 2g's CSW checklist item marked done;
"get one real READ(10) working end to end" stays explicitly open,
distinguishing "the mechanism works" from "the SCSI command succeeds."
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R4VMX6VSKCten8nGgaMkq4
First real use of the bulk Transfer Rings Configure Endpoint wired up.
xhci_bot_send_read10() builds a 31-byte Command Block Wrapper (USB Mass
Storage Class Bulk-Only Transport spec section 5.1) and submits it as a
single Normal TRB on the bulk OUT ring via a new
xhci_bulk_out_enqueue_and_ring() helper -- a CBW is always exactly one
TRB, so unlike the EP0 helper this one rings its own doorbell rather
than leaving that to a caller assembling a group.
usb_bot_cbw_t is a real struct (every field up to the CDB array is
naturally aligned, and this driver's targets are all little-endian
already assumed everywhere else), but its DMA length is the explicit
USB_BOT_CBW_LENGTH (31) constant, never sizeof(*cbw), since the
compiler may pad the struct to 32 bytes. The SCSI READ(10) CDB itself
is written byte-by-byte since its LBA/Transfer Length fields are
big-endian on the wire, unlike everything else in this driver -- the
one place two byte orders are both live in the same function.
Completion is correlated via the existing pending_transfer_slot_id/
transfer_purpose gate (new XHCI_XFER_CBW_SENT purpose) -- no
ring-specific dispatch needed, since this driver's single-outstanding-
transfer scope already implies which ring produced an event.
This covers construction and send only (one third of a full READ(10):
CBW -> Data-In stage -> CSW) -- reading the Data-In stage and CSW
receive/validation are separate, explicitly not-yet-implemented items.
Verified live via a temporary probe (written, run once, log captured,
reverted per this project's own probe convention) -- all three
architectures, byte-identical: CBW submitted -> CBW send completed,
then a clean disconnect even with the Data-In stage never drained
(confirms no wedge on a dangling BOT transaction). Probe-free
re-verification afterward on all three architectures.
FABRIC-2.md Section X Milestone 2g's CBW checklist item marked done.
Also records a monitoring gotcha hit three times this session: `ls -t`
over the logs/ tree can return a stale leftover log from an earlier
run in the same session -- fixed going forward by reading the log path
off the actual running QEMU process's own command line instead, and a
memory note added so it doesn't recur next session.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R4VMX6VSKCten8nGgaMkq4
Adds the xHCI Configure Endpoint command for the two bulk endpoints
identified by the previous increment, and fixes control-transfer
sequencing to match the spec: xHCI 1.2 section 4.3.5 requires Configure
Endpoint before SET_CONFIGURATION is sent to the device, the reverse of
the order this driver used through 2f (which happened to work against
QEMU's lenient qemu-xhci emulation but wasn't spec-correct).
New XHCI_TRB_TYPE_CONFIGURE_ENDPOINT_CMD, EP Context type constants for
Bulk IN/OUT, and an XHCI_EP_ADDR_TO_DCI() macro (DCI = 2*EndpointNumber
+ Direction) in xhci.h. xhci_cmd_configure_endpoint() builds the Input
Context (Slot + one EP Context per DCI up to the highest bulk endpoint
in use) and submits the command via the existing next_action deferral
mechanism, correlated on completion via a new
XHCI_CONN_AWAIT_CONFIGURE_ENDPOINT connect_state, then chains into the
existing SET_CONFIGURATION path.
Two allocations had to grow beyond what Address Device sized them for:
the Input Context (previously room for one EP Context only) and, less
obviously, the Device Context that DCBAA[slot_id] itself points at --
the controller only touches DCIs named in a command's own Add/Drop
flags, so growing that buffer required copying its existing Slot+EP0
content forward rather than zeroing it, to avoid handing the controller
a blank EP0 out from under an endpoint this command isn't touching.
Bulk Transfer Rings (bulk_in_ring/bulk_out_ring) are allocated and
wired into the new EP Contexts but not yet exercised by an actual
transfer -- CBW/CSW submission is next.
Verified live via QMP hotplug, all three architectures, byte-identical:
bulk endpoint identification -> configure endpoint command submitted ->
configure endpoint succeeded -> the existing set configuration ->
device configured chain, then a clean disconnect/disable-slot teardown
afterward with the larger Device Context installed.
FABRIC-2.md Section X Milestone 2g's endpoint identify+configure
checklist item marked fully done.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R4VMX6VSKCten8nGgaMkq4
Picked up from a crashed session: xhci_driver.h/xhci.h already had the
bulk_in/out_ep_addr/max_packet fields and Endpoint-descriptor offset
macros scaffolded, but the actual walk that populates them was never
written. Added it: after 2f confirms a Mass Storage/SCSI/BOT interface,
a nested walk continues through the Endpoint descriptors that follow it
(bDescriptorType==5, stopping at the next Interface descriptor or end
of stream), keeping only Bulk-type endpoints and splitting IN/OUT by
bEndpointAddress bit 7. Also reset the four new fields in
xhci_bringup(), which the scaffolding had missed.
Also completed 2e's disconnect teardown, which was fully implemented
this session (not scaffolded): a Disable Slot command is now submitted
on a real disconnect, with the port's tracked slot ID captured and
cleared from port_slot_id[] immediately (before the command completes)
so a fresh connect on the same port isn't confused for one already in
progress, and DCBAA[slot_id] cleared only on a successful completion.
Verified live via QMP hotplug (deliberate device_add/device_del against
freshly launched, individually-tracked instances -- not whatever
happened to be attached at boot), all three architectures,
byte-identical: bulk IN endpoint=0x81, bulk OUT endpoint=0x02, then a
clean disconnect -> disable slot succeeded, no wedge. Caught and fixed
a documentation near-miss in the same pass: an initial draft cited the
probe-free three-arch acceptance boots as this feature's verification
evidence, but a stale leftover log directory from a pre-crash orphaned
QEMU process had been picked up by an `ls -dt | head -1` glob during
monitoring and mistaken for this session's own result -- the real
acceptance logs never had a device attached at all. Re-verified against
real PIDs and real log paths before writing FABRIC-2.md's final
writeup.
FABRIC-2.md Section X Milestone 2 updated: 2e's disconnect-teardown
checklist item marked done, 2g's endpoint-identification item marked
partially done (identification only -- Configure Endpoint / EP Context
wiring is still open).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R4VMX6VSKCten8nGgaMkq4
Chains off a confirmed Mass Storage/SCSI/BOT interface match via the
existing next_action deferral mechanism: device descriptor -> config
descriptor -> SET_CONFIGURATION is now a single automatic sequence.
bConfigurationValue is read directly out of the already-fetched
config_descriptor buffer, no extra transfer needed.
First write control transfer this driver has issued (every prior one was
a read), so it needed its own submission helper,
xhci_ep0_control_write_nodata() -- SET_CONFIGURATION has no Data Stage
(wLength=0), and per USB 2.0 spec 8.5.3 a no-data control transfer's
Status Stage is always IN, the reverse of an OUT-data request's status
stage. XHCI_SETUP_TRT_NO_DATA already existed in xhci.h, unused until now.
Verified live via QMP hotplug, all three architectures, worked first try,
byte-identical: "set configuration submitted" -> "device configured",
guest stays running throughout (checked via QMP query-status). Disconnect
confirmed clean on every arch afterward, no wedge. FABRIC-2.md Section X
Milestone 2f updated -- 2f is now fully complete, 2g (Bulk-Only Transport)
can start.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QPfdtaXs9ay1nbwuMnrscu
Chains off the device descriptor request via a new deferred-action mechanism
on xhci_dev_t (next_action/next_action_slot_id/next_action_length): a short
9-byte Configuration descriptor read learns wTotalLength, then a full read
retrieves Config+Interface+Endpoint descriptors, walked for the Interface
descriptor to confirm bInterfaceClass/SubClass/Protocol == Mass Storage/
SCSI/Bulk-Only Transport.
The deferral exists because ringing the next doorbell synchronously inside
xhci_poll_events()'s event-processing loop -- before the current event's
ERDP write -- hung the guest outright (confirmed live via checkpoint
logging, amd64). Fixed by moving the actual control-transfer submission to
a small dispatch at the end of xhci_poll_events(), after ERDP is updated.
A debug hack that shipped mid-session (forcing a repeated 9-byte read
instead of chaining into the real 44-byte length, to isolate whether the
hang was doorbell-ordering or length-specific) has been reverted: restored
the real length and re-verified live. The doorbell-ordering fix was the
whole story -- the 44-byte read completes cleanly.
Verified live via QMP hotplug, all three architectures, byte-identical
results: wTotalLength=0x2c, bInterfaceClass=0x08, bInterfaceSubClass=0x06,
bInterfaceProtocol=0x50 -- confirmed Mass Storage/SCSI/BOT. Disconnect
confirmed clean on every arch, no wedge. FABRIC-2.md Section X Milestone 2f
updated with the full writeup.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QPfdtaXs9ay1nbwuMnrscu
Adds Setup/Data/Status stage TRB types and control bits (IDT, TRT, DIR)
to xhci.h, and xhci_ep0_enqueue_trb()/xhci_ep0_get_device_descriptor() to
xhci.c -- the first real control transfer this driver has issued.
Follows the same enqueue-then-doorbell-once pattern as the Command Ring,
operating on the EP0 Transfer Ring built during 2e's Address Device work.
Setup Stage uses Immediate Data (parameter IS the 8-byte setup packet);
Data Stage reads into a reused 18-byte device_descriptor buffer; Status
Stage alone carries IOC, so exactly one Transfer Event signals transfer
completion, correlated via a new pending_transfer_slot_id (same
single-outstanding-operation pattern as connect/Enable Slot/Address
Device).
Automatically triggered once Address Device succeeds. Verified live via
QMP hotplug, all three architectures, worked first try with identical
results everywhere: idVendor=0x46f4, idProduct=0x0001, bDeviceClass=0x00
-- the class=0 confirms Mass Storage class detection needs the
Configuration/Interface descriptor (2f's next item), not the device
descriptor.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HZ8kNoTuP63pbQtro4qvrm
New freestanding, verify-only Ed25519 (RFC 8032) implementation:
include/starkernel/{sha512,fe25519,scalar25519,ed25519}.h +
src/starkernel/crypto/{sha512,fe25519,scalar25519,ed25519}.c, wired into
Makefile.starkernel. Kernel never signs or generates keys -- only
ed25519_verify() is needed; signing happens in the host-side mkcapsule
build tool via libsodium/OpenSSL.
Confirmed __int128 multiply/add/shift-by-constant compile with zero
undefined symbols on all three target toolchains (only division needs
libgcc's __udivti3, per timer.c's existing documented finding -- that
file's comment updated to narrow the claim, since it had been read as
"avoid __int128 entirely"). This enabled the standard 5-limb radix-2^51
field arithmetic representation.
An abandoned first attempt (10-limb radix-2^26, avoiding __int128 out of
premature caution) hit two real bugs, both invisible on inspection and
found only by property-based testing against Python's own bignum
arithmetic: a non-uniform-radix limb misalignment in multiplication, and
a double-counted carry. Verification chain: SHA-512 against known +
boundary vectors (7/7); field arithmetic property-tested 25,045 cases;
scalar-mod-L arithmetic 300 cases (L confirmed prime via Miller-Rabin
first); full verify() end-to-end against 110 real signatures from
Python's cryptography library, including tampered inputs and the RFC
8032 S>=L malleability attack -- all correctly accepted/rejected.
Compiles clean (zero warnings) and links on all three architectures,
confirmed via the mandatory three-arch QEMU boot. The code is linked but
not yet called from anywhere -- wiring into capsule_birth.c needs a
from-scratch X.509/DER parser first (Captain Bob chose real X.509 over a
raw-blob cert format this session), which is the next open item.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HZ8kNoTuP63pbQtro4qvrm
Adds Slot/Endpoint/Input Control Context structs (32-byte layout only --
HCCPARAMS1.CSZ checked live and confirmed 0 against this driver's QEMU
target; 64-byte contexts refuse rather than silently mis-laying-out),
xhci_cmd_address_device(), and a new dev->connect_state
(idle/await-enable-slot/await-address-device) sequencing Enable Slot and
Address Device per connect. Input Context (what the command TRB's
parameter points at) and Device Context (what DCBAA[slot_id] points at)
are separate 64-byte-aligned allocations, lazily created once and reused
across every connect -- single-device driver scope, no free path needed.
A new EP0 Transfer Ring uses the same fixed-ring-plus-Link-TRB pattern as
the Command Ring.
Two facts checked live before writing any context code, not assumed:
HCCPARAMS1.CSZ (32-byte, confirmed) and PORTSC.PED at connect time
(already set -- PORTSC=0x00021203, SuperSpeed -- the test device
self-enables via USB3 link training, so no port-reset state machine was
needed this increment; USB2 would need one, untested). Both diagnostics
also added console_puts/println-based hex logging (xhci_log_hex32()) --
console_println() only takes string literals, no formatted print existed
on this driver's console path before now.
Verified live via QMP hotplug, all three architectures, succeeded on the
first attempt with no debugging needed: "enable slot succeeded" ->
"address device command submitted" -> "address device succeeded" on
every boot.
Also fixes a FABRIC-2.md dependency-direction error from the previous
commit (Address Device is 2f's prerequisite, not the reverse).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HZ8kNoTuP63pbQtro4qvrm
xhci_poll_events()'s Port Status Change connect branch now calls
xhci_cmd_enable_slot() directly (the earlier boot-time smoke test call is
gone), tracked via a new dev->pending_connect_port_id -- since this
driver only ever has one command outstanding at a time, that alone
identifies which port a later Command Completion Event answers, without
needing to match the Command TRB Pointer yet. On success the returned
Slot ID is recorded in a new dev->port_slot_id[], a fixed
uint32_t[XHCI_MAX_TRACKED_PORTS] (32) indexed by port. Disconnect clears
the port's tracked slot (real teardown -- Disable Slot, DCBAA clear,
Section U callback -- is still a later increment).
Fixed array, not heap-allocated: a first attempt sized port_slot_id
dynamically via kmalloc_aligned(dev->max_ports * sizeof(uint32_t), 64)
inside xhci_bringup() and it crashed amd64 with a page fault (IFETCH at
RIP=CR2=0xA0000, the legacy VGA hole) during the unrelated Mama-VM-birth
phase afterward -- a heap-corruption signature, not chased to root cause.
Switching to a fixed array (matching this driver's existing preference
for fixed over dynamic allocation) made the crash go away; the crashing
boot's log is kept (logs/20260822-102516/) as the evidence trail.
Verified live via QMP hotplug, all three architectures: connect ->
"enable slot command submitted" -> "enable slot succeeded", with a
disconnect/reconnect cycle repeating cleanly and no port wedge.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HZ8kNoTuP63pbQtro4qvrm
xhci_poll_events()'s Port Status Change branch now decodes the Port ID
from the event TRB (XHCI_PSC_EVT_PORT_ID, new in xhci.h), reads that
port's PORTSC.CCS via a new xhci_port_regs() helper, and logs connect vs.
disconnect. Acknowledges by writing back only PP (preserved) and CSC (the
bit being cleared) -- PED/PR/other _C bits written 0 so nothing is
accidentally disabled, reset, or silently cleared, matching the RW1C
discipline already used for ERDP.EHB in 2d.
Verified with the real target scenario via QMP hotplug on all three
architectures: boot with the xHCI controller present but no USB device
attached (confirmed zero port activity at ok>), then live
attach/detach/re-attach of a virtual USB thumb drive
(disk/usb-thumbdrive-test.img via usb-storage on xhci0.0). Full
connect->disconnect->connect cycle confirmed clean (no port wedge) on
amd64; single connect confirmed on aarch64 and riscv64.
Still open: correlating Command Completion Events back to their issuing
command, driving Enable Slot/Address Device from this connect path
(currently only a boot-time smoke test), and the callback surface into
Section U's higher-level code.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HZ8kNoTuP63pbQtro4qvrm
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
Enable Slot command TRB submitted via a new xhci_submit_command()/
xhci_cmd_enable_slot(), ring doorbell 0, confirmed by a real Command
Completion Event on all three architectures -- the first time this driver
has written a TRB rather than only reading the Event Ring (2d). Added the
Command Ring's previously-missing Link TRB (xHCI 1.2 spec sec 4.9.2) for
wraparound correctness.
Port Register connect/disconnect handling, slot-ID/context bookkeeping,
Address Device, and the callback surface into Section U's code are still
open -- this is the discriminating first step, not full 2e.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HZ8kNoTuP63pbQtro4qvrm
Implements Event Ring TRB parsing and ERDP dequeue-pointer update
(xhci_poll_events(), src/starkernel/usb/xhci.c), called from
sk_repl_idle()'s existing ~1s idle cadence rather than a per-arch
interrupt handler.
A first attempt wired real interrupt delivery (PCI->IOAPIC GSI routing,
a dedicated isr_stub34/vector 0x22, GIC/PLIC routing mirroring
virtio_input.c). Checked live via QMP query-pci before trusting it: the
amd64 PIRQ swizzle formula predicted GSI 16 for the xHCI controller at
PCI slot 4; the real QEMU-assigned IRQ was 10, and embedded ICH9
functions contradicted the same formula too. Reverted all of it back to
the exact committed baseline rather than chasing chipset PIRQ routing
further, and reframed around Section U item 6's own design intent
("interrupt-driven, coarse cadence, cheap early-exit... quick check
blocks... done") via sk_repl_idle() instead -- USB insertion is a
human-timescale event, not a hot path.
Added -device qemu-xhci to all three QEMU launch targets (required for
any of this to be testable). Verified end to end via genuine post-boot
hotplug (QMP device_add/device_del usb-storage): all three architectures
detect a live attach within seconds. A false-alarm heartbeat "freeze"
found mid-verification traced to querying the wrong counter
(vm->heartbeat.tick_count, which only advances during word execution,
not the kernel's real ISR-driven heartbeat_ticks()) -- confirmed via a
temporary diagnostic word, captured and reverted.
Full writeup, including the discarded interrupt-routing attempt and the
false-alarm investigation, in FABRIC-2.md's Milestone 2c/2d entries.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HZ8kNoTuP63pbQtro4qvrm
xhci_bringup() (HC reset, DCBAA, Command/Event rings, RUN/STOP) was
uncommitted and referenced an XHCI_WAIT_FOR macro that was never defined,
breaking the build. Wired all four wait sites to the existing
xhci_wait_bit() helper instead, matching each register/bit/polarity
needed (halt-before-reset waits for HCH set; HCRST, CNR, and post-RUN
HCH waits all wait for their bit to clear).
Also flipped g_doe_log_enabled's default from 1 to 0 -- the per-tick
[HADES][DOE] CSV export was flooding every boot log and slowing
interactive verification for no reason during ordinary acceptance runs;
HB-ON still re-enables it at the REPL for anyone running an actual DoE
campaign.
Three-arch acceptance: amd64/aarch64/riscv64 all boot clean to ok>,
zero DoE rows in any log. aarch64 and riscv64 both exited cleanly via
BYE with no exception, confirming the earlier SMC->HVC PSCI fix still
holds. Logs and DoE CSV artifacts from this run included.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HZ8kNoTuP63pbQtro4qvrm
New src/starkernel/usb/ subsystem directory (added to both
LOADER_SRCS_BASE and KERNEL_SRCS_BASE wildcards in Makefile.starkernel,
matching the existing virtio/*.c pattern). xhci_find_and_map() locates
the controller via the already-generic pci_find_first(), enables it,
maps BAR0 via the already-generic pci_map_bar(), and fills in all four
register-region pointers (cap/op/runtime/doorbell) plus max_slots/
max_ports/max_intrs from HCSPARAMS1 -- ready for controller bring-up
(2c) to consume directly.
No pci.c extension needed, per 2a's finding that PCI discovery here is
ID-based lookup (already generic), not class-code scanning. Verified:
clean standalone syntax check, full amd64 kernel build with zero
warnings, live boot still reaches POST 1012/0/0 unaffected (nothing
calls xhci_find_and_map() yet, so this is purely additive).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
live via QMP, ring sizing decided
include/starkernel/xhci.h: Capability/Operational/Runtime register
layouts, Port Register Set, Interrupter Register Set, Doorbell Array,
16-byte TRB struct -- all from the xHCI 1.2 spec, no existing
reference in this tree to build from (unlike virtio-blk). volatile
fields, no packed attribute, matching virtio_blk.c's documented
riscv64/QEMU-MMIO precedent. Compile-checked clean, sizeof(xhci_trb_t)
verified == 16.
QEMU qemu-xhci's PCI vendor:device ID (0x1B36:0x000D) confirmed live
via QMP query-pci against a real running instance -- not assumed from
memory, matches the Milestone 1 QMP infrastructure just built.
Ring sizing decided: fixed 256-TRB (one page) Command Ring and Event
Ring, single interrupter -- documented rationale in the header.
Bonus finding: src/starkernel/pci/pci.c already has more reusable
infrastructure than Milestone 2b assumed (pci_find_first is ID-based
lookup already existing; pci_bar/pci_map_bar/pci_enable are already
generic) -- 2b is smaller than originally scoped, noted in the punch
list.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Leftover from the milestone renumbering -- cross-references elsewhere
already said "Milestone 2e" etc., but the bare sub-item labels inside
Milestone 2's own section still said "3a."-"3h.". Now consistent.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
launch targets, three-arch verified
Makefile.starkernel: added -qmp unix:$QMP_SOCK,server=on,wait=off to
the amd64/aarch64/riscv64 qemu targets, matching the existing serial
chardev socket pattern exactly (same discoverability, same cleanup on
exit). Verified on all three architectures: QMP greeting arrives on
connect, qmp_capabilities handshake succeeds, device_add/device_del
round-trip correctly.
Real finding surfaced during device_add testing (recorded in
FABRIC-2.md's punch list for Milestone 2): the q35 machine's pcie.0
root bus doesn't support runtime PCI hotplug without a bridge --
Milestone 2's qemu-xhci USB controller needs to be present in the
static launch command, with USB devices hot-attached to its bus at
runtime, not the controller itself hot-added.
Also noted: g_doe_log_enabled's default-on per-tick heartbeat CSV
export was briefly mistaken for a hang during aarch64 verification --
it isn't one, just a large volume of routine diagnostic output before
reaching ok>. Not changing the source default; adopting HB-OFF
immediately after boot as the working pattern for the rest of this
punch list's dev work.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
execution order, physically reordered in the file
Previously kept stable IDs with a separate "read this note for the
real order" translation layer. Renumbered so the milestone numbers
themselves read top-to-bottom in execution order and physically
reordered the ### Milestone blocks in Section X to match -- no
translation needed anymore. New order: 1=QEMU monitor/QMP socket,
2=USB hardware stack, 3=block subsystem extensions, 4=drive/credential
security, 5=console/VM key-match binding, 6=PKI signing chain,
7=contributor capsules/trust tiers, 8=bare-metal USB boot (still
second-to-last, not first -- QEMU-first per Captain Bob's explicit
reinforcement), 9=networking (unchanged, still last). All cross-
references between milestones (including Milestone 2's internal
sub-item labels 2a-2h) updated to match throughout Sections U, W, and
X.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
continuous chain, not two parallel paths; resolves Milestone 7's
bootstrapping question precisely, not just for dev/test
Captain Bob's precise correction: "my own real root CA -> snakeoil
embedded cert -> blob & capsule + MANIFEST.md" is one chain. The
snakeoil intermediate is CA-signed, not self-signed/untrusted --
"snakeoil" names its informal/private-project status, not that it
lacks a real trust root. This means Milestone 7's CA-bootstrapping
question (how does the CA public key get into the kernel without
being just another unverifiable capsule) is resolved outright, not
just worked around for dev/test builds as the previous draft of
Section U's fourth addendum implied: trust is established once, at
build time, by whoever holds the real root CA and produces the build.
No kernel-boot-time verification against a hardcoded CA public key is
needed at all. Corrected both Section U item 20 and Milestone 7's
punch list in Section X to match.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
cert resolves Milestone 7's bootstrapping question for dev/test builds
Three distinct user-role tiers clarified (builder+dev, SDK-only dev,
no-SDK user) -- refines the trust-tier question beyond a simple core/
contrib boundary. More importantly: a snakeoil cert embedded directly
into each build (not loaded as a capsule, not verified against an
external CA at boot) is the actual answer to the CA-bootstrapping
problem Section X's Milestone 7 punch-list surfaced, at least for dev/
test builds -- trust is established at build time, sidestepping the
runtime chicken-and-egg entirely for that case. Two paths into a build
confirmed: snakeoil-signed, or code review + inclusion in the source
repo -- the latter likely makes at least one of Milestone 8's four
spitballed trust-tier directions (signature-authority tiers)
redundant, worth revisiting before picking one.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
in QEMU first, defer real-hardware USB boot to last; add UEFI-only
boot-path constraint
Captain Bob's explicit correction: real-hardware boot is "difficult
and lots of blind guesswork" (no serial log, unknown firmware quirks)
and isn't worth attempting until there's a working Artemis subsystem
to actually demonstrate, not just an empty kernel proving UEFI boot
works. QEMU's own USB hotplug emulation is sufficient to build and
validate the entire home-blocks subsystem without touching real
hardware at all.
Milestone IDs in Section X kept stable (not renumbered, to avoid
breaking cross-references between milestones) with an explicit
execution-order note instead: 2 -> 3 -> 4 -> 5 -> 6 -> 7 -> 8 -> 1,
networking (9) still deferred past all of them.
New scope constraint captured for whenever Milestone 1 resumes: UEFI-
only boot path, no legacy BIOS/MBR, no GRUB2 -- starkernel_loader.efi
is meant to be the entire boot path, not one stage in a longer chain.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
breakdown across all 9 milestones, no code written
Nine milestones, in Section W's sequencing order, each broken down to
single-function granularity per Captain Bob's explicit request:
1. Bare-metal USB boot (demo mode) -- the actual near-term milestone,
~9 concrete steps from ISO build through real-hardware validation.
2. QEMU monitor/QMP socket -- small dev-workflow unblock.
3. USB hardware stack -- the hard prerequisite, broken into 8 sub-areas
(spec groundwork, PCI discovery, controller bring-up, interrupt/
event handling, hotplug detection, device enumeration, Bulk-Only
Transport read/write, block-subsystem integration) since nothing
in this tree has ever touched USB before.
4. Block subsystem extensions (identity-derived ranges, drive map,
migration state machine, sk_repl_idle() body, unclean-removal
handling).
5. Drive/credential security (foreign-drive signature, zuse one-way
burn extending the existing acl_pinned mechanism).
6. Console/VM key-match binding.
7. Kernel/capsule PKI signing chain, including a real open
bootstrapping question (how the CA public key itself gets into the
kernel without being just another capsule) not previously
surfaced in Sections U/V/W.
8. Contributor capsules/trust tiers.
9. Networking -- deliberately left unexpanded, deferred per Captain
Bob's own sequencing, not premature-detailed.
Every item cross-references back to the specific Section U requirement
and Section V verified-status finding it comes from. Still direction
only -- no code, no capsule work started.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
one place, pulling together Sections U and V
Single-read consolidation of the whole Artemis thumbdrive/home-blocks/
PKI vision: one-paragraph statement of intent, a component table
cross-referencing each piece to its detail (Section U) and verified
status (Section V), and explicit sequencing with the actual near-term
milestone first -- bare-metal boot from a physical USB stick in demo/
"try it" mode, confirmed NOT gated on the USB hardware driver gap
since booting from USB is a UEFI firmware responsibility, not a kernel
one. The existing starkernel.iso/raw-disk-image build artifacts (built
on every QEMU launch already) are, mechanically, what gets dd'd onto a
physical drive for this. Two 64GB SanDisk drives confirmed on hand and
available now. Everything else in the concept board explicitly waits
on the USB hardware driver as the singular hard prerequisite.
Still direction only -- nothing implemented, no hardware testing done.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
blocks/thumbdrive/PKI subsystem against the actual codebase
Systematic pass over every requirement gathered in Section U, each
verified directly against the tree rather than recalled. Organized by
area (physical block layout, USB hardware, drive/credential security,
console/VM binding, capsule signing/PKI, contributor trust tiers,
networking, dev workflow).
Found more than expected already exists and is reusable as-is: the
block address space and device-chain abstraction, sk_repl_idle()'s
empty trigger hook, capsule_birth_baby()'s on-demand VM spin-up,
acl_pinned's one-way-ratchet mechanism (a direct precedent for the
zuse one-way-burn requirement), arbitrary binary payload capsule
embedding (proven by the font capsule), the manifest's already-
documented Ed25519 anchor point, and the live-boot ISO pipeline.
Confirmed real, clearly-scoped gaps with nothing partially started:
identity-to-block-range derivation, the block migration state machine,
drive-map format, console/VM key binding, all signature/cert
verification code, magic-number content-type/foreign-drive detection,
the contributor trust-tier flag, QEMU monitor socket exposure, and the
install path.
Identifies the USB stack itself as the one hard, load-bearing
prerequisite gating almost every other gap from being testable at all,
even in QEMU -- the honest first-cut recommendation if a concrete next
milestone gets picked from this analysis.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
sequencing, and spitballed trust-tier ideas -- still brainstorming,
nothing implemented
Captures the QEMU-dev-environment assumption, confirms capsules/contrib/
would fit the existing subdirectory convention (artemis/, common/,
fonts/, hermes/ already exist), and confirms via mkcapsule.c that no
provenance/trust-tier distinction exists today -- every non-Mama-init
capsule gets identical FLAG_PRODUCTION|FLAG_EXPERIMENT unconditionally.
Explicit sequencing: ACL/PKI work closes first, then contrib-directory/
trust-tier work, then networking (downloadable capsules named but not
scoped). Closes with four explicitly-unvetted spitballed directions on
the trust-tier question, requested as free brainstorm: a new
FLAG_CONTRIB bit, signature-authority tiers hanging off the cert chain,
block-namespace sandboxing for contrib capsules, and QEMU-vs-real-
hardware conditional signature enforcement.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
extending items 7-8 -- still brainstorming, nothing implemented
Five more points captured: (10) intermediate cert embedded as a capsule
blob (CA stays external/unrevocable), reusing the capsule system's
already-proven arbitrary-binary-payload capability (the font capsule is
existing precedent); (11) two-stage validation chain, both stages net
new code; (12) confirmed via tools/mkcapsule.c's own header comment
that Ed25519 signing hanging off the xxHash64 manifest column was
already the documented Phase 8 plan, independent of this conversation
-- strong validation of the whole direction; (13) signing granularity
is per-capsule, matching the existing hash column's 1:1 file
granularity exactly; (14) content-type detection via magic numbers
rather than a new MIME-type field, and confirmed to be the same
mechanism as item 7's foreign-drive detection -- one shared
byte-sniffing primitive plausibly serves both.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
burn, console/VM key-match attachment -- still brainstorming, nothing
implemented
Three more requirements captured while fresh, same design session:
(7) home-blocks write path must check for a home-blocks signature
before ever writing to an inserted drive, warn and refuse on foreign/
unrecognized/blank media instead of silently claiming it; (8) zuse
credential minting is one-way, asymmetric with an operator drive's
presumed re-provisioning path; (9) console/VM split -- console is
generic and shared, drive insertion spins up a per-identity VM (a
Tripod-birth-mechanism consumer), and console-to-VM attachment is a
key/lock match, structurally similar to ACL-PIN's existing key model
but not yet confirmed to reuse it directly.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
direction notes -- brainstorming only, nothing implemented
Captures the direction from a design conversation immediately following
the ACL-TTL campaign close (Section T): Phase 8 PKI/thumbdrive context,
confirmation that zero USB code exists anywhere in the kernel today,
verification that the block-address-space layout the conversation
converged on independently already matches block_subsystem.h's own
documented (unimplemented) chained-device design almost exactly, and
six requirements gathered in order (no quota for now, re-insertion
consistency, identity-derived not attach-order-derived block ranges,
drive-carries-its-own-map, bidirectional transparent block migration
as a state machine, and sk_repl_idle() as the likely trigger hook --
already an empty coarse-cadence placeholder found during Section R).
Explicitly not a spec or plan of record -- written up so the next
session starts from an accurate baseline instead of re-deriving the
shape from scratch. No code, no design doc, no capsule work started.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Section T -- +0.0603%, final accepted figure
Extended Section S's 3-seed/9-pair campaign to 6 seeds/18 pairs (36
cells) per Captain Bob's request for a fuller campaign before moving
on. All 36 cells: 480/480 rows, 0 errors, 17,280/17,280 rows total.
Every one of 18 disabled cells reads exactly 261063 ticks -- CV=0.000%
across all 3 architectures and 6 seeds, zero exceptions. Every enabled
cell's tick count is fully determined by seed alone, identical across
all 3 architectures, zero exceptions. Pooled overhead across all 18
pairs: +0.0603% (mean +0.0603%, stdev 0.0008%, range +0.0598%-
+0.0617%) -- statistically indistinguishable from Section S's 9-pair
figure, now confirmed over double the data with 3 entirely new seeds.
This closes the ACL-TTL overhead measurement line of investigation
(Sections P, Q, R, S, T). +0.0603% is the final accepted figure.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
amd64/99999/enabled, aarch64/24680/disabled added (cell 26 needed a
retry after an unexplained external SIGTERM killed the qemu process
mid-boot -- matches a previously-noted, still-unexplained SIGTERM
recurrence from a process named "claude", first seen 2026-08-18;
1-line stub log from the killed attempt kept as audit trail). All
successful cells: 480/480 rows, 0 errors.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
amd64/24680/disabled, amd64/24680/enabled, aarch64/11111/enabled
added. All 480/480 rows, 0 errors. Cross-arch consistency continues
holding: seed 24680 gives 261219 on both riscv64 and amd64; seed 11111
gives 261222 on both amd64 and aarch64.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Extended from 3 to 6 seeds (added 24680/11111/99999) per Captain Bob's
request for a fuller campaign before moving on. amd64/11111/enabled,
riscv64/24680/enabled, riscv64/24680/disabled added. All 480/480 rows,
0 errors. Disabled-arm determinism (261063) holding across new seeds.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
