hakmem/CURRENT_TASK.md

## HAKMEM 状況メモ (2025-12-05 更新 / C7 Warm/TLS Bind 反映)

### 現在の状態（Tiny / Superslab / Warm Pool）
- Tiny Front / Superslab / Shared Pool は Box Theory 準拠で 3 層構造に整理済み（HOT/WARM/COLD）。
- Tiny Gatekeeper Box（alloc/free）と Tiny Route Box により、USER→BASE 変換と Tiny vs Pool のルーティングを入口 1 箇所に集約。
- Superslab Tier Box（HOT/DRAINING/FREE）＋ Release Guard Box により、SuperSlab ライフサイクルと eager FREE の安全な境界を定義。
- Warm Pool 層:
  - `tiny_warm_pool.h`: per-thread の HOT SuperSlab プール。
  - `warm_pool_stats_box.h`: hits/misses/prefilled の統計箱。
  - `warm_pool_prefill_box.h`: registry スキャン時に Warm Pool を事前充填する cold-path helper。
- Prefault Box（`ss_prefault_box.h`）は追加済みだが、4MB MAP_POPULATE 問題を避けるためデフォルト OFF（`HAKMEM_SS_PREFAULT=0`）に設定。

### 直近の成果
- C7 TinyHeap Phase 3（stride キャッシュ＋meta-light 実装）
  - `tiny_heap_class_t` に stride キャッシュを追加し、ctx 初期化時に全クラスの stride を前計算。`tiny_heap_page_pop()` は hcls->stride を使うようにして C7 alloc の算術コストを削減。
  - free 側で class7 は「今 free した page を current_page に優先」するように変更し、alloc_slow_prepare の頻度を下げる方向に調整。
  - `HAKMEM_TINY_C7_META_LIGHT=1` で meta->used / ss_active_add/dec を per-alloc で触らないベンチ用モードを実装（デフォルト OFF、page->used は維持）。
  - ベンチ（Release, iters=20k ws=64, C7-only）:
    - legacy (`HEAP_BOX=0 HOT=1`): ≈42.5M ops/s。
    - TinyHeap front (`HEAP_BOX=1 HOT=1 LARSON_FIX=1 META_LIGHT=0`): ≈43.2M ops/s、stats=alloc_fast_current=10052 / alloc_slow_prepare=7681 / free_fast_local=10053 / free_slow_fallback=0。
    - TinyHeap front + meta-light (`META_LIGHT=1`): ≈48.1M ops/s、stats=alloc_fast_current=5837 / alloc_slow_prepare=5179 / free_fast_local=8727 / free_slow_fallback=0（active/meta の緩和によるベンチ専用モード）。
- C7 TinyHeap Phase 2（可視化＋警告抑止）
  - `HAKMEM_TINY_C7_HEAP_STATS` を追加し、C7 TinyHeap のステップ別カウンタ（alloc_fast_current/alloc_slow_prepare/free_fast_local/free_slow_fallback/alloc_prepare_fail/alloc_fail）を計測できるようにした（`HAKMEM_TINY_C7_HEAP_STATS_DUMP=1` で終了時にダンプ）。
  - `hak_alloc_at` で size==1024 かつ TinyHeap front ON の場合、Tiny lane 失敗扱いにせず `tiny_c7_alloc_fast` へフォールバック → Tiny lane failed 警告を除去。
  - TinyHeapBox に meta-light フラグ（`HAKMEM_TINY_C7_META_LIGHT`）の足場を追加（Phase3 でベンチ用実装に移行済み）。
  - Front gate の C7 分岐を TinyHeap front 優先に整理（likelyヒント付き）、C7 ラッパを `always_inline` に。
  - ベンチ: Legacy (`HEAP_BOX=0 HOT=1`) ≈43.0M ops/s。TinyHeap front ON (`HEAP_BOX=1 HOT=1 LARSON_FIX=1`) は警告なしで完走し、直近の測定では ≈34.8〜38.8M ops/s（DEBUG/環境の揺れあり）。`HAKMEM_TINY_C7_HEAP_STATS=1` でのカウンタは alloc_fast_current=10052 / alloc_slow_prepare=7681 / free_fast_local=10053 / free_slow_fallback=0 / alloc_prepare_fail=0 / alloc_fail=0。
- C7 TinyHeap front の SLL 切り離し（再現 SEGV 対応）:
  - `tiny_c7_heap_mode_enabled()` を追加し、`HAKMEM_TINY_HEAP_BOX=1 HAKMEM_TINY_C7_HOT=1` のときは C7 を完全に TinyHeapBox ルートへ固定。
  - `sll_refill_small_from_ss()` / `sll_refill_batch_from_ss()` で C7 を即 return する早期ゲートを追加し、`hak_tiny_prewarm_tls_cache()` でも C7 の TLS SLL prewarm をスキップ。
  - `tls_sll_push_impl()` に C7 + TinyHeap front の拒否ガードを入れ、万が一 push が来ても SLL を触らないようにした。
  - 旧 slow path (`hak_tiny_alloc_slow`) で C7 + TinyHeap front の場合は TinyHeapBox に委譲し、レガシー slow 経路を通さないようにした。
  - ベンチ: `HAKMEM_BENCH_C7_ONLY=1`、`HAKMEM_TINY_HEAP_BOX=1 HAKMEM_TINY_C7_HOT=1` で 20k ループ完走 (≈42–46M ops/s)。`HAKMEM_TINY_SLL_LOG_ANY=1` を付けても C7 の TLS SLL ログはゼロ。レガシー (`HEAP_BOX=0`) も同条件で ≈41.8M ops/s で回帰なし。
