From c5ab95d082b6f2d535dd5f46ca371cb4c4e54fa2 Mon Sep 17 00:00:00 2001
From: Selfhosting Dev <selfhost@example.invalid>
Date: Sat, 20 Sep 2025 01:15:26 +0900
Subject: [PATCH] docs(cf/pattern): add ControlFlowBuilder and PatternBuilder
 guides; reference from If/Match normalization; plan updated in CURRENT_TASK

---
 CURRENT_TASK.md                    |  2 +
 docs/guides/controlflow-builder.md | 59 ++++++++++++++++++++++++++++++
 docs/guides/if-match-normalize.md  |  4 ++
 docs/guides/pattern-builder.md     | 32 ++++++++++++++++
 4 files changed, 97 insertions(+)
 create mode 100644 docs/guides/controlflow-builder.md
 create mode 100644 docs/guides/pattern-builder.md

diff --git a/CURRENT_TASK.md b/CURRENT_TASK.md
index 551225fe..0293e3d9 100644
--- a/CURRENT_TASK.md
+++ b/CURRENT_TASK.md
@@ -56,6 +56,7 @@ Next (short)
 - Docs: enrich `docs/guides/loopform.md` with carrier examples and JSON builder snippets.
 - If/Match normalization pass: canonical If join with single PHI group and Match→If‑chain (scrutinee once, guard fused), expression results via join var.
 - ScopeBox (compile-time meta): design + docs; no-op macro scaffold; MIR hint names (no-op) and plan for zero-cost stripping.
+- ControlFlowBuilder/PatternBuilder docs and scaffolding: author APIs for If/Match normalization and pattern conditions; migrate macros to use them.
 
 Action Items (next 48h)
 - [x] Enable sugar by default (array/map literals)
@@ -64,6 +65,7 @@ Action Items (next 48h)
 - [ ] LoopForm MVP‑2: two‑vars carrier safe normalization + tests/smokes
 - [ ] LLVM PHI hygiene smoke on LoopForm cases
 - [ ] ScopeBox docs + macro scaffold (no-op) + MIR hint type sketch
+- [ ] ControlFlowBuilder/PatternBuilder docs（本commitで追加）→ スキャフォールド実装 → If/Matchマクロ置換の最初の1本
 
 ## Phase‑16 Outlook
 - MacroCtx (gensym/report/getEnv) and capabilities mapped to `nyash.toml`.
