tomoaki/hakorune
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5597b78f0de343628f9942fbca0e413005e08aa7
hakorune/docs/private/roadmap/phases/phase-20.23/INDEX.md

14 KiB
Raw Blame History

Phase 20.23-20.26 Complete Planning Index

作成日: 2025-10-30 ステータス: ✅ 完全版計画策定完了

📚 Document Structure

このディレクトリには Phase 20.23-20.26 の完全計画が含まれています。

🎯 Start Here（はじめに）

  1. EXECUTIVE_SUMMARY.md ⭐ 最優先

    • 3分で全体像を把握
    • User の critical insight
    • Before/After 比較
    • 主要成果まとめ

  2. TIMELINE_COMPARISON.md ⭐ 視覚的比較

    • Before/After タイムライン可視化
    • リスク推移グラフ
    • Cost-Benefit 分析
    • Gantt チャート

  3. 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

概要:

  • 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

概要:

  • 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

概要:

  • 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

概要:

  • 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

    • High-level overview
    • Key decisions
    • ROI analysis
    • Approval checklist

  2. TIMELINE_COMPARISON.md

    • Visual comparison
    • Cost-benefit analysis
    • Risk progression charts

For Implementers

  1. README.md (Phase 20.23)

    • Week-by-week implementation plan
    • Technical specifications
    • Testing strategy

  2. 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

✅ 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（前提フェーズ）

Reference Materials

  • Rust Removal Roadmap: 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
  2. Visual timeline: TIMELINE_COMPARISON.md
  3. Detailed analysis: 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）