hakorune/docs/private/roadmap/phases/phase-20.33/PLAN.md

PLAN — Phase 20.33 (Hakorune コンパイラ Stage‑B)

ゴール（概要）

• Hako 製コンパイラを Stage‑B に引き上げ、Ny → JSON v0 を実用レベルで安定出力。
• 入口を ParserBox → pipeline_v2(FlowEntry) に統一し、1 行 JSON（Quiet）契約を維持。
• 代表構文（return/binop/compare/if/index/new/boxcall/externcall）を優先対応。

フェーズ分割

1. 入口統合（Stage‑B ルートの opt‑in 実装）

   • lang/src/compiler/entry/compiler_stageb.hako を追加（既定: Stage‑B emit 専用）。
   • ParserBox.parse_program2(src) → FlowEntryBox.emit_v0_from_ast_with_context(..., usings, modules?, externs) → print 1 行 JSON。
   • フラグ: --prefer-cfg <N> で pipeline 選好を切替。--v1-compat で MirJsonV1Adapter 経路を opt-in。

2. 代表構文の緑化

   • binop/compare/if/index/new/boxcall/externcall を pipeline_v2 で受理できるよう確認。
   • Stage‑A canary と同等の selfhost canary を Stage‑B でも PASS。
   • Stage‑A 側の map parser（空/空白/エスケープ）を強化し、Stage‑B 引受け前の入力を安定化。

3. v1→v0 アダプタの橋渡し

   • MirCall(v1) を出す経路は MirJsonV1Adapter で v0 に降格。
   • JSON 形状の差分を最小化し、Runner/VM と整合を取る。

4. スモーク整備（opt‑in）

   • tools/smokes/v2/profiles/quick/core/selfhost_* を追加し、Gate‑C 直行と Runner 経由の両方で緑を確認。
   • Stage‑B canary (binop/if/index) に配列ネスト・境界ケースを追加。SMOKES_ENABLE_STAGEB=1 でのみ実行。

5. ドキュメント更新

   • README/PLAN/CHECKLIST を適宜更新。CI 既定は変更せず（既定OFF）。

6. Gate‑C(Core) 実行切替（短期緑化・既定OFF）

   • HAKO_NYVM_CORE=1 時のみ有効。
   • 入力 JSON 判定: schema_version を含む v1 は NyVmDispatcher 直行、version:0 は従来の v0 ブリッジ。
   • 代替（任意）: HAKO_NYVM_V1_DOWNCONVERT=1 で最小サブセット（const/binop/compare/ret/branch/jump/phi）を v0 へ降格。未対応は Fail‑Fast。

   実装ノート（現時点）

   • Runner→Ny 側の Gate‑C controller 呼び出しは子プロセスで実装（payload を env 経由で受け渡し、Quiet 環境を注入）。
   • 既知の問題: Hako controller が call("…") 解決に失敗し実行不可。直行は一時的に失敗→v0 ブリッジ側がエラーを出す。
   • 次の修正: controller 側で include 経由の直接呼び出しに変更するか、runner 側で JSON→Core のインライン実行を採用する（小差分優先）。

7. Bridge 正規化トグル実装（仕様確定後）

   • HAKO_BRIDGE_INJECT_SINGLETON: Array/Map 系の静的関数に必要な receiver/Singleton 補完を最小差分で注入。
   • HAKO_BRIDGE_EARLY_PHI_MATERIALIZE: φ をブロック先頭へ整列（or 指定形）して use‑before‑def を防止。
   • いずれも既定OFF、明示トグルでのみ有効。

トグル/フラグ（dev）

• --stage-b（entry 直下で Stage‑B パスを有効化）
• オプション：--prefer-cfg {0|1|2}（未指定は 1）

受け入れ基準

• selfhost canary（Stage‑B）: return/binop/if/index が緑（Gate‑C）。
• ny-llvmc の最小ケース（return/binop）で v0→EXE 生成が PASS。
• 既定 OFF のため、quick/integration の回帰なし。