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

Phase 21.8 — Numeric Core Integration & Builder Support

Status: partially completed（builder/imports導線まで・EXEベンチはPhase 25へ移管）

Goal

Integrate the new numeric core boxes (IntArrayCore + MatI64) into the Hakorune selfhost chain so that:

• Stage‑B → MirBuilder → ny‑llvmc(crate) can emit MIR(JSON) for code that uses:
  • using nyash.core.numeric.intarray as IntArrayCore
  • using nyash.core.numeric.matrix_i64 as MatI64
• The matmul_core microbench（MatI64 + IntArrayCore）については、構造的な導線（builder/imports）まで本フェーズで整備し、EXE/LLVM ベンチ統合は Phase 25 に移管する。

21.6 provides the core boxes; 21.8 focuses on wiring them into the builder/runtime chain（Stage‑B/Bridge/MirBuilder）without changing default behaviour for other code. LLVM での数値コア実行経路は Phase 25（Ring0/Ring1 再編・numeric runtime AOT）で扱う。

Scope (21.8, this host)

• Stage‑B / MirBuilder:

  • Ensure MatI64 and IntArrayCore are recognized as valid boxes when referenced via:
    • using nyash.core.numeric.matrix_i64 as MatI64
    • using nyash.core.numeric.intarray as IntArrayCore
  • Fix the current provider‑emit failure:
    • Error today: [mirbuilder/parse/error] undefined variable: MatI64 during env.mirbuilder.emit.
    • Diagnose and adjust Stage‑B / MirBuilder so that static box references (MatI64.new, A.mul_naive) compile in the same way as other boxes.

• AotPrep / emit pipeline:

  • Keep AotPrep unchanged for now; the goal is to make tools/hakorune_emit_mir.sh succeed on matmul_core sources without special‑casing.
  • Ensure tools/hakorune_emit_mir.sh with:
    • HAKO_APPLY_AOT_PREP=1 NYASH_AOT_COLLECTIONS_HOT=1 NYASH_LLVM_FAST=1 NYASH_MIR_LOOP_HOIST=1
    • can emit valid MIR(JSON) for MatI64/IntArrayCore code.

• Microbench integration:

  • Finish wiring matmul_core in tools/perf/microbench.sh:
    • Hako side: MatI64/IntArrayCore based O(n³) matmul (MatI64.mul_naive).
    • C side: MatI64Core { int64_t *ptr; rows; cols; stride; } with identical algorithm.
  • Accept that performance may still be far from the 80% target; 21.8 focuses on structural integration and parity, not tuning.

Out of scope:

• New optimizations inside AotPrep / CollectionsHot.
• SIMD/blocked matmul kernels (to be handled in a later optimization phase).
• f64/complex matrix variants.

Tasks for implementation (Claude Code)

1. Fix MatI64 visibility in Stage‑B / MirBuilder

   • Reproduce the current failure:
     • Use a small .hako like:
       • using nyash.core.numeric.matrix_i64 as MatI64
       • static box Main { method main(args) { local n = 4; local A = MatI64.new(n,n); return A.at(0,0); } }
     • Confirm env.mirbuilder.emit reports undefined variable: MatI64.
   • Investigate how modules from nyash.toml ("nyash.core.numeric.matrix_i64" = "lang/src/runtime/numeric/mat_i64_box.hako") are made visible to Stage‑B and MirBuilder.
   • Adjust the resolver / module prelude so that MatI64 (and IntArrayCore) are treated like other core boxes:
     • Either via explicit prelude inclusion,
     • Or via module registry entries consumed by the builder.

2. Ensure tools/hakorune_emit_mir.sh can emit MIR(JSON) for matmul_core

   • Once MatI64 is visible, run:
     • HAKO_APPLY_AOT_PREP=1 NYASH_AOT_COLLECTIONS_HOT=1 NYASH_LLVM_FAST=1 NYASH_MIR_LOOP_HOIST=1 NYASH_JSON_ONLY=1 tools/hakorune_emit_mir.sh <matmul_core.hako> tmp/matmul_core.json
   • Acceptance:
     • No undefined variable: MatI64 / IntArrayCore errors.
     • tmp/matmul_core.json is valid MIR(JSON) (same schema as existing matmul case).

3. Finish matmul_core microbench

   • Use the existing skeleton in tools/perf/microbench.sh (case matmul_core):
     • Confirm Hako side compiles and runs under --backend vm.
     • Confirm EXE path works:
       • NYASH_SKIP_TOML_ENV=1 NYASH_LLVM_SKIP_BUILD=1 tools/perf/microbench.sh --case matmul_core --backend llvm --exe --runs 1 --n 64
   • Update benchmarks/README.md:
     • Add matmul_core row with a short description:
       • “MatI64/IntArrayCore vs MatI64Core C struct (ptr+rows+cols+stride)”
     • Record initial ratios (even if far from 80%).

4. Keep existing behaviour stable

   • No changes to default user behaviour, env toggles, or existing benches beyond adding matmul_core.

• Ensure quick/profile smokes (where applicable) remain green with numeric core present.

結果（2025-11-14 時点）

本フェーズは「builder/imports 導線の整備」までを完了とし、EXE/LLVM ベンチ統合は Phase 25 に移管する。

達成済み（21.8）

• Stage‑B / Bridge / MirBuilder:
  • BridgeEnv に imports: HashMap<String,String> フィールドを追加し、using 由来のエイリアス情報（alias → box_type）を保持できるようにした。
  • MapVars::resolve を拡張し、env.imports を参照して MatI64 / IntArrayCore などの using エイリアスを「静的 box 参照」として MIR 上で解決できるようにした。
  • JSON v0 → MIR(JSON) 経路に *_with_imports 版を追加:
    • runner::json_v0_bridge::parse_json_v0_to_module_with_imports
    • host_providers::mir_builder::program_json_to_mir_json_with_imports
  • HAKO_MIRBUILDER_IMPORTS 環境変数を経由して、Stage‑B 側で収集した imports を Rust 側の MirBuilder に渡す配線を追加（読み取り側）。
• Using / imports 収集:
  • collect_using_and_strip の戻り値を (cleaned, prelude_paths, imports) に拡張し、using から alias 情報を収集できるようにした。
  • 既存呼び出し側は _imports として無視するため、従来挙動は維持。
• MatI64/IntArrayCore:
  • using nyash.core.numeric.matrix_i64 as MatI64 / using nyash.core.numeric.intarray as IntArrayCore の構文が Stage‑B/Bridge で undefined variable エラーにならないところまで確認済み（builder 経路に乗る）。

未完・移管（Phase 25 に送るもの）

• matmul_core microbench の EXE/LLVM 統合:
  • MIR 上では MatI64 が BoxCall として現れるが、LLVM ラインには BoxCall 実行経路がなく、AotPrep も MatI64 向けの書き換えを持たない。
  • 「MatI64/IntArrayCore を LLVM までどう運ぶか」（numeric ABI / AotPrep / Ring1 AOT 設計）は、Phase 25「脱Rustランタイム / Ring0-Ring1再編」で扱う。
• Numeric core AOT ライン:
  • IntArrayCore/MatI64 の実装を .hako（Ring1）側に寄せ、LLVM からは汎用 ExternCall/numeric ABI のみを見る構造は Phase 25 の設計スコープとする。

詳細な将来計画・numeric runtime AOT 方針については docs/development/roadmap/phases/phase-25/README.md を参照。