- TinyHeapBox 導入 (C7 先行 A/B):
  - `core/box/tiny_heap_box.h` で mimalloc 風 TinyHeap（current/partial/full + page 内 freelist）を Box 化。TLS `g_tiny_heap_ctx` に全クラスのヒープを保持し、下層 Box との接続は slow 境界 1 箇所に限定。
  - C7HotBox は薄いラッパ (`tiny_c7_alloc_fast` / `tiny_c7_free_fast_with_meta` / `tiny_c7_page_of` など) に縮退させ、ENV `HAKMEM_TINY_HEAP_BOX=1` かつ `HAKMEM_TINY_C7_HOT=1` で Gate から class7 を TinyHeap front に切替。
  - free 側は Larson 判定に関係なく、self-thread なら meta 渡しで即 TinyHeap free、owner mismatch は remote queue、lookup 失敗時は `tiny_c7_free_fast()` にフォールバック。
  - docs 追記: `docs/analysis/C7_HOTBOX_DESIGN.md` に TinyHeapBox 移行メモを追加、新規 `docs/analysis/TINY_HEAP_BOX_DESIGN.md` に構造/責務/ENV/今後の移行ステップを整理。
  - ベンチ/テスト:
    - `make -j4 bench_random_mixed_hakmem` ビルド成功。
    - C7-only (`HAKMEM_BENCH_C7_ONLY=1 HAKMEM_TINY_HEAP_BOX=0 HAKMEM_TINY_C7_HOT=1 ./bench_random_mixed_hakmem 20000 64 1`) → ≈42.95M ops/s。
    - TinyHeap front ON (`HAKMEM_TINY_HEAP_BOX=1 HAKMEM_TINY_C7_HOT=1`): 2k/5k/8k までは完走 (≈34–44M ops/s) するが、9k 以上で `tls_sll_push_impl` SEGV が再現。valgrind では 10k 完走するため、SLL 周りの防御/初期化順を後続フェーズで要調査。  
- C7 HotBox Phase 1.1（lookup 削減）:
  - free ホットパスに `tiny_c7_free_fast_with_meta(ss, slab_idx, base)` を追加し、Larson fix (`HAKMEM_TINY_LARSON_FIX!=0`) で owner==self と判定できた場合のみ Superslab lookup を再実行せずに即 free。cross-thread は従来どおり remote queue、Larson fix OFF か lookup 失敗時は UC 経路にフォールバック。
  - `tiny_c7_page_of()` を TLS fast-first 化し、self-thread の C7 slab なら `hak_super_lookup`/`slab_index_for` を呼ばずに attach するようにした。
  - C7-only ベンチ（Release, `HAKMEM_BENCH_C7_ONLY=1 HAKMEM_TINY_LARSON_FIX=1 ./bench_random_mixed_hakmem 20000 64 1`）で `HAKMEM_TINY_C7_HOT=0 → ≈42.4M ops/s`, `HOT=1 → ≈40.6M ops/s`（まだ -4% なので次フェーズで平滑化を続行）。
- C7 HotBox（C7 専用 TinyHeap）の骨格追加:
  - `core/box/tiny_c7_hotbox.h` に C7 ページ/ヒープ構造 (`tiny_c7_page_t`, `tiny_c7_heap_t`) とホットパス API (`tiny_c7_heap_for_thread`, `tiny_c7_alloc_fast`, `tiny_c7_alloc_slow_from_heap`, `tiny_c7_free_fast`, `tiny_c7_page_becomes_empty`) を実装。TLS ごとに current/partial/full を持つ箱に閉じ込めた。
  - Gate は `size==1024 && HAKMEM_TINY_C7_HOT=1` のときのみ C7HotBox へ分岐。オフ時は従来経路へフルフォールバックできる。
  - 設計メモ `docs/analysis/C7_HOTBOX_DESIGN.md` を追加し、目的/構造/フロー図/A/B ポリシーを整理。
  - ベンチは未実施（C7-only/C7-hot=1/0 のスモークを後続で実行予定）。
- Gatekeeper inlining（Phase A-1）完了：`malloc`/`free` ラッパの関数呼び出しを削減しつつ、Box 境界は維持。
- Unified Cache Refill の debug 検証を 1 箇所に集約し、リリースビルドの HOT パスを軽量化：
  - `bench_random_mixed_hakmem 1000000 256 42` が約 4.3M → 5.0M ops/s（~+17%）に改善。
- Tiny-only/Tiny Mixed / Non-Tiny の条件差分をドキュメント化・分離：
  - `bench_random_mixed_hakmem` に `HAKMEM_BENCH_MIN_SIZE` / `HAKMEM_BENCH_MAX_SIZE` を追加し、
    - 8–128B（Tiny-only）
    - 129–1024B（Tiny C5–C7 専用）
    を個別に測定可能にした。
  - `docs/PERF_ANALYSIS_TINY_MIXED.md` ほかに、8–128B/200K/ws=400（旧 Tiny 専用）と現在の 16–1024B/1M/ws=256（Tiny+Non-Tiny 混在）の違いを明記。
