hakmem/docs/analysis/PHASE5_E6_ENV_SNAPSHOT_SHAPE_NEXT_INSTRUCTIONS.md

Phase 5 E6: ENV Snapshot Branch-Shape Fix（結果: NO-GO / FROZEN）

Status（2025-12-14）

• 結果: NO-GO（Mixed: -1.71%）
• 理由: 二重分岐で branch 数/コードサイズが増え、mispredict 改善が吸収できない
• 対応: freeze（追わない）
• 参考: docs/analysis/PHASE5_E6_ENV_SNAPSHOT_SHAPE_AB_TEST_RESULTS.md

注意:

• E6 の “実装” は hot path を肥大化させるため、本線からは外す（doc だけ残すのが安全）。

背景（E5-2 / E5-4 連続 NEUTRAL 後）

• HAKMEM_PROFILE=MIXED_TINYV3_C7_SAFE では HAKMEM_ENV_SNAPSHOT=1 が常用。
• しかし hot path 側（例: malloc_tiny_fast_for_class()）に if (__builtin_expect(hakmem_env_snapshot_enabled(), 0)) のような “OFF 前提” hint が残っている。
• これは steady-state で毎回 mispredict になり得る（enabled が真のとき）。

狙い:

• 意味（semantic）は一切変えず、分岐形だけを “enabled 前提” に寄せる。
• ただし default build では HAKMEM_ENV_SNAPSHOT=0 もあり得るので、MIXED のみ opt-in に限定する（戻せる）。

---

Box Theory（箱の切り方）

• L0: env_snapshot_shape_enabled()（ENV gate, default OFF）
• L1: “shape 変更” は call site だけ（境界 1 箇所ずつ）
• Fail-fast: なし（意味不変なので）
• 見える化: perf / branch-misses のみ（常時ログ禁止）

---

Step 1: ENV gate を追加

新規:

• core/box/env_snapshot_shape_env_box.h
  • ENV: HAKMEM_ENV_SNAPSHOT_SHAPE=0/1（default 0）
  • static inline bool env_snapshot_shape_enabled(void)

有効化ポリシー:

• MIXED_TINYV3_C7_SAFE でのみ bench_setenv_default("HAKMEM_ENV_SNAPSHOT_SHAPE","1") を検討（GO 後）
• 他プロファイルは default OFF のまま

---

Step 2: call site を “enabled 前提” の形に変更（意味不変）

対象（例）:

• core/front/malloc_tiny_fast.h 内の複数箇所
• core/box/tiny_metadata_cache_hot_box.h
• core/box/tiny_legacy_fallback_box.h

置換パターン:

Before:

if (__builtin_expect(hakmem_env_snapshot_enabled(), 0)) {
    const HakmemEnvSnapshot* env = hakmem_env_snapshot();
    x = env->tiny_c7_ultra_enabled;
} else {
    x = tiny_c7_ultra_enabled_env();
}

After（shape gate ON のときだけ形を変える）:

if (__builtin_expect(env_snapshot_shape_enabled(), 0)) {
    if (__builtin_expect(!hakmem_env_snapshot_enabled(), 0)) {
        x = tiny_c7_ultra_enabled_env();
    } else {
        const HakmemEnvSnapshot* env = hakmem_env_snapshot();
        x = env->tiny_c7_ultra_enabled;
    }
} else {
    if (__builtin_expect(hakmem_env_snapshot_enabled(), 0)) {
        const HakmemEnvSnapshot* env = hakmem_env_snapshot();
        x = env->tiny_c7_ultra_enabled;
    } else {
        x = tiny_c7_ultra_enabled_env();
    }
}

注意:

• HAKMEM_ENV_SNAPSHOT=0 のときに mispredict が増えないよう、shape は MIXED だけで使う。

---

Step 3: A/B（Mixed 10-run）

A: shape OFF

HAKMEM_PROFILE=MIXED_TINYV3_C7_SAFE \
  HAKMEM_ENV_SNAPSHOT=1 \
  HAKMEM_ENV_SNAPSHOT_SHAPE=0 \
  ./bench_random_mixed_hakmem 20000000 400 1

B: shape ON

HAKMEM_PROFILE=MIXED_TINYV3_C7_SAFE \
  HAKMEM_ENV_SNAPSHOT=1 \
  HAKMEM_ENV_SNAPSHOT_SHAPE=1 \
  ./bench_random_mixed_hakmem 20000000 400 1

判定:

• GO: mean +1.0% 以上
• ±1.0%: NEUTRAL → freeze
• -1.0% 以下: NO-GO → freeze

---

Step 4: branch-miss を確認（任意）

HAKMEM_PROFILE=MIXED_TINYV3_C7_SAFE \
  HAKMEM_ENV_SNAPSHOT=1 HAKMEM_ENV_SNAPSHOT_SHAPE=0 \
  perf stat -e branches,branch-misses -- \
  ./bench_random_mixed_hakmem 20000000 400 1

HAKMEM_PROFILE=MIXED_TINYV3_C7_SAFE \
  HAKMEM_ENV_SNAPSHOT=1 HAKMEM_ENV_SNAPSHOT_SHAPE=1 \
  perf stat -e branches,branch-misses -- \
  ./bench_random_mixed_hakmem 20000000 400 1

期待:

• branch-misses が下がる（throughput も上がるのが理想）

---

Step 5: 健康診断

scripts/verify_health_profiles.sh

---

Step 6: 昇格（GO のときだけ）

• core/bench_profile.h（MIXED）:
  • bench_setenv_default("HAKMEM_ENV_SNAPSHOT_SHAPE","1")
• docs/analysis/ENV_PROFILE_PRESETS.md に A/B と rollback（=0）追記
• CURRENT_TASK.md を更新