hakmem/docs/status/P2.3_TINY_CONFIG_REORGANIZATION_TASK.md

# P2.3: TINY Allocator Configuration Reorganization Task

**Task ID**: P2.3
**Complexity**: Medium-High (2 days)
**Dependencies**: P2.1, P2.2 completed
**Objective**: Reorganize 113 TINY allocator variables → 40 canonical variables with backward compatibility

---

## Executive Summary

The TINY allocator (1-2048B) currently has **113 configuration variables** scattered across multiple subsystems with inconsistent naming and unclear hierarchy. This task consolidates them into **40 canonical variables** organized by functional category.

**Key Goals**:
1. **Reduce variable count**: 113 → 40 (-64%)
2. **Organize by category**: TLS Cache, SFC, P0, Header, Adaptive, Debug
3. **Maintain backward compatibility**: 6-month deprecation period (2025-11-26 → 2026-05-26)
4. **Simplify user experience**: Clear hierarchy and naming conventions

---

## Current State Analysis

### Variable Inventory (113 total)

#### TLS Cache (18 variables) → 6 canonical
```
Current (scattered):
HAKMEM_TINY_TLS_CAP
HAKMEM_TINY_TLS_REFILL
HAKMEM_TINY_TLS_CAP_C1, C2, C3, C4, C5, C6, C7 (7 per-class overrides)
HAKMEM_TINY_TLS_REFILL_C1, C2, C3, C4, C5, C6, C7 (7 per-class overrides)
HAKMEM_TINY_DRAIN_THRESH
HAKMEM_TINY_DRAIN_INTERVAL_MS

Canonical (6):
HAKMEM_TINY_TLS_CAP              # Global default capacity (default: 64)
HAKMEM_TINY_TLS_REFILL           # Global default refill batch (default: 16)
HAKMEM_TINY_TLS_DRAIN_THRESH     # Drain threshold (default: 128)
HAKMEM_TINY_TLS_DRAIN_INTERVAL   # Drain interval in ms (default: 100)
HAKMEM_TINY_TLS_CLASS_OVERRIDE   # Per-class override (format: "C1:128:32,C3:64:16")
HAKMEM_TINY_TLS_HOT_CLASSES      # Hot class list (format: "C1,C3,C5", default: auto-detect)
```

#### Super Front Cache (12 variables) → 4 canonical
```
Current:
HAKMEM_TINY_SFC_ENABLE
HAKMEM_TINY_SFC_CAPACITY
HAKMEM_TINY_SFC_HOT_CLASSES
HAKMEM_TINY_SFC_CAPACITY_C1, C2, C3, C4, C5, C6, C7 (7 per-class)
HAKMEM_TINY_SFC_PREFETCH
HAKMEM_TINY_SFC_STATS

Canonical (4):
HAKMEM_TINY_SFC_ENABLE           # Master toggle (default: 1)
HAKMEM_TINY_SFC_CAPACITY         # Global capacity (default: 128)
HAKMEM_TINY_SFC_HOT_CLASSES      # Hot class count (default: 8)
HAKMEM_TINY_SFC_CLASS_OVERRIDE   # Per-class override (format: "C1:256,C3:128")
```

#### P0 Batch Optimization (16 variables) → 5 canonical
```
Current:
HAKMEM_TINY_P0_ENABLE
HAKMEM_TINY_P0_BATCH
HAKMEM_TINY_P0_BATCH_C1, C2, C3, C4, C5, C6, C7 (7 per-class)
HAKMEM_TINY_P0_NO_DRAIN
HAKMEM_TINY_P0_LOG
HAKMEM_TINY_P0_STATS
HAKMEM_TINY_P0_THRESHOLD
HAKMEM_TINY_P0_MIN_SAMPLES
HAKMEM_TINY_P0_ADAPTIVE

Canonical (5):
HAKMEM_TINY_P0_ENABLE            # Master toggle (default: 1)
HAKMEM_TINY_P0_BATCH             # Global batch size (default: 16)
HAKMEM_TINY_P0_CLASS_OVERRIDE    # Per-class override (format: "C1:32,C3:24")
HAKMEM_TINY_P0_NO_DRAIN          # Disable remote drain (debug only, default: 0)
HAKMEM_TINY_P0_LOG               # Enable counter validation logging (default: 0)
```

