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.6/INDEX.md

14 KiB
Raw Blame History

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 ⭐ 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 (English)

    • Executive summary (5 lines)
    • Phase breakdown (Phase B + Phase C)
    • Week-by-week implementation plan
    • Golden Test strategy
    • CI integration

  3. 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 (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

# 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

# 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

# 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

  • HostBridge API complete
  • op_eq Migration complete (NoOperatorGuard)
  • VM Foundations PoC complete (5 instructions)
  • 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

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

💬 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

Related Documents

📝 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 で段階導入