345 lines
8.0 KiB
Markdown
345 lines
8.0 KiB
Markdown
# 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](README.md)** (日本語)
|
||
- Phase 20.8 概要
|
||
- Phase E: GC v0 (Week 1-4)
|
||
- Phase F: Rust VM Deprecation (Week 5-6)
|
||
- 成功基準
|
||
- マイルストーン
|
||
|
||
2. **[PLAN.md](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](CHECKLIST.md)** (タスクリスト)
|
||
- Week 1-4: GC v0 implementation
|
||
- Week 5-6: Rust VM deprecation
|
||
- Self-compilation verification
|
||
- Rust layer audit
|
||
|
||
4. **[INDEX.md](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](../phase-20.7/README.md)
|
||
- MapBox in Hakorune
|
||
- ArrayBox in Hakorune
|
||
- Deterministic behavior
|
||
|
||
- **Phase 15.80 (VM Core)**: [../phase-15.80/README.md](../phase-15.80/README.md)
|
||
- 16 MIR instructions
|
||
- Control flow
|
||
- Dispatch unification
|
||
|
||
- **Phase 20.5 (HostBridge)**: [../phase-20.5/README.md](../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](../phase-20.5/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](../phase-20.5/HOSTBRIDGE_API_DESIGN.md)**
|
||
- C-ABI boundary
|
||
- HostBridge API spec
|
||
- Error handling (TLS)
|
||
|
||
- **[OP_EQ_MIGRATION.md](../phase-20.5/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](../../../../architecture/box-externcall-design.md)**
|
||
- Everything is Box
|
||
- BoxCall vs ExternCall
|
||
- Unified invocation
|
||
|
||
- **[MIR Instruction Set](../../../../../reference/mir/INSTRUCTION_SET.md)**
|
||
- 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**:
|
||
```bash
|
||
# 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**:
|
||
```bash
|
||
# 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
|