- Unified Cache Refill 安全化（Step 1 完了）:
  - `core/front/tiny_unified_cache.c` の `unified_cache_refill()` で `max_batch <= 256` を保証し、`out[256]` と常に整合するよう修正。
  - C5〜C7 の Unified Cache 容量・バッチサイズを増やす実験を行ってもスタック破壊が起きない状態にした。
- Tiny Page Box（C7 Tiny-Plus 層）の導入（Step 2 第1段階完了）:
  - `core/box/tiny_page_box.h` / `core/box/tiny_page_box.c` を追加し、`HAKMEM_TINY_PAGE_BOX_CLASSES` で有効クラスを制御できる Page Box を実装。
  - `tiny_tls_bind_slab()` から `tiny_page_box_on_new_slab()` を呼び出し、TLS が bind した C7 slab を per-thread の page pool に登録。
  - `unified_cache_refill()` の先頭に Page Box 経路を追加し、C7 では「TLS が掴んでいるページ内 freelist/carve」からバッチ供給を試みてから Warm Pool / Shared Pool に落ちるようにした（Box 境界は `Tiny Page Box → Warm Pool → Shared Pool` の順序を維持）。
- TinyClassPolicy/Stats/Learner Box を追加し、Hot path は `tiny_policy_get(class_idx)` で Page/Warm ポリシーを読むだけに統一。
  - FROZEN デフォルト（legacy プロファイル）：Page Box は C5〜C7 のみ ON、Warm は C0〜C7 すべて ON（C0〜C4 cap=4、C5〜C7 cap=8）。
  - ENV `HAKMEM_TINY_POLICY_PROFILE=legacy|c5_7_only|tinyplus_all` で切替可能（未指定は legacy）。
  - Stats は OBSERVE 用に積むだけ、Learner は空実装のまま。
- mimalloc/system との最新ベンチ (Release, prefault デフォルト, policy=legacy, mode=2) を README_PERF に追記。C7-only 48.8M vs mimalloc 95.3M / system 73.9M、129–1024B 50.0M vs 128.4M / 97.7M、full 50.9M vs 123.6M / 83.5M、Tiny-only 8–128B 93.2M vs 123.7M / 66.3M。
- TLS Bind Box の導入:
  - `core/box/ss_tls_bind_box.h` に `ss_tls_bind_one()` を追加し、「Superslab + slab_idx → TLS」のバインド処理（`superslab_init_slab` / `meta->class_idx` 設定 / `tiny_tls_bind_slab`）を 1 箇所に集約。
  - `superslab_refill()`（Shared Pool 経路）および Warm Pool 実験経路から、この Box を経由して TLS に接続するよう統一。
- C7 Warm/TLS Bind 経路の実装と検証:
  - `core/front/tiny_unified_cache.c` に C7 専用の Warm/TLS Bind モード（0/1/2）を追加し、Debug では `HAKMEM_WARM_TLS_BIND_C7` で切替可能にした。
  - mode 0: Legacy Warm（レガシー/デバッグ用、C7 では carve 0 が多く非推奨）
  - mode 1: Bind-only（Warm から取得した Superslab を TLS Bind Box 経由でバインドする本番経路）
  - mode 2: Bind+TLS carve（TLS から直接 carve する実験経路）
  - Release ビルドでは常に mode=1 固定。Debug では `HAKMEM_WARM_TLS_BIND_C7=0/1/2` で切替。
- Warm Pool / Unified Cache の詳細計測:
  - `warm_pool_dbg_box.h` と Unified Cache の計測フックを拡張し、C7 向けに
    - Warm pop 試行/ヒット/実 carve 回数
    - TLS carve 試行/成功/失敗
    - UC ミスを Warm/TLS/Shared 別に分類
    を Debug ビルドで観測可能にした。
  - `bench_random_mixed.c` に `HAKMEM_BENCH_C7_ONLY=1` を追加し、C7 サイズ専用の micro-bench を追加。
- TinyClassPolicy / Stats / Learner Box の導入（初期フェーズ）:
  - `core/box/tiny_class_policy_box.{h,c}` にクラス別ポリシー構造体 `TinyClassPolicy` と `tiny_policy_get(class_idx)` を追加。
    - FROZEN デフォルト: Page Box = C5–C7, Warm = 全クラス（C0–C4 cap=4 / C5–C7 cap=8）。
    - `HAKMEM_TINY_POLICY_PROFILE=legacy|c5_7_only|tinyplus_all` でプロファイル切替可能（未知値は legacy にフォールバック）。
- `core/box/tiny_class_stats_box.{h,c}` に OBSERVE 用の軽量カウンタ（UC miss / Warm hit / Shared Pool lock など）を追加。
  - `core/box/tiny_policy_learner_box.{h,c}` に Learner の骨組みを追加（現状は FROZEN/OBSERVE モード向けの雛形）。
  - `core/front/tiny_unified_cache.c` / Page Box / Warm Pool 経路を `tiny_policy_get(class_idx)` ベースでゲートし、Hot path からは Policy Box を読む形に統一。
