hakorune/docs/private/roadmap/phases/phase-20.31/PLAN.md

PLAN — Phase‑20.31

1) LLVM 最適化レベルの統一トグル（既定：O2）

• CLI: --aot-engine {llvmlite|native}（実装済）に加え、ENV による最適化レベル指定を導入/透過。
  • ENV: HAKO_LLVM_OPT_LEVEL=0|1|2|3（alias: NYASH_LLVM_OPT_LEVEL）
  • llvmlite 経路: 環境をハーネスへ透過（未対応でも無害）。
  • native 経路: hako_llvm_set_opt_level(level) を呼び出す（実装は次フェーズで中身を加える）。
• 代表スモーク:
  • O0/O2/O3 で emit→exe→run が PASS。
  • O3 でも if/phi の意味論差が出ないこと（Result 値一致）。

2) MIR プリ最適化（安全セット）

• 目的: 意味論を変えずに IR 形状を整え、LLVM に渡る前にノイズを減らす。
• 最小セット（既定 ON、ブロック内のみ）
  • copy-prop: 単純 copy 連鎖を解消。
  • dead-def: 未使用の dst を削除。
  • cmp+branch fold: 両辺 const かつ直後に branch/ret なら固定化。
  • phi 簡約: 同一入力のみなら copy 化。
• トグル: HAKO_MIR_OPTS=copy,dead,cmpfold,phi（未指定は安全セット ON）
• スモーク: JSON if-diamond/phi で use-before-def が出ないこと、emit 順序回帰テストの緑維持。

3) ユーザーボックス生成（birth）高速化 — 設計と段階導入

• 問題: 動的フィールド登録/Map 経由の初期化でコスト過大。
• 方針: 形状（shape）キャッシュ＋連続領域確保（struct-like）によるファストパスを追加。
  • 形状キー: Box 型ID + フィールド順序/型（コンパイル時または初回起動時に確定）。
  • 実体: 連続領域に固定レイアウトを確保し、初期値を書き込むだけにする。
  • 既存 API は維持（責務は runtime 内部で高速経路に合流）。
• 段階導入（既定 OFF → 観測 → 既定 ON）
  • ENV: HAKO_BOX_BIRTH_FAST=1 で有効化（最初は quick 限定で観測）。
  • 回帰時は TTL を付与（CURRENT_TASK.md に撤去期限を書き、ドキュメント整備）。

4) ベンチ/スモーク

• ベンチ（tools/bench の簡易スクリプト）
  • 算術ループ×1e6、ユーザーボックス birth×1e6、Array push/pop×1e6。
  • C 版の同等プログラムと比較（最低 3 回、最小値採用）。
• スモーク
  • O0/O2/O3 の三点チェック、MIR プリ最適化 ON/OFF で意味論比較。
  • birth-fast 有効時と無効時の等価性（Result と出力）が一致。

5) 受け入れ基準

• 代表ベンチで C の ≥80% を達成。
• quick/integration 緑維持（既定挙動は不変）。
• birth-fast ON の観測で 2 桁％ 改善が見られること。