Phase 30.1 & 73: Stage-3 features env and JoinIR flag cleanup

2025-11-30 14:30:28 +09:00
parent 2ea0f2a202
commit a3d5bacc55
163 changed files with 638 additions and 576 deletions
--- a/docs/reference/environment-variables.md
+++ b/docs/reference/environment-variables.md
@ -63,8 +63,9 @@ NYASH_USE_STAGE1_CLI=1 STAGE1_EMIT_MIR_JSON=1 \

 | 変数 | デフォルト | 適用経路 | 説明 |
 | --- | --- | --- | --- |
-| `NYASH_PARSER_STAGE3=1` | OFF | Any | Stage-3 構文を許可 |
-| `HAKO_PARSER_STAGE3=1` | OFF | Any | `.hako` 向け Stage-3 alias |
+| `NYASH_FEATURES=stage3` | `stage3` (implicit) | Any | カンマ区切りの機能フラグ。`stage3` で Stage-3 構文を許可（既定ON）。 |
+| `NYASH_PARSER_STAGE3=1` | legacy | Any | Stage-3 旧エイリアス。将来削除予定。OFF にしたい場合のみ指定。 |
+| `HAKO_PARSER_STAGE3=1` | legacy | Any | `.hako` 向け Stage-3 legacy 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 解決のトレース |
@ -98,7 +99,7 @@ NYASH_USE_STAGE1_CLI=1 STAGE1_EMIT_MIR_JSON=1 \
 ```bash
 # Ny compiler 経路で Program(JSON v0)→MIR→dump を観測
 NYASH_USE_NY_COMPILER=1 \
-NYASH_PARSER_STAGE3=1 HAKO_PARSER_STAGE3=1 \
+NYASH_FEATURES=stage3 \
 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 \
@ -139,68 +140,64 @@ NYASH_CLI_VERBOSE=2 \

 ---

-## JoinIR 実験 (Phase 27+)
+## JoinIR トグル (Phase 72 整理版)

-JoinIR は制御構造を関数呼び出し + 継続に正規化する IR 層（実験中）。
+JoinIR は制御構造を関数呼び出し + 継続に正規化する IR 層。フラグは config/env のポリシーで集約するよ。

-| 変数 | デフォルト | 適用経路 | 説明 |
-| --- | --- | --- | --- |
-| `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_core_enabled()` … `NYASH_JOINIR_CORE` が優先。未設定時は `NYASH_JOINIR_EXPERIMENT` や IfSelect/VM bridge/LLVM 実験の明示設定で自動 ON。
+- `joinir_dev_enabled()` … `NYASH_JOINIR_DEV=1` または JoinIR debug level > 0 で ON（開発者向け束ねスイッチ）。

-### JoinIR 各変数の詳細
+### Core（本線化対象）

-**`NYASH_JOINIR_EXPERIMENT`**
- 対象: skip / trim / Stage-1 UsingResolver / Stage-B BodyExtractor / Stage-B FuncScanner
- 役割: JoinIR runner / JoinIR VM bridge / 各種テストを有効化する dev トグル
+| 変数 | デフォルト | 説明 |
+| --- | --- | --- |
+| `NYASH_JOINIR_CORE` | unset | Core トグルの明示 ON/OFF（未設定時は下記を見て自動判定） |
+| `NYASH_JOINIR_EXPERIMENT` | OFF | JoinIR 実験メイントグル（Core 判定に含まれる） |
+| `HAKO_JOINIR_IF_SELECT` | OFF | IfSelect/IfMerge JoinIR 経路。エイリアス `NYASH_JOINIR_IF_SELECT` は Deprecated。 |
+| `HAKO_JOINIR_IF_IN_LOOP_ENABLE` | OFF | if-in-loop JoinIR 本線切替（Core 候補）。 |
+| `NYASH_JOINIR_VM_BRIDGE` | OFF | VM bridge Route B。Core 判定に含まれる。 |
+| `NYASH_JOINIR_LLVM_EXPERIMENT` | OFF | LLVM 経路 JoinIR 実験（ハーネス専用）。Core 判定に含まれる。 |

-**`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）
+### DevOnly（開発/計測専用）

-**`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_DEV` | OFF | DevOnly まとめて ON。 |
+| `NYASH_JOINIR_LOWER_FROM_MIR` | OFF | MIR ベース lowering 切替。 |
+| `NYASH_JOINIR_LOWER_GENERIC` | OFF | 関数名フィルタなし generic lowering。 |
+| `NYASH_JOINIR_VM_BRIDGE_DEBUG` | OFF | VM bridge 追加ログ。 |
+| `NYASH_JOINIR_MAINLINE_DEBUG` | OFF | Mainline 追加ログ。 |
+| `HAKO_JOINIR_IF_IN_LOOP_DRYRUN` | OFF | if-in-loop dry-run。 |
+| `HAKO_JOINIR_IF_TOPLEVEL` / `_DRYRUN` | OFF | ループ外 if JoinIR 経路 / dry-run。 |
+| `HAKO_JOINIR_STAGE1` | OFF | Stage‑1 JoinIR 経路。 |
+| `HAKO_JOINIR_PRINT_TOKENS_MAIN` | OFF | print_tokens main A/B。 |
+| `HAKO_JOINIR_ARRAY_FILTER_MAIN` | OFF | array.filter main A/B。 |
+| `NYASH_JOINIR_DEBUG` / `HAKO_JOINIR_DEBUG` | OFF | 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) で解消されることを実証済み
+### Deprecated / 廃止候補

-### JoinIR 使用例
+| 変数 | 状態 | 説明 |
+| --- | --- | --- |
+| `HAKO_JOINIR_NESTED_IF` | Deprecated候補 | Route B nested if。 |
+| `HAKO_JOINIR_READ_QUOTED` / `_IFMERGE` | Deprecated候補 | read_quoted JoinIR 実験。 |
+
+### 使用例

 ```bash
-# JoinIR 実験モード有効化（基本）
-NYASH_JOINIR_EXPERIMENT=1 ./target/release/hakorune program.hako
+# Core JoinIR + Stage-3（推奨）
+env NYASH_FEATURES=stage3 NYASH_JOINIR_CORE=1 ./target/release/hakorune program.hako

-# Header PHI bypass 併用
-NYASH_JOINIR_EXPERIMENT=1 NYASH_JOINIR_HEADER_EXP=1 ./target/release/hakorune program.hako
+# VM bridge Route B（開発用）
+env NYASH_FEATURES=stage3 NYASH_JOINIR_EXPERIMENT=1 NYASH_JOINIR_VM_BRIDGE=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 \
+# LLVM ハーネス JoinIR 実験
+env NYASH_FEATURES=stage3 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)
+詳細: [ENV_INVENTORY.md](../private/roadmap2/phases/phase-29-longterm-joinir-full/ENV_INVENTORY.md) / [Phase 72 フラグ整理](../private/roadmap2/phases/phase-72-joinir-dev-flags/README.md)

 ---