docs: restore docs/private/roadmap from 7b4908f9 (Phase 20.31)
This commit is contained in:
nyash-codex
@ -0,0 +1,351 @@
|
||||
# Strategy Reconciliation — Phase 20.5 "Escape from Rust"
|
||||
|
||||
**Date**: 2025-10-14
|
||||
**Status**: APPROVED (Pure Hakorune Strategy)
|
||||
**Decision**: User preference: "純 Hakorune 大作戦" ✅
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Executive Summary
|
||||
|
||||
We had TWO competing strategies for Phase 20.5:
|
||||
|
||||
1. **Original Plan (Task Agent)**: C Code Generator approach - 10 weeks to bootstrap
|
||||
2. **ChatGPT Pro Proposal**: Pure Hakorune VM - 30+ weeks for complete realization
|
||||
|
||||
**Decision**: Adopt **Pure Hakorune Strategy** with phased implementation.
|
||||
|
||||
**Phase 20.5 (10 weeks)** will complete:
|
||||
- ✅ Phase A: HostBridge API (C-ABI boundary)
|
||||
- ✅ Phase B (start): VM foundations in Hakorune (`op_eq` migration, instruction dispatch PoC)
|
||||
|
||||
**Deferred to Phase 20.6+**:
|
||||
- ⏸️ Full VM core in Hakorune (Phase B complete)
|
||||
- ⏸️ Dispatch unification (Phase C)
|
||||
- ⏸️ Collections in Hakorune (Phase D)
|
||||
- ⏸️ GC v0 (Phase E)
|
||||
- ⏸️ Rust VM compat mode (Phase F)
|
||||
|
||||
**C Code Generator approach**: ❌ Discarded (not implemented)
|
||||
|
||||
---
|
||||
|
||||
## 📊 Side-by-Side Comparison
|
||||
|
||||
| Aspect | Original Plan (C Generator) | Pure Hakorune Strategy |
|
||||
|--------|----------------------------|------------------------|
|
||||
| **Timeline** | 10 weeks (Phase 20.5) | 30+ weeks (Phase 20.5-15.82) |
|
||||
| **Core Approach** | Generate C code from MIR | Implement VM itself in Hakorune |
|
||||
| **Rust Role** | Minimal (~200 lines) | Ultra-minimal (C-ABI bridge only) |
|
||||
| **Output** | `.c` files → EXE | VM runs MIR natively |
|
||||
| **Bootstrap Method** | v1 compiles v2 (via C code) | v1 VM runs v2 VM code |
|
||||
| **Complexity** | Medium (500 lines C emitter) | High (full VM in Hakorune) |
|
||||
| **Long-term Vision** | "Hakorune compiles Hakorune" | "Hakorune IS Hakorune" |
|
||||
| **Architecture** | Compiler-focused | VM-focused |
|
||||
| **Maintenance** | Two paths (Rust VM + C output) | Single path (Hakorune VM) |
|
||||
|
||||
---
|
||||
|
||||
## 💡 Why Pure Hakorune is Preferred
|
||||
|
||||
### Architectural Elegance
|
||||
|
||||
**C Generator Approach**:
|
||||
```
|
||||
Hakorune Source → [Rust Parser] → MIR JSON → [Hako C Gen] → C Code → [clang] → EXE
|
||||
↑ ↑
|
||||
Rust VM C compiler
|
||||
```
|
||||
|
||||
**Pure Hakorune Approach**:
|
||||
```
|
||||
Hakorune Source → [Hako Parser] → MIR JSON → [Hako VM] → Execution
|
||||
↑ ↑
|
||||
Everything in Hakorune Everything in Hakorune
|
||||
|
||||
Rust = Thin floor (C-ABI bridge only)
|
||||
```
|
||||
|
||||
**Result**: "Rust=floor, Hakorune=house" - Ultimate Box Theory realization
|
||||
|
||||
### Long-term Maintainability
|
||||
|
||||
**C Generator Issues**:
|
||||
- ❌ Two execution paths (Rust VM + compiled C)
|
||||
- ❌ C code generation adds complexity
|
||||
- ❌ C compiler dependency (clang/gcc)
|
||||
- ❌ Debugging split between Hakorune → C → EXE
|
||||
|
||||
**Pure Hakorune Benefits**:
|
||||
- ✅ Single execution path (Hakorune VM)
|
||||
- ✅ VM semantics defined once (in Hakorune)
|
||||
- ✅ No external compiler dependency (except Rust→Hakorune bridge)
|
||||
- ✅ Debugging entirely in Hakorune
|
||||
|
||||
### Reflects Past Learnings
|
||||
|
||||
**ChatGPT Pro's guidance incorporates fixes for**:
|
||||
1. **Equals/== recursion bug** (2025 issue):
|
||||
- Solution: `NoOperatorGuard` in `call_by_handle`
|
||||
- Pure Hakorune enforces this structurally
|
||||
|
||||
2. **Handle lifecycle complexity**:
|
||||
- Solution: Minimal C-ABI with `Retain/Release`
|
||||
- Pure Hakorune minimizes Rust↔Hakorune boundary
|
||||
|
||||
3. **Dispatch fragmentation**:
|
||||
- Solution: Single resolution path (`Resolver.lookup`)
|
||||
- Pure Hakorune unifies all dispatch
|
||||
|
||||
### Ultimate Box Theory
|
||||
|
||||
**C Generator**: Hakorune is a compiler *for* programs
|
||||
**Pure Hakorune**: Hakorune *is* the program (self-contained)
|
||||
|
||||
**Box Philosophy**:
|
||||
> Everything is Box, including the VM that runs Boxes.
|
||||
|
||||
Pure Hakorune realizes this fully.
|
||||
|
||||
---
|
||||
|
||||
## 🚧 What Gets Deferred to Phase 20.6+
|
||||
|
||||
### Phase 20.5 (10 weeks) Scope
|
||||
|
||||
**✅ CAN COMPLETE**:
|
||||
1. **HostBridge API** (Week 1-4):
|
||||
- Minimal C-ABI surface (`Hako_RunScriptUtf8`, `Retain/Release`, etc.)
|
||||
- Ubuntu/Windows ABI tests
|
||||
- Error handling (TLS `Hako_LastError`)
|
||||
|
||||
2. **`op_eq` Migration** (Week 5-6):
|
||||
- Move equality logic from Rust to Hakorune
|
||||
- Implement `NoOperatorGuard` (prevent recursion)
|
||||
- Golden tests: Rust-VM vs Hako-VM parity
|
||||
|
||||
3. **VM Foundations PoC** (Week 7-8):
|
||||
- Instruction dispatch skeleton (5 instructions: const, binop, compare, jump, ret)
|
||||
- MIR execution loop in Hakorune
|
||||
- Integration test: Run simple programs
|
||||
|
||||
4. **Documentation** (Week 9-10):
|
||||
- HostBridge API spec
|
||||
- Op_eq migration guide
|
||||
- Pure Hakorune roadmap
|
||||
- Phase 20.6 planning
|
||||
|
||||
**❌ CANNOT COMPLETE** (deferred):
|
||||
- Full VM core (all 16 instructions) → **Phase 20.6**
|
||||
- Dispatch unification (Resolver-based) → **Phase 20.6**
|
||||
- Collections in Hakorune (MapBox/ArrayBox) → **Phase 20.7**
|
||||
- GC v0 (mark&sweep) → **Phase 20.8**
|
||||
- Rust VM deprecation → **Phase 20.8**
|
||||
|
||||
### Phase 20.6-15.82 Roadmap
|
||||
|
||||
**Phase 20.6** (12 weeks): VM Core Complete
|
||||
- Phase B: All 16 MIR instructions in Hakorune
|
||||
- Phase C: Dispatch unification (`Resolver.lookup` everywhere)
|
||||
- Golden tests: 100% Rust-VM parity
|
||||
|
||||
**Phase 20.7** (8 weeks): Collections in Hakorune
|
||||
- Phase D: MapBox/ArrayBox implementation
|
||||
- Deterministic hash/eq
|
||||
- Key normalization (Symbol/Int/String)
|
||||
|
||||
**Phase 20.8** (6 weeks): GC + Rust Deprecation
|
||||
- Phase E: GC v0 (Stop-the-world mark&sweep)
|
||||
- Phase F: Rust VM becomes `--backend vm-rust` (compat mode)
|
||||
- Hakorune-VM is default
|
||||
|
||||
**Total**: 36 weeks (Phase 20.5 → 15.82)
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Risk Assessment
|
||||
|
||||
### Longer Timeline Risk
|
||||
|
||||
**Risk**: 36 weeks vs original 10 weeks
|
||||
**Impact**: HIGH (delayed complete self-hosting)
|
||||
**Mitigation**:
|
||||
- Phase 20.5 delivers **tangible value** (HostBridge, `op_eq`, VM PoC)
|
||||
- Each phase is independently useful
|
||||
- Can pause/reprioritize after each phase
|
||||
- Progressive derisking (start with easy parts)
|
||||
|
||||
### Higher Complexity Risk
|
||||
|
||||
**Risk**: Implementing VM in Hakorune is harder than C generator
|
||||
**Impact**: MEDIUM (more implementation effort)
|
||||
**Mitigation**:
|
||||
- Existing Rust VM as reference implementation
|
||||
- Golden tests ensure parity (catch bugs early)
|
||||
- Incremental approach (5 instructions → 16 instructions)
|
||||
- ChatGPT/Claude collaboration for complex parts
|
||||
|
||||
### Rust VM Maintenance Risk
|
||||
|
||||
**Risk**: Must maintain both Rust VM and Hakorune VM during transition
|
||||
**Impact**: MEDIUM (dual maintenance burden)
|
||||
**Mitigation**:
|
||||
- Rust VM frozen after Phase 20.5 (no new features)
|
||||
- Hakorune VM is where new work happens
|
||||
- Clear deprecation timeline (Phase 20.8)
|
||||
- Golden tests prevent divergence
|
||||
|
||||
### C-ABI Stability Risk
|
||||
|
||||
**Risk**: HostBridge API might need changes during implementation
|
||||
**Impact**: LOW (well-understood boundary)
|
||||
**Mitigation**:
|
||||
- Minimal API surface (5 functions)
|
||||
- Inspired by proven designs (Lua, Python C API)
|
||||
- Version function (`Hako_ApiVersion()`)
|
||||
- Comprehensive ABI tests (Ubuntu/Windows)
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Fallback Strategies
|
||||
|
||||
### If Pure Hakorune Takes Too Long
|
||||
|
||||
**Option 1**: Pause and ship Phase 20.5 deliverables
|
||||
- HostBridge API is valuable independently
|
||||
- `op_eq` in Hakorune improves correctness
|
||||
- VM PoC demonstrates feasibility
|
||||
- Resume Phase 20.6 later
|
||||
|
||||
**Option 2**: Hybrid approach (short-term)
|
||||
- Keep Rust VM as primary
|
||||
- Hakorune VM as experimental (`--backend vm-hako`)
|
||||
- Gradually expand Hakorune VM coverage
|
||||
- No hard deadline for full transition
|
||||
|
||||
**Option 3**: Revert to C Generator (if absolutely necessary)
|
||||
- Original plan documents preserved
|
||||
- C Generator design doc complete
|
||||
- Can pivot in Phase 20.6 if needed
|
||||
|
||||
### If HostBridge API Has Issues
|
||||
|
||||
**Problem**: C-ABI doesn't work on Windows/Ubuntu
|
||||
**Fallback**:
|
||||
- Simplify API (fewer functions)
|
||||
- Use more conservative types (no TLS, explicit context)
|
||||
- Add compatibility shims per platform
|
||||
|
||||
### If `op_eq` Migration Fails
|
||||
|
||||
**Problem**: Hakorune-side equality doesn't match Rust behavior
|
||||
**Fallback**:
|
||||
- Keep Rust `op_eq` as reference
|
||||
- Hakorune `op_eq` as opt-in (`HAKO_USE_PURE_EQ=1`)
|
||||
- Golden tests identify discrepancies
|
||||
- Fix incrementally
|
||||
|
||||
---
|
||||
|
||||
## 📋 Confidence Assessment
|
||||
|
||||
### High Confidence (80%+)
|
||||
|
||||
- ✅ **HostBridge API**: Well-understood, similar to Lua/Python C API
|
||||
- ✅ **`op_eq` Migration**: Clear algorithm, golden tests available
|
||||
- ✅ **VM PoC**: Rust VM as reference, only 5 instructions needed
|
||||
|
||||
### Medium Confidence (60-80%)
|
||||
|
||||
- ⚠️ **Full VM Core** (Phase 20.6): 16 instructions is more work
|
||||
- ⚠️ **Dispatch Unification**: Requires careful refactoring
|
||||
- ⚠️ **Collections**: MapBox/ArrayBox have subtle semantics
|
||||
|
||||
### Lower Confidence (40-60%)
|
||||
|
||||
- ⚠️ **GC v0**: Garbage collection is inherently complex
|
||||
- ⚠️ **Rust VM Deprecation**: Requires full parity, no gaps
|
||||
|
||||
### Overall Confidence: **70%** (MEDIUM-HIGH)
|
||||
|
||||
**Reasoning**:
|
||||
- Phase 20.5 deliverables are achievable (high confidence)
|
||||
- Phase 20.6+ depends on learnings from 20.5 (medium confidence)
|
||||
- Fallback options exist if needed (risk mitigation)
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Why This is Worth It
|
||||
|
||||
### Short-term (Phase 20.5)
|
||||
|
||||
1. **HostBridge API**: Clean boundary between Rust and Hakorune
|
||||
2. **`op_eq` in Hakorune**: Fixes recursion bugs, improves correctness
|
||||
3. **VM PoC**: Demonstrates feasibility of Pure Hakorune vision
|
||||
|
||||
### Medium-term (Phase 20.6-15.81)
|
||||
|
||||
4. **VM Core Complete**: Hakorune can run itself
|
||||
5. **Collections in Hakorune**: Everything is Box (truly)
|
||||
6. **Single Codebase**: All semantics defined once (in Hakorune)
|
||||
|
||||
### Long-term (Phase 20.8+)
|
||||
|
||||
7. **Rust Minimal**: Only C-ABI bridge (~100 lines)
|
||||
8. **True Self-Hosting**: Hakorune IS Hakorune (not just compiles)
|
||||
9. **Ultimate Box Theory**: Realized in its purest form
|
||||
|
||||
---
|
||||
|
||||
## 📚 Document Evolution
|
||||
|
||||
### Original Documents (Preserved)
|
||||
|
||||
- `/phase-20.5/README.md` (original plan) → **UPDATED**
|
||||
- `/phase-20.5/MILESTONE.md` (original milestones) → **UPDATED**
|
||||
- `/phase-20.5/C_CODE_GENERATOR_DESIGN.md` → **ARCHIVED** (not implemented)
|
||||
- `/phase-20.5/BOOTSTRAP_CHAIN_ANALYSIS.md` → **UPDATED** (Pure Hakorune approach added)
|
||||
|
||||
### New Documents (This Reconciliation)
|
||||
|
||||
- `/phase-20.5/STRATEGY_RECONCILIATION.md` → **THIS FILE**
|
||||
- `/phase-20.5/HOSTBRIDGE_API_DESIGN.md` → **NEW** (C-ABI spec)
|
||||
- `/phase-20.5/PURE_HAKORUNE_ROADMAP.md` → **NEW** (Phase 20.5-15.82 plan)
|
||||
- `/phase-20.5/OP_EQ_MIGRATION.md` → **NEW** (equality implementation guide)
|
||||
|
||||
### Updated Documents
|
||||
|
||||
- `/phase-20.5/README.md`: Removed C Generator, added HostBridge/op_eq
|
||||
- `/phase-20.5/MILESTONE.md`: Week-by-week plan updated
|
||||
- `/phase-20.5/BOOTSTRAP_CHAIN_ANALYSIS.md`: Pure Hakorune approach added
|
||||
|
||||
---
|
||||
|
||||
## 🎤 Final Recommendation
|
||||
|
||||
**Adopt Pure Hakorune Strategy** for the following reasons:
|
||||
|
||||
1. **Architectural elegance**: "Rust=floor, Hakorune=house"
|
||||
2. **Long-term maintainability**: Single execution path
|
||||
3. **Reflects learnings**: Incorporates past bug fixes
|
||||
4. **Ultimate Box Theory**: Realizes core philosophy
|
||||
5. **User preference**: tomoaki chose "純 Hakorune 大作戦" ✅
|
||||
|
||||
**Accept longer timeline** (36 weeks) for:
|
||||
- Clean architecture
|
||||
- Minimal technical debt
|
||||
- Future-proof foundation
|
||||
|
||||
**Phase 20.5 (10 weeks)** delivers:
|
||||
- HostBridge API (C-ABI boundary)
|
||||
- `op_eq` in Hakorune (correctness improvement)
|
||||
- VM PoC (feasibility demonstration)
|
||||
|
||||
**Next phases** (15.80-15.82) complete the vision.
|
||||
|
||||
---
|
||||
|
||||
**Status**: APPROVED
|
||||
**Decision Maker**: tomoaki
|
||||
**Implementation**: ChatGPT (lead), Claude (review)
|
||||
**Timeline**: 2025-12-21 → 2026-09-30 (Phase 20.5-15.82)
|
||||
Reference in New Issue
Block a user