hakmem/docs/design/BOX_THEORY_ARCHITECTURE_REPORT.md

# 箱理論アーキテクチャ検証レポート

**日付**: 2025-11-12
**検証対象**: Phase E1-CORRECT 統一箱構造
**ステータス**: ✅ 統一完了、⚠️ レガシー特殊ケース残存

---

## エグゼクティブサマリー

Phase E1-CORRECTで**すべてのクラス（C0-C7）に1バイトヘッダーを統一**しました。これにより：

✅ **達成**:
- Header層: C7特殊ケース完全排除（0件）
- Allocation層: 統一API（`tiny_region_id_write_header`）
- Free層: 統一Fast Path（`tiny_region_id_read_header`）

⚠️ **残存課題**:
- **Box層**: C7特殊ケース13箇所残存（`tls_sll_box.h`, `ptr_conversion_box.h`）
- **Backend層**: C7デバッグロギング5箇所（`tiny_superslab_*.inc.h`）
- **設計矛盾**: Phase E1でC7にheader追加したのに、Box層でheaderless扱い

---

## 1. 箱構造の検証結果

### 1.1 Header層の統一（✅ 完全達成）

**検証コマンド**:
```bash
grep -n "if.*class.*7" core/tiny_region_id.h
# 結果: 0件（C7特殊ケースなし）
```

**Phase E1-CORRECT設計**（`core/tiny_region_id.h:49-56`）:
```c
// Phase E1-CORRECT: ALL classes (C0-C7) have 1-byte header (no exceptions)
// Rationale: Unified box structure enables:
//   - O(1) class identification (no registry lookup)
//   - All classes use same fast path
//   - Zero special cases across all layers
// Cost: 0.1% memory overhead for C7 (1024B → 1023B usable)
// Benefit: 100% safety, architectural simplicity, maximum performance

// Write header at block start (ALL classes including C7)
uint8_t* header_ptr = (uint8_t*)base;
*header_ptr = HEADER_MAGIC | (class_idx & HEADER_CLASS_MASK);
```

**結論**: Header層は**完全統一**。C7特殊ケースは存在しない。

---

### 1.2 Box層の特殊ケース（⚠️ 13箇所残存）

**C7特殊ケース出現頻度**:
```
core/tiny_free_magazine.inc.h:  24件
core/box/tls_sll_box.h:         11件  ← Box層
core/tiny_alloc_fast.inc.h:     8件
core/box/ptr_conversion_box.h:  7件   ← Box層
core/tiny_refill_opt.h:         5件
```

#### 1.2.1 TLS-SLL Box（`tls_sll_box.h`）

**C7特殊ケースの理由**:
```c
// Line 84-88: C7 rejection
// CRITICAL: C7 (1KB) is headerless - MUST NOT use TLS SLL
// Reason: SLL stores next pointer in first 8 bytes (user data for C7)
if (__builtin_expect(class_idx == 7, 0)) {
    return false;  // C7 rejected
}
```

**問題点**:
- **Phase E1の設計矛盾**: C7にheader追加したのに、Box層で"headerless"扱い
- **実装矛盾**: C7もheader持つなら、TLS SLL使えるはず
- **パフォーマンス損失**: C7だけSlow Path強制（不要な制約）

#### 1.2.2 Pointer Conversion Box（`ptr_conversion_box.h`）

**C7特殊ケースの理由**:
```c
// Line 43-48: BASE→USER conversion
/* Class 7 (2KB) is headerless - no offset */
if (class_idx == 7) {
    return base_ptr;  // No +1 offset
}
// Classes 0-6 have 1-byte header - skip it
void* user_ptr = (void*)((uint8_t*)base_ptr + 1);
```

**問題点**:
- **Phase E1の設計矛盾**: C7もheaderあるなら+1必要
- **メモリ破壊リスク**: C7でbase==userだと、next pointer書き込みでheader破壊

---

### 1.3 Backend層の特殊ケース（5箇所、デバッグのみ）

**C7デバッグロギング**（`tiny_superslab_alloc.inc.h`, `tiny_superslab_free.inc.h`）:
```c
// 性能影響なし（デバッグビルドのみ）
if (ss->size_class == 7) {
    static _Atomic int c7_alloc_count = 0;
    fprintf(stderr, "[C7_FIRST_ALLOC] ptr=%p next=%p\n", block, next);
}
```

