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
128 lines
6.6 KiB
Markdown
128 lines
6.6 KiB
Markdown
# 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.
|
||
|