hakmem/docs/analysis/ENV_CONSOLIDATION_PLAN.md

# HAKMEM ENV Variable Consolidation - Detailed Mapping

## OBSOLETE Variables - Complete List (54 vars)

### BG (Background) System - 11 vars
```
HAKMEM_BATCH_BG
HAKMEM_L25_BG_DRAIN
HAKMEM_L25_BG_MS
```

### SFC (Shared Frontend Cache) - 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
```

### HotMag/Ultra/Quick Caches - 12 vars
```
HAKMEM_TINY_FRONT_ENABLE_ULTRAHOT
HAKMEM_TINY_QUICK
HAKMEM_TINY_ULTRA
HAKMEM_TINY_ULTRA_DEBUG
HAKMEM_TINY_ULTRA_FRONT
HAKMEM_TINY_ULTRA_HEAP_DUMP
HAKMEM_TINY_ULTRA_L0
HAKMEM_TINY_ULTRA_PAGE_DUMP
HAKMEM_TINY_ULTRA_SIMPLE
HAKMEM_TINY_ULTRA_SLIM
HAKMEM_TINY_ULTRA_VALIDATE
HAKMEM_ULTRA_SLIM_STATS
```

### Ring System - 7 vars
```
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
```

### Thread Cache (TC) - 4 vars
```
```

### BigCache/L25 Experiments - 7 vars
```
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
```

### Frontend Experiments - 13 vars
```
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
```

---

## DEBUG Variables - Complete List (59 vars)

### Tracing - 16 vars
```
HAKMEM_FREE_ROUTE_TRACE
HAKMEM_FREE_WRAP_TRACE
HAKMEM_PTR_TRACE_DUMP
HAKMEM_PTR_TRACE_VERBOSE
HAKMEM_SUPER_REG_REQTRACE
HAKMEM_TINY_MAILBOX_TRACE
HAKMEM_TINY_MAILBOX_TRACE_LIMIT
HAKMEM_TINY_RF_TRACE
HAKMEM_TINY_SUPERSLAB_TRACE
HAKMEM_TINY_TRACE_RING
```

### Logging - 8 vars
```
HAKMEM_ADAPTIVE_LOG
HAKMEM_EXTERNAL_GUARD_LOG
HAKMEM_INVALID_FREE_LOG
HAKMEM_LOG_FILE
HAKMEM_PTR_TRACE_VERBOSE
HAKMEM_VERBOSE
```

### Stats/Profiling - 16 vars
```
HAKMEM_EXTERNAL_GUARD_STATS
HAKMEM_POOL_COUNT_SAMPLE
HAKMEM_PROF_SAMPLE
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
HAKMEM_TINY_HEAP_V2_STATS
HAKMEM_ULTRA_SLIM_STATS
```

### Debug/Observe - 19 vars
```
HAKMEM_ACE_DEBUG
HAKMEM_ACE_OBSERVE
HAKMEM_DEBUG_SEGV
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
HAKMEM_TINY_FAST_DEBUG
HAKMEM_TINY_FAST_DEBUG_MAX
```

---

## POLICY Variables - Consolidation Proposals

### Proposal 1: Refill Parameters

**Remove (18 vars)**:
```
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
```

**Replace with (3 vars)**:
```
HAKMEM_REFILL_BATCH=64           # Default refill batch size
HAKMEM_REFILL_HOT_BATCH=192      # Hot class (C0-C3) batch size
HAKMEM_REFILL_MAX=1024           # Maximum refill per operation
```

### Proposal 2: Capacity Limits

**Remove (30+ vars including per-class)**:
```
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_MAG_CAP
HAKMEM_TINY_MAX_CLASS
HAKMEM_TINY_REFILL_MAX_HOT
HAKMEM_TINY_SS_MAX_MB
HAKMEM_TINY_SS_MIN_MB
...(30+ total)
```

**Replace with (6 vars)**:
```
HAKMEM_CACHE_PRESET=small|medium|large|custom  # Global preset
HAKMEM_TINY_CACHE_SLOTS=512      # TLS cache capacity (if custom)
HAKMEM_MID_CACHE_SLOTS=128       # Mid-tier cache (if custom)
HAKMEM_LARGE_CACHE_SLOTS=32      # Large-tier cache (if custom)
HAKMEM_SS_MEMORY_LIMIT_MB=512    # SuperSlab memory cap
HAKMEM_POOL_MEMORY_LIMIT_MB=256  # Pool memory cap
```

**Presets**:
```
small:  Tiny=256,  Mid=64,  Large=16,  SS=256MB,  Pool=128MB
medium: Tiny=512,  Mid=128, Large=32,  SS=512MB,  Pool=256MB  (default)
large:  Tiny=1024, Mid=256, Large=64,  SS=1024MB, Pool=512MB
custom: Use individual *_SLOTS/*_LIMIT_MB vars
```

### Proposal 3: Learning/Adaptation Systems

**Remove (35 vars)**:
```
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_HOT_SLOT
HAKMEM_INT_ADAPT_CAPS
HAKMEM_INT_ADAPT_REFILL
HAKMEM_INT_ENGINE
HAKMEM_INT_EVENT_TS
HAKMEM_INT_SAMPLE
HAKMEM_LEARN
HAKMEM_LEARN_SAMPLE
HAKMEM_MID_DYN1
HAKMEM_MID_DYN2
HAKMEM_PTR_TRACE_DUMP
HAKMEM_PTR_TRACE_VERBOSE
HAKMEM_THP_LEARN
...(35 total)
```

**Replace with (8 vars)**:
```
HAKMEM_ADAPTIVE_MODE=off|observe|active  # Master switch
HAKMEM_ADAPTIVE_TARGETS=caps,refill,wmax,thp  # Comma-separated targets
HAKMEM_ADAPTIVE_INTERVAL_MS=1000        # Update interval
HAKMEM_ADAPTIVE_AGGRESSIVENESS=0.1      # Learning rate (0.0-1.0)
HAKMEM_ADAPTIVE_MIN_CHANGE_PCT=5        # Minimum % change to apply
HAKMEM_THP_POLICY=off|auto|on           # THP policy
HAKMEM_WMAX_MID_KB=256                  # Mid-tier working set
HAKMEM_WMAX_LARGE_KB=2048               # Large-tier working set
```

### Proposal 4: Drain/Threshold Parameters

**Remove (20 vars)**:
```
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
```

**Replace with (5 vars)**:
```
HAKMEM_REMOTE_DRAIN_THRESHOLD=32   # Queue size to trigger drain
HAKMEM_REMOTE_DRAIN_BATCH=16       # Items per drain operation
HAKMEM_CACHE_SPILL_PCT=90          # % full to trigger spill
HAKMEM_MEMORY_TRIM_INTERVAL_MS=1000  # Trim check interval
HAKMEM_IDLE_TIMEOUT_MS=5000        # Idle detection timeout
```

### Proposal 5: L25/Pool Configuration

**Remove (15 vars)**:
```
HAKMEM_L25_DZ
HAKMEM_L25_INBOUND_SLOTS
HAKMEM_L25_MIN_BUNDLE
HAKMEM_L25_OWNER_INBOUND
HAKMEM_L25_PREF
HAKMEM_L25_REMOTE_SAFE
HAKMEM_L25_RUN_BLOCKS
HAKMEM_L25_RUN_FACTOR
HAKMEM_MID_TC
HAKMEM_POOL_MIN_BUNDLE
HAKMEM_SHARED_POOL_LOCK_STATS
HAKMEM_SHARED_POOL_STAGE_STATS
```

**Replace with (5 vars)**:
```
HAKMEM_L25_SIZE_ZONES="64,256,1024"    # Comma-separated size zones
HAKMEM_L25_BUNDLE_SIZE=4              # Refill bundle size
HAKMEM_MID_BUNDLE_SIZE=4              # Mid-tier bundle size
HAKMEM_L25_RUN_BLOCKS=16              # Blocks per run
HAKMEM_L25_RUN_FACTOR=2               # Run factor multiplier
```

### Proposal 6: Misc Policy Variables

**Remove (36 vars)**:
```
HAKMEM_ACE_ENABLED
HAKMEM_ALLOW_MALLOC_FALLBACK
HAKMEM_BENCH_FAST_FRONT
HAKMEM_BENCH_FAST_MODE
HAKMEM_BENCH_TINY_ONLY
HAKMEM_BIGCACHE_L25
HAKMEM_DISABLE_BATCH
HAKMEM_DISABLE_BIGCACHE
HAKMEM_DISABLE_ELO
HAKMEM_EXTERNAL_GUARD_LOG
HAKMEM_EXTERNAL_GUARD_MINCORE
HAKMEM_EXTERNAL_GUARD_STATS
HAKMEM_FREE_POLICY
HAKMEM_FREE_ROUTE_TRACE
HAKMEM_HDR_LIGHT
HAKMEM_INVALID_FREE
HAKMEM_INVALID_FREE_LOG
HAKMEM_L25_REMOTE_SAFE
HAKMEM_L25_TC_SPILL
HAKMEM_LD_BLOCK_JEMALLOC
HAKMEM_LD_SAFE
HAKMEM_MF2_ENABLE
HAKMEM_MF2_IDLE_THRESHOLD_US
HAKMEM_MF2_LEASE_MS
HAKMEM_MF2_MAX_QUEUES
HAKMEM_MODE
HAKMEM_PAGE_ARENA_ENABLE
HAKMEM_PRESET
HAKMEM_ROUTE
HAKMEM_ROUTE_SAMPLE_LG
...(36 total)
```

**Replace with (4 vars)**:
```
HAKMEM_MODE=fast|balanced|learning|minimal  # High-level preset
HAKMEM_FORCE_LIBC=0|1              # Force libc malloc fallback
HAKMEM_THP_POLICY=off|auto|on      # THP policy (from Proposal 3)
HAKMEM_RSS_BUDGET_KB=unlimited     # Total RSS budget
```

---

## Final 50 Variables (20 Essential + 30 Policy)

### Essential (20 vars)
```
# Core Features (8)
HAKMEM_WRAP_TINY=1
HAKMEM_TINY_USE_SUPERSLAB=1
HAKMEM_TINY_TLS_SLL=1
HAKMEM_TINY_FREE_FAST=1
HAKMEM_TINY_UNIFIED_CACHE=1
HAKMEM_SS_EMPTY_REUSE=1
HAKMEM_FRONT_GATE_UNIFIED=1
HAKMEM_POOL_TLS_FREE=1

# Pool TLS Arena (3)
HAKMEM_POOL_TLS_ARENA_MB_INIT=1
HAKMEM_POOL_TLS_ARENA_MB_MAX=8
HAKMEM_POOL_TLS_ARENA_GROWTH_LEVELS=3

# Page Arena (5)
HAKMEM_PAGE_ARENA_ENABLE=1
HAKMEM_PAGE_ARENA_HOT_SIZE=...
HAKMEM_PAGE_ARENA_WARM_64K=...
HAKMEM_PAGE_ARENA_WARM_128K=...
HAKMEM_PAGE_ARENA_WARM_2M=...

# Misc (4)
HAKMEM_PREWARM_SUPERSLABS=1
HAKMEM_TINY_PREWARM_ALL=1
HAKMEM_WRAP_TINY_REFILL=1
HAKMEM_SMALLMID_ENABLE=1
```

### Policy (30 vars)
```
# Refill (3)
HAKMEM_REFILL_BATCH=64
HAKMEM_REFILL_HOT_BATCH=192
HAKMEM_REFILL_MAX=1024

# Capacity (6)
HAKMEM_CACHE_PRESET=medium
HAKMEM_TINY_CACHE_SLOTS=512
HAKMEM_MID_CACHE_SLOTS=128
HAKMEM_LARGE_CACHE_SLOTS=32
HAKMEM_SS_MEMORY_LIMIT_MB=512
HAKMEM_POOL_MEMORY_LIMIT_MB=256

# Adaptive (8)
HAKMEM_ADAPTIVE_MODE=off
HAKMEM_ADAPTIVE_TARGETS=caps,refill,wmax
HAKMEM_ADAPTIVE_INTERVAL_MS=1000
HAKMEM_ADAPTIVE_AGGRESSIVENESS=0.1
HAKMEM_ADAPTIVE_MIN_CHANGE_PCT=5
HAKMEM_THP_POLICY=auto
HAKMEM_WMAX_MID_KB=256
HAKMEM_WMAX_LARGE_KB=2048

# Drain/Threshold (5)
HAKMEM_REMOTE_DRAIN_THRESHOLD=32
HAKMEM_REMOTE_DRAIN_BATCH=16
HAKMEM_CACHE_SPILL_PCT=90
HAKMEM_MEMORY_TRIM_INTERVAL_MS=1000
HAKMEM_IDLE_TIMEOUT_MS=5000

# L25/Pool (5)
HAKMEM_L25_SIZE_ZONES=64,256,1024
HAKMEM_L25_BUNDLE_SIZE=4
HAKMEM_MID_BUNDLE_SIZE=4
HAKMEM_L25_RUN_BLOCKS=16
HAKMEM_L25_RUN_FACTOR=2

# Global (3)
HAKMEM_MODE=balanced
HAKMEM_FORCE_LIBC=0
HAKMEM_RSS_BUDGET_KB=unlimited
```

---

## Migration Guide Examples

### Example 1: Refill Migration
```bash
# OLD (18 vars)
export HAKMEM_TINY_REFILL_MAX=64
export HAKMEM_TINY_REFILL_MAX_HOT=192
export HAKMEM_TINY_REFILL_COUNT=32
export HAKMEM_TINY_REFILL_COUNT_HOT=96
export HAKMEM_TINY_REFILL_COUNT_MID=48
# ... 13 more ...

# NEW (3 vars)
export HAKMEM_REFILL_BATCH=64          # Replaces *_COUNT
export HAKMEM_REFILL_HOT_BATCH=192     # Replaces *_HOT
export HAKMEM_REFILL_MAX=1024          # Replaces *_MAX
```

### Example 2: Capacity Migration
```bash
# OLD (30+ vars)
export HAKMEM_TINY_MAG_CAP=512
export HAKMEM_TINY_MAG_CAP_C0=256
export HAKMEM_TINY_MAG_CAP_C1=256
# ... 27 more ...

# NEW (1 var for most cases)
export HAKMEM_CACHE_PRESET=medium      # Tiny=512, Mid=128, Large=32

# OR (6 vars for custom)
export HAKMEM_CACHE_PRESET=custom
export HAKMEM_TINY_CACHE_SLOTS=512
export HAKMEM_MID_CACHE_SLOTS=128
export HAKMEM_LARGE_CACHE_SLOTS=32
export HAKMEM_SS_MEMORY_LIMIT_MB=512
export HAKMEM_POOL_MEMORY_LIMIT_MB=256
```

### Example 3: Learning Migration
```bash
# OLD (35 vars)
export HAKMEM_ACE_ENABLED=1
export HAKMEM_INT_ENGINE=1
export HAKMEM_INT_ADAPT_REFILL=1
export HAKMEM_INT_ADAPT_CAPS=1
export HAKMEM_WMAX_LEARN=1
# ... 30 more ...

# NEW (4 vars for most cases)
export HAKMEM_ADAPTIVE_MODE=active
export HAKMEM_ADAPTIVE_TARGETS=caps,refill,wmax
export HAKMEM_ADAPTIVE_INTERVAL_MS=1000
export HAKMEM_ADAPTIVE_AGGRESSIVENESS=0.1
```