hakorune/docs/development/current/main/phases/phase-188.3/README.md

Phase 188.3: Nested loop lowering (1-level) — make Pattern 6 real

Date: 2025-12-27 Status: Complete (Pattern6 lowering + merge/latch fix) Prereq: Phase 188.2 Option A is complete (StepTree depth SSOT + strict Fail-Fast)

---

Goal

max_loop_depth == 2（1-level nested loop）を JoinIR lowering で実際に通す。

• 既知の事実: LoopForm (=LoopShape) にはネスト情報が無いので、LoopFormベースの Pattern6 検出/ルーティングでは実装できない
• 実装は **StepTree（AST側）**を SSOT として扱う（Phase 188.2 Option A を継続）

---

Definition: max_loop_depth (SSOT)

StepTreeFeatures.max_loop_depth は「その関数（or 評価対象ブロック）の中で、最も深い loop{} ネストの深さ」を表す。

• loop が無い: 0（※StepTree実装に依存。現状の運用では “loopがある前提”で扱う）
• loop が 1 段: 1
• loop の中に loop が 1 つ: 2
• loop{ loop{ loop{ ... } } }: 3

Phase 188.2 の strict ガードは「depth > 2 を明示エラー」にしている。 これは言語仕様の制限ではなく、「JoinIR lowering の実装範囲（compiler capability）」の制限。

---

Scope (minimal)

対応するのは “NestedLoop Minimal” の 1形だけに限定する。

• depth: max_loop_depth == 2 のみ
• inner loop: Pattern1相当（break/continue 無し）
• outer loop: Pattern1相当（break/continue 無し）を優先
• それ以外:
  • strict mode: 明示エラー（Phase 188.2 の depth check とは別タグで良い）
  • non-strict mode: 既存の fallback 経路に任せる（ただし silent fallback を増やさない）

---

Current Code Status (reality)

Phase 188.3 は “選択ロジック（Pattern6選定）→ lowering → merge/rewriter 安定化” まで完了している。

• Selection SSOT: src/mir/builder/control_flow/joinir/routing.rs の choose_pattern_kind()
  • cheap check → StepTree → AST validation
  • max_loop_depth == 2 かつ “Pattern6 lowerable” のときだけ Pattern6NestedLoopMinimal を返す
• Lowering: src/mir/builder/control_flow/joinir/patterns/pattern6_nested_minimal.rs
  • JoinIR pipeline で inner_step/k_inner_exit/k_exit を含む関数群を生成して merge する
  • Fixture: apps/tests/phase1883_nested_minimal.hako（RC=9）
• Merge/Rewrite contract（SSOT）:
  • latch_incoming を記録してよいのは TailCallKind::BackEdge のみ（LoopEntry は上書き禁止）
  • entry-like は “JoinIR main の entry block のみ”
  • 二重 latch は debug_assert! で fail-fast
  • 実装: src/mir/builder/control_flow/joinir/merge/instruction_rewriter.rs, src/mir/builder/control_flow/joinir/merge/loop_header_phi_info.rs

---

SSOT (what to rely on)

• nesting depth SSOT: StepTreeFeatures.max_loop_depth
• depth > 2: strict mode で control_tree/nested_loop/depth_exceeded（Phase 188.2）

---

Scope & Variable Model (SSOT)

Nyash の変数スコープ方針に合わせて、nested loop lowering でも以下を SSOT として固定する。

Visibility (read)

• inner loop から outer の binding は参照できる（lexical scope: “1つ上は見える”）
• ただし JoinIR lowering では「見える」を 明示的な引数/継続で表現する（暗黙キャプチャを増やさない）

Mutation (write-back)

Phase 188.3 では段階的に進める：

• P188.3 (minimal): “最小の write-back” を 明示的な carrier として許す
  • inner loop が outer 変数を更新する場合、その変数は carrier として引数で受けて、k_inner_exit(...) で返す
  • 対応範囲は最小（fixtureが要求する 1 carrier 程度）に限定する
• P188.4+ (generalize): write-back を一般化（複数 carrier / 代入形 / break/continue を含む形）

この分離により、write-back の複雑さ（複数 carrier / break / continue / PHI の再接続）を Phase 188.3 に持ち込まずに済む。

---

Lowering sketch (how it should look)

Nested loop は JoinIR の「tail recursion + continuation」を再帰的に合成して表現する。

• outer: outer_step(state..., k_outer_exit)
• inner: inner_step(state..., k_inner_exit)
• inner が終わったら k_inner_exit(...) で outer の“残り”へ戻る

この k_inner_exit がスコープ境界として働くので、将来の write-back もここに集約できる。

Minimal function graph (recommended)

