From 03099f2c5181228bb73347137409fc54dc323fa7 Mon Sep 17 00:00:00 2001 From: rajames Date: Mon, 26 Oct 2026 19:50:32 -0400 Subject: [PATCH] docs(v4): the stick's sizes -- a minimum, and Artemis grows to fill the stick Captain Bob, 2026-10-26: sized for an off-the-shelf thumb drive, "a minimum and then ... no max or reasonable max size"; "all to Artemis, identity stays at 500 MiB". The image is 2 GiB (ESP 64 MiB, identity 500 MiB, Artemis the rest); the minimum stick 8 GB; at first boot Artemis grows to fill the stick, up to 2 TiB, writing metadata only (GPT, volume header, free map, fence); a stick under 8 GB is not grown. With genesis, increment 5; the GPT writer is INSTALL's too. Co-Authored-By: Claude Opus 5.5 --- docs/v4.0.0/STICK.md | 46 +++++++++++++++++++++++++++++++++++++------- 1 file changed, 39 insertions(+), 7 deletions(-) diff --git a/docs/v4.0.0/STICK.md b/docs/v4.0.0/STICK.md index 9bb53068..8f760fd5 100644 --- a/docs/v4.0.0/STICK.md +++ b/docs/v4.0.0/STICK.md @@ -84,11 +84,21 @@ gains the partitions below). Three partitions: subsystem) runs unchanged on the partition device. - **Raw identity drives stay accepted:** a device with no valid GPT is read as today (the minted scratch pair in `disk/zuse-scratch/`, any v3 identity drive). -- **Sizes:** the image is a fixed size and does not grow to fill a bigger stick. Partition sizes are - set at build time, in one place, `kernel/Makefile`, and are not fixed by the formats: ESP 64 MiB, - identity 500 MiB to start (Captain Bob, 2026-10-26: "64 megabytes does not need to be an engraved - in stone size ... start maybe 500 megabytes"; the identity format records its own size, - `homeblocks_sig_t.metadata_devblocks`), Artemis the rest of a 2 GiB image (my call). +- **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 @@ -124,6 +134,25 @@ Everything the identity gate does today (`kernel/src/v4/sk_v4_identity.c`), with 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 @@ -205,7 +234,7 @@ Standing rule: "we must ALWAYS maintain QEMU and bare metal builds hold parity." **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); growing the image to fill a bigger stick. +not exist yet). **Anti-goals — a failure even if it boots:** - Anything written to the PC's own disks before `INSTALL`. @@ -229,7 +258,10 @@ first and seen to fail: 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** (§6). +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). 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).