# Current Task — Phase 15 Snapshot (2025-09-18)

## Snapshot / Policy
- Execution policy: PHI-off (edge-copy) by default. MIR builders/bridge do not emit PHIs; LLVM (llvmlite harness) synthesizes PHIs. PHI-on is dev-only and gated by feature `phi-legacy`.
- Semantic reference: PyVM. AOT/EXE-first via llvmlite harness + `ny-llvmc`.
- Harness-first run path: `--backend llvm` uses llvmlite harness (when `NYASH_LLVM_USE_HARNESS=1`) to emit an EXE and run it, returning the program exit code.

Env toggles (current)
- `NYASH_MIR_NO_PHI` (default=1): PHI-off.
- `NYASH_VERIFY_EDGE_COPY_STRICT=1`: Enable strict edge-copy verifier in PHI-off.
- `NYASH_LLVM_USE_HARNESS=1`: Use llvmlite harness path.
- `NYASH_LLVM_PREPASS_IFMERGE=1`: Enable if-merge prepass for ret-merge convenience (harness).
- `NYASH_LLVM_TRACE_PHI=1` + `NYASH_LLVM_TRACE_OUT=<file>`: Emit PHI wiring JSONL trace.
- `phi-legacy` feature + `NYASH_MIR_NO_PHI=0`: Dev-only PHI-on (legacy/testing).

Planned (parser Stage‑3 gate):
- `NYASH_PARSER_STAGE3=1` to accept try/catch/throw/cleanup syntax in the core parser (postfix catch/cleanup included).

## Completed (highlights)
- Loop/If builder hygiene
  - Continue/Break commonized (`jump_with_pred`, `do_{break,continue}`) in MIR LoopBuilder and JSON bridge.
- PHI-off correctness tooling
  - Strict verifier (PHI-off): checks per-pred `Copy` coverage and forbids merge self-copy (`NYASH_VERIFY_EDGE_COPY_STRICT=1`).
  - LLVM PHI trace (JSONL): unified structured events from harness (`finalize_*`, `add_incoming`, `wire_choose`, `snapshot`).
  - Trace checker: `tools/phi_trace_check.py` (diffs on mismatch, `--summary`/`--strict-zero`).
- Harness-first runner
  - `--backend llvm` + `NYASH_LLVM_USE_HARNESS=1`: emit EXE via `ny-llvmc` and run (returns exit code).
- One-shot + smokes
  - `tools/phi_trace_run.sh`: build → run → trace → check in one shot (multi-app; `--strict-zero`).
  - `tools/test/smoke/llvm/phi_trace/test.sh`: curated cases (loop_if_phi / ternary_nested / phi_mix / heavy_mix).
  - Difficult mixes added: `apps/tests/llvm_phi_mix.nyash`, `apps/tests/llvm_phi_heavy_mix.nyash` (Box生成 + continue/break/early return)。
- Docs
  - PHI policy: `docs/reference/mir/phi_policy.md`（PHI‑off恒久・PHI‑on保守限定）。
  - Lowering contexts guide: `docs/design/LOWERING_CONTEXTS.md`（If/Loop スナップショット規約）。
  - PHI-off トラブルシュート: `docs/guides/phi-off-troubleshooting.md`。
  - Testing guide updated with trace usage.
  - Stage‑3 Exceptions (MVP): `docs/guides/exceptions-stage3.md`（単一catch＋Resultモード＋ThrowCtx の方針）。
- Stage‑3 parser gate（Phase A 完了）
  - Rust parser が `NYASH_PARSER_STAGE3=1` で try/catch/cleanup/throw を受理（`(Type x)|(x)|()` の各形式）。
  - parser tests/EBNF/doc を更新。
- Bridge Result‑mode（Phase B/C の実装基盤）
  - `NYASH_TRY_RESULT_MODE=1` で try/catch/cleanup を MIR Throw/Catch なしに構造化lower（単一catchポリシー）。
  - ThrowCtx（thread‑local）で try 降下中の任意スコープの throw を現在の catch に集約（ネスト throw 対応）。
  - 合流は PHI‑off 規約（edge‑copy）。Bridge 出力に PHI が混ざった場合は `strip_phi_functions` で正規化（後段ハーネスは PHI 合成）。
  - Bridge スモーク追加: `tools/test/smoke/bridge/try_result_mode.sh`（JSON v0 → Bridge → PyVM/VM。代表ケース緑）。

