Cleanup: Unify type naming and Cold Iface architecture

Refactoring:
- Type naming: Rename small_page_v4 → SmallPageMeta, small_class_heap_v4 → SmallClassHeap, small_heap_ctx_v4 → SmallHeapCtx
- Keep backward compatibility aliases for existing code
- SmallSegment struct unified, clean forward declarations
- Cold Iface: Remove vtable (SmallColdIfaceV4 struct) in favor of direct function calls
- Simplify refill_page/retire_page to direct calls, not callbacks
- smallobject_hotbox_v4.c: Update to call small_cold_v4_* functions directly

Documentation:
- Add docs/analysis/ENV_CLEANUP_CANDIDATES.md
- Categorize ENVs: KEEP (production), RESEARCH (opt-in), DELETE (obsolete)
- v2 code: Keep as research infrastructure (complete, safe, gated)
- v4 code: Research scaffold for future mid-level allocator

Build:
- ビルド成功（警告のみ）
- Backward compatible, all existing code still works

🤖 Generated with Claude Code

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

core/box/smallobject_cold_iface_v4.h

@@ -1,8 +1,9 @@
-// smallobject_cold_iface_v4.h - SmallObject HotHeap v4 Cold Interface (境界 API のみ)
+// smallobject_cold_iface_v4.h - SmallObject HotHeap v4 Cold Interface (Direct Functions)
 //
 // 役割:
-//   - HotBox_v4 と Superslab/Warm/Remote を繋ぐ関数ポインタの箱を定義する。
+//   - HotBox_v4 と Superslab/Warm/Remote を繋ぐ Cold 側のインターフェース。
-//   - 実装は後続フェーズで追加し、いまは型と宣言だけを置く。
+//   - 関数ポインタ（vtable）ではなく direct function で統一。
+//   - Hot Box は以下の関数を直接呼び出す（callback ではなく）。
 #pragma once
 
 #include <stdbool.h>
@@ -10,17 +11,8 @@
 
 #include "smallobject_hotbox_v4_box.h"
 
-typedef struct SmallColdIfaceV4 {
+// Cold path API: Direct functions (not function pointers)
-    small_page_v4* (*refill_page)(small_heap_ctx_v4*, uint32_t class_idx);
+// Hot box から直接呼び出される Cold 側の実装。
-    void (*retire_page)(small_heap_ctx_v4*, uint32_t class_idx, small_page_v4* page);
-    bool (*remote_push)(small_page_v4* page, void* ptr, uint32_t self_tid);
-    void (*remote_drain)(small_heap_ctx_v4*);
-} SmallColdIfaceV4;
-
-// Cold iface accessor（実装は後続フェーズ）
-const SmallColdIfaceV4* small_cold_iface_v4_get(void);
-
-// Direct function prototypes (Alternative API for direct calls, not yet implemented)
 small_page_v4* small_cold_v4_refill_page(small_heap_ctx_v4* ctx, uint32_t class_idx);
 void small_cold_v4_retire_page(small_heap_ctx_v4* ctx, small_page_v4* page);
 bool small_cold_v4_remote_push(small_page_v4* page, void* ptr, uint32_t tid);

core/box/smallobject_hotbox_v4_box.h

@@ -15,10 +15,14 @@
 #define SMALLOBJECT_NUM_CLASSES TINY_NUM_CLASSES
 #endif
 
-struct small_segment_v4;
+struct SmallSegment;  // Forward declaration, defined in smallsegment_v4_box.h
 
