Files
LithosAnanke/docs/v4.0.0/plans/2026-11-19-f18-artifact-build.md
T

6.3 KiB
Raw Blame History

Artifacts in the build -- design, for ruling

Written 2026-11-19. Step 3 of ADR-2026-11-19-F18-ARTIFACTS.md §7, "Integrate artifact production into the existing build system". It builds on:

  • ABI.md, ABI v0 as ruled, in particular choice 1, "A host tool";
  • ARTIFACT.md, the layout as ruled.

Nothing here is built. The questions are in §6, put to Captain Bob one at a time.

1. What is there already

  • The host assembler exists. v4/src/text.c assembles .f18 text onto a node. v4/tools/mkrom.c uses it on the build machine to build the ROM, "as a bitstream is built". The tests use it to build the system.

  • The ROM and text.c are proved to agree. test_host_rom_nucleus assembles the system's source twice:

    • once off the node with text.c, the oracle;
    • once on the machine, by the ROM fed through the console.

    Every word of RAM must be the same, apart from the ROM's own state. This is ABI choice 1's cell-for-cell check already, for the one train that has .f18 today.

  • Only one train has .f18 today: the nucleus. Its source is capsules/v4/sys. The map comes first, then the fourteen files in sys_files.h's order, then end.f18. The boot feeds them to the ROM as the blobs v4:sys:*.f18 (boot.c).

  • The nucleus is not relocatable. It is assembled at a fixed origin against the map's fixed addresses. end.f18 stores addresses into the map's variables, and its dictionary holds absolute links. Ruling 1 keeps it as it is: the ROM still assembles the system at boot (ABI.md §8).

2. The tool: v4/tools/mkf18a.c

A C tool beside mkrom.c, built the same way, one per cell width:

mkf18a OUT.f18a MAP.f18 SOURCE.f18...
  1. It assembles the sources with text.c, at origin 0, in the order given.
  2. It writes the artifact, laid out as ARTIFACT.md gives:
    • the header;
    • the provenance, with its four SHA-512 hashes;
    • the exports, the imports and the relocations;
    • an empty verification record;
    • the string pool and the code, low byte first.
  3. It fails the build if anything cannot be written as the ABI requires:
    • an export with no fixed effect (2c);
    • a relocation whose patched address is beyond its slot's reach;
    • a capability it cannot derive.

The relocations come from text.c. text.c gains a record of each cell it lays down that holds an address: every branch it resolves to a word or a label, and every &NAME. That is one hook, and test-first: test_text checks the record against the cells.

The stack effects come from a new analysis, v4/src/effect.c. It walks each word's instruction words from its entry to every ; and counts what each opcode takes and leaves on both stacks:

  • the opcode table is iword.h's;
  • a call takes the effect of the word it calls, derived first;
  • a branch that joins two paths with different depths is "no fixed effect";
  • so are a loop whose count is data, EXECUTE and a DEFERred word.

It is a module of its own, so the proofs can state it on its own (ADR step 5).

3. Where it runs

  • v4/Makefile: make -C v4 artifacts builds the artifacts of each width into v4/build/. make -C v4 test runs it, so a .f18 the tool refuses fails the test gate.
  • The check against the ROM: a new test, test_host_artifact, places the nucleus's artifact on node A at its own origin, by the relocation records. Node B is the ROM assembling the same source. Every word must agree, as test_host_rom_nucleus checks now. That proves the records, as well as the assembler.
  • The kernel build: nothing changes in step 3. The boot still feeds the ROM the source. Carrying the artifact in the capsule, and placing it, is steps 4 and 6.
  • CI: build.yml's v4-tests job runs make -C v4 test already, so it gains the gate with no change.

4. Test first, seen to fail

  1. test_text: the address record for a branch, a forward branch, a label, and an &NAME.
  2. test_effect, new: words of known effect, written in test_text's notation:
    • dup (1 → 2);
    • drop (1 → 0);
    • a call;
    • a for/next loop of fixed count;
    • two branches that agree;
    • two branches that disagree (no fixed effect).
  3. test_mkf18a, new: a small text's artifact read back unit by unit against ARTIFACT.md. It checks the magic, the counts, each record, every reserved unit 0, and the code low byte first.
  4. test_host_artifact: the nucleus, placed from its artifact, equal to the ROM's assembly word for word.

POST, the protocol and the dictionary gate are unchanged, since the boot is unchanged.

5. Cost

The build gains one assembly of the nucleus per width, which takes a second or less on the host (test_host_rom_nucleus reports its time today), plus the analysis. That is measured when it is built, as ADR step 8 asks. The boot gains nothing.

6. For ruling, one at a time

  1. Address literals. ARTIFACT.md §5's relocation covers branch fields only (a slot, 0–3). The system's source also holds addresses in whole cells: the &NAME literals (31 in capsules/v4/sys), and the dictionary's links. One fix is a slot value of 7 meaning "the whole cell". The top 3 bits allow 0–7, so the record keeps its size.
  2. Which train first. The nucleus is the only .f18 train, but it is not relocatable, and the ROM keeps assembling it (§1). Its artifact can be built and checked (§3), but it is never placed by the loader. Is the nucleus the first artifact, or is a small relocatable train written first?
  3. The order of the sources. Captain Bob's image is "the .f18 assembler assembles all .f18 files it finds", but the order matters: the map first, sys_files.h's list, end.f18 last. Does each train name its order in a list, as sys_files.h does, or does the tool take the files in name order?
  4. Which words are exports. The nucleus defines hundreds of words, and some have no fixed effect, which 2c refuses as exports. Is every word with a fixed effect exported, or only those a list names? With a list, the words outside it stay internal.
  5. The tool's identity. The provenance holds "the host tool's hash". The hash of the binary differs with the host's compiler. Should it be the hash of the tool's source (mkf18a.c, text.c, effect.c and their headers), or of the binary?
  6. The name. mkf18a and .f18a, after the magic, or something else?