From 16b8fddaef0aee7b70bc4da7e1d116c7ea112c07 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 19 Nov 2026 16:25:39 +0000 Subject: [PATCH] plans: artifacts in the build (ADR step 3), draft for ruling Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm --- .../plans/2026-11-19-f18-artifact-build.md | 111 ++++++++++++++++++ 1 file changed, 111 insertions(+) create mode 100644 docs/v4.0.0/plans/2026-11-19-f18-artifact-build.md diff --git a/docs/v4.0.0/plans/2026-11-19-f18-artifact-build.md b/docs/v4.0.0/plans/2026-11-19-f18-artifact-build.md new file mode 100644 index 00000000..2f99c5d1 --- /dev/null +++ b/docs/v4.0.0/plans/2026-11-19-f18-artifact-build.md @@ -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?