admin/LithosAnanake
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
rajames
2026-10-15 05:46:56 -04:00
co-authored by Claude Opus 5.5
parent 3eca84e433
commit 528bed0874
1 changed files with 21 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/v4.0.0/MACHINE.md
+21 -18
View File
@@ -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.