- `bench_random_mixed` に RSS ダンプ（`getrusage(RUSAGE_SELF).ru_maxrss`）を追加し、各 allocator で ops/s と合わせて常駐メモリを記録できるようにした。  
- 新規比較表 `PERF_COMPARISON_ALLOCATORS.md` を追加。C7-only / 129–1024B / 16–1024B で HAKMEM(full/larson_guard) は ~50M ops/s / ~29MB RSS、system は ~95–78M ops/s / ~1.6MB RSS、mimalloc は ~74–126M ops/s / ~1.8MB RSS。  
- SS stats (HAKMEM_SS_STATS_DUMP=1, full profile, 16–1024B ws=256/1M): live Superslab は C2=1, C7=1（empty_events: C7=1）、RSS は ~29MB。予算を 2 に絞っても同じ配置で RSS 変化なし → RSS は Superslab 枚数より TLS/Warm/Page stack 等の常駐分が支配的。  

### 性能の現状（Random Mixed, HEAD）
- 条件: Release, `HAKMEM_TINY_PROFILE=full HAKMEM_WARM_TLS_BIND_C7=2 HAKMEM_WARM_C7_MAX=8 HAKMEM_WARM_C7_PREFETCH=4`, ws=256
  - **C7-only (size=1024, iters=200K, ws=32)**  
    - policy=legacy: 47.3M / 47.3M / 43.9M ops/s（平均 ≈ **46M**）。C7 uc_miss=6660 / warm_hit=3329 / shared_lock=5 / tls_carve_success=3329。  
    - policy=auto（Learner: score=lock*4+miss）: 45.6M / 44.6M / 39.7M ops/s（平均 ≈ **43–45M**）、統計は legacy と同一（C7 固定 ON）。  
    - guard 比較: full **42.4M ops/s** vs larson_guard **40.7M ops/s**（-4%程度で安全側ガードを維持）。  
  - **129–1024B (iters=1M, ws=256)**  
    - legacy: **51.5M ops/s**。C5 uc_miss=1/warm_hit=0/shared_lock=1、C6 uc_miss=1/warm_hit=0/shared_lock=2、C7 uc_miss=17196/warm_hit=8597/shared_lock=5/tls_carve_success=8597。  
    - auto: **51.9M ops/s**（Learner=lock 重視でも C7 のみ ON、統計ほぼ同じ）。  
    - guard 比較: full **49.0M ops/s** vs larson_guard **48.4M ops/s**（-1.2%）。  
  - **full random_mixed 16–1024B (iters=1M, ws=256)**  
    - legacy: **51.0M ops/s**。C7 uc_miss=16702/warm_hit=8350/shared_lock=5/tls_carve_success=8350（C5/C6 は uc_miss=1〜2）。  
    - auto: **50.0M ops/s**（C7 固定 ON のまま、他クラスはほぼ動かず）。  
- 補足:
  - WarmPool-STATS と TinyClassStats を統合。`HAKMEM_WARM_POOL_STATS=1` で C7-only 実行時に hits=3329 / misses=1 / prefilled=1 を確認（TinyClassStats の warm_hit=3329 と一致）。
  - `TinyClassPolicy` に `tls_carve_enabled` を追加し、デフォルトで C5–C7 を ON。`TinyClassStats` に tls_carve_attempt/success を追加済み。
  - Learner のスコアを `score = shared_lock * 4 + uc_miss` に変更済み（auto プロファイル専用）。現状のワークロードでは C7 が圧倒的に優勢で、C5/C6 はまだほぼ選ばれない。

### サイズ→クラス対応（HAKMEM_TINY_HEADER_CLASSIDX=1 のため size+1 で判定）
- `hak_tiny_size_to_class(size)` は `needed=size+1` で `g_size_to_class_lut_2k` を引くため、512B 要求は 513B として class 7 判定になる（現状の挙動は仕様どおり）。
- 代表サイズのマップ（データサイズ→class_idx / 総バイト数）  
  - 8B → C1（16B stride）  
  - 16B → C2（32B）  
  - 32B → C3（64B）  
  - 64B → C4（128B）  
  - 128B → C5（256B）  
  - 256B → C6（512B）  
  - 512B → C7（2048B stride / 32 blocks per slab）  
  - 1024B → C7（同上）  
- 512B 固定ベンチで C7 経路が動くのはこのヘッダ加算による設計上の結果。現時点では「C7 支配」を前提に C5/C6 は拡張枠として観測を続ける。

### C5/C6 専用ワークロードの速報（Release, ws=512, iters=1,000,000, size fixed）
- 条件: `HAKMEM_BENCH_MIN_SIZE=256 HAKMEM_BENCH_MAX_SIZE=256 (実質 C6)`、`HAKMEM_TINY_PROFILE=full`、`HAKMEM_WARM_TLS_BIND_C7=2`、`HAKMEM_TINY_STATS_DUMP=1`
  - policy=legacy: Throughput ≈ **89.9M ops/s**。C6: uc_miss=5, warm_hit=1, shared_lock=2, tls_carve_attempt=1, tls_carve_success=1。
  - policy=auto: Throughput ≈ **87.5M ops/s**。C6 の統計はほぼ同じ（uc_miss=5, warm_hit=1, tls_carve_attempt/success=1）。C5 ほぼ負荷なし。
