hakorune/docs/reference/environment-variables.md

# 環境変数リファレンス

Nyash の主要な環境変数をカテゴリ別に整理するよ。`適用経路` はどのパスで効くかを示す:

- Rust AST: Rust パーサ直通 (`--dump-mir` など)
- JSON v0/Stage-1: selfhost/Stage-1/`--ny-parser-pipe` 経由（json_v0_bridge で処理）
- Any: どの経路でも有効

---

## ダンプ / 診断

| 変数 | デフォルト | 適用経路 | 説明 |
| --- | --- | --- | --- |
| `RUST_MIR_DUMP_PATH=/tmp/out.mir` | OFF | JSON v0/Stage-1 | MIR printer の出力をファイルに書く (`json_v0_bridge::maybe_dump_mir` 経由) |
| `NYASH_CLI_VERBOSE=1` | OFF | Any | 詳細ログ。`maybe_dump_mir` が stdout に MIR を出す |
| `NYASH_CLI_VERBOSE=2` | OFF | Any | さらに詳細なログ（Ny compiler 経路の診断ログ含む） |
| `NYASH_VM_DUMP_MIR=1` | OFF | Any | VM 実行前の MIR を出力 |
| `NYASH_DUMP_JSON_IR=1` | OFF | Any | JSON IR をダンプ |
| `NYASH_DEBUG_STACK_OVERFLOW=1` | OFF | Any | スタックオーバーフロー時に backtrace を有効化 |

### ダンプの使い分け
- Rust AST 直通: `./target/release/hakorune --dump-mir apps/tests/minimal.hako`（env は不要、stdout のみ）
- JSON v0 経路/Stage-1: `RUST_MIR_DUMP_PATH=/tmp/out.mir NYASH_USE_STAGE1_CLI=1 STAGE1_EMIT_MIR_JSON=1 ./target/release/hakorune --dump-mir`（stdout + ファイル）

---

## Stage-1 / selfhost CLI

| 変数 | デフォルト | 適用経路 | 説明 |
| --- | --- | --- | --- |
| `NYASH_USE_STAGE1_CLI=1` | OFF | Stage-1 | Stage-1 stub 経由に切替 |
| `NYASH_STAGE1_MODE=emit-mir` | unset | Stage-1 | `emit-program` / `emit-mir` / `run` を明示 |
| `STAGE1_EMIT_PROGRAM_JSON=1` | OFF | Stage-1 | Program(JSON v0) を吐いて終了（レガシー alias） |
| `STAGE1_EMIT_MIR_JSON=1` | OFF | Stage-1 | Program(JSON v0)→MIR(JSON) を Rust 側で降ろす（レガシー alias） |
| `HAKO_STAGE1_MODE={emit-program\|emit-mir\|run}` | unset | Stage-1 | .hako / Stage-1 ルート専用のモード指定（`--hako-*` が設定） |
| `HAKO_EMIT_PROGRAM_JSON=1` | OFF | Stage-1 | `.hako` stub に Program(JSON v0) emit を指示 |
| `HAKO_EMIT_MIR_JSON=1` | OFF | Stage-1 | `.hako` stub に MIR(JSON) emit を指示（json_v0_bridge 経由） |
| `NYASH_STAGE1_INPUT=path` | unset | Stage-1 | 入力ソース（alias: `STAGE1_SOURCE`, `STAGE1_INPUT`） |
| `HAKO_STAGE1_INPUT=path` | unset | Stage-1 | `.hako` stub 用の入力ソース（`--hako-*` が設定） |
| `NYASH_STAGE1_PROGRAM_JSON=path` | unset | Stage-1 | Program(JSON v0) のパス（alias: `STAGE1_PROGRAM_JSON`） |
| `HAKO_STAGE1_PROGRAM_JSON=path` | unset | Stage-1 | `.hako` stub 用 Program(JSON v0) パス |
| `NYASH_STAGE1_BACKEND=vm` | `vm` | Stage-1 | Stage-1 実行の backend ヒント（alias: `STAGE1_BACKEND`） |
| `NYASH_STAGE1_CLI_CHILD=1` | OFF | Stage-1 | 再帰呼び出しガード |
| `STAGE1_CLI_ENTRY=...` | `lang/src/runner/stage1_cli.hako` | Stage-1 | Stage-1 stub のエントリ差し替え |
| `STAGE1_*` alias | legacy | Stage-1 | `NYASH_STAGE1_*` の旧名。互換のため受理するが順次廃止予定 |

