# POOL_HOTBOX_V2_IMPLEMENTATION_GUIDE (Phase68 スケルトン)

目的
----
- pool allocator のホットパスを TinyHotHeap v2 と同様に Hot/Cold 分離するための実装ガイド。
- 現行 v1 をデフォルトのまま残しつつ、ENV ゲートで v2 を A/B できる形で段階的に導入する。

前提・ゲート
------------
- デフォルトは v1（`HAKMEM_POOL_V2_ENABLED=0`）。v2 は bench/研究用に opt-in。
- クラスマスクを追加する場合は `HAKMEM_POOL_V2_CLASSES`（bit per class）を想定。

実装ステップ
------------
1. 型整備（Hot Box）
   - `pool_page_v2`（freelist/used/capacity/base/meta/token）
   - `pool_class_v2`（current_page/partial_pages/full_pages/stride）
   - `pool_ctx_v2`（全クラス配列）

2. TLS 初期化
   - `pool_v2_tls_get()` を追加し、calloc + memset で ctx を用意。
   - 各クラスの block_size/stride を初期化。`max_partial_pages` 等のポリシー値もここで設定。

3. alloc/free Hot パス
   - `pool_v2_alloc(class_idx)`:
     - current → partial → refill の順で freelist pop、page 内 used++。
   - `pool_v2_free(class_idx, ptr)`:
     - page_of(ptr) を求め、freelist push / used--。
     - used==0 なら retire 判定（partial 上限を超えたら Cold へ返却）。
   - Hot パスでは OS/Stats/学習に触れない。

4. Cold IF
   - `PoolColdIface` を定義 (`refill_page`, `retire_page`)。
   - 初期実装は既存 pool/superslab の refill/retire API をラップして流用し、Hot からは IF だけを見る。

5. Gate/Route
   - front 入口は 1 LUT + switch（route）で v1/v2/legacy を選択。
   - `HAKMEM_POOL_V2_ENABLED` / classes mask で v2 を有効化し、fallback は常に v1 へ。

6. Stats/Fail-Fast
   - ENV で有効化できる軽量 stats（alloc_fast/slow/refill/fallback, free_fast/retire 等）を用意。
   - 不整合（class mismatch/範囲外）は Fail-Fast、フォールバックは明示的にカウントする。

ベンチ計画（目安）
------------------
- プロファイル: `./bench_mid_large_mt_hakmem 1 1000000 400 1`（Release, C7_SAFE, v2 OFF が基準）。
- 目標: 28–29M ops/s → 30–32M (+5〜10%)。perf stat で cycles を明確に下げる。

メモ
----
- Superslab/OS/Stats/Learning のロジックは変えない。Cold IF を挟んで境界を明確にするだけ。
- C6-heavy など特定クラスから段階的に v2 を試し、回帰が出たら即ゲートで戻せる構造を優先する。***