hakorune/docs/development/roadmap/phases/phase-25.1b/README.md

# Phase 25.1b — Selfhost Builder Parity (Planning → Design Deep‑Dive)

Status: planning-only（実装着手前の設計・分析フェーズ）

## ゴール

- Rust 側 Program→MIR (`env.mirbuilder.emit`) と Hakorune 側 selfhost builder (`MirBuilderBox.emit_from_program_json_v0`) の機能差を埋め、Stage1 CLI（launcher.hako）レベルの Program(JSON) を selfhost builder 単独で lowering できるようにする。
- `.hako → Program(JSON v0) → MIR(JSON)` のうち、「Program→MIR」を selfhost builder だけでも成立させ、provider 経路はあくまで退避路に下げていく。
- 最終的には `HAKO_SELFHOST_BUILDER_FIRST=1` を既定に戻し、Stage1 CLI EXE の I/O（JSON stdout + exit code）を Rust/llvmlite と同じ契約に揃える。

## 現状（Phase 25.1a 時点）

### Stage‑B（Program(JSON v0) emit）

- `compiler_stageb.hako` は `defs` を含む Program(JSON v0) を出力できる:
  - `HakoCli.run` / `HakoCli.cmd_emit_*` / `HakoCli.cmd_build_*` などのメソッドを `Program.defs` 配列として含む。
  - `FuncScannerBox` ＋ `HAKO_STAGEB_FUNC_SCAN=1` により、`static box` メソッド（暗黙の `me` 引数付き）も defs に載る。
- using 解決:
  - `Stage1UsingResolverBox`（`lang/src/compiler/entry/using_resolver_box.hako`）＋ `HAKO_STAGEB_MODULES_LIST` で `nyash.toml` の `[modules]` を参照し、`using lang.mir.builder.MirBuilderBox` 等をファイル結合前に解決。
  - Stage‑B entry 側は string literal using を廃止し、`using lang.compiler.entry.using_resolver as Stage1UsingResolverBox` のように module alias を使用する。

### Rust provider (`env.mirbuilder.emit`)

- `program_json_to_mir_json_with_imports`:
  - `Program.body` と `Program.defs` の両方を受理し、`FuncDefV0` から `func_map` を構築して Call を解決。
  - `HAKO_MIRBUILDER_IMPORTS` 経由で `MirBuilderBox` / `BuildBox` などの static box 名をインポートし、`Const(String(alias))` として扱う。
- JSON v0 ブリッジ:
  - `args` を暗黙パラメータとして扱う修正済み（`undefined variable: args` は解消）。
  - `hostbridge` は well‑known 変数として `Const(String("hostbridge"))` を生成し、`hostbridge.extern_invoke(...)` を含む Program(JSON) でも undefined にならない。
- 結果:
  - `launcher.hako` に対して ~62KB の MIR(JSON) を安定して生成できており、Phase 25.1a では provider 経路が事実上のメインルート。

### selfhost builder (`MirBuilderBox.emit_from_program_json_v0`)

- エントリ:
  - 入口で `HAKO_MIR_BUILDER_FUNCS=1` のときに `FuncLoweringBox.lower_func_defs(program_json, program_json)` を呼び出し、defs 専用の MIR 関数群を文字列として受け取る（`func_defs_mir`）。
  - その後、`internal` 配下の多数の `Lower*Box.try_lower` を順番に適用し、Program 全体を 1 関数（`main`）ベースの MIR(JSON) に落とす。
- `FuncLoweringBox` の現状:
  - `lower_func_defs` は Program(JSON) から `defs` 配列をパースし、各 def ごとに `_lower_func_body` を呼ぶ。
  - `_lower_func_body` がサポートするのは **単一の Return を持つ最小パターンのみ**:
    - `Return(Int)`
    - `Return(Binary(op, lhs, rhs))`（`+,-,*,/` のみ、かつ `Int/Var` 組み合わせ限定）
    - `Return(Call(name, args))`（Call 名は `func_map` を用いて `Box.method` に解決）
  - 複数ステートメント、`If`、`Loop`、メソッドチェインなど Stage1 CLI に実際に現れる構造はすべて `null` でスキップされる。
