Phase E3-FINAL: Fix Box API offset bugs - ALL classes now use correct offsets

## Root Cause Analysis (GPT5)

**Physical Layout Constraints**:
- Class 0: 8B = [1B header][7B payload] → offset 1 = 9B needed = ❌ IMPOSSIBLE
- Class 1-6: >=16B = [1B header][15B+ payload] → offset 1 = ✅ POSSIBLE
- Class 7: 1KB → offset 0 (compatibility)

**Correct Specification**:
- HAKMEM_TINY_HEADER_CLASSIDX != 0:
  - Class 0, 7: next at offset 0 (overwrites header when on freelist)
  - Class 1-6: next at offset 1 (after header)
- HAKMEM_TINY_HEADER_CLASSIDX == 0:
  - All classes: next at offset 0

**Previous Bug**:
- Attempted "ALL classes offset 1" unification
- Class 0 with offset 1 caused immediate SEGV (9B > 8B block size)
- Mixed 2-arg/3-arg API caused confusion

## Fixes Applied

### 1. Restored 3-Argument Box API (core/box/tiny_next_ptr_box.h)
```c
// Correct signatures
void tiny_next_write(int class_idx, void* base, void* next_value)
void* tiny_next_read(int class_idx, const void* base)

// Correct offset calculation
size_t offset = (class_idx == 0 || class_idx == 7) ? 0 : 1;
```

### 2. Updated 123+ Call Sites Across 34 Files
- hakmem_tiny_hot_pop_v4.inc.h (4 locations)
- hakmem_tiny_fastcache.inc.h (3 locations)
- hakmem_tiny_tls_list.h (12 locations)
- superslab_inline.h (5 locations)
- tiny_fastcache.h (3 locations)
- ptr_trace.h (macro definitions)
- tls_sll_box.h (2 locations)
- + 27 additional files

Pattern: `tiny_next_read(base)` → `tiny_next_read(class_idx, base)`
Pattern: `tiny_next_write(base, next)` → `tiny_next_write(class_idx, base, next)`

### 3. Added Sentinel Detection Guards
- tiny_fast_push(): Block nodes with sentinel in ptr or ptr->next
- tls_list_push(): Block nodes with sentinel in ptr or ptr->next
- Defense-in-depth against remote free sentinel leakage

## Verification (GPT5 Report)

**Test Command**: `./out/release/bench_random_mixed_hakmem --iterations=70000`

**Results**:
- ✅ Main loop completed successfully
- ✅ Drain phase completed successfully
- ✅ NO SEGV (previous crash at iteration 66151 is FIXED)
- ℹ️ Final log: "tiny_alloc(1024) failed" is normal fallback to Mid/ACE layers

**Analysis**:
- Class 0 immediate SEGV: ✅ RESOLVED (correct offset 0 now used)
- 66K iteration crash: ✅ RESOLVED (offset consistency fixed)
- Box API conflicts: ✅ RESOLVED (unified 3-arg API)

## Technical Details

### Offset Logic Justification
```
Class 0:  8B block → next pointer (8B) fits ONLY at offset 0
Class 1: 16B block → next pointer (8B) fits at offset 1 (after 1B header)
Class 2: 32B block → next pointer (8B) fits at offset 1
...
Class 6: 512B block → next pointer (8B) fits at offset 1
Class 7: 1024B block → offset 0 for legacy compatibility
```

### Files Modified (Summary)
- Core API: `box/tiny_next_ptr_box.h`
- Hot paths: `hakmem_tiny_hot_pop*.inc.h`, `tiny_fastcache.h`
- TLS layers: `hakmem_tiny_tls_list.h`, `hakmem_tiny_tls_ops.h`
- SuperSlab: `superslab_inline.h`, `tiny_superslab_*.inc.h`
- Refill: `hakmem_tiny_refill.inc.h`, `tiny_refill_opt.h`
- Free paths: `tiny_free_magazine.inc.h`, `tiny_superslab_free.inc.h`
- Documentation: Multiple Phase E3 reports

## Remaining Work

None for Box API offset bugs - all structural issues resolved.

Future enhancements (non-critical):
- Periodic `grep -R '*(void**)' core/` to detect direct pointer access violations
- Enforce Box API usage via static analysis
- Document offset rationale in architecture docs

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

core/box/tiny_next_ptr_box.h

@@ -1,83 +1,59 @@
-#ifndef TINY_NEXT_PTR_BOX_H
-#define TINY_NEXT_PTR_BOX_H
+#pragma once
 
