8.9 KiB
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
- HostBridge API Complete: Minimal C-ABI boundary (Rust↔Hakorune)
- op_eq Migration: Move equality logic from Rust to Hakorune (NoOperatorGuard)
- VM Foundations PoC: Instruction dispatch proof-of-concept (5 instructions)
- 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:
./test_hostbridge_abi # Ubuntu
./test_hostbridge_abi.exe # Windows
5 Core Functions:
Hako_RunScriptUtf8- Execute Hakorune scriptHako_Retain / Hako_Release- Handle reference countingHako_ToUtf8- Get string viewHako_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:
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:
./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:
#!/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
-
HostBridge API Works:
- C-ABI functions work on Ubuntu + Windows
- Handle lifecycle correct (no leaks)
- Error handling via TLS
-
op_eq Migration Works:
- NoOperatorGuard prevents infinite recursion
- Golden tests: 100% Rust-VM parity
- Performance: ≥ 70% of Rust-VM
-
VM PoC Works:
- 5 instructions execute correctly
- Simple programs run end-to-end
- Performance measurable
Process
-
Documentation Complete:
- User can understand Pure Hakorune strategy
- Technical specs enable Phase 20.6 implementation
- Lessons learned documented
-
Testing Comprehensive:
- ABI tests (Ubuntu/Windows)
- Golden tests (Rust-VM vs Hako-VM)
- Integration tests (E2E)
-
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)
- HostBridge API: Clean Rust↔Hakorune boundary
- op_eq in Hakorune: Improved correctness (NoOperatorGuard)
- VM PoC: Feasibility demonstrated
- Phase 20.6 Plan: Detailed roadmap ready
After Phase 20.8 (36 weeks, 2026-09-30)
- Complete Self-Hosting: Hakorune IS Hakorune
- Rust Minimized: ~100 lines (C-ABI bridge only)
- Ultimate Box Theory: VM also implemented as Box
- Long-term Maintainability: Single execution path
📚 Related Resources
Phase 20.5 Documents
- STRATEGY_RECONCILIATION.md - Why Pure Hakorune?
- HOSTBRIDGE_API_DESIGN.md - C-ABI specification
- OP_EQ_MIGRATION.md - Equality implementation guide
- PURE_HAKORUNE_ROADMAP.md - Overall plan
- CHATGPT_PURE_HAKORUNE_STRATEGY.md - Original proposal
Previous Phases
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")