#### Header Configuration (8 variables) → 3 canonical
```
Current:
HAKMEM_TINY_HEADER_CLASSIDX
HAKMEM_TINY_HEADER_SIZE
HAKMEM_TINY_HEADER_CANARY
HAKMEM_TINY_HEADER_MAGIC
HAKMEM_TINY_HEADER_C1_OFFSET, C2_OFFSET, C3_OFFSET, ... (7 per-class)

Canonical (3):
HAKMEM_TINY_HEADER_CLASSIDX      # Store class_idx in header (default: 1, enables fast free)
HAKMEM_TINY_HEADER_CANARY        # Canary protection (default: via HAKMEM_INTEGRITY_CHECKS)
HAKMEM_TINY_HEADER_CLASS_OFFSET  # Per-class offset override (format: "C1:0,C7:1")
```

#### Adaptive Sizing (22 variables) → 8 canonical
```
Current:
HAKMEM_TINY_ADAPTIVE_SIZING
HAKMEM_TINY_ADAPTIVE_INTERVAL_MS
HAKMEM_TINY_ADAPTIVE_WINDOW
HAKMEM_TINY_CAP_LEARN
HAKMEM_TINY_CAP_LEARN_RATE
HAKMEM_TINY_CAP_MIN, CAP_MAX (per-class: 14 variables)
... (various thresholds and tuning params)

Canonical (8):
HAKMEM_TINY_ADAPTIVE_ENABLE      # Master toggle (merged from ADAPTIVE_SIZING + CAP_LEARN)
HAKMEM_TINY_ADAPTIVE_INTERVAL    # Adjustment interval in ms (default: 1000)
HAKMEM_TINY_ADAPTIVE_WINDOW      # Sample window (default: via HAKMEM_ALLOC_LEARN_WINDOW)
HAKMEM_TINY_ADAPTIVE_RATE        # Learning rate (default: via HAKMEM_ALLOC_LEARN_RATE)
HAKMEM_TINY_ADAPTIVE_CAP_MIN     # Global min capacity (default: 16)
HAKMEM_TINY_ADAPTIVE_CAP_MAX     # Global max capacity (default: 256)
HAKMEM_TINY_ADAPTIVE_CLASS_RANGE # Per-class range (format: "C1:32-512,C3:16-128")
HAKMEM_TINY_ADAPTIVE_ADVANCED    # Enable advanced overrides (default: 0)
```

#### Prewarm & Initialization (10 variables) → 4 canonical
```
Current:
HAKMEM_TINY_PREWARM
HAKMEM_TINY_PREWARM_COUNT
HAKMEM_TINY_PREWARM_C1, C2, C3, C4, C5, C6, C7 (7 per-class)
HAKMEM_TINY_LAZY_INIT

Canonical (4):
HAKMEM_TINY_PREWARM              # Master toggle (default: 0)
HAKMEM_TINY_PREWARM_COUNT        # Global prewarm count (default: 8)
HAKMEM_TINY_PREWARM_CLASSES      # Class-specific prewarm (format: "C1:16,C3:8")
HAKMEM_TINY_LAZY_INIT            # Lazy initialization (default: 1)
```

#### Statistics & Debug (27 variables) → 10 canonical
```
Current:
HAKMEM_TINY_STATS
HAKMEM_TINY_STATS_INTERVAL
HAKMEM_TINY_STATS_VERBOSE
HAKMEM_TINY_COUNTERS
HAKMEM_TINY_PROFILE_*           # 10+ profiling flags
HAKMEM_TINY_TRACE_*             # 8+ tracing flags
... (various debug knobs)

Canonical (10):
# Most moved to global HAKMEM_DEBUG_LEVEL, HAKMEM_DEBUG_TINY, etc. (P0.4)
HAKMEM_TINY_STATS_INTERVAL       # Stats reporting interval (default: 10s)
HAKMEM_TINY_PROFILE_REFILL       # Profile refill operations (default: 0)
HAKMEM_TINY_PROFILE_DRAIN        # Profile drain operations (default: 0)
HAKMEM_TINY_PROFILE_CACHE        # Profile cache hit/miss (default: 0)
HAKMEM_TINY_PROFILE_P0           # Profile P0 batch operations (default: 0)
HAKMEM_TINY_PROFILE_SFC          # Profile SFC operations (default: 0)
HAKMEM_TINY_TRACE_CLASS          # Trace specific class (format: "C1,C3")
HAKMEM_TINY_TRACE_REFILL         # Trace refill calls (default: 0)
HAKMEM_TINY_TRACE_DRAIN          # Trace drain calls (default: 0)
HAKMEM_TINY_COUNTERS_VALIDATE    # Validate counter integrity (default: 1 in DEBUG)
```