**結論**: Backend層の特殊ケースは**非致命的**（デバッグ専用、性能影響なし）。

---

## 2. 層構造の分析

### 2.1 現在の層とファイルマッピング

```
Layer 1: Header Operations (完全統一 ✅)
  └─ core/tiny_region_id.h (222行)
     - tiny_region_id_write_header() - ALL classes (C0-C7)
     - tiny_region_id_read_header()  - ALL classes (C0-C7)
     - C7特殊ケース: 0件

Layer 2: Allocation Fast Path (統一 ✅、C7はSlow Path強制)
  └─ core/tiny_alloc_fast.inc.h (707行)
     - hak_tiny_malloc() - TLS SLL pop
     - C7特殊ケース: 8件（Slow Path強制のみ）

Layer 3: Free Fast Path (統一 ✅)
  └─ core/tiny_free_fast_v2.inc.h (315行)
     - hak_tiny_free_fast_v2() - Header-based O(1) class lookup
     - C7特殊ケース: 0件（Phase E3-1でregistry lookup削除）

Layer 4: Box Abstraction (設計矛盾 ⚠️)
  ├─ core/box/tls_sll_box.h (560行)
  │  - tls_sll_push/pop/splice API
  │  - C7特殊ケース: 11件（"headerless"扱い）
  │
  └─ core/box/ptr_conversion_box.h (90行)
     - ptr_base_to_user/ptr_user_to_base
     - C7特殊ケース: 7件（offset=0扱い）

Layer 5: Backend Storage (デバッグのみ)
  ├─ core/tiny_superslab_alloc.inc.h (801行)
  │  - C7特殊ケース: 3件（デバッグログ）
  │
  └─ core/tiny_superslab_free.inc.h (368行)
     - C7特殊ケース: 2件（デバッグ検証）

Layer 6: Classification (ドキュメントのみ)
  └─ core/box/front_gate_classifier.h (79行)
     - C7特殊ケース: 3件（コメント内"headerless"言及）
```

### 2.2 層間依存関係

```
┌─────────────────────────────────────────────────┐
│ Layer 1: Header Operations (tiny_region_id.h)  │ ← 完全統一
└─────────────────┬───────────────────────────────┘
                  │ depends on
                  ↓
┌─────────────────────────────────────────────────┐
│ Layer 2/3: Fast Path (alloc/free)              │ ← 統一
│   - tiny_alloc_fast.inc.h                       │
│   - tiny_free_fast_v2.inc.h                     │
└─────────────────┬───────────────────────────────┘
                  │ depends on
                  ↓
┌─────────────────────────────────────────────────┐
│ Layer 4: Box Abstraction (box/*.h)             │ ← 設計矛盾
│   - tls_sll_box.h (C7 rejection)                │
│   - ptr_conversion_box.h (C7 offset=0)          │
└─────────────────┬───────────────────────────────┘
                  │ depends on
                  ↓
┌─────────────────────────────────────────────────┐
│ Layer 5: Backend Storage (superslab_*.inc.h)    │ ← 非致命的
└─────────────────────────────────────────────────┘
```

**問題点**:
- **Layer 1（Header）**: C7にheader追加済み
- **Layer 4（Box）**: C7を"headerless"扱い（設計矛盾）
- **影響**: C7だけTLS SLL使えない → Slow Path強制 → 性能損失

---

## 3. モジュール化提案

### 3.1 現状の問題

**ファイルサイズ分析**:
```
core/tiny_superslab_alloc.inc.h:  801行  ← 巨大
core/tiny_alloc_fast.inc.h:       707行  ← 巨大
core/box/tls_sll_box.h:           560行  ← 巨大
core/tiny_superslab_free.inc.h:   368行
core/box/hak_core_init.inc.h:     373行
```

**問題**:
1. **単一責任原則違反**: `tls_sll_box.h`が560行（push/pop/splice/debug全部入り）
2. **C7特殊ケース散在**: 11ファイルに70+箇所
3. **Box境界不明確**: `tiny_alloc_fast.inc.h`がBox API直接呼び出し

### 3.2 リファクタリング提案

#### Option A: 箱理論レイヤー分離（推奨）

