hakmem/docs/analysis/PHASE87_INSTRUMENTATION_COMPLETE.md

# 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.