docs(v4.0.0): the hosted and bare-metal products part here

Captain Bob, 2026-10-05.  Withdraws the claim that the hosted v4 product
should become v3's hosted program with the node as its interpreter.  The
bare-metal product is LithosAnanke with the node in the VM's place; the
hosted product is its own and need not follow it; the six builds no longer
have to print the same lines.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
rajames
2026-10-05 19:14:24 -04:00
co-authored by Claude Opus 5.5
parent 085d0881de
commit ad3efdda65
+30 -16
View File
@@ -173,12 +173,27 @@ base, `vm_cleanup` — is not the engine and stays.
So the swap is a third interpreter file, for both builds: the same
functions, answered by a node. Everything else of v3 is compiled as it is.
**This changes what the hosted v4 product is.** It is not a separate
program (`v4/tools/hosted.c`, `v4/system/boot.c`). It is v3's hosted
program — its `main`, its REPL, its physics, its POST — built with the
node as its interpreter, exactly as the kernel product is v3's kernel
built the same way. `hosted.c` and `boot.c` are the lone node's and go
when that build reaches its prompt.
**The two products part here (Captain Bob, 2026-10-05):** "I would say we
are at a fair point where the hosted product and the bare metal product
diverge completely."
This section first said the hosted v4 product should become v3's hosted
program with the node as its interpreter. That is withdrawn. From here:
- **The bare-metal product** is LithosAnanke with the node in the VM's
place. Everything in this document about the kernel's interface, word
records, the hook at `call`, the fleet and identity is the bare-metal
product's. The third interpreter file is for the kernel build.
- **The hosted product** is its own thing and is not required to follow
the bare-metal one. Today it is the node, the nucleus, the FORTH-79
capsule, POST and its own prompt (`v4/tools/hosted.c`,
`v4/system/boot.c`), and it works on three ISAs.
- **The six builds no longer have to print the same lines.** The three
hosted builds agree with each other; the three bare-metal builds agree
with each other.
What the two still share, if anything beyond the engine in `v4/src`, is
for Captain Bob to say.
**Two things in v3's C words do not carry over as they are**, and must be
dealt with word by word:
@@ -233,13 +248,13 @@ the kernel will run a fleet, and goes with the lone node at step 5.
| Built 2026-10-05 | What becomes of it |
|---|---|
| `kernel_main.c` calling `sk_v4_run()` before the fleet tables | Goes at step 5. Until then it is how the bare-metal build is kept booting while the interface is built. |
| `v4/system/boot.c`: its own capsule loader and `PARITY:V4_*` lines | Goes at step 5, when v3's birth protocol loads the capsules and prints v3's parity lines. |
| `kernel_main.c` calling `sk_v4_run()` before the fleet tables | Goes at step 4. Until then it is how the bare-metal build is kept booting while the interface is built. |
| `v4/system/boot.c`: its own capsule loader and `PARITY:V4_*` lines | Stays for the hosted product. On bare metal v3's birth protocol loads the capsules and prints v3's parity lines (step 4). |
| The node's prompt loop, and the code that strips ` ok` from its output | Goes at step 1. |
| `capsules/v4/forth79.4th`, `post79.4th`, `mkpost.py`, the rules | Stay. POST is the gate for every word moved out of the nucleus. |
| `(CATCH)`, `(EMIT-HOOK)`, `NODE-ERROR` by name | Stay; POST uses them. |
| The per-call-target count (`v4/src/heat.c`, `call[]`) | Goes at step 3, when the node does at `call` what v3 does. |
| The hosted Linux product, as `v4/tools/hosted.c` | Goes at step 4: the hosted product is v3's hosted program with the node as its interpreter (3c). |
| The hosted Linux product (`v4/tools/hosted.c`, `v4/system/boot.c`) | Stays, as its own product (3c). |
## 5. Steps
@@ -275,14 +290,13 @@ its logs.
3. **A word is being executed (3.5).** The hook at `call`; the ACL's
countdown and recheck; the word's count; `stadium_word_dispatch`.
In-line words become calls. The per-call-target count goes.
4. **The node as v3's interpreter, hosted.** The third interpreter file
(3c). v3's hosted program built with it: `vm_interpret` hands the node
the line; `register_word` makes a kernel word and its record; the
node's own words get records. It reaches v3's prompt. v3's POST runs
4. **The node as the kernel's interpreter.** The third interpreter file
(3c), for the kernel build. Under `STARFORTH_V4` the kernel's boot
brings the node up where it brings a v3 VM up: `vm_interpret` hands the
node the line; `register_word` makes a kernel word and its record; the
node's own words get records. `sk_v4_run()` goes. v3's POST runs
through it and its failures are the list of what is not yet there.
5. **The same, in the kernel.** Under `STARFORTH_V4` the kernel's boot
brings the node up where it brings a v3 VM up. `sk_v4_run()`,
`boot.c` and `hosted.c` go.
5. (Folded into 4: the hosted product is no longer part of this path.)
6. **Hera as v3 has her.** `init.4th` runs on the node; v3's whole POST
passes; v3's parity lines.
7. **The fleet.** Hestia and Artemis; message delivery; who runs next.