## Tools & Scripts (quick)
- One-shot: `bash tools/phi_trace_run.sh apps/tests/llvm_phi_heavy_mix.nyash --strict-zero`
- PHI trace smoke (optional): `bash tools/test/smoke/llvm/phi_trace/test.sh`
- Fast smokes (opt-in trace): `NYASH_LLVM_TRACE_SMOKE=1 bash tools/smokes/fast_local.sh`
- Bridge (Result‑mode) smokes: `bash tools/test/smoke/bridge/try_result_mode.sh`
- Bridge→harness PHI trace (WIP): `bash tools/phi_trace_bridge_try.sh tests/json_v0_stage3/try_nested_if.json`

## Next — Stage‑3 Try/Catch/Throw (cleanup unified; parser→lowering, incremental)

Phase A — Parser acceptance (no behavior change)
- Goal: Accept Stage‑3 syntax in the Rust parser behind a gate.
- Scope:
- Parse `try { … } catch [(Type x)|(x)|()] { … } [cleanup { … }]` and `throw <expr>`.
  - Build existing AST forms: `ASTNode::TryCatch`, `CatchClause`, `ASTNode::Throw`.
  - Gate via env (planned): `NYASH_PARSER_STAGE3=1`（既定OFF）。
Status: DONE (cleanup unified; finally removed)
- Deliverables:
  - Parser unit tests: 正常（各バリアント）/構文エラー（不完全・重複cleanup等）。
  - EBNF/doc 更新（最小仕様、複数catchは将来）。

Phase B — Safe lowering path (no exceptions thrown)
- Goal: Allow “no-throw path” lowering to MIR/JSON so existing runners remain green.
- Scope:
  - Lower try/catch when try-body doesn’t throw; catch block is structurally present but not executed.
  - JSON v0 bridgeとASTの形状整合を確認（既存 `lowering/try_catch.rs` を安全適用）。
- Deliverables:
  - Minimal smoke: try/catch where try 内で例外なし（正常合流/ret の健全性）。

Status note (Result‑mode MVP)
- `NYASH_TRY_RESULT_MODE=1`: try/catch/cleanup を構造化lower（MIR Throw/Catch 不使用）。
- 単一catchポリシー＋ThrowCtx でネスト throw を含む try 範囲の throw を集約（catch パラメータは preds→値の束ねで受理）。
- 合流は PHI‑off（edge‑copy）。Bridge 出力時に PHI が残った場合は正規化して除去。

Phase C — Minimal throw/catch path
- Goal: Enable one end-to-end throw→catch→cleanup path for simple cases.
- Scope:
  - `throw "message"` → 単一 catch で受理（型は文字列ラベル相当の最小仕様）。
- cleanup は “常に実行” の構造のみ（副作用最小）。
  - PHI-off 合流は edge-copy 規約を維持（phi-trace で preds→dst 網羅を確認）。
- Deliverables:
  - 代表スモーク（print/return 系）
  - phi-trace を用いた整合チェック
Implementation track (current)
- Use `NYASH_TRY_RESULT_MODE=1` and single‑catch policy（catch 内分岐）。
- ThrowCtx によりネスト throw を集約。catch パラメータは preds→値の束ねで受理（PHI‑offはedge‑copy）。
- LLVM harness: PHI 責務を finalize_phis に一任。ret.py を簡素化（Return のみ）。if‑merge 事前宣言の安全化、uses 向け predeclare を追加。
- 結果: try/cleanup 基本・print・throw(デッド)・cleanup return override(許可) は harness 緑。
- 残: method 後置 cleanup + return(許可) は PHI 先頭化の徹底が必要（resolver の未宣言 multi‑pred PHI 合成を完全停止→predeclare 必須化）。