### Stage-1 経路の例
```bash
# Stage-1 で MIR(JSON) を受け取り、Rust 側で dump
RUST_MIR_DUMP_PATH=/tmp/out.mir \
NYASH_USE_STAGE1_CLI=1 STAGE1_EMIT_MIR_JSON=1 \
  ./target/release/hakorune --dump-mir apps/tests/minimal.hako

# hako- 前置で Stage-1 stub 経由
./target/release/hakorune --hako-emit-program-json /tmp/out.json apps/tests/minimal.hako
./target/release/hakorune --hako-emit-mir-json /tmp/out.mir apps/tests/minimal.hako --dump-mir
```

---

## Parser / using

| 変数 | デフォルト | 適用経路 | 説明 |
| --- | --- | --- | --- |
| `NYASH_PARSER_STAGE3=1` | OFF | Any | Stage-3 構文を許可 |
| `HAKO_PARSER_STAGE3=1` | OFF | Any | `.hako` 向け Stage-3 alias |
| `NYASH_ENABLE_USING=1` | ON | Any | using 文を有効化 |
| `HAKO_ENABLE_USING=1` | ON | Any | using 文 alias (.hako) |
| `NYASH_RESOLVE_TRACE=1` | OFF | Any | using/prelude 解決のトレース |
| `NYASH_VM_DUMP_MERGED_HAKO=1` | OFF | Rust AST | using/prelude マージ後の Hako ソースをダンプ |

---

## Runner / backend 選択

| 変数 | デフォルト | 適用経路 | 説明 |
| --- | --- | --- | --- |
| `NYASH_VM_USE_PY=1` | OFF | Any | PyVM を優先実行 |
| `NYASH_PIPE_USE_PYVM=1` | OFF | JSON v0/Stage-1 | pipe 実行を PyVM に直送 |
| `NYASH_VM_PLUGIN_STRICT=1` | OFF | Any | 必須プラグイン欠如で fail-fast |
| `NYASH_FAIL_FAST=0` | ON | Any | フォールバックを許容（既定は拒否） |

---

## Selfhost compiler / Ny compiler

| 変数 | デフォルト | 適用経路 | 説明 |
| --- | --- | --- | --- |
| `NYASH_USE_NY_COMPILER=1` | OFF | JSON v0 | Ny selfhost コンパイラを使用 |
| `NYASH_NY_COMPILER_STAGE3=1` | OFF | JSON v0 | Ny コンパイラ子プロセスで Stage-3 surface を許可 |
| `NYASH_NY_COMPILER_TIMEOUT_MS=2000` | `2000` | JSON v0 | selfhost 子プロセスのタイムアウト (ms) |
| `NYASH_NY_COMPILER_EMIT_ONLY=1` | ON | JSON v0 | selfhost コンパイラを emit-only で動かす |
| `NYASH_NY_COMPILER_CHILD_ARGS="-- --min-json"` | unset | JSON v0 | 子プロセスへ透過する追加引数 |

### Ny compiler 経路の観測テンプレート (Phase 29)

```bash
# Ny compiler 経路で Program(JSON v0)→MIR→dump を観測
NYASH_USE_NY_COMPILER=1 \
NYASH_PARSER_STAGE3=1 HAKO_PARSER_STAGE3=1 \
RUST_MIR_DUMP_PATH=/tmp/ny_selfhost_minimal.mir \
NYASH_CLI_VERBOSE=2 \
./target/release/hakorune --dump-mir apps/tests/minimal_ssa_skip_ws.hako \
  2>/tmp/ny_selfhost_minimal.log
```

