admin/LithosAnanake
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

starkernel: item 4.2 -- Hermes native on the Stadium (complete)

Browse Source 
Migrates Hermes's message/channel lifecycle onto the Stadium's unified
heat/capacity economy: MSG-ALLOC/FREE-NODE and CH-ALLOC/FREE-NODE now
route entirely through stadium_admit()/stadium_evict(), replacing the
old local free-list + independent heat-field mechanism. Eight
kernel-only STADIUM-* FORTH primitives (ADMIT, EVICT, RES@, RES-PULL,
RES-PUSH, HEAT@, HEAT!, WORD-HEAT), VM.stadium_vm_id threaded through
all three vm_core.c dispatch sites (replacing item 4.1's hardcoded
vm_uuid_hera()), and the stadium_owner[idx] fix so evict-credit lands
in the VM that actually admitted a patron, not whoever owned cell 0.

This session's own contribution, on top of that pre-existing
implementation: found and fixed two bugs blocking the item's own K≡1.0
conservation self-check (HERMES-K was reading 0, not 65536):

- Q.SLOT admission-heat fix (capsules/hermes/init.4th): MSG-SEND/
  CH-ACCEPT admitted with Q.1 (the entire fleet-wide "1.0" unit) per
  item, a leftover from before the Stadium migration when each
  message/channel had its own unconstrained heat field. Instantly
  drained the shared, finite reservoir.

- Reservoir floor for word-execution admission (stadium_words.c):
  stadium_word_dispatch() (item 4.1) pulls STADIUM_WORD_HEAT_QUANTUM on
  every word dispatch, not just first admission -- exhausts a VM's
  entire reservoir in ~32 dispatches, starving any application-level
  economy sharing that VM's reservoir before it gets a chance to pull
  anything. word_dispatch_pull() now clamps word-execution's own pulls
  to leave a Q48_ONE/3 floor (same fair-share figure COMMON-CH's own
  floor already uses); application-level pulls are unaffected.

- STADIUM-WORD-HEAT primitive + stadium_words_resident_heat(): the
  floor deliberately leaves word-execution residents holding real
  heat, invisible to HERMES-K's original formula (MSG+CH+reservoir,
  no term for word patrons). Adding this term closes K to exactly
  65536 on all three architectures.

Also rules on two open scope questions in FABRIC.md: MBR-ALLOC/
MBR-FREE-NODE stay off the Stadium (membership records have no heat
field, never did -- the acceptance bullet's inclusion of them was a
completeness gesture predating a check of the actual layout), and
records the effort number (12 implementation files, +759/-120 lines).

