v4: mkf18a, the host tool that builds a train's F18 artifact (ADR step 3, task 3)
Build / Image RASPI (push) Successful in 3m59s
Build / Image PC (push) Successful in 3m58s
Build / Image MILKV (push) Successful in 4m7s
Build / v4 tests (32- and 64-bit cells) (push) Successful in 16m5s

The artifact's layout and its check (artifact.h, artifact.c), the tool
(tools/f18a.c, mkf18a.c) and make -C v4 artifacts. test_mkf18a, 83
checks at both widths, failed against a stub first. Gates: test,
test-32 and sanitize pass, POST 990/990. Plan section 11.

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 21:09:22 +00:00
parent 84f119a1b3
commit dc3803ab47
12 changed files with 2924 additions and 3 deletions
@@ -247,3 +247,50 @@ this is a measure of the analysis, not an interface.
declaration. Where it can see a port or a request, it fails the build if the declaration is missing:
a literal port address put into A or B, or a kernel request with a literal number. What it cannot see
is the declaration's. This changes `ARTIFACT.md` choice 4's "the tool derives it from the code".
## 11. Task 3 built (2026-11-19): `mkf18a` and `make -C v4 artifacts`
**What changed.**
- `text.c` (part 1, committed first): the attributes after a `:` name (`immediate data inline compile-only
pinned mode N ports request N`), recorded and laid nowhere in the code; `import TRAIN NAME`, whose uses are
calls to a placeholder `V4_NODE_WORDS-1-k` and are recorded as relocations to import k. A use before the
declaration fails, and so does code that reaches the placeholders.
- `include/v4/artifact.h`, `src/artifact.c`: the layout of `ARTIFACT.md` and its check (§7), shared by the
tool and, later, by placement.
- `tools/f18a.c`, `tools/f18a.h`, `tools/mkf18a.c`: the tool, `mkf18a OUT.f18a MAP.f18 ROM DIR
[TRAIN=PATH.f18a ...]`. It assembles the map, then DIR's `.f18` files in name order, at 0, with the record
on (§6.3). It refuses a header, a start, and a store; resolves each import from the trains it is given;
derives the effects (§9) and exports every `:` word that has one (§6.4, ruling 1); checks the declared
capabilities (ruling 5); and writes the relocations, the pool and the four hashes.
- `Makefile`: `mkf18a-32`, `mkf18a-64` and their tests; `artifacts` builds the tool at both widths. `test`
runs `mkf18a-32/64`, `sanitize` their ASan+UBSan builds.
**Test first, seen to fail.** `test_text` had 11 failures of 274 checks before part 1
(`logs/20261119-mkf18a/text-before-64.txt`), none after (`text-after.txt`). `test_mkf18a` failed at its
first check against a stub that built nothing (`mkf18a-before-64.txt`), and passes 83 checks at both widths
after (`mkf18a-after-64.txt`, `mkf18a-after.txt`). It builds a library train and a train that imports from
it, reads every unit back against `text.c`, builds both twice for the same bytes, and checks ten refusals:
of the checker, and of the tool (r1-r9 refused, r10 built).
**The test's own error.** A name meant to be 32 characters, to be refused, was 31 and was taken; the test
was corrected, not the tool.
**Choices made in drafting, for ruling:**
1. The provenance hashes frame each input as its name, a NUL, its length in 8 bytes low first, then its bytes
(`f18a.h`).
2. The tool's hash covers `tools/mkf18a.c`, `tools/f18a.c`, `tools/f18a.h`, `src/artifact.c`, `asm.c`,
`effect.c`, `iword.c`, `text.c`, then every `include/v4/*.h`, in that order. The configuration hash covers
the text `V4_CELL_BITS=.. V4_NODE_WORDS=.. V4_DATA_RING=.. V4_RET_RING=.. V4_ROM_WORDS=..`, framed as
`config`, then the map. The ROM's is the ROM file.
3. The pool's unit 0 is always 0, so an offset of 0 means none.
4. A store of a literal number to `(PORT)` counts as a request, not as touching the ports.
5. Capabilities pass through calls: a word that calls one that declares `ports` must declare it too.
6. The imports' placeholders are the node's top words, `V4_NODE_WORDS-1-k`.
**Recorded, not fixed:** a store into the code below `here` is not caught by the store check, which looks
only above `here`.
**Verified** (`logs/20261119-mkf18a/v4-gates.txt`, exit 0):
- `make -C v4 test` passes, with the mesh boots at POST 990/990, and `mkf18a-64` and `mkf18a-32` at 83 checks.
- `make -C v4 test-32` passes.
- `make -C v4 sanitize` passes, `mkf18a` included at both widths.