Architecture
This directory contains system architecture documentation for StarForth's core subsystems and the path to StarKernel and StarshipOS.
Subsystems
- hal/ - Hardware Abstraction Layer (enables StarForth → StarKernel → StarshipOS)
- heartbeat-system/ - Centralized time-based tuning coordinator
- physics-engine/ - Physics-driven adaptive runtime
- pipelining/ - Speculative execution via word transition prediction
- adaptive-systems/ - Window inference and decay algorithms
Architecture Overview
StarForth's architecture consists of three layers:
┌──────────────────────────────────────┐
│ StarForth VM + Physics Subsystems │ ← Platform-agnostic
├──────────────────────────────────────┤
│ HAL (Hardware Abstraction Layer) │ ← Clean interfaces
├──────────────────────────────────────┤
│ Platform Implementation │ ← Linux | Kernel
└──────────────────────────────────────┘
Core Components
- VM Core (
src/vm.c) - FORTH-79 interpreter loop, stacks, dictionary - Physics Subsystems - Execution heat, rolling window, hot-words cache, pipelining
- Heartbeat System - Time-driven tuning coordinator (Loop #3 + Loop #5)
- HAL - Platform abstraction enabling portability
Key Innovation
Physics-grounded self-adaptive runtime with formally proven deterministic behavior:
- 0% algorithmic variance across 90 experimental runs
- Execution heat tracking drives dictionary optimization
- Rolling window of truth captures execution history
- Inference engine adapts window width and decay slope
Roadmap: StarForth → StarKernel → StarshipOS
Phase 1: StarForth VM ✅ COMPLETE
- FORTH-79 compliant interpreter
- Physics-driven adaptive runtime
- Runs on Linux, bare metal (HISTORICAL: also L4Re, through mid-2026; removed as an active target)
Phase 2: HAL Migration 🔄 IN PROGRESS
- Introduce Hardware Abstraction Layer
- Refactor VM to use HAL interfaces
- Preserve deterministic behavior guarantees
Phase 3: StarKernel 📋 PLANNED
- UEFI bootable kernel
- Freestanding C environment
- Forth as native control plane
- Boot to
okprompt on bare metal
Phase 4: StarshipOS 🔮 FUTURE
- Full operating system
- Storage, networking, device drivers
- Process model (Forth tasks)
- Self-hosting development environment
See hal/starkernel-integration.md for the detailed path to StarKernel.
Key Documents
- System Ontology:
../ONTOLOGY.md - Computational Framework:
../COMPUTATIONAL_PHYSICS_FRAMEWORK.md - Feedback Loops:
physics-engine/feedback-loops.md
For Developers
- Adding a new subsystem: Follow the pattern in
hal/(include README, overview, implementation guide) - Understanding interactions: See physics-engine/ for how subsystems coordinate via heartbeat
- Platform porting: See
hal/platform-implementations.md