# 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 側で担当）。