hakmem/docs/analysis/ENV_QUICK_REFERENCE.md

# ENV Cleanup Quick Reference Card

## ✅ SAFE TO REMOVE NOW (1 var)

### HAKMEM_TINY_FRONT_ENABLE_ULTRAHOT
**Status**: UltraHot feature completely removed in commit bcfb4f6b5
**File**: core/box/front_metrics_box.h:149
**Action**: Delete lines 148-152 (getenv check + usage)
**Risk**: ZERO - Feature doesn't exist anymore

```diff
File: core/box/front_metrics_box.h
-        const char* env = getenv("HAKMEM_TINY_FRONT_ENABLE_ULTRAHOT");
-        if (env && atoi(env) != 0) {
-            g_tiny_front_enable_ultrahot = 1;
-        }
```

---

## 🔧 LOW HANGING FRUIT (Deduplication)

### SFC_DEBUG - Called 4x, Should Be 1x

**Problem**: Same ENV var checked in 4 different files
**Solution**: Single global variable

**Step 1**: Add to core/hakmem_tiny_sfc.c (line ~36)
```c
int g_sfc_enabled = 1;
int g_sfc_debug = 0;  // ADD THIS
```

**Step 2**: Update init in core/hakmem_tiny_sfc.c (keep line 123):
```c
if (env_debug && *env_debug && *env_debug != '0') {
    g_sfc_debug = 1;  // Set global once
    fprintf(stderr, "...
```

**Step 3**: Replace in 3 files:

```diff
File: core/tiny_alloc_fast_sfc.inc.h:114
-            free_debug_enabled = getenv("HAKMEM_SFC_DEBUG") ? 1 : 0;
+            extern int g_sfc_debug;
+            free_debug_enabled = g_sfc_debug;

File: core/tiny_free_fast.inc.h:104
-        free_ss_debug_enabled = getenv("HAKMEM_SFC_DEBUG") ? 1 : 0;
+        extern int g_sfc_debug;
+        free_ss_debug_enabled = g_sfc_debug;

File: core/box/hak_wrappers.inc.h:89
-        debug_enabled = (getenv("HAKMEM_SFC_DEBUG") != NULL) ? 1 : 0;
+        extern int g_sfc_debug;
+        debug_enabled = g_sfc_debug;
```

**Savings**: -3 getenv() calls on hot paths
**Risk**: ZERO
**Impact**: 4 files, ~10 lines total

---

## ⚠️ NEED VERIFICATION (21 vars)

### Ask Maintainer/User:

#### 1. Ultra Features (3 vars) - Experimental or Dead?
```
HAKMEM_TINY_ULTRA_SLIM           core/box/ultra_slim_alloc_box.h
HAKMEM_ULTRA_SLIM_STATS          core/box/ultra_slim_alloc_box.h
HAKMEM_TINY_ULTRA_DEBUG          core/box/hak_core_init.inc.h
```
**Question**: Are Ultra features still being developed/used?

**Note**: The following 4 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)
```

#### 2. Heap V2 (7 vars) - Active or Replaced?
```
HAKMEM_TINY_HEAP_V2_CLASS_MASK   core/front/tiny_heap_v2.h
HAKMEM_TINY_HEAP_V2_LEFTOVER_MODE core/front/tiny_heap_v2.h
HAKMEM_TINY_HEAP_V2_DEBUG        core/front/tiny_heap_v2.h
HAKMEM_TINY_HEAP_V2_STATS        core/tiny_alloc_fast.inc.h
HAKMEM_TINY_FRONT_V2             core/tiny_alloc_fast.inc.h
HAKMEM_TINY_FRONT_SLIM           core/tiny_alloc_fast.inc.h
HAKMEM_TINY_FRONT_DISABLE_HEAPV2 core/box/front_metrics_box.h
```
**Question**: Is Heap V2 frontend still used or replaced by newer code?

#### 3. BG System (3 vars) - Keep or Deprecate?
```
HAKMEM_BATCH_BG                  core/hakmem_batch.c (g_bg_enabled=1)
HAKMEM_L25_BG_DRAIN              core/hakmem_l25_pool.c
HAKMEM_L25_BG_MS                 core/hakmem_l25_pool.c
```
**Question**: Is background drain still needed or deprecated?

**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)
```

