diff --git a/docs/v4.0.0/MACHINE.md b/docs/v4.0.0/MACHINE.md index 4b1e1c88..7a6d8ad1 100644 --- a/docs/v4.0.0/MACHINE.md +++ b/docs/v4.0.0/MACHINE.md @@ -26,7 +26,10 @@ machine and a ROM. | **Trailer** | Source, as named blobs. `.f18` is F18 assembler. `.4th` is FORTH. The blob's name gives its type. | The capsule directory (`capsules/`) | The ROM is the only binary. It runs the same on the C engine and on the FPGA: one binary, the -same behaviour. Assemble FORTH from the trailer and the node is a FORTH machine. Assemble Lisp +same behaviour. **Superseded in part, 2026-11-19** (Captain Bob, "ADR supersedes"; +`ADR-2026-11-19-F18-ARTIFACTS.md`): the build may also compile F18 into binary artifacts, with their +identity, provenance and interface. An artifact is a choice, not a requirement: the ROM still +assembles source at boot. Assemble FORTH from the trailer and the node is a FORTH machine. Assemble Lisp and it would be a Lisp machine. The engine and the ROM do not change. ### 1.1 What it is for @@ -204,7 +207,7 @@ streams the ROM instead. | Today | Becomes | |---|---| | `v4/capsule/*.v4`, 14 files, 311 words, assembled on the build machine | `.f18` blobs under `capsules/v4/`, assembled by the ROM at boot | -| `v4/tools/mkimage.c` → `nucleus-64.f18`, a prebuilt dictionary | Builds the ROM only. The nucleus binary is gone. | +| `v4/tools/mkimage.c` → `nucleus-64.f18`, a prebuilt dictionary | Builds the ROM only. The nucleus binary is gone. (2026-11-19: compiled F18 artifacts are allowed beside the ROM, `ADR-2026-11-19-F18-ARTIFACTS.md`.) | | `v4/src/text.c`, the assembler in C | The ROM's assembler is F18 code. `text.c` builds the ROM, as the first assembler builds the next. | | `forth79.4th`: `U*`, `U/MOD` only | Every FORTH-79 word that is not an opcode, a register or the FORTH machinery (`NUCLEUS.md` 4, rule 1). It moves group by group, with POST after each (`NUCLEUS.md` 8, step 3). | | `boot_capsules[]` in `v4/system/boot.c` | The system list (step 2, then step 3) is the loader's. Everything after POST is `init.4th`'s. | diff --git a/docs/v4.0.0/plans/2026-11-19-f18-artifacts.md b/docs/v4.0.0/plans/2026-11-19-f18-artifacts.md new file mode 100644 index 00000000..f6669b13 --- /dev/null +++ b/docs/v4.0.0/plans/2026-11-19-f18-artifacts.md @@ -0,0 +1,12 @@ +# F18 binary artifacts, ABI/API, live updates -- the rulings + +The decision is `docs/v4.0.0/ADR-2026-11-19-F18-ARTIFACTS.md`, recorded as given. This file records each +conflict between it and the existing record, put to Captain Bob one at a time, and his ruling. + +**Nothing is built.** The ADR's §7 order is followed; step 1 is the minimal ABI contract. + +## The conflicts, one at a time + +1. **"The ROM is the only binary"** (MACHINE.md §1, §5, ruled 2026-10-15) against compiled F18 artifacts. + **Ruled: "ADR supersedes".** MACHINE.md §1 and §5 now say that compiled artifacts are allowed beside the + ROM. An artifact is a choice, not a requirement: the ROM still assembles source at boot.