-// Page metadata for v4 HotBox
+// ============================================================================
-typedef struct small_page_v4 {
+// SmallObject v4 HotBox Type Definitions
+// ============================================================================
+
+// SmallPageMeta: Page metadata for v4 HotBox
+typedef struct SmallPageMeta {
     void* freelist;
     uint16_t used;
     uint16_t capacity;
@@ -26,29 +30,28 @@ typedef struct small_page_v4 {
     uint8_t flags;
     uint32_t block_size;
     uint8_t* base;
-    void* slab_ref;  // Superslab / lease token (box境界で扱う)
+    void* slab_ref;  // Superslab / lease token (box boundary)
-    struct small_segment_v4* segment;  // PF3: segment owner（NULLなら Tiny v1 経路）
+    struct SmallSegment* segment;  // Segment owner (NULL if Tiny v1 path)
-    struct small_page_v4* next;
+    struct SmallPageMeta* next;
-} small_page_v4;
+} SmallPageMeta;
 
-// Per-class heap state (current / partial / full lists)
+// SmallClassHeap: Per-class heap state (current / partial / full lists)
-typedef struct small_class_heap_v4 {
+typedef struct SmallClassHeap {
-    small_page_v4* current;
+    SmallPageMeta* current;
-    small_page_v4* partial_head;
+    SmallPageMeta* partial_head;
-    small_page_v4* full_head;
+    SmallPageMeta* full_head;
     uint32_t partial_count;
-} small_class_heap_v4;
+} SmallClassHeap;
 
-// TLS heap context (per-thread)
+// SmallHeapCtx: TLS heap context (per-thread)
-typedef struct small_heap_ctx_v4 {
+typedef struct SmallHeapCtx {
-    small_class_heap_v4 cls[SMALLOBJECT_NUM_CLASSES];
+    SmallClassHeap cls[SMALLOBJECT_NUM_CLASSES];
-} small_heap_ctx_v4;
+} SmallHeapCtx;
 
-// TLS accessor (実装は後続フェーズで追加)
+// Backward compatibility aliases (deprecated, use SmallXxx directly)
-// SmallPageMeta を external で使う場合のエイリアス
+typedef SmallPageMeta small_page_v4;
-typedef small_page_v4 SmallPageMeta;
+typedef SmallClassHeap small_class_heap_v4;
-typedef small_class_heap_v4 SmallClassHeap;
+typedef SmallHeapCtx small_heap_ctx_v4;
-typedef small_heap_ctx_v4 SmallHeapCtx;
 
 small_heap_ctx_v4* small_heap_ctx_v4_get(void);
 

core/box/smallsegment_v4_box.h

@@ -4,23 +4,29 @@
 
 #include <stdint.h>
 
-// Forward declaration for SmallPageMeta
+// Forward declaration
-struct small_page_v4;
+struct SmallPageMeta;
 
+// ============================================================================
 // SmallSegment: class_idx ごとに小さな segment を管理
-// 基本構造: base, page metadata array
+// ============================================================================
-typedef struct small_segment_v4 {
+
+typedef struct SmallSegment {
     uintptr_t base;           // Segment base address
     uint32_t num_pages;       // Number of pages in segment
     uint32_t owner_tid;       // Thread ID that owns this segment
     uint32_t magic;           // Magic number for validation
     // Page metadata array (flexible, actual size depends on SMALL_PAGE_SIZE / SMALL_SEGMENT_SIZE)
-    // struct small_page_v4* page_meta[];
+    // struct SmallPageMeta* page_meta[];
-} small_segment_v4;
+} SmallSegment;
 
-// API: Segment 取得・解放
+// Backward compatibility alias
-small_segment_v4* smallsegment_v4_acquire(int class_idx);
+typedef SmallSegment small_segment_v4;
-void smallsegment_v4_release_if_empty(small_segment_v4* seg, void* page, int class_idx);
 
-// API: ページメタデータの取得
+// ============================================================================
-struct small_page_v4* smallsegment_v4_page_meta_of(small_segment_v4* seg, void* ptr);
+// API: Segment Management
+// ============================================================================
+
+SmallSegment* smallsegment_v4_acquire(int class_idx);
+void smallsegment_v4_release_if_empty(SmallSegment* seg, void* page, int class_idx);
+struct SmallPageMeta* smallsegment_v4_page_meta_of(SmallSegment* seg, void* ptr);

core/smallobject_hotbox_v4.c

@@ -248,40 +248,24 @@ static void cold_retire_page_v4(small_heap_ctx_v4* hot_ctx, uint32_t class_idx,
     free(page);
 }
 
-static const SmallColdIfaceV4 g_cold_iface_v4 = {
+// Direct function implementations (phase v4-mid-0: cold_refill/retire を直接呼び出す)
-    .refill_page = cold_refill_page_v4,
-    .retire_page = cold_retire_page_v4,
-    .remote_push = NULL,
-    .remote_drain = NULL,
-};
-
-const SmallColdIfaceV4* small_cold_iface_v4_get(void) {
-    return &g_cold_iface_v4;
-}
-
-// Direct function stubs (phase v4-mid-0: delegates to iface)
 small_page_v4* small_cold_v4_refill_page(small_heap_ctx_v4* ctx, uint32_t class_idx) {
-    const SmallColdIfaceV4* iface = small_cold_iface_v4_get();
+    return cold_refill_page_v4(ctx, class_idx);
-    if (!iface || !iface->refill_page) return NULL;
-    return iface->refill_page(ctx, class_idx);
 }
 
 void small_cold_v4_retire_page(small_heap_ctx_v4* ctx, small_page_v4* page) {
-    const SmallColdIfaceV4* iface = small_cold_iface_v4_get();
+    if (!page) return;
-    if (!iface || !iface->retire_page || !page) return;
+    cold_retire_page_v4(ctx, (uint32_t)page->class_idx, page);
-    iface->retire_page(ctx, (uint32_t)page->class_idx, page);
 }
 
 bool small_cold_v4_remote_push(small_page_v4* page, void* ptr, uint32_t tid) {
-    const SmallColdIfaceV4* iface = small_cold_iface_v4_get();
+    (void)page; (void)ptr; (void)tid;
-    if (!iface || !iface->remote_push) return false;
+    return false;  // stub: not yet implemented
-    return iface->remote_push(page, ptr, tid);
 }
 
 void small_cold_v4_remote_drain(small_heap_ctx_v4* ctx) {
-    const SmallColdIfaceV4* iface = small_cold_iface_v4_get();
+    (void)ctx;
-    if (!iface || !iface->remote_drain) return;
+    // stub: not yet implemented
-    iface->remote_drain(ctx);
 }
 
 // Stub accessor for smallsegment_v4_page_meta_of
@@ -321,9 +305,8 @@ static small_page_v4* small_alloc_slow_v4(small_heap_ctx_v4* ctx, int class_idx)
         return from_partial;
     }
 
