# 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.