rajames
2e6262c91f
- docs/lithosananke/README.md + ROADMAP.md: correct branch topology (no lithosananke branch post-split; master is the sole line), mark M7.1 as live, and fix build commands (kernel/Makefile, not Makefile.starkernel) - docs/README.md: refresh current active work (Tripod = Hera/Artemis/Hestia, M7.1 live, StarForth v4) and flag INDEX.md as stale - docs/INDEX.md: add dated-snapshot staleness banner - Add TARGET-HAL / OBSOLETE / SUPERSEDED banners to stale HAL, physics, heartbeat, and DoE docs under docs/working/ (annotation only, no deletions)
196 lines
8.2 KiB
Markdown
196 lines
8.2 KiB
Markdown
# 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)
|