admin/LithosAnanake
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
db8a3e0fd980ea0ecb572848c6dcd0ba7c7165b8
LithosAnanake/.claude/CLAUDE.md
T

32 KiB
Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Note: There is also a docs/CLAUDE.md (older, hosted-only snapshot). This file at .claude/CLAUDE.md is the authoritative reference.

Tripod: .claude/TRIPOD.md is authoritative for all Tripod VM (Hera/Hermes/Artemis) work. Read it completely before touching any Tripod code. Hermes: .claude/HERMES.md is authoritative for all Hermes VM work. Read before touching Hermes. Artemis: .claude/ARTEMIS.md is authoritative for all Artemis VM work. Read before touching Artemis.

Hard Rules — Captain Bob's Law

  • NEVER CREATE A BRANCH WITHOUT EXPLICIT PERMISSION FROM THE USER. Work on the branch you are given or already on. Do not create feature branches, session branches, or any other branch unless the user explicitly asks. This applies every time, not just once per session — re-confirm before creating a branch even if one was created earlier in the same conversation.
  • NEVER WORK ON MASTER. master is a production branch. All development happens on feature or integration branches. If you find yourself on master, stop and ask.
  • BRANCH TOPOLOGY — know which production line you're on. master (origin) is StarForth production (the hosted VM). lithosananke is LithosAnanke production (the bare-metal kernel), branched off master and diverging intentionally from it — see "On Tags" below. A task about StarKernel, capsules, Tripod/Hermes/Artemis, or anything bare-metal belongs on lithosananke, not on a branch cut from master. If a session's assigned branch doesn't have .claude/ARTEMIS.md, .claude/HERMES.md, .claude/TRIPOD.md, that is a signal you're on the wrong line — stop and confirm with the user before doing any further work, rather than proceeding against a stale/wrong-branch view of these instructions.
  • NEVER STASH WITHOUT EXPLICIT PERMISSION. git stash hides work and creates debt. If the working tree is dirty, report it and wait for instructions. Do not stash to work around a problem.
  • NEVER APPLY A FIX NOT EXPLICITLY REQUESTED. If you identify a bug, report it. Do not fix it unless the user says to. Initiative on code changes causes damage.
  • USE A SUBVERSION-LIKE WORKFLOW. Commit and push directly to the working branch. No detours, no side branches, no pull requests unless explicitly requested.
  • AFTER ANY OUT-OF-BRANCH WORK (switching branches, resetting, fetching, etc.) always return to the correct working branch and do a full git fetch + git pull to ensure the working tree is clean and current before continuing.
  • ALWAYS START CLEAN. Before doing any work, verify git status is clean and the branch is the correct one. No surprises.
  • ANNOUNCE THE BRANCH at the start of every session resumption. First line of output after context load: state the current branch and last commit.

Lessons Learned — Hard-Won in the Field

On Tags

  • Tags are sacred ground. Each tag has logs attached proving its state. When in doubt about the correct state of any file or branch, look at the tag first. git show <tag> and git log <tag> are your oracle.
  • Two same-day tags = two production targets. v3.1.0 = StarForth hosted (master). v1.5.3 = LithosAnanke bare metal (lithosananke). They diverge intentionally.

On the FORTH Dictionary

  • BIRTH, RUN, USE are primitives — registered in C exactly like DUP, BYE, EXEC. Use ' BIRTH directly. Never reach for FIND, never add conditionals, never rename them to CAPSULE-BIRTH or anything else.
  • FIND is a proven, tested, registered word. Never modify it. The implementation is intentionally non-standard (parses from input stream). It is tested. Leave it alone.
  • Never modify a registered, tested word to "fix" it. If something seems wrong with a word, the problem is almost certainly in the caller, not the word.
  • ACL policy belongs in ACL.4th, never in C. No policy logic in kernel_main.c, no vm_find_word + field assignment for pinning. Use ' WORD ACL-PIN in FORTH exactly as IMMEDIATE works.
  • ' BIRTH in shared capsules breaks the hosted build — BIRTH is kernel-only. Pin it in a kernel-specific capsule, not in ACL.4th which is shared.