#### 4. HotMag/SmallMag (1 var) - Used?
```
HAKMEM_TINY_SMALL_MAG            core/hakmem_tiny_smallmag.inc.h
```
**Question**: Is SmallMag still in use? (File exists, no getenv found for HotMag)

#### 5. Ring/Debug (3 vars) - Needed?
```
HAKMEM_TINY_SLL_RING             core/box/tls_sll_box.h
HAKMEM_TINY_TRACE_RING           core/tiny_debug_ring.c
HAKMEM_TINY_DUMP_RING_ATEXIT    core/tiny_debug_ring.c
```
**Question**: Are Tiny SLL ring and debug ring different from L25 TLS ring?

---

## ✅ DEFINITELY KEEP (Active Features)

### SFC - Shared Frontend Cache (6 vars) ✅
- Default: ON (`g_sfc_enabled = 1`)
- Compiled: hakmem_tiny_sfc.o in all binaries
- Vars: HAKMEM_SFC_ENABLE, CAPACITY, REFILL_COUNT, DEBUG, STATS_DUMP, CASCADE_PCT

### TC - Thread Cache for Pool/L25 (10 vars) ✅
- Active for L25 and Pool allocations
- Vars: HAKMEM_L25_TC_*, HAKMEM_MID_TC_*, HAKMEM_TC_*

### L25 TLS Ring (3 vars) ✅
- Active in L25 pool
- Vars: HAKMEM_POOL_TLS_RING, HAKMEM_RING_RETURN_DIV, HAKMEM_L25_RING_TRIGGER

### BigCache (1 var) ✅
- Compiled: hakmem_bigcache.o
- Var: HAKMEM_BIGCACHE_L25

**Total KEEP**: 20 vars

---

## 📊 Summary Stats

| Category | Count | Action |
|----------|-------|--------|
| Safe to remove | 1 | Delete ULTRAHOT toggle |
| Deduplication | 4 | SFC_DEBUG consolidation |
| Need verification | 21 | Ask maintainer |
| Definitely keep | 20 | No action |
| Already removed | 11 | ✅ Done |
| **TOTAL** | **57** | |

**Current ENV vars**: 221
**Potential reduction**: 1-22 vars (0.5%-10%)

---

## 🚀 Execution Order

1. **Today**: Remove HAKMEM_TINY_FRONT_ENABLE_ULTRAHOT (1 line, zero risk)
2. **This week**: Deduplicate SFC_DEBUG (4 files, low risk)
3. **Next sprint**: Verify 21 experimental vars with maintainer
4. **Next release**: Deprecate confirmed obsolete vars (doc + warnings)
5. **Future release**: Remove deprecated vars after 3-release cycle

---

## 📂 Files to Modify (Immediate Actions)

### Priority 1: ULTRAHOT Removal
- core/box/front_metrics_box.h (lines 148-152)

### Priority 2: SFC_DEBUG Dedup
- core/hakmem_tiny_sfc.c (add global, ~2 lines)
- core/tiny_alloc_fast_sfc.inc.h (change to extern, ~2 lines)
- core/tiny_free_fast.inc.h (change to extern, ~2 lines)
- core/box/hak_wrappers.inc.h (change to extern, ~2 lines)

**Total: 5 files, ~10 lines of changes**

---

## 🔍 Verification Template

For each experimental feature, check:

```bash
# 1. Is it compiled?
ls -la out/release/*.o | grep <feature>

# 2. Is it used in benchmarks?
grep -r "HAKMEM_<FEATURE>" scripts/ apps/ bench/

# 3. Default value?
grep -r "g_<feature>_enabled.*=" core/ --include="*.c"

# 4. Last commit?
git log --all --oneline --grep="<feature>" | head -5
```

If all NO → mark as OBSOLETE candidate