- 補足: C5/C6 はワーキングセットを広げても Warm/TLS carve のヒットは少数（キャッシュヒット優位なため）。専用負荷を増やす場合はさらに ws を広げて観測予定。
- Larson ベンチ（Release, 10 runs, `./test_larson.sh`）  
  - profile=full: 1.15〜1.26M ops/s  
  - profile=larson_guard: 1.10〜1.27M ops/s（≈-3〜0%でほぼ同等）。`HAKMEM_SS_STATS_DUMP=1` で Superslab live が 1 前後に収まり、SEGV/OOM なし。サンプルログは `docs/analysis/SUPERSLAB_STATS_SNAPSHOT.md` に記録。

### 新しいログ/ENV スイッチ
- `HAKMEM_TINY_POLICY_LOG=0/1`: Policy 初期化/auto update のログ抑制（デフォルト ON）。
- `HAKMEM_TINY_WARM_LOG=0/1`: C7 prefill 関連ログ（PREFILL_META/skip 等）の抑制（デフォルト ON）。
- `HAKMEM_TINY_PAGEBOX_LOG=0/1`: Page Box の登録ログ抑制（Debug のみ、デフォルト ON）。
- 長時間ラン時は上記を 0 にしてノイズを抑える運用を推奨。短時間デバッグ時のみ 1 にする。

### 次にやること（広い条件での安定化確認）
1. `HAKMEM_BENCH_MIN_SIZE=129 HAKMEM_BENCH_MAX_SIZE=1024` や通常の `bench_random_mixed_hakmem 1000000 256 42` で
   空スラブ限定ガードが副作用なく動くかを継続確認（現状 Release で 29–30M ops/s を確認済み）。
2. ドキュメント更新:
   - Release だけ C7 Warm が死んでいた根本原因 = 満杯 C7 slab を Shared Pool がリセットせず再供給していた。
   - Acquire の空スラブ強制ガード＋Stage3(LRU) 再利用時の Superslab 全スロットリセット＋Warm/TLS carve 有効化で、
     C7-only Release が ~20–25M ops/s クラスに回復し、Random Mixed 16–1024B Release も ~29–30M ops/s クラスまで改善した。
3. 次フェーズ案:
   - Superslab ガード（Stats/Reset/Stage3/Budget/larson_guard）まで完了。以降は mimalloc/system との比較最適化や、必要に応じた C5/C6 Tiny-Plus 拡張を検討。

### 次フェーズ（Tiny 全クラス向け Page Box / Warm / Policy 汎用化の検討）
- 方向性:
  - 現在は C7 向け Tiny-Plus（Page Box + Warm Pool + TLS Bind）が安定したため、C1〜C7 まで「候補」として広げつつ、
    実際にどのクラスで有効化するかは Policy Box（学習/ENV）側で制御する設計に進める。
- 設計方針（案）:
  - `TinyClassPolicyBox` を新設し、クラス別ポリシー構造体（`TinyClassPolicy{ page_box_enabled, warm_enabled, warm_cap, ... }`）を配列で保持。
  - Hot path（Tiny Front / Unified Cache / Page Box / Warm Pool）は `tiny_policy_get(class_idx)` でポリシーを読むだけにし、
    学習/更新は `TinyPolicyLearnerBox` 側で行う。
  - `TinyClassStatsBox` を導入し、クラス別に UC miss / warm hit / shared_pool_lock などの軽量カウンタを記録（OBSERVE/LEARN モード用）。
  - モードは FROZEN / OBSERVE / LEARN を ENV で切替可能にし、デフォルトは FROZEN（C5–C7 のみ Page Box/Warm ON, 他クラス OFF）。
- 実装ステップ（案）:
  1. C7 Page Box / Warm / TLS Bind の API を「class_idx を引数に取る汎用形」に整理し、内部で `if (!policy->page_box_enabled) fallback` する形にリファクタ。
  2. `TinyClassPolicy` struct と `tiny_policy_get(class_idx)` を導入し、Hot path から直接 `HAKMEM_*` ENV を参照しないようにする（Policy Box 経由に統一）。
  3. `TinyClassStatsBox` を追加し、FROZEN/OBSERVE モードで C1〜C7 の stats を集計（policy はまだ固定）。
  4. `TinyPolicyLearnerBox` を追加し、LEARN モードで stats をもとに `page_box_enabled[]` / `warm_cap[]` を更新（ただし「同時に ON にできるクラス数」に上限を設ける）。
- 進捗メモ（実装済み）:
  - `TinyClassPolicyBox`/`TinyClassStatsBox`/`TinyPolicyLearnerBox` を追加し、デフォルトで C5〜C7 に Page Box + Warm を許可（Warm cap=8）。  
  - unified_cache_refill の Page/Warm 経路は `tiny_policy_get()` の返り値でゲートし、Warm push は per-class cap を尊重。  
  - Page Box 初期化もデフォルトで C5〜C7 を有効化。OBSERVE 用の軽量 stats increment を UC miss / Warm hit に接続済み。
- 次ステップの設計メモ:
  - TinyPageBoxContext を class 汎用構造に広げ、C5/C6 も「TLS Bind で page 登録 → UC refill で page 内 freelist からバッチ供給」を C7 と共有できるようにする（実装は未着手、設計メモのみ）。

