v4: init.4th and the ACL at call; the F18 ADR, ABI and artifact layout; ADR step 3 tasks 1-3 (mkf18a) #198

Merged
rajames merged 52 commits from StarForth-v4.0.0 into master 2026-11-20 18:42:33 +00:00
Owner

What and why

The work on StarForth-v4.0.0 since #197 (52 commits):

  • v4 init.4th and the ACL. The ACL policy is loaded after POST, then the search order (steps 1 and 2). init.4th pins the words that create or end nodes. The ACL countdown runs at call, as in v3, and the call hook may redirect (plan ruled first).
  • ADR 2026-11-19: F18 binary artifacts, ABI/API and live runtime updates. Recorded as given, with rulings 1–4. docs/v4.0.0/ABI.md (ADR step 1) and docs/v4.0.0/ARTIFACT.md (step 2) were drafted, then ruled choice by choice.
  • ADR step 3: artifacts in the build (docs/v4.0.0/plans/2026-11-19-f18-artifact-build.md, ruled §6 and §10):
    • task 1: text.c's address record (§8);
    • task 2: effect.c, stack effects derived from the code (§9);
    • task 3: mkf18a, the host tool that builds a train's .f18a, and make -C v4 artifacts (§11). This includes text.c's word attributes and import lines, and the artifact check in artifact.c.

Each was test-first, seen to fail; the evidence is in logs/20261119-*.

Acceptance

  • logs/20261119-230627/PROTOCOL.md for the head commit. The protocol ran on bd8997ff, with every stage passing. The head, 99851075, differs from it only in the evidence; scripts/check_protocol.sh accepts it.
    • amd64, aarch64 and riscv64 reach POST 990/990, with dict_hash=0x0ffb1d31c4aa7857 on all three (405 words);
    • stick-high reaches POST 990/990;
    • test-32: 42 programs, 0 failures;
    • the proofs, the images and the documents pass.
  • Logs from other runs made by hand are committed in logs/:
    • the earlier protocol on dc3803ab, whose boots and test-32 passed. It was not completed, because an evidence commit moved HEAD.
    • its two aarch64 runs that hit the 570 s foreground timeout, kept as stopped runs, not failures;
    • the make -C v4 test, test-32 and sanitize gates for each task.
  • Hardware this was tried on: none.

The record

  • docs/fabric/FABRIC-3.md has the ruling and what was built: not in this PR. The rulings and what was built are in docs/v4.0.0/ADR, ABI.md, ARTIFACT.md and the step 3 plan.
  • CHANGELOG.md: not a milestone.
  • Nothing in this PR is a fix nobody asked for. Two findings are recorded, not fixed:
    • the nucleus's UM*, D+ and DNEGATE have no fixed effect;
    • mkf18a's store check does not see stores below here.

🤖 Generated with Claude Code

https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm

## What and why The work on `StarForth-v4.0.0` since #197 (52 commits): - **v4 init.4th and the ACL.** The ACL policy is loaded after POST, then the search order (steps 1 and 2). init.4th pins the words that create or end nodes. The ACL countdown runs at call, as in v3, and the call hook may redirect (plan ruled first). - **ADR 2026-11-19: F18 binary artifacts, ABI/API and live runtime updates.** Recorded as given, with rulings 1–4. `docs/v4.0.0/ABI.md` (ADR step 1) and `docs/v4.0.0/ARTIFACT.md` (step 2) were drafted, then ruled choice by choice. - **ADR step 3: artifacts in the build** (`docs/v4.0.0/plans/2026-11-19-f18-artifact-build.md`, ruled §6 and §10): - task 1: `text.c`'s address record (§8); - task 2: `effect.c`, stack effects derived from the code (§9); - task 3: `mkf18a`, the host tool that builds a train's `.f18a`, and `make -C v4 artifacts` (§11). This includes `text.c`'s word attributes and `import` lines, and the artifact check in `artifact.c`. Each was test-first, seen to fail; the evidence is in `logs/20261119-*`. ## Acceptance - [x] `logs/20261119-230627/PROTOCOL.md` for the head commit. The protocol ran on bd8997ff, with every stage passing. The head, 99851075, differs from it only in the evidence; `scripts/check_protocol.sh` accepts it. - amd64, aarch64 and riscv64 reach POST 990/990, with `dict_hash=0x0ffb1d31c4aa7857` on all three (405 words); - stick-high reaches POST 990/990; - test-32: 42 programs, 0 failures; - the proofs, the images and the documents pass. - [x] Logs from other runs made by hand are committed in `logs/`: - the earlier protocol on dc3803ab, whose boots and test-32 passed. It was not completed, because an evidence commit moved HEAD. - its two aarch64 runs that hit the 570 s foreground timeout, kept as stopped runs, not failures; - the `make -C v4 test`, `test-32` and `sanitize` gates for each task. - [ ] Hardware this was tried on: none. ## The record - [ ] `docs/fabric/FABRIC-3.md` has the ruling and what was built: not in this PR. The rulings and what was built are in `docs/v4.0.0/ADR`, `ABI.md`, `ARTIFACT.md` and the step 3 plan. - [ ] `CHANGELOG.md`: not a milestone. - [x] Nothing in this PR is a fix nobody asked for. Two findings are recorded, not fixed: - the nucleus's `UM*`, `D+` and `DNEGATE` have no fixed effect; - `mkf18a`'s store check does not see stores below `here`. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
rajames added 52 commits 2026-11-20 00:02:32 +00:00
Captain Bob ruled "ACL at boot", loaded "From init.4th", the include
"Compose[d] in FORTH".
- capsules/v4/init.4th, at block 3980: S" v4:ACL.4th" CAPSULE-INCLUDE,
  then STARSHIPOS.
