# 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.