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

Phase 133: ConsoleBox LLVM 統合 & JoinIR→LLVM 第3章クローズ

🎯 ゴール

ConsoleBox（log/println 系）の振る舞いを LLVM backend でも Rust VM と完全一致 させる。

目的：

• JoinIR → MIR → LLVM → nyrt の経路で、ConsoleBox メソッド呼び出しが一貫した ABI で動く状態にする
• Phase 130 の 7 本ベースラインうち「ConsoleBox 由来の失敗」をすべて緑にする（7/7 達成）
• JoinIR → LLVM 第3章の完全クローズ

Phase 132: PHI 順序バグ修正（6/7 達成）✅
        ↓
Phase 133: ConsoleBox LLVM 統合 ← ← ここ！
        ↓
JoinIR → LLVM 第3章 完全クローズ 🎉

---

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

✅ やること

• LLVM backend 内の ConsoleBox / CoreMethodId / BoxCall lowering を整理
• 「ConsoleBox.{log,println,…} → 1 本の LLVM runtime 関数群」 に統一
• 既存の Rust VM 側 ConsoleService / logging_policy.md と意味論を揃える（出力文字列と順序）
• Phase 130/131/132 の代表 .hako ケースで LLVM 実行を検証し、Rust VM と結果を比較

❌ やらないこと

• JoinIR や MIR の意味論変更（BoxCall lowering 以前の層には触れない）
• Ring0 / FileBox / Logger 設計を変えること（今の三層構造はそのまま）
• LLVM backend 全体の最適化／別機能（PHI 以外の opcode は Phase 133 では触らない）

---

🏗️ 6 つのタスク

Task 1: 設計ドキュメント作成

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

書く内容:

現状整理

Rust VM 経路:

• ConsoleBox メソッドは CoreMethodId::ConsoleLog などにマップ
• log/println の alias は TypeRegistry / CoreMethodId 側で SSOT 管理済み（Phase 122）
• 実際の出力は ConsoleService → Ring0.log → stderr/stdout

LLVM 経路:

• BoxCall(ConsoleBox, method) がどう LLVM IR に落ちているか
  • printf 直叩き or 未実装 or stub
