hakmem/docs/analysis/ENV_PROFILE_PRESETS.md

# ENV Profile Presets (HAKMEM)

よく使う構成を 3 つのプリセットにまとめました。まずここからコピペし、必要な ENV だけを追加してください。v2 系や LEGACY 専用オプションは明示 opt-in で扱います。
ベンチバイナリでは `HAKMEM_PROFILE=<名前>` をセットすると、ここで定義した ENV を自動で注入します（既に設定済みの ENV は上書きしません）。

---

## Profile 1: MIXED_TINYV3_C7_SAFE（標準 Mixed 16–1024B）

### 目的
- Mixed 16–1024B の標準ベンチ用。
- C7-only SmallObject v3 + Tiny front v3 + LUT + fast classify ON。
- v4 系（C6/C7 v4、fast classify v4、small segment v4）はすべて OFF。
- Tiny/Pool v2 もすべて OFF。
- **v7 (C5/C6) は OFF** (Phase v10: Mixed 本線では v7 無効化、C5/C6 専用プリセット参照)
- C6 は凍結中（Tiny/SmallObject の特別扱いなし）。mid/pool の通常経路に任せる。

### ENV 最小セット（Release）
```sh
# プリセットでまとめて指定
HAKMEM_PROFILE=MIXED_TINYV3_C7_SAFE

# Mixed 16–1024B 前提のサイズ範囲（必要に応じて明示）
HAKMEM_BENCH_MIN_SIZE=16
HAKMEM_BENCH_MAX_SIZE=1024
```
プリセットで自動設定される主な ENV:
- `HAKMEM_TINY_HEAP_PROFILE=C7_SAFE`
- `HAKMEM_TINY_C7_HOT=1`
- `HAKMEM_TINY_HOTHEAP_V2=0`
- `HAKMEM_SMALL_HEAP_V3_ENABLED=1`
- `HAKMEM_SMALL_HEAP_V3_CLASSES=0x80`（C7-only v3）
- `HAKMEM_SMALL_HEAP_V4_ENABLED=0` / `HAKMEM_SMALL_HEAP_V4_CLASSES=0x0`
- `HAKMEM_TINY_PTR_FAST_CLASSIFY_ENABLED=1`
- `HAKMEM_TINY_PTR_FAST_CLASSIFY_V4_ENABLED=0`
- `HAKMEM_SMALL_SEGMENT_V4_ENABLED=0`
- `HAKMEM_POOL_V2_ENABLED=0`
- `HAKMEM_TINY_FRONT_V3_ENABLED=1`
- `HAKMEM_TINY_FRONT_V3_LUT_ENABLED=1`
- `HAKMEM_MID_V3_ENABLED=1`（Phase MID-V3: 257-768B, C6 only）
- `HAKMEM_MID_V3_CLASSES=0x40`（C6 only, C7 は ULTRA に任せる）
- `HAKMEM_MID_V35_ENABLED=0`（Phase v11a-5: Mixed では MID v3.5 OFF が最速）

### 任意オプション
- stats を見たいとき:
```sh
HAKMEM_TINY_HEAP_STATS=1
HAKMEM_TINY_HEAP_STATS_DUMP=1
HAKMEM_SMALL_HEAP_V3_STATS=1
```
- **Phase MID-V35-HOTPATH-OPT-1** (FROZEN - research only):
```sh
HAKMEM_MID_V35_HEADER_PREFILL=1     # refill境界でheader先行書き
HAKMEM_MID_V35_HOT_COUNTS=0         # alloc_count削除
HAKMEM_MID_V35_C6_FASTPATH=1        # C6特化 fast path
```
  - **Status**: Default OFF, FROZEN (all 3 knobs)
  - **Actual Results** (Phase MID-V35-HOTPATH-OPT-1 Mixed A/B):
    - Mixed (16–1024B, MID_V35_OFF): **-0.2%** (誤差範囲, ±2%以内) ✓
    - C6-heavy (257–768B, MID_V35_ON): **+7.3%** improvement ✅
  - **Finding**: Mixed は MID_V3(C6-only) 固定で効果微小；C6-heavy のみ効果大
  - **Recommendation**: C6_HEAVY_LEGACY_POOLV1 プリセットで推奨ON
  - **NOT recommended for**: MIXED_TINYV3_C7_SAFE mainline (keep all defaults OFF)