Phase 188.3 の最小形は「outer の loop_step の中で inner の loop_step を呼び、inner が終わったら k_inner_exit で outer に戻る」。

推奨の JoinIR 関数群（概念）:

• main(i0, sum0):
  • Call(loop_step, [i0, sum0])
  • Ret 0（statement-position loop の場合）
• loop_step(i, sum)（outer の step。canonical name は loop_step に寄せる）:
  • exit_cond = !(i < N_outer)
  • Jump(k_exit, [sum], cond=exit_cond)
  • Call(inner_step, [j0, i, sum])
• inner_step(j, i_outer, sum):
  • exit_cond = !(j < N_inner)
  • Jump(k_inner_exit, [i_outer, sum], cond=exit_cond)
  • sum_next = sum + 1（fixture の最小形）
  • j_next = j + 1
  • Call(inner_step, [j_next, i_outer, sum_next])
• k_inner_exit(i, sum):
  • i_next = i + 1
  • Call(loop_step, [i_next, sum])
• k_exit(sum)（canonical name k_exit）:
  • Ret sum

重要:

• carrier はグローバル扱いしない。sum は引数で運んで戻す。
• merge 側の “loop_step 関数の選定” を壊さないため、inner_step と k_inner_exit は boundary の continuation_func_ids に含めて除外する（詳細は指示書）。

---

Merge/Rewrite contract (SSOT) — “undef ValueId” を防ぐ

JoinIR merge は「JoinIR の param ValueId は SSA 命令で定義されない」前提なので、適切な Copy（param binding） が入らないと即 use of undefined value ValueId(...) になる。

特に Pattern6 では loop_step（outer）から inner_step へ tail-call するため、以下を SSOT として固定する：

• Skip するのは “target が loop header” のときだけ
  • header では PHI dst が carrier の SSOT なので、param Copy を入れて上書きしてはいけない
  • 一方で loop_step → inner_step は “target が header ではない” ため、inner_step params を定義する Copy が必要
• param の index ベース remap は危険
  • inner_step(j, i, sum) のように、先頭に loop-local（j）が混ざると carrier の index と一致しない
  • index remap は j を i の PHI dst に誤接続しやすい

この契約に反する場合の典型症状：

• Function 'inner_step' params: [ValueId(104), ...] の直後に use of undefined value ValueId(104)

修正の第一候補は merge/instruction_rewriter.rs 側（tail-call param binding の skip 条件）であり、merge/mod.rs の “パラメータ再マップを拡張する” で逃げない（責務を混ぜない）。

---

Deliverables

1. Fixture + integration smoke（exit code SSOT）

   • 1-level nested loop を最小で再現する .hako を追加
   • integration で実行し、exit code で判定（stdout比較はしない）

2. StepTree-based lowering implementation

   • StepTree を辿って、inner loop を outer loop の中で正しく lowering できるようにする
   • 入口は “StepTree→JoinIR” のどこか（LoopFormベースの router は使わない）

3. Docs update

   • Phase 188.1 の “Pattern6 specification” が design であることは維持
   • Phase 188.3 で “実装済み/未実装の境界” を明確に書く

---

Acceptance Criteria

• ./tools/smokes/v2/run.sh --profile quick が常にグリーン維持
• integration selfhost が FAIL=0 を維持
• 追加した nested loop fixture が PASS（JoinIR lowering が使われたことをログ/タグで確認可能）
  • 実測: ./target/release/hakorune --backend vm apps/tests/phase1883_nested_minimal.hako → RC=9

---

Instructions (handoff)

実装者（Claude Code）向けの手順書は docs/development/current/main/phases/phase-188.3/P1-INSTRUCTIONS.md を参照。

---

Next (schedule)

• Phase 188.3: depth=2 の最小形を “確実に通す” + PoC fixture を smoke 固定
• Phase 188.4+: write-back（outer carrier reconnection）と “再帰 lowering の一般化（depthを増やしても壊れない）” を docs-first で設計してから実装

Post-completion (refactoring window)

実装完了後のリファクタ（意味論不変）を挟む場合は、P2-REFACTORING-INSTRUCTIONS.md を入口にする。

Planned cleanup (after Phase 188.3)

Pattern6 を通す過程で露出しやすい “暗黙ルール” を SSOT 化して、今後の nested/generalization を楽にする：

• JoinInlineBoundary に loop header func name を明示する SSOT（merge の “entry func 推定” を段階的に減らす）
• ParamBinding の規則を “source-based ではなく target-based” に統一（header だけ特別扱い）
• （将来）param role（carrier vs local）を明文化し、index remap の誘惑を消す

---

Out of Scope

• nested loop + break/continue の一般対応
• LoopRegion を使った MIR-level nesting SSOT（Option B）