```
core/box/
  allocation/
    - header_box.h          (50行, Header write/read統一API)
    - fast_alloc_box.h      (200行, TLS SLL pop統一)

  free/
    - fast_free_box.h       (150行, Header-based free統一)
    - remote_free_box.h     (100行, Cross-thread free)

  storage/
    - tls_sll_core.h        (100行, Push/Pop/Splice core)
    - tls_sll_debug.h       (50行, Debug validation)
    - ptr_conversion.h      (50行, BASE↔USER統一)

  classification/
    - front_gate_box.h      (80行, 現状維持)
```

**利点**:
- 単一責任原則遵守（各ファイル50-200行）
- C7特殊ケースを1箇所に集約可能
- Box境界明確化

**コスト**:
- ファイル数増加（4 → 10ファイル）
- include階層深化（1-2レベル増）

---

#### Option B: C7特殊ケース統一（最小変更）

**Phase E1の設計意図を完遂**:
1. **C7にheader追加済み** → Box層も統一扱いに変更
2. **TLS SLL Box修正**:
   ```c
   // Before (矛盾)
   if (class_idx == 7) return false;  // C7 rejected

   // After (統一)
   // ALL classes (C0-C7) use same TLS SLL (header protects next pointer)
   ```
3. **Pointer Conversion Box修正**:
   ```c
   // Before (矛盾)
   if (class_idx == 7) return base_ptr;  // No offset

   // After (統一)
   void* user_ptr = (uint8_t*)base_ptr + 1;  // ALL classes +1
   ```

**利点**:
- 最小変更（2ファイル、30行程度）
- C7特殊ケース70+箇所 → 0箇所
- C7もFast Path使用可能（性能向上）

**リスク**:
- C7のuser size変更（1024B → 1023B）
- 既存アロケーションとの互換性（要テスト）

---

#### Option C: ハイブリッド（段階的移行）

**Phase 1**: C7特殊ケース統一（Option B）
- 目標: C7もFast Path使用可能に
- 期間: 1-2日
- リスク: 低（テスト充実）

**Phase 2**: レイヤー分離（Option A）
- 目標: 箱理論完全実装
- 期間: 1週間
- リスク: 中（大規模リファクタ）

---

## 4. 最終評価

### 4.1 箱理論統一の達成度

| 層 | 統一度 | C7特殊ケース | 評価 |
|---|---|---|---|
| **Layer 1: Header** | 100% | 0件 | ✅ 完璧 |
| **Layer 2/3: Fast Path** | 95% | 8件（Slow Path強制） | ✅ 良好 |
| **Layer 4: Box** | 60% | 18件（設計矛盾） | ⚠️ 改善必要 |
| **Layer 5: Backend** | 95% | 5件（デバッグのみ） | ✅ 良好 |
| **Layer 6: Classification** | 100% | 0件（コメントのみ） | ✅ 完璧 |

**総合評価**: **B+（85/100点）**

**強み**:
- Header層の完全統一（Phase E1の成功）
- Fast Path層の高度な抽象化
- Classification層の明確な責務分離

**弱み**:
- Box層の設計矛盾（Phase E1の意図が反映されていない）
- C7特殊ケースの散在（70+箇所）
- ファイルサイズの肥大化（560-801行）

---

### 4.2 モジュール化の必要性

**優先度**: **中～高**

**理由**:
1. **設計矛盾の解消**: Phase E1の意図（C7 header統一）がBox層で実現されていない
2. **性能向上**: C7がFast Path使えれば5-10%向上見込み
3. **保守性**: 560-801行の巨大ファイルは変更リスク大

**推奨アプローチ**: **Option C（ハイブリッド）**
- **短期**: C7特殊ケース統一（Option B、1-2日）
- **中期**: レイヤー分離（Option A、1週間）

---

### 4.3 次のアクション

#### 即座に実施（優先度: 高）
1. **C7特殊ケース統一の検証**
   ```bash
   # C7にheaderある前提でTLS SLL使用可能か検証
   ./build.sh debug bench_random_mixed_hakmem
   # Expected: C7もFast Path使用 → 5-10%性能向上
   ```

2. **Box層の設計矛盾修正**
   - `tls_sll_box.h:84-88` - C7 rejection削除
   - `ptr_conversion_box.h:44-48` - C7 offset=0削除
   - テスト: `bench_fixed_size_hakmem 200000 1024 128`

