Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
150 lines
6.9 KiB
Markdown
150 lines
6.9 KiB
Markdown
# 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 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-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~~ **Ruled 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.
|