hakorune/CURRENT_TASK.md

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 を配置」へ修正予定。