diff --git a/docs/development/current/main/design/loop-canonicalizer.md b/docs/development/current/main/design/loop-canonicalizer.md index 032b8206..ab5dc629 100644 --- a/docs/development/current/main/design/loop-canonicalizer.md +++ b/docs/development/current/main/design/loop-canonicalizer.md @@ -1,12 +1,77 @@ # Loop Canonicalizer(設計 SSOT) -Status: Phase 5 done(Decision Policy SSOT まで) -Scope: ループ形の組み合わせ爆発を抑えるための “前処理” の設計(fixture/shape guard/fail-fast と整合) +Status: Phase 141 完了(ドキュメント充実) +Scope: ループ形の組み合わせ爆発を抑えるための "前処理" の設計(fixture/shape guard/fail-fast と整合) Related: - SSOT (契約/不変条件): `docs/development/current/main/joinir-architecture-overview.md` - SSOT (地図/入口): `docs/development/current/main/design/joinir-design-map.md` - SSOT (パターン空間): `docs/development/current/main/loop_pattern_space.md` +## アーキテクチャ図 + +### データフロー + +```mermaid +graph LR + A[AST Loop] --> B[Canonicalizer] + B --> C{LoopSkeleton} + B --> D{RoutingDecision} + C --> E[Capability Guard] + D --> E + E --> F{Pass?} + F -->|Yes| G[Pattern Router] + F -->|No| H[Fail-Fast Error] + G --> I[JoinIR Lowerer] +``` + +### モジュール構成 + +``` +loop_canonicalizer/ +├── skeleton_types.rs [Data Structures] +│ ├── LoopSkeleton +│ ├── SkeletonStep +│ ├── UpdateKind +│ └── CarrierSlot +├── capability_guard.rs [Validation] +│ ├── RoutingDecision +│ ├── CapabilityTag (enum) +│ └── Decision constructors +├── pattern_recognizer.rs [Pattern Detection] +│ └── detect patterns (ast_feature_extractor 呼び出し) +└── canonicalizer.rs [Main Logic] + └── canonicalize_loop_expr() + ↓ + LoopSkeleton + RoutingDecision + ↓ + Pattern Router (patterns/router.rs) + ↓ + Pattern Lowerer (pattern1-5_*.rs) +``` + +### 処理フロー(Phase 140 完了後) + +```mermaid +sequenceDiagram + participant AST as AST Loop + participant Canon as Canonicalizer + participant Guard as Capability Guard + participant Router as Pattern Router + participant Lower as JoinIR Lowerer + + AST->>Canon: canonicalize_loop_expr() + Canon->>Canon: extract pattern (ast_feature_extractor) + Canon->>Canon: build LoopSkeleton + Canon->>Guard: validate capabilities + alt All capabilities satisfied + Guard->>Router: RoutingDecision(Pattern2) + Router->>Lower: lower to JoinIR + Lower-->>AST: MIR blocks + else Missing capabilities + Guard-->>AST: Fail-Fast error + end +``` + ## 目的 - 実アプリ由来のループ形を、fixture + shape guard + Fail-Fast の段階投入で飲み込む方針を維持したまま、 @@ -54,11 +119,69 @@ Skeleton を生成できても、lower/merge 契約が成立するとは限ら ## RoutingDecision(理由の SSOT) -Canonicalizer は “できない理由” を機械的に返す。 +Canonicalizer は "できない理由" を機械的に返す。 - `RoutingDecision { chosen, missing_caps, notes, error_tags }` - `missing_caps` は定型の語彙で出す(ログ/デバッグ/統計で集約可能にする) +## Capability Tags 対応表 + +### 各 Tag の詳細 + +| Tag | 必要な条件 | 対応Pattern | 検出方法 | +|-----|----------|------------|---------| +| `ConstStep` | キャリア更新が定数ステップ(`i = i + const`) | P1, P2, P3 | UpdateKind 分析(ConstStep variant) | +| `SingleBreak` | break 文が単一箇所のみ | P2 | AST 走査でカウント(`count_break_checks() == 1`) | +| `SingleContinue` | continue 文が単一箇所のみ | P1, P3 | AST 走査でカウント(`count_continue_checks() == 1`) | +| `PureHeader` | ループ条件に副作用がない | P1, P2, P3, P4 | 副作用解析(将来実装) | +| `OuterLocalCond` | 条件変数が外側スコープで定義済み | P3 | Scope 分析(BindingContext 参照) | +| `ExitBindings` | 境界へ渡す値が過不足ない | P2, P3 | Carrier 収支計算(ExitContract 分析) | +| `CarrierPromotion` | LoopBodyLocal を昇格可能 | P3, P4 | Binding 解析(promoted carriers 検出) | +| `BreakValueType` | break 値の型が一貫 | P2 | 型推論(TypeContext 参照) | + +### 各 Pattern の必須 Capability(Phase 140 時点) + +#### Pattern1 (Minimal) +- ✅ `ConstStep` - 定数ステップ増分 +- ✅ `PureHeader` - 副作用なし条件 +- ✅ `SingleContinue` - continue 単一箇所 + +#### Pattern2 (Break) +- ✅ `ConstStep` - 定数ステップ増分 +- ✅ `PureHeader` - 副作用なし条件 +- ✅ `SingleBreak` - break 単一箇所 +- ✅ `ExitBindings` - 出口値の完全性 + +**例**: `skip_whitespace` は `has_break=true` なので Pattern2 へルーティング(Phase 137-5) + +#### Pattern3 (IfPhi) +- ✅ `ConstStep` - 定数ステップ増分 +- ✅ `PureHeader` - 副作用なし条件 +- ✅ `OuterLocalCond` - 外側スコープ条件変数 +- ✅ `CarrierPromotion` - LoopBodyLocal 昇格 + +**例**: Trim パターン(Phase 133) + +#### Pattern4 (Composite) +- ✅ `PureHeader` - 副作用なし条件 +- ✅ `CarrierPromotion` - LoopBodyLocal 昇格 +- ✅ `ExitBindings` - 出口値の完全性 + +#### Pattern5 (Future) +- 🚧 TBD - 将来定義 + +### Capability 追加時のチェックリスト + +新しい Capability を追加する際は以下を確認: + +1. **enum 定義**: `capability_guard.rs` の `CapabilityTag` に variant 追加 +2. **文字列変換**: `to_tag()` メソッドに対応を追加(`CAP_MISSING_*` 形式) +3. **説明文**: `description()` メソッドに説明を追加 +4. **検出ロジック**: `canonicalizer.rs` に検出ロジックを実装 +5. **対応表更新**: このドキュメントの対応表を更新 +6. **Pattern 更新**: 必要に応じて各 Pattern の必須 Capability リストを更新 +7. **テスト追加**: 新 Capability の検出テストを追加 + ## Corpus / Signature(拡張のための仕組み) 将来の規模増加に備え、ループ形の差分検知を Skeleton ベースで行えるようにする。