---

## Target Architecture

### Canonical Variables (40 total)

```
# TLS Cache (6)
HAKMEM_TINY_TLS_CAP
HAKMEM_TINY_TLS_REFILL
HAKMEM_TINY_TLS_DRAIN_THRESH
HAKMEM_TINY_TLS_DRAIN_INTERVAL
HAKMEM_TINY_TLS_CLASS_OVERRIDE
HAKMEM_TINY_TLS_HOT_CLASSES

# Super Front Cache (4)
HAKMEM_TINY_SFC_ENABLE
HAKMEM_TINY_SFC_CAPACITY
HAKMEM_TINY_SFC_HOT_CLASSES
HAKMEM_TINY_SFC_CLASS_OVERRIDE

# P0 Batch Optimization (5)
HAKMEM_TINY_P0_ENABLE
HAKMEM_TINY_P0_BATCH
HAKMEM_TINY_P0_CLASS_OVERRIDE
HAKMEM_TINY_P0_NO_DRAIN
HAKMEM_TINY_P0_LOG

# Header Configuration (3)
HAKMEM_TINY_HEADER_CLASSIDX
HAKMEM_TINY_HEADER_CANARY
HAKMEM_TINY_HEADER_CLASS_OFFSET

# Adaptive Sizing (8)
HAKMEM_TINY_ADAPTIVE_ENABLE
HAKMEM_TINY_ADAPTIVE_INTERVAL
HAKMEM_TINY_ADAPTIVE_WINDOW
HAKMEM_TINY_ADAPTIVE_RATE
HAKMEM_TINY_ADAPTIVE_CAP_MIN
HAKMEM_TINY_ADAPTIVE_CAP_MAX
HAKMEM_TINY_ADAPTIVE_CLASS_RANGE
HAKMEM_TINY_ADAPTIVE_ADVANCED

# Prewarm & Init (4)
HAKMEM_TINY_PREWARM
HAKMEM_TINY_PREWARM_COUNT
HAKMEM_TINY_PREWARM_CLASSES
HAKMEM_TINY_LAZY_INIT

# Statistics & Profiling (10)
HAKMEM_TINY_STATS_INTERVAL
HAKMEM_TINY_PROFILE_REFILL
HAKMEM_TINY_PROFILE_DRAIN
HAKMEM_TINY_PROFILE_CACHE
HAKMEM_TINY_PROFILE_P0
HAKMEM_TINY_PROFILE_SFC
HAKMEM_TINY_TRACE_CLASS
HAKMEM_TINY_TRACE_REFILL
HAKMEM_TINY_TRACE_DRAIN
HAKMEM_TINY_COUNTERS_VALIDATE
```

---

## Implementation Plan (2 days)

### Day 1: Consolidation Shims + Core Implementation

#### Task 1.1: Create Consolidation Shims (3 hours)
Create `core/hakmem_tiny_config.h` and `core/hakmem_tiny_config.c`:

```c
// core/hakmem_tiny_config.h
#pragma once

#include <stddef.h>

// TLS Cache Configuration
typedef struct {
  int global_cap;
  int global_refill;
  int drain_thresh;
  int drain_interval_ms;

  // Per-class overrides (parsed from CLASS_OVERRIDE)
  int class_cap[7];        // -1 = use global
  int class_refill[7];     // -1 = use global

  // Hot classes
  int hot_classes[7];      // 1 = hot, 0 = cold
  int hot_count;
} HakmemTinyTLSConfig;

// SFC Configuration
typedef struct {
  int enabled;
  int global_capacity;
  int hot_classes_count;
  int class_capacity[7];   // -1 = use global
} HakmemTinySFCConfig;

// P0 Configuration
typedef struct {
  int enabled;
  int global_batch;
  int class_batch[7];      // -1 = use global
  int no_drain;
  int log;
} HakmemTinyP0Config;

// Header Configuration
typedef struct {
  int classidx_enabled;
  int canary_enabled;
  int class_offset[7];     // -1 = default
} HakmemTinyHeaderConfig;

// Adaptive Configuration
typedef struct {
  int enabled;
  int interval_ms;
  int window;
  double rate;
  int cap_min;
  int cap_max;
  int class_min[7];        // -1 = use global
  int class_max[7];        // -1 = use global
  int advanced;
} HakmemTinyAdaptiveConfig;

// Prewarm Configuration
typedef struct {
  int enabled;
  int global_count;
  int class_count[7];      // -1 = use global
  int lazy_init;
} HakmemTinyPrewarmConfig;

// Statistics Configuration
typedef struct {
  int interval_sec;
  int profile_refill;
  int profile_drain;
  int profile_cache;
  int profile_p0;
  int profile_sfc;
  int trace_class[7];      // 1 = trace this class
  int trace_refill;
  int trace_drain;
  int counters_validate;
} HakmemTinyStatsConfig;

// Master configuration
typedef struct {
  HakmemTinyTLSConfig tls;
  HakmemTinySFCConfig sfc;
  HakmemTinyP0Config p0;
  HakmemTinyHeaderConfig header;
  HakmemTinyAdaptiveConfig adaptive;
  HakmemTinyPrewarmConfig prewarm;
  HakmemTinyStatsConfig stats;
} HakmemTinyConfig;

// Parse new + legacy envs. New vars take precedence.
HakmemTinyConfig hakmem_tiny_config_parse(void);

// Backfill legacy env vars when only new vars are set
void hakmem_tiny_config_apply_compat_env(void);
```

#### Task 1.2: Implement Parsing Logic (4 hours)
`core/hakmem_tiny_config.c`:

