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

6.4 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 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: as the golden model stores them (host order), or fixed low-first like the records?