- `MirBuilderBox` の挙動:
  - 何らかの `Lower*Box` が Program 全体にマッチした場合は、その MIR(JSON) に対して `_norm_if_apply` を通し、`FuncLoweringBox.inject_funcs` で defs 分の MIR 関数を **追加注入** する。
  - どの `Lower*Box` もマッチしないが `func_defs_mir` が非空の場合は、`"{\"functions\":[" + defs + "]}"` という最小モジュールを組み立てて `_norm_if_apply` に渡す。
    - このケースでは main 関数を含まない defs だけの MIR モジュールになり、ny-llvmc 側でエントリポイント不足や空挙動 EXE を生む原因になる。
  - `func_defs_mir` も空で internal lowers も不発の場合は `null` を返し、最後に provider delegate（`env.mirbuilder.emit`）へフォールバックする。

### Stage1 EXE / build_stage1.sh の現状

- `tools/selfhost/build_stage1.sh`:
  - 既定値 `HAKO_SELFHOST_BUILDER_FIRST=0`（provider-first）では、Stage1 EXE ビルドは成功し、`emit program-json` / `emit mir-json` / `build exe` の I/O も Rust/llvmlite と同等の JSON+exit code 契約を満たす。
  - `HAKO_SELFHOST_BUILDER_FIRST=1`（selfhost-first）では、Stage1 CLI のような複雑な Program(JSON) に対して selfhost builder が「defs のみ」MIR か mini stub MIR を返し、結果として「Result: 0 だけ出す空 EXE」になる。
- スモーク:
  - `tools/smokes/v2/profiles/quick/core/phase251/stage1_launcher_program_to_mir_canary_vm.sh` は provider-first ルートのみをカバーしており、selfhost builder 単独経路のギャップは検出できていない（今後 canary を追加する必要がある）。

## 25.1b のスコープ（案）

- selfhost builder 本体（Hakorune 側）:
  - `Program.defs` の処理を実装し、`box + method` ごとに MIR 関数を生成する。
    - 例: `HakoCli.run` / `HakoCli.cmd_emit_program_json` / `HakoCli.cmd_emit_mir_json` / `HakoCli.cmd_build_exe` 等。
  - `call` / `BoxCall` / `ExternCall` の解決（`func_lowering` + call resolve 相当）を Hakorune 側にも実装し、`Call("cmd_emit_mir_json")` が `Global` callee に解決できるようにする。
  - Loop / branch / compare / Array/Map 操作など Stage1 CLI で出現する構造を包括的に lowering するため、`lang/src/mir/builder/internal/*` の helper を本番経路に統合する。
- JSON 出力:
  - 現状の `"{\"functions\":[...]}\"` ベタ書きから、jsonfrag 等を用いた構造的出力に切り替え、複数関数を同一モジュールに含められるようにする。
  - 既存の mini パターン用 JSON 組み立てとの互換性を維持しつつ、Stage1 CLI で必要な関数数に耐えられる形に拡張する。
- 運用ポリシー:
  - Phase 25.1b 中は `HAKO_SELFHOST_BUILDER_FIRST=0` のまま（provider-first）とし、selfhost builder が Stage1 CLI を lowering し切れることを確認した時点で `=1` への切り替えを検討する。
  - lambda/FunctionBox (`NewClosure` 等) は本フェーズでは扱わず、従来どおり builder からは排除したままにする（別フェーズ 25.2b に委ねる）。

## Guardrails / ポリシー

- Rust Freeze Policy:
  - Rust 側の Program→MIR 実装には原則手を入れず、selfhost builder は「Rust の既存挙動に合わせる」方向で実装する。
  - 変更は Hakorune 側 (`lang/src/mir/builder/*`) とツール (`tools/hakorune_emit_mir.sh`) に閉じる。
- Fail‑Fast:
  - selfhost builder が Program(JSON) の一部に対応していない場合は、明確なタグ付きで失敗させる（例: `[builder/selfhost-first:unsupported:Match]`）ようにし、silent stub には戻さない。
  - provider 経路は退避路として残しつつ、Stage1 CLI の代表ケースでは selfhost builder が先に成功することを目標にする。