```c
#include "hakmem_tiny_config.h"
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

static int get_env_int_default(const char* key, int fallback) {
  const char* v = getenv(key);
  return v ? atoi(v) : fallback;
}

static double get_env_double_default(const char* key, double fallback) {
  const char* v = getenv(key);
  return v ? atof(v) : fallback;
}

static void warn_deprecated(const char* old_var, const char* new_var) {
  fprintf(stderr,
          "[DEPRECATED] %s is deprecated; use %s instead. "
          "Sunset date: 2026-05-26. See DEPRECATED.md for migration.\n",
          old_var, new_var);
}

// Parse "C1:128:32,C3:64:16" format for CLASS_OVERRIDE
static void parse_class_override(const char* str, int* cap_array, int* refill_array) {
  if (!str) return;

  char buf[256];
  strncpy(buf, str, sizeof(buf) - 1);
  buf[sizeof(buf) - 1] = '\0';

  char* token = strtok(buf, ",");
  while (token) {
    int class_idx, cap, refill;
    if (sscanf(token, "C%d:%d:%d", &class_idx, &cap, &refill) == 3) {
      if (class_idx >= 1 && class_idx <= 7) {
        cap_array[class_idx - 1] = cap;
        refill_array[class_idx - 1] = refill;
      }
    }
    token = strtok(NULL, ",");
  }
}

// Similar parsing for other override formats...

HakmemTinyConfig hakmem_tiny_config_parse(void) {
  HakmemTinyConfig cfg;
  memset(&cfg, -1, sizeof(cfg));  // Initialize to -1 (not set)

  // TLS Cache
  cfg.tls.global_cap = get_env_int_default("HAKMEM_TINY_TLS_CAP", 64);
  cfg.tls.global_refill = get_env_int_default("HAKMEM_TINY_TLS_REFILL", 16);
  cfg.tls.drain_thresh = get_env_int_default("HAKMEM_TINY_TLS_DRAIN_THRESH",
                                              get_env_int_default("HAKMEM_TINY_DRAIN_THRESH", 128));
  if (getenv("HAKMEM_TINY_DRAIN_THRESH")) {
    warn_deprecated("HAKMEM_TINY_DRAIN_THRESH", "HAKMEM_TINY_TLS_DRAIN_THRESH");
  }

  // Parse CLASS_OVERRIDE
  const char* override = getenv("HAKMEM_TINY_TLS_CLASS_OVERRIDE");
  if (override) {
    parse_class_override(override, cfg.tls.class_cap, cfg.tls.class_refill);
  } else {
    // Fallback to legacy per-class vars
    for (int i = 0; i < 7; i++) {
      char key[64];
      snprintf(key, sizeof(key), "HAKMEM_TINY_TLS_CAP_C%d", i + 1);
      if (getenv(key)) {
        cfg.tls.class_cap[i] = get_env_int_default(key, -1);
        warn_deprecated(key, "HAKMEM_TINY_TLS_CLASS_OVERRIDE");
      }

      snprintf(key, sizeof(key), "HAKMEM_TINY_TLS_REFILL_C%d", i + 1);
      if (getenv(key)) {
        cfg.tls.class_refill[i] = get_env_int_default(key, -1);
        warn_deprecated(key, "HAKMEM_TINY_TLS_CLASS_OVERRIDE");
      }
    }
  }

  // ... (similar parsing for SFC, P0, Header, Adaptive, Prewarm, Stats)

  return cfg;
}

void hakmem_tiny_config_apply_compat_env(void) {
  HakmemTinyConfig cfg = hakmem_tiny_config_parse();

  // Backfill legacy vars for existing code paths
  if (cfg.tls.global_cap > 0 && !getenv("HAKMEM_TINY_TLS_CAP")) {
    char buf[32];
    snprintf(buf, sizeof(buf), "%d", cfg.tls.global_cap);
    setenv("HAKMEM_TINY_TLS_CAP", buf, 0);
  }

  // Backfill per-class vars if CLASS_OVERRIDE was used
  for (int i = 0; i < 7; i++) {
    if (cfg.tls.class_cap[i] > 0) {
      char key[64], val[32];
      snprintf(key, sizeof(key), "HAKMEM_TINY_TLS_CAP_C%d", i + 1);
      if (!getenv(key)) {
        snprintf(val, sizeof(val), "%d", cfg.tls.class_cap[i]);
        setenv(key, val, 0);
      }
    }
  }

  // ... (similar backfill for other subsystems)
}

__attribute__((constructor)) static void hakmem_tiny_config_ctor(void) {
  hakmem_tiny_config_apply_compat_env();
}
```

#### Task 1.3: Update Makefile (30 minutes)
Add new object files:
```makefile
OBJS_BASE = \
  core/hakmem_tiny_config.o \
  # ... (existing objects)
```

### Day 2: Documentation + Testing + Validation

#### Task 2.1: Update DEPRECATED.md (1 hour)
Add new section:

```markdown
### TINY Allocator Configuration (P2.3 Consolidation)

**Deprecated**: 2025-11-26
**Sunset**: 2026-05-26

**113 variables → 40 variables (-64%)**

#### TLS Cache (18→6)
| Deprecated Variable | Replacement | Notes |
|---------------------|-------------|-------|
| `HAKMEM_TINY_DRAIN_THRESH` | `HAKMEM_TINY_TLS_DRAIN_THRESH` | Renamed for clarity |
| `HAKMEM_TINY_TLS_CAP_C1` ... `C7` | `HAKMEM_TINY_TLS_CLASS_OVERRIDE` | Use format "C1:128:32,C3:64:16" |
| `HAKMEM_TINY_TLS_REFILL_C1` ... `C7` | `HAKMEM_TINY_TLS_CLASS_OVERRIDE` | Merged into override string |

#### SFC (12→4)
| Deprecated Variable | Replacement | Notes |
|---------------------|-------------|-------|
| `HAKMEM_TINY_SFC_CAPACITY_C1` ... `C7` | `HAKMEM_TINY_SFC_CLASS_OVERRIDE` | Use format "C1:256,C3:128" |

#### P0 (16→5)
| Deprecated Variable | Replacement | Notes |
|---------------------|-------------|-------|
| `HAKMEM_TINY_P0_BATCH_C1` ... `C7` | `HAKMEM_TINY_P0_CLASS_OVERRIDE` | Use format "C1:32,C3:24" |
| `HAKMEM_TINY_P0_STATS` | `HAKMEM_TINY_PROFILE_P0` | Moved to profiling category |
| `HAKMEM_TINY_P0_THRESHOLD` | (removed) | Auto-tuned |
| `HAKMEM_TINY_P0_MIN_SAMPLES` | (removed) | Auto-tuned |
| `HAKMEM_TINY_P0_ADAPTIVE` | `HAKMEM_TINY_ADAPTIVE_ENABLE` | Merged into adaptive system |

... (continue for all 113 variables)

**Migration Example**:
```bash
# OLD (deprecated, will be removed 2026-05-26)
export HAKMEM_TINY_TLS_CAP_C1=128
export HAKMEM_TINY_TLS_REFILL_C1=32
export HAKMEM_TINY_TLS_CAP_C3=64
export HAKMEM_TINY_TLS_REFILL_C3=16
export HAKMEM_TINY_DRAIN_THRESH=256

