hakorune/docs/development/roadmap/phases/phase-15.5/migration-phases.md

Phase 15.5段階移行計画

セルフホスティング前の基盤革命・詳細実装ロードマップ

🎯 全体戦略

基本原則

1. 急がない: 一気にJSON化せず段階的に
2. 壊さない: 既存機能の完全互換性維持
3. 戻れる: 各段階で前状態への撤退可能

3段階アプローチ

Phase A (今) → Phase B (次) → Phase C (最終)
JSON出力統一   JSON中心移行   完全JSON化

📋 Phase A: JSON出力統一（今すぐ実装）

🎯 目標

出力を統一Call対応JSON v1に

📊 優先度1: mir_json_emit統一Call対応

実装箇所

// src/runner/mir_json_emit.rs
I::Call { dst, func, callee, args, effects } => {
    if let Some(callee_info) = callee {
        // 統一Call v1形式でJSON出力
        emit_unified_call_json(callee_info, dst, args, effects)
    } else {
        // 旧形式（互換性維持）
        emit_legacy_call_json(func, dst, args)
    }
}

JSON v1スキーマ

{
  "op": "call",
  "dst": 12,
  "callee": {
    "kind": "Method",
    "box_id": "StringBox",
    "method": "upper",
    "receiver": 7
  },
  "args": [42],
  "flags": [],
  "effects": ["IO"]
}

環境変数制御

# v1形式出力（統一Call対応）
NYASH_MIR_UNIFIED_CALL=1 ./target/release/nyash program.nyash

# v0形式出力（既存互換）
NYASH_MIR_UNIFIED_CALL=0 ./target/release/nyash program.nyash

📊 優先度2: スキーマ情報追加

ヘッダー情報

{
  "ir_schema": "nyash-mir-json",
  "version": 1,
  "capabilities": [
    "unified_callee",
    "effect_mask",
    "call_flags"
  ],
  "generator": "nyash-rust-v0.1.0",
  "timestamp": "2025-09-24T...",
  "module": { ... }
}

📊 優先度3: Python側対応

instruction_lower.py更新

def handle_json_v1(inst_data):
    version = inst_data.get("version", 0)
    if version >= 1:
        # v1の統一Call処理
        return lower_unified_call_v1(inst_data)
    else:
        # v0の個別処理（既存）
        return lower_legacy_calls_v0(inst_data)

✅ Phase A完了条件

• 統一Call 6パターンのJSON化完了
• Python LLVM/PyVMでv1形式実行成功
• NYASH_MIR_UNIFIED_CALL=0で既存互換性維持
• round-trip整合性テスト通過

---

📋 Phase B: JSON中心化移行（次段階）

🎯 目標

MIR ModuleをJSON v0のラッパー化

📊 優先度1: JSON→MIRリーダー薄化

現状問題

// 現在: 重厚なMIR Module構造体
pub struct MirModule {
    functions: HashMap<String, MirFunction>,
    globals: HashMap<String, MirGlobal>,
    // ... 大量のRust固有構造
}

理想形

// 将来: JSON v0の薄いラッパー
pub struct MirModule {
    json_data: JsonValue,  // 実データはJSON
    // 型安全アクセサのみ
}

impl MirModule {
    fn get_function(&self, name: &str) -> Option<MirFunction> {
        // JSON→型安全ビューの変換
    }
}

📊 優先度2: HIR情報のJSON化

名前解決情報

{
  "hir_metadata": {
    "bindings": [
      {"id": "var_1", "name": "count", "scope": "local"},
      {"id": "func_main", "name": "main", "scope": "global"}
    ],
    "function_signatures": [
      {"id": "func_main", "params": [], "return_type": "void"}
    ]
  }
}

📊 優先度3: 型情報保持

型安全性維持

// JSON v0 + 型情報のハイブリッド
pub struct TypedMirModule {
    json: JsonValue,           // データ
    type_info: TypeRegistry,   // 型安全性
}

✅ Phase B完了条件

• JSON→MIRリーダーの薄化完了
• HIR情報の完全JSON化
• 型安全性・パフォーマンス維持
• 既存最適化の動作確認

---

📋 Phase C: 完全JSON化（最終段階）

🎯 目標

JSON v0を唯一の真実に

📊 優先度1: MIR Module廃止準備

依存箇所の洗い出し

# MIR Module直接利用の箇所を特定
grep -r "MirModule" src/ --include="*.rs"

移行計画

1. 最適化エンジン → JSON v0 + 型ビュー
2. VM実行器 → JSON v0直接読み
3. デバッガー → JSON v0直接表示

📊 優先度2: 多言語実装技術実証

Python実装PoC

# PyNyash: Nyash in Python
class NyashInterpreter:
    def __init__(self, json_v0_data):
        self.program = json_v0_data

    def execute(self):
        # JSON v0を直接実行
        pass

JavaScript実装PoC

// nyash.js: Nyash in Browser
class NyashVM {
    constructor(jsonV0) {
        this.program = jsonV0;
    }

    execute() {
        // JSON v0をブラウザで実行
    }
}

📊 優先度3: プリンターのJSON化

現状維持vs移行判断

利点: 統一性、他言語での再利用
欠点: 型情報喪失、パフォーマンス

→ Phase Cで慎重に判断

✅ Phase C完了条件

• 他言語実装の技術実証完了
• Rust依存の段階的削除
• セルフホスティング基盤完成
• パフォーマンス劣化なし

---

⏰ タイムライン

Phase A: 2-3週間

• Week 1: mir_json_emit統一Call実装
• Week 2: Python側対応・テスト
• Week 3: 統合テスト・安定化

Phase B: 4-6週間

• Week 1-2: JSON→MIRリーダー薄化
• Week 3-4: HIR情報JSON化
• Week 5-6: 型安全性確保・テスト

Phase C: 8-12週間

• Week 1-4: 依存箇所移行
• Week 5-8: 多言語実装PoC
• Week 9-12: 最終統合・テスト

セルフホスティング準備完了

Phase 15.5完了後、Phase 15本格開始

---

🚨 クリティカルパス

絶対に守るべき順序

1. Phase A完了まではRust MIR触らない
2. 各段階で既存機能の完全テスト
3. 撤退戦略の常時確保

並行作業可能項目

• ドキュメント整備
• テストケース拡充
• Python側の準備作業

これにより、セルフホスティング成功の確実な基盤が構築される。