確認項目:
- `/tmp/ny_selfhost_minimal.log` に以下の診断ログが出ているか:
  - `[selfhost/ny] spawning Ny compiler child process: ...`
  - `[selfhost/ny] received Program(JSON v0), size=... bytes`
  - `[selfhost/ny] lowering Program(JSON v0) → MIR via json_v0_bridge`
  - `[selfhost/ny] calling maybe_dump_mir (RUST_MIR_DUMP_PATH=..., cli_verbose=...)`
  - `[selfhost/ny] ✅ MIR dump file created` または `⚠️ MIR dump file NOT created`

注意: Ny selfhost compiler のエントリは現在 `lang/src/compiler/entry/compiler.hako` に統一されているよ。このファイルが存在しない場合、preferred child process 経路は発火しない。

---

## GC / Runtime

| 変数 | デフォルト | 適用経路 | 説明 |
| --- | --- | --- | --- |
| `NYASH_GC_MODE={auto|rc+cycle|minorgen|stw|rc|off}` | `rc+cycle` | Any | GC モード選択 |
| `NYASH_GC_TRACE=1` | OFF | Any | GC トレース出力 (0-3) |
| `NYASH_GC_METRICS=1` | OFF | Any | GC メトリクス (text) |
| `NYASH_GC_METRICS_JSON=1` | OFF | Any | GC メトリクス (JSON) |
| `NYASH_VM_TRACE=1` | OFF | Any | VM 実行トレース |

---

## プラグイン / Box

| 変数 | デフォルト | 適用経路 | 説明 |
| --- | --- | --- | --- |
| `NYASH_DISABLE_PLUGINS=1` | OFF | Any | プラグイン無効化 |
| `NYASH_BOX_FACTORY_POLICY={builtin_first|plugin_first}` | `builtin_first` | Any | Box factory の優先順位 |
| `NYASH_FILEBOX_MODE={auto|plugin|builtin}` | `auto` | Any | FileBox 実装選択 |

---

## JoinIR 実験 (Phase 27+)

JoinIR は制御構造を関数呼び出し + 継続に正規化する IR 層（実験中）。

| 変数 | デフォルト | 適用経路 | 説明 |
| --- | --- | --- | --- |
| `NYASH_JOINIR_EXPERIMENT=1` | OFF | Any | JoinIR 実験モード メイントグル |
| `NYASH_JOINIR_HEADER_EXP=1` | OFF | Any | Header PHI bypass 有効化（dev-only） |
| `NYASH_JOINIR_EXIT_EXP=1` | OFF | Any | Exit PHI 実験（dev-only） |
| `NYASH_JOINIR_LOWER_FROM_MIR=1` | OFF | Any | MIRベース lowering 有効化（dev-only） |
| `NYASH_JOINIR_LOWER_GENERIC=1` | OFF | Any | 構造ベースのみで Case-A 判定（関数名フィルタを外す） |
| `NYASH_JOINIR_VM_BRIDGE=1` | OFF | Any | VM bridge 経路（Route B）を有効化 |
| `NYASH_JOINIR_LLVM_EXPERIMENT=1` | OFF | llvm-harness | LLVM 経路で JoinIR を試す（L-4.3a） |

### JoinIR 各変数の詳細

**`NYASH_JOINIR_EXPERIMENT`**
- 対象: skip / trim / Stage-1 UsingResolver / Stage-B BodyExtractor / Stage-B FuncScanner
- 役割: JoinIR runner / JoinIR VM bridge / 各種テストを有効化する dev トグル

**`NYASH_JOINIR_VM_BRIDGE`**
- 対象: 上記と同じ
- 役割: VM モードで Route B（MIR→JoinIR→MIR→VM）を試す経路を有効化
- 重要: **実際に「JoinIR→VM 実行」まで行くのは Phase 32 時点では skip / trim に限定**。Stage-1 / Stage-B は lowering + Bridge の健全性確認まで（実行は VM Route A）

