starkernel: item 3.6 -- Hera as patron zero, pinned (Phase 3 core complete)

Punch list §25 item 3.6 complete. Phase 3 (§25.4) core is now done:
items 3.1-3.6 all closed.

stadium_evict() now panics via sk_hal_panic() if a resident cell 0
(Hera, patron zero by construction of §6's boot order) is ever
selected for eviction. Placement is deliberate: the check runs before
the pin/contains refusal checks, not after -- if it ran after, a
wrongly-cleared pin would let the ordinary refusal path quietly return
-1 instead of ever reaching the panic, defeating the point of a check
that's supposed to be independent of pin holding.

Per §20.5 #3's explicit wording, not implemented as a filter:
stadium_admit()'s least-dense search is unchanged, still relying on
the general pin skip from item 3.5. Adding a second filter there would
have done exactly what that section warns against ("filtering hides
the bug, asserting reports it").

The panic path is, and will remain, unexercised by the acceptance
mechanism: sk_hal_panic() halts the machine, and triggering it
deliberately is incompatible with the three-arch boot being this
project's sole acceptance test. Correctness rests on the placement
argument, not a test -- same honesty precedent as items 3.4 and 3.5's
other unexercised paths.

Verified: three-architecture boot (amd64, aarch64, riscv64), all
reaching ok> with identical dict_hash=0x3d4e1daf289da94f matching the
item-3.5 baseline.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Robert Allan James
2026-08-04 17:36:23 -04:00
co-authored by Claude Sonnet 5
parent f8a50561b0
commit 72487e7fff
10 changed files with 31376 additions and 6 deletions
+24 -4
View File
@@ -212,15 +212,35 @@ uint64_t stadium_density(size_t cell_index);
/* Sentinel returned by stadium_admit() on refusal -- no cell index is this large. */
#define STADIUM_CELL_NONE ((size_t)-1)
/*
* Hera is patron zero by construction of §6's boot order: she is the first
* entry admitted into the Stadium. This is a positional invariant, not a
* runtime check of who currently occupies cell 0 -- nothing yet births
* anything, Hera included, so today this index is never actually occupied.
* Used only by stadium_evict()'s item-3.6 assertion below.
*/
#define STADIUM_HERA_CELL_INDEX ((size_t)0)
/*
* stadium_evict - Reap the patron header at cell_index (FABRIC.md §17.2:
* "reap means leaves the floor, not destroyed"). Dispatches its behaviour
* (§18.3), clears its item-3.1 discriminator bit, zeroes its header.
*
* Refuses if the header is pinned (`flags` bit 0, §3's invariance wire) or
* has a non-none `contains` (item 1.1: a patron holding another cannot be
* reaped, full stop). Also refuses for an out-of-range index or a cell whose
* discriminator bit is not set (nothing resident there to reap).
* PANICS (does not return) if cell_index == STADIUM_HERA_CELL_INDEX and the
* cell is actually resident -- FABRIC.md §20.5 #3: Hera is pinned (§3), but
* pinning alone is a silent guarantee, and item 3.6 requires a hard
* assertion at the eviction site rather than relying on pin holding. This
* check runs BEFORE the pin/contains checks below, deliberately: if pin were
* ever wrongly cleared, the ordinary pin-refusal path would quietly return
* -1 instead of surfacing the break, defeating the point of a second,
* independent check. Selecting patron zero for eviction means the invariant
* is already broken; continuing would run the system without a governor.
*
* Refuses (returns -1, does not panic) if the header is pinned (`flags` bit
* 0, §3's invariance wire) or has a non-none `contains` (item 1.1: a patron
* holding another cannot be reaped, full stop). Also refuses for an
* out-of-range index or a cell whose discriminator bit is not set (nothing
* resident there to reap).
*
* @param cell_index Index of the patron header to reap.
* @return 0 on success, -1 if refused.