From bf9a63c53f4b98f05efd6079415db8d8970fb415 Mon Sep 17 00:00:00 2001 From: tomoaki Date: Mon, 29 Dec 2025 16:01:26 +0900 Subject: [PATCH] docs(phase29al): ssot skeleton/feature model; planfrag freeze tag --- CURRENT_TASK.md | 3 + docs/development/current/main/10-Now.md | 8 +- docs/development/current/main/30-Backlog.md | 7 +- .../design/coreplan-skeleton-feature-model.md | 100 ++++++++++++++++++ .../main/design/planfrag-freeze-taxonomy.md | 3 + .../main/design/planfrag-ssot-registry.md | 1 + .../P0-SKELETON-FEATURE-SSOT-INSTRUCTIONS.md | 34 ++++++ .../current/main/phases/phase-29al/README.md | 30 ++++++ 8 files changed, 183 insertions(+), 3 deletions(-) create mode 100644 docs/development/current/main/design/coreplan-skeleton-feature-model.md create mode 100644 docs/development/current/main/phases/phase-29al/P0-SKELETON-FEATURE-SSOT-INSTRUCTIONS.md create mode 100644 docs/development/current/main/phases/phase-29al/README.md diff --git a/CURRENT_TASK.md b/CURRENT_TASK.md index aa7c6f44..7e0bd898 100644 --- a/CURRENT_TASK.md +++ b/CURRENT_TASK.md @@ -42,6 +42,9 @@ Pattern1 guard を single_planner から撤去し、planner/facts 側 SSOT と f **2025-12-29: Phase 29ak P5 COMPLETE (planner candidate ctx gate)** Pattern1/8 の候補抑制を planner 側に集約し、single_planner の Pattern1 抑制を撤去。 +**2025-12-29: Phase 29al P0 COMPLETE (Skeleton/Feature model SSOT, docs-only)** +CorePlan を骨格→特徴→合成で説明する SSOT を追加し、Freeze taxonomy に unstructured を追加。 + **2025-12-29: Phase 29aj P10 COMPLETE (single_planner unified shape)** single_planner を全パターンで planner-first → extractor フォールバックの共通形に統一（挙動不変）。 diff --git a/docs/development/current/main/10-Now.md b/docs/development/current/main/10-Now.md index 468d94a3..7c8cc882 100644 --- a/docs/development/current/main/10-Now.md +++ b/docs/development/current/main/10-Now.md @@ -1,11 +1,15 @@ # Self Current Task — Now (main) -## Current Focus: Phase 29ak（PlanRuleOrder + PlannerContext） +## Current Focus: Phase 29al（CorePlan composition hardening / docs-first） -Next: Phase 29ak P6（TBD） +Next: Phase 29al P1（post-phi final form SSOT） 運用ルール: integration filter で phase143_* は回さない（JoinIR 回帰は phase29ae pack のみ） 運用ルール: phase286_pattern9_* は legacy pack (SKIP) を使う +**2025-12-29: Phase 29al P0 完了** ✅ +- 目的: Skeleton/Feature model を SSOT 化し、「通らない/危険」形を Freeze taxonomy に落とす（仕様不変） +- SSOT: `docs/development/current/main/design/coreplan-skeleton-feature-model.md` + **2025-12-29: Phase 29ak P5 完了** ✅ - 目的: planner の candidate gate を SSOT 化し、single_planner の Pattern1 抑制を撤去（仕様不変） - 実装: `src/mir/builder/control_flow/plan/planner/build.rs` / `src/mir/builder/control_flow/plan/planner/outcome.rs` / `src/mir/builder/control_flow/plan/single_planner/rules.rs` diff --git a/docs/development/current/main/30-Backlog.md b/docs/development/current/main/30-Backlog.md index 4bea4d99..b2162023 100644 --- a/docs/development/current/main/30-Backlog.md +++ b/docs/development/current/main/30-Backlog.md @@ -27,7 +27,12 @@ Related: - **Phase 29ak（candidate）: PlanRuleOrder SSOT + PlannerContext plumbing** - 入口: `docs/development/current/main/phases/phase-29ak/README.md` - 状況: P0/P1/P2/P3/P4/P5 ✅ 完了 - - Next: Phase 29ak P6（TBD） + - Next: None（phase-29al へ） + +- **Phase 29al（candidate）: CorePlan composition hardening (docs-first)** + - 入口: `docs/development/current/main/phases/phase-29al/README.md` + - 状況: P0 ✅ 完了（docs-only） + - Next: P1（post-phi final form SSOT）/ P2（effect classification SSOT） - **Phase 29ai（candidate）: Plan/Frag single-planner（Facts SSOT）** - 入口: `docs/development/current/main/phases/phase-29ai/README.md` diff --git a/docs/development/current/main/design/coreplan-skeleton-feature-model.md b/docs/development/current/main/design/coreplan-skeleton-feature-model.md new file mode 100644 index 00000000..49922f1d --- /dev/null +++ b/docs/development/current/main/design/coreplan-skeleton-feature-model.md @@ -0,0 +1,100 @@ +--- +Status: SSOT +Scope: Facts→Planner→(DomainPlan→CorePlan) の「非重複」設計（JoinIR/Plan/Frag） +Related: +- docs/development/current/main/design/planfrag-ssot-registry.md +- docs/development/current/main/design/planfrag-freeze-taxonomy.md +- docs/development/current/main/design/joinir-plan-frag-ssot.md +- docs/development/current/main/design/join-explicit-cfg-construction.md +--- + +# CorePlan Skeleton/Feature Model (SSOT) + +目的: “pattern 列挙の重なり” を増やさずに、Facts→Planner→CorePlan を **一意・合成可能**な形に収束させる。 + +結論: +- **CorePlan は構造SSOT**（emit/merge は CorePlan/Frag 以外を再解析しない） +- **DomainPlan は意図（recipe）**（長期的に縮む。SSOTは CorePlan 側に寄せる） +- “Pattern” は入口の分岐名ではなく、**(Skeleton, FeatureSet)** の合成へ落とす + +## 1. Skeleton（骨格）= まず一意に決める + +Skeleton は “構造カテゴリ” のみ。ここが一意に決まらない場合は `Freeze` の対象。 + +推奨の最小集合: +- `LoopSkeleton`（自然ループ: header/latch/exit が確定できる） +- `If2Skeleton`（2分岐 + join） +- `BranchNSkeleton`（match/switch 相当: N分岐 + join） +- `StraightLine`（plan 対象外 → `Ok(None)`） + +## 2. Features（直交特徴）= 骨格の上に足す + +Features は “別パターン” を増やさずに足す（重なりの根治）。 + +例（代表）: +- `ExitMap`（Return/Break/Continue の出口集合。Pattern2/4/5 を “別pattern” にしない） +- `ValueJoin`（join 値が必要 = post-phi 表現） +- `ContinueEdges`（continue が複数箇所から飛ぶ等。latch 一意に拘らない表現） +- `Cleanup`（return/break/continue で走る cleanup。将来 `Unwind` も同語彙へ） +- `CondShape` / `StepShape`（normalize 済みの “形”） +- `AlgorithmIntent`（scan/split/predicate 等のアルゴリズム意図: DomainPlan に残して良い） + +## 3. Freeze（Fail-Fast）にすべき “要注意パターン” + +“通らない” または “通るが設計が壊れやすい” を SSOT として明示する。 + +### A. Unstructured CFG（Irreducible / multi-entry loop） + +症状: +- Skeleton が一意に決まらない（複数入口ループ / irreducible） + +扱い: +- `Freeze(unstructured)`（strict/dev は即Fail） +- 既定挙動を変えない場合は `Ok(None)` に落とすのも可だが、strict/dev では **タグ付きで理由を観測**する + +### B. Unwind / 例外 / finally（“別系統の出口エッジ”） + +症状: +- Return/Break/Continue 以外の出口（unwind）で cleanup が必要になる + +扱い: +- 設計として `ExitKind::Unwind` を想定し、`ExitMap + Cleanup` で吸収できることを前提にする +- 未実装の段階では `Freeze(unsupported:unwind)`（“対象っぽいのにNone” にしない） + +### C. Coroutine / async generator（yield） + +症状: +- 関数内で制御が閉じない（skeleton だけでは表現できない） + +扱い: +- `Freeze(unsupported:coroutine)`（将来は別 Skeleton/別パイプライン） + +### D. 多分岐（match）を If2 で潰そうとする + +症状: +- planner が肥大化し、normalize が崩れる（pattern 爆発の起点） + +扱い: +- `BranchNSkeleton` を設計語彙として追加し、normalize で分岐順序を安定化する + +### E. “plan が JoinIR 専用パターンを飲み込む” 事故 + +実例: +- nested loop（phase1883）が plan 側の Pattern1 に誤マッチして JoinIR の `Pattern6NestedLoopMinimal` が選ばれない + +扱い: +- “より一般的な pattern” は **上位形（nested loop 等）を `Ok(None)` へ倒す**（pattern 側の責務） +- 入口での by-name 分岐ではなく、Facts/Extractor の **構造条件**で遮断する + +## 4. SSOT 運用ルール（設計側の約束） + +- Planner は “骨格推論→特徴推論” を意識して実装し、complete pattern 追加を最小化する +- Emit は CorePlan 以外を見ない（再解析禁止） +- `Ok(None)` / `Freeze` の境界は `docs/.../planfrag-freeze-taxonomy.md` を SSOT として従う + +## 5. Next (docs-first) + +次に SSOT として固める候補（レバレッジ順）: +1. post-phi（join 入力の最終表現）不変条件（局所 verify） +2. effect 分類（pure/control/rc/obs）と “許される変形” の法典 + diff --git a/docs/development/current/main/design/planfrag-freeze-taxonomy.md b/docs/development/current/main/design/planfrag-freeze-taxonomy.md index ff5363b8..8c9b80f9 100644 --- a/docs/development/current/main/design/planfrag-freeze-taxonomy.md +++ b/docs/development/current/main/design/planfrag-freeze-taxonomy.md @@ -29,6 +29,8 @@ Scope: Facts → Plan（仕様不変） - 形が契約を破っている（例: 必須 step が欠落、join 入力の整合が崩れている） - `plan/freeze:ambiguous` - 複数候補が成立し、一意化できない（将来のルール追加で解消される可能性がある） +- `plan/freeze:unstructured` + - Skeleton が確定できない（irreducible CFG / multi-entry loop など、構造化CFGの定義域外） - `plan/freeze:unsupported` - 一意に判定できるが、未実装で扱えない（“未対応” を誤って None にしない） - `plan/freeze:bug` @@ -47,3 +49,4 @@ Scope: Facts → Plan（仕様不変） - Entry: `docs/development/current/main/phases/phase-29ai/README.md` - Plan/Frag overview: `docs/development/current/main/design/edgecfg-fragments.md` - Pattern6/7 contracts: `docs/development/current/main/design/pattern6-7-contracts.md` +- CorePlan Skeleton/Feature model: `docs/development/current/main/design/coreplan-skeleton-feature-model.md` diff --git a/docs/development/current/main/design/planfrag-ssot-registry.md b/docs/development/current/main/design/planfrag-ssot-registry.md index 0525bd42..cff36d29 100644 --- a/docs/development/current/main/design/planfrag-ssot-registry.md +++ b/docs/development/current/main/design/planfrag-ssot-registry.md @@ -26,3 +26,4 @@ Scope: JoinIR plan/frag 導線（仕様不変） - Entry: `docs/development/current/main/phases/phase-29ai/README.md` - Plan/Frag overview: `docs/development/current/main/design/edgecfg-fragments.md` - Pattern6/7 contracts: `docs/development/current/main/design/pattern6-7-contracts.md` +- CorePlan Skeleton/Feature model: `docs/development/current/main/design/coreplan-skeleton-feature-model.md` diff --git a/docs/development/current/main/phases/phase-29al/P0-SKELETON-FEATURE-SSOT-INSTRUCTIONS.md b/docs/development/current/main/phases/phase-29al/P0-SKELETON-FEATURE-SSOT-INSTRUCTIONS.md new file mode 100644 index 00000000..ed13f859 --- /dev/null +++ b/docs/development/current/main/phases/phase-29al/P0-SKELETON-FEATURE-SSOT-INSTRUCTIONS.md @@ -0,0 +1,34 @@ +--- +Status: Active +Scope: docs-only（仕様不変） +Related: +- docs/development/current/main/phases/phase-29al/README.md +- docs/development/current/main/design/coreplan-skeleton-feature-model.md +- docs/development/current/main/design/planfrag-ssot-registry.md +- docs/development/current/main/design/planfrag-freeze-taxonomy.md +--- + +# Phase 29al P0: Skeleton/Feature SSOT（docs-only） + +Date: 2025-12-29 +Status: Complete（docs-only） +Scope: 設計SSOTの追加・導線固定（コード変更なし） + +## Objective + +- “pattern が重なる” 問題を、実装テクではなく **設計の約束（SSOT）**で根治する +- Facts→Planner→(DomainPlan→CorePlan) を **骨格→特徴→合成**として説明できる状態にする +- “通らない/危険な形” を Freeze taxonomy に落とし、`Ok(None)` との境界を揺らさない + +## Deliverables + +- `docs/development/current/main/design/coreplan-skeleton-feature-model.md`（SSOT） +- `docs/development/current/main/design/planfrag-ssot-registry.md` に参照追加 +- `docs/development/current/main/design/planfrag-freeze-taxonomy.md` に `plan/freeze:unstructured` を追加 + +## Non-goals + +- コード変更 +- 新しい env var / 新しい恒常ログ +- 新規パターン追加や互換性変更 + diff --git a/docs/development/current/main/phases/phase-29al/README.md b/docs/development/current/main/phases/phase-29al/README.md new file mode 100644 index 00000000..4f86b8e0 --- /dev/null +++ b/docs/development/current/main/phases/phase-29al/README.md @@ -0,0 +1,30 @@ +--- +Status: Active +Scope: JoinIR / PlanFrag “仕上げ”の設計SSOT（仕様不変） +Related: +- docs/development/current/main/design/coreplan-skeleton-feature-model.md +- docs/development/current/main/design/planfrag-ssot-registry.md +- docs/development/current/main/design/planfrag-freeze-taxonomy.md +- docs/development/current/main/design/joinir-plan-frag-ssot.md +--- + +# Phase 29al: CorePlan composition hardening (docs-first) + +Goal: “pattern が重なる/増殖する” を設計で根治し、JoinIR/PlanFrag を **美しく閉じる**ための SSOT を揃える。 + +## P0: Skeleton/Feature model SSOT（docs-only） + +- 指示書: `docs/development/current/main/phases/phase-29al/P0-SKELETON-FEATURE-SSOT-INSTRUCTIONS.md` +- ねらい: “骨格→特徴→合成” を SSOT として固定し、通らない/危険なパターンも Freeze taxonomy に落とす +- 成果: `docs/development/current/main/design/coreplan-skeleton-feature-model.md` + +## Next (planned) + +### P1: post-phi（join 入力の最終表現）SSOT + +- ねらい: join 値の “最終表現” と “局所 verify” の不変条件を SSOT 化する（emit/merge の再解析禁止を強化） + +### P2: effect classification SSOT + +- ねらい: pure/control/rc/observability などの効果分類と、許される変形（最適化/RC挿入/DCE）を法典化する +