465 lines
14 KiB
Markdown
465 lines
14 KiB
Markdown
# 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 で段階導入
|