# The F18 artifact -- its layout, draft for ruling Written 2026-11-19. Step 2 of `ADR-2026-11-19-F18-ARTIFACTS.md` §7, "Establish the canonical binary artifact representation". It gives the exact layout of the records `ABI.md` §4 lists, under ABI v0 as ruled: - one train per capsule; - a host tool assembles all of a capsule's `.f18` into its engine; - each export's stack effect is derived, and a word with none fixed is not exported; - imports name the exact build; - the source travels by reference. **Nothing here is built.** The choices left open are numbered in §8. ## 1. Units, order, width - **The unit is a 32-bit word**, stored little-endian, low byte first, as v4's blocks are (`blocks.h`: "four bytes to a cell, the first lowest"). Every record is a whole number of units, so the records read the same at either cell width. - **The code is cells of the build's width.** A 32-bit engine and a 64-bit engine are two artifacts: the header says which, and placement refuses the wrong one. - **A 64-bit value**, such as a capsule's hash, is two units, low unit first. - **A SHA-512 hash** (choice 2) is 16 units: its 64 bytes in their order, packed four to a unit, low byte first. - **A name** is a counted string, its length byte then its characters, packed four to a unit, low byte first, as the dictionary packs names (`dict.f18`). It sits in the string pool and is referred to by its unit offset. ## 2. The whole ``` header 16 units provenance 64 units exports E x 8 units imports I x 6 units relocations R x 2 units verification 18 units string pool S units code C cells ``` The offsets of each part are in the header, so a reader skips what it does not need. The artifact is the engine of a train: the capsule's payload. The capsule's content hash and Ed25519 signature, already `mkcapsule`'s, cover it whole. The artifact repeats neither. ## 3. Header (16 units) | Unit | Field | |---|---| | 0 | magic `F18A` (`0x41383146`) | | 1 | ABI version: 0 | | 2 | cell width in bits: 32 or 64 | | 3 | the node words it was built for (`V4_NODE_WORDS`) | | 4–5 | E, the export count; I, the import count | | 6–7 | R, the relocation count; S, the string pool's units | | 8 | C, the code's cells | | 9 | the unit offset of the exports (the others follow, in §2's order) | | 10–15 | reserved, 0 | ## 4. Provenance (64 units, ADR §3.1) Each hash is SHA-512 (choice 2). | Units | Field | |---|---| | 0–15 | the hash of the `.f18` source the engine was assembled from (ABI choice 3: by reference) | | 16–31 | the host tool's hash, the compiler's identity (ABI choice 1) | | 32–47 | the build configuration's hash: the knobs that change code, the cell width, `V4_NODE_WORDS`, the rings | | 48–63 | the ROM's hash it must agree with: the tool's output is checked against the ROM's assembly | ## 5. Exports, imports, relocations **An export (8 units):** | Unit | Field | |---|---| | 0 | the name, as a string pool offset | | 1 | the entry's offset in the code, in cells: the xt, relative to the base | | 2 | the flags, as the entry's: immediate, compile-only, in-line, and the ACL defaults (pinned, mode) | | 3 | the data stack effect: cells taken in the low 16 bits, cells left in the high 16, derived (choice 2) | | 4 | the return stack effect, the same way, derived | | 5 | the capabilities: bit 31 set if it touches ports; bits 0–30 the string pool offset of its list of kernel requests, or 0 for none | | 6–7 | reserved, 0 | **An import (6 units):** | Units | Field | |---|---| | 0–1 | the exporting train's capsule hash, the exact build (choice 4) | | 2 | the word's name, as a string pool offset | | 3 | the data stack effect it is expected to have | | 4 | the return stack effect it is expected to have | | 5 | reserved, 0 | **A relocation (2 units):** | Unit | Field | |---|---| | 0 | the code cell, as an offset, and in the top 3 bits the slot whose branch field holds the address (0–3) | | 1 | what it points to: `0xFFFFFFFF` for internal, so the base is added; otherwise the import's index | Placement (`ABI.md` §5) patches each relocation's branch field. It refuses a patched address beyond that slot's reach: 27, 22, 17 or 12 bits (`iword.h`). ## 6. Verification (18 units, ADR §5) | Units | Field | |---|---| | 0–15 | the SHA-512 hash of the proof that covers this exact artifact: its theory and its build; all 0 means none | | 16 | the assumptions it holds under, as a string pool offset, or 0 | | 17 | reserved, 0 | ## 7. What makes a valid artifact The tool writes these properties and placement checks them. They are also the first things Isabelle states about the format: - the magic and the version; - every count and offset within the payload; - every string pool offset on a counted string, or, for a capabilities list, on a unit holding its count *n* followed by *n* units, each a `KERNEL-WORD` number; - every export's entry inside the code; - every relocation's cell inside the code, its slot one that holds a branch, its import index below I; - every reserved unit 0. ## 8. Open, for ruling one at a time 1. ~~The unit~~ **Ruled 2026-11-19: "32-bit units".** Every record is in 32-bit units, low byte first, as v4's blocks are, so the records read the same at either cell width (§1). Only the code is in the build's cells. 2. ~~The hashes~~ **Ruled 2026-11-19: "SHA-512 for provenance".** The provenance hashes (source, tool, configuration, ROM) and the proof's hash are SHA-512, the one already in the tree for Ed25519, 16 units each (§4, §6). An import's capsule hash stays the capsule's ID, XXHash64, 2 units (§5), and signing stays Ed25519. The provenance record grows from 12 units to 64, with no reserved units, and verification from 4 to 18. 3. ~~The return-stack effect~~ **Ruled 2026-11-19: "Record and check both".** The tool derives the return-stack effect as it derives the data-stack effect, and records it in unit 4 of each export and import (§5). Placement, compatibility (`ABI.md` §7, "the same stack effect") and the proofs check both. 4. ~~Capabilities~~ **Ruled 2026-11-19: "Port bit + request list".** As drafted (§5, unit 5). The tool derives it from the code: a port opcode sets the bit, and each kernel request the word reaches goes in its list. Compatibility refuses a replacement that needs one the old did not (`ABI.md` §7). The list is a count unit then that many request numbers (§7). 5. **Endianness for the code cells:** as the golden model stores them (host order), or fixed low-first like the records?