hakorune/docs/development/current/main/phase130_joinir_llvm_baseline.md

# Phase 130: JoinIR → LLVM ベースライン確立

## 🎯 ゴール

「JoinIR で selfhost/hako_check まで安定した」現在の状態から、**JoinIR → LLVM 経路の現状を観測・記録する** フェーズ。

目的：
- 代表的な .hako を LLVM ラインで実行し、「どこまで通っているか、どこが赤いか」を一覧化
- JoinIR → MIR → LLVM（ny-llvmc / ハーネス）経路での問題点（命令未対応 / ABI ズレ / print系など）を洗い出す
- **実装修正は Phase 131+ に回す**（Phase 130 は「観測専用」と割り切る）

```
Phase 124: JoinIR/selfhost 第2章 完了 ✅
        ↓
Phase 130: 「JoinIR → LLVM どこが赤いか」を観測・記録 ← ← ここ！
        ↓
Phase 131+: 個別の LLVM 側問題を潰す
```

---

## 📋 スコープ（やること・やらないこと）

### ✅ やること
1. 代表ケース選定（JoinIR/selfhost/hako_check から 5〜8 本）
2. LLVM 実行コマンドと環境変数の整理（Rust VM と LLVM ハーネス両方）
3. 実行結果（成功 / 失敗 / 既知問題）を 1 つの docs にまとめる
4. CURRENT_TASK / Backlog に「JoinIR→LLVM 第3章の入り口」を追記

### ❌ やらないこと
- LLVM 側の実装修正（Phase 131 以降の役割）
- 新しい最適化パスやコード生成ルールの追加
- JoinIR / Ring0 の設計変更

---

## 🏗️ 4 つのタスク

### Task 1: 代表ケース選定（LLVM 用）

**ファイル**: `docs/development/current/main/phase130_joinir_llvm_baseline.md`（このファイル）

**やること**:

1. いまの代表パスから、LLVM でも意味があるやつをピックアップ：

   | カテゴリ | ファイル | 用途 |
   |---------|---------|-----|
   | selfhost Stage-3 | `apps/tests/peek_expr_block.hako` | 式ブロック・peek構文 |
   | selfhost Stage-3 | `apps/tests/loop_min_while.hako` | ループ・条件分岐 |
   | selfhost Stage-3 | `apps/tests/esc_dirname_smoke.hako` | ConsoleBox.println・複合処理 |
   | hako_check | Phase 121 から適切な最小ケース | hako_check 診断ロジック |
   | JoinIR/PHI | Phase 33–67 の if/loop PHI テスト | PHI マージ・LoopForm |

2. できれば 5〜8 本に絞る（あれもこれもはやらない）

3. 各代表ケースについて、この docs に記載：
   - `.hako` パス
   - 期待される挙動
   - 既知の過去フェーズ（Phase 15 / 120）の結果（もしあれば）

---

### Task 2: LLVM 実行コマンドの整理

**やること**:

1. Phase 130 用の「代表コマンド」を docs に固定：
   - **Rust VM 対応コマンド**（比較用）：
     ```bash
     ./target/release/nyash --backend vm apps/tests/peek_expr_block.hako
     ```
   - **LLVM ハーネス対応コマンド**：
     ```bash
     LLVM_SYS_180_PREFIX=$(llvm-config-18 --prefix) \
     NYASH_LLVM_USE_HARNESS=1 \
       ./target/release/nyash --backend llvm apps/tests/peek_expr_block.hako
     ```
   - **v2 スモーク実行**（統合テスト）：
     ```bash
     ./tools/smokes/v2/run.sh --profile integration
     ```

2. 各代表 .hako に対して、どう実行するかを docs に例として明記

3. 環境変数一覧：
   - `NYASH_LLVM_USE_HARNESS=1` → Python/llvmlite ハーネス使用
   - `LLVM_SYS_180_PREFIX=$(llvm-config-18 --prefix)` → LLVM 18 設定

---

### Task 3: 実行とベースライン記録（観測専用）

**やること**:

1. 代表 .hako を、少なくともこの 2 パターンで実行：
   - ✅ Rust VM（すでに green の比較軸）
   - 🔧 LLVM backend（NYASH_LLVM_USE_HARNESS=1 --backend llvm）

