# C6_HOTBOX_DESIGN

目的: class6 を C7 SAFE と同じ TinyHeap ベースでホット化するための箱を定義する。まずは SAFE（meta きちんと保持）だけを対象とし、ULTRA（meta を大胆に省く）は C6 ではやらない。

## 境界（箱の責務）
- **内側 (C6 HotBox)**: TinyHeapBox 上での heap → page → block 管理、current_page ポリシー。
- **外側 (Cold Box)**: Superslab / Tier / Guard / Stats。TLS SLL とは原則切断（TinyHeap クラスには SLL を使わせない）。

## ENV / A/B 切替
- `HAKMEM_TINY_HEAP_BOX` … TinyHeap front 全体の ON/OFF。
- `HAKMEM_TINY_HEAP_CLASSES` … クラスごとの TinyHeap マスク。デフォルトは `0x80` (C7 のみ)。
- `HAKMEM_TINY_C6_HOT` … C6 Hot front を有効化するスイッチ（1 で C6 専用直線パスを許可）。
- `HAKMEM_TINY_C6_META_MODE` … 0=OFF, 1=SAFE（当面は SAFE のみ。ULTRA はやらない）。
- **注意**: meta_mode=1 は現時点では bench/実験専用。長めの C6-heavy でクラッシュする既知事象があり、通常運用は
  meta_mode=0 または C6 TinyHeap OFF を推奨する。
- デバッグ用（meta_mode=1 時の Fail-Fast/可視化）:
  - `HAKMEM_TINY_C6_DEBUG_POP=1` … pop まわりの Fail-Fast を有効化。
  - `HAKMEM_TINY_C6_DELTA_TRACE=1` … delta を触った箇所を last_delta_site に記録。
  - `HAKMEM_TINY_C6_DELTA_DEBUG=1` … destructor で delta サマリを dump。
  - `HAKMEM_TINY_C6_DELTA_TRACE=1` が有効なときは delta サイト (ALLOC/FREE/ATTACH/EMPTY/THRESHOLD) をページに刻み、
    `HAKMEM_TINY_C6_DEBUG_POP=1` では pop/free の Fail-Fast（範囲外 freelist/ss mismatch/cap0 等）と 512 行までの debug log を出す。

## 現状の事実（2025-12 時点）
- C6 TinyHeap（`HAKMEM_TINY_HEAP_CLASSES=0x40`）は C6-heavy / Mixed どちらも回帰気味（最新測定 2025-12-05）。
  - C6-heavy (min=257/max=768, ws=256, iters=20k, debug OFF)  
    - LEGACY: **41.74M ops/s**（HEAP_STATS 0）  
    - TinyHeap mode0 (`C6_META_MODE=0`): **36.07M ops/s**（cls6 fast=5381 / slow_prepare=1）  
    - TinyHeap mode1 (`C6_META_MODE=1` SAFE): **28.86M ops/s**（cls6 fast=2692 / slow_prepare=2690）
  - Mixed 16–1024B (ws=256, iters=20k)  
    - LEGACY: **40.90M ops/s**  
    - C7_SAFE (C6 OFF): **40.96M ops/s**（cls7 fast=5691 / slow=1）  
    - C6+C7 SAFE (`HEAP_CLASSES=0xC0`、両方 meta_mode=1): **27.21M ops/s**（cls6 fast=1388 / slow=1366、cls7 fast=5664 / slow=19）
- mode0 は slow_prepare≈1 でも約 -14%（C6-heavy）と大きくマイナス、mode1 は slow_prepare が増えてさらに悪化。現状は bench/実験専用マスク（0x40/0xC0）とし、通常は LEGACY か C7_SAFE のみを推奨。
- slow_prepare が小さいまま回帰するため、原因は Front/Hot の命令コストや meta 更新コスト（delta/flush 実装）の重さにあると推定。mode1 は delta/flush を触ることで slow_prepare も増えやすい点に注意。
- meta_mode=1 の暫定防御（Phase21–22）:
  - attach で meta->freelist を範囲チェックし、OOB は NULL に潰す。
  - empty→release で meta->freelist を NULL にし、debug 時は page->free_list に poison。
  - pop で freelist OOB / ss mismatch / cap0 などを Fail-Fast。  
  - 上記後、C6-heavy iters=1000/1500/2000/20000 で再現していた SIGSEGV は出なくなり、delta サマリは 0/0/0（ただし bench 専用扱いは継続）。

## 要件と設計方針
- 当面は **SAFE のみ**（meta/active を delta + flush で正確寄りに保つ）。ULTRA は C6 では導入しない。
- A/B できるように:
  - C6 Hot front: `HAKMEM_TINY_C6_HOT=1` で直線パスを有効化。
  - C6 TinyHeap ON/OFF: `HAKMEM_TINY_HEAP_CLASSES` のビットで切替（デフォルトは OFF）。
- Box Theory 準拠:
  - HotBox（TinyHeap 内部）と Cold Box（Superslab/Tier/Guard/Stats）の境界は 1 箇所。
  - TLS SLL は C6 HotBox からは触らない。

## 今後のフォーカス
- C7 SAFE で効いた current_page 固定＋ delta/閾値 flush を C6 に横展開するかを検討。
- Front/Hot の命令数を減らすため、C6 専用の直線フロント（Gate → Heap 一本化）を C7 と対称に整える。
- 成果の指標:
  - C6-heavy で LEGACY と同等以上を目指す。
  - Mixed 16–1024B で C6 を載せてもマイナスが小さい（±1M 以内）こと。

v1 の結論と凍結方針
--------------------
- v1 では C6 TinyHeap/Hot はどのモードでも C6-heavy/Mixed で明確なマイナス。meta_mode=1 は bench/実験専用とし、通常は mode0 か OFF を推奨。
- C6 の本格的な再設計は TinyHeap v2（C5–C7 をまとめて組み直す箱）で行う。C6 を触るときは bench/実験マスク (0x40/0xC0) とデバッグ ENV を明示的に有効にする。