hakmem/docs/analysis/PHASE3_C3_STATIC_ROUTING_1_DESIGN.md

Phase 3 C3: Tiny Static Routing（policy snapshot bypass）設計メモ

目的（なにを削るか）

malloc_tiny_fast_for_class() / tiny_alloc_gate_fast() の hot path で毎回呼ばれている small_policy_v7_snapshot()（TLS policy snapshot）と route_kind[class] ロードを 省略し、 「このプロファイルでは route が固定」という前提で class→route を静的テーブル参照に置換する。

狙いはアルゴリズム変更ではなく 形（instruction / cache / branch） の削減。

非目標（やらないこと）

• Learner の学習ロジックを hot path に混ぜない（Learning Layer の箱を汚さない）
• route の意味（ULTRA/MID/LEGACY/V7）や優先順位は変えない
• 既存の ENV の意味を変えない（A/B で戻せる）

Box Theory（箱割り）

L0: StaticRouteEnvBox（戻せる）

• ENV: HAKMEM_TINY_STATIC_ROUTE=0/1（default: 0）
• 強制無効（安全フェンス）:
  • Learner が有効な場合は自動で OFF（static route は learner の更新を反映できない）
  • LD safe / diagnostic モード等の特殊経路では OFF（wrapper 側の cold に回す）

L1: TinyStaticRouteBox（境界: 1 箇所）

責務: class_idx -> route_kind の 静的スナップショットを保持するだけ。

• データ:
  • SmallRouteKind route_kind[8]
  • inited（1 回だけ初期化）
• 初期化境界:
  • small_policy_v7_init_from_env(&tmp) を 1 回呼び、tmp.route_kind[] をコピー
  • ※ Learner の update は一切適用しない（Learner ON なら L0 で無効化）

L2: Front Integration（hot path の差し替え点）

malloc_tiny_fast_for_class() で route_kind を取る部分だけを差し替える:

if (static_route_enabled) {
  route_kind = g_tiny_static_route.route_kind[class_idx];
} else {
  route_kind = small_policy_v7_snapshot()->route_kind[class_idx];
}

以降の dispatch（B3: route shape / 従来 switch）は そのまま。

実装指示（小パッチ順序）

1. ENV gate を追加

   • HAKMEM_TINY_STATIC_ROUTE を読み、cached にする（probe window 方式は不要推奨）
   • 併せて「Learner 有効なら強制 OFF」を入れる（ENV を直に読むだけでよい）

2. TinyStaticRouteBox を追加

   • core/box/tiny_static_route_box.h/.c
   • tiny_static_route_init_once() / tiny_static_route_route_kind(class_idx) を提供

3. malloc_tiny_fast_for_class に統合

   • route_kind 取得を Box 経由に変更（static ON の時だけ bypass）
   • 既存の B3 HAKMEM_TINY_ALLOC_ROUTE_SHAPE と 合成できること（静的 route を feed するだけ）

4. ベンチ用の ENV 注入（putenv）対策

   • bench は bench_apply_profile() が putenv するため、必要なら:
     • small_policy_v7_bump_version() を bench_apply_profile() 末尾で呼び、policy snapshot が「最終 ENV」を読むようにする
     • tiny_static_route_refresh_from_env() を用意し、bench_apply_profile() の末尾で呼ぶ
   • ただし tiny_env_cfg() と同様に「初回呼び出しが bench_apply_profile 後」なら refresh は不要。
     • 先に tiny_static_route_init が走らないことを確認してから追加する（余計な分岐は増やさない）。

5. 最小可視化（debug counters のみ）

   • HAKMEM_DEBUG_COUNTERS が 1 のときだけ:
     • static_route_hit / static_route_fallback を 64-bit で増やす
   • 常時ログは禁止（ワンショットのみ許可）

GO/NO-GO ゲート（A/B）

• Mixed（HAKMEM_PROFILE=MIXED_TINYV3_C7_SAFE）10-run:
  • GO: +1.0% 以上
  • NO-GO: -1.0% 以下（freeze）
• C6-heavy（HAKMEM_PROFILE=C6_HEAVY_LEGACY_POOLV1）5-run:
  • 参考（勝っても Mixed で負けたら本線には入れない）

想定される落とし穴

• small_policy_v7_snapshot() 自体が既に十分軽い場合:
  • bypass のメリットが薄く、追加分岐が負ける（その場合は迷わず freeze）
• Learner ON の状態で static route を ON にすると:
  • route 変更が反映されず挙動がズレる → L0 で強制 OFF