docs(phase287): Mark P3 complete, add P4 instructions

2025-12-27 12:17:47 +09:00
parent 3224d83a7b
commit 2f7061e2e5
6 changed files with 277 additions and 12 deletions
--- a/docs/development/current/main/10-Now.md
+++ b/docs/development/current/main/10-Now.md
@ -1,6 +1,6 @@
 # Self Current Task — Now (main)

-## Current Focus: Phase 287 P2（Contract Checks facade）
+## Current Focus: Phase 287 P4（Plan stage modularization）

 **2025-12-27: Phase 188.3 完了** ✅
 - Pattern6（NestedLoopMinimal）: `apps/tests/phase1883_nested_minimal.hako` が RC=9
@ -20,7 +20,19 @@
 - `pattern_recognizers/`（8 modules）へ分割（1 module = 1 質問）
 - 検証: Build 0 errors / Pattern6 RC=9 / quick 154 PASS / 恒常ログ増加なし
 - 入口: `docs/development/current/main/phases/phase-287/P1-AST_FEATURE_EXTRACTOR-INSTRUCTIONS.md`
- 次の指示書（P2）: `docs/development/current/main/phases/phase-287/P2-CONTRACT_CHECKS-MODULARIZATION-INSTRUCTIONS.md`
+- 次の指示書（P2）: `docs/development/current/main/phases/phase-287/P2-CONTRACT_CHECKS-MODULARIZATION-INSTRUCTIONS.md`（完了）
+
+**2025-12-27: Phase 287 P2 完了** ✅
+- `contract_checks.rs` を facade 化し、`contract_checks/` 配下へ契約単位で分割（1 module = 1 contract）
+- 検証: Build 0 errors / Pattern6 RC=9 / quick 154 PASS / 恒常ログ増加なし
+- 入口: `docs/development/current/main/phases/phase-287/P2-CONTRACT_CHECKS-MODULARIZATION-INSTRUCTIONS.md`
+- 次の指示書（P3）: `docs/development/current/main/phases/phase-287/P3-INSTRUCTION_REWRITER-MODULARIZATION-INSTRUCTIONS.md`（完了）
+
+**2025-12-27: Phase 287 P3 完了** ✅
+- `instruction_rewriter.rs` を stage 単位へ物理分割（Scan/Plan/Apply）し、facade（orchestrator）へ縮退（意味論不変）
+- 検証: Build 0 errors / quick 154 PASS / 恒常ログ増加なし
+- 入口: `docs/development/current/main/phases/phase-287/P3-INSTRUCTION_REWRITER-MODULARIZATION-INSTRUCTIONS.md`
+- 次の指示書（P4）: `docs/development/current/main/phases/phase-287/P4-PLAN_STAGE-MODULARIZATION-INSTRUCTIONS.md`

 **2025-12-27: Phase 188.2 完了** ✅
 - StepTreeの `max_loop_depth` を SSOT に採用（Option A）
@ -113,8 +125,8 @@
 - quick smoke 154/154 PASS 維持、Pattern1/4 PoC 両方 PASS

 **次のステップ**:
-1. **Phase 287（P2）**: `contract_checks.rs` の facade 化（意味論不変）
-   - 指示書: `docs/development/current/main/phases/phase-287/P2-CONTRACT_CHECKS-MODULARIZATION-INSTRUCTIONS.md`
+1. **Phase 287（P4）**: `rewriter/stages/plan.rs` の責務分割（意味論不変）
+   - 指示書: `docs/development/current/main/phases/phase-287/P4-PLAN_STAGE-MODULARIZATION-INSTRUCTIONS.md`
 2. （post self-host / docs-first）**Phase 29y**: MIR lifecycle vocab freeze（RC/weak/ABI）
   - 相談パケット: `docs/development/current/main/investigations/phase-29y-mir-lifecycle-vocab-consult.md`
 3. （future design, separate phase）Plan 生成の正規化（相談パケット）
--- a/docs/development/current/main/30-Backlog.md
+++ b/docs/development/current/main/30-Backlog.md
@ -14,10 +14,10 @@ Related:
  - 次: Phase 288.2+（任意）: REPL UX improvements（history / multiline / load 等）

 - **Phase 287（active）: Big Files Refactoring follow-ups（意味論不変）**