-    const SmallColdIfaceV4* cold = small_cold_iface_v4_get();
+    // Call direct Cold function (not vtable)
-    if (!cold || !cold->refill_page) return NULL;
+    small_page_v4* page = small_cold_v4_refill_page(ctx, (uint32_t)class_idx);
-    small_page_v4* page = cold->refill_page(ctx, (uint32_t)class_idx);
     if (!page) return NULL;
     h->current = page;
     return page;
@@ -400,7 +383,6 @@ void small_heap_free_fast_v4(small_heap_ctx_v4* ctx, int class_idx, void* ptr) {
     }
 
     if (page->used == 0) {
-        const SmallColdIfaceV4* cold = small_cold_iface_v4_get();
         if (loc != V4_LOC_CURRENT) {
             v4_unlink_from_list(h, loc, prev, page);
         }
@@ -417,11 +399,8 @@ void small_heap_free_fast_v4(small_heap_ctx_v4* ctx, int class_idx, void* ptr) {
             v4_page_push_partial(h, page);
             return;
         }
-        if (cold && cold->retire_page) {
+        // Call direct Cold function (not vtable)
-            cold->retire_page(ctx, (uint32_t)class_idx, page);
+        small_cold_v4_retire_page(ctx, page);
-        } else {
-            free(page);
-        }
         return;
     }
 

docs/analysis/ENV_CLEANUP_CANDIDATES.md

