hakorune/docs/private/roadmap/phases/phase-33

Phase‑33 — Native LLVM AOT (C ABI) Skeleton

目的

• llvmlite 既存経路を維持しつつ、ネイティブLLVM（C++実装）を C ABI で公開する薄いライブラリを用意し、段階的に自己完結AOTに移行する。

スコープ

• C ABI の契約を先に確定（関数名・戻り値・エラー方針）。
• ひな形（ビルド可能だが NYI 戻り）のライブラリを作成。
• 既存の quick/integration は既定を llvmlite のままにする（破壊的変更なし）。

非スコープ（本フェーズ）

• 実際の LLVM コード生成/リンク実装（次フェーズ）。
• マルチターゲット対応・最適化パスの詳細調整。

配置

• ライブラリ: c/llvm-native/ （CMakeベース）
  • include/hako_llvm.h — C ABI ヘッダ
  • src/hako_llvm.cpp — 骨格（NYI 返却）
  • CMakeLists.txt — いまは LLVM リンク未設定（スケルトン）

契約（C ABI の要旨）

• 初期化/終了: hako_llvm_init, hako_llvm_shutdown
• 設定: hako_llvm_set_opt_level, hako_llvm_set_reloc_model
• 生成: hako_llvm_emit_obj(mir_json → .o), hako_llvm_link_exe(.o + runtime → exe)
• 返却: 0=OK、負値=エラー。err に安定タグ（例: [aot/codegen] …）

導入方針

• 既定は llvmlite 維持。--aot-engine {llvmlite|native} などのトグルで opt‑in。
• 共有ライブラリ + システムLLVM 依存を基本とし、静的単一バイナリは用途限定で後続検討。

受け入れ基準（本フェーズ）

• C ABI ヘッダと NYI 実装がリポジトリに追加され、ビルド骨格が整っている。
• 既存スモークに影響なし（既定経路に変更なし）。

ENV / Toggles

• HAKO_AOT_ENGINE (llvmlite|native) — default llvmlite, native opt-in
• HAKO_LLVM_TOOL, HAKO_LLVM_LINKER — optional overrides for clang toolchain
• HAKO_LLVM_TARGET_TRIPLE, HAKO_LLVM_CPU, HAKO_LLVM_FEATURES — target hints
• If native engine is unavailable, pipeline falls back to llvmlite automatically

Fallback

• If native AOT fails or library is missing, llvmlite pipeline remains active.
• Quick / integration suites keep llvmlite as default (no regression risk).

Status Update — 2025‑10‑31

現状の確認と課題（main はクリーン、作業は phase33 側で継続）

• EXE 最小カナリア（return 7）は未緑化。

  • ny-llvmc（llvmlite ハーネス）で JSON→EXE が失敗。
    • エラー: unexpected indent (mir_call.py, line 26)（ハーネスの整備不足）。
  • cargo build --features llvm は workspace に含まれる欠損プラグイン（plugins/nyash-aot-plugin）で失敗。
    • 対処方針: workspace から欠損プラグインを一時除外、またはプレースホルダcrateを復旧。

• AOT UserBox マニフェストカナリアは環境未整備で SKIP。

  • 動的プラグイン未構築（stringbox/integerbox 等）。
  • パーサ互換（; の受理）と HAKO_PARSER_AUTO_FALLBACK=1 の実効も要確認。

次の一手（小さく前進）

• A) ハーネス修正（最短で EXE 緑化）
  • src/llvm_py/harness/mir_call.py のインデント修正 → ny-llvmc --emit exe で return 7 を通す。
• B) Workspace 調整
  • 欠損プラグインを Cargo.toml の workspace から除外（またはダミーcrate登録）して --features llvm を通す。
• C) 代替ルートの準備（任意）
  • アーカイバ経路の helper（.o + libnyash_kernel.a → exe）を復帰し、ハーネス依存を迂回可能にする。

進捗メモ（2025-10-31夕方）

• ✅ A) ハーネス修正済（mir_call.py indentation fix）
• ✅ B) Workspace exclude 適用済（欠損プラグインを除外）
• ⏳ NyRT(host_handles) へ移行中
  • encode.rs / plugin/{array,map,console,future,instance,invoke,invoke_core,string} などは jit::rt::handles から runtime::host_handles へ置換済み。
  • 残TODO: crates/nyash_kernel/src/lib.rs 全域と plugin/semantics.rs の to_handle/get を host_handles に揃え、i64→u64 キャストを整理する。
• 🧱 libnyash_kernel.a が未生成なため EXE リンクは保留。上記残TODO完了後に return 7 カナリアで確認する。

運用メモ

• main は docs 復元のみコミット済み。AOT 関連の差分は phase33 ブランチ（または stash）で保全し、段階的に進める。