# 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: a train** | 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`). **Ruled 2026-11-19, "One train per capsule":** each capsule is a train. Its *engine* is its `.f18` code, assembled by the host tool into one artifact. Its *rolling stock* is the named blobs coupled behind the engine: `.4th` source, data, and whatever else it carries, each with its own identity and provenance. A system is many trains; the nucleus is one of them. | | **Artifact: the engine** | A train's compiled F18 unit: code cells, and the records of §4 that make them placeable and checkable. It is assembled from all of that capsule's `.f18` files. | | **Rolling stock** | The named blobs behind an engine (MACHINE.md §1's trailer). The engine's code is what acts on them: the ROM's types, `.f18` assembled and `.4th` handed a line at a time, now carried by each train. | | **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 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 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. **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 host tool's hash, choice 1); 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. **Captain Bob's image, 2026-11-19:** "the .f18 assembler assembles all .f18 files it finds. Now here's a thought. That 'assembled' code can be the 'engine' for a train of named blobs as metaphorically rolling stock." Ruled "One train per capsule" (§1). **The rail yard: the SDK and CI's model** (Captain Bob, 2026-11-19, recorded as given; nothing built): > "When we build the SDK, we can naturally think of a railroad yard for staging outgoing artifact capsule > 'trains' from first order preexisting 'cars' prior to writing new ones.. That would be the model and on > the CI side we can use messaging as semaphores in our staging yard with inbound and outbound trains and > the artifacts are the persistent part. Signed, sealed and versioned." Read here as: - **The yard stages trains.** An outgoing train is made up first from cars that already exist, which are first-order and already built. New cars are written only for what is missing. - **In CI, messages are the semaphores.** They signal inbound and outbound trains through the yard: what may move, and when. - **What persists is the artifacts:** signed, sealed and versioned. The yard's moves are transient. It ties in `(-`, the build marker that asks CI to clear a block for the next image (`plans/2026-11-18- capsule-blocks.md` §5), and Artemis keeping what is kept (ruling 3). ## 9. Open, for ruling one at a time 1. ~~Where artifacts come from~~ **Ruled 2026-11-19: "A host tool".** A C tool beside `mkcapsule` compiles `.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: "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. - **2c, ruled 2026-11-19: "Refused as an export".** A word whose effect depends on its data (a loop leaving a count of values, branches that leave different depths, `EXECUTE`, a `DEFER`red word) has no fixed count. It cannot be exported by an engine: it stays internal to its train, or is restructured. Every export has a fixed effect, which the tool derives and the build fails without. 3. ~~What a capsule carries~~ **Ruled 2026-11-19: "No, by reference".** A train's engine carries only the hash of the `.f18` source it was assembled from, in its provenance record. The source stays in the repository and in its own capsule. To check an engine against its source, the source is fetched by that hash. 4. ~~Imports by capsule hash~~ **Ruled 2026-11-19: "Exact hash".** An import names the exact build of the train it imports from: (its capsule hash, the word's name). If that train is rebuilt or updated, its hash changes, so its importers are rebuilt too, and a live update replaces the whole dependent set of trains together. Placement refuses an import whose hash is not present. 5. ~~How callers reach a replacement~~ **Ruled 2026-11-19: "Jump at the old entry".** At activation, each replaced word's first code cell, at its xt, is overwritten with a `jump` to the new word: one cell per word, and every caller, compiled at run time or not, follows at once. The old code stays in place, unreachable but for that cell, until it is retired. The new word must be within the jump's reach from the old entry (27 bits in slot 0, which covers a node's memory), or activation is refused. 6. ~~The safe boundary~~ **Ruled 2026-11-19: "Scan at a heartbeat".** At a heartbeat tick the kernel scans every node's P and return stack for an address inside the old words' code. When none is there, it writes all of a set's jumps in that one tick. While some are there, it tries again on later ticks. A message waiting for an old word is not code on a stack and does not hold the set back: the word it reaches is the new one. 7. ~~Proofs first~~ **Ruled 2026-11-19: "Safe activation first".** The first Isabelle/HOL property: - the jump at each old entry is written only at a tick when no node's P or return stack holds an address inside the old code (choice 6); - after it, every call to an old word, from any caller, reaches the new word. Placement's checks, compatibility and the soundness of the derived stack effects come after. ## 10. Status All seven choices are ruled, plus 2c (no fixed effect means no export). This draft is the minimal ABI contract, the ADR's step 1, as ruled. The next step is the ADR's step 2, the artifact representation in detail: the exact cell layout of §4's records, a design for ruling before any code.