Files

T

rajamesandClaude Opus 5.5 7aed588f78 docs: reorganise -- current reference gathered, finished work archived, superseded and dead ideas marked as such

docs/CLAUDE.md Phase 2, 2026-10-14.  All moves by git mv; every archived
file carries a header saying what it is, why, and where to look instead.

- docs/reference/ (new): roadmap and versioning policy, M7.1, word-ACL
  design, kernel args, hosted acceptance test, dictionary, primitives,
  ontology, L8 table -- previously spread over docs/, docs/lithosananke/
  and docs/03-architecture/.
- docs/working/archive/historical/: finished work (session plan, test-gap
  audit, birthing plan, fix write-ups, the January architecture draft).
- docs/working/archive/superseded/: the Hermes-VM Tripod docs and July
  Hermes designs (-> FABRIC-3.5/3.6), the StarForth roadmap, every working
  doc already flagged superseded or obsolete.
- docs/working/archive/dead/: the hal_* target contract (never adopted),
  L4Re, metrics-and-knobs.
- Papers and proposals into docs/working/papers/.
- References rewritten across the repo (not logs/, not docs/patent/);
  CLAUDE.md's documentation section rewritten.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

2026-10-14 16:03:56 -04:00

3.4 KiB

Raw Blame History

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