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**: In progress (Phase 2 done: selection / Phase 3: lowering)
**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 が未実装（stub）な状態。

- 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 stub: `src/mir/builder/control_flow/joinir/patterns/pattern6_nested_minimal.rs`
  - 現在は `Err("[Pattern6] ... not yet implemented")` で Fail-Fast

この README のゴールは、stub を “実装済み” にして fixture を通すこと。

---

## 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` に含めて除外する（詳細は指示書）。

---

## 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 が使われたことをログ/タグで確認可能）

---

## 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 で設計してから実装

---

## Out of Scope

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