443 lines
14 KiB
Markdown
443 lines
14 KiB
Markdown
# Phase 20.23-20.26 Complete Planning Index
|
||
|
||
**作成日**: 2025-10-30
|
||
**ステータス**: ✅ 完全版計画策定完了
|
||
|
||
---
|
||
|
||
## 📚 Document Structure
|
||
|
||
このディレクトリには Phase 20.23-20.26 の完全計画が含まれています。
|
||
|
||
### 🎯 Start Here（はじめに）
|
||
|
||
1. **[EXECUTIVE_SUMMARY.md](EXECUTIVE_SUMMARY.md)** ⭐ **最優先**
|
||
- 3分で全体像を把握
|
||
- User の critical insight
|
||
- Before/After 比較
|
||
- 主要成果まとめ
|
||
|
||
2. **[TIMELINE_COMPARISON.md](TIMELINE_COMPARISON.md)** ⭐ **視覚的比較**
|
||
- Before/After タイムライン可視化
|
||
- リスク推移グラフ
|
||
- Cost-Benefit 分析
|
||
- Gantt チャート
|
||
|
||
3. **[PHASE_ORDER_ANALYSIS.md](PHASE_ORDER_ANALYSIS.md)** ⭐ **詳細分析**
|
||
- Option A vs B vs C 比較
|
||
- Why Option A is best
|
||
- リスクマトリックス
|
||
- 推奨実装順序
|
||
|
||
---
|
||
|
||
## 📖 Phase-by-Phase Plans
|
||
|
||
### Phase 20.23: Arc/RefCell in Hakorune（2-3週間）
|
||
|
||
**文書**: [README.md](README.md)
|
||
|
||
**概要**:
|
||
- Hakorune 実装（C ではない！）
|
||
- Policy-Data plane separation
|
||
- GcBox pattern 踏襲
|
||
|
||
**削減**: -0 lines（foundation phase）
|
||
**追加**: +100 lines C, +200 lines Hakorune
|
||
**リスク**: LOW ✅
|
||
**期間**: 2-3 weeks
|
||
|
||
**Key Sections**:
|
||
- Executive Summary: Why Hakorune, not C
|
||
- Architecture Design: ArcBox/RefCellBox API
|
||
- Week-by-Week Plan: 実装詳細
|
||
- C Side Minimal API: 100行のみ追加
|
||
|
||
---
|
||
|
||
### Phase 20.24: Parser削除（1-2ヶ月）
|
||
|
||
**文書**: [../phase-20.24/README.md](../phase-20.24/README.md)
|
||
|
||
**概要**:
|
||
- Rust Parser/AST 完全削除
|
||
- Hakorune Parser に完全移行
|
||
- Instant value delivery
|
||
|
||
**削減**: **-10,500 lines** ⚡（-9.0%）
|
||
**リスク**: LOW ✅
|
||
**期間**: 1-2 months
|
||
|
||
**Key Sections**:
|
||
- Deletion Targets: src/parser/, src/ast/
|
||
- Month 1: Gate & Validation
|
||
- Month 2: Deletion & Cleanup
|
||
- Acceptance Criteria: 296/296 tests PASS
|
||
|
||
---
|
||
|
||
### Phase 20.25: Box System + MIR Builder削除（2-3ヶ月）
|
||
|
||
**文書**: [../phase-20.25/README.md](../phase-20.25/README.md)
|
||
|
||
**概要**:
|
||
- MIR Builder/Optimizer/VM/Box System 削除
|
||
- 50% Rust 削減（最大マイルストーン）
|
||
- P0 Blockers 解決必須
|
||
|
||
**削減**: **-22,193 lines** ⚡（-19.0%）
|
||
**累計**: **-32,693 lines**（-28.0%）
|
||
**リスク**: MEDIUM ⚠️（P0 blocker 依存）
|
||
**期間**: 2-3 months
|
||
|
||
**Key Sections**:
|
||
- Month 1: MIR Builder/Optimizer deletion（P0 fixes）
|
||
- Month 2: Rust VM deletion（Bridge-B optimization）
|
||
- Month 3: Box System deletion（Arc/RefCell integration）
|
||
- P0 Blockers: Bridge-B timeout, map_len bug
|
||
|
||
---
|
||
|
||
### Phase 20.26: Final Rust Consolidation（2-3ヶ月）
|
||
|
||
**文書**: [../phase-20.26/README.md](../phase-20.26/README.md)
|
||
|
||
**概要**:
|
||
- Rust 層最終整理
|
||
- hakmem アロケータ統合
|
||
- True Self-Hosting 達成
|
||
|
||
**削減**: **-61,713 lines** ⚡（-52.8%）
|
||
**累計**: **-94,406 lines**（-80.8%）🔥
|
||
**最終状態**: Rust ~5,000 lines（8.3%）
|
||
**リスク**: MEDIUM ⚠️（hakmem integration）
|
||
**期間**: 2-3 months
|
||
|
||
**Key Sections**:
|
||
- Month 1: Audit & Wave 1 deletion（LLVM/WASM）
|
||
- Month 2: Plugin System & Kernel migration
|
||
- Month 3: hakmem integration & Final cleanup
|
||
- Final State: Rust = Floor, Hakorune = House ✅
|
||
|
||
---
|
||
|
||
## 🎯 Critical Documents
|
||
|
||
### For Decision Makers
|
||
|
||
1. **[EXECUTIVE_SUMMARY.md](EXECUTIVE_SUMMARY.md)**
|
||
- High-level overview
|
||
- Key decisions
|
||
- ROI analysis
|
||
- Approval checklist
|
||
|
||
2. **[TIMELINE_COMPARISON.md](TIMELINE_COMPARISON.md)**
|
||
- Visual comparison
|
||
- Cost-benefit analysis
|
||
- Risk progression charts
|
||
|
||
### For Implementers
|
||
|
||
1. **[README.md](README.md)** (Phase 20.23)
|
||
- Week-by-week implementation plan
|
||
- Technical specifications
|
||
- Testing strategy
|
||
|
||
2. **[PHASE_ORDER_ANALYSIS.md](PHASE_ORDER_ANALYSIS.md)**
|
||
- Why this order works
|
||
- Alternative options rejected
|
||
- Risk mitigation strategies
|
||
|
||
### For Reviewers
|
||
|
||
1. All Phase READMEs
|
||
- Detailed acceptance criteria
|
||
- Risk analysis
|
||
- Rollback plans
|
||
|
||
---
|
||
|
||
## 📊 Key Metrics Summary
|
||
|
||
### Duration
|
||
|
||
| Phase | Duration | Cumulative |
|
||
|-------|----------|------------|
|
||
| 20.23 | 2-3 weeks | 2-3 weeks |
|
||
| 20.24 | 1-2 months | 3-4 months |
|
||
| 20.25 | 2-3 months | 5-7 months |
|
||
| 20.26 | 2-3 months | **6-9 months** ✅ |
|
||
|
||
### Lines Deleted
|
||
|
||
| Phase | Lines Deleted | Cumulative | % Reduction |
|
||
|-------|---------------|------------|-------------|
|
||
| 20.23 | -0 | -0 | 0% |
|
||
| 20.24 | -10,500 | -10,500 | -9.0% |
|
||
| 20.25 | -22,193 | -32,693 | -28.0% |
|
||
| 20.26 | -61,713 | **-94,406** | **-80.8%** 🔥 |
|
||
|
||
### Risk Level
|
||
|
||
| Phase | Risk Level | Rationale |
|
||
|-------|-----------|-----------|
|
||
| 20.23 | LOW ✅ | Hakorune implementation, GcBox pattern |
|
||
| 20.24 | LOW ✅ | Complete duplication, well-tested |
|
||
| 20.25 | MEDIUM ⚠️ | P0 blockers, Bridge-B optimization |
|
||
| 20.26 | MEDIUM ⚠️ | hakmem integration, large-scale cleanup |
|
||
|
||
---
|
||
|
||
## 🔥 Critical Insight Impact
|
||
|
||
**User の発見**:
|
||
> "Arc/RefCell はHakoruneスクリプトで実装するやつじゃない？"
|
||
|
||
**Before**: C implementation（2-3 months, HIGH risk）
|
||
**After**: Hakorune implementation（2-3 weeks, LOW risk）
|
||
|
||
**Impact**:
|
||
- ✅ **Time savings**: ~2.5 months（10-11 weeks）⚡
|
||
- ✅ **Risk reduction**: HIGH → LOW
|
||
- ✅ **Complexity reduction**: C low-level → Hakorune script
|
||
- ✅ **Maintainability**: C code → Hakorune code
|
||
- ✅ **Total reduction**: -32,693 → -94,406 lines（**2.9x improvement**）🔥
|
||
|
||
**Pattern**: **Policy（Hakorune）vs Data（C）plane separation**
|
||
|
||
**Precedent**: `lang/src/runtime/gc/gc_box.hako`（既に検証済み）
|
||
|
||
---
|
||
|
||
## 🎯 Recommended Phase Order
|
||
|
||
### **Option A: Arc/RefCell First, Parser Second** ✅ Chosen
|
||
|
||
**Rationale**: Foundation → Value → Major Work → Cleanup
|
||
|
||
**Timeline**:
|
||
```
|
||
Phase 20.23: Arc/RefCell (2-3 weeks) ← Foundation ✅
|
||
Phase 20.24: Parser削除 (1-2 months) ← Value ✅
|
||
Phase 20.25: Box System削除 (2-3 mon) ← Major Work ⚠️
|
||
Phase 20.26: Final Rust削除 (2-3 mon) ← Cleanup ⚠️
|
||
```
|
||
|
||
**Why This Order**:
|
||
1. ✅ Natural dependency flow（Arc/RefCell → Box System）
|
||
2. ✅ Low risk start（2-3週間で基盤確立）
|
||
3. ✅ Consistent momentum（Small → Big → Huge wins）
|
||
4. ✅ Early testing（Box System 時に Arc/RefCell 運用実績あり）
|
||
5. ✅ Simple rollback（各 Phase ごとに checkpoint）
|
||
|
||
**Risk Progression**: **LOW → LOW → MEDIUM → MEDIUM** ✅
|
||
|
||
**Alternative Options**:
|
||
- Option B（Parser First）: ⚠️ Momentum gap（2-3週間停滞）
|
||
- Option C（Parallel Tracks）: ❌ High coordination overhead
|
||
|
||
**Details**: [PHASE_ORDER_ANALYSIS.md](PHASE_ORDER_ANALYSIS.md)
|
||
|
||
---
|
||
|
||
## ✅ Success Criteria
|
||
|
||
### Quantitative Goals
|
||
|
||
- [ ] **Duration**: 6-9 months total
|
||
- [ ] **Lines Deleted**: -94,406 lines（-80.8%）
|
||
- [ ] **Rust Layer**: ≤5,000 lines（8.3%）
|
||
- [ ] **Hakorune Layer**: ~55,000 lines（91.7%）
|
||
- [ ] **Test Coverage**: 296/296 smoke tests PASS
|
||
- [ ] **Performance**: ±10-20% vs original Rust
|
||
|
||
### Qualitative Goals
|
||
|
||
- [ ] **True Self-Hosting**: Rust = Floor, Hakorune = House ✅
|
||
- [ ] **Clean Architecture**: Policy-Data plane separation
|
||
- [ ] **Memory Safety**: hakmem + Arc/RefCell 完全自律
|
||
- [ ] **Maintainability**: Hakorune code > C/Rust code
|
||
- [ ] **Documentation**: Each phase fully documented
|
||
- [ ] **CI Green**: Daily regression tests passing
|
||
|
||
---
|
||
|
||
## 🚨 Critical Risks & Mitigation
|
||
|
||
### Phase-Level Risks
|
||
|
||
| Phase | Critical Risk | Mitigation |
|
||
|-------|--------------|------------|
|
||
| 20.23 | Atomic ops bug | C11 standard, existing patterns |
|
||
| 20.24 | Import cleanup miss | Cargo check + CI |
|
||
| 20.25 | **P0 Blockers** 🔥 | Week 1-2 専任対応 |
|
||
| 20.26 | hakmem stability | Extensive testing, fallback |
|
||
|
||
### P0 Blockers（Most Critical）
|
||
|
||
**Phase 20.25 Week 1-2 Must-Fix**:
|
||
|
||
1. **Bridge-B Timeout** 🔥
|
||
- Current: 60s timeout → no result
|
||
- Target: 300s timeout + heartbeat
|
||
- Priority: **P0 - Blocks everything**
|
||
|
||
2. **map_len Returns 0** 🔥
|
||
- Current: `MapBox.len()` returns 0（expected: 2）
|
||
- Target: Correct value returned
|
||
- Priority: **P0 - Collection tests fail**
|
||
|
||
**Mitigation**:
|
||
- [ ] Dedicated 1-2 week focus（Week 1-2 of Phase 20.25）
|
||
- [ ] No other work until P0 resolved
|
||
- [ ] Escalate if not resolved in 2 weeks
|
||
|
||
---
|
||
|
||
## 📁 File Structure
|
||
|
||
```
|
||
phase-20.23/
|
||
├── INDEX.md ← This file（全体ナビゲーション）
|
||
├── EXECUTIVE_SUMMARY.md ← 3分概要（最優先）
|
||
├── TIMELINE_COMPARISON.md ← 視覚的比較（Gantt, charts）
|
||
├── PHASE_ORDER_ANALYSIS.md ← 詳細分析（Option A vs B vs C）
|
||
└── README.md ← Phase 20.23 実装計画
|
||
|
||
phase-20.24/
|
||
└── README.md ← Phase 20.24 実装計画（Parser削除）
|
||
|
||
phase-20.25/
|
||
└── README.md ← Phase 20.25 実装計画（Box System削除）
|
||
|
||
phase-20.26/
|
||
└── README.md ← Phase 20.26 実装計画（Final Rust削除）
|
||
```
|
||
|
||
---
|
||
|
||
## 🔗 Related Documents
|
||
|
||
### Prerequisites（前提フェーズ）
|
||
|
||
- **Phase 20.20**: [C ABI Export via LLVM](../phase-20.20/README.md)
|
||
- **Phase 20.21**: [Manual Memory Management](../phase-20.21/README.md)
|
||
- **Phase 20.22**: [String/Array C-ABI](../phase-20.22/README.md)
|
||
|
||
### Reference Materials
|
||
|
||
- **Rust Removal Roadmap**: [rust-removal-comprehensive-roadmap.md](../../../development/analysis/rust-removal-comprehensive-roadmap.md)
|
||
- **GcBox Pattern**: `lang/src/runtime/gc/gc_box.hako`
|
||
- **hakmem PoC**: `apps/experiments/hakmem-poc/`
|
||
- **Bridge-B Implementation**: `src/backend/mir_interpreter/exec.rs:297-338`
|
||
- **Hakorune VM**: `lang/src/runtime/vm/`
|
||
|
||
---
|
||
|
||
## 🎉 Expected Final State
|
||
|
||
### Before Phase 20.23
|
||
|
||
```
|
||
┌────────────────────────────────────────────────┐
|
||
│ Rust Layer: 99,406 lines (85.1%) │
|
||
│ ├── Parser/AST (10,500) │
|
||
│ ├── MIR Builder/Optimizer (3,800) │
|
||
│ ├── Rust VM (2,393) │
|
||
│ ├── Box System (16,000) │
|
||
│ ├── LLVM/WASM backends (6,751) │
|
||
│ ├── Plugin System (10,000) │
|
||
│ ├── Kernel (8,000) │
|
||
│ └── Other (41,962) │
|
||
└────────────────────────────────────────────────┘
|
||
|
||
Hakorune Layer: 17,435 lines (14.9%)
|
||
|
||
Ratio: 85% Rust : 15% Hakorune
|
||
```
|
||
|
||
### After Phase 20.26
|
||
|
||
```
|
||
┌────────────────────────────────────────────────┐
|
||
│ Rust Layer: ~5,000 lines (8.3%) ✅ │
|
||
│ ├── HostBridge API (~500) │
|
||
│ ├── CLI Minimal (~1,000) │
|
||
│ ├── hakmem Binding (~500) │
|
||
│ └── Essential MIR Types (~3,000) │
|
||
└────────────────────────────────────────────────┘
|
||
|
||
┌────────────────────────────────────────────────┐
|
||
│ Hakorune Layer: ~55,000 lines (91.7%) ✅ │
|
||
│ ├── Compiler (12,000) │
|
||
│ ├── VM (5,000) │
|
||
│ ├── Box System (15,000) │
|
||
│ ├── Plugin System (5,000) │
|
||
│ ├── Kernel (5,000) │
|
||
│ ├── Standard Library (10,000) │
|
||
│ └── Other (3,000) │
|
||
└────────────────────────────────────────────────┘
|
||
|
||
hakmem (C): ~6,500 lines
|
||
|
||
Ratio: 8% Rust : 92% Hakorune : Minimal C ✅
|
||
```
|
||
|
||
**Achievement**: ✅ **True Self-Hosting** - Rust = Floor, Hakorune = House
|
||
|
||
---
|
||
|
||
## 🚀 Next Steps
|
||
|
||
### Immediate（Week 1）
|
||
|
||
1. [ ] **Review all documents** with stakeholders
|
||
2. [ ] **Approve Phase 20.23** commencement
|
||
3. [ ] **Set up tracking** (GitHub milestones, issues)
|
||
4. [ ] **Kickoff meeting** with team
|
||
|
||
### Phase 20.23 Start（Week 1-3）
|
||
|
||
1. [ ] Week 1: C data plane implementation
|
||
2. [ ] Week 2: Hakorune policy plane implementation
|
||
3. [ ] Week 3: Integration & testing
|
||
4. [ ] Checkpoint: Arc/RefCell complete ✅
|
||
|
||
### Beyond（Month 2+）
|
||
|
||
- [ ] Phase 20.24: Parser削除
|
||
- [ ] Phase 20.25: Box System削除
|
||
- [ ] Phase 20.26: Final Rust削除
|
||
- [ ] **Completion**: True Self-Hosting ✅
|
||
|
||
---
|
||
|
||
## 📞 Questions & Clarifications
|
||
|
||
**Have questions?** Check these resources:
|
||
|
||
1. **High-level overview**: [EXECUTIVE_SUMMARY.md](EXECUTIVE_SUMMARY.md)
|
||
2. **Visual timeline**: [TIMELINE_COMPARISON.md](TIMELINE_COMPARISON.md)
|
||
3. **Detailed analysis**: [PHASE_ORDER_ANALYSIS.md](PHASE_ORDER_ANALYSIS.md)
|
||
4. **Implementation details**: Each Phase's README.md
|
||
|
||
**Still unclear?** Contact plan author for clarification.
|
||
|
||
---
|
||
|
||
## ✅ Approval Status
|
||
|
||
- [ ] **Documents reviewed**: Executive Summary + Timeline + Phase Order Analysis
|
||
- [ ] **Phase READMEs reviewed**: 20.23, 20.24, 20.25, 20.26
|
||
- [ ] **Risks understood**: P0 blockers, hakmem integration
|
||
- [ ] **Resources confirmed**: 1 team, 6-9 months
|
||
- [ ] **Rollback plan accepted**: Git tags, backup branches
|
||
- [ ] **Go/No-Go decision**: [ ] GO [ ] NO-GO
|
||
|
||
---
|
||
|
||
**Created**: 2025-10-30
|
||
**Status**: ✅ Complete plan ready for approval
|
||
**Recommendation**: **Approve and commence Phase 20.23** ✅
|
||
**Expected Completion**: May-Aug 2026（6-9 months from start）
|