rajamesandClaude Opus 5.5
5d6043e37e
capsules/v4/post79.4th: 537 of v3's POST cases for the FORTH-79 Required Word Set, each carrying what the hosted v3 binary did with the same line (error or not, the stack, the length and checksum of what it printed). Written by v4/tools/mkpost.py. The harness is FORTH-79 plus the two nucleus hooks. docs/v4.0.0/NUCLEUS.md section 6. - NODE-ERROR has a FORTH name: how a definition in FORTH raises an error - the boot passes POST only on seeing its tally line with fail=0 - POST is not in the boot yet (V4_POST_AT_BOOT=0); make -C v4 post runs it Result: tests=537 pass=439 fail=98. The 98 are not yet sorted into v4 defects and differences needing a ruling; v4/README.md has a first reading. Verified: make -C v4 test passes; hosted-check passes on three ISAs; clean qemu with STARFORTH_V4=1 on amd64, aarch64 and riscv64 reaches ok> with the same hashes as hosted (logs/20261005-1601xx..1604xx). Nothing was typed at a bare-metal prompt. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
113 lines
5.3 KiB
Markdown
113 lines
5.3 KiB
Markdown
# v4/
|
||
|
||
StarForth v4: the 32-instruction F18-derived core. The design lives in
|
||
`docs/v4.0.0/JUSTIFICATION.md` (why) and `docs/v4.0.0/DECOMPOSITION.md`
|
||
(every v3 word mapped to a v4 fate).
|
||
|
||
The first deliverable is the hosted C99 golden model (`JUSTIFICATION.md` §10,
|
||
step 1). It must pass POST and hold K≡1.0 with 32- and 64-bit cells on all
|
||
three host ISAs.
|
||
|
||
Acceptance (`JUSTIFICATION.md` §16): v4 must be equivalent to v3 at any point
|
||
in time, with the same vocabularies and behaviour, on the F18-derived engine;
|
||
and every ISA, hosted and bare metal, must still reach its `ok` prompt.
|
||
`make -C v4 test` passing is a development check, not acceptance.
|
||
|
||
What exists so far is the single node: registers, circular stacks, memory, all
|
||
32 opcodes, per-opcode and per-call-target heat, and three console
|
||
registers (`CONSOLE-TX`, which captures output, and `CONSOLE-RX` and `CONSOLE-STATUS`, which hand out
|
||
input a test feeds) standing in for the console node until the mesh exists. The tests load definitions
|
||
onto a node either opcode by opcode (`v4/include/v4/asm.h`) or as text in the notation `DECOMPOSITION.md`
|
||
uses (`v4/include/v4/text.h`). `make -C v4 test` builds
|
||
and runs the tests at both cell widths; `make -C v4 sanitize` repeats them
|
||
under ASan and UBSan. There is no POST and no K measurement yet.
|
||
|
||
## The system: nucleus, capsules, prompt
|
||
|
||
`docs/v4.0.0/NUCLEUS.md` is the design. A v4 system is four things:
|
||
|
||
| Part | Where | What it is |
|
||
|---|---|---|
|
||
| Engine | `v4/src` | The golden model of the 32-opcode node |
|
||
| Nucleus | `v4/capsule/*.v4`, built by `v4/tools/mkimage.c` | The assembled words, as a memory image linked into the binary |
|
||
| Capsules | `capsules/v4/*.4th`, baked by `tools/mkcapsule.c` | FORTH source, loaded when the system comes up |
|
||
| Boot | `v4/system/boot.c` | Starts the nucleus, checks and loads each capsule, prints the parity lines, gives the prompt |
|
||
|
||
Two products link the same four and differ only in the console:
|
||
|
||
- **Hosted Linux**, `v4/tools/hosted.c`: `make -C v4 hosted` builds
|
||
`v4/build/starforth4-amd64`, `-aarch64` and `-riscv64`, static, 64-bit cells.
|
||
- **Bare metal**, `kernel/src/v4/sk_v4.c`: `make -f kernel/Makefile ARCH=<arch> STARFORTH_V4=1`.
|
||
|
||
A boot prints:
|
||
|
||
```
|
||
PARITY:V4_NUCLEUS words=292 image_hash=0x...
|
||
PARITY:V4_CAPSULE name=v4:forth79.4th capsule_id=0x... capsule_hash=0x... dict_hash=0x...
|
||
PARITY:OK
|
||
ok>
|
||
```
|
||
|
||
Every build of one commit prints the same hashes. `make -C v4 hosted-check`
|
||
boots the three hosted binaries (the two foreign ones under user-mode QEMU)
|
||
and fails unless their output is identical and ends in `PARITY:OK`.
|
||
|
||
A capsule line the node does not answer ` ok` to ends the boot, naming the
|
||
capsule, block and line, with `PARITY:FAIL` and `POST: FAILED`.
|
||
|
||
State, 2026-10-05, after the POST work began: all six builds load
|
||
`v4:forth79.4th` and reach `ok>` with the same lines:
|
||
|
||
```
|
||
PARITY:V4_NUCLEUS words=295 image_hash=0x3ed5d5fc83f0b026
|
||
PARITY:V4_CAPSULE name=v4:forth79.4th capsule_id=0xa4b74bdc7deaf204 capsule_hash=0xa4b74bdc7deaf204 dict_hash=0x118de9d37e682ea4
|
||
PARITY:OK
|
||
ok>
|
||
```
|
||
|
||
Bare-metal logs: `logs/20261005-160144/amd64/`, `logs/20261005-160234/aarch64/`,
|
||
`logs/20261005-160400/riscv64/`. Each run was ended once the prompt was in the
|
||
log; nothing was typed at a bare-metal prompt, so keyboard input there is not
|
||
yet verified. The capsules were unsigned (no signing key on this machine).
|
||
|
||
`forth79.4th` holds no definitions yet: every word is still in the nucleus.
|
||
|
||
## POST
|
||
|
||
`capsules/v4/post79.4th` is v3's POST cases for the FORTH-79 Required Word
|
||
Set, written by `v4/tools/mkpost.py` (`make -C v4 post79`): 537 cases in
|
||
blocks 7000–7112, covering 111 of the 130 required words. Each case carries
|
||
what the hosted v3 binary did with the same line — error or not, the stack,
|
||
the length and checksum of what was printed — and v4 must do the same.
|
||
|
||
**POST does not pass yet, so it is not in the boot.** `make -C v4 post` builds
|
||
the amd64 system with it (`-DV4_POST_AT_BOOT=1`) and boots it:
|
||
|
||
```
|
||
PARITY:V4_POST tests=537 pass=439 fail=98
|
||
PARITY:FAIL
|
||
POST: FAILED
|
||
```
|
||
|
||
The 98 are not yet sorted into v4 defects and differences that need a
|
||
ruling. A first reading finds four kinds:
|
||
|
||
| Kind | About | Examples |
|
||
|---|---|---|
|
||
| The case prints or leaves a memory address, which differs between the two machines | 40 | `HERE`, `PAD`, `1 BLOCK`, `BL WORD`, `CONTEXT @ .`, `FIND` |
|
||
| v3 departs from FORTH-79 and v4 follows the standard | 35 | `PICK` and `ROLL` count from 1; `<# # #S #>` take a double number; `LEAVE` ends the loop at the next `LOOP`; `>R` `R>` only inside a definition |
|
||
| The case assumes v3's byte address units, where a v4 address unit is a cell (D-1) | 8 | `42 , HERE 8 - @`, `PAD 42 OVER !` |
|
||
| Not yet understood | 15 | vocabulary cases, `LIST`'s layout, `16 BASE ! 255 .`, `321 EMIT`, cases v3 ends in an error and v4 does not |
|
||
|
||
Required words with no v3 case, and so no POST case: `U*` `U/MOD` `?`
|
||
`EXECUTE` `KEY` `EXPECT` `QUERY` `U.` `CONVERT` `'` `."` `LITERAL` `STATE`
|
||
`COMPILE` `[COMPILE]` `(` `QUIT` `BLK` `79-STANDARD`. `U*` and `U/MOD` are
|
||
in neither v3 nor v4.
|
||
|
||
Twelve v3 cases are left out: three read the keyboard, two forget a word of
|
||
the system, two store to the search order, and five leave v3 unable to
|
||
continue in one session (`mkpost.py` prints the list).
|
||
|
||
The boot passes POST only on seeing the tally line with `fail=0`
|
||
(`v4/system/boot.c`); that no line was refused is not enough.
|