On the Two Production Targets

  • Every change to shared VM code must compile and behave on both targets. src/vm.c, include/vm.h, capsules/, src/word_source/ are shared. Gate with #ifdef __STARKERNEL__ or #ifdef STARFORTH_ENABLE_VM.
  • The only valid acceptance test is the three-arch QEMU boot (see QEMU section below). Tests run automatically at binary startup — no separate test target exists.
  • INPUT_BUFFER_SIZE must be 1025. vm_interpret() is the shared dispatch path for BOTH interactive REPL lines AND block content from LOAD. LOAD copies up to 1024 bytes from block RAM and calls vm_interpret() directly; with a 256-byte cap, everything past byte 255 is silently dropped. 1025 = 1024 content bytes + 1 NUL terminator.

On Working Style

  • When told to stop, stop immediately. Do not make one more change. Do not commit "just to clean up". Stop.
  • Show the plan and wait for yes before destructive operations (force push, reset --hard, branch deletion). The user will say yes explicitly when ready.
  • Do not over-engineer. If the user says "BIRTH is a primitive", that is the complete specification. No conditionals, no fallbacks, no renamed variants.
  • Capsule subsystem wiring belongs in sk_vm_bootstrap.c, not kernel_main.c. The bootstrap owns VM init; kernel_main owns hardware milestones.
  • Compose in FORTH first. Before writing any new C primitive, exhaust the existing vocabulary. New C words are justified only for raw hardware access, atomics, syscalls, or freestanding kernel ops.

Word-Level ACL System — Complete through Phase 7

Design doc: docs/03-architecture/word-acl/DESIGN.md

The word-level ACL system is fully implemented and validated. Read the design doc before touching any ACL-related code. Key constraints:

  • All policy logic in ACL.4th — no new C primitives for policy
  • Four C fields: acl_ttl + acl_allow + acl_mode + acl_pinned in DictEntry
  • Two VM flags: emergency_console (fault handler active) + zuse_session (superuser authenticated)
  • ACL.4th is self-activating — init.4th only needs S" ACL.4th" EXEC (commented out by default)
  • Pin (ACL-PIN) is one-way; inheritance clears pin, copies mode
  • Two permanent console layers: emergency (ok>) and zuse (zuse)ok>)
  • Superuser zuse defined by capsules/zuse.4th, loaded by ACL.4th at boot
  • emergency_console bypass applies ONLY to bare ok> REPL — zuse sessions are subject to ACL

Implementation phases:

  1. ✅ C Infrastructure — DictEntry fields + interpreter hook + acl_recheck()
  2. ✅ ACL.4th — FORTH policy words + ACL-INIT-PRIMITIVES + self-activation
  3. ✅ capsules/zuse.4th — bootstrap superuser skeleton; CA root placeholder in ACL.4th
  4. ✅ init.4th opt-in toggle — \ S" ACL.4th" EXEC (comment out = no security)
  5. ✅ POST tests (800/800) + Isabelle/HOL proofs (5 theory files)
  6. ✅ EMERGENCY_CONSOLE_ENABLED build flag + vm_fault_handler extension point
  7. ✅ LithosAnanke parity — kernel ACL hook wired; all three ISAs boot to zuse)ok> (confirmed in log)
  8. ⬜ PKI / thumbdrive — Ed25519 challenge-response; user minting by zuse

Bug resolutions (all fixed, branch feature/acl-rwt):

  • Bug 1 ✅: Kernel ACL interpreter hook ported to src/starkernel/vm/vm_core.c
  • Bug 2 ✅: emergency_console set per-iteration in src/starkernel/repl.c (zuse_session ? 0 : 1)
  • Bug 3 ✅: !vm->zuse_session bypass removed from src/vm.c ACL checks

