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`（今後作成・拡充予定）