hakmem/docs/analysis/PHASE47_FAST_FRONT_PGO_MODE_INSTRUCTIONS.md

# Phase 47 — FAST Front “PGO mode” fixed config（`HAKMEM_TINY_FRONT_PGO=1` を FAST に適用）

## 目的

FAST build のフロント設定を `HAKMEM_TINY_FRONT_PGO=1`（= compile-time fixed config）で統一し、分岐・間接呼び出し・依存チェーンを減らして **+3〜8%** を狙う。

前提（ここまでの結論）:
- Phase 39 で gate はほぼ枯渇
- Phase 44/45 で cache-miss ではなく dependency chain 側が支配的
- Phase 46A で micro の上限が見えた（関数単体改善×寄与率で 1% 前後）

→ ここからは “個別関数” より **フロント全体の形（compile-time constants）**で勝ちに行く。

## 方針（Box Theory）

- Standard/OBSERVE は維持（安全/観測の正）。
- FAST は「性能測定の正」なので、**固定 config を採用してよい**（Phase 35-B の運用方針と整合）。
- link-out / 物理削除は禁止。`EXTRA_CFLAGS` で切替。

## 変更内容（FASTのみ）

`HAKMEM_TINY_FRONT_PGO=1` を FAST build 全 TU に適用する。

効果:
- `core/box/tiny_front_config_box.h` のマクロ群が **compile-time constants** になる
  - 例: `TINY_FRONT_UNIFIED_CACHE_ENABLED 1` / `TINY_FRONT_METRICS_ENABLED 0` など
- runtime gate 関数呼び出しが消えやすく、依存チェーンと I-cache footprint が減る

注意:
- これは “profile-guided optimization” の PGO ではなく、**fixed configuration** モード（名前が紛らわしい）。

## 実装手順

### Step 0: baseline（FAST v3）

- `make perf_fast` を 1回取り、mean/median を記録。

### Step 1: 新 FAST バイナリターゲット追加

Makefile に新ターゲットを追加（例）:
- `bench_random_mixed_hakmem_fast_front_pgo`
  - `$(MAKE) clean`
  - `$(MAKE) bench_random_mixed_hakmem EXTRA_CFLAGS='-DHAKMEM_BENCH_MINIMAL=1 -DHAKMEM_TINY_FRONT_PGO=1'`
  - `mv ... bench_random_mixed_hakmem_fast_front_pgo`

`perf_fast` と同等の 10-run を回せるようにする:
- `BENCH_BIN=./bench_random_mixed_hakmem_fast_front_pgo scripts/run_mixed_10_cleanenv.sh`

### Step 2: A/B（10-run）

- baseline: `BENCH_BIN=./bench_random_mixed_hakmem_minimal scripts/run_mixed_10_cleanenv.sh`
- treatment: `BENCH_BIN=./bench_random_mixed_hakmem_fast_front_pgo scripts/run_mixed_10_cleanenv.sh`

判定（build-level）:
- GO: **+0.5%** 以上
- NEUTRAL: **±0.5%**
- NO-GO: **-0.5%** 以下（revert / target撤去）

### Step 3: 互換確認（最小）

- `make perf_observe` を 1回（クラッシュ/ASSERT が無いこと）

## 出力ドキュメント

- `docs/analysis/PHASE47_FAST_FRONT_PGO_MODE_RESULTS.md`
  - baseline/treatment mean/median
  - 変更した compile flags
  - 判定（GO/NEUTRAL/NO-GO）
- `docs/analysis/PERFORMANCE_TARGETS_SCORECARD.md` に FAST variant と履歴を追記
-												Phase 54-60: Memory-Lean mode, Balanced mode stabilization, M1 (50%) achievement

## Summary

Completed Phase 54-60 optimization work:

**Phase 54-56: Memory-Lean mode (LEAN+OFF prewarm suppression)**
- Implemented ss_mem_lean_env_box.h with ENV gates
- Balanced mode (LEAN+OFF) promoted as production default
- Result: +1.2% throughput, better stability, zero syscall overhead
- Added to bench_profile.h: MIXED_TINYV3_C7_BALANCED preset

**Phase 57: 60-min soak finalization**
- Balanced mode: 60-min soak, RSS drift 0%, CV 5.38%
- Speed-first mode: 60-min soak, RSS drift 0%, CV 1.58%
- Syscall budget: 1.25e-7/op (800× under target)
- Status: PRODUCTION-READY

**Phase 59: 50% recovery baseline rebase**
- hakmem FAST (Balanced): 59.184M ops/s, CV 1.31%
- mimalloc: 120.466M ops/s, CV 3.50%
- Ratio: 49.13% (M1 ACHIEVED within statistical noise)
- Superior stability: 2.68× better CV than mimalloc

**Phase 60: Alloc pass-down SSOT (NO-GO)**
- Implemented alloc_passdown_ssot_env_box.h
- Modified malloc_tiny_fast.h for SSOT pattern
- Result: -0.46% (NO-GO)
- Key lesson: SSOT not applicable where early-exit already optimized

## Key Metrics

