Add stadium_conserved() -- FABRIC-3.6.md task 0.7, item 41

Boolean analogue of vm_physics_conserved(), for the Stadium per-VM
quota invariant rather than fleet-wide execution heat
(FABRIC-3.5.md SXXXIX.4). int stadium_conserved(VMUuid vm_id), in
src/starkernel/vm/stadium.c alongside stadium_resident_sum()/
stadium_reservoir_peek() that it's built from, declared in
include/starkernel/vm/stadium.h.

Implements the two-term form -- resident_sum(vm_id) +
reservoir_peek(vm_id) == Q48_ONE -- not the three-term form SXL.4
rules for the eventual system. That ruling's `consumed` term is a
Phase 2 kernel-Hermes ledger deliverable that doesn't exist yet:
nothing draws on any VM's Stadium quota today (task 2.2 is literally
where that wiring gets built), so consumed is honestly zero right now.
Folding it in as a placeholder would be inventing Phase 2 state ahead
of it existing -- the doc comment says so explicitly, so whoever
builds Phase 2's ledger extends this function rather than working
around it.

Wired into the existing per-VM boot diagnostic
(stadium_words_print_boot_diagnostics(), kernel_main.c:810, Hera
only -- the sole existing call site) rather than adding a new one,
printing CONSERVED/DRIFTED the same shape vm_physics_status() already
uses.

Three-arch boot clean: amd64/aarch64/riscv64 all reach [zuse@Hera] ok>,
zero UNKNOWN WORD, all print "Stadium conservation: CONSERVED" with
identical resident_sum=47641 reservoir=17895 sum=65536=Q48_ONE. No
compiler warnings on either edited file (forced recompile checked).

Authorized by Captain Bob ("Yes.").

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Robert Allan James
2026-09-19 13:56:14 -04:00
co-authored by Claude Sonnet 5
parent 9886ad5315
commit 380f0a09c9
11 changed files with 27604 additions and 2 deletions
+22
View File
@@ -368,6 +368,28 @@ int stadium_quota_slot_for_vm(VMUuid vm_id);
*/
uint64_t stadium_resident_sum(VMUuid vm_id);
/*
* stadium_conserved - Boolean analogue of vm_physics_conserved(), for the
* Stadium per-VM quota invariant rather than fleet-wide execution heat
* (FABRIC-3.5.md §XXXIX.4, item 41). Checks, epsilon zero:
*
* stadium_resident_sum(vm_id) + stadium_reservoir_peek(vm_id) == Q48_ONE
*
* FABRIC-3.5.md §XL.4 rules that the full invariant also adds a `consumed`
* term once kernel-Hermes exists and ledgers what its allocator consumes
* (Phase 2) -- until then nothing draws on a VM's Stadium quota, so the
* two-term form above is exact, not an approximation of the eventual one.
* A future caller adding the `consumed` term does so here, not by working
* around this function.
*
* Returns 0 (not conserved) for an unknown vm_id, same convention as
* stadium_reservoir_peek()/stadium_resident_sum() returning 0 for one.
*
* @param vm_id VM to check.
* @return Non-zero if vm_id's Stadium quota is exactly conserved, 0 otherwise.
*/
int stadium_conserved(VMUuid vm_id);
/*
* stadium_evict - Reap the patron header at cell_index (FABRIC-0.md §17.2:
* "reap means leaves the floor, not destroyed"). Dispatches its behaviour