60 lines
1.7 KiB
Markdown
60 lines
1.7 KiB
Markdown
|
# Phase 22: Research Box Prune (compile-out default-OFF boxes)
|
||
|
|
|
||
|
|
## Goal
|
||
|
|
|
||
|
|
Remove per-op overhead from **default-OFF** research boxes by compiling them out of hot paths.
|
||
|
|
|
||
|
|
This targets the pattern:
|
||
|
|
|
||
|
|
- feature is default OFF
|
||
|
|
- but hot path still pays an `if (enabled())` check and/or pulls in extra codegen
|
||
|
|
|
||
|
|
## Box Theory framing
|
||
|
|
|
||
|
|
- Treat this as a **build-time box boundary**:
|
||
|
|
- default build: research boxes compiled-out (zero runtime overhead)
|
||
|
|
- research build: boxes compiled-in (runtime ENV controls allowed)
|
||
|
|
- Rollback is build-flag only (no behavioral risk in default build).
|
||
|
|
|
||
|
|
## Scope (v1)
|
||
|
|
|
||
|
|
### Phase 14: Tiny tcache (intrusive LIFO)
|
||
|
|
|
||
|
|
Compile gate:
|
||
|
|
- `HAKMEM_TINY_TCACHE_COMPILED=0/1` (default: 0)
|
||
|
|
|
||
|
|
Integration points:
|
||
|
|
- `core/front/tiny_unified_cache.h`:
|
||
|
|
- wrap `tiny_tcache_try_push/pop()` callsites with `#if HAKMEM_TINY_TCACHE_COMPILED`
|
||
|
|
|
||
|
|
### Phase 15: UnifiedCache FIFO↔LIFO mode switch
|
||
|
|
|
||
|
|
Compile gate:
|
||
|
|
- `HAKMEM_TINY_UNIFIED_LIFO_COMPILED=0/1` (default: 0)
|
||
|
|
|
||
|
|
Integration points:
|
||
|
|
- `core/box/tiny_front_hot_box.h`:
|
||
|
|
- wrap `tiny_unified_lifo_enabled()` mode check + LIFO fast path with `#if HAKMEM_TINY_UNIFIED_LIFO_COMPILED`
|
||
|
|
|
||
|
|
## Implementation notes
|
||
|
|
|
||
|
|
- Compile gates live in `core/hakmem_build_flags.h`.
|
||
|
|
- Runtime ENV gates (`HAKMEM_TINY_TCACHE`, `HAKMEM_TINY_UNIFIED_LIFO`) remain valid for **research builds**
|
||
|
|
(i.e. when the compile gate is `1`).
|
||
|
|
- Default builds keep these features fully absent from hot paths.
|
||
|
|
|
||
|
|
## A/B plan
|
||
|
|
|
||
|
|
Use the standard Mixed A/B:
|
||
|
|
- `scripts/run_mixed_10_cleanenv.sh`
|
||
|
|
|
||
|
|
Compare:
|
||
|
|
- Phase 21 baseline (`HOTFULL=1`, compile gates OFF → default)
|
||
|
|
- Phase 21 + Phase 22 (compile gates OFF but callsites compiled-out)
|
||
|
|
|
||
|
|
## GO/NO-GO
|
||
|
|
|
||
|
|
- GO: Mixed 10-run mean +1.0% or more
|
||
|
|
- NEUTRAL: ±1.0%
|
||
|
|
- NO-GO: -1.0% or worse
|