docs: restore docs/private/roadmap from 7b4908f9 (Phase 20.31)

docs/private/roadmap/phases/phase-33/PLAN.md

@@ -0,0 +1,27 @@
+# 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+
+

docs/private/roadmap/phases/phase-33/README.md

@@ -0,0 +1,44 @@
+# 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).