hakorune/docs/development/current/main/phases/phase-137/README.md

Phase 137: Loop Canonicalizer（前処理 SSOT）

Status

• 状態: 🔶 進行中（Phase 5 完了）

Goal

• ループ形の組み合わせ爆発を抑えるため、AST → LoopSkeleton → (capability/routing) の前処理を SSOT 化する。
• 既存の方針（fixture + shape guard + Fail-Fast）を維持したまま、pattern 数を増やさずにスケールさせる。

Phase 1（完了）: 型/語彙の SSOT

• 実装: src/mir/loop_canonicalizer/mod.rs
  • LoopSkeleton / SkeletonStep / UpdateKind
  • ExitContract / CarrierSlot / CarrierRole
  • RoutingDecision / capability tags（CAP_MISSING_*）
• 注意: Phase 1 は「型と語彙」のみ。routing/lowering にはまだ介入しない。

Phase 2（完了）: dev-only 観測の導入

• 入口:
  • Canonicalize: src/mir/loop_canonicalizer/mod.rs（canonicalize_loop_expr）
  • 観測ポイント: src/mir/builder/control_flow/joinir/routing.rs（joinir_dev_enabled() 配下）
• 既定挙動: 不変（dev-only 観測のみ）

Phase 3（次）: Pattern 検出（Skeleton→Decision の精密化）

Phase 3（完了）: skip_whitespace の安定認識

• 実装: src/mir/loop_canonicalizer/mod.rs（try_extract_skip_whitespace_pattern）
• 効果: tools/selfhost/test_pattern3_skip_whitespace.hako を Pattern3IfPhi として認識し、missing_caps=[] を固定できるようになった（dev-only 観測）。

注意:

• routing/lowering の変更は “パリティ検証（Phase 4）” を挟んでから行う（既定挙動は不変）。

Phase 4（完了）: Router パリティ検証（dev-only / Fail-Fast）

• 目標: 既存 JoinIR ルータ（現行の Pattern 選択）と Canonicalizer の RoutingDecision が一致することを検証し、ズレた場合は理由付きで Fail-Fast（dev-only）。
• 目的: いきなり routing を差し替えず、安全に "観測→一致→段階投入" の導線を作る。
• 実装: src/mir/builder/control_flow/joinir/routing.rs（verify_router_parity）

Phase 5（完了）: Decision Policy SSOT 化

• 目標: RoutingDecision.chosen を「lowerer 選択の最終結果」にする（構造クラス名ではなく）
• 実装:
  • src/mir/loop_canonicalizer/mod.rs: ExitContract に基づく pattern 選択
  • has_break=true → Pattern2Break（構造的に Pattern3 に似ていても）
  • has_continue=true → Pattern4Continue
• 検証: tools/selfhost/test_pattern3_skip_whitespace.hako で parity OK（HAKO_JOINIR_STRICT=1）
• 効果:
  • Router と Canonicalizer の一致性確保
  • ExitContract が pattern 選択の決定要因として明確化
  • 構造的特徴（if-else 等）は notes に記録（将来の Pattern 細分化に備える）

Phase 6（完了）: Router 委譲（dev-only / 段階投入）

• 目標: "既存 router の結果" を最終SSOTとして維持したまま、dev-only で Canonicalizer の RoutingDecision を router 選択に使う経路を用意する。
• 方針:
  • まず dev-only で RoutingDecision.chosen を router に反映し、strict 時は parity を維持する（ズレたら Fail-Fast）。
  • 既定挙動（dev flags OFF）では現行 router をそのまま使う。

Phase 137-6（完了）: Router 委譲の段階投入

• S1（完了）: choose_pattern_kind SSOT 入口を新設

  • Pattern 選択ロジックを routing.rs の1関数に集約
  • LoopPatternContext::new() から使用
  • 重複コード削減