-  - 状況: P0/P1 ✅ 完了（merge modularize / ast_feature_extractor facade）
-  - 次（P2）: `contract_checks.rs` を facade 化して契約単位で分割
+  - 状況: P0/P1/P2/P3 ✅ 完了（merge modularize / ast_feature_extractor facade / contract_checks facade / rewriter stages split）
+  - 次（P4）: `rewriter/stages/plan.rs` を責務単位で分割（Plan stage の見える化）
  - 入口: `docs/development/current/main/phases/phase-287/README.md`
-  - 指示書: `docs/development/current/main/phases/phase-287/P2-CONTRACT_CHECKS-MODULARIZATION-INSTRUCTIONS.md`
+  - 指示書: `docs/development/current/main/phases/phase-287/P4-PLAN_STAGE-MODULARIZATION-INSTRUCTIONS.md`

 - **Phase 284（✅ COMPLETE）: Return as ExitKind SSOT（patternに散らさない）**
  - 目的: `return` を “pattern最適化の個別実装” にせず、`ExitKind` と `compose::*` / `emit_frag()` に収束させる
--- a/docs/development/current/main/phases/phase-287/P2-CONTRACT_CHECKS-MODULARIZATION-INSTRUCTIONS.md
+++ b/docs/development/current/main/phases/phase-287/P2-CONTRACT_CHECKS-MODULARIZATION-INSTRUCTIONS.md
@ -1,7 +1,7 @@
 # Phase 287 P2: `merge/contract_checks.rs` 分割指示書（意味論不変）

 **Date**: 2025-12-27  
-**Status**: Ready（next）  
+**Status**: Completed ✅  
 **Scope**: `src/mir/builder/control_flow/joinir/merge/contract_checks.rs`（~846行）を facade 化し、契約検証を “1 module = 1 契約” に分割  
 **Non-goals**: エラータグ変更、検証条件の追加/緩和、`merge/instruction_rewriter.rs` の分割、silent fallback 追加