diff --git a/docs/guides/controlflow-builder.md b/docs/guides/controlflow-builder.md
new file mode 100644
index 00000000..8d718323
--- /dev/null
+++ b/docs/guides/controlflow-builder.md
@@ -0,0 +1,59 @@
+# ControlFlowBuilder — If/Match 正規化ビルダー（コンパイル時メタ）
+
+目的
+- If/Match の正規化（join 変数導入・scrutinee 一回評価・ガード合成・単一 PHI 群）を安全に一貫化するためのビルダー。
+- 生成物は AST JSON v0 の文字列（マクロ内で使用）。実行時コストはゼロ。
+
+設計原則
+- 合流点は必ず join 変数（gensym）で収束（空 PHI を避け、PHI は合流ブロック先頭へ誘導）。
+- 条件/scrutinee は 1 回だけ評価してローカルへ束ねる。
+- 構造は If/Match → If 連鎖（パターン条件は PatternBuilder で構築）。
+
+想定 API（MVP）
+- if_stmt(cond_json, then_stmts_json[], else_stmts_json[]|null) -> If ノード文字列
+- if_expr(cond_json, then_expr_json, else_expr_json, res_name) -> statements_json[]
+  - [ Local(res), If(assign res in both branches) ] を返す
+- match_stmt(scrut_json, arms[]) -> statements_json[]
+- match_expr(scrut_json, arms[], res_name) -> statements_json[]
+  - arms: [{ cond_json, guard_json|null, body_expr_json }]
+  - cond_json は PatternBuilder で組み立てる（OR/型チェック等）
+
+使用例（式 If）
+```
+local JB = include "apps/lib/json_builder.nyash"
+local CF = include "apps/lib/cf_builder.nyash"   // 実装後に利用
+
+local cond = JB.binary("<", JB.variable("a"), JB.variable("b"))
+local then_e = JB.literal_int(10)
+local else_e = JB.literal_int(20)
+local stmts = CF.if_expr(cond, then_e, else_e, "__res0")
+// stmts を元の位置にスプライス（Program 配列へ結合）
+```
+
+使用例（式 Match）
+```
+local JB = include "apps/lib/json_builder.nyash"
+local CF = include "apps/lib/cf_builder.nyash"
+local PT = include "apps/lib/pattern_builder.nyash"
+
+local scrut = JB.variable("x")
+local c_small = PT.or_([ PT.eq(JB.literal_int(0)), PT.eq(JB.literal_int(1)) ])
+local arms = [
+  { cond_json: c_small, guard_json: JB.variable("small"), body_expr_json: JB.literal_string("small") },
+  { cond_json: PT.type_is("IntegerBox", scrut), guard_json: null,
+    body_expr_json: /* toString(as_int(scrut)) を別途構築 */ JB.variable("n_to_string") },
+  { cond_json: PT.default(), guard_json: null, body_expr_json: JB.literal_string("other") },
+]
+local stmts = CF.match_expr(scrut, arms, "__res1")
+```
+
+備考
+- gensym は MacroCtx から受け取る想定（CF 内では与えられた res_name/scrut_name を尊重）。
+- 実装は JsonBuilder を用いてノード文字列を生成。
+- 将来: cond/guard の短絡は既存の BinaryOp(&&,||) へ委譲し、PyVM/LLVM の規約に従う。
+
+関連
+- docs/guides/pattern-builder.md
+- docs/guides/if-match-normalize.md
+- docs/guides/loopform.md
+
diff --git a/docs/guides/if-match-normalize.md b/docs/guides/if-match-normalize.md
index 04fb97b0..21b8d1b5 100644
--- a/docs/guides/if-match-normalize.md
+++ b/docs/guides/if-match-normalize.md
@@ -4,6 +4,10 @@
 - If と Match を“合流点が明確な制御フロー”へ正規化し、MIR/LLVM が一貫した PHI 生成を行えるようにする。
 - ルールをシンプルに保ち、LoopForm（キャリア）と相性良く動作させる。
 
+推奨ビルダー（コンパイル時メタ）
+- ControlFlowBuilder: If/Match の正規化（join 変数・If 連鎖生成）。
+- PatternBuilder: パターン条件（==/OR/AND/型チェック/デフォルト）を構築。
+
 適用タイミング
 - マクロ前展開パスの中で、If/Match 正規化 →（必要に応じて）LoopForm 正規化の順で適用するのが基本。
 - ループ本体に If/Match が含まれていても、If/Match 正規化は局所的に完結する（LoopForm と独立に安全）。
diff --git a/docs/guides/pattern-builder.md b/docs/guides/pattern-builder.md
new file mode 100644
index 00000000..5f023f96
--- /dev/null
+++ b/docs/guides/pattern-builder.md
@@ -0,0 +1,32 @@
+# PatternBuilder — パターン条件ビルダー（コンパイル時メタ）
+
+目的
+- Match/If で用いるパターン条件を安全に構築するビルダー。
+- 生成物は AST JSON v0 の条件式文字列（BinaryOp/TypeOp 等）で、ControlFlowBuilder に渡して If 連鎖へ合成する。
+
+想定 API（MVP）
+- eq(expr_json)                       … scrut == expr
+- or_(conds_json_array)               … c1 || c2 || …
+- and_(conds_json_array)              … g1 && g2 && …
+- type_is(type_name, scrut_json)      … type_check(scrut, type_name)
+- default()                           … デフォルト用マーカー（CF側で末尾へ）
+
+使用例
+```
+local JB = include "apps/lib/json_builder.nyash"
+local PT = include "apps/lib/pattern_builder.nyash"
+
+local scrut = JB.variable("x")
+local p = PT.or_([ PT.eq(JB.literal_int(0)), PT.eq(JB.literal_int(1)) ])
+// guard 付き条件: (p) && small
+local cond = PT.and_([ p, JB.variable("small") ])
+```
+
+注意
+- default() は条件式ではないため、ControlFlowBuilder 側で最後の else に落とす処理を行う。
+- 型チェックは TypeOp(check) の JSON を生成するか、既存の JSON 片を組み立てる（実装詳細に依存）。
+
+関連
+- docs/guides/controlflow-builder.md
+- docs/guides/if-match-normalize.md
+