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

---

> **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 Hermes work now. Kept here as historical record
> only — note its message-layout table (8 cells) is confirmed stale against the real shipped
> capsule (9 cells, `capsules/hermes/init.4th`), see `FABRIC-2.md`. Do not read this for
> current design authority. See `.claude/CLAUDE.md`'s own pointer.

---

## 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 Known Scope Gaps

Named, bounded limitations. Logged here to prevent future confusion and make
the upgrade path explicit. None of these are defects in v1.

### Synchronous delivery — RESOLVED (G1)

`MSG-SEND` now queues only; `HERMES-TICK` drives delivery via `MSG-DELIVER-ALL`
as its first step. Delivered messages are marked `MSG-DELIVERED` (type=255) so the
scanner skips them on the next tick. `MSG-REAP` clears them when heat reaches zero.

### G2/G4: ACK/NACK server implemented; NACK-requeue deferred

`MSG-ACK-LAST` and `MSG-NACK-LAST` live in block 4121. `MSG-DELIVER` stores the
current message pointer in `MSG-LAST-MSG` before calling `VM-EXEC`; the target
VM's handler calls `HERMES-ACK` / `HERMES-NACK` (from `common:msg.4th`) which
use `VM-EXEC` back into Hermes to invoke the server words — no cross-VM stack
passing required. `MSG-DELIVER-ALL` guards the `MSG-DELIVERED` stamp so an ACK
inside the handler does not corrupt the freed slot.

v1 NACK = immediate reap (same as ACK). NACK-requeue (reduced heat, retry) is
deferred: it requires preserving the original message type through delivery, which
needs either an extra cell (MSG-CELLS=9) or a side table. Neither is warranted
until a real NACK-retry use case appears.

### MSG-REAP ordering bug — FIXED

`MSG-REAP` (block 4109) previously called `MSG-FREE-NODE` before clearing
the type field. `MSG-FREE-NODE` writes old_free_head into cell[0]; the
subsequent `MSG-TYPE!` then overwrote cell[0] with 0, severing the free list.

Fixed: type is cleared first (`0 MSG-SCAN @ MSG-TYPE!`), then the node is
prepended to the free list (`MSG-SCAN @ MSG-FREE-NODE`). Matches the correct
order already used by `MSG-ACK-LAST`/`MSG-NACK-LAST` in block 4121.

### Payload size coupled to block size

`MSG-PADDR`/`MSG-PLEN` carry FORTH string pointers. Payloads from `S"` literals
in block source are bounded by block size (1024 bytes). No logical-block spanning
is implemented. No real Hermes script has hit this ceiling yet — revisit when
something forces the issue.

### G8: HERMES-K implemented; K-FLEET integration deferred

`HERMES-K ( -- q48 )` = `MSG-TOTAL-HEAT + CH-TOTAL-HEAT` is implemented in
Hermes's VM (block 4116) and gives the total thermal mass of all in-flight
messages and active channels. Wiring it into `K-FLEET` in Hera requires a
cross-VM return value — something the current synchronous VM-EXEC model cannot
deliver. Full K≡1.0 accounting (K-FLEET includes Hermes thermal mass) is
deferred until the async inter-VM model supports return values (G1 path).

### `IDX>NAME` and `CH-ACCEPT` owner hardcoded for 3-VM Tripod

`IDX>NAME` maps 0→Hera, 1→Hermes, 2→Artemis only. `CH-ACCEPT` writes
`1 OVER CH-OWNER!` unconditionally. Correct for v1 Tripod; generalization
needed if Tripod grows beyond three VMs.

### G10: EVENT-WAIT reads raw arena slot 0

`EVENT-WAIT` returns `MSG-ARENA MSG-TYPE@` — the type field of slot 0, whatever
it happens to hold. With the async model this is unreliable: slot 0 may be
pending, delivered (type=255), or free (type=0) depending on allocation order.
`EVENT-EMIT` and `EVENT-DRAIN` have been corrected (G10): EMIT delegates to
`HERA-NOTIFY-*`; DRAIN is a no-op (MSG-REAP owns cleanup). `EVENT-WAIT` is
retained as a diagnostic peek but must not be used for correctness decisions.

### Terminology: heat-gated reclamation, not mark-and-sweep

Channel and message reaping is **heat-gated reclamation**: objects are freed only
when compudynamic heat decays to zero. This serializes reaping against active
traffic on that object only — it is not stop-the-world for the VM as a whole.
Do not apply GC vocabulary (mark-and-sweep, generational, root-set tracing) to
this mechanism; those terms carry expectations the design never intended.

---

## v1 Block Map — LOCKED

Blocks 4110–4113 are Artemis. NEVER touch them.

```
4100  Constants: event codes, channel states, node sizes, arena sizes, MSG-DELIVERED
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@/!
4122  Message field accessors cont.: MSG-CH@/!
4106  Channel+member accessors: CH-ID@/! CH-OWNER@/! CH-STATE@/! CH-HEAT@/! CH-MBRS@/! CH-NEXT@/! MBR-NEXT@ MBR-VM@
4107  VARIABLE MSG-LAST-MSG + IDX>NAME + MSG-DELIVER
4123  MSG-SEND
4108  VARIABLE MSG-SCAN + MSG-COOL-ONE + MSG-COOL-ALL
4124  MSG-TOTAL-HEAT
4128  MSG-DELIVER-ALL
4109  MSG-REAP
---- 4110–4113: ARTEMIS — DO NOT TOUCH ----
4114  VARIABLE CH-SCAN + CH-COOL-ALL + CH-TOTAL-HEAT
4115  CH-REAP-SAFE
4116  VARIABLE COMMON-CH + COMMON-INIT + HERMES-TICK
4125  HERMES-K + WELCOME (LOG-INFO at load)
4117  EVENT-EMIT + EVENT-WAIT + EVENT-DRAIN (backward compat)
4118  HERA-NOTIFY-SPAWN + HERA-NOTIFY-KILL
4119  CH-MINT-ID + CH-REQUEST
4126  CH-ACCEPT + CH-CONFIRM + CH-CLOSE
4120  CD-INIT (loads lib.4th + common:msg.4th; LOG-INFO" Hermes: ready")
4121  MSG-ACK-LAST + MSG-NACK-LAST
4127  MSG-USED + CH-USED + HERMES-STATUS
```

### Node layouts (cells)

**Message node — 8 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
- 7: channel ptr (0 = no channel)

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