FABRIC.md: resolve §17.3 -- words onto the Stadium, hosted/kernel split

Elevates §17.3 from LEANING to DECIDED, settled on paper before item
4.1's code per Captain Bob's request. The core claim (replace
round-robin eviction with Stadium density ranking) already argued for
itself in this section; what was missing was the hosted/kernel split
§25.5's "never two live heat mechanisms at once" implied but never
resolved.

Grounded in code, not policy: dictionary_management.c calls
hotwords_cache_lookup()/evict_*() unconditionally in the word-lookup
path (not gated by ENABLE_HOTWORDS_CACHE at the call sites), and that
file is vendored shared source required to work in both hosted and
kernel builds. The Stadium is kernel-only by construction of
everything built through item 3.7. ENABLE_HOTWORDS_CACHE already
defaults off in both Makefiles today (Kconfig.physics, verified
against both Makefiles directly).

Resolution: kernel builds retire the old cache's effect once item 4.1
lands (Stadium takes over, old call sites bypassed under
__STARKERNEL__ regardless of the Kconfig setting); hosted builds are
unchanged, no Stadium is built for them. Item 4.1 decides the exact
bypass mechanism, not invented here.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Robert Allan James
2026-08-04 18:13:54 -04:00
co-authored by Claude Sonnet 5
parent e55111c2c5
commit ec2c97ef70
+49 -2
View File
@@ -823,8 +823,55 @@ Consequences if this holds:
- Pin stops being a general-purpose escape hatch and goes back to meaning what §3 says:
invariance, for the few things that genuinely must not vary.
**LEANING.** The mechanism is already built and the fit is clean, but this reframes a
direction stated differently earlier the same day, and it deserves longer than a paragraph.
~~**LEANING.**~~ **DECIDED 2026-08-04**, on paper, before item 4.1's code — settled after
starting that item surfaced this section as its unresolved prerequisite.
**The core claim stands, for the reason already given above.** The existing cache is
self-contradictory as built: heat gates admission, nothing governs departure, and the
consequence is that the hottest word in the cache can be evicted purely because its slot
came up in the round-robin rotation. Moving words onto the Stadium repairs a real defect,
not a relabeling exercise, and `stats.evictions`/`stats.promotions`/`stats.cache_hits` make
it directly measurable before and after, exactly as this section already argued.
**What was actually missing was the hosted/kernel split** — §25.5's own header warns
"never two live heat mechanisms at once" (§11), but nothing said which way that resolves,
and the two subsystems involved are not symmetric:
- `src/physics_hotwords_cache.c` and `src/dictionary_management.c` are vendored, shared
source. `dictionary_management.c` calls `hotwords_cache_lookup()` /
`hotwords_cache_evict_*()` directly in the word-lookup path, **not gated by
`#ifdef ENABLE_HOTWORDS_CACHE`** at the call sites — the toggle only controls the cache's
own internal behaviour, not whether these call sites exist. This file must keep compiling
and working correctly in both the hosted and kernel builds (CLAUDE.md is explicit).
- The Stadium (`stadium.h`/`stadium.c`) is, and by construction of everything built through
item 3.7 can only be, kernel-only — every declaration in it is `#ifdef __STARKERNEL__`.
Nothing in this document has ever proposed a hosted Stadium, and building one is not
something item 4.1 needs to do.
- `ENABLE_HOTWORDS_CACHE` already defaults to **off** in both the hosted `Makefile` and
`Makefile.starkernel` today (`Kconfig.physics`, confirmed against both Makefiles directly
— a stale comment beside the Makefile default claims the opposite, but the actual default
is `n`/`0` in both). So "two live mechanisms" is not a live conflict in the default build
today; it only becomes one once item 4.1's kernel-side migration and the old cache are
both actually exercised at once.
**Resolution: kernel and hosted diverge, and that is the correct shape, not a compromise.**
- **Kernel builds:** once item 4.1 lands, the old cache's *effect* is retired under
`__STARKERNEL__` — word patrons migrate onto the Stadium, and
`hotwords_cache_lookup()`/`hotwords_cache_evict_*()`'s call sites in
`dictionary_management.c` are bypassed for the kernel build regardless of the
`ENABLE_HOTWORDS_CACHE` setting. The shared source can stay compiled as-is (untouched, for
hosted's sake) while being functionally inert on the kernel side. Item 4.1 decides the
exact mechanism (a build-time gate, a runtime check, or something else) — not invented
here.
- **Hosted builds: unchanged.** No Stadium exists there, none is being built for it, and the
existing mechanism — including its current off-by-default setting — stays exactly as it
is. This is what keeps CLAUDE.md's dual-target compileability requirement satisfied
without inventing a second Stadium implementation nobody asked for.
Consequences from above still hold: words need no pin exception (reap event is cooling off
the floor), §16.3's dictionary-parity concern narrows to the hot set alone, and pin goes
back to meaning invariance rather than a general-purpose escape hatch.
### 17.4 Open