rajamesandClaude Opus 5.5
10f5ffd00b
MESH.md 4.1, 7a, 7c.2, 7c.3, 7c.4 and step 6d say what the code now does,
what the review found and how each was mended, and what is small and not
mended. The README no longer says the aim is unmet; it says the mended
code has not been reviewed again.
Three bare-metal boots on 2cf37aab, typing 29 values on a line: POST 538
of 538, word_count=317, dict_hash=0xd41a6ac9448fff60 on all six.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
LithosAnanke v2.0.1
UEFI-bootable FORTH microkernel. Boots from firmware, initialises memory and interrupts, then runs the StarForth VM 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, 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 | |
|---|---|---|
| M0–M6 | UEFI boot · PMM · VMM · IDT · APIC · heap · framebuffer VT100 console (v1.5.1-FINAL) | ✅ Complete |
| M7 | StarForth VM integration + parity validation | ✅ Complete |
| M7.1 | Capsule birth protocol · Mama FORTH vocabulary · Tripod multi-VM fleet (Hermes/Artemis) · Word-level ACL (Phases 1–7) | 🔄 In Progress |
| M8 | REPL — keyboard input, interactive Forth | Planned |
| M9 | Block storage — AHCI driver | Planned |
POST at boot: parity hash verified across amd64/aarch64/riscv64 · Mama capsule dictionary: 453 words
What's live in M7.1
- Tripod — a named multi-VM fleet (Hera the Mama VM, Artemis, two Hermes instances) births, runs, and re-births independently, verified booting live pre-REPL on all three architectures.
- Hermes — a 17-block inter-VM messaging/channel layer between fleet members, with async delivery and channel negotiation.
- Artemis — a Block Allocation Map (BAM) storage subsystem with Q48.16
block-heat tracking and cooldown/reclamation (
ART-COOL/ART-REAP). - 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>). Phases 1–7 complete (C infrastructure, FORTH policy layer,zusebootstrap superuser, Isabelle proof stubs, kernel parity); Phase 8 (Ed25519 PKI / thumbdrive challenge-response) is the only item remaining. Measured overhead once active on every check: +0.0054%–+0.0088%, CV = 0.000%, across a 3×3 Latin-square DoE campaign (architecture × seed × 30 replicates) — three orders of magnitude below the measurement floor. - VM Fleet Attractor physics — the L8 Jacquard mode selector now has a real per-VM heat channel into fleet-wide tuning, replacing hardcoded compudynamics constants with a dynamically-inferred rate.
- Kconfig build configuration — every physics/heartbeat/pipelining/ kernel-only tuning knob (~40 total) is now a discoverable, optional Kconfig symbol shared with the hosted VM build. See Quick Start below.
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 boot_image TARGET=ZYNQ7020 # Zynq-7020 -- ARMv7 port in progress
make boards # list boards
# The same TARGET drives all, docs and clean (make help)
make # every board with a kernel port + hosted v3 + the book
make TARGET=RASPI # one board's image + build/docs/LithosAnanke-raspi.pdf
make docs # build/docs/LithosAnanke.pdf (LaTeX master: docs/book/main.tex)
make clean TARGET=RASPI # that board's outputs and build/aarch64/kernel
make clean # all of build/ except build/cache/
# Build kernel (requires cross-compilation toolchain, or native gcc)
make -f kernel/Makefile ARCH=amd64
# Run in QEMU with OVMF
make -f kernel/Makefile qemu
# Other architectures
make -f kernel/Makefile ARCH=aarch64 qemu
make -f kernel/Makefile ARCH=riscv64 qemu
Artifacts: build/amd64/kernel/starkernel_loader.efi · build/amd64/kernel/starkernel_kernel.elf
Tree: kernel/ (LithosAnanke: Makefile, src/, include/starkernel/, linker/),
v3/ (StarForth v3 engine and hosted build: Makefile, src/, include/),
v4/ (StarForth v4, see docs/v4.0.0/), boards/<board>/ (board.mk + boot files).
Every makefile runs from the repo root; the root Makefile forwards any other goal to
v3/Makefile (hosted build).
For the hosted VM by itself (Linux, no cross-compiler needed, no bare-metal tooling): see
the separate StarForth repository — LithosAnanke used to be a branch inside that repo,
now it's its own project with its own master.
Build configuration (optional)
Every kernel-only knob (STARFORTH_ENABLE_VM, PARITY_MODE, the shared
physics/heartbeat family, etc.) is an optional Kconfig symbol — a plain
make -f kernel/Makefile uses the same defaults it always has unless
you opt in:
make -f kernel/Makefile ARCH=amd64 menuconfig
make -f kernel/Makefile ARCH=amd64 kernel_amd64_defconfig
Documentation
| System Architecture | Full kernel + VM design |
| HAL Reference | Hardware abstraction layer interfaces |
| Capsule System — M7.1 | Capsule birth protocol design |
| VM Fleet Attractor design log | Tripod/Hermes/Artemis physics + build-system history |
| Getting Started / Kconfig reference | Full symbol reference for both build targets |
| Changelog | Milestone-level history |
| Roadmap | Milestone plan through self-hosting |
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