ACL-RWT DoE campaign (branch feature/acl-rwt, June 15–16 2026):

  • 3×3 Latin square: seeds 12345/67890/13579 × amd64/aarch64/riscv64, 30 reps each
  • This IS the first true ACL-active campaign (Bug 1 fixed before runs)
  • Results: +0.0054%–+0.0088% overhead across all 9 cells; CV = 0.000%
  • ISA gap closed: ACL-RWT vs Floor=16 is three orders of magnitude improvement
  • Baseline (no ACL): amd64=261,098 ticks; aarch64/riscv64=261,095 ticks
  • Report: experiments/bare_metal/analysis/report/bare_metal_doe_report.pdf (19 pages)
    • 5 R-generated vector figure pairs (10 SVGs via ggplot2/svglite)
    • All data from confirmed measured tick counts — patent support material

Pick up here next session:

  1. Phase 8 — PKI / Ed25519 thumbdrive (challenge-response; user minting by zuse)

Project Overview

StarForth is a FORTH-79 compliant virtual machine written in strict ANSI C99, featuring a physics-driven adaptive runtime. It is the primary execution engine for StarshipOS and runs standalone on Linux and bare metal via LithosAnanke (StarKernel). (HISTORICAL: L4Re/Fiasco.OC was a supported platform target through mid-2026; removed as an active target.)

Key distinguishing features:

  • Physics-grounded self-adaptive runtime with formally proven deterministic behavior (0% algorithmic variance across 90 experimental runs)
  • 7 feedback loops driving runtime optimization while preserving determinism
  • Formally verified with 19 Isabelle/HOL theory files covering all loops and word categories
  • Bare-metal UEFI kernel (LithosAnanke v1.5.3) enabling native execution without Linux
  • Patent pending on adaptive runtime mechanisms
  • Published SSRN paper: papers/James_Steady-State_Convergence_Adaptive_Runtime.pdf

Technology stack:

┌─────────────────────────────────────────────────────────────────┐
│  StarshipOS (future — self-hosting OS)                          │
├─────────────────────────────────────────────────────────────────┤
│  LithosAnanke v1.5.3)    │
│  ← Milestones M0–M6 complete; M7 VM integration in progress →  │
├─────────────────────────────────────────────────────────────────┤
│  StarForth v3.1.0  (FORTH-79 VM + physics-driven adaptive RT)   │
├───────────────────────────┬─────────────────────────────────────┤
│  Linux                    │  Bare metal (amd64, aarch64, riscv) │
└───────────────────────────┴─────────────────────────────────────┘

Build Commands

StarForth VM (hosted)

# Standard optimized build (auto-detects architecture)
make

# Maximum performance build (ASM + LTO + direct threading)
make fastest

# Profile-guided optimization build
make pgo

# Debug build with symbols
make debug

# Quick benchmark
make bench

# Clean build artifacts
make clean

StarKernel / LithosAnanke (bare metal)

# Build UEFI kernel (amd64, requires cross toolchain or native gcc)
make -f Makefile.starkernel

# Build for aarch64
make -f Makefile.starkernel ARCH=aarch64

# Build for riscv64
make -f Makefile.starkernel ARCH=riscv64

# Run in QEMU with OVMF
make -f Makefile.starkernel qemu

# Enable VM integration (M7)
make -f Makefile.starkernel STARFORTH_ENABLE_VM=1

Output: build/amd64/kernel/starkernel_loader.efi (UEFI PE32+ executable)

Build Targets and Architectures

  • TARGET=standard|fast|fastest|turbo|pgo - VM build profiles
  • ARCH=x86_64|amd64|aarch64|arm64|raspi|riscv64 - Target architecture
  • Cross-compile for Raspberry Pi: make rpi4-cross

Key Build Flags

  • STRICT_PTR=1 - Enforce pointer safety checks (default on)
  • USE_ASM_OPT=1 - Enable architecture-specific assembler optimizations
  • ENABLE_HOTWORDS_CACHE=1 - Physics-driven hot-words cache (default on)
  • ENABLE_PIPELINING=1 - Speculative execution via word transition prediction (default on)
  • HEARTBEAT_THREAD_ENABLED=1 - Background heartbeat thread for adaptive tuning (default on)
  • STARFORTH_ENABLE_VM=1 - Enable VM integration in StarKernel (M7)
  • PARITY_MODE=1 - Deterministic parity harness mode
  • EMERGENCY_CONSOLE_ENABLED=1 - Interactive fault handler / error recovery REPL (default on; set 0 for production or embedded builds to strip interactive fallthrough surface)

