hakmem/docs/analysis/PHASE6_FRONT_FASTLANE_1_DESIGN.md

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 にまとめる。