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

docs/private/roadmap/phases/phase-20.20/CHECKLIST.md

@@ -0,0 +1,25 @@
+# Phase 20.20 — チェックリスト（C ABI Export / LLVM）
+
+開始前
+- [ ] 仕様合意: 注釈 @extern_c と最小型（i64/i32）
+- [ ] 既定OFFポリシー確認（CLI先行・ENV最小）
+
+実装
+- [ ] @extern_c → MIR JSON flags 反映
+- [x] llvmlite: emit_c_abi_function 実装（ccc/visibility/unmangled）
+- [x] CHeaderGenerator 実装（extern "C"/stdint.h/prototype）＋ harness `--emit-header`
+
+テスト/スモーク
+- [ ] hako_add: .o + .h 生成 → C からリンク → 出力 30
+- [ ] 負数/ゼロ境界ケース
+- [ ] 片方未対応型で Fail‑Fast 診断
+
+ドキュメント
+- [ ] abi/README.md（設計/制約/CLI）
+- [ ] abi/types.md（型マッピングSSOT）
+- [ ] ツール例（gcc/clangリンク）
+
+受入基準
+- [ ] 代表関数の AOT 実行が C から成功
+- [ ] 警告/可視性問題がない（対象プラットフォームのうち1つで確認）
+- [ ] 失敗時は安定メッセージで Fail‑Fast

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

@@ -0,0 +1,41 @@
+# Phase 20.20 — 実装計画（C ABI Export / LLVM）
+
+マイルストーン
+- M1: 注釈→MIR JSON 反映（@extern_c）
+- M2: LLVM(IR) C ABI ラッパ生成（プリミティブ i64/i32）
+- M3: C ヘッダー生成（extern "C"、stdint.h）
+- M4: 最小スモーク（.o + .h → C からリンク実行）
+- M5: ドキュメント（設計/制約/使用例）
+
+タスク（詳細）
+1) 注釈設計と反映（M1）
+- [ ] @extern_c("c_symbol") の構文/意味論を docs に定義
+- [ ] パーサ→ビルダーで関数メタへ注釈を格納
+- [ ] MIR JSON に `function.flags.extern_c = "c_symbol"` を出力
+
+2) C ABI ラッパ生成（M2）
+- [ ] llvmlite builder に `emit_c_abi_function(func_name, c_name)` を追加
+- [ ] calling convention=ccc、unmangled 名、visibility（ELF/Mach‑O/Win）
+- [ ] プリミティブ i64/i32 のみ対応（fail-fast: その他は未対応メッセージ）
+
+3) ヘッダー生成（M3）
+- [ ] CHeaderGenerator を実装（MIR JSON→.h 生成）
+- [ ] extern "C"、include guard、stdint.h、プロトタイプ
+- [ ] 型マッピング表（SSOT）に基づき生成（当面: i64→int64_t、i32→int32_t）
+
+4) スモーク（M4）
+- [ ] Hakorune → MIR(JSON) → .o（C ABI）→ C からリンク→実行
+- [ ] 代表: `test_add(10,20)=30`、負/ゼロ境界
+
+5) ドキュメント（M5）
+- [ ] docs/development/abi/README.md（設計/制約/CLI）
+- [ ] docs/development/abi/types.md（型マッピングSSOT）
+- [ ] tools（最小ビルド/リンク例）
+
+ガード/ポリシー
+- 既定 OFF（CLIフラグ: `--emit-c-abi`, `--emit-header`）
+- ENV は原則導入しない。必要時のみ TTL（ドキュ必須）
+- 失敗は Fail‑Fast（ラッパ生成前に診断）
+
+見積
+- 実装 + スモーク + ドキュ: 2–3週間（最小構成）

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

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