Phase 23 Unified Cache + PageFaultTelemetry generalization: Mid/VM page-fault bottleneck identified

Summary:
- Phase 23 Unified Cache: +30% improvement (Random Mixed 256B: 18.18M → 23.68M ops/s)
- PageFaultTelemetry: Extended to generic buckets (C0-C7, MID, L25, SSM)
- Measurement-driven decision: Mid/VM page-faults (80-100K) >> Tiny (6K) → prioritize Mid/VM optimization

Phase 23 Changes:
1. Unified Cache implementation (core/front/tiny_unified_cache.{c,h})
   - Direct SuperSlab carve (TLS SLL bypass)
   - Self-contained pop-or-refill pattern
   - ENV: HAKMEM_TINY_UNIFIED_CACHE=1, HAKMEM_TINY_UNIFIED_C{0-7}=128

2. Fast path pruning (tiny_alloc_fast.inc.h, tiny_free_fast_v2.inc.h)
   - Unified ON → direct cache access (skip all intermediate layers)
   - Alloc: unified_cache_pop_or_refill() → immediate fail to slow
   - Free: unified_cache_push() → fallback to SLL only if full

PageFaultTelemetry Changes:
3. Generic bucket architecture (core/box/pagefault_telemetry_box.{c,h})
   - PF_BUCKET_{C0-C7, MID, L25, SSM} for domain-specific measurement
   - Integration: hak_pool_try_alloc(), l25_alloc_new_run(), shared_pool_allocate_superslab_unlocked()

4. Measurement results (Random Mixed 500K / 256B):
   - Tiny C2-C7: 2-33 pages, high reuse (64-3.8 touches/page)
   - SSM: 512 pages (initialization footprint)
   - MID/L25: 0 (unused in this workload)
   - Mid/Large VM benchmarks: 80-100K page-faults (13-16x higher than Tiny)

Ring Cache Enhancements:
5. Hot Ring Cache (core/front/tiny_ring_cache.{c,h})
   - ENV: HAKMEM_TINY_HOT_RING_ENABLE=1, HAKMEM_TINY_HOT_RING_C{0-7}=size
   - Conditional compilation cleanup

Documentation:
6. Analysis reports
   - RANDOM_MIXED_BOTTLENECK_ANALYSIS.md: Page-fault breakdown
   - RANDOM_MIXED_SUMMARY.md: Phase 23 summary
   - RING_CACHE_ACTIVATION_GUIDE.md: Ring cache usage
   - CURRENT_TASK.md: Updated with Phase 23 results and Phase 24 plan

Next Steps (Phase 24):
- Target: Mid/VM PageArena/HotSpanBox (page-fault reduction 80-100K → 30-40K)
- Tiny SSM optimization deferred (low ROI, ~6K page-faults already optimal)
- Expected improvement: +30-50% for Mid/Large workloads

Generated with Claude Code

Co-Authored-By: Claude <noreply@anthropic.com>

core/box/front_gate_classifier.c

@@ -28,11 +28,13 @@
 __thread uint64_t g_classify_header_hit = 0;
 __thread uint64_t g_classify_headerless_hit = 0;
 __thread uint64_t g_classify_pool_hit = 0;
+__thread uint64_t g_classify_mid_large_hit = 0;
 __thread uint64_t g_classify_unknown_hit = 0;
 
 void front_gate_print_stats(void) {
     uint64_t total = g_classify_header_hit + g_classify_headerless_hit +
-                     g_classify_pool_hit + g_classify_unknown_hit;
+                     g_classify_pool_hit + g_classify_mid_large_hit +
+                     g_classify_unknown_hit;
     if (total == 0) return;
 
     fprintf(stderr, "\n========== Front Gate Classification Stats ==========\n");
@@ -42,6 +44,8 @@ void front_gate_print_stats(void) {
             g_classify_headerless_hit, 100.0 * g_classify_headerless_hit / total);
     fprintf(stderr, "Pool TLS:          %lu (%.2f%%)\n",
             g_classify_pool_hit, 100.0 * g_classify_pool_hit / total);
+    fprintf(stderr, "Mid-Large (MMAP):  %lu (%.2f%%)\n",
+            g_classify_mid_large_hit, 100.0 * g_classify_mid_large_hit / total);
     fprintf(stderr, "Unknown:           %lu (%.2f%%)\n",
             g_classify_unknown_hit, 100.0 * g_classify_unknown_hit / total);
     fprintf(stderr, "Total:             %lu\n", total);
@@ -253,6 +257,30 @@ ptr_classification_t classify_ptr(void* ptr) {
         return result;
     }
 
+    // Check for Mid-Large allocation with AllocHeader (MMAP/POOL/L25_POOL)
+    // AllocHeader is placed before user pointer (user_ptr - HEADER_SIZE)
+    //
+    // Safety check: Need at least HEADER_SIZE (40 bytes) before ptr to read AllocHeader
+    // If ptr is too close to page start, skip this check (avoid SEGV)
+    uintptr_t offset_in_page_for_hdr = (uintptr_t)ptr & 0xFFF;
+    if (offset_in_page_for_hdr >= HEADER_SIZE) {
+        // Safe to read AllocHeader (won't cross page boundary)
+        AllocHeader* hdr = hak_header_from_user(ptr);
+        if (hak_header_validate(hdr)) {
+        // Valid HAKMEM header found
+        if (hdr->method == ALLOC_METHOD_MMAP ||
+            hdr->method == ALLOC_METHOD_POOL ||
+            hdr->method == ALLOC_METHOD_L25_POOL) {
+            result.kind = PTR_KIND_MID_LARGE;
+            result.ss = NULL;
+#if !HAKMEM_BUILD_RELEASE
+            g_classify_mid_large_hit++;
+#endif
+            return result;
+        }
+        }
+    }
+
     // Unknown pointer (external allocation or Mid/Large)
     // Let free wrapper handle Mid/Large registry lookups
     result.kind = PTR_KIND_UNKNOWN;