### LoopForm / PHI ポリシー（重要メモ）

- ループを含む関数本体を selfhost builder で扱うときは、**LoopForm 正規化を前提にする**:
  - 可能な限り `docs/guides/loopform.md` で定義された「キャリア＋1個の φ」モデルに従う。
  - break/continue を含むループは、LoopForm の制約（更新変数最大2個・セグメント整列など）を満たす範囲でのみ lowering 対象にする。
- MirBuilder 側で「生の while/for を直接 MIR の PHI に落とす」ような ad‑hoc 実装は行わない:
  - PHI ノードの生成・配置は既存の LoopForm/LowerLoop 系 helper（`loop_scan_box.hako`／`lower_loop_*_box.hako` など）に一元化し、builder 本体はそれを利用する立場にとどめる。
  - LLVM harness 側の PHI 不変条件（ブロック先頭グルーピング／well‑typed incoming）を崩さない。
- Phase 25.1b では:
  - まず LoopForm 前提で安全に扱える最小のループ形（既存 selfhost テストでカバー済みの while/for）から対応し、
  - LoopForm 未適用の複雑なループ（例: キャリア3変数以上・ネストが深いもの）は `[builder/selfhost-first:unsupported:loopform]` タグなどで Fail‑Fast する。

## Next Steps（実装フェーズに入るときの TODO）

1. 調査:
   - Rust 側 `program_json_to_mir_json_with_imports` の挙動をトレースし、どの AST ノードがどの MIR に降りているかを整理（特に defs/call/loop/boxcall）。
   - selfhost builder の現行 JSON 生成経路を洗い出し、stub を生成している箇所を特定。
2. 設計:
   - `Program.defs` → MIR 関数生成のインタフェース（必要なフィールドと lowering 手順）を定義。
   - call resolve 用の軽量マップ（`name -> qualified`）を selfhost builder に導入する。
3. 実装:
   - defs 対応・call resolve・loop/branch lowering を段階的に導入しつつ、各ステップで mini スモークを追加。
   - jsonfrag ベースの出力に切り替えながら、既存の mini テストを全て通ることを確認。
4. 検証:
   - `tools/hakorune_emit_mir.sh lang/src/runner/launcher.hako …` を `HAKO_SELFHOST_BUILDER_FIRST=1` で実行し、62KB クラスの MIR(JSON) が selfhost builder 単独で得られることを確認。
   - `tools/selfhost/build_stage1.sh` を selfhost-first でビルドし、Stage1 CLI EXE が `emit`/`build` コマンドを正しく実行できるか（JSON stdout + exit code）をスモークで検証。

## 設計 TODO（FuncLoweringBox / MirBuilderBox 拡張の方向性）

※ ここから先は「具体的にどこをどう広げるか」の設計メモ。実装はまだ行わない。

1. FuncLowering の対応範囲拡張
   - `_lower_func_body` を Stage1 CLI で実際に使われているパターンまで広げる:
     - 単一 Return だけでなく、ローカル変数定義＋if 分岐＋loop を含む「典型的な CLI ハンドラ」の形をサポート。
     - `MethodCall`（`args.size()` / `args.get(i)` / `FileBox.open/read/write` / `ArrayBox.push` など）を MIR `mir_call` か `call` に落とす処理を追加。
   - `func_map` / `resolve_call_target` を用いて、`HakoCli.cmd_emit_*` / `cmd_build_exe` などの内部 Call を `Global("HakoCli.cmd_emit_*")` 系に正規化。

2. MirBuilder 本体の出力構造
   - これまでの「Program 全体を 1 関数 main に落とす」前提から、「Program.body + defs を multi‑function MIR モジュールに落とす」前提へシフト:
     - `Program.body` からはエントリ `Main.main/1` 相当の MIR 関数を生成。
     - `Program.defs` からは `HakoCli.*` などの補助関数を生成。
   - `_norm_if_apply` / `inject_funcs` の役割を整理し、「main 関数を含まない defs‑only モジュール」を返さないように Fail‑Fast する。

