From a2a4a85d38c1d1be8154969507b5e5699eeb868b Mon Sep 17 00:00:00 2001 From: rajames Date: Sat, 3 Oct 2026 10:13:58 -0400 Subject: [PATCH] docs(v4.0.0): record the three products and v4's acceptance criteria Both ruled by Captain Bob, 2026-10-03. Products (README.md, JUSTIFICATION.md section 15): Hosted StarForth F18 (native Linux, amd64/arm64/riscv64, on hardware); FPGA StarForth F18 (a 32-bit build loaded into the FPGA, the gateway and foundation); and StarshipOS (bare metal, LithosAnanke on the v4 F18 engine). FORTH-79 recomposed on the F18 engine is stored as a capsule, as are the StarshipOS portions; the tree will be reorganised around this. Acceptance (JUSTIFICATION.md section 16, v4/README.md): v4 is equivalent to v3 at any point in time -- same vocabularies, same behaviour, on the F18-derived engine -- and every ISA, hosted and bare metal, must still reach its ok prompt. `make -C v4 test` is a development check, not acceptance. v4 had no acceptance criteria before this. Documentation only; no code changed. Co-Authored-By: Claude Opus 5.5 --- README.md | 19 +++++++++++++++++++ docs/v4.0.0/JUSTIFICATION.md | 31 +++++++++++++++++++++++++++++++ v4/README.md | 5 +++++ 3 files changed, 55 insertions(+) diff --git a/README.md b/README.md index 6fa97f8c..58957de6 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,25 @@ --- +## Products + +StarForth v4 moves the engine onto a 32-instruction core derived from Chuck Moore's F18 +(`docs/v4.0.0/`). With it, this repository carries three products, not one: + +| Product | What it is | +|---|---| +| **Hosted StarForth F18** | The v4 engine as a native Linux build, for amd64, arm64 and riscv64, on real hardware. | +| **FPGA StarForth F18** | A 32-bit build of the same engine loaded into the FPGA. It is the gateway to the rest: the foundation everything else is built up from. | +| **StarshipOS** | The bare-metal product: LithosAnanke running the v4 F18 engine. | + +FORTH-79 is recomposed on the F18 engine and stored as a capsule; the StarshipOS-specific +vocabulary gets the same treatment. The source tree will be reorganised around this split. + +v3 remains the reference system until v4 meets its acceptance criteria +(`docs/v4.0.0/JUSTIFICATION.md` §16). Everything below describes v3 as it stands today. + +--- + ## Status — M7.1 (Capsule System · Multi-VM Fleet) | Milestone | | Status | diff --git a/docs/v4.0.0/JUSTIFICATION.md b/docs/v4.0.0/JUSTIFICATION.md index 151110b3..24ae5735 100644 --- a/docs/v4.0.0/JUSTIFICATION.md +++ b/docs/v4.0.0/JUSTIFICATION.md @@ -224,3 +224,34 @@ LithosAnanke filing is a question for counsel. - K≡1.0 holds on the golden model at both widths, on all three host ISAs. - A hosted mesh runs the Tripod roles as nodes, with Hermes as the network. - Verilator co-simulation of one node matches the golden model instruction for instruction. + +## 15. Products + +Ruled by Captain Bob, 2026-10-03. v4 turns one project into three products built on the same engine: + +1. **Hosted StarForth F18.** The v4 engine as a native Linux build for amd64, arm64 and riscv64, on + real hardware. +2. **FPGA StarForth F18.** A 32-bit build of the engine loaded into the FPGA. This is the gateway into + building the whole system, and its foundation. +3. **StarshipOS.** The bare-metal product: LithosAnanke running the v4 F18 engine. + +The FORTH-79 vocabulary, recomposed on the F18 engine (`DECOMPOSITION.md`), is stored as a capsule. The +StarshipOS-specific portions are recomposed and stored as capsules in the same way. The source tree +will be reorganised around this split. + +## 16. Acceptance criteria + +Ruled by Captain Bob, 2026-10-03. Until then v4 had none: this document and `v4/README.md` named a +POST suite and K≡1.0 on three host ISAs, neither of which exists yet, so nothing could be called +accepted. + +- **v4 is equivalent to v3 at any point in time.** It must provide the same vocabularies and behave + the same way. The only difference is the machine underneath: the F18-derived engine instead of the + original StarForth VM. +- **Every ISA, hosted and bare metal, must still reach its `ok` prompt.** That is amd64, aarch64 and + riscv64, as a hosted build and as a bare-metal boot. + +The existing acceptance tests keep their force and their rules: the three-architecture QEMU boot for +anything bare metal (`.claude/CLAUDE.md`), and the hosted three-architecture test +(`docs/lithosananke/hosted-acceptance-test/README.md`). Passing `make -C v4 test` is a development +check on the golden model, not acceptance. diff --git a/v4/README.md b/v4/README.md index 3b1251dd..5315f636 100644 --- a/v4/README.md +++ b/v4/README.md @@ -8,6 +8,11 @@ The first deliverable is the hosted C99 golden model (`JUSTIFICATION.md` §10, step 1). It must pass POST and hold K≡1.0 with 32- and 64-bit cells on all three host ISAs. +Acceptance (`JUSTIFICATION.md` §16): v4 must be equivalent to v3 at any point +in time, with the same vocabularies and behaviour, on the F18-derived engine; +and every ISA, hosted and bare metal, must still reach its `ok` prompt. +`make -C v4 test` passing is a development check, not acceptance. + What exists so far is the single node: registers, circular stacks, memory, all 32 opcodes, and per-opcode and per-call-target heat. `make -C v4 test` builds and runs the tests at both cell widths; `make -C v4 sanitize` repeats them