# LithosAnanke — StarForth Kernel Branch > **⚠ PARTIALLY STALE (flagged 2026-10-09).** This page predates the repo split and the > Tripod/kernel reshuffle. There is no `lithosananke` branch in this repo — `master` is the > sole production line — and the VM fleet is now **Hera / Artemis / Hestia** (the Hermes VM > was removed; messaging moved into the kernel as kernel-Hermes). M7.1 is **live**, not > merely designed. For authoritative status see `.claude/CLAUDE.md` and > `docs/fabric/FABRIC-2.md` / `FABRIC-3.md` / `FABRIC-3.5.md` / `FABRIC-3.6.md`; for the > milestone plan see `ROADMAP.md` (this file is an orientation page). **Line:** `master` (sole production line post-split) **Status:** M7 Complete (VM Parity) · M7.1 Live (capsules, Tripod, Stadium, word-level ACL Phases 1–7) --- ## What is LithosAnanke? LithosAnanke is the kernel branch of StarForth — a UEFI-bootable microkernel with the StarForth VM as its native execution engine. **Etymology:** *Lithos* (stone/foundation) + *Ananke* (necessity/inevitability) The name reflects the project's nature: a necessary foundation for StarshipOS. --- ## Architecture ``` ┌─────────────────────────────────────────────────────────────┐ │ UEFI Firmware │ │ • ExitBootServices → handoff to kernel │ └─────────────────────┬───────────────────────────────────────┘ │ ↓ ┌─────────────────────────────────────────────────────────────┐ │ LithosAnanke Boot (M0) │ │ • UEFI loader collects BootInfo │ │ • Memory map, ACPI tables, framebuffer │ └─────────────────────┬───────────────────────────────────────┘ │ ↓ ┌─────────────────────────────────────────────────────────────┐ │ LithosAnanke HAL (M1-M6) │ │ • PMM: Physical Memory Manager (bitmap) │ │ • VMM: Virtual Memory Manager (4-level paging) │ │ • IDT: Interrupt Descriptor Table │ │ • APIC: Timer + IRQ routing │ │ • Heap: kmalloc/kfree │ │ • Console: Serial UART │ └─────────────────────┬───────────────────────────────────────┘ │ ↓ ┌─────────────────────────────────────────────────────────────┐ │ StarForth VM (M7+) │ │ • 295 FORTH-79 words │ │ • Parity validation (hash=0x684bbf2fa1d96d55) │ │ • Physics-driven adaptive runtime │ │ • Init capsule system (M7.1) │ └─────────────────────────────────────────────────────────────┘ ``` --- ## Current Milestones | Milestone | Description | Status | |-----------|-------------|--------| | M0 | UEFI Boot + Serial Output | Complete | | M1 | Physical Memory Manager | Complete | | M2 | Virtual Memory Manager | Complete | | M3 | IDT + Interrupts | Complete | | M4 | APIC Timer | Complete | | M5 | Timer Calibration | Complete | | M6 | Kernel Heap | Complete | | **M7** | **VM Parity Validation** | **Complete** | | **M7.1** | **Capsules · Tripod · Stadium · ACL** | **Live** (see FABRIC docs) | | M8 | REPL (keyboard input) | Superseded — see FABRIC-0 §25.5 item 4.4 | | M9 | Block Storage / Block I/O | Live (virtio-blk + block subsystem) | --- ## Build & Run ```bash # Build kernel with VM integration (loader + kernel) make -f kernel/Makefile ARCH=amd64 STARFORTH_ENABLE_VM=1 # Run in QEMU make -f kernel/Makefile ARCH=amd64 STARFORTH_ENABLE_VM=1 qemu # Other architectures make -f kernel/Makefile ARCH=aarch64 qemu make -f kernel/Makefile ARCH=riscv64 qemu ``` **Output artifacts:** - `build/amd64/kernel/starkernel_loader.efi` — UEFI loader - `build/amd64/kernel/starkernel_kernel.elf` — Kernel binary --- ## Documentation ### Core Design | Document | Description | |----------|-------------| | [M7.1.md](M7.1.md) | Init Capsule Architecture | | [ROADMAP.md](ROADMAP.md) | Milestone roadmap | | [amd64-isr-fix/README.md](amd64-isr-fix/README.md) | APIC timer ISR fix + kernel 3-arch acceptance test | | [hosted-acceptance-test/README.md](hosted-acceptance-test/README.md) | Hosted VM 3-arch acceptance test (amd64 native, aarch64/riscv64 under QEMU user-mode) | ### HAL (Hardware Abstraction Layer) | Document | Description | |----------|-------------| | [hal/overview.md](hal/overview.md) | HAL architecture and principles | | [hal/interfaces.md](hal/interfaces.md) | HAL interface specifications | | [hal/lithosananke-integration.md](hal/lithosananke-integration.md) | Kernel-specific HAL implementation | | [hal/platform-implementations.md](hal/platform-implementations.md) | Platform implementation guide | | [hal/migration-plan.md](hal/migration-plan.md) | Migration from hosted to kernel | --- ## Key Concepts ### One Truth Per VM Every VM has exactly one birth capsule — its identity and provenance. ``` PARITY:BIRTH vm_id=42 capsule_id=0xA13F mode=p capsule_hash=0x... dict_hash=0x... ``` ### DOMAIN vs PERSONALITY **DOMAIN** is a construction concept that exists **only in Mama FORTH**. It's how Mama classifies, composes, and selects capsules. DOMAIN is never visible to baby VMs. **PERSONALITY** is the result of executing a production `(p)` INIT capsule. It's what the baby VM *is* — its vocabulary, invariants, capabilities. PERSONALITY is immutable and defines the VM's entire worldview. ### Production (p) vs Experiment (e) - **(p) capsules** are truth-bearing — they can birth VMs - **(e) capsules** are Mama-only workloads — experiments that never touch babies A baby VM never sees, executes, or knows about (e) capsules. ### Content-Addressed Capsules Capsules are identified by content hash, not names. Names lie. Hashes don't. ### Mama FORTH The root VM that holds all truths, manages child VMs, and enforces the birth protocol. Mama: - Maintains the capsule directory - Selects (p) capsules for birth - Executes (e) capsules for experimentation - Logs all births and runs for provenance --- ## Directory Structure ``` src/starkernel/ ├── boot/ # UEFI loader, ELF loader ├── hal/ # Console, host services ├── memory/ # PMM, VMM, kmalloc ├── arch/amd64/ # x86_64 specific (APIC, IDT, timer) ├── vm/ # VM integration │ ├── arena.c # VM memory arena │ ├── parity.c # Parity validation │ ├── bootstrap/ # sk_vm_bootstrap │ └── host/ # Host services shim └── kernel_main.c # Entry point ``` --- ## Contributing The contributing rules are: 1. Maintain parity validation (M7 baseline) 2. Pass the three-arch QEMU boot test (`ARCH={amd64,aarch64,riscv64}`) 3. Not break the hosted VM build (plain `make` at the repo root) --- ## References - [StarForth README](../../README.md) — Main project - [FORTH-79 Standard](http://www.forth.org/forth-79.html) - [OSDev Wiki](https://wiki.osdev.org/) - [UEFI Specification](https://uefi.org/specifications)