3. Fail‑Fast とデバッグ
   - Stage1 CLI のような大きな Program(JSON) に対して selfhost builder が未対応の場合は:
     - `[builder/selfhost-first:unsupported:func_body]` などのタグ付きで明示的に失敗。
     - provider 経路（`env.mirbuilder.emit`）へのフォールバックは維持するが、「空 EXE になる stub MIR」は生成しない方針に切り替える。
   - `HAKO_SELFHOST_TRACE=1` 時に、FuncLowering がどの def でどこまで lowering できたかをログに出す。

4. 検証計画
   - selfhost‑first canary:
     - `stage1_launcher_program_to_mir_canary_vm.sh` の selfhost‑first 版を追加し、`HAKO_SELFHOST_BUILDER_FIRST=1` ＋ `MirBuilderBox.emit_from_program_json_v0` だけで 60KB 級の MIR(JSON) を生成できることを確認。
   - Stage1 build:
     - `tools/selfhost/build_stage1.sh` を selfhost-first で回し、生成された Stage1 EXE に対して `emit program-json` / `emit mir-json` / `build exe` スモークを追加。

このファイルは引き続き「Phase 25.1b の計画メモ（設計ディープダイブ）」として扱い、実装は Phase 25.1a の安定化完了後に、小さな差分に分割して順次進める。***

---

## 実装計画（順番にやる TODO）

備考: ここでは Phase 25.1b を「複数の最小ステップ」に分解して、順番/ゴール/ガードを具体的にメモしておくにゃ。

### Step 0 — Fail‑Fast・観測を揃える
- Status: implemented (2025-11-15). `MirBuilderBox` now tags `defs_only` / `no_match` failures and aborts, and `FuncLoweringBox` logs unsupported defs when `HAKO_SELFHOST_TRACE=1`.
- 目的: 既存の selfhost builder がどこで諦めているかを正確に観測し、stub MIR を返さずに Fail させる導線を整える。
- 作業:
  - `MirBuilderBox.emit_from_program_json_v0`
    - `func_defs_mir` だけが非空だった場合でも黙って `{ "functions": [defs] }` を返さず、`[builder/selfhost-first:unsupported:defs_only]` を出す。
    - internal lowers がすべて `null` の場合、`[builder/selfhost-first:unsupported:<reason>]` のタグを付与。
  - `FuncLoweringBox.lower_func_defs`
    - どの関数名で `_lower_func_body` が `null` を返したかを `HAKO_SELFHOST_TRACE=1` でログ出力。
  - `tools/hakorune_emit_mir.sh`
    - 既存の head/tail ログ出力で `[builder/selfhost-first:*]` タグがそのまま表示されることを確認済み（追加改修なし）。
- 成果物:
  - selfhost-first で Stage1 CLI を通したときに、どの関数/構造がまだ未サポートなのかがログで推測できる状態。

### Step 1 — defs injection の再設計
- Status: initial-implemented（main 必須チェックはトグル付き; multi-function への完全移行は後続 Step）。
- 目的: `FuncLoweringBox.inject_funcs` で main 関数の有無を意識し、multi-function モジュールの土台を整える。
- 作業:
  - `inject_funcs` 内で `HAKO_MIR_BUILDER_REQUIRE_MAIN=1` のときに `"name":"main"` を含まない `functions` 配列を拒否し、`[builder/funcs:fail:no-main]` をトレース出力して injection をスキップする（既定では OFF なので既存挙動は維持）。
  - 将来フェーズで、`Program.body` から生成した main と defs を「2段構え」でマージする API（main 名の受け渡しなど）を追加する。
- 成果物（現段階）:
  - Env トグルを有効化した状態では「main を含まない MIR に defs だけ差し込む」ケースを検知できるようになり、Stage1 実装時に安全に stricter モードへ移行する足場ができた。

### Step 2 — `_lower_func_body` の拡張（ローカル＋if）
- 目的: Stage1 CLI の `HakoCli.cmd_emit_program_json` のような「Local / Assign / If / Return だけで構成された関数」を selfhost builder で lowering できるようにする。
- 作業:
  - Body を JsonFrag で走査し、ローカル導入・代入・分岐を MIR ブロックへ展開する最小ロジックを FuncLoweringBox に追加。
  - Loop が出た時は `[builder/funcs:unsupported:loop]`（仮タグ）を出して Fail-Fast（Step 3 で LoopForm 対応を行う）。
