docs: restore docs/private/roadmap from 7b4908f9 (Phase 20.31)
This commit is contained in:
nyash-codex
344
docs/private/roadmap/phases/phase-20.8/INDEX.md
Normal file
344
docs/private/roadmap/phases/phase-20.8/INDEX.md
Normal file
@ -0,0 +1,344 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user