hakmem/docs/analysis/PHASE14_POINTER_CHASE_REDUCTION_1_NEXT_INSTRUCTIONS.md

# Phase 14: Pointer-Chase Reduction v1 — 次の指示書（Tiny tcache intrusive LIFO）

## 0. Status

- Phase 13 v1 / E5-2 で header write tax は **NEUTRAL** → 次の仮説へ
- 次の芯: **thread cache / pointer chase**（system malloc の tcache と構造差が濃厚）

設計: `docs/analysis/PHASE14_POINTER_CHASE_REDUCTION_1_DESIGN.md`

---

## 1. 目的（GO 条件）

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

---

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

### Patch 1: L0 ENV Box（戻せる + refresh）

新規:
- `core/box/tiny_tcache_env_box.h`
- `core/box/tiny_tcache_env_box.c`

ENV:
- `HAKMEM_TINY_TCACHE=0/1`（default: 0）
- `HAKMEM_TINY_TCACHE_CAP=64`（default: 64）

API:
- `tiny_tcache_enabled()`
- `tiny_tcache_cap()`
- `tiny_tcache_env_refresh_from_env()`

要件:
- hot path に `getenv()` を置かない（cached read のみ）

### Patch 2: L1 tcache Box（intrusive LIFO）

新規:
- `core/box/tiny_tcache_box.h`

中身:
- `__thread` の head/count を class 別に持つ（8クラス固定）
- next pointer の読み書きは `tiny_next_store/load` を必須にする

API:
- `tiny_tcache_try_push(class_idx, base) -> bool`
- `tiny_tcache_try_pop(class_idx) -> void*`（BASE or NULL）

### Patch 3: 統合点は unified_cache の内部（call site を増やさない）

修正:
- `core/front/tiny_unified_cache.h`（`unified_cache_push/pop` の先頭に “1回だけ if”）

方針:
- tcache hit: 即 return（配列に触らない）
- miss/overflow: 既存 array cache にフォールバック

### Patch 4: bench_profile の refresh 同期

修正:
- `core/bench_profile.h`

追加:
- `bench_setenv_default(...)` 後に `tiny_tcache_env_refresh_from_env()` を呼ぶ

---

## 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
```

任意（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. 可視化（最小）

必要なら tcache hit/miss を **TLS カウンタ**で持つ（atomic 禁止）。
“勝ち筋確認が必要なときだけ” `fprintf(stderr, ...)` でワンショット dump（常時ログ禁止）。

---

## 5. 昇格（GO の場合のみ）

GO のとき:
1. preset へ追加（まずは `MIXED_TINYV3_C7_SAFE` のみ）
2. `CURRENT_TASK.md` に A/B を記録
3. rollback 手順:
   - `export HAKMEM_TINY_TCACHE=0`

NO-GO/NEUTRAL のとき:
- research box freeze（default OFF のまま保持）

---

## Update（2025-12-15）

v1 の統合点（`core/front/tiny_unified_cache.h`）だけだと、現行の main alloc hot path（`tiny_hot_alloc_fast()`）が tcache を消費しないため、
`HAKMEM_TINY_TCACHE=1` で “sink” になりやすい。

次は hot path（`core/box/tiny_front_hot_box.h`）へ pop/push を接続し、通電した状態で再 A/B を取る（Phase 14 v2）:
- `docs/analysis/PHASE14_POINTER_CHASE_REDUCTION_2_NEXT_INSTRUCTIONS.md`