# Phase 20.20 — C ABI Export via LLVM（設計・計画）

目的
- Hakorune スクリプトから LLVM（llvmlite）を用いて C ABI 互換の関数をエクスポートできる最小ラインを構築する。
- Rust 層の一部（AOT/エクスポート境界）を置き換え可能な薄い導線を用意し、段階的に Rust 依存を薄くする。

スコープ（段階導入）
- 短期（Phase 20.20）: プリミティブ型（i64/i32）限定の純関数エクスポート。
  - `@extern_c("c_symbol")` 注釈を MIR JSON へ反映。
  - llvmlite で C calling convention（ccc）・unmangled symbol・visibility を設定したラッパー関数を生成。
  - C ヘッダー自動生成（extern "C"、stdint.h 依存、最小プロトタイプ）。
- 中期（次フェーズ）: String（const char* readonly）、Array（ptr+len 構造体）の読み出しサポート。
- 長期: Box ABI（Arc/RefCell 相当）と GC 連携（高リスク。段階的に）

進捗（2025‑10‑30, M2 到達）
- Python/llvmlite ビルダーに C‑ABI ラッパ生成を実装（flags.extern_c / metadata.extern_c）
  - MIR(JSON) 例（v1）:
    ```json
    {
      "schema_version": "1.0",
      "functions": [
        { "name": "add/2",
          "params": [{"name":"a","type":"i64"},{"name":"b","type":"i64"}],
          "blocks": [],
          "flags": { "extern_c": "hako_add" }
        }
      ]
    }
    ```
  - 生成IR: `define i64 @hako_add(i64,i64)` が挿入され、内部 `@"add/2"` を呼び出す
  - 使い方: `python3 tools/llvmlite_harness.py --in mir.json --emit-ll out.ll`（または `--out out.o`）

非対象（このフェーズ）
- メモリ管理（自動管理）
- 参照循環/所有権を跨いだ複雑な Box ABI
- 既存 CLI/VM ラインの既定挙動変更（すべて既定 OFF の新フラグでガード）

設計原則
- Box‑First（境界を箱化）: C ABI 層は `src/llvm_py/abi/`（純粋ツール）に隔離。VM/Runner へ依存しない。
- Fail‑Fast: 型不一致や未対応は IR 生成前にエラーメッセージで停止。
- ENV 最小: 既定は CLI フラグ優先。ENV は開発支援の短命 TTL のみ。

受け入れ基準（MVP）
- `@extern_c("hako_add")` を付与した i64 加算関数が `.o` と `.h` に出力され、C からリンクして実行可能。
- Linux/Mac/Win いずれか 1 プラットフォームで visibility/dllexport 設定に問題がない（警告なし）。
- MIR 注釈 → IR ラッパ生成 → ヘッダー生成の一貫性（SSOT）を満たす。

---

関連ドキュメント（起票予定）
- docs/development/abi/README.md — C ABI 全体設計・制約
- docs/development/abi/types.md — MIR 型→C 型マッピング（SSOT）