Verified: all three architectures boot clean, full self-test passes,
Stadium conservation closes exactly (resident_sum + reservoir =
Q48_ONE) at both the C/Stadium level and the FORTH-level HERMES-K
check.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Robert Allan James
2026-08-07 01:49:23 -04:00
co-authored by Claude Sonnet 5
parent 0a7f144367
commit 5a28458b21
19 changed files with 1034 additions and 162 deletions
Download Patch File Download Diff File Expand all files Collapse all files
include/starkernel/vm/stadium.h
+64
View File
@@ -307,6 +307,33 @@ void stadium_reservoir_push(VMUuid vm_id, uint64_t amount);
*/
uint64_t stadium_reservoir_peek(VMUuid vm_id);
/*
* stadium_quota_slot_for_vm - Read-only: vm_id's quota slot index (0 to
* STADIUM_MAX_VM_COUNT-1), for callers outside stadium.c that need to key
* their own per-VM state the same way stadium.c's internal arrays already
* do (FABRIC.md §25.5 item 4.2 -- stadium_words.c's word_id -> cell_index
* map needs this to stop colliding across VMs; word_id is scoped per-VM,
* not globally unique, so a single shared map aliases different VMs' words
* onto each other's Stadium cells and reservoirs).
*
* @param vm_id VM to look up.
* @return Quota slot index, or -1 if vm_id holds no quota.
*/
int stadium_quota_slot_for_vm(VMUuid vm_id);
/*
* stadium_resident_sum - Read-only: sum of heat across every cell currently
* resident AND owned by vm_id's own quota (FABRIC.md §25.5 item 4.2 --
* boot diagnostics need this filtered per-VM once a second VM holds a
* quota; summing every resident cell regardless of owner, as the pre-4.2
* diagnostic did, mixes two VMs' conservation totals together).
* Returns 0 for an unknown vm_id, same convention as stadium_reservoir_peek().
*
* @param vm_id Owning VM's id.
* @return Sum of resident heat owned by vm_id (Q48.16), or 0 if vm_id has no quota.
*/
uint64_t stadium_resident_sum(VMUuid vm_id);
/*
* stadium_evict - Reap the patron header at cell_index (FABRIC.md §17.2:
* "reap means leaves the floor, not destroyed"). Dispatches its behaviour
@@ -430,6 +457,43 @@ size_t stadium_admit(VMUuid vm_id, const StadiumPatronHeader *candidate);
*/
int stadium_grant_quota(VMUuid new_vm_id, VMUuid from_vm_id);
/*
* stadium_cell_heat_get - Read a resident cell's own heat (FABRIC.md item
* 4.2's fourth ruling). Requires cell_index to be resident AND owned by
* vm_id's quota -- returns 0 otherwise (out of range, not resident, or
* belongs to a different VM), same ambiguity-with-a-genuine-zero already
* accepted by stadium_reservoir_peek()'s doc: callers that need to
* distinguish "refused" from "actually zero" must already know the cell is
* theirs (e.g. from their own resident-cell tracking), same contract as
* every other implicit-self primitive here.
*
* @param vm_id Calling VM's own identity.
* @param cell_index Index of the resident patron header to read.
* @return The cell's current heat (Q48.16), or 0 if refused.
*/
uint64_t stadium_cell_heat_get(VMUuid vm_id, size_t cell_index);
/*
* stadium_cell_heat_set - Write a resident cell's own heat, reconciling the
* reservoir delta atomically (FABRIC.md item 4.2's fourth ruling). Same
* ownership requirement as stadium_cell_heat_get(). If new_heat is higher
* than the cell's current heat, pulls the exact difference from vm_id's own
* reservoir first -- refuses (returns -1, no mutation) if the reservoir
* cannot cover the full increase, never a partial credit that would invent
* heat. If new_heat is lower, pushes the exact difference back to the
* reservoir after writing. Equal is a no-op success. This is the only
* sanctioned way to change a resident cell's heat post-admission -- doing
* the reservoir accounting here, not leaving it to the FORTH caller, is the
* whole reason this primitive exists rather than a raw field poke.
*
* @param vm_id Calling VM's own identity.
* @param cell_index Index of the resident patron header to write.
* @param new_heat The heat value to set (Q48.16).
* @return 0 on success, -1 if refused (not owned/resident, or insufficient
* reservoir for an increase).
*/
int stadium_cell_heat_set(VMUuid vm_id, size_t cell_index, uint64_t new_heat);
#endif /* __STARKERNEL__ */
#endif /* STARKERNEL_VM_STADIUM_H */
include/starkernel/vm/stadium_words.h
+63 -25
View File
@@ -48,9 +48,17 @@
/*
* stadium_words_init - Zeroes the word_id -> cell_index map (DICTIONARY_SIZE
* entries, static -- no allocation). Must be called after stadium_boot_init()
* and stadium_birth_hera(), before any word ever dispatches. Safe to call
* again (re-zeroes); nothing does today.
* entries per VM quota slot, STADIUM_MAX_VM_COUNT slots, static -- no
* allocation). Must be called after stadium_boot_init() and
* stadium_birth_hera(), before any word ever dispatches. Safe to call again
* (re-zeroes for every slot); nothing does today.
*
* item 4.2 (FABRIC.md §25.5): the map is keyed by quota slot, not just
* word_id -- word_id is assigned per-VM (vm->next_word_id), not globally
* unique, so a single shared word_id -> cell_index map aliased different
* VMs' words onto each other's Stadium cells and reservoirs the moment a
* second VM (Hermes) held a quota. One system-wide init call still covers
* every slot; no per-VM init call is needed.
*/
void stadium_words_init(void);
@@ -65,25 +73,34 @@ void stadium_words_init(void);
* (fraction of the cell's own current heat, scaled by elapsed_ticks since
* this word's own last touch -- STADIUM_WORD_COOL_RATE_Q48) crediting the
* cooled amount back to vm_id's reservoir, then pulls
* STADIUM_WORD_HEAT_QUANTUM from the reservoir into the cell (both clamped
* to what the reservoir actually holds).
* STADIUM_WORD_HEAT_QUANTUM from the reservoir into the cell -- clamped to
* what the reservoir actually holds AND to a floor of Q48_ONE / 3 that
* word-execution admission alone may never dip the reservoir below
* (FABRIC.md §25.7, Captain Bob's ruling 2026-08-06: this pull fires on
* EVERY dispatch, not just first admission, and without a floor exhausts a
* VM's entire reservoir in ~32 dispatches, starving any application-level
* economy -- e.g. item 4.2's Hermes -- sharing the same VM's reservoir).
* Application-level pulls (stadium_reservoir_pull() called directly) are
* not subject to this floor.
*
* If word_id is not resident (or the map's entry is stale -- self-healing
* check against the cell's discriminator bit and identity, covers both a
* prior eviction and a FORGET/redefine word_id reuse this function did not
* itself clear): attempts Option B starter-grant admission -- pulls
* STADIUM_WORD_HEAT_QUANTUM from the reservoir, builds an unpinned COOL
* candidate, calls stadium_admit(). On refusal, pushes the pulled quantum
* back (rollback, preserves conservation across the failed attempt). On
* success, records the mapping and increments the promotion counter.
* STADIUM_WORD_HEAT_QUANTUM from the reservoir (same floor as above),
* builds an unpinned COOL candidate, calls stadium_admit(). On refusal,
* pushes the pulled quantum back (rollback, preserves conservation across
* the failed attempt). On success, records the mapping and increments the
* promotion counter.
*
* No-op if word_id == WORD_ID_INVALID, word_id >= DICTIONARY_SIZE, or the
* word layer has not been initialized.
* No-op if word_id == WORD_ID_INVALID, word_id >= DICTIONARY_SIZE, or vm_id
* holds no Stadium quota.
*
* @param vm_id Owning VM. Hardcoded to vm_uuid_hera() at every
* call site today -- Tripod is pruned to Hera alone
* (item 0.1), and she is the only VM with a Stadium
* quota. Revisit when item 4.2 restores Hermes.
* @param vm_id Owning VM -- vm->stadium_vm_id at every call site.
* Scopes the word_id -> cell_index lookup to this
* VM's own quota slot (item 4.2, FABRIC.md §25.5) so
* two VMs' independently-numbered word_ids cannot
* alias onto each other's cells/reservoirs.
* @param word_id The dispatching DictEntry's stable word_id.
* @param heartbeat_ticks Current vm->heartbeat.tick_count (virtual tick,
* never wall-clock -- same convention as every other
@@ -99,12 +116,34 @@ void stadium_word_dispatch(VMUuid vm_id, uint32_t word_id, uint64_t heartbeat_ti
* its stale heat (same failure class as the 2026-08-02 block_words.c
* aliasing bug). Evicts the cell if word_id is resident (crediting its heat
* back to the reservoir via stadium_evict()'s own credit path) and clears
* the map entry. No-op if word_id is not resident, out of range, or the
* word layer is not initialized.
* the map entry. No-op if word_id is not resident, out of range, or vm_id
* holds no Stadium quota.
*
* @param vm_id Owning VM -- vm->stadium_vm_id (item 4.2, FABRIC.md §25.5:
* scopes the lookup to this VM's own word_slots, same
* reason stadium_word_dispatch() takes it).
* @param word_id The DictEntry's word_id, about to be recycled.
*/
void stadium_word_forget(uint32_t word_id);
void stadium_word_forget(VMUuid vm_id, uint32_t word_id);
/*
* stadium_words_resident_heat - Sum of heat held by vm_id's own
* word-execution residents only (item 4.1's cells, tracked in this file's
* own word_slots map) -- NOT messages/channels/other application residents,
* which stadium_resident_sum() (stadium.h, item 4.2) mixes in alongside
* everything else a VM owns. Exists so a VM's own application-level
* conservation check (e.g. Hermes's HERMES-K, FABRIC.md §25.7, Captain
* Bob's ruling 2026-08-06) can add this as an explicit term instead of
* silently omitting word-execution heat it has no other way to see.
*
* Walks all DICTIONARY_SIZE word_slots for vm_id's quota slot; each
* resident entry contributes its cell's current heat, verified live against
* the discriminator bitmap (same self-healing pattern as
* resolve_resident_cell() -- a stale map entry contributes 0, not garbage).
*
* @param vm_id The VM whose word-execution residents to sum.
*/
uint64_t stadium_words_resident_heat(VMUuid vm_id);
/*
* stadium_words_stats - Promotion/eviction counters (same shape as the old
@@ -113,9 +152,10 @@ void stadium_word_forget(uint32_t word_id);
* admission. Eviction = this word's cell was reaped by another admission's
* eviction fallback (stadium_admit()'s density comparison), detected
* lazily via the self-healing stale check in stadium_word_dispatch(), or
* explicitly via stadium_word_forget().
* explicitly via stadium_word_forget(). Scoped to vm_id's own quota slot
* (item 4.2) -- counters are no longer system-wide.
*/
void stadium_words_stats(uint64_t *promotions, uint64_t *evictions);
void stadium_words_stats(VMUuid vm_id, uint64_t *promotions, uint64_t *evictions);
/*
* stadium_words_print_boot_diagnostics - Console output satisfying item
@@ -123,11 +163,9 @@ void stadium_words_stats(uint64_t *promotions, uint64_t *evictions);
* acceptance line. Prints promotions/evictions, then
* Σ(resident heat) + reservoir against Q48_ONE as a conservation check --
* not required by the acceptance text, but the mechanism proves nothing if
* this silently doesn't hold. The heat sum is taken over ALL resident
* Stadium cells, not scoped by owner -- correct only because vm_id is the
* sole VM with any Stadium quota today (item 0.1's Hera-only pruning); the
* per-cell owner byte is private to stadium.c and has no public accessor.
* Revisit the scoping when item 4.2 restores Hermes.
* this silently doesn't hold. The heat sum is scoped to vm_id's own quota
* (stadium_resident_sum(), item 4.2, FABRIC.md §25.5) so two VMs' checks
* close independently instead of mixing both VMs' resident heat together.
*
* @param vm_id The VM whose reservoir to read (vm_uuid_hera() today).
*/