-/**
- * 📦 Box: Next Pointer Operations (Lowest-Level API)
+/*
+ * box/tiny_next_ptr_box.h
  *
- * Phase E1-CORRECT: Unified next pointer read/write API for ALL classes (C0-C7)
+ * Tiny next-pointer Box API (thin wrapper over tiny_nextptr.h)
  *
- * This Box provides structural guarantee that ALL next pointer operations
- * use consistent offset calculation, eliminating scattered direct pointer
- * access bugs.
+ * このヘッダは Phase E1-CORRECT で確定した next オフセット仕様に従い、
+ * すべての tiny freelist / TLS / fast-cache / refill / SLL が経由すべき
+ * 「唯一の Box API」を提供する。
  *
- * Design:
- * - With HAKMEM_TINY_HEADER_CLASSIDX=1: Next pointer stored at base+1 (ALL classes)
- * - Without headers: Next pointer stored at base+0
- * - Inline expansion ensures ZERO performance cost
+ * 仕様は tiny_nextptr.h と完全一致:
  *
- * Usage:
- *   void* next = tiny_next_read(class_idx, base_ptr);      // Read next pointer
- *   tiny_next_write(class_idx, base_ptr, new_next);        // Write next pointer
+ *   HAKMEM_TINY_HEADER_CLASSIDX != 0:
+ *     - Class 0: next_off = 0  (free中は header を潰す)
+ *     - Class 1-6: next_off = 1
+ *     - Class 7: next_off = 0
  *
- * Critical:
- * - ALL freelist operations MUST use this API
- * - Direct access like *(void**)ptr is PROHIBITED
- * - Grep can detect violations: grep -rn '\*\(void\*\*\)' core/
+ *   HAKMEM_TINY_HEADER_CLASSIDX == 0:
+ *     - 全クラス: next_off = 0
+ *
+ * 呼び出し規約:
+ *   - base: 「内部 box 基底 (header位置または従来base)」
+ *   - class_idx: size class index (0-7)
+ *
+ * 禁止事項:
+ *   - ここを通さずに next オフセットを手計算すること
+ *   - 直接 *(void**) で next を読む/書くこと
  */
 
 #include <stdint.h>
-#include <stdio.h>   // For debug fprintf
-#include <stdatomic.h>  // For _Atomic
-#include <stdlib.h>  // For abort()
+#include "hakmem_tiny_config.h"
+#include "tiny_nextptr.h"
 
-/**
- * Write next pointer to freelist node
- *
- * @param class_idx Size class index (0-7)
- * @param base Base pointer (NOT user pointer)
- * @param next_value Next pointer to store (or NULL for list terminator)
- *
- * CRITICAL FIX: Class 0 (8B block) cannot fit 8B pointer at offset 1!
- * - Class 0: 8B total = [1B header][7B data] → pointer at base+0 (overwrite header when free)
- * - Class 1-6: Next at base+1 (after header)
- * - Class 7: Next at base+0 (no header in original design, kept for compatibility)
- *
- * NOTE: We take class_idx as parameter (NOT read from header) because:
- * - Linear carved blocks don't have headers yet (uninitialized memory)
- * - Class 0/7 overwrite header with next pointer when on freelist
- */
-static inline void tiny_next_write(int class_idx, void* base, void* next_value) {
-#if HAKMEM_TINY_HEADER_CLASSIDX
-    // Phase E1-CORRECT FIX: Use class_idx parameter (NOT header byte!)
-    // Reading uninitialized header bytes causes random offset calculation
-    size_t next_offset = (class_idx == 0 || class_idx == 7) ? 0 : 1;
-
-    // Direct write (header validation temporarily disabled to debug hang in drain phase)
-    *(void**)((uint8_t*)base + next_offset) = next_value;
-#else
-    // No headers: Next pointer at base
-    *(void**)base = next_value;
+#ifdef __cplusplus
+extern "C" {
 #endif
+
+// Box API: write next pointer
+static inline void tiny_next_write(int class_idx, void *base, void *next_value) {
+    tiny_next_store(base, class_idx, next_value);
 }
 
-/**
- * Read next pointer from freelist node
- *
- * @param class_idx Size class index (0-7)
- * @param base Base pointer (NOT user pointer)
- * @return Next pointer (or NULL if end of list)
- */
-static inline void* tiny_next_read(int class_idx, const void* base) {
-#if HAKMEM_TINY_HEADER_CLASSIDX
-    // Phase E1-CORRECT FIX: Use class_idx parameter (NOT header byte!)
-    size_t next_offset = (class_idx == 0 || class_idx == 7) ? 0 : 1;
-
-    // Direct read (corruption check temporarily disabled to debug hang in drain phase)
-    return *(void**)((const uint8_t*)base + next_offset);
-#else
-    // No headers: Next pointer at base
-    return *(void**)base;
-#endif
+// Box API: read next pointer
+static inline void *tiny_next_read(int class_idx, const void *base) {
+    return tiny_next_load(base, class_idx);
 }
 
-#endif  // TINY_NEXT_PTR_BOX_H
+/*
+ * Greppable macros:
+ * - 既存コードは TINY_NEXT_READ/WRITE か tiny_next_read/write を使う。
+ * - これらから tiny_nextptr.h 実装へ一元的に到達する。
+ */
+#define TINY_NEXT_WRITE(cls_, base_, next_) tiny_next_write((cls_), (base_), (next_))
+#define TINY_NEXT_READ(cls_, base_)         tiny_next_read((cls_), (base_))
+
+#ifdef __cplusplus
+}
+#endif