hakmem/CURRENT_TASK.md

# CURRENT TASK (Phase 12: Shared SuperSlab Pool – Debug Phase)

Phase12 の設計に沿った shared SuperSlab pool 実装および Box API 境界リファクタリングは導入済み。
現在は **shared backend 有効状態での SEGV 解消と安定化** を行うデバッグフェーズに入っている。

本タスクでは以下をゴールとする:

- shared Superslab pool backend (`hakmem_shared_pool.[ch]` + `hak_tiny_alloc_superslab_backend_shared`) を
  Box API (`hak_tiny_alloc_superslab_box`) 経由で安全に運用できる状態にする。
- `bench_random_mixed_hakmem` 実行時に SEGV が発生しないことを確認し、
  shared backend を実用レベルの「最小安定実装」として確定させる。

---

## 2. 現状サマリ（実装済み）

1. Box/API 境界
   - tiny フロントエンドから Superslab への入口:
     - `hak_tiny_alloc_superslab_box(int class_idx)` に一本化。
   - TLS SLL:
     - slow path を含む呼び出しは `tls_sll_box.h` (`tls_sll_pop(int, void**)` 等) の Box API 経由に統一。

2. shared Superslab pool 実装
   - `hakmem_shared_pool.[ch]`:
     - `SharedSuperSlabPool g_shared_pool` と
       `shared_pool_init`, `shared_pool_acquire_slab`, `shared_pool_release_slab` を実装。
     - SuperSlab を global に管理し、slab 単位で `class_idx` を割当/解放する shared pool 構造を提供。
   - `hakmem_tiny_superslab.c`:
     - `hak_tiny_alloc_superslab_backend_shared(int class_idx)`:
       - `shared_pool_acquire_slab` により `(ss, slab_idx)` を取得。
       - `superslab_init_slab` で未初期化 slab を初期化。
       - ジオメトリは `SUPERSLAB_SLAB0_DATA_OFFSET` + `slab_idx * SUPERSLAB_SLAB_USABLE_SIZE` + `used * stride` を使用。
       - 単純 bump でブロックを返却。
     - `hak_tiny_alloc_superslab_backend_legacy(int class_idx)`:
       - 旧 per-class `g_superslab_heads` ベースの実装を static backend に封じ込め。
     - `hak_tiny_alloc_superslab_box(int class_idx)`:
       - shared backend → 失敗時に legacy backend へフォールバックする実装に更新。
   - `make bench_random_mixed_hakmem`:
     - ビルドは成功し、shared backend を含む構造的な不整合は解消済み。

3. 現状の問題（2025-11-14 更新）
   - `bench_random_mixed_hakmem` は SLL（TLS 単方向リスト）有効時に早期 SEGV。
   - SLL を無効化（`HAKMEM_TINY_TLS_SLL=0`）すると、shared ON/OFF いずれも安定完走（Throughput 表示）。
   - よって、現時点のクラッシュ主因は「共有SS」ではなく「SLL フロント経路の不整合（BASE/USER/next 取り扱い）」である可能性が高い。

以降は、この SEGV を潰し「shared Superslab pool 最小安定版」を完成させるためのデバッグタスクとする。

## 3. デバッグフェーズの具体タスク

### 3-1. shared backend ON/OFF 制御と原因切り分け

1. shared backend スイッチ導入・確認
   - `hak_tiny_alloc_superslab_box(int class_idx)` に環境変数または定数フラグを導入し:
     - `HAKMEM_TINY_SS_SHARED=0` → legacy backend のみ（回帰確認用）
     - `HAKMEM_TINY_SS_SHARED=1` → 現行 shared backend（デバッグ対象）
   - 手順:
     - legacy 固定で `bench_random_mixed_hakmem` 実行 → SEGV が消えることを確認し、問題が shared 経路に限定されることを保証。

### 3-2. shared slab メタデータの一貫性検証

2. `shared_pool_acquire_slab` と `hak_tiny_alloc_superslab_backend_shared` の整合確認
   - 確認事項:
     - `class_idx` 割当時に:
       - `meta->class_idx` が正しく `class_idx` にセットされているか。
       - `superslab_init_slab` 呼び出し後、`capacity > 0`, `used == 0`, `freelist == NULL` になっているか。
     - `meta->used++` / `total_active_blocks++` の更新が free パスの期待と一致しているか。
   - 必要なら:
     - debug build で `assert(meta->class_idx == class_idx)` 等を追加して早期検出。