Important: Linker Configuration

The fastest target uses -flto=auto -fuse-linker-plugin instead of plain -flto to avoid "ELF section name out of range" errors with large codebases.

Running

./build/amd64/standard/starforth              # Interactive REPL
./build/amd64/standard/starforth --run-tests  # Run tests then REPL
./build/amd64/standard/starforth -c "1 2 + . BYE"  # Execute inline code

DoE (Design of Experiments) Mode

./build/amd64/fastest/starforth --doe

The --doe flag runs the full test harness. The CSV metrics row has been suppressed as of 2025-12-08 (redundant with internal VM metrics). See src/main.c:390-396. To re-enable, add a --csv-export flag or write to a file.

Kernel via QEMU

ACCEPTANCE CRITERIA — non-negotiable: The ONLY valid acceptance test for any kernel change is booting all three architectures in QEMU and capturing the serial log. There is no other test. make test (hosted VM) is NEVER used to validate kernel changes.

# Run in this exact order for every kernel change:
make -f Makefile.starkernel ARCH=amd64   clean qemu
make -f Makefile.starkernel ARCH=aarch64 clean qemu
make -f Makefile.starkernel ARCH=riscv64 clean qemu

QEMU rule — non-negotiable: Only ONE QEMU instance may run at a time, always in the foreground (never backgrounded). All three instances use accel=tcg (software emulation); concurrent runs compete for host CPU and corrupt the timing signal the DoE measures. Run each architecture to completion before starting the next.

Session keep-alive: When running from a mobile device, ping the session every 15–20 minutes during a QEMU run or the session will idle out. amd64 is particularly slow under TCG and is the most likely to outlast a silent interval. Captain Bob must stay engaged during long runs (30-rep DoE ≈ 25–30 min per ISA).

Always pass clean before qemu — never build-only without clean. Serial output is automatically captured to:

logs/YYYYMMDD-HHMMSS/amd64/qemu-amd64-YYYYMMDD-HHMMSS.log
logs/YYYYMMDD-HHMMSS/aarch64/qemu-aarch64-YYYYMMDD-HHMMSS.log
logs/YYYYMMDD-HHMMSS/riscv64/qemu-riscv64-YYYYMMDD-HHMMSS.log

These logs are audit artifacts — they are committed to the repo. Do not delete them. Do not claim a change is accepted until all three architectures have booted to zuse)ok> and their logs are present in logs/.

Architecture

Source Tree

