Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
6.9 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 in §8 are ruled (2026-11-19).
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, each stored low byte first (choice 5). 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-WORDnumber; - 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 hashesRuled 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.The return-stack effectRuled 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.CapabilitiesRuled 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).Endianness for the code cellsRuled 2026-11-19: "Low-first, like the records". Every byte of the artifact has one order, low byte first, so its hashes and signature are the same whichever host built it. A big-endian host swaps the bytes when it places the code.
9. Status
All five choices are ruled. This is the artifact layout, the ADR's step 2, as ruled. The next step is the ADR's step 3: artifact production in the build (the host tool), designed for ruling before any code.