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
2026-10-14 16:03:56 -04:00
co-authored by Claude Opus 5.5
parent 1a4b163861
commit 7aed588f78
116 changed files with 305 additions and 175 deletions
File diff suppressed because it is too large Load Diff
File diff suppressed because it is too large Load Diff
@@ -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.
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,265 @@
> **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.
# StarForth Complete 2^6 Factorial Design of Experiments
## Overview
**One-and-done comprehensive factorial testing** - collect all data systematically, analyze separately.
This guide describes how to run a **complete 2^6 factorial design of experiments** across all 6 feedback loops, yielding:
- **64 unique configurations** (all binary combinations)
- **1,920+ runs** (30 samples per configuration)
- **Single unified dataset** for factorial analysis
## The Why: Factorial DoE
Instead of incrementally tuning parameters, we collect **comprehensive experimental data** in one go:
### Traditional Approach (Old)
- Run baseline
- Run with Loop #1
- Run with Loops #1-2
- Run with Loops #1-3
- ... (sequential, incremental)
- **Problem:** Can't see interactions, trade-offs, or surprises
### Factorial Approach (New)
- Run ALL 2^6 = 64 combinations in randomized order
- Collect all data at once
- Analyze factorial effects, interactions, and main effects
- **Advantage:** Complete picture of how loops interact
## The 6 Feedback Loops
Each loop is a binary toggle in the Makefile:
| Loop | Makefile Flag | Purpose |
|------|---|---|
| **#1** | `ENABLE_LOOP_1_HEAT_TRACKING` | Count word execution frequency |
| **#2** | `ENABLE_LOOP_2_ROLLING_WINDOW` | Capture execution history (circular buffer) |
| **#3** | `ENABLE_LOOP_3_LINEAR_DECAY` | Age words by exponential decay over time |
| **#4** | `ENABLE_LOOP_4_PIPELINING_METRICS` | Track word-to-word transitions |
| **#5** | `ENABLE_LOOP_5_WINDOW_INFERENCE` | Infer optimal window width (Levene's test) |
| **#6** | `ENABLE_LOOP_6_DECAY_INFERENCE` | Infer decay slope via linear regression |
## Configuration Naming
Each of 64 configurations is named by its loop status:
```
L1_L2_L3_L4_L5_L6
Where each digit is 0 (OFF) or 1 (ON)
Examples:
000000 = Baseline (all loops OFF - pure FORTH-79)
000001 = Only heat tracking
111110 = All except decay inference
111111 = All loops ON (likely optimal)
101010 = Alternating pattern (for research)
```
## Quick Start
### Minimal Test (validate script)
```bash
./scripts/run_factorial_doe.sh --runs-per-config 1 TEST_RUN
# 64 builds × 1 run = 64 total runs
# Runtime: ~30-45 minutes
# Output: /home/rajames/CLionProjects/StarForth-DoE/experiments/TEST_RUN/
```
### Standard Comprehensive Run
```bash
./scripts/run_factorial_doe.sh --runs-per-config 30 2025_11_19_FACTORIAL
# 64 builds × 30 runs = 1,920 total runs
# Runtime: ~2-4 hours
# Output: /home/rajames/CLionProjects/StarForth-DoE/experiments/2025_11_19_FACTORIAL/
```
### High-Precision Run
```bash
./scripts/run_factorial_doe.sh --runs-per-config 100 HIGH_PRECISION_DOE
# 64 builds × 100 runs = 6,400 total runs
# Runtime: ~6-12 hours
# Output: /home/rajames/CLionProjects/StarForth-DoE/experiments/HIGH_PRECISION_DOE/
```
## Output Structure
```
/home/rajames/CLionProjects/StarForth-DoE/experiments/<EXPERIMENT_LABEL>/
├── experiment_results.csv # All measurements (1920+ rows)
├── experiment_summary.txt # Timing, metadata, statistics
├── configuration_manifest.txt # All 64 configs documented
├── test_matrix.txt # Randomized execution order
└── run_logs/
├── 000000_run_1.log
├── 000000_run_2.log
├── 000001_run_1.log
├── ...
└── 111111_run_30.log # 1,920 total log files
```
## CSV Schema
Each row in `experiment_results.csv` contains:
```
timestamp,configuration,run_number,
<35+ metrics from test harness>,
enable_loop_1_heat_tracking,
enable_loop_2_rolling_window,
enable_loop_3_linear_decay,
enable_loop_4_pipelining_metrics,
enable_loop_5_window_inference,
enable_loop_6_decay_inference
```
This lets you correlate every metric against every loop combination.
## Analysis Strategy
After collection, analyze in the separate `StarForth-DoE` repository:
### Step 1: Load Data
```python
import pandas as pd
df = pd.read_csv("experiment_results.csv")
print(df.shape) # Should be (1920, 38+)
print(df.columns)
```
### Step 2: Separate Metrics from Factors
```python
factor_cols = ['enable_loop_1_heat_tracking', ..., 'enable_loop_6_decay_inference']
metric_cols = ['total_lookups', 'cache_hit_percent', ..., 'vm_workload_duration_ns_q48']
factors = df[factor_cols]
metrics = df[metric_cols]
```
### Step 3: Factorial Analysis
```python
# Main effects: What's the average change when Loop X goes from 0→1?
main_effects = {}
for loop in factor_cols:
main_effects[loop] = metrics[factors[loop]==1].mean() - metrics[factors[loop]==0].mean()
# Interactions: Do loops work better/worse together?
# Can use statsmodels.formula.api for ANOVA/regression
# Optimal subset: Which combinations of loops give best throughput?
best_configs = df.nlargest(10, 'vm_workload_duration_ns_q48')
```
## Key Design Choices
### 1. **Rebuild Every Pass** ✓
- Each configuration requires a `make clean && make`
- Ensures clean, isolated state
- No cross-contamination
- True ground truth for each variant
### 2. **Randomized Execution**
- All 1,920 runs randomized into single matrix (not 64 separate runs)
- Prevents thermal ramp, temporal bias, or systematic trends
- DoE principle: randomization eliminates confounds
### 3. **Full Factorial** (not fractional)
- Testing ALL 2^6 = 64 combinations
- Can detect unexpected interactions
- Most expensive, most informative
### 4. **One-and-Done Collection**
- Single experiment, all data
- No progressive tuning during collection
- Separates measurement from analysis (good practice)
## Expected Results
### Hypothetical Output
Assuming typical performance distribution:
```
Configuration | Avg Time (ns) | Speed vs Baseline
─────────────────────────────────────────────────
000000 (base) | 10,000,000 | 1.0x
000001 (L1) | 9,950,000 | 1.005x
111111 (all) | 8,500,000 | 1.176x ← Likely best
```
### Expected Patterns
1. **Loop #1 (heat tracking)**: ~2-5% improvement alone
2. **Loop #2 (rolling window)**: ~1-3% improvement (depends on L1)
3. **Loops #3-6**: Increasingly synergistic (work better together)
4. **Interactions**: Loop #5 + #6 likely synergistic (inference loops)
## Troubleshooting
### Build Fails for a Configuration
```bash
# Check specific config build log
cat /home/rajames/CLionProjects/StarForth-DoE/experiments/<LABEL>/run_logs/build_<CONFIG>.log
```
### Test Harness Crashes on Some Configs
- Check if loop combination is invalid (e.g., Loop #5 without Loop #2)
- Verify Makefile flags are correctly parsed
- See: `include/vm.h` for interdependencies
### Results Look Suspicious
- Check `test_matrix.txt` - ensure randomization is present
- Verify CSV row counts match expected total
- Check for missing runs in log directory
## Performance Notes
### Timing Estimates
- **Minimal (1 run/config)**: 30-45 minutes
- **Standard (30 runs/config)**: 2-4 hours
- **High-precision (100 runs/config)**: 6-12 hours
- **Depends on:** CPU speed, disk I/O, test harness overhead
### Optimization
- Run overnight for high-precision experiments
- Use `screen` or `tmux` to keep session alive
- Monitor disk space (~100 MB for results + logs)
## Next Steps
1. **Run the experiment:**
```bash
./scripts/run_factorial_doe.sh 2025_11_19_COMPLETE_FACTORIAL
```
2. **Monitor progress:**
```bash
tail -f /home/rajames/CLionProjects/StarForth-DoE/experiments/2025_11_19_COMPLETE_FACTORIAL/experiment_summary.txt
```
3. **Move to analysis repo** (once complete):
```bash
cp -r /home/rajames/CLionProjects/StarForth-DoE/experiments/2025_11_19_COMPLETE_FACTORIAL \
/home/rajames/CLionProjects/StarForth-DoE-Analysis/data/
cd /home/rajames/CLionProjects/StarForth-DoE-Analysis
python3 analyze_factorial.py data/2025_11_19_COMPLETE_FACTORIAL/experiment_results.csv
```
4. **Generate reports:**
- Main effects plots
- Interaction matrices
- Pareto optimal configurations
- Recommendations for production builds
---
**Version:** 1.0
**Last Updated:** 2025-11-19
**Author:** Claude Code (with Robert A. James)
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,271 @@
> **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.
# StarForth Complete 2^6 Factorial DoE - Documentation Index
## Overview
This is a **one-and-done comprehensive factorial design of experiments** to systematically test all 64 possible combinations of 6 feedback loops.
**Key insight:** Don't toggle back-and-forth. Instead, systematically test ALL 2^6 combinations in a single experiment, then analyze the results afterward.
## Documentation Structure
### 1. **START HERE** 📋
- **File:** `docs/QUICK_START_FACTORIAL_DoE.md`
- **Purpose:** Entry point for quick reference
- **Read time:** 5 minutes
- **Contains:**
- 3 command options (quick/standard/high-precision)
- Time estimates
- What to expect during execution
- Basic troubleshooting
### 2. **Complete Guide** 📚
- **File:** `docs/FACTORIAL_DoE_GUIDE.md`
- **Purpose:** Full design documentation and rationale
- **Read time:** 20-30 minutes
- **Contains:**
- Why factorial DoE (vs. incremental tuning)
- 6 feedback loop definitions
- Configuration naming scheme (0_0_0_0_0_0 → 1_1_1_1_1_1)
- Design choices explained
- Expected results and patterns
- Troubleshooting guide
- Performance notes
### 3. **Analysis Workflow** 🔍
- **File:** `docs/FACTORIAL_DoE_ANALYSIS_WORKFLOW.md`
- **Purpose:** End-to-end pipeline from collection to insights
- **Read time:** 15-20 minutes (or 1-2 hours if coding along)
- **Contains:**
- Phase 1: Data collection (run script)
- Phase 2: Data transfer (to analysis repo)
- Phase 3: Statistical analysis (main effects, interactions)
- Phase 4: Reporting (generating insights)
- Python code examples:
* Load data and validate
* Compute main effects (individual loop impacts)
* Detect interactions (loop synergies)
* Optimize configuration subset
* Visualization code
- Example report structure
- Checklist for completion
### 4. **Main Script** ⚙️
- **File:** `scripts/run_factorial_doe.sh`
- **Purpose:** Executable for running the entire experiment
- **Read time:** 10 minutes (code + comments)
- **Contains:**
- Generates all 64 configurations
- Rebuilds for each unique configuration
- Randomizes execution order (1,920+ runs)
- Collects metrics to CSV
- Full instrumentation and progress reporting
---
## Reading Guide by Use Case
### "I just want to run the experiment"
1. Read: `QUICK_START_FACTORIAL_DoE.md` (5 min)
2. Execute: Choose command option (quick/standard/high-precision)
3. Wait: 30 min - 12 hours depending on option
4. Done!
### "I want to understand the design before running"
1. Read: `QUICK_START_FACTORIAL_DoE.md` (5 min)
2. Read: `FACTORIAL_DoE_GUIDE.md` (30 min)
3. Execute: Run with confidence
4. Analyze: Follow `FACTORIAL_DoE_ANALYSIS_WORKFLOW.md`
### "I need to analyze the results"
1. Read: `QUICK_START_FACTORIAL_DoE.md` → understand naming
2. Read: `FACTORIAL_DoE_ANALYSIS_WORKFLOW.md` → statistical methods
3. Code along: Use Python examples in Analysis Workflow
4. Interpret: Reference `FACTORIAL_DoE_GUIDE.md` for expected patterns
### "I want complete understanding"
Read in order:
1. `QUICK_START_FACTORIAL_DoE.md` (overview)
2. `FACTORIAL_DoE_GUIDE.md` (design rationale)
3. `scripts/run_factorial_doe.sh` (implementation)
4. `FACTORIAL_DoE_ANALYSIS_WORKFLOW.md` (analysis methods)
---
## Quick Command Reference
### Run Experiment
```bash
# Option A: Quick validation (30 min)
./scripts/run_factorial_doe.sh --runs-per-config 1 TEST_RUN
# Option B: Standard production (2-4 hours)
./scripts/run_factorial_doe.sh --runs-per-config 30 2025_11_19_FULL_FACTORIAL
# Option C: High-precision overnight (6-12 hours)
./scripts/run_factorial_doe.sh --runs-per-config 100 HIGH_PRECISION_FACTORIAL
```
### Monitor Progress
```bash
# Check results_run_01_2025_12_08 CSV growth
watch -n 5 'wc -l /path/to/experiment_results.csv'
# View summary
tail /path/to/experiment_summary.txt
# Count completed configurations
ls /path/to/run_logs/build_*.log | wc -l
```
### Analyze Results
```bash
# Load and analyze in Python
cd /path/to/StarForth-DoE-Analysis
python3 << 'EOF'
import pandas as pd
df = pd.read_csv('data/2025_11_19_FULL_FACTORIAL/experiment_results.csv')
print(f"Loaded {len(df)} runs")
# See FACTORIAL_DoE_ANALYSIS_WORKFLOW.md for full analysis code
EOF
```
---
## Key Concepts
### 64 Configurations
Each configuration is a unique combination of 6 binary factors:
- **0_0_0_0_0_0** = Baseline (all loops OFF)
- **1_0_0_0_0_0** = Only heat tracking
- **1_1_0_0_0_0** = Heat + rolling window
- ...
- **1_1_1_1_1_1** = All loops ON (current optimal)
### Randomized Execution
All 1,920+ runs (64 configs × 30 samples) are randomized into a single execution matrix.
- Eliminates temporal bias
- Prevents thermal ramp (if CPU heats during night)
- Proper DoE methodology
### One-and-Done Collection
Collect all data in single experiment, analyze separately.
- No tuning during collection (avoid bias)
- Single pass through parameter space
- Separates measurement from analysis
### Main Effects
Individual impact of each loop:
```
Loop #1: Loop turns ON, average metric changes by X%
Loop #2: Loop turns ON, average metric changes by Y%
... etc
```
### Interactions
How loops work together (amplify or suppress each other):
```
Loop #1 + Loop #2: Do they work better together than independently?
```
---
## Files at a Glance
| File | Size | Purpose |
|------|------|---------|
| `scripts/run_factorial_doe.sh` | 19 KB | Main executable script |
| `docs/QUICK_START_FACTORIAL_DoE.md` | 4.9 KB | Quick reference |
| `docs/FACTORIAL_DoE_GUIDE.md` | 8.0 KB | Design documentation |
| `docs/FACTORIAL_DoE_ANALYSIS_WORKFLOW.md` | 9.6 KB | Analysis pipeline |
| `docs/FACTORIAL_DoE_INDEX.md` | This file | Documentation index |
---
## Execution Timeline
### Phase 1: Preparation (5-10 min)
- Read `QUICK_START_FACTORIAL_DoE.md`
- Choose execution option
- Run command
### Phase 2: Collection (30 min - 12 hours)
- Script builds all 64 configs (as needed)
- Randomized execution of 1,920+ runs
- Metrics collected to CSV
- Progress shown every run
### Phase 3: Transfer (5 min)
- Copy results to analysis repo
- Verify file integrity
### Phase 4: Analysis (1-2 hours)
- Load CSV in Python
- Compute main effects
- Detect interactions
- Find optimal configurations
- Generate visualizations
### Phase 5: Reporting (1-2 hours)
- Summarize findings
- Create report
- Recommendations for production
**Total time:** Collection (2-4 hrs) + Analysis (2-4 hrs) = **4-8 hours**
---
## The Design Philosophy
### Problem Statement
How do we systematically understand the performance contribution and interactions of 6 interdependent feedback loops?
### Solution
**Complete 2^6 factorial design of experiments**
### Why This Approach
1. **Complete:** Tests all 64 combinations (no gaps)
2. **Systematic:** Proper experimental design methodology
3. **Separable:** Collection ≠ Analysis (reduces bias)
4. **Reproducible:** Randomized execution, full logging
5. **Scalable:** Single script, extensible to more factors
### Alternatives Rejected
- ❌ Incremental tuning ("baseline → +loop1 → +loop1+2"): Misses interactions
- ❌ Dynamic toggle without rebuild: Introduces state contamination
- ❌ Partial factorial: Misses key interactions
- ❌ One-at-a-time testing: Expensive and confounded
---
## Next Steps
1. **Read** `QUICK_START_FACTORIAL_DoE.md` (5 minutes)
2. **Decide** which execution option (quick/standard/precise)
3. **Run** the command and let it collect data
4. **Monitor** progress in another terminal
5. **Analyze** results using `FACTORIAL_DoE_ANALYSIS_WORKFLOW.md`
6. **Report** findings to stakeholders
---
## Questions?
- **"How long will this take?"** → See `QUICK_START_FACTORIAL_DoE.md`
- **"What does configuration X mean?"** → See `FACTORIAL_DoE_GUIDE.md`
- **"How do I analyze the results?"** → See `FACTORIAL_DoE_ANALYSIS_WORKFLOW.md`
- **"Why this approach?"** → See `FACTORIAL_DoE_GUIDE.md` - "The Why"
- **"How do I run it?"** → `./scripts/run_factorial_doe.sh`
---
**Version:** 1.0
**Created:** 2025-11-19
**Status:** Ready for production use
@@ -0,0 +1,158 @@
> **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
> driven by the L8 Jacquard runtime mode selector. Kept for historical record.
# Quick Start: Complete 2^6 Factorial DoE
## TL;DR
Run a **complete, exhaustive 2^6 = 64 configuration experiment** in one go, collecting all data for later analysis.
## Three Command Options
### Option 1: Quick Validation (30 min)
Test the script and infrastructure:
```bash
./scripts/run_factorial_doe.sh --runs-per-config 1 QUICK_TEST
```
- 64 builds × 1 run = 64 total runs
- Fast feedback on whether setup works
- Output: `/home/rajames/CLionProjects/StarForth-DoE/experiments/QUICK_TEST/`
### Option 2: Standard Full DoE (2-4 hours)
Comprehensive factorial collection:
```bash
./scripts/run_factorial_doe.sh --runs-per-config 30 2025_11_19_FULL_FACTORIAL
```
- 64 builds × 30 runs = 1,920 total runs
- Good statistical power for main effects
- Standard production-grade experiment
- Output: `/home/rajames/CLionProjects/StarForth-DoE/experiments/2025_11_19_FULL_FACTORIAL/`
### Option 3: High-Precision Run (6-12 hours)
Maximum data for deep analysis:
```bash
./scripts/run_factorial_doe.sh --runs-per-config 100 HIGH_PRECISION_FACTORIAL
```
- 64 builds × 100 runs = 6,400 total runs
- Best for detecting subtle interactions
- Run overnight for best results
- Output: `/home/rajames/CLionProjects/StarForth-DoE/experiments/HIGH_PRECISION_FACTORIAL/`
## What Gets Generated
```
/home/rajames/CLionProjects/StarForth-DoE/experiments/2025_11_19_FULL_FACTORIAL/
├── experiment_results.csv ← All 1,920 rows of measurements
├── experiment_summary.txt ← Timing and metadata
├── configuration_manifest.txt ← All 64 configs listed
├── test_matrix.txt ← Randomized execution order
└── run_logs/
├── 0_0_0_0_0_0_run_1.log
├── 0_0_0_0_0_0_run_2.log
├── ...
└── 1_1_1_1_1_1_run_30.log
```
## What's Being Tested
6 **independent binary feedback loops**:
| Loop | Toggle | What It Does |
|------|--------|---|
| 1 | `ENABLE_LOOP_1_HEAT_TRACKING` | Count execution frequency |
| 2 | `ENABLE_LOOP_2_ROLLING_WINDOW` | Capture execution history |
| 3 | `ENABLE_LOOP_3_LINEAR_DECAY` | Age words over time |
| 4 | `ENABLE_LOOP_4_PIPELINING_METRICS` | Track word transitions |
| 5 | `ENABLE_LOOP_5_WINDOW_INFERENCE` | Infer window width |
| 6 | `ENABLE_LOOP_6_DECAY_INFERENCE` | Infer decay slope |
**All 2^6 = 64 combinations** tested:
- `0_0_0_0_0_0` = Baseline (all OFF)
- `1_0_0_0_0_0` = Only heat tracking
- `0_1_0_0_0_0` = Only rolling window
- ...
- `1_1_1_1_1_1` = All loops ON (current optimal)
## During Execution
You'll see progress like:
```
═══════════════════════════════════════════════════════════
STARFORTH COMPLETE 2^6 FACTORIAL DoE
═══════════════════════════════════════════════════════════
→ Factors: 6 feedback loops (LOOP_1 through LOOP_6)
→ Configurations: 2^6 = 64
→ Runs per config: 30
→ TOTAL RUNS: 1,920
→ Output: /home/rajames/CLionProjects/StarForth-DoE/experiments/2025_11_19_FULL_FACTORIAL
>>> Generating randomized test matrix...
✓ Test matrix generated
→ Run 1/1920 - config 0_1_0_1_1_0 #14...
✓ Run 1/1920 completed (3s)
→ Run 2/1920 - config 1_1_1_0_0_1 #2...
✓ Run 2/1920 completed (2s)
...
```
The script:
1. **Builds** each of 64 configurations (rebuilds when config changes)
2. **Runs** tests in randomized order (no systematic bias)
3. **Collects** metrics to CSV
4. **Outputs** progress every run
## After Completion
Move to analysis repo to understand results:
```bash
cd /home/rajames/CLionProjects/StarForth-DoE-Analysis
python3 analyze_factorial.py \
data/2025_11_19_FULL_FACTORIAL/experiment_results.csv
```
Expected analysis outputs:
- **Main effects:** Which individual loops help most?
- **Interactions:** Do loops work better/worse together?
- **Optimal subset:** Best combination of loops?
- **Trade-offs:** Performance vs complexity?
## Key Design Decisions
✅ **Rebuild every pass** - ensures clean, isolated testing
✅ **Randomized execution** - eliminates temporal/thermal bias
✅ **Complete factorial** - captures all interactions
✅ **One-and-done** - collect all data, analyze later
## Estimated Time
| Runs/Config | Total | Time | When |
|---|---|---|---|
| 1 | 64 | 30-45 min | Quick test |
| 30 | 1,920 | 2-4 hours | Standard |
| 100 | 6,400 | 6-12 hours | Overnight |
Times depend on CPU, disk speed, and test harness overhead.
## Example Command
**Run it now:**
```bash
cd /home/rajames/CLionProjects/StarForth
./scripts/run_factorial_doe.sh 2025_11_19_FULL_FACTORIAL
```
**Monitor progress:**
```bash
tail -f /home/rajames/CLionProjects/StarForth-DoE/experiments/2025_11_19_FULL_FACTORIAL/experiment_summary.txt
```
---
**Ready?** Run the command above and let the experiment collect comprehensive data for downstream analysis.
File diff suppressed because it is too large Load Diff
File diff suppressed because it is too large Load Diff
File diff suppressed because it is too large Load Diff
File diff suppressed because it is too large Load Diff
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,278 @@
> **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
> in an open question and was never approved as designed. Kept for historical record.
# Loop #5: Context-Aware Window Tuning - Design Sketch
## The Challenge
**Current state:** Window size shrinks based on pattern diversity, but we don't know if shrinking improves or hurts **pipelining prediction accuracy**.
**Goal:** Use actual prefetch hit rate to guide window size tuning via binary chop search.
---
## What Loop #5 Should Do
### High-Level Flow
1. **Measure**: Track global pipelining metrics across ALL words
- Total speculative prefetch attempts
- Successful prefetch hits
- Current accuracy = hits / attempts
2. **Trigger**: Periodically (e.g., every 1000 executions when warm)
- Calculate prediction accuracy at current effective_window_size
- Call binary chop to suggest next size to try
3. **Adapt**: Shrink or grow effective_window_size based on accuracy trend
- If smaller window → better accuracy: keep shrinking
- If smaller window → worse accuracy: grow back up
- Converge to sweet spot
4. **Measure**: Record the accuracy at each window size tried
- Build history of (window_size → accuracy) pairs
- Use this history to accelerate convergence
---
## Architecture Needed
### 1. VM-Level Metrics (New)
**File:** `include/vm.h` (add to VM struct)
```c
typedef struct {
uint64_t prefetch_attempts; /* Total speculative prefetch calls */
uint64_t prefetch_hits; /* Successful hits (word was looked up next) */
uint64_t window_tuning_checks; /* How many times we've checked window size */
uint32_t last_checked_window_size;
double last_checked_accuracy;
uint32_t suggested_next_size; /* What binary chop recommends trying */
} PipelineGlobalMetrics;
```
**Add to VM struct:**
```c
struct VM {
// ... existing fields ...
PipelineGlobalMetrics pipeline_metrics; /* NEW: aggregated metrics */
};
```
### 2. Update Prefetch Feedback (in vm.c)
**When speculative prefetch succeeds:**
```c
// In execute_colon_word(), after promotion:
if (spec_entry && vm->hotwords_cache && ENABLE_HOTWORDS_CACHE)
{
spec_entry->execution_heat = HOTWORDS_EXECUTION_HEAT_THRESHOLD + 1;
hotwords_cache_promote(vm->hotwords_cache, spec_entry);
// NEW: Record the prefetch attempt globally
vm->pipeline_metrics.prefetch_attempts++;
prev_word->transition_metrics->prefetch_attempts++; // Per-word too
}
```
**When word is actually looked up (check if it was speculated):**
```c
// In vm_interpret_word(), during dictionary lookup:
if (entry && ENABLE_PIPELINING && vm->hotwords_cache)
{
// NEW: Check if this word was in speculated cache (dirty bit or timestamp)
if (word_was_speculatively_promoted_recently(entry))
{
vm->pipeline_metrics.prefetch_hits++; // Global metric
// per_word_metrics->prefetch_hits++; // Already done in prefetch logic
}
}
```
### 3. Window Tuning Decision Loop
**New function:** `physics_pipelining_metrics.c`
```c
/**
* Suggest window size via binary chop based on prefetch accuracy trend.
* Called periodically (every 1000 executions when pipelining is enabled).
*/
uint32_t loop_5_binary_chop_suggest_window(
const PipelineGlobalMetrics *global,
uint32_t current_window_size,
uint32_t min_window,
uint32_t max_window)
{
if (global->prefetch_attempts == 0)
return current_window_size; /* Not enough data yet */
double current_accuracy = (double)global->prefetch_hits / (double)global->prefetch_attempts;
/* Binary chop: try smaller window first (aggressive shrinking)
* If accuracy drops, back off and try larger windows */
if (global->window_tuning_checks == 0)
{
/* First check: try shrinking by 25% */
return (current_window_size * 75) / 100;
}
/* Compare current accuracy to last check */
double accuracy_delta = current_accuracy - global->last_checked_accuracy;
if (accuracy_delta > 0.01) /* Improvement threshold: 1% */
{
/* Accuracy improved! Try shrinking more */
uint32_t smaller = (current_window_size * 75) / 100;
return (smaller > min_window) ? smaller : min_window;
}
else if (accuracy_delta < -0.01)
{
/* Accuracy degraded. Try growing instead */
uint32_t larger = (current_window_size * 133) / 100; /* Grow by ~33% */
return (larger < max_window) ? larger : max_window;
}
else
{
/* Plateau: stick with current size */
return current_window_size;
}
}
```
### 4. Integration Point
**In rolling_window_of_truth.c: `rolling_window_check_adaptive_shrink()`**
```c
void rolling_window_check_adaptive_shrink(RollingWindowOfTruth* window)
{
// ... existing adaptive shrinking code ...
/* Loop #5: Binary chop window tuning (Phase 2 IMPLEMENTATION) */
if (ENABLE_PIPELINING && window->is_warm)
{
window->adaptive_check_count++;
/* Check every 1000 executions for tuning opportunity */
if (window->adaptive_check_count % 1000 == 0)
{
PipelineGlobalMetrics *metrics = &vm->pipeline_metrics;
/* Calculate current accuracy */
double current_accuracy = (metrics->prefetch_attempts > 0)
? (double)metrics->prefetch_hits / (double)metrics->prefetch_attempts
: 0.0;
/* Ask binary chop for next window size to try */
uint32_t suggested_size = loop_5_binary_chop_suggest_window(
metrics,
window->effective_window_size,
ADAPTIVE_MIN_WINDOW_SIZE,
ROLLING_WINDOW_SIZE
);
/* Apply if different */
if (suggested_size != window->effective_window_size)
{
log_message(LOG_INFO,
"Loop #5: Binary chop tuning: %u → %u (accuracy %.2f%%, %lu/%lu hits)",
window->effective_window_size,
suggested_size,
current_accuracy * 100.0,
metrics->prefetch_hits,
metrics->prefetch_attempts);
window->effective_window_size = suggested_size;
}
/* Record this check for next iteration */
metrics->last_checked_window_size = window->effective_window_size;
metrics->last_checked_accuracy = current_accuracy;
metrics->window_tuning_checks++;
}
}
}
```
---
## Key Design Decisions
### A. Accuracy Measurement
- **Count**: Successful speculative promotions that were actually used
- **Challenge**: How to know if lookup was "predicted" vs "natural"?
- Option 1: Mark speculatively-promoted entries with a timestamp/flag
- Option 2: Track word IDs predicted and check if they match next lookup
- Option 3: Use per-word prefetch metrics already collected
### B. Tuning Frequency
- **Every 1000 executions** (when window is warm)
- Could be tunable: `make WINDOW_TUNING_FREQUENCY=1000`
### C. Search Strategy
- **Greedy shrinking first**: Try smaller windows aggressively
- **Backoff on degradation**: If accuracy drops, grow back up
- **Convergence**: Stop when oscillating around sweet spot
### D. Knobs Needed (Makefile)
```bash
make ENABLE_PIPELINING=1 # Must be enabled for Loop #5
make WINDOW_TUNING_FREQUENCY=1000 # How often to check
make WINDOW_TUNING_ACCURACY_THRESHOLD=1 # % improvement to continue shrinking
```
---
## Validation Approach
Once Loop #5 is wired, DoE would test:
- **A_BASELINE**: No optimizations
- **A_B_CACHE**: Cache only
- **A_C_FULL**: Window tuning with pipelining only
- **A_B_C_FULL**: Cache + window tuning + pipelining
**Metrics to collect:**
- Final effective_window_size (what did it converge to?)
- Final prefetch accuracy (%)
- Throughput improvement vs baseline
---
## Risks & Unknowns
1. **Overhead**: Checking accuracy every 1000 executions adds latency
2. **Noise**: If accuracy is noisy, binary chop might oscillate
3. **Workload-dependent**: Optimal window size might vary by workload
4. **False positives**: Speculative lookup might not correlate with prediction
---
## Sketch Summary
**Loop #5 would:**
1. Track global prefetch accuracy (hits/attempts)
2. Every 1000 executions, ask binary chop: "Is current window size optimal?"
3. Binary chop suggests shrinking, holding, or growing based on accuracy trend
4. Apply suggestion and record for next iteration
5. Over time, converge to window size that maximizes prediction accuracy
**Code locations if implemented:**
- VM struct: Add PipelineGlobalMetrics field
- vm.c: Update global metrics on prefetch attempts/hits
- physics_pipelining_metrics.c: `loop_5_binary_chop_suggest_window()`
- rolling_window_of_truth.c: Call binary chop from adaptive shrink check
**Effort**: ~150 LOC across 3-4 files
---
**Question for user:** Does this architecture align with what you had in mind for Loop #5?
@@ -0,0 +1,223 @@
> **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
> was never reconciled with the implemented `ssm_jacquard.c` system. The canonical current
> reference for the physics/feedback model is `feedback-loops.md`. Kept for historical record.
# 1. Introduction
A Steady State Machine (SSM) is a novel computational model in which the system’s operational state is defined not by discrete symbolic transitions, but by convergence to an optimal runtime equilibrium.
Unlike traditional models such as Finite State Machines (FSMs), Pushdown Automata, or Turing Machines — where “state” is explicit and symbolic — a Steady State Machine derives its behavior from continuous thermodynamic variables such as:
* execution_heat
* entropy (diversity)
* pipeline readiness
* heat decay
* steady-state slope
* localized temperature gradients
* adaptive strategy selection
An SSM observes itself, adapts, and settles into stable performance basins called steady states.
This makes the Steady State Machine the first computational model where the attractor defines the machine, not the symbol.
# 2. Core Definition
Definition 1 — Steady State Machine
> A Steady State Machine is a computational system defined by:
A set of internal physical metrics
* 𝐻 = execution_heats
* 𝐸 = entropy/diversity measures
* 𝑃 = pipeline activation thresholds
* Θ = heat decay profile
* 𝑊 = sliding execution window
A set of adaptive policies
* lookup strategies
* caching regimes
* bucket reorganizations
* pipeline decisions
* inference-based mode switches
* A state-space composed of attractor basins, not symbolic states
* steady attractor
* quasi-steady attractor
* transient attractor
* chaotic attractor
* A governing dynamic
### 𝑀𝑡+1=𝑓(𝑀𝑡,Δ𝐻,Δ𝑊,Δ𝐸) where 𝑓 pushes the machine toward a stable basin.
The machine is defined by its convergence behavior, not its instruction sequence.
# 3. The Fundamental Insight
In an SSM, performance is the state.
The system is constantly measuring:
* how hot words are
* how often patterns recur
* how pipeline-able a sequence is
* how diverse the window is
* how much the dictionary should reorganize
And as these stabilize, the machine settles into a steady state — a self-maintaining optimal regime.
This regime is preserved until the environment changes (e.g., new workloads, diversity spikes), at which point the SSM moves into a transient or chaotic regime and eventually finds a new equilibrium.
# 4. Phases of a Steady State Machine
## 1. Transient Phase
- System warms up
- Execution patterns are sporadic
- Heat gradients are noisy
- Pipeline inactive or unstable
## 2. Quasi-Steady Phase
- Some patterns emerge
- Lookups begin to bias
- Hot words form local attractors
- Dictionary reorders stabilize
## 3. True Steady State
- Heat surface smooth
- Pipeline active
- Diversity window predictable
- Lookups converge to optimal
- Runtime > baseline VM
- System remains stable unless perturbed
## 4. Chaotic/Disruption Phase
### Triggered by:
- major workload shift
- dictionary mutation
- extreme entropy spike
- cold-cache shock
- SSM falls out of equilibrium temporarily.
## 5. Axioms of Steady State Machines
>Axiom 1 — Convergence
Every sustained workload induces the SSM to converge toward a stable attractor unless external entropy forces divergence.
>Axiom 2 — Locality of Heat
Execution heat reflects both locality and temporal relevance. Locality produces stability.
>Axiom 3 — Adaptive Reordering
Reordering is not symbolic mutation; it is thermodynamic self-optimization.
>Axiom 4 — Stability Maximizes Throughput
The steady state is always faster than the cold state, and usually faster than the naive baseline VM.
>Axiom 5 — Perturbation Response
When disrupted, the SSM seeks a new steady state; it does not thrash indefinitely.
## 6. Relationship to Other Computational Models
>FSM vs SSM
FSM: discrete symbolic states
SSM: emergent attractors in thermal space
>Turing Machine vs SSM
TM: behavior defined by tape symbols and transitions
SSM: behavior defined by adaptation toward equilibrium
>Markov Chain vs SSM
MC: probabilistic transitions between explicit states
SSM: deterministic drift toward stable basins, driven by observation
>Neural Network vs SSM
NN: learns weights
SSM: reorganizes runtime structures, not parameters
## 7. Why This Breaks New Ground
### A Steady State Machine is the first:
- runtime-thermodynamic computing model
- adaptive VM with convergence properties
- load-dependent reordering machine
- self-optimizing dictionary machine
- phase-shifting execution system
- state-machine whose state is emergent, not explicit
- This is a fundamental new category of computation.
## 8. Canonical Example: StarForth
### StarForth implements the first real SSM with:
- execution_heat
- rolling diversity windows
- phase-based lookup strategies
- adaptive dictionary ordering
- pipeline activation
- DOE-calibrated inference loop
- background physics monitor
- It is, quite literally, the reference implementation.
## 9. Formal Summary Statement
>A Steady State Machine (SSM) is a computational system in which the operational state is defined by attractor convergence in thermodynamic runtime space rather than by discrete symbolic transitions. An SSM continuously measures workload characteristics, adjusts internal structures, and stabilizes into performance-optimized steady states. When perturbed, it transitions through transient or chaotic phases before finding a new equilibrium. This model defines a new class of adaptive computational systems with properties distinct from finite state machines, pushdown automata, and Turing Machines.