docs: HAKMEM v2 generation summary and Phase v7-4 completion

- Add HAKMEM_V2_GENERATION_SUMMARY.md: comprehensive overview of v2 generation - Update CURRENT_TASK.md: 'v2 generation complete' section - Update SMALLOBJECT_V7_DESIGN.md: Phase v7-4 completion notes + v7-5 candidates v2 generation freeze: ULTRA (FROZEN) / MID_v3 (stable) / v7 (research, code freeze) Next: HakORune / JoinIR priority, HAKMEM resumes at v7-5 (multi-class expansion) Layer structure (L0-L3) established, Box Theory implementation patterns confirmed. Design documents serve as maps for future v7 second chapter. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
2025-12-12 04:00:55 +09:00
parent 8143e8b797
commit ea905b2ccb
3 changed files with 346 additions and 0 deletions
--- a/CURRENT_TASK.md
+++ b/CURRENT_TASK.md
@ -1782,3 +1782,41 @@ gcc -o bench_tiny_hot_hakmem ... core/smallobject_policy_v7.o ... -lm -lpthread
 2. **Learner 連携**: ENV defaults + runtime learning override
 3. **クラスごとの柔軟な優先順位**: ENV で ULTRA vs v7 の順序を逆転可能に
 4. **Multi-class v7**: C5/C4 追加 → coverage 拡大
+
+========================================================================
+## SECTION: HAKMEM v2 世代 完了宣言（第1章）
+========================================================================
+
+### Phase v7-4 完了時点での総括
+
+Policy Box 導入により、L0-L3 の層構造が確立。
+「芯の設計練習」は達成し、v2 世代は一旦完成。
+
+### 成果ハイライト
+
+| フェーズ | 目標 | 達成度 |
+|---------|------|--------|
+| ULTRA (C7) | +10% 目標 | ✅ +11% 達成 |
+| MID v3 | 257-768B 本線化 | ✅ 完了 |
+| v7 (C6-only) | 研究箱構築 | ✅ 完了、-4.3% overhead |
+| Policy Box | route 一元化 | ✅ 完了、ENV 集約 |
+
+### 次世代への課題一覧
+
+**v7 第2章（Phase v7-5 候補）**:
+1. Multi-class 拡張（C5/C4）→ overhead 分摊
+2. Learner 連携 → 動的 route 選択
+3. HeaderLess 統一 → v6/v7 mode 統合
+
+**開発再開条件**:
+- HakORune / JoinIR ノーマライズ優先
+- v2 世代ドキュメント（HAKMEM_V2_GENERATION_SUMMARY.md）が凍結状態で読み返せること
+
+### 凍結方針
+
+- ULTRA: 改造禁止（FROZEN）
+- MID v3: バグ修正のみ
+- v7: code freeze（research boxとして保存）
+- HAKMEM: ここで一旦完成
+
+次の開発は HakORune / JoinIR 優先。
--- a/docs/analysis/HAKMEM_V2_GENERATION_SUMMARY.md
+++ b/docs/analysis/HAKMEM_V2_GENERATION_SUMMARY.md
@ -0,0 +1,236 @@
+# 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（C6-only 研究箱）
+
+**狙い**: small～mid を 1 個の SmallHeapCtx + Segment で扱う土台作り
+
+**実装状況**:
+- 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 決定一元化）
+
+**性能**:
+- C6-only (400-510B, 500K iter):
+  - Legacy baseline: 58.6M ops/s
+  - v7 Phase v7-2: 54.5M ops/s (-7.0%)
+  - v7 Phase v7-3: 56.3M ops/s (-4.3%)
+- 改善トレンド: 38% overhead 削減済み
+
+**設計完了事項**:
+- 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
+
+**残課題**:
+- -4.3% overhead → ±0% へ（multi-class 拡張で分摊予定）
+- C5/C4 対応（Phase v7-5 候補）
+
+#### 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. サイズ帯の担当整理
+
+| サイズ | Class | Primary | Secondary | Status |
+|--------|-------|---------|-----------|--------|
+| 1KB | C7 | ULTRA | - | FROZEN |
+| 512B | C6 | v7 / MID_v3 | ULTRA | Research |
+| 256B | C5 | MID_v3 | ULTRA | Stable |
+| 128B | C4 | ULTRA | MID_v3 | Partial |
+| 64B | C3 | Legacy | - | Fallback |
+| 32B | C2 | Legacy | - | Fallback |
+| 16B | C1 | Legacy | - | Fallback |
+| 8B | C0 | 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 への橋渡し（設計メモ）
+
+### 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 拡張）
+- [ ] または HakORune / JoinIR 一段落後に再開
+- [ ] v2 設計ドキュメントが凍結状態で読み返せること
+
+## 7. 凍結方針
+
+v2 世代はここで一旦完成とする。
+
+**凍結対象**:
+- ULTRA (C4-C7): 改造禁止（FROZEN）
+- MID v3: バグ修正のみ（拡張禁止）
+- v7 (C6-only): 設計確定、性能改善研究中（code freeze）
+- Policy Box: route 決定一元化完了
+
+**HakORune / JoinIR優先**:
+- HAKMEM は凍結
+- 次世代 v7 再開は JoinIR ノーマライズ一段落後
+
+**再開条件**:
+- この総括ドキュメントが地図として機能すること
+- v7-4 の設計メモ (6-1/6-2/6-3) が実装ガイド足り得ること
+
+## 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
--- a/docs/analysis/SMALLOBJECT_V7_DESIGN.md
+++ b/docs/analysis/SMALLOBJECT_V7_DESIGN.md
@ -388,3 +388,75 @@ ULTRA/MID_v3/LEGACY は既存の `tiny_route_env_box.h` を併用（後で統合

 ---