3. free/refill 経路との整合性
   - 対象ファイル:
     - `tiny_superslab_free.inc.h`
     - `hakmem_tiny_free.inc`
     - `hakmem_tiny_bg_spill.c`
   - 確認事項:
     - pointer→SuperSlab→TinySlabMeta 解決ロジックが:
       - `meta->class_idx` ベースで正しい class を判定しているか。
       - shared/legacy の違いに依存せず動作するか。
     - 空 slab 判定時に:
       - `shared_pool_release_slab` を呼ぶ条件と `meta->used == 0` の扱いが矛盾していないか。
   - 必要な修正:
     - shared slab 専用の「空になった slab の返却」パスを導入し、UNASSIGNED への戻しを一元化。

### 3-3. Superslab registry / LRU / shared pool の連携確認

4. Registry & LRU 連携
   - `hakmem_super_registry.c` の:
     - `hak_super_register`, `hak_super_unregister`
     - `hak_ss_lru_pop/push`
   - 確認:
     - shared pool で確保した SuperSlab も registry に登録されていること。
     - LRU 経由再利用時に `class_idx`/slab 割付が破綻していないこと。
   - 必要に応じて:
     - shared pool 管理下の SuperSlab を区別するフラグや、再利用前のメタリセットを追加。

### 3-4. SEGV の直接解析

5. gdb によるスタックトレース取得（実施）
   - コマンド例:
     - `cd hakmem`
     - `gdb --args ./bench_random_mixed_hakmem`
       - `run`
       - `bt`
   - 結果（抜粋）:
     - `hak_tiny_alloc_fast_wrapper()` 内で SEGV。SLL 無効化で再現しないため、SLL 経路の BASE/USER/next の整合に絞る。

### 3-5. 安定版 shared Superslab pool の確定

6. 修正後確認
   - `HAKMEM_TINY_SS_SHARED=1`（shared 有効）で:
     - `bench_random_mixed_hakmem` が SEGV 無しで完走すること。
     - 簡易的な統計・ログで:
       - shared Superslab が複数 class で共有されていること。
       - メタデータ破綻や異常な解放が発生していないこと。
   - これをもって:
     - 「Phase12 Shared Superslab Pool 最小安定版」が完了。

### 2-3. TLS / SLL / Refill の整合性確保

**スコープ: `core/hakmem_tiny_refill.inc.h`, `core/hakmem_tiny_tls_ops.h`, `core/hakmem_tiny.c`（局所）**

6. **sll_refill_small_from_ss の Phase12 対応**
   - 入力: `class_idx`, `max_take`
   - 動作:
     - shared pool から該当 `class_idx` の slab を取得 or bind。
     - slab の freelist/bump から `max_take` 個を TLS SLL に積む。
   - ここでは:
     - **g_sll_cap_override を参照しない**（将来廃止しやすい形に）。
     - cap 計算は `sll_cap_for_class(class_idx, mag_cap)` に集約。

7. **tiny_fast_refill_and_take / TLS SLL 経路の一貫性**
   - `tiny_fast_refill_and_take` が:
     - まず TLS SLL / FastCache を見る。
     - 足りなければ `sll_refill_small_from_ss` を必ず経由するよう整理（旧経路の枝刈り）。
   - ただし:
     - 既存インラインとの整合性を崩さないよう、**分岐削除は段階的に**行う。

### 2-4. g_sll_cap_override の段階的無効化（安全版）

8. **参照経路のサニタイズ（非破壊）**
   - `hakmem_tiny_intel.inc`, `hakmem_tiny_background.inc`, `hakmem_tiny_init.inc` などで:
     - g_sll_cap_override を書き換える経路を `#if 0` or コメントアウトで停止。
     - 配列定義自体はそのまま残し、リンク切れを防ぐ。
   - `sll_cap_for_class()` は Phase12 ポリシーに従う実装に置き換える。
   - これにより:
     - 実際の SLL cap は sll_cap_for_class 経由に統一されるが、
     - ABI/シンボル互換性は保持される。

9. **ビルド & アセンブリ確認**
   - `make bench_random_mixed_hakmem`
   - `gdb -q ./bench_random_mixed_hakmem -ex "disassemble sll_refill_small_from_ss" -ex "quit"`
   - 確認項目:
     - g_sll_cap_override 更新経路は実際には使われていない。
     - sll_refill_small_from_ss が shared SuperSlab pool を用いる単一ロジックになっている。

### 2-5. Shared Pool 実装の検証とバグ切り分け

