From 0b306f72f40d98f9eea1a28ee06c63c39c6db537 Mon Sep 17 00:00:00 2001
From: "Moe Charm (CI)" <moecharm@example.com>
Date: Mon, 15 Dec 2025 00:32:56 +0900
Subject: [PATCH] Phase 14 kickoff: Pointer-chase reduction (tcache-style
 intrusive LIFO)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Design and implementation plan for Phase 14 v1:
- Target: Reduce pointer-chase overhead in TinyUnifiedCache
- Strategy: Add intrusive LIFO tcache layer before array-based cache
- Inspired by glibc tcache (per-bin head pointer, intrusive next)

Approach:
- L0: tiny_tcache_env_box (ENV gate: HAKMEM_TINY_TCACHE=0/1, default OFF)
- L1: tiny_tcache_box (intrusive LIFO: push/pop with cap=64)
- Integration: Inside unified_cache_push/pop (minimal call site changes)

Expected benefits:
- tcache hit: No array access, just head pointer + intrusive next
- Better locality (LIFO vs FIFO)
- Closer to system malloc tcache behavior

A/B plan:
- Test: HAKMEM_TINY_TCACHE=0/1 on Mixed 10-run
- GO threshold: +1.0% mean
- Rollback: ENV-gated, default OFF

Files added:
- docs/analysis/PHASE14_POINTER_CHASE_REDUCTION_1_DESIGN.md
- docs/analysis/PHASE14_POINTER_CHASE_REDUCTION_1_NEXT_INSTRUCTIONS.md

Next: Implement Phase 14 v1 patches (ENV box → tcache box → integration)

🤖 Generated with Claude Code

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 ...HASE14_POINTER_CHASE_REDUCTION_1_DESIGN.md | 149 ++++++++++++++++++
 ...TER_CHASE_REDUCTION_1_NEXT_INSTRUCTIONS.md | 111 +++++++++++++
 2 files changed, 260 insertions(+)
 create mode 100644 docs/analysis/PHASE14_POINTER_CHASE_REDUCTION_1_DESIGN.md
 create mode 100644 docs/analysis/PHASE14_POINTER_CHASE_REDUCTION_1_NEXT_INSTRUCTIONS.md