---

## Phase 15.5 — Block‑Postfix Catch（try を無くす設計）

Design (MVP)
- Syntax（後置）:
- `{ body } catch (e) { handler } [cleanup { … }]`
- `{ body } cleanup { … }`（catch 省略可）
- Policy:
  - 単一 catch（分岐は catch 内で行う）。パラメータ形式は `(Type x)|(x)|()` を許容。
  - 作用域は “同じ階層” のブロックに限定。ブロック内の `throw` は直後の catch にのみ到達（外に伝播しない）。
  - MVP 静的検査: 直後に catch のない独立ブロック内で「直接の `throw` 文」を禁止（ビルドエラー）。関数呼び出し由来の throw は当面ノーチェック。
  - 適用対象: 独立ブロック文に限定（if/else/loop の構文ブロック直後は不可）。必要なら独立ブロックで包む。

Gates / Flags
- Parser gate（提案）: `NYASH_BLOCK_CATCH=1`（受理ON）。初期は Stage‑3 と同一ゲートでも可（`NYASH_PARSER_STAGE3=1`）。
- Bridge: 既存 `NYASH_TRY_RESULT_MODE=1`（構造化lower／MIR Throw/Catch不使用）。

Lowering（実装方針）
- Parser で後置 catch/cleanup を既存 `ASTNode::TryCatch` に畳み込む（try_body=直前ブロック）。
- Bridge は既存 Result‑mode/ThrowCtx/単一catch・PHI‑off（edge‑copy）をそのまま利用（コード変更最小）。

Tasks（順番） — Progress
1) Parser acceptance（ゲート付き） — DONE（cleanup 統一）
- 後置 catch/cleanup を受理 → `ASTNode::TryCatch` に組み立て。
   - 限定: 独立ブロック文のみ。トップレベルの `catch`/`finally` 先頭は専用エラーで誘導（if/else/loop 直後では使わず、独立ブロックで包む）。
  - Unit tests: `(Type x)/(x)/()`＋cleanup、ネガティブ（直後に catch 無しで直接 throw など）。
2) Static checks（MVP） — DONE
   - 独立ブロック内 “直接の throw 文” に後置 catch が無ければビルドエラー。
   - 将来拡張: 関数に最小 throws 効果ビットを導入し、静的安全性を高める（未着手）。
3) Bridge / Lowering（確認のみ） — DONE
   - 既存 Result‑mode の try/catch/finally 経路で正常動作（ThrowCtx によるネスト throw 集約、PHI‑off 合流）。
   - Bridge スモーク（JSON v0→PyVM）を拡充。統合ハードケース追加（後述）。
4) Docs & EBNF 更新 — DONE
- 例外ガイドを後置 catch 中心に再編。EBNF に `block_catch := '{' stmt* '}' ('catch' '(' … ')' block)? ('cleanup' block)?` を追加し、ゲートも明記。
5) Harness PHI trace（継続） — WIP
   - finalize_phis の PHI 配置を「常にブロック先頭」へ修正し、Bridge→harness の後置構文ケースを緑に。

Migration / Compatibility
- 旧 `try { … } catch { … }` は当面受理（非推奨）。段階導入後に後置 catch を推奨デフォルトへ。
- 将来: フォーマッタ/自動変換の提供を検討。

Risks / Notes（Phase 15.5）
- 直後 catch 不在での throw を静的に完全検出するには “効果型” が必要。MVP は「直接の throw 文のみチェック」で開始。
- 構文の曖昧さ（if/else/loop ブロック直後）は独立ブロックに限定する規則で回避。

Out of scope（初期）
- 複数 catch/型階層、例外伝播/ネストの深い制御、最適化。

---

## Phase 15.6 — Method‑Level Postfix Catch/Finally（メソッド境界の安全化）

Design (MVP)
- Syntax（後置 at method end）:
- `method name(params) { body } [catch (e) { handler }] [cleanup { … }]`
- Policy:
  - 単一 catch、順序は `catch` → `finally` のみ許可。
  - 近接優先: ブロック後置の catch があればそれが優先。次にメソッドレベル、最後に呼出し側。