10. **機能検証**
    - `bench_random_mixed_hakmem` を実行:
      - SIGSEGV / abort の有無
      - ログと `HAKMEM_TINY_SUPERSLAB_TRACE` で shared pool の挙動を確認。

11. **パフォーマンス確認**
    - 目標: 設計書の期待値に対し、オーダーとして妥当な速度になっているか:
      - 9M → 70–90M ops/s のレンジを狙う（まずは退行していないことを確認）。

12. **問題発生時の切り分け**
    - クラッシュ/不正挙動があれば:
      - まず shared pool 周辺（slab class_idx, freelist 管理, owner/bind/unbind）に絞って原因特定。
      - Tiny front-end (bump, SLL, HotMag 等) を疑うのはその後。

---

## 3. 実装ルール（再確認）

- hakmem_tiny.c は write_to_file で全書き換えしない。
- 変更は:
  - `#if 0` / コメントアウト
  - 局所的な関数実装差し替え
  - 新しい shared pool 関数の追加
  - 既存呼び出し先の付け替え
  に限定し、逐次ビルド確認する。

---

## 4. 直近の変更（2025-11-14 追記）

- 定数/APIの復元・宣言不足解消（`SUPERSLAB_LG_*`, 所有権API, active dec, fail-fast スタブ 等）。
- Box 2 drain 境界を `_ss_remote_drain_to_freelist_unsafe()` に一本化。
- `tiny_fast_pop()` が USER を返していた不具合を修正（BASE返却へ）。
- SLL トグルの実効化:
  - free v2（ヘッダ系）で `g_tls_sll_enable==0` 時は即スローパスへ。
  - alloc fast でも SLL 無効時は TLS SLL pop を完全スキップ。
- `tls_sll_box` の capacity > 1<<20 を「無制限」扱いへ（過剰警告を抑制）。

暫定ガイド（shared の検証を先に進めるため）
- `HAKMEM_TINY_TLS_SLL=0` で shared ON/OFF の安定動作を確認し、shared 経路の SEGV 有無を切り分ける。

次の一手（SLL ルートの最小修正）
1) SLL push/pop すべての呼び出しを Box API 経由（BASEのみ）に強制。直書き・next手計算を禁止。
2) `tls_sll_box` にデバッグ限定の軽量ガードを追加（slab範囲＋stride整合）して最初の破綻ノードを特定。
3) 必要なら一時的に `HAKMEM_TINY_SLL_C03_ONLY=1`（C0–C3 のみ SLL 使用）で範囲を狭め、原因箇所を早期確定。

### 現在のトリアージ結果（2025-11-14 後半）

- 共有SS: SLL を C0..C4 に限定（`HAKMEM_TINY_SLL_MASK=0x1F`）で ON は安定完走。OFF（legacy）は SEGV（別途）
- SLL: C5（256B）を含めると SEGV 再現。`HAKMEM_TINY_HOTPATH_CLASS5=0` にすると安定化。
  - 対策（小変更）:
    - クラス4以上の alloc fast POP は `tls_sll_pop()`（Box API）で安全化。
    - SLL PUSH は `HAKMEM_TINY_SLL_SAFEHEADER=1` でヘッダ不一致時に上書きせず拒否（blind write回避）。
    - class5 ホットパスは POP/PUSH をガード付き（`tls_list_pop/push`）に変更。
  - それでも `g_tiny_hotpath_class5=1` だと再現 → ホットパス経路のどこかに BASE/USER/next 整合不備が残存。
  - 当面の安定デフォルト: `g_tiny_hotpath_class5=0`（Env で A/B 可: `HAKMEM_TINY_HOTPATH_CLASS5=1`）。

### C5 SEGV 根治（実装済み・最小パッチ）

- 直接原因（再現ログ/リングより）
  - TLS SLL へ push される C5 ノードの header が 0x00（`safeheader` による reject が連発）
  - パターン: 連番アドレス（`...8800, ...8900, ...8a00, ...`）で header=0 → carve/remote 経由の未整備ノード
- 修正点（Box 境界厳守の“点”修正）
  - Remote Queue → FreeList 変換時に header を復元
    - ファイル: `core/hakmem_tiny_superslab.c:120` 付近（`_ss_remote_drain_to_freelist_unsafe`）
    - 処理: クラス1–6は `*(uint8_t*)node = HEADER_MAGIC | (cls & HEADER_CLASS_MASK)` を実行後、`tiny_next_write()` で next を Box 形式に書換
  - Superslab→TLS SLL への refill 時に header を整備
    - ファイル: `core/hakmem_tiny_refill.inc.h:...`（`sll_refill_small_from_ss`）
    - 処理: SLL へ積む直前にクラス1–6の header を設定してから `tls_sll_push()`
  - 参考: 旧 `pool_tls_remote.c` も Box API 化（未使用系だが将来不整合防止）