--- a/docs/development/current/main/phases/phase-287/P3-INSTRUCTION_REWRITER-MODULARIZATION-INSTRUCTIONS.md
+++ b/docs/development/current/main/phases/phase-287/P3-INSTRUCTION_REWRITER-MODULARIZATION-INSTRUCTIONS.md
@ -0,0 +1,112 @@
+# Phase 287 P3: `merge/instruction_rewriter.rs` 分割指示書（意味論不変）
+
+**Date**: 2025-12-27  
+**Status**: Completed ✅  
+**Scope**: `src/mir/builder/control_flow/joinir/merge/instruction_rewriter.rs`（~1297行）を “Scan/Plan/Apply” の stage 単位に分割し、`instruction_rewriter.rs` を facade（orchestrator）へ縮退する。  
+**Non-goals**: 仕様変更、エラータグ/ヒント文の変更、検出条件の追加/緩和、silent fallback 追加、ログの恒常増加、Plan line / Pattern の挙動変更
+
+---
+
+## 目的（SSOT）
+
+- JoinIR merge の “3-stage pipeline” を **物理構造**で見える化し、責務を分離する。
+- 巨大ファイルを “入口（orchestrator）” と “stage 実装” に分けて、読む導線を短くする。
+- 意味論不変（behavior unchanged）を守りつつ、後続の小改修（Box 抽出/契約追加）を安全にする。
+
+---
+
+## 現状（問題点）
+
+- `instruction_rewriter.rs` が大きく、Scan/Plan/Apply の境界がコード上で追いにくい。
+- stage 実装が 1 ファイルに同居しているため、変更時に “どこまでが read-only / どこからが mutation” かが崩れやすい。
+
+※ 既に `rewriter/scan_box.rs` / `rewriter/plan_box.rs` 等の土台はあり、分割は “移動 + import 整理” が主になるはず。
+
+---
+
+## 目標の構造（案）
+
+最小の増分で “1 stage = 1 module” を実現する。
+
+```
+src/mir/builder/control_flow/joinir/merge/
+├── instruction_rewriter.rs            # facade（merge_and_rewrite の入口 + stage 呼び出し）
+└── rewriter/
+    └── stages/                        # NEW
+        ├── mod.rs
+        ├── scan.rs                    # scan_blocks()
+        ├── plan.rs                    # plan_rewrites()
+        └── apply.rs                   # apply_rewrites()
+```
+
+ルール:
+- facade は “順番” と “受け渡し” のみを担い、ロジックは stage 側へ移す。
+- `RewriteContext` は既存の SSOT を使い続ける（散らさない）。
+
+---
+
+## 手順（安全な順序）
+
+### Step 1: `rewriter/stages/` を追加して “空の mod” を作る
+
+- `rewriter/stages/mod.rs` を追加し、`pub(super) mod scan; pub(super) mod plan; pub(super) mod apply;` を置く。
+- 先にコンパイルが通る状態を作る（未使用は `pub(super)` に寄せる）。
+
+### Step 2: Stage 1 を移す（scan）
+
+- `instruction_rewriter.rs` の `scan_blocks(...)` を `rewriter/stages/scan.rs` へ移動する。
+- 署名と返り値は維持する（意味論不変のため）。
+
+### Step 3: Stage 2 を移す（plan）
+
+- `plan_rewrites(...)` を `rewriter/stages/plan.rs` へ移動する。
+- `plan.rs` 側の “ローカル helper” が肥大化する場合:
+  - まずは `plan_helpers.rs` へ移動して SSOT を 1 箇所に寄せる（新規 helper の乱立を避ける）。
+
+### Step 4: Stage 3 を移す（apply）
+
+- `apply_rewrites(...)` を `rewriter/stages/apply.rs` へ移動する。
+- boundary injection のブロックは動かし過ぎない（挙動差が出やすい）。
+
+### Step 5: facade を縮退する（orchestrator only）
+
+- `instruction_rewriter.rs` に残すのは:
+  - `merge_and_rewrite(...)`（外部 API）
+  - stage 呼び出し（scan → plan → apply）
+  - stage 間の contract check 呼び出し（例: `contract_checks::verify_carrier_inputs_complete(...)`）
+- “大きなローカル関数” は原則 stage 側へ移す。
+
+---
+
+## テスト（仕様固定）
+
+P3 は意味論不変が主目的のため、原則は既存 smoke を維持する。
+
+新規テストを足すなら “構造テスト” を 1 つだけ（任意）:
+- `scan_blocks` が “read-only” であること（builder を触らない）を保証する形のテストは難しいので、代替として
+  - `classify_tail_call()` の境界条件ユニットテスト
+  - `latch_incoming_recorder` の invariants テスト
+
+---
+
+## 検証手順（受け入れ基準）
+
+```bash
+cargo build --release
+./target/release/hakorune --backend vm apps/tests/phase1883_nested_minimal.hako   # RC=9
+./tools/smokes/v2/run.sh --profile quick
+```
+
+受け入れ:
+- Build: 0 errors
+- quick: 154/154 PASS
+- Pattern6: RC=9 維持
+- 恒常ログ増加なし
+
+---
+
+## Out of Scope（重要）
+
+- 既存の `TODO` 群（exit_collection への統合など）を進めること
+- `ReturnConverterBox` / `ParameterBindingBox` のさらなる箱化（P3 は “stage 物理分割” に限定）
+- 新しい env var / debug トグルの追加
--- a/docs/development/current/main/phases/phase-287/P4-PLAN_STAGE-MODULARIZATION-INSTRUCTIONS.md
+++ b/docs/development/current/main/phases/phase-287/P4-PLAN_STAGE-MODULARIZATION-INSTRUCTIONS.md
@ -0,0 +1,127 @@
+# Phase 287 P4: `rewriter/stages/plan.rs` 分割指示書（意味論不変）
+
+**Date**: 2025-12-27  
+**Status**: Ready（next）  
+**Scope**: `src/mir/builder/control_flow/joinir/merge/rewriter/stages/plan.rs`（~741行）を “責務単位” に分割して読みやすくし、`plan.rs` は facade（入口 + 組み立て）へ縮退する。  
+**Non-goals**: 仕様変更、エラータグ/ヒント文の変更、検出条件の追加/緩和、silent fallback 追加、恒常ログ増加、`merge/instruction_rewriter.rs` の再分割
+
+---
+
+## 前提（P3 完了）
+
+- P3 で `instruction_rewriter.rs` は facade 化され、pipeline 関数は `rewriter/stages/{scan,plan,apply}.rs` に物理分割済み。
+- P4 は Stage 2（Plan）の “中身” を構造で分割するフェーズ。
+
+---
+
+## 目的（SSOT）
+
+- Plan stage の責務（entry 解決 / block map / instruction rewrite / tail call / terminator / carrier_inputs）を **ファイル構造**で見える化する。
+- “どの判断がどこにあるか” を迷わず追えるようにし、将来のバグ修正を **局所化**する。
+- 意味論不変（copy/move のみ）を守り、Fail-Fast の契約を崩さない。
+
+---
+
+## 現状（問題点）
+
+`rewriter/stages/plan.rs` が長く、以下が同居している:
+
+- entry function 解決（boundary SSOT + fallback heuristic）
+- per-function / per-block の main loop
+- instruction filtering / remap
+- tail call detection + param binding + latch incoming
+- terminator remap（jump/branch/return → jump など）
+- carrier_inputs 収集（exit jump / skippable continuation）
+
+この同居は “後続で if が増殖する” 典型パターンなので、P4 で責務分離して予防する。
+
+---
+
+## 目標の構造（案）
+
+`plan.rs` は orchestrator、ロジックは `plan/` 配下へ。
+
+```
+src/mir/builder/control_flow/joinir/merge/rewriter/stages/
+├── plan.rs                         # facade（入口 + 部品の呼び出し）
+└── plan/                           # NEW（1 file = 1 responsibility）
+    ├── mod.rs
+    ├── entry_resolver.rs           # entry_func_name 解決（boundary SSOT）
+    ├── local_block_map.rs          # build_local_block_map の使い方を固定
+    ├── instruction_rewrite.rs      # inst の skip/remap + branch/phi block remap
+    ├── tail_call_rewrite.rs        # tail call 検出→binding→jump 生成
+    ├── terminator_rewrite.rs       # terminator の remap（jump/branch/return）
+    └── carrier_inputs.rs           # ExitJump(skippable) の carrier_inputs 収集
+```
+
+ルール:
+- **“移動だけ”** を徹底する（関数分割はするが、条件式・順序は変えない）。
+- helper が増えたら `plan/mod.rs` の下に閉じ込める（stages の外へ漏らさない）。
+
+---
+
+## 手順（安全な順序）
+
+### Step 1: `plan/` を追加（空の module）
+
+- `rewriter/stages/plan/mod.rs` を追加し、各 submodule を `pub(super) mod ...;` で宣言する。
+- まずは `plan.rs` から `mod plan;` を参照できる状態にする（実体は空でも良い）。
+
+### Step 2: entry 解決を抽出（純粋で安全）
+
+- `entry_func_name` の算出を `entry_resolver.rs` へ移動する。
+- 重要: `JoinInlineBoundary.loop_header_func_name` を優先する SSOT を維持。
+
+### Step 3: “instruction rewrite loop” を抽出
+
+- inst 単位の処理を `instruction_rewrite.rs` に移す（skip/remap/branch/phi remap）。
+- 既存の `InstructionFilterBox` / `ReturnConverterBox` の呼び出しは維持（置き換えない）。
+
+### Step 4: tail call の rewrite を抽出（最も注意）
+
+- tail call の検出・分類・param binding・latch incoming を `tail_call_rewrite.rs` へ移す。
+- 重要: 既存の `classify_tail_call(...)` の引数計算順序（entry-like 判定含む）を変えない。
+- 重要: `CarrierInputsCollector` の呼び出し箇所を変えない（ExitJump(skippable) のみ）。
+
+### Step 5: terminator rewrite を抽出
+
+- `terminator` の remap と `ReturnConverterBox` の適用を `terminator_rewrite.rs` へ移す。
+- “Return → Jump” の規約（skippable continuation を除く）を変えない。
+
+### Step 6: `plan.rs` を facade へ縮退
+
+- `plan_rewrites(...)` の中身は “部品を呼んで順番に組み立てるだけ” にする。
+- `resolve_target_func_name` / `is_joinir_main_entry_block` のようなローカル helper は、責務に応じた module 側へ移す。
+
+---
+
+## テスト（仕様固定）
+
+新規テストは原則不要（意味論不変）。
+
+ただし 1 つだけ足すなら “境界” の unit test（任意）:
+- `entry_resolver::resolve_entry_func_name(...)` が boundary を優先し、`MAIN` を除外すること。
+
+---
+
+## 検証手順（受け入れ基準）
+
+```bash
+cargo build --release
+./target/release/hakorune --backend vm apps/tests/phase1883_nested_minimal.hako   # RC=9
+./tools/smokes/v2/run.sh --profile quick
+```
+
+受け入れ:
+- Build: 0 errors（warnings は増やさない努力はするが 0 を要求しない）
+- quick: 154/154 PASS
+- Pattern6: RC=9 維持
+- 恒常ログ増加なし
+
+---
+
+## Out of Scope（重要）
+
+- “exit_collection へ統合する” などの仕様寄り整理（Phase 分けする）
+- contract_checks の新規契約追加（P4 ではやらない）
+- plan stage の最適化（性能改善）や algorithm 変更
--- a/docs/development/current/main/phases/phase-287/README.md
+++ b/docs/development/current/main/phases/phase-287/README.md
@ -1,6 +1,6 @@
 # Phase 287: Developer Hygiene（big files / smoke / normalizer）

