LithosAnanake/docs/lithosananke/README.md

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

# 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	Init Capsule Architecture
ROADMAP.md	Milestone roadmap
amd64-isr-fix/README.md	APIC timer ISR fix + kernel 3-arch acceptance test
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 architecture and principles
hal/interfaces.md	HAL interface specifications
hal/lithosananke-integration.md	Kernel-specific HAL implementation
hal/platform-implementations.md	Platform implementation guide
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 — Main project
• FORTH-79 Standard
• OSDev Wiki
• UEFI Specification