Robert Allan JamesandClaude Sonnet 5
f75228dda5
No document like this existed. Covers every core C-primitive FORTH word (~470 registrations, 435 unique names after collapsing double-registered ones) across all 36 src/word_source/*.c files plus src/starkernel/capsule/mama_forth_words.c, organized into 34 category sections matching the module order in register_forth79_words(). Each entry has word name, stack effect, and a one-sentence description pulled from the doc comment above its implementation (or inferred where none existed). Explicitly scoped to core primitives, not the ~330 FORTH-defined words inside .4th capsules -- those track individual experiments/policies rather than the language itself and would need their own document with a different update cadence. Resolved, not just noted, the two real name collisions in the live dictionary: [ ] STATE (dictionary_manipulation_words.c vs. defining_words.c) and MOD /MOD */ */MOD (arithmetic_words.c vs. mixed_arithmetic_words.c) -- checked actual registration order in word_registry.c against the newest-first FIND search to determine which implementation is actually reachable by name, rather than guessing. Includes a "keeping this current" section documenting how to extend it when words are added/removed/re-registered. Also includes BLOCK_MAP.md/artemis.img/amd64.csv regenerated by builds during this session, and a qemu boot log/DoE run that weren't from any command in this session -- kept per repo convention, logs are audit artifacts, not deleted. 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