LithosAnanke/docs/v4.0.0/STICK.md

StarForth v4.0.0 — The x86_64 StarshipOS stick

Design, 2026-10-26, from Captain Bob's answers the same day (each quoted where it is used). The first of three designs toward the goal below; the other two, INSTALL and DOE/SDK/demos, are written after this one is approved.

Amended 2026-10-29 -- plug and play, a proxy Zuse, and the real Zuse on a second stick (Captain Bob: "i want this a plug & play solution" -- "plug it in, it boots to the prompt, no setup"). §2, §3, §4, §6, §6a, §7, §9, §10 and §11 carry the change; each says what it said before.

1. Intent

"the goal is to be able to deliver an entirely self hosted thumbdrive build that can deliver the entire OS for x86_ 64 asap." (Captain Bob, 2026-10-26)

"we want a functional try it image with INSTALL should users decide to install StarshipOS in their bare metal."

One USB stick, written from one image, that a person plugs into an x86_64 PC and boots from the firmware's boot menu. It is the whole operating system: StarshipOS on LithosAnanke, running v4 ("v4 only"). Until the person installs, it is a "try it" — like Ubuntu's — that leaves the PC's own disk untouched. Installing is a later design (INSTALL); after it, the stick is Zuse's key.

Ordering (ruled): "stick first, then Part A" — this goes ahead of ENGINE step 4 Part A. Three designs, in this order: (1) the stick, this file; (2) INSTALL; (3) S" <doe name>" DOE, SDK and demos.

2. What the person sees

1. They boot the stick from the PC's firmware boot menu.
2. The screen shows only the StarshipOS splash with a progress bar ("splash only, log on serial"). The whole boot log goes to the serial port, if there is one.
3. First boot of a stick: the kernel finds no Zuse on it and mints one — "minted on first boot, each stick its own Zuse." Amended 2026-10-29: the Zuse minted there is the stick's proxy Zuse (§6). Until a real Zuse is minted she is full Zuse ("full zuse until the real one is minted"): plug the stick in, boot, [zuse@Hera] ok>, nothing to set up.
4. Every boot: the kernel recognises Zuse on the stick and logs her in by itself — "automatic, like v3 does when the drive is attached." The splash gives way to the console: [zuse@Hera] ok>, typed to with the PC's USB or PS/2 keyboard. 4a. The real Zuse (amended 2026-10-29): from a session, Zuse mints the real Zuse onto a second stick (§6a). From then on she logs in with that stick plugged in beside the system stick. Booted with the system stick alone, the proxy can do one thing: "only mint a replacement zuse stick", on a fixed screen, not at a prompt (§6a). A replacement kills the old Zuse stick: "the old stick dies for good".
5. While they try it, what they write persists on the stick across reboots — "persist on the stick until INSTALL." Nothing is written to the PC's own disk.
6. If they pull the stick mid-session: "go headless until it's plugged back in." The console goes; the splash comes back; plugging the stick in again logs Zuse in again.

3. Rulings this design rests on

Ruling (2026-10-26)	Where
Boot to a headless splash until Zuse logs in	§2
Zuse's identity is on the same stick that boots	§4
Zuse logs in automatically, as v3 does when her drive is attached	§5
Each stick mints its own Zuse on first boot	§6
What a try-it session writes persists on the stick until INSTALL	§4, §7
Splash only on screen; the log on serial	§8
Pulling the stick: headless until it is plugged back in	§7
GPT for boot media and installed disks — overturns FABRIC-2.md §F.8 ("GPT dropped entirely") for these two kinds of media; on v4 only this system's stick is used (amended 2026-10-28)	§4
v4 only	§1
On the stick, system=v3 is refused: a line says v3 is not on this stick, and v4 boots	§5
The GPT code runs on every ISA; every clean qemu boot attaches a small GPT data stick (identity and Artemis partitions) over USB in place of virtio; virtio Artemis leaves v4	§9
The splash: a PNG-only converter now, the general converter interface later; scaled at build to 1024×683; its capsule ID is the hash of the converted pixels	§8
QEMU and bare metal ALWAYS hold parity (standing rule)	§9
Plug and play (2026-10-29): "plug it in, it boots to the prompt, no setup"	§2, §6
Every stick boots first as a proxy Zuse, full Zuse "until the real one is minted" on a second drive (2026-10-29; amends "Zuse's identity is on the same stick that boots", above)	§6, §6a
The proxy stays as a fallback, but once a real Zuse exists it may "only mint a replacement zuse stick", on a fixed screen ("the later" of a prompt or a fixed screen) (2026-10-29)	§6a
Minting a replacement: "the old stick dies for good" (2026-10-29)	§6a

