hakorune/docs/development/roadmap/phases/phase-25.2/README.md

Phase 25.2 — Numeric Microbench & EXE Tuning

Status: proposal（Phase 25 / 25.1 の後続フェーズ）

ゴール

• Phase 25 で整備した numeric core / AotPrep / NYASH_AOT_NUMERIC_CORE の仕組みを前提に、
  • matmul_core を含む numeric 系 microbench（LLVM/EXE）を安定して実行できる状態にする。
  • EXE/LLVM ラインでの性能を観測しやすくし、「VM 側の自己ホスト部分の重さ」と「生成された EXE の速さ」を分離して評価できるようにする。
• Phase 25.1 の Stage0/Stage1 設計に沿って、将来的に Stage1(EXE) から microbench を叩く土台を作る。

スコープ（Phase 25.2）

1) matmul_core microbench EXE ラインの安定化

• 対象:
  • tools/perf/microbench.sh --case matmul_core --backend llvm --exe ...
• 目標:
  • NYASH_AOT_NUMERIC_CORE=1 ON の状態で、matmul_core microbench が LLVM/EXE 経路で安定して実行できること。
  • STRICT（NYASH_AOT_NUMERIC_CORE_STRICT=1）は AotPrep 後の MIR(JSON) に対してのみ適用し、pre-AotPrep の MIR emit/VM 起動を阻害しないこと。
• タスク（例）:
  • provider 経路（env.mirbuilder.emit）の安定化と診断強化（VM ハングや長時間化の原因切り分け）。
  • NYASH_LLVM_DUMP_MIR_IN を使った実際の matmul_core MIR 形状の観察と numeric_core パスの適用確認。

2) コンパイル経路とベンチ経路の分離

• 問題意識:
  • 現状 microbench は「`.hako → Program(JSON) → MIR(JSON) → AotPrep → ny-llvmc → EXE → 実行」を 1 コマンドで行うため、selfhost VM 部分の重さと EXE 実行の重さが混ざりやすい。
• 方針:
  • matmul_core 用に:
    • 一度だけ MIR(JSON) を生成し、その JSON を複数回再利用するモードを用意する（例: tools/dev_numeric_core_prep.sh + ny-llvmc 直呼び）。
    • microbench は「既に生成済みの EXE を何度も実行する」モードと、「.hako からフルコンパイルする」モードを分ける。

3) numeric_core STRICT モードの本番運用ルール

• Phase 25 では:
  • STRICT は AotPrep 後の MIR(JSON) に対してのみチェックするように整理済み。
  • pre-AotPrep 生 MIR へのチェックは Rust 側から削除済み。
• Phase 25.2 での追加整理:
  • microbench / CI で NYASH_AOT_NUMERIC_CORE_STRICT=1 を使う場合のガイドラインを docs に追記。
  • STRICT 違反時の代表的な原因（numeric_core がマッチできないパターン）を例示し、デバッグ手順を DEBUG_NUMERIC_CORE.md に統合。

スコープ外

• Stage0/Stage1 の設計・導線整理自体は Phase 25.1 の責務（本フェーズでは利用側の調整に留める）。
• 新しい numeric ABI の機能追加や IntArrayCore/MatI64 の API 拡張（根幹設計は Phase 25 側で担当）。