# The F18 ABI -- draft contract, for ruling Written 2026-11-19. Step 1 of `ADR-2026-11-19-F18-ARTIFACTS.md` §7: "Define and document the minimal ABI contract". It builds on the rulings in `plans/2026-11-19-f18-artifacts.md`: 1. compiled artifacts are allowed beside the ROM; 2. Hermes is the messaging role; 3. Artemis owns persistent memory; 4. a word's identity is its capsule plus its name. **Nothing here is built.** The choices left open are numbered in §9, and each will be put to Captain Bob on its own. ## 1. Terms | Term | Meaning | |---|---| | **Word** | The unit of interface and access control (ADR §1). It has a name, an entry point, a stack effect and its ACL fields. | | **Capsule** | The unit of packaging, distribution and deployment (ADR §1). It is content-addressed, so its ID is its hash, and it is signed, as now (`kernel/include/starkernel/capsule.h`). It carries source (`.4th`, `.f18`), an artifact, or both. | | **Artifact** | A compiled F18 unit: code cells, and the records of §4 that make them placeable and checkable. It travels inside a capsule. | | **Identity** | Ruling 4: a word's identity is (the hash of the capsule that defines it, the word's name). Addresses, word IDs and places are local resolution only. | | **Loader** | Whoever places an artifact in a node. As today, that is the node itself, through words like `CAPSULE-INCLUDE`, or the kernel at boot. No central linker (ADR §6). | ## 2. The hardware contract (unchanged; kept apart, ADR §3.2) The engine's contract is what it is today, and the ABI does not change it: - **Instruction words** of six slots (`v4/include/v4/iword.h`). A branch (`jump`, `call`, `next`, `if`, `-if`) carries its target in the bits to the right of its slot, page-relative, with a reach of 27, 22, 17 or 12 bits. - **The return stack and the data stack** are rings, with their depths set by the build (`V4_DATA_RING`, `V4_RET_RING`). A call pushes its return address. - **Ports and messages** between nodes, as MESH.md has them. The ABI adds nothing between nodes: "inter-core communication shall continue to use the established message architecture" (ADR §3.2). - **The call hook** (2026-11-19, `exec.h`) may redirect a call. The ACL uses it now; §6 may use it. **What this means for artifacts:** compiled code holds addresses in its branch fields. An artifact placed anywhere but where it was compiled needs those fields fixed (§5). ## 3. The word contract **The entry** is as `dict.f18` has it today: | Cell | Holds | |---|---| | `xt - 4` | the word ID, local | | `xt - 3` | the flags: 1 immediate, 2 hidden, 4 data, 8 in-line, 16 compile-only, 128 deferred, plus the ACL fields (bit 5 denied, bit 6 pinned, bits 8–15 the mode, bits 16–31 the TTL) | | `xt - 2` | the name | | `xt - 1` | the link | | `xt` | the code | **What the ABI adds is declared, not run.** Each exported word declares: - **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. - **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. **The calling convention:** a call with a return address on the return stack, as now. A word returns with `;`. Arguments and results travel on the data stack only, in the declared counts. There is nothing else. ## 4. The artifact All of it is in cells, so an F18 node can read it. | Record | Holds | |---|---| | **Header** | a magic number; the ABI version; the cell width (32 or 64); the record counts | | **Provenance** (ADR §3.1) | the source capsule's hash; the compiler's identity (the ROM's hash, which assembled it); the build configuration's hash (the knobs, `V4_NODE_WORDS`, the rings); the target | | **Exports** | for each word: its name, its entry's offset in the code, its flags, its declared stack effect, its capabilities | | **Imports** | for each word used from another capsule: (that capsule's hash, the name), and the stack effect it is expected to have | | **Relocations** | every cell of the code whose branch field holds an address, with how to fix it: internal (add the base), or import *k* | | **Code** | the compiled cells, as if placed at address 0 | | **Verification** | the identity of the proof that covers this exact artifact, and the assumptions it holds under (ADR §5), or none | **Integrity and authorship** are the capsule's: its content hash and its Ed25519 signature, as now. The artifact repeats neither, and, as ADR §5 says, a hash is not correctness. ## 5. Placement: resolution without a linker A loader places an artifact in one pass, in order: 1. **Check:** - the header is one this ABI version and cell width take; - the capsule's hash and signature check, as `CAPSULE-OPEN` already does; - every import's capsule is present in this node, and the imported word is exported by it with the stack effect expected. **Fail closed:** if any check fails, nothing is placed. 2. **Place:** the code cells are copied to the node's dictionary space at its `HERE`, the base. 3. **Fix:** each relocation's branch field is patched, adding the base, or putting in the import's resolved address. A field whose patched address does not fit its slot's reach is refused (fail closed). Patching happens at placement only, once, with no lazy binding and no later resolution. 4. **Enter:** an entry is made for each export, as `(HEADER)` makes one, and the kernel is told (`(WORD-DEFINED)`). The word accounts, the ACL fields and the defaults of §3 apply from here. This is the work FORTH's compiler already does when it compiles a reference to a word. It is done here from records, not from source. It is not dynamic linking in the ADR's sense: there are no shared libraries, no lazy binding, no global address space and no linker running beside the program. ## 6. Activation and retirement (ADR §4) **A replacement** is a newer capsule exporting a word of the same name. Its identity differs, because its capsule hash differs. Activation must make the code that calls the old word reach the new one. The call sites compiled into other definitions hold the old address (§2). Choice 5 is how they reach it. **A safe boundary** is a heartbeat at which no node is inside the old word: no return address into it is on any return stack, and no message for it is waiting. Choice 6 is how that is known. **Retirement:** the old code is freed only when nothing can reach it. Until then both versions coexist (ADR §4). **Rollback** is activating the old one again, as long as it is not retired. Artemis keeps the staged and recovery copies (ruling 3). ## 7. Compatibility **A replacement is compatible** when, for every word the old artifact exported: - the new one exports a word of the same name; - with the same stack effect; - needing no capability the old did not. Anything else is incompatible, and activation is refused. A verified artifact is not compatible because it is verified (ADR §5); compatibility is checked against the old artifact's records. ## 8. What stays as it is - POST, the protocol, and CI's gates (ADR §7). - Source capsules and the boot as it is: the ROM still assembles the system at boot (ruling 1). - The ACL's check at call, and the word accounts: an artifact's words are words like any other. - Messages between nodes. ## 9. Open, for ruling one at a time 1. **Where artifacts come from:** the ROM assembling the source as now, its output kept (the compiler identity is then the ROM's hash), or a host tool? 2. **The stack-effect declaration:** written in the source as today's `( a b -- c )` comments, parsed strictly, or a new form? 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? 5. **How callers reach a replacement:** - (a) the old entry's code is overwritten by a `jump` to the new: one cell, every caller follows, and the old code is unreachable but for that cell; - (b) the kernel's call hook redirects calls to the old address, from a table; - (c) callers are re-patched from records kept at placement. 6. **The safe boundary:** how the system knows no node is inside the old word. It could scan return stacks at a heartbeat for return addresses in its range, or wait until the node is idle at its prompt. 7. **Proofs:** which of ADR §5's properties come first in Isabelle/HOL. Placement's fail-closed checks and compatibility (§7) are the smallest.