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:
co-authored by
Claude Sonnet 5
parent
bd92c57834
commit
3d0b9351bd
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user