hakmem/docs/analysis/ENV_CLEANUP_CANDIDATES.md

# 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.