Working state before pushing to cyu remote

docs/analysis/PHASE87_INSTRUMENTATION_COMPLETE.md

@@ -0,0 +1,128 @@
+# Phase 87: Inline Slots Overflow Observation - Infrastructure Setup (COMPLETE)
+
+## Phase 87-1: Telemetry Box Created ✓
+
+### Files Added
+
+1. **core/box/tiny_inline_slots_overflow_stats_box.h**
+   - Global counter structure: `TinyInlineSlotsOverflowStats`
+   - Counters: C3/C4/C5/C6 push_full, pop_empty, overflow_to_uc, overflow_to_legacy
+   - Fast-path inline API with `__builtin_expect()` for zero-cost when disabled
+   - Enabled via compile-time gate:
+     - `HAKMEM_INLINE_SLOTS_OVERFLOW_STATS_COMPILED=0/1` (default 0)
+     - Non-RELEASE builds can also enable it (depending on build flags)
+
+2. **core/box/tiny_inline_slots_overflow_stats_box.c**
+   - Global state initialization
+   - Refresh function placeholder
+   - Report function for final statistics output
+
+### Makefile Integration
+
+- Added `core/box/tiny_inline_slots_overflow_stats_box.o` to:
+  - OBJS_BASE
+  - BENCH_HAKMEM_OBJS_BASE
+  - TINY_BENCH_OBJS_BASE
+ - OBSERVE build enables telemetry explicitly:
+   - `make bench_random_mixed_hakmem_observe` adds `-DHAKMEM_INLINE_SLOTS_OVERFLOW_STATS_COMPILED=1`
+
+### Build Status
+
+✓ Successfully compiled (no errors, no warnings in new code)
+✓ Binary ready: `bench_random_mixed_hakmem`
+
+---
+
+## Next: Phase 87-2 - Counter Integration Points
+
+To enable overflow measurement, counters must be injected at:
+
+### Free Path (Push FULL)
+- Location: `core/front/tiny_c6_inline_slots.h:37` (c6_inline_push)
+- Trigger: When ring is FULL, return 0
+- Counter: `tiny_inline_slots_count_push_full(6)`
+
+- Similar for C3 (`core/front/tiny_c3_inline_slots.h`), C4, C5
+
+### Alloc Path (Pop EMPTY)
+- Location: `core/front/tiny_c6_inline_slots.h:54` (c6_inline_pop)
+- Trigger: When ring is EMPTY, return NULL
+- Counter: `tiny_inline_slots_count_pop_empty(6)`
+
+- Similar for C3, C4, C5
+
+### Fallback Destinations (Unified Cache)
+- Location: `core/front/tiny_unified_cache.h:177-216` (unified_cache_push)
+- Trigger: When unified cache is FULL, return 0
+- Counter: `tiny_inline_slots_count_overflow_to_uc()`
+
+- Also: when unified_cache_push returns 0, legacy path gets called
+- Counter: `tiny_inline_slots_count_overflow_to_legacy()`
+
+---
+
+## Testing Plan (Phase 87-2)
+
+### Observation Conditions
+- **Profile**: MIXED_TINYV3_C7_SAFE
+- **Working Set**: WS=400 (default inline slots conditions)
+- **Iterations**: 20M (ITERS=20000000)
+- **Runs**: single-run OBSERVE preflight (SSOT throughput runs remain Standard/FAST)
+
+### Expected Output
+Debug build will print statistics:
+```
+=== PHASE 87: INLINE SLOTS OVERFLOW STATS ===
+
+PUSH FULL (Free Path Ring Overflow):
+  C3: ...
+  C4: ...
+  C5: ...
+  C6: ...
+
+POP EMPTY (Alloc Path Ring Underflow):
+  C3: ...
+  C4: ...
+  C5: ...
+  C6: ...
+
+Note: `OVERFLOW DESTINATIONS` counters are optional and may remain 0 unless explicitly instrumented at fallback call sites.
+```
+
+### GO/NO-GO Decision Logic
+
+**GO for Phase 88** if:
+- `(push_full + pop_empty) / (20M * 3 runs) ≥ 0.1%`
+- Indicates sufficient overflow frequency to warrant batch optimization
+
+**NO-GO for Phase 88** if:
+- Overflow rate < 0.1%
+- Suggests overhead reduction ROI is minimal
+- Consider alternative optimization layers
+
+---
+
+## Architecture Notes
+
+- Counters use `_Atomic` for thread-safety (single increment per operation)
+- Zero overhead in RELEASE builds (compile-time constant folding)
+- Reporting happens on exit (calls `tiny_inline_slots_overflow_report_stats()`)
+- Call point: Should add to bench program exit sequence
+
+---
+
+## Files Status
+
+| File | Status |
+|------|--------|
+| tiny_inline_slots_overflow_stats_box.h | ✓ Created |
+| tiny_inline_slots_overflow_stats_box.c | ✓ Created |
+| Makefile | ✓ Updated (object files added) |
+| C3/C4/C5/C6 inline slots | ⏳ Pending counter integration |
+| Observation binary build | ⏳ Pending debug build |
+
+---
+
+## Ready for Phase 87-2
+
+Next action: Inject counters into inline slots and run RUNS=3 observation.