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 ok prompt 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

3.4 KiB Raw Blame History