fix(mir-builder): static method arity mismatch根治 - Phase 25.x

**問題**: - ParserStmtBox.parse_using/4 に5引数が渡される - me.method呼び出しで instance/static 判別なし - static method に誤って receiver 追加 **修正**: - MeCallPolicyBox: params[0]の型で instance/static 判別 - Instance method: receiver 追加 - Static method: receiver なし - Arity検証（NYASH_ME_CALL_ARITY_STRICT=1） **ドキュメント**: - docs/reference/environment-variables.md 新規作成 - docs/development/architecture/mir-logs-observability.md 更新 **テスト**: - src/tests/mir_stage1_cli_emit_program_min.rs 追加 - 既存 stage1 テスト全てパス Phase: 25.x
2025-11-21 11:16:38 +09:00
parent b92d9f335d
commit c344451087
15 changed files with 702 additions and 53 deletions
--- a/docs/development/architecture/mir-logs-observability.md
+++ b/docs/development/architecture/mir-logs-observability.md
@ -97,12 +97,37 @@

 ---

+### 5. MeCall Arity Debug（Phase 25.x追加）
+
+**場所**: `src/mir/builder/method_call_handlers.rs`
+
+| 行番号 | タグ | 説明 | 用途 |
+|-------|------|-----|------|
+| 70-73 | `[me-call] arity mismatch (instance)` | Instance method arity不一致警告 | Dev専用 |
+| 98-101 | `[me-call] arity mismatch (static)` | Static method arity不一致警告 | Dev専用 |
+| 150-154 | `[static-call] emit` | Static method呼び出しトレース | 観測用 |
+
+**有効化環境変数**:
+- `NYASH_ME_CALL_ARITY_STRICT=1` - 厳密モード（不一致でエラー返却）
+- `NYASH_STATIC_CALL_TRACE=1` - トレースモード（warning出力）
+
+**説明**:
+- `me.method(...)` 呼び出しのarity検証
+- Instance method（receiver追加）vs Static method（receiver なし）の判別
+- ParserStmtBox.parse_using/4 の5引数バグ等の検出
+
+**用途と削除時期**:
+- Phase XX（static box instance化）完了後に削除予定
+- 過渡期のデバッグ支援ログ（static boxのsingleton化後は不要）
+
+---
+
 ## 用途別集計表

 | 用途 | 件数 | 内容 | 用途と削除時期 |
 |-----|-------|-----|----------|
-| **Dev専用** | 11 | Stage-1 CLI / StringHelpers デバッグ用 | 削除予定（Phase 25.x 完了） |
-| **観測用** | 3 | FuncScanner ループ反復観測 | 保持推奨（MIR観測 API 昇格） |
+| **Dev専用** | 13 | Stage-1 CLI / StringHelpers / MeCall Arity デバッグ用 | 削除予定（Phase 25.x 完了） |
+| **観測用** | 4 | FuncScanner ループ反復 / Static call トレース | 保持推奨（MIR観測 API 昇格） |
 | **コメント** | 1 | テスト場所の注釈 | - |

 ---
--- a/docs/development/roadmap/phases/phase-25.1/stage1-usingresolver-loopform.md
+++ b/docs/development/roadmap/phases/phase-25.1/stage1-usingresolver-loopform.md
@ -9,8 +9,12 @@
  - `src/mir/loop_builder.rs`
  - `src/mir/phi_core/loopform_builder.rs`
  - `src/mir/phi_core/loop_snapshot_merge.rs`
- Stage‑1 UsingResolver テストの観察点:
-  - `src/tests/mir_stage1_using_resolver_verify.rs`（collect_entries の SSA/PHI 期待を確認）
+  - Stage‑1 UsingResolver テストの観察点:
+  - `src/tests/mir_stage1_using_resolver_verify.rs`
+    - collect_entries 系ループ（JSON スキャン）
+    - Region+next_i 形の entries ループ
+    - modules_list 分割ループ（Region+next_start）
+    - resolve_for_source 相当で entries ループと modules_map 参照を同時に行うケース
  - 既存の JSON フロント経路でどのブロック/値が PHI 化されているかを dump しておくと導線が追いやすい。

 ## JSON v0 フロント側の契約（Stage‑B → Stage‑1）
