ABI choice 2 reopened: the stack effect is derived by the tool from the compiled code, not declared

Captain Bob withdrew the first answer, the ( -- ) comment, the same day:
it rested on a bad assumption tied to (-, the SDK's marker.

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 14:45:18 +00:00
parent 1008b442cd
commit d46ca3d174
+12 -5
View File
@@ -47,9 +47,10 @@ anywhere but where it was compiled needs those fields fixed (§5).
| `xt - 1` | the link | | `xt - 1` | the link |
| `xt` | the code | | `xt` | the code |
**What the ABI adds is declared, not run.** Each exported word declares: **What the ABI adds is recorded, not run.** Each exported word has:
- **its stack effect:** how many cells it takes and leaves on each stack. This is the "stack effects" of - **its stack effect:** how many cells it takes and leaves on each stack. This is the "stack effects" of
ADR §3.2. It is checked when the artifact is placed and in the proofs, never at run time. ADR §3.2. It is derived by the host tool from the compiled code (choice 2), checked when the artifact is
placed and in the proofs, never at run time.
- **its capabilities:** the kernel requests it may make (`KERNEL-WORD` numbers) and whether it touches ports. - **its capabilities:** the kernel requests it may make (`KERNEL-WORD` numbers) and whether it touches ports.
- **its ACL defaults:** pinned or not, and its mode. They are applied at placement, through the same fields. - **its ACL defaults:** pinned or not, and its mode. They are applied at placement, through the same fields.
@@ -130,9 +131,15 @@ is verified (ADR §5); compatibility is checked against the old artifact's recor
`.f18` to artifacts on the build machine. It is a second assembler beside the ROM's, so the two must `.f18` to artifacts on the build machine. It is a second assembler beside the ROM's, so the two must
agree: the tool's output is checked against what the ROM assembles from the same source, cell for cell, agree: the tool's output is checked against what the ROM assembles from the same source, cell for cell,
in the build and in CI. The compiler's identity in the provenance record is the tool's own hash. in the build and in CI. The compiler's identity in the provenance record is the tool's own hash.
2. ~~The stack-effect declaration~~ **Ruled 2026-11-19: "The ( -- ) comment, strict".** The host tool reads 2. ~~The stack-effect declaration~~ **Ruled 2026-11-19: "Derived by the tool".**
the first `( ... -- ... )` after an exported word's name and counts the items on each side, for example - A first answer, "the ( -- ) comment, strict", was withdrawn the same day. Captain Bob: "I think I may
`: NIP ( a b -- b )` is 2 taken and 1 left. Every exported word must have one, or the build fails. have made a bad assumption. I had the idea of that after (- was aliased to ( is for SDK special. We're
working on something more fundamental."
- **There is no declaration in the source.** The host tool computes each exported word's stack effect
from its compiled code, by static analysis of the F18 opcodes, and records it in the artifact. The
proofs check it. Comments stay comments.
- **Open within it:** a word whose effect depends on its data (a loop, a branch that leaves different
depths, `EXECUTE`) has no fixed count. What the tool records for such a word is a question of its own.
3. **What a capsule carries:** an artifact alone, or the artifact and its source (provenance, ADR §3.1)? 3. **What a capsule carries:** an artifact alone, or the artifact and its source (provenance, ADR §3.1)?
4. **Imports by capsule hash:** a hash pins one exact build. Is an import of an older build of the same 4. **Imports by capsule hash:** a hash pins one exact build. Is an import of an older build of the same
capsule a mismatch, or is the name of the capsule enough with the stack effect checked? capsule a mismatch, or is the name of the capsule enough with the stack effect checked?