Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
6.3 KiB
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.cassembles.f18text onto a node.v4/tools/mkrom.cuses 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.care proved to agree.test_host_rom_nucleusassembles 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
.f18today. - once off the node with
-
Only one train has
.f18today: the nucleus. Its source iscapsules/v4/sys. The map comes first, then the fourteen files insys_files.h's order, thenend.f18. The boot feeds them to the ROM as the blobsv4:sys:*.f18(boot.c). -
The nucleus is not relocatable. It is assembled at a fixed origin against the map's fixed addresses.
end.f18stores 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...
- It assembles the sources with
text.c, at origin 0, in the order given. - It writes the artifact, laid out as
ARTIFACT.mdgives:- 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.
- 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,
EXECUTEand aDEFERred 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 artifactsbuilds the artifacts of each width intov4/build/.make -C v4 testruns it, so a.f18the 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, astest_host_rom_nucleuschecks 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'sv4-testsjob runsmake -C v4 testalready, so it gains the gate with no change.
4. Test first, seen to fail
test_text: the address record for a branch, a forward branch, a label, and an&NAME.test_effect, new: words of known effect, written intest_text's notation:dup(1 → 2);drop(1 → 0);- a call;
- a
for/nextloop of fixed count; - two branches that agree;
- two branches that disagree (no fixed effect).
test_mkf18a, new: a small text's artifact read back unit by unit againstARTIFACT.md. It checks the magic, the counts, each record, every reserved unit 0, and the code low byte first.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
- 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&NAMEliterals (31 incapsules/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. - Which train first. The nucleus is the only
.f18train, 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? - 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.f18last. Does each train name its order in a list, assys_files.hdoes, or does the tool take the files in name order? - 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.
- 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.cand their headers), or of the binary? - The name.
mkf18aand.f18a, after the magic, or something else?