hakmem/docs/analysis/HAKMEM_V2_GENERATION_SUMMARY.md

# HAKMEM v2 世代 総括（第1章完）

## 1. 位置づけ

HAKMEM v2 世代は、ChatGPT Pro の層設計に基づく「芯から作り直す」実装練習として開始。
L0（ULTRA）から L3（Policy）までの層構造を確立し、Box Theory に沿った実装パターンを確立した。

Phase v7-4（Policy Box 導入）をもって、v2 世代は設計上の完成を見た。

## 2. アーキテクチャ層構造

### L0: ULTRA（C4-C7, FROZEN 世代）

**特性**:
- C7: 2MiB Segment + 64KiB Page + TLS freelist
- C4-C6: ULTRA-free / ULTRA-alloc (寄生型 TLS cache)
- Status: FROZEN（完成度高、これ以上改善不要）

**性能**:
- C7 phase 1a/1b: +11% 改善（division → bit shift 最適化完了）
- Mixed 16-1024B に貢献: +11% baseline 達成

### L1: SmallObject 新世代（v7 / MID v3 / Legacy）

#### L1-a: SmallObject v7（C5/C6 専用研究箱）

**狙い**: small～mid を 1 個の SmallHeapCtx + Segment で扱う土台作り

**位置づけ（Phase v10 確定）**:
- **基準線**: Mixed 本線では `HAKMEM_SMALL_HEAP_V7_ENABLED=0` (OFF)
- **用途**: C5/C6 ベンチマーク専用プリセット（Learner ON）
- **Status**: 研究実装（設計パターン確立済み）

**実装状況**:
- Phase v7-2: C6-only 本実装完了（refill/retire 動作確認）
- Phase v7-3: TLS segment fast path 最適化（overhead -7.0% → -4.3%）
- Phase v7-4: Policy Box 統合（route 決定一元化）
- Phase v7-5b: C5 対応（256B blocks）
- Phase v7-7: Learner 統合（動的ルート切り替え）
- Phase v10: Learner デフォルト ON、v3/v4/v5 削除

**性能（最新）**:
- C6-only (400-510B, 500K iter):
  - Legacy baseline: 58.6M ops/s
  - v7 Phase v7-3: 56.3M ops/s (-4.3%)
- C5/C6 mixed (200-500B, 300K iter):
  - v7 + Learner: 38.7M ops/s (+127% vs Legacy)
  - Learner route switch: C5 ratio 28% < threshold 30% → MID_v3

**設計完了事項**:
- SmallSegment_v7: 2MiB segment, free page stack
- SmallHeapCtx_v7: TLS context, TLS segment hints (v7-3)
- ColdIface_v7: page refill/retire
- RegionIdBox: v7 segment registration + fast lookup
- SmallPolicyV7: route 決定一元化
- SmallLearnerV7: 動的ワークロード検出

**C5/C6 プリセット**（ドキュメント参照）:
```bash
# C5/C6 ベンチマーク用（Learner ON）
HAKMEM_SMALL_HEAP_V7_ENABLED=1 \
HAKMEM_SMALL_HEAP_V7_CLASSES=0x60 \
./bench_random_mixed_hakmem 300000 400 1
```

**残課題**:
- Mixed 本線性能との差分解消（v3 backend 最適化、headerless v6 拡張）

#### L1-b: MID v3（257-768B 本線）

**特性**: Specialized TLS heap for mid-size allocations
**Status**: Stable, production-ready
**担当**: C5-C6 (mixed workload では ULTRA / v7 と共存)

#### L1-c: Legacy（TinyHeap v1 / Pool v1）

**特性**: Fallback for unhandled classes
**Status**: Stable, production baseline

### L2: Infrastructure（Segment / RegionId / ColdIface）

**Segment**:
- SmallSegment_v6: V6 headerless core 用（64KiB page, free stack）
- SmallSegment_v7: v7 core 用（2MiB segment, same geometry）
- 型パターン統一により、将来の multi-class 拡張が容易

**RegionIdBox**:
- v6/v7 segment の ptr → region lookup（O(log N) binary search）
- TLS cache で high-hit-rate workload を最適化
- Phase v7-3 で TLS fast path により overhead 削減

**ColdIface**:
- v6: small_cold_v6_refill_page / retire_page
- v7: small_cold_v7_refill_page / retire_page
- API 統一により multi-segment 拡張も設計可能

### L3: Policy & Stats（Route 決定・統計）

**Policy Box (Phase v7-4 新規)**:
- SmallPolicyV7: route_kind[8] で C0-C7 の route 一括決定
- Priority (固定): ULTRA > v7 > MID_v3 > LEGACY
- ENV 一元化: init_from_env で全 ENV を一度だけ解釈

**Frontend との関係**:
- Front: size → class_idx → policy->route_kind[ci] → switch
- Front は ENV を直接読まない（policy に委譲）
- 設定変更は Policy Box だけで完結

**Stats (将来)**:
- SmallPageStatsV7: page retire 時に publish
- PolicyLearner（v7-5 候補）: stats から最適 route を学習

## 3. サイズ帯の担当整理（Phase v10 確定）