- 検証（リング+ベンチ）
  - 環境: `HAKMEM_TINY_SLL_MASK=0x3F HAKMEM_TINY_SLL_SAFEHEADER=1 HAKMEM_TINY_HOTPATH_CLASS5=1`
  - 以前: `tls_sll_reject(class=5)` が多数 → SIGSEGV
  - 以後: `bench_random_mixed_hakmem 200000 256 42` 正常完走（リングに tls_sll_* 異常なし）
  - C5 単独（`mask=0x20`）でも異常なしを確認

### 次の実装（根治方針／小粒）

1) 共有SSの観測を先に確定（`HAKMEM_TINY_SLL_MASK=0x1F` でON/OFFのA/B、軽いFail‑Fast/リング有効）
2) C5根治: C5のみON（`HAKMEM_TINY_SLL_MASK=0x20`、`HAKMEM_TINY_SLL_SAFEHEADER=1`、`HAKMEM_TINY_HOTPATH_CLASS5=0`）で短尺実行→最初の破綻箇所をログ採取
   - 追加可視化（異常時のみリング記録）: `HAKMEM_TINY_SLL_RING=1 HAKMEM_TINY_TRACE_RING=1`
     - 追加イベント: `tls_sll_reject`（safeheaderで拒否）, `tls_sll_sentinel`（リモート哨戒混入）, `tls_sll_hdr_corrupt`（POP時ヘッダ不整合）
     - 実行例: `HAKMEM_TINY_SLL_MASK=0x20 HAKMEM_TINY_SLL_SAFEHEADER=1 HAKMEM_TINY_HOTPATH_CLASS5=0 HAKMEM_TINY_SLL_RING=1 HAKMEM_TINY_TRACE_RING=1 ./bench_random_mixed_hakmem 100000 256 42`
3) 該当箇所（BASE/USER/next、ヘッダ整合）に点で外科修正（~20–30行）。
4) 段階的にマスク拡張（C6→C7）し再検証。

---

## 5. Tiny フロント最適化ロードマップ（Phase 2/3 反映）

目的: 全ベンチで強い Tiny 層（≤1KB）を、箱理論の境界を守ったまま高速化。配列ベース（QuickSlot/FastCache）を主役に、SLL はオーバーフロー/合流専用に後退配置する。

構造（箱と境界）
- L0: QuickSlot（C0–C3向け 6–8 スロット固定）
  - 配列 push/pop だけ。ノードに一切書かない（BASE/USER/next 不触）。
  - Miss→L1。
- L1: FastCache（C0–C7、cap 128–256）
  - Refill は SS→FC へ“直補充”のみ（目標 cap まで一気に埋める）。
  - 1個返却: FC→返却（ヘッダ整備は Box 内 1 点）。
- L2: TLS SLL（Box API）
  - 役割は「オーバーフロー/合流」のみ（Remote Drain の合流や FC 溢れ時）。
  - アプリの通常ヒット経路からは外す（alloc 側の inline pop は行わない）。
- 採用境界（1 箇所維持）
  - `superslab_refill()` に adopt→remote_drain→bind→owner の順序を集約。
  - Remote Queue（Box 2）は push（offset0 書き）専任、drain は境界 1 箇所のみ。

A/B トグル（既存に追加・整理）
- `HAKMEM_TINY_REFILL_BATCH=1`（P0: SS→FC 直補充 ON）
- `HAKMEM_TINY_P0_DIRECT_FC_ALL=1`（全クラス FC 直補充）
- `HAKMEM_TINY_FRONT_DIRECT=1`（中間層をスキップし FC 直補充→FC 再ポップ、既定 OFF）
- プリセット（ベンチ良好）: `HAKMEM_TINY_REFILL_COUNT_HOT=256 HAKMEM_TINY_REFILL_COUNT_MID=96 HAKMEM_TINY_BUMP_CHUNK=256`