- Performance: 49.13% of mimalloc (M1 effectively achieved)
- Stability: CV 1.31% (superior to mimalloc 3.50%)
- Syscall budget: 1.25e-7/op (excellent)
- RSS: 33MB stable, 0% drift over 60 minutes

## Files Added/Modified

New boxes:
- core/box/ss_mem_lean_env_box.h
- core/box/ss_release_policy_box.{h,c}
- core/box/alloc_passdown_ssot_env_box.h

Scripts:
- scripts/soak_mixed_single_process.sh
- scripts/analyze_epoch_tail_csv.py
- scripts/soak_mixed_rss.sh
- scripts/calculate_percentiles.py
- scripts/analyze_soak.py

Documentation: Phase 40-60 analysis documents

## Design Decisions

1. Profile separation (core/bench_profile.h):
   - MIXED_TINYV3_C7_SAFE: Speed-first (no LEAN)
   - MIXED_TINYV3_C7_BALANCED: Balanced mode (LEAN+OFF)

2. Box Theory compliance:
   - All ENV gates reversible (HAKMEM_SS_MEM_LEAN, HAKMEM_ALLOC_PASSDOWN_SSOT)
   - Single conversion points maintained
   - No physical deletions (compile-out only)

3. Lessons learned:
   - SSOT effective only where redundancy exists (Phase 60 showed limits)
   - Branch prediction extremely effective (~0 cycles for well-predicted branches)
   - Early-exit pattern valuable even when seemingly redundant

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

											
										
										
											2025-12-17 06:24:01 +09:00
+								# Phase 47 — FAST Front “PGO mode” fixed config（`HAKMEM_TINY_FRONT_PGO=1` を FAST に適用）
 								## 目的
 								FAST build のフロント設定を `HAKMEM_TINY_FRONT_PGO=1`（= compile-time fixed config）で統一し、分岐・間接呼び出し・依存チェーンを減らして **+3〜8%** を狙う。
 								前提（ここまでの結論）:
 								- Phase 39 で gate はほぼ枯渇
 								- Phase 44/45 で cache-miss ではなく dependency chain 側が支配的
 								- Phase 46A で micro の上限が見えた（関数単体改善×寄与率で 1% 前後）
 								→ ここからは “個別関数” より **フロント全体の形（compile-time constants）**で勝ちに行く。
 								## 方針（Box Theory）
 								- Standard/OBSERVE は維持（安全/観測の正）。
 								- FAST は「性能測定の正」なので、**固定 config を採用してよい**（Phase 35-B の運用方針と整合）。
 								- link-out / 物理削除は禁止。`EXTRA_CFLAGS` で切替。
 								## 変更内容（FASTのみ）
 								`HAKMEM_TINY_FRONT_PGO=1` を FAST build 全 TU に適用する。
 								効果:
 								- `core/box/tiny_front_config_box.h` のマクロ群が **compile-time constants** になる
 								  - 例: `TINY_FRONT_UNIFIED_CACHE_ENABLED 1` / `TINY_FRONT_METRICS_ENABLED 0` など
 								- runtime gate 関数呼び出しが消えやすく、依存チェーンと I-cache footprint が減る
 								注意:
 								- これは “profile-guided optimization” の PGO ではなく、**fixed configuration** モード（名前が紛らわしい）。
 								## 実装手順
 								### Step 0: baseline（FAST v3）
 								- `make perf_fast` を 1回取り、mean/median を記録。
 								### Step 1: 新 FAST バイナリターゲット追加
 								Makefile に新ターゲットを追加（例）:
 								- `bench_random_mixed_hakmem_fast_front_pgo`
 								  - `$(MAKE) clean`
 								  - `$(MAKE) bench_random_mixed_hakmem EXTRA_CFLAGS='-DHAKMEM_BENCH_MINIMAL=1 -DHAKMEM_TINY_FRONT_PGO=1'`
 								  - `mv ... bench_random_mixed_hakmem_fast_front_pgo`
 								`perf_fast` と同等の 10-run を回せるようにする:
 								- `BENCH_BIN=./bench_random_mixed_hakmem_fast_front_pgo scripts/run_mixed_10_cleanenv.sh`
 								### Step 2: A/B（10-run）
 								- baseline: `BENCH_BIN=./bench_random_mixed_hakmem_minimal scripts/run_mixed_10_cleanenv.sh`
 								- treatment: `BENCH_BIN=./bench_random_mixed_hakmem_fast_front_pgo scripts/run_mixed_10_cleanenv.sh`
 								判定（build-level）:
 								- GO: **+0.5%** 以上
 								- NEUTRAL: **±0.5%**
 								- NO-GO: **-0.5%** 以下（revert / target撤去）
 								### Step 3: 互換確認（最小）
 								- `make perf_observe` を 1回（クラッシュ/ASSERT が無いこと）
 								## 出力ドキュメント
 								- `docs/analysis/PHASE47_FAST_FRONT_PGO_MODE_RESULTS.md`
 								  - baseline/treatment mean/median
 								  - 変更した compile flags
 								  - 判定（GO/NEUTRAL/NO-GO）
 								- `docs/analysis/PERFORMANCE_TARGETS_SCORECARD.md` に FAST variant と履歴を追記