- **Phase POLICY-FAST-PATH-V2** (FROZEN - research only):
```sh
HAKMEM_TINY_FREE_POLICY_FAST_V2=1  # Fast-path free optimization
```
  - **Status**: Default OFF, FROZEN (merge complete)
  - **Actual Results** (Phase POLICY-FAST-PATH-V2 A/B):
    - Mixed (ws=400): **-1.6%** regression ❌ (added branch cost > skip benefit)
    - C6-heavy (ws=200): **+5.4%** improvement ✅
  - **Finding**: Large working set (ws>300) causes branch misprediction cost to dominate
  - **Recommendation**: Use only for C6-heavy or ws<300 research benchmarks
  - **NOT recommended for**: MIXED_TINYV3_C7_SAFE mainline (keep OFF)
  - **Requirement**: Only effective when v7 Learner is disabled
- v2 系は触らない（C7_SAFE では Pool v2 / Tiny v2 は常時 OFF）。
- FREE_POLICY/THP を触る実験例（現在の HEAD では必須ではなく、組み合わせによっては微マイナスになる場合もある）:
```sh
HAKMEM_FREE_POLICY=keep
HAKMEM_DISABLE_BATCH=1
HAKMEM_SS_MADVISE_STRICT=0
# or
HAKMEM_FREE_POLICY=batch
HAKMEM_THP=auto
```
- 参考（v4 研究箱の現状）:
  - C7/C6 v4 + fast classify v4 ON（v3 OFF, segment OFF）: **≈32.0–32.5M ops/s**（MIXED 1M/ws=400, Release）。
  - C7-only v4（C6 v1、v3 OFF）: **≈33.0M ops/s**。
  - 現状は v3 構成が最速のため、標準プロファイルでは v4 系をすべて OFF に固定。

---

## Profile 2: C6_HEAVY_LEGACY_POOLV1（mid/smallmid C6-heavy ベンチ）

### 目的
- C6-heavy mid/smallmid のベンチ用。
- C6 は v1 固定（C6 v3/v4/ULTRA は研究箱のみ）。Pool v2 OFF。Pool v1 flatten は bench 用に opt-in。

### ENV（v1 基準線 + MID v3）
```sh
HAKMEM_PROFILE=C6_HEAVY_LEGACY_POOLV1
# または直接指定:
HAKMEM_BENCH_MIN_SIZE=257
HAKMEM_BENCH_MAX_SIZE=768
HAKMEM_TINY_HEAP_PROFILE=C7_SAFE
HAKMEM_TINY_C6_HOT=0
HAKMEM_TINY_HOTHEAP_V2=0
HAKMEM_SMALL_HEAP_V3_ENABLED=1
HAKMEM_SMALL_HEAP_V3_CLASSES=0x80   # C7-only v3, C6 v3 は OFF
HAKMEM_POOL_V2_ENABLED=0
HAKMEM_POOL_V1_FLATTEN_ENABLED=0    # flatten は初回 OFF
HAKMEM_MID_V3_ENABLED=1             # Phase MID-V3: 257-768B, C6 only
HAKMEM_MID_V3_CLASSES=0x40          # C6 only (+11% on C6-heavy)
HAKMEM_MID_V35_ENABLED=1            # Phase v11a-5: C6-heavy で +8% 改善
HAKMEM_MID_V35_CLASSES=0x40         # C6 only (53.1M ops/s)

# Phase MID-V35-HOTPATH-OPT-1: C6-heavy 最速セット（推奨ON）
# 機能: header prefill + hot counts削除 + C6 fast path (組み合わせで +7.3%)
HAKMEM_MID_V35_HEADER_PREFILL=1     # refill境界でheader先行書き
HAKMEM_MID_V35_HOT_COUNTS=0         # alloc_count削除（free_count/retire残す）
HAKMEM_MID_V35_C6_FASTPATH=1        # C6特化 fast path (constant slot_size=512)
```
- mid_desc_lookup TLS キャッシュを試すときだけ: `HAKMEM_MID_DESC_CACHE_ENABLED=1` を上乗せ（デフォルトは OFF）。

