From e43cd6393625503bf3b94b21b896277a45d1ab81 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 19 Nov 2026 16:05:50 +0000 Subject: [PATCH] ARTIFACT.md: the F18 artifact's layout, draft for ruling (ADR step 2) Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm --- docs/v4.0.0/ARTIFACT.md | 129 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 129 insertions(+) create mode 100644 docs/v4.0.0/ARTIFACT.md diff --git a/docs/v4.0.0/ARTIFACT.md b/docs/v4.0.0/ARTIFACT.md new file mode 100644 index 00000000..67fa8afb --- /dev/null +++ b/docs/v4.0.0/ARTIFACT.md @@ -0,0 +1,129 @@ +# 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 hash, is two units, low unit 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 12 units +exports E x 8 units +imports I x 6 units +relocations R x 2 units +verification 4 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 (12 units, ADR §3.1) + +| Units | Field | +|---|---| +| 0–1 | the hash of the `.f18` source the engine was assembled from (choice 3: by reference) | +| 2–3 | the host tool's hash, the compiler's identity (choice 1) | +| 4–5 | the build configuration's hash: the knobs that change code, the cell width, `V4_NODE_WORDS`, the rings | +| 6–7 | the ROM's hash it must agree with: the tool's output is checked against the ROM's assembly | +| 8–11 | reserved, 0 | + +## 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: a bit for the ports, then a string pool offset to its list of kernel request numbers, or 0 | +| 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 (4 units, ADR §5) + +| Units | Field | +|---|---| +| 0–1 | the hash of the proof that covers this exact artifact: its theory and its build; 0 means none | +| 2 | the assumptions it holds under, as a string pool offset, or 0 | +| 3 | 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; +- 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:** 32-bit units, width-independent records (§1), or the build's cell for everything? +2. **The hashes:** XXHash64, as capsule identities are today, for every hash in the artifact, or a + cryptographic hash (SHA-512, already in the tree for Ed25519) for provenance and proofs? Signing stays + Ed25519 either way. +3. **The return-stack effect:** recorded and checked (§5, unit 4), or the data stack only? +4. **Capabilities:** the port bit plus a list of kernel request numbers (§5, unit 5), or something else? +5. **Endianness for the code cells:** as the golden model stores them (host order), or fixed low-first like + the records?