plans: artifacts in the build (ADR step 3), draft for ruling

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
This commit is contained in:
Claude
2026-11-19 16:25:39 +00:00
parent f2174a39a4
commit 16b8fddaef
@@ -0,0 +1,111 @@
# 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` `store`s 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 `DEFER`red 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?