hakmem/docs/analysis/ENV_CLEANUP_ANALYSIS.md

# HAKMEM ENV Variables - Comprehensive Cleanup Analysis
**Total Variables: 282 → Target: <50**

Generated: 2025年 11月 26日 水曜日 16:58:53 JST

## Executive Summary

| Category | Count | Percentage | Action |
|----------|-------|------------|--------|
| OBSOLETE | 54 | 19% | **REMOVE** (defunct features) |
| DEBUG | 59 | 21% | **GATE** (#if !HAKMEM_BUILD_RELEASE) |
| ESSENTIAL | 20 | 7% | **KEEP** (core functionality) |
| POLICY | 149 | 53% | **CONSOLIDATE** (reduce to ~30) |

**Reduction Path**: 282 → 113 (remove obsolete) → 54 (gate debug) → **~50** (consolidate policy)

---

## Category 1: OBSOLETE (54 vars - REMOVE)

These variables control removed/deprecated features and should be deleted:

### 1.1 Background Processing (BG) - 9 vars
**Status**: BG system removed in 2025-12 cleanup
```
HAKMEM_BATCH_BG
HAKMEM_L25_BG_DRAIN
HAKMEM_L25_BG_MS
```

**Note**: The following 2 Tiny BG vars were removed in commit 6b791b97d (2025-11-26):
```
HAKMEM_TINY_BG_REMOTE          (deleted)
HAKMEM_TINY_BG_REMOTE_BATCH    (deleted)
```

### 1.2 SFC (Shared Frontend Cache) - 7 vars
**Status**: SFC removed, replaced by UNIFIED_CACHE
```
HAKMEM_SFC_CAPACITY
HAKMEM_SFC_CASCADE_PCT
HAKMEM_SFC_DEBUG
HAKMEM_SFC_ENABLE
HAKMEM_SFC_REFILL_COUNT
HAKMEM_SFC_STATS_DUMP
HAKMEM_TINY_SFC_CASCADE
```

### 1.3 HotMag/UltraHot/Quick - 4 vars
**Status**: Experimental caches removed
```
HAKMEM_TINY_QUICK
HAKMEM_TINY_ULTRA
HAKMEM_TINY_ULTRA_VALIDATE
HAKMEM_TINY_ULTRA_SLIM
```

**Note**: The following 6 vars were removed in commit 6b791b97d (2025-11-26):
```
HAKMEM_TINY_ULTRA_FRONT        (deleted)
HAKMEM_TINY_ULTRA_L0           (deleted)
HAKMEM_TINY_ULTRA_HEAP_DUMP    (deleted)
HAKMEM_TINY_ULTRA_PAGE_DUMP    (deleted)
HAKMEM_TINY_BG_REMOTE          (deleted)
HAKMEM_TINY_BG_REMOTE_BATCH    (deleted)
```

### 1.4 Ring Cache - 4 vars
**Status**: Ring system removed
```
HAKMEM_L25_RING_TRIGGER
HAKMEM_POOL_TLS_RING
HAKMEM_RING_RETURN_DIV
HAKMEM_TINY_ALLOC_RING
HAKMEM_TINY_DUMP_RING_ATEXIT
HAKMEM_TINY_SLL_RING
HAKMEM_TINY_TRACE_RING
```

### 1.5 Thread Cache (TC) - 4 vars
**Status**: TC system deprecated
```
```

### 1.6 L25 BigCache - 8 vars
**Status**: BigCache system removed
```
HAKMEM_BIGCACHE_L25
HAKMEM_DISABLE_BIGCACHE
HAKMEM_L25_BG_DRAIN
HAKMEM_L25_BG_MS
HAKMEM_L25_RING_TRIGGER
HAKMEM_L25_TC_CAP
HAKMEM_L25_TC_SPILL
```

### 1.7 Frontend Experiments - 10 vars
**Status**: Experimental frontends (V2, Heap, Slim) removed
```
HAKMEM_TINY_FASTCACHE
HAKMEM_TINY_FRONTEND
HAKMEM_TINY_FRONT_DISABLE_HEAPV2
HAKMEM_TINY_FRONT_ENABLE_ULTRAHOT
HAKMEM_TINY_FRONT_SLIM
HAKMEM_TINY_FRONT_V2
HAKMEM_TINY_HEAP_V2_CLASS_MASK
HAKMEM_TINY_HEAP_V2_DEBUG
HAKMEM_TINY_HEAP_V2_LEFTOVER_MODE
HAKMEM_TINY_HEAP_V2_STATS
```

---

## Category 2: DEBUG_ONLY (59 vars - COMPILE-TIME GATE)

These should be gated with `#if !HAKMEM_BUILD_RELEASE` and removed from production:

### 2.1 Tracing/Logging - 20 vars
```
HAKMEM_ADAPTIVE_LOG
HAKMEM_EXTERNAL_GUARD_LOG
HAKMEM_FREE_ROUTE_TRACE
HAKMEM_FREE_WRAP_TRACE
HAKMEM_INVALID_FREE_LOG
HAKMEM_LOG_FILE
HAKMEM_PTR_TRACE_DUMP
HAKMEM_PTR_TRACE_VERBOSE
HAKMEM_SUPER_REG_REQTRACE
HAKMEM_TIMING
HAKMEM_TINY_MAILBOX_TRACE
HAKMEM_TINY_MAILBOX_TRACE_LIMIT
HAKMEM_TINY_RF_TRACE
HAKMEM_TINY_SUPERSLAB_TRACE
HAKMEM_TINY_TRACE_RING
HAKMEM_VERBOSE
```

### 2.2 Statistics/Profiling - 18 vars
```
HAKMEM_ACE_PROFILE
HAKMEM_ACE_SAMPLE
HAKMEM_EVO_SAMPLE
HAKMEM_EXTERNAL_GUARD_STATS
HAKMEM_HIST_SAMPLE
HAKMEM_INT_SAMPLE
HAKMEM_LEARN_SAMPLE
HAKMEM_POOL_COUNT_SAMPLE
HAKMEM_PROF
HAKMEM_PROF_SAMPLE
HAKMEM_ROUTE_SAMPLE_LG
HAKMEM_SFC_STATS_DUMP
HAKMEM_SHARED_POOL_LOCK_STATS
HAKMEM_SHARED_POOL_STAGE_STATS
HAKMEM_TINY_ALLOC_1024_METRIC
HAKMEM_TINY_COUNT_SAMPLE
HAKMEM_TINY_FAST_STATS
HAKMEM_TINY_FRONT_METRICS
```

### 2.3 Debug/Validation - 21 vars
```
HAKMEM_ACE_DEBUG
HAKMEM_ACE_OBSERVE
HAKMEM_DEBUG_SEGV
HAKMEM_EXTERNAL_GUARD_LOG
HAKMEM_EXTERNAL_GUARD_MINCORE
HAKMEM_EXTERNAL_GUARD_STATS
HAKMEM_PTR_TRACE_DUMP
HAKMEM_SFC_DEBUG
HAKMEM_SFC_STATS_DUMP
HAKMEM_SS_ACQUIRE_DEBUG
HAKMEM_SS_FREE_DEBUG
HAKMEM_SS_LRU_DEBUG
HAKMEM_SS_PREWARM_DEBUG
HAKMEM_SUPER_LOOKUP_DEBUG
HAKMEM_SUPER_REG_DEBUG
HAKMEM_TINY_ALLOC_DEBUG
HAKMEM_TINY_COUNTERS_DUMP
HAKMEM_TINY_DEBUG_FAST0
HAKMEM_TINY_DEBUG_REMOTE_GUARD
HAKMEM_TINY_DUMP_ATEXIT_ONLY
HAKMEM_TINY_DUMP_RING_ATEXIT
```

---

## Category 3: ESSENTIAL (20 vars - KEEP)

Core functionality that must remain:

### 3.1 Major Features (8 vars)
```
HAKMEM_TINY_UNIFIED_CACHE=1      # Phase 3d-B (default ON)
HAKMEM_SS_EMPTY_REUSE=1          # Phase 12-1.1 (default ON)
HAKMEM_FRONT_GATE_UNIFIED=1      # Phase 26 (default ON)
HAKMEM_WRAP_TINY=1               # Enable Tiny Pool
HAKMEM_TINY_USE_SUPERSLAB=1      # SuperSlab backend
HAKMEM_TINY_TLS_SLL=1            # TLS cache layer
HAKMEM_TINY_FREE_FAST=1          # Fast free path
HAKMEM_POOL_TLS_FREE=1           # Pool TLS free
```

### 3.2 Pool TLS Arena (3 vars)
```
HAKMEM_POOL_TLS_ARENA_MB_INIT=1  # Initial arena size
HAKMEM_POOL_TLS_ARENA_MB_MAX=8   # Max arena size
HAKMEM_POOL_TLS_ARENA_GROWTH_LEVELS=3  # Growth stages
```

### 3.3 Page Arena (5 vars)
```
HAKMEM_PAGE_ARENA_ENABLE=1       # Page arena system
HAKMEM_PAGE_ARENA_HOT_SIZE=...   # Hot size threshold
HAKMEM_PAGE_ARENA_WARM_64K=...   # Warm level 1
HAKMEM_PAGE_ARENA_WARM_128K=...  # Warm level 2
HAKMEM_PAGE_ARENA_WARM_2M=...    # Warm level 3
```

### 3.4 Misc Essential (4 vars)
```
HAKMEM_PREWARM_SUPERSLABS=1      # Phase 11 prewarm
HAKMEM_TINY_PREWARM_ALL=1        # Full prewarm
HAKMEM_WRAP_TINY_REFILL=1        # Wrapper refill
HAKMEM_SMALLMID_ENABLE=1         # SmallMid allocator
```

---

## Category 4: POLICY (149 vars - CONSOLIDATE to ~30)

### 4.1 Duplicate/Similar Functionality

#### Refill Parameters (18 vars → 3 vars)
**Current**:
```
HAKMEM_INT_ADAPT_REFILL
HAKMEM_SFC_REFILL_COUNT
HAKMEM_TINY_MID_REFILL_SIMPLE
HAKMEM_TINY_REFILL_COUNT
HAKMEM_TINY_REFILL_COUNT_HOT
HAKMEM_TINY_REFILL_COUNT_MID
HAKMEM_TINY_REFILL_DUMP
HAKMEM_TINY_REFILL_FAILFAST
HAKMEM_TINY_REFILL_MAX
HAKMEM_TINY_REFILL_MAX_HOT
HAKMEM_TINY_REFILL_ONE_ON_MISS
HAKMEM_TINY_REFILL_OPT_DEBUG
HAKMEM_WRAP_TINY_REFILL
```
**Proposal**: Consolidate to:
```
HAKMEM_TINY_REFILL_BATCH=64      # Default batch size
HAKMEM_TINY_REFILL_HOT_BATCH=192 # Hot class batch
HAKMEM_TINY_REFILL_MAX=1024      # Global max
```

#### Capacity Parameters (25 vars → 5 vars)
**Current**:
```
HAKMEM_CAP_LARGE
HAKMEM_CAP_MID
HAKMEM_CAP_MID_DYN1
HAKMEM_CAP_MID_DYN2
HAKMEM_L25_MIN_BUNDLE
HAKMEM_MF2_MAX_QUEUES
HAKMEM_POOL_MIN_BUNDLE
HAKMEM_SUPERSLAB_MAX_CACHED
HAKMEM_SUPERSLAB_MAX_MEMORY_MB
HAKMEM_TINY_MAX_CLASS
HAKMEM_TINY_REFILL_MAX_HOT
HAKMEM_TINY_SS_MAX_MB
HAKMEM_TINY_SS_MIN_MB
...(25 total)
```
**Proposal**: Use tiered approach:
```
HAKMEM_TINY_CACHE_SIZE=small|medium|large  # Preset
HAKMEM_MID_CACHE_SIZE=small|medium|large
HAKMEM_LARGE_CACHE_SIZE=small|medium|large
HAKMEM_SS_MEMORY_LIMIT_MB=512    # Global limit
HAKMEM_POOL_MEMORY_LIMIT_MB=256  # Pool limit
```

#### Learning/Adaptation (35 vars → 8 vars)
**Current**: ACE, INT, WMAX, THP, ELO, LEARN, ADAPTIVE, HOT, DYN systems
```
HAKMEM_ACE_DEBUG
HAKMEM_ACE_ENABLED
HAKMEM_ACE_OBSERVE
HAKMEM_ACE_PROFILE
HAKMEM_ACE_SAMPLE
HAKMEM_ADAPTIVE_LOG
HAKMEM_ADAPTIVE_SIZING
HAKMEM_CAP_MID_DYN1
HAKMEM_CAP_MID_DYN2
HAKMEM_DISABLE_ELO
HAKMEM_DYN1_AUTO
HAKMEM_DYN2_AUTO
HAKMEM_INT_ADAPT_CAPS
HAKMEM_INT_ADAPT_REFILL
HAKMEM_INT_ENGINE
...(35 total)
```
**Proposal**: Unified learning system:
```
HAKMEM_LEARN_MODE=off|observe|active     # Master switch
HAKMEM_LEARN_TARGETS=caps,refill,wmax    # What to tune
HAKMEM_LEARN_INTERVAL_MS=1000            # Update rate
HAKMEM_LEARN_AGGRESSIVENESS=0.1          # Tuning rate
HAKMEM_THP_POLICY=off|auto|on            # THP
HAKMEM_ADAPTIVE_CAPS=1                   # Enable cap adaptation
HAKMEM_ADAPTIVE_REFILL=1                 # Enable refill adaptation
HAKMEM_ADAPTIVE_WMAX=1                   # Enable wmax adaptation
```

#### Drain/Threshold Parameters (20 vars → 5 vars)
**Current**:
```
HAKMEM_L25_BG_DRAIN
HAKMEM_L25_RING_TRIGGER
HAKMEM_MF2_IDLE_THRESHOLD_US
HAKMEM_TC_DRAIN_MAX
HAKMEM_TC_DRAIN_TRIGGER
HAKMEM_TINY_DRAIN_TO_SLL
HAKMEM_TINY_REMOTE_DRAIN_THRESHOLD
HAKMEM_TINY_REMOTE_DRAIN_TRYRATE
HAKMEM_TINY_SLL_DRAIN_DEBUG
HAKMEM_TINY_SLL_DRAIN_ENABLE
HAKMEM_TINY_SLL_DRAIN_INTERVAL
HAKMEM_TINY_TENSION_DRAIN_ENABLE
HAKMEM_TINY_TENSION_DRAIN_THRESHOLD
...(20 total)
```
**Proposal**: Unified thresholds:
```
HAKMEM_REMOTE_DRAIN_THRESHOLD=32   # When to drain
HAKMEM_REMOTE_DRAIN_BATCH=16       # Drain batch size
HAKMEM_SPILL_THRESHOLD_PCT=90      # Cache spill %
HAKMEM_TRIM_INTERVAL_MS=1000       # Memory trim rate
HAKMEM_IDLE_TIMEOUT_MS=5000        # Idle detection
```

### 4.2 Recommended Consolidation Summary

| Area | Current | Proposed | Reduction |
|------|---------|----------|-----------|
| Refill params | 18 | 3 | -83% |
| Capacity params | 25 | 5 | -80% |
| Learning/Adapt | 35 | 8 | -77% |
| Drain/Threshold | 20 | 5 | -75% |
| L25/Pool config | 15 | 5 | -67% |
| Misc policy | 36 | 4 | -89% |
| **TOTAL** | **149** | **30** | **-80%** |

---

## Final Reduction Path

```
Step 1: Remove OBSOLETE             282 → 228 (-54)
Step 2: Gate DEBUG with #if         228 → 169 (-59)
Step 3: Keep ESSENTIAL as-is        169 → 149 (-20)
Step 4: Consolidate POLICY          149 → 30  (-119)

FINAL COUNT: 20 (essential) + 30 (policy) = 50 variables
```

---

## Top Removal Candidates (By Priority)

### Priority 1: Dead Code (Immediate Removal) - 54 vars

**BG System** (11 vars):
```
HAKMEM_L25_BG_DRAIN
HAKMEM_L25_BG_MS
```

**SFC System** (7 vars):
```
HAKMEM_SFC_CAPACITY
HAKMEM_SFC_CASCADE_PCT
HAKMEM_SFC_DEBUG
HAKMEM_SFC_ENABLE
HAKMEM_SFC_REFILL_COUNT
HAKMEM_SFC_STATS_DUMP
HAKMEM_TINY_SFC_CASCADE
```

**Experimental Caches** (4 vars):
```
HAKMEM_TINY_QUICK
HAKMEM_TINY_ULTRA
HAKMEM_TINY_ULTRA_VALIDATE
HAKMEM_TINY_ULTRA_SLIM
```

**Note**: 6 Ultra/BG vars removed in commit 6b791b97d (see section 1.3 above)

**Ring/TC/Frontend** (18 vars):
```
HAKMEM_L25_RING_TRIGGER
HAKMEM_L25_TC_CAP
HAKMEM_L25_TC_SPILL
HAKMEM_MID_TC_CAP
HAKMEM_POOL_TLS_RING
HAKMEM_RING_RETURN_DIV
HAKMEM_TC_DRAIN_MAX
HAKMEM_TC_DRAIN_TRIGGER
HAKMEM_TC_ENABLE
HAKMEM_TC_UNBOUNDED
HAKMEM_TINY_ALLOC_RING
HAKMEM_TINY_DUMP_RING_ATEXIT
HAKMEM_TINY_FASTCACHE
HAKMEM_TINY_FRONT_V2
HAKMEM_TINY_HEAP_V2_CLASS_MASK
HAKMEM_TINY_HEAP_V2_DEBUG
HAKMEM_TINY_HEAP_V2_LEFTOVER_MODE
HAKMEM_TINY_HEAP_V2_STATS
```

### Priority 2: Debug Gate (Next Phase) - 59 vars

Move to `#if !HAKMEM_BUILD_RELEASE` block:
```
HAKMEM_ACE_DEBUG
HAKMEM_ACE_OBSERVE
HAKMEM_ACE_PROFILE
HAKMEM_ADAPTIVE_LOG
HAKMEM_DEBUG_SEGV
HAKMEM_EXTERNAL_GUARD_LOG
HAKMEM_EXTERNAL_GUARD_MINCORE
HAKMEM_EXTERNAL_GUARD_STATS
HAKMEM_FREE_ROUTE_TRACE
HAKMEM_FREE_WRAP_TRACE
HAKMEM_INVALID_FREE_LOG
HAKMEM_LOG_FILE
HAKMEM_PROF
HAKMEM_PROF_SAMPLE
HAKMEM_PTR_TRACE_DUMP
HAKMEM_PTR_TRACE_VERBOSE
HAKMEM_SFC_DEBUG
HAKMEM_SFC_STATS_DUMP
HAKMEM_SHARED_POOL_LOCK_STATS
HAKMEM_SHARED_POOL_STAGE_STATS
HAKMEM_SS_ACQUIRE_DEBUG
HAKMEM_SS_FREE_DEBUG
HAKMEM_SS_LRU_DEBUG
HAKMEM_SS_PREWARM_DEBUG
HAKMEM_SUPER_LOOKUP_DEBUG
HAKMEM_SUPER_REG_DEBUG
HAKMEM_SUPER_REG_REQTRACE
HAKMEM_TINY_ALLOC_DEBUG
HAKMEM_TINY_COUNTERS_DUMP
HAKMEM_TINY_DEBUG_FAST0
...(59 total)
```

### Priority 3: Policy Consolidation (Final Phase) - 119 vars

**High-impact consolidation targets**:

1. **Per-class overrides** (30+ vars): Remove HAKMEM_TINY_*_C{0..7}, use class-agnostic tuning
2. **Learning systems** (35 vars): Unify ACE/INT/WMAX/ELO into HAKMEM_LEARN_*
3. **Capacity limits** (25 vars): Use tiered presets (small/medium/large)
4. **Drain thresholds** (20 vars): Unify under HAKMEM_DRAIN_* namespace

---

## Undocumented Variables

Variables in code but not in ENV_VARS.md:
```
(Run: comm -13 <(grep -o 'HAKMEM_[A-Z_0-9]*' ENV_VARS.md | sort -u) <(grep -rh 'getenv("HAKMEM_' core/ | grep -o 'HAKMEM_[A-Z_0-9]*' | sort -u))
```

---

## Recommended Actions

### Phase 1: Remove OBSOLETE (Week 1)
- [ ] Remove all BG system ENV vars (11 vars)
- [ ] Remove all SFC system ENV vars (7 vars)
- [ ] Remove HotMag/Ultra/Quick ENV vars (10 vars)
- [ ] Remove Ring/TC ENV vars (8 vars)
- [ ] Remove experimental frontend ENV vars (18 vars)
- [ ] **Result**: 282 → 228 vars (-19%)

### Phase 2: Gate DEBUG (Week 2)
- [ ] Create `core/hakmem_debug_env.h` with #if !HAKMEM_BUILD_RELEASE
- [ ] Move all *_DEBUG, *_TRACE, *_STATS, *_DUMP vars
- [ ] Move all *_LOG, *_PROF, *_OBSERVE vars
- [ ] Update build.sh to strip debug ENV in release
- [ ] **Result**: 228 → 169 vars (-21% production)

### Phase 3: Consolidate POLICY (Week 3-4)
- [ ] Consolidate REFILL_* params (18 → 3)
- [ ] Consolidate CAP_/MAX_/MIN_ params (25 → 5)
- [ ] Unify learning systems (35 → 8)
- [ ] Consolidate drain thresholds (20 → 5)
- [ ] Simplify L25/Pool config (15 → 5)
- [ ] Merge misc policy vars (36 → 4)
- [ ] **Result**: 169 → 50 vars (-82% total)

### Phase 4: Document & Test (Week 5)
- [ ] Update ENV_VARS.md with final 50 vars
- [ ] Create ENV_MIGRATION_GUIDE.md for old→new mapping
- [ ] Add ENV validation warnings for removed vars
- [ ] Regression test all 50 vars
- [ ] Update CLAUDE.md with new ENV list