v4 effect.c: stack effects derived from code (ADR step 3, task 2)
Build / Image RASPI (push) Successful in 4m35s
Build / Image PC (push) Successful in 4m20s
Build / Image MILKV (push) Successful in 4m6s
Build / v4 tests (32- and 64-bit cells) (push) Successful in 15m23s

Walks a word's code, opcode by opcode with the engine's own counts, and
gives what it takes and leaves on both stacks, or why it has none.
Called and in-line words; recursion, computed jumps, paths that meet at
different depths and loops that leave a count have none. Test first:
23 checks failed against a stub. SWAP', UM/MOD, C@, C! and ROUNDTRIP
agree with their stack comments. On the nucleus: 214 of 315 headers
fixed. v4 test, test-32 and ASan+UBSan pass.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
This commit is contained in:
Claude
2026-11-19 19:28:33 +00:00
parent 4d64e677f5
commit daf614285a
8 changed files with 2325 additions and 0 deletions
@@ -178,3 +178,48 @@ accepted before the next:
one-hour background limit at the 64-bit `test_host_mesh`, so the rest was run again from there.
`v4-gates.txt` and `v4-sanitize-rest.txt` hold the two parts.
- The boot does not use the record, so the kernel and the protocol are unchanged.
## 9. Task 2 built (2026-11-19): `effect.c`, the stack effects
**What it is:** `v4/include/v4/effect.h` and `v4/src/effect.c`, a build-machine analysis, not part of the
engine or the kernel. `v4_effect_of(e, addr, how)` walks a word's code from its entry and gives what it
takes and leaves on both stacks, or why it has none, and where. The opcode counts are the engine's own
table (`exec.c`, D-16). Effects of called words are kept, so each is walked once. A callback gives the
effects of code outside the range analysed: the ROM's, or another train's.
**Two ways a word is reached,** from the header's flag 8:
- **Called:** it returns with `;` at its own entry depth on the return stack, so its return-stack effect
is always 0 → 0. A `;` with its own value on the return stack is a computed jump (EXECUTE, a DEFERred
word), and has no fixed effect. So has touching its caller's return address, and `ex`.
- **In line:** the body runs to the first `;` wherever the return stack is. `push` in line is data 1 → 0
and return stack 0 → 1.
No fixed effect: paths that meet with different depths (a loop that leaves a count of values), returns
that disagree, recursion, a word that never returns, and a call to a word with none.
**Test first** (`logs/20261119-effect/`): `test_effect`, 34 checks.
- Against a stub that derived nothing, the 23 checks that expect a fixed effect failed. The 10 that
expect none passed vacuously.
- Three of my expectations were wrong, and the analysis was right. I corrected them:
- `a! @ !` is 1 → 0, not 2 → 0: the value fetched is stored back;
- `drop jump A`, with A `dup`, is 2 → 2: `dup` needs a second cell;
- `3 FOR dup drop NEXT` is 1 → 1: the `dup` needs a cell already there. The fixed-loop check now uses
`5 drop`, and the 1 → 1 case is a check of its own.
- **Five real words agree with their stack comments:** SWAP', UM/MOD, C@, C! and ROUNDTRIP (2 → 1, through
its `jump C@`).
**On the nucleus** (`nucleus-dictionary.txt`, a one-off measurement): of 315 headers, 65 of them in line,
214 have a fixed effect and 101 have none.
- 78 call a word with no fixed effect;
- 11 have a computed jump;
- 8 have returns that disagree;
- 4 touch their caller's return address.
Under ruling §6.4, the 214 would be the nucleus's exports. The nucleus is not an artifact (§6.2a), so
this is a measure of the analysis, not an interface.
**Verified:**
- `make -C v4 test` passes, with all three mesh boots at POST 990/990.
- `make -C v4 test-32` passes.
- `make -C v4 sanitize` passes: every test at both widths, and the mesh boot at POST 990/990, under
ASan+UBSan.