diff --git a/docs/v4.0.0/ABI.md b/docs/v4.0.0/ABI.md index 94e37629..45cecfe0 100644 --- a/docs/v4.0.0/ABI.md +++ b/docs/v4.0.0/ABI.md @@ -47,9 +47,10 @@ anywhere but where it was compiled needs those fields fixed (§5). | `xt - 1` | the link | | `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 - 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 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 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. -2. ~~The stack-effect declaration~~ **Ruled 2026-11-19: "The ( -- ) comment, strict".** The host tool reads - the first `( ... -- ... )` after an exported word's name and counts the items on each side, for example - `: NIP ( a b -- b )` is 2 taken and 1 left. Every exported word must have one, or the build fails. +2. ~~The stack-effect declaration~~ **Ruled 2026-11-19: "Derived by the tool".** + - A first answer, "the ( -- ) comment, strict", was withdrawn the same day. Captain Bob: "I think I may + 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)? 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?