Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
5.5 KiB
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
.f18into 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
The unitRuled 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.- 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.
- The return-stack effect: recorded and checked (§5, unit 4), or the data stack only?
- Capabilities: the port bit plus a list of kernel request numbers (§5, unit 5), or something else?
- Endianness for the code cells: as the golden model stores them (host order), or fixed low-first like the records?