docs(router): Phase 282 P0+P1 - Router shrinkage SSOT + entrypoint logging

P0: Documentation SSOT (~80 lines added)
- Router Responsibilities SSOT (DOES/DOESN'T split)
- Ok(None)/Err boundary rules (Fail-Fast principle)
- Entrypoint table (Plan/JoinIR/None, 収束先明記)
- Pattern番号 = 症状ラベル定義(最小記述)

P1: Minimal Code (~10 lines)
- 4 trace statements modified (router.rs)
- Entrypoint-based logging (route=plan/joinir/none)
- Pattern names preserved (backward compatible)
- No new environment variables (既存trace機構のみ)

Test Results:
- quick profile: 45 PASS / 1 FAIL (既知failure)
- Pattern6 VM: PASS (phase258_p0_index_of_string_vm.sh)
- Pattern6 LLVM: PASS (phase258_p0_index_of_string_llvm_exe.sh)
- Zero regression 

Phase 282 Goal Achieved:
- Router shrinkage complete (SSOT positioning clear)
- Pattern numbers → symptom labels transition documented
- CFG construction converges to emit_frag() SSOT
This commit is contained in:
2025-12-23 05:03:25 +09:00
parent a744be929a
commit 519e58a977
2 changed files with 134 additions and 4 deletions

View File

@ -0,0 +1,129 @@
# Phase 282: Router Shrinkage (pattern番号の症状ラベル化)
Status: Planned (design-first)
Goal:
- pattern番号Pattern1/2/…)を “症状ラベル(テスト名)” に縮退させ、router の責務を「抽出の配線」へ収束させる。
- CFG 構築は `Frag/ExitKind` 合成 SSOT`compose::*` + `emit_frag()`)へ一本化する。
## SSOT References
- Frag/emit SSOT: `docs/development/current/main/design/edgecfg-fragments.md`
- Composition SSOT: `src/mir/builder/control_flow/edgecfg/api/compose.rs`
- JoinIR overview: `docs/development/current/main/joinir-architecture-overview.md`
- Plan linePattern6/7: `docs/development/current/main/phases/phase-273/README.md`
- Composition adoptionPattern6/7: `docs/development/current/main/phases/phase-281/README.md`
## Problem
pattern番号が router の分岐点として肥大化すると、以下が起きる:
- “認識extract” と “CFG構築lower” が混ざる
- 分岐の追加が雪だるま式に増える実質、2つ以上のコンパイラを育てる
- 収束先SSOTが曖昧になり、バグ修正の導線が折れる
## Target Shape (SSOT)
router の役割をここまで縮退させる:
- **やる**: Extractor の列挙、Ok(None)/Err の境界管理、Plan/JoinIR の入口選択
- **やらない**: CFG構築のディテール、terminator 生成、推測 fallback
CFG構築は以下に収束させる
- Plan line: `Extractor → DomainPlan → Normalizer → CorePlan → Lowerer → emit_frag()`
- JoinIR line: `cf_loop → (必要な抽出) → Frag composition → emit_frag()`
## P0 (docs-only) — SSOT 固定
- router の責務/禁止事項を明文化by-name hardcode禁止、silent fallback禁止
- "pattern番号の意味" を SSOT として定義(テスト名/症状ラベル)
- 入口リンクを `10-Now.md` に固定
### Router Responsibilities SSOT
**Router がやること**:
1. Extraction 戦略の列挙Plan-based, JoinIR table-based
2. Extractor を優先順で呼び出しPlan line → JoinIR table
3. Ok(None)/Err の境界管理Fail-Fast原則
4. Entrypoint の選択Plan line vs JoinIR line
5. Routing 決定のログ出力debug mode のみ、既存 trace 機構)
**Router がやらないこと**(禁止事項):
1. CFG 構築block 割り当て、PHI 挿入、terminator 生成)
2. Pattern 固有の lowering ロジックNormalizer/Lowerer に委譲)
3. Silent fallbackエラーは明示的に
4. By-name hardcode関数名マッチング禁止、debug 以外)
5. Mock path fallbacktest 専用パターンの本番使用禁止)
**Pattern 番号 = 症状ラベル**Phase 280 SSOT positioning:
- ✅ 正しい用途: テスト名(`loop_if_phi.hako` → Pattern3_WithIfPhi、debug ログ
- ❌ 禁止: CFG 分岐(`if pattern == 6 then ...`)、アーキテクチャ SSOTFrag composition が SSOT
**Detection 戦略**(簡潔版、詳細は P2+ で補完):
- **ExtractionBased**Pattern6,7,8: extract() 成功 → matchSSOT 単一)
- **StructureBased**Pattern1-5,9: ctx.pattern_kind チェックlegacy、2 つの SSOT
**SSOT 参照**:
- Frag composition: `src/mir/builder/control_flow/edgecfg/api/compose.rs`
- Plan line: `src/mir/builder/control_flow/plan/normalizer.rs`
- Terminator 生成: `emit_frag()` (Phase 267)
### Ok(None)/Err Boundary Rules
**Fail-Fast 原則**:
- `Ok(None)`: Extraction がパターンに一致しなかった(次を試す)
- `Err(String)`: Extraction が一致したが検証失敗(即座に fail
- **禁止**: Close-but-unsupported → Ok(None)Err で返すべき)
**例**:
```rust
// ✅ 正しい: 一致しない
extract_scan_with_init_plan() Ok(None) // 次のパターンを試す
// ✅ 正しい: 一致したが非サポート
extract_scan_with_init_plan() Err("P1 scope: reverse scan not supported")
// ❌ 禁止: Silent fallback
extract_scan_with_init_plan() Ok(None) for unsupported cases
// (非サポートケースを Ok(None) で返してはいけない)
```
**境界の位置**router.rs 実装):
- Plan linelines 310-337, 341-368: extract → match → Normalize → Verify → Lower
- JoinIR tablelines 376-382: can_lower → lower
- No matchlines 384-395: Ok(None) を caller に返すErr ではない)
### Entrypoint Table
| Entrypoint | Entry Condition | Patterns | SSOT Downstream |
|------------|----------------|----------|-----------------|
| **Plan line** | extract_*_plan() が Ok(Some) | Pattern6/7 | Normalizer → CorePlan → Lowerer → emit_frag |
| **JoinIR table** | LOOP_PATTERNS 反復 | Pattern1-5,8-9 | cf_loop 抽出 → Frag composition → emit_frag |
| **No match** | すべての extract が Ok(None) | (none) | Err を caller に返す |
**Plan line の責務**Phase 273 SSOT:
1. **Extraction**: extract_*_plan()pure、builder 不要)
2. **Normalization**: PlanNormalizerpattern 知識の展開)
3. **Verification**: PlanVerifierfail-fast 検証)
4. **Lowering**: PlanLowererblock/value 割り当て + Frag composition
5. **Emission**: emit_frag()terminator SSOT
**JoinIR table の責務**Phase 194+ table-driven:
1. **Detection**: can_lower()structure-based、ctx.pattern_kind
2. **Extraction**: cf_loop 抽出
3. **収束先**: Frag composition → emit_frag内部パイプライン詳細は最小化
**収束先の統一**Phase 282 Goal:
- すべての entrypoint が最終的に `emit_frag()` に収束terminator 生成の SSOT
- CFG 構築の詳細は router が持たない(抽出の配線のみ)
## P1 (code, minimal) — 配線の可視化
- router に “経路ログ” を追加既定OFF、debugのみに限定
- pattern番号ではなく “entrypointPlan/JoinIR” をログの主語にする
## Acceptance (Phase 282)
- router の責務が docs で SSOT 化されている
- router の変更が「extractor配線」のみになっているCFG構築の詳細を持たない
- 既存の VM/LLVM smokes に退行がない