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

Open
rajames wants to merge 52 commits from StarForth-v4.0.0 into master
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
All checks were successful
Acceptance / Acceptance (pull_request) Successful in 37m45s
Required
Details
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
You are not authorized to merge this pull request.
This pull request can be merged automatically.
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin StarForth-v4.0.0:StarForth-v4.0.0
git checkout StarForth-v4.0.0
Sign in to join this conversation.