hakorune/docs/development/architecture/loops/loopform_ssot.md

LoopForm SSOT（単一起点）設計ノート

目的

• ループのPHI整形・前処理（preheader Copy、header PHI seed、latch/continue 合流）を単一モジュールに集約してドリフトを防ぐ。
• ビルダー（Direct MIR）とブリッジ（JSON v0 → MIR）の双方で同一の規約と検証を通す。

SSOT（Single Source of Truth）

• 中心: src/mir/phi_core/loop_phi.rs
  • 型: IncompletePhi, VarSnapshot
  • API: prepare_loop_variables_with, seal_incomplete_phis_with, build_exit_phis_with
  • デバッグ: phi_core::common::debug_verify_phi_inputs（到達検証・重複検出）
• Direct MIR（既にSSOT使用）
  • src/mir/loop_builder.rs が LoopPhiOps を実装し、prepare/seal/exit を phi_core へ委譲。
  • 形状: preheader → header(φ) → body → latch → header|exit（LoopForm準拠）。
• JSON v0 Bridge（段階移行→完了済みの範囲）
  • header PHI（seed/完成）・exit PHI を LoopPhiOps アダプタ経由で SSOT API に委譲。
  • break/continue スナップショットは thread‑local stack で収集し、seal/build_exit に渡す。
  • 代表 parity カナリア（opt‑in）で Direct と Bridge の一致を検証。

規約（不変条件）

• header の PHI 入力は「preheader 経由の定義済み値」と「latch/continue からの値」だけ。
• preheader で Copy を先行挿入し、PHI 入力は Copy の出力を参照する（Use-Before-Def回避）。
• 1 predecessor なら直接 bind（PHI省略）、2つ以上で PHI を生成。
• 検証は Fail‑Fast ではなく開発時 WARN（debug_assert）だが、将来 Core 側で整形に移管予定。

今後の移行

• Bridge 側に LoopPhiOps 実装を追加し、prepare/seal/exit を直接呼ぶ。
• ループ形状の生成をユーティリティ化（builder/bridge 双方から共通呼び出し）。

関連

• src/mir/loop_builder.rs
• src/runner/json_v0_bridge/lowering/loop_.rs
• src/mir/phi_core/common.rs