-**Status**: In progress (P0/P1 complete, P2 next)
+**Status**: In progress (P0/P1/P2/P3 complete, P4 next)
 **Date**: 2025-12-27
 **Previous**: Phase 286 (Plan Line完全運用化)

@ -19,17 +19,31 @@ Phase 287 は「開発導線の整備（意味論不変）」を優先して、
 `ast_feature_extractor.rs` を facade にして、`pattern_recognizers/` 配下へ recognizer 単位で分割した（意味論不変）。

 - 入口: `docs/development/current/main/phases/phase-287/P1-AST_FEATURE_EXTRACTOR-INSTRUCTIONS.md`
- 次（P2）: `docs/development/current/main/phases/phase-287/P2-CONTRACT_CHECKS-MODULARIZATION-INSTRUCTIONS.md`
+- 次（P2）: `docs/development/current/main/phases/phase-287/P2-CONTRACT_CHECKS-MODULARIZATION-INSTRUCTIONS.md`（完了）

 ---

-## Next (P2)
+## 2025-12-27 Update: Contract Checks modularization（P2）✅

- `contract_checks.rs` を facade 化して、契約検証を “1 module = 1 契約” に分割する（意味論不変）。
+- `contract_checks.rs` を facade 化して、契約検証を “1 module = 1 契約” に分割した（意味論不変）。
  - 指示書: `docs/development/current/main/phases/phase-287/P2-CONTRACT_CHECKS-MODULARIZATION-INSTRUCTIONS.md`

 ---

+## 2025-12-27 Update: Instruction Rewriter stage split（P3）✅
+
+- `merge/instruction_rewriter.rs` を “Scan/Plan/Apply” の stage 単位に分割し、facade（orchestrator）へ縮退した（意味論不変）。
+  - 指示書: `docs/development/current/main/phases/phase-287/P3-INSTRUCTION_REWRITER-MODULARIZATION-INSTRUCTIONS.md`
+
+---
+
+## Next (P4)
+
+- `rewriter/stages/plan.rs` を “責務単位” に分割し、Plan stage を読みやすくする（意味論不変）。
+  - 指示書: `docs/development/current/main/phases/phase-287/P4-PLAN_STAGE-MODULARIZATION-INSTRUCTIONS.md`
+
+---
+
 ## Legacy / Historical (2025-12-26 plan)

 以下は「Phase 287 を hygiene として計画していた時期のログ」。今後の候補として残すが、P0/P1（big files）とは別系統。