Files
LithosAnanke/docs/v4.0.0/plans/2026-11-19-acl-at-call.md
T
Claude 7af88cc704
Build / Image PC (push) Successful in 6m13s
Build / Image MILKV (push) Successful in 6m40s
Build / v4 tests (32- and 64-bit cells) (push) Successful in 14m18s
Build / Image RASPI (push) Successful in 3m11s
v4 ACL: the countdown at call, as v3 -- the call hook may redirect
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
2026-11-19 14:10:16 +00:00

6.6 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."

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.