src/
├── main.c                         # Entry point, CLI, VM init, DoE mode
├── vm.c                           # Interpreter loop, stacks, dictionary state
├── vm_api.c                       # External VM API
├── vm_bootstrap.c                 # VM bootstrap initialization
├── vm_debug.c                     # Debugging utilities
├── vm_time.c                      # Time-related VM operations
├── repl.c                         # REPL read-eval-print loop
├── cli.c                          # CLI parsing
├── io.c                           # I/O operations
├── log.c                          # Logging infrastructure
├── memory_management.c            # Dictionary allocator
├── dictionary_management.c        # Dictionary allocation & search
├── dictionary_heat_optimization.c # Heat tracking (Loop #1)
├── word_registry.c                # Word registration system
├── block_subsystem.c              # Logical→physical block mapper
├── blkio_*.c                      # Block I/O backends (file, RAM, factory)
├── stack_management.c             # Stack operations
├── math_portable.c                # Portable math functions
├── profiler.c                     # Performance profiling
├── heartbeat_export.c             # Heartbeat metrics export
├── ssm_jacquard.c                 # L8 Jacquard steady-state machine
├── doe_metrics.c                  # Design of Experiments metrics (2^7 factorial)
│
├── Physics Engine (7 Feedback Loops):
├── physics_runtime.c              # Main physics coordinator
├── physics_hotwords_cache.c       # Loop #1: Hot-words caching
├── physics_metadata.c             # Metadata tracking
├── physics_pipelining_metrics.c   # Loop #4: Word transition prediction
├── physics_execution_hooks.c      # Execution instrumentation
├── rolling_window_of_truth.c      # Loop #2: Circular execution history
├── inference_engine.c             # Loops #5/#6: ANOVA + statistical inference
│
├── word_source/                   # 25 FORTH-79 word implementation files
│   ├── arithmetic_words.c         # + - * / MOD ABS MIN MAX
│   ├── stack_words.c              # DUP DROP SWAP ROT OVER NIP TUCK
│   ├── control_words.c            # IF ELSE THEN DO LOOP BEGIN UNTIL WHILE
│   ├── defining_words.c           # : ; CREATE DOES> VARIABLE CONSTANT
│   ├── memory_words.c             # @ ! C@ C! MOVE FILL
│   ├── return_stack_words.c       # >R R> R@ RDROP 2>R 2R@ 2R>
│   ├── double_words.c             # 2DUP 2DROP 2SWAP 2@ 2! D+ D-
│   ├── logical_words.c            # AND OR XOR NOT INVERT LSHIFT RSHIFT
│   ├── io_words.c                 # EMIT KEY TYPE CR TAB SPACE ACCEPT
│   ├── string_words.c             # S" SLITERAL string operations
│   ├── block_words.c              # BLOCK BUFFER LOAD THRU FLUSH
│   ├── format_words.c             # .( .R .S HEX DECIMAL BASE
│   ├── system_words.c             # BYE ABORT INCLUDE STATE
│   ├── dictionary_words.c         # FIND SEARCH-WORDLIST WORDS
│   ├── vocabulary_words.c         # VOCABULARY DEFINITIONS FORTH-WORDLIST
│   ├── q48_16_words.c             # Q48.16 fixed-point word definitions
│   ├── starforth_words.c          # StarForth-specific extensions
│   ├── physics_benchmark_words.c  # Benchmark harness (L1-L7)
│   ├── physics_diagnostic_words.c # Physics diagnostics (WORD-ENTROPY)
│   ├── physics_freeze_words.c     # PHYSICS-FREEZE / PHYSICS-THAW
│   └── physics_pipelining_diagnostic_words.c
│
├── test_runner/                   # 936+ test cases
│   ├── test_runner.c              # Test harness orchestration
│   ├── test_common.c              # Shared test utilities
│   ├── test_contracts.c           # Contract-based testing
│   └── modules/                   # 22 per-category test files
│       ├── arithmetic_words_test.c
│       ├── stack_words_test.c ... (22 files, incl. integration & stress)
│
├── platform/                      # Platform abstraction (hosted)
│   ├── linux/time.c               # POSIX timing
│   └── l4re/time.c                # HISTORICAL: L4Re timing, no longer wired into any build
│
└── starkernel/                    # LithosAnanke bare-metal kernel (37 files)
    ├── kernel_main.c              # Kernel entry point (M0–M7 milestones)
    ├── repl.c                     # Kernel REPL
    ├── arch/amd64/                # AMD64: arch.c apic.c timer.c interrupts.c boot.S isr.S
    ├── boot/                      # uefi_loader.c elf_loader.c reloc_stub.c reloc.S
    ├── capsule/                   # capsule_birth.c capsule_run.c capsule_loader.c
    │                              #   capsule_find.c capsule_validate.c capsule_vm_hooks.c
    │                              #   mama_forth_words.c
    ├── hal/                       # hal.c console.c memory.c host_services.c
    ├── memory/                    # kmalloc.c pmm.c vmm.c
    ├── math/q48_16.c              # Q48.16 fixed-point (kernel build)
    ├── hash/xxhash64.c            # XXHash64 (content addressing)
    └── vm/                        # Kernel VM subsystem
        ├── bootstrap/sk_vm_bootstrap.c
        ├── host/shim.c
        ├── vm_core.c vm_runtime.c vm_bootstrap.c
        ├── parity.c               # Birth/execution parity logging
        ├── arena.c                # Capsule arena allocator
        └── alloc_kernel.c

