From 528bed08745f8bebe644e0cc2b69d2fef8f65fcc Mon Sep 17 00:00:00 2001 From: rajames Date: Thu, 15 Oct 2026 05:46:56 -0400 Subject: [PATCH] docs(v4.0.0): MACHINE.md -- rulings: the VM is a machine; .f18 pretty-printed text; v3 deleted at parity; the whole system loads before POST Co-Authored-By: Claude Opus 5.5 --- docs/v4.0.0/MACHINE.md | 39 +++++++++++++++++++++------------------ 1 file changed, 21 insertions(+), 18 deletions(-) diff --git a/docs/v4.0.0/MACHINE.md b/docs/v4.0.0/MACHINE.md index 9f2ad596..346b05e7 100644 --- a/docs/v4.0.0/MACHINE.md +++ b/docs/v4.0.0/MACHINE.md @@ -57,15 +57,16 @@ width (32 and 64 bits). (ruled 2026-10-15): 1. **`forth79.4th`**: the FORTH-79 Standard, adhered to 100 percent. 2. **`starforth.4th`**: the StarForth words. - 3. **Anything else**: every other capsule, such as `starshipos.4th`. + 3. **Anything else**: every other system capsule, such as `starshipos.4th`. All three load + before POST (section 7, item 4). - Ruled: the kernel loads `forth79.4th` as the system's own vocabulary, before POST and before + Ruled: the kernel loads them as the system's own vocabulary, before POST and before `init.4th`, the way v3 registers its words. 4. **POST**, with the existing test DSL: the case table `v4/system/post_cases.c` (name, lines, expected error, stack and output) and its runner `v4/system/post.c`. Seal before it, `COLD` after, as now. -5. **`init.4th`.** From here the boot is `init.4th` only. It `EXEC`s `starshipos.4th` and sets - `STARSHIPOS` as the search vocabulary. No boot policy is written in C. +5. **`init.4th`.** From here the boot is `init.4th` only: what must follow `COLD`, such as + setting `STARSHIPOS` as the search vocabulary. No boot policy is written in C. 6. `ok>`. The **loader** in steps 2 and 3 is whoever owns the machine: the kernel on bare metal, the @@ -88,7 +89,7 @@ streams the ROM instead. | `v4/src/text.c`, the assembler in C | The ROM's assembler is F18 code. `text.c` builds the ROM, as the first assembler builds the next. | | `forth79.4th`: `U*`, `U/MOD` only | Every FORTH-79 word that is not an opcode, a register or the FORTH machinery (`NUCLEUS.md` 4, rule 1). It moves group by group, with POST after each (`NUCLEUS.md` 8, step 3). | | `boot_capsules[]` in `v4/system/boot.c` | The system list (step 2, then step 3) is the loader's. Everything after POST is `init.4th`'s. | -| `capsules/v4/starshipos.4th` (uncommitted) | `EXEC`ed by `init.4th` | +| `capsules/v4/starshipos.4th` (uncommitted) | A system capsule, loaded before POST | ### 5.1 v3 leaves the build @@ -112,7 +113,7 @@ binary only to write the cases again. Proof: the same `dict_hash`, `PARITY:V4_POST tests=538 pass=538`. 2. **The trailer.** The `.v4` files become `.f18` blobs. The boot runs ROM, then `.f18`, then `forth79.4th`, then POST. `mkimage.c` keeps only the ROM. -3. **`init.4th`.** It takes over after POST. `starshipos.4th` is loaded from it. +3. **`init.4th`.** It takes over after POST. `starshipos.4th` joins the system capsules. 4. **Hera** streams the ROM, not the nucleus. 5. **FORTH-79 out of the `.f18`**, group by group, into `forth79.4th`, with POST after each. 6. **v3 out of the build.** @@ -122,19 +123,21 @@ Each step is accepted as `.claude/CLAUDE.md` says: all three; - `make -C v4 test-32`. -## 7. For Captain Bob to rule +## 7. Ruled 2026-10-15 -1. **What the ROM's assembler knows of names.** `text.c` today has `header`, which lays down a - FORTH dictionary entry. That is FORTH, so it belongs in `.f18` source. The ROM would know - only its own symbols: labels and named addresses. Is that the line? -2. **Format of an `.f18` blob.** `.4th` keeps the `Block N` format, 64 × 16. Today's `.v4` has - 1080 lines over 64 characters. Proposed: `.f18` is plain text with no block format. -3. **The `v3/` tree.** Deleted, or kept out of every build but left in the repository? Kept, - it lets `mkpost.py` write POST's cases again. -4. **Where `starforth.4th` loads.** Proposed: with `forth79.4th`, by the kernel and before - POST, because v3's StarForth words are system words and v3's POST covers them. Layer 3 is - `init.4th`'s. -5. **Where the standard's names live.** "100 percent" in `forth79.4th`: does it name all 130 +1. **The VM is a machine**: registers, a control unit, the opcodes. Names, dictionary entries + (`text.c`'s `header`) and every other part of FORTH are source, not machine. +2. **`.f18` blobs are plain text**, laid out as pretty-printed F18 code. No `Block N` format. +3. **v3 is deleted once v4 is shown at parity with v3, not before.** Until then the `v3/` tree + stays, as the reference to compare against and for `mkpost.py`. +4. **Everything that can load before POST does.** That is the system. `forth79.4th`, + `starforth.4th` and every other system capsule load before POST. POST tests the system. + +## 8. Still open + +1. **Where the standard's names live.** "100 percent" in `forth79.4th`: does it name all 130 Required words, including the ones that are single opcodes (`DUP`, `+`, `@`)? Proposed: yes. The `.f18` primitives carry their own names, and `forth79.4th` gives every standard word its standard name and behaviour. The `.f18` layer then holds no FORTH-79 names at all. +2. **What `init.4th` does after POST**, now that the system loads before it: what follows + `COLD`, such as making `STARSHIPOS` the search vocabulary and starting Hera's births.