rajamesandClaude Opus 5.5
79db0e8d88
Captain Bob, 2026-10-14: "v4 is the default build", "no, qemu to v4 too ... we are effectively trying to retire v3", "the 32 bit build needs to go into the acceptance test too", "i don't care about v3". - STARFORTH_V4 defaults on (Kconfig default y) and V4_DEFAULT=1 everywhere: every kernel carries v4 and v3 and boots v4; system=v3 boots v3; STARFORTH_V4=0 builds v3 alone. Board images write system=v4. - Acceptance (CLAUDE.md): the three ISAs as built (v4, POST passed, V4_SYSTEM dict_hash equal) and make -C v4 test-32. v3 is not part of it. Acceptance run: amd64, aarch64, riscv64 -- PARITY:V4_POST 538/538, dict_hash=0xe5a57f3eb72ff94a on all three, no unknown word; test-32: 30 suites, 0 failures. The SER5 image under OVMF boots v4 as built, v3 after the one-word edit. README, BRINGUP, FABRIC-3 XLIII, the register updated. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
LithosAnanke v2.1.0
UEFI-bootable FORTH microkernel. Boots from firmware, initialises memory and interrupts, then runs StarForth as its sole userspace runtime. No libc. No OS. Just stone and necessity.
Lithos (foundation) + Ananke (necessity) — the kernel under StarshipOS.
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. |
| FPGA StarForth F18 | A 32-bit build of the same engine loaded into the FPGA: the gateway to the rest, the foundation everything else is built up from. |
| StarshipOS | The bare-metal product: LithosAnanke running StarForth. |
FORTH-79 is recomposed on the F18 engine and stored as a capsule; the StarshipOS-specific
vocabulary gets the same treatment. v3 remains the reference system until v4 meets its
acceptance criteria (docs/v4.0.0/JUSTIFICATION.md §16). Both run on bare metal now: every
board image carries v4 and v3, boots v4 as built, and one word in its boot configuration
chooses (see below).
Status
| Milestone | Status | |
|---|---|---|
| M0–M6 | UEFI boot · PMM · VMM · IDT · APIC · heap · framebuffer VT100 console | ✅ Complete |
| M7 | StarForth VM integration + parity validation | ✅ Complete |
| M7.1 | Capsule birth · Mama FORTH vocabulary · the Tripod fleet · kernel-Hermes · word-level ACL | ✅ Live |
| M8 | Keyboard input to the REPL — PS/2, virtio and USB keyboards (a full keyboard: Caps/Num Lock, keypad) | ✅ In QEMU, all three ISAs |
| M9 | Block storage — Artemis's disk on virtio-blk; identity thumbdrives on USB mass storage | ✅ In QEMU · real disks: no driver yet (boards/BRINGUP.md A4) |
| Bare metal | SER5 (amd64), Raspberry Pi 5 (aarch64), Milk-V Mars (riscv64); Zynq-7020 (ARMv7) not yet ported | Images build; first boots on the bench — boards/BRINGUP.md |
v4 is the default build, and v3 is being retired: every kernel boots v4 unless its boot
arguments say system=v3. POST at boot, on all three ISAs: v4 — 538 tests,
PARITY:V4_SYSTEM word_count=317 dict_hash=0xe5a57f3eb72ff94a; v3 — 1052 tests,
PARITY:M7.1a word_count=526 hash=0x82f4ae7cb2e2d424.
What's live
- The Tripod — a named multi-VM fleet: Hera (the Mama VM, the governor), Artemis (block storage: a Block Allocation Map with Q48.16 block heat, cooldown and reclamation) and Hestia, birthed, run and re-birthed independently on all three architectures.
- kernel-Hermes — messaging moved into the kernel (the Hermes VM is gone,
docs/fabric/FABRIC-3.5.md): every VM takes its own messages on its own turn, under a cooperative switcher that every VM takes part in. - Identities on thumbdrives — Zuse, the superuser, and every user is a minted USB thumbdrive (Ed25519, Zuse-signed); plugging one in births that user's VMs, pulling it out ends them. There is only the drive: no password, no PIN.
- Word-level ACL — every dictionary entry carries a TTL/allow/mode/pin access-control
record; strict, TTL and pinned modes; two console layers (emergency
ok>and superuserzuse)ok>). Measured overhead of the live ACL-TTL mechanism: +0.0603%, CV 0.000%, architecture-independent (docs/fabric/FABRIC-1.md§T). - Logs that persist — every VM's log records go to a ring on Artemis's disk (
LOG-FLUSH,LOG-SHOW). - The physics-driven runtime — seven feedback loops and the L8 Jacquard mode selector, with a per-VM heat channel into fleet-wide tuning (VM Fleet Attractor).
- Kconfig build configuration — about 40 physics, heartbeat, pipelining and kernel-only knobs, shared with the hosted build.
Quick Start
# One boot image per physical target (output: build/boards/<board>/)
make boot_image TARGET=SER5 # Beelink SER5 -- GPT/ESP, BOOTX64.EFI
make boot_image TARGET=RASPI # Raspberry Pi 5 -- FAT, config.txt + kernel_2712.img + DTB
make boot_image TARGET=MILKV # Milk-V Mars -- GPT/ESP, BOOTRISCV64.EFI (U-Boot bootefi)
make boards # list boards (the Zynq-7020 has no ARMv7 port yet)
# Each image carries v4 and v3. As built it boots v4; to boot v3, change the one word
# system=v4 -> system=v3
# in starforth.cfg on the SER5's stick or the Mars's card, or cmdline.txt on the Pi 5's card.
# The same TARGET drives all, docs and clean (make help)
make # every board with a kernel port + hosted v3 + the book
make docs # build/docs/LithosAnanke.pdf (LaTeX master: docs/book/main.tex)
make clean TARGET=RASPI # that board's outputs and build/aarch64/kernel
# The kernel in QEMU (OVMF / AAVMF / EDK2), one architecture at a time -- boots v4
make -f kernel/Makefile ARCH=amd64 clean qemu
make -f kernel/Makefile ARCH=aarch64 clean qemu
make -f kernel/Makefile ARCH=riscv64 clean qemu
make -f kernel/Makefile ARCH=amd64 KERNEL_ARGS=system=v3 clean qemu # v3, while it remains
# The Pi 5's native boot path, rehearsed on QEMU's virt machine at EL2
make -f kernel/Makefile ARCH=aarch64 RPI5_NATIVE_BASE=0x40080000 rpi5-rehearsal
Artifacts: build/<arch>/kernel/starkernel_loader.efi · build/<arch>/kernel/starkernel_kernel.elf
Tree: kernel/ (LithosAnanke: Makefile, src/, include/starkernel/, linker/),
v3/ (StarForth v3 engine and hosted build), v4/ (StarForth v4, see docs/v4.0.0/),
boards/<board>/ (board.mk + boot files), capsules/ (the FORTH capsules). Every makefile
runs from the repo root; the root Makefile forwards any other goal to v3/Makefile.
For the hosted v3 VM by itself, see the separate StarForth repository — LithosAnanke used to be a branch inside it, and is now its own project.
Build configuration (optional)
Every kernel-only knob is an optional Kconfig symbol; a plain make -f kernel/Makefile uses
the defaults unless you opt in:
make -f kernel/Makefile ARCH=amd64 menuconfig
make -f kernel/Makefile ARCH=amd64 kernel_amd64_defconfig
Documentation
Start at docs/README.md — the map: where each kind of document lives and which to believe. Among them:
| The FABRIC record | Every design decision and the work as it happened (FABRIC-3.md is the living one) |
| StarForth v4 | The F18-derived engine |
| Board bring-up | Getting onto the SER5, the Pi 5 and the Mars |
| Roadmap and versioning | Milestone plan and release-versioning policy |
| Capsule System — M7.1 | Capsule birth protocol |
| Word-level ACL | The access-control design |
| HAL, as built | Hardware abstraction layer |
| Developer guide / Kconfig reference | Full symbol reference for both builds |
| Dead ideas and revised claims | What is no longer true, and since when |
| Changelog | Milestone-level history |
License
Starship License 1.0 (SL-1.0) — free for personal, research, and educational use. Commercial use requires a separate agreement. Attribution to R.A. James (Captain Bob) must be preserved in all distributions.
Patent pending. USPTO provisional filed December 2025 — physics-grounded self-adaptive runtime system. This license does not grant patent rights. Licensing inquiries: rajames440@gmail.com
Robert A. James (Captain Bob) · Systems Engineer · Hacking since 1973