4. The stick's layout

A GPT disk, written from one image built by make boot_image TARGET=PC (scripts/mkdiskimage.sh gains the partitions below). Three partitions:

#	Partition	GPT type	Contents
1	EFI System (FAT32)	EFI System (C12A7328-…)	the loader BOOTX64.EFI, starforth.cfg (system=v4), startup.nsh — as today's PC image
2	StarshipOS identity	a StarshipOS identity type GUID (new)	blank in the image; on first boot, Zuse's identity in today's home-blocks layout (homeblocks_sig.h: signature at devblock 1, identity record, cert), counted from the partition's start
3	StarshipOS Artemis	a StarshipOS Artemis type GUID (new)	today's Artemis disk layout (STFR volume header, artemis_sig_t genesis signature, the metadata fence holding Zuse's genesis marker), counted from the partition's start

• The kernel reads GPT (new: a GPT reader, on every ISA, used again by INSTALL). It reads the primary GPT header and entries (checking their CRC-32s) and makes a block device of each partition whose type is one of the two StarshipOS types: a thin blkio device that adds the partition's start to every block number and refuses blocks past its end.
• Which disk (my call). Zuse and Artemis are taken from one disk: the stick the PC booted from. The UEFI loader already knows its boot device; it passes it to the kernel (BootInfo), and the kernel takes the USB disk that matches it. Both StarshipOS partitions must be on that disk. A second stick, or a blank drive the person happens to have plugged in, is not used: no Zuse is minted onto it and it is not attached to the block subsystem. (So pulling the stick is never refused for a drive attached after it — blk_subsys_detach_device removes only the last device in the chain — and on replug Artemis is the first disk slot again, where the fence with Zuse's marker must be.) In QEMU, with no boot device among the USB disks (the clean qemu boots start from the ISO or the ESP image), the data stick (§9) is the one disk with both partition types; the rule is the same: one disk carries both.
• The identity and Artemis formats do not change. Every check that reads them (homeblocks_sig_check, capsule_zuse_boot_check, artemis_sig_check, the block subsystem) runs unchanged on the partition device.
• Raw identity drives on v4 — amended 2026-10-28 (Captain Bob, ruling R2 of plans/2026-10-27-stick-4-one-disk.md): this bullet said "raw identity drives stay accepted", which contradicted "one disk" above. On v4, Artemis and Zuse come only from this system's stick, and no other drive is attached — raw or GPT, blank or minted: "USB: a drive that is not this system's stick -- not used". Amended again 2026-10-29 (§6a): one other drive is used -- this system's real Zuse stick, a GPT disk with one StarshipOS identity partition whose identity matches the real Zuse key in the genesis marker. It is attached after the system stick's two partitions, so Artemis keeps the first disk slot. And while the minting of §6a asks for one, a stick the person names is written (after they confirm). Every other drive is still not used. Once Artemis is only on the stick, a raw drive could be Zuse's only as a copy of the stick's own identity partition, and attaching it before the stick would take the first disk slot, where the fence must be. This is not a "never" for other people's drives: drives of users minted by this system's Zuse, and checked by WIREBIND against her key, come with the users design after INSTALL (Captain Bob, 2026-10-28: an installed v4 system mints and accepts its own users' drives). On system=v3, raw identity drives are read exactly as before; v3 reads no GPT at all.
• Sizes: a minimum, and dynamic above it (Captain Bob, 2026-10-26: "pick like the generic size of any old ... thumb drive off the shelf ... I want the sizing to be dynamic, so like a minimum and then ... no max or reasonable max size"; "all to Artemis, identity stays at 500 MiB"). Set in one place, kernel/Makefile; none is fixed by the formats (the identity format records its own size, homeblocks_sig_t.metadata_devblocks):
  • The image as built: 2 GiB — ESP 64 MiB, identity 500 MiB, Artemis the rest. Small, so it is quick to write to a stick.
  • The minimum stick: 8 GB. Sticks on the shelf are 16–64 GB; 8 GB is the floor.
  • The identity partition stays 500 MiB. About half a million 1 KiB blocks for Zuse's keys and her own pool.
  • Artemis grows to fill the stick at its first boot (§5a), up to 2 TiB for the partition (the block layer numbers 1 KiB blocks with 32 bits: 4 TiB is its hard limit; 2 TiB keeps a margin and is past any thumb drive). Space past 2 TiB is left unused, and the boot says so.
  • A stick under 8 GB is not grown: it runs at the 2 GiB it was written with, and the boot says so.
• The Artemis partition is formatted when the image is built (my call), not on first boot: the image builder writes its STFR volume header and its artemis_sig_t genesis signature, so the kernel never meets a blank Artemis on a stick and never has to decide whether a disk may be formatted. (v4's rule that the boot writes no disk until its owner says so — kernel_main.c, sk_v4_block_chain's comment; ENGINE step 4 Phase 5 — is met: the stick's Artemis partition was made to be written, by the image's maker. The kernel confirms the format (blk_subsys_confirm_format) only for a partition whose GPT type is StarshipOS Artemis and whose artemis_sig_t checks out.)

5. Boot

Everything the identity gate does today (kernel/src/v4/sk_v4_identity.c), with five changes:

1. Where the disks are found. After POST, the kernel brings up every xHCI controller (as now) and, for the boot stick, reads its GPT: the Artemis partition is attached to the block subsystem as Artemis's disk (the first disk slot, so the metadata fence — Zuse's genesis marker — is on it), and the identity partition is checked as an identity drive. The virtio disk is no longer how v4 finds Artemis, in QEMU or anywhere (§9).
2. Entropy. rng_init() is called on the v4 path (it is not today); on x86_64 the backend is RDRAND (kernel/src/rng/rng.c). Minting needs it. On aarch64 and riscv64 the clean qemu boots mint with virtio-rng, the only backend those ISAs have (BRINGUP.md A5): a known QEMU-only path, which their own sticks (later) must replace with real hardware entropy.
3. The screen. The framebuffer is brought up on the v4 path, as v3 does (console_fb_init, kernel_main.c v3 path), but the console's text goes to serial only until Zuse logs in; the screen shows the splash (§8). When she logs in, the screen becomes the console.
4. The keyboard. The USB and PS/2 keyboard bridge v3's console reads (repl.c: sk_kbd_getc, sk_console_getc_raw, the per-tick xHCI servicing while a USB keyboard runs) is moved out of repl.c into a file both paths use, unchanged in behaviour, and the v4 line editor reads it as well as serial.
5. system=v3 is refused on the stick (ruled). The stick's kernel carries v3 too, and v3 has no GPT reader: it would see the whole stick as one raw drive and its genesis could mint over the partition table. So when the boot medium is a StarshipOS stick (a GPT disk with the two StarshipOS partition types), system=v3 is not obeyed: "System: v3 is not on this stick -- StarForth v4", and v4 boots.