diff --git a/docs/analysis/PHASE14_POINTER_CHASE_REDUCTION_1_DESIGN.md b/docs/analysis/PHASE14_POINTER_CHASE_REDUCTION_1_DESIGN.md
new file mode 100644
index 00000000..caf63702
--- /dev/null
+++ b/docs/analysis/PHASE14_POINTER_CHASE_REDUCTION_1_DESIGN.md
@@ -0,0 +1,149 @@
+# Phase 14: Pointer-Chase Reduction v1（Tiny tcache-style intrusive LIFO）
+
+**Date**: 2025-12-14  
+**Status**: DESIGN（Phase 14 kickoff）
+
+---
+
+## 0. Executive Summary（1枚）
+
+Phase 12 の gap 仮説のうち:
+- Header write tax → Phase 13 v1 / E5-2 の範囲では **NEUTRAL**（決定打にならない）
+
+次の高 ROI 候補は **thread cache / pointer-chase / “tcache 相当の構造差”**。
+
+現状の Tiny frontend は `TinyUnifiedCache`（配列 + head/tail の FIFO）を多用しており、
+- pointer indirection（`cache->slots` 参照）
+- FIFO による “古いブロック再利用”（局所性低下）
+- 操作あたりの命令数（full/empty 判定 + index 更新）
+
+が system malloc（glibc tcache: intrusive LIFO）に比べて不利になり得る。
+
+Phase 14 v1 は Box Theory を維持したまま、**TinyUnifiedCache の前段に “intrusive LIFO tcache” を 1 層追加**する：
+
+- **hit 時**: head pointer + block 内 next だけで完結（配列アクセス無し）
+- **miss / overflow 時**: 既存の UnifiedCache（配列）へフォールバック（境界 1 箇所）
+
+---
+
+## 1. 現状（why）
+
+### 1.1 現行の主要ホット
+
+Phase 10 以降の統合で `front_fastlane_try_free` が集約点になっている（consolidation 成功）。
+その中で “legacy fallback” が `unified_cache_push/pop` に寄るため、TinyUnifiedCache の形状が ROI に直結する。
+
+### 1.2 UnifiedCache の現行形状
+
+- `core/front/tiny_unified_cache.h`:
+  - `slots`（ヒープ確保配列）+ `head/tail`（FIFO）
+  - push/pop で配列アクセスが必ず発生
+
+対して glibc tcache は:
+- per-bin head pointer（intrusive LIFO）
+- small count（上限）だけ
+
+---
+
+## 2. 提案（Phase 14 v1）
+
+### 2.1 追加する箱（Box Theory）
+
+```
+L0: tiny_tcache_env_box          (ENV gate, refresh, rollback)
+  ↓
+L1: tiny_tcache_box              (intrusive LIFO: push/pop, cap, minimal stats)
+  ↓
+L2: tiny_unified_cache_box        (既存: array cache)
+```
+
+**境界は 1 箇所**:
+- `tiny_tcache_try_*()` が fail したら **既存 unified_cache_*() に落とすだけ**。
+
+### 2.2 API（最小）
+
+```c
+// core/box/tiny_tcache_env_box.h
+int tiny_tcache_enabled(void);              // ENV: HAKMEM_TINY_TCACHE=0/1 (default 0)
+uint16_t tiny_tcache_cap(void);             // ENV: HAKMEM_TINY_TCACHE_CAP (default 64, pow2不要)
+void tiny_tcache_env_refresh_from_env(void);// bench_profile putenv 同期用
+
+// core/box/tiny_tcache_box.h
+bool tiny_tcache_try_push(int class_idx, void* base); // handled?
+void* tiny_tcache_try_pop(int class_idx);             // BASE or NULL
+```
+
+実装は `tiny_next_store/load()` に委譲して next layout を SSOT 化する（Phase 13 の教訓を踏襲）。
+
+### 2.3 統合点（最小改造で ROI を出す）
+
+Phase 14 v1 は “call site を増やさない” ため、統合点は **`unified_cache_push/pop` の内部**に置く。
+
+- `unified_cache_push()` 先頭:
+  - tcache が enabled なら `tiny_tcache_try_push()` を試し、成功なら即 return（配列アクセス無し）
+  - 失敗（cap overflow）なら既存の array push にフォールバック
+- `unified_cache_pop()` 先頭:
+  - tcache が enabled なら `tiny_tcache_try_pop()` を試し、成功なら即 return（配列アクセス無し）
+  - miss なら既存の array pop にフォールバック
+
+これにより、FastLane/legacy/他経路の caller を改造せずに効果を出せる。
+
+---
+
+## 3. Invariants / Fail-Fast
+
+- tcache に格納するのは **BASE pointer のみ**（USER は入れない）
+- 一つの block は **tcache or unified_cache のどちらか**にしか居ない（重複禁止）
+- `count <= cap` を常に守る（debug build で assert）
+- next pointer の読み書きは `tiny_next_store/load` のみ（直書き禁止）
+
+Fail-fast（debug のみ）:
+- cap overflow をワンショットで記録（必要なら stats）
+- `base` が怪しい値（<4096 等）の場合 abort（既存 guard パターン）
+
+---
+
+## 4. A/B 計測計画（同一バイナリ）
+
+ENV:
+- `HAKMEM_TINY_TCACHE=0/1`（default 0）
+- `HAKMEM_TINY_TCACHE_CAP=64`（研究用、必要なら）
+
+ベンチ:
+- Mixed: `scripts/run_mixed_10_cleanenv.sh`
+- 追加: C6-heavy 5-run（回帰がないこと）
+
+GO/NO-GO:
+- GO: mean +1.0% 以上
+- NO-GO: mean -1.0% 以下
+- NEUTRAL: ±1.0% → freeze
+
+---
+
+## 5. リスクと対策
+
+### リスク 1: 追加 branch の固定費が勝つ（Phase 11 の再来）
+
+対策:
+- env gate は cached read（getenv を hot path に置かない）
+- `unified_cache_push/pop` 内の “1回だけ if” に限定（call site helper を増やさない）
+
+### リスク 2: next layout の齟齬（C7/C0 など）
+
+対策:
+- next は SSOT: `tiny_next_store/load` を必須化
+- C7 preserve header の research knob とは独立（Phase 13 v1 は freeze）
+
+### リスク 3: tcache が大きすぎて locality を壊す
+
+対策:
+- v1 は cap=64 をデフォルト（glbic tcache 相当）
+- cap の探索は research knob として後段で行う
+
+---
+
+## 6. 期待値（当たり筋）
+
+- tcache hit 率が高い場合、配列アクセス・FIFO の古い再利用を回避できる
+- “system malloc が速い” の差分（tcache 的挙動）に寄せる最短の一手
+
diff --git a/docs/analysis/PHASE14_POINTER_CHASE_REDUCTION_1_NEXT_INSTRUCTIONS.md b/docs/analysis/PHASE14_POINTER_CHASE_REDUCTION_1_NEXT_INSTRUCTIONS.md
new file mode 100644
index 00000000..4e7dac60
--- /dev/null
+++ b/docs/analysis/PHASE14_POINTER_CHASE_REDUCTION_1_NEXT_INSTRUCTIONS.md
@@ -0,0 +1,111 @@
+# 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 のまま保持）
+