### Pool v1 flatten A/B 用（LEGACY 専用）
```sh
# LEGACY + flatten ON (研究/bench専用)
HAKMEM_TINY_HEAP_PROFILE=LEGACY
HAKMEM_POOL_V2_ENABLED=0
HAKMEM_POOL_V1_FLATTEN_ENABLED=1
HAKMEM_POOL_V1_FLATTEN_STATS=1
```

## Profile 2b: C6_HEAVY_LEGACY_POOLV1_FLATTEN（mid/smallmid LEGACY flatten ベンチ専用）

### 目的
- LEGACY プロファイルで mid/smallmid の flatten + header-only zero をまとめて opt-in するベンチ専用セット。
- C7_SAFE では使わないこと（安定性優先のため C7_SAFE は flatten 常時 OFF）。

### ENV（ベンチ専用）
```sh
HAKMEM_PROFILE=C6_HEAVY_LEGACY_POOLV1    # base を流用
HAKMEM_POOL_V1_FLATTEN_ENABLED=1
HAKMEM_POOL_ZERO_MODE=header
HAKMEM_POOL_V1_FLATTEN_STATS=1
```
※ LEGACY 専用。C7_SAFE / C7_ULTRA_BENCH ではこのプリセットを使用しないこと。
- flatten は LEGACY 専用。C7_SAFE / C7_ULTRA_BENCH ではコード側で強制 OFF になる前提。

### C6 研究用プリセット（標準ラインには影響させない）

- C6 v3 研究（Tiny/SmallObject に C6 を載せるときだけ）
```sh
HAKMEM_PROFILE=C6_SMALL_HEAP_V3_EXPERIMENT
HAKMEM_BENCH_MIN_SIZE=257
HAKMEM_BENCH_MAX_SIZE=768
# bench_profile が以下を自動注入（既存 ENV を上書きしません）:
# HAKMEM_TINY_C6_HOT=1
# HAKMEM_SMALL_HEAP_V3_ENABLED=1
# HAKMEM_SMALL_HEAP_V3_CLASSES=0x40   # C6 only v3
```

- C6 v4 研究（C6 を v4 に載せるときだけ）
```sh
HAKMEM_PROFILE=C6_SMALL_HEAP_V4_EXPERIMENT
HAKMEM_BENCH_MIN_SIZE=257
HAKMEM_BENCH_MAX_SIZE=768
# bench_profile が以下を自動注入（既存 ENV を上書きしません）:
# HAKMEM_TINY_C6_HOT=1
# HAKMEM_SMALL_HEAP_V3_ENABLED=0
# HAKMEM_SMALL_HEAP_V4_ENABLED=1
# HAKMEM_SMALL_HEAP_V4_CLASSES=0x40   # C6 only v4
```

※ いずれも「研究箱」です。Mixed/C6-heavy の標準評価では使わず、回帰やセグフォを許容できるときだけ明示的に opt-in してください。

---

## Research Profile 0: C6_SMALL_HEAP_V5_STUB（SmallObject v5 C6-only route stub, Phase v5-1）

### 目的
- C6-only を SmallObject v5 route に載せるベンチ専用（v5-1 段階では挙動は v1/pool fallback）。
- ENV gate（HAKMEM_SMALL_HEAP_V5_ENABLED=1, HAKMEM_SMALL_HEAP_V5_CLASSES=0x40）で route 制御。
- front 経由で v5 通電確認＆sanity テスト（実装は v5-2 以降）。
- Mixed/C6-heavy で v1 baseline と同じ perf を期待。

### ENV（v5 C6-only opt-in）
```sh
HAKMEM_BENCH_MIN_SIZE=257
HAKMEM_BENCH_MAX_SIZE=768
HAKMEM_TINY_HEAP_PROFILE=C7_SAFE
HAKMEM_TINY_C6_HOT=0
HAKMEM_TINY_HOTHEAP_V2=0
HAKMEM_SMALL_HEAP_V3_ENABLED=1
HAKMEM_SMALL_HEAP_V3_CLASSES=0x80        # C7-only v3（C6 は v3 OFF）
HAKMEM_SMALL_HEAP_V5_ENABLED=1           # ★ v5 ON
HAKMEM_SMALL_HEAP_V5_CLASSES=0x40        # ★ C6(bit6) だけ v5 route に
HAKMEM_POOL_V2_ENABLED=0
HAKMEM_POOL_V1_FLATTEN_ENABLED=0
```

