hakorune/docs/private/roadmap/phases/phase-20.8/INDEX.md

Phase 20.8: GC + Rust Deprecation - Document Index

Phase: 20.8 Duration: 6 weeks (2026-07-20 → 2026-08-30) Status: Not Started

---

📚 Document Structure

Core Documents

1. README.md (日本語)

   • Phase 20.8 概要
   • Phase E: GC v0 (Week 1-4)
   • Phase F: Rust VM Deprecation (Week 5-6)
   • 成功基準
   • マイルストーン

2. PLAN.md (English)

   • Executive summary
   • Week-by-week implementation plan
   • GC implementation details
   • Rust VM deprecation strategy
   • Bit-identical verification
   • Success criteria

3. CHECKLIST.md (タスクリスト)

   • Week 1-4: GC v0 implementation
   • Week 5-6: Rust VM deprecation
   • Self-compilation verification
   • Rust layer audit

4. INDEX.md (このファイル)

   • Document structure
   • Quick reference
   • Related phases

---

🎯 Quick Reference

Phase E: GC v0 (Week 1-4)

Goal: Implement Mark & Sweep garbage collection in Hakorune

Key Features:

• Stop-the-world GC
• Mark phase: Trace reachable objects from roots
• Sweep phase: Free unreachable objects
• GC Roots: Stack frames, global static boxes, HandleRegistry
• Metrics: Allocation count, survivor count, sweep time
• Observability: HAKO_GC_TRACE=1

Deliverables:

• GcBox implementation (Mark & Sweep)
• GcMetricsBox (metrics collection)
• VM integration (allocation hook, GC trigger)
• Tests: Golden tests, smoke tests

Phase F: Rust VM Deprecation (Week 5-6)

Goal: Deprecate Rust VM and achieve true self-hosting

Key Features:

• Hakorune-VM is default (--backend vm)
• Rust-VM opt-in (--backend vm-rust, with warning)
• Bit-identical self-compilation (Hako₁ → Hako₂ → Hako₃)
• Rust layer ≤ 100 lines (HostBridge API only)

Deliverables:

• CLI updated (Hakorune-VM default)
• Deprecation warning added
• Self-compilation verification script
• CI integration (daily verification)
• Rust layer audit (≤ 100 lines)

---

✅ Success Criteria Summary

Phase E (GC v0)

• GC v0 works (no memory leaks)
• Mark & Sweep correct
• GC roots detected (stack, global, handles)
• Metrics collection working
• HAKO_GC_TRACE=1 provides detailed logs

Phase F (Rust VM Deprecation)

• Hakorune-VM is default backend
• Rust-VM deprecated (warning displayed)
• Bit-identical self-compilation verified
• CI daily verification passes
• Rust layer ≤ 100 lines

Overall

• True Self-Hosting: Hakorune IS Hakorune
• Rust=floor, Hakorune=house: Architecture realized
• All smoke tests pass with Hakorune-VM

---

🔗 Related Phases

Prerequisites

• Phase 20.7 (Collections): ../phase-20.7/README.md

  • MapBox in Hakorune
  • ArrayBox in Hakorune
  • Deterministic behavior

• Phase 15.80 (VM Core): ../phase-15.80/README.md

  • 16 MIR instructions
  • Control flow
  • Dispatch unification

• Phase 20.5 (HostBridge): ../phase-20.5/README.md

  • HostBridge API (C-ABI)
  • Op_eq migration
  • VM foundations PoC

Follow-up Phases

• Phase 15.82 (Advanced GC & Optimization): TBD
  • Generational GC
  • Incremental GC
  • Performance optimization
  • JIT compilation

---

📖 Additional Resources

Pure Hakorune Roadmap

• PURE_HAKORUNE_ROADMAP.md
  • 36-week timeline (2025-12-21 → 2026-09-30)
  • 6 phases: A → B → C → D → E → F
  • "Rust=floor, Hakorune=house" vision

Technical Specifications

• HOSTBRIDGE_API_DESIGN.md

  • C-ABI boundary
  • HostBridge API spec
  • Error handling (TLS)

• OP_EQ_MIGRATION.md

  • Equality logic migration
  • NoOperatorGuard pattern
  • Golden tests

Experimental Tracks (not adopted yet)