# NEW (use this)
export HAKMEM_TINY_TLS_CLASS_OVERRIDE="C1:128:32,C3:64:16"
export HAKMEM_TINY_TLS_DRAIN_THRESH=256
```
```

#### Task 2.2: Update scripts/validate_config.sh (1 hour)
Add 113 deprecated variables to registry:

```bash
declare -A DEPRECATED_VARS=(
    # ... (existing vars)

    # TINY TLS (18 vars deprecated)
    ["HAKMEM_TINY_DRAIN_THRESH"]="HAKMEM_TINY_TLS_DRAIN_THRESH"
    ["HAKMEM_TINY_TLS_CAP_C1"]="HAKMEM_TINY_TLS_CLASS_OVERRIDE"
    ["HAKMEM_TINY_TLS_CAP_C2"]="HAKMEM_TINY_TLS_CLASS_OVERRIDE"
    # ... (continue for all C1-C7)

    # TINY SFC (12 vars deprecated)
    ["HAKMEM_TINY_SFC_CAPACITY_C1"]="HAKMEM_TINY_SFC_CLASS_OVERRIDE"
    # ... (continue)

    # ... (continue for all 113 deprecated vars)
)

# Add 40 canonical vars to KNOWN_VARS
declare -a KNOWN_VARS=(
    # ... (existing vars)

    # TINY TLS (6)
    "HAKMEM_TINY_TLS_CAP"
    "HAKMEM_TINY_TLS_REFILL"
    "HAKMEM_TINY_TLS_DRAIN_THRESH"
    "HAKMEM_TINY_TLS_DRAIN_INTERVAL"
    "HAKMEM_TINY_TLS_CLASS_OVERRIDE"
    "HAKMEM_TINY_TLS_HOT_CLASSES"

    # ... (continue for all 40 canonical vars)
)

# Add validation for override string format
validate_class_override() {
    local var="$1"
    local val="$2"

    # Check format: "C1:128:32,C3:64:16"
    if [[ ! "$val" =~ ^(C[1-7]:[0-9]+:[0-9]+(,C[1-7]:[0-9]+:[0-9]+)*)?$ ]]; then
        log_error "$var has invalid format (expected: 'C1:128:32,C3:64:16')"
        return 1
    fi
}
```

#### Task 2.3: Update CONFIGURATION.md (1 hour)
Update TINY Allocator section with new canonical variables and examples.

#### Task 2.4: Testing (3 hours)

**Test 1: Build Verification**
```bash
make clean
make bench_random_mixed_hakmem
./out/release/bench_random_mixed_hakmem
# Expected: Clean build, no warnings, baseline performance maintained
```

**Test 2: Backward Compatibility (Legacy Vars)**
```bash
# Test with old per-class vars
export HAKMEM_TINY_TLS_CAP_C1=256
export HAKMEM_TINY_TLS_REFILL_C1=32
export HAKMEM_TINY_DRAIN_THRESH=128

./out/release/bench_random_mixed_hakmem
# Expected: Deprecation warnings shown, functionality preserved
```