- 成果物:
  - Loop を含まない defs は selfhost builder で MIR 関数にできるようになり、Stage1 CLI の emit/build ハンドラの半分程度を selfhost パスで賄える。

### Step 3 — Loop（LoopForm）の受理
- Status: initial-implemented (2025-11-15). `FuncBodyBasicLowerBox` now calls `LowerLoopSumBcBox`/`LowerLoopSimpleBox` from `_try_lower_loop`, tags unsupported loops with `[builder/funcs:unsupported:loopform]`, and delegates all PHI/carrier handling to LoopForm lowers.
- 目的: LoopForm 正規化済みの while/for を MIR に落とす。ループの正規化・PHI設計はLoopForm/既存lower_loop系Boxに任せ、FuncLowering/MirBuilder側はそれを使うだけにする。
- 作業内容（実装済み）:
  - `FuncBodyBasicLowerBox`に`_try_lower_loop`メソッド追加:
    - Loop判定 → `LowerLoopSumBcBox.try_lower` → `LowerLoopSimpleBox.try_lower` の順に試す。
    - 成功時は`_rebind`で関数名を`Box.method/arity`に付け替え。
    - 失敗時は`[builder/funcs:unsupported:loopform]`でFail-Fast。
  - `lower`メソッド冒頭でLoop優先処理:
    - Loop含む場合は`_try_lower_loop`を呼び、成功/失敗で明確に分岐。
    - Loopが無い場合のみ既存のLocal/If/Return処理に進む。
  - PHI地獄防止ポリシー徹底:
    - FuncBodyBasicLowerBox/FuncLowering側でPHIやキャリアを直接いじらない。
    - LoopForm制約外は必ずタグ付きでFail-Fast（Rust providerに退避可能）。
- 成果物:
  - `cmd_build_exe`の`loop(i < argc)`等、Stage1 CLIの代表的なwhile/forパターンをselfhost builderで通せる基礎が整った。
  - 次のステップ: LoopForm対応の動作確認スモークテスト追加、Step4（MethodCall/ExternCall）へ進む。

### Step 4 — MethodCall / ExternCall パリティ
- 目的: `hostbridge.extern_invoke` / `FileBox` / `ArrayBox` など Stage1 CLI で多用される呼び出しを selfhost builder でも再現。
- 作業:
  - `FuncLoweringBox` に MethodCall/ExternCall の lowering ルートを追加し、`mir_call Method` もしくは `extern_call` を生成。
  - `func_map` により `me.cmd_build_exe` のような self-call も Box.method/N に resolve（未対応の呼び出しは `[builder/funcs:unsupported:call]` で Fail）。
- 成果物:
  - Stage1 CLI の主要メソッド体が selfhost builder で MIR 関数化できる。

### Step 5 — call resolve / methodize 後処理
- 目的: 生成済み MIR に対して call resolver / methodize pass をかけ、Rust provider と同じ命名・呼び出し形式を実現。
- 作業:
  - `HAKO_MIR_BUILDER_CALL_RESOLVE=1` を本格利用し、call の `Const("Box.method/N")` を `mir_call` に変換。Stage1 CLI で `mir_call Method` を使うケースをテストし、Methodize との組み合わせでも崩れないことを確認。

### Step 6 — selfhost-first canary / build_stage1.sh
- 目的: selfhost builder を既定 ON に戻す準備。
- 作業:
  - `stage1_launcher_program_to_mir_canary_vm.sh` の selfhost-first 版を追加して selfhost builder 単独で 60KB 級 MIR を生成できることを検証。
  - `tools/selfhost/build_stage1.sh` を selfhost-first で回し、selfhost builder 由来の MIR で `emit program-json` / `emit mir-json` / `build exe` が通ることを確認。
  - 問題が無ければ `HAKO_SELFHOST_BUILDER_FIRST=1` を既定に戻す（別PRでも可）。

作業順は Step 0 → 1 → 2 → 3 → 4 → 5 → 6 を想定、各ステップで必ず docs（このファイル＆CURRENT_TASK）とスモーク/テストを更新する。***