docs(v4.0.0): correct V3-PARITY -- the pieces are not missing, v4 is beside them

The table called rows 1 and 6-12 missing in v4.  They are all in this
kernel and run today.  kernel_main.c calls sk_v4_run() before the fleet
tables, VM bootstrap, devices, Mama birth, heartbeat and fleet birth, and it
never returns, so the v4 node comes up beside the system and skips it.
Records how v3's boot fits together around the VM interface, and that the
open question is how the F18 engine takes the VM's place behind it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
rajames
2026-10-05 16:49:52 -04:00
co-authored by Claude Opus 5.5
parent e88032b7e8
commit 79db64c4e2
+58
View File
@@ -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