hakmem/CURRENT_TASK.md

# CURRENT_TASK（Rolling, SSOT）

## 0) 今の「正」（SSOT）

- **性能比較の正**: FAST PGO build（`make pgo-fast-full` → `bench_random_mixed_hakmem_minimal_pgo`）＋ **WarmPool=16**（Phase 69 強GOで昇格済み）
- **安全・互換の正**: Standard build（`make bench_random_mixed_hakmem`）
- **観測の正**: OBSERVE build（`make perf_observe`）
- **スコアカード（目標/現在値）**: `docs/analysis/PERFORMANCE_TARGETS_SCORECARD.md`
  - Current baseline（FAST v3 + PGO, Phase 69）: **62.63M ops/s = 51.77% of mimalloc**
  - 次の目標: **M2 = 55%**（残り **+3.23pp**）
- **Mixed 10-run SSOT**: `scripts/run_mixed_10_cleanenv.sh`（`ITERS=20000000 WS=400`、`HAKMEM_WARM_POOL_SIZE=16` デフォルト）

## 1) 迷子防止（経路/観測）

“経路が踏まれていない最適化” を防ぐための最小手順。

- **Route Banner（経路の誤認を潰す）**: `HAKMEM_ROUTE_BANNER=1`
  - 出力: Route assignments（backend route kind）+ cache config（`unified_cache_enabled` / `warm_pool_max_per_class`）
- **Refill観測のSSOT**: `docs/analysis/PHASE70_REFILL_OBSERVABILITY_PREREQS_SSOT.md`
  - WS=400（Mixed SSOT）では miss が極小 → `unified_cache_refill()` 最適化は **凍結（ROIゼロ）**

## 2) 直近の結論（要点だけ）

- **Phase 69（WarmPool sweep）**: `HAKMEM_WARM_POOL_SIZE=16` が **強GO（+3.26%）**、baseline 昇格済み。
  - 設計: `docs/analysis/PHASE69_REFILL_TUNING_0_DESIGN.md`
  - 結果: `docs/analysis/PHASE69_REFILL_TUNING_1_RESULTS.md`
- **Phase 70（観測SSOT）**: 統計の見える化/前提ゲート確立。WS=400 SSOT では refill は冷たい。
  - SSOT: `docs/analysis/PHASE70_REFILL_OBSERVABILITY_PREREQS_SSOT.md`
- **Phase 71/73（WarmPool=16 の勝ち筋確定）**: 勝ち筋は **instruction/branch の微減**（perf stat で確定）。
  - 詳細: `docs/analysis/PHASE70_71_WARMPOOL16_ANALYSIS.md`
- **Phase 72（ENV knob ROI枯れ）**: WarmPool=16 を超える ENV-only 勝ち筋なし → **構造（コード）で攻める段階**。

## 3) 運用ルール（Box Theory + layout tax 対策）

- 変更は必ず **箱 + 境界1箇所 + ENVで戻せる** で積む（Fail-fast、最小可視化）。
- A/B は **同一バイナリでENVトグル**が原則（別バイナリ比較は layout が混ざる）。
- “削除して速い” は封印（link-out/大削除は layout tax で符号反転しやすい）→ **compile-out** を優先。
  - 診断: `scripts/box/layout_tax_forensics_box.sh` / `docs/analysis/PHASE67A_LAYOUT_TAX_FORENSICS_SSOT.md`

## 4) 次の指示書（Active）

### Phase 74（構造）: UnifiedCache hit-path を短くする ✅ **P1 (LOCALIZE) 凍結**

**前提**:
- WS=400 SSOT では UnifiedCache miss が極小 → refill最適化は ROIゼロ。
- WarmPool=16 の勝ちは instruction/branch 微減 → hit-path を短くするのが正攻法。

**Phase 74-1: LOCALIZE (ENV-gated)** ✅ **完了 (NEUTRAL +0.50%)**
- ENV: `HAKMEM_TINY_UC_LOCALIZE=0/1`
- Runtime branch overhead で instructions/branches **増加** (+0.7%/+0.4%)
- 判定: **NEUTRAL (+0.50%)**

**Phase 74-2: LOCALIZE (compile-time gate)** ✅ **完了 (NEUTRAL -0.87%)**
- Build flag: `HAKMEM_TINY_UC_LOCALIZE_COMPILED=0/1` (default 0)
- Runtime branch 削除 → instructions/branches **改善** (-0.6%/-2.3%) ✓
- しかし **cache-misses +86%** (register pressure / spill) → throughput **-0.87%**
- 切り分け成功: **LOCALIZE本体は勝ち、cache-miss 増加で相殺**
- 判定: **NEUTRAL (-0.87%)** → **P1 (LOCALIZE) 凍結**

**結論**:
- P1 (LOCALIZE) は default OFF で凍結（dependency chain 削減の ROI 低い）
- 次: **Phase 74-3 (P0: FASTAPI)** へ進む

**Phase 74-3: P0 (FASTAPI)** 🟡 **次の指示書**

**Goal**: `unified_cache_enabled()` / `lazy-init` / `stats` 判定を **hot loop の外へ追い出す**

**Approach**:
- `unified_cache_push_fast()` / `unified_cache_pop_fast()` API 追加
- 前提: "valid/enabled/no-stats" を caller 側で保証
- Fail-fast: 想定外の状態なら slow path へ fallback（境界1箇所）
- ENV gate: `HAKMEM_TINY_UC_FASTAPI=0/1` (default 0, research box)

**Expected**: +1-2% via branch reduction (P1 と異なる軸)

**判定**:
- **GO**: +1.0% 以上
- **NEUTRAL**: ±1.0%（freeze、次へ）
- **NO-GO**: -1.0% 以下（即 revert）

**参考**:
- 設計: `docs/analysis/PHASE74_UNIFIEDCACHE_HITPATH_STRUCTURAL_OPT_0_DESIGN.md`
- 指示書: `docs/analysis/PHASE74_UNIFIEDCACHE_HITPATH_STRUCTURAL_OPT_1_NEXT_INSTRUCTIONS.md`
- 結果 (P1): `docs/analysis/PHASE74_UNIFIEDCACHE_HITPATH_STRUCTURAL_OPT_2_RESULTS.md`

## 5) アーカイブ

- 詳細ログ: `CURRENT_TASK_ARCHIVE_20251210.md`
- 整理前スナップショット: `docs/analysis/CURRENT_TASK_ARCHIVE.md`