hakorune/docs/development/current/main/phases/phase-29af/P4-LAYOUT-CONSISTENCY-CONTRACT-INSTRUCTIONS.md

Phase 29af P4: Layout Consistency Contract — Instructions

Status: Ready for execution
Scope: carrier layout / header PHI の順序整合を Fail-Fast で固定（仕様不変）

Goal

Phase 29af P3 で導入した BoundaryCarrierLayout（order SSOT）と、merge が生成する header PHI 側の order がズレた場合に、 JoinIR merge の入口で fail-fast できる状態にする。

• “BTreeMapの反復順” などの偶然に依存して順序が崩れたとき、即時に検知できる
• Pattern2/6/7/phase1883 の回帰パックを壊さず、将来の refactor を安全にする

Non-goals

• 既定挙動の変更（release 既定では挙動不変）
• env var の追加
• ループ仕様の拡張（PHI/edge_args の新設など）

SSOT

• Carrier order SSOT: src/mir/builder/control_flow/joinir/merge/boundary_carrier_layout.rs
• Header PHI Entry/Latch contract: docs/development/current/main/phases/phase-29ae/README.md

Implementation Steps

Step 1: Boundary の “layout長” を実質的なチェックに強化

対象: src/mir/builder/control_flow/joinir/merge/contract_checks/boundary_hygiene.rs

carrier_info があるとき:

• boundary.loop_var_name == Some(carrier_info.loop_var_name) を要求（名前不整合を fail-fast）
• BoundaryCarrierLayout::from_boundary(boundary).ordered_names() が ["loop_var", ...carrier_info.carriers] と 同名同順 で一致することを要求
• boundary.join_inputs.len() == boundary.host_inputs.len() == layout.len() を要求
  • 注: host_inputs の中身（ValueId(0) placeholder）は問わない（SkipBinding があるため）

実行条件は既存と同じ（joinir_strict または joinir_dev のみ）。

Step 2: Header PHI 側の order と BoundaryCarrierLayout を突合して fail-fast

新規チェック（案）:

• src/mir/builder/control_flow/joinir/merge/contract_checks/header_phi_layout.rs
  • verify_header_phi_layout(boundary: &JoinInlineBoundary, info: &LoopHeaderPhiInfo) -> Result<(), String>
  • BoundaryCarrierLayout の ordered_names() と info.carrier_order が一致することを要求

呼び出し場所（案）:

• src/mir/builder/control_flow/joinir/merge/coordinator.rs
  • prebuild_header_phis 後、rewrite/merge の前（info が確定した直後）

Step 3: docs 更新（迷子防止）

• docs/development/current/main/phases/phase-29af/README.md
  • P4 として “order consistency contract” を追記し、入口ファイルを列挙
• docs/development/current/main/10-Now.md
  • 次にやる P4 のリンクを追記
• docs/development/current/main/30-Backlog.md
  • Phase 29af の “Next: P4” を追記

Verification

• cargo build --release
• ./tools/smokes/v2/run.sh --profile quick
• ./tools/smokes/v2/profiles/integration/joinir/phase29ae_regression_pack_vm.sh

Acceptance Criteria

• strict/dev を有効にしたときのみ新しい fail-fast が働く（release 既定挙動は不変）
• order mismatch を意図的に作ると、P4 の tag で freeze する（診断が安定）
• 回帰パック（phase29ae entrypoint）が PASS のまま