hakmem/docs/analysis/PHASE14_POINTER_CHASE_REDUCTION_2_NEXT_INSTRUCTIONS.md

# Phase 14 v2: Pointer-Chase Reduction — Hot Path Integration Next Instructions（Tiny tcache intrusive LIFO）

## Status

- Phase 14 v1（tcache L1 追加）は Mixed 10-run で **NEUTRAL**（+0.20% mean / +0.59% median）
  - 結果: `docs/analysis/PHASE14_POINTER_CHASE_REDUCTION_1_AB_TEST_RESULTS.md`
  - 実装: `core/box/tiny_tcache_env_box.{h,c}` / `core/box/tiny_tcache_box.h` / `core/front/tiny_unified_cache.h`
- ただし現状の v1 は **free 側（`unified_cache_push()`）だけ tcache に入れて、alloc 側（`tiny_hot_alloc_fast()`）が tcache を消費しない**ため、
  - tcache が「実質 sink」になり、ROI が正しく測れない
  - “tcache-style” の前提（push/pop の対称）が崩れている

Phase 14 v2 は **tiny front の実ホットパス**に tcache を接続して、正しい A/B を取り直す。

---

## 0. 目的（GO 条件）

Mixed 10-run（clean env）で:
- **GO**: mean +1.0% 以上
- **NO-GO**: mean -1.0% 以下（即 rollback / freeze）
- **NEUTRAL**: ±1.0%（research box freeze）

追加ゲート（必須）:
- `HAKMEM_TINY_TCACHE=1` のとき **tcache pop が実際に発生**している（0 なら設計未通電）

---

## 1. Box 図（境界 1 箇所）

```
L0: tiny_tcache_env_box        (ENV gate / refresh / rollback)
  ↓
L1: tiny_tcache_box            (intrusive LIFO: push/pop, cap)
  ↓
L2: tiny_front_hot_box         (hot alloc/free: tcache → unified_cache(FIFO))
  ↓
L3: cold/refill                (unified_cache_refill → SuperSlab)
```

境界は **“tcache miss/overflow → 既存 UnifiedCache”** の 1 箇所に固定する。

---

## 2. 実装パッチ順（小さく積む）

### Patch 1: Hot alloc に tcache pop を接続（必須）

対象:
- `core/box/tiny_front_hot_box.h`

変更:
- `tiny_hot_alloc_fast(int class_idx)` の先頭で
  - `tiny_tcache_try_pop(class_idx)` を試す
  - HIT なら `tiny_header_finalize_alloc(base, class_idx)` で即 return
  - MISS なら既存の FIFO（`cache->slots[head]`）へフォールバック

要件:
- tcache OFF（default）ではホット経路が肥大しないよう最小差分にする
- “確信がないなら fallback” を厳守（Fail-Fast）

### Patch 2: Hot free に tcache push を接続（推奨）

対象:
- `core/box/tiny_front_hot_box.h`

変更:
- `tiny_hot_free_fast(int class_idx, void* base)` の先頭で
  - `tiny_tcache_try_push(class_idx, base)` を試す
  - SUCCESS なら `return 1`
  - overflow / disabled のときだけ既存 FIFO へ

狙い:
- `unified_cache_push()` 経由以外の “直 push” 経路でも tcache が効く状態にする

### Patch 3: 可視化（最小・TLS）

対象候補:
- `core/box/tiny_tcache_box.h`（TLS カウンタ）

追加（debug / research 用）:
- `tcache_pop_hit/miss`
- `tcache_push_hit/overflow`
- “ワンショット dump” を 1 回だけ（ENV opt-in）で出せるようにする

禁止:
- hot path に atomic 統計を置かない（Phase 12 / POOL-DN-BATCH の教訓）

---

## 3. A/B テスト（同一バイナリ）

Baseline:
```sh
HAKMEM_TINY_TCACHE=0 scripts/run_mixed_10_cleanenv.sh
```

Optimized:
```sh
HAKMEM_TINY_TCACHE=1 scripts/run_mixed_10_cleanenv.sh
```

追加（効果が class 依存か確認）:
```sh
HAKMEM_BENCH_C7_ONLY=1 HAKMEM_TINY_TCACHE=0 scripts/run_mixed_10_cleanenv.sh
HAKMEM_BENCH_C7_ONLY=1 HAKMEM_TINY_TCACHE=1 scripts/run_mixed_10_cleanenv.sh
```

cap 探索（research、必要なときだけ）:
```sh
HAKMEM_TINY_TCACHE=1 HAKMEM_TINY_TCACHE_CAP=32  scripts/run_mixed_10_cleanenv.sh
HAKMEM_TINY_TCACHE=1 HAKMEM_TINY_TCACHE_CAP=64  scripts/run_mixed_10_cleanenv.sh
HAKMEM_TINY_TCACHE=1 HAKMEM_TINY_TCACHE_CAP=128 scripts/run_mixed_10_cleanenv.sh
```

---

## 4. 健康診断（必須）

```sh
scripts/verify_health_profiles.sh
```

---

## 5. 判定と扱い

- GO: `bench_profile` への昇格は **MIXED_TINYV3_C7_SAFE のみ**から開始（段階的）
- NEUTRAL/NO-GO: Phase 14 v2 は research box として freeze（default OFF のまま）
- Rollback:
  - `export HAKMEM_TINY_TCACHE=0`

---

## 6. 追加調査（やるなら最小 2 本だけ）

Phase 14 v2 が NEUTRAL の場合、これ以上 “cap 探索” を無制限に回すより、まず原因を 2 本に絞る:

1) **tcache hit 率の可視化（TLS カウンタのみ、atomic 禁止）**  
   - `tiny_tcache_try_pop/push` の hit/miss/overflow を TLS で数え、Mixed/C7-only で “本当に hit しているか” を確認する。

2) **TLS-only nextptr wrapper（fence なし）を tcache 専用に導入する v3**  
   - `tiny_next_load/store` は汎用 SSOT のため fence / header restore 分岐を含む。
   - tcache は TLS-only なので、`tiny_nextptr_offset()` だけを使い、load/store は memcpy/直書き（fenceなし）にする “tcache専用 next” を L1 に閉じ込めて A/B。

上記 2 本が “当たらない” 場合は、Phase 14 系（tcache 追加）は freeze を確定し、別の構造差（metadata/segment/remote/footprint）へ移る。