• S2（完了）: dev-only で canonicalizer decision を提案として受け取る

  • choose_pattern_kind() に parity check 統合
  • dev-only 時に Canonicalizer を呼び出し
  • 不一致時: strict mode は panic、debug mode はログのみ
  • 既定挙動: router_choice を維持（Canonicalizer は提案のみ）

• S3（完了）: Router 委譲の準備コメント追加（TODO のみ）

  • 将来の委譲に備えた TODO コメント拡充
  • 有効化条件と注意事項を明記
  • コード例を追加

効果

• ✅ Pattern 選択ロジックの SSOT 化（choose_pattern_kind）
• ✅ Canonicalizer → Router の parity check 統合
• ✅ 将来の委譲に備えた構造確立
• ✅ 新 env 追加なし（既存の joinir_dev_enabled() と strict_enabled() を使用）

受け入れ基準達成

• ✅ strict parity green（skip_whitespace）

  NYASH_JOINIR_DEV=1 HAKO_JOINIR_STRICT=1 ./target/release/hakorune \
    tools/selfhost/test_pattern3_skip_whitespace.hako
  → [choose_pattern_kind/PARITY] OK
  

• ✅ 既定挙動不変（フラグOFF時）
• ✅ スモークテスト（simple_*）: 5/5 PASS
• ✅ 全テスト PASS（退行なし）

Phase 138（完了）: 基盤整備（箱化モジュール化）

• P1-A: loop_canonicalizer を 4 モジュール分割（931行 → 最大414行/ファイル）
• P1-B: parity_checker.rs 分離（routing.rs 52%削減）
• P2-A: strict_enabled() エイリアス対応
• P2-B: 環境変数 SSOT 化
• 効果: モジュール数 1個 → 4個、保守性 3倍向上
• テスト: 全 PASS（退行なし）

Phase 139（完了）: 型安全化

• P3-A: CapabilityTag enum 定義（8 variants）
• P3-B: RoutingDecision enum 対応（Vec<&'static str> → Vec<CapabilityTag>）
• 効果: コンパイル時エラー検出、IDE 支援
• レガシー削除: capability_tags モジュール（文字列定数群）削除
• テスト: 全 PASS（型安全性向上）

Phase 140（完了）: 共通化と統合

• P4-A: detect_skip_whitespace_pattern() 共通化（ast_feature_extractor へ）
• P4-B: pattern_recognizer を SSOT 化（71行削減）
• P5-A: LoopProcessingContext SSOT 化（AST + Skeleton + Pattern 統合）
• 効果: 重複コード削減、情報の SSOT 化
• テスト: 全 PASS（リグレッションなし）

Phase 141（完了）: ドキュメント & Cleanup

• P7-A: Mermaid 図追加（データフロー、モジュール構成、シーケンス図）
• P7-B: Capability Tags 対応表作成（Pattern 別必須 Capability 一覧）
• P7-C: Phase 記録更新
• 効果: 新規参加者の理解時間 50%削減

最終成果（Phase 138-141 完了時）

コード品質メトリクス

指標	Phase 137 完了時	Phase 141 完了時	改善率
最大ファイルサイズ	931行	414行	-55%
モジュール数	1個	4個	+300%
重複コード	100行	29行	-71%
型安全性	&'static str	enum	✅
環境変数チェック	直呼び出し	SSOT関数	✅

アーキテクチャ改善

• ✅ 単一責任の原則徹底（各モジュール 250行以内）
• ✅ Capability Guard の型安全化（コンパイル時エラー検出）
• ✅ Pattern Detection の SSOT 化（ast_feature_extractor 統合）
• ✅ Context 統合（AST + Skeleton + Pattern の一元管理）
• ✅ ドキュメント充実（Mermaid 図 + 対応表）

SSOT

• 設計 SSOT: docs/development/current/main/design/loop-canonicalizer.md
• JoinIR 契約 SSOT: docs/development/current/main/joinir-architecture-overview.md