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:
@@ -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?
|
||||
Reference in New Issue
Block a user