From 666cf39b8bdb8e43da0c7cdc3ffbf2e88c1c14d2 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 19 Nov 2026 13:17:32 +0000 Subject: [PATCH] plan: the ACL countdown at call -- design, for ruling (the call hook may redirect) Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm --- docs/v4.0.0/plans/2026-11-19-acl-at-call.md | 83 +++++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 docs/v4.0.0/plans/2026-11-19-acl-at-call.md diff --git a/docs/v4.0.0/plans/2026-11-19-acl-at-call.md b/docs/v4.0.0/plans/2026-11-19-acl-at-call.md new file mode 100644 index 00000000..223d6e5e --- /dev/null +++ b/docs/v4.0.0/plans/2026-11-19-acl-at-call.md @@ -0,0 +1,83 @@ +# 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." + +**Nothing here is 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?