LithosAnanke / StarKernel

LithosAnanke ("stone inevitability") is the bare-metal UEFI kernel that boots StarForth directly on hardware. Version 1.5.3, monolithic UEFI PE32+ executable.

Boot sequence:

UEFI Firmware → uefi_loader.c (BOOTX64.EFI)
    ExitBootServices() → owns hardware
    BootInfo{memory map, ACPI, framebuffer}
    → kernel_main()
        M1: Console init (UART 16550 + framebuffer)
        M2: PMM (physical memory manager, bitmap)
        M3: VMM (4-level x86_64 paging)
        M4: IDT + APIC interrupts
        M5: TSC + HPET + APIC timer (100 Hz heartbeat)
        M6: kmalloc heap
        M7: StarForth VM bootstrap + capsule loading → "ok" REPL

Milestone status (as of v1.5.3):

  • ✅ M0–M5: complete (verified with QEMU/OVMF, three-arch tested)
  • ✅ M6: kmalloc infrastructure present (full validation deferred)
  • 🔄 M7: VM integration in progress (capsule execution pipeline partially wired)

Kernel memory layout:

  • Kernel heap: 16 MB (kmalloc)
  • Block RAM (LBN 0–991): 1 MB dedicated RAM blocks
  • Kernel ramdrive (LBN 2048–3071): 1 MB for capsule loading
  • LBN 2048 = entry point for init.4th

LinkerScripts in linker/:

  • starkernel-loader-amd64.ld — UEFI loader
  • starkernel-loader-amd64-pe.ld — PE32+ format
  • starkernel-kernel-amd64.ld — ELF kernel (split build)
  • starkernel-amd64.ld — monolithic build

Capsule System

Capsules are immutable, content-addressed VM initialization payloads. A capsule ID is its XXHash64 content hash — any mutation is detectable.

Capsule types:

  • (m) MAMA_INIT — exactly one Mama VM initialization capsule
  • (p) PRODUCTION — truth-bearing baby VM initializers
  • (e) EXPERIMENT — DoE workload-only initializers

Birth protocol: locate by name → validate hash → allocate VM ID → execute IDENTITY (capsule code) → execute PERSONALITY (block 1 from ramdrive) → log parity record (VM ID + capsule hash + dict hash).

Capsule files in capsules/ (17 .4th files):

  • init.4th — default Mama VM personality
  • init-0.4th through init-9.4th — numbered variants
  • init-l8-{stable,volatile,diverse,temporal,transition,omni}.4th — L8 Jacquard variants

Tool tools/mkcapsule.c assembles .4th files into the binary capsule directory format (capsule_generated.c) baked into the kernel image.

ACL capsules (implemented):

  • capsules/ACL.4th — word-level ACL system; self-activating; contains CA root placeholder
  • capsules/zuse.4th — bootstrap superuser; loaded by ACL.4th at boot

MANDATORY: Read before writing capsules. Before writing or modifying any .4th capsule file, read experiments/bare_metal/README.md in full. The block namespace is shared across all loaded capsules; violations cause silent word-definition collisions and corrupt the DoE. Block ranges are:

  • 2048–2099 — init.4th only
  • 2100–2199 — doe.4th only
  • 3000–3999 — workload capsules
  • 4000+ — user-defined capsules (ACL.4th, zuse.4th, etc.) Each block header line counts against the 1024-byte limit. Any block exceeding 1024 bytes is truncated silently at load time — verify with wc -c before committing.

Physics-Driven Adaptive Runtime

Uses thermodynamic metaphors as modeling language (see ONTOLOGY.md):

  1. Loop #1 — Execution Heat (dictionary_heat_optimization.c) — frequency counter per word
  2. Loop #2 — Rolling Window (rolling_window_of_truth.c) — circular buffer, execution history
  3. Loop #3 — Linear Decay — quiescent words lose heat over time
  4. Loop #4 — Pipelining (physics_pipelining_metrics.c) — word-to-word transition prediction
  5. Loop #5 — Window Width Inference (inference_engine.c) — Levene's test, binary chop
  6. Loop #6 — Decay Slope Inference (inference_engine.c) — exponential regression
  7. Loop #7 — Adaptive Heartrate (HeartbeatState) — background tick coordinator