### メモ
- ページフォルト問題は Prefault Box + ウォームアップで一定水準まで解消済みで、現在の主ボトルネックはユーザー空間の箱（Unified Cache / free / Pool）側に移っている。
- 以降の最適化は「箱を削る」ではなく、「HOT 層で踏む箱を減らし、Tiny 的なシンプル経路と Tiny-Plus 経路（Page Box + Warm）をクラス別ポリシーでどう使い分けるか」にフォーカスする。

### 今回の変更（C7 meta-light をページ境界バッチ flush 化）
- `tiny_heap_page_t` に C7 用の delta (`c7_active_delta` / `c7_used_delta`) を追加し、meta-light ON 時は per-alloc で meta/active を触らず delta のみ更新。
- ページが empty になる/ノード解放時に `tiny_c7_meta_flush_page()` で delta をまとめて meta->used / total_active_blocks に反映。負側は `ss_active_dec_one` を繰り返す素朴実装（ベンチ頻度は低い前提）。
- `HAKMEM_TINY_C7_META_LIGHT` は依然 bench/研究用。デフォルト OFF。本番統計は OFF 時と同じ挙動を維持。
- C7-only 20k/ws64 ベンチ: legacy (HEAP_BOX=0 HOT=1) ≈41.2M ops/s、TinyHeap front META_LIGHT=0 ≈41.9M ops/s、META_LIGHT=1（バッチ） ≈53.5M ops/s。stats: META_LIGHT=1 で alloc_fast_current=11013 / alloc_slow_prepare=3 / free_fast_local=9294。

## 今後のフォーカス（C7 支配を前提に一旦整理）
- 設計明記: 257–512→C6, 513–2048→C7（size+1 判定）。実負荷は C7 が受ける設計として確定。C5/C6 は拡張枠・観測対象。
- 優先度: C5-only ≈91M ops/s、512B 固定も C7 経路で ≈47M ops/s → C5/C6 最適化は auto/実験用に留め、本命は C7 Tiny-Plus＋Policy。
- プロファイル運用: legacy=本番、auto=C7固定＋上位2クラス観測用のまま据え置き。学習拡張は新ワークロードで C5/C6 がホットになった際に検討。
- 次の大きな箱候補: (1) mimalloc/system とのフルベンチ整理（論文/README 更新）、(2) hakorune 側 PHI/JoinIR の開発にリソースを戻す。

## 巨大 BSS グローバルの棚卸しと今後

- `nm -S --size-sort bench_random_mixed_hakmem` と SS_STATS のサンプルから、RSS を支配しているのは Tiny 層ではなく巨大 BSS 配列であることを確認。
  - 代表例: `g_super_reg` ≈24MB, `g_shared_pool` ≈2.3MB, `g_super_reg_by_class` ≈1MB, `g_rem_side` ≈1MB など。
  - SS_STATS（ws=64, iters=10k）では live Superslab は C2=1, C7=1 程度で、巨大レジストリの大半は未使用キャパシティになっている。
  - Tiny 用メモリ会計 Box（`tiny_mem_stats_box`）では UC/Warm/Page/TLS/Policy-Stats 合計でも ≈40KB 程度と判明し、RSS≈29MB の主因ではないことを確認。
- docs/analysis/LARGE_GLOBALS_OVERVIEW.md に各大型シンボルのサイズ/役割と SS_STATS とのギャップを一覧化済み。

次フェーズ候補:
- Superslab Registry / Shared Pool / Remote Queue を Box 化し、プロファイル別に「必要なだけ動的確保」できる SuperRegBox / SharedPoolBox / RemoteSideBox への移行を検討。
- `HAKMEM_PROFILE` や ENV から「bench 向け縮小設定」と「本番向けフル設定」を切り替えられるようにし、RSS を抑えつつ Box 構造は維持する。

進捗（巨大BSS Box化フェーズ）
- docs/analysis/LARGE_GLOBALS_OVERVIEW.md に大型シンボルの定義元・役割・縮小目安を追記（SuperReg/SharedPool/Remote など）。
- 設計スタブを追加:
  - `core/box/super_reg_box.h` … レジストリ容量をプロファイルで切替するための API メモ。
  - `core/box/shared_pool_box.h` … Shared Pool の容量/ガードをプロファイルに紐づけるための API メモ。
  - `core/box/remote_side_box.h` … Remote Queue テーブルをプロファイルで縮小するための API メモ。
- `HAKMEM_PROFILE=bench` を追加し、SuperReg/SharedPool/Remote の「論理有効スロット」を 1/8〜1/16 に制限するラッパを実装（配列は現状サイズのまま）。`bench_random_mixed_hakmem` は full/bench ともビルド・完走済み。C7-only/129–1024B/16–1024B で ops/s は ±数% 以内、RSS は ~32.6MB でほぼ不変（論理制限のみのため）。  
- SuperReg/Remote を Box 内で動的確保に置き換え、`HAKMEM_PROFILE=bench` では実容量も縮小（SuperReg: 1/8〜1/16、Remote: log2 を 12〜）。C7-only 200k/ws32 では full=29.6MB → bench=7.2MB (ops ≈44.4M 同レンジ) まで RSS を削減できた。
- bench 実容量版での広いワークロード検証: 129–1024B ws=256/1M は full=48.9M ops/s & 29.6MB → bench=49.2M & 7.2MB。16–1024B ws=256/1M は full=48.3M & 29.7MB → bench=48.8M & 7.2MB。SS_STATS（bench）でも live Superslab は C2=1, C7=1 に収まり、Tiny 層メモリは ~41KB のまま。
- 次ステップ: SharedPool 側も必要なら動的化/縮小を検討しつつ、RSS をさらに攻めるか、CPU パス最適化に戻るか判断。***