• どのファイルが Console を扱っているか
  • 候補: src/backend/llvm/*box* / src/backend/llvm/*call* など BoxCall lowering 周辺

目指す構造

Console LLVM Bridge 箱 を定義するイメージ図:

BoxCall(ConsoleBox, method)
    ↓
CoreMethodId / メソッド種別判定
    ↓
ConsoleLlvmBridge 箱
    ↓
LLVM 外部関数 @ny_console_log / @ny_console_warn … に lowering

Rust VM と LLVM の間で一致すべき項目:

• 文字列 API（i8* + len）
• 改行有無（println の扱い）
• ログレベル（log/warn/error）

ABI 方針

LLVM 側の runtime 関数 signature（例）:

declare void @ny_console_log(i8* %ptr, i64 %len)
declare void @ny_console_warn(i8* %ptr, i64 %len)
declare void @ny_console_error(i8* %ptr, i64 %len)

nyrt（C/Rust ランタイム）側の実装:

• 今の ConsoleService と同じポリシーで出力
• println は log + 改行 or そのまま log として扱う（設計書で明文化）

---

Task 2: 現状実装の棚卸し（ConsoleBox ↔ LLVM）

対象候補ファイル:

# BoxCall lowering 周辺
rg "BoxCall" src/backend/llvm/ --type rust

# ConsoleBox の CoreMethodId マッピング
rg "ConsoleLog|ConsolePrintln" src/runtime/type_registry.rs

やること:

1. ConsoleBox 関連の lowering の現状把握:

   • 文字列をそのまま printf に渡しているか
   • 未実装で panic/log を吐いているか
   • CoreMethodId ベースか、Box 名＋メソッド名の文字列ベースか

2. Phase 122 のエイリアス統一の反映確認:

   • println/log エイリアスが LLVM 経路でも共有されているか
   • 共有されていない場合は「どこで divergence しているか」をメモ

結果記録:

• この Task の結果は、そのまま phase133 ドキュメントの「現状問題点」セクションに追記

---

Task 3: ConsoleLlvmBridge（仮）設計 & 実装

目的: Console 関連 BoxCall lowering を 1 箇所に集約した「箱」 に閉じ込める

実装方針:

箱の設計

場所: src/backend/llvm/console_bridge.rs（新規モジュール）

役割:

1. CoreBoxId / CoreMethodId から「Console メソッド種別」を判定
   • 例: ConsoleLog, ConsoleWarn, ConsoleError, ConsoleClear, ConsolePrintln
2. 文字列引数（Nyash の StringBox or i8* + len）を LLVM IR 上の (i8*, i64) に変換
3. 対応する runtime 関数呼び出しを生成

BoxCall lowering 側の修正

最小限の分岐に集約:

// BoxCall lowering 側（例）
if box_id == CoreBoxId::Console {
    ConsoleLlvmBridge::emit_call(builder, method_id, args)?;
    return;
}

箱化の効果:

• 解析やログ文字列構築を BoxCall lowering から追い出す
• Console 関連のロジックが 1 箇所に集約される
• テストしやすく、後でレガシー削除しやすい

注意点

• 既に nyrt / LLVM runtime に似た関数があれば、それに合わせる（新規関数を増やさずに統合）
• なければ、最小限の関数だけ追加し、Phase 133 のドキュメントに ABI を記録

---

Task 4: 代表ケースでの JoinIR→LLVM 実行確認

代表 .hako:

Phase 130/131 で使っていた 7 本から、Console 出力を含むものを 最低 3 本 選ぶ：

• apps/tests/esc_dirname_smoke.hako（Console 出力あり）
• apps/tests/peek_expr_block.hako（軽量）
• apps/tests/loop_min_while.hako（ループ + Console）

検証手順:

1. Rust VM 実行（baseline）:

   ./target/release/nyash --backend vm apps/tests/esc_dirname_smoke.hako
   

2. LLVM 実行:

   LLVM_SYS_180_PREFIX=$(llvm-config-18 --prefix) \
   NYASH_LLVM_USE_HARNESS=1 \
     ./target/release/nyash --backend llvm apps/tests/esc_dirname_smoke.hako
   

3. 両者の標準出力を比較:

   • 最低限、行数と大まかなメッセージ一致を確認
   • 差分があれば原因調査

期待:

• Phase 132 で PHI 順序は整っているので、ConsoleBox を含む代表ケースは LLVM でも成功するはず
• Phase 130 で「Rust VM OK / LLVM NG」だったうち Console 起因のものは緑にしたい

---

Task 5: テスト追加（LLVM 専用 or 統合テスト）

テスト戦略:

Option A: Rust 側に小さな LLVM 専用テスト追加

入力: 簡単な MIR/JoinIR（ConsoleBox.log/println を 1–2 回呼ぶだけ） 出力:

• LLVM IR text を dump して、@ny_console_log への call が生成されていること
• 実行したときに期待メッセージが出ること

Option B: スクリプトでの手動テスト

もしテストが重くなる場合：

• Phase 130 の手動スクリプトを使って、最低限の再現手順を docs に書く
• tools/test_phase133_console_llvm.sh のようなスクリプトを用意できればベスト

実装例:

#!/bin/bash
# tools/test_phase133_console_llvm.sh

set -e

test_cases=(
    "apps/tests/esc_dirname_smoke.hako"
    "apps/tests/peek_expr_block.hako"
    "apps/tests/loop_min_while.hako"
)

echo "=== Phase 133: ConsoleBox LLVM Integration Test ==="

for case in "${test_cases[@]}"; do
    echo "Testing: $case"

    # VM baseline
    vm_output=$(./target/release/nyash --backend vm "$case" 2>&1)

    # LLVM execution
    llvm_output=$(NYASH_LLVM_USE_HARNESS=1 \
                  ./target/release/nyash --backend llvm "$case" 2>&1)

    # Compare
    if [ "$vm_output" == "$llvm_output" ]; then
        echo "✅ $case PASS"
    else
        echo "❌ $case FAIL"
        echo "VM output:"
        echo "$vm_output"
        echo "LLVM output:"
        echo "$llvm_output"
        exit 1
    fi
done

echo "All tests PASSED! 🎉"

---

Task 6: ドキュメント / CURRENT_TASK 更新

やること:

1. phase133_consolebox_llvm_integration.md に追記:

   ## Phase 133 実装結果
   
   ### 修正ファイル
   - `src/backend/llvm/console_bridge.rs`: ConsoleLlvmBridge 箱（新規）
   - `src/backend/llvm/boxcall_lowering.rs`: Console 分岐を箱に委譲
   - `src/llvm_py/runtime.py`: @ny_console_log 等の外部関数実装
   
   ### ABI 設計
   | 関数名 | Signature | 用途 |
   |--------|----------|------|
   | @ny_console_log | void(i8*, i64) | ログ出力 |
   | @ny_console_warn | void(i8*, i64) | 警告出力 |
   | @ny_console_error | void(i8*, i64) | エラー出力 |
   
   ### テスト結果
   | ケース | Rust VM | LLVM (Phase 132) | LLVM (Phase 133) |
   |--------|---------|------------------|------------------|
   | esc_dirname_smoke.hako | ✅ | ❌ | ✅ |
   | peek_expr_block.hako | ✅ | ✅ | ✅ |
   | loop_min_while.hako | ✅ | ❌ | ✅ |
   
   ### 成果
   - ConsoleBox LLVM 統合完了
   - JoinIR → LLVM 経路が 7/7 動作確認
   - JoinIR → LLVM 第3章完全クローズ 🎉
   

2. CURRENT_TASK.md 更新:

   ### Phase 133: ConsoleBox LLVM 統合 & JoinIR→LLVM 第3章クローズ ✅
   
   **完了内容**:
   - ConsoleLlvmBridge 箱化モジュール実装
   - ConsoleBox.{log,println,warn,error} の LLVM runtime 関数統一
   - Phase 130 代表ケース 7/7 LLVM 実行成功
   
   **修正箇所**:
   - src/backend/llvm/console_bridge.rs: 新規箱化モジュール
   - src/backend/llvm/boxcall_lowering.rs: Console 分岐を箱に委譲
   - src/llvm_py/runtime.py: @ny_console_* 外部関数実装
   
   **テスト結果**:
   - 修正前: LLVM 6/7 実行可能（ConsoleBox 未統合）
   - 修正後: LLVM 7/7 実行可能（完全一致）
   
   **成果**:
   - JoinIR → LLVM 第3章完全クローズ
   - PHI 順序（Phase 132）+ ConsoleBox 統合（Phase 133）で「JoinIR-heavy .hako の LLVM 実行ライン確立」
   
   **次フェーズ**: selfhost Stage-4 拡張 or 次の大型改善へ
   

3. 30-Backlog.md 更新:

   ### JoinIR → LLVM 第3章完全クローズ ✅
   
   Phase 130-133 で以下を達成：
   - Phase 130: ベースライン確立（観測フェーズ）
   - Phase 131: LLVM backend re-enable（1/7 達成）
   - Phase 132: PHI 順序バグ修正（6/7 達成）
   - Phase 133: ConsoleBox LLVM 統合（7/7 達成）
   
   完了条件：
   - ✅ 7/7 テストが Rust VM と LLVM で実行成功
   - ✅ PHI 順序バグ構造的修正
   - ✅ ConsoleBox 箱化モジュール統合
   - ✅ JoinIR → LLVM 経路完全確立
   

---

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

• ConsoleBox LLVM 統合の設計ドキュメント作成
• 現状実装の棚卸し（BoxCall lowering 周辺）
• ConsoleLlvmBridge 箱化モジュール実装（新規 or 既存統合）
• ConsoleBox メソッドの LLVM runtime 関数マッピング実装
• BoxCall lowering 側を箱に委譲（分岐削除・レガシー削除）
• 代表ケース 3 本以上で LLVM 実行成功確認
• phase133_consolebox_llvm_integration.md に実装結果追記
• CURRENT_TASK.md & Backlog 更新（第3章クローズ宣言）
• git commit で記録

---

所要時間

4〜5 時間程度

• Task 1-2 (設計ドキュメント & 棚卸し): 1時間
• Task 3 (ConsoleLlvmBridge 実装): 2時間
• Task 4-5 (実行確認 & テスト): 1時間
• Task 6 (ドキュメント更新): 30分

---

次のステップ

JoinIR → LLVM 第3章完全クローズ後:

Phase 133 が完了すると：

• ✅ JoinIR / selfhost / hako_check（第2章）
• ✅ JoinIR → LLVM（第3章）の「最低限動くベースライン」確立

次の方向性：

• selfhost Stage-4 拡張（より複雑なパターン対応）
• LLVM backend 最適化（Phase 134 以降）
• 別の大型改善フェーズへ

---

進捗

• ✅ Phase 130: JoinIR → LLVM ベースライン確立（完了）
• ✅ Phase 131: LLVM backend re-enable & PHI 問題発見（完了）
• ✅ Phase 132: LLVM PHI 命令順序バグ修正（完了）
• 🎯 Phase 133: ConsoleBox LLVM 統合 & 第3章クローズ（← 現在のフェーズ）
• 📋 Phase 134+: 次の改善フェーズ（予定）