diff --git a/docs/v4.0.0/STICK.md b/docs/v4.0.0/STICK.md index a0bcd956..867924da 100644 --- a/docs/v4.0.0/STICK.md +++ b/docs/v4.0.0/STICK.md @@ -4,6 +4,10 @@ Design, 2026-10-26, from Captain Bob's answers the same day (each quoted where i 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 @@ -27,10 +31,17 @@ and demos. 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." + 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 @@ -53,6 +64,10 @@ and demos. | 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 @@ -86,7 +101,11 @@ gains the partitions below). Three partitions: `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". Once Artemis is only on the stick, a raw drive could be Zuse's + 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, @@ -181,6 +200,53 @@ the genesis marker (her public key) is written to the Artemis partition's fence - 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 @@ -194,6 +260,10 @@ the genesis marker (her public key) is written to the Artemis partition's fence - **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 @@ -233,6 +303,11 @@ Standing rule: "we must ALWAYS maintain QEMU and bare metal builds hold parity." `[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. @@ -248,6 +323,12 @@ 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. @@ -274,6 +355,11 @@ first and seen to fail: 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).