/* StarForth — Steady-State Virtual Machine Runtime Copyright (c) 2023–2025 Robert A. James All rights reserved. This file is part of the StarForth project. Licensed under the StarForth License, Version 1.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at: https://github.com/star.4th@proton.me/StarForth/LICENSE.txt This software is provided "AS IS", WITHOUT WARRANTY OF ANY KIND, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and noninfringement. See the License for the specific language governing permissions and limitations under the License. */ /** * stadium_words.h - Word patrons on the Stadium (FABRIC.md §17.3/§17.7, * punch list item 4.1) * * The word-specific layer on top of the generic L0 engine (stadium.h). * Nothing in stadium.c/.h knows a word patron exists -- it only ever sees * cell_index, VMUuid, and StadiumPatronHeader. This file is where "word" * becomes a concrete meaning: a word_id -> cell_index map (kernel-side, * deliberately NOT a DictEntry field, decided 2026-08-05), the starter-grant * admission rule (Option B), and the reservoir-quantum touch/cool that feed * and drain a resident word's Stadium heat. * * `execution_heat` and `dict_hash` are untouched by anything in this file * (§17.7) -- this is a second, independent conserved quantity living in the * Stadium cell's `heat` field, not a representation of the first. */ #ifndef STARKERNEL_VM_STADIUM_WORDS_H #define STARKERNEL_VM_STADIUM_WORDS_H #ifdef __STARKERNEL__ #include #include "starkernel/vm_uuid.h" /* * 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. */ void stadium_words_init(void); /* * stadium_word_dispatch - The per-dispatch entry point (FABRIC.md §17.7), * called once per DictEntry touched at each of vm_core.c's three * physics_execution_heat_increment() call sites -- deliberately mirroring * that function's existing call pattern 1:1, including the entry != canon * double-touch case, rather than inventing a different shape. * * If word_id is already resident: applies the redirected Loop #3 cooling * (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). * * 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. * * No-op if word_id == WORD_ID_INVALID, word_id >= DICTIONARY_SIZE, or the * word layer has not been initialized. * * @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 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 * decay computation in this tree). */ void stadium_word_dispatch(VMUuid vm_id, uint32_t word_id, uint64_t heartbeat_ticks); /* * stadium_word_forget - Coherence hook for FORGET (word_id recycling). * vm_dictionary_untrack_entry() must call this BEFORE the word_id is pushed * onto vm->recycled_word_ids -- otherwise the next word assigned the same * recycled id would alias onto the forgotten word's still-resident cell and * 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. * * @param word_id The DictEntry's word_id, about to be recycled. */ void stadium_word_forget(uint32_t word_id); /* * stadium_words_stats - Promotion/eviction counters (same shape as the old * cache's HotwordsStats.promotions/.evictions, not that struct -- §25.5's * acceptance for item 4.1). Promotion = a successful starter-grant * 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(). */ void stadium_words_stats(uint64_t *promotions, uint64_t *evictions); /* * stadium_words_print_boot_diagnostics - Console output satisfying item * 4.1's "observable via a diagnostic word or boot console output" * 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. * * @param vm_id The VM whose reservoir to read (vm_uuid_hera() today). */ void stadium_words_print_boot_diagnostics(VMUuid vm_id); #endif /* __STARKERNEL__ */ #endif /* STARKERNEL_VM_STADIUM_WORDS_H */