hakmem/docs/analysis/PHASE56_PROMOTE_LEAN_OFF_IMPLEMENTATION.md

# Phase 56: Promote LEAN+OFF as "Balanced Mode" — Implementation

> Note (Phase 58): This “promote as default” approach was later replaced by a profile split: `MIXED_TINYV3_C7_SAFE` (Speed-first) and `MIXED_TINYV3_C7_BALANCED` (LEAN+OFF). See `docs/analysis/PHASE58_PROFILE_SPLIT_SPEED_FIRST_DEFAULT_RESULTS.md`.

## Objective

Promote `HAKMEM_SS_MEM_LEAN=1` + `HAKMEM_SS_MEM_LEAN_DECOMMIT=OFF` (LEAN+OFF) as the production-recommended "Balanced mode" preset by adding it to the `MIXED_TINYV3_C7_SAFE` benchmark profile.

## Background

Phase 55 validated that LEAN+OFF provides:
- **+1.2% throughput improvement** over baseline (56.8M vs 56.2M ops/s)
- **Zero syscall overhead** (prewarm suppression only, no decommit)
- **Better stability** (CV 5.41% vs 5.52% baseline)
- **Production-ready** (30-min validation passed with GO verdict)

LEAN+OFF is not a "memory-lean" mode (RSS stays ~33MB), but rather a **prewarm suppression policy** that avoids unnecessary superslab allocation during initialization, leading to better cache behavior and throughput.

## Implementation Approach

**Option A (Selected)**: Modify bench profile defaults — does NOT change library global defaults, only affects benchmark profiles where `HAKMEM_PROFILE=MIXED_TINYV3_C7_SAFE` is set.

**Option B (Deferred)**: Change library defaults — would affect all users, requires more extensive validation.

## Changes Made

### File: `core/bench_profile.h`

**Location**: In the `MIXED_TINYV3_C7_SAFE` profile section (line 59-109)

**Lines Added** (after line 96):

```c
    // Phase 56: Promote LEAN+OFF as "Balanced mode" (production-recommended preset)
    // Effect: +1.2% throughput, better stability, zero syscall overhead
    bench_setenv_default("HAKMEM_SS_MEM_LEAN", "1");
    bench_setenv_default("HAKMEM_SS_MEM_LEAN_DECOMMIT", "OFF");
    bench_setenv_default("HAKMEM_SS_MEM_LEAN_TARGET_MB", "10");
```

**Note**: The `HAKMEM_SS_MEM_LEAN_TARGET_MB=10` setting is not used when `DECOMMIT=OFF`, but is explicitly set for documentation/clarity purposes.

### Behavior

- `bench_setenv_default()` only sets ENV if not already set by user
- User can override with explicit ENV settings: `HAKMEM_SS_MEM_LEAN=0` disables all lean behavior
- Applies to all builds using `HAKMEM_PROFILE=MIXED_TINYV3_C7_SAFE`:
  - FAST build (`bench_random_mixed_hakmem_minimal`)
  - Standard build (`bench_random_mixed_hakmem`)
  - OBSERVE build (if profile is set)

## Rollback Procedure

To revert to "Speed-first" mode:

### Method 1: ENV Override (per-run)
```bash
HAKMEM_SS_MEM_LEAN=0 ./bench_random_mixed_hakmem_minimal
```

### Method 2: Code Rollback (permanent)
Remove the 3 lines from `core/bench_profile.h` (lines 97-101):
```diff
-    // Phase 56: Promote LEAN+OFF as "Balanced mode" (production-recommended preset)
-    // Effect: +1.2% throughput, better stability, zero syscall overhead
-    bench_setenv_default("HAKMEM_SS_MEM_LEAN", "1");
-    bench_setenv_default("HAKMEM_SS_MEM_LEAN_DECOMMIT", "OFF");
-    bench_setenv_default("HAKMEM_SS_MEM_LEAN_TARGET_MB", "10");
```

Then rebuild:
```bash
make bench_random_mixed_hakmem_minimal
make bench_random_mixed_hakmem
```

## Box Theory Compliance

- **Single conversion point**: Only `core/bench_profile.h` modified
- **ENV-gated**: User can override with `HAKMEM_SS_MEM_LEAN=0`
- **Reversible**: 3-line deletion reverts behavior
- **Library-safe**: Does NOT change global library defaults
- **Standard/OBSERVE/FAST builds**: All unmodified (only profile defaults changed)

## Profile Definition

### Speed-first Mode (opt-in via `HAKMEM_SS_MEM_LEAN=0`)
- Full prewarm enabled (allocates superslabs at initialization)
- Maximizes throughput at cost of higher initial RSS
- **Use case**: Latency-critical applications, no memory constraints

### Balanced Mode (default via profile)
- Prewarm suppression enabled (defers superslab allocation)
- +1.2% throughput gain, better stability
- No decommit overhead (zero syscall tax)
- **Use case**: Production workloads, general-purpose (recommended)

## Build Targets Affected

All builds using the `MIXED_TINYV3_C7_SAFE` profile:
- `make bench_random_mixed_hakmem_minimal` (FAST)
- `make bench_random_mixed_hakmem` (Standard)
- Any custom builds setting `HAKMEM_PROFILE=MIXED_TINYV3_C7_SAFE`

## Validation Plan

See `PHASE56_PROMOTE_LEAN_OFF_RESULTS.md` for detailed validation results.

1. **Mixed 10-run validation** (FAST and Standard builds)
2. **Syscall budget verification** (200M ops, baseline vs LEAN+OFF)
3. **Tail proxy analysis** (Phase 52 methodology)
4. **Performance scorecard update** (Speed-first vs Balanced comparison)

## Future Work

- **Option B consideration**: Evaluate changing library global defaults after extended production validation
- **Extended validation**: 60-min+ soak tests in production-like environments
- **Memory-constrained environments**: Evaluate LEAN+FREE/DONTNEED modes for extreme cases (Phase 57+)