### フェーズ整理と次の方針
- SharedPool は現状サイズを維持し、`HAKMEM_PROFILE=full` を本番、`HAKMEM_PROFILE=bench` を対 mimalloc/system の軽量プロファイルとして運用（bench は SuperReg/Remote 縮小済み、RSS≈7.2MB）。
- 巨大BSS Box化フェーズは「bench で RSS≈7.2MB / ops≈同等」まで完了。今後は perf（CPUサイクル）最適化にフォーカス。

### Phase 5: C7 delta debug フック（meta-light バッチ版）
- `core/box/tiny_heap_box.h` に `HAKMEM_TINY_C7_DELTA_DEBUG` ゲートと `tiny_c7_heap_debug_dump_deltas()` を追加。meta-light ON 時に page ごとの `c7_used_delta` / `c7_active_delta` を stderr へダンプできるようにした。
- `core/hakmem_tiny.c` に destructor フックを追加し、`HAKMEM_TINY_C7_META_LIGHT=1 HAKMEM_TINY_C7_DELTA_DEBUG=1` でベンチ終了時に自動チェック（1 スレッド前提で TLS TinyHeap ctx を走査）。
- ベンチ (C7-only, ws=64, Release):
  - 20k: legacy (HEAP_BOX=0 HOT=1) ≈39.7M ops/s、TinyHeap META_LIGHT=0 ≈39.9M、META_LIGHT=1 ≈54.0M。
  - 100k: TinyHeap META_LIGHT=0 ≈39.9M、META_LIGHT=1+DELTA_DEBUG ≈51.3M（delta 残: idx0 used_delta=7669 active_delta=7669 used=6）。
  - 200k: TinyHeap META_LIGHT=1+DELTA_DEBUG ≈48.1M（delta 残: idx0 used_delta=14727 active_delta=14727 used=6）。
- delta debug から、長時間ランでも live page に delta が積み上がる（empty/release でのみ flush する設計のため）ことを確認。次フェーズで閾値 flush や partial→current の切替タイミング改善を検討する。

### Phase 6: C7 delta 閾値 flush + clamp
- `tiny_c7_delta_should_flush()` を追加し、C7 meta-light ON かつ `|delta| >= max(256, capacity*16)` でホットパスから `tiny_c7_meta_flush_page()` を実行。per-alloc atomic なしで delta を capacity の数倍にバウンド。
- `tiny_heap_attach_page()` で C7 meta-light 時に `used` を `capacity` へ clamp（c7_delta も 0 クリア）し、過去ラン由来の巨大 meta->used でも TLS ノードを安全に再利用。
- ベンチ (C7-only ws=64, Release):
  - Legacy HEAP_BOX=0 HOT=1: ≈42.5M ops/s
  - TinyHeap HEAP_BOX=1 HOT=1 LARSON_FIX=1 META_LIGHT=0: ≈43.1M ops/s
  - TinyHeap META_LIGHT=1 (閾値 flush/clamp): ≈42.6M ops/s
- 長時間 delta debug（META_LIGHT=1 DELTA_DEBUG=1）:
  - 100k/200k: `[C7_DELTA_SUMMARY] nonzero_pages=0 used_delta_sum=0 active_delta_sum=0`（delta 残なし）

### Phase 7: TinyHeap クラス選択（C6 載せ替えの土台）
- ENV `HAKMEM_TINY_HEAP_CLASSES`（bitmask、デフォルト 0x80=C7 のみ）を追加。`tiny_heap_class_route_enabled(cls)` で TinyHeap front を使うクラスを切替。
- Front gate: `malloc_tiny_fast` / `free_tiny_fast` でクラスごとに TinyHeap ルートを選択。C7 は従来通り `tiny_c7_heap_mode_enabled()`（HAKMEM_TINY_C7_HOT 連動）でガードし、それ以外のクラスは `tiny_heap_alloc/free_class_fast()` を呼ぶ経路を追加。
- TLS SLL との分離をクラス単位に拡張: `sll_refill_small_from_ss` / `sll_refill_batch_from_ss` / `hak_tiny_prewarm_tls_cache` は `tiny_heap_class_route_enabled(cls)` のとき即 return/skip（C6 も TinyHeap に載せたら SLL を経由しない）。
- ドキュメント: TinyHeapBox/C7HotBox 設計にクラス bitmask と multi-class 対応の方針を追記。ベンチは今後 C6/C7 切替パターンで再計測予定。  

ホットパス perf フェーズの TODO（案）
1. tiny_alloc_fast / tiny_free_fast_v2 の再プロファイル：残存分岐・間接呼び出し・重い箱を特定。
2. Unified Cache ヒットパスを最短化：ヒット時を 1–2 load + 軽分岐に近づける（必要なら C7 専用インライン版検討）。
3. free パス Gatekeeper/Box の再配線：C7 ホットケースだけ分岐極小のストレートラインにする。

