Compare commits
71
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
6eecf0d2d7 | ||
|
|
65737e282f | ||
|
|
a9a8687fa5 | ||
|
|
43f8687f70 | ||
|
|
0522d77337 | ||
|
|
27ab2bce1e | ||
|
|
41befb0294 | ||
|
|
9039ce836d | ||
|
|
0a0be0cafd | ||
|
|
adcfadb7f7 | ||
|
|
1990a40f09 | ||
|
|
40e9773885 | ||
|
|
f7769c0e93 | ||
|
|
cf2a321807 | ||
|
|
0684cd8362 | ||
|
|
7cfcbf2b68 | ||
|
|
3945d3964a | ||
|
|
7422dc5319 | ||
|
|
33bd835474 | ||
|
|
998510757a | ||
|
|
bd8997ffdf | ||
|
|
dc3803ab47 | ||
|
|
84f119a1b3 | ||
|
|
d6b894769c | ||
|
|
cad8291478 | ||
|
|
57f556e645 | ||
|
|
9b114fff83 | ||
|
|
a1b26eacaf | ||
|
|
daf614285a | ||
|
|
4d64e677f5 | ||
|
|
29b99f90e6 | ||
|
|
6c639e5d20 | ||
|
|
3733949c28 | ||
|
|
a6371b1ce3 | ||
|
|
255dd92deb | ||
|
|
b5e85392c1 | ||
|
|
9c8b8dbd8b | ||
|
|
4ecdc80197 | ||
|
|
1961348e15 | ||
|
|
16b8fddaef | ||
|
|
f2174a39a4 | ||
|
|
fe0f709498 | ||
|
|
4a7ca4e288 | ||
|
|
c9cc39f4ec | ||
|
|
d052af6d53 | ||
|
|
c4b922d496 | ||
|
|
2b8609e4fc | ||
|
|
e43cd63936 | ||
|
|
b450c92858 | ||
|
|
cb1d6d6790 | ||
|
|
07f86d94c8 | ||
|
|
5d9737223b | ||
|
|
bc876f8088 | ||
|
|
3b229ba635 | ||
|
|
913b74a631 | ||
|
|
2957be86e5 | ||
|
|
d46ca3d174 | ||
|
|
1008b442cd | ||
|
|
0c2aab1ab5 | ||
|
|
f8be000b0a | ||
|
|
5e1dcc197b | ||
|
|
4f7521290a | ||
|
|
e6addc73b7 | ||
|
|
8dd1129ff0 | ||
|
|
d06a16f869 | ||
|
|
d93e985794 | ||
|
|
7af88cc704 | ||
|
|
666cf39b8b | ||
|
|
9e737b6252 | ||
|
|
04f917f005 | ||
|
|
b13d452e66 |
+4
-1
@@ -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
|
||||
|
||||
@@ -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
@@ -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.*
|
||||
|
||||
@@ -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
|
||||
@@ -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 )
|
||||
|
||||
@@ -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
|
||||
@@ -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@
|
||||
-->
|
||||
|
||||
@@ -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
@@ -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
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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 |
|
||||
| --- | --- | --- |
|
||||
|
||||
@@ -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
@@ -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)
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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`.
|
||||
|
||||
@@ -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
Reference in New Issue
Block a user