Files
LithosAnanke/docs/v4.0.0/plans/2026-11-19-acl-at-call.md
T

4.2 KiB
Raw Blame History

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?