目標: シングルスレッド小オブジェクトで ~50M ops/s → 70M〜80M 帯を狙う（mimalloc との差を半減イメージ）。***

補足（CPU ホットパス観測メモ）
- `HAKMEM_PROFILE=bench HAKMEM_TINY_PROFILE=full HAKMEM_WARM_TLS_BIND_C7=2` で perf を試行したが、`perf_event_paranoid` 制約で `cycles` が取れず page-fault サンプルのみ（`__memset_avx2_unaligned_erms` が warmup を支配）。`perf.data` は即削除済み。集計結果と次の測定案は `docs/analysis/CPU_HOTPATH_OVERVIEW.md` に記載。
- C7 alloc/free flattening と UC ヒット簡略化の設計メモを追加：`docs/analysis/C7_HOTPATH_FLATTENING.md`, `docs/analysis/C7_FREE_HOTPATH.md`。実装はこれから。
- C7 HotBox を追加（`core/box/tiny_c7_hotbox.h` + `HAKMEM_TINY_C7_HOT`）。size==1024 のときだけ C7 専用 TinyHeap に直結し、per-thread ヒープ内の current_page→free_list pop で完結させる経路を用意。ベンチ/IPC 計測は後続。  

### C7 ホットパス平坦化（第1段階）の結果メモ
- `HAKMEM_PROFILE=bench HAKMEM_TINY_PROFILE=full HAKMEM_WARM_TLS_BIND_C7=2`、129–1024B ws=256/1M（Release）で:
  - `HAKMEM_TINY_C7_HOT=0`: ≈49.7M ops/s
  - `HAKMEM_TINY_C7_HOT=1`: ≈46.7M ops/s（分岐ミスは僅かに改善するがスループットはノイズ〜微減）
- 16–1024B ws=256/1M では:
  - hot=0: ops≈47.4M, IPC≈2.13, br-miss≈2.90%
  - hot=1: ops≈47.4–47.6M, IPC≈2.16, br-miss≈2.75%
- 現状の C7 ホットパス実装は「ヒット専用 UC ＋ TLS→UC→cold 直線化」の初期版で、大幅な伸びはまだ無い。回帰はなく、分岐ミス率はわずかに改善。今後さらに UC ヒット専用関数の最短化や free 側の直線化を詰める余地あり。
- 方針: `HAKMEM_TINY_C7_HOT` は実験用スイッチとして残し、デフォルト OFF。perf フェーズは bench プロファイルで ≈50M ops/s / RSS ≈7MB を維持できる現行経路を基準に一旦完了とする。***

## ChatGPT Pro 設計レビュー要約（mimalloc にさらに迫るための方向性）

- 現状:
  - bench プロファイル（`HAKMEM_PROFILE=bench`）で 16–1024B は ~50M ops/s / RSS≈7MB。mimalloc は ~100–120M ops/s / RSS≈2MB 前後で、性能は 0.4×〜0.5× 程度。
  - IPC≈2.1 前後とパイプラインはそれなりに埋まっているが、命令数と多層経路（Gate/Route/TinyFront/UC/Page/Warm/Shared）が支配的。
- 評価:
  - 「今の箱構造のまま小手先だけで 2× 持ち上げるのはほぼ無理」で、Tiny front を mimalloc 風 TinyHeap に寄せる**小さめの再設計**が必要。
  - Superslab/Tier/Guard/Budget/Stats/Remote といった COLD/Safety 層は Box として残し、HOT 側をより薄い TinyHeapBox に集約するのが筋が良い。
- 推奨パターン（案）:
  - パターン1: **Hot TinyHeap vs Cold SafetyBox**
    - per-thread TinyHeap（heap→page→block）で C0〜C7 の小オブジェクトを mimalloc 風に処理し、Superslab/Shared/Tier/Guard/Budget/Stats/Remote はレアイベント専用の外側の Box として扱う。
  - パターン2: **Policy Snapshot Box の徹底**
    - `_Atomic TinyPolicySnapshot` を使い、Hot path は `policy[cls]` を読むだけにし、Learner/ENV 読み・更新は完全に外側の Box に隔離する（現行実装をさらに徹底）。
  - パターン3: **C7HotBox（C7専用 TinyHeap Box）の本格分離**
    - size==1024 のみ `C7HotBox` に直行させ、UC/Page/Warm/TLS を C7HotBox 内部で self-contained に扱う。Superslab/Tier/Guard とは「page が尽きる/全 free になる」ときだけ話す。
- ロードマップ案:
  1. Phase 1: C7HotBox を本格化し、C7-only ベンチで 50M→70M 付近を狙う（他クラスは従来 TinyFront のまま）。
  2. Phase 2: UC + Page + Warm を統合した TinyHeapBox を導入し、C5〜C7 を TinyHeap 経由に寄せる（129–1024B/16–1024B で 60–80M を目標）。
  3. Phase 3: 必要に応じて C0〜C4 も段階的に TinyHeap 側へ移植し、TinyFront は薄いラッパ層に縮退させる。
- 方針メモ:
  - Box Theory は維持しつつ、「Hot TinyHeap（シンプル・高速）」と「Cold Superslab/SafetyBox（複雑・安全）」の二層構造に整理することで、mimalloc に近い性能と HAKMEM 固有の安全性・観測性・学習レイヤを両立させる方向性と認識。