369 lines
8.9 KiB
Markdown
369 lines
8.9 KiB
Markdown
# Phase 20.5 — Milestone (Escape from Rust / Pure Hakorune Strategy)
|
||
|
||
Status: Planning (Pure Hakorune Strategy Adopted; v1.1‑frozen reminted)
|
||
Start: 2025-12-21
|
||
End: 2026-02-28 (10 weeks)
|
||
Strategy Change: 2025-10-14 (C Code Generator → Pure Hakorune VM)
|
||
Dependency: Phase 15.77/15.78 complete; Frozen v1.1 (Linux/MSVC/MinGW) available
|
||
|
||
---
|
||
|
||
## 🎯 Objectives
|
||
|
||
**"Rust=floor, Hakorune=house" - Implement VM itself in Hakorune**
|
||
|
||
1. **HostBridge API Complete**: Minimal C-ABI boundary (Rust↔Hakorune)
|
||
2. **op_eq Migration**: Move equality logic from Rust to Hakorune (NoOperatorGuard)
|
||
3. **VM Foundations PoC**: Instruction dispatch proof-of-concept (5 instructions)
|
||
4. **Pure Hakorune Roadmap**: Detailed plan for Phase 20.6-15.82
|
||
|
||
**Note**: C Code Generator implementation is **CANCELLED** (Pure Hakorune strategy adopted)
|
||
|
||
---
|
||
|
||
## ✅ Deliverables (DoD)
|
||
|
||
### 1️⃣ HostBridge API Complete
|
||
|
||
**C-ABI Functions Working**:
|
||
```bash
|
||
./test_hostbridge_abi # Ubuntu
|
||
./test_hostbridge_abi.exe # Windows
|
||
```
|
||
|
||
**5 Core Functions**:
|
||
- `Hako_RunScriptUtf8` - Execute Hakorune script
|
||
- `Hako_Retain / Hako_Release` - Handle reference counting
|
||
- `Hako_ToUtf8` - Get string view
|
||
- `Hako_LastError` - Get error message (TLS)
|
||
|
||
**Checklist**:
|
||
- [ ] 5 core functions implemented
|
||
- [ ] Ubuntu ABI tests PASS
|
||
- [ ] Windows ABI tests PASS
|
||
- [ ] Error handling (TLS) working
|
||
|
||
---
|
||
|
||
### 2️⃣ op_eq Migration Complete
|
||
|
||
**Hakorune-side op_eq Working**:
|
||
```bash
|
||
HAKO_USE_PURE_EQ=1 ./hako test.hako
|
||
|
||
# Golden Test: Rust vs Hako
|
||
./test_op_eq_golden.sh # Expected: 100% parity
|
||
```
|
||
|
||
**Checklist**:
|
||
- [ ] NoOperatorGuard implemented (prevents infinite recursion)
|
||
- [ ] 8 comparison types (int/bool/null/string/array/map/enum/user)
|
||
- [ ] Golden tests: 20/20 PASS
|
||
- [ ] Performance: Hako-VM ≥ 70% of Rust-VM
|
||
|
||
---
|
||
|
||
### 3️⃣ VM Foundations PoC
|
||
|
||
**5 Instructions Working**:
|
||
```bash
|
||
./hako --backend vm-hako simple_program.hako
|
||
# Instructions: const, binop, compare, jump, ret
|
||
```
|
||
|
||
**Checklist**:
|
||
- [ ] 5 instructions implemented
|
||
- [ ] MIR execution loop (Hakorune implementation)
|
||
- [ ] Integration test: Run simple programs
|
||
- [ ] Performance measured
|
||
|
||
---
|
||
|
||
### 4️⃣ Documentation Complete
|
||
|
||
**Checklist**:
|
||
- [ ] STRATEGY_RECONCILIATION.md (why Pure Hakorune?)
|
||
- [ ] HOSTBRIDGE_API_DESIGN.md (C-ABI spec)
|
||
- [ ] OP_EQ_MIGRATION.md (equality implementation guide)
|
||
- [ ] PURE_HAKORUNE_ROADMAP.md (Phase 20.5-15.82 plan)
|
||
- [ ] Phase 20.6 planning document
|
||
|
||
---
|
||
|
||
## 📊 Weekly Milestones
|
||
|
||
### Week 1-2: HostBridge API Design & Implementation
|
||
|
||
**Goal**: Establish C-ABI boundary
|
||
|
||
**Tasks**:
|
||
- [ ] HostBridge API design (5 core functions)
|
||
- [ ] HandleRegistry implementation (Rust side)
|
||
- [ ] C header generation (hakorune_hostbridge.h)
|
||
- [ ] Basic implementation (RunScriptUtf8, Retain/Release)
|
||
|
||
**Deliverables**:
|
||
```
|
||
src/hostbridge/
|
||
├── mod.rs # C-ABI exports
|
||
├── handle_registry.rs # Handle management
|
||
└── tests.rs # Unit tests
|
||
|
||
include/
|
||
└── hakorune_hostbridge.h # C header
|
||
```
|
||
|
||
---
|
||
|
||
### Week 3-4: HostBridge API Complete & Testing
|
||
|
||
**Goal**: Ubuntu/Windows ABI tests PASS
|
||
|
||
**Tasks**:
|
||
- [ ] ToUtf8, LastError implementation
|
||
- [ ] Error handling (TLS)
|
||
- [ ] ABI test creation (C language)
|
||
- [ ] Ubuntu/Windows verification
|
||
|
||
**Deliverables**:
|
||
```
|
||
tests/
|
||
├── hostbridge_abi_test.c # C ABI tests
|
||
└── hostbridge_integration/
|
||
└── test_hostbridge_call.hako
|
||
|
||
tools/
|
||
└── test_hostbridge_abi.sh
|
||
```
|
||
|
||
---
|
||
|
||
### Week 5-6: op_eq Migration
|
||
|
||
**Goal**: Move equality logic from Rust to Hakorune
|
||
|
||
**Tasks**:
|
||
- [ ] NoOperatorGuard implementation (recursion prevention)
|
||
- [ ] 8 comparison types (int/bool/null/string/array/map/enum/user)
|
||
- [ ] Golden test creation (20 cases)
|
||
- [ ] Rust-VM vs Hako-VM parity verification
|
||
|
||
**Deliverables**:
|
||
```
|
||
apps/hakorune-vm/
|
||
├── op_eq_box.hako
|
||
├── no_operator_guard_box.hako
|
||
└── tests/
|
||
|
||
tests/golden/op_eq/
|
||
├── primitives.hako
|
||
├── arrays.hako
|
||
├── maps.hako
|
||
├── recursion.hako
|
||
└── user_defined.hako
|
||
```
|
||
|
||
---
|
||
|
||
### Week 7-8: VM Foundations PoC
|
||
|
||
**Goal**: Instruction dispatch proof-of-concept (5 instructions)
|
||
|
||
**Tasks**:
|
||
- [ ] MIR execution loop (Hakorune implementation)
|
||
- [ ] 5 instructions (const, binop, compare, jump, ret)
|
||
- [ ] Integration test (run simple programs)
|
||
- [ ] Performance measurement
|
||
|
||
**Deliverables**:
|
||
```
|
||
apps/hakorune-vm/
|
||
├── mini_vm_box.hako
|
||
├── instruction_dispatch.hako
|
||
└── tests/
|
||
|
||
tests/vm_poc/
|
||
├── hello.hako
|
||
├── arithmetic.hako
|
||
└── control_flow.hako
|
||
```
|
||
|
||
---
|
||
|
||
### Week 9: Integration Testing & Performance
|
||
|
||
**Goal**: Integrated operation verification
|
||
|
||
**Tasks**:
|
||
- [ ] HostBridge + op_eq + VM PoC integration
|
||
- [ ] E2E tests (10 cases)
|
||
- [ ] Performance measurement & comparison
|
||
- [ ] Issue identification & fixes
|
||
|
||
**Verification Script**:
|
||
```bash
|
||
#!/bin/bash
|
||
set -e
|
||
|
||
echo "Test 1: HostBridge API"
|
||
./test_hostbridge_abi
|
||
|
||
echo "Test 2: op_eq Golden Tests"
|
||
./test_op_eq_golden.sh
|
||
|
||
echo "Test 3: VM PoC"
|
||
./hako --backend vm-hako tests/vm_poc/arithmetic.hako
|
||
|
||
echo "✅ PASS: Phase 20.5 Integration Tests"
|
||
```
|
||
|
||
---
|
||
|
||
### Week 10: Documentation & Phase 20.6 Planning
|
||
|
||
**Goal**: Documentation & next phase planning
|
||
|
||
**Tasks**:
|
||
- [ ] STRATEGY_RECONCILIATION.md
|
||
- [ ] HOSTBRIDGE_API_DESIGN.md
|
||
- [ ] OP_EQ_MIGRATION.md
|
||
- [ ] PURE_HAKORUNE_ROADMAP.md
|
||
- [ ] Phase 20.6 planning document
|
||
- [ ] Completion report
|
||
|
||
**Deliverables**:
|
||
```
|
||
docs/private/roadmap/phases/phase-20.5/
|
||
├── STRATEGY_RECONCILIATION.md
|
||
├── HOSTBRIDGE_API_DESIGN.md
|
||
├── OP_EQ_MIGRATION.md
|
||
├── PURE_HAKORUNE_ROADMAP.md
|
||
├── COMPLETION_REPORT.md
|
||
└── LESSONS_LEARNED.md
|
||
|
||
docs/private/roadmap/phases/phase-20.6/
|
||
└── README.md
|
||
```
|
||
|
||
---
|
||
|
||
## 🎯 Success Criteria
|
||
|
||
### Technical
|
||
|
||
1. **HostBridge API Works**:
|
||
- C-ABI functions work on Ubuntu + Windows
|
||
- Handle lifecycle correct (no leaks)
|
||
- Error handling via TLS
|
||
|
||
2. **op_eq Migration Works**:
|
||
- NoOperatorGuard prevents infinite recursion
|
||
- Golden tests: 100% Rust-VM parity
|
||
- Performance: ≥ 70% of Rust-VM
|
||
|
||
3. **VM PoC Works**:
|
||
- 5 instructions execute correctly
|
||
- Simple programs run end-to-end
|
||
- Performance measurable
|
||
|
||
### Process
|
||
|
||
1. **Documentation Complete**:
|
||
- User can understand Pure Hakorune strategy
|
||
- Technical specs enable Phase 20.6 implementation
|
||
- Lessons learned documented
|
||
|
||
2. **Testing Comprehensive**:
|
||
- ABI tests (Ubuntu/Windows)
|
||
- Golden tests (Rust-VM vs Hako-VM)
|
||
- Integration tests (E2E)
|
||
|
||
3. **Review Approved**:
|
||
- ChatGPT review complete
|
||
- Claude review complete
|
||
- No blocking issues
|
||
|
||
---
|
||
|
||
## 🚨 Risks & Mitigations
|
||
|
||
### Risk 1: Longer Timeline (36 weeks total)
|
||
|
||
**Impact**: HIGH (delayed complete self-hosting)
|
||
**Mitigation**:
|
||
- Phase 20.5 delivers independent value
|
||
- Can pause after each phase
|
||
- Progressive derisking
|
||
|
||
### Risk 2: Implementation Complexity
|
||
|
||
**Impact**: MEDIUM (more effort than C Generator)
|
||
**Mitigation**:
|
||
- Rust VM as reference implementation
|
||
- Golden tests catch bugs early
|
||
- Incremental approach (5→16 instructions)
|
||
|
||
### Risk 3: Dual VM Maintenance
|
||
|
||
**Impact**: MEDIUM (maintenance burden)
|
||
**Mitigation**:
|
||
- Freeze Rust VM after Phase 20.5
|
||
- All new work in Hakorune VM
|
||
- Clear deprecation timeline (Phase 20.8)
|
||
|
||
### Risk 4: C-ABI Stability
|
||
|
||
**Impact**: LOW (well-understood boundary)
|
||
**Mitigation**:
|
||
- Minimal API (5 functions)
|
||
- Proven design (Lua/Python C API)
|
||
- Comprehensive ABI tests
|
||
|
||
---
|
||
|
||
## 🎉 Success Impact
|
||
|
||
### After Phase 20.5 (10 weeks)
|
||
|
||
1. **HostBridge API**: Clean Rust↔Hakorune boundary
|
||
2. **op_eq in Hakorune**: Improved correctness (NoOperatorGuard)
|
||
3. **VM PoC**: Feasibility demonstrated
|
||
4. **Phase 20.6 Plan**: Detailed roadmap ready
|
||
|
||
### After Phase 20.8 (36 weeks, 2026-09-30)
|
||
|
||
5. **Complete Self-Hosting**: Hakorune IS Hakorune
|
||
6. **Rust Minimized**: ~100 lines (C-ABI bridge only)
|
||
7. **Ultimate Box Theory**: VM also implemented as Box
|
||
8. **Long-term Maintainability**: Single execution path
|
||
|
||
---
|
||
|
||
## 📚 Related Resources
|
||
|
||
### Phase 20.5 Documents
|
||
- [STRATEGY_RECONCILIATION.md](STRATEGY_RECONCILIATION.md) - Why Pure Hakorune?
|
||
- [HOSTBRIDGE_API_DESIGN.md](HOSTBRIDGE_API_DESIGN.md) - C-ABI specification
|
||
- [OP_EQ_MIGRATION.md](OP_EQ_MIGRATION.md) - Equality implementation guide
|
||
- [PURE_HAKORUNE_ROADMAP.md](PURE_HAKORUNE_ROADMAP.md) - Overall plan
|
||
- [CHATGPT_PURE_HAKORUNE_STRATEGY.md](CHATGPT_PURE_HAKORUNE_STRATEGY.md) - Original proposal
|
||
|
||
### Previous Phases
|
||
- [Phase 15.77 - Frozen EXE Finalization](../phase-15.77/)
|
||
- [Phase 15.76 - extern_c & Frozen Toolchain](../phase-15.76/)
|
||
|
||
### Industry Patterns
|
||
- **Lua**: Minimal C-API (5-10 functions)
|
||
- **Python**: C-API + Pure Python stdlib
|
||
- **Rust**: stage0 (frozen) → stage1 (bootstrap) → stage2 (verify)
|
||
- **Go**: Go 1.4 frozen → Go 1.5 self-hosted
|
||
|
||
---
|
||
|
||
**Created**: 2025-10-14
|
||
**Strategy Changed**: 2025-10-14 (Pure Hakorune adopted)
|
||
**Phase Start**: 2025-12-21 (after Phase 15.77 completion)
|
||
**Duration**: 10 weeks (Phase 20.5 only)
|
||
**Complete Realization**: 36 weeks (Phase 20.5-15.82)
|
||
**Strategy**: Pure Hakorune ("Rust=floor, Hakorune=house")
|