• HakMem — C‑ABI Allocator (paper; dev only)
  • docs/private/papers-active/hakmem-c-abi-allocator/README.md
• HakMem POC (app skeleton; no wiring)
  • apps/experiments/hakmem-poc/README.md

Architecture Documents

• Box/ExternCall Design

  • Everything is Box
  • BoxCall vs ExternCall
  • Unified invocation

• MIR Instruction Set

  • 16 frozen instructions
  • MIR semantics
  • VM execution model

---

🧪 Testing Strategy

Golden Tests

Goal: Prove Hakorune-VM produces identical output to Rust-VM

Test Suite:

tests/golden/
├── arithmetic.hako          # Basic arithmetic
├── control_flow.hako        # if/loop/branch
├── collections.hako         # Array/Map operations
├── recursion.hako           # Recursive functions
├── strings.hako             # String manipulation
├── enums.hako               # @enum types
├── closures.hako            # Closure capture
└── selfhost_mini.hako       # Mini compiler

Verification:

# Run same program on both VMs
./hako --backend vm-rust test.hako > rust_output.txt
./hako --backend vm test.hako > hako_output.txt

# Compare outputs
diff rust_output.txt hako_output.txt
# Expected: No differences

Self-Compilation Verification

Goal: Prove Hakorune compiler is bit-identical across generations

Verification Chain:

# Hako₁: Rust-based compiler
cargo build --release
cp target/release/hako hako_1

# Hako₂: Compiled by Hako₁
./hako_1 apps/selfhost-compiler/main.hako -o hako_2

# Hako₃: Compiled by Hako₂
./hako_2 apps/selfhost-compiler/main.hako -o hako_3

# Verify bit-identical
diff hako_2 hako_3  # Expected: No differences

GC Tests

Goal: Verify GC correctness and performance

Test Categories:

1. Leak Tests: Ensure no memory leaks
2. Stress Tests: Allocate/free large number of objects
3. Cycle Tests: Verify cyclic references are collected
4. Root Tests: Verify all roots are traced
5. Metrics Tests: Verify metrics accuracy

Tools:

• HAKO_GC_TRACE=1: Detailed GC logs
• Valgrind: Memory leak detection
• Custom GC metrics

---

📊 Milestones

Week 1-2: GC Mark Phase

• GC roots detection
• Mark algorithm
• Cycle detection
• Tests: Mark correctness

Week 3-4: GC Sweep Phase & Metrics

• Sweep algorithm
• Metrics collection
• HAKO_GC_TRACE=1
• Integration & testing

Week 5: Backend Switching & Deprecation

• Hakorune-VM default
• Rust-VM deprecation warning
• Golden tests verification
• Documentation updates

Week 6: Bit-Identical Verification & Audit

• Self-compilation chain
• CI integration
• Rust layer audit (≤ 100 lines)
• Final documentation

---

🎉 Final Success Impact

Before Phase 20.8

Rust Layer:
├── VM implementation (~5000 lines)
├── Collections (MapBox, ArrayBox) (~2000 lines)
├── GC (reference counting) (~500 lines)
└── HostBridge API (~100 lines)

Hakorune Layer:
├── Parser (selfhost-compiler)
└── Standard library

After Phase 20.8

Rust Layer (~100 lines):
└── HostBridge API (C-ABI only)

Hakorune Layer (everything else):
├── VM (MiniVmBox)
├── Parser (MirJsonBuilderBox)
├── Collections (MapBox, ArrayBox)
├── GC (GcBox)
└── Standard library (StringBox, IntegerBox, etc.)

Achievement: "Rust=floor, Hakorune=house" ✅

True Self-Hosting: Hakorune IS Hakorune

---

🚀 Next Steps

After Phase 20.8 completion:

1. Phase 15.82 (Advanced GC):

   • Generational GC
   • Incremental GC
   • Write barriers

2. Performance Optimization:

   • JIT compilation
   • Inline caching
   • Type specialization

3. Language Features:

   • Async/await
   • Generators
   • Pattern matching

4. Tooling:

   • Debugger
   • Profiler
   • Language server

---

Status: Not Started Start Date: 2026-07-20 Target Completion: 2026-08-30 Dependencies: Phase 20.7 complete

Last Updated: 2025-10-14