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
+30
View File
@@ -93,6 +93,36 @@ config STADIUM_MEMORY_PERCENT
against a QEMU -m 1024 test config while leaving the kernel heap
and everything else nearly all of physical memory.
config STADIUM_WORD_HEAT_QUANTUM
int "Q48.16 heat quantum moved per word touch/starter-grant (STADIUM_WORD_HEAT_QUANTUM)"
default 2048
help
FABRIC.md §17.7 (item 4.1): the fixed Q48.16 amount transferred between
a VM's Stadium reservoir and a word patron's cell on every touch
(already-resident) or starter-grant admission attempt (non-resident,
Option B). Q48_ONE is 65536; the default of 2048 is Q48_ONE divided by
HOTWORDS_CACHE_SIZE (32) -- the population of the cache mechanism this
item retires under __STARKERNEL__ -- so roughly 32 words could hold a
"fully loaded" starter share at once, matching the old cache's slot
count. An untuned placeholder, not a derived optimum: real tuning is
DoE work (item 5.1), same treatment as STADIUM_MEMORY_PERCENT above.
config STADIUM_WORD_COOL_RATE_Q48
int "Q48.16 fraction of resident heat removed per tick (STADIUM_WORD_COOL_RATE_Q48)"
default 21845
help
FABRIC.md §17.7 (item 4.1): redirects Loop #3's decay shape onto
Stadium word-patron heat instead of discarding it -- cooled heat
returns to the VM's reservoir rather than vanishing, so this must be a
fraction of the patron's OWN current heat removed per elapsed tick
(unit-safe for a conserved share of 1.0), not a flat per-tick amount
the way execution_heat's own decay works. Default reuses
INITIAL_DECAY_SLOPE_Q48's numeric value (21845, ~1/3) reinterpreted as
this fraction -- the existing inference engine converged on that
magnitude for the analogous cooling purpose on execution_heat, so it
is a reasonable starting point, not the same quantity. Untuned
placeholder: real tuning is DoE work (item 5.1).
endif # STARFORTH_VARIANT_KERNEL
endmenu