2. それぞれについて：
   - 実行結果: ✅ / ⚠️ / ❌
   - エラーの場合:
     - エラーメッセージ
     - どのフェーズで失敗したか（parse / JoinIR / MIR / LLVM / 実行時）
   - 既知の LLVM 側制約（Phase 15 docs）と照らし合わせる

3. 結果を表形式でまとめる：

   ```markdown
   ### apps/tests/esc_dirname_smoke.hako

   | 経路         | 結果  | メモ                                      |
   |--------------|-------|-------------------------------------------|
   | Rust VM      | ✅    | Phase 122 で ConsoleBox.println 問題解決済み |
   | LLVM harness | ❌    | [ERROR] 未対応 BoxCall / console access issue |
   ```

4. **この Phase では「修正せず、観測だけ」で止める**
   - 赤いところは「Phase 131 以降の TODO」として列挙しておく

---

### Task 4: CURRENT_TASK / Backlog 更新

**ファイル**:
- `CURRENT_TASK.md`
- `docs/development/current/main/30-Backlog.md`

**やること**:

1. CURRENT_TASK.md に Phase 130 セクション追加：
   ```markdown
   ### Phase 130: JoinIR → LLVM ベースライン確立 ✅

   **完了内容**:
   - 代表パス 8 本を選定（selfhost/hako_check/JoinIR系）
   - Rust VM vs LLVM ハーネスで両実行結果を記録
   - LLVM 側の Known Issues 一覧（赤いところ）を確認

   **テスト結果**:
   - Rust VM: X/8 PASS
   - LLVM harness: X/8 PASS（赤いところ Y 個を特定）

   **成果**:
   - JoinIR→LLVM 経路の現状を可視化
   - Phase 131 以降の優先度付けが可能に

   **次フェーズ**: Phase 131 - JoinIR→LLVM 個別修正ライン
   ```

2. Backlog に「Phase 131: JoinIR→LLVM 個別修正ライン」を軽く書いておく：
   ```markdown
   ### Phase 131: JoinIR→LLVM 個別修正ライン（予定）

   Phase 130 で検出された赤いところを潰す：
   - BoxCall 未対応 → LLVM IR 生成ルール追加
   - JoinIR 命令 → LLVM 側の lowering 脱落 → 実装追加
   - Console/Logger まわりの LLVM 経路整合 → ハーネス側修正
   - [他、Phase 130 で検出された問題を随時追加]
   ```

---

## ✅ 完成チェックリスト（Phase 130）

- [ ] `phase130_joinir_llvm_baseline.md` が存在し、代表パス/コマンド/結果が整理されている
- [ ] 少なくとも 5〜8 本の .hako が「Rust VM / LLVM backend」両方で実行されている
  - LLVM 側は「結果を記録」できていれば OK（赤でも OK）
- [ ] 実行結果の表が表形式で docs に記載されている
- [ ] CURRENT_TASK.md に Phase 130 完了行が追加されている
- [ ] Backlog に「Phase 131: JoinIR→LLVM 個別修正ライン」が追加されている
- [ ] **実装修正は一切入れていない**（赤は赤のまま、一覧化だけしている）
- [ ] git commit で記録（コミットメッセージ例: `docs(phase130): JoinIR→LLVM ベースライン確立`）

---

## 所要時間

**5〜6 時間程度**

- Task 1 (代表ケース選定): 30分
- Task 2 (コマンド整理): 30分
- Task 3 (実行とベースライン記録): 3〜4時間（.hako 実行 + 結果記録）
- Task 4 (ドキュメント更新): 30分

---

## 次のステップ

**Phase 131: JoinIR→LLVM 個別修正ライン** - Phase 130 で検出された問題を優先度順に潰す

---

## 進捗

- ✅ Phase 124: hako_check レガシー削除 & JoinIR 専用化（完了）
- ✅ Phase 56: array_ext.filter JoinIR 対応（テスト修正完了）
- 🎯 Phase 130: JoinIR → LLVM ベースライン確立（← **現在のフェーズ**）
- 📋 Phase 131+: JoinIR→LLVM 個別修正ライン（予定）