hakorune/docs/development/current/main/design/loop-canonicalizer.md

Loop Canonicalizer（設計 SSOT）

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

アーキテクチャ図

データフロー

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 完了後）

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 の段階投入で飲み込む方針を維持したまま、
  “パターン数を増やさない” 形でスケールさせる。
• ループ lowerer が「検出 + 正規化 + merge 契約」を同時に背負って肥大化するのを防ぎ、責務を前処理に寄せる。

推奨配置（結論）

おすすめ: AST → LoopSkeleton → JoinIR(Structured) の前処理として Canonicalizer を置く。

• 「組み合わせ爆発」が Pattern 検出/shape guard の手前で起きるため、Normalized 変換だけでは吸収しきれない。
• LoopSkeleton を SSOT にすると、lowerer は “骨格を吐く” だけの薄い箱になり、Fail-Fast の理由が明確になる。

代替案（参考）:

• Structured JoinIR → Normalized JoinIR を実質 Canonicalizer とみなす（既存延長）。
  ただし「検出/整理の肥大」は Structured 生成側に残りやすい。

LoopSkeleton（SSOT になる出力）

Canonicalizer の出力は “ループの骨格” に限る。例示フィールド:

• steps: Vec<Step>
  • HeaderCond（あれば）
  • BodyInit（body-local 初期化を分離するなら）
  • BreakCheck / ContinueCheck（あれば）
  • Updates（carrier 更新規則）
  • Tail（継続呼び出し/次ステップ）
• carriers: Vec<CarrierSlot>（loop var を含む。役割/更新規則/境界通過の契約）
• exits: ExitContract（break/continue/return の有無と payload）
• captured: Vec<CapturedSlot>（外側変数の取り込み）
• derived: Vec<DerivedSlot>（digit_pos 等の派生値）

Capability Guard（shape guard の上位化）

Skeleton を生成できても、lower/merge 契約が成立するとは限らない。
そこで SkeletonGuard を “Capability の集合” として設計する。

例:

• RequiresConstStepIncrement（i=i+const のみ）
• BreakOnlyOnce / ContinueOnlyInTail
• NoSideEffectInHeader（header に副作用がない）
• ExitBindingsComplete（境界へ渡す値が過不足ない）

未達の場合は Fail-Fast（理由を RoutingDecision に載せる）。

RoutingDecision（理由の SSOT）

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 ベースで行えるようにする。

• LoopSkeletonSignature = hash(steps + exit_contract + carrier_roles + required_caps)
• 既知集合との差分が出たら “fixture 化候補” として扱う（設計上の導線）。

実装の境界（非目標）

• 新しい言語仕様/ルール実装はしない（既存の意味論を保つ）。
• 非 JoinIR への退避（prohibited fallback）は導入しない。
• 既定挙動は変えない（必要なら dev-only で段階投入する）。

LoopSkeleton の最小フィールド（SSOT 境界）

Canonicalizer の出力は以下のフィールドに限定する（これ以上細かくしない）：

/// ループの骨格（Canonicalizer の唯一の出力）
pub struct LoopSkeleton {
    /// ステップの列（HeaderCond, BodyInit, BreakCheck, Updates, Tail）
    pub steps: Vec<SkeletonStep>,

    /// キャリア（ループ変数・更新規則・境界通過の契約）
    pub carriers: Vec<CarrierSlot>,

    /// 出口契約（break/continue/return の有無と payload）
    pub exits: ExitContract,

    /// 外部キャプチャ（省略可: 外側変数の取り込み）
    pub captured: Option<Vec<CapturedSlot>>,
}

/// ステップの種類（最小限）
pub enum SkeletonStep {
    /// ループ継続条件（loop(cond) の cond）
    HeaderCond { expr: AstExpr },

    /// 早期終了チェック（if cond { break }）
    BreakCheck { cond: AstExpr, has_value: bool },

    /// スキップチェック（if cond { continue }）
    ContinueCheck { cond: AstExpr },

    /// キャリア更新（i = i + 1 など）
    Update { carrier_name: String, update_kind: UpdateKind },

    /// 本体（その他の命令）
    Body { stmts: Vec<AstStmt> },
}

/// キャリアの更新種別
pub enum UpdateKind {
    /// 定数ステップ（i = i + const）
    ConstStep { delta: i64 },

    /// 条件付き更新（if cond { x = a } else { x = b }）
    Conditional { then_value: AstExpr, else_value: AstExpr },

    /// 任意更新（上記以外）
    Arbitrary,
}

/// 出口契約
pub struct ExitContract {
    pub has_break: bool,
    pub has_continue: bool,
    pub has_return: bool,
    pub break_has_value: bool,
}

/// キャリアスロット
pub struct CarrierSlot {
    pub name: String,
    pub role: CarrierRole,
    pub update_kind: UpdateKind,
}

/// キャリアの役割
pub enum CarrierRole {
    /// ループカウンタ（i < n の i）
    Counter,
    /// アキュムレータ（sum += x の sum）
    Accumulator,
    /// 条件変数（while(is_valid) の is_valid）
    ConditionVar,
    /// 派生値（digit_pos 等）
    Derived,
}

SSOT 境界の原則

• 入力: AST（LoopExpr）
• 出力: LoopSkeleton のみ（JoinIR は生成しない）
• 禁止: Skeleton に JoinIR 固有の情報を含めない（BlockId, ValueId 等）

---

実装の入口（現状）

実装（Phase 1–2）はここ：

• src/mir/loop_canonicalizer/mod.rs

