hakmem/CURRENT_TASK.md

# Current Task: Phase E1-CORRECT - 最下層ポインターBox実装

**Date**: 2025-11-13  
**Status**: 🔧 In Progress  
**Priority**: CRITICAL

---

## 🎯 Goal

Phase E1-CORRECT において、**tiny freelist next ポインタのレイアウト仕様と API を物理制約込みで厳密に統一**し、  
C7/C0 特殊ケースや直接 *(void\*\*) アクセス起因の SEGV を構造的に排除する。

---

## ✅ 正式仕様（決定版）

HAKMEM_TINY_HEADER_CLASSIDX フラグ有無と size class ごとに next の格納オフセットを厳密定義する。

### 1. ヘッダ有効時 (HAKMEM_TINY_HEADER_CLASSIDX != 0)

各クラスの物理レイアウトと next オフセット:

- Class 0:
  - 物理: `[1B header][7B payload]` (合計 8B)
  - 制約: offset 1 に 8B pointer は入らない (1 + 8 = 9B > 8B) → 不可能
  - 仕様:
    - freelist 中は header を上書きして next を `base + 0` に格納
    - free 中 header不要のため問題なし
  - next offset: `0`

- Class 1〜6:
  - 物理: `[1B header][payload >= 8B]`
  - 仕様:
    - header は保持
    - freelist next は header 直後の `base + 1` に格納
  - next offset: `1`

- Class 7:
  - 大きなブロック / もともと特殊扱いだった領域
  - 実装と互換性・余裕を考慮し、freelist next は `base + 0` 扱いとするのが合理的
  - next offset: `0`

まとめ:

- `HAKMEM_TINY_HEADER_CLASSIDX != 0` のとき:
  - Class 0,7 → `next_off = 0`
  - Class 1〜6 → `next_off = 1`

### 2. ヘッダ無効時 (HAKMEM_TINY_HEADER_CLASSIDX == 0)

- 全クラス:
  - header なし
  - freelist next は従来通り `base + 0`
  - next offset: 常に `0`

---

## 📦 Box / API 統一方針

重複・矛盾していた Box API / tiny_nextptr 実装を以下の方針で統一する。

### Authoritative Logic

単一の「next offset 計算」と「安全な load/store」を真実として定義:

- `size_t tiny_next_off(int class_idx)`:
  - `#if HAKMEM_TINY_HEADER_CLASSIDX`
    - `return (class_idx == 0 || class_idx == 7) ? 0 : 1;`
  - `#else`
    - `return 0;`
- `void* tiny_next_load(const void* base, int class_idx)`
- `void tiny_next_store(void* base, int class_idx, void* next)`

この3つを中心に全ての next アクセスを集約する。

### box/tiny_next_ptr_box.h

- `tiny_nextptr.h` をインクルード、もしくは同一ロジックを使用し、
  「Box API」としての薄いラッパ/マクロを提供:

例（最終イメージ）:

- `static inline void tiny_next_write(int class_idx, void* base, void* next)`
  - 中で `tiny_next_store(base, class_idx, next)` を呼ぶ
- `static inline void* tiny_next_read(int class_idx, const void* base)`
  - 中で `tiny_next_load(base, class_idx)` を呼ぶ
- `#define TINY_NEXT_WRITE(cls, base, next) tiny_next_write((cls), (base), (next))`
- `#define TINY_NEXT_READ(cls, base)        tiny_next_read((cls), (base))`

ポイント:

- API は `class_idx` と `base pointer` を明示的に受け取る。
- next offset の分岐 (0 or 1) は API 内だけに閉じ込め、呼び出し元での条件分岐は禁止。
- `*(void**)` による直接アクセスは禁止（grep で検出対象）。

---

## 🚫 禁止事項

- Phase E1-CORRECT 以降のコードで以下を使用することは禁止:
  - `*(void**)ptr` などの直接 next 読み書き
  - `class_idx == 7 ? 0 : 1` など、ローカルに next offset を決めるロジック
  - `ALL classes offset 1` 前提のコメントや実装

これらは順次削除・修正対象。

---

## 🔍 現状の問題と対策

### 以前の問題点

- `tiny_nextptr.h` が「ALL classes → offset 1」として実装されていた時期があり、
  - Class 0 に対して offset 1 書き込み → 即時 SEGV
  - Class 7 や一部 call site での不整合も誘発
- `box/tiny_next_ptr_box.h` と `tiny_nextptr.h` が別仕様になり、
  - どちらが正しいか不明瞭な状態で混在していた

### 対策（このドキュメントが指示すること）

1. 正式仕様を上記の通り固定（Class 0,7 → 0 / Class 1〜6 → 1）。
2. `tiny_nextptr.h` をこの仕様に合わせて修正する。
3. `box/tiny_next_ptr_box.h` を `tiny_nextptr.h` ベースの Box API として整理する。
4. 全ての tiny/TLS/fastcache/refill/SLL 関連コードから、直接 offset 計算と `*(void**)` を排除し、
   `tiny_next_*` / `TINY_NEXT_*` API 経由に統一する。
5. grep による監査:
   - `grep -R '\*\(void\*\*\)' core/` で違反箇所検出
   - 残存している場合は順次修正

---

## ✅ Success Criteria

- 10K〜100K iterations のストレステストで全サイズ (C0〜C7) SEGV 0件
- Class 0 に対する offset1 アクセスが存在しない (grep/レビューで確認)
- Class 7 の next アクセスも Box API 経由で一貫 (offset0扱い)
- すべての next アクセスパスが:
  - 「仕様: next_off(class_idx)」に従う tiny_next_* 経由のみで記述されている
- 将来のリファクタ時も、この CURRENT_TASK.md を見れば
  「next はどこにあり、どうアクセスすべきか」が一意に判断できる状態

---

## 📌 実装タスクまとめ（開発者向け）

- [ ] tiny_nextptr.h を上記仕様（0/1 mixed: C0,7→0 / C1-6→1）に修正
- [ ] box/tiny_next_ptr_box.h を tiny_nextptr.h ベースのラッパとして整理
- [ ] 既存コードから next オフセット直書きロジックを撤廃し、Box API に統一
- [ ] `*(void**)` の直接使用箇所を grep で洗い、必要なものを tiny_next_* に置換
- [ ] Release/Debug ビルド + 長時間テストで安定性確認
- [ ] ドキュメント・コメントから「ALL classes offset 1」系の誤記を除去