rajamesandClaude Opus 5.5
7aed588f78
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>
79 lines
3.4 KiB
Markdown
79 lines
3.4 KiB
Markdown
<!-- Moved from docs/working/archive/superseded/2026-08-tripod/03-architecture-README.md to docs/working/architecture/03-architecture/README.md on 2026-06-16 (docs reorg Phase 2) -->
|
|
# Architecture
|
|
|
|
This directory contains system architecture documentation for StarForth's core subsystems and the path to StarKernel and StarshipOS.
|
|
|
|
## Subsystems
|
|
|
|
- **[hal/](hal/)** - Hardware Abstraction Layer (enables StarForth → StarKernel → StarshipOS)
|
|
- **[heartbeat-system/](heartbeat-system/)** - Centralized time-based tuning coordinator
|
|
- **[physics-engine/](physics-engine/)** - Physics-driven adaptive runtime
|
|
- **[pipelining/](pipelining/)** - Speculative execution via word transition prediction
|
|
- **[adaptive-systems/](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
|
|
|
|
1. **VM Core** (`src/vm.c`) - FORTH-79 interpreter loop, stacks, dictionary
|
|
2. **Physics Subsystems** - Execution heat, rolling window, hot-words cache, pipelining
|
|
3. **Heartbeat System** - Time-driven tuning coordinator (Loop #3 + Loop #5)
|
|
4. **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` |