L8 Jacquard Mode Selector (ssm_jacquard.c) — additional steady-state machine layer that switches between mode configurations based on attractor bucket statistics. Modes: stable, volatile, diverse, temporal, transition, omni. Controlled by vm->ssm_l8_state.

All loops are independently togglable via Makefile build flags.

Key Data Structures (include/vm.h)

  • VM struct — entire VM state: stacks, dictionary, memory, physics, heartbeat, SSM
  • DictEntry — execution_heat, physics (DictPhysics), transition_metrics, word_id, acl_default
  • DictPhysics — temperature_q8, last_active_ns, mass_bytes, avg_latency_ns, acl_hint
  • RollingWindowOfTruth — circular buffer, double-buffered snapshots, adaptive sizing
  • HeartbeatState — tick coordinator, DoE observation counters, L8 bucket stats, M5 time trust
  • HeartbeatTickSnapshot — per-tick: cache hits, heat, window width, jitter, L8 mode
  • PipelineGlobalMetrics — prefetch accuracy, binary-chop window tuning state
  • CapsuleDesc — 64-byte cache-aligned capsule descriptor with content hash

Memory Model

  • vaddr_t — VM addresses are byte offsets, not C pointers
  • vm_load_cell() / vm_store_cell() — canonical memory accessors
  • VM_ADDR(cell) / CELL(vaddr) — explicit stack↔offset conversions
  • Dictionary occupies first 2MB (DICTIONARY_BLOCKS=2048), user blocks start at 2048
  • Total VM memory: 5MB (VM_MEMORY_SIZE)
  • Log blocks: 3072–5120 (2MB for persistent log, 32768 max lines at 64 bytes/line)

Testing

Tests are organized in POST (Power-On Self Test) order:

  1. Unit tests: Q48.16 fixed-point, inference statistics, decay slope inference
  2. Dictionary tests: FORTH-79 word validation across 22 categories (not 18)
  3. Integration tests, stress tests, adversarial/fuzzing tests (break_me_tests.c)

Test files: src/test_runner/modules/ — 22 *_test.c files (including mama_forth_words_test.c, integration_tests.c, stress_tests.c, break_me_tests.c).

Kernel baseline: QEMU_BASELINE.log captures reference QEMU/OVMF output for regression detection.

Formal Verification

The proof/ directory contains 19 Isabelle/HOL theory files providing machine-checkable proofs of determinism and correctness:

proof/
├── ROOT                           # Isabelle project manifest
├── StarForth_Base.thy             # Base definitions and type system
├── StarForth_Loop1_Heat.thy       # Execution heat tracking
├── StarForth_Loop2_Window.thy     # Rolling window
├── StarForth_Loop3_Decay.thy      # Linear decay
├── StarForth_Loop4_Pipeline.thy   # Pipelining metrics
├── StarForth_Loop5_WinInf.thy     # Window width inference
├── StarForth_Loop6_DecayInf.thy   # Decay slope inference
├── StarForth_Loop7_Heartrate.thy  # Adaptive heartrate
├── StarForth_Arithmetic_Words.thy
├── StarForth_Stack_Words.thy
├── StarForth_Logical_Words.thy
├── StarForth_Memory_Words.thy
├── StarForth_Return_Stack_Words.thy
├── StarForth_Q48_16.thy           # Q48.16 fixed-point
├── StarForth_Correctness.thy      # Overall correctness
├── StarForth_Concurrent.thy       # Concurrency properties
├── StarForth_Transition.thy       # State transitions
└── StarForth_Mutex.thy            # Mutual exclusion

To check proofs: isabelle build -D proof/ (requires Isabelle installation, see docs/01-getting-started/DEVELOPER.md).