**Test 3: New Variables (CLASS_OVERRIDE)**
```bash
unset HAKMEM_TINY_TLS_CAP_C1 HAKMEM_TINY_TLS_REFILL_C1
export HAKMEM_TINY_TLS_CLASS_OVERRIDE="C1:256:32,C3:128:16"
export HAKMEM_TINY_TLS_DRAIN_THRESH=128

./out/release/bench_random_mixed_hakmem
# Expected: No warnings, same performance
```

**Test 4: Validation Script**
```bash
./scripts/validate_config.sh
# Expected: Show deprecation warnings for old vars, validate new vars
```

**Test 5: Multi-threaded Stability**
```bash
./out/release/larson_hakmem 8
# Expected: No crashes, stable performance
```

---

## Deliverables Checklist

### Code
- [ ] `core/hakmem_tiny_config.h` - Configuration structures and API
- [ ] `core/hakmem_tiny_config.c` - Parsing and backward-compat shims
- [ ] `Makefile` - Add new object files

### Documentation
- [ ] `DEPRECATED.md` - Add TINY consolidation section (113→40 mapping)
- [ ] `CONFIGURATION.md` - Update TINY section with new canonical vars
- [ ] `scripts/validate_config.sh` - Add 113 deprecated vars, 40 canonical vars

### Testing
- [ ] Build verification (clean compile)
- [ ] Backward compatibility test (legacy vars work)
- [ ] New variables test (CLASS_OVERRIDE format)
- [ ] Validation script test (deprecation warnings)
- [ ] Multi-threaded stability test (Larson 8T)
- [ ] Performance regression check (within ±2% of baseline)

---

## Success Criteria

1. **Variable Reduction**: 113 → 40 canonical variables (-64%)
2. **Backward Compatibility**: All 113 legacy variables still work with deprecation warnings
3. **Build Success**: Clean compile with no errors
4. **Performance**: No regression (within ±2% of baseline)
5. **Validation**: Script correctly identifies deprecated/invalid variables
6. **Documentation**: Complete migration guide in DEPRECATED.md

---

## Timeline Estimate

| Task | Duration | Difficulty |
|------|----------|------------|
| 1.1: Create consolidation shims | 3 hours | Medium |
| 1.2: Implement parsing logic | 4 hours | Medium-High |
| 1.3: Update Makefile | 30 min | Easy |
| 2.1: Update DEPRECATED.md | 1 hour | Medium |
| 2.2: Update validate_config.sh | 1 hour | Medium |
| 2.3: Update CONFIGURATION.md | 1 hour | Medium |
| 2.4: Testing | 3 hours | Medium |
| **Total** | **~14 hours** | **~2 days** |

---

## Notes for Implementation

### Parsing Format Details

**CLASS_OVERRIDE formats**:
```bash
# TLS (capacity:refill)
HAKMEM_TINY_TLS_CLASS_OVERRIDE="C1:128:32,C3:64:16,C7:256:48"

# SFC (capacity only)
HAKMEM_TINY_SFC_CLASS_OVERRIDE="C1:256,C3:128,C5:64"

# P0 (batch size only)
HAKMEM_TINY_P0_CLASS_OVERRIDE="C1:32,C3:24,C7:16"

# Header (offset only)
HAKMEM_TINY_HEADER_CLASS_OFFSET="C1:0,C7:1"

# Adaptive (min-max range)
HAKMEM_TINY_ADAPTIVE_CLASS_RANGE="C1:32-512,C3:16-256"
```

### Advanced Override Pattern
Similar to P2.2 (Learning Systems), use `HAKMEM_TINY_ADAPTIVE_ADVANCED=1` to enable deprecated fine-tuning knobs (P0_THRESHOLD, P0_MIN_SAMPLES, etc.).

### Error Handling
- Invalid format in CLASS_OVERRIDE → log warning, ignore that entry
- Class index out of range (not 1-7) → log warning, ignore
- Negative values → log error, use default

---

## Reference Implementation (P2.2)

See `core/hakmem_alloc_learner.c` for similar consolidation pattern:
- ENV parsing with fallback to legacy vars
- Deprecation warnings
- Auto-backfill for existing code paths
- Constructor-based initialization

---

**Task Specification Version**: 1.0
**Created**: 2025-11-26
**For**: ChatGPT (or other AI assistant)
**Context**: HAKMEM Phase 2 cleanup (P2.3 - TINY Config Reorganization)