# Phase‑33 — Execution Plan (Native LLVM AOT)

## Milestones

1) Skeleton & Contract (this phase)
- Add C ABI header + stub implementation returning NYI
- CMake project in `c/llvm-native/` without LLVM linkage
- Document API and error policy; keep defaults unchanged (llvmlite)

2) Minimal Codegen
- Implement JSON→IR→OBJ for: const i64 / ret / binop / compare+branch
- Target: Linux x86_64 only; opt-level configurable
- Add canaries mirroring existing AOT tests (return/binop/if)

3) Linking
- Implement `.o + libhako_kernel.a → exe`
- Provide flags for relocation model / LTO (optional)
- Add canaries to assert rc/last-line parity with VM/llvmlite

4) Packaging & Toggle
- Provide `--aot-engine native` / `HAKO_AOT_ENGINE=native`, fall back to llvmlite if native unavailable
- Doc: system LLVM vs. bundled releases; size/perf trade-offs

## Acceptance (Phase 33)
- C ABI skeleton present and isolated; repository builds unchanged by default
- Plan/README written; follow-up work scoped to Phase 34+

---

## Current Blockers (2025‑10‑31)

- Harness error in `ny-llvmc` path: `unexpected indent (mir_call.py, line 26)` → JSON→EXE が停止。
- Workspace includes missing plugin crates (`plugins/nyash-aot-plugin` 等) → `--features llvm` ビルドが失敗。
- AOT userbox canary は環境不足（動的プラグイン未構築、パーサ互換）で SKIP。

## Immediate Steps

1) Fix harness indentation (mir_call.py) → return 7 カナリアを緑化（EXE 生成・rc 7）。
2) Exclude missing plugins from workspace（またはダミーcrate）→ `cargo build --features llvm` が通る状態へ。
3) Optional: アーカイバ helper を復帰（`.o + libnyash_kernel.a → exe`）し、ハーネス迂回のバックアップ経路を確保。

## Notes

- main ブランチは docs のみコミット済み。AOT の作業差分は phase33 ブランチで継続（混在回避）。
- 既定は llvmlite 維持。native は opt‑in（失敗時は llvmlite に自動フォールバック）。