hakorune/docs/development/current/main/design/control-tree.md

ControlTree / StepTree（構造SSOT）

Status: SSOT（design / vocabulary）
Scope: AST の“構造”だけを表現し、JoinIR/MIR の値・PHI・ブロックを一切持たない。

目的:

• ループ/if の ネスト構造を SSOT として持ち、pattern/policy の増殖先を「構造」側へ寄せる。
• LoopSkeleton（loop_canonicalizer の骨格）を壊さずに、“次の一般化”の受け皿を追加する。

基本方針（禁止事項）

StepTree は「制御構造の形」だけを表す。

禁止（混ぜない）:

• ValueId / BlockId / PHI / JoinInst / MirInstruction など、値やCFGの概念
• backend 依存の最適化・型情報
• “動くための lowering” ロジック（生成・変換）

許可（持ってよいもの）:

• AST の最小要約（条件の形 / 文の種類 / span など）
• Capability / Feature（例: has_loop, has_if, has_return などの分類）

用語

ControlTree

StepTree（後述）を含む、構造SSOTの総称。将来 “BlockTree / BoundaryTree” 等を追加しても、値は持たない。

StepTree

AST を「構造ノード」に落とした木（または木＋Block列）で、次のノード種別を持つ:

• Block: 文の列（順序を保持）
• If: cond と then/else の Block
• Loop: cond と body の Block
• Stmt: 構造化していない文（Local/Assign/Return/Break/Continue/Expr などを tag 化）

StepTreeContract（構造契約SSOT）

StepTreeContract は「この構造が何を含み、何を要求するか」を最小の契約として宣言する。 lowering/PHI/CFG の判断にはまだ使わない（dev-only）だが、再解析の増殖を防ぐための SSOT になる。

最小フィールド案（P1）:

• exits: return / break / continue の存在（構造だけ）
• writes: 変数への書き込み（最小は Assignment target=Variable(name) と Local 宣言の集合）
• required_caps: capability 宣言（例: NestedLoop, TryCatch, Throw, Lambda など）
• cond_sig: if/loop 条件式の要約（下記）

cond_sig の方針（SSOT）

• cond_sig は ASTNode 参照を保持しない（巨大化・ライフタイム・clone コストの問題を避ける）。
• cond_sig は summary（要約）SSOT とし、AstSummary 相当の安定表現に固定する。
  • 目的は「構造分類/契約の固定」であり、式同値（完全な等価判定）は非対象。
• StepTree は当面 観測/分類の SSOT（dev-only） として運用する。
  • 将来 StepTree→Normalized（env+継続）を “本番導線” にする場合は、cond の lowering 用に AstExprId 等を保持する 別SSOT（例: StepTreeRef）を追加し、cond_sig は署名/ログ用途として維持する。

StepTreeSignature（構造署名）

StepTreeSignature は StepTreeContract + node kinds の “安定な基底文字列” を hash した識別子。

用途:

• dev-only ログの検索キー
• “同型ループ/同型if” の増殖検知（再解析の増殖防止）

注意:

• Span 等の位置情報は signature に含めない（入力差でブレるため）。

Capability（段階投入のSSOT）

StepTree は capability を“宣言”し、未対応は Fail-Fast（dev-only / strict） で止める。

想定する段階（例）:

1. if-only（ネストifまで）: Phase 110 P1
2. loop-in-if / if-in-loop: Phase 111+（予定）
3. nested loop: capability guard のまま（別Phaseで解禁）

位置づけ（LoopSkeleton との関係）

• LoopSkeleton（loop_canonicalizer）: loop 1個の骨格を正規化して、JoinIR に渡せる形へ整える。
• StepTree（control_tree）: 関数/ブロック全体の“構造”をSSOT化し、ネスト対応の入口を提供する。

両者は競合しない:

• LoopSkeleton は “loop単体の正規化” が責務
• StepTree は “構造の観測と分類” が責務（値やCFGを持たない）

デバッグ出力（dev-only）

• 既定では出さない（既定挙動不変）。
• NYASH_JOINIR_DEV=1 のときのみ StepTree をダンプする（prefix は [trace:dev] control_tree/step_tree）。
• StepTree は routing の入力にしない（当面は parity/観測のみ。routing SSOT は feature extractor + analyzer）。