tomoaki/hakorune
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ae84391a954a742e65f3a2a5f85faafaa39b775a
hakorune/docs/private/roadmap/phases/phase-20.5/STRATEGY_RECONCILIATION.md

11 KiB
Raw Blame History

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)

  1. VM Core Complete: Hakorune can run itself
  2. Collections in Hakorune: Everything is Box (truly)
  3. Single Codebase: All semantics defined once (in Hakorune)

Long-term (Phase 20.8+)

  1. Rust Minimal: Only C-ABI bridge (~100 lines)
  2. True Self-Hosting: Hakorune IS Hakorune (not just compiles)
  3. 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)