+
+## 8. v7 第2章への設計メモ（Phase v7-4 完了時点）
+
+### 現状（C6-only 研究箱）
+
+- **性能**: 56.3M ops/s (Phase v7-3, -4.3% overhead)
+- **設計完了**: SmallHeapCtx / Segment / ColdIface / RegionIdBox 統一
+- **Policy統合**: 完了（route 一元化）
+
+### -4.3% Overhead の内訳（仮説）
+
+| 要因 | 推定 | 対策 |
+|------|------|------|
+| Page metadata 間接参照 | ~2% | Multi-class で分摊 |
+| Extra validation | ~1% | Branch優化 |
+| RegionIdBox fallback | ~1% | TLS cache強化 |
+
+### Multi-class 拡張時の検討項目
+
+1. **Segment 設計**:
+   - Option A: Class ごとに独立 segment (SmallSegment_v7_C6, v7_C5, ...)
+   - Option B: 複数 class を 1 segment 内で共存
+   - Decision point: TLS hint の複数 segment 対応
+
+2. **TLS Context 拡張**:
+   ```c
+   typedef struct SmallHeapCtx_v7_multi {
+       SmallClassHeap_v7 cls[8];
+       // Multi-class TLS hints
+       struct {
+           uintptr_t seg_base;
+           uintptr_t seg_end;
+           SmallSegment_v7* seg;
+       } tls_seg[5];  // C3-C7
+   } SmallHeapCtx_v7_multi;
+   ```
+
+3. **Overhead 分摊の期待値**:
+   - C6-only: -4.3% (current)
+   - C5+C6: -2% (overhead 薄まる)
+   - C4+C5+C6: -1% (さらに薄まる)
+
+### Learner 連携（Phase v7-5 候補）
+
+**概要**: SmallPageStatsV7 から実行時最適 route を学習
+
+```c
+// Policy Box update interface
+void small_policy_v7_update_from_learner(
+    const SmallLearnerStats* stats,
+    SmallPolicyV7* policy_out
+);
+```
+
+**学習要件**:
+- Alloc/free count, peak_live, lifetime_ms
+- v7 vs MID_v3 の速度比較
+- Learner の信頼度 threshold
+
+### HeaderLess 統一（将来検討）
+
+v7-5 以降でも header を削除できるかの検証:
+- v6 headerless: page->class_idx で header-free を実装済み
+- v7 適用: free 時に page_meta から class_idx を取得
+- Benefit: 1 byte 削減 per allocation（micro, 但し alloc density up）
+
+### 次世代開始チェックリスト
+
+- [ ] HAKMEM_V2_GENERATION_SUMMARY.md が地図として機能
+- [ ] v7-4 時点の設計メモ (本セクション) が読み返せる
+- [ ] HakORune / JoinIR が一段落（or 並行可能に）
+- [ ] v7 research box は冷凍庫に保存完了