LithosAnanake/.claude/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.

---

SUPERSEDED (Captain Bob, 2026-08-15). This document is no longer authoritative. FABRIC.md/FABRIC-2.md (repo root — read FABRIC-2.md first, it is the current/living one) are the sole design-of-record for Tripod work now. Kept here as historical record only; do not read this for current design authority, and do not cite it in place of FABRIC.md/FABRIC-2.md. See .claude/CLAUDE.md's own pointer.

---

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

Corrected 2026-08-13 — stale since item 0.1 (FABRIC.md Phase 0), flagged in FABRIC-2.md §A item 5.3, never fixed until now. This section used to say Hera spawns Hermes and Artemis automatically at boot. She does not, by deliberate design: item 0.1 pruned capsules/init.4th to boot Hera alone (confirmed current — capsules/init.4th births no other VM). Hermes and Artemis-as-VM-patron births happen on demand today, via test tooling (tools/hermes_smoke.sh, tools/hermes_channel_smoke.sh, tools/hermes_tripod_smoke.sh) and manual capsule swaps, not automatic boot behavior. Separately, and not to be confused with a VM birth: Artemis's block-storage device (the virtio-blk disk, disk/artemis.img) does attach automatically at boot at the C level (kernel_main.c's M7.pre step) on all three architectures — that is real and live, but it is storage attachment, not Artemis initializing as a compudynamic VM patron.

The goal below is still the eventual target; it describes where the Tripod is headed, not what boot does today.

Hera must be able to spawn Hermes and Artemis, 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 can spawn Hermes. Hermes initializes his own compudynamic state.
3. Hera can spawn 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.