hakmem/docs/design/BOX3_REFACTORING.md

# Box 3 Refactoring Complete - Geometry & Capacity Calculator

## 📦 **概要**

Box理論に基づき、Stride/Capacity/Slab Base計算を**単一の責任Box**に集約しました。

---

## 🎯 **Box 3の責任**

### 新設ファイル: `core/tiny_box_geometry.h`

**責任範囲**:
1. **Stride計算**: Block size + header（C7はheaderless）
2. **Capacity計算**: Usable bytes / stride（Slab 0は特殊容量）
3. **Slab Base計算**: Slab 0の2048オフセット処理
4. **境界検証**: Linear carveのFail-Fastガード

---

## 📋 **提供API**

### 1️⃣ **Stride計算**
```c
size_t tiny_stride_for_class(int class_idx);
```
- C7 (1KB): `1024` (headerless)
- C0-C6: `class_size + 1` (1-byte header)

### 2️⃣ **Capacity計算**
```c
uint16_t tiny_capacity_for_slab(int slab_idx, size_t stride);
```
- Slab 0: `SUPERSLAB_SLAB0_USABLE_SIZE / stride`
- Slab 1+: `SUPERSLAB_SLAB_USABLE_SIZE / stride`

### 3️⃣ **Slab Base取得**
```c
uint8_t* tiny_slab_base_for_geometry(SuperSlab* ss, int slab_idx);
```
- Slab 0: `ss + SLAB_SIZE * 0 + SUPERSLAB_SLAB0_DATA_OFFSET`
- Slab 1+: `ss + SLAB_SIZE * slab_idx`

### 4️⃣ **Block Address計算**
```c
void* tiny_block_at_index(uint8_t* base, uint16_t index, size_t stride);
```
- `base + (index * stride)`

### 5️⃣ **境界検証**
```c
int tiny_carve_guard(int slab_idx, uint16_t carved, size_t stride, uint32_t reserve);
int tiny_carve_guard_verbose(...);  // Debug版（詳細ログ付き）
```

---

## 🔧 **修正したファイル**

### ✅ **Box 2 (Refill Dispatcher)**
- `core/hakmem_tiny_refill.inc.h`
  - ❌ Before: `size_t bs = g_tiny_class_sizes[c] + ((c != 7) ? 1 : 0);` （4箇所重複）
  - ✅ After: `size_t bs = tiny_stride_for_class(c);`
  - ❌ Before: `uint8_t* base = tiny_slab_base_for(...);`
  - ✅ After: `uint8_t* base = tiny_slab_base_for_geometry(...);`

### ✅ **Box 2 - P0 Optimized Path**
- `core/hakmem_tiny_refill_p0.inc.h`
  - 2箇所のstride計算を統一
  - Slab base/limit計算をBox 3委譲

### ✅ **Box 4 (SuperSlab Manager)**
- `core/tiny_superslab_alloc.inc.h`
  - Linear alloc, Freelist alloc, Retry pathをBox 3使用
  - Debug guardsをBox 3のAPIに置き換え

### ✅ **Box 5 (SuperSlab Primitives)**
- `core/superslab/superslab_inline.h`
  - `tiny_slab_base_for()` → Box 3へ委譲する薄いwrapperに変更
  - 後方互換性のためwrapperは維持

---

## 🐛 **C7 (1KB) バグ修正への寄与**

### **問題**: メインパス（Legacy refill）でC7のみSEGV発生

### **仮説**: Box境界が曖昧だったため、C7特有の処理が漏れていた

| 処理 | Before（分散） | After（集約） |
|------|----------------|---------------|
| Stride計算 | 各ファイルで個別実装（7箇所） | Box 3の1箇所のみ |
| Slab base計算 | 各ファイルで重複（5箇所） | Box 3の1箇所のみ |
| Capacity計算 | 各ファイルで独自実施 | Box 3の1箇所のみ |
| C7 headerless処理 | `(class_idx != 7) ? 1 : 0` が散在 | Box 3で明示的に扱う |

### **期待される効果**:
1. **C7の特殊処理が明示的**になる → バグが入りにくい
2. **単一の真実の源**により、修正が1箇所で済む
3. **境界検証が統一**される → Debug時のFail-Fastが確実

---

## 📊 **コード削減効果**

- **重複コード削除**: 約80行（stride/capacity/base計算の重複）
- **Box 3新設**: 約200行（集約+ドキュメント）
- **ネット増**: +120行（可読性・保守性の大幅向上と引き換え）

---

## 🚀 **次のステップ**

### **Phase 1: ビルド検証**
```bash
./build.sh release bench_fixed_size_hakmem
./build.sh debug bench_fixed_size_hakmem
```

### **Phase 2: C7デバッグ**
Box 3により、以下が容易になります：

1. **Stride/Capacity計算の検証**
   - `tiny_stride_for_class(7)` が正しく `1024` を返すか
   - `tiny_capacity_for_slab(0, 1024)` が正しい容量を返すか

2. **Slab Base計算の検証**
   - `tiny_slab_base_for_geometry(ss, 0)` が正しいオフセットを適用するか

3. **境界検証の有効化**
   - Debug buildで `tiny_carve_guard_verbose()` の詳細ログ出力

### **Phase 3: Task先生によるデバッグ**
```bash
# Debug build with verbose guards
./build.sh debug bench_fixed_size_hakmem

# Run C7 with fail-fast level 2
HAKMEM_TINY_REFILL_FAILFAST=2 \
./bench_fixed_size_hakmem 200000 1024 128
```

---

## 📝 **Box理論の勝利**

### **Before (Box境界曖昧)**:
```
[ hakmem_tiny_refill.inc.h ]
  ├─ stride計算 × 3
  ├─ slab_base計算 × 3
  └─ capacity計算（implicit）

[ tiny_superslab_alloc.inc.h ]
  ├─ stride計算 × 2
  ├─ slab_base計算 × 2
  └─ capacity計算（implicit）

[ hakmem_tiny_refill_p0.inc.h ]
  ├─ stride計算 × 2
  └─ slab_base計算 × 2
```

### **After (Box 3で集約)**:
```
┌─────────────────────────────┐
│ Box 3: Geometry Calculator  │
│  ├─ stride_for_class()      │ ← Single Source of Truth
│  ├─ capacity_for_slab()     │ ← C7特殊処理を明示
│  ├─ slab_base_for_geometry()│ ← Slab 0オフセット処理
│  ├─ block_at_index()        │ ← 統一されたアドレス計算
│  └─ carve_guard_verbose()   │ ← Fail-Fast検証
└─────────────────────────────┘
         ↑
         │ (呼び出し)
         │
┌────────┴────────┬─────────────────┬──────────────────┐
│ Box 2: Refill   │ Box 2: P0 Path  │ Box 4: SuperSlab │
│ (Legacy)        │ (Optimized)     │ Manager          │
└─────────────────┴─────────────────┴──────────────────┘
```

---

## ✅ **受け入れ基準**

- [x] Box 3新設完了（`core/tiny_box_geometry.h`）
- [x] 全ファイルでstride/capacity/base計算をBox 3に統一
- [x] C7特殊処理（headerless）がBox 3で明示的
- [ ] Release buildコンパイル成功
- [ ] Debug buildコンパイル成功
- [ ] 256B (C5) 安定性維持（3/3 runs成功）
- [ ] 1KB (C7) SEGV修正（次フェーズ）

---

**Box理論により、コードの責任境界が明確になり、C7バグのデバッグが容易になりました！** 🎉