- capsules/v4/ACL.4th is the policy, git mv'ed from v4/capsule/ACL.fth
  and reflowed into chained 64x16 blocks, its text unchanged.
- CAPSULE-INCLUDE in centre.4th places a capsule and LOADs its lowest
  block. It is composed from CAPSULE-OPEN and CAPSULE-LINE, with no new
  C word.
- The mesh loads v4:init.4th after POST and COLD, its one fixed step
  there.

Test first in test_mesh_boot: the parity line, DOE without naming
STARSHIPOS, and ACL-BOOT pinned. The before-run failed.

After: 113 checks pass and POST is 990/990. All 52 tests, test-32 and
ASan/UBSan pass. The dictionary has 405 words. One amd64 session passes
18/18 with "ACL: active".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
Captain Bob ruled: "Also pin the kernel words". After the policy loads,
init.4th pins 11 words: BIRTH, BIRTH-AS, UNIT, KILL, UNIT-KILL, PAUSE,
RESUME, NODE-BORN, NODE-KILL, NODE-SLEEP and NODE-WAKE. Their fields
cannot be changed, so no policy can deny them. v4 has no CAPSULE-BIRTH.
The wiring words, NODE-WIRE and NODE-UNWIRE, are not pinned; they
neither create nor end a node.

Test first in test_mesh_boot: each of the 11 is pinned. The before-run
had all 11 unpinned. After: 114 checks pass, POST 990/990.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
v4 ACL: the countdown at call, as v3 -- the call hook may redirect
Build / Image PC (push) Successful in 6m13s
Build / Image MILKV (push) Successful in 6m40s
Build / v4 tests (32- and 64-bit cells) (push) Successful in 14m18s
Build / Image RASPI (push) Successful in 3m11s
7af88cc704
Captain Bob ruled "As v3: add at call", "Engine: call redirects" and
"Build it".
- The engine's call hook returns where P goes.
- The kernel checks every call from code defined at run time. A TTL is
  counted down at the call. At a TTL of 0, or a denied word, the call is
  sent to (ACL-CALL), with the target on the data stack, which rechecks
  or refuses it by the word's own name, then goes on to it.
- A word being compiled is no longer checked, as in v3.

Two things were added while building, both from v3:
- (ACL-BUSY) turns the check off while the policy rechecks. Without it
  the recheck recursed.
- (ACL-CALL) does its own refusal and leaves WORD's buffer alone. A first
  version broke POST's CONVERT.digits.

Test first: test_mesh_boot's five new checks failed before; now 120 pass
and POST is 990/990. test_exec tests the redirect. test_host_quit's two
v4-only expectations now follow v3: a denied word compiles.