### テストコマンド
```sh
export HAKMEM_PROFILE=C6_HEAVY_LEGACY_POOLV1
export HAKMEM_SMALL_HEAP_V5_ENABLED=1
export HAKMEM_SMALL_HEAP_V5_CLASSES=0x40
./bench_random_mixed_hakmem 256 512 100  # C6 size range
./bench_mid_large_mt_hakmem 1 1000000 400 1  # pool baseline comparison
```

### 期待値
- Throughput ≈ v1 baseline（変化なし、v1 fallback の為）
- segv/assert なし
- route snapshot で C6 → TINY_ROUTE_SMALL_HEAP_V5 に分岐確認

### 注意
- v5-1 では中身は v1/pool fallback のまま（実装は v5-2）
- 本線には載せない、研究箱扱い

---

## Research Profile 1: C6_ONLY_SMALLOBJECT_V4（SmallObject v4 C6-only 試運転）

### 目的
- C6-only を SmallObject v4 route に載せて、page_meta_of() の試運転。
- 挙動はまだ pool v1 fallback のため、perf は v1 固定と同じ。
- Phase v4-mid-1: page_meta_of() が落ちないか、segv/assert なしか確認する研究ベンチ。

### ENV（v4 C6-only opt-in）
```sh
HAKMEM_BENCH_MIN_SIZE=257
HAKMEM_BENCH_MAX_SIZE=768
HAKMEM_TINY_HEAP_PROFILE=C7_SAFE
HAKMEM_TINY_C6_HOT=0
HAKMEM_TINY_HOTHEAP_V2=0
HAKMEM_SMALL_HEAP_V3_ENABLED=1
HAKMEM_SMALL_HEAP_V3_CLASSES=0x80        # C7-only v3（C6 は v3 OFF）
HAKMEM_SMALL_HEAP_V4_ENABLED=1           # ★ v4 ON
HAKMEM_SMALL_HEAP_V4_CLASSES=0x40        # ★ C6(bit6) だけ v4 route に
HAKMEM_POOL_V2_ENABLED=0
HAKMEM_POOL_V1_FLATTEN_ENABLED=0
```

### テストコマンド
```sh
export HAKMEM_PROFILE=C6_HEAVY_LEGACY_POOLV1
export HAKMEM_SMALL_HEAP_V4_ENABLED=1
export HAKMEM_SMALL_HEAP_V4_CLASSES=0x40
./bench_mid_large_mt_hakmem 1000000 400 1
```

### 期待値
- Throughput ≈ **28–29M ops/s**（v1 基線の ≈28M と同じ）
- segv/assert なし
- small_segment_v4_page_meta_of(ptr) が動く（debug output で確認可能）

### 注意
- 実際の alloc/free 動作は pool v1 のまま（v4 freelist は使わない）
- Phase v4-mid-2 で本格実装時に差し替える

---

## Research Profile 2: C7_C6_V4_EXPERIMENT（C7+C6 v4 統合研究）

### 目的
- 後続フェーズで C7+C6 両者を v4 に載せるときの参考プリセット。
- 現フェーズではまだ使わない（v4-mid-1 は C6-only）。

### ENV（参考用）
```sh
HAKMEM_BENCH_MIN_SIZE=16
HAKMEM_BENCH_MAX_SIZE=1024
HAKMEM_SMALL_HEAP_V4_ENABLED=1
HAKMEM_SMALL_HEAP_V4_CLASSES=0xC0        # C6(0x40) + C7(0x80)
```

---

## Profile 3: DEBUG_TINY_FRONT_PERF（perf 用 DEBUG プロファイル）

### 目的
- Tiny front v3（C7 v3 含む）の perf record 用。
- -O0 / -g / LTO OFF でシンボル付き計測。

### ビルド例
```sh
make clean
CFLAGS='-O0 -g' USE_LTO=0 OPT_LEVEL=0 NATIVE=0 \
  make bench_random_mixed_hakmem -j4
```

