# Debug Environment Variables Consolidation

**Date:** 2025-11-29
**Status:** Phase 1 Complete (4 vars consolidated)
**Total Survey:** 43+ debug/trace/log environment variables

---

## Summary

Successfully consolidated 4 new debug environment variables added during bug fixes
into the existing `HAKMEM_DEBUG_LEVEL` system (expanded to 0-5 levels).

### Impact
- **Before:** 43+ individual debug environment variables
- **After (Phase 1):** 4 consolidated to HAKMEM_DEBUG_LEVEL
- **Target (Future):** Consolidate 30+ more variables

---

## Unified Debug Level System

### Level Definitions

```
HAKMEM_DEBUG_LEVEL=<0-5>

0 = OFF       Production mode (all debug disabled)
1 = ERROR     Critical errors only
2 = WARN      Warnings + errors
3 = INFO      Allocation paths, header validation, stats
4 = DEBUG     Guard instrumentation, failfast
5 = TRACE     Verbose tracing (all debug output)
```

### Usage Examples

```bash
# Production (default)
HAKMEM_DEBUG_LEVEL=0 ./larson_hakmem ...

# Enable allocation path tracking + header validation
HAKMEM_DEBUG_LEVEL=3 ./larson_hakmem ...

# Enable all debug features including guard/failfast
HAKMEM_DEBUG_LEVEL=4 ./larson_hakmem ...

# Full verbose tracing
HAKMEM_DEBUG_LEVEL=5 ./larson_hakmem ...
```

---

## Phase 1: Completed (2025-11-29)

### Consolidated Variables

| Old ENV Variable | New Control | Level | Commit |
|------------------|-------------|-------|--------|
| `HAKMEM_ALLOC_PATH_TRACE` | `HAKMEM_DEBUG_LEVEL >= 3` | INFO | 3f461ba25 |
| `HAKMEM_TINY_SLL_VALIDATE_HDR` | `HAKMEM_DEBUG_LEVEL >= 3` | INFO | 3f461ba25 |
| `HAKMEM_TINY_REFILL_FAILFAST` | `HAKMEM_DEBUG_LEVEL >= 4` | DEBUG | 3f461ba25 |
| `HAKMEM_TINY_GUARD` | `HAKMEM_DEBUG_LEVEL >= 4` | DEBUG | 3f461ba25 |

### Kept for Special Purposes

| ENV Variable | Purpose | Reason |
|--------------|---------|--------|
| `HAKMEM_TINY_GUARD_CLASS` | Target class for guard (0-7) | Fine-grained control |
| `HAKMEM_TINY_GUARD_MAX` | Max guard events (default: 8) | Fine-grained control |

### Backward Compatibility

✅ **All legacy environment variables still work**
- Uses `hak_debug_check_level()` for compatibility
- Old code continues to function
- Graceful migration path

---

## Remaining Variables (Future Work)

### Category A: General Debug Control (4 vars)
- `HAKMEM_DEBUG_ALL` → Consolidate to LEVEL=5
- `HAKMEM_TRACE_LEVEL` → Consolidate to LEVEL
- `HAKMEM_TRACE` → Consolidate to LEVEL=5

### Category B: Component Debug (4 vars)
- `HAKMEM_ACE_DEBUG` → Consolidate to LEVEL>=2
- `HAKMEM_ACE_LOG_LEVEL` → Consolidate to LEVEL
- `HAKMEM_ADAPTIVE_LOG` → Consolidate to LEVEL>=3
- `HAKMEM_SFC_DEBUG` → Consolidate to LEVEL>=3

### Category C: Pointer Tracing (5 vars)
- `HAKMEM_PTR_TRACE` → Consolidate to LEVEL>=4
- `HAKMEM_PTR_TRACE_ALL` → Consolidate to LEVEL=5
- `HAKMEM_PTR_TRACE_CLASS` → Keep (special purpose)
- `HAKMEM_PTR_TRACE_DUMP` → Consolidate to LEVEL=5
- `HAKMEM_PTR_TRACE_VERBOSE` → Consolidate to LEVEL=5

### Category D: SuperSlab Debug (7 vars)
- `HAKMEM_SS_ACQUIRE_DEBUG` → Consolidate to LEVEL>=3
- `HAKMEM_SS_FREE_DEBUG` → Consolidate to LEVEL>=3
- `HAKMEM_SS_LRU_DEBUG` → Consolidate to LEVEL>=4
- `HAKMEM_SS_PREWARM_DEBUG` → Consolidate to LEVEL>=3
- `HAKMEM_SUPER_LOOKUP_DEBUG` → Consolidate to LEVEL>=3
- `HAKMEM_SUPER_REG_DEBUG` → Consolidate to LEVEL>=3
- `HAKMEM_SUPER_REG_REQTRACE` → Consolidate to LEVEL>=4