5a. First boot: Artemis grows to fill the stick

Before genesis, on a stick whose GPT ends where the 2 GiB image ended and whose disk is larger (the first boot of a freshly written stick), the kernel grows Artemis:

• It moves the backup GPT header and entry array to the disk's end, extends the Artemis partition's last LBA to the end of the usable space (capped at 2 TiB of partition), and rewrites both headers with their CRCs (the GPT writer; INSTALL reuses it).
• It grows Artemis's volume to the partition: its STFR header's size, its free map for the new blocks, and its metadata fence (with the genesis marker's slot) moved to the new top, as the block subsystem lays a volume out (v3/src/block_subsystem.c).
• Growth writes metadata only — the GPT, the volume header, the free map, the fence — never the partition's data blocks. Through USB under QEMU's TCG, writing 16 GB would take hours; on a real stick, many minutes. The first boot's time is measured in the tests.
• It happens once: a stick already grown (its GPT reaches the disk's end) is not grown again. If power is lost mid-growth, the next boot finds either the old GPT (and grows again) or the new one (the backup header is written before the primary, so a torn write leaves one valid header).
• A stick under the 8 GB minimum is not grown (§4).

6. First boot: genesis on the stick

On the first boot of a stick, the identity partition is blank and the Artemis partition's fence has no genesis marker: capsule_zuse_boot_check says ZUSE_DRIVE_GENESIS. The kernel then does what v3's genesis does (capsule_zuse_boot_try_attach), with no VM: capsule_mint_identity(dev, NULL, "Zuse", "zuse", …) mints her onto the identity partition, and the genesis marker (her public key) is written to the Artemis partition's fence (blk_meta_zone_write(0, …)). "Zuse: genesis minted onto attached thumbdrive"; she is logged in.

• This lifts the identity gate's D2 ("recognise only") for the stick: genesis is allowed where the Artemis disk is one the kernel was given to write (§4). A blank Artemis that is not a stick's partition — QEMU's old blank disk/artemis.img, an unknown disk — still gets no genesis.
• The genesis is shared code: the VM-free part of v3's genesis (mint, then marker) is split out of capsule_zuse_boot_try_attach as capsule_zuse_boot_check was (D1), and both paths call it.
• If the mint fails (no entropy, a write error): "Zuse: genesis mint failed", and the system stays headless behind the splash. Nothing half-written is taken for an identity.

Amended 2026-10-29 -- the Zuse minted here is the stick's proxy Zuse. Everything above stands (the same genesis, at the same moment, onto the same partition); what changes is what she is:

• She is the proxy Zuse: full Zuse while no real Zuse exists ("full zuse until the real one is minted"), and after that only the fallback of §6a.
• Minted at first boot, not at build (my call). Captain Bob: "id always want the image to be with zuse as the first boot". The image could carry a proxy minted when it is built, but then every stick written from one image would share one proxy key -- an anti-goal (§10). Minted at first boot, each stick has its own, and the image holds no key at all. The person sees the same thing: the first boot ends at [zuse@Hera] ok>.
• The genesis marker gains a version (2) that holds two keys: the proxy's (written here) and the real Zuse's (zero until §6a writes it). Version 1 markers -- the minted pair in disk/zuse-scratch/, sticks built with STICK_PAIR -- read as a proxy with no real Zuse, so they log in as today. v3 reads only version 1, but v3 never runs from a stick (§5.5).
• Plug and play is reached here: make boot_image TARGET=PC, make write_stick DEVICE=..., plug in, boot, prompt. STICK_PAIR stays only for tests that need a known Zuse.

6a. The real Zuse, on a second stick (amended 2026-10-29)

Minting her. At the prompt, Zuse (the proxy, or a real Zuse) types MINT-ZUSE (name my call). The kernel asks for a stick to be plugged in, shows the one that arrives (its size and, from USB, its vendor and product), says everything on it will be erased, and writes nothing until the person types YES (my call: Captain Bob's other stick may not be blank). It then writes a GPT with one StarshipOS identity partition (the whole stick up to 500 MiB, as §4's identity partition; my call), mints a fresh Zuse identity into it (capsule_mint_identity, as genesis does), reads it back, and only then writes the real key into the genesis marker on the system stick's Artemis. "Zuse: real Zuse minted onto the second stick". The session goes on as the real Zuse.

• A failure writes no marker: if the mint or its read-back fails, the marker is not touched and nothing changes -- the old real Zuse stick, if there was one, still works.
• Done from the real Zuse's own session too it is how she replaces herself on purpose; the same steps, the same effect.

Every boot after. The system stick's proxy is recognised as before, then:

• The real Zuse stick plugged in (at boot, or later): her identity is checked against the marker's real key; she is logged in, [zuse@Hera] ok>. Pulling it ends her session (§7).
• No real Zuse stick: the proxy does not get a prompt. A fixed screen (screen and serial, my wording) says: "Zuse's stick is not here. Plug it in to log in. Or plug in another stick and press R to mint a replacement -- the old Zuse stick will stop working." Every other key is read and dropped, as typed-ahead keys are today (the identity gate's review item 4). Plugging in the real Zuse stick logs her in, as above. R runs the minting above, then she is logged in.
• The old stick dies: a replacement overwrites the marker's real key, so the old stick's identity no longer matches: "Zuse: not this system's Zuse stick -- not used".

What this leaves open (written down, not hidden): whoever holds the system stick can use the fallback to mint themselves a Zuse -- the old one then stops working, so the owner finds out, but the system stick stays a master key. Captain Bob chose the fallback knowing this (2026-10-29). Copying a system stick before a replacement and booting the copy later is not guarded against.

7. A session, and pulling the stick

• Writes persist on the stick — the Artemis partition — and nowhere else. The idle beat writes the node's updated blocks about once a second, as v3's does (blk_vm_flush_all in sk_repl_idle is the same code as SAVE-BUFFERS) (my call, for v3 parity): on v4 it is the kernel saving the node's block window's updated slots, at the prompt or while headless, never mid-line.
• Pulling the stick detaches both its partitions. Zuse's session ends ("Zuse: session ended -- reattach to re-authenticate"); the screen goes back to the splash; the system is headless. Blocks written since the last flush are lost, as with v3's unclean detach (my call).
• Plugging it back in finds the same partitions again; Artemis is reattached, Zuse is recognised and logged in, the console comes back.
• The kernel keeps running from memory while the stick is out: it was loaded into RAM at boot.
• With a real Zuse (amended 2026-10-29, §6a): pulling her stick ends her session and the fixed screen of §6a comes up (the system stick is still in). Pulling the system stick ends any session and the system is headless, as above; the kernel lets the Zuse stick go first, since the block subsystem detaches only the last device in its chain and hers was attached last.

8. The splash

• StarshipOS.png (1358×905; tracked at the repo root, copied to capsules/v4/splash/) is converted when the image is built by a PNG-only converter in mkcapsule (ruled: the general "Tika-ish" converter interface queued 2026-10-16 is designed later): PNG in, scaled to 1024×683, the framebuffer's raw 32-bit pixel format out (about 2.7 MB), with its width and height, baked in as a capsule blob like the fonts. Its capsule ID is the hash of the converted pixels. The PNG is decoded on the build machine (zlib there); nothing PNG-shaped reaches the kernel.
• On screen: the image centred on black, scaled down if the screen is smaller (never up), and a progress bar under it.
• The progress bar (my call) advances at fixed boot milestones the kernel already passes: hardware up, the ROM has assembled the system, the capsules are loaded, POST has passed, the disks are found, Zuse is recognised (or minted). Six steps; it does not estimate time.
• Serial carries the full boot log throughout, as today.

9. QEMU, and parity

Standing rule: "we must ALWAYS maintain QEMU and bare metal builds hold parity."

• QEMU boots the stick image itself, as boards/BRINGUP.md §3.2 rehearses the PC image: q35 with OVMF, the image as a USB stick on the xHCI controller (a copy of it: the kernel writes to it), no -cdrom, no virtio disk, no separate thumbdrive. The kernel finds Artemis and Zuse through the same USB storage driver and GPT code it uses on a PC.
• The clean qemu boots, all three ISAs (ruled): each attaches a small GPT data stick — the identity and Artemis partitions, no ESP — over USB on the xHCI controller, in place of the virtio disk and the raw scratch identity drive. Built by make from the same partition layout as the stick (§4), fresh for each boot, so the first boot mints. Every v4 boot then finds Zuse and Artemis the same way, on every ISA; virtio Artemis leaves the v4 path (sk_v4_block_chain keeps fast RAM and the ramdrive). v3's own boot (system=v3) is not changed.
• Entropy: QEMU's CPU is given RDRAND (-cpu max or +rdrand), so the same RDRAND path runs in both; virtio-rng is not what makes minting work in QEMU.
• The screen and keyboard: QEMU's display and a USB keyboard on its xHCI controller, and its PS/2 keyboard, are the same drivers the PC uses.
• Acceptance once the stick works: the three-ISA clean qemu boots with the data stick, to [zuse@Hera] ok> with POST passing and dict_hash equal; and for x86_64 the stick image booted as above, from a fresh copy (first boot: genesis) and then the same copy again (recognition). The identity gate's QEMU defaults (D4: disk/zuse-scratch/) are retired then. Amended 2026-10-29 (§6a): QEMU tests the real Zuse stick with a second USB stick on the same xHCI controller (as the two-stick session does today): MINT-ZUSE onto it; reboot with the system stick alone (the fixed screen; keys typed there do not run); plug the Zuse stick in (the prompt); mint a replacement with R onto a third stick; plug the old one in ("not this system's Zuse stick -- not used").
• What QEMU cannot show (written down, not assumed): the PC's own firmware and its USB controller's firmware handoff (BRINGUP.md A1), its real framebuffer modes, a legacy-free PC's PIC (S3). Those wait for the bench.

10. Goals, non-goals, anti-goals

Goals: §2, on a real x86_64 PC and identically in QEMU; v4 only.

Non-goals (later designs): INSTALL; DOE, SDK, demos; WIREBIND identities and other users on the stick; ARM and RISC-V sticks (the Pi build later adds a GPIO vocabulary/VM, which does not exist yet).

Anti-goals — a failure even if it boots:

• Anything written to the PC's own disks before INSTALL.
• Two sticks sharing one Zuse (every stick mints its own).
• (2026-10-29) Setup before the first prompt: anything to type, edit or choose between writing the stick and [zuse@Hera] ok> (the PC's firmware settings -- Secure Boot off, the stick first -- are the PC's, written in the stick's notes, not ours).
• (2026-10-29) Once a real Zuse exists: a prompt for the proxy, or anything she can do but mint a replacement; an old Zuse stick that still logs in after a replacement; a marker written before the new stick's identity has been read back.
• A prompt on screen with no Zuse logged in, or typed-ahead keys run as her (the identity gate's review items 1 and 4 stand).
• A path that works in QEMU and not on a PC, or the reverse.
• v3 code changing behaviour (shared code split out, as D1, with v3's behaviour unchanged).

11. What is built, in order

Each an increment with the full acceptance (.claude/CLAUDE.md), each test a QEMU session written first and seen to fail:

1. The keyboard bridge shared, and the v4 screen: the framebuffer and the USB/PS-2 keyboard on the v4 path (§5.3, §5.4); serial-only text until login; the console on screen after.
2. The GPT reader and partition block devices, every ISA (§4); raw devices still read as now.
3. The images: the stick (three partitions) and the data stick (two), Artemis formatted and signed at build (§4); QEMU boots the stick as a USB stick, and every clean qemu boot attaches the data stick (§9). Amended (Captain Bob, 2026-10-27): the data stick is wired into the qemu targets behind DATASTICK=1, off by default -- until increments 4 and 5 the kernel cannot take Artemis from it or mint Zuse onto it, so as the default it would leave every acceptance boot headless. Increment 5 turns it on and retires the scratch pair and the virtio disk.
4. Artemis and Zuse from one disk: the boot device from the loader, the partitions found and attached, virtio Artemis off the v4 path; recognition of a minted stick; entropy on the v4 path; system=v3 refused on a stick (§4, §5).
5. Genesis on the stick, and growth (§5a, §6): the GPT writer; Artemis grown to fill the stick, metadata only; genesis. Tested on a fresh 16 GB sparse stick image (first boot: grows, mints, the prompt; the second boot of the same copy: recognised, not grown again; the first boot's time recorded) and a 4 GB one (below the minimum: not grown, said so). Amended 2026-10-29: the genesis is the proxy's, with the version 2 marker (§6); the fresh stick's first boot reaching [zuse@Hera] ok> with nothing set up is the test of plug and play. 5a. The real Zuse stick (2026-10-29) (§6a): MINT-ZUSE and its confirmation, the GPT and identity written to the second stick, the marker's real key; recognition of the real Zuse stick; the fixed screen and its R; the old stick refused after a replacement.
6. Pull and replug (§7), and the flush.
7. The splash and progress bar (§8), with the mkcapsule PNG converter.
8. Acceptance moves to the stick boot for x86_64 (§9).

12. Left to the builder

• The two StarshipOS partition type GUIDs (generated once, recorded in a header and in mkdiskimage.sh).
• How the GPT reader handles a damaged primary header (use the backup, or refuse; refusing is enough for a stick we wrote).
• The splash blob's exact header, and how the converter fits the "Tika-ish" interface's table.
• Where the shared keyboard bridge lives (a HAL input file, not repl.c).