Author SHA1 Message Date
Claude 6eecf0d2d7 logs: the protocol on 65737e28: PASS -- the loops the same on the four boots (#189)
Build / v4 tests (32- and 64-bit cells) (push) Waiting to run
Acceptance / Acceptance (pull_request) Waiting to run
Build / Image RASPI (push) Successful in 6m46s
Build / Image PC (push) Successful in 9m26s
Build / Image MILKV (push) Successful in 3m32s
All eight stages, a clean tree. loops() on every boot: heat 6, 1000
cooled to 0, variance not 0 and width 455 with L8 held on card 18, 66
card changes ending on card 11 -- the same on amd64, aarch64, riscv64
and the stick. dict_hash 0x7c5a2f0c02145e63, POST 992/992. The record
is logs/20261120-192820/README.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-20 20:20:31 +00:00
Claude 65737e282f v4-dictionary.tsv: L8-CARD@ and L8-HOLD; the protocol on a9a8687f, failed at docs for want of them
The protocol's docs stage refused the two Task 9 words without
dictionary entries (my omission); every other stage passed, the loops
the same on the four boots: H=6, D=0, V=-1 455, L=66 11. Its report,
FAIL, is kept. The entries added, in the file's order; make dictionary
passes. The protocol runs again from accept-amd64.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-20 19:28:12 +00:00
Claude a9a8687fa5 v4: acceptance asserts the loops -- L1, L3, L2 with L5, L8 -- and WORD_PHYSICS (#189, Phase 7 Task 9)
Build / Image RASPI (push) Successful in 6m16s
Build / Image PC (push) Successful in 6m19s
Build / Image MILKV (push) Successful in 8m30s
Build / v4 tests (32- and 64-bit cells) (push) Successful in 16m7s
The acceptance session's loops(), at every v4 boot's prompt: a word's
heat (L1), its decay from a set heat (L3), INFER-RUN's variance and
width with L8 held on card 18 (L2, L5), and L8's changes. L8-HOLD
( card -- ), request -42, beside L8-CARD@, with its POST case: POST 992.
WORD_PHYSICS (Kconfig.physics, default y) turns the word loops off: a
boot with it off fails acceptance at POST (ruled 3a). Measured on amd64:
heat 6, 1000 cooled to 0 in 40 s, width 455, 66 changes. L8 unheld
settles on card 11, with the window off, so L2/L5 hold a card (ruled).
test_mesh_boot: L8-HOLD failed first, 144 checks now. V3-PARITY.md 2.2
corrected, dated. Gates pass, POST 992/992.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-20 18:06:09 +00:00
Claude 43f8687f70 v4: L8-CARD@ ( -- card changes ), and its POST case; POST 991 (#189, Phase 7 Task 9, part A)
Request -41, served by the kernel from the node's L8 state; the word
in physics.4th. test_mesh_boot checks it against the kernel's own
values, changes more than 0: failed first (UNKNOWN WORD), now 142
checks pass. POST.md takes only the new case and the counts: the two
cells that differ run to run are #199's. POST_FLOOR 990 -> 991.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-20 15:12:33 +00:00
Claude 0522d77337 plans: Phase 7 Task 9, 2a -- L8-CARD@ leaves the card and its changes (#189)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-20 15:08:48 +00:00
Claude 27ab2bce1e plans: Phase 7 Task 9 ruled -- all the loops asserted, L8-CARD@, a WORD_PHYSICS switch (#189)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-20 15:04:28 +00:00
Claude 41befb0294 plans: Phase 7 Task 9 -- acceptance asserts the loops (#189), design, for ruling
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-20 14:54:18 +00:00
Claude 9039ce836d logs: make -C v4 post79 twice -- post_cases.c and POST79.md the same (#190), POST.md not (#199)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-20 14:52:47 +00:00
Claude 0a0be0cafd CLAUDE.md: while a PR is open, commit locally and push once (#152)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-20 14:43:46 +00:00
Claude adcfadb7f7 capsules/BLOCK_MAP.md: refreshed -- v4:ACL.4th and v4:init.4th, and centre.4th's hash
Stale since those capsules changed on this branch: the build rewrites
it, but each boot's restore (nightly.sh, qemu_session.py) put the
committed copy back. make -f kernel/Makefile manifest (#145, ruled).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-20 14:41:41 +00:00
Claude 1990a40f09 fe25519: take the carry out by multiplying, not by a left shift of a negative value
fe25519_carry's c << 51, with c negative after fe25519_sub, is
undefined in C99; the nightly's sanitized mesh boot stopped on it
(2026-11-20, run 333), reaching it through CI's signed capsules.
c * 2^51 is the same value. test_fe25519 (16 checks: values that
send a limb negative, and RFC 8032 tests 1 and 2 signed and verified)
runs in make -C v4 test and under ASan+UBSan in sanitize; it failed
first under UBSan at fe25519.c:31:26. Gates pass, POST 990/990.
The acceptance protocol runs before it reaches a PR (ruled: the next
PR, not #198).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-20 14:01:15 +00:00
Claude 40e9773885 logs: the nightly's fe25519 sanitizer failure, reproduced without the signing key
fe25519_carry shifts a negative carry left (fe25519.c:31, and :35),
undefined in C99; CI's signed capsules reach it in san-mesh-boot.
Reported, not fixed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-20 12:54:08 +00:00
Claude f7769c0e93 v4: the host placer, and a small train placed on Hera at her HERE (ADR step 3, task 4)
place.c places a train's artifact as ABI.md section 5 has it, the
code split at each export with its entry before it. test_mesh_boot
places tests/train-place, built by mkf18a with an import from the
nucleus: its words run by name, the nucleus's ABS is reached, the
kernel records each export, and six refusals leave Hera unchanged.
mkf18a refuses a word that runs on into an export. Failed first;
gates pass, POST 990/990. Plan section 13.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-20 12:44:50 +00:00
Claude cf2a321807 plans: task 4, 2a corrected -- a word that runs on into an export is refused by the tool
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-20 11:42:29 +00:00
Claude 0684cd8362 v4 mkf18a: import nucleus NAME -- hash 0, the effect from the nucleus (task 4, part 1)
mkf18a takes nucleus=SYSDIR, assembles the nucleus as the ROM does and
looks NAME up by its dictionary name; a word in line there, or one with
no fixed effect, is refused (plan section 12, rulings 3 and 4).
test_mkf18a: 5 new checks failed first, 93 pass at both widths. Its
build now has the host node's size, as the tool's has: the nucleus did
not fit a mesh node's.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-20 03:53:57 +00:00
Claude 7cfcbf2b68 plans: task 4 ruling 2a -- the placer splits the code at each export, entry before code
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-20 03:47:49 +00:00
Claude 3945d3964a plans: task 4 ruled -- host placer in C, it lays entries, the tool assembles the nucleus, import nucleus NAME
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-20 03:46:54 +00:00
Claude 7422dc5319 plans: task 4, the small train placed -- design, for ruling
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-20 03:44:41 +00:00
Claude 33bd835474 plans, ARTIFACT.md: task 3's six drafting choices ruled, each kept as drafted
The hash framing and what each provenance hash covers (choices 1, 2,
now in ARTIFACT.md section 4), the pool's unit 0, a literal store to
(PORT) as a request, capabilities through calls, and the import
placeholders at the node's top. Held locally until #198 merges.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-20 00:21:36 +00:00
Claude 998510757a 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
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
2026-11-19 23:51:12 +00:00
Claude bd8997ffdf 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
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
2026-11-19 22:20:59 +00:00
Claude dc3803ab47 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
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
2026-11-19 21:09:22 +00:00
Claude 84f119a1b3 v4 text.c: a word's flags and capabilities after its name; import lines (task 3, part 1)
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
2026-11-19 19:53:07 +00:00
Claude d6b894769c plans, ARTIFACT.md: task 3 ruling, capabilities declared, then checked
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-19 19:48:24 +00:00
Claude cad8291478 plans, ABI.md: task 3 ruling, a train's hash is its .f18a's capsule ID
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-19 19:47:39 +00:00
Claude 57f556e645 plans: task 3 ruling, an import line
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-19 19:42:13 +00:00
Claude 9b114fff83 plans: task 3 ruling, flags after the : name
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-19 19:41:42 +00:00
Claude a1b26eacaf plans: task 3 ruling, exports are the : words, no headers
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-19 19:41:13 +00:00
Claude daf614285a 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
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
2026-11-19 19:28:33 +00:00
Claude 4d64e677f5 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
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
2026-11-19 17:51:54 +00:00
Claude 29b99f90e6 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
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-19 16:33:29 +00:00
Claude 6c639e5d20 plans: step 3 §6.5 ruled, the tool's hash is its source's
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-19 16:32:59 +00:00
Claude 3733949c28 ABI.md 2c: a word with no fixed effect stays internal, the build does not fail
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-19 16:32:39 +00:00
Claude a6371b1ce3 plans: step 3 §6.4 ruled, every fixed-effect word exported
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-19 16:32:21 +00:00
Claude 255dd92deb plans: step 3 §6.3a ruled, the nucleus renamed to name order
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-19 16:31:07 +00:00
Claude b5e85392c1 plans: step 3 §6.3 ruled, all it finds, name order
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-19 16:30:24 +00:00
Claude 9c8b8dbd8b plans: step 3 §6.2a ruled, the nucleus is not an artifact
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-19 16:28:47 +00:00
Claude 4ecdc80197 plans: step 3 §6.2 ruled, both, nucleus first
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-19 16:27:31 +00:00
Claude 1961348e15 ARTIFACT.md: relocation slot 7, the whole cell (step 3 §6.1 ruled)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-19 16:26:29 +00:00
Claude 16b8fddaef plans: artifacts in the build (ADR step 3), draft for ruling
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-19 16:25:39 +00:00
Claude f2174a39a4 ABI.md, ARTIFACT.md: three drafting additions confirmed
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-19 16:24:51 +00:00
Claude fe0f709498 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
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-19 16:19:58 +00:00
Claude 4a7ca4e288 ARTIFACT.md: choice 4 ruled, port bit plus request list
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-19 16:19:00 +00:00
Claude c9cc39f4ec ARTIFACT.md: choice 3 ruled, both stack effects recorded and checked
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-19 16:17:11 +00:00
Claude d052af6d53 ARTIFACT.md: choice 2 ruled, SHA-512 for provenance and proofs
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-19 16:16:20 +00:00
Claude c4b922d496 ABI.md §4: records in 32-bit units, code in cells, as ARTIFACT.md rules
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-19 16:15:13 +00:00
Claude 2b8609e4fc ARTIFACT.md: choice 1 ruled, 32-bit units
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-19 16:13:57 +00:00
Claude e43cd63936 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
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-19 16:05:50 +00:00
Claude b450c92858 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
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-19 15:00:36 +00:00
Claude cb1d6d6790 ABI choice 6: the safe moment is a heartbeat tick at which no P or return stack is inside the old code
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-19 14:59:24 +00:00
Claude 07f86d94c8 ABI choice 5: callers reach a replacement through a jump written at the old entry
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-19 14:58:39 +00:00
Claude 5d9737223b ABI: the rail yard -- the SDK and CI's model for staging trains, recorded as given (Captain Bob)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-19 14:57:53 +00:00
Claude bc876f8088 ABI choice 4: imports name the exact build (capsule hash); an update replaces the dependent set together
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-19 14:51:53 +00:00
Claude 3b229ba635 ABI choice 3: the engine carries its source by reference (its hash), not as a car
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-19 14:51:31 +00:00
Claude 913b74a631 ABI choice 2c: a word with no fixed stack effect cannot be exported; every export has a fixed, derived effect
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-19 14:50:48 +00:00
Claude 2957be86e5 ABI: one train per capsule -- an engine of assembled .f18, its named blobs as rolling stock (Captain Bob)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-19 14:49:40 +00:00
Claude d46ca3d174 ABI choice 2 reopened: the stack effect is derived by the tool from the compiled code, not declared
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
2026-11-19 14:45:18 +00:00
Claude 1008b442cd ABI choice 2: the stack effect is the ( -- ) comment, read strictly; every export must have one
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-19 14:41:53 +00:00
Claude 0c2aab1ab5 ABI choice 1: artifacts come from a host tool, checked cell for cell against the ROM's assembly
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-19 14:41:22 +00:00
Claude f8be000b0a 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
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-19 14:40:03 +00:00
Claude 5e1dcc197b ABI.md: the F18 ABI, draft contract for ruling (ADR step 1)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-19 14:39:53 +00:00
Claude 4f7521290a 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
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-19 14:37:55 +00:00
Claude e6addc73b7 ADR rulings 3: Artemis owns persistent memory; run-time memory stays the kernel's
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-19 14:37:12 +00:00
Claude 8dd1129ff0 ADR rulings 2: Hermes is the messaging role, not a VM (in v4, the fabric's wires and routing)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-19 14:36:24 +00:00
Claude d06a16f869 ADR rulings 1: compiled F18 artifacts allowed beside the ROM ("ADR supersedes"); MACHINE.md 1 and 5 corrected
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-19 14:35:47 +00:00
Claude d93e985794 ADR 2026-11-19: F18 binary artifacts, ABI/API and live runtime updates -- recorded as given (Captain Bob)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-19 14:34:02 +00:00
Claude 7af88cc704 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
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
2026-11-19 14:10:16 +00:00
Claude 666cf39b8b plan: the ACL countdown at call -- design, for ruling (the call hook may redirect)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-19 13:17:32 +00:00
Claude 9e737b6252 v4 init.4th pins the words that create or end nodes
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
2026-11-19 12:00:23 +00:00
Claude 04f917f005 logs: the amd64 session with init.4th and the ACL on (18/18), the serial log for logs/20261119-init-acl/amd64-session.txt
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-19 11:57:54 +00:00
Claude b13d452e66 v4 init.4th, steps 1 and 2: the ACL policy loaded after POST, then the search order
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
2026-11-19 11:57:42 +00:00
231 changed files with 193608 additions and 157 deletions
+4 -1
View File
@@ -315,7 +315,10 @@ for its tree -- any change outside the evidence after the run is stale, and the
again. **One stage per foreground command is also a protocol**, and is how an agent runs it (the
QEMU rule: never in the background): `scripts/nightly.sh protocol accept-amd64`, then
`accept-aarch64`, `accept-riscv64`, `accept-stick-high`, `test-32`, `proofs`, `images`, `docs`,
each its own command, then `scripts/nightly.sh protocol-report`. The tools: `make
each its own command, then `scripts/nightly.sh protocol-report`. **While a PR is open, commit locally and
push once** (#152, 2026-11-08): Gitea redoes the PR's patch test and diff statistics on every push to its
branch, and a burst of pushes with large log directories took it to 1.75 GiB. Its `app.ini` diff limits
(`MAX_GIT_DIFF_LINES` 300, `MAX_GIT_DIFF_FILES` 30) stop a runaway diff; one push keeps it to one test. The tools: `make
ARCH=amd64,aarch64,riscv64 init`, plus the HOL-Library heap the CI image has (`ci/runner-image`).
**v4 is the default build (Captain Bob, 2026-10-14: "v4 is the default build ... no, qemu to v4
+11
View File
@@ -20,6 +20,17 @@ config ENABLE_HOTWORDS_CACHE
migration exists to collapse to one source of truth. Set to y
to enable; also gates L8 Jacquard's L1_heat_tracking bit.
config WORD_PHYSICS
bool "Compudynamics on a v4 node's words: the loops at call and at each tick (WORD_PHYSICS)"
default y
help
#189 Phase 7 Task 9 (Captain Bob, 2026-11-20, "A Kconfig switch"): a
word's heat, its decay, the rolling window, pipelining, inference and
L8, run by the kernel at every call and at every heartbeat tick. Off,
a word's calls are still counted and charged to the Stadium, and none
of the loops runs: the boot the acceptance checks are seen to fail
on. The revert, as OPCODE_PHYSICS is the opcodes'.
config OPCODE_PHYSICS
bool "Compudynamics on the 32 F18 opcodes as well as the words (OPCODE_PHYSICS)"
default y
+22 -15
View File
@@ -29,10 +29,12 @@
| `sdk.4th` | 5109, 5110, 5111, 5112, 5113, 5114, 5115 | `0x008fdbbb62c94a3a` | n/a |
| `turtle.4th` | 5100, 5101, 5102, 5103, 5104, 5105, 5106, 5107, 5108 | `0x4d470418ca543365` | n/a |
| `user-font-demo.4th` | 4200, 4201, 4202 | `0xce1fd7d1b581a56d` | n/a |
| `v4:centre.4th` | 3964, 3965, 3966, 3967, 3968, 3969, 3970 | `0xea5815290d56dff3` | n/a |
| `v4:ACL.4th` | 3984, 3985, 3986, 3987 | `0xdba5690fb0ee12a4` | n/a |
| `v4:centre.4th` | 3964, 3965, 3966, 3967, 3968, 3969, 3970 | `0x53b1e3df644e8e25` | n/a |
| `v4:forth79.4th` | 3948, 3949, 3950 | `0x4609d6ef54166ef8` | n/a |
| `v4:hera.4th` | 3960, 3961 | `0x78730b1d6effe892` | n/a |
| `v4:physics.4th` | 3972, 3973, 3974, 3975, 3976 | `0x5b0195fc30828bde` | n/a |
| `v4:init.4th` | 3980 | `0x13fe8932fa4d2934` | n/a |
| `v4:physics.4th` | 3972, 3973, 3974, 3975, 3976 | `0xb26da18d35ce5a84` | n/a |
| `v4:starshipos.4th` | 3956, 3957 | `0x1734a8f4fe7483a5` | n/a |
| `workload-0.4th` | 2200, 2201 | `0x93f86f60aeba8feb` | n/a |
| `workload-1-lite.4th` | 5058, 5059 | `0x44a7a7e3176dcc8d` | n/a |
@@ -112,18 +114,23 @@
| 3957 | `v4:starshipos.4th` | `0x1734a8f4fe7483a5` | ok |
| 3960 | `v4:hera.4th` | `0x78730b1d6effe892` | ok |
| 3961 | `v4:hera.4th` | `0x78730b1d6effe892` | ok |
| 3964 | `v4:centre.4th` | `0xea5815290d56dff3` | ok |
| 3965 | `v4:centre.4th` | `0xea5815290d56dff3` | ok |
| 3966 | `v4:centre.4th` | `0xea5815290d56dff3` | ok |
| 3967 | `v4:centre.4th` | `0xea5815290d56dff3` | ok |
| 3968 | `v4:centre.4th` | `0xea5815290d56dff3` | ok |
| 3969 | `v4:centre.4th` | `0xea5815290d56dff3` | ok |
| 3970 | `v4:centre.4th` | `0xea5815290d56dff3` | ok |
| 3972 | `v4:physics.4th` | `0x5b0195fc30828bde` | ok |
| 3973 | `v4:physics.4th` | `0x5b0195fc30828bde` | ok |
| 3974 | `v4:physics.4th` | `0x5b0195fc30828bde` | ok |
| 3975 | `v4:physics.4th` | `0x5b0195fc30828bde` | ok |
| 3976 | `v4:physics.4th` | `0x5b0195fc30828bde` | ok |
| 3964 | `v4:centre.4th` | `0x53b1e3df644e8e25` | ok |
| 3965 | `v4:centre.4th` | `0x53b1e3df644e8e25` | ok |
| 3966 | `v4:centre.4th` | `0x53b1e3df644e8e25` | ok |
| 3967 | `v4:centre.4th` | `0x53b1e3df644e8e25` | ok |
| 3968 | `v4:centre.4th` | `0x53b1e3df644e8e25` | ok |
| 3969 | `v4:centre.4th` | `0x53b1e3df644e8e25` | ok |
| 3970 | `v4:centre.4th` | `0x53b1e3df644e8e25` | ok |
| 3972 | `v4:physics.4th` | `0xb26da18d35ce5a84` | ok |
| 3973 | `v4:physics.4th` | `0xb26da18d35ce5a84` | ok |
| 3974 | `v4:physics.4th` | `0xb26da18d35ce5a84` | ok |
| 3975 | `v4:physics.4th` | `0xb26da18d35ce5a84` | ok |
| 3976 | `v4:physics.4th` | `0xb26da18d35ce5a84` | ok |
| 3980 | `v4:init.4th` | `0x13fe8932fa4d2934` | ok |
| 3984 | `v4:ACL.4th` | `0xdba5690fb0ee12a4` | ok |
| 3985 | `v4:ACL.4th` | `0xdba5690fb0ee12a4` | ok |
| 3986 | `v4:ACL.4th` | `0xdba5690fb0ee12a4` | ok |
| 3987 | `v4:ACL.4th` | `0xdba5690fb0ee12a4` | ok |
| 4000 | `ACL.4th` | `0xf8890c05c0d8f921` | ok |
| 4001 | `ACL.4th` | `0xf8890c05c0d8f921` | ok |
| 4002 | `ACL.4th` | `0xf8890c05c0d8f921` | ok |
@@ -387,4 +394,4 @@
| 5115 | `sdk.4th` | `0x008fdbbb62c94a3a` | ok |
---
*40 capsule(s) scanned. Re-run `mkcapsule --manifest <dir>` to refresh.*
*42 capsule(s) scanned. Re-run `mkcapsule --manifest <dir>` to refresh.*
+60
View File
@@ -0,0 +1,60 @@
Block 3984
\ ACL.4th -- word-level access control: the policy.
\ v3's capsules/ACL.4th, as FORTH source the node compiles.
\ The capsule supplies an entry's fields and the check
\ (acl.f18, compile.f18); what is strict, how long a TTL
\ lasts and what is pinned is decided here. Loading it
\ switches access control on: its last line runs ACL-BOOT.
\ A system that does not load it has none. init.4th loads
\ it after POST (MACHINE.md 1.1: the init turns on security).
\ The xt these words take is what FIND and ['] give.
FORTH DEFINITIONS
1 CONSTANT ACL-STRICT-MODE
0 CONSTANT ACL-TTL-MODE-VAL
\ the TTL of a cold word, tuned 2026-06-15 on v3
256 CONSTANT ACL-BASE-TTL
65535 CONSTANT ACL-MAX-TTL
-->
Block 3985
\ ( xt -- xt ) for symmetry: the xt is the entry
: ACL-ENTRY ;
: ACL-STRICT ( xt -- )
DUP ACL-PINNED? IF DROP EXIT THEN
ACL-STRICT-MODE SWAP ACL-MODE! ;
: ACL-TTL-MODE ( xt -- )
DUP ACL-PINNED? IF DROP EXIT THEN
ACL-TTL-MODE-VAL SWAP ACL-MODE! ;
\ ( xt -- ttl ) a hotter word earns a longer TTL:
\ heat/4 + 256, at most 65535
: ACL-TTL-COMPUTE
ACL-HEAT@ 4 / ACL-BASE-TTL + ACL-MAX-TTL MIN ;
-->
Block 3986
\ ( xt -- ) what the check runs when a word's TTL is 0.
\ STRICT: allow, and leave the TTL 0 so that every use
\ comes back here. TTL: compute a TTL from the word's
\ heat; allow.
: ACL-RECHECK
DUP ACL-PINNED? IF DROP EXIT THEN
DUP ACL-MODE@ ACL-STRICT-MODE = IF
1 OVER ACL-ALLOW! 0 OVER ACL-TTL! DROP EXIT
THEN
DUP ACL-TTL-COMPUTE OVER ACL-TTL! 1 SWAP ACL-ALLOW! ;
\ the system CA's public key; placeholders, as in v3
0 CONSTANT ACL-CA-KEY-LO
0 CONSTANT ACL-CA-KEY-HI
-->
Block 3987
\ ( req-hi req-lo -- allow? ) the fabric asks this word
\ whether a channel may be opened. The default approves
\ every request; a policy edits this.
: HERMES-CHANNEL-OPEN? 2DROP 1 ;
\ ( -- ) default fields on every word; the words that
\ enforce the policy pinned; the recheck switched on
: ACL-BOOT
ACL-INIT-PRIMITIVES
['] ACL-RECHECK ACL-PIN ['] ACL-INIT-PRIMITIVES ACL-PIN
['] ACL-RECHECK ACL-HOOK !
LOG-INFO" ACL: active" ;
' ACL-BOOT ACL-PIN
ACL-BOOT
+5
View File
@@ -38,6 +38,11 @@ Block 3966
: (LINES) ( baddr u -- ) CAPSULE-OPEN 0= IF (FAIL) THEN
BEGIN PAD CAPSULE-LINE DUP 0< 0= WHILE PAD SWAP (TELL) REPEAT
DROP ;
( a capsule of FORTH blocks into this node: its lowest LOADed )
: CAPSULE-INCLUDE ( baddr u -- )
CAPSULE-OPEN 0= IF -1 NODE-ERROR ! EXIT THEN
PAD CAPSULE-LINE 0< IF EXIT THEN
0 0 PAD 1- CONVERT DROP DROP LOAD ;
-->
Block 3967
( Who it is, where its printing goes, which of its ports )
+16
View File
@@ -0,0 +1,16 @@
Block 3980
( init.4th -- the system's init, run after POST and COLD. )
( MACHINE.md 1.1 and 3, step 5: everything after POST is )
( init.4th's. docs/v4.0.0/plans/2026-11-18-v4-init.md. )
( Step 2, security on: the ACL policy, ACL.4th. )
S" v4:ACL.4th" CAPSULE-INCLUDE
( The words that create or end nodes, pinned: their fields )
( cannot be changed, so no policy can deny them. )
' BIRTH ACL-PIN ' BIRTH-AS ACL-PIN ' UNIT ACL-PIN
' KILL ACL-PIN ' UNIT-KILL ACL-PIN
' PAUSE ACL-PIN ' RESUME ACL-PIN
' NODE-BORN ACL-PIN ' NODE-KILL ACL-PIN
' NODE-SLEEP ACL-PIN ' NODE-WAKE ACL-PIN
( Step 1, the search order: STARSHIPOS, then FORTH. Last, )
( since ACL.4th ends in FORTH DEFINITIONS. )
STARSHIPOS
+2
View File
@@ -23,6 +23,8 @@ Block 3973
-32 KERNEL-WORD INFER-VARIANCE@ ( -- d )
-33 KERNEL-WORD INFER-FIT@ ( -- d )
-34 KERNEL-WORD INFER-EARLY-EXIT@ ( -- flag )
-41 KERNEL-WORD L8-CARD@ ( -- card changes )
-42 KERNEL-WORD L8-HOLD ( card -- ; -1: L8 chooses )
( v3's DECAY_RATE_PER_US_Q16, its compile-time constant )
1 CONSTANT DECAY-RATE@
-->
+22
View File
@@ -81,3 +81,25 @@ set HDR-NFA here ", ACL-HEAT@ #id, #, 0 #, HDR-NFA #, HDR-LINK set HDR-LIN
\ ( xt -- n ) a number for the word that never changes: its address
set HDR-NFA here ", ACL-WORD-ID #id, #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: ACL-WORD-ID (ACL-XT) ;
\ ( xt -- ) a call from code defined at run time that the kernel sent here
\ (v4/system/mesh.c, on_call) because the word's TTL is 0 or it is denied.
\ As v3's inner interpreter, and as (ACL?): the recheck, or the TTL counted
\ down; then a denied word refused with v3's line -- by its own name, from
\ its entry (WORD's buffer is the running code's, not this) -- the stack
\ emptied and the line ended; an allowed word is jumped to, so it returns to
\ the caller as the call would have (docs/v4.0.0/plans/2026-11-19-acl-at-call.md).
: (ACL-CALL)
dup -3 + a! @ \ xt flags
dup $FFFF0000 and if ZERO
drop -65536 + ! jump TEST \ one use fewer
ZERO: drop drop dup (ACL-RECHECK)
TEST: dup -3 + a! @ 32 and if OK
drop
$33335B1B (EMIT4) $6D (EMIT4) $4E524157 (EMIT4) $203A (EMIT4) $6D305B1B (EMIT4) \ v3's line: WARN: in yellow
$3A4C4341 (EMIT4) $6E656420 (EMIT4) $20646569 (EMIT4) $27 (EMIT4)
-2 + a! @ 4* COUNT TYPE 39 EMIT CR \ the word's own name
DSTACK-DEPTH b! a !b \ as v3, the stack is emptied
pop drop jump (ABANDON)
OK: drop push ; \ on to the word
+16 -13
View File
@@ -113,22 +113,25 @@ macro ROT push SWAP pop SWAP endmacro
\ bits 16 .. 31 the TTL, a count of uses left before the next recheck
\ A new entry has all of them zero: allowed, not pinned, TTL mode, TTL 0.
\
\ (ACL?) is run by INTERPRET for every word it is about to execute or
\ compile. As v3: if the TTL is 0 the word is rechecked, otherwise the TTL
\ is counted down; then a denied word is refused. The recheck is the word
\ whose address is in (ACL-HOOK) -- ACL-RECHECK, once ACL.fth has loaded --
\ and with none there the word is allowed and given the longest TTL.
\ (ACL?) is run by INTERPRET for every word it is about to execute. As v3:
\ if the TTL is 0 the word is rechecked, otherwise the TTL is counted down;
\ then a denied word is refused. The recheck is the word whose address is in
\ (ACL-HOOK) -- ACL-RECHECK, once ACL.4th has loaded -- and with none there the
\ word is allowed and given the longest TTL.
\
\ v3 checks every execution, inside definitions too. v4 code is native: a
\ compiled call goes straight to its word. So v4 checks a word when it is
\ compiled as well as when it is interpreted -- a denied word cannot be
\ built into anything new -- but a call compiled while the word was allowed
\ is not checked again.
\ As v3, every execution is checked, inside definitions too (2026-11-19,
\ docs/v4.0.0/plans/2026-11-19-acl-at-call.md): a call from code defined at
\ run time is checked by the kernel at the call -- counted down there, or,
\ at a TTL of 0 or a denied word, sent to (ACL-CALL) (acl.f18), which runs
\ (ACL?). A word being compiled is not checked, as in v3. While the policy
\ rechecks a word, (ACL-BUSY) is 1 and the kernel checks nothing, as v3 runs
\ its policy with the check off.
\ ( xt -- ) recheck
: (ACL-RECHECK)
(ACL-HOOK) a! @ if NONE push ex \ call it with the xt
;
(ACL-HOOK) a! @ if NONE
1 (ACL-BUSY) a! ! push ex \ call it with the xt, the kernel's check off
0 (ACL-BUSY) a! ! ;
NONE: drop -3 + a! @ 65535 and -33 and $FFFF0000 + ! ;
\ ( xt -- xt ) as above; a denied word ends the line
@@ -202,7 +205,7 @@ set HDR-NFA here ", INTERPRET #id, #, 0 #, HDR-NFA #, HDR-LINK set HDR-LIN
STATE a! @ if INTERP
drop 1 and if COMP \ compiling: immediate words still run
drop (ACL?) jump (GO)
COMP: drop (ACL?) (COMPILE,) jump (IL)
COMP: drop (COMPILE,) jump (IL) \ compiled, not checked: the call is, when it runs (as v3)
INTERP: drop 16 and if RUN
drop drop (.WORD) \ ": compile-only"
$6F63203A (EMIT4) $6C69706D (EMIT4) $6E6F2D65 (EMIT4) $796C (EMIT4) CR
+4
View File
@@ -35,5 +35,9 @@ store (IMG) &(IDLE)
store (IMG)+1 &(FAULTS)
store (IMG)+2 &KEY
store (IMG)+3 &CR
\ the ACL's check at call: where the kernel sends a call to be checked; and the
\ policy not running
store (ACL-CALLX) &(ACL-CALL)
store (ACL-BUSY) 0
start (IDLE)
+2
View File
@@ -120,6 +120,8 @@ constant RSTACK-DEPTH 32752
constant HEAT-OP 29216
constant (EXEC) 30047
constant (RUNX) 29954
constant (ACL-CALLX) 29956
constant (ACL-BUSY) 29925
constant ANTICLOCK 29248
constant CFBASE 32672
constant CFEND 32704
+2
View File
@@ -120,6 +120,8 @@ constant RSTACK-DEPTH 32752
constant HEAT-OP 29216
constant (EXEC) 30047
constant (RUNX) 29954
constant (ACL-CALLX) 29956
constant (ACL-BUSY) 29925
constant ANTICLOCK 29248
constant CFBASE 32672
constant CFEND 32704
+3
View File
@@ -208,6 +208,8 @@ IS ( xt -- ) IS xxx: make the deferred word xxx run xt; compiled when compiling.
J ( -- n ) Compile-only: the index of the next outer DO loop.
KERNEL-WORD ( n -- ) KERNEL-WORD xxx: define xxx, a word that asks the kernel to do request n (as BYE, BLOCK).
KEY ( -- c ) Wait for a key and leave its character.
L8-CARD@ ( -- card changes ) L8's current card on this node, 0 to 63, and how many times it has changed: more than 0 once L8 has run.
L8-HOLD ( card -- ) Holds L8 on the card given, 0 to 63, its gates applied; -1 lets L8 choose again.
LATEST ( -- xt ) The newest entry of the CURRENT vocabulary.
LEAVE ( -- ) Compile-only: leave the innermost DO loop at its next LOOP or +LOOP.
LFA ( xt -- addr ) The link field of the entry (>LINK).
@@ -389,6 +391,7 @@ BIRTH-AS ( number port childport baddr u -- place ) BIRTH, and given the capsule
CAPSULE-CELL ( -- w flag ) The next cell of the capsule of F18 code this node has open, and true; 0 0 at its end. A kernel request.
CAPSULE-LINE ( baddr -- u | -1 ) The next line of the capsule of FORTH blocks this node has open, copied to baddr: its length, or -1 at its end. A kernel request.
CAPSULE-OPEN ( baddr u -- flag ) Find the named capsule, check its hash and signature, and open it to be read from its start by this node. A kernel request.
CAPSULE-INCLUDE ( baddr u -- ) Load the named capsule of FORTH blocks into this node: CAPSULE-OPEN places its blocks in RAM, block n at n - R, and its lowest block is LOADed; what runs after it is the capsule's own (-->, LOAD, THRU). init.4th loads the ACL policy so. centre.4th.
CENTRE ( n -- ) Hera only: a second centre, node n, from its port 6 to Hera's port 6, given centre.4th; it births its own unit, n+1 to n+4.
KILL ( n -- ) Hera only: node n is removed, whatever it was doing; every node is told it is gone, and Hera forgets the way to it.
NODE-BORN ( number -- place | -1 ) A node is born, empty, and entered in the registry with this node as its parent: its place, or -1 if there is no room. A kernel request.
Can't render this file because it contains an unexpected character in line 11 and column 3.
+206
View File
@@ -0,0 +1,206 @@
# The F18 ABI -- draft contract, for ruling
Written 2026-11-19. Step 1 of `ADR-2026-11-19-F18-ARTIFACTS.md` §7: "Define and document the minimal ABI
contract". It builds on the rulings in `plans/2026-11-19-f18-artifacts.md`:
1. compiled artifacts are allowed beside the ROM;
2. Hermes is the messaging role;
3. Artemis owns persistent memory;
4. a word's identity is its capsule plus its name.
**Nothing here is built.** The choices left open are numbered in §9, and each will be put to Captain Bob on
its own.
## 1. Terms
| Term | Meaning |
|---|---|
| **Word** | The unit of interface and access control (ADR §1). It has a name, an entry point, a stack effect and its ACL fields. |
| **Capsule: a train** | The unit of packaging, distribution and deployment (ADR §1). It is content-addressed, so its ID is its hash, and it is signed, as now (`kernel/include/starkernel/capsule.h`). **Ruled 2026-11-19, "One train per capsule":** each capsule is a train. Its *engine* is its `.f18` code, assembled by the host tool into one artifact. Its *rolling stock* is the named blobs coupled behind the engine: `.4th` source, data, and whatever else it carries, each with its own identity and provenance. A system is many trains; the nucleus is one of them. |
| **Artifact: the engine** | A train's compiled F18 unit: code cells, and the records of §4 that make them placeable and checkable. It is assembled from all of that capsule's `.f18` files. |
| **Rolling stock** | The named blobs behind an engine (MACHINE.md §1's trailer). The engine's code is what acts on them: the ROM's types, `.f18` assembled and `.4th` handed a line at a time, now carried by each train. |
| **Identity** | Ruling 4: a word's identity is (the hash of the capsule that defines it, the word's name). Addresses, word IDs and places are local resolution only. |
| **Loader** | Whoever places an artifact in a node. As today, that is the node itself, through words like `CAPSULE-INCLUDE`, or the kernel at boot. No central linker (ADR §6). |
## 2. The hardware contract (unchanged; kept apart, ADR §3.2)
The engine's contract is what it is today, and the ABI does not change it:
- **Instruction words** of six slots (`v4/include/v4/iword.h`). A branch (`jump`, `call`, `next`, `if`,
`-if`) carries its target in the bits to the right of its slot, page-relative, with a reach of 27, 22, 17
or 12 bits.
- **The return stack and the data stack** are rings, with their depths set by the build (`V4_DATA_RING`,
`V4_RET_RING`). A call pushes its return address.
- **Ports and messages** between nodes, as MESH.md has them. The ABI adds nothing between nodes: "inter-core
communication shall continue to use the established message architecture" (ADR §3.2).
- **The call hook** (2026-11-19, `exec.h`) may redirect a call. The ACL uses it now; §6 may use it.
**What this means for artifacts:** compiled code holds addresses in its branch fields. An artifact placed
anywhere but where it was compiled needs those fields fixed (§5).
## 3. The word contract
**The entry** is as `dict.f18` has it today:
| Cell | Holds |
|---|---|
| `xt - 4` | the word ID, local |
| `xt - 3` | the flags: 1 immediate, 2 hidden, 4 data, 8 in-line, 16 compile-only, 128 deferred, plus the ACL fields (bit 5 denied, bit 6 pinned, bits 8–15 the mode, bits 16–31 the TTL) |
| `xt - 2` | the name |
| `xt - 1` | the link |
| `xt` | the code |
**What the ABI adds is recorded, not run.** Each exported word has:
- **its stack effect:** how many cells it takes and leaves on each stack. This is the "stack effects" of
ADR §3.2. It is derived by the host tool from the compiled code (choice 2), checked when the artifact is
placed and in the proofs, never at run time.
- **its capabilities:** the kernel requests it may make (`KERNEL-WORD` numbers) and whether it touches ports.
- **its ACL defaults:** pinned or not, and its mode. They are applied at placement, through the same fields.
**The calling convention:** a call with a return address on the return stack, as now. A word returns with
`;`. Arguments and results travel on the data stack only, in the declared counts. There is nothing else.
## 4. The artifact
**The records are in 32-bit units, low byte first, and the code is in the build's cells** (`ARTIFACT.md`
§1, ruled 2026-11-19, "32-bit units"). A node reads the records as it reads a block, four bytes to a
cell. *Corrected 2026-11-19: this line said "All of it is in cells, so an F18 node can read it".*
| Record | Holds |
|---|---|
| **Header** | a magic number; the ABI version; the cell width (32 or 64); the record counts |
| **Provenance** (ADR §3.1) | the source capsule's hash; the compiler's identity (the host tool's hash, choice 1); the build configuration's hash (the knobs, `V4_NODE_WORDS`, the rings); the target |
| **Exports** | for each word: its name, its entry's offset in the code, its flags, its declared stack effect, its capabilities |
| **Imports** | for each word used from another capsule: (that capsule's hash, the name), and the stack effect it is expected to have |
| **Relocations** | every cell of the code whose branch field holds an address, with how to fix it: internal (add the base), or import *k* |
| **Code** | the compiled cells, as if placed at address 0 |
| **Verification** | the identity of the proof that covers this exact artifact, and the assumptions it holds under (ADR §5), or none |
**Integrity and authorship** are the capsule's: its content hash and its Ed25519 signature, as now. The
artifact repeats neither, and, as ADR §5 says, a hash is not correctness.
## 5. Placement: resolution without a linker
A loader places an artifact in one pass, in order:
1. **Check:**
- the header is one this ABI version and cell width take;
- the capsule's hash and signature check, as `CAPSULE-OPEN` already does;
- every import's capsule is present in this node, and the imported word is exported by it with the
stack effect expected. **Fail closed:** if any check fails, nothing is placed.
2. **Place:** the code cells are copied to the node's dictionary space at its `HERE`, the base.
3. **Fix:** each relocation's branch field is patched, adding the base, or putting in the import's
resolved address. A field whose patched address does not fit its slot's reach is refused (fail
closed). Patching happens at placement only, once, with no lazy binding and no later resolution.
4. **Enter:** an entry is made for each export, as `(HEADER)` makes one, and the kernel is told
(`(WORD-DEFINED)`). The word accounts, the ACL fields and the defaults of §3 apply from here.
This is the work FORTH's compiler already does when it compiles a reference to a word. It is done here
from records, not from source. It is not dynamic linking in the ADR's sense: there are no shared libraries,
no lazy binding, no global address space and no linker running beside the program.
## 6. Activation and retirement (ADR §4)
**A replacement** is a newer capsule exporting a word of the same name. Its identity differs, because its
capsule hash differs. Activation must make the code that calls the old word reach the new one. The call
sites compiled into other definitions hold the old address (§2). Choice 5 is how they reach it.
**A safe boundary** is a heartbeat at which no node is inside the old word: no return address into it is
on any return stack, and no message for it is waiting. Choice 6 is how that is known.
**Retirement:** the old code is freed only when nothing can reach it. Until then both versions coexist
(ADR §4).
**Rollback** is activating the old one again, as long as it is not retired. Artemis keeps the staged and
recovery copies (ruling 3).
## 7. Compatibility
**A replacement is compatible** when, for every word the old artifact exported:
- the new one exports a word of the same name;
- with the same stack effect;
- needing no capability the old did not.
Anything else is incompatible, and activation is refused. A verified artifact is not compatible because it
is verified (ADR §5); compatibility is checked against the old artifact's records.
## 8. What stays as it is
- POST, the protocol, and CI's gates (ADR §7).
- Source capsules and the boot as it is: the ROM still assembles the system at boot (ruling 1).
- The ACL's check at call, and the word accounts: an artifact's words are words like any other.
- Messages between nodes.
**Captain Bob's image, 2026-11-19:** "the .f18 assembler assembles all .f18 files it finds. Now here's a
thought. That 'assembled' code can be the 'engine' for a train of named blobs as metaphorically rolling
stock." Ruled "One train per capsule" (§1).
**The rail yard: the SDK and CI's model** (Captain Bob, 2026-11-19, recorded as given; nothing built):
> "When we build the SDK, we can naturally think of a railroad yard for staging outgoing artifact capsule
> 'trains' from first order preexisting 'cars' prior to writing new ones.. That would be the model and on
> the CI side we can use messaging as semaphores in our staging yard with inbound and outbound trains and
> the artifacts are the persistent part. Signed, sealed and versioned."
Read here as:
- **The yard stages trains.** An outgoing train is made up first from cars that already exist, which are
first-order and already built. New cars are written only for what is missing.
- **In CI, messages are the semaphores.** They signal inbound and outbound trains through the yard: what
may move, and when.
- **What persists is the artifacts:** signed, sealed and versioned. The yard's moves are transient.
It ties in `(-`, the build marker that asks CI to clear a block for the next image (`plans/2026-11-18-
capsule-blocks.md` §5), and Artemis keeping what is kept (ruling 3).
## 9. Open, for ruling one at a time
1. ~~Where artifacts come from~~ **Ruled 2026-11-19: "A host tool".** A C tool beside `mkcapsule` compiles
`.f18` to artifacts on the build machine. It is a second assembler beside the ROM's, so the two must
agree: the tool's output is checked against what the ROM assembles from the same source, cell for cell,
in the build and in CI. The compiler's identity in the provenance record is the tool's own hash.
The cell-for-cell check was added in drafting; confirmed by Captain Bob, 2026-11-19 ("Yes").
2. ~~The stack-effect declaration~~ **Ruled 2026-11-19: "Derived by the tool".**
- A first answer, "the ( -- ) comment, strict", was withdrawn the same day. Captain Bob: "I think I may
have made a bad assumption. I had the idea of that after (- was aliased to ( is for SDK special. We're
working on something more fundamental."
- **There is no declaration in the source.** The host tool computes each exported word's stack effect
from its compiled code, by static analysis of the F18 opcodes, and records it in the artifact. The
proofs check it. Comments stay comments.
- **2c, ruled 2026-11-19: "Refused as an export".** A word whose effect depends on its data (a loop
leaving a count of values, branches that leave different depths, `EXECUTE`, a `DEFER`red word) has no
fixed count. It cannot be exported by an engine: it stays internal to its train, or is restructured.
Every export has a fixed effect, derived by the tool; a word with none stays internal, and the build
does not fail for it (`plans/2026-11-19-f18-artifact-build.md` §6.4). *Corrected 2026-11-19: this
said "which the tool derives and the build fails without".*
3. ~~What a capsule carries~~ **Ruled 2026-11-19: "No, by reference".** A train's engine carries only the
hash of the `.f18` source it was assembled from, in its provenance record. The source stays in the
repository and in its own capsule. To check an engine against its source, the source is fetched by
that hash.
4. ~~Imports by capsule hash~~ **Ruled 2026-11-19: "Exact hash".** An import names the exact build of
the train it imports from: (its capsule hash, the word's name). If that train is rebuilt or updated,
its hash changes, so its importers are rebuilt too, and a live update replaces the whole dependent set
of trains together. Placement refuses an import whose hash is not present.
**Ruled 2026-11-19 (step 3, `plans/2026-11-19-f18-artifact-build.md` §10.4):** a train's hash is its
`.f18a`'s capsule ID. The nucleus has none, so a word imported from it has hash 0 and is resolved by name
in the node's dictionary at placement; exact hashes hold between artifact trains only.
5. ~~How callers reach a replacement~~ **Ruled 2026-11-19: "Jump at the old entry".** At activation, each
replaced word's first code cell, at its xt, is overwritten with a `jump` to the new word: one cell per
word, and every caller, compiled at run time or not, follows at once. The old code stays in place,
unreachable but for that cell, until it is retired. The new word must be within the jump's reach from
the old entry (27 bits in slot 0, which covers a node's memory), or activation is refused.
6. ~~The safe boundary~~ **Ruled 2026-11-19: "Scan at a heartbeat".** At a heartbeat tick the kernel
scans every node's P and return stack for an address inside the old words' code. When none is there, it
writes all of a set's jumps in that one tick. While some are there, it tries again on later ticks. A
message waiting for an old word is not code on a stack and does not hold the set back: the word it
reaches is the new one. That last point was added in drafting; confirmed by Captain Bob, 2026-11-19
("Yes").
7. ~~Proofs first~~ **Ruled 2026-11-19: "Safe activation first".** The first Isabelle/HOL property:
- the jump at each old entry is written only at a tick when no node's P or return stack holds an address
inside the old code (choice 6);
- after it, every call to an old word, from any caller, reaches the new word.
Placement's checks, compatibility and the soundness of the derived stack effects come after.
## 10. Status
All seven choices are ruled, plus 2c (no fixed effect means no export). This draft is the minimal ABI
contract, the ADR's step 1, as ruled.
The next step is the ADR's step 2, the artifact representation in detail: the exact cell layout of §4's
records, a design for ruling before any code.
+181
View File
@@ -0,0 +1,181 @@
# StarshipOS Architectural Design Decision
<!-- Recorded verbatim as given by Captain Bob, 2026-11-19. The conflicts it raises with the existing record
are put to him one at a time, and ruled in docs/v4.0.0/plans/2026-11-19-f18-artifacts.md. -->
## F18 Binary Artifacts, ABI/API, and Live Runtime Updates
Status: ACCEPTED — Immediate Design Decision
Date: 2026-11-19
Scope: F18 build system, LithosAnanke, StarshipOS runtime
Priority: Architectural foundation
---
### 1. Decision
StarshipOS shall establish a canonical binary artifact format for compiled F18 code, supported by a minimal, formally specified Application Binary Interface (ABI) and Application Programming Interface (API).
The ABI shall operate at the word and capsule levels:
- Words are the units of interface and access control.
- Capsules are the units of packaging, distribution, and deployment.
The implementation shall preserve the existing StarshipOS architecture without introducing conventional dynamic linking, shared-library infrastructure, or unnecessary runtime machinery.
### 2. Motivation
This decision supports four primary objectives:
1. Performance: Eliminate redundant compilation, dependency resolution, and other avoidable work from build and startup paths.
2. Verification: Provide immutable binary artifacts suitable for Isabelle/HOL verification and reproducible-build validation.
3. Authenticity and provenance: Establish traceability between source, build configuration, compiler, binary artifact, and formal verification evidence.
4. Live updates: Permit verified binary components to be staged and activated within a running StarshipOS instance without requiring a complete system restart.
Performance improvements must be measured. Binary artifact creation alone does not guarantee reduced startup latency.
### 3. Architectural Contract
#### 3.1 F18 Binary Artifacts
The build system shall compile F18 source into a canonical, versioned binary artifact representation.
An artifact shall provide sufficient information to establish:
- Artifact identity and integrity.
- Source and build provenance.
- Target architecture and compatibility constraints.
- Exported and imported word identities.
- Word-level interface contracts.
- Dependencies and required capabilities.
- Verification status and associated proof identity.
The format may contain individually addressable compiled units.
Artifacts shall remain independent of final deployment decisions. A compiled unit may be incorporated into kernel ROM or distributed as a runtime-consumable capsule.
Source files, compiled binaries, and supporting documentation shall retain their individual provenance.
#### 3.2 Application Binary Interface (ABI)
The ABI shall define the minimum binary-level contract necessary for independently compiled components to interoperate.
It shall address:
- Word identity and resolution.
- Calling conventions and stack effects.
- Memory ownership and access constraints.
- Entry points and dependencies.
- Capability and ACL requirements.
- Binary compatibility.
- Activation and retirement semantics.
The F18 hardware execution contract and the StarshipOS artifact interoperability contract shall remain conceptually distinct.
Logical word identity shall not depend on physical memory addresses or processor placement.
Local execution may resolve to physical addresses. Inter-core communication shall continue to use the established message architecture.
#### 3.3 Application Programming Interface (API)
The API shall expose the minimum operations necessary for artifact discovery, verification, staging, activation, retirement, and recovery.
These operations should be implemented through existing StarshipOS facilities wherever practical.
They shall not automatically require new kernel primitives.
The API shall preserve the existing responsibilities of:
- Hera: System ownership, component creation, and coordination.
- Hermes: Messaging, routing, and communication.
<!-- Ruled 2026-11-19 ("The messaging role"): Hermes names the role, not a VM. In v4 it is the fabric's wires
and routing (MESH.md), and kernel-Hermes on v3; no Hermes node is brought back. -->
- Artemis: Memory, persistence, and recovery.
<!-- Ruled 2026-11-19 ("Persistent memory"): Artemis owns what is kept -- persistent storage, staged artifacts,
recovery copies (FABRIC-3.5 XIV.3). Run-time memory stays the kernel's: the Stadium allocates it, and the
kernel serves blocks. -->
Specific API word names and signatures remain implementation decisions.
### 4. Live Runtime Updates
StarshipOS shall support the architectural capability to introduce verified replacement artifacts into a running system.
The intended lifecycle is:
1. Build the replacement artifact.
2. Verify integrity, compatibility, and applicable formal properties.
3. Distribute and stage the artifact.
4. Establish a safe activation boundary.
5. Activate the replacement.
6. Retire the previous implementation when safe.
7. Preserve recovery or rollback capability where applicable.
Heartbeat boundaries may provide logical activation points, but safe replacement must account for outstanding execution, messages, dependencies, and persistent state.
Multiple artifact versions may coexist during transitions.
Live replacement shall not violate existing runtime invariants or word-level ACL guarantees.
### 5. Formal Verification
The ABI and artifact format shall be suitable for specification in Isabelle/HOL.
Verification objectives include:
- Artifact structural validity.
- Interface and stack-effect compatibility.
- Dependency satisfaction.
- Memory and capability constraints.
- Safe activation and retirement.
- Preservation of established invariants across compatible replacements.
Proof evidence shall be associated with the exact artifact and its applicable assumptions.
Cryptographic integrity and authenticity shall be distinguished from functional correctness. Hashes alone do not establish correctness or authorship.
A verified replacement shall not be considered universally compatible merely because its individual components have been verified.
### 6. Explicit Non-Goals
This decision does not authorize introducing:
- ELF-style dynamic linking or shared libraries.
- A conventional process loader.
- A centralized runtime linker.
- A global executable address space.
- A conventional scheduler or memory manager.
- A new execution model.
- Mandatory inclusion of all compiled artifacts in kernel ROM.
- Unnecessary kernel primitives or additional abstraction layers.
The existing asynchronous, message-driven architecture remains authoritative.
### 7. Implementation Direction
Implementation shall proceed incrementally:
1. Define and document the minimal ABI contract.
2. Establish the canonical binary artifact representation.
3. Integrate artifact production into the existing build system.
4. Add integrity, provenance, and reproducibility checks.
5. Formalize applicable ABI properties in Isabelle/HOL.
6. Implement minimal artifact API operations.
7. Validate staged and live replacement using controlled experiments.
8. Measure build time, startup latency, runtime overhead, and replacement correctness.
Existing build, POST, CI, and verification gates shall remain in force unless explicitly superseded by independently validated equivalents.
### 8. Governing Principle
Words define interfaces. Capsules define deployment. Artifacts establish identity and provenance. The ABI guarantees interoperability. The API exposes operations. Isabelle/HOL verifies the applicable contracts.
No additional machinery shall be introduced without demonstrated necessity.
The machine remains the machine.
---
Decision: ACCEPTED
Implementation: Pending incremental design and experimental validation
Architectural impact: Foundational — F18 toolchain, capsule infrastructure, formal verification, and live deployment.
+165
View File
@@ -0,0 +1,165 @@
# The F18 artifact -- its layout, draft for ruling
Written 2026-11-19. Step 2 of `ADR-2026-11-19-F18-ARTIFACTS.md` §7, "Establish the canonical binary
artifact representation". It gives the exact layout of the records `ABI.md` §4 lists, under ABI v0 as
ruled:
- one train per capsule;
- a host tool assembles all of a capsule's `.f18` into its engine;
- each export's stack effect is derived, and a word with none fixed is not exported;
- imports name the exact build;
- the source travels by reference.
**Nothing here is built.** The choices in §8 are ruled (2026-11-19).
## 1. Units, order, width
- **The unit is a 32-bit word**, stored little-endian, low byte first, as v4's blocks are (`blocks.h`:
"four bytes to a cell, the first lowest"). Every record is a whole number of units, so the records read
the same at either cell width.
- **The code is cells of the build's width**, each stored low byte first (choice 5). A 32-bit engine and a 64-bit engine are two artifacts: the
header says which, and placement refuses the wrong one.
- **A 64-bit value**, such as a capsule's hash, is two units, low unit first.
- **A SHA-512 hash** (choice 2) is 16 units: its 64 bytes in their order, packed four to a unit, low byte
first.
- **A name** is a counted string, its length byte then its characters, packed four to a unit, low byte
first, as the dictionary packs names (`dict.f18`). It sits in the string pool and is referred to by its
unit offset.
## 2. The whole
```
header 16 units
provenance 64 units
exports E x 8 units
imports I x 6 units
relocations R x 2 units
verification 18 units
string pool S units
code C cells
```
The offsets of each part are in the header, so a reader skips what it does not need. The artifact is the
engine of a train: the capsule's payload. The capsule's content hash and Ed25519 signature, already
`mkcapsule`'s, cover it whole. The artifact repeats neither.
## 3. Header (16 units)
| Unit | Field |
|---|---|
| 0 | magic `F18A` (`0x41383146`) |
| 1 | ABI version: 0 |
| 2 | cell width in bits: 32 or 64 |
| 3 | the node words it was built for (`V4_NODE_WORDS`) |
| 4–5 | E, the export count; I, the import count |
| 6–7 | R, the relocation count; S, the string pool's units |
| 8 | C, the code's cells |
| 9 | the unit offset of the exports (the others follow, in §2's order) |
| 10–15 | reserved, 0 |
## 4. Provenance (64 units, ADR §3.1)
Each hash is SHA-512 (choice 2).
| Units | Field |
|---|---|
| 0–15 | the hash of the `.f18` source the engine was assembled from (ABI choice 3: by reference) |
| 16–31 | the host tool's hash, the compiler's identity (ABI choice 1) |
| 32–47 | the build configuration's hash: the knobs that change code, the cell width, `V4_NODE_WORDS`, the rings |
| 48–63 | the ROM's hash it must agree with: the tool's output is checked against the ROM's assembly |
**How each hash is taken** (ruled 2026-11-20, "Keep as drafted": plan 2026-11-19-f18-artifact-build §11,
choices 1 and 2). Each input is framed as its name, a NUL, its length in 8 bytes low first, then its
bytes, so two inputs cannot run together. The tool's hash covers its own sources and every `include/v4`
header, in a fixed order. The configuration's covers the sizes as text, framed as `config`, then the map.
The ROM's covers the ROM file. `v4/tools/f18a.h` names the files.
## 5. Exports, imports, relocations
**An export (8 units):**
| Unit | Field |
|---|---|
| 0 | the name, as a string pool offset |
| 1 | the entry's offset in the code, in cells: the xt, relative to the base |
| 2 | the flags, as the entry's: immediate, compile-only, in-line, and the ACL defaults (pinned, mode) |
| 3 | the data stack effect: cells taken in the low 16 bits, cells left in the high 16, derived (choice 2) |
| 4 | the return stack effect, the same way, derived |
| 5 | the capabilities: bit 31 set if it touches ports; bits 0–30 the string pool offset of its list of kernel requests, or 0 for none |
| 6–7 | reserved, 0 |
**An import (6 units):**
| Units | Field |
|---|---|
| 0–1 | the exporting train's capsule hash, the exact build (choice 4) |
| 2 | the word's name, as a string pool offset |
| 3 | the data stack effect it is expected to have |
| 4 | the return stack effect it is expected to have |
| 5 | reserved, 0 |
**A relocation (2 units):**
| Unit | Field |
|---|---|
| 0 | the code cell, as an offset, and in the top 3 bits the slot whose branch field holds the address (0–3), or 7 for the whole cell |
| 1 | what it points to: `0xFFFFFFFF` for internal, so the base is added; otherwise the import's index |
Placement (`ABI.md` §5) patches each relocation's branch field. It refuses a patched address beyond that
slot's reach: 27, 22, 17 or 12 bits (`iword.h`).
**Slot 7, the whole cell** (ruled 2026-11-19, "Slot 7 = whole cell", step 3's design §6.1). The cell holds
an address as a value: an `&NAME` literal, or a dictionary link. Placement adds the base, or puts in the
import's address, to the whole cell, which reaches all of a node. Slots 4–6 are unused.
## 6. Verification (18 units, ADR §5)
| Units | Field |
|---|---|
| 0–15 | the SHA-512 hash of the proof that covers this exact artifact: its theory and its build; all 0 means none |
| 16 | the assumptions it holds under, as a string pool offset, or 0 |
| 17 | reserved, 0 |
## 7. What makes a valid artifact
The tool writes these properties and placement checks them. They are also the first things Isabelle states
about the format:
- the magic and the version;
- every count and offset within the payload;
- every string pool offset on a counted string, or, for a capabilities list, on a unit holding its count
*n* followed by *n* units, each a `KERNEL-WORD` number;
- every export's entry inside the code;
- every relocation's cell inside the code, its slot 0–3 one that holds a branch or 7, its import index
below I;
- every reserved unit 0.
## 8. Open, for ruling one at a time
1. ~~The unit~~ **Ruled 2026-11-19: "32-bit units".** Every record is in 32-bit units, low byte first,
as v4's blocks are, so the records read the same at either cell width (§1). Only the code is in the
build's cells.
2. ~~The hashes~~ **Ruled 2026-11-19: "SHA-512 for provenance".** The provenance hashes (source, tool,
configuration, ROM) and the proof's hash are SHA-512, the one already in the tree for Ed25519, 16
units each (§4, §6). An import's capsule hash stays the capsule's ID, XXHash64, 2 units (§5), and
signing stays Ed25519. The provenance record grows from 12 units to 64, with no reserved units, and
verification from 4 to 18.
3. ~~The return-stack effect~~ **Ruled 2026-11-19: "Record and check both".** The tool derives the
return-stack effect as it derives the data-stack effect, and records it in unit 4 of each export and
import (§5). Placement, compatibility (`ABI.md` §7, "the same stack effect") and the proofs check
both.
4. ~~Capabilities~~ **Ruled 2026-11-19: "Port bit + request list".** As drafted (§5, unit 5). The tool
derives it from the code: a port opcode sets the bit, and each kernel request the word reaches goes in
its list. Compatibility refuses a replacement that needs one the old did not (`ABI.md` §7). The list
is a count unit then that many request numbers (§7). The bit layout and the list's form were chosen in
drafting; confirmed by Captain Bob, 2026-11-19 ("Yes").
**Changed 2026-11-19 (step 3, `plans/2026-11-19-f18-artifact-build.md` §10.5, "Declared, then checked"):**
v4 has no port opcode, so capabilities cannot be derived. Each word declares them (`ports`, `request N`),
and the tool fails the build where it can see a port or a request that is not declared. The layout is
unchanged.
5. ~~Endianness for the code cells~~ **Ruled 2026-11-19: "Low-first, like the records".** Every byte of
the artifact has one order, low byte first, so its hashes and signature are the same whichever host
built it. A big-endian host swaps the bytes when it places the code.
## 9. Status
All five choices are ruled. This is the artifact layout, the ADR's step 2, as ruled. The next step is the
ADR's step 3: artifact production in the build (the host tool), designed for ruling before any code.
+14 -5
View File
@@ -892,11 +892,20 @@ is rechecked, otherwise the TTL is counted down; then a denied word is refused w
is in the variable `ACL-HOOK`; with none there, the word is allowed and given the longest TTL. `ACL.fth` puts
its `ACL-RECHECK` there (v3 finds it by name each time).
**Where this is weaker than v3.** v3's inner interpreter checks every execution, inside definitions too. v4
code is native: a compiled call goes straight to its word, and no opcode asks permission. So v4 checks a
word when it is *compiled* as well as when it is interpreted — a denied word cannot be built into anything
new — but a call compiled while the word was allowed is not checked again when it runs. Closing that needs
the check in the node itself (the `call` opcode), which is a hardware decision and is not taken here.
**Where this was weaker than v3, and is not now** (2026-11-19, Captain Bob: "As v3: add at call"; "Engine: call
redirects"; `docs/v4.0.0/plans/2026-11-19-acl-at-call.md`).
- **The old gap:** v3's inner interpreter checks every execution, inside definitions too. v4 checked a word
when it was compiled and when it was interpreted, and a compiled call was never checked again.
- **Now, at the call:** the engine's call hook may send a call elsewhere. The kernel checks every call from
code defined at run time. A word with TTL left is counted down at the call. At a TTL of 0, or for a denied
word, the call goes to `(ACL-CALL)` (`acl.f18`), which rechecks or refuses it by the word's name and goes on
to it.
- **No compile-time check:** a word being compiled is not checked, as in v3.
- **The policy runs unchecked:** while the policy rechecks a word, `(ACL-BUSY)` is 1 and nothing is checked,
as v3 runs its policy with the check off.
- **A node with no kernel has no check at call:** the hosted node is one. Its compiled calls are not checked.
- **On the FPGA,** the `call` opcode must offer its kernel the same redirect. That is to be designed with the
FPGA.
| Word | Fate | Notes |
| --- | --- | --- |
+5 -2
View File
@@ -26,7 +26,10 @@ machine and a ROM.
| **Trailer** | Source, as named blobs. `.f18` is F18 assembler. `.4th` is FORTH. The blob's name gives its type. | The capsule directory (`capsules/`) |
The ROM is the only binary. It runs the same on the C engine and on the FPGA: one binary, the
same behaviour. Assemble FORTH from the trailer and the node is a FORTH machine. Assemble Lisp
same behaviour. **Superseded in part, 2026-11-19** (Captain Bob, "ADR supersedes";
`ADR-2026-11-19-F18-ARTIFACTS.md`): the build may also compile F18 into binary artifacts, with their
identity, provenance and interface. An artifact is a choice, not a requirement: the ROM still
assembles source at boot. Assemble FORTH from the trailer and the node is a FORTH machine. Assemble Lisp
and it would be a Lisp machine. The engine and the ROM do not change.
### 1.1 What it is for
@@ -204,7 +207,7 @@ streams the ROM instead.
| Today | Becomes |
|---|---|
| `v4/capsule/*.v4`, 14 files, 311 words, assembled on the build machine | `.f18` blobs under `capsules/v4/`, assembled by the ROM at boot |
| `v4/tools/mkimage.c` → `nucleus-64.f18`, a prebuilt dictionary | Builds the ROM only. The nucleus binary is gone. |
| `v4/tools/mkimage.c` → `nucleus-64.f18`, a prebuilt dictionary | Builds the ROM only. The nucleus binary is gone. (2026-11-19: compiled F18 artifacts are allowed beside the ROM, `ADR-2026-11-19-F18-ARTIFACTS.md`.) |
| `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. |
+4 -2
View File
@@ -6,7 +6,7 @@ the standard first -- FORTH-79, FORTH-83, ANS 1994 -- then v3's table, not v3's
The cases are `v4/system/post_cases.c`; those of the words `capsules/v4/physics.4th` defines
need the kernel and are not run by the hosted product.
POST runs 990 cases. 783 are v3's, with what the hosted v3 binary did as the
POST runs 992 cases. 783 are v3's, with what the hosted v3 binary did as the
expected result. This file lists every other case, and why.
## 1. Rewritten: the standard's result, or v3's table's (159)
@@ -206,7 +206,7 @@ printed unless an address is printed; the values are not.
| `LIST.basic` | `1 LIST` | values left only |
| `SCR.after_list` | `1 LIST SCR @ . CR` | values left only |
## 3. Written by hand (28)
## 3. Written by hand (30)
For required words v3 has no case for. The expected results are the
standard's; no v3 run stands behind them.
@@ -241,6 +241,8 @@ standard's; no v3 run stands behind them.
| `WORD.delimiter` | `: W2 44 WORD COUNT TYPE ; W2 A B,` | stack `empty`, prints `A B` |
| `WORD.count` | `: W3 BL WORD C@ . ; W3 ABC` | stack `empty`, prints `3 ` |
| `WORD.skips_leading` | `: W4 BL WORD COUNT TYPE ; W4 X` | stack `empty`, prints `X` |
| `L8-CARD@.basic` | `L8-CARD@ 0< . 64 U< . CR` | stack `empty`, prints `0 -1 \n` |
| `L8-HOLD.basic` | `18 L8-HOLD L8-CARD@ DROP . -1 L8-HOLD CR` | stack `empty`, prints `18 \n` |
## 4. v3 cases left out (52)
+17
View File
@@ -515,6 +515,23 @@ it.
- There is no decay, rolling window, pipelining, inference, L8, heartbeat
or Stadium wire on the node.
*Corrected 2026-11-20 (#189; ENGINE step 4 Phase 7, `plans/2026-11-13-engine-step4-phase7-the-loops-and-parity.md`).*
Section 2.2 was true of the lone node of 2026-10-07. It no longer is of v4 in its place in the system. The
kernel keeps every word's record (Phase 2) and runs v3's loops on it, at `call` and on the one heartbeat
(Phase 7, Tasks 1 to 4):
- L1: heat;
- L2: the rolling window;
- L3: decay, on touch and in the background;
- L4: pipelining and the hot-words cache, behind `ENABLE_PIPELINING` and `ENABLE_HOTWORDS_CACHE`, off as in v3;
- L5 and L6: inference;
- L7: the adaptive heartbeat, the kernel's one heartbeat (2026-11-17);
- L8: the Jacquard selector.
The loops also run on the 32 opcodes (`OPCODE_PHYSICS`). The words of `physics.4th` read and set them, among
them `L8-CARD@` and `L8-HOLD` (Task 9). Each acceptance boot asserts L1, L3, L2 with L5, and L8 at the
prompt (`scripts/qemu_session.py`, `loops()`), and `WORD_PHYSICS=0`, the revert, fails acceptance at POST.
The call-target count of `heat.c` described above is still there, beside the kernel's records.
### 2.3 What the v4 design documents say
The documents ruled on 2026-10-01 do not say "as v3". They say:
@@ -213,8 +213,58 @@ Phase 4).
**Done 2026-11-14** (`POST-PARITY.md` section 6): 990 cases, all pass on Hera; each case rewritten is
listed with its reason in `POST.md`; the floor (`v4/system/POST_FLOOR`) is 990.
### Task 9: acceptance -- the full protocol; ENGINE.md, V3-PARITY.md, FABRIC-3
**Designed 2026-11-20, for ruling** (#189's last two items: "Acceptance asserts it on the three architectures
and the stick -- a boot without the physics fails", and "V3-PARITY.md section 2 and #4 say what is now
built"). Nothing here is built.
Each task gets its steps when the one before it is accepted, test first, as Phase 2's did.
What a boot shows today: the heartbeat ticking, the Stadium conserved, Hera's words admitted after POST
(`scripts/qemu_session.py`, every acceptance boot). Nothing there fails if a word's heat, its decay, the
window, inference or L8 did not run: those are seen in `test_mesh_boot` on the host only.
The words of Task 4 read them at the prompt, on the real boot, so the session can ask. The steps:
1. **Test first: a build without the physics.** `OPCODE_PHYSICS=0` takes out only the opcodes' loops, so
it is not the case. The check is seen to fail on a boot whose per-call hook does nothing: a
one-line stub, in a diagnostic build only, never committed in the tree that ships.
2. **The checks, in the v4 session of `qemu_session.py`,** after the prompt, each a line typed and its
answer matched:
- L1, heat: a word defined and called three times. `' W HEAT@ .` is more than 0.
- L3, decay: `HEAT!` sets a word's heat; after a set number of heartbeat ticks, `HEAT@` is less.
- L2 and L5, the window and inference: after a workload, `INFER-RUN INFER-WINDOW@ .` is not 0.
- L8: no word reads the card today. See the open questions.
Each value is measured on the three architectures first, and the matches are written from what the
boots print, not guessed.
3. **The record:** `V3-PARITY.md` section 2.2 corrected, dated, to what is built (it says "There is no
decay, rolling window, pipelining, inference, L8, heartbeat or Stadium wire on the node"), and #4 told.
4. **The protocol** on the result: four boots, test-32, the proofs, the images, the documents.
**Ruled 2026-11-20, one at a time:**
1. **The loops asserted: "L1, L3, L2/L5, L8".** Heat, decay, the window and inference, and L8: every loop v4
carries, seen on the real boot on the three architectures and the stick. Asked: those, or a smaller set
with the rest left to `test_mesh_boot`.
2. **L8: "A word, L8-CARD@".** A kernel request, as Task 4's words are, in `physics.4th`. It leaves the node's
current card number. It gets a POST case, and the session checks that it is one of the table's cards
after a workload. Asked: a word, a line the kernel prints, or L8 left to the host test.
**2a, ruled 2026-11-20: "L8-CARD@ leaves card and changes".** `( -- card changes )`. The check is that the
card is one of the table's and that changes is more than 0 after a workload. The card alone could not
fail: L8 starts on card 8, and with the physics off it never runs, so the card stays 8, which is one of
the table's. With the physics on, UCB1 tries each untried card once, and the kernel counts each change
(`v4_mesh_l8.changes`).
3. **The boot without the physics: "A Kconfig switch".** `WORD_PHYSICS` (default y), beside `OPCODE_PHYSICS`,
turns the per-call and per-tick word loops off. It is a real revert, as ruling 7's is. The session's
checks are seen to fail on `WORD_PHYSICS=0`, and pass on the boot as built. Step 1 above, the stub, is
replaced by this. Asked: that, or a one-off stub in a diagnostic build.
**3a, ruled 2026-11-20: "POST's failure is enough".** A `WORD_PHYSICS=0` boot fails acceptance at POST
(amd64, `logs/20261120-task9/amd64-nophysics.txt`): its `ENTROPY@` cases need a word's heat. So it
never reaches the prompt, and every loop check fails with it, but not one at a time. The checks are
then measured and passed on the boot as built. Nothing in POST changes. Asked: that, POST's physics
cases skipped under `WORD_PHYSICS=0`, or each loop failed by holding L8 on cards that turn it off.
**The L2/L5 check, measured 2026-11-20** (taken as recommended: Captain Bob, "Yes go on"). On amd64,
as built, `INFER-WINDOW@` was 0. Every loop but L1 is gated by L8's current card, and L5's width is
computed only on ticks whose card has L5 on, so on a real boot it may or may not be set. The check is
instead that `INFER-RUN INFER-VARIANCE@` is not 0 after the workload: the variance is computed whenever
the window holds calls, whatever the card, and stays 0 with no window. That is L2's window with the
engine run on it. The width is printed beside it, not checked; L5's width stays in `test_mesh_boot`,
where L8 is held on a card. The same boot: L1 H=6, L3 1000 cooled to 0 in 40 s, L8 65 changes on card 11.
## Review focus
+34
View File
@@ -88,3 +88,37 @@ the system capsules. It is the only boot policy, so the loader's one fixed step
It may also change what `init.4th` is: a capsule, or not. **Nothing of this design is built until
that conversation.**
## 7. Steps 1 and 2 built (2026-11-19)
**Ruled:** "ACL at boot", first of the new work after `v4.0.0-alpha.5`. The policy loads "From
init.4th", so `init.4th` comes off hold. The include is to be "Compose[d] in FORTH". Capsules are
ephemeral and placed by block (`2026-11-18-capsule-blocks.md`), which settles the hold.
**What is built:**
- **`capsules/v4/init.4th`**, at block 3980, so it lands at RAM 1932. It runs
`S" v4:ACL.4th" CAPSULE-INCLUDE` (security on), then `STARSHIPOS` (the search order). The order is
last-first because `ACL.4th` ends in `FORTH DEFINITIONS`.
- **`capsules/v4/ACL.4th`**: the policy, `git mv`ed from `v4/capsule/ACL.fth`. It is reflowed into
four 64×16 blocks chained with `-->` (3984–3987, landing at 1936), and its text is unchanged.
- **`CAPSULE-INCLUDE ( baddr u -- )`** in `centre.4th`, composed from `CAPSULE-OPEN` and
`CAPSULE-LINE`: the capsule is placed, and its lowest block is `LOAD`ed. It has a dictionary entry.
- **The mesh loads `v4:init.4th` after POST and `COLD`,** after the `PARITY:V4_SYSTEM` line, so that
line's `dict_hash` stays the sealed system's. This is the loader's one fixed step there.
- **`test_host_quit`** types `ACL.4th` as it types any capsule, skipping its `Block` and `-->` lines.
**Test first** (`logs/20261119-init-acl/`):
- `test_mesh_boot`: `init.4th`'s parity line; `DOE` found without naming `STARSHIPOS`; `ACL-BOOT`
and `ACL-RECHECK` pinned. The before-run failed.
- One false pass was found and corrected on the way. The two checks had first been placed after the
test's own `COLD`, where the search-order check passed only because the line before it named
`STARSHIPOS`. They now run straight after the boot.
**Results:**
- 113 checks pass, with POST 990/990.
- All 52 tests at 64 bits, test-32 and ASan/UBSan pass.
- The dictionary gate passes with 405 words.
- One amd64 kernel session passes 18/18, with "ACL: active" at boot.
**Still open, one at a time:** `BIRTH` pinned; the countdown "at call"; `CAPSULE-BIRTH`; births by
`init.4th`; the identity gate and the prompt moving from C into `init.4th`.
+127
View File
@@ -0,0 +1,127 @@
# The ACL countdown at `call` -- design, for ruling
Written 2026-11-19. Captain Bob ruled "As v3: add at call", then "Engine: call redirects". That takes the
decision DECOMPOSITION.md §5.20 left open: "Closing that needs the check in the node itself (the `call`
opcode), which is a hardware decision and is not taken here."
**Built 2026-11-19, ruled "Build it"; section 6 is as built.**
## 1. v3, and v4 today
**v3** (`v3/src/vm.c`) checks a word in two places:
- in the inner interpreter (:600–620), at every execution inside a colon definition: the TTL is counted
down, or the word is rechecked when it is 0, and refused if it is denied;
- in the outer interpreter (:725–742), for a word executed at the prompt.
v3 does not check when it compiles a word. Its system words are C, so their calls among themselves are not
checked.
**v4** (`compile.f18`, `(ACL?)`) checks in `INTERPRET`, for every word it is about to execute **or
compile**. A call compiled into a definition is never checked again when it runs.
## 2. The design
### 2.1 The engine: the call hook may redirect
`v4_call_hook` now returns the address to go to. The engine (`v4/src/exec.c`) sets P to what the hook
returns rather than to the target. With no hook, or a hook that returns the target, nothing changes.
This is the engine change §5.20 called a hardware decision. On the FPGA, the `call` opcode would have to
offer the same to its kernel, so this needs a design of its own when the FPGA is built. In the golden model
the hook is the kernel watching its node's calls, as it already does for the word accounts.
### 2.2 The kernel's hook (`v4/system/mesh.c`, `on_call`)
The hook already picks the calls v3 would count: calls from code defined at run time, a word known to the
kernel's table. For those only (not `INTERPRET`'s dispatch, which `(ACL?)` checks already), it reads the
target's flags cell, `target - 3`:
- **Fast path**, TTL above 0 and not denied: the TTL is counted down (one cell written) and the call goes
on to the target. No FORTH runs.
- **Slow path**, TTL 0, or denied: the target is kept in a node variable, `(ACL-TARGET)`, and the call is
redirected to `(ACL-CALL)`.
### 2.3 `(ACL-CALL)`, F18 source beside `(ACL?)` in `compile.f18`
`(ACL-CALL)` fetches `(ACL-TARGET)` and runs `(ACL?)` on it, which is v3's check:
- a TTL of 0 is rechecked through `(ACL-HOOK)`, the policy's `ACL-RECHECK`;
- otherwise the TTL is counted down;
- a denied word is refused with v3's line, `WARN: ACL: denied 'xxx'`, the stack emptied and the line ended.
An allowed word is then jumped to. The return address the `call` pushed is still on the return stack, so
the word returns to the original caller, as if it had been called directly.
### 2.4 The compile-time check goes
As ruled ("drop its compile-time check so both match v3"), `INTERPRET` checks only the words it executes,
and a word being compiled is not checked. A denied word can be compiled into a definition; the definition is
refused when it runs and reaches the call.
## 3. Cost
- **Fast path:** one memory read and one write, for calls the hook already examines. The hook already reads
`target - 4` (the word ID), next to it.
- **Slow path:** only at a recheck, every TTL-worth of uses (256 to 65535), or for a denied word.
- **Measured as before:** the host mesh boot, five alternating runs, old and new. Then the protocol.
## 4. Tests, first
In `test_mesh_boot`, with the policy loaded by `init.4th`:
1. A word called from inside a definition counts down: `: F 65 EMIT ; : G F ; G`, then `' F ACL-TTL@`, is
one less than after the first use.
2. A denied word called from inside a definition is refused when the definition runs: `0 ' F ACL-ALLOW!`,
then `G`, gives `WARN: ACL: denied 'F'`.
3. A word whose TTL is 0, reached from a definition, is rechecked by the policy and given its TTL.
4. A denied word can be compiled into a definition. The compile is not refused; the refusal comes at run.
5. A word at the prompt is counted once, not twice: `INTERPRET`'s check, and no second one from the hook.
6. POST is 990/990 unchanged: POST runs before `init.4th`, with no policy.
Each is seen to fail before the change.
## 5. For ruling
1. The design above, 2.1 to 2.4?
2. The FPGA: record the redirect as the call opcode's requirement, to be designed with the FPGA?
## 6. As built (2026-11-19)
**Two things changed from the design, both found while building.** Both are needed to match v3, so
neither is a new ruling:
1. **`(ACL-BUSY)`, a recursion guard.** The policy's `ACL-RECHECK` is code defined at run time. Its own
calls would be checked, and at a TTL of 0 they would recheck themselves without end. v3 runs its policy
with the check off (`emergency_console`). `(ACL-RECHECK)` now sets `(ACL-BUSY)` around the policy, and
the kernel checks nothing while it is set.
2. **`(ACL-CALL)` has its own check and refusal.** It prints the word's name from its entry, not from
`WORD`'s buffer. A first version copied the name into that buffer and broke POST's
`CONVERT.digits`, which reads that buffer after `WORD`.
**The target goes on the data stack** for `(ACL-CALL)`, so it needs no variable. Two map cells were added
from free memory:
- `(ACL-CALLX)`, at `BUF0_W - 113`: `(ACL-CALL)`'s address, stored by `end.f18`;
- `(ACL-BUSY)`, at `BUF0_W - 144`.
**What changed:**
- `exec.h` and `exec.c`: the hook returns where P goes.
- `mesh.c`: `acl_at_call()`, applied to calls from code; `INTERPRET`'s dispatch is left to `(ACL?)`.
- `compile.f18`: `INTERPRET`'s compile path no longer checks, and `(ACL-RECHECK)` sets `(ACL-BUSY)`.
- `acl.f18`: `(ACL-CALL)`.
- `end.f18`, `host_map.h`, `mkmap.c`, `image.h`: the two cells.
**Test first** (`logs/20261119-acl-at-call/`):
- `test_mesh_boot`, with the policy on. Five checks failed before:
- a call from a definition is counted down;
- a denied word called from a definition is refused by its own name, and does not run;
- a denied word compiles;
- it is refused when the definition runs.
The sixth, that a word at the prompt is counted once, passed before and after.
- `test_exec`: a hook that returns another address redirects the call, which returns to the caller.
- `test_host_quit`'s two v4-only expectations changed to v3's: a denied word compiles. That host node has
no kernel, so its compiled calls are not checked there.
**Verified:**
- `test_mesh_boot` passes 120 checks, with POST 990/990.
- All 52 tests at 64 bits, test-32, and ASan/UBSan pass.
- The amd64 kernel builds, and one amd64 session passes 18/18.
- **The cost** (`timing.txt`, five alternating host mesh boots): median 15.227 s old against 15.439 s new,
+1.4%. That is inside the old runs' own spread, 15.06 to 15.99 s, so no measurable cost.
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,26 @@
# F18 binary artifacts, ABI/API, live updates -- the rulings
The decision is `docs/v4.0.0/ADR-2026-11-19-F18-ARTIFACTS.md`, recorded as given. This file records each
conflict between it and the existing record, put to Captain Bob one at a time, and his ruling.
**Nothing is built.** The ADR's §7 order is followed; step 1 is the minimal ABI contract.
## The conflicts, one at a time
1. **"The ROM is the only binary"** (MACHINE.md §1, §5, ruled 2026-10-15) against compiled F18 artifacts.
**Ruled: "ADR supersedes".** MACHINE.md §1 and §5 now say that compiled artifacts are allowed beside the
ROM. An artifact is a choice, not a requirement: the ROM still assembles source at boot.
2. **"Hermes: Messaging, routing, and communication"** (ADR §3.3) against the record. The Hermes VM was
removed (FABRIC-3.5/3.6, 2026-09-22), and v4's messages travel on the fabric's wires and routes.
**Ruled: "The messaging role".** Hermes names the role, not a VM: in v4 the fabric's wires and routing,
and on v3 kernel-Hermes. No Hermes node is brought back. The ADR carries a note saying so.
3. **"Artemis: Memory, persistence, and recovery"** (ADR §3.3) against the record. Artemis is the persistence
path (FABRIC-3.5 XIV.3), and memory is the kernel's. **Ruled: "Persistent memory".** Artemis owns what is
kept: persistent storage, staged artifacts and recovery copies. Run-time memory stays the kernel's: the
Stadium allocates it, and the kernel serves blocks. The ADR carries a note saying so.
4. **A word's logical identity** (ADR §3.2: not addresses or placement). Today v4 has three identities: the
word ID (assigned in order, given back by FORGET), `ACL-WORD-ID` (its address) and the kernel's table of
entries (addresses). **Ruled: "Capsule + name".** A word's identity is its defining artifact's identity,
the content hash, plus the word's name. It is stable across builds of the same source and independent of
where the word loads. Addresses and word IDs stay as local resolution only.

Some files were not shown because too many files have changed in this diff Show More