Files
LithosAnanke/docs/v4.0.0/ARTIFACT.md
T

132 lines
5.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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~~ **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:** 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?