### Category E: Tiny Allocator Debug (15+ vars)
- `HAKMEM_TINY_ALLOC_DEBUG` → Consolidate to LEVEL>=3
- `HAKMEM_TINY_DEBUG_FAST` → Consolidate to LEVEL>=3
- `HAKMEM_TINY_DEBUG_REMOTE_GUARD` → Consolidate to LEVEL>=4
- `HAKMEM_TINY_FAST_DEBUG` → Consolidate to LEVEL>=3
- `HAKMEM_TINY_FAST_DEBUG_MAX` → Keep (special purpose)
- `HAKMEM_TINY_HEAP_V` → Consolidate to LEVEL>=3
- `HAKMEM_TINY_MAILBOX_TRACE_LIMIT` → Keep (special purpose)
- `HAKMEM_TINY_PATH_DEBUG` → Consolidate to LEVEL>=3
- `HAKMEM_TINY_REFILL_OPT_DEBUG` → Consolidate to LEVEL>=3
- `HAKMEM_TINY_RF_TRACE` → Consolidate to LEVEL>=4
- `HAKMEM_TINY_SLL_DRAIN_DEBUG` → Consolidate to LEVEL>=3
- `HAKMEM_TINY_SUPERSLAB_TRACE` → Consolidate to LEVEL>=4
- `HAKMEM_TINY_TRACE_RING` → Consolidate to LEVEL>=4
- `HAKMEM_TINY_ULTRA_DEBUG` → Consolidate to LEVEL=5

### Category F: Free Path Tracing (3 vars)
- `HAKMEM_FREE_ROUTE_TRACE` → Consolidate to LEVEL>=3
- `HAKMEM_FREE_WRAP_TRACE` → Consolidate to LEVEL>=3
- `HAKMEM_INVALID_FREE_LOG` → Consolidate to LEVEL>=2

### Category G: Misc Debug (5 vars)
- `HAKMEM_DEBUG_SEGV` → Consolidate to LEVEL>=1
- `HAKMEM_EXTERNAL_GUARD_LOG` → Consolidate to LEVEL>=3
- `HAKMEM_FOO_DEBUG` → Remove (unused test var)
- `HAKMEM_FOO_TRACE` → Remove (unused test var)
- `HAKMEM_LOG_FILE` → Keep (special purpose)

---

## Consolidation Plan (Phase 2-4)

### Phase 2: High-Priority Consolidation (10-15 vars)
**Target:** SuperSlab + Tiny Allocator debug variables
**Effort:** 4-6 hours
**Impact:** Most frequently used debug variables

Candidates:
- Category D: SuperSlab Debug (7 vars)
- Category E: High-frequency Tiny debug (5 vars)

### Phase 3: Component Debug Consolidation (10-15 vars)
**Target:** Component-specific debug variables
**Effort:** 3-4 hours
**Impact:** Cleaner component debugging

Candidates:
- Category B: Component Debug (4 vars)
- Category C: Pointer Tracing (consolidate 3/5)
- Category F: Free Path Tracing (3 vars)

### Phase 4: Cleanup & Documentation (5-10 vars)
**Target:** Remaining + unused variables
**Effort:** 2-3 hours
**Impact:** Final cleanup

Tasks:
- Remove unused test variables (FOO_DEBUG, etc.)
- Document special-purpose variables
- Update ENV_VARS.md with consolidated list

---

## Estimated Final State

### After Full Consolidation

**Environment Variables:**
- `HAKMEM_DEBUG_LEVEL=<0-5>` - Main debug control
- `HAKMEM_QUIET=1` - Suppress all debug (override)
- `HAKMEM_DEBUG_ALL=1` - Enable all debug (legacy)

**Special-Purpose (5-10 vars):**
- `HAKMEM_TINY_GUARD_CLASS` - Guard target class
- `HAKMEM_TINY_GUARD_MAX` - Guard event limit
- `HAKMEM_PTR_TRACE_CLASS` - Pointer trace class
- `HAKMEM_TINY_FAST_DEBUG_MAX` - Fast debug limit
- `HAKMEM_LOG_FILE` - Log file path
- ...

**Total:** 10-15 variables (down from 43+)

**Reduction:** ~70% fewer environment variables

---

## References

- Master debug header: `core/hakmem_debug_master.h`
- Consolidated variables: commits 20f8d6f17, 3f461ba25
- Full survey: 43+ debug/trace/log variables identified (2025-11-29)
- Implementation: `hak_debug_check_level()` API

---

## Migration Guide

### For Users

**Old way (still works):**
```bash
HAKMEM_ALLOC_PATH_TRACE=1 ./larson_hakmem ...
HAKMEM_TINY_SLL_VALIDATE_HDR=1 ./larson_hakmem ...
```

**New way (recommended):**
```bash
HAKMEM_DEBUG_LEVEL=3 ./larson_hakmem ...
```

### For Developers

**Old pattern:**
```c
static int dbg = -1;
if (dbg == -1) {
    const char* e = getenv("HAKMEM_FOO_DEBUG");
    dbg = (e && *e && *e != '0') ? 1 : 0;
}
```

**New pattern:**
```c
static int dbg = -1;
if (dbg == -1) {
    dbg = hak_debug_check_level("HAKMEM_FOO_DEBUG", 3);  // INFO level
}
```

---

## Acknowledgments

- Initial consolidation: Claude Code (ultrathink) + Task agent
- Survey and planning: 2025-11-29
- Implementation: commits 20f8d6f17, 3f461ba25