### ENV
```sh
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
HAKMEM_SMALL_HEAP_V3_ENABLED=1
HAKMEM_SMALL_HEAP_V3_CLASSES=0x80
HAKMEM_POOL_V2_ENABLED=0
HAKMEM_TINY_FRONT_V3_ENABLED=1
HAKMEM_TINY_FRONT_V3_LUT_ENABLED=1
HAKMEM_TINY_PTR_FAST_CLASSIFY_ENABLED=1
```

### perf 例
```sh
perf record -F 5000 --call-graph dwarf -e cycles:u \
  -o perf.data.tiny_front_tf3 \
  ./bench_random_mixed_hakmem 1000000 400 1
```
- perf 計測時はログを極力 OFF、ENV は MIXED_TINYV3_C7_SAFE をベースにする。

---

## Research Profile 3: C5_C6_SMALL_HEAP_V7_LEARNER（SmallObject v7 C5/C6 専用プリセット, Phase v10）

### 目的
- **C5/C6 サイズ帯専用（Mixed 本線では使わない）**
- SmallObject v7 + Learner で動的ルート最適化を検証。
- Learner がワークロード比率を監視し、C5 route を v7 ↔ MID_v3 で自動切り替え。
- Phase v10 で v7 を「C5/C6 専用プリセット」として凍結し、本プリセットで完全に管理。

### 性能実績
- C5/C6 mixed (200-500B, 300K iter):
  - **v7 + Learner: 38.7M ops/s** (+127% vs Legacy)
  - Learner route switch: C5 ratio 28% < threshold 30% → MID_v3 自動切り替え

### ENV（v7 C5/C6 opt-in）
```sh
HAKMEM_BENCH_MIN_SIZE=200
HAKMEM_BENCH_MAX_SIZE=500
HAKMEM_SMALL_HEAP_V7_ENABLED=1          # ★ v7 ON
HAKMEM_SMALL_HEAP_V7_CLASSES=0x60       # ★ C5(0x20) + C6(0x40)
# Learner は v7 enabled 時にデフォルト ON (Phase v10)
# HAKMEM_SMALL_LEARNER_V7_ENABLED=0 で個別無効化可
```

### テストコマンド
```sh
# C5/C6 混合（50/50）
HAKMEM_BENCH_MIN_SIZE=200 HAKMEM_BENCH_MAX_SIZE=500 \
  HAKMEM_SMALL_HEAP_V7_ENABLED=1 HAKMEM_SMALL_HEAP_V7_CLASSES=0x60 \
  ./bench_random_mixed_hakmem 300000 400 1

# C6 heavy（90% C6, 10% C5）→ Learner route switch トリガー
HAKMEM_BENCH_MIN_SIZE=200 HAKMEM_BENCH_MAX_SIZE=500 \
  HAKMEM_SMALL_HEAP_V7_ENABLED=1 HAKMEM_SMALL_HEAP_V7_CLASSES=0x60 \
  ./bench_allocators --allocator hakmem --scenario c6heavy --iterations 10
```

### 期待値
- Throughput: **38-39M ops/s** (C5/C6 mixed)
- Learner log: `[LEARNER_V7] C5 route switch: V7 → MID_V3` (C5 ratio < 30%)
- Route decision: `[POLICY_V7_INIT] C5: v7, C6: v7`

### 注意
- **Mixed 本線(16-1040B)では v7 OFF** (HAKMEM_SMALL_HEAP_V7_ENABLED=0)
- v7 は C5/C6 専用、他のサイズ帯には影響なし
- Learner は C5 の動的最適化のみ（C6 は固定 v7）
- Phase v10 で v3/v4/v5 削除済み（古い ENV は無視される）

---

## Research Profile 4: C6_ULTRA_INTRUSIVE_EXPERIMENT_V12（C6 ULTRA intrusive LIFO vs array magazine, Phase TLS-UNIFY-3）

**FROZEN - Research Only**: Phase TLS-UNIFY-3 validation complete.
Findings:
- C6-heavy (257-512B): +3.8% improvement ✅
- Mixed (16-1024B): -12~14% regression ❌ (policy overhead + TLS contention)
- Recommendation: Use only for C6-heavy workloads or research/debugging
- Default: OFF (MID v3/v3.5 faster for Mixed)