@@ -0,0 +1,137 @@
+# ENV Variable Cleanup Candidates
+
+**Date**: 2025-12-10
+**Status**: Documentation for code cleanup planning
+
+---
+
+## Summary
+
+This document lists environment variables that are candidates for cleanup, categorization, and potential removal. The analysis is based on current usage in bench profiles, default configurations, and implementation status.
+
+---
+
+## Categories
+
+### 1. KEEP: Core Production (Always ON by default)
+
+These ENVs control essential features that are ON by default in all standard profiles.
+
+| ENV | Default | Purpose | Status |
+|-----|---------|---------|--------|
+| `HAKMEM_TINY_FRONT_V3_ENABLED` | 1 | Front v3 fast path | CORE |
+| `HAKMEM_TINY_FRONT_V3_LUT_ENABLED` | 1 | Front v3 lookup table | CORE |
+| `HAKMEM_SMALL_HEAP_V3_ENABLED` | 1 | SmallObject HotBox v3 | CORE |
+| `HAKMEM_SMALL_HEAP_V3_CLASSES` | 0x80 | SmallObject v3 class mask (C7 by default) | CORE |
+| `HAKMEM_TINY_C7_ULTRA_ENABLED` | 1 | C7 ULTRA segment path | CORE |
+| `HAKMEM_POOL_V1_FLATTEN_ENABLED` | 0 | Pool v1 flatten fast path (OFF default) | SAFE |
+
+---
+
+### 2. RESEARCH: Experimental & Gate-able (OFF by default)
+
+These ENVs control alternative/experimental implementations. All are OFF by default, enabling opt-in for A/B testing.
+
+| ENV | Default | Purpose | Status | Notes |
+|-----|---------|---------|--------|-------|
+| `HAKMEM_SMALL_HEAP_V4_ENABLED` | 0 | SmallObject HotBox v4 (research) | RESEARCH | Phase v4-mid-0 onwards |
+| `HAKMEM_SMALL_HEAP_V4_CLASSES` | 0x0 | SmallObject v4 class mask | RESEARCH | Opt-in only |
+| `HAKMEM_TINY_HOTHEAP_V2` | 0 | TinyHotHeap v2 (research) | RESEARCH | Complete but disabled |
+| `HAKMEM_TINY_HOTHEAP_CLASSES` | 0x00 | TinyHotHeap class mask | RESEARCH | v2 only, OFF by default |
+| `HAKMEM_POOL_V2_ENABLED` | 0 | Pool HotBox v2 (research) | RESEARCH | Stub, not used |
+| `HAKMEM_POOL_V2_CLASSES` | 0x0 | Pool v2 class mask | RESEARCH | Unused |
+| `HAKMEM_SMALL_SEGMENT_V4_ENABLED` | 0 | SmallSegment v4 (research) | RESEARCH | Phase v4 onwards |
+| `HAKMEM_TINY_C7_ULTRA_HEADER_LIGHT` | 0 | C7 ULTRA header optimization (research) | RESEARCH | Experimental |
+
+---
+
+### 3. DELETE CANDIDATES: Dead/Obsolete Code
+
+These ENVs should be considered for removal (after confirming no active usage):
+
+| ENV | Status | Reason | Action |
+|-----|--------|--------|--------|
+| `HAKMEM_TINY_FRONT_V2` | OBSOLETE | Front v2 replaced by v3 | Consider deletion |
+| `HAKMEM_TINY_HEAP_V2` | RESEARCH-ONLY | Magazine variant, no perf gain | Keep as research |
+| `POOL_V2_*` (all) | STUB | Not fully implemented | Consider deletion |
+
+---
+
+### 4. CONFIGURATION: Profile-specific (Should not be user-editable)
+
+These ENVs are set by bench profiles and should not be manually edited:
+
+| ENV | Typical Value | Purpose |
+|-----|---------------|---------|
+| `HAKMEM_BENCH_MIN_SIZE` | 16 or 257 | Workload size range (bench only) |
+| `HAKMEM_BENCH_MAX_SIZE` | 1024 or 768 | Workload size range (bench only) |
+| `HAKMEM_PROFILE` | `MIXED_TINYV3_C7_SAFE` | Bench profile selection |
+| `HAKMEM_TINY_HEAP_PROFILE` | `C7_SAFE` | Tiny heap profile |
+
+---
+
+### 5. STATISTICS & DEBUG (Non-functional)
+
+These ENVs control measurement and debugging, not behavior:
+
+| ENV | Default | Purpose |
+|-----|---------|---------|
+| `HAKMEM_SMALL_HEAP_V3_STATS` | 0 | SmallObject v3 stats collection |
+| `HAKMEM_TINY_HOTHEAP_V2_STATS` | 0 | TinyHotHeap v2 stats collection |
+| `HAKMEM_SS_OS_STATS` | 0 | SuperSlab OS stats |
+| `HAKMEM_POOL_V1_FLATTEN_STATS` | 0 | Pool flatten stats |
+
+---
+
+## Recommended Action Plan
+
+### Phase 1: Immediate Documentation (Done)
+
+- [x] Categorize all active ENVs
+- [x] Document which are production vs. research
+- [x] Mark deletion candidates
+
+### Phase 2: Cleanup (Future)
+
+1. **Create `ENV_DEFAULTS.h`**: Consolidate default values
+2. **Deprecate dead code**: Mark `HAKMEM_TINY_FRONT_V2`, `POOL_V2_*` as obsolete
+3. **Organize env boxes**: Group by category
+   - `core/box/env/production_env_box.h` (KEEP)
+   - `core/box/env/research_env_box.h` (RESEARCH)
+   - `core/box/env/profile_env_box.h` (PROFILE)
+
+### Phase 3: Deletion (Later)
+
+- Confirm zero references to deprecated ENVs
+- Remove associated code (v2, pool_v2)
+- Update documentation
+
+---
+
+## Default Configuration (Current Standard)
+
+The `MIXED_TINYV3_C7_SAFE` profile (Mixed workload baseline) uses:
+
+```bash
+HAKMEM_BENCH_MIN_SIZE=16
+HAKMEM_BENCH_MAX_SIZE=1024
+HAKMEM_TINY_HEAP_PROFILE=C7_SAFE
+HAKMEM_TINY_C7_HOT=1
+HAKMEM_TINY_HOTHEAP_V2=0              # OFF
+HAKMEM_SMALL_HEAP_V3_ENABLED=1        # ON
+HAKMEM_SMALL_HEAP_V3_CLASSES=0x80     # C7-only
+HAKMEM_SMALL_HEAP_V4_ENABLED=0        # OFF (research)
+HAKMEM_POOL_V2_ENABLED=0              # OFF (research)
+HAKMEM_TINY_FRONT_V3_ENABLED=1        # ON
+HAKMEM_TINY_FRONT_V3_LUT_ENABLED=1    # ON
+HAKMEM_TINY_C7_ULTRA_ENABLED=1        # ON
+```
+
+---
+
+## Notes
+
+- **v2 code is complete and safe**: Not marked for deletion; remains as research/A/B testing infrastructure.
+- **v4 code is scaffolding**: Phase v4-mid-0 introduces type skeleton; later phases will add implementation.
+- **Research boxes are intentional**: Pool v2, TinyHeap v2, and v4 variants serve as design exploration layers.
+