ACL proofs complete (Phase 6): ACL_Pin_Monotone.thy, ACL_Inherit_Clears_Pin.thy, ACL_TTL_Bounded.thy, ACL_Emergency_Bypass.thy, ACL_No_Escalation.thy. Total: 24 theory files.

Roadmap

Full roadmap: ROADMAP.md. Summary:

2025 (done)     2026             2027             2028
StarForth  →  StarKernel   →  StarshipOS   →   FPGA Hardware
   VM        (bare metal)   (self-hosting)     (custom silicon)
  DONE       M0-M6 done      storage,net,       feasibility
             M7 in progress  multitask,         study
                             self-compile

LithosAnanke roadmap:

  • v1.0.x — serial-only production (current)
  • v1.5.0 — framebuffer VT100 terminal milestone
  • v2.0.0 — StarForth SDK release

Code Standards

  • Strict ANSI C99 — No GNU extensions, no C++ features
  • Zero warnings — Build with -Wall -Werror
  • No hidden state — All VM state is explicit in the VM struct
  • Platform-agnostic — Kernel code gated by __STARKERNEL__ and STARFORTH_ENABLE_VM
  • Content-addressed immutability — Capsule ID = content hash; any mutation is detectable

Important Conventions

  • Stack values are VM offsets (vaddr_t), not C pointers — use VM_ADDR() / CELL()
  • WORD_IMMEDIATE flag = executes during compilation (not deferred)
  • WORD_PINNED = execution heat cannot decay to zero
  • WORD_FROZEN = execution heat does not decay at all
  • STRICT_PTR=1 enforces bounds checking (disable only for benchmarking)
  • Kernel code uses #ifdef __STARKERNEL__; VM-enabled path uses #ifdef STARFORTH_ENABLE_VM
  • Never add acl_* fields to DictEntry beyond the four already planned (see ACL design doc)

Critical Implementation Details

DoE CSV Output Suppression

Intentionally suppressed as of 2025-12-08. See src/main.c:390-396:

  • Metrics still collected via metrics_from_vm()
  • CSV row was redundant with internal VM metrics
  • To re-enable: add --csv-export flag or write to file

Heartbeat Instrumentation (Planned)

HeartbeatTickSnapshot and tick_buffer are declared in include/vm.h, but heartbeat_export_csv() is not yet implemented. See docs/03-architecture/heartbeat-system/instrumentation-plan.md.

Word Statistics Output

WORD-ENTROPY prints execution heat statistics to stdout. Kept enabled in DoE mode intentionally (diagnostic value outweighs noise cost).

StarKernel M7 Parity

parity.c logs every VM birth and execution with: VM ID, capsule hash, dictionary hash. This enables offline determinism verification — an independent system can load the same capsule and compare dict hashes. Zero-deviation means 0% algorithmic variance.

Documentation

make book         # LaTeX → PDF (gold standard)
make book-html    # HTML single-page + multi-page with dark.css

Key files:

  • README.md — project overview and quick start
  • ROADMAP.md — full VM→Kernel→OS→FPGA roadmap
  • ONTOLOGY.md — formal taxonomy: thermodynamic metaphors, literal implementations, lexicon
  • docs/01-getting-started/DEVELOPER.md — dev environment, Isabelle setup, CI/CD
  • docs/03-architecture/OVERVIEW.md — complete architecture overview
  • docs/03-architecture/physics-engine/feedback-loops.md — all 7 loops detailed
  • docs/03-architecture/hal/ — HAL architecture docs (6 files)
  • docs/03-architecture/heartbeat-system/ — heartbeat architecture, planned instrumentation
  • docs/03-architecture/word-acl/DESIGN.md — ACL system design + implementation punch list
  • docs/02-experiments/ — DoE guides (factorial, heartbeat, physics-optimization)
  • papers/James_Steady-State_Convergence_Adaptive_Runtime.pdf — published SSRN paper
  • sbom.spdx / sbom.spdx.json — Software Bill of Materials
  • QEMU_BASELINE.log — QEMU/OVMF reference output for kernel regression testing

License

See ./LICENSE (Starship License 1.0). Commercial license available.

Reference in New Issue View Git Blame Copy Permalink