@ -113,7 +117,9 @@ source -> | Stage-B (block) |  -->  | Stage-1 UsingRes |  -->  | MirBuilder (.ha
 ### ループ洗い出しメモ（entry / pipeline_v2）
 - entry UsingResolver（lang/src/compiler/entry/using_resolver_box.hako）
  - Region+next_i 化済み: entries イテレーション / JSON スキャン / modules_list 分割
-  - 追加テスト: modules_list 分割ループ（start/next_start）をそのまま MIR 化できることを `mir_stage1_using_resolver_module_map_regionized_verifies` で固定。
+  - 追加テスト:
+    - modules_list 分割ループ（start/next_start）をそのまま MIR 化できることを `mir_stage1_using_resolver_module_map_regionized_verifies` で固定。
+    - resolve_for_source 相当で entries ループと modules_map 参照（MapBox.has/get）を同時に行うケースを `mir_stage1_using_resolver_resolve_with_modules_map_verifies` で固定。
  - 残り: なし（現状の 3 ループは all Region 形）
 - pipeline_v2 UsingResolver（lang/src/compiler/pipeline_v2/using_resolver_box.hako）
  - 役割: modules_json 上で alias を解決する stateful helper（テキスト収集は entry 側）。
--- a/docs/development/runtime/cli-hakorune-stage1.md
+++ b/docs/development/runtime/cli-hakorune-stage1.md
@ -17,6 +17,10 @@ Status: design-only + Stage0 stub 実装済み（Phase 25.1 時点では仕様
  - Stage1 実行時は「CLI として」ではなく、これらのランタイムサービス層（C-ABI/extern）として利用することを前提とする。
  - Phase 25.1 現在は、Rust Stage0 から `.hako` 側 stub CLI（`lang/src/runner/stage1_cli.hako`）を子プロセスとして起動する
    ブリッジ（`src/runner/stage1_bridge.rs`）のみ実装済みで、自己ホスト EXE（`target/selfhost/hakorune`）はまだ設計段階。
+    - ブリッジは env-only 仕様で Stage1 stub を呼び出し、`STAGE1_EMIT_PROGRAM_JSON` / `STAGE1_EMIT_MIR_JSON` / `STAGE1_BACKEND`
+      / `STAGE1_SOURCE` などの環境変数をセットする。
+    - Stage‑1 UsingResolver は `HAKO_STAGEB_APPLY_USINGS=0` を既定とし、CLI 経路では prefix 連結を行わない（using 解決の検証は
+      専用テストで行い、CLI 本線は Program(JSON) 生成に集中させる）。
 - Stage1（Hakorune selfhost CLI）
  - 実体: `target/selfhost/hakorune`（Phase 25.1 では Ny Executor プロトタイプ）。
  - 役割: `.hako → Program(JSON) → MIR(JSON) → 実行/EXE` というパイプラインの制御。
@ -229,6 +233,35 @@ hakorune emit mir-json [-o <out>] [--quiet] <source.hako>
  - `tools/selfhost/run_stage1_cli.sh --bin /tmp/hakorune-dev emit program-json apps/tests/minimal.hako` は exit code 0 だが stdout が空のまま。Stage‑B 側で box 定義を Program(JSON) に含められるようになるまで、Rust CLI / BuildBox (`tools/hakorune_emit_mir.sh`) 経由での JSON 取得を継続する。
  - using 解決は Stage0（Rust Runner）と Stage1（Hakorune）の二系統に分離する方針。Stage1 側は `lang.compiler.entry.using_resolver_box` で `nyash.toml` の `[modules]` を参照し、`HAKO_STAGEB_MODULES_LIST`（shell 側で生成した `name=path` リスト）をキーに依存 Box を text merge する。Rust 側は既存の Runner using 実装を維持し、Stage1 経路はこの Box で独立した自己ホスト導線を持つ。

+### Stage‑1 CLI デバッグメモ（Stage1Cli + BuildBox + ParserBox）
+
+- 中間スモーク: `apps/tests/stage1_cli_emit_program_min.hako`
+  - 役割: `Stage1Cli.emit_program_json` → `BuildBox.emit_program_json_v0` → `ParserBox.parse_program2` までを、Rust ブリッジや Stage0 runner を経由せずに直接 VM 上で実行する最小ケース。
+  - 実行例:
+    ```bash
+    NYASH_PARSER_STAGE3=1 HAKO_PARSER_STAGE3=1 \
+    NYASH_ENABLE_USING=1 HAKO_ENABLE_USING=1 \
+    ./target/release/hakorune apps/tests/stage1_cli_emit_program_min.hako
+    ```
+- Rust テスト側のハーネス: `src/tests/mir_stage1_cli_emit_program_min.rs`
+  - `include_str!("../../lang/src/runner/stage1_cli.hako")` で Stage1Cli 本体をバンドルし、`static box Main` を末尾に付けて 1 ソースとしてパースする形に統一。
+  - `mir_stage1_cli_emit_program_min_compiles_and_verifies`:
+    - Stage1Cli + UsingResolver + BuildBox を含んだモジュールが MIR 生成・verify まで通ることを確認（SSA/PHI 崩壊なし）。
+  - `mir_stage1_cli_emit_program_min_exec_hits_type_error`:
+    - VM 実行まで進め、Stage‑1 CLI 経路がまだ決定的に失敗すること（型エラー or 未解決呼び出し）が Rust テスト内で再現できることを確認するための箱。
+- 現時点で観測されている実行時エラー（2025‑11‑21 時点）:
+  - `apps/tests/stage1_cli_emit_program_min.hako` を直接 `hakorune` で実行すると、
+    - 以前の「String + Void」「String + MapBox」ではなく、
+    - `Type error: unsupported compare Ge on String("using \"foo/bar.hako\" as Foo\n") and Integer(19)`
+    - というエラーが Stage‑1 経路で発生している。
+  - 経路としては `Stage1Cli.emit_program_json` → `BuildBox.emit_program_json_v0` → `ParserBox.parse_program2` まで進んだうえで、
+    どこかで Compare(Ge) の両辺が String vs Int に崩れていることが確認できている。
+- デバッグ方針:
+  - Stage‑1 CLI 本線のバグ追跡は、必ず「小さな箱」から行う:
+    - `.hako` 側: `apps/tests/stage1_cli_emit_program_min.hako` で Stage1Cli+UsingResolver+BuildBox をまとめて叩く中間スモーク。
+    - Rust 側: `src/tests/mir_stage1_cli_emit_program_min.rs` で同じソースを `NyashParser → MirCompiler → VM` まで持ち込むテスト。
+  - 次フェーズでは、このハーネス上で Compare(Ge) 命令をスキャンし、「左オペランドがソース行 String、右が Int になっている Compare」を 1 関数単位まで特定し、その関数を別の minimal .hako + Rust テストに切り出して修正する。
+
 ## `check` コマンド（予約）

 ```text
--- a/docs/reference/environment-variables.md
+++ b/docs/reference/environment-variables.md
@ -0,0 +1,153 @@
+# 環境変数リファレンス
+
+Nyashの動作を制御する環境変数の一覧。
+
+---
+
+## MIR Builder検証系
+
+MIRビルダーの動作検証・デバッグ用環境変数。
+
+| 環境変数 | デフォルト | 用途 | 追加Phase |
+|---------|----------|-----|-----------|
+| `NYASH_ME_CALL_ARITY_STRICT=1` | OFF | me.method呼び出しのarity不一致でエラー返却 | Phase 25.x |
+| `NYASH_STATIC_CALL_TRACE=1` | OFF | Static method呼び出しのトレース出力 | Phase 25.x |
+| `NYASH_VERIFY_ALLOW_NO_PHI=1` | OFF | PHI検証スキップ（支配・マージ） | - |
+| `NYASH_VERIFY_ALLOW_LEGACY=1` | OFF | レガシー命令許可 | - |
+| `NYASH_VERIFY_BARRIER_STRICT=1` | OFF | Barrier配置厳密チェック | - |
+| `NYASH_VERIFY_EDGE_COPY_STRICT=1` | OFF | Edge copy検証 | - |
+| `NYASH_VERIFY_RET_PURITY=1` | OFF | Return block純粋性検証 | - |
+| `NYASH_BREAKFINDER_SSA_TRACE=1` | OFF | SSA詳細トレース（BreakFinderBox等） | - |
+
+### 使用例
+
+```bash
+# Dev環境で厳密検証（arity不一致でビルドエラー）
+NYASH_ME_CALL_ARITY_STRICT=1 cargo test
+
+# トレースのみ（warning表示、エラーにはしない）
+NYASH_STATIC_CALL_TRACE=1 ./target/release/hakorune program.hako
+
+# PHI検証を一時的にスキップ
+NYASH_VERIFY_ALLOW_NO_PHI=1 ./target/release/hakorune program.hako
+
+# SSA詳細トレース（BreakFinderBox等のデバッグ）
+NYASH_BREAKFINDER_SSA_TRACE=1 cargo test mir_stage1_using_resolver_verify 2>&1 | grep "breakfinder/ssa"
+```
+
+---
+
+## Stage-1 CLI制御系
+
+Stage-1 CLI（Nyash selfhosting compiler）の制御用環境変数。
+
+| 環境変数 | デフォルト | 用途 | 追加Phase |
+|---------|----------|-----|-----------|
+| `NYASH_USE_STAGE1_CLI=1` | OFF | Stage-1 CLI有効化 | Phase 25.1 |
+| `STAGE1_CLI_DEBUG=1` | OFF | Stage-1 CLI詳細ログ | Phase 25.1 |
+| `STAGE1_EMIT_PROGRAM_JSON=1` | OFF | Program JSON出力モード | Phase 25.1 |
+| `STAGE1_EMIT_MIR_JSON=1` | OFF | MIR JSON出力モード | Phase 25.1 |
+| `STAGE1_BACKEND={vm\|llvm\|pyvm}` | `vm` | 実行バックエンド指定 | Phase 25.1 |
+| `STAGE1_SOURCE=<path>` | - | ソースファイルパス | Phase 25.1 |
+| `STAGE1_SOURCE_TEXT=<text>` | - | ソーステキスト（inline指定） | Phase 25.1 |
+| `STAGE1_PROGRAM_JSON=<path>` | - | Program JSONパス | Phase 25.1 |
+
+### 使用例
+
+```bash
+# Stage-1 CLI経由で.hakoファイルをコンパイル
+NYASH_USE_STAGE1_CLI=1 STAGE1_SOURCE=program.hako \
+  ./target/release/hakorune lang/src/runner/stage1_cli.hako
+
+# Program JSON生成
+STAGE1_EMIT_PROGRAM_JSON=1 STAGE1_SOURCE=program.hako \
+  ./target/release/hakorune lang/src/runner/stage1_cli.hako
+
+# デバッグログ付き
+STAGE1_CLI_DEBUG=1 NYASH_USE_STAGE1_CLI=1 \
+  ./target/release/hakorune program.hako
+```
+
+---
+
+## Parser制御系
+
+パーサーの動作制御用環境変数。
+
+| 環境変数 | デフォルト | 用途 | 追加Phase |
+|---------|----------|-----|-----------|
+| `NYASH_PARSER_STAGE3=1` | OFF | Stage-3 parser有効化 | Phase 25.3 |
+| `HAKO_PARSER_STAGE3=1` | OFF | Stage-3 parser有効化（.hako側） | Phase 25.3 |
+| `NYASH_ENABLE_USING=1` | OFF | using文サポート有効化 | Phase 25.1 |
+| `HAKO_ENABLE_USING=1` | OFF | using文サポート有効化（.hako側） | Phase 25.1 |
+| `HAKO_STAGEB_APPLY_USINGS=1` | OFF | Stage-B using適用 | Phase 25.1 |
+
+### 使用例
+
+```bash
+# using文を使ったプログラムをパース
+NYASH_PARSER_STAGE3=1 NYASH_ENABLE_USING=1 \
+  ./target/release/hakorune program_with_using.hako
+```
+
+---
+
+## デバッグ・観測系
+
+デバッグ・トレース用環境変数。
+
+| 環境変数 | デフォルト | 用途 | 追加Phase |
+|---------|----------|-----|-----------|
+| `NYASH_CLI_VERBOSE=1` | OFF | 詳細診断情報出力 | - |
+| `NYASH_VM_TRACE=1` | OFF | VM実行トレース出力 | - |
+| `NYASH_VM_DUMP_MIR=1` | OFF | VM実行前MIR出力 | - |
+| `NYASH_DUMP_JSON_IR=1` | OFF | JSON IR出力 | - |
+| `NYASH_STAGE1_MIR_DUMP=1` | OFF | Stage-1 MIR出力 | Phase 25.x |
+| `NYASH_STAGE1_SCAN_GE=1` | OFF | Compare Ge命令スキャン | Phase 25.x |
+| `NYASH_TO_I64_DEBUG=1` | OFF | to_i64変換デバッグ | Phase 25.x |
+| `NYASH_FUNCSCANNER_DEBUG=1` | OFF | FuncScanner詳細ログ | Phase 25.3 |
+
+### 使用例
+
+```bash
+# VM実行トレース
+NYASH_VM_TRACE=1 ./target/release/hakorune program.hako 2>&1 | grep "vm-trace"
+
+# MIR確認（複数手法）
+NYASH_VM_DUMP_MIR=1 ./target/release/hakorune program.hako
+./target/release/hakorune --dump-mir program.hako
+./target/release/hakorune --emit-mir-json debug.json program.hako
+
+# Stage-1 CLI + MIRダンプ
+NYASH_STAGE1_MIR_DUMP=1 cargo test mir_stage1_cli_emit_program_min
+```
+
+---
+
+## プラグイン・Box制御系
+
+プラグインとBox factoryの制御用環境変数。
+
+| 環境変数 | デフォルト | 用途 | 追加Phase |
+|---------|----------|-----|-----------|
+| `NYASH_DISABLE_PLUGINS=1` | OFF | プラグイン無効化 | - |
+| `NYASH_BOX_FACTORY_POLICY={builtin_first\|plugin_first}` | `builtin_first` | Box factory優先順位 | Phase 15.5 |
+| `NYASH_FILEBOX_MODE={auto\|plugin\|builtin}` | `auto` | FileBox実装選択 | Phase 15.5 |
+
+### 使用例
+
+```bash
+# プラグイン無効で実行（コアBox経路のみ）
+NYASH_DISABLE_PLUGINS=1 ./target/release/hakorune program.hako
+
+# Plugin優先でBox生成
+NYASH_BOX_FACTORY_POLICY=plugin_first ./target/release/hakorune program.hako
+```
+
+---
+
+## 参考
+
+- **MIRログ観測**: [docs/development/architecture/mir-logs-observability.md](../development/architecture/mir-logs-observability.md)
+- **Phase 25.4計画**: [docs/development/roadmap/phases/phase-25.4-naming-cli-cleanup/README.md](../development/roadmap/phases/phase-25.4-naming-cli-cleanup/README.md)
+- **MIR検証システム**: [src/mir/verification/](../../src/mir/verification/)