starkernel: item 4.1 -- hot words onto the Stadium, density-ranked eviction

Punch list §25 item 4.1 complete.
Replaces the round-robin hotwords cache with Stadium density-ranked
admission/eviction on the kernel side, via the §17.7 reservoir mechanism and a
kernel-side word_id -> cell_index map (no DictEntry change, dict_hash
untouched). Adds stadium_birth_hera() to close the cell-0 panic hazard,
STADIUM_WORD_HEAT_QUANTUM/STADIUM_WORD_COOL_RATE_Q48 Kconfig knobs (flagged
untuned), and a stadium_word_forget() FORGET coherence hook to close a
recycled-word_id aliasing gap.

Verified: all five hotwords_cache_* call sites in dictionary_management.c
bypassed under __STARKERNEL__; word dispatch feeds the Stadium at all three
vm_core.c physics_execution_heat_increment() sites; hosted make unaffected;
all three architectures booted to ok> with matching dict_hash
(0x3d4e1daf289da94f) and matching conservation stats (promotions=354
evictions=0, resident_sum=65536 reservoir=0 sum=65536).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Robert Allan James
2026-08-05 13:37:10 -04:00
co-authored by Claude Sonnet 5
parent bd92c57834
commit 3d0b9351bd
19 changed files with 32009 additions and 24 deletions
+66
View File
@@ -241,6 +241,72 @@ uint64_t stadium_density(size_t cell_index);
*/
#define STADIUM_HERA_CELL_INDEX ((size_t)0)
/*
* stadium_birth_hera - Admits Hera as a real resident of cell 0 (FABRIC.md
* item 3.6's invariant, actually enforced -- item 4.1 found that nothing had
* ever called this until a word patron was about to become the first-ever
* occupant of cell 0 by accident via the free list). Candidate: identity 0,
* heat 0, mass 1, pinned (STADIUM_FLAG_PIN), behaviour COOL. Heat 0 means no
* reservoir transfer is needed -- conservation holds trivially (the
* reservoir keeps the VM's whole share; Hera's own cell contributes 0).
* Being pinned excludes her from every eviction-candidate scan (§3), so the
* stadium_evict() panic guard at STADIUM_HERA_CELL_INDEX stays correctly
* dormant rather than reachable-by-accident.
*
* Idempotent: a second call is a no-op (returns 0) if she is already
* resident. Must be called after stadium_boot_init() and before any word
* ever dispatches (§6) -- kernel_main.c calls it immediately after
* stadium_boot_init(), before M7's VM bootstrap.
*
* @return 0 on success (or already born), -1 if the Stadium is not
* initialized or the admission was refused (should not happen: her
* quota is granted in full, empty, at stadium_boot_init()).
*/
int stadium_birth_hera(void);
/*
* stadium_reservoir_pull - Transfers up to `amount` (Q48.16) out of vm_id's
* reservoir (FABRIC.md §17.7's reservoir mechanism). Clamped to what the
* reservoir actually holds -- never goes negative, never invents heat.
* Returns the amount actually pulled, which may be less than requested (or
* 0, e.g. a drained reservoir or an unknown vm_id). Callers that go on to
* fail their own operation (e.g. a refused stadium_admit()) MUST push the
* pulled amount back via stadium_reservoir_push() to preserve
* Σ(resident heat) + reservoir == Q48_ONE across the failed attempt.
*
* @param vm_id Owning VM's id.
* @param amount Requested Q48.16 amount.
* @return Amount actually pulled (0..amount).
*/
uint64_t stadium_reservoir_pull(VMUuid vm_id, uint64_t amount);
/*
* stadium_reservoir_push - Credits `amount` (Q48.16) back into vm_id's
* reservoir. The other half of every reservoir transfer (§17.7): cooling
* returns heat here, a refused starter-grant rolls back here, and
* stadium_evict() credits a departing patron's remaining heat here before
* the cell returns to the free list -- the invariant is a transfer, never a
* reset. No-op if vm_id has no quota (caller contract; mirrors
* stadium_admit()'s silent refusal for the same case).
*
* @param vm_id Owning VM's id.
* @param amount Q48.16 amount to credit.
*/
void stadium_reservoir_push(VMUuid vm_id, uint64_t amount);
/*
* stadium_reservoir_peek - Read-only: vm_id's current reservoir balance
* (Q48.16), for diagnostics/conservation checks. Does not mutate state.
* Returns 0 for an unknown vm_id -- indistinguishable from a genuinely
* drained reservoir, same as stadium_reservoir_pull()'s 0 return; callers
* that need to tell those apart must already know whether vm_id has a
* quota (e.g. via the same check they'd use before calling stadium_admit()).
*
* @param vm_id Owning VM's id.
* @return Current reservoir balance, or 0 if vm_id has no quota.
*/
uint64_t stadium_reservoir_peek(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