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

Phase 25.1c — Env / Extern / BoxIntrospect Structural Cleanup

Status: planning（構造整理フェーズ・挙動は変えない）

ゴール

• env.* / hostbridge.* / env.box_introspect.* の責務と経路を整理し、型システムまわりの「正しい入口」を 1 箇所に揃える。
• Box 型情報 API（env.box_introspect.kind + BoxTypeInspectorBox）を コア型システムとして扱えるようにする（plugins の有無に依存しない）。
• i64 / MapBox / ArrayBox の unwrap ロジックを SSOT に寄せ、MirBuilder / JsonEmit / LoopOpts / BoxHelpers が同じ前提で動くようにする。

スコープ（何をここで扱うか）

• 対象:
  • Rust 側: extern_registry.rs / handlers/externals.rs / handlers/extern_provider.rs / runtime/plugin_loader_v2/*
  • Hako 側: BoxTypeInspectorBox / BoxHelpers / JsonEmitBox / MirSchemaBox / LoopOptsBox
  • ドキュメント: docs/specs（env externs / box_introspect / numeric view の設計メモ）
• 非対象:
  • 新しい言語機能や VM 命令の追加（Phase 25 ポリシーに従い、仕様拡張はしない）。
  • MirBuilder の意味論変更（multi‑carrier や LoopForm の設計は Phase 25.1b の範囲に留める）。

やりたい整理（タスクリスト）

1. env. extern の SSOT を決める*

   • env.get / env.mirbuilder.emit / env.codegen.emit_object / env.codegen.link_object / env.box_introspect.kind を一覧化し、仕様（引数・戻り値・MIR 形）を docs/specs/env_externs.md（仮）に明文化する。
   • JSON v0 → MIR ブリッジ（MapVars::resolve / lowering）で、上記が必ず ExternCall("env.*", ..) に落ちることを確認・修正する。

2. hostbridge.extern_invoke を「互換レイヤ」に押し込める

   • 方針: 「env.* で表現できるものは ExternCall を正義とし、hostbridge.extern_invoke は互換用ラッパに限定する」。

• Hako 側: hostbridge.extern_invoke("env.*", ..) は内部で env.* を呼ぶだけにする（新規コードは直接 env.* を使う）。
• Rust 側: "hostbridge.extern_invoke" の実装は、extern_provider_dispatch("env.*", ..) に委譲する薄いブリッジに整理する。

3. BoxIntrospect をコア型システムに昇格させる

   • env.box_introspect.kind の実装を plugin loader v2 直下ではなく、コア runtime（例: runtime/box_introspect.rs）に寄せる。
   • コア型（MapBox / ArrayBox / StringBox / IntegerBox / BoolBox / NullBox）は runtime 側で build_box_info を定義し、plugin loader は「ユーザー Box の拡張」だけを担当する。
   • BoxTypeInspectorBox は env.box_introspect.kind(value) を唯一の情報源として扱い、repr ベースの fallback は「plugins も env.* も使えないデバッグ環境のみ」で使うことをコメントで明示する。

4. Numeric view（i64 unwrap）の SSOT 化

• Hako 側: string_helpers / BoxHelpers / MirSchemaBox / JsonEmitBox / LoopOptsBox に散っている i64 unwrap ロジックを、小さなユーティリティ（仮: box_numeric_view.hako）に寄せる。
• Rust 側: NyashBox から i64 を取り出す as_i64 的な関数を 1 箇所に置き、extern / BoxIntrospect 経路からはそれを使う。

5. Stage‑B Main を箱に分割して SSA/デバッグを軽くする

   • 現状の compiler_stageb.hako: Main.main は:
     • CLI 引数パース (--source / --bundle-* / --require-mod)
     • bundle/require 解決 (BundleResolver)
     • body 抽出 (body_src の抽出ロジック)
     • ParserBox 呼び出し (parse_program2 → emit JSON)
     • defs スキャン (FuncScannerBox.scan_all_boxes) が 1 関数に詰め込まれており、MIR 上でも巨大な Main.main になっている。
   • 25.1c ではこれを「箱理論」に沿って分割する方針を立てており、Phase 25.1c 冒頭でまず Stage‑B 側を 4 箱構造にリファクタした:
     • Main（エントリ薄箱）: main(args){ return StageBDriverBox.main(args) } のみを担当。
     • StageBDriverBox（オーケストレーション）: StageBArgsBox.resolve_src → StageBBodyExtractorBox.build_body_src → ParserBox.parse_block2 → defs 挿入 → print(ast_json) だけを見る。
     • StageBArgsBox（CLI 引数と bundle/require の扱いだけを担当）: もともとの「args/src/src_file/HAKO_SOURCE_FILE_CONTENT/return 0」ロジックを完全移動。
     • StageBBodyExtractorBox（body_src 抽出ロジック＋bundle/using/trim を担当）: もともとの body_src 抽出〜コメント削除〜BundleResolver/Stage1UsingResolverBox〜前後 trim までを丸ごとカプセル化。
   • いずれもロジックはそのまま移動であり、コメント・using・ログを含めて挙動は完全に不変（同じ Program(JSON v0)、同じログ、同じ VM error: Invalid value）であることを selfhost CLI サンプルで確認済み。エラーの発生箇所は Main.main から StageBArgsBox.resolve_src/1 に関数名だけ変わっており、SSA/Loop 側の根本修正はこの後のタスク（LoopBuilder / LocalSSA 整理）で扱う。

6. LoopBuilder / pin スロットの型付け・箱化

   • いまの LoopBuilder は __pin$*$@recv のような文字列ベースの「内部変数名」を variable_map に直接突っ込んで、SSA/phi/pin を管理している。
   • 25.1c では、Loop 状態を「箱」として切り出して型付けする:
     • 例: LoopStateBox（Rust 側構造体）に
       • recv_slots（Method receiver 用）
       • index_slots（ループカウンタ用）
       • limit_slots（limit/上限 expr 用） を明示的に持たせる。
   • LoopBuilder::emit_phi_at_block_start / update_variable は、この LoopStateBox を通じてのみ pin/phi を操作し、「recv に Null/未定義が混ざらない」ことを構造レベルで保証する。

7. ビルダー観測用の専用レイヤ（デバッグ箱）

   • すでに NYASH_BUILDER_TRACE_RECV / NYASH_BUILDER_DEBUG などで ad-hoc に eprintln を入れているが、出力箇所が複数ファイルに散っていて再利用しにくい。
   • 25.1c ではこれを builder.observe 的なモジュール（箱）に集約する:
     • 例: observe::recv::log(fn, bb, name, src, dst)、observe::phi::log(fn, bb, dst, inputs) など。
   • ポリシー:
     • すべて dev トグル（NYASH_BUILDER_TRACE_*）越しに呼ぶ。
     • 本番挙動は変えず、「どこをどうトレースできるか」を構造として明示する。

8. Stage‑B 向けの極小 MIR 再現ハーネス

   • docs/private/roadmap/phases/phase-20.33/DEBUG.md にあるような Stage‑B 向けメモを踏まえ、Stage‑B/MirBuilder 用の「極小 Hako → MIR テスト」を 1 つ用意する。
   • 例:
     • 100〜200 行程度の .hako を lang/src/compiler/tests/stageb_min_sample.hako のようなファイルに固定。
     • Rust 側で MirBuilder に直接その AST を食わせて MIR を生成し、NYASH_VM_VERIFY_MIR=1 で「Undefined value」が出ないことを確認するユニット／スモークを足す（構造バグ検知用）。
   • これにより、Stage‑B/LoopBuilder に関する修正が .hako 本番コード全体に依存せず、小さな再現ケースで検証できるようにする。

進め方メモ

• 先にドキュメントを書く（env extern / BoxIntrospect / numeric view の仕様を docs/specs 配下に整理）→ そのあとで Bridge / VM / Hako を小さく揃える。
• 既存フェーズとの関係:
  • Phase 25.1b: selfhost builder / multi‑carrier / BoxTypeInspector 実装フェーズ（機能側）。
  • Phase 25.1c: そのうち「env.* / hostbridge.* / BoxIntrospect」に加えて、Stage‑B Main / LoopBuilder / builder 観測レイヤの構造と責務も整理するメタフェーズ（構造側）。
  • 挙動を変えないこと（Fail‑Fast / default path は現状維持）を前提に、小さな差分で進める。

デバッグ方針（25.1c で踏みたい順番）

• 1. Stage‑B rc=1 の発生箇所を箱単位まで特定する
  • 代表 canary:
    • tools/smokes/v2/profiles/quick/core/phase251/stageb_fib_program_defs_canary_vm.sh
    • tools/smokes/v2/profiles/quick/core/phase251/selfhost_cli_run_basic_vm.sh
    • まずは compiler_stageb.hako の流れを箱ごとに分解してログする:
    • StageBArgsBox.resolve_src
    • StageBBodyExtractorBox.build_body_src
    • ParserBox.parse_program2 / ParserBox.parse_block2
    • StageBFuncScannerBox.scan_all_boxes（Phase 25.1c 時点では Stage‑B ローカル実装）
  • 各箱の入口/出口に [stageb/trace:<box>.<method>:enter|leave] のような軽いタグを置き、どの箱が rc=1 の直前で止まっているかを特定する（挙動は変えない）。
• 2. Rust Region レイヤを「正解ビュー」として .hako 側を寄せる
  • Rust 側にはすでに Region / RefSlotKind / FunctionSlotRegistry + ControlForm があり、StageBBodyExtractorBox.* 周辺のスロット（src/body_src/bundle_* など）がどの Loop/If Region に属しているかを NYASH_REGION_TRACE=1 で観測できる。
  • 25.1c では .hako 側に観測専用 Box（案: StageBRegionObserverBox）を追加し、
    • enter_region(kind, name, slots_json)
    • leave_region() のような API で「箱名・構造名・スロット名の集合」だけを JSON で print する。
  • StageBBodyExtractorBox の外側ループ・内側 if など、問題になりやすい箇所でこの Box を呼び出し、Rust の [region/observe] ログと「木構造＋スロット名」が対応しているかを確認する。
    → ずれている Region（例: body_src などが早期に欠落するスコープ）から優先的に修正する。
• 3. Stage‑B 用の極小ハーネスを Rust / .hako 両方に用意する
  • fib canary はやや重いため、100〜200 行程度の「using + 1 box + 1 loop」だけの最小サンプルを lang/src/compiler/tests/stageb_min_sample.hako のようなファイルとして固定する。
  • Rust 側:
    • そのサンプルを AST→MIR に通し、NYASH_VM_VERIFY_MIR=1 で Undefined value が出ないことを確認する小さなテストを用意（既存の Stage‑B 向け MIR テスト群に揃える）。
  • .hako 側:
    • 同じサンプルを入力として StageBDriverBox の簡易版（mini driver）を作り、StageBArgsBox.resolve_src → StageBBodyExtractorBox.build_body_src → ParserBox.parse_program2 だけを通す driver を追加する。
    • これにより、Stage‑B/LoopBuilder に対する修正を「本番 compiler_stageb.hako 全体」ではなく「ミニマムな Hako 断片」で検証できるようにする。
• 4. Stage‑1 CLI (HakoCli.run) の selfhost ラインは Stage‑B が緑になってから扱う
  • selfhost_cli_run_basic_vm.sh の現状の失敗は、Stage‑B が rc=1 で Program(JSON) を 1 行も返していないことが原因であり、HakoCli.run の MIR 生成まで到達していない。
  • 25.1c ではまず Stage‑B 側（fib defs / stageb_min / mini driver）を rc=0 に戻し、
    その Program(JSON v0) を固定入力にして Phase 25.1b 側の selfhost builder / HakoCli.run MIR を Rust ラインと diff する、という順番で進める。