注意:

• Phase 2 で canonicalize_loop_expr(...) -> Result<(LoopSkeleton, RoutingDecision), String> を導入し、JoinIR ループ入口で dev-only 観測できるようにした（既定挙動は不変）。
• 観測ポイント（JoinIR ループ入口）: src/mir/builder/control_flow/joinir/routing.rs（joinir_dev_enabled() 配下）
• Phase 3 で skip_whitespace の最小形を Pattern3IfPhi として安定に識別できるようにした（dev-only 観測）。

Capability の語彙（Fail-Fast reason タグ）

Skeleton を生成できても lower/merge できるとは限らない。以下の Capability で判定する：

Capability	説明	未達時の理由タグ
ConstStepIncrement	キャリア更新が定数ステップ（i=i+const）	CAP_MISSING_CONST_STEP
SingleBreakPoint	break が単一箇所のみ	CAP_MISSING_SINGLE_BREAK
SingleContinuePoint	continue が単一箇所のみ	CAP_MISSING_SINGLE_CONTINUE
NoSideEffectInHeader	ループ条件に副作用がない	CAP_MISSING_PURE_HEADER
OuterLocalCondition	条件変数が外側スコープで定義済み	CAP_MISSING_OUTER_LOCAL_COND
ExitBindingsComplete	境界へ渡す値が過不足ない	CAP_MISSING_EXIT_BINDINGS
CarrierPromotion	LoopBodyLocal を昇格可能	CAP_MISSING_CARRIER_PROMOTION
BreakValueConsistent	break 値の型が一貫	CAP_MISSING_BREAK_VALUE_TYPE

語彙の安定性

• reason タグは CAP_MISSING_* プレフィックスで統一
• 新規追加時は loop-canonicalizer.md に先に追記してからコード実装
• ログ / 統計 / error_tags で集約可能

---

RoutingDecision の出力先

Canonicalizer の判定結果は RoutingDecision に集約し、以下に流す：

pub struct RoutingDecision {
    /// 選択された Pattern（None = Fail-Fast）
    /// Phase 137-5: ExitContract に基づく最終 lowerer 選択を反映
    pub chosen: Option<LoopPatternKind>,

    /// 不足している Capability のリスト
    pub missing_caps: Vec<&'static str>,

    /// 選択理由（デバッグ用）
    pub notes: Vec<String>,

    /// error_tags への追記（contract_checks 用）
    pub error_tags: Vec<String>,
}

Phase 137-5: Decision Policy SSOT

原則: RoutingDecision.chosen は「lowerer 選択の最終結果」を返す（構造クラス名ではなく）。

• ExitContract が優先: has_break=true なら Pattern2Break、has_continue=true なら Pattern4Continue
• 構造的特徴は notes へ: 「if-else 構造がある」等の情報は notes フィールドに記録
• 一致保証: Router と Canonicalizer の pattern 選択が一致することを parity check で検証

例: skip_whitespace パターン

• 構造: if-else 形式（Pattern3IfPhi に似ている）
• ExitContract: has_break=true
• chosen: Pattern2Break（ExitContract が決定）
• notes: "if-else structure with break in else branch"（構造特徴を記録）

出力先マッピング

出力先	条件	用途
error_tags	chosen.is_none()	Fail-Fast のエラーメッセージ
contract_checks	debug build + 契約違反時	Phase 135 P1 の verifier に統合
JoinIR dev/debug	joinir_dev_enabled()==true	開発時のルーティング追跡
統計 JSON	将来拡張	Corpus 分析（Skeleton Signature）

error_tags との統合

• RoutingDecision の Fail-Fast 文言は src/mir/join_ir/lowering/error_tags.rs の語彙に寄せる
• 既存のエラータグ（例: error_tags::freeze(...)）を使用し、文字列直書きを増やさない

---

最初の対象ループ: skip_whitespace（受け入れ基準）

対象ファイル

tools/selfhost/test_pattern3_skip_whitespace.hako

loop(p < len) {
  local ch = s.substring(p, p + 1)
  local is_ws = ... // whitespace 判定
  if is_ws == 1 {
    p = p + 1
  } else {
    break
  }
}

Skeleton 差分

フィールド	値
steps[0]	HeaderCond { expr: p < len }
steps[1]	Body { ... } (ch, is_ws 計算)
steps[2]	BreakCheck { cond: is_ws == 0 }
steps[3]	Update { carrier: "p", ConstStep(1) }
carriers[0]	{ name: "p", role: Counter, ConstStep }
exits	{ has_break: true, break_has_value: false }

必要 Capability

• ✅ ConstStepIncrement (p = p + 1)
• ✅ SingleBreakPoint (else { break } のみ)
• ✅ OuterLocalCondition (p, len は外側定義)
• ✅ ExitBindingsComplete (p を境界に渡す)

受け入れ基準

1. LoopCanonicalizer::canonicalize(ast) が上記 Skeleton を返す
2. RoutingDecision.chosen == Some(Pattern3)
3. RoutingDecision.missing_caps == []
4. 既存 smoke phase135_trim_mir_verify.sh が退行しない

---

追加・変更チェックリスト

• 追加するループ形を最小 fixture に落とす（再現固定）
• LoopSkeleton の差分（steps/exits/carriers）を明示する
• 必要 Capability を列挙し、未達は Fail-Fast（理由が出る）
• 既存 smoke/verify が退行しない（quick は重くしない）
• 新規 Capability は先に loop-canonicalizer.md に追記してから実装