tomoaki/hakorune
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: restore docs/private/roadmap from 7b4908f9 (Phase 20.31)

Browse Source
This commit is contained in:
nyash-codex
2025-10-31 18:00:10 +09:00
parent 1d49e24bf0
commit 8fd3a2b509
433 changed files with 108935 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

365
docs/private/roadmap/phases/phase-20.5/INDEX.md Normal file
View File

@ -0,0 +1,365 @@
# Phase 20.5 — Index
**Escape from Rust: Bootstrap Compiler Implementation**
Status: Planning (Gate plan active)
Duration: 10 weeks (2025-12-21 - 2026-02-28)
---
## 📚 Documentation Structure
### Core Documents
1. **[README.md](README.md)** ⭐ START HERE
- Phase overview and goals
- Weekly breakdown (Week 1-10)
- Implementation strategy decision (Option B)
- Success criteria and DoD
2. **[MILESTONE.md](MILESTONE.md)**
- Objectives and deliverables
- Weekly milestones
- Success criteria
- Risk analysis
3. **[BOOTSTRAP_CHAIN_ANALYSIS.md](BOOTSTRAP_CHAIN_ANALYSIS.md)**
- 3-stage bootstrap chain detailed design
- Stage 1 (Rust) → Stage 2 (Hako v1) → Stage 3 (Hako v2)
- Data flow analysis
- Verification strategy
4. **[C_CODE_GENERATOR_DESIGN.md](C_CODE_GENERATOR_DESIGN.md)**
- MIR → C conversion design
- 16-instruction mapping table
- PHI resolution strategy
- Test strategy (43 test cases)
5. **[PLAN.md](PLAN.md)** ✅ Gate-based execution plan（短縮版）
- 5行サマリ / 最小命令セット / DoD
- Gate A〜E（Parser→MIR→VM PoC→op_eq→統合）
- テスト/CI/リスク/次ステップ
---
## 🎯 Quick Reference
### What is Phase 20.5? (5-line summary)
1) Goal: 脱Rust。凍結EXEを土台に自己ホストへ前進。
2) Strategy: Gate方式（Parser→MIR→VM PoC→op_eq→統合）。
3) Boundary: C‑ABI/HostBridgeのみ外部境界。中はEverything is Box。
4) Proof: 決定性（JSON正規化）、Golden＆固定点で検証。
5) Policy: 小さく、順序よく、SKIPはWARN、回帰のみFAIL。
### Key Deliverables
1. **Bootstrap Compiler** (`apps/bootstrap-compiler/`)
- Written in Hakorune
- Runs on frozen EXE
- Outputs C code
2. **C Code Generator**
- MIR JSON → C source
- 16 instructions fully supported
- NyRT function calls
3. **Verification**
- v1 == v2 (compiler parity)
- v2 == v3 (fixed point)
- 10 test programs PASS
---
## 📊 Timeline at a Glance
| Weeks | Focus | Deliverable |
|-------|-------|-------------|
| 1-2 | Design & Analysis | Design docs complete |
| 3-4 | Parser Adaptation | Parser works on frozen EXE |
| 5-6 | MIR Builder Migration | MIR JSON generation works |
| 7-8 | C Code Generator | C code emission works |
| 9 | Bootstrap Integration | v1 == v2 verified |
| 10 | Documentation & Review | Phase complete |
---
## 🔄 Bootstrap Chain Overview
```
┌─────────────────┐
│ hako-frozen-v1 │
│ (Rust, 724KB) │
└────────┬────────┘
│
│ compiles
v
┌─────────────────┐
│ bootstrap_v1 │
│ (Hakorune code) │
│ runs on frozen │
└────────┬────────┘
│
│ compiles itself
v
┌─────────────────┐
│ bootstrap_v2.c │
│ (C source) │
└────────┬────────┘
│
│ clang + NyRT
v
┌─────────────────┐
│ bootstrap_v2 │
│ (native binary) │
└─────────────────┘
Verify: v1 output == v2 output ✅
```
---
## 💡 Implementation Strategy
### Decision: Option B (Reuse apps/selfhost-compiler/)
**Rationale**:
- 2500 lines of existing, tested code
- 170 smoke tests already PASS
- 90%+ reusability
- Proven architecture
**Code Reuse Breakdown**:
```
✅ 90% Reusable: Parser, Emitter, MIR Builder (2250 lines)
⚠️ 10% Adaptation: using paths, Box constraints (250 lines)
❌ New Code: C Code Generator (500 lines)
Total Effort: ~750 lines (vs 2500+ for Option A)
```
---
## 🧪 Test Strategy
### Test Pyramid
```
/\
/ \ Level 3: Self-Compilation (1 test, slow)
/____\ - v1 compiles itself → v2
/ \ - v2 compiles itself → v3
/ \ - Verify: v2 == v3
/__________\
/ \ Level 2: Comprehensive (10 tests, medium)
/ \ - If/else, loops, functions, boxes, arrays
/________________\
/ \ Level 1: Smoke Tests (43 tests, fast)
- Each MIR instruction
- Basic parsing
- C generation
```
---
## 📦 Directory Structure
```
Phase 20.5 Planning:
docs/private/roadmap/phases/phase-20.5/
├── INDEX.md # ← You are here
├── README.md # Phase overview
├── MILESTONE.md # Milestones & DoD
├── BOOTSTRAP_CHAIN_ANALYSIS.md # 3-stage bootstrap
├── C_CODE_GENERATOR_DESIGN.md # C codegen design
├── REUSABILITY_ANALYSIS.md # (Week 1-2 deliverable)
├── RISK_ASSESSMENT.md # (Week 1-2 deliverable)
├── IMPLEMENTATION_GUIDE.md # (Week 3+ deliverable)
└── COMPLETION_REPORT.md # (Week 10 deliverable)
Implementation:
apps/bootstrap-compiler/
├── parser/ # Week 3-4
│ ├── parser_box.hako
│ └── lexer_box.hako
├── mir_builder/ # Week 5-6
│ └── builder_box.hako
├── codegen/ # Week 7-8
│ ├── c_emitter_box.hako
│ └── c_runtime_box.hako
├── tests/ # Week 3-9
│ ├── smoke/ # 43 tests
│ ├── integration/ # 10 tests
│ └── bootstrap/ # 1 test (v1==v2==v3)
├── main.hako # Entry point
└── README.md # User guide
```
---
## 🚀 Quick Start (After Phase Complete)
### Compile a Hakorune Program
```bash
# Stage 1: Use frozen EXE to run bootstrap compiler
./hako-frozen-v1 apps/bootstrap-compiler/main.hako \
--input my_program.hako \
--output my_program.c
# Stage 2: Compile C to native binary
clang my_program.c -o my_program \
-L /path/to/hako_kernel \
-lhako_kernel \
-lpthread -ldl -lm
# Stage 3: Run
./my_program
```
### Verify Bootstrap Chain
```bash
# Run verification script
bash tools/verify_bootstrap_chain.sh
# Expected output:
# ✅ Stage 1 → Stage 2: OK
# ✅ Stage 2 → Stage 3: OK
# ✅ v1 == v2: VERIFIED
# ✅ v2 == v3: VERIFIED (fixed point)
# ✅ Bootstrap chain complete!
```
---
## ⚠️ Prerequisites
### From Phase 15.77
- [x] Frozen EXE built and tested (`hako-frozen-v1.exe`)
- [x] NyRT function calls working (Result: 6 test PASS)
- [x] MIR JSON → .o → EXE pipeline verified
- [x] Windows (MSVC/MinGW) + Linux support
### For Phase 20.5
- [ ] apps/selfhost-compiler/ analysis complete (Week 1-2)
- [ ] Frozen EXE constraints documented (Week 1-2)
- [ ] C Code Generator design approved (Week 1-2)
- [ ] Test infrastructure ready (Week 3+)
---
## 🎯 Success Criteria Summary
### Technical
- [ ] Bootstrap chain works: Stage 1 → 2 → 3
- [ ] C Code Generator: 16/16 instructions supported
- [ ] Verification: v1 == v2 == v3 (identical output)
- [ ] Tests: 43 smoke + 10 integration + 1 bootstrap PASS
### Performance
- [ ] Stage 2 compile time: < 30s for self-compilation
- [ ] Stage 3 compile time: < 5s for self-compilation
- [ ] Memory usage: < 100MB
### Quality
- [ ] Documentation complete (user guide + design docs)
- [ ] Code is modular (Box-based)
- [ ] Edge cases covered
- [ ] Review approved (ChatGPT + Claude)
---
## 📚 Related Phases
### Previous
- [Phase 15.77 - Frozen EXE Finalization](../phase-15.77/)
- [Phase 15.76 - extern_c & Frozen Toolchain](../phase-15.76/)
- [Phase 15.75 - Escape from Rust Planning](../phase-15.75/)
### Next
- **Phase 20.6 - Complete Rust Removal**
- VM executor → Hakorune implementation
- Rust codebase → 0 lines
- Pure Hakorune self-hosting
### Parallel
- [Phase 15.78 - Frozen UX Polish](../phase-15.78/)
- Distribution packaging
- Doctor improvements
- Windows polish
---
## 💬 Communication
### Weekly Sync Points
- **Monday**: Week start, goal setting
- **Wednesday**: Mid-week progress check
- **Friday**: Week review, next week planning
### Issue Tracking
- Use GitHub issues with label `phase-20.5`
- Prefix: `[20.5]` in commit messages
- Milestone: `Phase 20.5 - Bootstrap Compiler`
### Review Process
- Each week: Self-review + smoke tests
- Week 5, 10: Full review with ChatGPT/Claude
- Blocking issues: Immediate escalation
---
## 🔗 External Resources
### Industry Examples
- **Rust Bootstrap**: [Rust stage0 documentation](https://rustc-dev-guide.rust-lang.org/building/bootstrapping.html)
- **Go Bootstrap**: [Go 1.5 Bootstrap Process](https://go.dev/doc/go1.5#bootstrap)
- **OCaml Bootstrap**: [OCaml self-hosting](https://ocaml.org/docs/compiling-ocaml-projects)
### Papers
- [Rapid Self-Hosting Paper](../../../../private/papers-active/rapid-selfhost-ai-collaboration/)
- [Reflections on Trusting Trust](https://www.cs.cmu.edu/~rdriley/487/papers/Thompson_1984_ReflectionsonTrustingTrust.pdf) (Ken Thompson, 1984)
---
## 📝 Notes
### Naming Conventions
- **Stage 1**: Rust compiler, frozen EXE (`hako-frozen-v1`)
- **Stage 2**: Hakorune compiler v1 (`bootstrap_v1`)
- **Stage 3**: Hakorune compiler v2 (`bootstrap_v2`)
- **Fixed Point**: v2 == v3 (self-consistency)
### File Naming
- Test outputs: `test_v1.c`, `test_v2.c`
- Bootstrap outputs: `bootstrap_v2.c`, `bootstrap_v3.c`
- Always include version suffix for clarity
### Verification
- Use `diff` for exact comparison
- Use `md5sum` for quick hash checks
- Use `tools/verify_bootstrap_chain.sh` for automation
---
**Created**: 2025-10-14
**Last Updated**: 2025-10-14
**Status**: Planning (Phase not yet started)
**Next Review**: 2025-12-21 (Phase start)