hakmem/docs/analysis/LEARNING_LAYER_OVERVIEW.md

Learning Layer Overview (ACE / ELO / CAP Learner)

このドキュメントは、hakmem 内の「学習する箱」を縦に貫いて整理した総覧です。 実装は複数のファイル・フェーズに分かれていますが、Box Theory の観点では次の 3 つの箱に分解できます。

---

1. Box A: ELO + Evolution (L2 / BigCache / THP)

範囲

• サイズ帯: おおむね ≥ 2MB（BigCache / THP / batch madvise が関わる領域）
• 箱の責務:
  • 大きな割り当てに対する mmap 閾値（いつ BigCache / THP を使うか）の選択
  • 戦略候補（しきい値）間の比較と「勝ち残り」管理

実装ファイル

• core/hakmem_elo.{c,h} — ELO Rating Strategy Selection（複数のしきい値候補にレーティング）
• core/hakmem_evo.h — LEARN → FROZEN → CANARY ライフサイクル
• core/hakmem_config.{c,h} — HAKMEM_MODE と Features（HAKMEM_FEATURE_ELO, HAKMEM_FEATURE_EVOLUTION）
• core/box/mid_large_config_box.h — MID_LARGE_ELO_ENABLED マクロ（PGO/通常モード）

モード

• FROZEN（デフォルト）
  • HAKMEM_MODE=balanced / fast では features.learning に ELO は含まれるが、evo_phase = EVO_PHASE_FROZEN。
  • 戦略は事前に決めたしきい値を使い続け、ランタイムでのレーティング更新は行わない。
• LEARN（開発・研究用）
  • HAKMEM_MODE=learning / research で HAKMEM_FEATURE_EVOLUTION が有効。
  • ELO レーティングと Evolution 状態機械が動作し、しきい値を動的に調整。

Box Theory 観点

• Hot path（実際の割り当て）は「現在のしきい値」を見るだけ。
• レーティング更新・進化は 完全にオフパス（バックグラウンド） の箱に閉じ込める。
• 切り戻しは:
  • HAKMEM_MODE 変更、または HAKMEM_DISABLE_ELO=1 で ELO を丸ごと無効化。

---

2. Box B: ACE Controller (L1 Mid/Large, UCB1-based Knob Tuning)

範囲

• サイズ帯: 1KB〜2MB（L1 ACE レイヤ: Mid / Large Pool）
• 箱の責務:
  • Mid/Large Pool の TLS capacity / drain threshold / bundle width などの「ノブ」を UCB1 で自動調整。
  • 断片化ストレスや巨大ワーキングセットに対して、オフパスでキャッシュ構成を最適化。

実装ファイル

• core/hakmem_ace_controller.{c,h} — ACE Controller 本体
• core/hakmem_ace_metrics.{c,h} — メトリクス収集箱（throughput, llc_miss, backlog 等）
• core/hakmem_ace_ucb1.{c,h} — UCB1 Multi-Armed Bandit 実装
• core/box/hak_core_init.inc.h — hkm_ace_controller_init() / hkm_ace_controller_start() 呼び出し

起動条件（ENV）

• HAKMEM_ACE_ENABLED=1 で有効化（デフォルト 0）
• 主な補助 ENV:
  • HAKMEM_ACE_FAST_INTERVAL_MS（デフォルト 500ms）
  • HAKMEM_ACE_SLOW_INTERVAL_MS（デフォルト 30000ms）
  • HAKMEM_ACE_LOG_LEVEL（0=off,1=info,2=debug）

挙動

• 有効時:
  • バックグラウンドで fast-loop / slow-loop を回し、compute_reward() の結果を UCB1 に渡してノブを更新。
  • Tiny / Mid / Large のホットパスは「現在のノブ値」を読むだけで、学習ロジックには触れない。
• 無効時:
  • hkm_ace_controller_init() が早期 return し、ACE に関連するオーバーヘッドはほぼゼロ。

Box Theory 観点

• ACE は「ポリシー箱」であり、実際の割り当て/解放箱には侵入しない。
• 境界:
  • ノブの読み出しは mid_large_config_box 等の 1 箇所 から行う。
  • メトリクスの書き込みは hakmem_ace_metrics に集約（alloc/free 側は軽量カウンタ更新のみ）。

