hakmem/docs/analysis/PHASE4_ALLOC_GATE_SPECIALIZATION_NEXT_INSTRUCTIONS.md

# Phase 4: Alloc Gate Specialization（D3 実装指示書）

Phase 3 は **D1 昇格 / D2 凍結**で完全閉鎖。次の “芯” は alloc 側の gate を削る D3。

## 現在地（SSOT）

- Active defaults（Mixed）:
  - `HAKMEM_TINY_ALLOC_ROUTE_SHAPE=1`（B3）
  - `HAKMEM_WRAP_SHAPE=1`（B4）
  - `HAKMEM_TINY_STATIC_ROUTE=1`（C3）
  - `HAKMEM_FREE_STATIC_ROUTE=1`（D1, promoted）
  - `HAKMEM_MID_V3_ENABLED=0`（Mixed 本線 SSOT）
- Frozen / ignore:
  - `HAKMEM_WRAP_ENV_CACHE=1`（D2, NO-GO）

## Status（2025-12-13）

- D3 実装: ✅ 完了（`core/box/tiny_alloc_gate_shape_env_box.h`, `core/box/tiny_alloc_gate_box.h`）
- Mixed A/B（10-run, iter=20M, ws=400）: Mean **+0.56%**（Median -0.5%）→ **NEUTRAL**
- 判定: **default OFF の research box として freeze**（本線プリセットへ昇格しない）

## Step 0: perf で “GO 条件” を満たしているか確認

判定基準: `tiny_alloc_gate_fast` が **self% ≥ 5%**。

推奨（Mixed, iter=20M, ws=400, 1T）:
```bash
HAKMEM_PROFILE=MIXED_TINYV3_C7_SAFE perf record -F 99 -- \
  ./bench_random_mixed_hakmem 20000000 400 1
perf report --stdio --no-children
```

メモ（直近の 1-run perf）:
- `tiny_alloc_gate_fast` self% ≈ **18.8%** → **D3 GO 条件は満たす**

## Step 1: D3 実装（Box Theory）

設計メモ（SSOT）: `docs/analysis/PHASE4_D3_ALLOC_GATE_SPECIALIZATION_1_DESIGN.md`

### 箱割り（必須）

- L0: ENV（戻せる）
  - `HAKMEM_ALLOC_GATE_SHAPE=0/1`（default 0）
- L1: Gate Shape（境界 1 箇所）
  - `tiny_alloc_gate_fast()` 内の分岐形だけを変更（意味は変えない）
  - `tiny_route_get()` を呼ばずに `g_tiny_route[]` を直接読む（release logging branch を避ける）
  - **Safety**: `g_tiny_route[ci] == ROUTE_POOL_ONLY` のときは必ず `NULL` を返す（`HAKMEM_TINY_PROFILE=hot/off` を壊さない）

## Step 2: A/B（GO/NO-GO）

Mixed 10-run（推奨: iter=20M, ws=400, 1T）:

- Baseline:
```bash
HAKMEM_PROFILE=MIXED_TINYV3_C7_SAFE HAKMEM_ALLOC_GATE_SHAPE=0 \
  ./bench_random_mixed_hakmem 20000000 400 1
```
- Optimized:
```bash
HAKMEM_PROFILE=MIXED_TINYV3_C7_SAFE HAKMEM_ALLOC_GATE_SHAPE=1 \
  ./bench_random_mixed_hakmem 20000000 400 1
```

判定（10-run mean）:
- GO: **+1.0% 以上**
- NO-GO: **-1.0% 以下**
- ±1.0%: NEUTRAL（研究箱維持、default OFF）

## Step 3: 昇格（GO の場合のみ）

- `MIXED_TINYV3_C7_SAFE` プリセットへ default 注入（`core/bench_profile.h`）
- `docs/analysis/ENV_PROFILE_PRESETS.md` に結果・rollback 手順を追記
- `CURRENT_TASK.md` を “Phase 4 完了” に更新

## Step 4: 失敗時の扱い（箱理論）

- NO-GO/NEUTRAL の場合:
  - D3 は research box として freeze（default OFF）
  - 本線は汚さない（プリセット昇格はしない）

## Next（次の指示）

- `perf report --no-children` で self% ≥ 5% を 1 つ選び、同じ “分岐形（shape）” 最適化を当てる
  - 現状の候補: `malloc` / `free` / `tiny_alloc_gate_fast`（ただし D3 は NEUTRAL なので “意味のある形” 以外は追わない）