#### 後で実施（優先度: 中）
3. **レイヤー分離リファクタリング**（Option A）
   - `core/box/allocation/` ディレクトリ作成
   - `tls_sll_box.h`を3ファイルに分割
   - 期間: 1週間

4. **ドキュメント更新**
   - `CLAUDE.md`: Phase E1の意図を明記
   - `BOX_THEORY.md`: 層構造図追加

---

## 5. 結論

Phase E1-CORRECTは**Header層の完全統一**に成功しました。しかし、**Box層に設計矛盾**が残存しています。

**現状**:
- ✅ Header層: C7特殊ケース0件（完璧）
- ⚠️ Box層: C7特殊ケース18件（設計矛盾）
- ✅ Backend層: C7特殊ケース5件（非致命的）

**推奨事項**:
1. **即座に実施**: C7特殊ケース統一（Box層修正、1-2日）
2. **後で実施**: レイヤー分離リファクタリング（1週間）

**期待効果**:
- C7性能向上: Slow Path → Fast Path（5-10%）
- コード削減: C7特殊ケース70+箇所 → 0箇所
- 保守性向上: 巨大ファイル（560-801行）→ 小ファイル（50-200行）

---

## 付録A: C7特殊ケース完全リスト

### Box層（18件、設計矛盾）

**tls_sll_box.h（11件）**:
- Line 7: コメント "C7 (1KB headerless)"
- Line 72: コメント "C7 (headerless): ptr == base"
- Line 75: コメント "C7 always rejected"
- Line 84-88: C7 rejection in `tls_sll_push`
- Line 251: `next_offset = (class_idx == 7) ? 0 : 1`
- Line 389: コメント "C7 (headerless): next at base"
- Line 397-398: C7 next pointer clear
- Line 455-456: C7 rejection in `tls_sll_splice`
- Line 554: エラーメッセージ "C7 is headerless!"

**ptr_conversion_box.h（7件）**:
- Line 10: コメント "Class 7 (2KB) is headerless"
- Line 43-48: C7 BASE→USER no offset
- Line 69-74: C7 USER→BASE no offset

### Fast Path層（8件、Slow Path強制）

**tiny_alloc_fast.inc.h（8件）**:
- Line 205-207: コメント "C7 (1KB) is headerless"
- Line 209: C7 Slow Path強制
- Line 355: `sfc_next_off = (class_idx == 7) ? 0 : 1`
- Line 387-389: コメント "C7's headerless design"

### Backend層（5件、デバッグのみ）

**tiny_superslab_alloc.inc.h（3件）**:
- Line 629: デバッグログ（failfast level 3）
- Line 648: デバッグログ（failfast level 3）
- Line 775-786: C7 first alloc デバッグログ

**tiny_superslab_free.inc.h（2件）**:
- Line 31-39: C7 first free デバッグログ
- Line 94-99: C7 lightweight guard

### Classification層（3件、コメントのみ）

**front_gate_classifier.h（3件）**:
- Line 9: コメント "C7 (headerless)"
- Line 63: コメント "headerless"
- Line 71: 変数名 `g_classify_headerless_hit`

---

## 付録B: ファイルサイズ統計

```
core/box/*.h (32ファイル):
  560行: tls_sll_box.h            ← 最大
  373行: hak_core_init.inc.h
  327行: pool_core_api.inc.h
  324行: pool_api.inc.h
  313行: hak_wrappers.inc.h
  285行: pool_mf2_core.inc.h
  269行: hak_free_api.inc.h
  266行: pool_mf2_types.inc.h
  244行: integrity_box.h
  90行:  ptr_conversion_box.h      ← 最小（Box層）
  79行:  front_gate_classifier.h

core/tiny_*.inc.h (主要ファイル):
  801行: tiny_superslab_alloc.inc.h  ← 最大
  707行: tiny_alloc_fast.inc.h
  471行: tiny_free_magazine.inc.h
  368行: tiny_superslab_free.inc.h
  315行: tiny_free_fast_v2.inc.h
  222行: tiny_region_id.h
```

**総計**: 約15,000行（`core/box/*.h` + `core/tiny_*.h` + `core/tiny_*.inc.h`）

---

**レポート作成者**: Claude Code
**検証日**: 2025-11-12
**HAKMEMバージョン**: Phase E1-CORRECT