---

3. Box C: CAP/W_MAX Learner + Tiny ACE Observer

範囲

• Mid/Large Pool:
  • クラス別 CAP（ページ数 / バンドル数）と W_MAX（許容丸め率）の自動調整。
• Tiny:
  • hak_tiny_superslab_ace_observe_all() による Tiny Superslab 利用状況の観測（Phase 8.4）。

実装ファイル

• core/hakmem_learner.{c,h} — CAP/W_MAX/THP 学習スレッド
• core/hakmem_tiny_superslab.h — Tiny Superslab 監視用 API（ACE Observer）
• core/box/hak_core_init.inc.h — hkm_learner_init() 呼び出し

起動条件（ENV）

• 学習スレッド:
  • HAKMEM_LEARN=1 で有効化（デフォルト 0）。
• Tiny ACE Observer:
  • HAKMEM_ACE_OBSERVE=1 で Tiny Superslab の観測を ON。
  • 追加で HAKMEM_ACE_DEBUG=1 を付けると、観測呼び出しをログ出力。

挙動

• 学習スレッドは:
  • 一定間隔（HAKMEM_LEARN_WINDOW_MS）でヒット率をサンプリング。
  • 目標ヒット率 (HAKMEM_TARGET_HIT_MID/LARGE) とのズレに応じて CAP を増減。
  • オプションで W_MAX 候補を UCB1 で試す（HAKMEM_WMAX_LEARN=1）。
• Tiny ACE Observer は:
  • Superslab / Tiny キャッシュの利用状況をスキャンし、後続の設計/学習に使う「観測専用箱」。
  • 現時点では Tiny の動作そのものは変えず、将来の ACE-Alloc 設計のための下準備。

Box Theory 観点

• CAP/W_MAX の調整は、hakmem_learner 箱の中だけで完結。
• Mid/Large のホットパスは「現在の CAP / W_MAX」を見るだけで、学習状態を知らない。
• Tiny は「Observer に観測される側」であり、ACE が Tiny のホットパスを直接いじらない設計になっている。

---

4. モードと組み合わせ（どこまで学習させるか）

グローバルモード (HAKMEM_MODE)

• minimal:
  • ELO/ACE/CAP Learner などの学習箱はすべて OFF。
• fast / balanced（デフォルト）:
  • ELO: FROZEN（学習オフ、しきい値のみ利用）
  • ACE Controller: HAKMEM_ACE_ENABLED が 1 のときのみ動作
  • CAP Learner: HAKMEM_LEARN が 1 のときのみ動作
• learning / research:
  • ELO: LEARN + EVOLUTION 有効
  • その他の箱も ENV に応じて積極的に動く前提。

推奨パターン（論文用 / 評価用）

• Baseline:
  • HAKMEM_MODE=balanced、HAKMEM_ACE_ENABLED=0、HAKMEM_LEARN=0
• ACE only:
  • HAKMEM_MODE=balanced、HAKMEM_ACE_ENABLED=1、HAKMEM_LEARN=0
• CAP/W_MAX only:
  • HAKMEM_MODE=balanced、HAKMEM_ACE_ENABLED=0、HAKMEM_LEARN=1
• Full learning:
  • HAKMEM_MODE=learning、HAKMEM_ACE_ENABLED=1、HAKMEM_LEARN=1

各パターンのベンチ結果は、docs/benchmarks/LEARNING_AB_RESULTS.md に逐次追記していく想定です。

---

5. 関連ドキュメント

• 概要・設計:
  • docs/ACE_LEARNING_LAYER.md
  • docs/ACE_LEARNING_LAYER_PLAN.md
  • docs/design/ARCHITECTURE_DESIGN.md
• 詳細分析:
  • docs/analysis/ACE_INVESTIGATION_REPORT.md
  • docs/analysis/ACE_POOL_ARCHITECTURE_INVESTIGATION.md
  • docs/analysis/ENV_CLEANUP_ANALYSIS.md
• 論文ドラフト:
  • docs/paper/ACE-Alloc/main.md
  • メモ用: docs/paper/ACE_ALLOC_NOTES.md（今後作成・拡充予定）