レガシー整理方針（本体を美しく）
- 入口/出口をモジュール化し、本体は 500 行以内を目安に維持。
  - front 層: `core/front/quick_slot.h`, `core/front/fast_cache.h`, `core/front/front_gate.h`
  - refill 層: `core/refill/ss_refill_fc.h`（SS→FC 直補充の 1 本化）
  - SLL 層（後退配置）: `core/box/tls_sll_box.h` のみ公開、呼出しは refill/合流だけに限定
- レガシー経路の段階的削除/封印
  - inline SLL pop（C0–C3 用）や SFC cascade の常用経路を削除/既定無効化。
  - `.bak` 系や重複/未使用ユーティリティを整理（削除）
  - すべて A/B ガード付きで移行、Fail‑Fast とリングは“異常時のみ”記録。

受け入れ基準（箱単位）
- Front（L0/L1）ヒット率>80% を狙い、Refill 回数/1 回あたり取得数・SS 書換回数を計測。
- Remote Drain は採用境界 1 箇所だけで発生し、drain 後の `remote_counts==0` を保証。
- ベンチ指標（単スレ）
  - 128/256B: 15M→30M→60M の順に上積み（A/B でトレンド確認）。
- 安定性: sentinel 混入・ヘッダ不整合は Fail‑Fast、リングは異常時のみワンショット。

実装ステップ（Phase 2/3）
1) SS→FC 直補充の標準化（現行 `HAKMEM_TINY_REFILL_BATCH` を標準パスに昇格）
2) L0/L1 先頭化（alloc は FC→返却が基本、SLL は合流専用）
3) SFC は残差処理へ限定（既定 OFF、A/B 実験のみ）
4) レガシー経路の削除・モジュール化（500 行以内目安で本体を分割）
5) プリセットの標準化（Hot-heavy をデフォルト、A/B で Balanced/Light 切替）

---

## 6. 現在の進捗と次作業（Claude code 君に引き継ぎ）

完了済み（沙汰の通り）
- 新モジュール: `core/refill/ss_refill_fc.h`（SS→FC 直補充、236行）
- Front モジュール化: `core/front/quick_slot.h`, `core/front/fast_cache.h`
- Front‑Direct 経路: alloc/free 双方で SLL バイパス（ENV: `HAKMEM_TINY_FRONT_DIRECT=1`）
- Refill dispatch: ENV で `ss_refill_fc_fill()` を使用（`HAKMEM_TINY_REFILL_BATCH/…DIRECT_FC_ALL`）
- SFC cascade: 既定 OFF（ENV: `HAKMEM_TINY_SFC_CASCADE=1` で opt‑in）
- ベンチ短尺での安定確認（SLL イベント 0, SEGV なし）

未了・次作業（Claude code 君にお願い）
1) レガシー封印/削除（A/B 残し）
   - inline SLL pop 常用呼び出しを封印（`#if HAKMEM_TINY_INLINE_SLL` 未定義時は無効）
   - `.bak` 系や未使用ユーティリティの削除（参照有無を `rg` で確認）
   - SFC cascade は ENV でのみ有効（既定 OFF の確認）
2) Refill 一本化の明文化
   - `ss_refill_fc_fill()` を唯一の補充入口に昇格（コメントと呼び出し点整理）
   - Front‑Direct 時は SLL/TLS List を通らないことをコード上明示
3) 128/256 専用ショートパスの薄化（FC 命中率 UP）
   - C0–C3: QuickSlot→FC→（必要時のみ）直補充→FC 再ポップ
   - C4–C7: FC→（必要時のみ）直補充→FC 再ポップ
4) 本体の簡素化（500 行目安）
   - front*/refill*/box* への分割を継続、入口/出口の箱のみ本体に残す

ベンチの推奨プリセット（再起動後の確認用）
```
HAKMEM_BENCH_FAST_FRONT=1 \
HAKMEM_TINY_FRONT_DIRECT=1 \
HAKMEM_TINY_REFILL_BATCH=1 \
HAKMEM_TINY_P0_DIRECT_FC_ALL=1 \
HAKMEM_TINY_REFILL_COUNT_HOT=256 \
HAKMEM_TINY_REFILL_COUNT_MID=96 \
HAKMEM_TINY_BUMP_CHUNK=256
```

備考: 既存の SLL 由来 SEGV は Front‑Direct 経路で回避済。SLL 経路は当面合流専用に後退配置し、常用経路からは外す。


備考（計測メモ）
- Phase 0/1 の改善で ~10M→~15M。Front-Direct 単体はブレが増え安定増速せず（既定 OFF）。
- 次は FC 命中率を上げる配分とリフィル簡素化で 30–60M を狙う。