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

84 lines
4.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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?