**`NYASH_JOINIR_LOWER_GENERIC`** (Phase 32 L-1.2)
- 既定 OFF: minimal 4 本（skip_ws / trim / append_defs / Stage-1 minimal）のみ LoopToJoinLowerer 対象
- ON: LoopRegion / LoopControlShape / LoopScopeShape の構造条件を満たすループ全般を Case-A 候補として扱う
- 注意: Phase 32 では Stage-B / Stage-1 本線については「構造テスト・JoinIR 構造観測」用途で使うトグルであり、「意味論の本番切り替え」ではない

**`NYASH_JOINIR_LLVM_EXPERIMENT`** (Phase 32 L-4.3a)
- 前提: `NYASH_JOINIR_EXPERIMENT=1` と `NYASH_LLVM_USE_HARNESS=1` が必要
- 役割: LLVM 経路（llvmlite ハーネス）で JoinIR を経由して PHI 問題を回避する実験
- 動作: `Main.skip/1` を JoinIR 経由で MIR' に変換し、元の PHI 問題のある関数を置換
- 検証: Route A (MIR→LLVM) の PHI エラーが Route B (MIR→JoinIR→MIR'→LLVM) で解消されることを実証済み

### JoinIR 使用例

```bash
# JoinIR 実験モード有効化（基本）
NYASH_JOINIR_EXPERIMENT=1 ./target/release/hakorune program.hako

# Header PHI bypass 併用
NYASH_JOINIR_EXPERIMENT=1 NYASH_JOINIR_HEADER_EXP=1 ./target/release/hakorune program.hako

# Stage-B JoinIR lowering を観測したい場合（Phase 32 開発用）
# → JoinIR lowering + JoinIR→MIR Bridge が走り、ログで JoinIR 構造が確認できる
# → 実際の実行は VM Route A にフォールバック
NYASH_JOINIR_EXPERIMENT=1 \
NYASH_JOINIR_VM_BRIDGE=1 \
NYASH_JOINIR_LOWER_GENERIC=1 \
  ./target/release/hakorune --dump-mir apps/tests/stageb_case.hako

# LLVM 経路で JoinIR を使う（L-4.3a）
# Route A (MIR→LLVM) の PHI エラーが Route B (MIR→JoinIR→MIR'→LLVM) で解消される
env NYASH_PARSER_STAGE3=1 HAKO_PARSER_STAGE3=1 \
    NYASH_DISABLE_PLUGINS=1 NYASH_LLVM_USE_HARNESS=1 \
    NYASH_JOINIR_EXPERIMENT=1 NYASH_JOINIR_LLVM_EXPERIMENT=1 \
    ./target/release/hakorune --backend llvm apps/tests/minimal_ssa_skip_ws.hako
```

詳細: [ENV_INVENTORY.md](../private/roadmap2/phases/phase-29-longterm-joinir-full/ENV_INVENTORY.md) / [Phase 32 README](../private/roadmap2/phases/phase-32-joinir-complete-migration/README.md)

---

## MIR 検証系（代表）

| 変数 | デフォルト | 適用経路 | 説明 |
| --- | --- | --- | --- |
| `NYASH_VERIFY_ALLOW_NO_PHI=1` | OFF | Any | PHI 検証をスキップ |
| `NYASH_VERIFY_EDGE_COPY_STRICT=1` | OFF | Any | Edge copy 検証を厳格化 |
| `NYASH_VERIFY_RET_PURITY=1` | OFF | Any | return ブロックの純粋性検証 |
| `NYASH_ME_CALL_ARITY_STRICT=1` | OFF | Any | me.method の arity 不一致でエラー |

---

参考: [docs/development/architecture/mir-logs-observability.md](../development/architecture/mir-logs-observability.md) / [src/mir/verification/](../../src/mir/verification/)