From 2f7061e2e5b1c2f5177439746afe9e381db8b34d Mon Sep 17 00:00:00 2001 From: tomoaki Date: Sat, 27 Dec 2025 12:17:47 +0900 Subject: [PATCH] docs(phase287): Mark P3 complete, add P4 instructions --- docs/development/current/main/10-Now.md | 20 ++- docs/development/current/main/30-Backlog.md | 6 +- ...RACT_CHECKS-MODULARIZATION-INSTRUCTIONS.md | 2 +- ...ON_REWRITER-MODULARIZATION-INSTRUCTIONS.md | 112 +++++++++++++++ ...-PLAN_STAGE-MODULARIZATION-INSTRUCTIONS.md | 127 ++++++++++++++++++ .../current/main/phases/phase-287/README.md | 22 ++- 6 files changed, 277 insertions(+), 12 deletions(-) create mode 100644 docs/development/current/main/phases/phase-287/P3-INSTRUCTION_REWRITER-MODULARIZATION-INSTRUCTIONS.md create mode 100644 docs/development/current/main/phases/phase-287/P4-PLAN_STAGE-MODULARIZATION-INSTRUCTIONS.md diff --git a/docs/development/current/main/10-Now.md b/docs/development/current/main/10-Now.md index 0f077771..5b94c8b8 100644 --- 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 生成の正規化（相談パケット） diff --git a/docs/development/current/main/30-Backlog.md b/docs/development/current/main/30-Backlog.md index d1bcb57a..cb5d07e4 100644 --- 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()` に収束させる diff --git 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 index ffd6a1da..36eb3f6c 100644 --- 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 追加 diff --git 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 new file mode 100644 index 00000000..8a56d88c --- /dev/null +++ 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 トグルの追加 diff --git 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 new file mode 100644 index 00000000..96d4006c --- /dev/null +++ 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 変更 diff --git a/docs/development/current/main/phases/phase-287/README.md b/docs/development/current/main/phases/phase-287/README.md index 04340801..2ddadc85 100644 --- 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）とは別系統。