diff --git a/docs/v4.0.0/V3-PARITY.md b/docs/v4.0.0/V3-PARITY.md index 7b6164dc..7ed1b48a 100644 --- a/docs/v4.0.0/V3-PARITY.md +++ b/docs/v4.0.0/V3-PARITY.md @@ -38,6 +38,64 @@ Rows 1, 6, 9, 10 and 11 are messaging, blocks and the console's wider setting. They are to be discussed before anything is written about them. Section 2 is row 3. +## 1a. Correction (2026-10-05): the table above is wrong about "Missing" + +Captain Bob: "You haven't looked at the codebase. You're assuming missing +pieces that are not missing and ignoring the entire v3 architecture. Don't +look at pieces until you see how they fit." + +The table was made from a boot log and a few functions. Read as a whole, +the system is this. + +**How v3 fits together.** After the hardware milestones, `kernel_main.c` +(`kernel_main_deep`, from line 526) does, in order: + +1. Fleet tables, before any VM exists: Stadium, sessions, switch-signal, + kernel-Hermes channels and queues; Hera made patron zero. +2. `sk_vm_bootstrap_parity()` (`kernel/src/vm/bootstrap/sk_vm_bootstrap.c`): + one `VM` is initialised with the kernel's host services; the capsule + hooks and the VM registry are set up; its fleet physics is seeded + (`vm_physics_init`); the kernel's own words are registered (`BIRTH`, + `KILL`, the capsule words); the block subsystem is given to it; POST + runs; parity is collected and printed. +3. Devices: block RAM and ramdrive, PCI, entropy, Artemis's virtio disk and + its signature, keyboard, USB, framebuffer. +4. The capsule directory is copied and `capsule_birth_mama()` runs + `init.4th` on that VM; `BIRTH` and `CAPSULE-BIRTH` are pinned. +5. The timer starts: the heartbeat. +6. Stadium and kernel-Hermes self-tests; Hestia and Artemis are born, each + another `VM`; Zuse; the banner; the REPL. + +Every one of those steps is kernel code in `kernel/src` and works on a +`VM` through one interface: the `VM` structure (`v3/include/vm.h`) and the +functions on it. Counted across the kernel's services, the most used are +the stacks (`vm_push`, `vm_pop`), `vm_interpret`, `vm_find_word`, the +dictionary (`latest`, `here`, `DictEntry`), `error`, the heartbeat state, +the rolling window, and `stadium_vm_id`. + +**What v4 is, by its own justification** (`JUSTIFICATION.md` section 16): +"The only difference is the machine underneath: the F18-derived engine +instead of the original StarForth VM." And section 15: StarshipOS is +"LithosAnanke running the v4 F18 engine", with the FORTH-79 vocabulary and +"the StarshipOS-specific portions" stored as capsules. + +**So nothing in rows 1, 6, 7, 8, 9, 10, 11 or 12 is missing.** It is all +in this kernel and it all runs today. What is wrong is where v4 was put: +`kernel_main.c` calls `sk_v4_run()` *before* step 1 and it never returns. +The v4 node comes up beside the system instead of inside it, and so the +whole of the architecture is skipped. That is the detour. The capsule +loader, POST and parity lines built on 2026-10-05 (`v4/system/boot.c`) +repeat, for a lone node, things steps 2 and 4 already do for a `VM`. + +**The real question** is therefore not "what does v4 lack" but "how does +the F18 engine take the place of the StarForth VM behind that one +interface", so that steps 1 to 6 run as they do now. That has not been +worked out, and nothing here should be read as a plan for it. + +Section 2 below was written before this correction. Its account of what +v3's inner loop does is from the code and stands. Its section 2.2, "what +v4 has", describes the lone node, not v4 in its place in the system. + ## 2. Row 3: physics and per-word heat ### 2.1 What v3 does