hakorune/docs/private/roadmap/phase-31.4-blockbuilder-cleanup.md

Phase‑31.4 — Selfhost BlockBuilder ModuleFunction 依存撤退（設計メモ）

Context

• BlockBuilderBox が Mir.* と MirSchemaBox.* の二系統 API を混在使用（約 60 箇所）。
• 生成フェーズで ModuleFunction 解決に依存し、自己ホスト実行時に name 解決ゆらぎ（Unknown module function）を招く。
• JsonEmitBox は BoxHelpers 経由へ統一済み。StringHelpers の依存は最小（int_to_str/json_quote）で妥当。

Goal（根治）

• BlockBuilderBox から ModuleFunction 依存（Mir.*/MirSchemaBox.* 呼び出し）を撤退し、Map/Array の直接生成（または MirSchemaBox の単一路）に統一する。
• 以後の自己ホスト系は、BoxAPI（MapBox/ArrayBox）＋ JsonEmitBox だけで MIR(JSON) を構築し、using/探索の影響を受けない。

Plan（小さく段階導入）

1. API統一（P1）

   • Mir.* を全撤退。MirSchemaBox.* に一本化（inst_const/inst_ret/inst_compare/inst_binop/inst_branch/inst_jump/block/fn_main/module）。
   • import も using "selfhost/shared/mir/mir_schema_box.hako" as MirSchemaBox に統一。
   • 未使用の StringHelpers import を削除。

2. 直接生成（P2・最小）

   • MirSchemaBox 呼び出し自体も Map/Array 直接構築に段階移行（可読性を維持するため mk_inst_* ヘルパを同ファイルに薄く導入）。
   • 代表ルート（const_ret/compare_branch/binop/extern_call_ret）から順次適用。

3. 検証（Smokes/Strict）

   • selfhost_mircall_extern_from_builder_vm.sh が Gate‑C→Mini‑VM で true。
   • Gate‑C Strict（quick/quick‑lite）を既定ONのまま緑を維持（PARSE_STRICT/VERIFY_CORE_EXTERN）。

Acceptance

• BlockBuilderBox 内の ModuleFunction 呼び出しが 0。未使用 import なし。
• 生成 JSON 形状は現行のバリデータ（validate_shape/Gate‑C Reader）を満たす。
• 自己ホスト quick/selfhost スモークが緑（外部依存なし）。

Notes

• StringHelpers の使用は JsonEmitBox の補助（int_to_str/json_quote）のみ許容。数値正規化は BoxHelpers で担保。
• MirSchemaBox は SSOTとして残すが、将来的に Map 直接生成へ段階移行（設計単純化のため）。