# Phase 6: Front FastLane（Layer Collapse）Design v1

## 0. 背景 / ねらい

直近の勝ち筋は「分岐形」ではなく **重複排除（境界の一本化）** と **ENV/TLS 読み回数の削減**だった。
一方で “削る（別バイナリ比較）” は配置/LTO の二次効果で壊れやすく **NO-GO**。

外部レビュー（ML2）では、次の芯は **Front FastLane（wrapper→gate→policy→route の Layer Collapse）**が最優先、という結論になった。

- 外部回答の記録: `PHASE_ML2_CHATGPT_RESPONSE_FASTLANE.md`
- 質問状: `PHASE_ML2_CHATGPT_QUESTIONNAIRE_FASTLANE.md`

## 1. ゴール（Box Theory）

- **Hot の入口を 1 箱に畳む**（malloc/free の “入口固定費” を減らす）
- **境界は 1 箇所**（FastLane → ColdFallback の単一フォールバック）
- **戻せる**（ENV gate で A/B）
- **見える化は最小**（hit/fallback のカウンタだけ）
- **Fail-Fast**（確信が持てないものは必ず既存経路へ）

## 2. 非ゴール（やらない）

- 凍結箱を「削除して痩せさせる」（E7 NO-GO）
  - 参照: `docs/analysis/PHASE5_E7_FROZEN_BOX_PRUNE_AB_TEST_RESULTS.md`
- “branch hint” の固定最適化（CPU/モードで逆効果になりやすい）

## 3. 形（Box 図）

```
                  (ENV: HAKMEM_FRONT_FASTLANE=0/1)
                          +---------------------+
                          | L0: FastLaneEnvBox  |
                          +---------------------+
                                     |
                                     v
  +--------------------+     +--------------------------+
  | malloc/free wrapper| --> | L1: FrontFastLaneBox      |
  | (既存のまま)        |     |  - size->class->route     |
  +--------------------+     |  - try_alloc / try_free   |
                              |  - fast: 直線 + 早期return|
                              +--------------------------+
                                 |                \
                        handled->|                 \ not-handled
                                 v                  v
                      +------------------+   +-----------------------+
                      | L1a: HotHandlers |   | L2: ColdFallbackIface |
                      | (既存を呼ぶだけ) |   | (既存 wrapper 継続)   |
                      +------------------+   +-----------------------+
```

**境界 1 箇所**: `FrontFastLaneBox` が “handled できない” と判断したら即 `ColdFallbackIface`（=既存 wrapper の続き）へ落とす。

## 4. 既存資産の再利用（重要）

FastLane を “新規で全部作る” のではなく、既に勝っている箱を **Hot 入口で 1 回だけ読む**形に揃える。

- Wrapper ENV snapshot:
  - `core/box/malloc_wrapper_env_snapshot_box.h`
  - `core/box/free_wrapper_env_snapshot_box.h`
- Tiny route snapshot:
  - `core/box/tiny_route_env_box.h`（route_kind を class ごとに決める）
- ENV snapshot consolidation（ある場合）:
  - `core/box/hakmem_env_snapshot_box.h`

方針:
- FastLane 内で “同じ判定を 2 回やらない”。
- 既存の Hot handler（例: `malloc_tiny_fast_for_class()` / `tiny_alloc_gate_fast()` / `free_tiny_fast()`）を **呼ぶだけ**に留める。

## 5. FastLane の責務（L1）

### 5.1 alloc: try_alloc(size) の責務

- size から class を決める（可能なら LUT / 1 回）
- class から route を決める（可能なら snapshot / 1 回）
- “確信が持てる”場合のみ Hot handler に直行し、成功したら即 return
- 失敗したら **即 not-handled**（Cold へ）

### 5.2 free: try_free(ptr) の責務

- **確信が持てる**場合のみ tiny free へ直行（例: header で tiny 物を fail-fast 判定できる）
- それ以外は not-handled（Cold へ）

## 6. Fail-Fast（安全ゲート）

FastLane の原則:
- “fast path に入る条件” は **必要最小**
- “fallback 条件” は **広く**

例（alloc）:
- `size <= tiny_get_max_size()`（もしくは wrapper snapshot 由来の cheap 判定）
- class が範囲内
- route が “既知の tiny hot handler で処理可能”

例（free）:
- header magic / class_idx が valid
- “tiny が確実” と言える場合のみ（曖昧なら必ず Cold）

## 7. ENV / A/B 方針

- `HAKMEM_FRONT_FASTLANE=0/1`（default 1, opt-out）
- optional:
  - `HAKMEM_FRONT_FASTLANE_CLASS_MASK=0x??`（段階導入用）

A/B:
- Mixed 10-run は必ず clean env runner を使う（ENV 漏れ防止）
  - `scripts/run_mixed_10_cleanenv.sh`

GO/NO-GO（運用）:
- GO: Mixed 10-run mean **+1.0% 以上**
- NEUTRAL: **±1.0%**（freeze）
- NO-GO: **-1.0% 以下**（rollback/freeze）

## 8. 実装方針（小パッチ順）

1. **ENV gate 箱**（default ON）
2. **FrontFastLaneBox**（alloc のみ / tiny のみ）
3. **free を追加**（tiny 直通のみ、曖昧なら落とす）
4. **最小 stats**（hit/fallback、理由は 3〜6 種類まで）
5. 健康診断 + Mixed 10-run A/B

次の具体指示は `docs/analysis/PHASE6_FRONT_FASTLANE_NEXT_INSTRUCTIONS.md` にまとめる。