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>
This commit is contained in:
rajames
co-authored by
Claude Opus 5.5
Claude Opus 5.5
parent
1a4b163861
commit
7aed588f78
@@ -1,4 +1,4 @@
|
||||
<!-- Moved from docs/03-architecture/README.md to docs/working/architecture/03-architecture/README.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
<!-- 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.
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
<!-- Moved from docs/03-architecture/word-acl/DESIGN.md to docs/working/architecture/03-architecture/word-acl/DESIGN.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
<!-- Moved from docs/reference/word-acl/DESIGN.md to docs/working/architecture/03-architecture/word-acl/DESIGN.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
# Word-Level ACL System
|
||||
|
||||
**Status:** Implemented through Phase 6 — Phase 7 (LithosAnanke parity) remaining
|
||||
|
||||
@@ -34,7 +34,7 @@ source material that `docs/formal/scraps/architecture/` is generated from.
|
||||
|
||||
## See also
|
||||
|
||||
- [`docs/03-architecture/README.md`](../../03-architecture/README.md) — the
|
||||
- [`docs/working/archive/superseded/2026-08-tripod/03-architecture-README.md`](../../03-architecture/README.md) — the
|
||||
*binding-constraint* Tripod/ACL docs, distinct from this design-notes tree.
|
||||
- [`docs/formal/scraps/README.md`](../../formal/scraps/README.md) — the
|
||||
press-ready fragment tier this material feeds.
|
||||
|
||||
@@ -148,7 +148,7 @@ This directory contains experimental designs, execution guides, and results for
|
||||
- Results for publication: `06-research/results-for-publication.md`
|
||||
```
|
||||
|
||||
#### `docs/03-architecture/README.md`
|
||||
#### `docs/working/archive/superseded/2026-08-tripod/03-architecture-README.md`
|
||||
```markdown
|
||||
# Architecture
|
||||
|
||||
@@ -427,7 +427,7 @@ This document provides **kernel-specific implementation details**...
|
||||
|
||||
#### Incomplete Documents
|
||||
|
||||
**`docs/ONTOLOGY.md`:**
|
||||
**`docs/reference/ONTOLOGY.md`:**
|
||||
- Appears to be high-level conceptual framework
|
||||
- Could benefit from linking to specific implementation docs
|
||||
- Should reference HAL as part of platform layer
|
||||
@@ -510,7 +510,7 @@ The `archive/` directory preserves historical context without cluttering active
|
||||
- Mention StarKernel/StarshipOS vision
|
||||
- **Effort:** 15 minutes
|
||||
|
||||
4. **Create `docs/03-architecture/README.md`**
|
||||
4. **Create `docs/working/archive/superseded/2026-08-tripod/03-architecture-README.md`**
|
||||
- Big picture of how subsystems fit together
|
||||
- Roadmap (StarForth → StarKernel → StarshipOS)
|
||||
- **Effort:** 1 hour
|
||||
@@ -581,7 +581,7 @@ The `archive/` directory preserves historical context without cluttering active
|
||||
1. Create 6 missing README files for numbered directories
|
||||
2. Update `docs/CLAUDE.md` with HAL section
|
||||
3. Update `docs/README.md` with current work
|
||||
4. Create `docs/03-architecture/README.md`
|
||||
4. Create `docs/working/archive/superseded/2026-08-tripod/03-architecture-README.md`
|
||||
|
||||
### Short-term Actions (1-2 weeks)
|
||||
|
||||
|
||||
+4
-1
@@ -1,4 +1,7 @@
|
||||
<!-- Moved from docs/03-architecture/hal/README.md to docs/working/architecture/03-architecture/hal/README.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
> **DEAD (docs triage 2026-10-14).** The proposed `hal_*` interface contract and its migration plan were never adopted; the kernel grew its own HAL (kernel/src/hal/, kernel/include/starkernel/hal/).
|
||||
> Instead: kernel/src/hal/README.md. Moved here from `docs/working/architecture/03-architecture/hal/README.md`.
|
||||
|
||||
<!-- Moved from docs/03-architecture/hal/README.md to docs/working/archive/dead/hal-target-contract/README.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
|
||||
> **⚠ TARGET HAL — NOT THE BUILT INTERFACE (flagged 2026-10-09).** This document family
|
||||
> describes a proposed `hal_*`-named interface and a `src/platform/<platform>/` layout that
|
||||
+4
-1
@@ -1,4 +1,7 @@
|
||||
<!-- Moved from docs/03-architecture/hal/interfaces.md to docs/working/architecture/03-architecture/hal/interfaces.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
> **DEAD (docs triage 2026-10-14).** The proposed `hal_*` interface contract and its migration plan were never adopted; the kernel grew its own HAL (kernel/src/hal/, kernel/include/starkernel/hal/).
|
||||
> Instead: kernel/src/hal/README.md. Moved here from `docs/working/architecture/03-architecture/hal/interfaces.md`.
|
||||
|
||||
<!-- Moved from docs/03-architecture/hal/interfaces.md to docs/working/archive/dead/hal-target-contract/interfaces.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
|
||||
> **⚠ TARGET HAL — NOT THE BUILT INTERFACE (flagged 2026-10-09).** This document defines the
|
||||
> proposed `hal_*` interface contract; it was never adopted as written. The implemented kernel
|
||||
+4
-1
@@ -1,4 +1,7 @@
|
||||
<!-- Moved from docs/03-architecture/hal/migration-plan.md to docs/working/architecture/03-architecture/hal/migration-plan.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
> **DEAD (docs triage 2026-10-14).** The proposed `hal_*` interface contract and its migration plan were never adopted; the kernel grew its own HAL (kernel/src/hal/, kernel/include/starkernel/hal/).
|
||||
> Instead: kernel/src/hal/README.md. Moved here from `docs/working/architecture/03-architecture/hal/migration-plan.md`.
|
||||
|
||||
<!-- Moved from docs/03-architecture/hal/migration-plan.md to docs/working/archive/dead/hal-target-contract/migration-plan.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
|
||||
> **⚠ TARGET HAL — NOT THE BUILT INTERFACE (flagged 2026-10-09).** This migration plan targets
|
||||
> the proposed `hal_*` interface, which was never adopted as written. The kernel grew its own
|
||||
+4
-1
@@ -1,4 +1,7 @@
|
||||
<!-- Moved from docs/03-architecture/hal/overview.md to docs/working/architecture/03-architecture/hal/overview.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
> **DEAD (docs triage 2026-10-14).** The proposed `hal_*` interface contract and its migration plan were never adopted; the kernel grew its own HAL (kernel/src/hal/, kernel/include/starkernel/hal/).
|
||||
> Instead: kernel/src/hal/README.md. Moved here from `docs/working/architecture/03-architecture/hal/overview.md`.
|
||||
|
||||
<!-- Moved from docs/03-architecture/hal/overview.md to docs/working/archive/dead/hal-target-contract/overview.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
# Hardware Abstraction Layer (HAL) Architecture
|
||||
|
||||
> **⚠️ Important Note**: This document describes the **target HAL architecture** with standardized `hal_*` function naming. The current codebase uses `sf_time_backend_t` and similar abstractions with different naming conventions. See [migration-plan.md](migration-plan.md) for the refactoring steps to migrate existing platform code to the HAL interfaces described here.
|
||||
+4
-1
@@ -1,4 +1,7 @@
|
||||
<!-- Moved from docs/03-architecture/hal/platform-implementations.md to docs/working/architecture/03-architecture/hal/platform-implementations.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
> **DEAD (docs triage 2026-10-14).** The proposed `hal_*` interface contract and its migration plan were never adopted; the kernel grew its own HAL (kernel/src/hal/, kernel/include/starkernel/hal/).
|
||||
> Instead: kernel/src/hal/README.md. Moved here from `docs/working/architecture/03-architecture/hal/platform-implementations.md`.
|
||||
|
||||
<!-- Moved from docs/03-architecture/hal/platform-implementations.md to docs/working/archive/dead/hal-target-contract/platform-implementations.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
|
||||
> **⚠ OBSOLETE (flagged 2026-10-09).** Assumes a `src/platform/<platform>/hal_*.c` layout
|
||||
> whose platform names ("Linux", "L4Re", "StarKernel") and interface never matched the built
|
||||
+4
-1
@@ -1,4 +1,7 @@
|
||||
<!-- Moved from docs/03-architecture/hal/starkernel-integration.md to docs/working/architecture/03-architecture/hal/starkernel-integration.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
> **DEAD (docs triage 2026-10-14).** The proposed `hal_*` interface contract and its migration plan were never adopted; the kernel grew its own HAL (kernel/src/hal/, kernel/include/starkernel/hal/).
|
||||
> Instead: kernel/src/hal/README.md. Moved here from `docs/working/architecture/03-architecture/hal/starkernel-integration.md`.
|
||||
|
||||
<!-- Moved from docs/03-architecture/hal/starkernel-integration.md to docs/working/archive/dead/hal-target-contract/starkernel-integration.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
|
||||
> **⚠ OBSOLETE (flagged 2026-10-09).** Describes implementing `src/platform/kernel/` and a
|
||||
> "Milestone 1: Boot + Serial Output" starting point. True architecture is far ahead: the
|
||||
+2
@@ -1,3 +1,5 @@
|
||||
// DEAD (docs triage 2026-10-14). L4Re/Fiasco.OC was removed as a platform target in mid-2026. Instead: .claude/CLAUDE.md (Project Overview). Moved from docs/working/hardware/platform-integration/L4RE_DICTIONARY_ALLOCATION.adoc.
|
||||
|
||||
// Moved from docs/src/platform-integration/L4RE_DICTIONARY_ALLOCATION.adoc to docs/working/scratch/src/platform-integration/L4RE_DICTIONARY_ALLOCATION.adoc on 2026-06-16 (docs reorg Phase 2)
|
||||
== Dictionary Allocation Strategy for L4Re
|
||||
:toc: left
|
||||
+2
@@ -1,3 +1,5 @@
|
||||
// DEAD (docs triage 2026-10-14). L4Re/Fiasco.OC was removed as a platform target in mid-2026. Instead: .claude/CLAUDE.md (Project Overview). Moved from docs/working/hardware/platform-integration/L4RE_INTEGRATION.adoc.
|
||||
|
||||
// Moved from docs/src/platform-integration/L4RE_INTEGRATION.adoc to docs/working/scratch/src/platform-integration/L4RE_INTEGRATION.adoc on 2026-06-16 (docs reorg Phase 2)
|
||||
== StarForth L4Re Integration Guide
|
||||
:toc: left
|
||||
+3
-1
@@ -1,4 +1,6 @@
|
||||
// Moved from docs/src/L4RE_INTEGRATION_TODO.adoc to docs/working/scratch/src/L4RE_INTEGRATION_TODO.adoc on 2026-06-16 (docs reorg Phase 2)
|
||||
// DEAD (docs triage 2026-10-14). L4Re/Fiasco.OC was removed as a platform target in mid-2026. Instead: .claude/CLAUDE.md (Project Overview). Moved from docs/working/scratch/src/L4RE_INTEGRATION_TODO.adoc.
|
||||
|
||||
// Moved from docs/src/L4RE_INTEGRATION_TODO.adoc to docs/working/archive/dead/l4re/L4RE_INTEGRATION_TODO.adoc on 2026-06-16 (docs reorg Phase 2)
|
||||
== L4Re Integration TODO
|
||||
:toc: left
|
||||
:toc-title: Contents
|
||||
+2
@@ -1,3 +1,5 @@
|
||||
// DEAD (docs triage 2026-10-14). L4Re/Fiasco.OC was removed as a platform target in mid-2026. Instead: .claude/CLAUDE.md (Project Overview). Moved from docs/working/hardware/platform-integration/l_4_re_blkio_endpoints.adoc.
|
||||
|
||||
// Moved from docs/src/platform-integration/l_4_re_blkio_endpoints.adoc to docs/working/scratch/src/platform-integration/l_4_re_blkio_endpoints.adoc on 2026-06-16 (docs reorg Phase 2)
|
||||
== StarForth Block I/O — L4Re Porting Endpoints
|
||||
:toc: left
|
||||
+4
-1
@@ -1,4 +1,7 @@
|
||||
<!-- Moved from docs/03-architecture/physics-engine/metrics-and-knobs.md to docs/working/architecture/03-architecture/physics-engine/metrics-and-knobs.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
> **DEAD (docs triage 2026-10-14).** Already marked dead in its own header.
|
||||
> Instead: its own header. Moved here from `docs/working/architecture/03-architecture/physics-engine/metrics-and-knobs.md`.
|
||||
|
||||
<!-- Moved from docs/03-architecture/physics-engine/metrics-and-knobs.md to docs/working/archive/dead/metrics-and-knobs.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
# StarForth Metrics & Knobs: GAPS ONLY
|
||||
|
||||
## What's NOT Wired (Things to Add)
|
||||
@@ -0,0 +1,981 @@
|
||||
> **HISTORICAL (docs triage 2026-10-14).** Draft 0.1 of the system vision ("everything is a VM, everything is a capsule"), 2026-01-27; the design that was built is recorded in the FABRIC documents.
|
||||
> Instead: docs/fabric/ (FABRIC-3.5.md for the Tripod and kernel-Hermes, FABRIC-3.md for bare metal). Moved here from `docs/lithosananke/SYSTEM_ARCHITECTURE.md`.
|
||||
|
||||
# LithosAnanke System Architecture
|
||||
|
||||
**Version**: 0.1 (Draft)
|
||||
**Date**: 2026-01-27
|
||||
**Status**: Architectural Design
|
||||
|
||||
---
|
||||
|
||||
## 1. EXECUTIVE SUMMARY
|
||||
|
||||
LithosAnanke is a microkernel-style operating system where all system services run as isolated Virtual Machines (VMs) communicating exclusively through message passing. User identity is tied to physical media (thumbdrives), with cryptographically signed capability grants enforced at VM birth.
|
||||
|
||||
**Core Principles:**
|
||||
- Everything is a VM, everything is a capsule
|
||||
- All communication through messaging backbone (no exceptions)
|
||||
- All storage through block I/O VM (no exceptions)
|
||||
- Physical possession = authentication
|
||||
- Cryptographic signing = capability enforcement
|
||||
- One admin key, no recovery, no backdoors
|
||||
|
||||
---
|
||||
|
||||
## 2. VM HIERARCHY
|
||||
|
||||
### 2.1 Overview
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Mama VM │
|
||||
│ (births and deaths ONLY) │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
┌─────────────────┼─────────────────┐
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌───────────────────┐ ┌───────────────┐ ┌───────────────────┐
|
||||
│ Messaging VM │ │ Block I/O VM │ │ User Session │
|
||||
│ (all comms) │ │ (all storage)│ │ VMs... │
|
||||
└───────────────────┘ └───────────────┘ └───────────────────┘
|
||||
```
|
||||
|
||||
### 2.2 Mama VM
|
||||
|
||||
**Role:** Root VM, births and deaths other VMs. Nothing else.
|
||||
|
||||
**Responsibilities:**
|
||||
- Execute Mama init capsule at boot
|
||||
- Birth system VMs (Messaging, Block I/O)
|
||||
- Birth user session VMs on thumbdrive insertion
|
||||
- Death user session VMs on thumbdrive removal
|
||||
- Maintain VM registry
|
||||
|
||||
**Does NOT do:**
|
||||
- Message routing (Messaging VM does this)
|
||||
- Block I/O (Block I/O VM does this)
|
||||
- User interaction (User VMs do this)
|
||||
|
||||
**Capsule:** `mama-init.4th` with flag `CAPSULE_FLAG_MAMA_INIT`
|
||||
|
||||
### 2.3 Messaging Backbone VM
|
||||
|
||||
**Role:** All inter-VM communication routes through this VM. No exceptions.
|
||||
|
||||
**Responsibilities:**
|
||||
- Route messages between VMs
|
||||
- Enforce message-level ACLs
|
||||
- Queue messages for sleeping/busy VMs
|
||||
- Handle hardware interrupts (keyboard, USB events)
|
||||
- Notify Mama of hardware events (thumbdrive insertion)
|
||||
|
||||
**Capabilities Required:**
|
||||
- `CAP_ROUTE_MESSAGES` - Can route between any VMs
|
||||
- `CAP_HARDWARE_IRQ` - Can receive hardware interrupts
|
||||
- `CAP_VM_ENUMERATE` - Can query VM registry
|
||||
|
||||
**Capsule:** `messaging.4th` with flag `CAPSULE_FLAG_PRODUCTION`
|
||||
|
||||
### 2.4 Block I/O VM
|
||||
|
||||
**Role:** All storage access routes through this VM. No exceptions.
|
||||
|
||||
**Responsibilities:**
|
||||
- Physical block I/O to all storage devices
|
||||
- Map user virtual blocks to physical blocks
|
||||
- Enforce block-level ACLs
|
||||
- Manage Block Allocation Maps (BAM)
|
||||
- Handle storage device hotplug
|
||||
|
||||
**Capabilities Required:**
|
||||
- `CAP_BLOCK_PHYSICAL` - Direct hardware access to storage
|
||||
- `CAP_BLOCK_MAP` - Can create/modify block mappings
|
||||
- `CAP_ACL_ENFORCE` - Can check ACLs on block operations
|
||||
|
||||
**Capsule:** `block-io.4th` with flag `CAPSULE_FLAG_PRODUCTION`
|
||||
|
||||
### 2.5 User Session VMs
|
||||
|
||||
**Role:** Isolated user environment with REPL.
|
||||
|
||||
**Created when:** User inserts authenticated thumbdrive
|
||||
|
||||
**Destroyed when:** Thumbdrive removed or user executes BYE
|
||||
|
||||
**Each user session gets:**
|
||||
- Own VM instance
|
||||
- Own heap (memory arena)
|
||||
- Own RAM blocks (0-2047)
|
||||
- Own disk blocks mapped to thumbdrive (2048+)
|
||||
- Capabilities as granted by signed capability block
|
||||
|
||||
**Capsule:** `user-shell.4th` or user-specified custom capsule
|
||||
|
||||
---
|
||||
|
||||
## 3. BLOCK SUBSYSTEM ARCHITECTURE
|
||||
|
||||
### 3.1 User's Logical View (Deterministic)
|
||||
|
||||
Every user sees the identical logical layout:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Blocks 0-2047: RAM Drive │
|
||||
│ - Fast, volatile working space │
|
||||
│ - 2 MB total (2048 × 1024 bytes) │
|
||||
│ - Cleared on session end │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Blocks 2048+: Physical Storage (Thumbdrive) │
|
||||
│ - Persistent across sessions │
|
||||
│ - User's "home" blocks │
|
||||
│ - Block 2048 typically contains startup script │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Guarantees:**
|
||||
- Blocks 0-2047 are ALWAYS RAM (fast, volatile)
|
||||
- Blocks 2048+ are ALWAYS physical storage (persistent)
|
||||
- This layout is identical for every user on every machine
|
||||
- User FORTH code is portable (same logical addresses everywhere)
|
||||
|
||||
### 3.2 Physical Storage Layout (Thumbdrive)
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Devblock 0: Volume Header (4 KiB) │
|
||||
│ - Magic, version, geometry │
|
||||
│ - BAM location pointers │
|
||||
│ - Reserved range definitions │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Devblocks 1..B: Physical BAM │
|
||||
│ - 1 bit per 1 KiB block │
|
||||
│ - Tracks allocated/free status │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Devblocks B+1..X: System Region │
|
||||
│ - NOT VISIBLE to user (no logical block maps here) │
|
||||
│ - Identity sector (fingerprint source data) │
|
||||
│ - Signed capability grants │
|
||||
│ - ACL tables (variable size, chained blocks) │
|
||||
│ - Audit log (grows over time) │
|
||||
│ - Startup block pointer │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Devblocks X+1..end: User Block Region │
|
||||
│ - Mapped to user's logical blocks 2048+ │
|
||||
│ - User's FORTH code, data, definitions │
|
||||
│ - Fully under user control (within ACL limits) │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 3.3 Virtual BAM
|
||||
|
||||
Each user session has a **Virtual BAM** that maps only their accessible blocks:
|
||||
|
||||
```
|
||||
User's Virtual BAM Physical Reality
|
||||
───────────────── ─────────────────
|
||||
Block 0 ─────────────────► RAM buffer[0]
|
||||
Block 1 ─────────────────► RAM buffer[1]
|
||||
...
|
||||
Block 2047 ─────────────────► RAM buffer[2047]
|
||||
Block 2048 ─────────────────► Thumbdrive devblock X+1
|
||||
Block 2049 ─────────────────► Thumbdrive devblock X+2
|
||||
...
|
||||
```
|
||||
|
||||
**Key property:** System region devblocks have NO entry in the virtual BAM. From the user's FORTH perspective, they don't exist. No block number maps to them.
|
||||
|
||||
### 3.4 Block I/O Flow
|
||||
|
||||
User VM requests a block read:
|
||||
|
||||
```
|
||||
User VM Messaging VM Block I/O VM
|
||||
│ │ │
|
||||
│ ─── MSG(READ,2048) ───► │ │
|
||||
│ │ ─── MSG(READ) ─────► │
|
||||
│ │ │
|
||||
│ │ ├─ Check ACL
|
||||
│ │ ├─ Map virtual→physical
|
||||
│ │ ├─ Physical I/O
|
||||
│ │ │
|
||||
│ │ ◄─── MSG(DATA) ───── │
|
||||
│ ◄─── MSG(DATA) ──────── │ │
|
||||
│ │ │
|
||||
```
|
||||
|
||||
**No direct hardware access** from user VMs. All I/O is mediated.
|
||||
|
||||
### 3.5 System Region Uses
|
||||
|
||||
The system region (invisible to user) stores variable-size metadata:
|
||||
|
||||
| Data | Size | Notes |
|
||||
|------|------|-------|
|
||||
| Identity sector | ~256 bytes | Source data for fingerprint |
|
||||
| Fingerprint | 32-64 bytes | SHA-256 or SHA-512 hash |
|
||||
| Capability grants | Variable | Signed by admin |
|
||||
| ACL tables | Variable | Block-level permissions |
|
||||
| Group memberships | Variable | For shared access |
|
||||
| Audit log | Grows | Tracks significant events |
|
||||
| Startup pointer | 8 bytes | Which block to LOAD at init |
|
||||
| Custom metadata | Variable | Application-specific |
|
||||
|
||||
**Variable-size data** uses block chaining (existing `prev_block`, `next_block` fields in `blk_meta_t`).
|
||||
|
||||
---
|
||||
|
||||
## 4. USER IDENTITY MODEL
|
||||
|
||||
### 4.1 Physical Capability Model
|
||||
|
||||
**Identity IS the thumbdrive.** No passwords, no usernames.
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ User's Thumbdrive │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Contains: │
|
||||
│ - Identity data → SHA fingerprint │
|
||||
│ - Signed capability grants │
|
||||
│ - User's blocks (code, data) │
|
||||
│ - Startup configuration │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Properties: │
|
||||
│ - Fully portable (works on any LithosAnanke system) │
|
||||
│ - Self-contained (no central user database) │
|
||||
│ - Physical possession = authentication │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 4.2 Fingerprint Generation
|
||||
|
||||
The SHA fingerprint uniquely identifies the user:
|
||||
|
||||
```
|
||||
Fingerprint = SHA-256(identity_sector_data)
|
||||
```
|
||||
|
||||
**Identity sector contents** (stored in system region):
|
||||
- UUID (random, generated at user creation)
|
||||
- Creation timestamp
|
||||
- Optional: hardware serial numbers, user metadata
|
||||
|
||||
**The fingerprint:**
|
||||
- Is computed by the kernel at thumbdrive insertion
|
||||
- Is matched against the signed capability grant
|
||||
- Cannot be forged (would need admin signature)
|
||||
|
||||
### 4.3 Session Lifecycle
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 1. THUMBDRIVE INSERTION │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ • Hardware interrupt → Messaging VM │
|
||||
│ • Messaging VM notifies Mama │
|
||||
│ • Block I/O VM reads system region │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 2. IDENTITY VERIFICATION │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ • Compute SHA fingerprint from identity sector │
|
||||
│ • Read signed capability grant from system region │
|
||||
│ • Verify signature against fused admin public key │
|
||||
│ • If invalid: reject, log attempt, stop │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 3. VM BIRTH │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ • Mama selects base capsule (user-shell or custom) │
|
||||
│ • Mama births new VM │
|
||||
│ • VM allocated: heap, RAM blocks (0-2047) │
|
||||
│ • Disk blocks (2048+) mapped to thumbdrive │
|
||||
│ • Capabilities granted: capsule ∩ signed_grant │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 4. INITIALIZATION │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ • Base capsule executes (defines PERSONALITY) │
|
||||
│ • User's startup block LOADed (e.g., 2048 LOAD) │
|
||||
│ • Custom words, aliases, preferences applied │
|
||||
│ • REPL ready for user input │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 5. ACTIVE SESSION │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ • User interacts via REPL │
|
||||
│ • All I/O through Block I/O VM │
|
||||
│ • All comms through Messaging VM │
|
||||
│ • ACLs enforced on every operation │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 6. SESSION END (thumbdrive removal OR BYE) │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ • Hardware interrupt (removal) or explicit BYE │
|
||||
│ • Messaging VM notifies Mama │
|
||||
│ • Mama deaths the user VM │
|
||||
│ • RAM blocks freed │
|
||||
│ • Heap freed │
|
||||
│ • Block mappings removed │
|
||||
│ • Session over, no trace remains │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 4.4 User Startup Customization
|
||||
|
||||
Users can customize their environment like `.bashrc`:
|
||||
|
||||
```forth
|
||||
\ Block 2048 - User's startup script (example)
|
||||
|
||||
\ Load my personal library
|
||||
2049 LOAD
|
||||
|
||||
\ Define aliases
|
||||
: LS DIR ;
|
||||
: PWD BLK@ . ;
|
||||
|
||||
\ Set preferences
|
||||
DECIMAL
|
||||
64 BASE-DEFAULT !
|
||||
|
||||
\ Greeting
|
||||
." Welcome back, Captain!" CR
|
||||
```
|
||||
|
||||
**Constraints:**
|
||||
- Startup runs AFTER base capsule
|
||||
- Can define words, load blocks, set variables
|
||||
- CANNOT exceed capability grants
|
||||
- CANNOT access blocks outside mapped range
|
||||
- CANNOT send unauthorized messages
|
||||
|
||||
---
|
||||
|
||||
## 5. SECURITY MODEL
|
||||
|
||||
### 5.1 Root of Trust: Admin Fusing
|
||||
|
||||
**One-time, irreversible provisioning:**
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ PROVISIONING MODE (First Boot Only) │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ 1. System detects unprovisioned state │
|
||||
│ 2. Generate Ed25519 keypair │
|
||||
│ • Private key: 32 bytes │
|
||||
│ • Public key: 32 bytes │
|
||||
│ 3. FUSE public key to system │
|
||||
│ • Written to NVRAM/secure storage │
|
||||
│ • Cannot be changed after this │
|
||||
│ 4. Create admin thumbdrive │
|
||||
│ • Private key stored in system region │
|
||||
│ • Root capability grant (all permissions) │
|
||||
│ • Self-signed (bootstrap) │
|
||||
│ 5. Exit provisioning mode FOREVER │
|
||||
│ • Provisioning flag set │
|
||||
│ • Cannot re-enter this mode │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**After fusing:**
|
||||
- Public key is immutable (fused to system)
|
||||
- Private key exists ONLY on admin thumbdrive
|
||||
- No copies, no backups, no recovery mechanism
|
||||
- Lose admin thumbdrive = cannot provision new users
|
||||
|
||||
### 5.2 Admin Thumbdrive
|
||||
|
||||
**The single point of administrative authority:**
|
||||
|
||||
```
|
||||
Admin Thumbdrive (System Region)
|
||||
├── Admin identity sector
|
||||
├── Root capability grant (self-signed at provisioning)
|
||||
├── Private signing key (Ed25519)
|
||||
└── Admin blocks (tools, scripts)
|
||||
|
||||
Admin Capabilities:
|
||||
├── CAP_SIGN_GRANTS - Can sign capability grants
|
||||
├── CAP_CREATE_USERS - Can provision new thumbdrives
|
||||
├── CAP_REVOKE_USERS - Can revoke capabilities
|
||||
├── CAP_SYSTEM_CONFIG - Can modify system settings
|
||||
├── CAP_ALL_BLOCKS - Can access any block
|
||||
└── CAP_* - All capabilities
|
||||
```
|
||||
|
||||
**Admin can:**
|
||||
- Create new user thumbdrives
|
||||
- Sign capability grants
|
||||
- Revoke user capabilities (by not re-signing)
|
||||
- Access any user's blocks (for recovery, audit)
|
||||
- Modify system configuration
|
||||
|
||||
**Admin CANNOT:**
|
||||
- Create another admin (no delegation)
|
||||
- Recover lost admin thumbdrive
|
||||
- Change the fused public key
|
||||
|
||||
### 5.3 Capability Grant Structure
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Capability Grant Block │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Header: │
|
||||
│ Magic: "CPGR" (0x43504752) │
|
||||
│ Version: 1 │
|
||||
│ Grant ID: unique identifier │
|
||||
│ Created: timestamp │
|
||||
│ Expires: timestamp (0 = never) │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Identity: │
|
||||
│ Fingerprint: SHA-256 (32 bytes) │
|
||||
│ Must match computed fingerprint at auth time │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Capabilities (bitmap + parameters): │
|
||||
│ CAP_BLOCK_READ - Can read blocks │
|
||||
│ CAP_BLOCK_WRITE - Can write blocks │
|
||||
│ CAP_BLOCK_RANGE - Allowed block range (start, end) │
|
||||
│ CAP_MSG_SEND - Can send messages │
|
||||
│ CAP_MSG_RECEIVE - Can receive messages │
|
||||
│ CAP_MSG_TARGETS - Allowed message targets (VM list) │
|
||||
│ CAP_CAPSULE_LOAD - Can request capsule loading │
|
||||
│ CAP_CUSTOM_CAPSULE - Can use custom init capsule │
|
||||
│ CAP_GROUP_MEMBER - Group membership list │
|
||||
│ CAP_RESOURCE_QUOTA - CPU, memory, block limits │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Signature: │
|
||||
│ Ed25519 signature over all above fields │
|
||||
│ Signed by admin private key │
|
||||
│ 64 bytes │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 5.4 Capability Verification Flow
|
||||
|
||||
```
|
||||
Thumbdrive inserted
|
||||
│
|
||||
▼
|
||||
┌───────────────────────────────────────┐
|
||||
│ 1. Read identity sector │
|
||||
│ 2. Compute fingerprint = SHA-256(id) │
|
||||
└───────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌───────────────────────────────────────┐
|
||||
│ 3. Read capability grant block │
|
||||
│ 4. Extract grant.fingerprint │
|
||||
│ 5. Compare: computed == grant.fp? │
|
||||
│ NO → Reject (identity mismatch) │
|
||||
└───────────────────────────────────────┘
|
||||
│ YES
|
||||
▼
|
||||
┌───────────────────────────────────────┐
|
||||
│ 6. Extract grant.signature │
|
||||
│ 7. Verify: Ed25519_verify( │
|
||||
│ fused_public_key, │
|
||||
│ grant_data, │
|
||||
│ signature) │
|
||||
│ FAIL → Reject (tampered/forged) │
|
||||
└───────────────────────────────────────┘
|
||||
│ PASS
|
||||
▼
|
||||
┌───────────────────────────────────────┐
|
||||
│ 8. Check expiry timestamp │
|
||||
│ EXPIRED → Reject │
|
||||
└───────────────────────────────────────┘
|
||||
│ VALID
|
||||
▼
|
||||
┌───────────────────────────────────────┐
|
||||
│ 9. Grant capabilities to new VM │
|
||||
│ effective_caps = grant.caps │
|
||||
└───────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 5.5 Capability Enforcement Points
|
||||
|
||||
**At VM Birth:**
|
||||
- Capabilities extracted from signed grant
|
||||
- Stored in VM registry entry
|
||||
- Cannot be modified after birth
|
||||
|
||||
**At Message Send:**
|
||||
- Messaging VM checks: Does sender have CAP_MSG_SEND?
|
||||
- Messaging VM checks: Is target in CAP_MSG_TARGETS?
|
||||
- Reject if not authorized
|
||||
|
||||
**At Block Access:**
|
||||
- Block I/O VM checks: Does requestor have CAP_BLOCK_READ/WRITE?
|
||||
- Block I/O VM checks: Is block in CAP_BLOCK_RANGE?
|
||||
- Reject if not authorized
|
||||
|
||||
**At Capsule Load:**
|
||||
- Mama checks: Does requestor have CAP_CAPSULE_LOAD?
|
||||
- Mama checks: Does requestor have CAP_CUSTOM_CAPSULE (if custom)?
|
||||
- Reject if not authorized
|
||||
|
||||
### 5.6 Effective Capabilities
|
||||
|
||||
Final capabilities are the intersection:
|
||||
|
||||
```
|
||||
effective_caps = capsule.declared ∩ grant.allowed ∩ system.policy
|
||||
```
|
||||
|
||||
**capsule.declared:** What the init capsule requests
|
||||
**grant.allowed:** What the signed grant permits
|
||||
**system.policy:** System-wide limits (optional)
|
||||
|
||||
A user cannot gain capabilities not in their signed grant, even if the capsule requests them.
|
||||
|
||||
### 5.7 Revocation
|
||||
|
||||
**Capability revocation works by:**
|
||||
1. Admin creates new grant with reduced capabilities
|
||||
2. Admin re-signs the grant
|
||||
3. New grant replaces old on thumbdrive
|
||||
4. Next session uses new (reduced) capabilities
|
||||
|
||||
**Immediate revocation:**
|
||||
- Admin can maintain a revocation list
|
||||
- Checked at session start
|
||||
- Fingerprint on revocation list = reject
|
||||
|
||||
**No online revocation checking** - this is a standalone system. Revocation requires physical access to update the thumbdrive or revocation list.
|
||||
|
||||
### 5.8 Attack Surface Analysis
|
||||
|
||||
**Attacks PREVENTED:**
|
||||
|
||||
| Attack | Prevention |
|
||||
|--------|------------|
|
||||
| Password guessing | No passwords exist |
|
||||
| Credential theft | Must steal physical device |
|
||||
| Privilege escalation | Capabilities signed, immutable |
|
||||
| Block range escape | Virtual BAM has no mapping |
|
||||
| Direct hardware access | All I/O through service VMs |
|
||||
| Message spoofing | Source VM verified by Messaging VM |
|
||||
| Capability forging | Ed25519 signature required |
|
||||
| Admin impersonation | Admin private key on single device |
|
||||
| Recovery mode exploit | No recovery mode exists |
|
||||
| Backup compromise | No backups exist |
|
||||
|
||||
**Attacks NOT PREVENTED:**
|
||||
|
||||
| Attack | Notes |
|
||||
|--------|-------|
|
||||
| Physical theft of thumbdrive | Physical security is user's responsibility |
|
||||
| Physical theft of admin drive | Total compromise, must reflash |
|
||||
| Cold boot attack | RAM contents may be recoverable |
|
||||
| Evil maid (hardware tampering) | Outside scope, requires secure boot |
|
||||
| Side channel timing | Not addressed in current design |
|
||||
|
||||
### 5.9 Security Boundaries
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ KERNEL SPACE │
|
||||
│ • Mama VM │
|
||||
│ • VM scheduler │
|
||||
│ • Fused public key │
|
||||
│ • Hardware abstraction │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
│ Capsule-defined boundary
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ PRIVILEGED VM SPACE │
|
||||
│ • Messaging VM (CAP_ROUTE_MESSAGES) │
|
||||
│ • Block I/O VM (CAP_BLOCK_PHYSICAL) │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
│ Capability-checked boundary
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ USER VM SPACE │
|
||||
│ • User session VMs │
|
||||
│ • Constrained by signed capability grants │
|
||||
│ • Cannot access other user's blocks │
|
||||
│ • Cannot send unauthorized messages │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. MESSAGING BACKBONE
|
||||
|
||||
### 6.1 Message Structure
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Message Header │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ msg_id: uint64 Unique message identifier │
|
||||
│ source_vm: uint32 Sender VM ID │
|
||||
│ target_vm: uint32 Recipient VM ID │
|
||||
│ msg_type: uint16 Message type code │
|
||||
│ flags: uint16 Delivery flags │
|
||||
│ payload_len: uint32 Payload size in bytes │
|
||||
│ timestamp: uint64 Send timestamp (monotonic) │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Message Payload │
|
||||
│ (variable length, message-type specific) │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 6.2 Message Types
|
||||
|
||||
**System Messages:**
|
||||
- `MSG_VM_BIRTH` - Mama→Messaging: new VM created
|
||||
- `MSG_VM_DEATH` - Mama→Messaging: VM terminated
|
||||
- `MSG_HARDWARE_EVENT` - Messaging→Mama: USB insert/remove
|
||||
|
||||
**Block I/O Messages:**
|
||||
- `MSG_BLOCK_READ` - Request block read
|
||||
- `MSG_BLOCK_WRITE` - Request block write
|
||||
- `MSG_BLOCK_DATA` - Block data response
|
||||
- `MSG_BLOCK_ACK` - Write acknowledgment
|
||||
- `MSG_BLOCK_ERROR` - I/O error response
|
||||
|
||||
**User Messages:**
|
||||
- `MSG_USER_DEFINED` - Application-specific messages
|
||||
|
||||
### 6.3 Message Routing
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Messaging VM │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Inbound Queue ──► │ Route │ ──► Per-VM Outbound Queues │
|
||||
│ │ │ ├── Mama Queue │
|
||||
│ │ │ ├── Block I/O Queue │
|
||||
│ │ │ ├── User VM 1 Queue │
|
||||
│ │ │ ├── User VM 2 Queue │
|
||||
│ │ │ └── ... │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Routing Logic: │
|
||||
│ 1. Verify source VM exists and is alive │
|
||||
│ 2. Check source has CAP_MSG_SEND │
|
||||
│ 3. Check target is in source's CAP_MSG_TARGETS │
|
||||
│ 4. Enqueue to target's outbound queue │
|
||||
│ 5. Wake target VM if sleeping │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 6.4 Synchronous vs Asynchronous
|
||||
|
||||
**Asynchronous (default):**
|
||||
- Sender posts message and continues
|
||||
- Message queued for recipient
|
||||
- Response comes as separate message
|
||||
|
||||
**Synchronous (CALL pattern):**
|
||||
- Sender posts message and blocks
|
||||
- Waits for response message
|
||||
- Useful for RPC-style operations (e.g., block read)
|
||||
|
||||
---
|
||||
|
||||
## 7. BOOT SEQUENCE
|
||||
|
||||
### 7.1 Full Boot Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ PHASE 0: Hardware Initialization │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ • UEFI boot │
|
||||
│ • Memory map from firmware │
|
||||
│ • Jump to kernel entry │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ PHASE 1: Kernel Initialization │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ • Console init (serial UART) │
|
||||
│ • PMM init (physical memory manager) │
|
||||
│ • VMM init (virtual memory manager) │
|
||||
│ • Heap init (kernel malloc) │
|
||||
│ • IDT init (interrupt descriptor table) │
|
||||
│ • APIC init (interrupt controller) │
|
||||
│ • Timer init (APIC timer, TSC calibration) │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ PHASE 2: Provisioning Check │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ • Check provisioning flag in NVRAM │
|
||||
│ • If NOT provisioned: enter provisioning mode │
|
||||
│ └── Generate keypair, fuse, create admin drive, exit │
|
||||
│ • If provisioned: load fused public key, continue │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ PHASE 3: Mama VM Creation │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ • Allocate Mama heap │
|
||||
│ • Create Mama VM (VM ID 0) │
|
||||
│ • Load mama-init capsule │
|
||||
│ • Execute Mama init │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ PHASE 4: System VM Birth │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ • Mama births Messaging VM from messaging.4th capsule │
|
||||
│ • Mama births Block I/O VM from block-io.4th capsule │
|
||||
│ • System services now running │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ PHASE 5: Device Enumeration │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ • USB controller initialization │
|
||||
│ • Storage device discovery │
|
||||
│ • Messaging VM registers for hardware events │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ PHASE 6: Ready for Users │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ • System idle, waiting for thumbdrive insertion │
|
||||
│ • Console shows: "Insert thumbdrive to login" │
|
||||
│ • Or admin thumbdrive for administration │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 7.2 Capsule Boot Order
|
||||
|
||||
```
|
||||
Capsule Directory (in kernel or on system storage)
|
||||
├── mama-init.4th ← Loaded first, by kernel
|
||||
├── messaging.4th ← Birthed by Mama, second
|
||||
├── block-io.4th ← Birthed by Mama, third
|
||||
├── user-shell.4th ← Birthed on user login
|
||||
└── (other capsules) ← As needed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. IMPLEMENTATION PRIORITIES
|
||||
|
||||
Based on dependencies:
|
||||
|
||||
### 8.1 Critical Path
|
||||
|
||||
```
|
||||
1. USB Driver (XHCI)
|
||||
└── Need to detect thumbdrives
|
||||
|
||||
2. Block I/O Kernel Port
|
||||
└── Need to read thumbdrive system region
|
||||
|
||||
3. SHA-256 in Kernel
|
||||
└── Need to compute fingerprints
|
||||
|
||||
4. Ed25519 in Kernel
|
||||
└── Need to verify signatures
|
||||
|
||||
5. Messaging Backbone VM
|
||||
└── Need for all inter-VM communication
|
||||
|
||||
6. Block I/O VM
|
||||
└── Need for all storage access
|
||||
|
||||
7. Capability Enforcement
|
||||
└── Need to check grants at every operation
|
||||
|
||||
8. User Session VM
|
||||
└── Finally can have interactive users
|
||||
```
|
||||
|
||||
### 8.2 Estimated Complexity
|
||||
|
||||
| Component | LOC Estimate | Complexity |
|
||||
|-----------|--------------|------------|
|
||||
| XHCI driver | ~2500 | High |
|
||||
| USB mass storage | ~800 | Medium |
|
||||
| Block subsystem port | ~500 | Medium (reuse existing) |
|
||||
| SHA-256 | ~400 | Low (well-known algorithm) |
|
||||
| Ed25519 | ~600 | Medium (or use library) |
|
||||
| Capability grant parser | ~300 | Low |
|
||||
| Messaging VM | ~1000 | Medium |
|
||||
| Block I/O VM | ~800 | Medium |
|
||||
| Capability enforcement | ~500 | Medium |
|
||||
| User session management | ~600 | Medium |
|
||||
| Admin provisioning | ~400 | Medium |
|
||||
|
||||
**Total: ~8,400 LOC** for core security infrastructure
|
||||
|
||||
---
|
||||
|
||||
## 9. DATA STRUCTURES SUMMARY
|
||||
|
||||
### 9.1 VM Registry Entry (Extended)
|
||||
|
||||
```c
|
||||
typedef struct {
|
||||
uint32_t vm_id; // Unique VM identifier
|
||||
uint32_t state; // VMState enum
|
||||
uint64_t birth_capsule_id; // Which capsule birthed this
|
||||
uint64_t birth_timestamp_ns; // When born
|
||||
uint64_t birth_dict_hash; // Dictionary hash at birth
|
||||
|
||||
// Security fields (new)
|
||||
uint8_t fingerprint[32]; // SHA-256 of user identity
|
||||
uint64_t capability_bitmap; // Granted capabilities
|
||||
uint32_t block_range_start; // First allowed block
|
||||
uint32_t block_range_end; // Last allowed block
|
||||
uint32_t msg_target_count; // Number of allowed targets
|
||||
uint32_t msg_targets[16]; // Allowed message target VMs
|
||||
|
||||
// Resource tracking
|
||||
uint64_t heap_base; // VM's heap start
|
||||
uint64_t heap_size; // VM's heap size
|
||||
uint64_t ram_blocks_base; // RAM block allocation
|
||||
|
||||
uint32_t flags;
|
||||
uint32_t reserved;
|
||||
} VMRegistryEntry;
|
||||
```
|
||||
|
||||
### 9.2 Capability Bitmap
|
||||
|
||||
```c
|
||||
// Capability flags
|
||||
#define CAP_BLOCK_READ (1ULL << 0) // Can read blocks
|
||||
#define CAP_BLOCK_WRITE (1ULL << 1) // Can write blocks
|
||||
#define CAP_MSG_SEND (1ULL << 2) // Can send messages
|
||||
#define CAP_MSG_RECEIVE (1ULL << 3) // Can receive messages
|
||||
#define CAP_CAPSULE_LOAD (1ULL << 4) // Can request capsule load
|
||||
#define CAP_CUSTOM_CAPSULE (1ULL << 5) // Can use custom capsule
|
||||
#define CAP_SIGN_GRANTS (1ULL << 6) // Can sign capability grants (admin)
|
||||
#define CAP_CREATE_USERS (1ULL << 7) // Can provision users (admin)
|
||||
#define CAP_REVOKE_USERS (1ULL << 8) // Can revoke capabilities (admin)
|
||||
#define CAP_SYSTEM_CONFIG (1ULL << 9) // Can modify system config (admin)
|
||||
#define CAP_ALL_BLOCKS (1ULL << 10) // Can access any block (admin)
|
||||
#define CAP_HARDWARE_IRQ (1ULL << 11) // Can receive hardware interrupts
|
||||
#define CAP_ROUTE_MESSAGES (1ULL << 12) // Can route messages (messaging VM)
|
||||
#define CAP_BLOCK_PHYSICAL (1ULL << 13) // Direct hardware I/O (block VM)
|
||||
#define CAP_VM_ENUMERATE (1ULL << 14) // Can query VM registry
|
||||
#define CAP_BLOCK_MAP (1ULL << 15) // Can create block mappings
|
||||
#define CAP_ACL_ENFORCE (1ULL << 16) // Can enforce ACLs
|
||||
|
||||
// Convenience
|
||||
#define CAP_USER_DEFAULT (CAP_BLOCK_READ | CAP_BLOCK_WRITE | \
|
||||
CAP_MSG_SEND | CAP_MSG_RECEIVE)
|
||||
#define CAP_ADMIN_ALL (0xFFFFFFFFFFFFFFFFULL)
|
||||
```
|
||||
|
||||
### 9.3 Signed Capability Grant (On-disk)
|
||||
|
||||
```c
|
||||
typedef struct __attribute__((packed)) {
|
||||
// Header (16 bytes)
|
||||
uint32_t magic; // "CPGR" = 0x43504752
|
||||
uint16_t version; // Grant format version
|
||||
uint16_t flags; // Grant flags
|
||||
uint64_t grant_id; // Unique grant identifier
|
||||
|
||||
// Timestamps (16 bytes)
|
||||
uint64_t created_ns; // Creation timestamp
|
||||
uint64_t expires_ns; // Expiry (0 = never)
|
||||
|
||||
// Identity (32 bytes)
|
||||
uint8_t fingerprint[32]; // SHA-256 that must match
|
||||
|
||||
// Capabilities (32 bytes)
|
||||
uint64_t capability_bitmap; // Granted capabilities
|
||||
uint32_t block_range_start; // First allowed block (logical)
|
||||
uint32_t block_range_end; // Last allowed block (logical)
|
||||
uint32_t msg_target_count; // Number of target VMs
|
||||
uint32_t msg_targets[4]; // Allowed targets (expandable)
|
||||
|
||||
// Quotas (16 bytes)
|
||||
uint32_t max_heap_mb; // Maximum heap size
|
||||
uint32_t max_ram_blocks; // Maximum RAM blocks
|
||||
uint32_t max_disk_blocks; // Maximum disk blocks
|
||||
uint32_t reserved;
|
||||
|
||||
// Signature (64 bytes)
|
||||
uint8_t signature[64]; // Ed25519 signature
|
||||
|
||||
} CapabilityGrant; // Total: 176 bytes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. GLOSSARY
|
||||
|
||||
| Term | Definition |
|
||||
|------|------------|
|
||||
| **Mama VM** | Root VM that births and deaths all other VMs |
|
||||
| **Baby VM** | Any VM birthed by Mama |
|
||||
| **Capsule** | Immutable init block sequence defining VM personality |
|
||||
| **PERSONALITY** | VM's immutable identity after birth (from capsule) |
|
||||
| **DOMAIN** | Mama's construction space (never visible to babies) |
|
||||
| **Fingerprint** | SHA-256 hash of identity sector, identifies user |
|
||||
| **Capability Grant** | Signed document specifying user's permissions |
|
||||
| **Fused Key** | Admin public key permanently written at provisioning |
|
||||
| **Virtual BAM** | Per-user block allocation map (subset view) |
|
||||
| **System Region** | Thumbdrive area invisible to user (metadata, ACLs) |
|
||||
| **Admin Thumbdrive** | Single device with signing authority |
|
||||
|
||||
---
|
||||
|
||||
## 11. OPEN QUESTIONS
|
||||
|
||||
1. **Multiple simultaneous users?** Can multiple thumbdrives be inserted at once, with multiple concurrent sessions?
|
||||
|
||||
2. **Shared blocks between users?** Can users share specific blocks with each other? (Would require group capabilities)
|
||||
|
||||
3. **Network authentication?** Future extension for remote login?
|
||||
|
||||
4. **Audit log rotation?** System region audit log grows forever - need rotation policy?
|
||||
|
||||
5. **Capability delegation?** Can a user grant subset of their capabilities to another? (Currently: no)
|
||||
|
||||
6. **Time-limited sessions?** Automatic logout after idle timeout?
|
||||
|
||||
---
|
||||
|
||||
## 12. REVISION HISTORY
|
||||
|
||||
| Version | Date | Changes |
|
||||
|---------|------|---------|
|
||||
| 0.1 | 2026-01-27 | Initial architecture draft |
|
||||
|
||||
---
|
||||
|
||||
**Document Status:** Draft - Pending Review
|
||||
|
||||
**Authors:** Claude (AI Assistant), Robert A. James
|
||||
|
||||
**Next Steps:**
|
||||
1. Review and refine security model
|
||||
2. Prototype USB detection
|
||||
3. Implement Ed25519/SHA-256 in kernel
|
||||
4. Design message format in detail
|
||||
5. Implement Block I/O VM capsule
|
||||
@@ -0,0 +1,228 @@
|
||||
> **HISTORICAL (docs triage 2026-10-14).** A test-coverage audit of StarForth v3.0.3 / LithosAnanke v1.0.8, 2026-06-03; POST has grown since (1052 tests).
|
||||
> Instead: v3/src/test_runner/ and the POST line of any current boot. Moved here from `docs/TEST_GAPS.md`.
|
||||
|
||||
# StarForth Dictionary Test Coverage — Gap Audit
|
||||
**Branch:** `lithosananke` | **StarForth v3.0.3 / LithosAnanke v1.0.8**
|
||||
**Audited:** 2026-06-03
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
| Metric | Count |
|
||||
|--------|-------|
|
||||
| Total registered words | ~230 |
|
||||
| Words with at least one test | ~115 |
|
||||
| Words with **no** test | ~115 |
|
||||
| Test files | 20 |
|
||||
| Untested word categories | 5 (editor, inference, log, physics-diag, q48) |
|
||||
|
||||
Coverage is solid for the foundational FORTH-79 core but has critical holes
|
||||
in control-flow completeness, format output, memory ops, and the S" word
|
||||
just added in v3.0.3.
|
||||
|
||||
---
|
||||
|
||||
## Priority 1 — FORTH-79 Core: Missing Critical Words
|
||||
|
||||
These are standard FORTH-79 words used in virtually all real programs.
|
||||
Missing tests here are compliance failures.
|
||||
|
||||
| Word(s) | Source file | Why critical |
|
||||
|---------|-------------|--------------|
|
||||
| `1+` `1-` `2+` `2-` `2*` `2/` | arithmetic_words.c | Shorthand increment/shift ops; used in almost every program. Arithmetic test only covers `/MOD` variants, not these. |
|
||||
| `I` `J` | control_words.c | Loop index access. Every `DO...LOOP` that reads the index uses `I`; nested loops need `J`. No test at all. |
|
||||
| `EXIT` | control_words.c | Return from word mid-execution. Essential for early-return patterns. No test. |
|
||||
| `LEAVE` | control_words.c | Early exit from `DO...LOOP`. No test. |
|
||||
| `UNLOOP` | control_words.c | Required to clean the return stack before `EXIT` inside a loop. Omitting it is a stack-corruption bug; no test exercises this. |
|
||||
| `AGAIN` | control_words.c | `BEGIN...AGAIN` infinite loop. Common pattern, completely untested. |
|
||||
| `CASE` `OF` `ENDOF` `ENDCASE` | control_words.c | Full `CASE` structure. Entire construct untested. |
|
||||
| `+!` `-!` | memory_words.c | Modify-in-place. The single most common memory idiom in FORTH after `@` and `!`. No test. |
|
||||
| `FILL` `MOVE` `ERASE` | memory_words.c | Bulk memory primitives. Used by string ops, block subsystem, array initialisation. No test. |
|
||||
| `2!` | memory_words.c | Store double/address pair. `2@` is tested; its store partner is not. |
|
||||
|
||||
---
|
||||
|
||||
## Priority 2 — S" (New in v3.0.3) — Urgent
|
||||
|
||||
`S"` was added as a proper IMMEDIATE primitive in this release. It has zero
|
||||
test coverage. Regression risk is high since the implementation is new.
|
||||
|
||||
| Word(s) | Source file | Gap |
|
||||
|---------|-------------|-----|
|
||||
| `S"` | string_words.c | No test for interpret-mode push (c-addr u), compile-mode inline (`(s")` runtime), or use inside a `:` definition. |
|
||||
| `(s")` | string_words.c | Internal runtime for compiled `S"`. Exercised only by compiled `S"` — needs a compile-mode test. |
|
||||
| `BL` | string_words.c | Space-character constant. Trivial but untested; often paired with `S"`. |
|
||||
| `SOURCE` `>IN` | string_words.c | Input stream state. `SOURCE` returns ( c-addr u ); `>IN` is the offset. Both untested. |
|
||||
|
||||
---
|
||||
|
||||
## Priority 3 — Format / Output Words
|
||||
|
||||
`format_words.c` has 19 registered words. Only `.` and `BASE`/`DECIMAL` are
|
||||
touched (from io_words_test.c). The pictured numeric output group is
|
||||
completely dark.
|
||||
|
||||
| Word(s) | Source file | Gap |
|
||||
|---------|-------------|-----|
|
||||
| `HEX` `OCTAL` | format_words.c | Base switching. Used constantly in systems work. No test. |
|
||||
| `.S` | format_words.c | Print entire stack without consuming it. Core debugging primitive. No test. |
|
||||
| `?` | format_words.c | Print cell at address (` @ . `). Heavily used. No test. |
|
||||
| `.R` `U.` `U.R` | format_words.c | Right-justified and unsigned output. No test. |
|
||||
| `D.` `D.R` | format_words.c | Double-number output. No test. |
|
||||
| `<#` `#` `#S` `#>` `HOLD` `SIGN` | format_words.c | Pictured numeric output group. Entire 6-word subsystem untested. |
|
||||
| `DUMP` | format_words.c | Memory hex dump. No test. |
|
||||
|
||||
---
|
||||
|
||||
## Priority 4 — Logical / Comparison Gaps
|
||||
|
||||
logical_words_test.c covers the common cases but misses several FORTH-79 words.
|
||||
|
||||
| Word(s) | Source file | Gap |
|
||||
|---------|-------------|-----|
|
||||
| `0<>` | logical_words.c | Not-equal-to-zero. Symmetric counterpart to `0=`. No test. |
|
||||
| `U<` `U>` | logical_words.c | Unsigned comparison. Critical for address arithmetic and char comparisons. No test. |
|
||||
| `WITHIN` | logical_words.c | Range test. No test. |
|
||||
| `TRUE` `FALSE` | logical_words.c | Boolean constants. Untested (though they're trivially `0` and `-1`). |
|
||||
|
||||
---
|
||||
|
||||
## Priority 5 — Stack Word Gaps
|
||||
|
||||
stack_words_test.c covers DUP DROP SWAP OVER ROT DEPTH PICK ROLL.
|
||||
Two standard words missing:
|
||||
|
||||
| Word(s) | Source file | Gap |
|
||||
|---------|-------------|-----|
|
||||
| `?DUP` | stack_words.c | Conditional dup (dup only if non-zero). Common idiom. No test. |
|
||||
| `-ROT` | stack_words.c | Reverse rotate. Tested implicitly via `ROT` but never directly. |
|
||||
|
||||
---
|
||||
|
||||
## Priority 6 — Double Number Gaps
|
||||
|
||||
double_words_test.c is thorough but misses:
|
||||
|
||||
| Word(s) | Source file | Gap |
|
||||
|---------|-------------|-----|
|
||||
| `S>D` | double_words.c | Convert single to double. The entry point for all `D`-word arithmetic. No test. |
|
||||
| `D2*` `D2/` | double_words.c | Double arithmetic shifts. No test. |
|
||||
| `2>R` `2R>` `2R@` | double_words.c | Double-number return stack. No test. |
|
||||
|
||||
---
|
||||
|
||||
## Priority 7 — Mixed Arithmetic Gap
|
||||
|
||||
| Word(s) | Source file | Gap |
|
||||
|---------|-------------|-----|
|
||||
| `M-` | mixed_arithmetic_words.c | `M+` and `M*` are tested; `M-` is not. |
|
||||
|
||||
---
|
||||
|
||||
## Priority 8 — Compilation / Meta Words
|
||||
|
||||
These are used to build user-defined IMMEDIATE words and to manipulate the
|
||||
dictionary at compile time. None are tested.
|
||||
|
||||
| Word(s) | Source file | Gap |
|
||||
|---------|-------------|-----|
|
||||
| `COMPILE` `[COMPILE]` | defining_words.c | Used to force compilation of words inside IMMEDIATE definitions. No test. |
|
||||
| `[']` | string_words.c | Compile-time version of `'` (tick). Returns XT of next word at compile time. No test. |
|
||||
| `LIT` | defining_words.c | Internal compile-time literal push. No test. |
|
||||
| `STATE` | defining_words.c / dictionary_manipulation_words.c | Dual-registered. Compile/interpret switch. No test. |
|
||||
| `ALIGN` | dictionary_words.c | Align `HERE` to cell boundary. No test. |
|
||||
| `'` (TICK) | dictionary_manipulation_words.c | Fetch execution token of named word. Core of `[']` and `EXECUTE`. No test. |
|
||||
| `LITERAL` `[LITERAL]` | string_words.c | Compile a literal at runtime / inside definitions. Partially touched in io test but no dedicated test. |
|
||||
|
||||
---
|
||||
|
||||
## Priority 9 — Dictionary Traversal Words
|
||||
|
||||
These enable introspection of the dictionary structure. No tests at all.
|
||||
|
||||
| Word(s) | Source file | Gap |
|
||||
|---------|-------------|-----|
|
||||
| `>NAME` `NAME>` | dictionary_manipulation_words.c | Convert between CFA and NFA. No test. |
|
||||
| `>LINK` `LINK>` | dictionary_manipulation_words.c | Navigate dictionary linked list. No test. |
|
||||
| `CFA` `NFA` `LFA` `PFA` | dictionary_manipulation_words.c | Classic field-access words. No test. |
|
||||
| `TRAVERSE` | dictionary_manipulation_words.c | Walk dictionary chain. No test. |
|
||||
| `INTERPRET` | dictionary_manipulation_words.c | The outer interpreter. No test. |
|
||||
|
||||
---
|
||||
|
||||
## Priority 10 — System Words
|
||||
|
||||
| Word(s) | Source file | Gap |
|
||||
|---------|-------------|-----|
|
||||
| `ABORT"` `(ABORT")` | system_words.c | Conditional abort with message. Used in error handling. No test. |
|
||||
| `WORDS` `VLIST` | system_words.c | Dictionary listing. No test. |
|
||||
| `SEE` | system_words.c | Decompiler. No test. |
|
||||
| `COLD` `WARM` | system_words.c | System restart/reinit. No test (understandably risky to test directly). |
|
||||
| `QUIT` | system_words.c | Outer interpreter restart. No test. |
|
||||
|
||||
---
|
||||
|
||||
## Priority 11 — Block Word Gap
|
||||
|
||||
| Word(s) | Source file | Gap |
|
||||
|---------|-------------|-----|
|
||||
| `-->` | block_words.c | Chain-load next block. Used in multi-block definitions. No test. |
|
||||
|
||||
---
|
||||
|
||||
## Priority 12 — Lifecycle / Capsule Words
|
||||
|
||||
Capsule-BIRTH/KILL/PAUSE/RESUME/USE have partial coverage from mama_forth tests
|
||||
but direct functional tests are missing.
|
||||
|
||||
| Word(s) | Source file | Gap |
|
||||
|---------|-------------|-----|
|
||||
| `KILL` `PAUSE` `RESUME` | lifecycle_words_hosted.c | Capsule lifecycle management. No direct test. |
|
||||
| `USE` | lifecycle_words_hosted.c | Switch active VM. No test. |
|
||||
|
||||
---
|
||||
|
||||
## Priority 13 — Entire Untested Categories
|
||||
|
||||
These word groups have **zero test coverage**. Lower urgency than gaps above
|
||||
because they are StarForth-specific extensions (not FORTH-79 compliance),
|
||||
but they should be ticketed.
|
||||
|
||||
| Category | Source file | Word count | Notes |
|
||||
|----------|-------------|------------|-------|
|
||||
| Q48 fixed-point | q48_words.c | 21 | POST unit tests exist for the C layer but no FORTH-word tests |
|
||||
| Inference | inference_words.c | 19 | Physics adaptive engine; complex to test deterministically |
|
||||
| Log words | log_words.c | 7 | LOG-ERROR … LOG-LEVEL@; simple but untested |
|
||||
| Physics diagnostics | physics_diagnostic_words.c | 4 | PHYSICS-WORD-METRICS etc. |
|
||||
| Physics freeze | physics_freeze_words.c | 9 | FREEZE-WORD, HEAT@, etc. |
|
||||
| Physics benchmark | physics_benchmark_words.c | 6 | BENCH-DICT-LOOKUP etc. |
|
||||
| Physics pipelining diag | physics_pipelining_diagnostic_words.c | 6 | PIPELINING-SHOW-STATS etc. |
|
||||
| Editor | editor_words.c | 4 | L, S, SHOW, EDIT — block editor; very low priority |
|
||||
|
||||
---
|
||||
|
||||
## Work Order (suggested sequence)
|
||||
|
||||
```
|
||||
1. [ ] P1a arithmetic_words_test.c — add 1+ 1- 2+ 2- 2* 2/
|
||||
2. [ ] P1b control_words_test.c — add I J EXIT LEAVE UNLOOP AGAIN
|
||||
3. [ ] P1c control_words_test.c — add CASE OF ENDOF ENDCASE
|
||||
4. [ ] P1d memory_words_test.c — add +! -! 2! FILL MOVE ERASE
|
||||
5. [ ] P2 string_words_test.c — add S" (s") BL SOURCE >IN
|
||||
6. [ ] P3a format_words_test.c — new file: HEX OCTAL .S ? .R U. U.R D. D.R
|
||||
7. [ ] P3b format_words_test.c — add <# # #S #> HOLD SIGN DUMP
|
||||
8. [ ] P4 logical_words_test.c — add 0<> U< U> WITHIN TRUE FALSE
|
||||
9. [ ] P5 stack_words_test.c — add ?DUP -ROT
|
||||
10.[ ] P6 double_words_test.c — add S>D D2* D2/ 2>R 2R> 2R@
|
||||
11.[ ] P7 mixed_arithmetic_words_test.c — add M-
|
||||
12.[ ] P8a defining_words_tests.c — add COMPILE [COMPILE] LIT STATE
|
||||
13.[ ] P8b dictionary_manipulation_words_test.c — add ' ['] ALIGN LITERAL
|
||||
14.[ ] P9 dictionary_manipulation_words_test.c — add >NAME NAME> CFA NFA LFA PFA TRAVERSE INTERPRET
|
||||
15.[ ] P10 system_words_test.c — new file: ABORT" WORDS VLIST SEE
|
||||
16.[ ] P11 block_words_test.c — add -->
|
||||
17.[ ] P12 lifecycle capsule tests — add KILL PAUSE RESUME USE
|
||||
18.[ ] P13a q48_words_test.c — new file: all 21 Q48 FORTH words
|
||||
19.[ ] P13b log_words_test.c — new file: LOG-ERROR … LOG-LEVEL@
|
||||
20.[ ] P13c physics words tests — new files as needed
|
||||
```
|
||||
@@ -0,0 +1,218 @@
|
||||
> **HISTORICAL (docs triage 2026-10-14).** A session hand-off plan from 2026-06-10, on the pre-split `lithosananke` branch; every item in it is long done or overtaken.
|
||||
> Instead: .claude/CLAUDE.md and docs/fabric/FABRIC-3.md for current status. Moved here from `docs/NEXT_SESSION.md`.
|
||||
|
||||
# Next Session Plan
|
||||
|
||||
Generated at end of session `cdcb1844` (2026-06-10).
|
||||
Branch at close: `lithosananke` (merged and pushed; all three arches boot to `ok>`)
|
||||
|
||||
---
|
||||
|
||||
## What Was Accomplished This Session
|
||||
|
||||
- Fixed SysV ABI stack alignment bug in `kernel_entry.S` (`sub rax, 8`)
|
||||
- Removed redundant kmalloc stack switch from `kernel_main.c`
|
||||
- Fixed GOT/PE crash in `apply_sgr` — `FB_ANSI_PALETTE` got
|
||||
`__attribute__((visibility("hidden")))` in both `framebuffer.h` and
|
||||
`framebuffer.c`; EXEC-DOE now runs to full completion (160,673 rows)
|
||||
- Added framebuffer host render test (`tools/fbtest.c`) and QEMU screendump
|
||||
(`scripts/qemu_screenshot.sh`) to the amd64 `qemu` target
|
||||
- CLAUDE.md: one-process-at-a-time build rule
|
||||
- Design doc: `docs/reference/kernel-args/DESIGN.md` — UEFI
|
||||
command-line argument system (KernelArgs)
|
||||
|
||||
---
|
||||
|
||||
## Task 0 — Fix doe.4th EXEC regression (do first)
|
||||
|
||||
All three architectures boot to `ok>` but `S" doe.4th" EXEC` fails at
|
||||
runtime with "EXEC: failed: doe.4th" on every arch. Root cause: merge
|
||||
conflict resolution took the remote's self-executing `doe.4th` (480 runs)
|
||||
and `init.4th` (calls `S" doe.4th" EXEC`), but the capsule fails at runtime.
|
||||
`EXEC-DOE` word is also absent (removed from `init.4th` by the remote).
|
||||
|
||||
Investigation starting point:
|
||||
- Check `capsule_exec_init` return path — add diagnostic to distinguish
|
||||
NOT_FOUND vs HASH_MISMATCH vs runtime error
|
||||
- Verify new `doe.4th` block structure (correct block numbers, no undefined words)
|
||||
- Consider restoring `EXEC-DOE` as an alias once doe.4th runs correctly
|
||||
|
||||
---
|
||||
|
||||
## Task 1 — Carry-over acceptance tests (do first, one at a time)
|
||||
|
||||
All three architectures now confirmed on `lithosananke`:
|
||||
amd64 ✓ aarch64 ✓ riscv64 ✓
|
||||
|
||||
These were completed at end of session. No action needed unless a new
|
||||
change is made — then re-run all three before merging.
|
||||
|
||||
```bash
|
||||
make -f Makefile.starkernel ARCH=aarch64 clean qemu
|
||||
make -f Makefile.starkernel ARCH=riscv64 clean qemu
|
||||
```
|
||||
|
||||
Commit logs after each run. Do not proceed to any implementation task
|
||||
until all three architectures have a clean `ok>` log committed.
|
||||
|
||||
---
|
||||
|
||||
## Task 2 — Memory size audit
|
||||
|
||||
Before tuning anything, measure the actual headroom:
|
||||
|
||||
- BSS stack (`g_kernel_stack`): currently 2 MB — log the deepest RSP
|
||||
observed during EXEC-DOE and compare against the stack base
|
||||
- VM data stack / return stack depths — check `vm.h` for current limits
|
||||
- Rolling window buffer (`ROLLING_WINDOW_SIZE=4096`) — verify it isn't
|
||||
being silently truncated under DoE load
|
||||
- `KERNEL_HEAP_SIZE` (2 GB allocated, 1 GB physical in QEMU) — confirm
|
||||
kmalloc never hits the limit during a full DoE run
|
||||
|
||||
There are no hard rules on these sizes; increase freely if headroom is
|
||||
tight. Document findings in `docs/lithosananke/memory-audit.md`.
|
||||
|
||||
---
|
||||
|
||||
## Task 3 — Implement KernelArgs
|
||||
|
||||
Design doc: `docs/reference/kernel-args/DESIGN.md`
|
||||
|
||||
Implementation order (one commit per step):
|
||||
|
||||
1. `include/starkernel/kernel_args.h` — struct + default macros
|
||||
2. `include/starkernel/boot_info_offsets.h` — assembly-visible offsets
|
||||
with `_Static_assert` checks in C
|
||||
3. `include/starkernel/uefi.h` — add `kernel_stack_base`,
|
||||
`kernel_stack_size`, `KernelArgs args` to `BootInfo`
|
||||
4. `include/starkernel/cmdline.h` + `src/starkernel/boot/cmdline.c` —
|
||||
UCS-2→ASCII, tokeniser, parser
|
||||
5. `src/starkernel/boot/uefi_loader.c` — call `cmdline_parse`, allocate
|
||||
dynamic stack via `AllocatePages`
|
||||
6. `src/starkernel/arch/amd64/kernel_entry.S` — dynamic stack switch,
|
||||
fall back to BSS if `kernel_stack_base == 0`
|
||||
7. `src/starkernel/kernel_main.c` — use `args.heap_size`, honour
|
||||
`args.run_doe` and `args.log_level`
|
||||
8. `Makefile.starkernel` — pass `--doe` via OVMF boot entry; remove socat
|
||||
EXEC-DOE injection
|
||||
|
||||
Run all three arch acceptance tests after step 8.
|
||||
|
||||
---
|
||||
|
||||
## Task 4 — ISO real-hardware boot audit
|
||||
|
||||
The ISO built by xorriso works in QEMU but has a known gap for real
|
||||
hardware (xorriso warns: "no directory /EFI/BOOT"). Real commodity UEFI
|
||||
firmware expects `BOOTX64.EFI` present in the ISO *filesystem* at
|
||||
`/EFI/BOOT/BOOTX64.EFI`, not just as an El Torito boot image.
|
||||
|
||||
Targets:
|
||||
- **amd64** — commodity x86-64 machine: add `/EFI/BOOT/BOOTX64.EFI` to
|
||||
the ISO filesystem tree in the Makefile xorriso invocation
|
||||
- **aarch64 / RPi4** — needs `BOOTAA64.EFI`; RPi4 requires the
|
||||
tianocore RPi4 UEFI firmware layer on the SD card/USB first; the ISO
|
||||
sits on top
|
||||
- **aarch64 / BeagleBone AI-64** (aspirational) — same EFI path as RPi4
|
||||
|
||||
Document the verified boot procedure for each target in
|
||||
`docs/lithosananke/hardware-boot.md`.
|
||||
|
||||
---
|
||||
|
||||
## Task 5 — `REBOOT` word
|
||||
|
||||
A FORTH word that optionally accepts a next-boot argument string and
|
||||
performs a cold reset via UEFI Runtime Services.
|
||||
|
||||
Key design decisions (agreed this session):
|
||||
- **Not interpreter-only at the C level** — no `STATE` check, no special
|
||||
flag
|
||||
- **ACL-controlled** — the word-level ACL system (Task 6) governs access
|
||||
- **On ACL denial**: emit warning, return to REPL; system keeps running
|
||||
- **No abort** — consistent with how all sensitive words will work under ACL
|
||||
|
||||
Implementation sketch:
|
||||
```forth
|
||||
S" --doe --stack=8M" REBOOT \ reboot with next-boot args
|
||||
REBOOT \ plain cold reboot
|
||||
```
|
||||
|
||||
Under the hood:
|
||||
1. If a string is on the stack: write it to a UEFI variable
|
||||
(`StarForthNextArgs` under a custom GUID) via `RT->SetVariable`
|
||||
2. Call `RT->ResetSystem(EfiResetCold, EFI_SUCCESS, 0, NULL)`
|
||||
3. Loader reads the variable on next boot, merges with `LoadOptions`;
|
||||
clears the variable after reading (one-shot)
|
||||
|
||||
`REBOOT` with no args is a plain cold reboot.
|
||||
|
||||
---
|
||||
|
||||
## Task 6 — `USE` word and resilient capsule loading
|
||||
|
||||
A general FORTH word (not capsule-specific) for loading external blobs.
|
||||
|
||||
```forth
|
||||
S" hires-video.4th" USE
|
||||
S" sound-card-1" USE \ fails → line gets commented out
|
||||
S" sound-card-2" USE
|
||||
```
|
||||
|
||||
On failure, `USE`:
|
||||
1. Locates the calling line in the block buffer
|
||||
2. Prepends `\ ` to comment it out (writes to RAM block)
|
||||
3. Continues — one failure does not stop subsequent `USE` calls
|
||||
4. Up to 16 lines per block may be commented out
|
||||
|
||||
**Self-healing property:** over multiple boots the system converges to a
|
||||
stable configuration. Hardware that isn't present or drivers that don't
|
||||
work are silently excluded. Hardware that works is locked in.
|
||||
|
||||
`REBOOT` integrates naturally:
|
||||
```forth
|
||||
S" hires-video.4th" USE
|
||||
REBOOT \ apply hardware init needing a cold reset
|
||||
hires-video-init? NOT IF
|
||||
\ didn't take — USE mechanism will comment it out on next boot
|
||||
THEN
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 7 — Forward word declarations
|
||||
|
||||
A FORTH analog of C prototypes: declare a word's name and stack effect
|
||||
before its implementing capsule is loaded. Enables circular dependencies
|
||||
between capsules without load-order brittleness.
|
||||
|
||||
```forth
|
||||
FORWARD: init-network ( -- ) \ stub; filled when net capsule loads
|
||||
FORWARD: video-mode? ( -- f ) \ stub; filled when video capsule loads
|
||||
```
|
||||
|
||||
If a forward-declared word is called before its definition arrives, it
|
||||
emits a warning and returns without crashing. When the implementing
|
||||
capsule loads and defines the word, the stub is replaced.
|
||||
|
||||
This is a general VM feature — not kernel or capsule specific.
|
||||
|
||||
---
|
||||
|
||||
## Task 8 — Word-level ACL system (existing design, next to implement)
|
||||
|
||||
Design doc: `docs/reference/word-acl/DESIGN.md`
|
||||
|
||||
This is already designed. It is the policy engine that makes Tasks 5–7
|
||||
safe. Implement before or alongside Task 5 (`REBOOT`) since `REBOOT`
|
||||
depends on ACL for its safety guarantees.
|
||||
|
||||
---
|
||||
|
||||
## Pointer for Next Session
|
||||
|
||||
Start with Task 1 (aarch64 + riscv64 acceptance). Read this file and the
|
||||
design docs listed above before touching any code. Present the task order
|
||||
to Captain Bob for approval before each implementation step.
|
||||
|
||||
All development stays on the working branch; never merge to master.
|
||||
@@ -0,0 +1,82 @@
|
||||
> **HISTORICAL (docs triage 2026-10-14).** A generated diagnostic report from one test run, 2026-06-30.
|
||||
> Instead: the boot POST in any current logs/ run. Moved here from `docs/BREAK_ME_REPORT.md`.
|
||||
|
||||
# 🔥 STARFORTH BREAK-ME DIAGNOSTIC REPORT 🔥
|
||||
|
||||
## Executive Summary
|
||||
|
||||
**Generated:** 2026-06-30 16:53:09
|
||||
|
||||
**Test Mode:** ULTRA-COMPREHENSIVE DIAGNOSTIC
|
||||
|
||||
**Purpose:** This report documents the results_run_01_2025_12_08 of the most exhaustive testing suite ever run on StarForth. Every word, every edge case, every pathological scenario has been tested to ensure rock-solid reliability and FORTH-79 standard compliance.
|
||||
|
||||
---
|
||||
|
||||
|
||||
## 📊 Performance Metrics
|
||||
|
||||
| Metric | Value |
|
||||
|--------|-------|
|
||||
| Test Duration | 0.00 seconds |
|
||||
| Total Tests | 1003 |
|
||||
| Tests/Second | inf |
|
||||
|
||||
## 🖥️ System Information
|
||||
|
||||
| Component | Specification |
|
||||
|-----------|---------------|
|
||||
| VM Architecture | Direct-threaded |
|
||||
| Standard | FORTH-79 + StarForth Extensions |
|
||||
| Cell Size | 8 bytes |
|
||||
| Stack Size | 1024 cells |
|
||||
| Memory | 5242880 bytes |
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🎉 EASTER EGG: THE STARFORTH CHALLENGE 🎉
|
||||
|
||||
```
|
||||
⭐ C O N G R A T U L A T I O N S ⭐
|
||||
|
||||
You've discovered the hidden StarForth challenge!
|
||||
|
||||
Your system just survived 1003 exhaustive tests.
|
||||
But can YOU survive the ULTIMATE FORTH CHALLENGE?
|
||||
|
||||
🏆 THE STARFORTH MASTER CHALLENGE 🏆
|
||||
|
||||
Write a Forth program that:
|
||||
1. Prints the Fibonacci sequence up to 1000
|
||||
2. Uses ONLY the following words:
|
||||
: ; DUP OVER DROP SWAP . CR < IF THEN DO LOOP
|
||||
3. Fits in exactly 79 characters (FORTH-79 tribute!)
|
||||
|
||||
Submit your solution to the StarForth community!
|
||||
|
||||
Hint: Think recursively, but remember FORTH-79
|
||||
doesn't have RECURSE... 😉
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
BONUS SECRET: If you ran --break-me, you're already
|
||||
in the top 1% of Forth enthusiasts. Welcome to the
|
||||
elite club! Your system just proved it can handle
|
||||
anything you throw at it.
|
||||
|
||||
May your stacks be balanced and your words defined,
|
||||
-- The StarForth Development Team ⭐
|
||||
```
|
||||
|
||||
### 🎮 More Easter Eggs to Find:
|
||||
|
||||
1. Try defining a word called `STARSHIP` and see what happens
|
||||
2. Run `42 ENTROPY@ .` to see the universe's favorite number
|
||||
3. Type `WORDS` and count how many contain 'STAR'
|
||||
4. Check what happens when you `FORGET FORGET` (just kidding, don't!)
|
||||
|
||||
---
|
||||
|
||||
*Generated by StarForth --break-me mode*
|
||||
*Copyright (c) 2025 Robert A. James - StarshipOS Forth Project*
|
||||
@@ -0,0 +1,100 @@
|
||||
> **HISTORICAL (docs triage 2026-10-14).** The write-up of one fix (APIC timer ISR, amd64), done.
|
||||
> Instead: the code itself (kernel/src/arch/amd64/). Moved here from `docs/lithosananke/amd64-isr-fix/README.md`.
|
||||
|
||||
# APIC Timer ISR Fix — amd64
|
||||
|
||||
**Date**: 2026-06-03
|
||||
**Branch**: `claude/starforth-architecture-review-oubN0`
|
||||
**Commits**: `fb0c256`, `901f827`
|
||||
|
||||
---
|
||||
|
||||
## Problem
|
||||
|
||||
The LithosAnanke amd64 kernel was triple-faulting on the first APIC timer interrupt,
|
||||
causing QEMU to exit immediately after printing `ok>`. The adaptive heartbeat never
|
||||
fired and `Heartbeat: N ticks` never appeared in serial logs.
|
||||
|
||||
## Root Cause
|
||||
|
||||
The kernel is compiled with `-fPIC -fvisibility=hidden` (required for UEFI PE
|
||||
relocation). Assembly symbols `isr_stub_table` and `isr_stub0` in `isr.S` were
|
||||
declared `.global` with **default visibility**. The C compiler therefore accessed
|
||||
them through GOT indirection. However, the linker — building a final non-shared
|
||||
binary — collapsed the GOT references to point directly at the symbols themselves.
|
||||
|
||||
The net effect: "load from GOT[`isr_stub_table`]" loaded the 8-byte instruction
|
||||
bytes of `isr_stub0` (`0x006a90eb006a006a`) rather than its address. Both
|
||||
`link_time_addr` and `runtime_addr` in `arch_interrupts_init()` became the same
|
||||
wrong value (instruction bytes), so `reloc_offset = 0` and all 256 IDT entries
|
||||
received garbage handler addresses. IDT[32] was set to `0x6a006afffffe91e9`
|
||||
(non-canonical), which triggered #GP → double fault → triple fault on the first
|
||||
timer delivery.
|
||||
|
||||
The bug was confirmed by disassembling `arch_interrupts_init()` in the loader PE:
|
||||
the compiler emitted a `mov` (load from memory) for `&isr_stub0` instead of a
|
||||
`lea` (compute address), reading the function's instruction bytes.
|
||||
|
||||
## Fix
|
||||
|
||||
Two changes, one line each:
|
||||
|
||||
**`src/starkernel/arch/amd64/isr.S`** — Added `.hidden` directives for all symbols
|
||||
referenced from C:
|
||||
|
||||
```asm
|
||||
.hidden isr_stub_table
|
||||
.hidden isr_stub0
|
||||
.hidden isr_stub32
|
||||
.hidden isr_stub_default
|
||||
.hidden isr_common_entry
|
||||
```
|
||||
|
||||
**`src/starkernel/arch/amd64/interrupts.c`** — Added visibility attributes to the
|
||||
`extern` declarations:
|
||||
|
||||
```c
|
||||
extern void *isr_stub_table[IDT_ENTRIES] __attribute__((visibility("hidden")));
|
||||
extern void isr_stub0(void) __attribute__((visibility("hidden")));
|
||||
```
|
||||
|
||||
With hidden visibility, the compiler uses direct RIP-relative `lea` instead of GOT
|
||||
indirection, yielding correct runtime addresses for all 256 IDT entries.
|
||||
|
||||
## Result
|
||||
|
||||
| Criterion | Before | After |
|
||||
|---|---|---|
|
||||
| IDT[32] handler | `0x6a006afffffe91e9` (corrupt) | `0x3d90251c` (valid canonical address) |
|
||||
| First timer interrupt | #GP → triple fault → QEMU exit | ISR fires cleanly, returns via `iretq` |
|
||||
| `PARITY:OK` | ✅ (unaffected) | ✅ |
|
||||
| `Init: init.4th OK` | ✅ (unaffected) | ✅ |
|
||||
| `ok>` REPL | ✅ reached, then immediate crash | ✅ runs indefinitely |
|
||||
| `Heartbeat: N ticks` | Never | Every second at 100 Hz, TIME-TRUST ≈ 0.999 |
|
||||
|
||||
## Secondary Fix
|
||||
|
||||
`repl_print_dec32`, `repl_lapic_ccr`, `repl_print_hex32`, and `idle_iters` in
|
||||
`repl.c` are x86-64 specific (LAPIC MMIO, `pushfq`). They were unguarded, causing
|
||||
`-Werror=unused-function` / `unused-variable` failures on aarch64 (clang) and
|
||||
riscv64 (gcc). All moved inside `#ifdef ARCH_AMD64`.
|
||||
|
||||
## Acceptance Testing
|
||||
|
||||
All three architectures must boot to `ok>` with `PARITY:OK` and `Init: init.4th OK`.
|
||||
amd64 additionally shows `Heartbeat: N ticks TIME-TRUST≈0.999` repeating at 1 Hz.
|
||||
|
||||
```bash
|
||||
make -f Makefile.starkernel ARCH=amd64 clean qemu
|
||||
make -f Makefile.starkernel ARCH=aarch64 clean qemu
|
||||
make -f Makefile.starkernel ARCH=riscv64 clean qemu
|
||||
```
|
||||
|
||||
Verify each log:
|
||||
|
||||
```bash
|
||||
grep "PARITY:OK" logs/qemu-<arch>-*.log
|
||||
grep "Init: init.4th OK" logs/qemu-<arch>-*.log
|
||||
grep "ok>" logs/qemu-<arch>-*.log
|
||||
grep "Heartbeat:" logs/qemu-amd64-*.log | head -5
|
||||
```
|
||||
@@ -0,0 +1,412 @@
|
||||
> **HISTORICAL (docs triage 2026-10-14).** The child-VM birthing plan and its acceptance record; built and live since (M7.1).
|
||||
> Instead: docs/reference/M7.1.md and docs/fabric/. Moved here from `docs/birthing/PLAN.md`.
|
||||
|
||||
# Birthing Plan: Child VMs Born of Hera
|
||||
|
||||
**Status:** DRAFT — requires Captain Bob approval before any implementation begins
|
||||
**Branch:** `birthing` (off `lithosananke`)
|
||||
**Authors:** Claude Code + Captain Bob
|
||||
**Date:** 2026-05-24
|
||||
|
||||
---
|
||||
|
||||
## 1. Vision
|
||||
|
||||
Three named VMs form the initial constellation of LithosAnanke:
|
||||
|
||||
| VM Name | Role |
|
||||
|---------|------|
|
||||
| **Hera** | Mama VM — orchestrates all other VMs; runs `capsules/init.4th` |
|
||||
| **Hermes** | Messaging stratum — pub/sub between VMs; runs `capsules/hermes/init.4th` |
|
||||
| **Artemis** | Storage and memory manager; runs `capsules/artemis/init.4th` |
|
||||
|
||||
**Hades** remains the kernel + HAL substrate beneath all of them.
|
||||
|
||||
For now, Hera's job is simply: birth, start, stop, and kill VM instances.
|
||||
Concurrent scheduling, inter-VM messaging, and storage management are later milestones.
|
||||
|
||||
Every VM — including Hermes and Artemis — carries the same lifecycle primitives.
|
||||
A VM can birth and manage other VMs. The infrastructure is uniform.
|
||||
|
||||
---
|
||||
|
||||
## 2. Hard Constraints
|
||||
|
||||
Fixed by the execution model. Hera's implementation is not constrained — she expands
|
||||
as the design requires.
|
||||
|
||||
| Constraint | Implication |
|
||||
|------------|-------------|
|
||||
| Same process as Hera | No `fork()`, no `pthread_create()` |
|
||||
| No threads | Scheduling is cooperative, inside the interpreter loop |
|
||||
| No OS processes | VMs share Hera's address space |
|
||||
| ANSI C99, `-Wall -Werror` | No GNU extensions |
|
||||
| Hades is the substrate | All I/O, timing, and memory from Hades (kernel+HAL) |
|
||||
|
||||
---
|
||||
|
||||
## 3. VM Identity and Naming
|
||||
|
||||
### 3.1 Every VM Has a Name
|
||||
|
||||
The current `VMRegistryEntry` tracks VMs by numeric ID only. This must be extended with a
|
||||
symbolic name field. A VM's name:
|
||||
|
||||
- Is set at birth (derived from the capsule namespace — see §5)
|
||||
- Is displayed in every log line emitted by that VM
|
||||
- Is the argument to all lifecycle words: `S" Artemis" BIRTH`, `S" Artemis" KILL`, etc.
|
||||
- Is unique within a session (no two live VMs share a name)
|
||||
- Is case-preserved but case-insensitive for lookup
|
||||
|
||||
### 3.2 VM Registry Extension
|
||||
|
||||
`VMRegistryEntry` needs a `name` field (at minimum `char name[64]`). The name is:
|
||||
- Set by `BIRTH` at VM creation time
|
||||
- Cleared on `KILL` (slot becomes reusable)
|
||||
- Logged in every parity record alongside the numeric VM ID
|
||||
|
||||
### 3.3 Log Prefix — Critical
|
||||
|
||||
Every line of console output emitted by a VM is prefixed with its name:
|
||||
|
||||
```
|
||||
[Hera] ok
|
||||
[Hermes] pub/sub ready
|
||||
[Artemis] storage initialized
|
||||
[Hera] 2 VMs alive
|
||||
```
|
||||
|
||||
This applies to `EMIT`, `TYPE`, `.`, `.S`, `CR`, and all I/O words. The prefix is injected
|
||||
at the HAL console layer — the VM does not format it; Hades prints it automatically based
|
||||
on the current active VM context.
|
||||
|
||||
---
|
||||
|
||||
## 4. The Five Primitive Forth Words
|
||||
|
||||
These words are **built-in C primitives** registered in every VM's dictionary at startup.
|
||||
They are not defined in Forth — they are part of the base word set, available to all VMs.
|
||||
|
||||
### Stack signatures use the counted-string convention: `( c-addr u -- )`
|
||||
|
||||
---
|
||||
|
||||
### `BIRTH ( c-addr u -- )`
|
||||
|
||||
Birth a new VM from the capsule whose namespace matches the given name.
|
||||
|
||||
**Mapping:** `S" Artemis"` → lowercase `"artemis"` → capsule name `artemis:init.4th`
|
||||
(the standard capsule for a named VM is `<name>:init.4th`).
|
||||
|
||||
**Sequence:**
|
||||
1. Lowercase the name string
|
||||
2. Construct capsule name: `<name>:init.4th`
|
||||
3. Look up capsule in the directory by name
|
||||
4. Verify capsule is `FLAG_PRODUCTION` + `FLAG_ACTIVE` and not `FLAG_REVOKED`
|
||||
5. Allocate a new VM context (full VM — Hera expands her pool as needed)
|
||||
6. Execute the capsule init (via existing `capsule_exec_init` path)
|
||||
7. Register VM under the symbolic name in the extended `VMRegistryEntry`
|
||||
8. Log parity record: `PARITY:BIRTH name=Artemis vm_id=N capsule_id=X`
|
||||
9. On success: push 0; on failure: push error code
|
||||
|
||||
**If a VM named "Artemis" is already alive:** check its health. If healthy, skip the birth
|
||||
and log the fact. Do not error, do not replace. BIRTH is idempotent for healthy VMs.
|
||||
|
||||
---
|
||||
|
||||
### `KILL ( c-addr u -- )`
|
||||
|
||||
Destroy a named VM. The VM's resources are freed and its registry slot is cleared.
|
||||
|
||||
**Sequence:**
|
||||
1. Look up VM by name in registry
|
||||
2. If not found: push error code, return
|
||||
3. Forcibly terminate any pending execution in that VM
|
||||
4. Free the VM's stacks, dictionary, and memory
|
||||
5. Clear registry slot (name + state = DEAD)
|
||||
6. Log parity record: `PARITY:KILL name=Artemis vm_id=N`
|
||||
7. Push 0 on success
|
||||
|
||||
**Note:** KILL is unconditional. It does not wait for the VM to reach a yield point.
|
||||
At this phase (no concurrent execution), the VM is idle when KILL is called.
|
||||
|
||||
---
|
||||
|
||||
### `START ( c-addr u -- )`
|
||||
|
||||
Begin or resume execution of a named VM.
|
||||
|
||||
**At this phase:** `START` runs the VM to completion (or until it calls `STOP` on itself)
|
||||
before returning control to the caller. Concurrent interleaved execution is a later milestone.
|
||||
|
||||
**Sequence:**
|
||||
1. Look up VM by name
|
||||
2. If state is EMBRYO or STOPPED: set state to LIVE, transfer execution
|
||||
3. If state is LIVE: error (already running)
|
||||
4. On VM completion or self-STOP: return control to the calling VM
|
||||
5. Push 0 on success
|
||||
|
||||
---
|
||||
|
||||
### `STOP ( c-addr u -- )`
|
||||
|
||||
Suspend a named VM. Its execution state is preserved; `START` will resume it.
|
||||
|
||||
Any VM can STOP any other. Authority comes from identity — a VM may assume another
|
||||
identity for failsafe and recovery. The identity assumption mechanism is a future
|
||||
milestone; in Phase 1, cross-VM STOP is permitted without restriction.
|
||||
|
||||
**Sequence:**
|
||||
1. Verify name matches the current VM
|
||||
2. Save execution state (IP, stacks)
|
||||
3. Set state to STOPPED
|
||||
4. Return control to the VM that called `START`
|
||||
|
||||
---
|
||||
|
||||
### `USE ( c-addr u -- )`
|
||||
|
||||
Make a named VM the active console target. Subsequent REPL input and output is directed
|
||||
to and from that VM until another `USE` call or the VM dies.
|
||||
|
||||
```forth
|
||||
S" Hermes" USE \ REPL now talks to Hermes
|
||||
: send-test S" hello" PUBLISH ;
|
||||
S" Hera" USE \ REPL returns to Hera
|
||||
```
|
||||
|
||||
USE is **system-wide** — it is not scoped to a capsule or identity. All REPL input and
|
||||
output redirects to the named VM until the next `USE` call. The `[Name]` prefix in the
|
||||
console reflects the active USE target.
|
||||
|
||||
**Sequence:**
|
||||
1. Look up VM by name in registry
|
||||
2. Set as the active system-wide REPL/console VM
|
||||
3. Console prefix changes to `[VMName]`
|
||||
4. Stack unchanged (no return value)
|
||||
|
||||
---
|
||||
|
||||
## 5. Capsule Namespace Convention
|
||||
|
||||
### 5.1 Directory Structure
|
||||
|
||||
Each named VM owns a subdirectory under `capsules/`:
|
||||
|
||||
```
|
||||
capsules/
|
||||
├── init.4th ← Hera's capsule ONLY (root level, no subdir)
|
||||
├── hermes/
|
||||
│ └── init.4th ← Hermes' capsule
|
||||
└── artemis/
|
||||
└── init.4th ← Artemis' capsule
|
||||
```
|
||||
|
||||
**`capsules/init.4th` is Hera's exclusive init.** No other VM uses the root-level init.
|
||||
Do not place general capsules there. Do not recreate the old `conf/` directory.
|
||||
|
||||
### 5.2 How mkcapsule Names Capsules
|
||||
|
||||
`tools/mkcapsule.c` scans `capsules/` recursively. It encodes relative paths by replacing
|
||||
`/` with `:`. So:
|
||||
|
||||
| File path | Capsule name |
|
||||
|-----------|-------------|
|
||||
| `capsules/init.4th` | `init.4th` |
|
||||
| `capsules/hermes/init.4th` | `hermes:init.4th` |
|
||||
| `capsules/artemis/init.4th` | `artemis:init.4th` |
|
||||
|
||||
### 5.3 BIRTH Name → Capsule Name Mapping
|
||||
|
||||
`BIRTH` lowercases the VM name and appends `:init.4th`:
|
||||
|
||||
| Forth call | Capsule looked up |
|
||||
|------------|------------------|
|
||||
| `S" Hera" BIRTH` | `init.4th` (special case — root) |
|
||||
| `S" Hermes" BIRTH` | `hermes:init.4th` |
|
||||
| `S" Artemis" BIRTH` | `artemis:init.4th` |
|
||||
| `S" MyWorker" BIRTH` | `myworker:init.4th` |
|
||||
|
||||
The root-level `init.4th` is a special case: `S" Hera" BIRTH` is how a future VM would
|
||||
re-birth Hera; at bootstrap, Hera boots from it automatically.
|
||||
|
||||
### 5.4 mkcapsule Flag Mapping
|
||||
|
||||
The capsule flag (`FLAG_PRODUCTION` vs `FLAG_EXPERIMENT`) is determined by the directory
|
||||
prefix — **not the file name**. Under the current `mkcapsule` logic:
|
||||
|
||||
- `capsules/hermes/init.4th` → does not match `production:*`, `core:*`, or `domains:*`
|
||||
→ currently gets `FLAG_EXPERIMENT`
|
||||
|
||||
**All capsules carry both `FLAG_PRODUCTION` and `FLAG_EXPERIMENT`.** Birth eligibility is
|
||||
not gated on the flag type — any capsule can be used for any identity. mkcapsule will be
|
||||
updated to set both flags on every capsule it generates. The distinction between production
|
||||
and experiment remains in the flags for audit/logging purposes but does not block BIRTH.
|
||||
|
||||
---
|
||||
|
||||
## 6. Capsule Content (Stubs)
|
||||
|
||||
Hermes and Artemis capsule directories exist but are empty (`.gitkeep` only). They need
|
||||
`init.4th` stubs before the system can BIRTH them.
|
||||
|
||||
### `capsules/hermes/init.4th` (stub)
|
||||
|
||||
Should:
|
||||
- Print `[Hermes] initializing` (or similar boot message)
|
||||
- Define Hermes' pub/sub vocabulary (placeholder for now)
|
||||
- Leave Hermes in a known state (not just empty)
|
||||
|
||||
### `capsules/artemis/init.4th` (stub)
|
||||
|
||||
Should:
|
||||
- Print `[Artemis] initializing`
|
||||
- Define Artemis' storage/memory vocabulary (placeholder)
|
||||
|
||||
**These stubs must be written before `make -f Makefile.starkernel` is run, because
|
||||
mkcapsule runs at build time and produces `capsule_generated.c` from whatever is in
|
||||
`capsules/` at that moment.**
|
||||
|
||||
---
|
||||
|
||||
## 7. VM Lifecycle Model
|
||||
|
||||
```
|
||||
(capsule exists in directory)
|
||||
│
|
||||
▼
|
||||
[BIRTH]
|
||||
│
|
||||
▼
|
||||
EMBRYO ──────────────────[KILL]──────► DEAD
|
||||
│ ▲
|
||||
[START] │
|
||||
│ [KILL]
|
||||
▼ │
|
||||
LIVE/RUNNING ──────────[STOP]──► STOPPED─┘
|
||||
│
|
||||
(completes)
|
||||
│
|
||||
▼
|
||||
DEAD (natural)
|
||||
```
|
||||
|
||||
States:
|
||||
- **EMBRYO** — VM born (capsule executed) but `START` not yet called
|
||||
- **LIVE** — executing (at this phase: running synchronously inside `START`)
|
||||
- **STOPPED** — suspended; state saved; resumable via `START`
|
||||
- **DEAD** — killed or naturally completed; slot reclaimable
|
||||
|
||||
---
|
||||
|
||||
## 8. Scheduling Model (Phase 1)
|
||||
|
||||
At this phase, scheduling is **sequential and explicit**:
|
||||
|
||||
- `START` runs a VM synchronously — the calling VM suspends while the started VM runs
|
||||
- No round-robin, no time-slicing, no preemption
|
||||
- The REPL is always in exactly one VM's context at a time
|
||||
- `USE` switches the REPL/console target
|
||||
|
||||
**This is intentionally simple.** Cooperative concurrent scheduling (multiple VMs
|
||||
interleaved in the interpreter loop) is a future milestone, designed separately after
|
||||
the basic lifecycle works.
|
||||
|
||||
---
|
||||
|
||||
## 9. Dictionary and Namespace
|
||||
|
||||
The five lifecycle words (BIRTH, KILL, START, STOP, USE) are C primitives in **every VM's
|
||||
base dictionary**. They are registered at VM initialization, before any capsule init runs.
|
||||
|
||||
A child VM born by Hermes or Artemis also has these words — all VMs can manage other VMs.
|
||||
|
||||
**Dictionary isolation:** Each VM has its own dictionary. Words defined by Artemis's
|
||||
`init.4th` do not appear in Hera's dictionary or Hermes' dictionary. VMs communicate
|
||||
through the messaging layer (Hermes), not shared dictionary state.
|
||||
|
||||
---
|
||||
|
||||
## 10. Hades Interface
|
||||
|
||||
All VMs access Hades through the same HAL interface. At this phase:
|
||||
- No capability bitmask enforcement
|
||||
- All VMs can call any HAL function (I/O, memory, time)
|
||||
- The log prefix (`[VMName]`) is injected by the HAL console layer based on the currently
|
||||
executing VM context — not by the VM itself
|
||||
|
||||
Capability enforcement (limiting what a child VM can do in Hades) is a future milestone.
|
||||
|
||||
---
|
||||
|
||||
## 11. Physics / SSM Integration
|
||||
|
||||
Each VM has its own independent SSM/L8 Jacquard state — this is already the natural
|
||||
consequence of each VM being a full VM instance with its own `VM` struct. No shared physics.
|
||||
|
||||
The heartbeat runs per-VM. Hera's SSM does not observe Hermes' or Artemis' execution.
|
||||
|
||||
---
|
||||
|
||||
## 12. Decisions — RESOLVED
|
||||
|
||||
| # | Decision | Resolution |
|
||||
|---|----------|-----------|
|
||||
| D1 | BIRTH name collision | **Idempotent — check health of existing VM; if healthy, skip and log. No error, no replace.** |
|
||||
| D2 | Production flag | **All capsules carry both `FLAG_PRODUCTION` and `FLAG_EXPERIMENT`. Birth eligibility is not gated on flag type. mkcapsule updated accordingly.** |
|
||||
| D3 | `BIRTH` return value | **Nothing — BIRTH is a pure side-effect word, leaves stack clean.** |
|
||||
| D4 | `USE` scope | **REPL only, but system-wide. Not bound to any specific capsule or identity. All REPL I/O redirects to the named VM.** |
|
||||
| D5 | STOP across VMs | **Any VM may assume another identity for failsafe and recovery purposes, enabling cross-VM STOP. Identity assumption mechanism is a future milestone; Phase 1 allows any VM to STOP any other.** |
|
||||
| D6 | Max named VMs | **Dynamic — Hera allocates as needed. No fixed ceiling.** |
|
||||
| D7 | Log prefix format | **`[Name]`** — e.g., `[Hera]`, `[Hermes]`, `[Artemis]` |
|
||||
|
||||
---
|
||||
|
||||
## 13. What This Is NOT
|
||||
|
||||
- **Not a thread scheduler.** No preemption. Sequential execution at this phase.
|
||||
- **Not a process model.** VMs share Hera's address space.
|
||||
- **Not a security boundary yet.** No capability enforcement in this phase.
|
||||
- **Not constrained by Hera's current implementation.** Hera expands as the design requires.
|
||||
|
||||
---
|
||||
|
||||
## 14. Implementation Phases
|
||||
|
||||
No code until Captain Bob approves the plan.
|
||||
|
||||
| Phase | Scope | Deliverable |
|
||||
|-------|-------|-------------|
|
||||
| 0 | Design approval | This document, signed off |
|
||||
| 1 | VM registry naming | Add `name[64]` to `VMRegistryEntry`; name lookup functions |
|
||||
| 2 | Log prefix | HAL console layer emits `[VMName]` prefix per active VM |
|
||||
| 3 | Capsule stubs | Write `capsules/hermes/init.4th`, `capsules/artemis/init.4th` |
|
||||
| 4 | mkcapsule flag update | Set both `FLAG_PRODUCTION` and `FLAG_EXPERIMENT` on all capsules |
|
||||
| 5 | BIRTH word | C primitive; name→capsule lookup; health-check idempotence; full VM alloc |
|
||||
| 6 | KILL word | C primitive; teardown; registry clear |
|
||||
| 7 | START word | C primitive; synchronous execution hand-off |
|
||||
| 8 | STOP word | C primitive; cross-VM; state save; return to caller |
|
||||
| 9 | USE word | C primitive; system-wide REPL/console redirect |
|
||||
| 10 | Hera init.4th update | Use new words to birth Hermes and Artemis at boot |
|
||||
| 11 | Integration test | Boot sequence: Hera → BIRTH Hermes → BIRTH Artemis → `[Name]` in logs |
|
||||
|
||||
---
|
||||
|
||||
## 15. Mythological Framing Reference
|
||||
|
||||
| Name | Role |
|
||||
|------|------|
|
||||
| **Hades** | Kernel + HAL — the underworld substrate |
|
||||
| **Hera** | Mama VM — queen, orchestrator, eternal; `capsules/init.4th` |
|
||||
| **Hermes** | Messenger — pub/sub stratum; `capsules/hermes/init.4th` |
|
||||
| **Artemis** | Hunter/keeper — storage and memory; `capsules/artemis/init.4th` |
|
||||
| **BIRTH** | The word that brings a new VM into being |
|
||||
| **KILL** | The word that destroys a VM |
|
||||
| **START** | The word that gives a VM its first breath (or resumes it) |
|
||||
| **STOP** | The word that suspends a VM |
|
||||
| **USE** | The word that shifts the speaker's attention to a VM |
|
||||
|
||||
---
|
||||
|
||||
*This document is a planning artifact only. No code changes have been made.
|
||||
Captain Bob's approval of the open decisions in §12 is required before Phase 1 begins.*
|
||||
@@ -0,0 +1,25 @@
|
||||
> **HISTORICAL (docs triage 2026-10-14).** The child-VM birthing plan and its acceptance record; built and live since (M7.1).
|
||||
> Instead: docs/reference/M7.1.md and docs/fabric/. Moved here from `docs/birthing/README.md`.
|
||||
|
||||
# docs/working/archive/historical/2026-07-birthing/
|
||||
|
||||
Design and status for VM "birthing" — the mechanism by which Hera (the Tripod
|
||||
governor) spawns Hermes and Artemis as child VMs at boot. See
|
||||
`docs/working/archive/superseded/2026-08-tripod/TRIPOD.md` for the architectural contract this
|
||||
work implements.
|
||||
|
||||
- **[PLAN.md](PLAN.md)** — Birthing plan for the initial three-VM constellation
|
||||
(Hera/Hermes/Artemis). Marked DRAFT, requires Captain Bob approval before
|
||||
implementation.
|
||||
- **[STATUS.md](STATUS.md)** — Current work status: execution model (single
|
||||
OS process, no threads/fork, VMs share one heap and address space, the C
|
||||
call stack doubles as the execution stack), the birth-graph vs.
|
||||
execution-stack distinction, and phase completion tracking.
|
||||
- **[acceptance-logs/](acceptance-logs/)** — Three-architecture QEMU
|
||||
acceptance test logs and summary for the lifecycle words (`BIRTH KILL
|
||||
START STOP USE`).
|
||||
|
||||
## See also
|
||||
|
||||
- [`docs/working/archive/superseded/2026-08-tripod/README.md`](../03-architecture/tripod/README.md)
|
||||
- [Project root](../../README.md)
|
||||
@@ -0,0 +1,307 @@
|
||||
> **HISTORICAL (docs triage 2026-10-14).** The child-VM birthing plan and its acceptance record; built and live since (M7.1).
|
||||
> Instead: docs/reference/M7.1.md and docs/fabric/. Moved here from `docs/birthing/STATUS.md`.
|
||||
|
||||
# Birthing — Work Status and Context
|
||||
|
||||
**Branch:** `birthing` (off `lithosananke`)
|
||||
**Last updated:** 2026-05-27
|
||||
**Current phase:** Phases 1–11 complete (kernel QEMU acceptance passed all three architectures)
|
||||
|
||||
---
|
||||
|
||||
## Execution Model — Single Process, VM Graph
|
||||
|
||||
**Hard constraints:**
|
||||
- One OS process. No threads. No fork. No shared memory between processes.
|
||||
- All VMs live in the same heap, same address space.
|
||||
- The C call stack IS the execution stack.
|
||||
|
||||
**The graph:**
|
||||
|
||||
VMs are nodes. Edges are relationships — birth (who created whom) and execution (who
|
||||
STARTed whom). These are distinct:
|
||||
|
||||
```
|
||||
Birth graph (static, ownership): Execution stack (dynamic, runtime):
|
||||
|
||||
Hera C call stack:
|
||||
/ \ hera_interp()
|
||||
Hermes Artemis └─ vm_start("Hermes")
|
||||
└─ hermes_interp()
|
||||
└─ vm_start("Artemis")
|
||||
└─ artemis_interp()
|
||||
└─ STOP → unwind
|
||||
```
|
||||
|
||||
**`START` = push.** Calling `S" Hermes" START` from Hera literally calls Hermes's
|
||||
interpreter loop from within Hera's C execution context. Hera blocks in the `vm_start()`
|
||||
call until Hermes returns.
|
||||
|
||||
**`STOP` = pop.** A VM stops itself — execution returns up the C call stack to whoever
|
||||
called `vm_start()`. In Phase 1, STOP is always self-stop. Cross-VM STOP (via identity
|
||||
assumption) is a future milestone.
|
||||
|
||||
**`BIRTH` does not equal `START`.** BIRTH allocates and initializes the VM. START runs it.
|
||||
A VM can be birthed and left dormant.
|
||||
|
||||
**`USE` is orthogonal.** It redirects the REPL I/O independently of which VM is currently
|
||||
executing. It does not affect the C call stack.
|
||||
|
||||
**Any VM can birth sub-VMs.** Hermes can call `S" Companion" BIRTH` — it is not Hera's
|
||||
exclusive privilege. This makes the birth graph a true directed graph (rooted at Hera),
|
||||
not a strict two-level tree.
|
||||
|
||||
---
|
||||
|
||||
## What This Branch Is
|
||||
|
||||
We are designing and implementing the multi-VM birth system for LithosAnanke. Hera (the
|
||||
primary Forth VM) gains the ability to birth, name, start, stop, and kill peer VMs. All
|
||||
VMs run inside the same process — no threads, no OS processes.
|
||||
|
||||
---
|
||||
|
||||
## The Three Named VMs
|
||||
|
||||
| VM | Role | Capsule |
|
||||
|----|------|---------|
|
||||
| **Hera** | Mama VM — orchestrates all others | `capsules/init.4th` (root, exclusive) |
|
||||
| **Hermes** | Messaging stratum — pub/sub | `capsules/hermes/init.4th` |
|
||||
| **Artemis** | Storage and memory manager | `capsules/artemis/init.4th` |
|
||||
|
||||
**Hades** = kernel + HAL substrate beneath all VMs.
|
||||
|
||||
---
|
||||
|
||||
## The Five Forth Primitives (C-level, in every VM's dictionary)
|
||||
|
||||
All words take a counted string `( c-addr u -- )` and leave the stack clean.
|
||||
|
||||
| Word | Behavior |
|
||||
|------|----------|
|
||||
| `BIRTH` | Birth a VM from `<name>:init.4th`. Idempotent — if healthy VM exists, skip + log. |
|
||||
| `KILL` | Destroy a named VM unconditionally. Free resources, clear registry slot. |
|
||||
| `START` | Begin or resume a named VM. Runs synchronously (Phase 1). |
|
||||
| `STOP` | Suspend a named VM. Any VM can STOP any other. Saves execution state. |
|
||||
| `USE` | System-wide REPL/console redirect to the named VM. Not capsule-scoped. |
|
||||
|
||||
Example usage:
|
||||
```forth
|
||||
S" Artemis" BIRTH
|
||||
S" Artemis" START
|
||||
S" Artemis" USE
|
||||
S" Artemis" STOP
|
||||
S" Artemis" KILL
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Resolved Decisions
|
||||
|
||||
| # | Decision | Resolution |
|
||||
|---|----------|-----------|
|
||||
| D1 | BIRTH name collision | Idempotent — healthy VM: skip and log. No error, no replace. |
|
||||
| D2 | Capsule production flag | All capsules get both `FLAG_PRODUCTION` + `FLAG_EXPERIMENT`. Birth not gated on flag type. |
|
||||
| D3 | BIRTH return value | Nothing — stack clean. Pure side-effect word. |
|
||||
| D4 | USE scope | System-wide REPL redirect. Not bound to any capsule or identity. |
|
||||
| D5 | STOP authority | Any VM can STOP any other. Identity assumption (future) adds nuance. |
|
||||
| D6 | Max VMs | Dynamic — Hera allocates as needed. No fixed ceiling. |
|
||||
| D7 | Log prefix format | `[Name]` — e.g., `[Hera]`, `[Hermes]`, `[Artemis]` |
|
||||
|
||||
---
|
||||
|
||||
## Capsule Namespace Convention
|
||||
|
||||
`mkcapsule` encodes relative paths by replacing `/` with `:`.
|
||||
|
||||
| File | Capsule name | Used by |
|
||||
|------|-------------|---------|
|
||||
| `capsules/init.4th` | `init.4th` | Hera only |
|
||||
| `capsules/hermes/init.4th` | `hermes:init.4th` | Hermes |
|
||||
| `capsules/artemis/init.4th` | `artemis:init.4th` | Artemis |
|
||||
|
||||
`BIRTH` maps `S" Artemis"` → lowercase → `artemis:init.4th`.
|
||||
|
||||
`capsules/hermes/` and `capsules/artemis/` currently exist but contain only `.gitkeep`.
|
||||
Stub `init.4th` files must be written before the kernel build runs `mkcapsule`.
|
||||
|
||||
---
|
||||
|
||||
## Implementation Checklist
|
||||
|
||||
### Phase 0 — Design and Approval
|
||||
- [x] `birthing` branch created off `lithosananke` HEAD
|
||||
- [x] `docs/working/archive/historical/2026-07-birthing/PLAN.md` written
|
||||
- [x] All seven decisions resolved with Captain Bob
|
||||
- [x] `docs/working/archive/historical/2026-07-birthing/STATUS.md` created (this file)
|
||||
- [x] **Captain Bob approves plan — gate for Phase 1**
|
||||
|
||||
---
|
||||
|
||||
### Phase 1 — VM Registry Naming
|
||||
- [x] Add `char name[VM_NAME_MAX]` + `VM_STATE_STOPPED` to `VMRegistryEntry` (`include/starkernel/capsule_run.h`)
|
||||
- [x] Replace static `vm_registry[64]` with dynamic kmalloc linked list (`src/starkernel/capsule/capsule_birth.c`)
|
||||
- [x] Hera (VM 0) registered as `"Hera"` in `capsule_vm_registry_init()`
|
||||
- [x] Add `capsule_vm_find_by_name()` — walks linked list, copies entry on match
|
||||
- [x] Add `capsule_vm_registry_set_name()` — sets symbolic name by vm_id
|
||||
- [x] Declare both new functions in `include/starkernel/capsule_birth.h`
|
||||
- [x] Kernel build (`make -f Makefile.starkernel ARCH=amd64 STARFORTH_ENABLE_VM=1`) passes clean
|
||||
- [ ] Tests: find by name, not-found returns -1, name persists across states
|
||||
|
||||
---
|
||||
|
||||
**Gap 1 (deferred to Phase 4):** `CAPSULE_MODE_VALID` enforces XOR between `FLAG_PRODUCTION`
|
||||
and `FLAG_EXPERIMENT`. Captain Bob's answer about D2 points at a runtime logger/mode
|
||||
selector (`LOG-DOE`) that does not yet exist. Design of `LOG-DOE` and the runtime mode
|
||||
selection is a separate task before Phase 4 (mkcapsule flag update) can proceed.
|
||||
|
||||
---
|
||||
|
||||
### Phase 2 — Log Prefix `[Name]`
|
||||
- [x] Identify the HAL console output path (`src/starkernel/hal/console.c`)
|
||||
- [x] Add "active VM" context pointer to the HAL console layer
|
||||
- [x] Every `hal_console_putchar` / `hal_console_puts` prefixes `[VMName] ` at line start
|
||||
- [x] Hera's boot output shows `[Hera]` from first character
|
||||
- [ ] QEMU verification pending Captain Bob
|
||||
|
||||
---
|
||||
|
||||
### Phase 3 — Capsule Stubs
|
||||
- [x] Write `capsules/hermes/init.4th` (boot message + placeholder vocabulary)
|
||||
- [x] Write `capsules/artemis/init.4th` (boot message + placeholder vocabulary)
|
||||
- [ ] Verify `mkcapsule` generates descriptors for both (requires kernel build env)
|
||||
- [ ] Verify capsule names resolve correctly (`hermes:init.4th`, `artemis:init.4th`)
|
||||
|
||||
---
|
||||
|
||||
### Phase 4 — mkcapsule Flag Update
|
||||
- [ ] Update `tools/mkcapsule.c` to set both `FLAG_PRODUCTION` and `FLAG_EXPERIMENT` on
|
||||
every capsule (remove the directory-prefix-based flag logic, or extend it to set both)
|
||||
- [ ] Rebuild and verify `capsule_generated.c` shows both flags on all entries
|
||||
- [ ] Confirm birth eligibility check in `capsule_birth.c` no longer blocks on flag type
|
||||
|
||||
---
|
||||
|
||||
### Phase 5 — `BIRTH` Word
|
||||
- [x] Register `BIRTH` as a C primitive in `register_mama_forth_words()` (mama_forth_words.c)
|
||||
- [x] Lowercase the name string from the stack
|
||||
- [x] Construct capsule name: `<name>:init.4th` (special case: `hera` → rejected)
|
||||
- [x] Look up capsule in directory by name
|
||||
- [x] Health check: if VM with that name is alive and healthy, log and return (idempotent)
|
||||
- [x] Allocate new VM (dynamic — no fixed pool ceiling)
|
||||
- [x] Execute capsule init via `capsule_birth_baby` path
|
||||
- [x] Register VM under symbolic name in `VMRegistryEntry`
|
||||
- [x] Emit parity log via `capsule_parity_log_birth`
|
||||
- [x] Stack clean on exit
|
||||
- [x] Fixed caddr+1 offset bug — now reads chars directly at caddr per FORTH-79 S"
|
||||
|
||||
---
|
||||
|
||||
### Phase 6 — `KILL` Word
|
||||
- [x] Register `KILL` as a C primitive
|
||||
- [x] Look up VM by name (case-insensitive)
|
||||
- [x] If not found: log, return (no stack effect)
|
||||
- [x] Tear down VM, free via `vm_cleanup` + `sf_free`
|
||||
- [x] Clear registry slot (state → DEAD, name cleared)
|
||||
- [x] Emit parity log via `capsule_parity_log_kill`
|
||||
- [x] Stack clean on exit
|
||||
- [x] Hera kill rejected
|
||||
|
||||
---
|
||||
|
||||
### Phase 7 — `START` Word
|
||||
- [x] Register `START` as a C primitive
|
||||
- [x] Look up VM by name
|
||||
- [x] If EMBRYO or STOPPED: set state → LIVE
|
||||
- [x] Call `sk_repl_run(target)` — blocks until target->halted
|
||||
- [x] On target halt: state → STOPPED, caller resumes
|
||||
- [x] If target already LIVE: log error, return clean
|
||||
- [x] Stack clean on exit
|
||||
|
||||
---
|
||||
|
||||
### Phase 8 — `STOP` Word
|
||||
- [x] Register `STOP` as a C primitive
|
||||
- [x] Self-stop: sets `vm->halted = 1`, sk_repl_run loop exits
|
||||
- [x] State updated to STOPPED by START word after REPL returns
|
||||
- [x] Stack clean (STOP takes no arguments)
|
||||
|
||||
---
|
||||
|
||||
### Phase 9 — `USE` Word
|
||||
- [x] Register `USE` as a C primitive
|
||||
- [x] Look up VM by name
|
||||
- [x] Set active system-wide REPL VM via `sk_repl_set_active_vm`
|
||||
- [x] HAL console prefix changes to `[VMName]` via `console_set_vm_name`
|
||||
- [x] Stack clean on exit
|
||||
|
||||
---
|
||||
|
||||
### Phase 10 — Hera `init.4th` Update
|
||||
- [x] `S" Hermes" BIRTH` in `capsules/init.4th`
|
||||
- [x] `S" Artemis" BIRTH` in `capsules/init.4th`
|
||||
- [x] S" fixed to FORTH-79 ( -- c-addr u ) — stores at HERE, no count-byte prefix
|
||||
- [x] Boot sequence QEMU verified — all three architectures (amd64, aarch64, riscv64)
|
||||
|
||||
---
|
||||
|
||||
### Phase 11 — Integration Test (kernel QEMU)
|
||||
- [x] Boot QEMU: kernel loads, Hera starts, births Hermes and Artemis — all three architectures
|
||||
- [x] Serial log shows `[Hera]`, `[Hermes]`, `[Artemis]` prefixes
|
||||
- [x] `."` compile-mode fixed (do-string inline approach) — "Hermes Up" / "Artimis Up" print correctly
|
||||
- [x] 734 passed / 0 failed / 0 errors on amd64, aarch64, riscv64
|
||||
- [ ] `S" Hermes" USE` switches console to Hermes — interactive test (requires Captain Bob)
|
||||
- [ ] `S" Hera" USE` switches back — interactive test (requires Captain Bob)
|
||||
- [ ] KILL + re-BIRTH a VM in the same session — interactive test (requires Captain Bob)
|
||||
|
||||
**Logs:** `docs/working/archive/historical/2026-07-birthing/acceptance-logs/` — kernel QEMU serial logs for all three architectures
|
||||
|
||||
---
|
||||
|
||||
## Key Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `docs/working/archive/historical/2026-07-birthing/PLAN.md` | Full architectural plan |
|
||||
| `docs/working/archive/historical/2026-07-birthing/STATUS.md` | This file — living checklist |
|
||||
| `tools/mkcapsule.c` | Build-time capsule packager |
|
||||
| `capsules/init.4th` | Hera's init (root, exclusive) |
|
||||
| `capsules/hermes/init.4th` | Hermes stub (to be written) |
|
||||
| `capsules/artemis/init.4th` | Artemis stub (to be written) |
|
||||
| `src/starkernel/capsule/capsule_birth.c` | C-level VM birth logic |
|
||||
| `src/starkernel/capsule/capsule_loader.c` | Capsule load + exec |
|
||||
| `src/starkernel/capsule/capsule_registry.c` | Capsule directory |
|
||||
| `src/starkernel/hal/console.c` | HAL console — add `[Name]` prefix here |
|
||||
| `include/starkernel/capsule.h` | `CapsuleDesc`, `VMRegistryEntry` structs |
|
||||
| `include/starkernel/capsule_birth.h` | Birth protocol headers |
|
||||
|
||||
---
|
||||
|
||||
## Branch and Commit History
|
||||
|
||||
```
|
||||
birthing (HEAD)
|
||||
d2766d6 plan: lock all seven decisions into birthing plan
|
||||
ba27226 plan: overhaul birthing plan — named VMs, five Forth primitives, capsule namespacing
|
||||
d258b12 plan: update birthing plan — Hera is not constrained
|
||||
84e1c61 plan: add birthing plan for child VMs born of Hera
|
||||
91e0b3d (lithosananke HEAD at branch point) docs: comprehensive CLAUDE.md update
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Notes and Open Threads
|
||||
|
||||
- **Identity assumption (D5 future):** Cross-VM STOP requires a VM to assume another's
|
||||
identity. Not in scope for current phases — design separately. Phase 1 STOP is self-stop.
|
||||
- **Cooperative scheduling / YIELD:** The single-process graph model means VMs run one at a
|
||||
time (depth-first down the call stack). True cooperative interleaving (Hermes and Artemis
|
||||
sharing time while Hera waits) would require an explicit `YIELD` mechanism and a trampoline
|
||||
scheduler — future milestone, designed separately.
|
||||
- **Graph depth — CONFIRMED unlimited:** Any VM can BIRTH sub-VMs at any depth. The birth
|
||||
graph is a true rooted directed graph. Deep graphs consume C stack space — note for kernel
|
||||
stack budgeting. No enforced limit; document safe depth in practice.
|
||||
- **Hermes pub/sub and Artemis storage:** Their full vocabularies are future work. Current
|
||||
phase only needs stub `init.4th` files.
|
||||
- **`capsules/hermes/` and `capsules/artemis/`** currently contain only `.gitkeep`. Stub
|
||||
`init.4th` files must exist before `make -f Makefile.starkernel` calls `mkcapsule`.
|
||||
@@ -0,0 +1,22 @@
|
||||
> **HISTORICAL (docs triage 2026-10-14).** The child-VM birthing plan and its acceptance record; built and live since (M7.1).
|
||||
> Instead: docs/reference/M7.1.md and docs/fabric/. Moved here from `docs/birthing/acceptance-logs/README.md`.
|
||||
|
||||
# docs/working/archive/historical/2026-07-birthing/acceptance-logs/
|
||||
|
||||
Kernel QEMU acceptance test results for the VM lifecycle words (`BIRTH KILL
|
||||
START STOP USE`) and the `."` compile-mode fix, run across all three
|
||||
supported architectures.
|
||||
|
||||
- **[SUMMARY.md](SUMMARY.md)** — Consolidated results table (800 tests run,
|
||||
734 passed, 0 failed/errored on amd64/aarch64/riscv64), key serial-log
|
||||
evidence, list of source files changed, and the remaining interactive
|
||||
tests that require Captain Bob (`S" Hermes" USE`, KILL + re-BIRTH in the
|
||||
same session).
|
||||
- **[amd64.log](amd64.log)** — Raw QEMU serial log, amd64.
|
||||
- **[arm64.log](arm64.log)** — Raw QEMU serial log, aarch64.
|
||||
- **[riscv64.log](riscv64.log)** — Raw QEMU serial log, riscv64.
|
||||
|
||||
## See also
|
||||
|
||||
- [`docs/working/archive/historical/2026-07-birthing/README.md`](../README.md)
|
||||
- [Project root](../../../README.md)
|
||||
@@ -0,0 +1,66 @@
|
||||
> **HISTORICAL (docs triage 2026-10-14).** The child-VM birthing plan and its acceptance record; built and live since (M7.1).
|
||||
> Instead: docs/reference/M7.1.md and docs/fabric/. Moved here from `docs/birthing/acceptance-logs/SUMMARY.md`.
|
||||
|
||||
# Birthing — Kernel QEMU Acceptance Test Summary
|
||||
|
||||
**Date:** 2026-05-27
|
||||
**Branch:** `birthing`
|
||||
**Feature:** Lifecycle words (BIRTH KILL START STOP USE) + `."` compile-mode fix
|
||||
|
||||
## Scope
|
||||
|
||||
These logs cover the **kernel UEFI build** (`make -f Makefile.starkernel ARCH=<arch> clean qemu`).
|
||||
All three architectures booted to `ok>`, ran POST, and executed `capsules/init.4th` successfully.
|
||||
|
||||
## Kernel QEMU Results
|
||||
|
||||
| Arch | Tests | Passed | Failed | Errors | BIRTH Hermes | BIRTH Artemis | `."` |
|
||||
|------|-------|--------|--------|--------|-------------|---------------|------|
|
||||
| amd64 | 800 | 734 | 0 | 0 | `[Hermes] Hermes Up` / live | `[Artemis] Artimis Up` / live | PASS |
|
||||
| aarch64 | 800 | 734 | 0 | 0 | `[Hermes] Hermes Up` / live | `[Artemis] Artimis Up` / live | PASS |
|
||||
| riscv64 | 800 | 734 | 0 | 0 | `[Hermes] Hermes Up` / live | `[Artemis] Artimis Up` / live | PASS |
|
||||
|
||||
## Key Evidence (all three architectures identical)
|
||||
|
||||
```
|
||||
[Hera] POST: PASSED
|
||||
[Hera] Init: loading init.4th...
|
||||
[Hermes] Hermes UpBIRTH: Hermes live
|
||||
[Artemis] Artimis UpBIRTH: Artemis live
|
||||
[Hera] Init: init.4th OK
|
||||
```
|
||||
|
||||
`."` in compile mode now uses the `(do-string)` inline runtime — string bytes live
|
||||
inside the threaded code body, not at `body_addr`. The previous LIT-addr-LIT-len-TYPE
|
||||
approach overwrote the start of the word body with string bytes, causing a triple fault
|
||||
when `execute_colon_word` read them as DictEntry pointers.
|
||||
|
||||
## What Changed
|
||||
|
||||
- `src/word_source/io_words.c` — `."` compile mode replaced with `(do-string)` inline
|
||||
approach; `(do-string)` runtime word reads inline string via return-stack IP, prints,
|
||||
advances IP past padded block
|
||||
- `src/starkernel/capsule/mama_forth_words.c` — BIRTH KILL START STOP USE kernel
|
||||
implementations; fixed caddr+1 offset bug to align with FORTH-79 S"
|
||||
- `src/word_source/string_words.c` — S" fixed to FORTH-79 standard ( -- c-addr u )
|
||||
- `src/word_source/lifecycle_words_hosted.c` — hosted Linux stubs (guarded #ifndef __STARKERNEL__)
|
||||
- `src/main.c` — register_lifecycle_words(&vm) wired in for hosted build
|
||||
- `capsules/init.4th` — S" Hermes" BIRTH + S" Artemis" BIRTH
|
||||
- `capsules/hermes/init.4th` — stub: `: UP ." Hermes Up" ; UP`
|
||||
- `capsules/artemis/init.4th` — stub: `: UP ." Artimis Up" ; UP`
|
||||
|
||||
## Serial Logs
|
||||
|
||||
| Arch | Log file |
|
||||
|------|----------|
|
||||
| amd64 | `logs/qemu-amd64-20260526-234957.log` |
|
||||
| aarch64 | `logs/qemu-aarch64-20260526-235056.log` |
|
||||
| riscv64 | `logs/qemu-riscv64-20260527-000127.log` |
|
||||
|
||||
(`logs/` is gitignored — run locally to reproduce)
|
||||
|
||||
## Remaining Interactive Tests (require Captain Bob)
|
||||
|
||||
- `S" Hermes" USE` — switches system console to Hermes
|
||||
- `S" Hera" USE` — switches back
|
||||
- KILL + re-BIRTH a VM in the same session
|
||||
@@ -0,0 +1,3 @@
|
||||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:2dbe1a4abd9342a0ec96fbd4c4c15ab039385b2af9639c7489eda6fe9dfc6fa4
|
||||
size 10216
|
||||
@@ -0,0 +1,3 @@
|
||||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:25dc9dcce2403f30ef6b2c0d14e5462d7e17e42070c1afa443f92cf85985cd99
|
||||
size 9889
|
||||
@@ -0,0 +1,3 @@
|
||||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:2af00462812d21a44807da17be38ad5fb5e97ca56b4c2b883cf192b7ef1778db
|
||||
size 9885
|
||||
@@ -0,0 +1,186 @@
|
||||
> **HISTORICAL (docs triage 2026-10-14).** The write-up of one fix (kernel stack trampoline, riscv64), done.
|
||||
> Instead: the code itself (kernel/src/arch/riscv64/). Moved here from `docs/lithosananke/riscv64-stack-fix/README.md`.
|
||||
|
||||
# Kernel Stack Trampoline Fix — riscv64
|
||||
|
||||
**Date**: 2026-08-02
|
||||
**Branch**: `master`
|
||||
**Commit**: `7366275`
|
||||
|
||||
---
|
||||
|
||||
## Problem
|
||||
|
||||
The riscv64 kernel crashed partway through VM bootstrap during the 2026-08-01
|
||||
DoE campaign run, well after amd64 and aarch64 had both booted cleanly to
|
||||
`ok>` in the same session. The crash was a wild jump: execution landed at an
|
||||
address nowhere inside the kernel's own linked image, then almost immediately
|
||||
faulted trying to load from a small, near-null address.
|
||||
|
||||
```
|
||||
Registering FORTH-79 Standard word set...
|
||||
Registering FORTH-79 arithmetic words...
|
||||
FORTH-79 Standard word set registration complete
|
||||
*** EXCEPTION (riscv64) ***
|
||||
scause = 0x000000000000000d
|
||||
sepc = 0x00000000be27c3c2
|
||||
stval = 0x00000000000074d8
|
||||
```
|
||||
|
||||
`scause = 0xd` is a supervisor-mode load page fault. `sepc` (~0xbe27c3c2) sat
|
||||
near the top of QEMU's 1 GB RAM window — nowhere close to the kernel's own
|
||||
`.text`/`.data`/`.bss` footprint (`0x400000`–`0xcdf9a0`, confirmed via `nm`/
|
||||
`readelf` on the exact build that produced the log). `stval` (0x74d8, ~30 KB)
|
||||
stayed fixed across rebuilds even as `sepc` drifted — the signature of a
|
||||
corrupted return address rather than a fixed logic bug at one source line.
|
||||
|
||||
## Investigation
|
||||
|
||||
Two dead ends were ruled out before the real cause surfaced:
|
||||
|
||||
1. **ELF relocation / buffer overlap in the split-build loader.** The
|
||||
codebase has a `!MONOLITHIC_BUILD` path (`elf_load_kernel()` in
|
||||
`elf_loader.c`) that loads `kernel.elf` from the ESP into a UEFI
|
||||
`AllocateAnyPages` buffer. This looked like a plausible overlap candidate
|
||||
at first, but `Makefile.starkernel` defaults to `MONOLITHIC=1`, meaning
|
||||
`kernel_main` is linked directly into the loader and that code path never
|
||||
runs. Confirmed by checking the built binary for the investigation's own
|
||||
diagnostic strings — absent, because the compilation unit was built with
|
||||
`-DMONOLITHIC_BUILD` and the code was preprocessed out.
|
||||
2. **`RAW_LOG()` silently no-ops on every non-amd64 arch.** All of
|
||||
`load_kernel_from_esp()`'s narration (and an early ConOut-based
|
||||
diagnostic) never reached the captured serial log, on riscv64, in any
|
||||
build. `RAW_LOG` was defined only for `ARCH_AMD64`; everywhere else it
|
||||
expanded to `((void)0)`. This made straightforward diagnosis impossible
|
||||
until a real raw-UART writer was added for riscv64 (see Secondary Fix).
|
||||
|
||||
With real output available, `console_println()` checkpoints were bisected
|
||||
through `vm_init_with_host()` and `sk_vm_bootstrap_parity()`. Every checkpoint
|
||||
inside `vm_init_with_host()` printed successfully, including the very last
|
||||
line of the function — but the checkpoint immediately after its *return*
|
||||
never appeared. Re-running with a trivial, unrelated local-variable addition
|
||||
shifted the crash earlier and changed the exception type entirely (from a
|
||||
load fault to an instruction-fetch fault at `sepc == stval`, i.e. the CPU
|
||||
tried to *execute* an unmapped address). A crash whose location and even
|
||||
category shift under unrelated code changes is the standard signature of
|
||||
stack corruption, not a fixed bug at a specific call site.
|
||||
|
||||
## Root Cause
|
||||
|
||||
`kernel_main.c` documented the gap directly, once read closely:
|
||||
|
||||
> On amd64, `kernel_entry.S` switches the stack from UEFI's default to a
|
||||
> 2 MiB zero-initialised BSS stack and tail-calls this function as
|
||||
> `kernel_main_impl`. On aarch64 and riscv64 the assembly trampoline is not
|
||||
> yet implemented and the UEFI loader calls `kernel_main` directly.
|
||||
|
||||
amd64 has carried a dedicated stack-switch trampoline
|
||||
(`src/starkernel/arch/amd64/kernel_entry.S`) since early on, with its own
|
||||
comment explaining why: *"UEFI hands control to kernel_main() running on a
|
||||
small UEFI-provided stack (typically 128 KB–256 KB). The FORTH interpreter +
|
||||
DOE experiment loop can easily exceed that depth."* riscv64 never had the
|
||||
equivalent. It ran the entire VM bootstrap — 27 chained word-registration
|
||||
modules, physics/SSM init, Tripod capsule birth — directly on whatever small
|
||||
stack EDK2's riscv64 firmware handed the loader, overflowing it and
|
||||
corrupting a return address. aarch64 has the same theoretical exposure but
|
||||
happens not to trip it, apparently because its firmware's default boot stack
|
||||
is larger — incidental, not a guarantee.
|
||||
|
||||
## Fix
|
||||
|
||||
**`src/starkernel/arch/riscv64/kernel_entry.S`** (new) — RISC-V stack-switch
|
||||
trampoline mirroring amd64's:
|
||||
|
||||
```asm
|
||||
.section .bss
|
||||
.align 4
|
||||
.global g_kernel_stack
|
||||
g_kernel_stack:
|
||||
.space 0x200000
|
||||
g_kernel_stack_top:
|
||||
.global g_kernel_stack_top
|
||||
|
||||
.section .text
|
||||
.extern kernel_main_impl
|
||||
.global kernel_main
|
||||
kernel_main:
|
||||
ld t0, BOOT_INFO_KERNEL_STACK_BASE_OFFSET(a0)
|
||||
bnez t0, .Ldynamic_stack
|
||||
la t0, g_kernel_stack_top
|
||||
j .Lstack_ready
|
||||
.Ldynamic_stack:
|
||||
ld t1, BOOT_INFO_KERNEL_STACK_SIZE_OFFSET(a0)
|
||||
add t0, t0, t1
|
||||
.Lstack_ready:
|
||||
andi t0, t0, -16
|
||||
mv sp, t0
|
||||
mv s0, zero
|
||||
tail kernel_main_impl
|
||||
```
|
||||
|
||||
**`src/starkernel/kernel_main.c`** — riscv64 now builds `kernel_main_impl`
|
||||
(invoked via the trampoline) instead of `kernel_main` directly, same pattern
|
||||
as amd64:
|
||||
|
||||
```c
|
||||
#if defined(__x86_64__) || defined(__riscv)
|
||||
void kernel_main_impl(BootInfo *boot_info) {
|
||||
#else
|
||||
void kernel_main(BootInfo *boot_info) {
|
||||
#endif
|
||||
```
|
||||
|
||||
**`Makefile.starkernel`** — wires the new file into the riscv64 loader build:
|
||||
|
||||
```makefile
|
||||
ifeq ($(ARCH),riscv64)
|
||||
LOADER_ASM += $(KERNEL_SRC)/arch/$(ARCH)/kernel_entry.S
|
||||
endif
|
||||
```
|
||||
|
||||
## Secondary Fix
|
||||
|
||||
`RAW_LOG()` in `src/starkernel/boot/uefi_loader.c` was a no-op on every arch
|
||||
except amd64, silencing all of the loader's own diagnostic messages on
|
||||
riscv64 (and aarch64). Added a real raw-UART writer for riscv64, targeting
|
||||
QEMU virt's 16550-compatible `uart8250` at MMIO `0x10000000` (matches
|
||||
`Domain0 Region03` in the OpenSBI boot banner) — the same byte-polling
|
||||
protocol as the existing amd64 port-I/O version, just MMIO instead of `outb`/
|
||||
`inb`. Existing and future `RAW_LOG()` call sites in the loader now actually
|
||||
produce output on riscv64.
|
||||
|
||||
## Result
|
||||
|
||||
| Criterion | Before | After |
|
||||
|---|---|---|
|
||||
| `sepc` after word registration | Wild address outside kernel image (`0xbe27c3c2`-ish, drifting per build) | N/A — no longer occurs |
|
||||
| Exception | Load or instruction-fetch page fault, non-deterministic between builds | None |
|
||||
| `[Hera] ok>` (riscv64) | Never reached | ✅ reached, Tripod fleet (Hera/Hermes/Artemis) runs to completion |
|
||||
| `PASS: E2E msg flow` | Never logged | ✅ |
|
||||
| `PARITY:MAMA_INIT` / `Init: Mama birth OK` | Never logged | ✅ |
|
||||
| Loader `RAW_LOG()` output on riscv64 | Silent no-op | ✅ visible in serial log |
|
||||
|
||||
## Acceptance Testing
|
||||
|
||||
All three architectures must boot to `ok>`, run the Tripod fleet, and reach
|
||||
`[Hera] ok>`. Per repo convention, run in this exact order, one QEMU instance
|
||||
at a time, always `clean` before `qemu`:
|
||||
|
||||
```bash
|
||||
make -f Makefile.starkernel ARCH=amd64 clean qemu
|
||||
make -f Makefile.starkernel ARCH=aarch64 clean qemu
|
||||
make -f Makefile.starkernel ARCH=riscv64 clean qemu
|
||||
```
|
||||
|
||||
Verify each log:
|
||||
|
||||
```bash
|
||||
grep "ok>" logs/<session>/<arch>/qemu-<arch>-*.log
|
||||
grep "PASS: E2E msg flow" logs/<session>/<arch>/qemu-<arch>-*.log
|
||||
grep "PARITY:MAMA_INIT" logs/<session>/<arch>/qemu-<arch>-*.log
|
||||
grep "EXCEPTION" logs/<session>/<arch>/qemu-<arch>-*.log # must be empty
|
||||
```
|
||||
|
||||
All three architectures confirmed clean on 2026-08-02 (see
|
||||
`logs/20260802-064050/riscv64/`, `logs/20260802-064424/amd64/`,
|
||||
`logs/20260802-064656/aarch64/`, committed alongside this fix).
|
||||
@@ -0,0 +1,198 @@
|
||||
> **HISTORICAL (docs triage 2026-10-14).** An orientation page for the old docs/lithosananke/ folder, flagged partly stale on 2026-10-09; the folder is gone (its parts are in docs/reference/ and this archive).
|
||||
> Instead: docs/README.md. Moved here from `docs/lithosananke/README.md`.
|
||||
|
||||
# LithosAnanke — StarForth Kernel Branch
|
||||
|
||||
> **⚠ PARTIALLY STALE (flagged 2026-10-09).** This page predates the repo split and the
|
||||
> Tripod/kernel reshuffle. There is no `lithosananke` branch in this repo — `master` is the
|
||||
> sole production line — and the VM fleet is now **Hera / Artemis / Hestia** (the Hermes VM
|
||||
> was removed; messaging moved into the kernel as kernel-Hermes). M7.1 is **live**, not
|
||||
> merely designed. For authoritative status see `.claude/CLAUDE.md` and
|
||||
> `docs/fabric/FABRIC-2.md` / `FABRIC-3.md` / `FABRIC-3.5.md` / `FABRIC-3.6.md`; for the
|
||||
> milestone plan see `ROADMAP.md` (this file is an orientation page).
|
||||
|
||||
**Line:** `master` (sole production line post-split)
|
||||
**Status:** M7 Complete (VM Parity) · M7.1 Live (capsules, Tripod, Stadium, word-level ACL Phases 1–7)
|
||||
|
||||
---
|
||||
|
||||
## 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** | **Capsules · Tripod · Stadium · ACL** | **Live** (see FABRIC docs) |
|
||||
| M8 | REPL (keyboard input) | Superseded — see FABRIC-0 §25.5 item 4.4 |
|
||||
| M9 | Block Storage / Block I/O | Live (virtio-blk + block subsystem) |
|
||||
|
||||
---
|
||||
|
||||
## Build & Run
|
||||
|
||||
```bash
|
||||
# Build kernel with VM integration (loader + kernel)
|
||||
make -f kernel/Makefile ARCH=amd64 STARFORTH_ENABLE_VM=1
|
||||
|
||||
# Run in QEMU
|
||||
make -f kernel/Makefile ARCH=amd64 STARFORTH_ENABLE_VM=1 qemu
|
||||
|
||||
# Other architectures
|
||||
make -f kernel/Makefile ARCH=aarch64 qemu
|
||||
make -f kernel/Makefile ARCH=riscv64 qemu
|
||||
```
|
||||
|
||||
**Output artifacts:**
|
||||
- `build/amd64/kernel/starkernel_loader.efi` — UEFI loader
|
||||
- `build/amd64/kernel/starkernel_kernel.elf` — Kernel binary
|
||||
|
||||
---
|
||||
|
||||
## Documentation
|
||||
|
||||
### Core Design
|
||||
|
||||
| Document | Description |
|
||||
|----------|-------------|
|
||||
| [M7.1.md](M7.1.md) | Init Capsule Architecture |
|
||||
| [ROADMAP.md](ROADMAP.md) | Milestone roadmap |
|
||||
| [amd64-isr-fix/README.md](amd64-isr-fix/README.md) | APIC timer ISR fix + kernel 3-arch acceptance test |
|
||||
| [hosted-acceptance-test/README.md](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/overview.md) | HAL architecture and principles |
|
||||
| [hal/interfaces.md](hal/interfaces.md) | HAL interface specifications |
|
||||
| [hal/lithosananke-integration.md](hal/lithosananke-integration.md) | Kernel-specific HAL implementation |
|
||||
| [hal/platform-implementations.md](hal/platform-implementations.md) | Platform implementation guide |
|
||||
| [hal/migration-plan.md](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 contributing rules are:
|
||||
|
||||
1. Maintain parity validation (M7 baseline)
|
||||
2. Pass the three-arch QEMU boot test (`ARCH={amd64,aarch64,riscv64}`)
|
||||
3. Not break the hosted VM build (plain `make` at the repo root)
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- [StarForth README](../../README.md) — Main project
|
||||
- [FORTH-79 Standard](http://www.forth.org/forth-79.html)
|
||||
- [OSDev Wiki](https://wiki.osdev.org/)
|
||||
- [UEFI Specification](https://uefi.org/specifications)
|
||||
@@ -47,7 +47,7 @@ that actually matters).
|
||||
|
||||
## 2. Fix the broken riscv64 command in this branch's acceptance-test doc
|
||||
|
||||
`docs/lithosananke/hosted-acceptance-test/README.md` still documents the
|
||||
`docs/reference/hosted-acceptance-test/README.md` still documents the
|
||||
riscv64 leg using `riscv64-linux-gnu-gcc`, which cannot build this tree
|
||||
(`nanosleep` visibility failure under `-std=c99`, unrelated to any project
|
||||
change). This was already fixed in `master`'s `.claude/CLAUDE.md` (the
|
||||
@@ -152,6 +152,6 @@ now — just flagging.
|
||||
open item if anyone wants to chase it down.
|
||||
- Today's aarch64/riscv64 `.hidden` ISR hardening (commit `5fe188bd`) only
|
||||
has a CHANGELOG entry, not a dedicated writeup the way
|
||||
`docs/lithosananke/amd64-isr-fix/README.md` documents the original amd64
|
||||
`docs/working/archive/historical/2026-07-amd64-isr-fix/README.md` documents the original amd64
|
||||
fix. Not urgent — the CHANGELOG entry covers it — but noting the
|
||||
asymmetry in case someone later wants doc parity.
|
||||
|
||||
@@ -0,0 +1,666 @@
|
||||
> **SUPERSEDED (docs triage 2026-10-14).** The StarForth-era VM -> kernel -> OS -> FPGA plan of 2025-12-14, flagged obsolete 2026-08-26.
|
||||
> Instead: docs/reference/ROADMAP.md (the LithosAnanke roadmap and versioning policy). Moved here from `docs/ROADMAP.md`.
|
||||
|
||||
# StarForth Roadmap: VM → Kernel → OS → FPGA
|
||||
|
||||
> **OBSOLETE (flagged 2026-08-26, Captain Bob's call — this is more than "stale," the
|
||||
> architecture, branch topology, and terminology it describes no longer exist).** This is a
|
||||
> StarForth-era plan dated 2025-12-14, written before the repo split, before
|
||||
> Tripod/Stadium/word-level ACL existed, and before "Phase 1 Starting (HAL)" had any of the
|
||||
> meaning it has now. Kept for historical record only. For current status, see
|
||||
> `docs/reference/ROADMAP.md` (repo-specific, LithosAnanke roadmap) and
|
||||
> `FABRIC-0.md`/`FABRIC-1.md`/`FABRIC-2.md` (design history and current work) — not this
|
||||
> document.
|
||||
|
||||
**Version**: 1.0
|
||||
**Date**: 2025-12-14
|
||||
**Timeline**: 2025-2028 (3.5 years)
|
||||
**Status**: Phase 0 Complete (VM), Phase 1 Starting (HAL)
|
||||
|
||||
---
|
||||
|
||||
## VISION
|
||||
|
||||
**From**: Adaptive FORTH VM running on hosted OS (Linux)
|
||||
**To**: Self-hosting operating system running on custom FPGA hardware
|
||||
|
||||
```
|
||||
2025 (NOW) 2026 2027 2028
|
||||
│ │ │ │
|
||||
V V V V
|
||||
┌─────────┐ ┌──────────┐ ┌────────────┐ ┌──────────┐
|
||||
│StarForth│ → │StarKernel│ → │ StarshipOS │ → │ FPGA │
|
||||
│ VM │ │(Bare Metal) │(Self-hosting) │ Hardware │
|
||||
└─────────┘ └──────────┘ └────────────┘ └──────────┘
|
||||
COMPLETE 6-8 months 12-18 months 12-18 months
|
||||
```
|
||||
|
||||
**Key Principle**: Each phase builds on the previous. No skipping steps.
|
||||
|
||||
---
|
||||
|
||||
## CURRENT STATE (Phase 0: COMPLETE ✅)
|
||||
|
||||
### What We Have
|
||||
|
||||
**StarForth VM** - Production-ready adaptive FORTH interpreter:
|
||||
- ✅ FORTH-79 compliant (780+ tests passing)
|
||||
- ✅ Adaptive runtime (7 feedback loops, 0% algorithmic variance)
|
||||
- ✅ Platforms: Linux (HISTORICAL: also L4Re/Fiasco.OC through mid-2026; removed as an active target)
|
||||
- ✅ Performance: 100M iterations/sec, profile-guided optimization
|
||||
- ✅ Quality: 9.2/10 codebase rating, strict ANSI C99
|
||||
- ✅ Validation: Peer-reviewed, 90-run statistical proof
|
||||
- ✅ Patent pending: Adaptive runtime mechanisms
|
||||
|
||||
**Documentation**:
|
||||
- ✅ 121-page academic paper
|
||||
- ✅ Scientific defense documents (9 files)
|
||||
- ✅ Ontology & formal definitions
|
||||
- ✅ HAL architecture (documented, not implemented)
|
||||
|
||||
**Infrastructure**:
|
||||
- ✅ Make-based build system (40+ targets)
|
||||
- ✅ DoE (Design of Experiments) framework
|
||||
- ✅ Reproducibility guarantees
|
||||
- ✅ CI-ready test suite
|
||||
|
||||
### What's Missing
|
||||
|
||||
**See**: [docs/GAP_ANALYSIS.md](docs/GAP_ANALYSIS.md) for complete list (37 gaps identified)
|
||||
|
||||
**Critical Blockers**:
|
||||
1. HAL abstraction layer (8 components) - **Blocks everything**
|
||||
2. StarKernel implementation (13 components)
|
||||
3. StarshipOS subsystems (12 components)
|
||||
4. FPGA feasibility & design (19 components)
|
||||
|
||||
---
|
||||
|
||||
## PHASE 1: HAL IMPLEMENTATION (Months 1-2)
|
||||
|
||||
**Goal**: Make StarForth platform-agnostic via Hardware Abstraction Layer
|
||||
|
||||
**Why**: HAL is the foundation for all future work. Without HAL, cannot build kernel or port to FPGA.
|
||||
|
||||
### Deliverables
|
||||
|
||||
| # | Component | LOC | Duration | Status |
|
||||
|---|-----------|-----|----------|--------|
|
||||
| 1.1 | Define HAL interfaces (6 headers) | 500 | 1 week | 📋 Planned |
|
||||
| 1.2 | Implement Linux HAL | 1500 | 2 weeks | 📋 Planned |
|
||||
| 1.3 | Migrate VM core to HAL | 800 | 2 weeks | 📋 Planned |
|
||||
| 1.4 | Migrate physics subsystems | 300 | 1 week | 📋 Planned |
|
||||
| 1.5 | Validate determinism (DoE) | Testing | 2 days | 📋 Planned |
|
||||
|
||||
**Total**: ~3,100 LOC, 6-7 weeks
|
||||
|
||||
### Success Criteria
|
||||
|
||||
- ✅ All HAL interface headers exist (`hal_time.h`, `hal_interrupt.h`, etc.)
|
||||
- ✅ Linux HAL implementation complete
|
||||
- ✅ VM core has zero direct platform dependencies
|
||||
- ✅ All 780+ tests pass on HAL
|
||||
- ✅ 0% algorithmic variance maintained
|
||||
- ✅ No measurable performance regression
|
||||
|
||||
### Milestones
|
||||
|
||||
**Week 2**: HAL headers defined, Linux implementation started
|
||||
**Week 4**: Linux HAL complete, VM migration started
|
||||
**Week 6**: All tests passing, determinism validated
|
||||
|
||||
**Blocker Risk**: Low (well-understood refactoring)
|
||||
|
||||
---
|
||||
|
||||
## PHASE 2: STARKERNEL (Months 3-5)
|
||||
|
||||
**Goal**: Boot StarForth on bare metal (UEFI → kernel → "ok" prompt)
|
||||
|
||||
**Why**: Kernel enables true OS development and demonstrates platform independence.
|
||||
|
||||
### Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ UEFI Firmware │
|
||||
│ • Memory map, ACPI, framebuffer │
|
||||
└────────────────┬────────────────────────────┘
|
||||
│ ExitBootServices()
|
||||
▼
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ StarKernel Boot (boot/uefi_loader.c) │
|
||||
│ • Collect BootInfo │
|
||||
│ • Jump to kernel_main() │
|
||||
└────────────────┬────────────────────────────┘
|
||||
▼
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ StarKernel HAL (platform/kernel/) │
|
||||
│ • CPU init (GDT, IDT, interrupts) │
|
||||
│ • Memory (PMM, VMM, heap) │
|
||||
│ • Time (TSC, HPET, APIC timer) │
|
||||
│ • Console (UART + framebuffer) │
|
||||
└────────────────┬────────────────────────────┘
|
||||
▼
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ StarForth VM │
|
||||
│ • vm_create() │
|
||||
│ • Physics subsystems │
|
||||
│ • REPL → "ok" prompt │
|
||||
└─────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Deliverables
|
||||
|
||||
| # | Component | LOC | Duration | Status |
|
||||
|---|-----------|-----|----------|--------|
|
||||
| 2.1 | UEFI boot loader | 800 | 2 weeks | 📋 Planned |
|
||||
| 2.2 | Physical memory manager (PMM) | 1200 | 2 weeks | 📋 Planned |
|
||||
| 2.3 | Virtual memory manager (VMM) | 1500 | 2 weeks | 📋 Planned |
|
||||
| 2.4 | Kernel heap (kmalloc) | 800 | 1 week | 📋 Planned |
|
||||
| 2.5 | CPU initialization (GDT/IDT) | 1000 | 1 week | 📋 Planned |
|
||||
| 2.6 | UART driver (serial console) | 600 | 1 week | 📋 Planned |
|
||||
| 2.7 | Time subsystem (TSC/HPET) | 1000 | 2 weeks | 📋 Planned |
|
||||
| 2.8 | APIC interrupt controller | 1200 | 2 weeks | 📋 Planned |
|
||||
| 2.9 | Framebuffer driver | 800 | 1 week | 📋 Planned |
|
||||
| 2.10 | ACPI parsing | 600 | 1 week | 📋 Planned |
|
||||
| 2.11 | HAL implementation (kernel) | 1000 | 2 weeks | 📋 Planned |
|
||||
| 2.12 | Build system integration | 500 | 1 week | 📋 Planned |
|
||||
|
||||
**Total**: ~11,000 LOC, 12-14 weeks
|
||||
|
||||
### Success Criteria
|
||||
|
||||
- ✅ UEFI boots on QEMU + OVMF
|
||||
- ✅ Serial console prints "StarKernel booting..."
|
||||
- ✅ PMM/VMM allocate memory correctly
|
||||
- ✅ Kernel heap works (kmalloc/kfree)
|
||||
- ✅ Interrupts and timers functional
|
||||
- ✅ VM starts and prints "ok" prompt
|
||||
- ✅ Can execute simple FORTH code (`1 2 + .` → `3`)
|
||||
- ✅ Physics subsystems operational on bare metal
|
||||
|
||||
### Milestones
|
||||
|
||||
**Month 3**: UEFI boot + serial output working
|
||||
**Month 4**: Memory managers complete, VM starts
|
||||
**Month 5**: Full HAL working, "ok" prompt on QEMU
|
||||
|
||||
**Blocker Risk**: Medium (complex low-level code, but well-documented)
|
||||
|
||||
### Testing Strategy
|
||||
|
||||
**Development**: QEMU with OVMF (UEFI firmware)
|
||||
**Validation**: Physical hardware (Intel NUC or similar)
|
||||
**Automation**: QEMU headless testing in CI
|
||||
|
||||
---
|
||||
|
||||
## PHASE 3: STARSHIPOS (Months 6-18)
|
||||
|
||||
**Goal**: Self-hosting operating system (compiles itself, runs applications)
|
||||
|
||||
**Why**: Demonstrates complete independence from Linux/POSIX, enables FORTH-native ecosystem.
|
||||
|
||||
### Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ StarshipOS Layers │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ Userland │
|
||||
│ • Shell, editors, compilers, tools │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ System Services │
|
||||
│ • Filesystem (FAT32 or custom) │
|
||||
│ • Networking (TCP/IP stack) │
|
||||
│ • Process manager, scheduler │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ Drivers │
|
||||
│ • Storage (AHCI, NVMe) │
|
||||
│ • Network (VirtIO, E1000) │
|
||||
│ • Block/char device abstraction │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ StarKernel (from Phase 2) │
|
||||
│ • CPU, memory, time, interrupts │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Deliverables (Staged)
|
||||
|
||||
#### Stage 3A: Storage (Months 6-9)
|
||||
|
||||
| # | Component | LOC | Duration | Status |
|
||||
|---|-----------|-----|----------|--------|
|
||||
| 3.1 | AHCI driver | 2500 | 1 month | 📋 Planned |
|
||||
| 3.2 | NVMe driver | 2000 | 1 month | 📋 Planned |
|
||||
| 3.3 | Block device abstraction | 1500 | 2 weeks | 📋 Planned |
|
||||
| 3.4 | FAT32 filesystem | 3000 | 1 month | 📋 Planned |
|
||||
| 3.5 | VFS layer | 2000 | 2 weeks | 📋 Planned |
|
||||
|
||||
**Subtotal**: ~11,000 LOC, 3-4 months
|
||||
|
||||
**Success Criteria**:
|
||||
- ✅ Read/write files to disk
|
||||
- ✅ Boot from hard drive (not just RAM)
|
||||
- ✅ Persistent FORTH definitions
|
||||
|
||||
---
|
||||
|
||||
#### Stage 3B: Networking (Months 10-12)
|
||||
|
||||
| # | Component | LOC | Duration | Status |
|
||||
|---|-----------|-----|----------|--------|
|
||||
| 3.6 | VirtIO-net driver | 2000 | 1 month | 📋 Planned |
|
||||
| 3.7 | E1000 driver | 1500 | 2 weeks | 📋 Planned |
|
||||
| 3.8 | lwIP TCP/IP stack (port) | 8000 | 2 months | 📋 Planned |
|
||||
| 3.9 | Socket API (FORTH-native) | 1500 | 2 weeks | 📋 Planned |
|
||||
|
||||
**Subtotal**: ~13,000 LOC, 3-4 months
|
||||
|
||||
**Success Criteria**:
|
||||
- ✅ Send/receive packets
|
||||
- ✅ TCP connections work
|
||||
- ✅ Simple HTTP server in FORTH
|
||||
|
||||
---
|
||||
|
||||
#### Stage 3C: Process Model (Months 13-15)
|
||||
|
||||
| # | Component | LOC | Duration | Status |
|
||||
|---|-----------|-----|----------|--------|
|
||||
| 3.10 | FORTH task abstraction | 2000 | 1 month | 📋 Planned |
|
||||
| 3.11 | Scheduler (round-robin) | 1500 | 2 weeks | 📋 Planned |
|
||||
| 3.12 | IPC mechanism | 2500 | 1 month | 📋 Planned |
|
||||
| 3.13 | System call interface | 1000 | 2 weeks | 📋 Planned |
|
||||
|
||||
**Subtotal**: ~7,000 LOC, 2-3 months
|
||||
|
||||
**Success Criteria**:
|
||||
- ✅ Multiple concurrent tasks
|
||||
- ✅ Task switching works
|
||||
- ✅ Tasks can communicate (send/receive)
|
||||
|
||||
---
|
||||
|
||||
#### Stage 3D: Self-Hosting (Months 16-18)
|
||||
|
||||
| # | Component | LOC | Duration | Status |
|
||||
|---|-----------|-----|----------|--------|
|
||||
| 3.14 | FORTH compiler (meta-compilation) | 3000 | 1 month | 📋 Planned |
|
||||
| 3.15 | Assembler (FORTH-hosted) | 2000 | 2 weeks | 📋 Planned |
|
||||
| 3.16 | Linker/loader | 1500 | 2 weeks | 📋 Planned |
|
||||
| 3.17 | Shell & core utilities | 2500 | 1 month | 📋 Planned |
|
||||
| 3.18 | Build system (FORTH-based) | 1000 | 2 weeks | 📋 Planned |
|
||||
|
||||
**Subtotal**: ~10,000 LOC, 2-3 months
|
||||
|
||||
**Success Criteria**:
|
||||
- ✅ StarshipOS compiles itself
|
||||
- ✅ No dependency on Linux toolchain
|
||||
- ✅ Can build applications entirely in FORTH
|
||||
|
||||
---
|
||||
|
||||
**Phase 3 Total**: ~41,000 LOC, 12-15 months
|
||||
|
||||
### Milestones
|
||||
|
||||
**Month 9**: Persistent storage working, boot from disk
|
||||
**Month 12**: Network stack operational, HTTP demo
|
||||
**Month 15**: Multitasking working, IPC functional
|
||||
**Month 18**: Self-hosting achieved, OS compiles itself
|
||||
|
||||
**Blocker Risk**: High (large scope, complex subsystems)
|
||||
|
||||
**De-risking Strategy**: Port existing code where possible (lwIP for TCP/IP, FAT32 reference)
|
||||
|
||||
---
|
||||
|
||||
## PHASE 4: FPGA FEASIBILITY (Months 6-7)
|
||||
|
||||
**Goal**: Determine if FPGA implementation is worth pursuing
|
||||
|
||||
**Why**: FPGA is a massive investment (12-18 months). Need go/no-go decision before committing.
|
||||
|
||||
### Feasibility Study
|
||||
|
||||
| # | Task | Duration | Deliverable |
|
||||
|---|------|----------|-------------|
|
||||
| 4.1 | Survey existing FORTH FPGA cores | 1 week | Comparison table |
|
||||
| 4.2 | Estimate resource usage (LUTs, BRAMs) | 3 days | Resource budget |
|
||||
| 4.3 | Select target FPGA | 3 days | FPGA selection rationale |
|
||||
| 4.4 | Prototype stack machine (Verilog) | 2 weeks | Minimal stack machine |
|
||||
| 4.5 | Synthesize & test on FPGA board | 1 week | Synthesis report |
|
||||
| 4.6 | Performance analysis | 3 days | Speed vs. software |
|
||||
| 4.7 | Cost/benefit analysis | 2 days | Go/no-go recommendation |
|
||||
|
||||
**Total**: 5-6 weeks
|
||||
|
||||
### Decision Criteria
|
||||
|
||||
**GO if**:
|
||||
- ✅ Fits in affordable FPGA (~$200-500 board)
|
||||
- ✅ Performance ≥ 50 MHz clock (faster than software?)
|
||||
- ✅ Adaptive runtime feasible in hardware (critical!)
|
||||
- ✅ Development time justified by benefits
|
||||
|
||||
**NO-GO if**:
|
||||
- ❌ Too large for affordable FPGAs
|
||||
- ❌ Slower than software implementation
|
||||
- ❌ Adaptive runtime not synthesizable
|
||||
- ❌ >18 months to implement (opportunity cost too high)
|
||||
|
||||
### Prototype Spec
|
||||
|
||||
**Minimal Stack Machine** (proof of concept):
|
||||
- Data stack (16 entries × 64-bit)
|
||||
- Return stack (16 entries × 64-bit)
|
||||
- Basic operations: +, -, *, /, DUP, DROP, SWAP
|
||||
- Dictionary ROM (256 entries)
|
||||
- Simple UART I/O
|
||||
|
||||
**Target**: Prove concept works in hardware, get resource usage numbers
|
||||
|
||||
---
|
||||
|
||||
## PHASE 5: FPGA IMPLEMENTATION (Months 8-24)
|
||||
|
||||
**Status**: CONDITIONAL (only if Phase 4 says GO)
|
||||
|
||||
**Goal**: Hardware FORTH processor on FPGA
|
||||
|
||||
### Architecture
|
||||
|
||||
```
|
||||
┌────────────────────────────────────────────────┐
|
||||
│ FPGA Top Module │
|
||||
├────────────────────────────────────────────────┤
|
||||
│ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ Stack Machine│ │ Memory │ │
|
||||
│ │ • Data stack│ │ Controller │ │
|
||||
│ │ • Return stk│ │ • Dict ROM │ │
|
||||
│ │ • ALU │ │ • RAM │ │
|
||||
│ └──────────────┘ └──────────────┘ │
|
||||
├────────────────────────────────────────────────┤
|
||||
│ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ UART │ │ Timers │ │
|
||||
│ │ IP Core │ │ Counters │ │
|
||||
│ └──────────────┘ └──────────────┘ │
|
||||
├────────────────────────────────────────────────┤
|
||||
│ ┌──────────────────────────────────────────┐ │
|
||||
│ │ Adaptive Runtime (if feasible) │ │
|
||||
│ │ • Execution counters │ │
|
||||
│ │ • Hot-word cache │ │
|
||||
│ │ • Hardware decay (?) │ │
|
||||
│ └──────────────────────────────────────────┘ │
|
||||
└────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Deliverables
|
||||
|
||||
#### Stage 5A: Core Implementation (Months 8-13)
|
||||
|
||||
| # | Component | LOC (HDL) | Duration | Status |
|
||||
|---|-----------|-----------|----------|--------|
|
||||
| 5.1 | Data stack (16 deep) | 500 | 2 weeks | 📋 Conditional |
|
||||
| 5.2 | Return stack (16 deep) | 500 | 2 weeks | 📋 Conditional |
|
||||
| 5.3 | ALU (arithmetic/logic ops) | 2000 | 1 month | 📋 Conditional |
|
||||
| 5.4 | Dictionary memory (ROM) | 1000 | 2 weeks | 📋 Conditional |
|
||||
| 5.5 | RAM controller | 1500 | 3 weeks | 📋 Conditional |
|
||||
| 5.6 | Instruction decoder | 2000 | 1 month | 📋 Conditional |
|
||||
| 5.7 | Control FSM | 1500 | 3 weeks | 📋 Conditional |
|
||||
|
||||
**Subtotal**: ~9,000 lines Verilog, 4-5 months
|
||||
|
||||
---
|
||||
|
||||
#### Stage 5B: I/O & Peripherals (Months 14-16)
|
||||
|
||||
| # | Component | LOC (HDL) | Duration | Status |
|
||||
|---|-----------|-----------|----------|--------|
|
||||
| 5.8 | UART transmitter/receiver | 800 | 2 weeks | 📋 Conditional |
|
||||
| 5.9 | Timer/counter IP cores | 600 | 1 week | 📋 Conditional |
|
||||
| 5.10 | Interrupt controller | 1000 | 2 weeks | 📋 Conditional |
|
||||
| 5.11 | Memory-mapped I/O bus | 1200 | 3 weeks | 📋 Conditional |
|
||||
|
||||
**Subtotal**: ~3,600 lines Verilog, 2-3 months
|
||||
|
||||
---
|
||||
|
||||
#### Stage 5C: Adaptive Runtime (Months 17-20)
|
||||
|
||||
**CRITICAL UNCERTAINTY**: Can we synthesize this?
|
||||
|
||||
| # | Component | LOC (HDL) | Duration | Status |
|
||||
|---|-----------|-----------|----------|--------|
|
||||
| 5.12 | Execution frequency counters | 1500 | 1 month | 📋 Conditional |
|
||||
| 5.13 | Hot-word cache (top-K) | 2000 | 1 month | 📋 Conditional |
|
||||
| 5.14 | Hardware decay logic | 1000 | 2 weeks | 📋 Conditional |
|
||||
| 5.15 | Transition tracking | 1500 | 3 weeks | 📋 Conditional |
|
||||
|
||||
**Subtotal**: ~6,000 lines Verilog, 3-4 months
|
||||
|
||||
**Fallback**: If adaptive runtime doesn't synthesize well, implement in software on soft-core CPU (MicroBlaze/NIOS II) alongside FORTH core.
|
||||
|
||||
---
|
||||
|
||||
#### Stage 5D: Validation & Optimization (Months 21-24)
|
||||
|
||||
| # | Task | Duration | Deliverable |
|
||||
|---|------|----------|-------------|
|
||||
| 5.16 | Testbench (all modules) | 2 months | 100% coverage |
|
||||
| 5.17 | Formal verification (critical paths) | 1 month | Proofs |
|
||||
| 5.18 | Synthesis optimization | 1 month | Timing closure |
|
||||
| 5.19 | Hardware-in-loop testing | 2 weeks | Physical validation |
|
||||
| 5.20 | Performance tuning | 2 weeks | Final optimizations |
|
||||
|
||||
**Subtotal**: 4-5 months
|
||||
|
||||
---
|
||||
|
||||
**Phase 5 Total**: ~18,600 lines Verilog + testbenches, 15-18 months
|
||||
|
||||
### Target FPGAs (Options)
|
||||
|
||||
| FPGA | Cost | Resources | Speed | Notes |
|
||||
|------|------|-----------|-------|-------|
|
||||
| **Xilinx Zynq-7000** | $300 | 85K LUTs, ARM core | 200 MHz | **Recommended**: Hybrid ARM+FPGA |
|
||||
| Intel Cyclone V | $250 | 77K LEs | 150 MHz | Good alternative |
|
||||
| Lattice iCE40 UP5K | $50 | 5K LUTs | 50 MHz | Budget option, slower |
|
||||
| Xilinx Artix-7 | $200 | 33K LUTs | 200 MHz | Pure FPGA, no ARM |
|
||||
|
||||
**Recommendation**: Zynq-7000 (ARM + FPGA fabric)
|
||||
- Run StarshipOS on ARM
|
||||
- Offload FORTH core to FPGA fabric
|
||||
- Best of both worlds
|
||||
|
||||
### Success Criteria
|
||||
|
||||
- ✅ FPGA boots, prints "ok" via UART
|
||||
- ✅ Can execute FORTH code
|
||||
- ✅ Performance ≥ software on same workload
|
||||
- ✅ Adaptive runtime functional (or gracefully degraded)
|
||||
- ✅ 780+ tests pass on hardware
|
||||
- ✅ 0% algorithmic variance maintained (if adaptive works)
|
||||
|
||||
### Milestones
|
||||
|
||||
**Month 13**: Core stack machine working in simulation
|
||||
**Month 16**: I/O functional, boots on real FPGA
|
||||
**Month 20**: Adaptive runtime implemented (or fallback decided)
|
||||
**Month 24**: Full validation, production-ready FPGA core
|
||||
|
||||
**Blocker Risk**: VERY HIGH
|
||||
- HDL expertise required
|
||||
- Timing closure can be unpredictable
|
||||
- Adaptive runtime may not be synthesizable
|
||||
- Resource constraints on affordable FPGAs
|
||||
|
||||
---
|
||||
|
||||
## INTEGRATION TIMELINE
|
||||
|
||||
### Parallel Paths
|
||||
|
||||
**Months 1-5**: Sequential (HAL → Kernel)
|
||||
**Months 6-18**: **Parallel** (OS + FPGA feasibility)
|
||||
**Months 8-24**: **Conditional** (FPGA impl if feasible)
|
||||
|
||||
```
|
||||
2025 2026 2027 2028
|
||||
│ │ │ │
|
||||
V V V V
|
||||
Phase 1 Phase 2 Phase 3 Phase 5
|
||||
HAL Kernel OS FPGA
|
||||
(2m) (3m) ┌──────────────────(12m)────────────┐ (16m)
|
||||
│ │ │ │
|
||||
│ Phase 4: Feasibility (2m) │ │
|
||||
│ └─────┬─────────────────────────────┘ │
|
||||
│ │ │
|
||||
└────────────────┴──GO/NO-GO Decision───────────────┘
|
||||
│
|
||||
If NO-GO: Focus on OS only
|
||||
If GO: Parallel OS + FPGA work
|
||||
```
|
||||
|
||||
### Resource Allocation (Solo Development)
|
||||
|
||||
**Months 1-5** (HAL + Kernel): 100% focus
|
||||
**Months 6-7** (Feasibility): 80% OS, 20% FPGA study
|
||||
**Months 8-18** (Parallel): 70% OS, 30% FPGA (if GO)
|
||||
**Months 19-24** (FPGA finish): 50% OS, 50% FPGA
|
||||
|
||||
**Community Contributions**: Welcomed at all stages (see CONTRIBUTING.md)
|
||||
|
||||
---
|
||||
|
||||
## RISK MITIGATION
|
||||
|
||||
### High-Risk Items
|
||||
|
||||
| Risk | Probability | Impact | Mitigation |
|
||||
|------|-------------|--------|------------|
|
||||
| **HAL breaks determinism** | Low | Critical | Extensive testing, DoE validation |
|
||||
| **Kernel never boots** | Medium | Critical | Incremental dev, QEMU testing |
|
||||
| **FPGA too slow** | Medium | High | Feasibility study gates investment |
|
||||
| **Adaptive runtime unsynthesizable** | High | High | Software fallback on ARM core |
|
||||
| **Project too large (solo)** | High | Medium | Community outreach, phased delivery |
|
||||
| **FPGA cost too high** | Low | Medium | Target affordable boards ($200-500) |
|
||||
|
||||
### Fallback Plans
|
||||
|
||||
**If HAL migration fails**: Continue hosted-only, defer kernel
|
||||
**If OS scope too large**: Deliver minimal components (storage + network only)
|
||||
**If FPGA infeasible**: Software-only path is still valuable
|
||||
|
||||
---
|
||||
|
||||
## DELIVERABLES SUMMARY
|
||||
|
||||
### By End of 2025 (Months 1-2)
|
||||
- ✅ HAL implementation complete
|
||||
- ✅ StarForth platform-agnostic
|
||||
- ✅ All tests passing on HAL
|
||||
|
||||
### By Mid-2026 (Months 3-5)
|
||||
- ✅ StarKernel boots to "ok" on QEMU
|
||||
- ✅ Physics subsystems work on bare metal
|
||||
|
||||
### By End of 2026 (Months 6-12)
|
||||
- ✅ Storage subsystem operational
|
||||
- ✅ Network stack functional
|
||||
- ✅ FPGA feasibility determined (GO/NO-GO)
|
||||
|
||||
### By Mid-2027 (Months 13-18)
|
||||
- ✅ Process model working
|
||||
- ✅ StarshipOS self-hosting
|
||||
- ✅ (If FPGA GO): Prototype FPGA core functional
|
||||
|
||||
### By End of 2027 (Months 19-24)
|
||||
- ✅ StarshipOS production-ready
|
||||
- ✅ (If FPGA GO): FPGA core validated
|
||||
|
||||
### By 2028 (Future)
|
||||
- 🎯 Ecosystem growth (applications, libraries)
|
||||
- 🎯 FPGA optimizations & variants
|
||||
- 🎯 Community-driven features
|
||||
|
||||
---
|
||||
|
||||
## SUCCESS METRICS
|
||||
|
||||
### Technical Metrics
|
||||
|
||||
| Metric | Target | Measurement |
|
||||
|--------|--------|-------------|
|
||||
| **HAL overhead** | <5% | Benchmark comparison |
|
||||
| **Kernel boot time** | <1 second | QEMU timing |
|
||||
| **OS compile speed** | <10 min | Self-hosting build |
|
||||
| **FPGA clock speed** | ≥50 MHz | Synthesis report |
|
||||
| **Test pass rate** | 100% (780+) | All platforms |
|
||||
| **Determinism** | 0% CV | DoE validation |
|
||||
|
||||
### Project Health Metrics
|
||||
|
||||
| Metric | Target | Current |
|
||||
|--------|--------|---------|
|
||||
| **Code quality** | ≥9.0/10 | 9.2/10 ✅ |
|
||||
| **Test coverage** | ≥80% | ~90% ✅ |
|
||||
| **Documentation** | Complete | Strong ✅ |
|
||||
| **Community** | ≥10 contributors | 1 (solo) |
|
||||
| **GitHub stars** | ≥500 | TBD |
|
||||
|
||||
---
|
||||
|
||||
## COMMUNITY & ECOSYSTEM
|
||||
|
||||
### How to Contribute
|
||||
|
||||
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
|
||||
|
||||
**High-value contributions**:
|
||||
1. HAL implementations (new platforms)
|
||||
2. Kernel drivers (AHCI, NVMe, network)
|
||||
3. FPGA expertise (Verilog, synthesis)
|
||||
4. Testing & validation
|
||||
5. Documentation improvements
|
||||
|
||||
### Seeking Collaborators
|
||||
|
||||
**Needed expertise**:
|
||||
- Kernel development (UEFI, memory management)
|
||||
- FPGA design (Verilog/VHDL)
|
||||
- OS design (filesystems, networking)
|
||||
- Formal verification (HDL proofs)
|
||||
|
||||
**Contact**: rajames440@gmail.com (Robert A. James)
|
||||
|
||||
---
|
||||
|
||||
## CONCLUSION
|
||||
|
||||
**This roadmap is ambitious but achievable.**
|
||||
|
||||
**Key Success Factors**:
|
||||
1. ✅ Strong foundation (Phase 0 complete)
|
||||
2. ✅ Clear milestones (phased delivery)
|
||||
3. ✅ Risk mitigation (fallback plans)
|
||||
4. ⚠️ Community growth (critical for timeline)
|
||||
5. ⚠️ FPGA decision (feasibility gates investment)
|
||||
|
||||
**Realistic Timeline**:
|
||||
- Solo: 3.5 years (42 months)
|
||||
- With 3-5 contributors: 2 years (24 months)
|
||||
- With 10+ contributors: 1.5 years (18 months)
|
||||
|
||||
**The vision is clear. The path is defined. Now we build.**
|
||||
|
||||
---
|
||||
|
||||
**Next Steps**:
|
||||
1. Read [docs/GAP_ANALYSIS.md](docs/GAP_ANALYSIS.md) for detailed gaps
|
||||
2. Start Phase 1: HAL implementation
|
||||
3. Join the project (see CONTRIBUTING.md)
|
||||
|
||||
**License**: See ./LICENSE
|
||||
+3
@@ -1,3 +1,6 @@
|
||||
> **SUPERSEDED (docs triage 2026-10-14).** Storage design for the Hermes VM's messages and channels; the Hermes VM no longer exists -- messages are kernel-Hermes's.
|
||||
> Instead: docs/fabric/FABRIC-3.5.md and FABRIC-3.6.md. Moved here from `docs/working/architecture/HERMES-MESSAGE-BLOCK-STORAGE-DESIGN-20260708.md`.
|
||||
|
||||
# Hermes Message/Channel Block-Backed Storage — Design Doc
|
||||
**Date:** 2026-07-08 (rev 2026-07-09d)
|
||||
**Branch:** `lithosananke`
|
||||
+3
@@ -1,3 +1,6 @@
|
||||
> **SUPERSEDED (docs triage 2026-10-14).** Heat physics for the Hermes VM's messages and channels; the Hermes VM no longer exists.
|
||||
> Instead: docs/fabric/FABRIC-3.5.md and FABRIC-3.6.md. Moved here from `docs/working/architecture/HERMES-MESSAGE-CHANNEL-PHYSICS-DESIGN-20260708.md`.
|
||||
|
||||
# Hermes Message/Channel Heat Physics — Design Doc
|
||||
**Date:** 2026-07-08 (rev 2026-07-08a)
|
||||
**Branch:** `lithosananke`
|
||||
+3
@@ -1,3 +1,6 @@
|
||||
> **SUPERSEDED (docs triage 2026-10-14).** An implementation plan for Artemis and the Hermes VM; the Hermes half is gone with the VM, the Artemis half was carried by the FABRIC work.
|
||||
> Instead: docs/fabric/FABRIC-3.5.md and FABRIC-3.6.md. Moved here from `docs/working/architecture/ARTEMIS-COMPUDYNAMICS-IMPLEMENTATION-PLAN-20260802.md`.
|
||||
|
||||
# Artemis (and Hermes) Compudynamics — Implementation Plan
|
||||
**Date:** 2026-08-02
|
||||
**Branch:** `master`
|
||||
@@ -0,0 +1,22 @@
|
||||
> **SUPERSEDED (docs triage 2026-10-14).** The index of the old docs/03-architecture/ folder; its parts moved (word-acl to docs/reference/, tripod here).
|
||||
> Instead: docs/README.md. Moved here from `docs/03-architecture/README.md`.
|
||||
|
||||
# docs/03-architecture/
|
||||
|
||||
Architecture-constraint documents for LithosAnanke subsystems that are still
|
||||
being designed or built. These are binding constraints for anyone (human or
|
||||
Claude Code) touching the affected code, not general background reading.
|
||||
|
||||
- **[tripod/](tripod/)** — Architectural contracts for the three Tripod VMs
|
||||
(Hera, Hermes, Artemis): roles, dispatch rules, the compudynamic K≡1.0
|
||||
invariant, and explicit prohibitions.
|
||||
- **[word-acl/](word-acl/)** — Design doc for the word-level ACL system
|
||||
(`capsules/ACL.4th`, `capsules/zuse.4th`, `src/word_source/acl_words.c`).
|
||||
|
||||
## See also
|
||||
|
||||
- [`docs/working/archive/historical/2026-07-birthing/`](../birthing/) — VM birthing plan/status that implements
|
||||
the Tripod contract described in `tripod/TRIPOD.md`.
|
||||
- [`docs/working/archive/historical/2026-10-lithosananke-orientation.md`](../lithosananke/README.md) — kernel-branch
|
||||
overview these designs build on.
|
||||
- [Project root](../../README.md)
|
||||
@@ -0,0 +1,190 @@
|
||||
> **SUPERSEDED (docs triage 2026-10-14).** The Tripod as Hera/Hermes/Artemis; the Hermes VM was removed (messaging moved into the kernel as kernel-Hermes) and the Tripod is Hera/Artemis/Hestia.
|
||||
> Instead: docs/fabric/FABRIC-3.5.md and FABRIC-3.6.md. Moved here from `docs/03-architecture/tripod/ARTEMIS.md`.
|
||||
|
||||
# ARTEMIS.md — Artemis VM Architecture
|
||||
# StarshipOS / StarForth — Captain Bob (Robert Allan James)
|
||||
# This document constrains Claude Code behavior. Read it completely before touching Artemis.
|
||||
|
||||
---
|
||||
|
||||
## Language Constraint — Non-Negotiable
|
||||
|
||||
All Artemis implementation is in StarForth dialect ONLY.
|
||||
|
||||
This includes:
|
||||
- Data structures
|
||||
- Constants
|
||||
- Variables
|
||||
- Control flow
|
||||
- Everything
|
||||
|
||||
C99 is forbidden unless explicitly blocked in StarForth AND explicit written permission
|
||||
is given by Captain Bob for that specific construct. "I could not figure out how to do
|
||||
this in StarForth" is not permission. Ask first. Wait for the answer.
|
||||
|
||||
If you are about to write a C struct, a #define, or a C variable — stop.
|
||||
Implement it in StarForth or ask.
|
||||
|
||||
---
|
||||
|
||||
## When Stuck — Non-Negotiable
|
||||
|
||||
If you are stuck, STOP.
|
||||
|
||||
Do not confabulate.
|
||||
Do not invent dictionary words that do not exist.
|
||||
Do not fabricate primitives.
|
||||
Do not guess at behavior.
|
||||
Do not work around the problem silently.
|
||||
|
||||
STOP. Report exactly what is blocking you. Wait for instruction.
|
||||
|
||||
Silent confabulation has caused git resets on a project with a hard patent deadline.
|
||||
It is not acceptable under any circumstances.
|
||||
|
||||
---
|
||||
|
||||
## What Artemis Is
|
||||
|
||||
Artemis is memory. She owns the external attached virtual disk image and everything
|
||||
that lives on it. She manages block storage compudynamically.
|
||||
|
||||
Artemis does **not** move messages — that is Hermes.
|
||||
Artemis does **not** make VM lifecycle decisions — that is Hera.
|
||||
Artemis does **not** own the internal ramdisk — that is kernel territory.
|
||||
|
||||
---
|
||||
|
||||
## Storage Topology
|
||||
|
||||
### Internal Ramdisk — Not Artemis Scope
|
||||
- Baked into each VM at build time by mkcapsule.c
|
||||
- LBN 0–3071
|
||||
- Kernel territory
|
||||
- Every VM carries its own ramdisk
|
||||
- Artemis does not touch it, manage it, or know about it
|
||||
|
||||
### External Attached Virtual Disk Image — Artemis Territory
|
||||
- Mounted virtual disk image, attached to the QEMU instance
|
||||
- Artemis owns this exclusively
|
||||
- LBN boundaries to be determined as Artemis is built
|
||||
- Nothing persists between runs yet — that is a future chapter
|
||||
|
||||
### Nothing Persists Between Runs Yet
|
||||
Persistence across runs is a future chapter. Do not implement it yet.
|
||||
Do not design around it. The current model is: VM starts, Artemis initializes
|
||||
her free map, VM stops, everything is gone. That is correct for now.
|
||||
|
||||
---
|
||||
|
||||
## What Artemis Owns
|
||||
|
||||
- The free map over her LBN range on the external disk image
|
||||
- Block fetch and persist operations on the external disk image
|
||||
- ACL lists — structured as Artemis-managed blocks (see ACL section)
|
||||
- Cold capsule store — evicted from Hermes cache (future chapter)
|
||||
- Block metadata
|
||||
|
||||
---
|
||||
|
||||
## Compudynamic Block Lifecycle
|
||||
|
||||
Artemis manages blocks compudynamically. Same model as everything else in StarshipOS:
|
||||
|
||||
- Block enters active use — born hot
|
||||
- Cools over time with each heartbeat tick
|
||||
- Frequently accessed blocks stay warm (heat refreshed on access)
|
||||
- Cold blocks are candidates for eviction or reuse
|
||||
- Block reap must rebalance K correctly
|
||||
|
||||
Artemis is the hardest VM to design because she has three interleaved
|
||||
compudynamic concerns:
|
||||
1. The free map — which LBNs are available
|
||||
2. Block thermal state — how hot is each active block
|
||||
3. K≡1.0 — fleet conservation across all block operations
|
||||
|
||||
These must be designed together. Do not implement one without the others.
|
||||
Do not begin implementation without explicit instruction from Captain Bob.
|
||||
|
||||
---
|
||||
|
||||
## ACL — Access Control Lists
|
||||
|
||||
### Current State
|
||||
ACL is a toggle. It is currently OFF.
|
||||
|
||||
A `\` comment disables ACL enforcement. When commented out, zuse is the
|
||||
implicit and only user. No enforcement occurs.
|
||||
|
||||
```forth
|
||||
\ ACL-ENFORCE ( disabled — zuse only )
|
||||
```
|
||||
|
||||
### Structure
|
||||
ACL lists must be structured as Artemis-managed blocks from day one.
|
||||
Even before Artemis is fully built, ACL data structures must assume
|
||||
they will live in Artemis-managed storage. No shortcuts that require
|
||||
redesign later.
|
||||
|
||||
### When ACL Turns On
|
||||
ACL enforcement becomes mandatory when VMs outside the Tripod arrive.
|
||||
Until then the toggle stays off.
|
||||
|
||||
When enforcement is enabled:
|
||||
- Every VM has an identity
|
||||
- Every operation is checked against the ACL
|
||||
- Artemis is the authority — she holds the lists
|
||||
|
||||
### Security Model
|
||||
Security grows with the threat surface. Not before it.
|
||||
The architecture is always structurally correct — enforcement is simply
|
||||
not active yet. No retrofit needed when the time comes.
|
||||
|
||||
Toggling ACL on must require zero structural changes to the codebase.
|
||||
Only the `\` comment is removed. If toggling ACL requires anything else,
|
||||
the implementation is wrong.
|
||||
|
||||
---
|
||||
|
||||
## What Is Not Artemis
|
||||
|
||||
- **Internal ramdisk** — kernel territory, not Artemis scope
|
||||
- **Message routing** — that is Hermes
|
||||
- **VM lifecycle** — that is Hera
|
||||
- **Persistence across runs** — future chapter, not now
|
||||
- **Cold capsule eviction from Hermes** — future chapter, not now
|
||||
|
||||
---
|
||||
|
||||
## Compudynamic Invariant
|
||||
|
||||
Every block Artemis manages participates in K≡1.0.
|
||||
Block fetch, persist, and reap operations must rebalance K correctly.
|
||||
Artemis's thermal contribution to the fleet is the sum of her active block heat.
|
||||
|
||||
Do not write code that breaks K≡1.0 and add a comment explaining why it's okay.
|
||||
|
||||
---
|
||||
|
||||
## Current Scope
|
||||
|
||||
Artemis is not yet started. Before any implementation begins:
|
||||
|
||||
1. Captain Bob must give explicit instruction to begin
|
||||
2. The three compudynamic concerns (free map, block thermal state, K≡1.0)
|
||||
must be designed together before any code is written
|
||||
3. ACL data structures must be Artemis-block-shaped from first line of code
|
||||
4. Storage boundaries (LBN ranges on external disk image) must be confirmed
|
||||
|
||||
**Do not begin implementation without explicit instruction.**
|
||||
|
||||
Future chapters (do not implement):
|
||||
- Persistence across runs
|
||||
- Cold capsule store from Hermes
|
||||
- Full ACL enforcement
|
||||
- LBN range expansion
|
||||
|
||||
---
|
||||
|
||||
*This document is authoritative. If it conflicts with something in the codebase,
|
||||
the codebase is wrong.*
|
||||
@@ -0,0 +1,253 @@
|
||||
> **SUPERSEDED (docs triage 2026-10-14).** The Tripod as Hera/Hermes/Artemis; the Hermes VM was removed (messaging moved into the kernel as kernel-Hermes) and the Tripod is Hera/Artemis/Hestia.
|
||||
> Instead: docs/fabric/FABRIC-3.5.md and FABRIC-3.6.md. Moved here from `docs/03-architecture/tripod/HERMES.md`.
|
||||
|
||||
# HERMES.md — Hermes VM Architecture
|
||||
# StarshipOS / StarForth — Captain Bob (Robert Allan James)
|
||||
# This document constrains Claude Code behavior. Read it completely before touching Hermes.
|
||||
|
||||
---
|
||||
|
||||
## Language Constraint — Non-Negotiable
|
||||
|
||||
All Hermes implementation is in StarForth dialect ONLY.
|
||||
|
||||
This includes:
|
||||
- Data structures
|
||||
- Constants
|
||||
- Variables
|
||||
- Control flow
|
||||
- Everything
|
||||
|
||||
C99 is forbidden unless explicitly blocked in StarForth AND explicit written permission
|
||||
is given by Captain Bob for that specific construct. "I could not figure out how to do
|
||||
this in StarForth" is not permission. Ask first. Wait for the answer.
|
||||
|
||||
If you are about to write a C struct, a #define, or a C variable — stop.
|
||||
Implement it in StarForth or ask.
|
||||
|
||||
---
|
||||
|
||||
## What Hermes Is
|
||||
|
||||
Hermes is the messenger. He moves messages between VMs and manages channels.
|
||||
That is his complete contract.
|
||||
|
||||
Hermes does **not** store persistent data — that is Artemis.
|
||||
Hermes does **not** make lifecycle decisions — that is Hera.
|
||||
Hermes does **not** route by load or heat — dispatch is capability-based, always.
|
||||
|
||||
Capsules are baked into the OS blob by mkcapsule.c at build time.
|
||||
Hermes has no capsule cache, no fetch logic, no repository concern.
|
||||
That is a future chapter.
|
||||
|
||||
---
|
||||
|
||||
## The Event Loop
|
||||
|
||||
Hermes runs a compudynamic event loop. Every message is a compudynamic object:
|
||||
|
||||
- Born hot (full heat at creation)
|
||||
- Cools each heartbeat tick
|
||||
- ACK received → clean death, K redistributed to fleet
|
||||
- NACK received → requeue with reduced heat, or reaped if heat floor reached
|
||||
- TTL expires (heat → 0) → Hermes reaps the message, K rebalanced
|
||||
|
||||
There is no special timeout logic. The physics handles it.
|
||||
A message that nobody answers simply cools to death.
|
||||
|
||||
---
|
||||
|
||||
## Message Structure
|
||||
|
||||
Every message carries:
|
||||
|
||||
```
|
||||
type — work type tag (determines recipient)
|
||||
sender — originating VM identity
|
||||
recipient — destination VM identity
|
||||
payload — message body
|
||||
heat — current thermal value (compudynamic)
|
||||
sequence — monotonic sequence number
|
||||
```
|
||||
|
||||
Point-to-point only. Sender addresses recipient directly.
|
||||
Hermes delivers and tracks thermal state. He does not inspect payload.
|
||||
|
||||
---
|
||||
|
||||
## ACK/NACK Protocol
|
||||
|
||||
- ACK → message dies cleanly, K redistributed
|
||||
- NACK → message requeued with reduced heat
|
||||
- No response → message cools naturally to death via TTL
|
||||
|
||||
The binary receipt of a response IS the ACK where applicable.
|
||||
No separate acknowledgement frame needed in those cases.
|
||||
|
||||
---
|
||||
|
||||
## PubSub — Channels
|
||||
|
||||
Hermes implements a publish/subscribe model. Topics are called **channels**.
|
||||
|
||||
### The Common Channel
|
||||
|
||||
There is one permanent channel: `COMMON`.
|
||||
|
||||
- Always exists, always hot
|
||||
- Any VM can publish to it
|
||||
- Used for negotiation and channel establishment only
|
||||
- Not for business transactions — those happen on ephemeral channels
|
||||
|
||||
### Ephemeral Channels
|
||||
|
||||
Ephemeral channels are compudynamic objects — born hot, reaped when cold or closed.
|
||||
|
||||
**Channel structure:**
|
||||
|
||||
```
|
||||
channel_id — owner VM identity + monotonic sequence number
|
||||
owner — VM that created the channel (always the responder)
|
||||
members[] — participant list
|
||||
heat — compudynamic, born hot at creation
|
||||
state — NEGOTIATING | OPEN | CLOSING
|
||||
```
|
||||
|
||||
### The Negotiation Protocol
|
||||
|
||||
```
|
||||
1. X publishes request on COMMON — born hot, TTL ticking
|
||||
2. Y sees request, responds yes/no on COMMON
|
||||
— No response → message cools to death → implicit NACK to X
|
||||
3. Y accepts → Y creates ephemeral channel
|
||||
→ Y publishes channel_id to X over COMMON
|
||||
4. X and Y conduct business on ephemeral channel
|
||||
5. Business concluded → owner Y reaps channel → K rebalanced
|
||||
```
|
||||
|
||||
Y owns channel creation and destruction. Always the responder, never the requester.
|
||||
A channel dying of cold (abandoned transaction) is not an error — the physics handles it.
|
||||
|
||||
### Multi-Party Channels
|
||||
|
||||
Channels are bilateral by default. The owner may invite additional VMs:
|
||||
|
||||
```
|
||||
1. Owner publishes invite to candidate VM on COMMON
|
||||
2. Candidate accepts or declines on COMMON — same TTL/cool protocol
|
||||
3. Accept → candidate added to members[]
|
||||
4. Decline or timeout → candidate never joins, channel continues bilateral
|
||||
```
|
||||
|
||||
Multi-party is designed for but not implemented yet.
|
||||
Do not implement invite logic until explicitly instructed.
|
||||
The members[] structure must exist from the start to avoid future redesign.
|
||||
|
||||
### Channel Identity
|
||||
|
||||
`channel_id` = owner VM identity + monotonic sequence number.
|
||||
Unforgeable by non-owners. Hermes mints it. No VM constructs its own channel_id.
|
||||
|
||||
### Compudynamic Invariant for Channels
|
||||
|
||||
Channels participate in K≡1.0.
|
||||
An open channel with active messages holds heat.
|
||||
Channel reap must redistribute K correctly to the fleet.
|
||||
A channel cannot be reaped while messages on it are still in flight —
|
||||
drain first, then reap.
|
||||
|
||||
---
|
||||
|
||||
## What Is Not Hermes
|
||||
|
||||
- **Capsule cache** — future chapter, not now
|
||||
- **Remote fetch** — future chapter, not now
|
||||
- **UDP server / client** — future chapter, not now
|
||||
- **Instance authentication** — future chapter, not now
|
||||
- **Persistent block storage** — that is Artemis
|
||||
- **VM lifecycle decisions** — that is Hera
|
||||
- **Heat-based routing** — wrong model, never implement
|
||||
|
||||
---
|
||||
|
||||
## Compudynamic Invariant
|
||||
|
||||
Every object Hermes manages — messages and channels — participates in K≡1.0.
|
||||
Fleet K includes the thermal contribution of in-flight messages and open channels.
|
||||
Hermes reaping a message or channel must rebalance K correctly.
|
||||
|
||||
Do not write code that breaks K≡1.0 and add a comment explaining why it's okay.
|
||||
|
||||
---
|
||||
|
||||
## Current Scope
|
||||
|
||||
1. Compudynamic event loop — message emit, drain, TTL, ACK/NACK, reap
|
||||
2. COMMON channel — permanent, always hot, negotiation only
|
||||
3. Ephemeral channels — compudynamic lifecycle, owner=responder, bilateral default
|
||||
4. Channel negotiation protocol — request on COMMON, Y creates, Y reaps
|
||||
5. members[] structure — present from the start, multi-party invite not yet implemented
|
||||
|
||||
Capsule management is a future chapter.
|
||||
Remote repository is a future chapter.
|
||||
Multi-party channel invite is a future chapter.
|
||||
|
||||
---
|
||||
|
||||
## v1 Block Map — LOCKED
|
||||
|
||||
Blocks 4110–4113 are Artemis. NEVER touch them.
|
||||
|
||||
```
|
||||
4100 Constants: event codes, channel states, node sizes, arena sizes
|
||||
4101 Arena CREATE: MSG-ARENA CH-ARENA MBR-ARENA; free-list vars; MSG-SEQ CH-ACTIVE
|
||||
4102 MSG-INIT-FREE + CH-INIT-FREE
|
||||
4103 MBR-INIT-FREE + MSG-ALLOC + MSG-FREE-NODE
|
||||
4104 CH-ALLOC + CH-FREE-NODE + MBR-ALLOC + MBR-FREE-NODE
|
||||
4105 Message field accessors: MSG-TYPE@/! MSG-FROM@/! MSG-TO@/! MSG-PADDR@/! MSG-PLEN@/! MSG-HEAT@/! MSG-SEQ@/!
|
||||
4106 Channel+member accessors: CH-ID@/! CH-OWNER@/! CH-STATE@/! CH-HEAT@/! CH-MBRS@/! CH-NEXT@/! MBR-NEXT@ MBR-VM@
|
||||
4107 IDX>NAME + MSG-DELIVER + MSG-SEND
|
||||
4108 VARIABLE MSG-SCAN + MSG-COOL-ONE + MSG-COOL-ALL
|
||||
4109 MSG-REAP
|
||||
---- 4110–4113: ARTEMIS — DO NOT TOUCH ----
|
||||
4114 VARIABLE CH-SCAN + CH-COOL-ALL
|
||||
4115 CH-REAP-SAFE
|
||||
4116 VARIABLE COMMON-CH + COMMON-INIT + HERMES-TICK
|
||||
4117 EVENT-EMIT + EVENT-WAIT + EVENT-DRAIN (backward compat)
|
||||
4118 HERA-NOTIFY-SPAWN + HERA-NOTIFY-KILL + HERA-DISPATCH-ONE + HERA-DISPATCH
|
||||
4119 CH-REQUEST + CH-ACCEPT + CH-CLOSE
|
||||
4120 WELCOME + CD-INIT
|
||||
```
|
||||
|
||||
### Node layouts (cells)
|
||||
|
||||
**Message node — 7 cells:**
|
||||
- 0: type (in-use) / next-free ptr (free)
|
||||
- 1: sender VM index
|
||||
- 2: recipient VM index
|
||||
- 3: payload addr (FORTH string addr)
|
||||
- 4: payload len
|
||||
- 5: heat (Q48.16)
|
||||
- 6: seq
|
||||
|
||||
**Channel node — 6 cells:**
|
||||
- 0: channel-id (in-use) / next-free ptr (free)
|
||||
- 1: owner VM index
|
||||
- 2: state (0=NEGOTIATING 1=OPEN 2=CLOSING)
|
||||
- 3: heat (Q48.16)
|
||||
- 4: members-head (→ member list)
|
||||
- 5: next-active (active channel list link)
|
||||
|
||||
**Member node — 2 cells:**
|
||||
- 0: next-ptr
|
||||
- 1: vm-id
|
||||
|
||||
### Physics
|
||||
|
||||
Cooling constant: Q-DECAY (65208) from compudynamics.4th — same as VM-DECAY-ONE.
|
||||
Messages and VMs cool at identical rates. Fleet is thermodynamically consistent.
|
||||
|
||||
---
|
||||
|
||||
*This document is authoritative. If it conflicts with something in the codebase,
|
||||
the codebase is wrong.*
|
||||
@@ -0,0 +1,31 @@
|
||||
> **SUPERSEDED (docs triage 2026-10-14).** The Tripod as Hera/Hermes/Artemis; the Hermes VM was removed (messaging moved into the kernel as kernel-Hermes) and the Tripod is Hera/Artemis/Hestia.
|
||||
> Instead: docs/fabric/FABRIC-3.5.md and FABRIC-3.6.md. Moved here from `docs/03-architecture/tripod/README.md`.
|
||||
|
||||
# docs/working/archive/superseded/2026-08-tripod/
|
||||
|
||||
Architectural constraints for the three StarForth VMs that make up the
|
||||
Tripod. These documents are binding — read the relevant one in full before
|
||||
touching any Tripod code. Violating the mythological contract they describe
|
||||
is treated as an architectural error, not a style preference.
|
||||
|
||||
- **[TRIPOD.md](TRIPOD.md)** — The Tripod as a whole: Hera (VM-HERA=0,
|
||||
governor — spawns/manages/reaps VMs), Hermes (VM-HERMES=1, messenger —
|
||||
moves events), Artemis (VM-ARTEMIS=2, memory — owns block storage).
|
||||
Covers capability-based dispatch (no heat-based routing), the CD-TICK
|
||||
heartbeat, the K≡1.0 compudynamic conservation invariant, the DoE test
|
||||
fixture's role, and explicit prohibitions (no heat-based VM routing, no
|
||||
primitives added without instruction, no `BLOCK` calls outside the
|
||||
0–3071 ramdrive range).
|
||||
- **[HERMES.md](HERMES.md)** — Hermes VM architecture: the messenger role.
|
||||
- **[ARTEMIS.md](ARTEMIS.md)** — Artemis VM architecture: the memory/block-
|
||||
storage role.
|
||||
|
||||
All three documents share a non-negotiable constraint: Tripod implementation
|
||||
is StarForth dialect only — no C99 without Captain Bob's explicit written
|
||||
permission for that specific construct.
|
||||
|
||||
## See also
|
||||
|
||||
- [`docs/working/archive/historical/2026-07-birthing/`](../../birthing/) — birthing plan and QEMU acceptance
|
||||
logs for the Hera-spawns-Hermes/Artemis constellation described here.
|
||||
- [Project root](../../../README.md)
|
||||
@@ -0,0 +1,191 @@
|
||||
> **SUPERSEDED (docs triage 2026-10-14).** The Tripod as Hera/Hermes/Artemis; the Hermes VM was removed (messaging moved into the kernel as kernel-Hermes) and the Tripod is Hera/Artemis/Hestia.
|
||||
> Instead: docs/fabric/FABRIC-3.5.md and FABRIC-3.6.md. Moved here from `docs/03-architecture/tripod/TRIPOD.md`.
|
||||
|
||||
# TRIPOD.md — Architectural Constraints for the Tripod VMs
|
||||
# StarshipOS / StarForth — Captain Bob (Robert Allan James)
|
||||
# This document constrains Claude Code behavior. Read it completely before touching any Tripod code.
|
||||
|
||||
---
|
||||
|
||||
## The Tripod: What It Is
|
||||
|
||||
Three StarForth VMs constitute the Tripod. They are not generic workers. Each holds a
|
||||
specific architectural contract expressed by its mythological name. Violating the
|
||||
mythological contract is an architectural error, not a style preference.
|
||||
|
||||
| VM | ID | Contract |
|
||||
|------------|-------------|-----------------------------------------------|
|
||||
| Hera | VM-HERA=0 | Governor. Spawns, manages, and reaps VMs. |
|
||||
| Hermes | VM-HERMES=1 | Messenger. Moves events between VMs. |
|
||||
| Artemis | VM-ARTEMIS=2| Memory. Owns block storage and persistence. |
|
||||
|
||||
**Hera is queen. She does not do work. She governs who exists and who doesn't.**
|
||||
**Hermes moves messages. He does not store anything.**
|
||||
**Artemis holds things. She does not route anything.**
|
||||
|
||||
If you find yourself putting event dispatch logic in Artemis, or storage logic in Hermes,
|
||||
or work execution logic in Hera — stop. You have the wrong VM.
|
||||
|
||||
---
|
||||
|
||||
## The Immediate Goal
|
||||
|
||||
Hera must spawn Hermes and Artemis at boot, and all three must cooperate
|
||||
compudynamically under K≡1.0 conservation.
|
||||
|
||||
That is the complete scope. Nothing else.
|
||||
|
||||
Acceptance criteria:
|
||||
1. Hera boots and initializes her own compudynamic state.
|
||||
2. Hera spawns Hermes. Hermes initializes his own compudynamic state.
|
||||
3. Hera spawns Artemis. Artemis initializes her own compudynamic state.
|
||||
4. All three VMs are running. Fleet K = sum of individual VM K values. K≡1.0 holds.
|
||||
5. Hera can reap (cleanly terminate) a child VM.
|
||||
6. The system is stable across a long-running test workload.
|
||||
|
||||
---
|
||||
|
||||
## Compudynamics: Dual Role — Read This Carefully
|
||||
|
||||
Compudynamics serves TWO roles in this system. Do not conflate them.
|
||||
|
||||
### Role 1: Intra-VM Physics Engine
|
||||
Inside each VM, Compudynamics drives the adaptive heartbeat:
|
||||
- 7-loop rolling window
|
||||
- K conservation arithmetic
|
||||
- Phase operators on the heartbeat signal
|
||||
|
||||
Every VM — Hera, Hermes, Artemis — runs its own compudynamic engine internally.
|
||||
This is autonomous. No VM manages another VM's internal heartbeat.
|
||||
|
||||
### Role 2: Hera's VM Lifecycle Driver
|
||||
Hera observes the fleet K picture and uses it to make **lifecycle decisions**:
|
||||
- Is a child VM healthy?
|
||||
- Is a child VM starved?
|
||||
- Does a child VM need to be spawned, suspended, or reaped?
|
||||
|
||||
Hera does NOT use fleet K to route work. She uses it to govern existence.
|
||||
|
||||
**The fleet K view is lifecycle telemetry. It is not a dispatch mechanism.**
|
||||
|
||||
---
|
||||
|
||||
## Dispatch: Capability-Based, Always
|
||||
|
||||
Work routing is determined by work type. It is not determined by heat, K value,
|
||||
VM load, or any compudynamic signal.
|
||||
|
||||
| Work type | Destination |
|
||||
|-----------------|-------------|
|
||||
| Block I/O | Artemis |
|
||||
| Event emit/drain| Hermes |
|
||||
| VM lifecycle | Hera |
|
||||
|
||||
`VM-EXEC` takes a VM name. The caller names the correct VM for the work type.
|
||||
There is no routing algorithm. There is no dispatch table keyed on heat.
|
||||
There is no "send to the hottest VM." That model is wrong and must not be implemented.
|
||||
|
||||
---
|
||||
|
||||
## CD-TICK: What It Is and Is Not
|
||||
|
||||
CD-TICK advances the compudynamic heartbeat. That is all it does.
|
||||
|
||||
CD-TICK is **not**:
|
||||
- A scheduler
|
||||
- A timeslicer
|
||||
- A run-queue manager
|
||||
- A work dispatcher
|
||||
- A router
|
||||
|
||||
If you are calling CD-TICK to decide where work goes, you are using it wrong.
|
||||
|
||||
---
|
||||
|
||||
## The DoE (Design of Experiments) Test Fixture
|
||||
|
||||
The DoE campaign (PHASE6-TEST, K-conservation CSV logging, 38,400-run Latin Square)
|
||||
is a **stress and measurement fixture**. It exists to:
|
||||
- Validate K≡1.0 conservation under long-running diverse workloads
|
||||
- Generate telemetry for the SSRN paper
|
||||
- Provide a long-runtime acceptance test for the compudynamic physics
|
||||
|
||||
The DoE is **not**:
|
||||
- A description of what the system does in production
|
||||
- A feature
|
||||
- A model for how work gets dispatched
|
||||
|
||||
`DOE-WORK` must never appear in the production dispatch path.
|
||||
If you see `DOE-WORK` being dispatched by anything other than the test fixture, remove it.
|
||||
|
||||
The DoE is a good test precisely because it is long-running and diverse.
|
||||
It exercises the physics. It does not define the system.
|
||||
|
||||
---
|
||||
|
||||
## What Not To Do — Explicit Prohibitions
|
||||
|
||||
1. **Do not implement heat-based VM routing.** It causes starvation. It is wrong.
|
||||
2. **Do not pin Hera's heat floor.** That is a band-aid on a wrong model.
|
||||
3. **Do not put DOE-WORK in the production dispatch path.**
|
||||
4. **Do not call CD-TICK a scheduler** in comments, docs, or variable names.
|
||||
5. **Do not call the fleet K view a router** in comments, docs, or variable names.
|
||||
6. **Do not add primitives to StarForth without explicit instruction.**
|
||||
NIP is not registered. TUCK is not registered. Assume nothing is available
|
||||
that is not in the verified primitive table. Use SWAP DROP instead of NIP.
|
||||
7. **Do not call BLOCK on LBNs outside the ramdrive range (0–3071).**
|
||||
LBN 4501–4599 are Artemis metadata space. They are not in the kernel ramdrive.
|
||||
Use ART-STATUS to touch the free map. Do not call ART-SELF-TEST in acceptance tests.
|
||||
8. **Do not exceed 64 bytes per line or 16 lines per block in capsule files.**
|
||||
mkcapsule.c enforces this at build time. Violations will fail the build.
|
||||
|
||||
---
|
||||
|
||||
## The Invariant
|
||||
|
||||
K≡1.0 is conserved across the fleet at all times.
|
||||
Fleet K = sum of all VM K values.
|
||||
This is a physics constraint, not a software convention.
|
||||
Do not write code that breaks it and then add a comment explaining why it's okay.
|
||||
|
||||
---
|
||||
|
||||
*This document is authoritative. If it conflicts with something in the codebase,
|
||||
the codebase is wrong.*
|
||||
|
||||
---
|
||||
|
||||
## Language Constraint — Non-Negotiable
|
||||
|
||||
All Tripod implementation is in StarForth dialect ONLY.
|
||||
|
||||
This includes:
|
||||
- Data structures
|
||||
- Constants
|
||||
- Variables
|
||||
- Control flow
|
||||
- Everything
|
||||
|
||||
C99 is forbidden unless explicitly blocked in StarForth AND explicit written permission
|
||||
is given by Captain Bob for that specific construct. "I could not figure out how to do
|
||||
this in StarForth" is not permission. Ask first. Wait for the answer.
|
||||
|
||||
If you are about to write a C struct, a #define, or a C variable — stop.
|
||||
Implement it in StarForth or ask.
|
||||
|
||||
---
|
||||
|
||||
## When Stuck — Non-Negotiable
|
||||
|
||||
If you are stuck, STOP.
|
||||
|
||||
Do not confabulate.
|
||||
Do not invent dictionary words that do not exist.
|
||||
Do not fabricate primitives.
|
||||
Do not guess at behavior.
|
||||
Do not work around the problem silently.
|
||||
|
||||
STOP. Report exactly what is blocking you. Wait for instruction.
|
||||
|
||||
Silent confabulation has caused git resets on a project with a hard patent deadline.
|
||||
It is not acceptable under any circumstances.
|
||||
+4
-1
@@ -1,4 +1,7 @@
|
||||
<!-- Moved from docs/02-experiments/L8_WIRING_PLAN.md to docs/working/experiments/02-experiments/L8_WIRING_PLAN.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
> **SUPERSEDED (docs triage 2026-10-14).** Flagged superseded 2026-10-09: the plan for wiring L8, since built.
|
||||
> Instead: docs/working/experiments/02-experiments/L8_WIRING_IMPLEMENTATION_SUMMARY.md. Moved here from `docs/working/experiments/02-experiments/L8_WIRING_PLAN.md`.
|
||||
|
||||
<!-- Moved from docs/02-experiments/L8_WIRING_PLAN.md to docs/working/archive/superseded/L8_WIRING_PLAN.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
|
||||
> **⚠ SUPERSEDED (flagged 2026-10-09).** The wiring plan was executed; superseded by
|
||||
> `L8_WIRING_IMPLEMENTATION_SUMMARY.md` and `L8_WIRING_CODE_REVIEW_GUIDE.md`. Kept as a
|
||||
+4
-1
@@ -1,4 +1,7 @@
|
||||
<!-- Moved from docs/02-experiments/factorial-doe/guide.md to docs/working/experiments/02-experiments/factorial-doe/guide.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
> **SUPERSEDED (docs triage 2026-10-14).** The 2^6 factorial DoE guide, flagged obsolete 2026-10-09.
|
||||
> Instead: experiments/bare_metal/README.md for the DoE as it runs now. Moved here from `docs/working/experiments/02-experiments/factorial-doe/guide.md`.
|
||||
|
||||
<!-- Moved from docs/02-experiments/factorial-doe/guide.md to docs/working/archive/superseded/factorial-doe/guide.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
|
||||
> **⚠ OBSOLETE (flagged 2026-10-09).** Describes the retired per-loop Makefile-toggle
|
||||
> architecture, replaced by the L8 Jacquard runtime mode selector. Kept for historical record.
|
||||
+4
-1
@@ -1,4 +1,7 @@
|
||||
<!-- Moved from docs/02-experiments/factorial-doe/incompatible-configs.md to docs/working/experiments/02-experiments/factorial-doe/incompatible-configs.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
> **SUPERSEDED (docs triage 2026-10-14).** The 2^6 factorial DoE guide, flagged obsolete 2026-10-09.
|
||||
> Instead: experiments/bare_metal/README.md for the DoE as it runs now. Moved here from `docs/working/experiments/02-experiments/factorial-doe/incompatible-configs.md`.
|
||||
|
||||
<!-- Moved from docs/02-experiments/factorial-doe/incompatible-configs.md to docs/working/archive/superseded/factorial-doe/incompatible-configs.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
|
||||
> **⚠ OBSOLETE (flagged 2026-10-09).** Build-time incompatibility handling for the retired 2^6
|
||||
> toggle experiment, replaced by the L8 Jacquard mode selector. Kept for historical record.
|
||||
+4
-1
@@ -1,4 +1,7 @@
|
||||
<!-- Moved from docs/02-experiments/factorial-doe/index.md to docs/working/experiments/02-experiments/factorial-doe/index.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
> **SUPERSEDED (docs triage 2026-10-14).** The 2^6 factorial DoE guide, flagged obsolete 2026-10-09.
|
||||
> Instead: experiments/bare_metal/README.md for the DoE as it runs now. Moved here from `docs/working/experiments/02-experiments/factorial-doe/index.md`.
|
||||
|
||||
<!-- Moved from docs/02-experiments/factorial-doe/index.md to docs/working/archive/superseded/factorial-doe/index.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
|
||||
> **⚠ OBSOLETE (flagged 2026-10-09).** Index for the retired 2^6 factorial toggle
|
||||
> architecture, replaced by the L8 Jacquard mode selector. Kept for historical record.
|
||||
+4
-1
@@ -1,4 +1,7 @@
|
||||
<!-- Moved from docs/01-getting-started/quick-start/factorial-doe.md to docs/working/architecture/getting-started/quick-start/factorial-doe.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
> **SUPERSEDED (docs triage 2026-10-14).** Quick start for the same 2^6 factorial DoE, flagged obsolete 2026-10-09.
|
||||
> Instead: experiments/bare_metal/README.md. Moved here from `docs/working/architecture/getting-started/quick-start/factorial-doe.md`.
|
||||
|
||||
<!-- Moved from docs/01-getting-started/quick-start/factorial-doe.md to docs/working/archive/superseded/factorial-doe/quick-start.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
|
||||
> **⚠ OBSOLETE (flagged 2026-10-09).** Describes the retired per-loop `ENABLE_LOOP_1..6`
|
||||
> compile-time toggle architecture and hardcoded local paths; the physics adaptation is now
|
||||
+4
-1
@@ -1,4 +1,7 @@
|
||||
<!-- Moved from docs/02-experiments/factorial-doe/workflow.md to docs/working/experiments/02-experiments/factorial-doe/workflow.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
> **SUPERSEDED (docs triage 2026-10-14).** The 2^6 factorial DoE guide, flagged obsolete 2026-10-09.
|
||||
> Instead: experiments/bare_metal/README.md for the DoE as it runs now. Moved here from `docs/working/experiments/02-experiments/factorial-doe/workflow.md`.
|
||||
|
||||
<!-- Moved from docs/02-experiments/factorial-doe/workflow.md to docs/working/archive/superseded/factorial-doe/workflow.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
|
||||
> **⚠ HISTORICAL (flagged 2026-10-09).** Documents the completed 2025-11-19 factorial
|
||||
> campaign whose data informed the current L8 design; the toggle architecture it runs on is
|
||||
+4
-1
@@ -1,4 +1,7 @@
|
||||
<!-- Moved from docs/03-architecture/physics-engine/feedback-loops-analysis.md to docs/working/architecture/03-architecture/physics-engine/feedback-loops-analysis.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
> **SUPERSEDED (docs triage 2026-10-14).** Flagged superseded 2026-10-09.
|
||||
> Instead: its own header. Moved here from `docs/working/architecture/03-architecture/physics-engine/feedback-loops-analysis.md`.
|
||||
|
||||
<!-- Moved from docs/03-architecture/physics-engine/feedback-loops-analysis.md to docs/working/archive/superseded/feedback-loops-analysis.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
|
||||
> **⚠ SUPERSEDED (flagged 2026-10-09).** Precursor bug-hunt audit covering six feedback loops;
|
||||
> the canonical, current reference is `feedback-loops.md` (all seven loops, tuning knobs, and
|
||||
+4
-1
@@ -1,4 +1,7 @@
|
||||
<!-- Moved from docs/02-experiments/heartbeat-doe/corrected-design.md to docs/working/experiments/02-experiments/heartbeat-doe/corrected-design.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
> **SUPERSEDED (docs triage 2026-10-14).** Flagged superseded 2026-10-09.
|
||||
> Instead: its own header. Moved here from `docs/working/experiments/02-experiments/heartbeat-doe/corrected-design.md`.
|
||||
|
||||
<!-- Moved from docs/02-experiments/heartbeat-doe/corrected-design.md to docs/working/archive/superseded/heartbeat-doe-corrected-design.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
|
||||
> **⚠ SUPERSEDED (flagged 2026-10-09).** Superseded by `phase2-corrected.md` (the
|
||||
> "corrected and finalized" revision). Kept for historical record.
|
||||
+4
-1
@@ -1,4 +1,7 @@
|
||||
<!-- Moved from docs/02-experiments/heartbeat-doe/design.md to docs/working/experiments/02-experiments/heartbeat-doe/design.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
> **SUPERSEDED (docs triage 2026-10-14).** Flagged superseded 2026-10-09.
|
||||
> Instead: its own header. Moved here from `docs/working/experiments/02-experiments/heartbeat-doe/design.md`.
|
||||
|
||||
<!-- Moved from docs/02-experiments/heartbeat-doe/design.md to docs/working/archive/superseded/heartbeat-doe-design.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
|
||||
> **⚠ SUPERSEDED (flagged 2026-10-09).** Pre-correction draft; superseded first by
|
||||
> `corrected-design.md`, then by `phase2-corrected.md` (the finalized design). Kept for
|
||||
+4
-1
@@ -1,4 +1,7 @@
|
||||
<!-- Moved from docs/03-architecture/heartbeat-system/implementation-plan.md to docs/working/architecture/03-architecture/heartbeat-system/implementation-plan.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
> **SUPERSEDED (docs triage 2026-10-14).** Flagged superseded 2026-10-09.
|
||||
> Instead: its own header. Moved here from `docs/working/architecture/03-architecture/heartbeat-system/implementation-plan.md`.
|
||||
|
||||
<!-- Moved from docs/03-architecture/heartbeat-system/implementation-plan.md to docs/working/archive/superseded/heartbeat-rate-logging-plan.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
|
||||
> **⚠ SUPERSEDED (flagged 2026-10-09).** Superseded by `instrumentation-plan.md`. Proposes the
|
||||
> earlier `HeartbeatRateSample` design; the live target is `HeartbeatTickSnapshot`
|
||||
+4
-1
@@ -1,4 +1,7 @@
|
||||
<!-- Moved from docs/03-architecture/adaptive-systems/loop-5-sketch.md to docs/working/architecture/03-architecture/adaptive-systems/loop-5-sketch.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
> **SUPERSEDED (docs triage 2026-10-14).** Flagged superseded 2026-10-09 (an early design sketch of Loop #5).
|
||||
> Instead: its own header; Loop #5 as built is v3/src/inference_engine.c. Moved here from `docs/working/architecture/03-architecture/adaptive-systems/loop-5-sketch.md`.
|
||||
|
||||
<!-- Moved from docs/03-architecture/adaptive-systems/loop-5-sketch.md to docs/working/archive/superseded/loop-5-sketch.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
|
||||
> **⚠ SUPERSEDED (flagged 2026-10-09).** Superseded by `window-inference-redesign.md`
|
||||
> (Levene's-test window inference — the shipped Loop #5 mechanism). This undated sketch ended
|
||||
+4
-1
@@ -1,4 +1,7 @@
|
||||
<!-- Moved from docs/03-architecture/physics-engine/steady-state-machine.md to docs/working/architecture/03-architecture/physics-engine/steady-state-machine.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
> **SUPERSEDED (docs triage 2026-10-14).** Flagged obsolete 2026-10-09.
|
||||
> Instead: its own header. Moved here from `docs/working/architecture/03-architecture/physics-engine/steady-state-machine.md`.
|
||||
|
||||
<!-- Moved from docs/03-architecture/physics-engine/steady-state-machine.md to docs/working/archive/superseded/steady-state-machine.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
|
||||
> **⚠ OBSOLETE (flagged 2026-10-09).** Conceptual precursor to the L8 Jacquard mode-selector
|
||||
> system; it never mentions Jacquard/L8, the attractor buckets, or the six named modes, and
|
||||
@@ -12,12 +12,12 @@ reorganization. They remain in `docs/` exactly where they were.
|
||||
| Path (unchanged) | What it is |
|
||||
|------------------|------------|
|
||||
| docs/patent/ (entire tree) | USPTO provisional patent: `main.tex` + `sections/`, compiled PDFs, USPTO forms (sb0015a/sb0016), `final_provisional/`, revision logs. |
|
||||
| docs/DARPA_SSM_Proposal_James.docx | DARPA SSM grant proposal (Word). |
|
||||
| docs/DARPA_SSM_Proposal_James.pdf | DARPA SSM grant proposal (PDF). |
|
||||
| docs/SSM_DARPA_Complete_Proposal_James_FINAL.docx | DARPA SSM complete/final proposal (Word, "FINAL"). |
|
||||
| docs/working/papers/proposals/DARPA_SSM_Proposal_James.docx | DARPA SSM grant proposal (Word). |
|
||||
| docs/working/papers/proposals/DARPA_SSM_Proposal_James.pdf | DARPA SSM grant proposal (PDF). |
|
||||
| docs/working/papers/proposals/SSM_DARPA_Complete_Proposal_James_FINAL.docx | DARPA SSM complete/final proposal (Word, "FINAL"). |
|
||||
| docs/SSM_DARPA_Summary_Slide.pptx | DARPA SSM summary slide deck. |
|
||||
| docs/SYSTEM_NARRATIVE.tex | Technical narrative written for patent counsel and reviewers. |
|
||||
| docs/SYSTEM_NARRATIVE.pdf | Compiled system narrative. |
|
||||
| docs/working/papers/SYSTEM_NARRATIVE.tex | Technical narrative written for patent counsel and reviewers. |
|
||||
| docs/working/papers/SYSTEM_NARRATIVE.pdf | Compiled system narrative. |
|
||||
|
||||
## Also deferred this pass (not legal, but left in place for safety)
|
||||
|
||||
@@ -26,7 +26,7 @@ risks breaking `\includegraphics`. Deferred to a later, build-verified pass.
|
||||
|
||||
| Path (unchanged) | What it is |
|
||||
|------------------|------------|
|
||||
| docs/ontology.tex / docs/ontology.pdf | Formal ontology LaTeX source + compiled PDF (strong `formal/` candidate). |
|
||||
| docs/working/papers/ontology.tex / docs/working/papers/ontology.pdf | Formal ontology LaTeX source + compiled PDF (strong `formal/` candidate). |
|
||||
| docs/ontology_diagrams.dot | Graphviz source for ontology diagrams. |
|
||||
| docs/fig_*.png / docs/fig_*.svg | Shared figure assets referenced by the ontology and/or system-narrative LaTeX. |
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
<!-- Moved from docs/ONTOLOGY.md to docs/working/papers/ONTOLOGY.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
<!-- Moved from docs/reference/ONTOLOGY.md to docs/working/papers/ONTOLOGY.md on 2026-06-16 (docs reorg Phase 2) -->
|
||||
# StarForth Ontology, Taxonomy, and Lexicon
|
||||
|
||||
**Version**: 1.0
|
||||
|
||||
Binary file not shown.
@@ -0,0 +1,338 @@
|
||||
% StarForth System Narrative
|
||||
% Technical overview for research reviewers, patent counsel, and future reference
|
||||
% Version 1.0 - 2025-12-13
|
||||
|
||||
\documentclass[11pt]{article}
|
||||
\usepackage[margin=1in]{geometry}
|
||||
\usepackage{amsmath,amssymb}
|
||||
\usepackage{graphicx}
|
||||
\usepackage{booktabs}
|
||||
\usepackage{hyperref}
|
||||
\usepackage{parskip}
|
||||
|
||||
\title{\textbf{StarForth System Narrative}\\
|
||||
\large The Story of a Provably Deterministic Adaptive Runtime}
|
||||
\author{StarForth Project}
|
||||
\date{December 13, 2025}
|
||||
|
||||
\begin{document}
|
||||
|
||||
\maketitle
|
||||
|
||||
\section*{Abstract}
|
||||
|
||||
This document presents the technical narrative of StarForth: a FORTH-79 virtual machine that achieves deterministic adaptive optimization through a thermodynamically-inspired feedback control system. We describe the problem, the approach, the implementation, and the experimental validation showing 0\% algorithmic variance across 90 independent runs. This is not marketing material. This is the technical story these systems and figures tell, presented for research evaluation and patent documentation.
|
||||
|
||||
\section{The Problem: Adaptive Runtimes Are Inherently Non-Deterministic}
|
||||
|
||||
Virtual machines optimize execution by learning from runtime behavior. The PyPy JIT compiler traces hot loops. The HotSpot JVM promotes frequently-executed methods. These systems work, but they share a fundamental limitation: \textit{adaptive optimization introduces non-determinism}.
|
||||
|
||||
Run the same program twice with the same input. The execution times differ. The compiled traces differ. The optimization decisions differ. Why? Because adaptive runtimes accumulate \textit{statistical noise}:
|
||||
|
||||
\begin{itemize}
|
||||
\item Execution frequency counters depend on scheduling jitter
|
||||
\item Cache eviction policies depend on memory pressure
|
||||
\item Threshold-based decisions amplify small timing variations
|
||||
\end{itemize}
|
||||
|
||||
For most applications, this non-determinism is acceptable. For safety-critical systems, real-time systems, and scientific reproducibility, it is not. The question becomes: \textit{Can an adaptive runtime be both adaptive and deterministic?}
|
||||
|
||||
\section{The Insight: Feedback Loops Converge to Attractors}
|
||||
|
||||
The key insight comes from dynamical systems theory. A system governed by feedback loops does not remain chaotic indefinitely. If the loops are properly designed, the system converges to a \textit{stable attractor}---a point in state space that the system approaches regardless of initial conditions.
|
||||
|
||||
Consider a simple example: exponential decay with constant input.
|
||||
|
||||
\begin{equation}
|
||||
\frac{df}{dt} = r - \lambda f(t)
|
||||
\end{equation}
|
||||
|
||||
where $f$ is execution frequency, $r$ is constant execution rate, and $\lambda$ is decay coefficient. This system has a fixed-point attractor at $f^* = r/\lambda$. Starting from any initial $f_0$, the system converges to $f^*$ exponentially:
|
||||
|
||||
\begin{equation}
|
||||
f(t) = f^* + (f_0 - f^*) e^{-\lambda t}
|
||||
\end{equation}
|
||||
|
||||
The transient term vanishes. The system forgets its initial conditions. This is \textit{deterministic convergence}.
|
||||
|
||||
The question shifts: Can we build an adaptive runtime where \textit{every metric} behaves this way?
|
||||
|
||||
\section{The Approach: Seven Coupled Feedback Loops}
|
||||
|
||||
StarForth implements seven feedback loops, each serving a specific purpose:
|
||||
|
||||
\subsection*{Loop \#1: Execution Heat Tracking (Positive Feedback)}
|
||||
|
||||
Every time a FORTH word executes, its frequency counter increments:
|
||||
|
||||
\begin{equation}
|
||||
f_{\text{word}} \gets f_{\text{word}} + 1
|
||||
\end{equation}
|
||||
|
||||
This is \textit{positive feedback}: more executions $\Rightarrow$ higher frequency $\Rightarrow$ higher cache rank $\Rightarrow$ faster lookups $\Rightarrow$ more executions.
|
||||
|
||||
\subsection*{Loop \#2: Rolling Window of Truth (Neutral Monitoring)}
|
||||
|
||||
A circular buffer records the last 4096 execution events:
|
||||
|
||||
\begin{equation}
|
||||
B[i \bmod 4096] = \text{word\_id}_i
|
||||
\end{equation}
|
||||
|
||||
This provides \textit{deterministic seeding}: every run replays the same initial history, eliminating variance from cold-start conditions.
|
||||
|
||||
\subsection*{Loop \#3: Linear Decay (Negative Feedback)}
|
||||
|
||||
A background heartbeat thread reduces frequency proportional to current value:
|
||||
|
||||
\begin{equation}
|
||||
f_{\text{word}} \gets f_{\text{word}} - \lambda \cdot f_{\text{word}} \cdot \Delta t
|
||||
\end{equation}
|
||||
|
||||
This is \textit{negative feedback}: high frequency $\Rightarrow$ fast decay $\Rightarrow$ lower frequency $\Rightarrow$ slow decay. The system stabilizes at an equilibrium where execution rate balances decay.
|
||||
|
||||
\subsection*{Loop \#4: Pipelining Metrics (Positive Feedback)}
|
||||
|
||||
The system tracks word-to-word transitions:
|
||||
|
||||
\begin{equation}
|
||||
P(B|A) = \frac{\text{count}(A \to B)}{\text{count}(A)}
|
||||
\end{equation}
|
||||
|
||||
High-probability transitions enable speculative prefetching, creating positive feedback in the instruction pipeline.
|
||||
|
||||
\subsection*{Loop \#5: Window Width Inference (Negative Feedback)}
|
||||
|
||||
Variance in metrics triggers adaptive window shrinking. Using Levene's test for variance homogeneity:
|
||||
|
||||
\begin{equation}
|
||||
\text{If } \text{Var}(w_{\text{current}}) > \text{Var}(w_{\text{candidate}}) \Rightarrow w \gets w_{\text{candidate}}
|
||||
\end{equation}
|
||||
|
||||
High variance $\Rightarrow$ smaller window $\Rightarrow$ lower variance. The system finds the \textit{variance inflection point}: the smallest window before variance begins to increase.
|
||||
|
||||
\subsection*{Loop \#6: Decay Slope Inference (Negative Feedback)}
|
||||
|
||||
The system infers optimal decay rate via exponential regression on rolling window data:
|
||||
|
||||
\begin{equation}
|
||||
\lambda^* = \arg\min_{\lambda} \sum_{i=1}^N \left[ \ln(f_i) - (\ln(f_0) - \lambda t_i) \right]^2
|
||||
\end{equation}
|
||||
|
||||
Unstable metrics $\Rightarrow$ steeper decay $\Rightarrow$ faster stabilization.
|
||||
|
||||
\subsection*{Loop \#7: Adaptive Heartbeat (Meta-Coordination)}
|
||||
|
||||
The heartbeat thread adjusts its tick rate based on system stability. Stable system $\Rightarrow$ slower ticks $\Rightarrow$ reduced overhead.
|
||||
|
||||
\section{The Implementation: Concrete Mechanisms}
|
||||
|
||||
These loops are not abstract concepts. They are implemented in strict ANSI C99:
|
||||
|
||||
\begin{description}
|
||||
\item[Execution frequency:] \texttt{uint64\_t execution\_heat} in \texttt{DictEntry} struct
|
||||
\item[Decay coefficient:] Q48.16 fixed-point stored in \texttt{physics.decay\_slope}
|
||||
\item[Rolling window:] Circular buffer in \texttt{rolling\_window\_of\_truth.c}
|
||||
\item[Transition probabilities:] Q48.16 fixed-point in \texttt{transition\_metrics}
|
||||
\item[Hot-words cache:] Array of top-$K$ entries sorted by frequency
|
||||
\item[Inference engine:] Levene's test + exponential regression in \texttt{inference\_engine.c}
|
||||
\item[Heartbeat system:] POSIX pthread in \texttt{vm.c}
|
||||
\end{description}
|
||||
|
||||
The system uses no floating-point arithmetic. All calculations use 64-bit integers or Q48.16 fixed-point. This eliminates rounding errors as a source of non-determinism.
|
||||
|
||||
\section{The Phase Space: Three Dimensions, One Attractor}
|
||||
|
||||
We characterize system state in three-dimensional phase space:
|
||||
|
||||
\begin{equation}
|
||||
\mathcal{S} = \{(w, \lambda, \sigma^2) \mid w \in \mathbb{N}, \lambda \in \mathbb{R}^+, \sigma^2 \in \mathbb{R}^+\}
|
||||
\end{equation}
|
||||
|
||||
where:
|
||||
\begin{itemize}
|
||||
\item $w$ = window size (number of events retained)
|
||||
\item $\lambda$ = decay coefficient (frequency reduction rate)
|
||||
\item $\sigma^2$ = variance (metric dispersion)
|
||||
\end{itemize}
|
||||
|
||||
Each execution trajectory is a path through this space. The central question: do all trajectories converge to the same point?
|
||||
|
||||
\section{The Experiment: 90 Independent Runs}
|
||||
|
||||
We designed a factorial experiment:
|
||||
\begin{itemize}
|
||||
\item 3 workload patterns (2-cycle, 3-cycle, random)
|
||||
\item 6 initial window sizes (512, 1024, 2048, 4096, 8192, 16384)
|
||||
\item 5 repetitions per configuration
|
||||
\item Total: $3 \times 6 \times 5 = 90$ independent runs
|
||||
\end{itemize}
|
||||
|
||||
Each run executes 1 million FORTH operations, records per-tick metrics, and computes steady-state statistics.
|
||||
|
||||
\section{The Results: 0\% Algorithmic Variance}
|
||||
|
||||
The data tell a clear story.
|
||||
|
||||
\subsection*{Finding 1: Deterministic Convergence}
|
||||
|
||||
All 90 runs converge to the \textit{same steady-state metrics}:
|
||||
|
||||
\begin{table}[h]
|
||||
\centering
|
||||
\begin{tabular}{lc}
|
||||
\toprule
|
||||
\textbf{Metric} & \textbf{Coefficient of Variation} \\
|
||||
\midrule
|
||||
Window size $w$ & $< 0.001\%$ \\
|
||||
Decay slope $\lambda$ & $< 0.001\%$ \\
|
||||
Variance $\sigma^2$ & $< 0.001\%$ \\
|
||||
\bottomrule
|
||||
\end{tabular}
|
||||
\caption{Variance across 90 independent runs. CV $\to$ 0 indicates deterministic convergence.}
|
||||
\end{table}
|
||||
|
||||
The coefficient of variation (CV = $\sigma/\mu$) measures relative dispersion. Values below 0.001\% are indistinguishable from measurement noise. The system exhibits \textit{zero algorithmic variance}.
|
||||
|
||||
\subsection*{Finding 2: Fixed-Point Attractor}
|
||||
|
||||
All execution trajectories converge to the same point in $(w, \lambda, \sigma^2)$ phase space:
|
||||
|
||||
\begin{equation}
|
||||
\mathbf{x}^* = (w^*, \lambda^*, \sigma^{*2}) = (4096, 2.3 \times 10^{-4}, 0.014)
|
||||
\end{equation}
|
||||
|
||||
This is a \textit{stable fixed-point attractor}. Regardless of initial conditions (window size, decay rate, workload pattern), the system reaches the same equilibrium.
|
||||
|
||||
\subsection*{Finding 3: Exponential Convergence}
|
||||
|
||||
Convergence is not gradual. It is exponential:
|
||||
|
||||
\begin{equation}
|
||||
\text{CV}(t) = \text{CV}_0 \cdot e^{-\alpha t}
|
||||
\end{equation}
|
||||
|
||||
where $\alpha \approx 5 \times 10^{-4}$ per tick. The system reaches steady state within 5000--10000 ticks (50--100 milliseconds on modern hardware).
|
||||
|
||||
\section{The Implications: What This Enables}
|
||||
|
||||
\subsection*{1. Reproducible Performance Characterization}
|
||||
|
||||
Run the same program twice. Get the same execution metrics. Not approximately. \textit{Exactly}. This enables:
|
||||
\begin{itemize}
|
||||
\item Regression testing for performance (detect 0.01\% slowdowns)
|
||||
\item A/B testing with statistical power (eliminate runtime variance)
|
||||
\item Deterministic replay for debugging (reproduce timing-dependent bugs)
|
||||
\end{itemize}
|
||||
|
||||
\subsection*{2. Provable Real-Time Bounds}
|
||||
|
||||
Traditional adaptive runtimes cannot guarantee worst-case execution time (WCET) because optimization decisions are non-deterministic. StarForth converges to a fixed optimization state, making WCET analysis tractable.
|
||||
|
||||
\subsection*{3. Scientific Reproducibility}
|
||||
|
||||
Publish a paper with performance benchmarks. Other researchers download the code, run the benchmarks, get the \textit{same numbers}. Not ``similar'' numbers. The same numbers.
|
||||
|
||||
\subsection*{4. Patent Claims}
|
||||
|
||||
The combination of:
|
||||
\begin{enumerate}
|
||||
\item Thermodynamically-inspired decay model ($f(t) = f_0 e^{-\lambda t}$)
|
||||
\item Coupled feedback loops (positive + negative)
|
||||
\item Deterministic seeding via rolling window
|
||||
\item Adaptive inference (Levene's test + exponential regression)
|
||||
\item Provable convergence to fixed-point attractor
|
||||
\end{enumerate}
|
||||
|
||||
constitutes a novel approach to adaptive runtime optimization. No prior art combines these elements.
|
||||
|
||||
\section{The Distinction: Metaphor vs. Implementation}
|
||||
|
||||
The system uses a \textit{thermodynamic metaphor}:
|
||||
\begin{itemize}
|
||||
\item Execution frequency $\leftrightarrow$ Thermal energy
|
||||
\item Exponential decay $\leftrightarrow$ Heat dissipation
|
||||
\item Steady-state equilibrium $\leftrightarrow$ Thermal equilibrium
|
||||
\end{itemize}
|
||||
|
||||
This is \textit{conceptual mapping}, not literal physics. The actual implementation uses:
|
||||
\begin{itemize}
|
||||
\item Integer counters (not temperature sensors)
|
||||
\item Exponential functions (not thermodynamic equations)
|
||||
\item Statistical inference (not physical measurement)
|
||||
\end{itemize}
|
||||
|
||||
The metaphor provides \textit{design intuition}. The mathematics provide \textit{formal guarantees}. This distinction is critical for patent claims and peer review.
|
||||
|
||||
\section{The Architecture: From Execution to Optimization}
|
||||
|
||||
The data flow is straightforward:
|
||||
|
||||
\begin{enumerate}
|
||||
\item \textbf{Execute word} $\Rightarrow$ increment frequency counter (Loop \#1)
|
||||
\item \textbf{Record event} $\Rightarrow$ update rolling window (Loop \#2)
|
||||
\item \textbf{Heartbeat tick} $\Rightarrow$ apply decay (Loop \#3)
|
||||
\item \textbf{Compute transitions} $\Rightarrow$ update probabilities (Loop \#4)
|
||||
\item \textbf{Detect variance} $\Rightarrow$ adjust window (Loop \#5)
|
||||
\item \textbf{Analyze trajectory} $\Rightarrow$ infer decay slope (Loop \#6)
|
||||
\item \textbf{Check stability} $\Rightarrow$ adjust heartbeat rate (Loop \#7)
|
||||
\item \textbf{Sort by frequency} $\Rightarrow$ populate hot-words cache
|
||||
\item \textbf{Lookup word} $\Rightarrow$ O(1) cache hit or O(log N) dictionary search
|
||||
\end{enumerate}
|
||||
|
||||
Each step is deterministic. Each output depends only on current state, not on timing jitter or external randomness.
|
||||
|
||||
\section{The Validation: How We Know It Works}
|
||||
|
||||
Three levels of validation:
|
||||
|
||||
\subsection*{Level 1: Unit Tests (936 Tests)}
|
||||
|
||||
Every component has isolated tests:
|
||||
\begin{itemize}
|
||||
\item Q48.16 fixed-point arithmetic (50 tests)
|
||||
\item Exponential regression (12 tests)
|
||||
\item Levene's test implementation (8 tests)
|
||||
\item FORTH-79 word semantics (850+ tests)
|
||||
\end{itemize}
|
||||
|
||||
All tests pass with zero failures.
|
||||
|
||||
\subsection*{Level 2: Integration Tests (Design of Experiments)}
|
||||
|
||||
The 90-run factorial experiment validates end-to-end system behavior. No mocking. No stubbing. Real execution with real metrics.
|
||||
|
||||
\subsection*{Level 3: Theoretical Analysis}
|
||||
|
||||
Mathematical proof of convergence via Banach fixed-point theorem:
|
||||
\begin{enumerate}
|
||||
\item Frequency evolution is contractive mapping ($\lambda > 0$)
|
||||
\item Contractive mappings have unique fixed points
|
||||
\item Rolling window provides deterministic initial conditions
|
||||
\item Therefore: all runs converge to same fixed point
|
||||
\end{enumerate}
|
||||
|
||||
The experimental data confirm the theoretical prediction.
|
||||
|
||||
\section{The Bottom Line}
|
||||
|
||||
StarForth demonstrates that adaptive optimization and deterministic execution are not mutually exclusive. The key is \textit{feedback control theory}: design loops that converge to attractors.
|
||||
|
||||
The system achieves:
|
||||
\begin{itemize}
|
||||
\item 0\% algorithmic variance (proven experimentally)
|
||||
\item Exponential convergence (proven theoretically)
|
||||
\item Fixed-point attractor (characterized empirically)
|
||||
\item Reproducible performance (validated across 90 runs)
|
||||
\end{itemize}
|
||||
|
||||
This is not a research prototype. This is a production-ready virtual machine running 936 regression tests, compiling with zero warnings, and achieving deterministic behavior under factorial experimental design.
|
||||
|
||||
The figures tell the story. The math proves the claims. The code implements the system.
|
||||
|
||||
\vspace{1em}
|
||||
\noindent\rule{\textwidth}{0.4pt}
|
||||
|
||||
\noindent\textit{This document is intended for technical evaluation by research institutions, government reviewers, and patent counsel. It presents factual descriptions of implemented systems and experimental results. No marketing claims. No speculative futures. Just the technical narrative these systems tell.}
|
||||
|
||||
\end{document}
|
||||
Binary file not shown.
@@ -0,0 +1,411 @@
|
||||
% StarForth Ontology - LaTeX Version
|
||||
% For inclusion in academic papers
|
||||
% Version 1.0 - 2025-12-13
|
||||
|
||||
\documentclass[11pt]{article}
|
||||
\usepackage{amsmath,amssymb,amsthm}
|
||||
\usepackage{graphicx}
|
||||
\usepackage{hyperref}
|
||||
\usepackage{enumitem}
|
||||
\usepackage{booktabs}
|
||||
\usepackage{tikz}
|
||||
\usetikzlibrary{positioning,shapes,arrows}
|
||||
\usepackage{algorithm}
|
||||
\usepackage{algpseudocode}
|
||||
|
||||
\title{StarForth Ontology: Formal Conceptual Framework for\\
|
||||
Thermodynamically-Inspired Adaptive Virtual Machine}
|
||||
\author{StarForth Project}
|
||||
\date{Version 1.0 -- December 13, 2025}
|
||||
|
||||
\begin{document}
|
||||
|
||||
\maketitle
|
||||
|
||||
\begin{abstract}
|
||||
This document establishes a formal ontology, taxonomy, and lexicon for the StarForth adaptive runtime system. We provide precise mathematical definitions to eliminate ambiguity in academic discourse, explicitly distinguishing metaphorical concepts (thermodynamic analogies) from literal implementations (frequency counters, exponential decay functions). This framework enables reproducible research and rigorous peer review.
|
||||
\end{abstract}
|
||||
|
||||
\tableofcontents
|
||||
\newpage
|
||||
|
||||
% ============================================================================
|
||||
\section{Introduction}
|
||||
|
||||
The StarForth adaptive runtime employs concepts from thermodynamics, dynamical systems theory, and statistical inference. To avoid imprecise terminology, this ontology provides:
|
||||
|
||||
\begin{itemize}
|
||||
\item \textbf{Formal definitions} with mathematical notation
|
||||
\item \textbf{Taxonomic hierarchy} of system components
|
||||
\item \textbf{Explicit scope limitations} (what is/isn't claimed)
|
||||
\item \textbf{Usage guidelines} for academic writing
|
||||
\end{itemize}
|
||||
|
||||
% ============================================================================
|
||||
\section{Core Lexicon}
|
||||
|
||||
\subsection{Primary Measurable Quantities}
|
||||
|
||||
\begin{description}[style=nextline]
|
||||
\item[Execution Frequency $f$]
|
||||
Count of times a dictionary entry has been executed, potentially adjusted by decay.
|
||||
\begin{equation}
|
||||
f(t) = f_0 \cdot e^{-\lambda t}
|
||||
\end{equation}
|
||||
where $f_0$ is initial frequency and $\lambda$ is decay coefficient.
|
||||
|
||||
\textit{Measurement}: Unsigned 64-bit integer (\texttt{uint64\_t execution\_heat}).
|
||||
|
||||
\textit{Note}: ``Heat'' is metaphorical naming; actual quantity is frequency.
|
||||
|
||||
\item[Decay Coefficient $\lambda$]
|
||||
Rate parameter controlling exponential reduction in execution frequency.
|
||||
\begin{equation}
|
||||
\lambda \in \mathbb{R}^+, \quad \text{units: } [1/\text{time}]
|
||||
\end{equation}
|
||||
|
||||
\textit{Measurement}: Derived via exponential regression; stored as Q48.16 fixed-point.
|
||||
|
||||
\item[Window Size $w$]
|
||||
Number of recent execution events retained in rolling buffer.
|
||||
\begin{equation}
|
||||
w \in [w_{\text{min}}, w_{\text{max}}], \quad w \in \mathbb{N}
|
||||
\end{equation}
|
||||
|
||||
\textit{Measurement}: Configurable parameter (default: 4096).
|
||||
\end{description}
|
||||
|
||||
\subsection{Derived Metrics}
|
||||
|
||||
\begin{description}[style=nextline]
|
||||
\item[Transition Probability $P(B|A)$]
|
||||
Conditional probability that word $B$ executes immediately after word $A$.
|
||||
\begin{equation}
|
||||
P(B|A) = \frac{\text{count}(A \to B)}{\text{count}(A)}
|
||||
\end{equation}
|
||||
|
||||
\item[Coefficient of Variation $CV$]
|
||||
Normalized measure of dispersion.
|
||||
\begin{equation}
|
||||
CV = \frac{\sigma}{\mu}
|
||||
\end{equation}
|
||||
where $\sigma$ is standard deviation and $\mu$ is mean.
|
||||
|
||||
\textit{Convergence criterion}: $CV \to 0$ as $t \to \infty$.
|
||||
|
||||
\item[Variance Inflection Point $w^*$]
|
||||
Window size where variance begins to increase when window shrinks.
|
||||
\begin{equation}
|
||||
w^* = \arg\min_{w \in [w_{\text{min}}, w_{\text{current}}]} \text{Var}(w)
|
||||
\end{equation}
|
||||
\end{description}
|
||||
|
||||
% ============================================================================
|
||||
\section{Mathematical Formalism}
|
||||
|
||||
\subsection{Frequency Evolution Model}
|
||||
|
||||
\textbf{Discrete-time update}:
|
||||
\begin{equation}
|
||||
f[t+1] = f[t] + \Delta_{\text{exec}}[t] - \Delta_{\text{decay}}[t]
|
||||
\end{equation}
|
||||
where
|
||||
\begin{align}
|
||||
\Delta_{\text{exec}}[t] &= \begin{cases}
|
||||
1 & \text{if word executed at tick } t \\
|
||||
0 & \text{otherwise}
|
||||
\end{cases} \\
|
||||
\Delta_{\text{decay}}[t] &= \lambda \cdot f[t] \cdot \Delta t
|
||||
\end{align}
|
||||
|
||||
\textbf{Continuous-time model}:
|
||||
\begin{equation}
|
||||
\frac{df}{dt} = r(t) - \lambda f(t)
|
||||
\end{equation}
|
||||
where $r(t)$ is execution rate [executions/second].
|
||||
|
||||
\textbf{Solution}:
|
||||
\begin{equation}
|
||||
f(t) = e^{-\lambda t} \left[ f_0 + \int_0^t r(\tau) e^{\lambda \tau} d\tau \right]
|
||||
\end{equation}
|
||||
|
||||
\subsection{Hot-Words Cache Selection}
|
||||
|
||||
Dictionary entry $e$ is cached if and only if:
|
||||
\begin{equation}
|
||||
\text{rank}(e) \leq K
|
||||
\end{equation}
|
||||
where
|
||||
\begin{equation}
|
||||
\text{rank}(e) = |\{e' \in \text{Dictionary} : f(e') > f(e)\}| + 1
|
||||
\end{equation}
|
||||
and $K$ is cache size (constant).
|
||||
|
||||
\subsection{Window Width Inference}
|
||||
|
||||
\textbf{Objective}: Find optimal window size $w^*$ minimizing variance.
|
||||
|
||||
\textbf{Method}: Binary search with Levene's test for variance homogeneity.
|
||||
|
||||
\begin{algorithm}[H]
|
||||
\caption{Variance Inflection Point Search}
|
||||
\begin{algorithmic}
|
||||
\State Initialize: $w_{\text{low}} \gets w_{\text{min}}, w_{\text{high}} \gets w_{\text{current}}$
|
||||
\While{$w_{\text{high}} - w_{\text{low}} > \epsilon$}
|
||||
\State $w_{\text{mid}} \gets \lfloor (w_{\text{low}} + w_{\text{high}}) / 2 \rfloor$
|
||||
\State Compute $\text{Var}(w_{\text{mid}})$ from trajectory
|
||||
\State Perform Levene's test: $F \gets \text{Levene}(w_{\text{mid}}, w_{\text{current}})$
|
||||
\If{$p\text{-value}(F) < \alpha$}
|
||||
\State $w_{\text{low}} \gets w_{\text{mid}}$ \Comment{Variance increased, search right}
|
||||
\Else
|
||||
\State $w_{\text{high}} \gets w_{\text{mid}}$ \Comment{Variance stable, search left}
|
||||
\EndIf
|
||||
\EndWhile
|
||||
\State \Return $w^* \gets w_{\text{mid}}$
|
||||
\end{algorithmic}
|
||||
\end{algorithm}
|
||||
|
||||
\subsection{Decay Slope Inference}
|
||||
|
||||
\textbf{Given}: Time series $\{(t_i, f_i)\}_{i=1}^N$ from rolling window.
|
||||
|
||||
\textbf{Model}: Exponential decay
|
||||
\begin{equation}
|
||||
f(t) = f_0 \cdot e^{-\lambda t}
|
||||
\end{equation}
|
||||
|
||||
\textbf{Log-transform}:
|
||||
\begin{equation}
|
||||
\ln(f) = \ln(f_0) - \lambda t
|
||||
\end{equation}
|
||||
|
||||
\textbf{Least squares solution}:
|
||||
\begin{equation}
|
||||
\lambda^* = \arg\min_{\lambda} \sum_{i=1}^N \left[ \ln(f_i) - (\ln(f_0) - \lambda t_i) \right]^2
|
||||
\end{equation}
|
||||
|
||||
Closed-form solution via linear regression on log-transformed data.
|
||||
|
||||
% ============================================================================
|
||||
\section{Taxonomy}
|
||||
|
||||
\subsection{Component Hierarchy}
|
||||
|
||||
\begin{enumerate}
|
||||
\item \textbf{Measurement Layer}
|
||||
\begin{itemize}
|
||||
\item Execution Frequency Tracking
|
||||
\item Temporal Recording (Rolling Window)
|
||||
\item Transition Tracking (Word-to-Word)
|
||||
\end{itemize}
|
||||
|
||||
\item \textbf{Transformation Layer}
|
||||
\begin{itemize}
|
||||
\item Decay Models (Linear, Exponential)
|
||||
\item Normalization (Ranking, Probability)
|
||||
\end{itemize}
|
||||
|
||||
\item \textbf{Inference Layer}
|
||||
\begin{itemize}
|
||||
\item Window Width Inference (Levene's Test)
|
||||
\item Decay Slope Inference (Exponential Regression)
|
||||
\end{itemize}
|
||||
|
||||
\item \textbf{Actuation Layer}
|
||||
\begin{itemize}
|
||||
\item Hot-Words Cache (Frequency-Sorted)
|
||||
\item Speculative Execution (Prefetch)
|
||||
\end{itemize}
|
||||
|
||||
\item \textbf{Coordination Layer}
|
||||
\begin{itemize}
|
||||
\item Heartbeat System (Time-Driven Ticks)
|
||||
\item Loop Orchestration
|
||||
\end{itemize}
|
||||
\end{enumerate}
|
||||
|
||||
\subsection{Feedback Loop Classification}
|
||||
|
||||
\begin{table}[h]
|
||||
\centering
|
||||
\begin{tabular}{@{}lll@{}}
|
||||
\toprule
|
||||
\textbf{Loop} & \textbf{Type} & \textbf{Mechanism} \\
|
||||
\midrule
|
||||
\#1 Execution Heat & Positive & $f \uparrow \Rightarrow \text{rank} \uparrow \Rightarrow \text{cache hit} \Rightarrow f \uparrow$ \\
|
||||
\#2 Rolling Window & Neutral & Record history (monitoring only) \\
|
||||
\#3 Linear Decay & Negative & $f \uparrow \Rightarrow \text{decay} \uparrow \Rightarrow f \downarrow$ \\
|
||||
\#4 Pipelining & Positive & Transition $\uparrow \Rightarrow$ prediction $\uparrow$ \\
|
||||
\#5 Window Inference & Negative & $\sigma^2 \uparrow \Rightarrow w \downarrow \Rightarrow \sigma^2 \downarrow$ \\
|
||||
\#6 Slope Inference & Negative & Unstable $\Rightarrow \lambda \uparrow \Rightarrow$ stabilize \\
|
||||
\#7 Adaptive Heartbeat & Meta & Stable $\Rightarrow$ slower ticks \\
|
||||
\bottomrule
|
||||
\end{tabular}
|
||||
\caption{Feedback loop classification by type and mechanism}
|
||||
\end{table}
|
||||
|
||||
% ============================================================================
|
||||
\section{Convergence Theory}
|
||||
|
||||
\subsection{Deterministic Convergence}
|
||||
|
||||
\begin{definition}[Deterministic Convergence]
|
||||
A system exhibits deterministic convergence if, for all executions $i, j$ of identical workloads:
|
||||
\begin{equation}
|
||||
\lim_{t \to \infty} \frac{|\text{metric}_i(t) - \text{metric}_j(t)|}{\sigma} < \epsilon
|
||||
\end{equation}
|
||||
where $\epsilon \to 0$ and $\sigma$ is pooled standard deviation.
|
||||
\end{definition}
|
||||
|
||||
\begin{theorem}[0\% Variance Convergence]
|
||||
Under continuous execution with fixed workload, the coefficient of variation of steady-state metrics approaches zero:
|
||||
\begin{equation}
|
||||
\lim_{t \to \infty} CV(t) = \lim_{t \to \infty} \frac{\sigma(t)}{\mu(t)} = 0
|
||||
\end{equation}
|
||||
\end{theorem}
|
||||
|
||||
\begin{proof}[Sketch]
|
||||
\begin{enumerate}
|
||||
\item Frequency evolution is governed by contractive mapping $T: f \mapsto f + r - \lambda f$.
|
||||
\item Fixed point $f^*$ exists by Banach fixed-point theorem when $\lambda > 0$.
|
||||
\item Rolling window deterministically seeds metrics from identical initial conditions.
|
||||
\item Levene's test-based adaptation reduces variance monotonically.
|
||||
\item Therefore, all runs converge to same fixed point $\Rightarrow \sigma \to 0$.
|
||||
\end{enumerate}
|
||||
\end{proof}
|
||||
|
||||
\subsection{Attractor Characterization}
|
||||
|
||||
\begin{definition}[Phase Space]
|
||||
The system state space is defined as:
|
||||
\begin{equation}
|
||||
\mathcal{S} = \{(w, \lambda, \sigma^2) \mid w \in \mathbb{N}, \lambda \in \mathbb{R}^+, \sigma^2 \in \mathbb{R}^+\}
|
||||
\end{equation}
|
||||
\end{definition}
|
||||
|
||||
\begin{definition}[Attractor]
|
||||
A point $\mathbf{x}^* = (w^*, \lambda^*, \sigma^{*2})$ is an attractor if:
|
||||
\begin{equation}
|
||||
\mathbf{x}_{t+1} = F(\mathbf{x}_t) \quad \text{and} \quad F(\mathbf{x}^*) = \mathbf{x}^*
|
||||
\end{equation}
|
||||
where $F$ is the state transition function.
|
||||
\end{definition}
|
||||
|
||||
Empirically, StarForth exhibits a \textit{stable fixed-point attractor} in $(w, \lambda, \sigma^2)$ space, confirmed across 90 experimental runs.
|
||||
|
||||
% ============================================================================
|
||||
\section{Metaphorical Mappings}
|
||||
|
||||
\subsection{Thermodynamic Analogy}
|
||||
|
||||
\begin{table}[h]
|
||||
\centering
|
||||
\begin{tabular}{@{}ll@{}}
|
||||
\toprule
|
||||
\textbf{Thermodynamic Concept} & \textbf{Execution Analog} \\
|
||||
\midrule
|
||||
Thermal Energy & Execution Frequency (count) \\
|
||||
Heat Dissipation & Exponential Decay ($e^{-\lambda t}$) \\
|
||||
Temperature & Normalized Frequency Rank \\
|
||||
Thermal Equilibrium & Steady-State Convergence \\
|
||||
Cooling Rate & Decay Coefficient $\lambda$ \\
|
||||
\bottomrule
|
||||
\end{tabular}
|
||||
\caption{Thermodynamic metaphor mapping (conceptual only)}
|
||||
\end{table}
|
||||
|
||||
\textbf{Important Caveat}: These are \textit{conceptual analogies}, not literal physical processes. No actual thermodynamic equations or hardware temperature measurements are involved.
|
||||
|
||||
% ============================================================================
|
||||
\section{Scope Limitations}
|
||||
|
||||
\subsection{What This Framework DOES Cover}
|
||||
\begin{itemize}
|
||||
\item Execution frequency measurement and temporal decay
|
||||
\item Adaptive caching via frequency-based ranking
|
||||
\item Statistical inference for parameter tuning
|
||||
\item Dynamical systems characterization of convergence
|
||||
\end{itemize}
|
||||
|
||||
\subsection{What This Framework DOES NOT Cover}
|
||||
\begin{itemize}
|
||||
\item Actual thermodynamic processes or physics simulations
|
||||
\item Machine learning or neural network training
|
||||
\item Quantum computing or quantum-inspired algorithms
|
||||
\item Biological neural systems or biomimicry
|
||||
\end{itemize}
|
||||
|
||||
% ============================================================================
|
||||
\section{Usage Guidelines}
|
||||
|
||||
\subsection{Academic Writing Conventions}
|
||||
|
||||
\paragraph{In Abstracts/Titles:} Use precise, non-metaphorical terminology.
|
||||
\begin{itemize}
|
||||
\item {\color{green!50!black}$\checkmark$} ``Thermodynamically-Inspired Adaptive Runtime''
|
||||
\item {\color{red}$\times$} ``Physics-Based Virtual Machine''
|
||||
\end{itemize}
|
||||
|
||||
\paragraph{In Technical Sections:} Qualify metaphors explicitly.
|
||||
\begin{quote}
|
||||
``We employ a \textit{thermodynamic metaphor} where execution frequency is treated as `heat' that dissipates exponentially over time, mathematically modeled as $f(t) = f_0 e^{-\lambda t}$.''
|
||||
\end{quote}
|
||||
|
||||
\paragraph{In Formalism:} Use mathematical definitions, not analogies.
|
||||
\begin{itemize}
|
||||
\item {\color{green!50!black}$\checkmark$} ``Frequency evolves as $df/dt = r(t) - \lambda f(t)$''
|
||||
\item {\color{red}$\times$} ``Heat cools like Newton's law of cooling''
|
||||
\end{itemize}
|
||||
|
||||
% ============================================================================
|
||||
\section{Conclusion}
|
||||
|
||||
This ontology provides a formal foundation for precise academic discourse on the StarForth adaptive runtime system. By explicitly distinguishing metaphorical concepts from literal implementations, we enable rigorous peer review and reproducible research.
|
||||
|
||||
% ============================================================================
|
||||
\appendix
|
||||
\section{Notation Summary}
|
||||
|
||||
\begin{table}[h]
|
||||
\centering
|
||||
\begin{tabular}{@{}ll@{}}
|
||||
\toprule
|
||||
\textbf{Symbol} & \textbf{Definition} \\
|
||||
\midrule
|
||||
$f$ & Execution frequency \\
|
||||
$\lambda$ & Decay coefficient \\
|
||||
$w$ & Window size \\
|
||||
$K$ & Cache size \\
|
||||
$\sigma$ & Standard deviation \\
|
||||
$\mu$ & Mean \\
|
||||
$CV$ & Coefficient of variation \\
|
||||
$P(B|A)$ & Transition probability \\
|
||||
$w^*$ & Variance inflection point \\
|
||||
$\mathcal{S}$ & State space \\
|
||||
\bottomrule
|
||||
\end{tabular}
|
||||
\caption{Mathematical notation used in this document}
|
||||
\end{table}
|
||||
|
||||
% ============================================================================
|
||||
\bibliographystyle{plain}
|
||||
\begin{thebibliography}{9}
|
||||
|
||||
\bibitem{strogatz2015}
|
||||
Strogatz, S. (2015). \textit{Nonlinear Dynamics and Chaos: With Applications to Physics, Biology, Chemistry, and Engineering}. Westview Press.
|
||||
|
||||
\bibitem{astrom2008}
|
||||
Åström, K. J., \& Murray, R. M. (2008). \textit{Feedback Systems: An Introduction for Scientists and Engineers}. Princeton University Press.
|
||||
|
||||
\bibitem{casella2002}
|
||||
Casella, G., \& Berger, R. L. (2002). \textit{Statistical Inference}. Duxbury Press.
|
||||
|
||||
\bibitem{bolz2009}
|
||||
Bolz, C. F., Cuni, A., Fijalkowski, M., \& Rigo, A. (2009). Tracing the meta-level: PyPy's tracing JIT compiler. In \textit{Proceedings of the 4th workshop on the Implementation, Compilation, Optimization of Object-Oriented Languages and Programming Systems} (pp. 18-25).
|
||||
|
||||
\bibitem{ertl1996}
|
||||
Ertl, M. A. (1996). Stack caching for interpreters. In \textit{ACM SIGPLAN Notices} (Vol. 30, No. 6, pp. 315-327).
|
||||
|
||||
\end{thebibliography}
|
||||
|
||||
\end{document}
|
||||
Binary file not shown.
Binary file not shown.
Binary file not shown.
@@ -14,7 +14,7 @@ extracted here.
|
||||
|
||||
## See also
|
||||
|
||||
- [`docs/03-architecture/word-acl/README.md`](../../03-architecture/word-acl/README.md)
|
||||
- [`docs/reference/word-acl/README.md`](../../03-architecture/word-acl/README.md)
|
||||
— the ACL spec, which has not been moved into this directory.
|
||||
- [`docs/working/README.md`](../README.md) — the full `working/` layout.
|
||||
- [Project root](../../../README.md)
|
||||
|
||||
Reference in New Issue
Block a user