admin/LithosAnanake
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: the 12 duplicates deleted; README rewritten to the system as it is

Browse Source 
Captain Bob's rulings, 2026-10-14: "delete" -- the duplicates listed in
DELETE-CANDIDATES.md are removed (the list stays as the record; the
formal tier's provenance comments repointed at the maintained copies) --
and "rewrite" the README: v2.1.0, the Tripod as Hera/Artemis/Hestia,
kernel-Hermes, identities on thumbdrives, the corrected ACL overhead,
1052-test POST and the current parity line, keyboards and storage, board
images carrying both systems and how to switch, and docs/README.md as
the way in.  The book is left as it is, to be reworked later.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
rajames
2026-10-14 16:45:39 -04:00
co-authored by Claude Opus 5.5
parent 776c89457e
commit f8fbc37698
23 changed files with 91 additions and 4932 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+69 -68
View File
@@ -1,6 +1,7 @@
# LithosAnanke v2.0.1
# LithosAnanke v2.1.0
**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.
**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.
@@ -13,54 +14,52 @@ StarForth v4 moves the engine onto a 32-instruction core derived from Chuck Moor
| 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. |
| **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. 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.
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 v3 and v4, and one word in its boot configuration chooses (see below).
---
## Status — M7.1 (Capsule System · Multi-VM Fleet)
## Status
| Milestone | | Status |
|---|---|---|
| M0–M6 | UEFI boot · PMM · VMM · IDT · APIC · heap · framebuffer VT100 console (v1.5.1-FINAL) | ✅ Complete |
| M0–M6 | UEFI boot · PMM · VMM · IDT · APIC · heap · framebuffer VT100 console | ✅ 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 |
| 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` |
POST at boot: **parity hash verified across amd64/aarch64/riscv64 · Mama capsule dictionary: 453 words**
POST at boot, on all three ISAs: **1052 tests**, parity hash verified —
`PARITY:M7.1a word_count=526 hash=0x82f4ae7cb2e2d424`. The v4 system's POST: 538 tests.
### What's live in M7.1
### What's live
- **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 superuser `zuse)ok>`). Phases 1–7 complete (C
infrastructure, FORTH policy layer, `zuse` bootstrap 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.
- **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 superuser
`zuse)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.
---
@@ -71,45 +70,41 @@ POST at boot: **parity hash verified across amd64/aarch64/riscv64 · Mama capsul
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
make boards # list boards (the Zynq-7020 has no ARMv7 port yet)
# Each image carries v3 and v4. As built it boots v3; to boot v4, change the one word
# system=v3 -> system=v4
# 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 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
# The kernel in QEMU (OVMF / AAVMF / EDK2), one architecture at a time
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 STARFORTH_V4=1 clean qemu # the v4 system
# 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
# 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/amd64/kernel/starkernel_loader.efi` · `build/amd64/kernel/starkernel_kernel.elf`
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: `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).
`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 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`.
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 (`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:
Every kernel-only knob is an optional Kconfig symbol; a plain `make -f kernel/Makefile` uses
the defaults unless you opt in:
```bash
make -f kernel/Makefile ARCH=amd64 menuconfig
@@ -120,15 +115,21 @@ make -f kernel/Makefile ARCH=amd64 kernel_amd64_defconfig
## Documentation
**Start at [docs/README.md](docs/README.md)** — the map: where each kind of document lives and
which to believe. Among them:
| | |
|---|---|
| [System Architecture](docs/working/archive/historical/2026-01-27-system-architecture-draft.md) | Full kernel + VM design |
| [HAL Reference](kernel/src/hal/README.md) | Hardware abstraction layer, as built |
| [Capsule System — M7.1](docs/reference/M7.1.md) | Capsule birth protocol design |
| [VM Fleet Attractor design log](docs/working/architecture/VM-FLEET-ATTRACTOR-DESIGN-20260705.md) | Tripod/Hermes/Artemis physics + build-system history |
| [Getting Started / Kconfig reference](docs/working/architecture/getting-started/DEVELOPER.md#build-configuration-kconfig) | Full symbol reference for both build targets |
| [The FABRIC record](docs/fabric/) | Every design decision and the work as it happened (`FABRIC-3.md` is the living one) |
| [StarForth v4](docs/v4.0.0/) | The F18-derived engine |
| [Board bring-up](boards/BRINGUP.md) | Getting onto the SER5, the Pi 5 and the Mars |
| [Roadmap and versioning](docs/reference/ROADMAP.md) | Milestone plan and release-versioning policy |
| [Capsule System — M7.1](docs/reference/M7.1.md) | Capsule birth protocol |
| [Word-level ACL](docs/reference/word-acl/DESIGN.md) | The access-control design |
| [HAL, as built](kernel/src/hal/README.md) | Hardware abstraction layer |
| [Developer guide / Kconfig reference](docs/working/architecture/getting-started/DEVELOPER.md#build-configuration-kconfig) | Full symbol reference for both builds |
| [Dead ideas and revised claims](docs/DEAD-AND-REVISED.md) | What is no longer true, and since when |
| [Changelog](CHANGELOG.md) | Milestone-level history |
| [Roadmap](docs/reference/ROADMAP.md) | Milestone plan through self-hosting |
---