# LithosAnanke — StarForth Kernel Branch

**Branch:** `lithosananke`
**Status:** M7 Complete (VM Parity Validation)
**Parent:** `master` (hosted StarForth)

---

## 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 | Init Capsule Architecture | Design Complete |
| M8 | REPL + Interactive Forth | Planned |
| M9 | Block Storage | Planned |

---

## Build & Run

```bash
# Build kernel with VM integration
make -f Makefile.starkernel ARCH=amd64 STARFORTH_ENABLE_VM=1

# Run in QEMU
make -f Makefile.starkernel ARCH=amd64 STARFORTH_ENABLE_VM=1 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 lithosananke branch is experimental. Changes should:

1. Maintain parity validation (M7 baseline)
2. Pass QEMU boot test
3. Not break hosted StarForth (master branch)

---

## 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)