From 5e1dcc197b2c98955cf4ca3e29fb0f30746e025b Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 19 Nov 2026 14:39:53 +0000 Subject: [PATCH] ABI.md: the F18 ABI, draft contract for ruling (ADR step 1) Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm --- docs/v4.0.0/ABI.md | 144 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 144 insertions(+) create mode 100644 docs/v4.0.0/ABI.md diff --git a/docs/v4.0.0/ABI.md b/docs/v4.0.0/ABI.md new file mode 100644 index 00000000..207d38b8 --- /dev/null +++ b/docs/v4.0.0/ABI.md @@ -0,0 +1,144 @@ +# 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, 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.