### 目的
- **Phase TLS-UNIFY-3 validation**: C6 ULTRA intrusive LIFO freelist と array magazine の比較。
- C6 を ULTRA path に routing し、TLS 内の LIFO 表現だけを A/B。
- ULTRA routing は MID v3/v3.5 を override するため、研究コンテキストのみで使用。

### 性能実績
- C6-heavy (257-512B, 1M iter, ws=200, 5-run mean):
  - Baseline (C6=MID v3.5): 55.3M ops/s
  - ULTRA+array (intrusive OFF): 57.4M ops/s (+3.79% vs Baseline)
  - ULTRA+intrusive (intrusive ON): 54.5M ops/s (-1.44% vs Baseline, ✅ PASS)
  - IFL stats: push=265,890 / pop=265,815 / fallback=0（perfect LIFO behavior）
- Mixed 16–1024B（標準本線）:
  - **ULTRA+intrusive は約 -14% の回帰**を確認。
  - Root cause:
    - 8 クラス(C0–C7)が 1TLS 内で競合し、C4/C5/C6/C7 の ULTRA TLS(約2KB)が奪い合い状態になる。
    - ULTRA miss が増え、Legacy fallback が約 24% に達する。
  - **結論**: Mixed 本線では C6 ULTRA を使わない（`MIXED_TINYV3_C7_SAFE` の設計どおり）。

### ENV（ULTRA intrusive opt-in）
```sh
HAKMEM_BENCH_MIN_SIZE=257
HAKMEM_BENCH_MAX_SIZE=512
HAKMEM_TINY_C6_ULTRA_FREE_ENABLED=1        # ★ C6 を ULTRA path に routing
HAKMEM_TINY_C6_ULTRA_INTRUSIVE_FL=1        # ★ intrusive LIFO freelist 有効化
HAKMEM_FREE_PATH_STATS=1                   # stats 取得用
```

### テストコマンド
```sh
# Baseline: C6=MID v3.5 (ULTRA routing なし)
HAKMEM_BENCH_MIN_SIZE=257 HAKMEM_BENCH_MAX_SIZE=512 \
  ./bench_random_mixed_hakmem 1000000 200 1

# ULTRA+array: array magazine (intrusive OFF)
HAKMEM_BENCH_MIN_SIZE=257 HAKMEM_BENCH_MAX_SIZE=512 \
  HAKMEM_TINY_C6_ULTRA_FREE_ENABLED=1 HAKMEM_TINY_C6_ULTRA_INTRUSIVE_FL=0 \
  HAKMEM_FREE_PATH_STATS=1 ./bench_random_mixed_hakmem 1000000 200 1

# ULTRA+intrusive: intrusive LIFO freelist
HAKMEM_BENCH_MIN_SIZE=257 HAKMEM_BENCH_MAX_SIZE=512 \
  HAKMEM_TINY_C6_ULTRA_FREE_ENABLED=1 HAKMEM_TINY_C6_ULTRA_INTRUSIVE_FL=1 \
  HAKMEM_FREE_PATH_STATS=1 ./bench_random_mixed_hakmem 1000000 200 1
```

### 期待値
- ULTRA+intrusive >= Baseline（or small regression < 5%）
- c6_ifl_fallback ≈ 0（intrusive LIFO が正常動作）
- c6_ultra_free/alloc > 0（ULTRA path が動作）

### 注意
- **WARNING**: ULTRA routing overrides MID v3/v3.5 - use only in research context.
- **Usage**: C6-heavy 専用の研究箱として使用（Mixed 本線では非推奨 / 回帰あり）。
- 本線には載せない、研究箱扱い。

---

### 共通注意
- プリセットから外れて単発の ENV を積み足すと再現が難しくなるので、まずは上記いずれかからスタートし、変更点を必ずメモしてください。
- v2 系（Pool v2 / Tiny v2）はベンチごとに opt-in。不要なら常に 0。
- **Phase v10**: v3/v4/v5 は削除されました（古い ENV は無視されます）。C5/C6 最適化には本プリセット(v7+Learner)を使用してください。