Robert Allan JamesandClaude Sonnet 5
8e2c5dae5f
Not implementation -- documentation-only. M8 is tracked outside Stadium (FABRIC.md §27.5), so this scoping lives in docs/lithosananke/ROADMAP.md rather than as new FABRIC.md 4.3.x items. Read the code before scoping, not assumed: the REPL already works interactively over serial (sk_repl_run(), repl.c) with working backspace/echo, and its on-screen text already renders via the existing VT100 console (vt100_init()/font_8x16.c) independent of both the stroke font and TrueType work -- neither was ever a REPL-strip prerequisite. What's actually missing: sk_readline()'s console_getc() is serial-UART-only, never touches KEY-EVENT (4.3.5f); KEY/?TERMINAL (io_words.c) are dead stubs (KEY calls a getchar() hardcoded to EOF in shim.c, ?TERMINAL always returns false). Resolved design decisions: minimal US-QWERTY scancode->ASCII layout with shift-state tracking (KEY-EVENT carries no modifier state today); merge keyboard into console_getc()'s poll with serial staying a co-equal source, not replaced (the entire acceptance/DoE harness injects over the serial socket -- breaking that breaks make qemu, DOE_INJECT, and every screendump technique used throughout 4.3.x); wire KEY/?TERMINAL to the same merged source for FORTH-79 compliance; CANVAS viewport sizing last, since it's presentation not input plumbing. Extended scancodes, autorepeat-as-character-repeat, arrow-key history explicitly out of scope for the "minimal" bar. FABRIC.md's existing "not yet scoped" notes (4.3.5f's landing-point note, 4.3.7f's closing note) updated to point here rather than duplicating the design content. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
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
# 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 loaderbuild/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 lithosananke branch is experimental. Changes should:
- Maintain parity validation (M7 baseline)
- Pass QEMU boot test
- Not break hosted StarForth (master branch)
References
- StarForth README — Main project
- FORTH-79 Standard
- OSDev Wiki
- UEFI Specification