Files
LithosAnanke/docs/v4.0.0/ARTIFACT.md
T
Claude e43cd63936
Build / Image RASPI (push) Successful in 5m28s
Build / Image PC (push) Successful in 4m15s
Build / Image MILKV (push) Successful in 5m11s
Build / v4 tests (32- and 64-bit cells) (push) Successful in 15m13s
ARTIFACT.md: the F18 artifact's layout, draft for ruling (ADR step 2)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-19 16:05:50 +00:00

5.3 KiB
Raw Blame History

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?