All 52 tests, test-32 and ASan/UBSan pass. An amd64 session passes 18/18.
Five alternating host boots: +1.4% median, inside the noise.
DECOMPOSITION.md 5.20 is updated, and the FPGA's call opcode is recorded
as owing the same redirect.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
ADR rulings 4: a word's logical identity is its capsule (content hash) + its name
Build / Image RASPI (push) Successful in 3m42s
Build / Image MILKV (push) Successful in 3m58s
Build / v4 tests (32- and 64-bit cells) (push) Successful in 13m55s
Build / Image PC (push) Successful in 3m57s
4f7521290a
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
ABI.md: the flags cell also has 8, in-line (compile.f18)
Build / Image RASPI (push) Successful in 3m32s
Build / Image PC (push) Successful in 7m23s
Build / Image MILKV (push) Successful in 7m12s
Build / v4 tests (32- and 64-bit cells) (push) Successful in 14m9s
f8be000b0a
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
Captain Bob withdrew the first answer, the ( -- ) comment, the same day:
it rested on a bad assumption tied to (-, the SDK's marker.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
ABI choice 7: safe activation is the first property proved; the ABI v0 contract is ruled
Build / Image RASPI (push) Successful in 5m54s
Build / Image PC (push) Successful in 7m15s
Build / Image MILKV (push) Successful in 6m17s
Build / v4 tests (32- and 64-bit cells) (push) Successful in 14m53s
b450c92858
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
ARTIFACT.md: the F18 artifact's layout, draft for ruling (ADR step 2)
Build / Image RASPI (push) Successful in 5m28s
Build / Image PC (push) Successful in 4m15s
Build / Image MILKV (push) Successful in 5m11s
Build / v4 tests (32- and 64-bit cells) (push) Successful in 15m13s
e43cd63936
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
ARTIFACT.md: choice 5 ruled, code cells low-first; layout ruled
Build / Image RASPI (push) Successful in 4m17s
Build / Image PC (push) Successful in 5m37s
Build / Image MILKV (push) Successful in 5m40s
Build / v4 tests (32- and 64-bit cells) (push) Successful in 13m56s
fe0f709498
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
plans: step 3 §6.6 ruled, mkf18a / .f18a; design ruled
Build / Image RASPI (push) Successful in 4m41s
Build / Image PC (push) Successful in 5m50s
Build / Image MILKV (push) Successful in 6m2s
Build / v4 tests (32- and 64-bit cells) (push) Successful in 15m51s
29b99f90e6
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
v4 text.c: the address record (ADR step 3, task 1)
Build / Image RASPI (push) Successful in 4m13s
Build / Image PC (push) Successful in 3m51s
Build / Image MILKV (push) Successful in 4m30s
Build / v4 tests (32- and 64-bit cells) (push) Successful in 17m32s
4d64e677f5
Every cell laid down that holds an address of the assembly is recorded,
with its branch slot or 7 for the whole cell, as ARTIFACT.md's
relocations need. Test first: test_text 13 checks failed before.
test_host_rom_nucleus runs with the record on: 1825 branches, 664 whole
cells, the ROM still equal word for word. v4 test, test-32 and
ASan+UBSan pass.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
v4 effect.c: stack effects derived from code (ADR step 3, task 2)
Build / Image RASPI (push) Successful in 4m35s
Build / Image PC (push) Successful in 4m20s
Build / Image MILKV (push) Successful in 4m6s
Build / v4 tests (32- and 64-bit cells) (push) Successful in 15m23s
daf614285a
Walks a word's code, opcode by opcode with the engine's own counts, and
gives what it takes and leaves on both stacks, or why it has none.
Called and in-line words; recursion, computed jumps, paths that meet at
different depths and loops that leave a count have none. Test first:
23 checks failed against a stub. SWAP', UM/MOD, C@, C! and ROUNDTRIP
agree with their stack comments. On the nucleus: 214 of 315 headers
fixed. v4 test, test-32 and ASan+UBSan pass.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
As ruled (plans §10.2, §10.3, §10.5): ': NAME inline pinned mode N
ports request N' records the word's attributes and lays nothing down;
'import TRAIN NAME' declares another train's word, its calls, jumps and
&NAME recorded as that import. test_text: 11 checks failed before; 274
pass at both widths. The check that ': T immediate ;' is refused is
replaced, as ruled. Full gates run at the end of task 3.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
v4: mkf18a, the host tool that builds a train's F18 artifact (ADR step 3, task 3)
Build / Image RASPI (push) Successful in 3m59s
Build / Image PC (push) Successful in 3m58s
Build / Image MILKV (push) Successful in 4m7s
Build / v4 tests (32- and 64-bit cells) (push) Successful in 16m5s
dc3803ab47
The artifact's layout and its check (artifact.h, artifact.c), the tool
(tools/f18a.c, mkf18a.c) and make -C v4 artifacts. test_mkf18a, 83
checks at both widths, failed against a stub first. Gates: test,
test-32 and sanitize pass, POST 990/990. Plan section 11.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
logs: the protocol on dc3803ab so far -- four boots and test-32 pass
Build / Image RASPI (push) Successful in 5m47s
Build / v4 tests (32- and 64-bit cells) (push) Successful in 15m7s
Build / Image PC (push) Successful in 6m2s
Build / Image MILKV (push) Successful in 5m57s
bd8997ffdf
accept-amd64, accept-aarch64, accept-riscv64 and accept-stick-high
pass, POST 990/990, dict_hash 0x0ffb1d31c4aa7857 on all three (405
words); test-32, 42 programs, 0 failures. Two aarch64 runs stopped at
the 570 s foreground cap, not failed (212934 after the heartbeat,
213939 at node 11's SEND), are kept; the third ran in the background,
alone (rules, 2026-11-18), and passed. Proofs, images and docs to come.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
logs: the protocol on bd8997ff (mkf18a, ADR step 3 task 3): PASS
Acceptance / Acceptance (pull_request) Successful in 37m45s
Build / Image RASPI (push) Successful in 4m47s
Build / Image PC (push) Successful in 5m28s
Build / Image MILKV (push) Successful in 5m39s
Build / v4 tests (32- and 64-bit cells) (push) Successful in 16m10s
998510757a
Every stage passes: the four boots at POST 990/990, dict_hash
0x0ffb1d31c4aa7857 on all three (405 words), test-32 (42 programs, 0
failures), the proofs, the images and the documents.
logs/20261119-230627/PROTOCOL.md. test-32 ran twice: a container
restart lost the first run, with no result.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
rajames merged commit d5605eddb6 into master 2026-11-20 18:42:33 +00:00
Sign in to join this conversation.