tomoaki/hakorune
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: restore docs/private/roadmap from 7b4908f9 (Phase 20.31)

Browse Source
This commit is contained in:
nyash-codex
2025-10-31 18:00:10 +09:00
parent 1d49e24bf0
commit 8fd3a2b509
433 changed files with 108935 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

464
docs/private/roadmap/phases/phase-20.6/INDEX.md Normal file
View File

@ -0,0 +1,464 @@
# Phase 20.6 — Index
**VM Core Complete + Dispatch Unification**
Status: Planning
Duration: 12 weeks (2026-03-01 - 2026-05-24)
Prerequisite: Phase 20.5 complete
---
## 📚 Documentation Structure
### Core Documents
1. **[README.md](README.md)** ⭐ START HERE (日本語)
- Phase overview and goals
- Architecture overview (16 instructions + Dispatch)
- Weekly breakdown (Week 1-12)
- Success criteria and DoD
- Risk mitigation
2. **[PLAN.md](PLAN.md)** (English)
- Executive summary (5 lines)
- Phase breakdown (Phase B + Phase C)
- Week-by-week implementation plan
- Golden Test strategy
- CI integration
3. **[CHECKLIST.md](CHECKLIST.md)**
- Week 1-6: VM Core Complete tasks
- Week 7-12: Dispatch Unification tasks
- Golden Test checklist (100+ tests)
- Documentation checklist
4. **[COMPLETION_REPORT.md](COMPLETION_REPORT.md)** (Week 12 deliverable)
- Phase 20.6 results
- Performance measurements
- Lessons learned
- Phase 20.7 recommendations
---
## 🎯 Quick Reference
### What is Phase 20.6? (5-line summary)
1. **Goal**: Complete Hakorune VM Core (16 MIR instructions) + Unify Dispatch (single Resolver path).
2. **Strategy**: Phase B (Week 1-6) = All instructions; Phase C (Week 7-12) = Resolver integration.
3. **Verification**: Golden Tests (100+ cases) ensure Rust-VM vs Hako-VM 100% output parity.
4. **Performance**: Target ≥ 50% of Rust-VM speed (acceptable for PoC, optimize later).
5. **Policy**: Fail-Fast (unknown methods → RuntimeError), no special-case dispatch, Everything is Box.
### Key Deliverables
**Phase B Complete (Week 1-6)**:
1. **MIR Core + Unified Call (MirCall)** in Hakorune:
- const, binop, compare, jump, branch, phi, ret ✅ (from 20.5)
- MirCall(callee=Method|ModuleFunction|Extern|Constructor) ⬜ (Week 3-4)
- load, store, copy, typeop ⬜ (Week 1-2, 5)
- barrier, safepoint, loopform, unaryop ⬜ (Week 6)
2. **Control Flow**:
- Basic blocks
- Branch/jump handling
- PHI node resolution
- Loop detection
3. **Golden Tests**:
- 100+ test cases: Rust-VM vs Hako-VM parity
- All outputs must match exactly
- Performance: Hako-VM ≥ 50% of Rust-VM speed
**Phase C: Dispatch Unification (Week 7-12)**:
1. **Resolver Integration**:
- `Resolver.lookup(type_id, method, arity) -> MethodHandle`
- All method calls go through Resolver
- No special-case dispatch
2. **CallableBox Refactoring**:
- `ExecBox.call_by_handle(handle, args, NoOperatorGuard)`
- Single entry point for all invocations
- Macro desugaring: `arr.methodRef("push",1)` → `Callable.ref_method(arr, :push, 1)`
3. **Universal Route Minimization**:
- Remove pseudo-method implementations
- Everything delegates to Resolver
- Fail-Fast: Unknown methods → RuntimeError
---
## 📊 Timeline at a Glance
| Weeks | Focus | Deliverable |
|-------|-------|-------------|
| 1-2 | Memory Operations | load, store, copy working |
| 3-4 | Unified Call | MirCall(callee=Method/Module/Extern/Constructor) working |
| 5 | Type Operations | typeop working（newはConstructor経由） |
| 6 | Control + Golden Tests | All 16 instructions + 100 tests PASS |
| 7-8 | Resolver Integration | Resolver.lookup working |
| 9-10 | CallableBox Refactoring | ExecBox.call_by_handle working |
| 11 | Route Minimization | Special-case dispatch removed |
| 12 | Integration + Docs | Phase complete, Phase 20.7 planned |
---
## 🏗️ Architecture Overview
### Phase B: MIR Core + Unified Call
```
┌─────────────────────────────────────┐
│ Phase 20.5 Complete (5 instructions)│
│ ✅ const, ret, jump, branch, phi │
│ ✅ binop (Add/Sub/Mul/Div/Mod) │
│ ✅ compare (Eq/Ne/Lt/Le/Gt/Ge) │
├─────────────────────────────────────┤
│ Phase 20.6 Additions (11 instructions)
│ ⬜ load, store, copy (Week 1-2) │
│ ⬜ MirCall (Week 3-4) │
│ ⬜ typeop（newはConstructor） (Week 5)│
│ ⬜ barrier, safepoint, loopform, │
│ unaryop (Week 6) │
└─────────────────────────────────────┘
```
### Phase C: Dispatch Unification
```
Before (multiple dispatch paths):
┌────────────────────────────────────┐
│ Method Call Dispatch │
│ ├─ Global Function (special) │
│ ├─ Box Method (special) │
│ ├─ Closure (special) │
│ ├─ Constructor (special) │
│ └─ Module Function (special) │
└────────────────────────────────────┘
After (single dispatch path):
┌────────────────────────────────────┐
│ Unified Resolver Path │
│ │
│ Resolver.lookup(type_id, method, arity)
│ ↓ │
│ MethodHandle │
│ ↓ │
│ ExecBox.call_by_handle( │
│ handle, args, NoOperatorGuard)│
└────────────────────────────────────┘
```
---
## 🧪 Test Strategy Overview
### Golden Test Pyramid
```
/\
/ \ Integration (30 tests)
/____\ Complex scenarios
/ \
/ \ Functional (70 tests)
/__________\ Individual instruction tests
/ \
/ \ Unit (per-handler)
/________________\ Each handler has dedicated tests
```
### Test Categories
1. **Memory Operations** (10 tests):
- load, store, copy
- Memory aliasing
- Edge cases
2. **Method Calls** (15 tests):
- call (Global/Module/Closure)
- boxcall
- externcall
3. **Type Operations** (10 tests):
- typeop
- newbox
4. **Control Flow** (15 tests):
- barrier, safepoint, loopform
- Branch/jump combinations
5. **Resolver** (20 tests):
- lookup success/failure
- Arity mismatches
- Type not found
6. **Callable** (25 tests):
- call_by_handle
- NoOperatorGuard
- Macro desugaring
7. **Integration** (30 tests):
- Arithmetic
- Control flow
- Collections
- Recursion
- Closures
- Strings
**Total**: 100+ Golden Tests
---
## 📦 Implementation Structure
```
Phase 20.6 Planning:
docs/private/roadmap/phases/phase-20.6/
├── INDEX.md # ← You are here
├── README.md # Phase overview (日本語)
├── PLAN.md # Execution plan (English)
├── CHECKLIST.md # Week-by-week checklist
└── COMPLETION_REPORT.md # (Week 12 deliverable)
Hakorune VM Implementation:
selfhost/hakorune-vm/
├── handlers/ # Week 1-6 deliverables
│ ├── load_handler.hako # Week 1-2
│ ├── store_handler.hako # Week 1-2
│ ├── copy_handler.hako # Week 1-2
│ ├── call_handler.hako # Week 3-4 (Unified MirCall)
│ ├── boxcall_handler.hako # Week 3-4
│ ├── externcall_handler.hako # Week 3-4
│ ├── typeop_handler.hako # Week 5
│ ├── newbox_handler.hako # Week 5
│ ├── barrier_handler.hako # Week 6
│ ├── safepoint_handler.hako # Week 6
│ ├── loopform_handler.hako # Week 6
│ └── unaryop_handler.hako # Week 6
├── resolver/ # Week 7-8 deliverables
│ ├── resolver_box.hako
│ ├── method_handle_box.hako
│ └── type_registry_box.hako
├── callable/ # Week 9-10 deliverables
│ ├── exec_box.hako
│ ├── no_operator_guard_box.hako
│ └── macro_desugar.hako
└── tests/ # Week 1-12
├── golden/ # 100+ tests
│ ├── phase-b/ # Week 1-6
│ │ ├── memory/ # 10 tests
│ │ ├── calls/ # 15 tests
│ │ ├── types/ # 10 tests
│ │ └── control/ # 15 tests
│ ├── phase-c/ # Week 7-12
│ │ ├── resolver/ # 20 tests
│ │ ├── callable/ # 25 tests
│ │ └── unification/ # 30 tests
│ └── integration/ # Week 12
│ ├── arithmetic.hako
│ ├── control_flow.hako
│ ├── collections.hako
│ ├── recursion.hako
│ ├── strings.hako
│ └── closures.hako
└── benchmark/ # Performance tests
├── benchmark_suite.sh
└── performance_report.md
```
---
## 🚀 Quick Start (After Phase Complete)
### Run Golden Tests
```bash
# Run all Golden Tests
bash tools/golden_test_hakorune_vm.sh
# Expected output:
# ✅ phase-b/memory: 10/10 PASS
# ✅ phase-b/calls: 15/15 PASS
# ✅ phase-b/types: 10/10 PASS
# ✅ phase-b/control: 15/15 PASS
# ✅ phase-c/resolver: 20/20 PASS
# ✅ phase-c/callable: 25/25 PASS
# ✅ phase-c/unification: 30/30 PASS
# ✅ integration: 30/30 PASS
# ────────────────────────────────────
# Total: 155/155 PASS (100%)
```
### Run Performance Benchmark
```bash
# Benchmark Hako-VM vs Rust-VM
bash tools/benchmark_hakorune_vm.sh
# Expected output:
# Test: arithmetic.hako
# Rust-VM: 1.2s
# Hako-VM: 2.1s (57% speed) ✅
#
# Test: control_flow.hako
# Rust-VM: 0.8s
# Hako-VM: 1.5s (53% speed) ✅
#
# Average: Hako-VM = 55% of Rust-VM ✅
# Memory: 180MB (< 200MB target) ✅
```
### Use Unified Dispatch
```bash
# Run program with unified dispatch
./target/release/hako --backend vm program.hako
# Debug Resolver
HAKO_RESOLVER_TRACE=1 ./target/release/hako --backend vm program.hako
# Output:
# [resolver] lookup type_id=42 method="push" arity=1 → handle=0x123
# [exec] call_by_handle handle=0x123 args=[value] → OK
```
---
## ⚠️ Prerequisites
### From Phase 20.5
- [x] HostBridge API complete
- [x] op_eq Migration complete (NoOperatorGuard)
- [x] VM Foundations PoC complete (5 instructions)
- [x] Golden Test infrastructure ready
### For Phase 20.6
- [ ] Week 1: Memory operation design approved
- [ ] Week 3: Method call design approved (Unified MirCall)
- [ ] Week 7: Resolver design approved
- [ ] Week 9: CallableBox design approved
---
## 🎯 Success Criteria Summary
### Technical
- [ ] All 16 MIR instructions working
- [ ] Control flow complete (branch, phi, loopform)
- [ ] Golden Tests: 100+ cases ALL PASS
- [ ] Dispatch unified (single Resolver path)
- [ ] Special-case dispatch removed
### Performance
- [ ] Hako-VM ≥ 50% of Rust-VM speed ✅
- [ ] Memory usage < 200MB ✅
- [ ] Compile time < 10s (small programs) ✅
### Quality
- [ ] Test coverage: All instructions covered
- [ ] Documentation: Complete architecture docs
- [ ] Code review: ChatGPT + Claude approved
- [ ] CI: All tests passing
---
## 📚 Related Phases
### Previous
- [Phase 20.5 - VM Foundations](../phase-20.5/)
- HostBridge API
- op_eq Migration
- VM Foundations PoC (5 instructions)
### Next
- **Phase 20.7 - Collections in Hakorune** (8 weeks, 2026-05-25 → 2026-07-19)
- MapBox in Hakorune
- ArrayBox in Hakorune
- Deterministic iteration order
- Performance: ≥ 70% of Rust-Collections
### Parallel
- [Phase 15.78 - Frozen UX Polish](../phase-15.78/)
- Distribution packaging
- Doctor improvements
---
## 💬 Communication
### Weekly Sync Points
- **Monday**: Week start, goal setting
- **Wednesday**: Mid-week progress check
- **Friday**: Week review, performance measurement
### Issue Tracking
- Use GitHub issues with label `phase-20.6`
- Prefix: `[20.6]` in commit messages
- Milestone: `Phase 20.6 - VM Core Complete`
### Review Process
- Each week: Self-review + Golden Tests
- Week 6, 12: Full review with ChatGPT/Claude
- Blocking issues: Immediate escalation
---
## 🔗 External Resources
### Reference Implementations
- **Rust VM**: `/src/backend/mir_interpreter/` (reference implementation)
- **MIR Spec**: [INSTRUCTION_SET.md](../../../../reference/mir/INSTRUCTION_SET.md)
- **Phase 20.5 Roadmap**: [PURE_HAKORUNE_ROADMAP.md](../phase-20.5/PURE_HAKORUNE_ROADMAP.md)
### Related Documents
- [Hakorune VM Discovery](../phase-20.5/HAKORUNE_VM_DISCOVERY.md) - VM implementation analysis
- [HostBridge API Design](../phase-20.5/HOSTBRIDGE_API_DESIGN.md) - C-ABI boundary
- [Op_eq Migration](../phase-20.5/OP_EQ_MIGRATION.md) - NoOperatorGuard pattern
---
## 📝 Notes
### Naming Conventions
- **Phase B**: VM Core Complete (Week 1-6)
- **Phase C**: Dispatch Unification (Week 7-12)
- **Golden Tests**: Rust-VM vs Hako-VM parity tests
- **Resolver**: Single resolution path for all method calls
### File Naming
- Handlers: `{instruction}_handler.hako`
- Tests: `test_{feature}_{case}.hako`
- Golden outputs: `{test}_rust.txt`, `{test}_hako.txt`
### Verification
- Use `diff` for exact output comparison
- Use Golden Test script for automation
- Use benchmark script for performance measurement
---
**Created**: 2025-10-14
**Last Updated**: 2025-10-14
**Status**: Planning (Phase not yet started)
**Phase Start**: 2026-03-01
**Phase End**: 2026-05-24
**Next Review**: 2026-03-01 (Phase start)
5. **ABI（design only）**
- Phase 20.6 では C‑ABI の SSOT/ポリシー/フラグを追加（挙動は不変）
- 実装切替（String/Array/Map）は Phase 20.7 で段階導入