| サイズ | Class | Mixed 本線 | C5/C6 専用 | Status |
|--------|-------|-----------|-----------|--------|
| 1KB | C7 | ULTRA | ULTRA | FROZEN |
| 512B | C6 | MID_v3 | v7+Learner | Research preset |
| 256B | C5 | MID_v3 | v7+Learner | Research preset |
| 128B | C4 | ULTRA | ULTRA | Stable |
| 64B | C3 | Legacy | Legacy | Fallback |
| 32B | C2 | Legacy | Legacy | Fallback |
| 16B | C1 | Legacy | Legacy | Fallback |
| 8B | C0 | Legacy | Legacy | Fallback |

## 4. 最適化達成状況

### Throughput
- Baseline (no optimization): 39.5M ops/s (Mixed 16-1024B)
- Phase 1a (division → shift): 39.5M ops/s (±0%)
- Phase 1b (segment learning 削除): 42.3M ops/s (+7.1%)
- **Final (v7-3 + Policy Box)**: 43-44M ops/s (+11.1% 実測)

### Overhead Reduction
- v7 Phase v7-2: -7.0% (RegionIdBox binary search cost)
- v7 Phase v7-3: -4.3% (TLS fast path optimization)
- **Improvement**: 38% overhead削減

### Architectural Wins
- ✅ Layer structure (L0-L3) 明確化
- ✅ Box Theory 実装パターン確立
- ✅ Policy Box で ENV 一元化
- ✅ Segment/RegionId 型パターン統一

## 5. Box Theory 実装パターン（v2 で確立）

**各層の責務**:
```
L0: ULTRA
  └─ 最高速アロケータ（size class 専用）

L1: HotBox (v7/MID/Legacy)
  └─ TLS cache + current/partial page 管理

L2: ColdIface + Segment + RegionId
  └─ Page lifecycle (refill/retire) + segment管理 + region lookup

L3: Policy Box + Stats + Learner (将来)
  └─ Route決定・env管理・統計・学習
```

**特徴**:
- 各層が内部完結（下の層に依存しない API）
- ENV は L3 だけで読む（L1-L0 は ENV-free）
- TLS cache はレイヤーごとに独立
- Future: Learner で L3 ← stats をフィードバック

## 6. 次世代 v7 / v3 への橋渡し（設計メモ）

### v7 第2章の候補

#### 6-1. Multi-class 拡張（C5/C4 対応）

**狙い**: -4.3% overhead を複数クラスで分摊して ±0% へ

**設計考察**:
- SmallSegment_v7 を class ごとに独立 (C6/C5/C4 各segment)
- または: 複数 class を 1 segment 内で共存
- TLS segment hint が複数class対応可能か検証

**実装レベル**:
- SmallHeapCtx_v7.tls_seg_base/end は 1 segment 前提
- Multi-segment 対応なら: tls_seg_list[] or segment registry
- 既存 RegionIdBox で OK（拡張不要）

#### 6-2. Learner 連携（動的 route 選択）

**狙い**: 実行時統計で v7 / MID_v3 の最適 route を自動選択

**設計考察**:
- SmallPageStatsV7 publish → PolicyLearner ingestion
- Learner から Policy Box へ route_kind[] 更新
- 学習率・履歴長・信頼度 threshold は TBD

**実装レベル**:
- Policy Box snapshot は read-only
- 更新は small_policy_v7_update_from_learner() 経由
- Thread-safe update (maybe atomic or RCU)

#### 6-3. HeaderLess 統一（v7/v6 の mode 統合）

**狙い**: RegionId lookup で headerless を完全活用

**設計考察**:
- v7 でも header を書かない mode の検証
- Free 時に page_meta から class_idx を取得
- Small allocation では header mismatch のリスク軽減

**実装レベル**:
- SmallPageMeta にはすでに class_idx あり
- Free path: hint 無視して page->class_idx 信頼
- Validation: class_idx 範囲チェックだけ

### 次世代開始の条件

- [ ] v7 が ±0% overhead 達成（multi-class 拡張）
- [ ] v3 / v7 コアの SPEC がこの総括＋各 DESIGN ドキュメントから一貫して読み取れること

## 7. v2 世代の位置づけ

v2 世代はここで一旦「第1章の完成版」とする。

**扱い方**:
- ULTRA (C4-C7): 大きな構造変更はせず、第2世代でも L0 の完成箱として前提にする。
- MID v3: 257–768B 帯の本線箱として維持しつつ、将来 v7/mid コアに統合する際の比較対象・退避先として使う。
- v7 (C6-only): 設計・実装パターンは確立済みの研究箱として残し、第2世代の v7/mid コアを作るときの参照実装にする。
- Policy Box: route 決定の一元化パターンとして、そのまま v3 世代でも使い続ける。

この総括は「ここまでが第1世代で、ここから先は v3 / v7 世代でさらに芯を削る」というための地図として扱う。

## 8. 謝辞・振り返り

この v2 世代を通じて以下を学んだ/確立した:

- Box Theory の実装パターン（L0-L3 層分離）
- ENV 一元化の必要性（Policy Box）
- TLS cache の効果（segment fast hint, page cache）
- Multi-layer allocation の複雑性と取り組み方

「芯から作り直す」というゴールに向けて、設計練習としては十分成功。
次の v7 第2章（multi-class）は、ここの学びを足がかりに進める。

---

**Document Date**: 2025-12-12
**Final Commit**: Phase v7-4 Policy Box 導入
**Next Phase**: v7-5 (Multi-class expansion) / HakORune priority