docs(v4.0.0): correction -- each kind of patron keeps its own accounts

Captain Bob, 2026-10-05.  Records, from stadium.c and its layers, the
accounting rules of the VM, word, block and message patrons, that a v3
word already has more than one account, and withdraws two statements that
treated heat as one number per thing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
rajames
2026-10-05 17:50:28 -04:00
co-authored by Claude Opus 5.5
parent bd996a1106
commit e692759a96
+42
View File
@@ -328,6 +328,48 @@ one field.
- How the node tells a dictionary entry from a bare address at the call.
- `EXECUTE`, which enters a word by a return.
## 1g. Correction: every kind of patron keeps its own accounts
Captain Bob, 2026-10-05: "You're looking at it all wrong. Think of v3. The
VM is not the same thing as a word. It has a different set of accounting
rules in the Stadium. Same for any other patron. They define their own
accounting rules. Look at how the code is written."
Sections 1f and 2 above treat heat as one number per thing and ask where
to put it. That is wrong, and the code shows it. The generic engine
(`kernel/src/vm/stadium.c`) knows only a cell, a VM's quota and reservoir,
admission, eviction and the conservation check. What a patron *is*, and
how it is charged, is defined by its own layer:
| Patron | Layer | Its own rules |
|---|---|---|
| VM | `kernel/src/capsule/capsule_vm_physics.c`; quotas in `stadium.c` | Fleet-wide: the heat of all live VMs sums to 1.0. Born at zero. Touched only at dispatch points (`BIRTH`, `KILL`, `VM-EXEC`, `VM-CALL`, `VM-STEP`), which pull heat from the rest of the fleet toward it by elapsed ticks times a slope. On death its heat goes up the parent chain to Hera. Its Stadium quota and reservoir are granted from its parent. |
| Word | `kernel/src/vm/stadium_words.c` | One cell per (VM, word ID). Admitted on first dispatch with a starter grant. Every dispatch pulls a quantum from the VM's reservoir, never below a floor of one third. Cools by a fraction of its own heat per tick, back to the reservoir. Unpinned. Leaves by `COOL`. |
| Block | `kernel/src/vm/stadium_blocks.c` | One cell per (VM, LBN), in a hash table since LBNs are sparse. Its own quantum and cooling rate. Leaves by `MIGRATE`. |
| Message | `kernel/src/vm/kernel_hermes.c` | Admission costs the sender one slot's share. Decays by a fixed factor each time it is applied, and what decays is *consumed*, not returned. A ledger of held, pulled, returned and consumed must balance exactly. |
Each layer's constants are its own Kconfig symbols
(`STADIUM_WORD_HEAT_QUANTUM`, `STADIUM_WORD_COOL_RATE_Q48`,
`STADIUM_BLOCK_HEAT_QUANTUM`, `STADIUM_BLOCK_COOL_RATE_Q48`,
`STADIUM_CAPACITY_TICK`). Per VM, resident heat plus reservoir is 1.0.
**A v3 word already has more than one account.** Its Stadium cell is one.
The `execution_heat` field of its dictionary entry is another, with a
different rule (a flat amount per tick, not a fraction), and
`stadium_words.c` says of admission: "execution_heat plays no role". The
ACL's TTL reads `execution_heat`.
So these earlier statements are withdrawn:
- "A v4 node has two counts where v3 has one field" (section 1f). v3 has
separate accounts already; that is the design, not an anomaly.
- "Whether a word is a Stadium patron or only the 32 opcodes are" (section
1f, open list). It is not either-or. The opcode is a kind of patron with
rules of its own, as the word, the VM, the block and the message each
are.
What is actually open is what the opcode's own rules are.
## 2. Row 3: physics and per-word heat
### 2.1 What v3 does