- Gates / Flags
  - `NYASH_METHOD_CATCH=1`（または `NYASH_PARSER_STAGE3=1` と同梱）

Plan（段階）
1) Parser acceptance（ゲート付き）
   - 既存メソッド定義の末尾に `catch/finally` を受理 → `TryCatch` に正規化（body を try_body に束ねる）。
   - Unit tests: 正常/順序違反/複数catchエラー/末尾finallyのみ。
2) Lowering（確認のみ）
   - 既存 Result‑mode/ThrowCtx/PHI‑off 降下を再利用（変更なし）。
3) Docs & EBNF 更新（本チケットで一部済）
   - 仕様・ガイドを method‑level 追記、使用例と制約を明記。

Future (Phase 16.x)
- ブロック先行・メソッド後置 `{ body } method name(..) [catch..] [finally..]` に拡張（先読み/二段パース）。

Handoff (2025‑09‑18)
- Status
  - Parser: DONE（ゲート `NYASH_METHOD_CATCH=1` または `NYASH_PARSER_STAGE3=1`）。
  - AST: FunctionDeclaration.body は TryCatch に正規化（単一catch、順序=catch→cleanup）。
  - Docs/EBNF: 更新済。
  - Unit tests: パーサ単体（cleanup‑only）追加済。
  - E2E: PENDING（VM/MIR 経路）。現状 `static box Main { main() { … } finally { … } }` で MIR ビルダが duplicate terminator panic。
- Repro (E2E panic)
  - `NYASH_METHOD_CATCH=1 NYASH_PARSER_STAGE3=1 ./target/release/nyash --backend vm apps/tests/method_postfix_finally_only.nyash`
  - Panic: `Basic block bb* already has a terminator`（src/mir/basic_block.rs:94）。
- Next
  1) MIR builder: Try/Cleanup の終端整理（return は cleanup 実行後に有効化；二重 terminator 抑止）。
  2) E2E samples: method_postfix_finally_only（期待 42）/ method_postfix_catch_basic（構造確認）。
  3) 追加テスト: 複数 catch エラー/順序違反/近接優先の確認。
  4) Optional: TRM（JSON v0 Bridge）経由へのルート（暫定の回避パスとして）検討。

## How to Run / Verify (current)
- Harness-first run（EXE ファースト）
  - `NYASH_LLVM_USE_HARNESS=1 ./target/release/nyash --backend llvm apps/tests/loop_if_phi.nyash`
- PHI trace（one-shot）
  - `bash tools/phi_trace_run.sh apps/tests/llvm_phi_heavy_mix.nyash --strict-zero`
- Strict verifier（PHI-off）
  - `NYASH_VERIFY_EDGE_COPY_STRICT=1 cargo test --lib`
- Bridge(Result‑mode) — JSON v0 → Bridge → PyVM/VM
  - `bash tools/test/smoke/bridge/try_result_mode.sh`
  - 直接: `NYASH_TRY_RESULT_MODE=1 NYASH_PIPE_USE_PYVM=1 ./target/release/nyash --ny-parser-pipe --backend vm < tests/json_v0_stage3/try_basic.json`
  - 統合ケース（複合）: `tests/json_v0_stage3/try_unified_hard.json`（期待 exit=40）
- Bridge→Harness PHI trace（WIP）
  - `bash tools/phi_trace_bridge_try.sh tests/json_v0_stage3/try_nested_if.json`

## Risks / Notes
- PHI-off と LLVM 合成の一貫性は phi-trace/strict で監視。開発時にズレが出たら JSONL と diff 出力で即座に特定可能。
- Harness 実行に Python/llvmlite が必要。`ny-llvmc` は `cargo build -p nyash-llvm-compiler --release` で用意。
- 現在の課題: llvmlite ハーネス側の PHI 配置順序（"PHI nodes not grouped at top"）により Bridge→harness の一部ケースで失敗。Bridge 側は PHI‑off 正規化済み。ハーネスの `finalize_phis` を「常にブロック先頭に PHI を配置」へ修正予定。