6.6 KiB
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:
- Hera boots and initializes her own compudynamic state.
- Hera spawns Hermes. Hermes initializes his own compudynamic state.
- Hera spawns Artemis. Artemis initializes her own compudynamic state.
- All three VMs are running. Fleet K = sum of individual VM K values. K≡1.0 holds.
- Hera can reap (cleanly terminate) a child VM.
- 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
- Do not implement heat-based VM routing. It causes starvation. It is wrong.
- Do not pin Hera's heat floor. That is a band-aid on a wrong model.
- Do not put DOE-WORK in the production dispatch path.
- Do not call CD-TICK a scheduler in comments, docs, or variable names.
- Do not call the fleet K view a router in comments, docs, or variable names.
- 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.
- 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.
- 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.