docs: restore docs/private/roadmap from 7b4908f9 (Phase 20.31)
This commit is contained in:
nyash-codex
@ -0,0 +1,598 @@
|
||||
# Bootstrap Chain Analysis — Phase 20.5
|
||||
|
||||
Purpose: Detailed analysis of the 3-stage bootstrap chain for achieving true self-hosting
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Overview
|
||||
|
||||
**Goal**: Establish a bootstrap chain where Hakorune can compile itself
|
||||
|
||||
```
|
||||
Stage 1 (Rust Frozen) → Stage 2 (Hako v1) → Stage 3 (Hako v2)
|
||||
Trusted Bootstrap Verification
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Three-Stage Bootstrap Chain
|
||||
|
||||
### Stage 1: Rust Compiler (Frozen Toolchain)
|
||||
|
||||
**Identity**:
|
||||
- Binary: `hako-frozen-v1.exe` (724KB MSVC, 7.4MB MinGW)
|
||||
- Language: Rust
|
||||
- Status: **Frozen** (no changes after Phase 15.77)
|
||||
- Git Tag: `v1.0.0-frozen`
|
||||
|
||||
**Capabilities**:
|
||||
- Parse Hakorune source → AST
|
||||
- Lower AST → MIR JSON
|
||||
- Execute MIR (VM mode)
|
||||
- Call NyRT functions via C ABI
|
||||
|
||||
**Inputs/Outputs**:
|
||||
```
|
||||
Input: program.hako (Hakorune source)
|
||||
Output: program.mir.json (MIR JSON)
|
||||
OR
|
||||
program.exe (via AOT: MIR → .o → EXE)
|
||||
```
|
||||
|
||||
**Role in Bootstrap**:
|
||||
- Compile the Hakorune-written compiler (Stage 2)
|
||||
- Provide trusted baseline for verification
|
||||
- Emergency fallback if Stage 2/3 fail
|
||||
|
||||
**Constraints**:
|
||||
- No modifications allowed (frozen)
|
||||
- Limited Box set (String, Array, Map, Console, Time, JSON, File[min])
|
||||
- Must remain stable for reproducibility
|
||||
|
||||
---
|
||||
|
||||
### Stage 2: Hakorune Compiler v1 (Bootstrap)
|
||||
|
||||
**Identity**:
|
||||
- Source: `apps/bootstrap-compiler/**/*.hako`
|
||||
- Implementation: ~3000 lines Hakorune code
|
||||
- Compiled by: Stage 1 (frozen EXE)
|
||||
- Execution: On frozen EXE VM
|
||||
|
||||
**Capabilities**:
|
||||
- Parse Hakorune source → AST JSON
|
||||
- Lower AST → MIR JSON
|
||||
- Generate C code from MIR JSON
|
||||
- Output: `.c` files that link with NyRT
|
||||
|
||||
**Inputs/Outputs**:
|
||||
```
|
||||
Input: program.hako (Hakorune source)
|
||||
Output: program.c (C source code)
|
||||
|
||||
Execution:
|
||||
./hako-frozen-v1 apps/bootstrap-compiler/main.hako \
|
||||
--input program.hako \
|
||||
--output program.c
|
||||
```
|
||||
|
||||
**Role in Bootstrap**:
|
||||
- **Primary compiler**: Compile arbitrary Hakorune programs
|
||||
- **Self-compilation**: Compile its own source (Stage 2 → Stage 3)
|
||||
- **Verification baseline**: Reference for v2 output
|
||||
|
||||
**Implementation Strategy**:
|
||||
```
|
||||
apps/bootstrap-compiler/
|
||||
├── parser/ # Reuse from apps/selfhost-compiler/
|
||||
│ ├── parser_box.hako # 90% reusable
|
||||
│ └── lexer_box.hako
|
||||
├── mir_builder/ # Reuse from apps/selfhost-compiler/
|
||||
│ └── builder_box.hako # 80% reusable
|
||||
├── codegen/ # NEW - C Code Generator
|
||||
│ ├── c_emitter_box.hako
|
||||
│ └── c_runtime_box.hako
|
||||
└── main.hako # Entry point
|
||||
```
|
||||
|
||||
**Key Features**:
|
||||
1. **C Output**: Unlike frozen EXE (MIR JSON), outputs C code
|
||||
2. **Self-Hosting**: Can compile itself
|
||||
3. **NyRT Integration**: Generated C calls NyRT functions
|
||||
4. **Verification**: Must match Stage 3 output
|
||||
|
||||
---
|
||||
|
||||
### Stage 3: Hakorune Compiler v2 (Verification)
|
||||
|
||||
**Identity**:
|
||||
- Source: Same as Stage 2 (`apps/bootstrap-compiler/**/*.hako`)
|
||||
- Compiled by: Stage 2 (Hakorune v1)
|
||||
- Execution: As standalone EXE (or on frozen VM)
|
||||
|
||||
**Capabilities**:
|
||||
- **Identical to Stage 2**
|
||||
- Parse → MIR → C code generation
|
||||
|
||||
**Inputs/Outputs**:
|
||||
```
|
||||
Input: program.hako
|
||||
Output: program.c (must be identical to Stage 2 output)
|
||||
|
||||
Execution:
|
||||
# Compile v2 using v1
|
||||
./hako-frozen-v1 apps/bootstrap-compiler/main.hako \
|
||||
--input apps/bootstrap-compiler/main.hako \
|
||||
--output bootstrap_v2.c
|
||||
|
||||
# Compile bootstrap_v2.c → v2 binary
|
||||
clang bootstrap_v2.c -o bootstrap_v2 -lhako_kernel
|
||||
|
||||
# Use v2 to compile a test program
|
||||
./bootstrap_v2 --input test.hako --output test_v2.c
|
||||
```
|
||||
|
||||
**Role in Bootstrap**:
|
||||
- **Verification**: Prove v1 == v2 (identical output)
|
||||
- **Self-Consistency**: v2 can compile v3, v3 == v2
|
||||
- **Confidence**: If v1 == v2 == v3, bootstrap is successful
|
||||
|
||||
**Verification Process**:
|
||||
```bash
|
||||
# Step 1: v1 compiles test.hako
|
||||
./hako-frozen-v1 apps/bootstrap-compiler/main.hako \
|
||||
--input test.hako --output test_v1.c
|
||||
|
||||
# Step 2: v1 compiles itself → v2
|
||||
./hako-frozen-v1 apps/bootstrap-compiler/main.hako \
|
||||
--input apps/bootstrap-compiler/main.hako \
|
||||
--output bootstrap_v2.c
|
||||
|
||||
# Step 3: Build v2 binary
|
||||
clang bootstrap_v2.c -o bootstrap_v2 -lhako_kernel
|
||||
|
||||
# Step 4: v2 compiles test.hako
|
||||
./bootstrap_v2 --input test.hako --output test_v2.c
|
||||
|
||||
# Step 5: Verify v1 == v2
|
||||
diff test_v1.c test_v2.c
|
||||
# Expected: No differences
|
||||
|
||||
# Step 6 (optional): v2 compiles itself → v3
|
||||
./bootstrap_v2 --input apps/bootstrap-compiler/main.hako \
|
||||
--output bootstrap_v3.c
|
||||
|
||||
# Step 7: Verify v2 == v3
|
||||
diff bootstrap_v2.c bootstrap_v3.c
|
||||
# Expected: No differences
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Data Flow Analysis
|
||||
|
||||
### Stage 1 → Stage 2
|
||||
|
||||
**Input**: Hakorune compiler source (`apps/bootstrap-compiler/`)
|
||||
|
||||
**Process**:
|
||||
```
|
||||
[Hakorune Source]
|
||||
↓
|
||||
Stage 1: hako-frozen-v1.exe
|
||||
- Parser (Rust)
|
||||
- MIR Builder (Rust)
|
||||
- VM Executor (Rust)
|
||||
↓
|
||||
[Hakorune Compiler v1 Running on VM]
|
||||
- Capabilities: Parse, MIR Build, C Gen
|
||||
```
|
||||
|
||||
**Output**: Running Hakorune compiler (v1)
|
||||
|
||||
**Key Points**:
|
||||
- v1 runs **on** the frozen EXE VM
|
||||
- v1 is **interpreted**, not compiled to native
|
||||
- v1 has access to frozen EXE's Box set (String, Array, Map, etc.)
|
||||
|
||||
---
|
||||
|
||||
### Stage 2 → Stage 3
|
||||
|
||||
**Input**: Hakorune compiler source (same as Stage 1 input)
|
||||
|
||||
**Process**:
|
||||
```
|
||||
[Hakorune Compiler Source]
|
||||
↓
|
||||
Stage 2: Hakorune Compiler v1
|
||||
- Parser (Hakorune)
|
||||
- MIR Builder (Hakorune)
|
||||
- C Generator (Hakorune)
|
||||
↓
|
||||
[bootstrap_v2.c]
|
||||
↓
|
||||
clang + NyRT
|
||||
↓
|
||||
[bootstrap_v2 EXE]
|
||||
```
|
||||
|
||||
**Output**: Standalone Hakorune compiler binary (v2)
|
||||
|
||||
**Key Points**:
|
||||
- v2 is **native binary** (compiled C → EXE)
|
||||
- v2 is **independent** (doesn't need frozen EXE to run)
|
||||
- v2 must produce **identical output** to v1
|
||||
|
||||
---
|
||||
|
||||
### Stage 3 → Verification
|
||||
|
||||
**Process**:
|
||||
```
|
||||
Test Program (test.hako)
|
||||
│
|
||||
┌─────┴─────┐
|
||||
│ │
|
||||
v v
|
||||
Stage 2 Stage 3
|
||||
(v1) (v2)
|
||||
│ │
|
||||
v v
|
||||
test_v1.c test_v2.c
|
||||
│ │
|
||||
└─────┬─────┘
|
||||
│
|
||||
diff
|
||||
│
|
||||
v
|
||||
Identical? ✅
|
||||
```
|
||||
|
||||
**Verification Criteria**:
|
||||
1. **Bytecode Level**: test_v1.c == test_v2.c (character-by-character)
|
||||
2. **Semantic Level**: Compiled EXEs produce same output
|
||||
3. **Recursive**: v2 → v3, v3 == v2 (fixed point)
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ Technical Constraints
|
||||
|
||||
### Stage 1 Constraints (Frozen EXE)
|
||||
|
||||
**Available Boxes**:
|
||||
```
|
||||
✅ String - Full support
|
||||
✅ Array - Full support
|
||||
✅ Map - Full support
|
||||
✅ Console (print) - Output only
|
||||
✅ Time (now_ms) - Timing
|
||||
✅ JSON (stringify) - JSON generation
|
||||
✅ File[min] - Read/write (minimal)
|
||||
```
|
||||
|
||||
**NOT Available**:
|
||||
```
|
||||
❌ Regex - Too heavy for frozen
|
||||
❌ Network - Security concern
|
||||
❌ OS/Path (extended) - Environment-specific
|
||||
❌ Crypto - Not needed for compiler
|
||||
```
|
||||
|
||||
**Implications**:
|
||||
- Hakorune compiler must work with limited Box set
|
||||
- No regex for parsing (use manual string ops)
|
||||
- No network I/O for compiler
|
||||
- File I/O limited to read source, write output
|
||||
|
||||
### Stage 2 Constraints (Hakorune v1)
|
||||
|
||||
**Execution Environment**:
|
||||
- Runs **on** frozen EXE VM (interpreted)
|
||||
- No native compilation until Stage 3
|
||||
- Performance: ~10x slower than native (acceptable)
|
||||
|
||||
**Implementation Constraints**:
|
||||
- Must use only frozen EXE Box set
|
||||
- Cannot rely on Rust-specific features
|
||||
- Must be pure Hakorune code
|
||||
|
||||
**Memory Constraints**:
|
||||
- VM register limit: 256 per function (typical)
|
||||
- Stack depth: Limited by VM (avoid deep recursion)
|
||||
- Heap: Managed by frozen EXE GC
|
||||
|
||||
### Stage 3 Constraints (Hakorune v2)
|
||||
|
||||
**Binary Constraints**:
|
||||
- Must link with NyRT (`libhako_kernel.a`)
|
||||
- C code must be valid C11
|
||||
- No undefined behavior
|
||||
|
||||
**Verification Constraints**:
|
||||
- Output must be **deterministic**
|
||||
- No timestamps, PIDs, or non-deterministic data in output
|
||||
- Identical AST/MIR JSON for same input
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Success Criteria
|
||||
|
||||
### Functional Success
|
||||
|
||||
1. **Stage 1 → 2 Works**:
|
||||
```bash
|
||||
./hako-frozen-v1 apps/bootstrap-compiler/main.hako \
|
||||
--input hello.hako --output hello_v1.c
|
||||
# ✅ Compiles successfully
|
||||
```
|
||||
|
||||
2. **Stage 2 → 3 Works**:
|
||||
```bash
|
||||
./bootstrap_v1 --input apps/bootstrap-compiler/main.hako \
|
||||
--output bootstrap_v2.c
|
||||
clang bootstrap_v2.c -o bootstrap_v2 -lhako_kernel
|
||||
# ✅ Builds successfully
|
||||
```
|
||||
|
||||
3. **v1 == v2 Verification**:
|
||||
```bash
|
||||
diff <(./bootstrap_v1 --input test.hako) \
|
||||
<(./bootstrap_v2 --input test.hako)
|
||||
# ✅ No differences
|
||||
```
|
||||
|
||||
4. **v2 == v3 Fixed Point**:
|
||||
```bash
|
||||
./bootstrap_v2 --input apps/bootstrap-compiler/main.hako \
|
||||
--output bootstrap_v3.c
|
||||
diff bootstrap_v2.c bootstrap_v3.c
|
||||
# ✅ No differences (fixed point reached)
|
||||
```
|
||||
|
||||
### Performance Success
|
||||
|
||||
1. **Stage 2 Compile Time**:
|
||||
- Simple program (< 100 lines): < 2 seconds
|
||||
- Medium program (< 1000 lines): < 10 seconds
|
||||
- Compiler itself (3000 lines): < 30 seconds
|
||||
|
||||
2. **Stage 3 Compile Time**:
|
||||
- Should be ~10x faster than Stage 2 (native vs interpreted)
|
||||
- Simple program: < 0.5 seconds
|
||||
- Medium program: < 2 seconds
|
||||
- Compiler itself: < 5 seconds
|
||||
|
||||
3. **Memory Usage**:
|
||||
- Stage 2: < 100MB
|
||||
- Stage 3: < 50MB
|
||||
|
||||
### Quality Success
|
||||
|
||||
1. **Test Coverage**:
|
||||
- 10+ test programs compile correctly
|
||||
- All 16 MIR instructions covered
|
||||
- Edge cases tested (recursion, loops, etc.)
|
||||
|
||||
2. **Error Handling**:
|
||||
- Parse errors: Clear messages
|
||||
- MIR errors: Diagnostic output
|
||||
- C generation errors: Fail-fast with context
|
||||
|
||||
3. **Maintainability**:
|
||||
- Code is modular (Box-based)
|
||||
- Each component has tests
|
||||
- Documentation for each Box
|
||||
|
||||
---
|
||||
|
||||
## 🔍 Verification Strategy
|
||||
|
||||
### Level 1: Smoke Tests (Fast)
|
||||
|
||||
**Goal**: Quick sanity check
|
||||
|
||||
```bash
|
||||
# Test 1: Hello World
|
||||
echo 'static box Main { main() { return 42 } }' > hello.hako
|
||||
./bootstrap_v1 --input hello.hako --output hello_v1.c
|
||||
./bootstrap_v2 --input hello.hako --output hello_v2.c
|
||||
diff hello_v1.c hello_v2.c # ✅
|
||||
|
||||
# Test 2: Arithmetic
|
||||
cat > arith.hako << 'EOF'
|
||||
static box Main {
|
||||
main() {
|
||||
local x = 10
|
||||
local y = 20
|
||||
return x + y
|
||||
}
|
||||
}
|
||||
EOF
|
||||
./bootstrap_v1 --input arith.hako --output arith_v1.c
|
||||
./bootstrap_v2 --input arith.hako --output arith_v2.c
|
||||
diff arith_v1.c arith_v2.c # ✅
|
||||
```
|
||||
|
||||
### Level 2: Comprehensive Tests (Medium)
|
||||
|
||||
**Goal**: Test all language features
|
||||
|
||||
```bash
|
||||
# Test Suite: 10 programs covering:
|
||||
# - If/else
|
||||
# - Loops
|
||||
# - Functions
|
||||
# - Boxes
|
||||
# - Arrays
|
||||
# - Strings
|
||||
# - Recursion
|
||||
# - etc.
|
||||
|
||||
for test in tests/*.hako; do
|
||||
name=$(basename "$test" .hako)
|
||||
./bootstrap_v1 --input "$test" --output "${name}_v1.c"
|
||||
./bootstrap_v2 --input "$test" --output "${name}_v2.c"
|
||||
diff "${name}_v1.c" "${name}_v2.c" || exit 1
|
||||
done
|
||||
echo "✅ All tests passed"
|
||||
```
|
||||
|
||||
### Level 3: Self-Compilation (Slow)
|
||||
|
||||
**Goal**: Verify fixed point (v2 == v3)
|
||||
|
||||
```bash
|
||||
# Compile v2
|
||||
./bootstrap_v1 --input apps/bootstrap-compiler/main.hako \
|
||||
--output bootstrap_v2.c
|
||||
clang bootstrap_v2.c -o bootstrap_v2 -lhako_kernel
|
||||
|
||||
# Compile v3 using v2
|
||||
./bootstrap_v2 --input apps/bootstrap-compiler/main.hako \
|
||||
--output bootstrap_v3.c
|
||||
|
||||
# Verify v2 == v3
|
||||
diff bootstrap_v2.c bootstrap_v3.c
|
||||
echo "✅ Fixed point reached: v2 == v3"
|
||||
|
||||
# (Optional) Compile v4 using v3, verify v3 == v4
|
||||
clang bootstrap_v3.c -o bootstrap_v3 -lhako_kernel
|
||||
./bootstrap_v3 --input apps/bootstrap-compiler/main.hako \
|
||||
--output bootstrap_v4.c
|
||||
diff bootstrap_v3.c bootstrap_v4.c
|
||||
echo "✅ Fixed point stable: v3 == v4"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Bootstrap Timeline Estimate
|
||||
|
||||
### Week 3-4: Parser Adaptation (Stage 1 → 2 foundation)
|
||||
- Migrate apps/selfhost-compiler/parser/ → apps/bootstrap-compiler/
|
||||
- Adapt to frozen EXE constraints
|
||||
- Test: 10 parsing tests PASS
|
||||
|
||||
**Output**: Stage 2 can parse Hakorune → AST JSON
|
||||
|
||||
### Week 5-6: MIR Builder (Stage 1 → 2 complete)
|
||||
- Migrate MIR Builder
|
||||
- Support 16 instructions
|
||||
- Test: 10 MIR generation tests PASS
|
||||
|
||||
**Output**: Stage 2 can parse → MIR JSON
|
||||
|
||||
### Week 7-8: C Code Generator (Stage 2 → 3 foundation)
|
||||
- Implement C emitter
|
||||
- 16 instructions → C
|
||||
- Test: 43 C generation tests PASS
|
||||
|
||||
**Output**: Stage 2 can parse → MIR → C
|
||||
|
||||
### Week 9: Bootstrap Integration (Stage 2 ↔ 3)
|
||||
- Compile v2 using v1
|
||||
- Verify v1 == v2 (10 tests)
|
||||
- Verify v2 == v3 (fixed point)
|
||||
|
||||
**Output**: Bootstrap chain complete, verified
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Risk Analysis
|
||||
|
||||
### Risk 1: v1 != v2 (Output Mismatch)
|
||||
|
||||
**Probability**: MEDIUM
|
||||
**Impact**: HIGH
|
||||
|
||||
**Causes**:
|
||||
- Non-deterministic output (timestamps, PIDs)
|
||||
- Floating-point precision differences
|
||||
- Hash map iteration order
|
||||
- Different AST/MIR construction
|
||||
|
||||
**Mitigation**:
|
||||
- Enforce deterministic output
|
||||
- Canonical JSON formatting (sorted keys)
|
||||
- Test incrementally (Stage 1 → 2 first)
|
||||
- Golden tests with known outputs
|
||||
|
||||
### Risk 2: Performance Too Slow
|
||||
|
||||
**Probability**: LOW
|
||||
**Impact**: MEDIUM
|
||||
|
||||
**Causes**:
|
||||
- Stage 2 is interpreted (10x slower)
|
||||
- Inefficient algorithms
|
||||
- Excessive memory allocation
|
||||
|
||||
**Mitigation**:
|
||||
- Profile Stage 2 execution
|
||||
- Optimize hot paths
|
||||
- Acceptable threshold: < 30s for self-compilation
|
||||
|
||||
### Risk 3: Frozen EXE Constraints Too Limiting
|
||||
|
||||
**Probability**: LOW
|
||||
**Impact**: MEDIUM
|
||||
|
||||
**Causes**:
|
||||
- Missing Box functionality
|
||||
- File I/O limitations
|
||||
- Memory constraints
|
||||
|
||||
**Mitigation**:
|
||||
- Pre-survey required Boxes (done)
|
||||
- Workarounds in Hakorune code
|
||||
- Minimal compiler design (no advanced features)
|
||||
|
||||
---
|
||||
|
||||
## 🎉 Success Impact
|
||||
|
||||
After Bootstrap Chain is verified:
|
||||
|
||||
1. **True Self-Hosting**: Hakorune compiles Hakorune
|
||||
2. **Reproducibility**: v2 == v3 proves determinism
|
||||
3. **Independence**: No Rust needed for new features
|
||||
4. **Foundation**: Ready for Phase 20.6 (complete Rust removal)
|
||||
|
||||
---
|
||||
|
||||
## 📚 Industry Examples
|
||||
|
||||
### Rust Bootstrap
|
||||
|
||||
```
|
||||
stage0 (frozen) → stage1 (bootstrap) → stage2 (verify)
|
||||
| | |
|
||||
rustc rustc (built by stage0) rustc (built by stage1)
|
||||
(frozen)
|
||||
Verify: stage1 == stage2
|
||||
```
|
||||
|
||||
### Go Bootstrap
|
||||
|
||||
```
|
||||
Go 1.4 (C) → Go 1.5 (built by Go 1.4) → Go 1.6 (built by Go 1.5)
|
||||
| | |
|
||||
Frozen Bootstrap Verification
|
||||
```
|
||||
|
||||
### Hakorune Bootstrap (Our Plan)
|
||||
|
||||
```
|
||||
hako-frozen-v1.exe → bootstrap_v1 (Hako) → bootstrap_v2 (Hako)
|
||||
| | |
|
||||
Rust Interpreted Native Binary
|
||||
(frozen) (on frozen VM) (standalone)
|
||||
|
||||
Verify: v1 == v2 == v3 (fixed point)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Created**: 2025-10-14
|
||||
**Phase**: 20.5
|
||||
**Component**: Bootstrap Chain Analysis
|
||||
@ -0,0 +1,223 @@
|
||||
# ChatGPT Pro: Pure Hakorune Strategy (2025-10-14)
|
||||
|
||||
## Context
|
||||
|
||||
This document captures ChatGPT Pro's strategic recommendation for Phase 20.5, received on 2025-10-14.
|
||||
|
||||
**Original Question**: Should we implement a C Code Generator (500 lines) or pursue a different strategy for "Escape from Rust"?
|
||||
|
||||
**ChatGPT Pro's Answer**: Go for **Pure Hakorune VM** - implement the VM itself in Hakorune, not just a compiler.
|
||||
|
||||
---
|
||||
|
||||
## Original Response (Japanese)
|
||||
|
||||
凍結 EXE（Ubuntu/Windows）& C ABI 到達、おめでとにゃー！🎉
|
||||
`selfhost` ブランチにも Windows 成果物っぽいパスや C/extern の検証用スクリプトが見えるので、今が"脱 Rust を箱理論で仕上げる"最適タイミングだよ。たとえば `build/windows_artifacts/`、`hako.toml`、`static_plugins.toml`、`test_hostbridge_call.hako` などが並んでいるのを確認できた（public 側の `selfhost` ブランチ）。
|
||||
|
||||
以下、"Rust＝床（薄い橋）/ Hakorune＝家（振る舞い）"で**きれいに脱 Rust**するための**箱理論ブループリント**を置いておくね。
|
||||
|
||||
---
|
||||
|
||||
## 0) 境界の原則（ここだけはブレさせない）
|
||||
|
||||
1. **唯一の境界は C-ABI（＝HostBridge）**
|
||||
|
||||
* OS/FFI/ファイル/プロセスは **C ABI の薄いシム**（`hakorune_host` 的な C 層）だけが扱う。
|
||||
* それ以外は **Everything is Box** で Hako 側に寄せる（VM/等価/コレクション/ディスパッチ/マクロ）。
|
||||
|
||||
2. **呼び出しは MethodHandle 一経路**
|
||||
|
||||
* `Resolver.lookup(type_id, :method, arity) -> MethodHandle`
|
||||
* `CallableBox.call` は `ExecBox.call_by_handle(handle, args, NoOperatorGuard)` 固定。
|
||||
* これで equals/== の再入事故を完全封殺（以前の無限再帰の学びを反映）。
|
||||
|
||||
3. **決定モードの厳格化**
|
||||
|
||||
* C 経由での非決定機能は **caps** で拒否。
|
||||
* 生成物・メソッドに **Provenance**（plugin_id/version）を残す。
|
||||
|
||||
---
|
||||
|
||||
## 1) 構成（箱で縫う分割）
|
||||
|
||||
**Rust（床/最小橋）**
|
||||
|
||||
* プロセス起動・CLI
|
||||
* C ABI の輸出入（dlopen・`extern "C"`）
|
||||
* LLVM/WASM ブリッジ（薄いハンドル）
|
||||
* 最小のファイル/OS I/O（Capability ゲート付き）
|
||||
|
||||
**Hakorune（家/本実装）**
|
||||
|
||||
* パーサ/マクロ/脱糖（@macro/@facet/@enum/@match）
|
||||
* Lower/SSA/Verifier/Tracer
|
||||
* VM ディスパッチ（MIR14 実行）
|
||||
* op_eq/算術/論理/配列/Map/enum/@match の意味論
|
||||
* Resolver + CallableBox（動的ディスパッチ）
|
||||
* コレクション実装（MapBox/ArrayBox）
|
||||
* プラグイン・ポリシ（`new→birth` 一元化、`HAKO_PLUGIN_POLICY=auto`）
|
||||
|
||||
> すでに selfhost ブランチに `hako.toml` / `static_plugins.toml` / `test_hostbridge_call.hako` があるので、この境界は今のリポ構成と自然に噛むはず。
|
||||
|
||||
---
|
||||
|
||||
## 2) 移行フェーズ（Strangler Fig）
|
||||
|
||||
### Phase A — **HostBridge 固定化（3項目）**
|
||||
|
||||
* **C-ABI シムの最小 API 固定**
|
||||
|
||||
* `Hako_RunScriptUtf8(src, &out_handle)`
|
||||
* `Hako_Retain/Release`（ハンドル所有権）
|
||||
* `Hako_ToUtf8(HakoHandle, &HakoStr)`（文字列 view）
|
||||
* エラーは `int` 戻り＋`Hako_LastError()`（TLS）。
|
||||
* **Hakorune 側に HostBridgeBox**
|
||||
|
||||
* C 呼び出しは **必ずこの箱を経由**。
|
||||
* **CI：Ubuntu/Windows の ABI テスト**
|
||||
|
||||
* ローダ/解決/呼び出し／戻り値が両 OS で一致すること。
|
||||
|
||||
> Windows 成果物ディレクトリがある今が整備の良いタイミング（`build/windows_artifacts/`）。
|
||||
|
||||
### Phase B — **VM コアの Hako 化**
|
||||
|
||||
* **命令ディスパッチ**（`pc`/frame/blk jump）を Hako で実装
|
||||
* **`op_eq` を Hako 側へ**
|
||||
|
||||
* 先頭に `ptr_eq` → プリミティブ → Array/Map → 構造（@enum）→ ユーザ equals
|
||||
* 呼出は常に **NoOperatorGuard**
|
||||
* **ゴールデン比較**
|
||||
|
||||
* Rust-VM と Hako-VM で **同一プログラムのトレース/出力/ハッシュ一致**
|
||||
* selfhost 用スイートを固定化（`CURRENT_TASK_SELFHOST.md` があるので入れやすい）。
|
||||
|
||||
### Phase C — **ディスパッチの一本化**
|
||||
|
||||
* **Resolver + CallableBox を既定経路に**
|
||||
|
||||
* `arr.methodRef("push",1)` は **マクロ脱糖**で `Callable.ref_method(arr, :push, 1)` に
|
||||
* Universal ルートの "疑似メソッド" 実装は **最小**に留め、実体は Resolver 呼び
|
||||
|
||||
### Phase D — **コレクションの箱実装**
|
||||
|
||||
* **MapBox/ArrayBox を Hako 実装に寄せる**
|
||||
|
||||
* **Key 正規化**（Symbol/Int/String の比較規約）
|
||||
* **Deterministic hash/eq**（決定モードで固定）
|
||||
* **ValueBox/DataBox** の位置づけ
|
||||
|
||||
* パイプライン境界には ValueBox を通して **Fail‑Fast** に型を確定
|
||||
* 長持ちは避け、**入口/出口で早めに解包**
|
||||
|
||||
### Phase E — **GC v0 + 観測**
|
||||
|
||||
* **Stop-the-world mark&sweep（最小）**
|
||||
|
||||
* まずは到達可能集合のマークのみでもよい
|
||||
* **メトリクス**：alloc・survivor・sweep 時間・ハンドル数
|
||||
|
||||
### Phase F — **Rust VM の"互換モード化"**
|
||||
|
||||
* Hako-VM を既定、Rust-VM は `--backend vm-rust` のみに降格
|
||||
* 二重セルフビルド（Hako₁→Hako₂→Hako₃）で **bit-identical** を連日チェック
|
||||
|
||||
---
|
||||
|
||||
## 3) ルールカード（箱言語としての"契約"）
|
||||
|
||||
* **唯一の境界**：HostBridge（C-ABI）。
|
||||
* **唯一の呼び出し**：`ExecBox.call_by_handle(handle, args, NoOperatorGuard)`。
|
||||
* **唯一の解決**：`Resolver.lookup(type_id, method, arity)`。
|
||||
* **唯一の型越境**：`DataBox/ValueBox`（入口/出口のみ）。
|
||||
* **プラグイン**：`new → birth` を **VM 側で必ず**呼ぶ（birth 未実装は no‑op）。
|
||||
* **決定モード**：caps でゲート、Provenance を刻む。
|
||||
|
||||
---
|
||||
|
||||
## 4) すぐできる"今日の 3 つ"
|
||||
|
||||
1. **HostBridge API を `include/` 配下に固定**（`.h` 自動生成 & バージョン関数）
|
||||
|
||||
* 例：`Hako_ApiVersion()` / 名前は `hako1_*` プレフィクス
|
||||
2. **`Callable.ref_method` を実装**（Resolver 経由で MethodHandle を取得）
|
||||
|
||||
* `arr.methodRef("push",1)` はマクロで脱糖（ArrayBox 側に直生やさない）
|
||||
3. **`op_eq` を Hako へ移し、Rust 側の equals ガードは入口で `NoOperatorGuard` に**
|
||||
|
||||
* 無限再帰の経路を構造的に断つ
|
||||
|
||||
---
|
||||
|
||||
## 5) リポに合わせた小メモ
|
||||
|
||||
* `selfhost` ブランチに **hostbridge 検証**、**構成ファイル（`hako.toml`/`static_plugins.toml`）**、**Windows 成果物**が見えているので、このまま **HostBridge→VM→Resolver** の順で固めるのが最短。
|
||||
* README には CLI/バックエンドの扱い・フェーズポリシが書かれているので（selfhost）、ここに **"Rust=床/Hako=家" の宣言**と **C-ABI 安定ポリシ**を追記しておくと、今後の PR レビューが楽になる。
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
* すでに **凍結 EXE** と **C-ABI 呼び出し**まで到達してる今、**境界＝C-ABI/呼出＝Handle/解決＝Resolver** の"三位一体"だけを不動にして、**中身（VM・コレクション・等価・ディスパッチ）を全部 Hakorune 側に寄せる**のが一番きれい。
|
||||
* Rust は **OS の薄い橋**に収斂させ、**箱で構成された言語の"家"**をどんどん厚くしていこう。
|
||||
|
||||
必要なら、`HostBridge.h` の最小テンプレ、`Callable.ref_method` の擬似コード、`op_eq` の比較順テンプレもすぐ出せるよ。
|
||||
|
||||
---
|
||||
|
||||
## Key Differences from Original Plan
|
||||
|
||||
**Original Plan (Task Agent)**:
|
||||
- Implement C Code Generator (500 lines)
|
||||
- Generate C code from Hakorune programs
|
||||
- Link with `hako_kernel.lib`
|
||||
- Focus: Bootstrap compiler in 10 weeks
|
||||
|
||||
**ChatGPT Pro's Proposal**:
|
||||
- Implement VM itself in Hakorune
|
||||
- Rust becomes minimal bridge (HostBridge only)
|
||||
- Everything else in Hakorune (VM, collections, dispatch)
|
||||
- Focus: Long-term architecture, not short-term bootstrap
|
||||
|
||||
**Timeline**:
|
||||
- Original: 10 weeks (Phase 20.5 complete)
|
||||
- Pure Hakorune: 30+ weeks (Phase 20.5→15.80→15.81→15.82)
|
||||
|
||||
**Philosophy**:
|
||||
```
|
||||
Original: "Hakorune compiles Hakorune" (via C code)
|
||||
Pure Hako: "Hakorune IS Hakorune" (VM in Hakorune)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Analysis
|
||||
|
||||
**Advantages of Pure Hakorune Strategy**:
|
||||
- ✅ Architecturally elegant ("Rust=floor, Hakorune=house")
|
||||
- ✅ Long-term maintainability (minimal Rust dependency)
|
||||
- ✅ Reflects past learnings (equals/== recursion fix)
|
||||
- ✅ Ultimate Box Theory realization
|
||||
|
||||
**Challenges**:
|
||||
- ⚠️ Much longer timeline (30+ weeks vs 10 weeks)
|
||||
- ⚠️ Higher implementation complexity (VM in Hakorune)
|
||||
- ⚠️ Requires phased approach (can't do all in Phase 20.5)
|
||||
|
||||
**Recommendation**:
|
||||
- Phase 20.5 (10 weeks): Phase A (HostBridge) + Phase B start (VM foundations)
|
||||
- Phase 20.6 (12 weeks): Phase B complete (VM core) + Phase C (Dispatch)
|
||||
- Phase 20.7 (8 weeks): Phase D (Collections in Hakorune)
|
||||
- Phase 20.8 (6 weeks): Phase E (GC v0) + Phase F (Rust VM compat mode)
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Get Task Agent's opinion**: Can we reconcile the two approaches?
|
||||
2. **Revise Phase 20.5 plan**: HostBridge + VM foundations (not C Generator)
|
||||
3. **Create Phase 20.6-15.82 roadmap**: Pure Hakorune completion
|
||||
4. **Decision point**: Do we accept the longer timeline for architectural elegance?
|
||||
|
||||
**User's preference**: "純 Hakorune 大作戦" (Pure Hakorune Grand Strategy) ✅
|
||||
@ -0,0 +1,709 @@
|
||||
# C Code Generator Design — Phase 20.5
|
||||
|
||||
Purpose: Convert MIR JSON to executable C code that links with NyRT runtime
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Design Goals
|
||||
|
||||
1. **Correctness First**: Readable output is secondary to correct execution
|
||||
2. **NyRT Dependency**: All Box operations via NyRT function calls
|
||||
3. **16-Instruction Complete**: Support entire MIR frozen instruction set
|
||||
4. **Test-Driven**: Each instruction has dedicated test cases
|
||||
|
||||
---
|
||||
|
||||
## 📋 MIR Instruction Set → C Mapping
|
||||
|
||||
### 1. Const
|
||||
|
||||
**MIR**:
|
||||
```json
|
||||
{
|
||||
"op": "const",
|
||||
"dst": 0,
|
||||
"value": {"type": "Int", "value": 42}
|
||||
}
|
||||
```
|
||||
|
||||
**C Output**:
|
||||
```c
|
||||
int64_t v0 = 42;
|
||||
```
|
||||
|
||||
**String Constant**:
|
||||
```json
|
||||
{
|
||||
"op": "const",
|
||||
"dst": 1,
|
||||
"value": {"type": "String", "value": "Hello"}
|
||||
}
|
||||
```
|
||||
|
||||
**C Output**:
|
||||
```c
|
||||
int64_t v1 = nyash_box_from_i8_string("Hello");
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. BinOp
|
||||
|
||||
**MIR**:
|
||||
```json
|
||||
{
|
||||
"op": "binop",
|
||||
"dst": 2,
|
||||
"kind": "Add",
|
||||
"lhs": 0,
|
||||
"rhs": 1
|
||||
}
|
||||
```
|
||||
|
||||
**C Output**:
|
||||
```c
|
||||
int64_t v2 = v0 + v1; // For integers
|
||||
```
|
||||
|
||||
**Box BinOp** (via NyRT):
|
||||
```c
|
||||
int64_t v2 = nyrt_int_add(v0, v1);
|
||||
```
|
||||
|
||||
**All BinOp Kinds**:
|
||||
```c
|
||||
Add → + (or nyrt_int_add)
|
||||
Sub → - (or nyrt_int_sub)
|
||||
Mul → * (or nyrt_int_mul)
|
||||
Div → / (or nyrt_int_div)
|
||||
Mod → % (or nyrt_int_mod)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. Compare
|
||||
|
||||
**MIR**:
|
||||
```json
|
||||
{
|
||||
"op": "compare",
|
||||
"dst": 3,
|
||||
"kind": "Gt",
|
||||
"lhs": 0,
|
||||
"rhs": 1
|
||||
}
|
||||
```
|
||||
|
||||
**C Output**:
|
||||
```c
|
||||
int64_t v3 = (v0 > v1) ? 1 : 0;
|
||||
```
|
||||
|
||||
**All Compare Kinds**:
|
||||
```c
|
||||
Eq → ==
|
||||
Ne → !=
|
||||
Lt → <
|
||||
Le → <=
|
||||
Gt → >
|
||||
Ge → >=
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. Jump
|
||||
|
||||
**MIR**:
|
||||
```json
|
||||
{
|
||||
"op": "jump",
|
||||
"target": "bb1"
|
||||
}
|
||||
```
|
||||
|
||||
**C Output**:
|
||||
```c
|
||||
goto bb1;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. Branch
|
||||
|
||||
**MIR**:
|
||||
```json
|
||||
{
|
||||
"op": "branch",
|
||||
"cond": 3,
|
||||
"then_block": "bb_then",
|
||||
"else_block": "bb_else"
|
||||
}
|
||||
```
|
||||
|
||||
**C Output**:
|
||||
```c
|
||||
if (v3) {
|
||||
goto bb_then;
|
||||
} else {
|
||||
goto bb_else;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 6. Phi
|
||||
|
||||
**MIR**:
|
||||
```json
|
||||
{
|
||||
"op": "phi",
|
||||
"dst": 5,
|
||||
"inputs": [
|
||||
{"block": "bb_then", "value": 1},
|
||||
{"block": "bb_else", "value": 2}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**C Output** (pre-computed):
|
||||
```c
|
||||
// At bb_then:
|
||||
phi_v5 = v1;
|
||||
goto bb_merge;
|
||||
|
||||
// At bb_else:
|
||||
phi_v5 = v2;
|
||||
goto bb_merge;
|
||||
|
||||
// At bb_merge:
|
||||
int64_t v5 = phi_v5;
|
||||
```
|
||||
|
||||
**Note**: PHI requires preprocessing to convert to explicit assignments before merge blocks.
|
||||
|
||||
---
|
||||
|
||||
### 7. Return
|
||||
|
||||
**MIR**:
|
||||
```json
|
||||
{
|
||||
"op": "ret",
|
||||
"value": 3
|
||||
}
|
||||
```
|
||||
|
||||
**C Output**:
|
||||
```c
|
||||
return v3;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 8. Call (Global Function)
|
||||
|
||||
**MIR**:
|
||||
```json
|
||||
{
|
||||
"op": "call",
|
||||
"dst": 4,
|
||||
"callee": "print",
|
||||
"args": [0, 1]
|
||||
}
|
||||
```
|
||||
|
||||
**C Output**:
|
||||
```c
|
||||
int64_t v4 = ny_print(v0, v1);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 9. BoxCall (Method Call)
|
||||
|
||||
**MIR**:
|
||||
```json
|
||||
{
|
||||
"op": "boxcall",
|
||||
"dst": 5,
|
||||
"receiver": 0,
|
||||
"method": "concat",
|
||||
"args": [1]
|
||||
}
|
||||
```
|
||||
|
||||
**C Output** (via NyRT):
|
||||
```c
|
||||
int64_t args[] = {v1};
|
||||
int64_t v5 = nyash_boxcall(v0, "concat", args, 1);
|
||||
```
|
||||
|
||||
**Common Methods**:
|
||||
```c
|
||||
String.concat → nyash_string_concat_hh
|
||||
String.len → nyash_string_len_h
|
||||
String.substring → nyash_string_substring_hii
|
||||
Array.size → nyash_array_size_h
|
||||
Array.get → nyash_array_get_hi
|
||||
Map.set → nyash_map_set_hhh
|
||||
Map.get → nyash_map_get_hh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 10. ExternCall
|
||||
|
||||
**MIR**:
|
||||
```json
|
||||
{
|
||||
"op": "externcall",
|
||||
"dst": 6,
|
||||
"interface": "env.console",
|
||||
"method": "log",
|
||||
"args": [0]
|
||||
}
|
||||
```
|
||||
|
||||
**C Output**:
|
||||
```c
|
||||
int64_t v6 = nyrt_externcall("env.console.log", v0);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 11. Load
|
||||
|
||||
**MIR**:
|
||||
```json
|
||||
{
|
||||
"op": "load",
|
||||
"dst": 7,
|
||||
"addr": 6
|
||||
}
|
||||
```
|
||||
|
||||
**C Output**:
|
||||
```c
|
||||
int64_t v7 = *(int64_t*)v6;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 12. Store
|
||||
|
||||
**MIR**:
|
||||
```json
|
||||
{
|
||||
"op": "store",
|
||||
"addr": 6,
|
||||
"value": 7
|
||||
}
|
||||
```
|
||||
|
||||
**C Output**:
|
||||
```c
|
||||
*(int64_t*)v6 = v7;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 13. Copy
|
||||
|
||||
**MIR**:
|
||||
```json
|
||||
{
|
||||
"op": "copy",
|
||||
"dst": 8,
|
||||
"src": 7
|
||||
}
|
||||
```
|
||||
|
||||
**C Output**:
|
||||
```c
|
||||
int64_t v8 = v7;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 14. TypeOp
|
||||
|
||||
**MIR**:
|
||||
```json
|
||||
{
|
||||
"op": "typeop",
|
||||
"dst": 9,
|
||||
"kind": "TypeCheck",
|
||||
"value": 7,
|
||||
"target_type": "String"
|
||||
}
|
||||
```
|
||||
|
||||
**C Output**:
|
||||
```c
|
||||
int64_t v9 = nyrt_typecheck(v7, "String");
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 15. Barrier (GC)
|
||||
|
||||
**MIR**:
|
||||
```json
|
||||
{
|
||||
"op": "barrier",
|
||||
"kind": "write",
|
||||
"addr": 6,
|
||||
"value": 7
|
||||
}
|
||||
```
|
||||
|
||||
**C Output**:
|
||||
```c
|
||||
nyrt_gc_barrier_write((void*)v6, v7);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 16. Safepoint (GC)
|
||||
|
||||
**MIR**:
|
||||
```json
|
||||
{
|
||||
"op": "safepoint"
|
||||
}
|
||||
```
|
||||
|
||||
**C Output**:
|
||||
```c
|
||||
nyrt_gc_safepoint();
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Overall C Structure
|
||||
|
||||
### Template
|
||||
|
||||
```c
|
||||
// === Header ===
|
||||
#include <stdint.h>
|
||||
#include <stdio.h>
|
||||
|
||||
// NyRT Function Declarations
|
||||
extern int64_t nyash_box_from_i8_string(const char*);
|
||||
extern int64_t nyash_string_concat_hh(int64_t, int64_t);
|
||||
extern int64_t nyash_string_len_h(int64_t);
|
||||
extern int64_t nyash_array_size_h(int64_t);
|
||||
extern int64_t nyash_map_set_hhh(int64_t, int64_t, int64_t);
|
||||
extern int64_t nyash_boxcall(int64_t, const char*, int64_t*, int);
|
||||
extern int64_t nyrt_externcall(const char*, int64_t);
|
||||
extern int64_t nyrt_typecheck(int64_t, const char*);
|
||||
extern void nyrt_gc_barrier_write(void*, int64_t);
|
||||
extern void nyrt_gc_safepoint(void);
|
||||
|
||||
// === Function Definitions ===
|
||||
int64_t ny_main(void) {
|
||||
// Variable declarations
|
||||
int64_t v0, v1, v2, v3, v4, v5;
|
||||
int64_t phi_v5; // PHI variables
|
||||
|
||||
// === bb0 (entry) ===
|
||||
bb0:
|
||||
v0 = nyash_box_from_i8_string("Hello");
|
||||
v1 = nyash_box_from_i8_string(" World");
|
||||
v2 = nyash_string_concat_hh(v0, v1);
|
||||
v3 = nyash_string_len_h(v2);
|
||||
return v3;
|
||||
}
|
||||
|
||||
// === Main Entry Point ===
|
||||
int main(int argc, char** argv) {
|
||||
int64_t result = ny_main();
|
||||
printf("Result: %lld\n", (long long)result);
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Test Strategy
|
||||
|
||||
### Test Cases per Instruction
|
||||
|
||||
| Instruction | Test Count | Priority |
|
||||
|-------------|------------|----------|
|
||||
| const | 3 (int, string, bool) | HIGH |
|
||||
| binop | 5 (add, sub, mul, div, mod) | HIGH |
|
||||
| compare | 6 (eq, ne, lt, le, gt, ge) | HIGH |
|
||||
| jump | 2 (basic, nested) | HIGH |
|
||||
| branch | 3 (true, false, nested) | HIGH |
|
||||
| phi | 4 (if-else, loop, multiple) | HIGH |
|
||||
| ret | 2 (int, box) | HIGH |
|
||||
| call | 2 (0-arg, 2-arg) | MEDIUM |
|
||||
| boxcall | 5 (string, array, map) | HIGH |
|
||||
| externcall | 2 (console, time) | MEDIUM |
|
||||
| load | 2 (basic, nested) | LOW |
|
||||
| store | 2 (basic, nested) | LOW |
|
||||
| copy | 1 (basic) | LOW |
|
||||
| typeop | 2 (typecheck, cast) | LOW |
|
||||
| barrier | 1 (basic) | LOW |
|
||||
| safepoint | 1 (basic) | LOW |
|
||||
|
||||
**Total Test Cases**: 43
|
||||
|
||||
---
|
||||
|
||||
## 📦 Implementation Structure
|
||||
|
||||
### apps/bootstrap-compiler/codegen/
|
||||
|
||||
```
|
||||
codegen/
|
||||
├── c_emitter_box.hako # Main C emitter
|
||||
│ ├── emit_function() # Function-level emission
|
||||
│ ├── emit_block() # Basic block emission
|
||||
│ └── emit_instruction() # Instruction-level emission
|
||||
├── c_header_box.hako # Header generation
|
||||
│ ├── emit_includes()
|
||||
│ └── emit_nyrt_decls()
|
||||
├── c_phi_resolver_box.hako # PHI → explicit assignments
|
||||
│ └── resolve_phi()
|
||||
├── c_runtime_box.hako # NyRT call helpers
|
||||
│ ├── emit_boxcall()
|
||||
│ ├── emit_externcall()
|
||||
│ └── emit_typeop()
|
||||
└── tests/ # 43 test cases
|
||||
├── test_const.hako
|
||||
├── test_binop.hako
|
||||
├── test_compare.hako
|
||||
└── ...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Compilation Pipeline
|
||||
|
||||
```
|
||||
Input: program.mir.json
|
||||
|
||||
Step 1: Parse MIR JSON
|
||||
↓
|
||||
Step 2: Preprocess PHI instructions
|
||||
↓
|
||||
Step 3: Emit C header
|
||||
↓
|
||||
Step 4: Emit function declarations
|
||||
↓
|
||||
Step 5: For each function:
|
||||
- Emit variable declarations
|
||||
- For each basic block:
|
||||
- Emit block label
|
||||
- For each instruction:
|
||||
- Emit C statement
|
||||
↓
|
||||
Step 6: Emit main entry point
|
||||
↓
|
||||
Output: program.c
|
||||
|
||||
Step 7: Compile with clang
|
||||
clang program.c -o program \
|
||||
-L /path/to/hako_kernel \
|
||||
-lhako_kernel \
|
||||
-lpthread -ldl -lm
|
||||
↓
|
||||
Output: program (executable)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💡 PHI Resolution Strategy
|
||||
|
||||
### Problem
|
||||
|
||||
PHI nodes in SSA form don't directly translate to C:
|
||||
|
||||
```
|
||||
MIR:
|
||||
bb_merge:
|
||||
v5 = phi [bb_then: v1, bb_else: v2]
|
||||
```
|
||||
|
||||
C doesn't have PHI!
|
||||
|
||||
### Solution: Pre-Merge Assignment
|
||||
|
||||
```c
|
||||
// bb_then:
|
||||
phi_v5 = v1; // ← Explicit assignment before jump
|
||||
goto bb_merge;
|
||||
|
||||
// bb_else:
|
||||
phi_v5 = v2; // ← Explicit assignment before jump
|
||||
goto bb_merge;
|
||||
|
||||
// bb_merge:
|
||||
int64_t v5 = phi_v5; // ← Load from PHI variable
|
||||
```
|
||||
|
||||
### Algorithm
|
||||
|
||||
1. **Identify PHI nodes**: Scan all blocks for PHI instructions
|
||||
2. **Create PHI variables**: `phi_vN` for each PHI destination
|
||||
3. **Insert assignments**: Before each predecessor jump, assign `phi_vN = vX`
|
||||
4. **Replace PHI**: PHI node becomes `vN = phi_vN`
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Edge Cases
|
||||
|
||||
### 1. String Escaping
|
||||
|
||||
**Problem**: C string literals need escaping
|
||||
|
||||
**Example**:
|
||||
```
|
||||
MIR: const v0 = "Hello \"World\"\n"
|
||||
C: v0 = nyash_box_from_i8_string("Hello \\\"World\\\"\\n");
|
||||
```
|
||||
|
||||
**Escaping Rules**:
|
||||
- `"` → `\"`
|
||||
- `\` → `\\`
|
||||
- `\n` → `\\n`
|
||||
- `\t` → `\\t`
|
||||
|
||||
### 2. Null Values
|
||||
|
||||
**Problem**: How to represent null?
|
||||
|
||||
**Solution**:
|
||||
```c
|
||||
#define NYRT_NULL ((int64_t)0)
|
||||
int64_t v0 = NYRT_NULL;
|
||||
```
|
||||
|
||||
### 3. Large Constants
|
||||
|
||||
**Problem**: String/Array constants in MIR JSON
|
||||
|
||||
**Solution**:
|
||||
```c
|
||||
// Option A: Inline (simple)
|
||||
v0 = nyash_box_from_i8_string("very long string...");
|
||||
|
||||
// Option B: Static data (future optimization)
|
||||
static const char str_0[] = "very long string...";
|
||||
v0 = nyash_box_from_i8_string(str_0);
|
||||
```
|
||||
|
||||
### 4. Recursive Functions
|
||||
|
||||
**Problem**: C requires forward declarations
|
||||
|
||||
**Solution**:
|
||||
```c
|
||||
// Forward declarations
|
||||
int64_t ny_func_a(int64_t);
|
||||
int64_t ny_func_b(int64_t);
|
||||
|
||||
// Definitions
|
||||
int64_t ny_func_a(int64_t arg) {
|
||||
return ny_func_b(arg + 1);
|
||||
}
|
||||
|
||||
int64_t ny_func_b(int64_t arg) {
|
||||
if (arg > 10) return arg;
|
||||
return ny_func_a(arg * 2);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Success Criteria
|
||||
|
||||
### Correctness
|
||||
|
||||
- [ ] All 16 instructions → C correctly
|
||||
- [ ] 43/43 test cases PASS
|
||||
- [ ] No segfaults or memory errors
|
||||
- [ ] Output matches VM execution
|
||||
|
||||
### Performance
|
||||
|
||||
- [ ] Compilation time < 1 second for 100-line programs
|
||||
- [ ] Generated C compiles without warnings
|
||||
- [ ] Execution time comparable to Rust VM
|
||||
|
||||
### Maintainability
|
||||
|
||||
- [ ] Each instruction has dedicated test
|
||||
- [ ] Code is modular (Box-based)
|
||||
- [ ] Edge cases documented
|
||||
- [ ] Examples for common patterns
|
||||
|
||||
---
|
||||
|
||||
## 📚 NyRT Function Reference
|
||||
|
||||
### String Operations
|
||||
|
||||
```c
|
||||
int64_t nyash_box_from_i8_string(const char* str);
|
||||
int64_t nyash_string_concat_hh(int64_t lhs, int64_t rhs);
|
||||
int64_t nyash_string_len_h(int64_t str);
|
||||
int64_t nyash_string_substring_hii(int64_t str, int64_t start, int64_t end);
|
||||
```
|
||||
|
||||
### Array Operations
|
||||
|
||||
```c
|
||||
int64_t nyash_array_size_h(int64_t arr);
|
||||
int64_t nyash_array_get_hi(int64_t arr, int64_t index);
|
||||
int64_t nyash_array_set_hih(int64_t arr, int64_t index, int64_t value);
|
||||
```
|
||||
|
||||
### Map Operations
|
||||
|
||||
```c
|
||||
int64_t nyash_map_set_hhh(int64_t map, int64_t key, int64_t value);
|
||||
int64_t nyash_map_get_hh(int64_t map, int64_t key);
|
||||
int64_t nyash_map_size_h(int64_t map);
|
||||
```
|
||||
|
||||
### Generic Operations
|
||||
|
||||
```c
|
||||
int64_t nyash_boxcall(int64_t receiver, const char* method, int64_t* args, int arg_count);
|
||||
int64_t nyrt_externcall(const char* interface_method, int64_t arg);
|
||||
int64_t nyrt_typecheck(int64_t value, const char* type_name);
|
||||
```
|
||||
|
||||
### GC Operations
|
||||
|
||||
```c
|
||||
void nyrt_gc_barrier_write(void* addr, int64_t value);
|
||||
void nyrt_gc_safepoint(void);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Implementation Plan
|
||||
|
||||
### Week 7: Basic Instructions
|
||||
|
||||
**Day 1-2**: const, copy, ret
|
||||
**Day 3-4**: binop, compare
|
||||
**Day 5-7**: jump, branch, phi (basic)
|
||||
|
||||
### Week 8: Advanced Instructions
|
||||
|
||||
**Day 1-2**: call, boxcall
|
||||
**Day 3-4**: externcall, typeop
|
||||
**Day 5-6**: load, store, barrier, safepoint
|
||||
**Day 7**: Integration testing
|
||||
|
||||
---
|
||||
|
||||
**Created**: 2025-10-14
|
||||
**Phase**: 20.5 (Week 7-8)
|
||||
**Component**: C Code Generator
|
||||
342
docs/private/roadmap/phases/phase-20.5/HAKORUNE_VM_DISCOVERY.md
Normal file
342
docs/private/roadmap/phases/phase-20.5/HAKORUNE_VM_DISCOVERY.md
Normal file
@ -0,0 +1,342 @@
|
||||
# 🎉 Hakorune VM Discovery Report — Critical Finding
|
||||
|
||||
**Date**: 2025-10-14
|
||||
**Status**: ⚠️ **CRITICAL PLANNING CHANGE**
|
||||
**Impact**: Phase 20.5 strategy requires complete rewrite
|
||||
|
||||
---
|
||||
|
||||
## 🔍 Executive Summary
|
||||
|
||||
**Original Assumption**: Hakorune VM does not exist, needs to be implemented from scratch over 36 weeks.
|
||||
|
||||
**Actual Reality**: **Hakorune VM is 100% COMPLETE** - fully implemented in `selfhost/hakorune-vm/` with 3,413 lines across 44 files.
|
||||
|
||||
**Impact**: Phase 20.5 timeline changes from **36 weeks (implementation)** to **4-6 weeks (validation & adoption)**.
|
||||
|
||||
---
|
||||
|
||||
## 📊 Discovery Details
|
||||
|
||||
### What We Found
|
||||
|
||||
**Location**: `selfhost/hakorune-selfhost/selfhost/hakorune-vm/`
|
||||
|
||||
**Statistics**:
|
||||
- **Total Lines**: 3,413 lines of Hakorune code
|
||||
- **Total Files**: 44 .hako files
|
||||
- **Instruction Handlers**: 22 handlers (MORE than 16 MIR instructions!)
|
||||
- **Test Files**: Comprehensive test suite included
|
||||
- **Implementation Period**: October 5-13, 2025 (8 days)
|
||||
|
||||
### Complete Instruction Coverage
|
||||
|
||||
```bash
|
||||
# All 22 handlers found:
|
||||
barrier ✅ MIR instruction
|
||||
binop ✅ MIR instruction
|
||||
boxcall ✅ MIR instruction
|
||||
closure_call ✅ Advanced (MIR "mir_call" variant)
|
||||
compare ✅ MIR instruction
|
||||
const ✅ MIR instruction
|
||||
constructor_call ✅ Advanced (MIR "mir_call" variant)
|
||||
copy ✅ MIR instruction
|
||||
extern_call ✅ Advanced (externCall)
|
||||
global_call ✅ Advanced (MIR "mir_call" variant)
|
||||
load ✅ MIR instruction
|
||||
method_call ✅ Advanced (MIR "mir_call" variant)
|
||||
mircall ✅ MIR instruction (unified)
|
||||
module_function_call ✅ Advanced (MIR "mir_call" variant)
|
||||
newbox ✅ MIR instruction
|
||||
nop ✅ MIR instruction
|
||||
phi ✅ MIR instruction
|
||||
safepoint ✅ MIR instruction
|
||||
store ✅ MIR instruction
|
||||
terminator ✅ Control flow (jump/branch/ret)
|
||||
typeop ✅ MIR instruction
|
||||
unaryop ✅ MIR instruction
|
||||
```
|
||||
|
||||
**Coverage**: 16/16 MIR frozen instructions + 6 advanced handlers = **138% coverage**!
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Hakorune VM Architecture
|
||||
|
||||
### Core Files
|
||||
|
||||
```
|
||||
selfhost/hakorune-vm/
|
||||
├── hakorune_vm_core.hako (225 lines) # Main VM execution loop
|
||||
├── instruction_dispatcher.hako (72 lines) # @match-based dispatch
|
||||
├── blocks_locator.hako # Control flow
|
||||
├── error_builder.hako # Error handling
|
||||
├── args_guard.hako # Argument validation
|
||||
├── json_normalize_box.hako # JSON normalization
|
||||
└── [22 handler files] # Instruction implementations
|
||||
```
|
||||
|
||||
### Key Design Patterns
|
||||
|
||||
#### 1. @match-Based Dispatch
|
||||
```hakorune
|
||||
// instruction_dispatcher.hako
|
||||
dispatch(inst_json, regs, mem) {
|
||||
local op = inst_json.substring(op_start, op_end)
|
||||
|
||||
return match op {
|
||||
"const" => ConstHandlerBox.handle(inst_json, regs)
|
||||
"binop" => BinOpHandlerBox.handle(inst_json, regs)
|
||||
"compare" => CompareHandlerBox.handle(inst_json, regs)
|
||||
"mir_call" => MirCallHandlerBox.handle(inst_json, regs, mem)
|
||||
// ... all 22 handlers
|
||||
_ => Result.Err("unsupported instruction: " + op)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. Result-Based Error Handling
|
||||
```hakorune
|
||||
// Every handler returns Result
|
||||
handle(inst_json, regs) {
|
||||
// Validation
|
||||
if (error_condition) {
|
||||
return Result.Err("error message")
|
||||
}
|
||||
|
||||
// Success
|
||||
return Result.Ok(value)
|
||||
}
|
||||
```
|
||||
|
||||
#### 3. Comprehensive Test Coverage
|
||||
```
|
||||
selfhost/hakorune-vm/tests/
|
||||
├── test_phase1_minimal.hako # Basic VM tests
|
||||
├── test_phase1_day3.hako
|
||||
├── test_phase2_day4.hako
|
||||
├── test_phase2_day5.hako
|
||||
├── test_boxcall.hako # BoxCall tests
|
||||
├── test_mircall_phase1.hako # MIR call tests
|
||||
├── test_mircall_phase2_closure.hako # Closure tests
|
||||
├── test_mircall_phase2_constructor.hako
|
||||
├── test_mircall_phase2_method.hako
|
||||
├── test_mircall_phase2_module.hako
|
||||
├── test_compare_bug.hako # Regression tests
|
||||
├── test_mapbox_*.hako # MapBox tests
|
||||
└── [16 more test files]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 What This Means for Phase 20.5
|
||||
|
||||
### Original Plan (OBSOLETE)
|
||||
|
||||
**Timeline**: 36 weeks (Phase 20.5 → 20.8)
|
||||
|
||||
**Phases**:
|
||||
- Phase A (4 weeks): HostBridge API
|
||||
- Phase B (8 weeks): VM Core implementation ← **ALREADY DONE!**
|
||||
- Phase C (6 weeks): Dispatch unification ← **ALREADY DONE!**
|
||||
- Phase D (8 weeks): Collections in Hakorune
|
||||
- Phase E (6 weeks): GC v0
|
||||
- Phase F (4 weeks): Rust VM deprecation
|
||||
|
||||
### New Reality (UPDATED)
|
||||
|
||||
**Timeline**: 4-6 weeks (Phase 20.5 only)
|
||||
|
||||
**Phases**:
|
||||
- Week 1-2: **Hakorune VM Validation** (verify all 22 handlers work)
|
||||
- Week 3-4: **Golden Testing** (Rust-VM vs Hako-VM parity)
|
||||
- Week 5: **Integration** (make Hako-VM accessible from CLI)
|
||||
- Week 6: **Documentation** (architecture docs, migration guide)
|
||||
|
||||
**Deferred** (may not even be needed):
|
||||
- HostBridge API: Only if we need C-ABI for other reasons
|
||||
- op_eq migration: Hakorune VM likely already handles this
|
||||
- GC v0: Rust GC can remain for now
|
||||
- Collections: Already implemented in Hakorune VM
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Architecture Clarification
|
||||
|
||||
### Three VM Implementations Found
|
||||
|
||||
```
|
||||
1. Rust VM (Reference Implementation)
|
||||
Location: src/backend/mir_interpreter/
|
||||
Purpose: Production VM, fully tested
|
||||
Status: Active, stable
|
||||
|
||||
2. Mini-VM (Early Prototype)
|
||||
Location: apps/hakorune/vm/
|
||||
Lines: ~586 lines
|
||||
Purpose: Early experiment, semantic prototype
|
||||
Status: OBSOLETE (replaced by Full Hakorune VM)
|
||||
|
||||
3. Full Hakorune VM (COMPLETE!)
|
||||
Location: selfhost/hakorune-vm/
|
||||
Lines: 3,413 lines
|
||||
Purpose: Pure Hakorune VM implementation
|
||||
Status: READY FOR TESTING
|
||||
Coverage: 22 handlers (138% of MIR frozen set)
|
||||
```
|
||||
|
||||
### Recommendation
|
||||
|
||||
**Deprecate Mini-VM**: Replaced by Full Hakorune VM
|
||||
**Keep Rust VM**: Reference implementation for Golden Testing
|
||||
**Promote Hakorune VM**: Make it the default VM backend
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Validation Strategy
|
||||
|
||||
### Week 1-2: Handler Validation
|
||||
|
||||
**Goal**: Verify all 22 handlers work correctly
|
||||
|
||||
```bash
|
||||
# Run existing test suite
|
||||
for test in selfhost/hakorune-vm/tests/*.hako; do
|
||||
echo "Testing: $test"
|
||||
NYASH_DISABLE_PLUGINS=1 ./target/release/hako "$test"
|
||||
done
|
||||
```
|
||||
|
||||
**Expected**: All 26+ tests PASS
|
||||
|
||||
### Week 3-4: Golden Testing
|
||||
|
||||
**Goal**: Prove Hakorune VM produces identical output to Rust VM
|
||||
|
||||
```bash
|
||||
# Create golden test suite
|
||||
tests/golden/hakorune-vm/
|
||||
├── arithmetic.hako # Basic arithmetic
|
||||
├── control_flow.hako # if/loop/branch
|
||||
├── collections.hako # Array/Map operations
|
||||
├── recursion.hako # Recursive functions
|
||||
├── closures.hako # Closure capture
|
||||
└── selfhost_mini.hako # Mini compiler
|
||||
|
||||
# Run comparison
|
||||
for test in tests/golden/hakorune-vm/*.hako; do
|
||||
./hako --backend vm "$test" > rust_output.txt
|
||||
./hako --backend vm-hako "$test" > hako_output.txt
|
||||
diff rust_output.txt hako_output.txt || echo "FAIL: $test"
|
||||
done
|
||||
```
|
||||
|
||||
### Week 5: CLI Integration
|
||||
|
||||
**Goal**: Make Hakorune VM accessible via `--backend vm-hako`
|
||||
|
||||
**Implementation**:
|
||||
```rust
|
||||
// src/cli.rs
|
||||
match backend {
|
||||
Backend::Vm => run_rust_vm(mir),
|
||||
Backend::VmHako => run_hakorune_vm(mir), // NEW!
|
||||
Backend::Llvm => run_llvm(mir),
|
||||
Backend::Wasm => run_wasm(mir),
|
||||
}
|
||||
|
||||
// src/backend/hakorune_vm_runner.rs (NEW)
|
||||
pub fn run_hakorune_vm(mir_json: String) -> Result<i64> {
|
||||
// Load selfhost/hakorune-vm/hakorune_vm_core.hako
|
||||
// Call HakoruneVmCoreBox.run(mir_json)
|
||||
// Return result
|
||||
}
|
||||
```
|
||||
|
||||
### Week 6: Documentation
|
||||
|
||||
**Goal**: Complete architecture documentation
|
||||
|
||||
**Documents**:
|
||||
- `selfhost/hakorune-vm/README.md` - Architecture overview
|
||||
- `selfhost/hakorune-vm/DESIGN.md` - Design patterns (@match, Result, etc.)
|
||||
- `selfhost/hakorune-vm/TESTING.md` - Test strategy
|
||||
- `docs/guides/hakorune-vm-migration.md` - User migration guide
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Key Differences from Original Plan
|
||||
|
||||
| Aspect | Original Plan | Actual Reality |
|
||||
|--------|--------------|----------------|
|
||||
| **Timeline** | 36 weeks | 4-6 weeks |
|
||||
| **VM Implementation** | Need to build | **Already complete** |
|
||||
| **Instruction Coverage** | 5 → 16 (phased) | **22 handlers (done)** |
|
||||
| **Dispatch** | Need to implement | **@match-based (done)** |
|
||||
| **Error Handling** | Need to design | **Result-based (done)** |
|
||||
| **Test Coverage** | Need to create | **26+ tests (done)** |
|
||||
| **HostBridge API** | Critical path | **Optional** (only if needed) |
|
||||
| **op_eq migration** | Week 5-6 | **Likely done** (verify) |
|
||||
| **Collections** | Phase D (Week 19-26) | **Likely done** (verify) |
|
||||
|
||||
---
|
||||
|
||||
## 🎉 Immediate Next Steps
|
||||
|
||||
### 1. Run Existing Test Suite (ASAP)
|
||||
```bash
|
||||
# Verify Hakorune VM works right now
|
||||
cd /home/tomoaki/git/hakorune-selfhost
|
||||
for test in selfhost/hakorune-vm/tests/*.hako; do
|
||||
NYASH_DISABLE_PLUGINS=1 ./target/release/hako "$test" || echo "FAIL: $test"
|
||||
done
|
||||
```
|
||||
|
||||
### 2. Create VM Runner Integration (Week 1)
|
||||
```bash
|
||||
# Add --backend vm-hako support
|
||||
# Location: src/backend/hakorune_vm_runner.rs (NEW)
|
||||
```
|
||||
|
||||
### 3. Golden Testing Framework (Week 2-3)
|
||||
```bash
|
||||
# Create tests/golden/hakorune-vm/ suite
|
||||
# Compare Rust VM vs Hakorune VM outputs
|
||||
```
|
||||
|
||||
### 4. Update All Phase 20.5 Documentation (Week 1)
|
||||
```bash
|
||||
# Files to update:
|
||||
docs/private/roadmap/phases/phase-20.5/
|
||||
├── README.md # Complete rewrite
|
||||
├── STRATEGY_RECONCILIATION.md # Update with discovery
|
||||
├── PURE_HAKORUNE_ROADMAP.md # 4-6 weeks, not 36
|
||||
├── MILESTONE.md # Update deliverables
|
||||
└── HAKORUNE_VM_DISCOVERY.md # THIS FILE
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📚 References
|
||||
|
||||
### Hakorune VM Implementation
|
||||
- **Location**: `/home/tomoaki/git/hakorune-selfhost/selfhost/hakorune-vm/`
|
||||
- **Entry Point**: `hakorune_vm_core.hako`
|
||||
- **Dispatcher**: `instruction_dispatcher.hako`
|
||||
- **Tests**: `tests/*.hako` (26+ files)
|
||||
|
||||
### Related VMs
|
||||
- **Rust VM**: `src/backend/mir_interpreter/` (reference)
|
||||
- **Mini-VM**: `apps/hakorune/vm/` (obsolete, 586 lines)
|
||||
|
||||
### Documentation
|
||||
- **MIR Instruction Set**: `docs/reference/mir/INSTRUCTION_SET.md`
|
||||
- **Phase 20.5 Index**: `docs/private/roadmap/phases/phase-20.5/INDEX.md`
|
||||
|
||||
---
|
||||
|
||||
**Discovery Date**: 2025-10-14
|
||||
**Discovered By**: tomoaki (user pointed Claude to correct directory)
|
||||
**Impact**: Phase 20.5 timeline reduced from 36 weeks to 4-6 weeks
|
||||
**Status**: **READY FOR VALIDATION**
|
||||
**Next Action**: Run existing test suite to verify functionality
|
||||
679
docs/private/roadmap/phases/phase-20.5/HOSTBRIDGE_API_DESIGN.md
Normal file
679
docs/private/roadmap/phases/phase-20.5/HOSTBRIDGE_API_DESIGN.md
Normal file
@ -0,0 +1,679 @@
|
||||
# HostBridge API Design — Phase 20.5
|
||||
|
||||
**Purpose**: Define minimal C-ABI surface for Rust↔Hakorune boundary
|
||||
**Status**: Design (Week 1-4 implementation)
|
||||
**Platforms**: Ubuntu/Windows
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Design Principles
|
||||
|
||||
### 1. Minimal Surface
|
||||
- **5 core functions** (not 50)
|
||||
- Each function has single responsibility
|
||||
- No feature creep
|
||||
|
||||
### 2. Platform Independence
|
||||
- Pure C-ABI (no C++ exceptions, no OS-specific types)
|
||||
- Works on Ubuntu (gcc/clang) and Windows (MSVC/MinGW)
|
||||
- Thread-Local Storage (TLS) for error handling
|
||||
|
||||
### 3. Handle-Based Ownership
|
||||
- All Hakorune values represented as `HakoHandle` (opaque 64-bit)
|
||||
- Explicit `Retain/Release` for reference counting
|
||||
- No manual memory management exposed
|
||||
|
||||
### 4. UTF-8 Everywhere
|
||||
- All strings are UTF-8 (`const char*` or `HakoStr`)
|
||||
- No wide strings (Windows `wchar_t`)
|
||||
- Simple, consistent encoding
|
||||
|
||||
### 5. Fail-Fast
|
||||
- Errors are explicit (return codes + `Hako_LastError`)
|
||||
- No silent failures
|
||||
- No undefined behavior
|
||||
|
||||
---
|
||||
|
||||
## 📋 Core API (5 Functions)
|
||||
|
||||
### 1. `Hako_RunScriptUtf8`
|
||||
|
||||
**Purpose**: Execute Hakorune script, return handle to result
|
||||
|
||||
```c
|
||||
int32_t Hako_RunScriptUtf8(
|
||||
const char* source_utf8,
|
||||
HakoHandle* out_result_handle
|
||||
);
|
||||
```
|
||||
|
||||
**Parameters**:
|
||||
- `source_utf8`: Hakorune source code (null-terminated UTF-8)
|
||||
- `out_result_handle`: Output handle to result value
|
||||
|
||||
**Returns**:
|
||||
- `0`: Success (`out_result_handle` is valid)
|
||||
- `-1`: Error (use `Hako_LastError()` for details)
|
||||
|
||||
**Ownership**:
|
||||
- Caller owns `out_result_handle` (must call `Hako_Release`)
|
||||
- Caller manages `source_utf8` memory
|
||||
|
||||
**Example**:
|
||||
```c
|
||||
const char* script = "static box Main { main() { return 42 } }";
|
||||
HakoHandle result = 0;
|
||||
if (Hako_RunScriptUtf8(script, &result) == 0) {
|
||||
// Success - result is valid
|
||||
// ... use result ...
|
||||
Hako_Release(result);
|
||||
} else {
|
||||
fprintf(stderr, "Error: %s\n", Hako_LastError());
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. `Hako_Retain`
|
||||
|
||||
**Purpose**: Increment reference count on handle
|
||||
|
||||
```c
|
||||
void Hako_Retain(HakoHandle handle);
|
||||
```
|
||||
|
||||
**Parameters**:
|
||||
- `handle`: Handle to retain
|
||||
|
||||
**Returns**: void (no error possible)
|
||||
|
||||
**Ownership**:
|
||||
- Caller must call `Hako_Release` for each `Retain`
|
||||
|
||||
**Example**:
|
||||
```c
|
||||
HakoHandle result = /* from Hako_RunScriptUtf8 */;
|
||||
Hako_Retain(result); // Now refcount = 2
|
||||
// Pass to another function
|
||||
other_function(result);
|
||||
// Still valid here
|
||||
Hako_Release(result); // Decrement to 1
|
||||
Hako_Release(result); // Decrement to 0, freed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. `Hako_Release`
|
||||
|
||||
**Purpose**: Decrement reference count, free if zero
|
||||
|
||||
```c
|
||||
void Hako_Release(HakoHandle handle);
|
||||
```
|
||||
|
||||
**Parameters**:
|
||||
- `handle`: Handle to release (can be 0/null)
|
||||
|
||||
**Returns**: void (no error possible)
|
||||
|
||||
**Ownership**:
|
||||
- Handle may be freed if refcount reaches zero
|
||||
- Safe to call with `handle=0` (no-op)
|
||||
|
||||
**Example**:
|
||||
```c
|
||||
HakoHandle result = /* from Hako_RunScriptUtf8 */;
|
||||
Hako_Release(result); // Decrement refcount
|
||||
// result is now INVALID - do not use
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. `Hako_ToUtf8`
|
||||
|
||||
**Purpose**: Get UTF-8 string view of handle
|
||||
|
||||
```c
|
||||
typedef struct {
|
||||
const char* data; // UTF-8 bytes (NOT null-terminated)
|
||||
size_t len; // Byte length
|
||||
} HakoStr;
|
||||
|
||||
int32_t Hako_ToUtf8(
|
||||
HakoHandle handle,
|
||||
HakoStr* out_str
|
||||
);
|
||||
```
|
||||
|
||||
**Parameters**:
|
||||
- `handle`: Handle to convert to string
|
||||
- `out_str`: Output string view
|
||||
|
||||
**Returns**:
|
||||
- `0`: Success (`out_str` is valid)
|
||||
- `-1`: Error (not a string, or conversion failed)
|
||||
|
||||
**Ownership**:
|
||||
- `out_str->data` is **borrowed** (valid until `Hako_Release(handle)`)
|
||||
- Caller must NOT free `out_str->data`
|
||||
- String is NOT null-terminated (use `len`)
|
||||
|
||||
**Example**:
|
||||
```c
|
||||
HakoHandle result = /* from Hako_RunScriptUtf8 */;
|
||||
HakoStr str;
|
||||
if (Hako_ToUtf8(result, &str) == 0) {
|
||||
printf("Result: %.*s\n", (int)str.len, str.data);
|
||||
// Do NOT free str.data
|
||||
}
|
||||
Hako_Release(result); // Now str.data is INVALID
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. `Hako_LastError`
|
||||
|
||||
**Purpose**: Get last error message (thread-local)
|
||||
|
||||
```c
|
||||
const char* Hako_LastError(void);
|
||||
```
|
||||
|
||||
**Parameters**: none
|
||||
|
||||
**Returns**:
|
||||
- Error message (null-terminated UTF-8)
|
||||
- Valid until next Hako API call on this thread
|
||||
- Never returns NULL (returns "Unknown error" if none)
|
||||
|
||||
**Thread-Safety**:
|
||||
- Uses Thread-Local Storage (TLS)
|
||||
- Each thread has independent error state
|
||||
|
||||
**Example**:
|
||||
```c
|
||||
if (Hako_RunScriptUtf8(script, &result) != 0) {
|
||||
fprintf(stderr, "Error: %s\n", Hako_LastError());
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Optional Functions (Future)
|
||||
|
||||
### `Hako_ApiVersion`
|
||||
|
||||
**Purpose**: Get API version for compatibility checks
|
||||
|
||||
```c
|
||||
typedef struct {
|
||||
uint32_t major; // Breaking changes
|
||||
uint32_t minor; // New features
|
||||
uint32_t patch; // Bug fixes
|
||||
} HakoVersion;
|
||||
|
||||
HakoVersion Hako_ApiVersion(void);
|
||||
```
|
||||
|
||||
**Example**:
|
||||
```c
|
||||
HakoVersion ver = Hako_ApiVersion();
|
||||
if (ver.major != 1) {
|
||||
fprintf(stderr, "Incompatible API version: %u.%u.%u\n",
|
||||
ver.major, ver.minor, ver.patch);
|
||||
exit(1);
|
||||
}
|
||||
```
|
||||
|
||||
### `Hako_ToInt64`
|
||||
|
||||
**Purpose**: Get integer value from handle
|
||||
|
||||
```c
|
||||
int32_t Hako_ToInt64(
|
||||
HakoHandle handle,
|
||||
int64_t* out_value
|
||||
);
|
||||
```
|
||||
|
||||
**Example**:
|
||||
```c
|
||||
int64_t num;
|
||||
if (Hako_ToInt64(result, &num) == 0) {
|
||||
printf("Result: %lld\n", (long long)num);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Implementation Strategy
|
||||
|
||||
### Phase 1: Rust Side (Week 1-2)
|
||||
|
||||
**File**: `src/hostbridge/mod.rs` (new)
|
||||
|
||||
```rust
|
||||
use std::ffi::{CStr, CString};
|
||||
use std::os::raw::{c_char, c_int};
|
||||
|
||||
pub type HakoHandle = u64;
|
||||
|
||||
#[repr(C)]
|
||||
pub struct HakoStr {
|
||||
pub data: *const u8,
|
||||
pub len: usize,
|
||||
}
|
||||
|
||||
#[no_mangle]
|
||||
pub extern "C" fn Hako_RunScriptUtf8(
|
||||
source_utf8: *const c_char,
|
||||
out_result_handle: *mut HakoHandle
|
||||
) -> c_int {
|
||||
// 1. Convert C string to Rust &str
|
||||
// 2. Parse + execute Hakorune code
|
||||
// 3. Create handle for result
|
||||
// 4. Store in HandleRegistry
|
||||
// 5. Return handle via out_result_handle
|
||||
unimplemented!("Week 1-2")
|
||||
}
|
||||
|
||||
#[no_mangle]
|
||||
pub extern "C" fn Hako_Retain(handle: HakoHandle) {
|
||||
// Increment refcount in HandleRegistry
|
||||
unimplemented!("Week 1-2")
|
||||
}
|
||||
|
||||
#[no_mangle]
|
||||
pub extern "C" fn Hako_Release(handle: HakoHandle) {
|
||||
// Decrement refcount in HandleRegistry
|
||||
// Free if refcount == 0
|
||||
unimplemented!("Week 1-2")
|
||||
}
|
||||
|
||||
#[no_mangle]
|
||||
pub extern "C" fn Hako_ToUtf8(
|
||||
handle: HakoHandle,
|
||||
out_str: *mut HakoStr
|
||||
) -> c_int {
|
||||
// 1. Lookup handle in HandleRegistry
|
||||
// 2. Convert to string (if possible)
|
||||
// 3. Return borrowed pointer + length
|
||||
unimplemented!("Week 1-2")
|
||||
}
|
||||
|
||||
thread_local! {
|
||||
static LAST_ERROR: RefCell<CString> = RefCell::new(CString::new("").unwrap());
|
||||
}
|
||||
|
||||
#[no_mangle]
|
||||
pub extern "C" fn Hako_LastError() -> *const c_char {
|
||||
LAST_ERROR.with(|err| err.borrow().as_ptr())
|
||||
}
|
||||
|
||||
fn set_last_error(msg: &str) {
|
||||
LAST_ERROR.with(|err| {
|
||||
*err.borrow_mut() = CString::new(msg).unwrap_or_default();
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 2: HandleRegistry (Week 2-3)
|
||||
|
||||
**File**: `src/hostbridge/handle_registry.rs` (new)
|
||||
|
||||
```rust
|
||||
use std::collections::HashMap;
|
||||
use std::sync::{Arc, Mutex};
|
||||
|
||||
pub struct HandleRegistry {
|
||||
next_id: u64,
|
||||
handles: HashMap<u64, (Arc<Box<dyn Any>>, u32)>, // (value, refcount)
|
||||
}
|
||||
|
||||
impl HandleRegistry {
|
||||
pub fn new() -> Self {
|
||||
HandleRegistry {
|
||||
next_id: 1,
|
||||
handles: HashMap::new(),
|
||||
}
|
||||
}
|
||||
|
||||
pub fn insert(&mut self, value: Arc<Box<dyn Any>>) -> u64 {
|
||||
let id = self.next_id;
|
||||
self.next_id += 1;
|
||||
self.handles.insert(id, (value, 1)); // refcount = 1
|
||||
id
|
||||
}
|
||||
|
||||
pub fn retain(&mut self, handle: u64) {
|
||||
if let Some((_, ref mut refcount)) = self.handles.get_mut(&handle) {
|
||||
*refcount += 1;
|
||||
}
|
||||
}
|
||||
|
||||
pub fn release(&mut self, handle: u64) {
|
||||
if let Some((_, ref mut refcount)) = self.handles.get_mut(&handle) {
|
||||
*refcount -= 1;
|
||||
if *refcount == 0 {
|
||||
self.handles.remove(&handle);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
pub fn get(&self, handle: u64) -> Option<Arc<Box<dyn Any>>> {
|
||||
self.handles.get(&handle).map(|(val, _)| val.clone())
|
||||
}
|
||||
}
|
||||
|
||||
lazy_static! {
|
||||
static ref GLOBAL_REGISTRY: Mutex<HandleRegistry> = Mutex::new(HandleRegistry::new());
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 3: C Header (Week 3)
|
||||
|
||||
**File**: `include/hakorune_hostbridge.h` (new)
|
||||
|
||||
```c
|
||||
#ifndef HAKORUNE_HOSTBRIDGE_H
|
||||
#define HAKORUNE_HOSTBRIDGE_H
|
||||
|
||||
#include <stdint.h>
|
||||
#include <stddef.h>
|
||||
|
||||
#ifdef __cplusplus
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
/* Opaque handle type */
|
||||
typedef uint64_t HakoHandle;
|
||||
|
||||
/* String view (not null-terminated) */
|
||||
typedef struct {
|
||||
const char* data;
|
||||
size_t len;
|
||||
} HakoStr;
|
||||
|
||||
/* Core API */
|
||||
int32_t Hako_RunScriptUtf8(const char* source_utf8, HakoHandle* out_result_handle);
|
||||
void Hako_Retain(HakoHandle handle);
|
||||
void Hako_Release(HakoHandle handle);
|
||||
int32_t Hako_ToUtf8(HakoHandle handle, HakoStr* out_str);
|
||||
const char* Hako_LastError(void);
|
||||
|
||||
/* Optional API */
|
||||
typedef struct {
|
||||
uint32_t major;
|
||||
uint32_t minor;
|
||||
uint32_t patch;
|
||||
} HakoVersion;
|
||||
|
||||
HakoVersion Hako_ApiVersion(void);
|
||||
int32_t Hako_ToInt64(HakoHandle handle, int64_t* out_value);
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
#endif
|
||||
|
||||
#endif /* HAKORUNE_HOSTBRIDGE_H */
|
||||
```
|
||||
|
||||
### Phase 4: ABI Tests (Week 4)
|
||||
|
||||
**File**: `tests/hostbridge_abi_test.c`
|
||||
|
||||
```c
|
||||
#include "hakorune_hostbridge.h"
|
||||
#include <stdio.h>
|
||||
#include <assert.h>
|
||||
|
||||
void test_hello_world() {
|
||||
const char* script = "static box Main { main() { return \"Hello\" } }";
|
||||
HakoHandle result = 0;
|
||||
|
||||
assert(Hako_RunScriptUtf8(script, &result) == 0);
|
||||
assert(result != 0);
|
||||
|
||||
HakoStr str;
|
||||
assert(Hako_ToUtf8(result, &str) == 0);
|
||||
assert(str.len == 5);
|
||||
assert(memcmp(str.data, "Hello", 5) == 0);
|
||||
|
||||
Hako_Release(result);
|
||||
printf("✅ test_hello_world PASS\n");
|
||||
}
|
||||
|
||||
void test_retain_release() {
|
||||
const char* script = "static box Main { main() { return 42 } }";
|
||||
HakoHandle result = 0;
|
||||
|
||||
assert(Hako_RunScriptUtf8(script, &result) == 0);
|
||||
Hako_Retain(result); // refcount = 2
|
||||
Hako_Release(result); // refcount = 1
|
||||
|
||||
// Still valid
|
||||
int64_t num;
|
||||
assert(Hako_ToInt64(result, &num) == 0);
|
||||
assert(num == 42);
|
||||
|
||||
Hako_Release(result); // refcount = 0, freed
|
||||
printf("✅ test_retain_release PASS\n");
|
||||
}
|
||||
|
||||
void test_error_handling() {
|
||||
const char* bad_script = "this is not valid syntax!!!";
|
||||
HakoHandle result = 0;
|
||||
|
||||
assert(Hako_RunScriptUtf8(bad_script, &result) != 0);
|
||||
const char* err = Hako_LastError();
|
||||
assert(err != NULL);
|
||||
assert(strlen(err) > 0);
|
||||
|
||||
printf("✅ test_error_handling PASS (error: %s)\n", err);
|
||||
}
|
||||
|
||||
int main() {
|
||||
test_hello_world();
|
||||
test_retain_release();
|
||||
test_error_handling();
|
||||
printf("✅ All HostBridge ABI tests PASS\n");
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
**Build**:
|
||||
```bash
|
||||
# Ubuntu
|
||||
gcc -o test_abi tests/hostbridge_abi_test.c -L target/release -lhakorune_kernel
|
||||
./test_abi
|
||||
|
||||
# Windows (MinGW)
|
||||
gcc -o test_abi.exe tests/hostbridge_abi_test.c -L target/release -lhako_kernel
|
||||
./test_abi.exe
|
||||
|
||||
# Windows (MSVC)
|
||||
cl tests/hostbridge_abi_test.c /link target/release/hako_kernel.lib
|
||||
./test_abi.exe
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Testing Strategy
|
||||
|
||||
### Level 1: Unit Tests (Rust)
|
||||
|
||||
**File**: `src/hostbridge/tests.rs`
|
||||
|
||||
```rust
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn test_handle_registry_insert_release() {
|
||||
let mut registry = HandleRegistry::new();
|
||||
let value = Arc::new(Box::new(42i64) as Box<dyn Any>);
|
||||
let handle = registry.insert(value);
|
||||
|
||||
assert!(registry.get(handle).is_some());
|
||||
registry.release(handle);
|
||||
assert!(registry.get(handle).is_none());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_handle_registry_retain() {
|
||||
let mut registry = HandleRegistry::new();
|
||||
let value = Arc::new(Box::new("test") as Box<dyn Any>);
|
||||
let handle = registry.insert(value);
|
||||
|
||||
registry.retain(handle);
|
||||
registry.release(handle);
|
||||
assert!(registry.get(handle).is_some()); // Still valid
|
||||
registry.release(handle);
|
||||
assert!(registry.get(handle).is_none()); // Now freed
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Level 2: ABI Tests (C)
|
||||
|
||||
**Ubuntu + Windows** (see Phase 4 above)
|
||||
|
||||
**Coverage**:
|
||||
- Basic execution (hello world)
|
||||
- Handle lifetime (retain/release)
|
||||
- Error handling (syntax errors)
|
||||
- String conversion (UTF-8)
|
||||
- Integer conversion (Int64)
|
||||
|
||||
### Level 3: Integration Tests (Hakorune)
|
||||
|
||||
**File**: `apps/examples/hostbridge/test_hostbridge_call.hako`
|
||||
|
||||
```hakorune
|
||||
using hostbridge.HostBridgeBox
|
||||
|
||||
static box Main {
|
||||
main() {
|
||||
local bridge = new HostBridgeBox()
|
||||
|
||||
// Test 1: Execute script via C-ABI
|
||||
local script = "static box Main { main() { return 42 } }"
|
||||
local result = bridge.run_script(script)
|
||||
|
||||
if (result != 42) {
|
||||
bridge.log("❌ FAIL: Expected 42")
|
||||
return 1
|
||||
}
|
||||
|
||||
bridge.log("✅ PASS: HostBridge call works")
|
||||
return 0
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ Error Handling Strategy
|
||||
|
||||
### Error Categories
|
||||
|
||||
1. **Parse Errors**: Invalid syntax
|
||||
- Example: `Hako_LastError()` → "Parse error at line 3: Expected '}'"
|
||||
|
||||
2. **Execution Errors**: Runtime exceptions
|
||||
- Example: `Hako_LastError()` → "Runtime error: Division by zero"
|
||||
|
||||
3. **Type Errors**: Invalid type conversion
|
||||
- Example: `Hako_ToInt64(string_handle, &num)` → -1
|
||||
- `Hako_LastError()` → "Type error: Expected Int, got String"
|
||||
|
||||
4. **Handle Errors**: Invalid handle access
|
||||
- Example: `Hako_Release(999999)` → silently ignored (no error)
|
||||
- `Hako_ToUtf8(999999, &str)` → -1, "Invalid handle"
|
||||
|
||||
### Error Message Format
|
||||
|
||||
```
|
||||
[Category] Context: Details
|
||||
|
||||
Examples:
|
||||
[Parse] Line 3: Expected '}'
|
||||
[Runtime] Division by zero in function 'calculate'
|
||||
[Type] Expected Int, got String
|
||||
[Handle] Invalid handle: 12345
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛡️ Platform Considerations
|
||||
|
||||
### Ubuntu (gcc/clang)
|
||||
|
||||
**Thread-Local Storage**:
|
||||
```c
|
||||
__thread CString LAST_ERROR; // gcc extension
|
||||
```
|
||||
|
||||
**Linker Flags**:
|
||||
```bash
|
||||
-lpthread -ldl -lm
|
||||
```
|
||||
|
||||
### Windows (MSVC)
|
||||
|
||||
**Thread-Local Storage**:
|
||||
```c
|
||||
__declspec(thread) CString LAST_ERROR; // MSVC extension
|
||||
```
|
||||
|
||||
**Linker Flags**:
|
||||
```
|
||||
/link advapi32.lib ws2_32.lib
|
||||
```
|
||||
|
||||
### Windows (MinGW)
|
||||
|
||||
**Thread-Local Storage**:
|
||||
```c
|
||||
__thread CString LAST_ERROR; // gcc extension works
|
||||
```
|
||||
|
||||
**Linker Flags**:
|
||||
```bash
|
||||
-lws2_32 -ladvapi32
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📋 Success Criteria
|
||||
|
||||
### Functional
|
||||
|
||||
- [ ] All 5 core functions implemented
|
||||
- [ ] ABI tests PASS on Ubuntu
|
||||
- [ ] ABI tests PASS on Windows
|
||||
- [ ] Error handling works (TLS)
|
||||
- [ ] Handle lifecycle correct (no leaks)
|
||||
|
||||
### Non-Functional
|
||||
|
||||
- [ ] API documentation complete
|
||||
- [ ] Examples for each function
|
||||
- [ ] Integration tests in Hakorune
|
||||
- [ ] Performance: < 1ms overhead per call
|
||||
|
||||
---
|
||||
|
||||
## 🔗 Related Documents
|
||||
|
||||
- [STRATEGY_RECONCILIATION.md](STRATEGY_RECONCILIATION.md) - Why HostBridge?
|
||||
- [PURE_HAKORUNE_ROADMAP.md](PURE_HAKORUNE_ROADMAP.md) - Overall plan
|
||||
- [OP_EQ_MIGRATION.md](OP_EQ_MIGRATION.md) - Next step after HostBridge
|
||||
|
||||
---
|
||||
|
||||
**Status**: Design Phase (Week 1-4 implementation)
|
||||
**Owner**: ChatGPT (implementation), Claude (review)
|
||||
**Timeline**: Week 1-4 of Phase 20.5
|
||||
365
docs/private/roadmap/phases/phase-20.5/INDEX.md
Normal file
365
docs/private/roadmap/phases/phase-20.5/INDEX.md
Normal 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)
|
||||
318
docs/private/roadmap/phases/phase-20.5/INDEX_JA.md
Normal file
318
docs/private/roadmap/phases/phase-20.5/INDEX_JA.md
Normal file
@ -0,0 +1,318 @@
|
||||
# Phase 20.5 — 索引（日本語版）
|
||||
|
||||
**脱Rust大作戦: Gate方式による段階的実装**
|
||||
|
||||
状態: 実行中（Gate A 安定化・Gate B 着手）
|
||||
期間: 6-8週間 (2025-12-21 - 2026-02-中旬)
|
||||
|
||||
---
|
||||
|
||||
## 📚 ドキュメント構造
|
||||
|
||||
### 核心ドキュメント
|
||||
|
||||
1. **[PLAN.md](PLAN.md)** ⭐ **実行中の計画書（英語）**
|
||||
- 5行サマリー / 最小命令セット / DoD
|
||||
- Gate A〜E（Parser→MIR→VM PoC→op_eq→統合）
|
||||
- テスト/CI/リスク/次ステップ
|
||||
|
||||
2. **[README.md](README.md)** ⭐ **全体概要（日本語）**
|
||||
- フェーズ概要とゴール
|
||||
- 週次計画（Week 1-6）
|
||||
- 成功基準とDoD
|
||||
- **Hakorune VM発見による更新版**
|
||||
|
||||
3. **[HAKORUNE_VM_DISCOVERY.md](HAKORUNE_VM_DISCOVERY.md)** ⭐ **重大発見レポート（英語）**
|
||||
- Hakorune VM完全実装の発見（3,413行、22ハンドラー）
|
||||
- アーキテクチャ解析
|
||||
- Phase 20.5戦略の変更（36週間→6週間）
|
||||
|
||||
4. **[STRATEGY_RECONCILIATION.md](STRATEGY_RECONCILIATION.md)** - 戦略比較
|
||||
- C Code Generator vs Pure Hakorune Strategy
|
||||
- リスク評価、信頼度評価
|
||||
- Pure Hakorune戦略採用の理由
|
||||
|
||||
5. **[PURE_HAKORUNE_ROADMAP.md](PURE_HAKORUNE_ROADMAP.md)** - 全体ロードマップ
|
||||
- Phase 20.5-20.8の計画（36週間）
|
||||
- 6フェーズ構成（Phase A-F）
|
||||
- Golden Testing戦略
|
||||
|
||||
---
|
||||
|
||||
## 🎯 クイックリファレンス（5行サマリー）
|
||||
|
||||
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。
|
||||
|
||||
---
|
||||
|
||||
## 📊 Phase 20.5のGate構成（進捗）
|
||||
|
||||
```
|
||||
Gate A（安定）: Parser v1（Hakorune製）→ Canonical AST JSON
|
||||
├─ DoD: ~10ケース PASS、非決定性ゼロ、キーソート
|
||||
├─ CLI: --dump-ast-json, --emit-ast-json
|
||||
└─ Smoke: 9件追加済み（quick-selfhost）
|
||||
|
||||
Gate B（進行中）: MIR Builder v1（最小16命令）
|
||||
├─ DoD: 16命令到達可能、ゴールデンJSON一致
|
||||
└─ 追加スモーク（const+ret, add+ret, eq+branch, lt+branch, binop-mul, compare-ge）
|
||||
|
||||
補足（安定化トピック — 反映済み）
|
||||
- Router 表駆動（String/Map/Array の最小ルート）を builtin/plugin 双方で共有し、ENV 導線を `env_gate_box` へ集約。
|
||||
- Plugin strict（`HAKO_PLUGIN_POLICY=force`）の Fail‑Fast を `env_gate_box::plugin_policy_force()` で単一起点化。
|
||||
- MIR ビルダーのエントリ Copy 配置を PHI→pin Copy→本体へ固定化（use‑before‑def 抑止）。
|
||||
- DCE の used_values() に Method(receiver) を含める経路を単体テストで固定（直線/分岐/ループ）。
|
||||
- Optimizer で `nyrt.string.*` family を Extern に固定（Extern→Method への巻き戻し抑止）。
|
||||
- quick-selfhost に `mir_builder_binop_mul_vm` / `mir_builder_compare_ge_vm` を追加し、Mul/Ge など残りの命令を網羅。
|
||||
|
||||
Gate C（その次）: VM Foundations PoC（5命令 via HostBridge）
|
||||
├─ 命令: const, binop, compare, jump, ret
|
||||
├─ HostBridge経由で実行
|
||||
└─ DoD: シンプルなプログラムend-to-end実行
|
||||
|
||||
Gate D（その次）: op_eq Migration（下準備）
|
||||
├─ NoOperatorGuard + 8型
|
||||
└─ 5-8ゴールデンケース
|
||||
|
||||
Gate E（最後）: Integration & Docs
|
||||
├─ E2E 10ケース PASS
|
||||
└─ ドキュメント完備
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 主要成果物
|
||||
|
||||
### 1️⃣ **Parser canonical JSON**（Gate A）
|
||||
- Hakorune製Parserが決定的AST JSON出力
|
||||
- キー辞書順ソート、非決定性排除
|
||||
- v1==v2==v3検証の土台
|
||||
|
||||
### 2️⃣ **MIR Builder v1**（Gate B）
|
||||
- 最小16命令サポート
|
||||
- MIR JSON正規化
|
||||
- Rust MIR Builder vs Hakorune MIR Builder比較
|
||||
|
||||
### 3️⃣ **VM Foundations PoC**（Gate C）
|
||||
- 5命令のみ（const/binop/compare/jump/ret）
|
||||
- HostBridge経由で実行
|
||||
- Full Hakorune VM（selfhost/hakorune-vm/）への橋渡し
|
||||
|
||||
### 4️⃣ **Full Hakorune VM統合**（Gate C+）
|
||||
- 既存実装（3,413行、22ハンドラー）
|
||||
- HostBridge経由で実行可能に
|
||||
- Rust VM vs Hakorune VM Golden Testing
|
||||
|
||||
---
|
||||
|
||||
## 🔄 全体フロー
|
||||
|
||||
```
|
||||
【Phase 20.5実装フロー】
|
||||
|
||||
Week 1-2: Gate A/B（ChatGPT主導）
|
||||
├─ Parser canonical JSON実装
|
||||
├─ MIR Builder v1実装
|
||||
└─ MirIoBox.normalize()統合
|
||||
|
||||
Week 3-4: Gate C（ChatGPT + Claude協調）
|
||||
├─ VM Foundations PoC（5命令）
|
||||
├─ HostBridge設計・実装
|
||||
└─ Full Hakorune VM統合準備
|
||||
|
||||
Week 5: Full VM統合（両者協調）
|
||||
├─ 5命令PoC → 22命令Full VM拡張
|
||||
├─ selfhost/hakorune-vm/ 統合
|
||||
└─ HostBridge経由実行確認
|
||||
|
||||
Week 6: Gate D/E（Claude主導）
|
||||
├─ op_eq Migration
|
||||
├─ Golden Testing（Rust-VM vs Hako-VM）
|
||||
└─ CLI統合（--backend vm-hako）
|
||||
|
||||
Week 7-8: Integration & Docs
|
||||
├─ E2E 10ケース
|
||||
├─ ドキュメント整備
|
||||
└─ CI minimal green
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧪 テスト戦略
|
||||
|
||||
### テストピラミッド
|
||||
|
||||
```
|
||||
/\
|
||||
/ \ Level 3: Self-Compilation（1テスト、遅い）
|
||||
/____\ - v1が自分自身をコンパイル → v2
|
||||
/ \ - v2が自分自身をコンパイル → v3
|
||||
/ \ - 検証: v2 == v3
|
||||
/__________\
|
||||
/ \ Level 2: 包括的（10テスト、中速）
|
||||
/ \ - if/else、ループ、関数、Box、配列
|
||||
/________________\
|
||||
/ \ Level 1: スモークテスト（43+テスト、高速）
|
||||
- 各MIR命令
|
||||
- 基本パース
|
||||
- JSON正規化
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📦 ディレクトリ構造
|
||||
|
||||
```
|
||||
Phase 20.5計画:
|
||||
docs/private/roadmap/phases/phase-20.5/
|
||||
├── INDEX_JA.md # ← このファイル（日本語版）
|
||||
├── INDEX.md # 英語版索引
|
||||
├── README.md # Phase概要（日本語）
|
||||
├── PLAN.md # Gate実行計画（英語）
|
||||
├── HAKORUNE_VM_DISCOVERY.md # VM発見レポート（英語）
|
||||
├── STRATEGY_RECONCILIATION.md # 戦略比較（英語）
|
||||
└── PURE_HAKORUNE_ROADMAP.md # 全体ロードマップ（英語）
|
||||
|
||||
実装:
|
||||
selfhost/hakorune-vm/ # Full Hakorune VM（既存）
|
||||
├── hakorune_vm_core.hako # VM実行ループ
|
||||
├── instruction_dispatcher.hako # @match dispatch
|
||||
├── *_handler.hako # 22ハンドラー
|
||||
└── tests/*.hako # 26+テスト
|
||||
|
||||
selfhost/shared/mir/
|
||||
└── mir_io_box.hako # MIR JSON I/O（tomoaki作）
|
||||
|
||||
selfhost/shared/json/
|
||||
└── json_canonical_box.hako # JSON正規化（ChatGPT追加）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 成功基準サマリー
|
||||
|
||||
### 技術的基準
|
||||
|
||||
- [ ] Gate A: Parser canonical JSON（~10ケースPASS）
|
||||
- [ ] Gate B: MIR Builder v1（16命令到達可能）
|
||||
- [ ] Gate C: VM PoC（5命令end-to-end実行）
|
||||
- [ ] Gate C+: Full Hakorune VM統合（22ハンドラー）
|
||||
- [ ] Gate D: op_eq Migration（5-8ゴールデンPASS）
|
||||
- [ ] Gate E: 統合テスト（E2E 10ケースPASS）
|
||||
|
||||
### パフォーマンス
|
||||
|
||||
- [ ] VM PoC実行時間: 測定可能
|
||||
- [ ] Full VM性能: Rust VM比≥50%
|
||||
- [ ] メモリ使用量: < 100MB
|
||||
|
||||
### 品質
|
||||
|
||||
- [ ] ドキュメント完備（日本語+英語）
|
||||
- [ ] コードモジュール性（Box-based）
|
||||
- [ ] エッジケース網羅
|
||||
- [ ] レビュー承認（ChatGPT + Claude）
|
||||
|
||||
---
|
||||
|
||||
## 📚 関連フェーズ
|
||||
|
||||
### 前フェーズ
|
||||
|
||||
- [Phase 15.77 - 凍結EXE確定](../phase-15.77/)
|
||||
- [Phase 15.76 - extern_c & Frozen Toolchain](../phase-15.76/)
|
||||
- [Phase 15.75 - 脱Rust計画](../phase-15.75/)
|
||||
|
||||
### 次フェーズ
|
||||
|
||||
- **Phase 20.6 - Rust完全削除**
|
||||
- VM executor → Hakorune実装
|
||||
- Rustコードベース → 0行
|
||||
- Pure Hakorune自己ホスト
|
||||
|
||||
---
|
||||
|
||||
## 💬 開発体制
|
||||
|
||||
### 実装担当
|
||||
|
||||
- **tomoaki**: Hakorune VM実装完了（selfhost/hakorune-vm/）、MirIoBox設計
|
||||
- **ChatGPT**: Gate A/B/C実装（Parser → MIR Builder → VM PoC）
|
||||
- **Claude**: Full VM統合、Golden Testing、ドキュメント整備
|
||||
|
||||
### レビュー方針
|
||||
|
||||
- 各Week終了時: Self-review + スモークテスト
|
||||
- Week 4, 6: Full review（ChatGPT + Claude）
|
||||
- ブロッキング問題: 即座にエスカレーション
|
||||
|
||||
---
|
||||
|
||||
## 🔗 外部リソース
|
||||
|
||||
### 業界事例
|
||||
|
||||
- **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)
|
||||
|
||||
### 論文
|
||||
|
||||
- [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_ReflectiononTrustingTrust.pdf) (Ken Thompson, 1984)
|
||||
|
||||
---
|
||||
|
||||
## 📝 命名規則
|
||||
|
||||
### Stage命名
|
||||
|
||||
- **Stage 1**: Rustコンパイラ、凍結EXE (`hako-frozen-v1`)
|
||||
- **Stage 2**: Hakoruneコンパイラ v1 (`bootstrap_v1`)
|
||||
- **Stage 3**: Hakoruneコンパイラ v2 (`bootstrap_v2`)
|
||||
- **Fixed Point**: v2 == v3（自己一貫性）
|
||||
|
||||
### ファイル命名
|
||||
|
||||
- テスト出力: `test_v1.json`, `test_v2.json`
|
||||
- Bootstrap出力: `bootstrap_v2.c`, `bootstrap_v3.c`
|
||||
- 常にバージョン接尾辞を含める
|
||||
|
||||
### 検証
|
||||
|
||||
- 完全一致比較: `diff`
|
||||
- ハッシュチェック: `md5sum`
|
||||
- 自動化: `tools/verify_bootstrap_chain.sh`
|
||||
|
||||
---
|
||||
|
||||
## 🌟 重要ポイント
|
||||
|
||||
### **Hakorune VM発見の意義**
|
||||
|
||||
- ✅ **36週間→6週間に短縮**（83%削減）
|
||||
- ✅ **実装完了**: 3,413行、22ハンドラー、26+テスト
|
||||
- ✅ **検証・統合に集中**: 実装ではなく、動作確認とGolden Testing
|
||||
|
||||
### **Gate方式の利点**
|
||||
|
||||
- ✅ **段階的進行**: 各Gateは独立してテスト可能
|
||||
- ✅ **ロールバック容易**: 問題発生時は前Gateに戻れる
|
||||
- ✅ **進捗可視化**: Gate完了=具体的マイルストーン
|
||||
|
||||
### **Pure Hakorune戦略**
|
||||
|
||||
- ✅ **"Rust=floor, Hakorune=house"**: Rust最小化（HostBridgeのみ）
|
||||
- ✅ **単一実行パス**: Hakorune VMのみ
|
||||
- ✅ **究極のBox理論**: VMもBoxで実装
|
||||
|
||||
---
|
||||
|
||||
**作成日**: 2025-10-14
|
||||
**最終更新**: 2025-10-14
|
||||
**状態**: Gate A実装中
|
||||
**次回レビュー**: Week 2終了時（Gate B完了後）
|
||||
368
docs/private/roadmap/phases/phase-20.5/MILESTONE.md
Normal file
368
docs/private/roadmap/phases/phase-20.5/MILESTONE.md
Normal file
@ -0,0 +1,368 @@
|
||||
# Phase 20.5 — Milestone (Escape from Rust / Pure Hakorune Strategy)
|
||||
|
||||
Status: Planning (Pure Hakorune Strategy Adopted; v1.1‑frozen reminted)
|
||||
Start: 2025-12-21
|
||||
End: 2026-02-28 (10 weeks)
|
||||
Strategy Change: 2025-10-14 (C Code Generator → Pure Hakorune VM)
|
||||
Dependency: Phase 15.77/15.78 complete; Frozen v1.1 (Linux/MSVC/MinGW) available
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Objectives
|
||||
|
||||
**"Rust=floor, Hakorune=house" - Implement VM itself in Hakorune**
|
||||
|
||||
1. **HostBridge API Complete**: Minimal C-ABI boundary (Rust↔Hakorune)
|
||||
2. **op_eq Migration**: Move equality logic from Rust to Hakorune (NoOperatorGuard)
|
||||
3. **VM Foundations PoC**: Instruction dispatch proof-of-concept (5 instructions)
|
||||
4. **Pure Hakorune Roadmap**: Detailed plan for Phase 20.6-15.82
|
||||
|
||||
**Note**: C Code Generator implementation is **CANCELLED** (Pure Hakorune strategy adopted)
|
||||
|
||||
---
|
||||
|
||||
## ✅ Deliverables (DoD)
|
||||
|
||||
### 1️⃣ HostBridge API Complete
|
||||
|
||||
**C-ABI Functions Working**:
|
||||
```bash
|
||||
./test_hostbridge_abi # Ubuntu
|
||||
./test_hostbridge_abi.exe # Windows
|
||||
```
|
||||
|
||||
**5 Core Functions**:
|
||||
- `Hako_RunScriptUtf8` - Execute Hakorune script
|
||||
- `Hako_Retain / Hako_Release` - Handle reference counting
|
||||
- `Hako_ToUtf8` - Get string view
|
||||
- `Hako_LastError` - Get error message (TLS)
|
||||
|
||||
**Checklist**:
|
||||
- [ ] 5 core functions implemented
|
||||
- [ ] Ubuntu ABI tests PASS
|
||||
- [ ] Windows ABI tests PASS
|
||||
- [ ] Error handling (TLS) working
|
||||
|
||||
---
|
||||
|
||||
### 2️⃣ op_eq Migration Complete
|
||||
|
||||
**Hakorune-side op_eq Working**:
|
||||
```bash
|
||||
HAKO_USE_PURE_EQ=1 ./hako test.hako
|
||||
|
||||
# Golden Test: Rust vs Hako
|
||||
./test_op_eq_golden.sh # Expected: 100% parity
|
||||
```
|
||||
|
||||
**Checklist**:
|
||||
- [ ] NoOperatorGuard implemented (prevents infinite recursion)
|
||||
- [ ] 8 comparison types (int/bool/null/string/array/map/enum/user)
|
||||
- [ ] Golden tests: 20/20 PASS
|
||||
- [ ] Performance: Hako-VM ≥ 70% of Rust-VM
|
||||
|
||||
---
|
||||
|
||||
### 3️⃣ VM Foundations PoC
|
||||
|
||||
**5 Instructions Working**:
|
||||
```bash
|
||||
./hako --backend vm-hako simple_program.hako
|
||||
# Instructions: const, binop, compare, jump, ret
|
||||
```
|
||||
|
||||
**Checklist**:
|
||||
- [ ] 5 instructions implemented
|
||||
- [ ] MIR execution loop (Hakorune implementation)
|
||||
- [ ] Integration test: Run simple programs
|
||||
- [ ] Performance measured
|
||||
|
||||
---
|
||||
|
||||
### 4️⃣ Documentation Complete
|
||||
|
||||
**Checklist**:
|
||||
- [ ] STRATEGY_RECONCILIATION.md (why Pure Hakorune?)
|
||||
- [ ] HOSTBRIDGE_API_DESIGN.md (C-ABI spec)
|
||||
- [ ] OP_EQ_MIGRATION.md (equality implementation guide)
|
||||
- [ ] PURE_HAKORUNE_ROADMAP.md (Phase 20.5-15.82 plan)
|
||||
- [ ] Phase 20.6 planning document
|
||||
|
||||
---
|
||||
|
||||
## 📊 Weekly Milestones
|
||||
|
||||
### Week 1-2: HostBridge API Design & Implementation
|
||||
|
||||
**Goal**: Establish C-ABI boundary
|
||||
|
||||
**Tasks**:
|
||||
- [ ] HostBridge API design (5 core functions)
|
||||
- [ ] HandleRegistry implementation (Rust side)
|
||||
- [ ] C header generation (hakorune_hostbridge.h)
|
||||
- [ ] Basic implementation (RunScriptUtf8, Retain/Release)
|
||||
|
||||
**Deliverables**:
|
||||
```
|
||||
src/hostbridge/
|
||||
├── mod.rs # C-ABI exports
|
||||
├── handle_registry.rs # Handle management
|
||||
└── tests.rs # Unit tests
|
||||
|
||||
include/
|
||||
└── hakorune_hostbridge.h # C header
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Week 3-4: HostBridge API Complete & Testing
|
||||
|
||||
**Goal**: Ubuntu/Windows ABI tests PASS
|
||||
|
||||
**Tasks**:
|
||||
- [ ] ToUtf8, LastError implementation
|
||||
- [ ] Error handling (TLS)
|
||||
- [ ] ABI test creation (C language)
|
||||
- [ ] Ubuntu/Windows verification
|
||||
|
||||
**Deliverables**:
|
||||
```
|
||||
tests/
|
||||
├── hostbridge_abi_test.c # C ABI tests
|
||||
└── hostbridge_integration/
|
||||
└── test_hostbridge_call.hako
|
||||
|
||||
tools/
|
||||
└── test_hostbridge_abi.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Week 5-6: op_eq Migration
|
||||
|
||||
**Goal**: Move equality logic from Rust to Hakorune
|
||||
|
||||
**Tasks**:
|
||||
- [ ] NoOperatorGuard implementation (recursion prevention)
|
||||
- [ ] 8 comparison types (int/bool/null/string/array/map/enum/user)
|
||||
- [ ] Golden test creation (20 cases)
|
||||
- [ ] Rust-VM vs Hako-VM parity verification
|
||||
|
||||
**Deliverables**:
|
||||
```
|
||||
apps/hakorune-vm/
|
||||
├── op_eq_box.hako
|
||||
├── no_operator_guard_box.hako
|
||||
└── tests/
|
||||
|
||||
tests/golden/op_eq/
|
||||
├── primitives.hako
|
||||
├── arrays.hako
|
||||
├── maps.hako
|
||||
├── recursion.hako
|
||||
└── user_defined.hako
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Week 7-8: VM Foundations PoC
|
||||
|
||||
**Goal**: Instruction dispatch proof-of-concept (5 instructions)
|
||||
|
||||
**Tasks**:
|
||||
- [ ] MIR execution loop (Hakorune implementation)
|
||||
- [ ] 5 instructions (const, binop, compare, jump, ret)
|
||||
- [ ] Integration test (run simple programs)
|
||||
- [ ] Performance measurement
|
||||
|
||||
**Deliverables**:
|
||||
```
|
||||
apps/hakorune-vm/
|
||||
├── mini_vm_box.hako
|
||||
├── instruction_dispatch.hako
|
||||
└── tests/
|
||||
|
||||
tests/vm_poc/
|
||||
├── hello.hako
|
||||
├── arithmetic.hako
|
||||
└── control_flow.hako
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Week 9: Integration Testing & Performance
|
||||
|
||||
**Goal**: Integrated operation verification
|
||||
|
||||
**Tasks**:
|
||||
- [ ] HostBridge + op_eq + VM PoC integration
|
||||
- [ ] E2E tests (10 cases)
|
||||
- [ ] Performance measurement & comparison
|
||||
- [ ] Issue identification & fixes
|
||||
|
||||
**Verification Script**:
|
||||
```bash
|
||||
#!/bin/bash
|
||||
set -e
|
||||
|
||||
echo "Test 1: HostBridge API"
|
||||
./test_hostbridge_abi
|
||||
|
||||
echo "Test 2: op_eq Golden Tests"
|
||||
./test_op_eq_golden.sh
|
||||
|
||||
echo "Test 3: VM PoC"
|
||||
./hako --backend vm-hako tests/vm_poc/arithmetic.hako
|
||||
|
||||
echo "✅ PASS: Phase 20.5 Integration Tests"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Week 10: Documentation & Phase 20.6 Planning
|
||||
|
||||
**Goal**: Documentation & next phase planning
|
||||
|
||||
**Tasks**:
|
||||
- [ ] STRATEGY_RECONCILIATION.md
|
||||
- [ ] HOSTBRIDGE_API_DESIGN.md
|
||||
- [ ] OP_EQ_MIGRATION.md
|
||||
- [ ] PURE_HAKORUNE_ROADMAP.md
|
||||
- [ ] Phase 20.6 planning document
|
||||
- [ ] Completion report
|
||||
|
||||
**Deliverables**:
|
||||
```
|
||||
docs/private/roadmap/phases/phase-20.5/
|
||||
├── STRATEGY_RECONCILIATION.md
|
||||
├── HOSTBRIDGE_API_DESIGN.md
|
||||
├── OP_EQ_MIGRATION.md
|
||||
├── PURE_HAKORUNE_ROADMAP.md
|
||||
├── COMPLETION_REPORT.md
|
||||
└── LESSONS_LEARNED.md
|
||||
|
||||
docs/private/roadmap/phases/phase-20.6/
|
||||
└── README.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Success Criteria
|
||||
|
||||
### Technical
|
||||
|
||||
1. **HostBridge API Works**:
|
||||
- C-ABI functions work on Ubuntu + Windows
|
||||
- Handle lifecycle correct (no leaks)
|
||||
- Error handling via TLS
|
||||
|
||||
2. **op_eq Migration Works**:
|
||||
- NoOperatorGuard prevents infinite recursion
|
||||
- Golden tests: 100% Rust-VM parity
|
||||
- Performance: ≥ 70% of Rust-VM
|
||||
|
||||
3. **VM PoC Works**:
|
||||
- 5 instructions execute correctly
|
||||
- Simple programs run end-to-end
|
||||
- Performance measurable
|
||||
|
||||
### Process
|
||||
|
||||
1. **Documentation Complete**:
|
||||
- User can understand Pure Hakorune strategy
|
||||
- Technical specs enable Phase 20.6 implementation
|
||||
- Lessons learned documented
|
||||
|
||||
2. **Testing Comprehensive**:
|
||||
- ABI tests (Ubuntu/Windows)
|
||||
- Golden tests (Rust-VM vs Hako-VM)
|
||||
- Integration tests (E2E)
|
||||
|
||||
3. **Review Approved**:
|
||||
- ChatGPT review complete
|
||||
- Claude review complete
|
||||
- No blocking issues
|
||||
|
||||
---
|
||||
|
||||
## 🚨 Risks & Mitigations
|
||||
|
||||
### Risk 1: Longer Timeline (36 weeks total)
|
||||
|
||||
**Impact**: HIGH (delayed complete self-hosting)
|
||||
**Mitigation**:
|
||||
- Phase 20.5 delivers independent value
|
||||
- Can pause after each phase
|
||||
- Progressive derisking
|
||||
|
||||
### Risk 2: Implementation Complexity
|
||||
|
||||
**Impact**: MEDIUM (more effort than C Generator)
|
||||
**Mitigation**:
|
||||
- Rust VM as reference implementation
|
||||
- Golden tests catch bugs early
|
||||
- Incremental approach (5→16 instructions)
|
||||
|
||||
### Risk 3: Dual VM Maintenance
|
||||
|
||||
**Impact**: MEDIUM (maintenance burden)
|
||||
**Mitigation**:
|
||||
- Freeze Rust VM after Phase 20.5
|
||||
- All new work in Hakorune VM
|
||||
- Clear deprecation timeline (Phase 20.8)
|
||||
|
||||
### Risk 4: C-ABI Stability
|
||||
|
||||
**Impact**: LOW (well-understood boundary)
|
||||
**Mitigation**:
|
||||
- Minimal API (5 functions)
|
||||
- Proven design (Lua/Python C API)
|
||||
- Comprehensive ABI tests
|
||||
|
||||
---
|
||||
|
||||
## 🎉 Success Impact
|
||||
|
||||
### After Phase 20.5 (10 weeks)
|
||||
|
||||
1. **HostBridge API**: Clean Rust↔Hakorune boundary
|
||||
2. **op_eq in Hakorune**: Improved correctness (NoOperatorGuard)
|
||||
3. **VM PoC**: Feasibility demonstrated
|
||||
4. **Phase 20.6 Plan**: Detailed roadmap ready
|
||||
|
||||
### After Phase 20.8 (36 weeks, 2026-09-30)
|
||||
|
||||
5. **Complete Self-Hosting**: Hakorune IS Hakorune
|
||||
6. **Rust Minimized**: ~100 lines (C-ABI bridge only)
|
||||
7. **Ultimate Box Theory**: VM also implemented as Box
|
||||
8. **Long-term Maintainability**: Single execution path
|
||||
|
||||
---
|
||||
|
||||
## 📚 Related Resources
|
||||
|
||||
### Phase 20.5 Documents
|
||||
- [STRATEGY_RECONCILIATION.md](STRATEGY_RECONCILIATION.md) - Why Pure Hakorune?
|
||||
- [HOSTBRIDGE_API_DESIGN.md](HOSTBRIDGE_API_DESIGN.md) - C-ABI specification
|
||||
- [OP_EQ_MIGRATION.md](OP_EQ_MIGRATION.md) - Equality implementation guide
|
||||
- [PURE_HAKORUNE_ROADMAP.md](PURE_HAKORUNE_ROADMAP.md) - Overall plan
|
||||
- [CHATGPT_PURE_HAKORUNE_STRATEGY.md](CHATGPT_PURE_HAKORUNE_STRATEGY.md) - Original proposal
|
||||
|
||||
### Previous Phases
|
||||
- [Phase 15.77 - Frozen EXE Finalization](../phase-15.77/)
|
||||
- [Phase 15.76 - extern_c & Frozen Toolchain](../phase-15.76/)
|
||||
|
||||
### Industry Patterns
|
||||
- **Lua**: Minimal C-API (5-10 functions)
|
||||
- **Python**: C-API + Pure Python stdlib
|
||||
- **Rust**: stage0 (frozen) → stage1 (bootstrap) → stage2 (verify)
|
||||
- **Go**: Go 1.4 frozen → Go 1.5 self-hosted
|
||||
|
||||
---
|
||||
|
||||
**Created**: 2025-10-14
|
||||
**Strategy Changed**: 2025-10-14 (Pure Hakorune adopted)
|
||||
**Phase Start**: 2025-12-21 (after Phase 15.77 completion)
|
||||
**Duration**: 10 weeks (Phase 20.5 only)
|
||||
**Complete Realization**: 36 weeks (Phase 20.5-15.82)
|
||||
**Strategy**: Pure Hakorune ("Rust=floor, Hakorune=house")
|
||||
593
docs/private/roadmap/phases/phase-20.5/OP_EQ_MIGRATION.md
Normal file
593
docs/private/roadmap/phases/phase-20.5/OP_EQ_MIGRATION.md
Normal file
@ -0,0 +1,593 @@
|
||||
# Op_eq Migration — Move Equality to Hakorune
|
||||
|
||||
**Purpose**: Migrate equality (`==`) logic from Rust to Hakorune
|
||||
**Timeline**: Week 5-6 of Phase 20.5
|
||||
**Why**: Fix recursion bugs, improve correctness, prepare for Pure Hakorune
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Problem Statement
|
||||
|
||||
### Current Implementation (Rust)
|
||||
|
||||
**Location**: `src/vm_ops/compare/mod.rs`
|
||||
|
||||
**Issues**:
|
||||
1. **Infinite Recursion**: Nested comparisons can loop forever
|
||||
```rust
|
||||
// Example bug (2025 issue):
|
||||
struct A { field: B }
|
||||
struct B { field: A }
|
||||
a1 == a2 // ← Infinite recursion!
|
||||
```
|
||||
|
||||
2. **Rust-side Logic**: Equality is in Rust, not Hakorune
|
||||
- Violates "Everything in Hakorune" principle
|
||||
- Hard to extend (requires Rust code changes)
|
||||
- Not accessible from Hakorune VM
|
||||
|
||||
3. **No Guard Mechanism**: Missing protection against re-entry
|
||||
- `op_eq` calls `Box.equals()` calls `op_eq` → loop
|
||||
- No way to detect/prevent this cycle
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Target Implementation (Hakorune)
|
||||
|
||||
### New Location
|
||||
|
||||
**File**: `apps/hakorune-vm/op_eq_box.hako` (new)
|
||||
|
||||
**Key Features**:
|
||||
1. **NoOperatorGuard**: Prevents infinite recursion
|
||||
2. **Comparison Order**: Predictable, stable algorithm
|
||||
3. **Extensible**: User-defined `equals` methods
|
||||
4. **Golden Tested**: Rust-VM vs Hako-VM parity
|
||||
|
||||
---
|
||||
|
||||
## 📋 Comparison Algorithm
|
||||
|
||||
### Comparison Order (Top to Bottom)
|
||||
|
||||
```hakorune
|
||||
static box OpEqBox {
|
||||
compare(lhs, rhs, guard) {
|
||||
// 1. Pointer equality (fast path)
|
||||
if (ptr_eq(lhs, rhs)) { return 1 }
|
||||
|
||||
// 2. Primitive types
|
||||
if (is_int(lhs) && is_int(rhs)) {
|
||||
return int_eq(lhs, rhs)
|
||||
}
|
||||
if (is_bool(lhs) && is_bool(rhs)) {
|
||||
return bool_eq(lhs, rhs)
|
||||
}
|
||||
if (is_null(lhs) && is_null(rhs)) {
|
||||
return 1
|
||||
}
|
||||
if (is_null(lhs) || is_null(rhs)) {
|
||||
return 0 // null != non-null
|
||||
}
|
||||
|
||||
// 3. String (value equality)
|
||||
if (is_string(lhs) && is_string(rhs)) {
|
||||
return string_eq(lhs, rhs)
|
||||
}
|
||||
|
||||
// 4. Array (recursive, but guarded)
|
||||
if (is_array(lhs) && is_array(rhs)) {
|
||||
return array_eq(lhs, rhs, guard)
|
||||
}
|
||||
|
||||
// 5. Map (key-value pairs)
|
||||
if (is_map(lhs) && is_map(rhs)) {
|
||||
return map_eq(lhs, rhs, guard)
|
||||
}
|
||||
|
||||
// 6. Enum (@enum types)
|
||||
if (is_enum(lhs) && is_enum(rhs)) {
|
||||
return enum_eq(lhs, rhs, guard)
|
||||
}
|
||||
|
||||
// 7. User-defined equals (via Resolver)
|
||||
if (has_equals_method(lhs)) {
|
||||
return call_user_equals(lhs, rhs, guard)
|
||||
}
|
||||
|
||||
// 8. Default: pointer equality
|
||||
return ptr_eq(lhs, rhs)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛡️ NoOperatorGuard Implementation
|
||||
|
||||
### Purpose
|
||||
|
||||
**Problem**:
|
||||
```
|
||||
A.equals(B) → op_eq(A.field, B.field) → C.equals(D) → op_eq(C.field, D.field) → ...
|
||||
```
|
||||
|
||||
**Solution**: Track visited pairs, detect cycles
|
||||
|
||||
### Design
|
||||
|
||||
```hakorune
|
||||
box NoOperatorGuard {
|
||||
visited: MapBox // Map<(ptr_lhs, ptr_rhs), bool>
|
||||
|
||||
birth() {
|
||||
me.visited = new MapBox()
|
||||
}
|
||||
|
||||
check(lhs, rhs) {
|
||||
local key = make_key(lhs, rhs)
|
||||
if (me.visited.has(key)) {
|
||||
return 0 // Already visiting → false (prevent recursion)
|
||||
}
|
||||
me.visited.set(key, 1)
|
||||
return 1
|
||||
}
|
||||
|
||||
uncheck(lhs, rhs) {
|
||||
local key = make_key(lhs, rhs)
|
||||
me.visited.remove(key)
|
||||
}
|
||||
}
|
||||
|
||||
// Helper
|
||||
make_key(lhs, rhs) {
|
||||
local ptr_lhs = get_ptr(lhs)
|
||||
local ptr_rhs = get_ptr(rhs)
|
||||
return ptr_lhs + ":" + ptr_rhs
|
||||
}
|
||||
```
|
||||
|
||||
### Usage
|
||||
|
||||
```hakorune
|
||||
static box OpEqBox {
|
||||
array_eq(lhs, rhs, guard) {
|
||||
// Check guard before recursing
|
||||
if (!guard.check(lhs, rhs)) {
|
||||
return 0 // Cycle detected
|
||||
}
|
||||
|
||||
local result
|
||||
if (lhs.size() != rhs.size()) {
|
||||
result = 0
|
||||
} else {
|
||||
result = 1
|
||||
local i = 0
|
||||
loop(i < lhs.size()) {
|
||||
// Recursive call with guard
|
||||
if (!me.compare(lhs.get(i), rhs.get(i), guard)) {
|
||||
result = 0
|
||||
break
|
||||
}
|
||||
i = i + 1
|
||||
}
|
||||
}
|
||||
|
||||
// Uncheck after recursion
|
||||
guard.uncheck(lhs, rhs)
|
||||
return result
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔍 Detailed Comparison Implementations
|
||||
|
||||
### 1. Pointer Equality (Fast Path)
|
||||
|
||||
```hakorune
|
||||
ptr_eq(lhs, rhs) {
|
||||
// C-ABI call: Check if same memory address
|
||||
return HostBridgeBox.ptr_eq(lhs, rhs)
|
||||
}
|
||||
```
|
||||
|
||||
**Benefit**: O(1), handles self-references
|
||||
|
||||
---
|
||||
|
||||
### 2. Primitive Types
|
||||
|
||||
```hakorune
|
||||
int_eq(lhs, rhs) {
|
||||
return lhs.value() == rhs.value()
|
||||
}
|
||||
|
||||
bool_eq(lhs, rhs) {
|
||||
return lhs.value() == rhs.value()
|
||||
}
|
||||
|
||||
null_eq(lhs, rhs) {
|
||||
return is_null(lhs) && is_null(rhs)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. String (Value Equality)
|
||||
|
||||
```hakorune
|
||||
string_eq(lhs, rhs) {
|
||||
if (lhs.length() != rhs.length()) {
|
||||
return 0
|
||||
}
|
||||
// Byte-by-byte comparison
|
||||
return lhs.equals(rhs) // StringBox.equals (built-in)
|
||||
}
|
||||
```
|
||||
|
||||
**Note**: StringBox.equals is special (no recursion risk)
|
||||
|
||||
---
|
||||
|
||||
### 4. Array (Recursive, Guarded)
|
||||
|
||||
```hakorune
|
||||
array_eq(lhs, rhs, guard) {
|
||||
if (!guard.check(lhs, rhs)) { return 0 } // Cycle detection
|
||||
|
||||
if (lhs.size() != rhs.size()) {
|
||||
guard.uncheck(lhs, rhs)
|
||||
return 0
|
||||
}
|
||||
|
||||
local result = 1
|
||||
local i = 0
|
||||
loop(i < lhs.size()) {
|
||||
if (!me.compare(lhs.get(i), rhs.get(i), guard)) {
|
||||
result = 0
|
||||
break
|
||||
}
|
||||
i = i + 1
|
||||
}
|
||||
|
||||
guard.uncheck(lhs, rhs)
|
||||
return result
|
||||
}
|
||||
```
|
||||
|
||||
**Complexity**: O(n * m) where n = array size, m = element comparison cost
|
||||
|
||||
---
|
||||
|
||||
### 5. Map (Key-Value Pairs)
|
||||
|
||||
```hakorune
|
||||
map_eq(lhs, rhs, guard) {
|
||||
if (!guard.check(lhs, rhs)) { return 0 }
|
||||
|
||||
if (lhs.size() != rhs.size()) {
|
||||
guard.uncheck(lhs, rhs)
|
||||
return 0
|
||||
}
|
||||
|
||||
local result = 1
|
||||
local keys = lhs.keys()
|
||||
local i = 0
|
||||
loop(i < keys.size()) {
|
||||
local key = keys.get(i)
|
||||
|
||||
// Check key exists in rhs
|
||||
if (!rhs.has(key)) {
|
||||
result = 0
|
||||
break
|
||||
}
|
||||
|
||||
// Check value equality (recursive)
|
||||
local lhs_val = lhs.get(key)
|
||||
local rhs_val = rhs.get(key)
|
||||
if (!me.compare(lhs_val, rhs_val, guard)) {
|
||||
result = 0
|
||||
break
|
||||
}
|
||||
|
||||
i = i + 1
|
||||
}
|
||||
|
||||
guard.uncheck(lhs, rhs)
|
||||
return result
|
||||
}
|
||||
```
|
||||
|
||||
**Complexity**: O(k * v) where k = key count, v = value comparison cost
|
||||
|
||||
---
|
||||
|
||||
### 6. Enum (@enum types)
|
||||
|
||||
```hakorune
|
||||
enum_eq(lhs, rhs, guard) {
|
||||
// 1. Check enum type
|
||||
if (lhs.enum_type() != rhs.enum_type()) {
|
||||
return 0
|
||||
}
|
||||
|
||||
// 2. Check variant
|
||||
if (lhs.variant() != rhs.variant()) {
|
||||
return 0
|
||||
}
|
||||
|
||||
// 3. Check payload (recursive)
|
||||
if (!guard.check(lhs, rhs)) { return 0 }
|
||||
|
||||
local lhs_payload = lhs.payload()
|
||||
local rhs_payload = rhs.payload()
|
||||
local result = me.compare(lhs_payload, rhs_payload, guard)
|
||||
|
||||
guard.uncheck(lhs, rhs)
|
||||
return result
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 7. User-Defined Equals
|
||||
|
||||
```hakorune
|
||||
call_user_equals(lhs, rhs, guard) {
|
||||
// Lookup equals method via Resolver
|
||||
local type_id = lhs.type_id()
|
||||
local handle = Resolver.lookup(type_id, :equals, 1)
|
||||
|
||||
if (handle == null) {
|
||||
// No user-defined equals → fallback to ptr_eq
|
||||
return ptr_eq(lhs, rhs)
|
||||
}
|
||||
|
||||
// Call user equals with guard
|
||||
return ExecBox.call_by_handle(handle, [lhs, rhs], guard)
|
||||
}
|
||||
```
|
||||
|
||||
**Important**: User `equals` receives `guard` as implicit parameter
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Golden Testing Strategy
|
||||
|
||||
### Goal: Rust-VM vs Hako-VM Parity
|
||||
|
||||
**Test Suite**: `tests/golden/op_eq/`
|
||||
|
||||
```
|
||||
op_eq/
|
||||
├── primitives.hako # Int, Bool, Null
|
||||
├── strings.hako # String equality
|
||||
├── arrays.hako # Array equality
|
||||
├── maps.hako # Map equality
|
||||
├── enums.hako # @enum equality
|
||||
├── recursion.hako # Cyclic structures
|
||||
└── user_defined.hako # Custom equals methods
|
||||
```
|
||||
|
||||
### Example Test: Cyclic Array
|
||||
|
||||
**File**: `tests/golden/op_eq/recursion.hako`
|
||||
|
||||
```hakorune
|
||||
static box Main {
|
||||
main() {
|
||||
local arr1 = new ArrayBox()
|
||||
arr1.push(1)
|
||||
arr1.push(arr1) // Self-reference
|
||||
|
||||
local arr2 = new ArrayBox()
|
||||
arr2.push(1)
|
||||
arr2.push(arr2) // Self-reference
|
||||
|
||||
// Should NOT infinite loop
|
||||
if (arr1 == arr2) {
|
||||
return 1 // Expected: true (both self-referential)
|
||||
} else {
|
||||
return 0
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Verification**:
|
||||
```bash
|
||||
# Rust-VM
|
||||
./hako --backend vm-rust tests/golden/op_eq/recursion.hako
|
||||
# Output: 1
|
||||
|
||||
# Hako-VM
|
||||
./hako --backend vm tests/golden/op_eq/recursion.hako
|
||||
# Output: 1
|
||||
|
||||
# Expected: Both return 1 (no infinite loop)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Implementation Timeline
|
||||
|
||||
### Week 5: Core Implementation
|
||||
|
||||
**Day 1-2**: NoOperatorGuard
|
||||
- [ ] Guard data structure (MapBox)
|
||||
- [ ] check/uncheck methods
|
||||
- [ ] Unit tests
|
||||
|
||||
**Day 3-4**: Primitive Comparisons
|
||||
- [ ] ptr_eq, int_eq, bool_eq, null_eq
|
||||
- [ ] string_eq
|
||||
- [ ] Unit tests
|
||||
|
||||
**Day 5-7**: Recursive Comparisons
|
||||
- [ ] array_eq (with guard)
|
||||
- [ ] map_eq (with guard)
|
||||
- [ ] enum_eq (with guard)
|
||||
- [ ] Integration tests
|
||||
|
||||
### Week 6: User-Defined + Golden Tests
|
||||
|
||||
**Day 1-2**: User-Defined Equals
|
||||
- [ ] Resolver integration
|
||||
- [ ] call_user_equals implementation
|
||||
- [ ] Custom equals examples
|
||||
|
||||
**Day 3-5**: Golden Tests
|
||||
- [ ] 20+ test cases (primitives, arrays, maps, enums, recursion)
|
||||
- [ ] Rust-VM vs Hako-VM comparison
|
||||
- [ ] CI integration
|
||||
|
||||
**Day 6-7**: Performance Tuning
|
||||
- [ ] Profile op_eq execution
|
||||
- [ ] Optimize hot paths
|
||||
- [ ] Benchmark: Hako-VM ≥ 70% of Rust-VM speed
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Success Criteria
|
||||
|
||||
### Functional
|
||||
|
||||
- [ ] NoOperatorGuard prevents infinite recursion
|
||||
- [ ] All comparison types implemented (8 types)
|
||||
- [ ] Golden tests: 100% Rust-VM parity
|
||||
- [ ] No crashes or hangs
|
||||
|
||||
### Performance
|
||||
|
||||
- [ ] Hako-VM op_eq ≥ 70% of Rust-VM speed
|
||||
- [ ] No memory leaks (guard cleanup)
|
||||
- [ ] Acceptable overhead (< 10% in non-equality operations)
|
||||
|
||||
### Quality
|
||||
|
||||
- [ ] Unit tests for each comparison type
|
||||
- [ ] Integration tests for complex cases
|
||||
- [ ] Documentation for user-defined equals
|
||||
- [ ] Examples for common patterns
|
||||
|
||||
---
|
||||
|
||||
## 🚧 Migration Strategy
|
||||
|
||||
### Phase 1: Hakorune Implementation (Week 5)
|
||||
|
||||
**Keep Rust op_eq**: Still in use (default)
|
||||
**Add Hako op_eq**: New implementation (opt-in)
|
||||
|
||||
```bash
|
||||
# Use Rust op_eq (default)
|
||||
./hako test.hako
|
||||
|
||||
# Use Hako op_eq (opt-in)
|
||||
HAKO_USE_PURE_EQ=1 ./hako test.hako
|
||||
```
|
||||
|
||||
### Phase 2: Golden Testing (Week 6)
|
||||
|
||||
**Run both implementations**:
|
||||
```bash
|
||||
for test in tests/golden/op_eq/*.hako; do
|
||||
# Rust op_eq
|
||||
./hako --backend vm-rust "$test" > rust.txt
|
||||
|
||||
# Hako op_eq
|
||||
HAKO_USE_PURE_EQ=1 ./hako --backend vm "$test" > hako.txt
|
||||
|
||||
# Compare
|
||||
diff rust.txt hako.txt || echo "FAIL: $test"
|
||||
done
|
||||
```
|
||||
|
||||
### Phase 3: Switchover (End of Week 6)
|
||||
|
||||
**Make Hako op_eq default**:
|
||||
```rust
|
||||
// src/vm_ops/compare/mod.rs
|
||||
pub fn op_eq(lhs: &Value, rhs: &Value) -> bool {
|
||||
if env::var("HAKO_USE_RUST_EQ").is_ok() {
|
||||
// Old Rust implementation (compat mode)
|
||||
rust_op_eq(lhs, rhs)
|
||||
} else {
|
||||
// New Hakorune implementation (default)
|
||||
call_hako_op_eq(lhs, rhs)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 4: Rust Deprecation (Phase 20.6+)
|
||||
|
||||
**Remove Rust op_eq entirely**:
|
||||
- Rust side only calls Hakorune
|
||||
- No Rust equality logic
|
||||
- "Rust=floor, Hakorune=house" ✅
|
||||
|
||||
---
|
||||
|
||||
## 🛡️ Edge Cases
|
||||
|
||||
### 1. Cyclic Structures
|
||||
|
||||
**Test**:
|
||||
```hakorune
|
||||
local arr = new ArrayBox()
|
||||
arr.push(arr) // Self-reference
|
||||
arr == arr // Should return 1 (no infinite loop)
|
||||
```
|
||||
|
||||
**Solution**: NoOperatorGuard detects `(arr, arr)` already visiting
|
||||
|
||||
---
|
||||
|
||||
### 2. Mixed Types
|
||||
|
||||
**Test**:
|
||||
```hakorune
|
||||
1 == "1" // Should return 0 (Int != String)
|
||||
```
|
||||
|
||||
**Solution**: Type check before comparison
|
||||
|
||||
---
|
||||
|
||||
### 3. Null Handling
|
||||
|
||||
**Test**:
|
||||
```hakorune
|
||||
null == null // Should return 1
|
||||
null == 0 // Should return 0
|
||||
```
|
||||
|
||||
**Solution**: Special-case null in comparison order
|
||||
|
||||
---
|
||||
|
||||
### 4. Floating Point (Future)
|
||||
|
||||
**Test**:
|
||||
```hakorune
|
||||
3.14 == 3.14 // Should return 1
|
||||
NaN == NaN // Should return 0 (IEEE 754)
|
||||
```
|
||||
|
||||
**Solution**: Add float_eq with IEEE 754 rules (Phase 20.6+)
|
||||
|
||||
---
|
||||
|
||||
## 📚 Related Documents
|
||||
|
||||
- [STRATEGY_RECONCILIATION.md](STRATEGY_RECONCILIATION.md) - Why migrate op_eq?
|
||||
- [PURE_HAKORUNE_ROADMAP.md](PURE_HAKORUNE_ROADMAP.md) - Overall plan
|
||||
- [CHATGPT_PURE_HAKORUNE_STRATEGY.md](CHATGPT_PURE_HAKORUNE_STRATEGY.md) - Original guidance
|
||||
|
||||
---
|
||||
|
||||
**Status**: Design (Week 5-6 implementation)
|
||||
**Owner**: ChatGPT (implementation), Claude (review)
|
||||
**Timeline**: Week 5-6 of Phase 20.5
|
||||
80
docs/private/roadmap/phases/phase-20.5/PLAN.md
Normal file
80
docs/private/roadmap/phases/phase-20.5/PLAN.md
Normal file
@ -0,0 +1,80 @@
|
||||
# Phase 20.5 — Gate Plan (脱Rust 大作戦)
|
||||
|
||||
Status: Active
|
||||
Scope: Minimal, verifiable, gate‑based execution plan
|
||||
|
||||
## Executive Summary (5 lines)
|
||||
- Goal: Escape from Rust by bootstrapping a self‑hosting Hakorune line.
|
||||
- Strategy: Freeze Rust (v1.1‑frozen) and build upward in small, verifiable gates.
|
||||
- Shape: Parser → MIR → (Pure VM Foundations) with HostBridge as the only external boundary.
|
||||
- Proof: Deterministic outputs, parity, and fixed‑point (v1==v2==v3) where applicable.
|
||||
- Policy: Keep changes minimal, deterministic, and test‑first (SKIP when preconditions unmet).
|
||||
|
||||
## Gates (must pass in order)
|
||||
- Gate A: Parser v1 (Hakorune) produces canonical AST JSON
|
||||
- DoD: ~10 cases PASS; no non‑determinism; keys sorted
|
||||
- Implemented CLI: `--dump-ast-json` (stdout), `--emit-ast-json <file>` (pre‑macro)
|
||||
- Smokes (quick‑selfhost):
|
||||
- parser_ast_json_canonical_vm.sh, parser_ast_json_return_vm.sh, parser_ast_json_unary_vm.sh
|
||||
- parser_ast_json_array_literal_vm.sh, parser_ast_json_map_literal_vm.sh
|
||||
- parser_ast_json_empty_array_vm.sh, parser_ast_json_empty_map_vm.sh
|
||||
- parser_ast_json_if_else_vm.sh, parser_ast_json_emit_file_vm.sh
|
||||
- MirIoBox normalize（guarded by `HAKO_JSON_CANON`）: mirio_canonicalize_vm.sh
|
||||
- Gate B: MIR Builder v1 (Hakorune) emits minimal MIR (16 ops)
|
||||
- Scope (P1): const, ret, binop(Add/Sub/Mul/Div/Mod), compare(Eq/Ne/Lt/Le/Gt/Ge), jump, branch
|
||||
- DoD: 16 ops reachable; quick-selfhostで4本の代表スモークPASS（不足はSKIPガードで段階導入）
|
||||
- Smokes (quick-selfhost):
|
||||
- mir_builder_const_ret_vm.sh（const→ret）
|
||||
- mir_builder_binop_add_vm.sh（const,const→binop(Add)→ret）
|
||||
- mir_builder_compare_eq_vm.sh（compare(Eq)→branch→then/else→ret）
|
||||
- mir_builder_compare_lt_vm.sh（compare(Lt)→branch→then/else→ret）
|
||||
- Status（2025-10-23）:
|
||||
- Stage‑1 default/vararg/named 混在を Fail‑Fast 化（`NYASH_PIPELINE_V2=1` gate、selfhost_pipeline_v2_stage1_invalid_args_fail_vm.sh）。
|
||||
- selfhost 系スモークは `SMOKES_SELFHOST_ENABLE=1` で opt-in（既定では quick/integration から除外）。
|
||||
- Gate C: VM Foundations (Pure Hakorune) — 5 ops PoC via HostBridge
|
||||
- Ops: const, binop, compare, jump, ret
|
||||
- DoD: Simple programs run end‑to‑end; measurable performance
|
||||
- CLI entry (thin wiring):
|
||||
- `--nyvm-json-file <path>` → read MIR(JSON v0) and execute via HakoruneVmCore.run_from_file
|
||||
- `--nyvm-pipe` → read MIR(JSON v0) from stdin and execute via HakoruneVmCore.run
|
||||
- Gate D: op_eq Migration (NoOperatorGuard + 8 types)
|
||||
- DoD: 20 golden tests PASS; ≥70% perf vs Rust‑VM
|
||||
- Gate E: Integration & Docs
|
||||
- DoD: E2E 10 cases PASS; docs complete; CI minimal green
|
||||
|
||||
Note: C Code Generator track is preserved as design reference but not primary; Pure Hakorune VM is the active plan.
|
||||
|
||||
## Minimal Instruction Set (Phase 20.5 scope)
|
||||
- Values/control: const, ret
|
||||
- Arithmetic: binop(Add/Sub/Mul/Div/Mod)
|
||||
- Compare: Eq/Ne/Lt/Le/Gt/Ge (boolean 0/1)
|
||||
- Control: jump, branch
|
||||
- Phi: pre‑compute lowering (block‑local temps)
|
||||
|
||||
## Determinism & DoD
|
||||
- Canonicalize JSON (sorted keys), stable whitespace/newlines
|
||||
- No timestamps/PIDs/randomness/hash iteration variance
|
||||
- DoD per gate as listed; aggregate: Parser→MIR→VM PoC end‑to‑end
|
||||
|
||||
## Test Plan
|
||||
- Level 1 (Sanity): 4 tests → const/ret/binop/compare
|
||||
- Level 2 (Coverage): 10 tests → if/loops/arrays/strings/minimal recursion
|
||||
- Level 3 (PoC): 1 test → VM 5‑ops program runs (Pure Hakorune)
|
||||
- Policy: preconditions unmet → SKIP（WARN）; only regressions are FAIL
|
||||
|
||||
## CI & Packaging (minimal)
|
||||
- CI minimal: cargo build --release + quick‑selfhost (SKIP前提で緑) + make release(manifest)
|
||||
- Windows builds: manual MSVC preferred; MinGW as reference
|
||||
- Dist: Linux + Windows(MSVC/MinGW) with README_FROZEN_QUICKSTART and release notes
|
||||
|
||||
## Risks & Mitigations (short)
|
||||
- v1 != v2 drift → deterministic JSON + canonical emit + golden tests
|
||||
- Performance slow → accept PoC cost; profile hot paths; ≤30s budget for self‑compile later
|
||||
- Box不足 → pre‑surveyed minimal set; add only under gates
|
||||
|
||||
## Next Steps (actionable)
|
||||
1) Lock Gate A/B test lists; add golden fixtures（json sorted）
|
||||
2) Implement VM PoC (5 ops) via HostBridge（apps/hakorune‑vm）
|
||||
3) Migrate op_eq with NoOperatorGuard + 20 golden tests
|
||||
4) Turn SKIP gates into PASS progressively（quick‑selfhost → plugins → integration）
|
||||
5) Update MILESTONE/INDEX weekly; keep artifacts/manifest fresh
|
||||
317
docs/private/roadmap/phases/phase-20.5/PLAN_JA.md
Normal file
317
docs/private/roadmap/phases/phase-20.5/PLAN_JA.md
Normal file
@ -0,0 +1,317 @@
|
||||
# Phase 20.5 — Gate計画（脱Rust大作戦）
|
||||
|
||||
状態: 実行中
|
||||
範囲: 最小、検証可能、Gate方式実行計画
|
||||
|
||||
## エグゼクティブサマリー（5行）
|
||||
|
||||
- **Goal（目標）**: Rustから脱却し、自己ホスト可能なHakoruneラインをブートストラップする。
|
||||
- **Strategy（戦略）**: Rustを凍結（v1.1-frozen）し、小さく検証可能なGateで積み上げる。
|
||||
- **Shape（形状）**: Parser → MIR → (Pure VM Foundations)、HostBridgeが唯一の外部境界。
|
||||
- **Proof（証明）**: 決定的出力、パリティ、固定点（v1==v2==v3）で検証。
|
||||
- **Policy（方針）**: 変更は最小限、決定的、テストファースト（前提条件未達→SKIP）。
|
||||
|
||||
---
|
||||
|
||||
## Gates（順番に通過必須）
|
||||
|
||||
### Gate A: Parser v1（Hakorune製）→ Canonical AST JSON
|
||||
- **DoD**: ~10ケース PASS、非決定性なし、キーソート済み
|
||||
- **実装CLI**: `--dump-ast-json`（stdout）、`--emit-ast-json <file>`（マクロ前）
|
||||
- **Smokes（quick-selfhost）**:
|
||||
- `parser_ast_json_canonical_vm.sh`, `parser_ast_json_return_vm.sh`
|
||||
- `parser_ast_json_unary_vm.sh`, `parser_ast_json_array_literal_vm.sh`
|
||||
- `parser_ast_json_map_literal_vm.sh`, `parser_ast_json_empty_array_vm.sh`
|
||||
- `parser_ast_json_empty_map_vm.sh`, `parser_ast_json_if_else_vm.sh`
|
||||
- `parser_ast_json_emit_file_vm.sh`
|
||||
- **MirIoBox正規化**: `mirio_canonicalize_vm.sh`（`HAKO_JSON_CANON`でガード）
|
||||
|
||||
### Gate B: MIR Builder v1（Hakorune製）→ 最小MIR（16命令）
|
||||
- **DoD**: 16命令到達可能、ゴールデンJSON一致、キーソート済み
|
||||
|
||||
### Gate C: VM Foundations（Pure Hakorune）→ 5命令PoC via HostBridge
|
||||
- **命令**: const, binop, compare, jump, ret
|
||||
- **DoD**: シンプルなプログラムがend-to-end実行、測定可能なパフォーマンス
|
||||
|
||||
### Gate D: op_eq Migration（NoOperatorGuard + 8型）
|
||||
- **DoD**: 20ゴールデンテストPASS、Rust-VM比≥70%パフォーマンス
|
||||
|
||||
### Gate E: Integration & Docs
|
||||
- **DoD**: E2E 10ケースPASS、ドキュメント完備、CI minimal green
|
||||
|
||||
---
|
||||
|
||||
**注**: C Code Generatorトラックは設計参考として保存されているが、主要ではない。Pure Hakorune VMが実行中の計画。
|
||||
|
||||
---
|
||||
|
||||
## 最小命令セット（Phase 20.5スコープ）
|
||||
|
||||
- **値/制御**: const, ret
|
||||
- **算術**: binop(Add/Sub/Mul/Div/Mod)
|
||||
- **比較**: Eq/Ne/Lt/Le/Gt/Ge（boolean 0/1）
|
||||
- **制御**: jump, branch
|
||||
- **Phi**: 事前計算による降格（ブロックローカル一時変数）
|
||||
|
||||
---
|
||||
|
||||
## 決定性 & DoD
|
||||
|
||||
- **JSON正規化**: キーソート、安定した空白/改行
|
||||
- **非決定性排除**: タイムスタンプ/PID/乱数/ハッシュ反復順序の分散なし
|
||||
- **GateごとのDoD**: 上記リスト参照、集約: Parser→MIR→VM PoC end-to-end
|
||||
|
||||
---
|
||||
|
||||
## テスト計画
|
||||
|
||||
- **Level 1（Sanity）**: 4テスト → const/ret/binop/compare
|
||||
- **Level 2（Coverage）**: 10テスト → if/loops/arrays/strings/最小再帰
|
||||
- **Level 3（PoC）**: 1テスト → VM 5命令プログラム実行（Pure Hakorune）
|
||||
- **方針**: 前提条件未達 → SKIP（WARN）、回帰のみFAIL
|
||||
|
||||
---
|
||||
|
||||
## CI & パッケージング（最小限）
|
||||
|
||||
- **CI最小限**: `cargo build --release` + quick-selfhost（SKIP前提でグリーン） + `make release`（manifest）
|
||||
- **Windowsビルド**: 手動MSVC推奨、MinGW参考
|
||||
- **配布**: Linux + Windows（MSVC/MinGW）、README_FROZEN_QUICKSTART + リリースノート
|
||||
|
||||
---
|
||||
|
||||
## リスク & 対策（短文）
|
||||
|
||||
- **v1 != v2ドリフト** → 決定的JSON + 正規化emit + ゴールデンテスト
|
||||
- **パフォーマンス低下** → PoCコスト受容、ホットパスプロファイル、後で自己コンパイル≤30s予算
|
||||
- **Box不足** → 事前調査済み最小セット、Gateの下でのみ追加
|
||||
|
||||
---
|
||||
|
||||
## 次のステップ（実行可能）
|
||||
|
||||
1. Gate A/Bテストリスト確定、ゴールデンフィクスチャ追加（jsonソート済み）
|
||||
2. VM PoC（5命令）実装 via HostBridge（`apps/hakorune-vm`）
|
||||
3. op_eq移行 with NoOperatorGuard + 20ゴールデンテスト
|
||||
4. SKIPゲートを段階的にPASSへ（quick-selfhost → plugins → integration）
|
||||
5. MILESTONE/INDEXを週次更新、artifacts/manifestを新鮮に保つ
|
||||
|
||||
---
|
||||
|
||||
## 詳細: 各Gate
|
||||
|
||||
### 🎯 **Gate A: Parser canonical JSON**
|
||||
|
||||
**目的**: Hakorune製Parserが決定的なAST JSONを出力
|
||||
|
||||
**実装内容**:
|
||||
```bash
|
||||
# 新しいCLIフラグ
|
||||
./hako --dump-ast-json program.hako # stdout
|
||||
./hako --emit-ast-json output.json program.hako # file
|
||||
```
|
||||
|
||||
**DoD（完了定義）**:
|
||||
- [ ] ~10テストケースPASS
|
||||
- [ ] 非決定性ゼロ（タイムスタンプ/PID/ハッシュ順序なし）
|
||||
- [ ] JSONキー辞書順ソート
|
||||
- [ ] 9個のスモークテスト追加（quick-selfhost）
|
||||
|
||||
**スモークテスト一覧**:
|
||||
1. `parser_ast_json_canonical_vm.sh` - 基本カノニカル化
|
||||
2. `parser_ast_json_return_vm.sh` - return文
|
||||
3. `parser_ast_json_unary_vm.sh` - 単項演算子
|
||||
4. `parser_ast_json_array_literal_vm.sh` - 配列リテラル
|
||||
5. `parser_ast_json_map_literal_vm.sh` - マップリテラル
|
||||
6. `parser_ast_json_empty_array_vm.sh` - 空配列
|
||||
7. `parser_ast_json_empty_map_vm.sh` - 空マップ
|
||||
8. `parser_ast_json_if_else_vm.sh` - if/else
|
||||
9. `parser_ast_json_emit_file_vm.sh` - ファイル出力
|
||||
|
||||
**MirIoBox統合**:
|
||||
- `mirio_canonicalize_vm.sh` - MirIoBox.normalize()テスト
|
||||
- 環境変数ガード: `HAKO_JSON_CANON=1`
|
||||
|
||||
---
|
||||
|
||||
### 🎯 **Gate B: MIR Builder v1**
|
||||
|
||||
**目的**: 最小16命令のMIR JSON生成
|
||||
|
||||
**命令セット**:
|
||||
```
|
||||
const, ret # 値/制御
|
||||
binop(Add/Sub/Mul/Div/Mod) # 算術（5種類）
|
||||
compare(Eq/Ne/Lt/Le/Gt/Ge) # 比較（6種類）
|
||||
jump, branch # 制御フロー
|
||||
```
|
||||
|
||||
**DoD（完了定義）**:
|
||||
- [ ] 16命令すべて到達可能
|
||||
- [ ] ゴールデンJSON一致（Rust MIR vs Hako MIR）
|
||||
- [ ] キーソート済み
|
||||
- [ ] 4本のスモークテストPASS:
|
||||
- `const+ret` - 定数返却
|
||||
- `add+ret` - 加算返却
|
||||
- `eq+branch` - 等価比較分岐
|
||||
- `lt+branch` - 大小比較分岐
|
||||
|
||||
**実装場所**:
|
||||
- `selfhost/compiler/mir_builder/` - 既存骨格再利用
|
||||
- 出力: 共通正規化適用（`JsonCanonicalBox`）
|
||||
|
||||
---
|
||||
|
||||
### 🎯 **Gate C: VM Foundations PoC**
|
||||
|
||||
**目的**: 5命令のみでend-to-end実行（HostBridge経由）
|
||||
|
||||
**対象命令**:
|
||||
```
|
||||
const # 定数ロード
|
||||
binop # 二項演算（Add/Sub/Mul/Div/Mod）
|
||||
compare # 比較（Eq/Ne/Lt/Le/Gt/Ge）
|
||||
jump # 無条件ジャンプ
|
||||
ret # 返却
|
||||
```
|
||||
|
||||
**DoD（完了定義）**:
|
||||
- [ ] 5命令がHostBridge経由で実行可能
|
||||
- [ ] 2本のスモークテストPASS:
|
||||
- `const+ret` - 定数返却
|
||||
- `compare+branch相当` - if条件分岐
|
||||
- [ ] シンプルなプログラムがend-to-end実行
|
||||
- [ ] 測定可能なパフォーマンス
|
||||
|
||||
**HostBridge設計**:
|
||||
```
|
||||
HostBridge.extern_invoke() 最小パス
|
||||
↓
|
||||
ExternAdapter/HostBridge活用
|
||||
↓
|
||||
VM 5命令実行
|
||||
↓
|
||||
Result返却
|
||||
```
|
||||
|
||||
**実装メモ**: `phase-20.5/PLAN.md`に「PoCの入口・戻り値・制限」を明記
|
||||
|
||||
---
|
||||
|
||||
### 🎯 **Gate D: op_eq Migration**
|
||||
|
||||
**目的**: 等価性ロジックをRust→Hakoruneへ移行（下準備）
|
||||
|
||||
**仕様整理**:
|
||||
- MIRでEq/Neの意味論確定
|
||||
- Box同士は呼び出し正規化
|
||||
- ドキュメントに原則・禁止パターン・Verifier観点を追記（短文）
|
||||
|
||||
**最小ゴールデン（5-8ケース）**:
|
||||
- プリミティブ（i64/string/bool）
|
||||
- BoxRef（pointer equalityのみ）を固定
|
||||
|
||||
**DoD（完了定義）**:
|
||||
- [ ] 仕様ドキュメント完成
|
||||
- [ ] 5-8ゴールデンケース作成
|
||||
- [ ] quick-selfhostでPASS
|
||||
|
||||
---
|
||||
|
||||
### 🎯 **Gate E: Integration & Docs**
|
||||
|
||||
**目的**: 全体統合、ドキュメント整備
|
||||
|
||||
**DoD（完了定義）**:
|
||||
- [ ] E2E 10ケースPASS
|
||||
- [ ] ドキュメント完備（日本語+英語）
|
||||
- [ ] CI minimal green
|
||||
- [ ] Phase 20.5完了報告書作成
|
||||
|
||||
---
|
||||
|
||||
## 🔄 実装フロー
|
||||
|
||||
```
|
||||
Week 1-2: Gate A Polish + Gate B実装
|
||||
├─ Parser canonical JSON仕上げ（10ケース）
|
||||
├─ MirIoBox.normalize()統合
|
||||
└─ MIR Builder v1実装（16命令）
|
||||
|
||||
Week 3-4: Gate C実装 + Full VM統合準備
|
||||
├─ VM Foundations PoC（5命令）
|
||||
├─ HostBridge設計・実装
|
||||
└─ Full Hakorune VM（selfhost/hakorune-vm/）調査
|
||||
|
||||
Week 5: Full VM統合
|
||||
├─ 5命令PoC → 22命令Full VM拡張
|
||||
├─ selfhost/hakorune-vm/ 統合
|
||||
└─ HostBridge経由実行確認
|
||||
|
||||
Week 6: Gate D/E
|
||||
├─ op_eq Migration（下準備）
|
||||
├─ Golden Testing
|
||||
└─ Integration & Docs
|
||||
|
||||
Week 7-8（オプション）: Polish & CI
|
||||
├─ CI minimal green
|
||||
└─ リリース準備
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 進捗追跡
|
||||
|
||||
### **Gate A: Parser canonical JSON**（実装中）
|
||||
|
||||
- [x] CLI実装（`--dump-ast-json`, `--emit-ast-json`）
|
||||
- [x] 9個のスモークテスト追加
|
||||
- [x] MirIoBox.normalize()統合
|
||||
- [ ] ~10ケース全PASS
|
||||
- [ ] ドキュメント追記（docs/guides/env-variables.md）
|
||||
|
||||
### **Gate B: MIR Builder v1**（次）
|
||||
|
||||
- [ ] 最小16命令仕様明記（docs/reference/ir/mir-json-v0.md）
|
||||
- [ ] 最小ビルダー実装（selfhost側）
|
||||
- [ ] 4本スモークPASS
|
||||
|
||||
### **Gate C: VM Foundations PoC**（その次）
|
||||
|
||||
- [ ] HostBridge設計
|
||||
- [ ] 5命令実装 via HostBridge
|
||||
- [ ] 2本スモークPASS
|
||||
|
||||
### **Gate D: op_eq Migration**（その次）
|
||||
|
||||
- [ ] 仕様整理
|
||||
- [ ] 5-8ゴールデンケース
|
||||
|
||||
### **Gate E: Integration & Docs**（最後）
|
||||
|
||||
- [ ] E2E 10ケース
|
||||
- [ ] ドキュメント完備
|
||||
|
||||
---
|
||||
|
||||
## 🎉 成功の定義
|
||||
|
||||
Phase 20.5完了時:
|
||||
|
||||
1. ✅ **Parser canonical JSON動作**（Gate A）
|
||||
2. ✅ **MIR Builder v1動作**（Gate B）
|
||||
3. ✅ **VM PoC動作**（Gate C: 5命令）
|
||||
4. ✅ **Full Hakorune VM統合**（Gate C+: 22命令）
|
||||
5. ✅ **op_eq下準備完了**（Gate D）
|
||||
6. ✅ **E2E統合テスト**（Gate E）
|
||||
7. ✅ **ドキュメント完備**（日本語+英語）
|
||||
8. ✅ **CI minimal green**
|
||||
|
||||
次のPhase（Phase 20.6）への準備完了！
|
||||
|
||||
---
|
||||
|
||||
**作成日**: 2025-10-14
|
||||
**最終更新**: 2025-10-14（Gate A実装中）
|
||||
**状態**: Gate A Polish中
|
||||
**次回マイルストーン**: Gate B完了（Week 2終了時）
|
||||
482
docs/private/roadmap/phases/phase-20.5/PURE_HAKORUNE_ROADMAP.md
Normal file
482
docs/private/roadmap/phases/phase-20.5/PURE_HAKORUNE_ROADMAP.md
Normal file
@ -0,0 +1,482 @@
|
||||
# Pure Hakorune Roadmap — Phase 20.5 to 15.82
|
||||
|
||||
**Vision**: "Rust=floor, Hakorune=house" - Implement VM itself in Hakorune
|
||||
**Timeline**: 36 weeks (2025-12-21 → 2026-09-30)
|
||||
**Status**: APPROVED (User preference: "純 Hakorune 大作戦")
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Overview: 6 Phases of Pure Hakorune
|
||||
|
||||
ChatGPT Pro's strategy divides implementation into 6 logical phases:
|
||||
|
||||
```
|
||||
Phase A: HostBridge (Week 1-4) ← Phase 20.5
|
||||
Phase B: VM Core (Week 5-12) ← Phase 20.5 (start) → 15.80 (complete)
|
||||
Phase C: Dispatch Unity (Week 13-18) ← Phase 20.6
|
||||
Phase D: Collections (Week 19-26) ← Phase 20.7
|
||||
Phase E: GC v0 (Week 27-32) ← Phase 20.8
|
||||
Phase F: Rust Compat Mode (Week 33-36) ← Phase 20.8
|
||||
```
|
||||
|
||||
**Key Insight**: Phase 20.5 (10 weeks) completes Phase A + starts Phase B.
|
||||
|
||||
---
|
||||
|
||||
## 📊 Phase Breakdown
|
||||
|
||||
### Phase 20.5 (10 weeks): Foundation
|
||||
|
||||
**Dates**: 2025-12-21 → 2026-02-28
|
||||
|
||||
**Completes**:
|
||||
- ✅ **Phase A: HostBridge** (Week 1-4)
|
||||
- ✅ **Phase B (start): VM Foundations** (Week 5-8)
|
||||
|
||||
**Deliverables**:
|
||||
1. **HostBridge API** (C-ABI boundary):
|
||||
- `Hako_RunScriptUtf8`, `Retain/Release`, `ToUtf8`, `LastError`
|
||||
- Ubuntu/Windows ABI tests
|
||||
- Error handling (TLS)
|
||||
|
||||
2. **`op_eq` Migration** (Week 5-6):
|
||||
- Equality logic moved from Rust → Hakorune
|
||||
- `NoOperatorGuard` prevents recursion
|
||||
- Golden tests: Rust-VM vs Hako-VM parity
|
||||
|
||||
3. **VM Foundations PoC** (Week 7-8):
|
||||
- Instruction dispatch skeleton (5 instructions)
|
||||
- MIR execution loop in Hakorune
|
||||
- Integration test: Run simple programs
|
||||
|
||||
4. **Documentation** (Week 9-10):
|
||||
- HostBridge API spec
|
||||
- Op_eq migration guide
|
||||
- Pure Hakorune roadmap (this doc)
|
||||
- Phase 20.6 planning
|
||||
|
||||
**Success Criteria**:
|
||||
- ✅ HostBridge API stable (Ubuntu/Windows)
|
||||
- ✅ `op_eq` in Hakorune (NoOperatorGuard working)
|
||||
- ✅ VM PoC runs 5 instructions (const, binop, compare, jump, ret)
|
||||
- ⚠️ NOT: Full VM (deferred to Phase 20.6)
|
||||
- ⚠️ NOT: Bootstrap compiler (deferred to Phase 20.8+)
|
||||
|
||||
---
|
||||
|
||||
### Phase 20.6 (12 weeks): VM Core Complete
|
||||
|
||||
**Dates**: 2026-03-01 → 2026-05-24
|
||||
|
||||
**Completes**:
|
||||
- ✅ **Phase B (complete): VM Core in Hakorune**
|
||||
- ✅ **Phase C: Dispatch Unification**
|
||||
|
||||
**Deliverables**:
|
||||
|
||||
#### Phase B Complete (Week 1-6):
|
||||
1. **All 16 MIR Instructions** in Hakorune:
|
||||
- const, binop, compare, jump, branch, phi, ret ✅ (from 20.5)
|
||||
- call, boxcall, externcall
|
||||
- load, store, copy, typeop
|
||||
- barrier, safepoint, loopform
|
||||
|
||||
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
|
||||
|
||||
**Success Criteria**:
|
||||
- ✅ Hako-VM runs all 16 instructions
|
||||
- ✅ Golden tests: 100% Rust-VM parity
|
||||
- ✅ Dispatch unified (single Resolver path)
|
||||
- ✅ Performance: Hako-VM ≥ 50% of Rust-VM
|
||||
- ⚠️ NOT: Collections in Hakorune (deferred to Phase 20.7)
|
||||
|
||||
---
|
||||
|
||||
### Phase 20.7 (8 weeks): Collections in Hakorune
|
||||
|
||||
**Dates**: 2026-05-25 → 2026-07-19
|
||||
|
||||
**Completes**:
|
||||
- ✅ **Phase D: Collections (MapBox/ArrayBox)**
|
||||
|
||||
**Deliverables**:
|
||||
|
||||
1. **MapBox in Hakorune**:
|
||||
- Hash map implementation
|
||||
- Deterministic hash/eq (decision mode)
|
||||
- Key normalization (Symbol/Int/String)
|
||||
- Methods: `set`, `get`, `has`, `remove`, `size`, `keys`, `values`
|
||||
|
||||
2. **ArrayBox in Hakorune**:
|
||||
- Dynamic array implementation
|
||||
- Methods: `push`, `pop`, `get`, `set`, `size`, `slice`, `concat`
|
||||
|
||||
3. **Key Comparison Order**:
|
||||
- Symbol < Int < String (stable sort)
|
||||
- Deterministic iteration order
|
||||
- Provenance tracking (plugin_id, version)
|
||||
|
||||
4. **ValueBox/DataBox Boundaries**:
|
||||
- ValueBox: Temporary (pipeline boundaries only)
|
||||
- DataBox: Persistent (long-lived)
|
||||
- Fail-Fast: Unpack at entry/exit points
|
||||
|
||||
**Success Criteria**:
|
||||
- ✅ MapBox/ArrayBox fully in Hakorune
|
||||
- ✅ Golden tests: Rust-Collections vs Hako-Collections parity
|
||||
- ✅ Deterministic behavior (decision mode)
|
||||
- ✅ Performance: ≥ 70% of Rust-Collections
|
||||
- ⚠️ NOT: GC (still using Rust-side GC)
|
||||
|
||||
---
|
||||
|
||||
### Phase 20.8 (6 weeks): GC + Rust Deprecation
|
||||
|
||||
**Dates**: 2026-07-20 → 2026-08-30
|
||||
|
||||
**Completes**:
|
||||
- ✅ **Phase E: GC v0 (Mark & Sweep)**
|
||||
- ✅ **Phase F: Rust VM Compat Mode**
|
||||
|
||||
**Deliverables**:
|
||||
|
||||
#### Phase E: GC v0 (Week 1-4):
|
||||
1. **Stop-the-world Mark & Sweep**:
|
||||
- Mark: Trace reachable objects from roots
|
||||
- Sweep: Free unreachable objects
|
||||
- Minimal implementation (no generational, no incremental)
|
||||
|
||||
2. **Roots**:
|
||||
- Stack frames (local variables)
|
||||
- Global static boxes
|
||||
- HandleRegistry (C-ABI handles)
|
||||
|
||||
3. **Metrics**:
|
||||
- Allocation count
|
||||
- Survivor count
|
||||
- Sweep time
|
||||
- Handle count
|
||||
|
||||
4. **Observability**:
|
||||
- `HAKO_GC_TRACE=1` → detailed GC log
|
||||
- GC stats at program exit
|
||||
|
||||
#### Phase F: Rust VM Compat Mode (Week 5-6):
|
||||
1. **Deprecate Rust VM**:
|
||||
- Hakorune-VM is default (`--backend vm`)
|
||||
- Rust-VM becomes opt-in (`--backend vm-rust`)
|
||||
- Warning: "Rust-VM is deprecated, use Hakorune-VM"
|
||||
|
||||
2. **Bit-Identical Verification**:
|
||||
- Hako₁ → Hako₂ → Hako₃ (self-compilation)
|
||||
- Verify: Hako₁ == Hako₂ == Hako₃ (byte-by-byte)
|
||||
- CI runs daily verification
|
||||
|
||||
3. **Rust Layer Minimization**:
|
||||
- Rust code: ~100 lines (HostBridge only)
|
||||
- Everything else in Hakorune
|
||||
- "Rust=floor, Hakorune=house" ✅
|
||||
|
||||
**Success Criteria**:
|
||||
- ✅ GC v0 works (no memory leaks)
|
||||
- ✅ Hakorune-VM is default backend
|
||||
- ✅ Rust-VM deprecated (compat mode)
|
||||
- ✅ Bit-identical self-compilation
|
||||
- ✅ Rust layer ≤ 100 lines
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Dependencies Between Phases
|
||||
|
||||
```
|
||||
Phase A (HostBridge)
|
||||
↓
|
||||
Phase B (VM Core) ← Needs HostBridge for C-ABI
|
||||
↓
|
||||
Phase C (Dispatch) ← Needs VM Core for execution
|
||||
↓
|
||||
Phase D (Collections) ← Needs Dispatch for method calls
|
||||
↓
|
||||
Phase E (GC) ← Needs Collections for memory management
|
||||
↓
|
||||
Phase F (Deprecate Rust) ← Needs GC for full autonomy
|
||||
```
|
||||
|
||||
**Critical Path**: A → B → C → D → E → F (sequential)
|
||||
|
||||
**Parallelization Opportunities**:
|
||||
- Phase C (Dispatch) can start during Phase B (VM Core) Week 5-6
|
||||
- Phase D (Collections) design can happen during Phase C
|
||||
- Phase E (GC) design can happen during Phase D
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ Implementation Principles
|
||||
|
||||
### 1. Box-First ("箱理論")
|
||||
|
||||
**Every component is a Box**:
|
||||
```hakorune
|
||||
// HostBridge
|
||||
box HostBridgeBox { /* C-ABI calls */ }
|
||||
|
||||
// VM
|
||||
box MiniVmBox { /* Instruction dispatch */ }
|
||||
|
||||
// Collections
|
||||
box MapBox { /* Hash map */ }
|
||||
box ArrayBox { /* Dynamic array */ }
|
||||
|
||||
// GC
|
||||
box GcBox { /* Mark & sweep */ }
|
||||
```
|
||||
|
||||
### 2. Boundary = C-ABI ("境界")
|
||||
|
||||
**Single boundary**:
|
||||
```
|
||||
Rust (floor) Hakorune (house)
|
||||
| |
|
||||
|--- HostBridge (C-ABI) -------|
|
||||
| |
|
||||
~100 lines Everything else
|
||||
```
|
||||
|
||||
### 3. Invocation = Handle ("呼び出し")
|
||||
|
||||
**Single invocation path**:
|
||||
```hakorune
|
||||
// All calls go through:
|
||||
ExecBox.call_by_handle(handle, args, NoOperatorGuard)
|
||||
|
||||
// handle from:
|
||||
Resolver.lookup(type_id, method, arity)
|
||||
```
|
||||
|
||||
### 4. Resolution = Resolver ("解決")
|
||||
|
||||
**Single resolution path**:
|
||||
```hakorune
|
||||
// No special-case dispatch
|
||||
Resolver.lookup(type_id, method, arity) -> MethodHandle
|
||||
|
||||
// Example:
|
||||
local handle = Resolver.lookup(arr_type_id, :push, 1)
|
||||
ExecBox.call_by_handle(handle, [arr, value], NoOperatorGuard)
|
||||
```
|
||||
|
||||
### 5. Fail-Fast ("即失敗")
|
||||
|
||||
**No silent fallbacks**:
|
||||
```hakorune
|
||||
// ❌ BAD: Silent fallback
|
||||
if (lookup_fails) { return default_value }
|
||||
|
||||
// ✅ GOOD: Explicit error
|
||||
if (lookup_fails) { panic("Method not found: " + method) }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Golden Testing Strategy
|
||||
|
||||
### Golden Test = Rust-VM vs Hako-VM Parity
|
||||
|
||||
**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
|
||||
```
|
||||
|
||||
**CI Integration**:
|
||||
```yaml
|
||||
# .github/workflows/golden_tests.yml
|
||||
name: Golden Tests
|
||||
on: [push, pull_request]
|
||||
jobs:
|
||||
golden:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Run golden tests
|
||||
run: |
|
||||
for test in tests/golden/*.hako; do
|
||||
./hako --backend vm-rust "$test" > rust.txt
|
||||
./hako --backend vm "$test" > hako.txt
|
||||
diff rust.txt hako.txt || exit 1
|
||||
done
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Risk Mitigation
|
||||
|
||||
### Risk 1: Longer Timeline (36 weeks)
|
||||
|
||||
**Mitigation**:
|
||||
- Each phase delivers independent value
|
||||
- Can pause after Phase 20.5 (HostBridge + op_eq + VM PoC)
|
||||
- Can pause after Phase 20.6 (Full VM Core)
|
||||
- Progressive derisking
|
||||
|
||||
### Risk 2: Implementation Complexity
|
||||
|
||||
**Mitigation**:
|
||||
- Rust VM as reference implementation
|
||||
- Golden tests catch bugs early
|
||||
- Incremental approach (5 instructions → 16 instructions)
|
||||
- ChatGPT/Claude collaboration
|
||||
|
||||
### Risk 3: Performance
|
||||
|
||||
**Mitigation**:
|
||||
- Measure at each phase
|
||||
- Accept slower performance initially (50% of Rust-VM is OK)
|
||||
- Optimize hot paths after correctness is proven
|
||||
- Profile-guided optimization in later phases
|
||||
|
||||
### Risk 4: Maintenance Burden (Dual VMs)
|
||||
|
||||
**Mitigation**:
|
||||
- Freeze Rust VM after Phase 20.5 (no new features)
|
||||
- All new work happens in Hakorune-VM
|
||||
- Clear deprecation timeline (Phase 20.8)
|
||||
- Golden tests prevent divergence
|
||||
|
||||
---
|
||||
|
||||
## 📊 Progress Tracking
|
||||
|
||||
### Phase 20.5 (Current)
|
||||
|
||||
**Week 1-4**: HostBridge API
|
||||
- [ ] C-ABI design finalized
|
||||
- [ ] Rust implementation (5 functions)
|
||||
- [ ] Ubuntu ABI tests PASS
|
||||
- [ ] Windows ABI tests PASS
|
||||
|
||||
**Week 5-6**: Op_eq Migration
|
||||
- [ ] Equality logic in Hakorune
|
||||
- [ ] NoOperatorGuard implementation
|
||||
- [ ] Golden tests: Rust vs Hako equality
|
||||
|
||||
**Week 7-8**: VM Foundations PoC
|
||||
- [ ] 5 instructions implemented (const, binop, compare, jump, ret)
|
||||
- [ ] MIR execution loop
|
||||
- [ ] Integration test: Run simple programs
|
||||
|
||||
**Week 9-10**: Documentation
|
||||
- [ ] HostBridge API spec
|
||||
- [ ] Op_eq migration guide
|
||||
- [ ] Pure Hakorune roadmap
|
||||
- [ ] Phase 20.6 planning
|
||||
|
||||
### Phase 20.6 (Future)
|
||||
|
||||
**Week 1-6**: VM Core Complete
|
||||
- [ ] 16 instructions implemented
|
||||
- [ ] Control flow (branch, phi, loop)
|
||||
- [ ] Golden tests: 100% parity
|
||||
|
||||
**Week 7-12**: Dispatch Unification
|
||||
- [ ] Resolver integration
|
||||
- [ ] CallableBox refactoring
|
||||
- [ ] Universal route minimization
|
||||
|
||||
### Phase 20.7 (Future)
|
||||
|
||||
**Week 1-4**: MapBox in Hakorune
|
||||
**Week 5-8**: ArrayBox in Hakorune
|
||||
|
||||
### Phase 20.8 (Future)
|
||||
|
||||
**Week 1-4**: GC v0
|
||||
**Week 5-6**: Rust VM deprecation
|
||||
|
||||
---
|
||||
|
||||
## 🎉 Success Impact
|
||||
|
||||
### After Phase 20.5 (10 weeks)
|
||||
|
||||
1. **HostBridge API**: Clean C-ABI boundary
|
||||
2. **Op_eq in Hakorune**: Improved correctness (NoOperatorGuard)
|
||||
3. **VM PoC**: Feasibility demonstrated
|
||||
|
||||
### After Phase 20.6 (22 weeks total)
|
||||
|
||||
4. **VM Core Complete**: Hakorune can run itself
|
||||
5. **Dispatch Unified**: Single resolution path (Resolver)
|
||||
6. **Performance**: ≥ 50% of Rust-VM
|
||||
|
||||
### After Phase 20.7 (30 weeks total)
|
||||
|
||||
7. **Collections in Hakorune**: MapBox/ArrayBox
|
||||
8. **Deterministic**: Stable iteration order
|
||||
9. **Everything is Box**: True realization
|
||||
|
||||
### After Phase 20.8 (36 weeks total)
|
||||
|
||||
10. **GC v0**: No memory leaks
|
||||
11. **Rust Minimal**: ≤ 100 lines (HostBridge only)
|
||||
12. **True Self-Hosting**: Hakorune IS Hakorune ✅
|
||||
|
||||
---
|
||||
|
||||
## 📚 Related Documents
|
||||
|
||||
- [STRATEGY_RECONCILIATION.md](STRATEGY_RECONCILIATION.md) - Why Pure Hakorune?
|
||||
- [HOSTBRIDGE_API_DESIGN.md](HOSTBRIDGE_API_DESIGN.md) - C-ABI spec
|
||||
- [OP_EQ_MIGRATION.md](OP_EQ_MIGRATION.md) - Equality implementation
|
||||
- [CHATGPT_PURE_HAKORUNE_STRATEGY.md](CHATGPT_PURE_HAKORUNE_STRATEGY.md) - Original proposal
|
||||
|
||||
---
|
||||
|
||||
**Status**: APPROVED
|
||||
**Timeline**: 2025-12-21 → 2026-09-30 (36 weeks)
|
||||
**Current Phase**: 20.5 (Week 1-10)
|
||||
**Next Phase**: 15.80 (Week 11-22)
|
||||
639
docs/private/roadmap/phases/phase-20.5/README.md
Normal file
639
docs/private/roadmap/phases/phase-20.5/README.md
Normal file
@ -0,0 +1,639 @@
|
||||
# Phase 20.5 - Hakorune VM Validation & Adoption
|
||||
|
||||
**期間**: 2025-12-21 - 2026-01-31 (6週間)
|
||||
**状態**: Planning ⚠️ **CRITICAL UPDATE** - VM already exists!
|
||||
**前提**: Phase 15.77完了 (凍結EXE確定)
|
||||
**重大発見**: Hakorune VM is **100% COMPLETE** (2025-10-14)
|
||||
|
||||
---
|
||||
|
||||
## 🎉 Critical Discovery (2025-10-14)
|
||||
|
||||
**Original Assumption**: Hakorune VM does not exist, needs 36 weeks to build.
|
||||
|
||||
**Actual Reality**: **Hakorune VM is COMPLETE** in `selfhost/hakorune-vm/`!
|
||||
- ✅ 3,413 lines of Hakorune code
|
||||
- ✅ 44 files including 22 instruction handlers
|
||||
- ✅ 26+ comprehensive tests
|
||||
- ✅ All 16 MIR instructions + 6 advanced handlers
|
||||
- ✅ @match-based dispatch architecture
|
||||
- ✅ Result-based error handling
|
||||
- ✅ Implementation period: October 5-13, 2025 (8 days!)
|
||||
|
||||
**Impact**: Phase 20.5 changes from "implementation" to **"validation & adoption"**.
|
||||
|
||||
📖 **Full Discovery Report**: [HAKORUNE_VM_DISCOVERY.md](HAKORUNE_VM_DISCOVERY.md)
|
||||
|
||||
---
|
||||
|
||||
## 🎯 このフェーズで実現すること（更新版）
|
||||
|
||||
**"Hakorune VM → 検証 → CLI統合 → デフォルト化"**
|
||||
|
||||
1. **Hakorune VM検証**: 既存22ハンドラーの動作確認
|
||||
2. **Golden Testing**: Rust-VM vs Hako-VM 完全一致保証
|
||||
3. **CLI統合**: `--backend vm-hako` 実装
|
||||
4. **ドキュメント整備**: アーキテクチャ・移行ガイド
|
||||
5. **オプション: HostBridge API**: C-ABI境界（他の理由で必要な場合のみ）
|
||||
|
||||
**変更点**:
|
||||
- ❌ **VM実装** → ✅ **VM検証**（既に完成）
|
||||
- ❌ **36週間** → ✅ **6週間**
|
||||
- ❌ **段階的実装** → ✅ **全機能検証**
|
||||
|
||||
---
|
||||
|
||||
## 💡 このフェーズの位置づけ（更新版）
|
||||
|
||||
```
|
||||
Phase 15.77（凍結EXE確定）✅
|
||||
├── hako-frozen-v1.exe (724KB MSVC)
|
||||
├── NyRT関数呼び出し可能
|
||||
└── MIR JSON → .o → EXE 導線確立
|
||||
|
||||
Hakorune VM実装完了（2025-10-05 → 10-13）✅
|
||||
├── 3,413 lines / 44 files
|
||||
├── 22 instruction handlers
|
||||
├── 26+ comprehensive tests
|
||||
└── selfhost/hakorune-vm/
|
||||
|
||||
Phase 20.5（VM検証・統合）← 今ここ
|
||||
├── Week 1-2: VM検証・テスト拡充
|
||||
├── Week 3-4: Golden Testing（Rust-VM vs Hako-VM）
|
||||
├── Week 5: CLI統合（--backend vm-hako）
|
||||
└── Week 6: ドキュメント・Phase 20.6計画
|
||||
|
||||
Phase 20.6（オプション: HostBridge + Rust最小化）
|
||||
├── HostBridge API実装（必要な場合）
|
||||
├── Rust VM非推奨化
|
||||
└── Hakorune VM デフォルト化
|
||||
```
|
||||
|
||||
**重要**: Phase 20.6以降は「必要に応じて」実施。Hakorune VM単体で動作可能。
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Progress Snapshot（2025-10-23）
|
||||
|
||||
- **Constructor parity**: VM/LLVM 双方で `Callee::Constructor` の birth 引数（0〜3）と未知 Box Fail‑Fast を確認する parity スモークを追加。
|
||||
- quick: `tools/smokes/v2/profiles/quick/llvm/parity_constructor_birth_arity_vm_llvm.sh`, `parity_constructor_errors_vm_llvm.sh`
|
||||
- integration: `tools/smokes/v2/profiles/integration/parity/parity_constructor_birth_arity_vm_llvm.sh`, `parity_constructor_errors_vm_llvm.sh`
|
||||
- **ModuleFunction 静的 me 合成**: `src/tests/mir_module_function_static.rs` で Builder が singleton `me` を自動注入し、Rust VM が 42 を返すことを固定（`static_singleton_me` ヒントの整合性を検証）。
|
||||
- **Selfhost pipeline Stage‑1 ガード**: `NYASH_PIPELINE_V2=1` で Stage‑1 の default/vararg/named 混在を Fail‑Fast 化し、`selfhost_pipeline_v2_stage1_invalid_args_fail_vm.sh`（`SMOKES_SELFHOST_ENABLE=1` opt-in）で回帰テストを追加。
|
||||
- **Profiles**: quick 299/299 PASS・integration 35/35 PASS を継続監視（macro child 停止 & noise filter 追加済み）。
|
||||
|
||||
---
|
||||
|
||||
## 🏆 成功基準（DoD）
|
||||
|
||||
### 1️⃣ Hakorune VM検証完了
|
||||
|
||||
```bash
|
||||
# 既存テストスイート実行
|
||||
cd selfhost/hakorune-vm
|
||||
for test in tests/*.hako; do
|
||||
NYASH_DISABLE_PLUGINS=1 ../../target/release/hako "$test"
|
||||
done
|
||||
|
||||
# 期待: 26+ tests ALL PASS
|
||||
```
|
||||
|
||||
**チェックリスト**:
|
||||
- [ ] 26個の既存テスト すべて PASS
|
||||
- [ ] 22個のハンドラー動作確認
|
||||
- [ ] エラーハンドリング（Result）動作確認
|
||||
- [ ] @match dispatch 動作確認
|
||||
|
||||
### 2️⃣ Golden Testing完了
|
||||
|
||||
```bash
|
||||
# Golden Test実行（Rust-VM vs Hako-VM）
|
||||
bash tools/golden_test_hakorune_vm.sh
|
||||
|
||||
# 期待: 100% parity
|
||||
```
|
||||
|
||||
**テストケース**:
|
||||
- [ ] 算術演算（10ケース）
|
||||
- [ ] 制御フロー（10ケース）
|
||||
- [ ] コレクション操作（10ケース）
|
||||
- [ ] 再帰（5ケース）
|
||||
- [ ] クロージャ（5ケース）
|
||||
- [ ] 合計40ケース すべて一致
|
||||
|
||||
### 3️⃣ CLI統合完了
|
||||
|
||||
```bash
|
||||
# Hakorune VM経由で実行可能
|
||||
./target/release/hako --backend vm-hako program.hako
|
||||
|
||||
# 環境変数でもOK
|
||||
HAKO_USE_HAKORUNE_VM=1 ./target/release/hako program.hako
|
||||
```
|
||||
|
||||
**チェックリスト**:
|
||||
- [ ] `--backend vm-hako` フラグ実装
|
||||
- [ ] `HAKO_USE_HAKORUNE_VM=1` 環境変数対応
|
||||
- [ ] エラーメッセージ整備
|
||||
- [ ] パフォーマンス測定
|
||||
|
||||
### 4️⃣ ドキュメント整備完了
|
||||
|
||||
**必須ドキュメント**:
|
||||
- [ ] `selfhost/hakorune-vm/README.md` - アーキテクチャ概要
|
||||
- [ ] `selfhost/hakorune-vm/DESIGN.md` - 設計パターン
|
||||
- [ ] `selfhost/hakorune-vm/TESTING.md` - テスト戦略
|
||||
- [ ] `docs/guides/hakorune-vm-migration.md` - 移行ガイド
|
||||
- [ ] Phase 20.6計画書（オプション: HostBridge）
|
||||
|
||||
---
|
||||
|
||||
## 📊 週次計画（Week 1-6）
|
||||
|
||||
### Week 1（2025-12-21 - 12-27）VM検証・テスト実行
|
||||
|
||||
**目標**: 既存実装の動作確認
|
||||
|
||||
#### タスク
|
||||
```bash
|
||||
# 1. 既存テスト全実行
|
||||
cd selfhost/hakorune-vm
|
||||
for test in tests/*.hako; do
|
||||
echo "Testing: $test"
|
||||
NYASH_DISABLE_PLUGINS=1 ../../target/release/hako "$test" || echo "FAIL"
|
||||
done
|
||||
|
||||
# 2. ハンドラーカバレッジ確認
|
||||
ls *_handler.hako | wc -l # 期待: 22
|
||||
|
||||
# 3. エラーケーステスト
|
||||
# - 不正なMIR JSON
|
||||
# - 未定義命令
|
||||
# - 型エラー
|
||||
```
|
||||
|
||||
**成果物**:
|
||||
- [ ] テスト実行レポート（26+ tests）
|
||||
- [ ] カバレッジレポート（22 handlers）
|
||||
- [ ] バグ修正リスト（あれば）
|
||||
|
||||
### Week 2（2025-12-28 - 2026-01-03）テスト拡充
|
||||
|
||||
**目標**: テストカバレッジ拡大
|
||||
|
||||
#### タスク
|
||||
```bash
|
||||
# 新規テストケース追加
|
||||
selfhost/hakorune-vm/tests/
|
||||
├── test_edge_cases/
|
||||
│ ├── test_large_numbers.hako
|
||||
│ ├── test_deep_recursion.hako
|
||||
│ ├── test_long_strings.hako
|
||||
│ └── test_complex_control_flow.hako
|
||||
└── test_stress/
|
||||
├── test_1000_instructions.hako
|
||||
└── test_nested_calls_100_deep.hako
|
||||
```
|
||||
|
||||
**成果物**:
|
||||
- [ ] 10個の新規テストケース
|
||||
- [ ] エッジケース網羅
|
||||
- [ ] ストレステスト実施
|
||||
|
||||
### Week 3-4（2026-01-04 - 01-17）Golden Testing
|
||||
|
||||
**目標**: Rust-VM vs Hako-VM 完全一致保証
|
||||
|
||||
#### Golden Testスイート作成
|
||||
```bash
|
||||
tests/golden/hakorune-vm/
|
||||
├── arithmetic/
|
||||
│ ├── test_add.hako
|
||||
│ ├── test_mul.hako
|
||||
│ └── test_div.hako (10 tests)
|
||||
├── control_flow/
|
||||
│ ├── test_if_else.hako
|
||||
│ ├── test_loop.hako
|
||||
│ └── test_branch.hako (10 tests)
|
||||
├── collections/
|
||||
│ ├── test_array_ops.hako
|
||||
│ ├── test_map_ops.hako
|
||||
│ └── test_string_ops.hako (10 tests)
|
||||
├── recursion/
|
||||
│ ├── test_factorial.hako
|
||||
│ └── test_fibonacci.hako (5 tests)
|
||||
└── closures/
|
||||
├── test_capture.hako
|
||||
└── test_nested.hako (5 tests)
|
||||
```
|
||||
|
||||
#### Golden Test実行スクリプト
|
||||
```bash
|
||||
# tools/golden_test_hakorune_vm.sh
|
||||
#!/bin/bash
|
||||
set -e
|
||||
|
||||
PASS=0
|
||||
FAIL=0
|
||||
|
||||
for test in tests/golden/hakorune-vm/**/*.hako; do
|
||||
echo "Testing: $test"
|
||||
|
||||
# Rust VM実行
|
||||
./target/release/hako --backend vm "$test" > /tmp/rust_out.txt 2>&1
|
||||
rust_exit=$?
|
||||
|
||||
# Hakorune VM実行
|
||||
./target/release/hako --backend vm-hako "$test" > /tmp/hako_out.txt 2>&1
|
||||
hako_exit=$?
|
||||
|
||||
# 出力比較
|
||||
if diff /tmp/rust_out.txt /tmp/hako_out.txt && [ $rust_exit -eq $hako_exit ]; then
|
||||
echo " ✅ PASS"
|
||||
((PASS++))
|
||||
else
|
||||
echo " ❌ FAIL"
|
||||
echo " Rust output:"
|
||||
cat /tmp/rust_out.txt
|
||||
echo " Hako output:"
|
||||
cat /tmp/hako_out.txt
|
||||
((FAIL++))
|
||||
fi
|
||||
done
|
||||
|
||||
echo ""
|
||||
echo "Golden Test Results:"
|
||||
echo " PASS: $PASS"
|
||||
echo " FAIL: $FAIL"
|
||||
echo " Total: $((PASS + FAIL))"
|
||||
|
||||
if [ $FAIL -eq 0 ]; then
|
||||
echo "✅ All Golden Tests PASSED!"
|
||||
exit 0
|
||||
else
|
||||
echo "❌ Some Golden Tests FAILED"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
**成果物**:
|
||||
- [ ] 40個のGolden Testケース
|
||||
- [ ] Golden Test実行スクリプト
|
||||
- [ ] CI統合（GitHub Actions）
|
||||
- [ ] パフォーマンス比較レポート
|
||||
|
||||
### Week 5（2026-01-18 - 01-24）CLI統合
|
||||
|
||||
**目標**: `--backend vm-hako` 実装
|
||||
|
||||
#### 実装ファイル
|
||||
```rust
|
||||
// src/backend/hakorune_vm_runner.rs (NEW)
|
||||
use std::path::PathBuf;
|
||||
use crate::error::Result;
|
||||
|
||||
pub fn run_hakorune_vm(mir_json: String) -> Result<i64> {
|
||||
// 1. selfhost/hakorune-vm/hakorune_vm_core.hako をロード
|
||||
let vm_core_path = PathBuf::from("selfhost/hakorune-vm/hakorune_vm_core.hako");
|
||||
|
||||
// 2. Rust VMでHakoruneVmCoreBoxを実行
|
||||
let vm_instance = load_and_run_box(&vm_core_path)?;
|
||||
|
||||
// 3. HakoruneVmCoreBox.run(mir_json) を呼び出し
|
||||
let result = vm_instance.call_method("run", vec![Box::new(mir_json)])?;
|
||||
|
||||
// 4. 結果を返す
|
||||
Ok(result.as_int()?)
|
||||
}
|
||||
|
||||
// src/cli.rs (MODIFY)
|
||||
match backend {
|
||||
Backend::Vm => run_rust_vm(mir),
|
||||
Backend::VmHako => run_hakorune_vm(mir), // NEW!
|
||||
Backend::Llvm => run_llvm(mir),
|
||||
Backend::Wasm => run_wasm(mir),
|
||||
}
|
||||
```
|
||||
|
||||
**テスト**:
|
||||
```bash
|
||||
# 基本実行
|
||||
./target/release/hako --backend vm-hako apps/tests/hello.hako
|
||||
# 期待: Hello World出力
|
||||
|
||||
# 環境変数版
|
||||
HAKO_USE_HAKORUNE_VM=1 ./target/release/hako apps/tests/hello.hako
|
||||
|
||||
# デバッグモード
|
||||
HAKO_VM_TRACE=1 ./target/release/hako --backend vm-hako test.hako
|
||||
```
|
||||
|
||||
**成果物**:
|
||||
- [ ] `src/backend/hakorune_vm_runner.rs` 実装
|
||||
- [ ] CLI統合完了
|
||||
- [ ] 環境変数対応
|
||||
- [ ] エラーメッセージ整備
|
||||
|
||||
### Week 6（2026-01-25 - 01-31）ドキュメント・Phase 20.6計画
|
||||
|
||||
**目標**: ドキュメント整備、次フェーズ計画
|
||||
|
||||
#### ドキュメント作成
|
||||
```
|
||||
selfhost/hakorune-vm/
|
||||
├── README.md # アーキテクチャ概要
|
||||
├── DESIGN.md # 設計パターン詳解
|
||||
├── TESTING.md # テスト戦略
|
||||
└── CHANGELOG.md # 実装履歴（Oct 5-13）
|
||||
|
||||
docs/guides/
|
||||
└── hakorune-vm-migration.md # ユーザー移行ガイド
|
||||
|
||||
docs/private/roadmap/phases/phase-20.5/
|
||||
├── HAKORUNE_VM_DISCOVERY.md # 発見レポート
|
||||
├── README.md # このファイル（更新済み）
|
||||
├── VALIDATION_REPORT.md # 検証レポート
|
||||
└── COMPLETION_REPORT.md # 完了報告
|
||||
|
||||
docs/private/roadmap/phases/phase-20.6/ (オプション)
|
||||
└── README.md # HostBridge計画（必要な場合）
|
||||
```
|
||||
|
||||
**成果物**:
|
||||
- [ ] 5個のドキュメント完成
|
||||
- [ ] Phase 20.5完了報告書
|
||||
- [ ] Phase 20.6計画書（オプション）
|
||||
- [ ] tomoakiさんへの報告
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Hakorune VM アーキテクチャ（既存実装）
|
||||
|
||||
### ファイル構成
|
||||
|
||||
```
|
||||
selfhost/hakorune-vm/ (3,413 lines, 44 files)
|
||||
├── hakorune_vm_core.hako (225 lines) # Entry point
|
||||
├── instruction_dispatcher.hako (72 lines) # @match dispatch
|
||||
├── blocks_locator.hako # Control flow
|
||||
├── error_builder.hako # Error messages
|
||||
├── args_guard.hako # Argument validation
|
||||
├── json_normalize_box.hako # JSON processing
|
||||
│
|
||||
├── [22 handler files] # Instruction handlers:
|
||||
│ ├── barrier_handler.hako # GC barrier
|
||||
│ ├── binop_handler.hako # Binary operations
|
||||
│ ├── boxcall_handler.hako # Box method calls
|
||||
│ ├── closure_call_handler.hako # Closure invocation
|
||||
│ ├── compare_handler.hako # Comparisons
|
||||
│ ├── const_handler.hako # Constants
|
||||
│ ├── constructor_call_handler.hako # Constructor calls
|
||||
│ ├── copy_handler.hako # Copy operation
|
||||
│ ├── extern_call_handler.hako # External calls
|
||||
│ ├── global_call_handler.hako # Global functions
|
||||
│ ├── load_handler.hako # Memory load
|
||||
│ ├── method_call_handler.hako # Method calls
|
||||
│ ├── mircall_handler.hako # Unified MIR call
|
||||
│ ├── module_function_call_handler.hako # Module functions
|
||||
│ ├── newbox_handler.hako # Box creation
|
||||
│ ├── nop_handler.hako # No-op
|
||||
│ ├── phi_handler.hako # PHI nodes
|
||||
│ ├── safepoint_handler.hako # GC safepoint
|
||||
│ ├── store_handler.hako # Memory store
|
||||
│ ├── terminator_handler.hako # Control flow (jump/branch/ret)
|
||||
│ ├── typeop_handler.hako # Type operations
|
||||
│ └── unaryop_handler.hako # Unary operations
|
||||
│
|
||||
└── tests/ (26+ files) # Comprehensive tests
|
||||
├── test_phase1_minimal.hako
|
||||
├── test_phase2_day4.hako
|
||||
├── test_boxcall.hako
|
||||
├── test_mircall_*.hako (5 files)
|
||||
├── test_mapbox_*.hako (3 files)
|
||||
└── ... (16 more)
|
||||
```
|
||||
|
||||
### 設計パターン
|
||||
|
||||
#### 1. @match-Based Dispatch
|
||||
```hakorune
|
||||
// instruction_dispatcher.hako
|
||||
dispatch(inst_json, regs, mem) {
|
||||
local op = extract_op(inst_json)
|
||||
|
||||
return match op {
|
||||
"const" => ConstHandlerBox.handle(inst_json, regs)
|
||||
"binop" => BinOpHandlerBox.handle(inst_json, regs)
|
||||
"compare" => CompareHandlerBox.handle(inst_json, regs)
|
||||
"load" => LoadHandlerBox.handle(inst_json, regs, mem)
|
||||
"store" => StoreHandlerBox.handle(inst_json, regs, mem)
|
||||
"mir_call" => MirCallHandlerBox.handle(inst_json, regs, mem)
|
||||
"boxcall" => BoxCallHandlerBox.handle(inst_json, regs)
|
||||
"newbox" => NewBoxHandlerBox.handle(inst_json, regs)
|
||||
"phi" => PhiHandlerBox.handle(inst_json, regs)
|
||||
"copy" => CopyHandlerBox.handle(inst_json, regs)
|
||||
"typeop" => TypeOpHandlerBox.handle(inst_json, regs, mem)
|
||||
"nop" => NopHandlerBox.handle(inst_json, regs, mem)
|
||||
"safepoint" => SafepointHandlerBox.handle(inst_json, regs, mem)
|
||||
"barrier" => BarrierHandlerBox.handle(inst_json, regs, mem)
|
||||
"jump" | "branch" | "ret" => TerminatorHandlerBox.handle(inst_json, regs)
|
||||
_ => Result.Err("Unsupported instruction: " + op)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**特徴**:
|
||||
- ✅ すべての命令を1箇所で管理
|
||||
- ✅ 新規命令の追加が容易
|
||||
- ✅ Fail-Fast（未知命令→即エラー）
|
||||
|
||||
#### 2. Result-Based Error Handling
|
||||
```hakorune
|
||||
// Every handler returns Result<Value>
|
||||
static box BinOpHandlerBox {
|
||||
handle(inst_json, regs) {
|
||||
// Validation
|
||||
local lhs_result = get_register(regs, lhs_id)
|
||||
if lhs_result.is_Err() {
|
||||
return Result.Err("BinOp: lhs register not found")
|
||||
}
|
||||
|
||||
// Compute
|
||||
local result = compute_binop(kind, lhs, rhs)
|
||||
if result.is_Err() {
|
||||
return result // Propagate error
|
||||
}
|
||||
|
||||
// Store result
|
||||
set_register(regs, dst, result.as_Ok())
|
||||
return Result.Ok(result.as_Ok())
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**特徴**:
|
||||
- ✅ 型安全なエラー処理
|
||||
- ✅ エラー伝播が明示的
|
||||
- ✅ Rustと同じパターン
|
||||
|
||||
#### 3. Block-Based Execution
|
||||
```hakorune
|
||||
// hakorune_vm_core.hako
|
||||
_execute_blocks(mir_json, regs, mem) {
|
||||
local current_block = "entry"
|
||||
|
||||
loop(current_block != null) {
|
||||
// Get block instructions
|
||||
local block = BlocksLocatorBox.locate(mir_json, current_block)
|
||||
if block.is_Err() { return block }
|
||||
|
||||
// Execute instructions
|
||||
local result = me._execute_block(block.as_Ok(), regs, mem)
|
||||
if result.is_Err() { return result }
|
||||
|
||||
// Update current block (from terminator)
|
||||
current_block = result.as_Ok()
|
||||
}
|
||||
|
||||
return Result.Ok(get_register(regs, "return_value"))
|
||||
}
|
||||
```
|
||||
|
||||
**特徴**:
|
||||
- ✅ MIR Block構造に忠実
|
||||
- ✅ Control flowが明示的
|
||||
- ✅ TerminatorでBlock遷移
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Phase 20.6以降（オプション）
|
||||
|
||||
### Option A: Pure Hakorune Path（推奨）
|
||||
|
||||
**前提**: Hakorune VM単体で完結
|
||||
|
||||
**Phase 20.6以降は不要**:
|
||||
- ✅ VM実装完了
|
||||
- ✅ すべての命令サポート済み
|
||||
- ✅ テストカバレッジ十分
|
||||
- ✅ CLI統合可能
|
||||
|
||||
**次のステップ**:
|
||||
1. Hakorune VMをデフォルトに
|
||||
2. Rust VMを `--backend vm-rust` (互換モード)
|
||||
3. パフォーマンス最適化
|
||||
|
||||
### Option B: HostBridge Path（必要な場合のみ）
|
||||
|
||||
**条件**: C-ABI境界が他の理由で必要
|
||||
|
||||
**Phase 20.6（8週間）**:
|
||||
- Week 1-4: HostBridge API実装
|
||||
- Week 5-6: Rust最小化（~100行）
|
||||
- Week 7-8: ドキュメント・検証
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ リスク & 対策（更新版）
|
||||
|
||||
### リスク1: Hakorune VM のバグ
|
||||
|
||||
**問題**: 既存実装に未発見のバグがある可能性
|
||||
|
||||
**影響**: MEDIUM（Golden Testで検出可能）
|
||||
|
||||
**対策**:
|
||||
- Golden Testで Rust-VM との一致を検証
|
||||
- エッジケーステスト拡充
|
||||
- ストレステスト実施
|
||||
- バグ発見時は即座に修正
|
||||
|
||||
### リスク2: パフォーマンス
|
||||
|
||||
**問題**: Hakorune VM が Rust VM より遅い可能性
|
||||
|
||||
**影響**: LOW（機能的には問題なし）
|
||||
|
||||
**対策**:
|
||||
- ベンチマーク測定
|
||||
- ボトルネック特定
|
||||
- 最適化は Phase 20.7以降
|
||||
- 「動作正しさ」が最優先
|
||||
|
||||
### リスク3: CLI統合の複雑性
|
||||
|
||||
**問題**: Rust VM経由で Hakorune VM を呼び出す必要
|
||||
|
||||
**影響**: LOW（標準的なパターン）
|
||||
|
||||
**対策**:
|
||||
- Rust VM の既存実行パスを再利用
|
||||
- Box loading機構を活用
|
||||
- エラーハンドリング整備
|
||||
|
||||
---
|
||||
|
||||
## 📚 関連リソース
|
||||
|
||||
### Phase 20.5ドキュメント
|
||||
- **[HAKORUNE_VM_DISCOVERY.md](HAKORUNE_VM_DISCOVERY.md)** ⭐ 重大発見レポート
|
||||
- **[STRATEGY_RECONCILIATION.md](STRATEGY_RECONCILIATION.md)** - 戦略変更の理由
|
||||
- **[PURE_HAKORUNE_ROADMAP.md](PURE_HAKORUNE_ROADMAP.md)** - 全体計画（更新予定）
|
||||
- [C_CODE_GENERATOR_DESIGN.md](C_CODE_GENERATOR_DESIGN.md) - ❌ 中止（参考用）
|
||||
|
||||
### Hakorune VM実装
|
||||
- **Location**: `selfhost/hakorune-vm/` (3,413 lines)
|
||||
- **Entry Point**: `hakorune_vm_core.hako`
|
||||
- **Dispatcher**: `instruction_dispatcher.hako`
|
||||
- **Tests**: `tests/*.hako` (26+ files)
|
||||
|
||||
### 前フェーズ
|
||||
- [Phase 15.77 - 凍結EXE確定](../phase-15.77/)
|
||||
- [Phase 15.76 - extern_c & Frozen Toolchain](../phase-15.76/)
|
||||
|
||||
---
|
||||
|
||||
## 💬 開発体制
|
||||
|
||||
### 実装担当
|
||||
- **tomoaki**: Hakorune VM実装完了 ✅（Oct 5-13, 2025）
|
||||
- **ChatGPT**: Golden Test設計・CLI統合支援
|
||||
- **Claude**: ドキュメント整備・検証スクリプト作成
|
||||
|
||||
### レビュー方針
|
||||
- Week 2, 4, 6終了時にレビュー
|
||||
- Golden Test すべて PASS が必須
|
||||
- バグ発見時は即座に修正
|
||||
|
||||
---
|
||||
|
||||
## 🎉 成功後の世界
|
||||
|
||||
### Phase 20.5完了後（6週間）:
|
||||
|
||||
1. **Hakorune VM検証完了**: 22ハンドラーすべて動作確認
|
||||
2. **Golden Testing完了**: Rust-VM vs Hako-VM 100%一致
|
||||
3. **CLI統合完了**: `--backend vm-hako` で実行可能
|
||||
4. **ドキュメント完備**: アーキテクチャ・移行ガイド
|
||||
5. **次フェーズ判断**: HostBridge必要性の決定
|
||||
|
||||
### Option A: Pure Hakorune Path（推奨）
|
||||
|
||||
6. **Hakorune VMデフォルト化**: `--backend vm` で Hakorune VM 使用
|
||||
7. **Rust VM互換モード化**: `--backend vm-rust` でRust VM（旧来）
|
||||
8. **完全自己ホスト達成**: Hakorune IS Hakorune ✅
|
||||
|
||||
### Option B: HostBridge Path（必要な場合）
|
||||
|
||||
6. **HostBridge API実装**: C-ABI境界確立
|
||||
7. **Rust最小化**: ~100行（C-ABI橋のみ）
|
||||
8. **Phase 20.7以降**: パフォーマンス最適化、GC改良
|
||||
|
||||
---
|
||||
|
||||
**作成日**: 2025-10-14
|
||||
**重大更新**: 2025-10-14（Hakorune VM発見による全面改訂）
|
||||
**Phase開始予定**: 2025-12-21（Phase 15.77完了後）
|
||||
**想定期間**: 6週間（36週間 → 6週間に短縮！）
|
||||
**戦略**: 検証・統合（実装ではなく）
|
||||
**成果**: Pure Hakorune VM 実現 ✅
|
||||
@ -0,0 +1,351 @@
|
||||
# Strategy Reconciliation — Phase 20.5 "Escape from Rust"
|
||||
|
||||
**Date**: 2025-10-14
|
||||
**Status**: APPROVED (Pure Hakorune Strategy)
|
||||
**Decision**: User preference: "純 Hakorune 大作戦" ✅
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Executive Summary
|
||||
|
||||
We had TWO competing strategies for Phase 20.5:
|
||||
|
||||
1. **Original Plan (Task Agent)**: C Code Generator approach - 10 weeks to bootstrap
|
||||
2. **ChatGPT Pro Proposal**: Pure Hakorune VM - 30+ weeks for complete realization
|
||||
|
||||
**Decision**: Adopt **Pure Hakorune Strategy** with phased implementation.
|
||||
|
||||
**Phase 20.5 (10 weeks)** will complete:
|
||||
- ✅ Phase A: HostBridge API (C-ABI boundary)
|
||||
- ✅ Phase B (start): VM foundations in Hakorune (`op_eq` migration, instruction dispatch PoC)
|
||||
|
||||
**Deferred to Phase 20.6+**:
|
||||
- ⏸️ Full VM core in Hakorune (Phase B complete)
|
||||
- ⏸️ Dispatch unification (Phase C)
|
||||
- ⏸️ Collections in Hakorune (Phase D)
|
||||
- ⏸️ GC v0 (Phase E)
|
||||
- ⏸️ Rust VM compat mode (Phase F)
|
||||
|
||||
**C Code Generator approach**: ❌ Discarded (not implemented)
|
||||
|
||||
---
|
||||
|
||||
## 📊 Side-by-Side Comparison
|
||||
|
||||
| Aspect | Original Plan (C Generator) | Pure Hakorune Strategy |
|
||||
|--------|----------------------------|------------------------|
|
||||
| **Timeline** | 10 weeks (Phase 20.5) | 30+ weeks (Phase 20.5-15.82) |
|
||||
| **Core Approach** | Generate C code from MIR | Implement VM itself in Hakorune |
|
||||
| **Rust Role** | Minimal (~200 lines) | Ultra-minimal (C-ABI bridge only) |
|
||||
| **Output** | `.c` files → EXE | VM runs MIR natively |
|
||||
| **Bootstrap Method** | v1 compiles v2 (via C code) | v1 VM runs v2 VM code |
|
||||
| **Complexity** | Medium (500 lines C emitter) | High (full VM in Hakorune) |
|
||||
| **Long-term Vision** | "Hakorune compiles Hakorune" | "Hakorune IS Hakorune" |
|
||||
| **Architecture** | Compiler-focused | VM-focused |
|
||||
| **Maintenance** | Two paths (Rust VM + C output) | Single path (Hakorune VM) |
|
||||
|
||||
---
|
||||
|
||||
## 💡 Why Pure Hakorune is Preferred
|
||||
|
||||
### Architectural Elegance
|
||||
|
||||
**C Generator Approach**:
|
||||
```
|
||||
Hakorune Source → [Rust Parser] → MIR JSON → [Hako C Gen] → C Code → [clang] → EXE
|
||||
↑ ↑
|
||||
Rust VM C compiler
|
||||
```
|
||||
|
||||
**Pure Hakorune Approach**:
|
||||
```
|
||||
Hakorune Source → [Hako Parser] → MIR JSON → [Hako VM] → Execution
|
||||
↑ ↑
|
||||
Everything in Hakorune Everything in Hakorune
|
||||
|
||||
Rust = Thin floor (C-ABI bridge only)
|
||||
```
|
||||
|
||||
**Result**: "Rust=floor, Hakorune=house" - Ultimate Box Theory realization
|
||||
|
||||
### Long-term Maintainability
|
||||
|
||||
**C Generator Issues**:
|
||||
- ❌ Two execution paths (Rust VM + compiled C)
|
||||
- ❌ C code generation adds complexity
|
||||
- ❌ C compiler dependency (clang/gcc)
|
||||
- ❌ Debugging split between Hakorune → C → EXE
|
||||
|
||||
**Pure Hakorune Benefits**:
|
||||
- ✅ Single execution path (Hakorune VM)
|
||||
- ✅ VM semantics defined once (in Hakorune)
|
||||
- ✅ No external compiler dependency (except Rust→Hakorune bridge)
|
||||
- ✅ Debugging entirely in Hakorune
|
||||
|
||||
### Reflects Past Learnings
|
||||
|
||||
**ChatGPT Pro's guidance incorporates fixes for**:
|
||||
1. **Equals/== recursion bug** (2025 issue):
|
||||
- Solution: `NoOperatorGuard` in `call_by_handle`
|
||||
- Pure Hakorune enforces this structurally
|
||||
|
||||
2. **Handle lifecycle complexity**:
|
||||
- Solution: Minimal C-ABI with `Retain/Release`
|
||||
- Pure Hakorune minimizes Rust↔Hakorune boundary
|
||||
|
||||
3. **Dispatch fragmentation**:
|
||||
- Solution: Single resolution path (`Resolver.lookup`)
|
||||
- Pure Hakorune unifies all dispatch
|
||||
|
||||
### Ultimate Box Theory
|
||||
|
||||
**C Generator**: Hakorune is a compiler *for* programs
|
||||
**Pure Hakorune**: Hakorune *is* the program (self-contained)
|
||||
|
||||
**Box Philosophy**:
|
||||
> Everything is Box, including the VM that runs Boxes.
|
||||
|
||||
Pure Hakorune realizes this fully.
|
||||
|
||||
---
|
||||
|
||||
## 🚧 What Gets Deferred to Phase 20.6+
|
||||
|
||||
### Phase 20.5 (10 weeks) Scope
|
||||
|
||||
**✅ CAN COMPLETE**:
|
||||
1. **HostBridge API** (Week 1-4):
|
||||
- Minimal C-ABI surface (`Hako_RunScriptUtf8`, `Retain/Release`, etc.)
|
||||
- Ubuntu/Windows ABI tests
|
||||
- Error handling (TLS `Hako_LastError`)
|
||||
|
||||
2. **`op_eq` Migration** (Week 5-6):
|
||||
- Move equality logic from Rust to Hakorune
|
||||
- Implement `NoOperatorGuard` (prevent recursion)
|
||||
- Golden tests: Rust-VM vs Hako-VM parity
|
||||
|
||||
3. **VM Foundations PoC** (Week 7-8):
|
||||
- Instruction dispatch skeleton (5 instructions: const, binop, compare, jump, ret)
|
||||
- MIR execution loop in Hakorune
|
||||
- Integration test: Run simple programs
|
||||
|
||||
4. **Documentation** (Week 9-10):
|
||||
- HostBridge API spec
|
||||
- Op_eq migration guide
|
||||
- Pure Hakorune roadmap
|
||||
- Phase 20.6 planning
|
||||
|
||||
**❌ CANNOT COMPLETE** (deferred):
|
||||
- Full VM core (all 16 instructions) → **Phase 20.6**
|
||||
- Dispatch unification (Resolver-based) → **Phase 20.6**
|
||||
- Collections in Hakorune (MapBox/ArrayBox) → **Phase 20.7**
|
||||
- GC v0 (mark&sweep) → **Phase 20.8**
|
||||
- Rust VM deprecation → **Phase 20.8**
|
||||
|
||||
### Phase 20.6-15.82 Roadmap
|
||||
|
||||
**Phase 20.6** (12 weeks): VM Core Complete
|
||||
- Phase B: All 16 MIR instructions in Hakorune
|
||||
- Phase C: Dispatch unification (`Resolver.lookup` everywhere)
|
||||
- Golden tests: 100% Rust-VM parity
|
||||
|
||||
**Phase 20.7** (8 weeks): Collections in Hakorune
|
||||
- Phase D: MapBox/ArrayBox implementation
|
||||
- Deterministic hash/eq
|
||||
- Key normalization (Symbol/Int/String)
|
||||
|
||||
**Phase 20.8** (6 weeks): GC + Rust Deprecation
|
||||
- Phase E: GC v0 (Stop-the-world mark&sweep)
|
||||
- Phase F: Rust VM becomes `--backend vm-rust` (compat mode)
|
||||
- Hakorune-VM is default
|
||||
|
||||
**Total**: 36 weeks (Phase 20.5 → 15.82)
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Risk Assessment
|
||||
|
||||
### Longer Timeline Risk
|
||||
|
||||
**Risk**: 36 weeks vs original 10 weeks
|
||||
**Impact**: HIGH (delayed complete self-hosting)
|
||||
**Mitigation**:
|
||||
- Phase 20.5 delivers **tangible value** (HostBridge, `op_eq`, VM PoC)
|
||||
- Each phase is independently useful
|
||||
- Can pause/reprioritize after each phase
|
||||
- Progressive derisking (start with easy parts)
|
||||
|
||||
### Higher Complexity Risk
|
||||
|
||||
**Risk**: Implementing VM in Hakorune is harder than C generator
|
||||
**Impact**: MEDIUM (more implementation effort)
|
||||
**Mitigation**:
|
||||
- Existing Rust VM as reference implementation
|
||||
- Golden tests ensure parity (catch bugs early)
|
||||
- Incremental approach (5 instructions → 16 instructions)
|
||||
- ChatGPT/Claude collaboration for complex parts
|
||||
|
||||
### Rust VM Maintenance Risk
|
||||
|
||||
**Risk**: Must maintain both Rust VM and Hakorune VM during transition
|
||||
**Impact**: MEDIUM (dual maintenance burden)
|
||||
**Mitigation**:
|
||||
- Rust VM frozen after Phase 20.5 (no new features)
|
||||
- Hakorune VM is where new work happens
|
||||
- Clear deprecation timeline (Phase 20.8)
|
||||
- Golden tests prevent divergence
|
||||
|
||||
### C-ABI Stability Risk
|
||||
|
||||
**Risk**: HostBridge API might need changes during implementation
|
||||
**Impact**: LOW (well-understood boundary)
|
||||
**Mitigation**:
|
||||
- Minimal API surface (5 functions)
|
||||
- Inspired by proven designs (Lua, Python C API)
|
||||
- Version function (`Hako_ApiVersion()`)
|
||||
- Comprehensive ABI tests (Ubuntu/Windows)
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Fallback Strategies
|
||||
|
||||
### If Pure Hakorune Takes Too Long
|
||||
|
||||
**Option 1**: Pause and ship Phase 20.5 deliverables
|
||||
- HostBridge API is valuable independently
|
||||
- `op_eq` in Hakorune improves correctness
|
||||
- VM PoC demonstrates feasibility
|
||||
- Resume Phase 20.6 later
|
||||
|
||||
**Option 2**: Hybrid approach (short-term)
|
||||
- Keep Rust VM as primary
|
||||
- Hakorune VM as experimental (`--backend vm-hako`)
|
||||
- Gradually expand Hakorune VM coverage
|
||||
- No hard deadline for full transition
|
||||
|
||||
**Option 3**: Revert to C Generator (if absolutely necessary)
|
||||
- Original plan documents preserved
|
||||
- C Generator design doc complete
|
||||
- Can pivot in Phase 20.6 if needed
|
||||
|
||||
### If HostBridge API Has Issues
|
||||
|
||||
**Problem**: C-ABI doesn't work on Windows/Ubuntu
|
||||
**Fallback**:
|
||||
- Simplify API (fewer functions)
|
||||
- Use more conservative types (no TLS, explicit context)
|
||||
- Add compatibility shims per platform
|
||||
|
||||
### If `op_eq` Migration Fails
|
||||
|
||||
**Problem**: Hakorune-side equality doesn't match Rust behavior
|
||||
**Fallback**:
|
||||
- Keep Rust `op_eq` as reference
|
||||
- Hakorune `op_eq` as opt-in (`HAKO_USE_PURE_EQ=1`)
|
||||
- Golden tests identify discrepancies
|
||||
- Fix incrementally
|
||||
|
||||
---
|
||||
|
||||
## 📋 Confidence Assessment
|
||||
|
||||
### High Confidence (80%+)
|
||||
|
||||
- ✅ **HostBridge API**: Well-understood, similar to Lua/Python C API
|
||||
- ✅ **`op_eq` Migration**: Clear algorithm, golden tests available
|
||||
- ✅ **VM PoC**: Rust VM as reference, only 5 instructions needed
|
||||
|
||||
### Medium Confidence (60-80%)
|
||||
|
||||
- ⚠️ **Full VM Core** (Phase 20.6): 16 instructions is more work
|
||||
- ⚠️ **Dispatch Unification**: Requires careful refactoring
|
||||
- ⚠️ **Collections**: MapBox/ArrayBox have subtle semantics
|
||||
|
||||
### Lower Confidence (40-60%)
|
||||
|
||||
- ⚠️ **GC v0**: Garbage collection is inherently complex
|
||||
- ⚠️ **Rust VM Deprecation**: Requires full parity, no gaps
|
||||
|
||||
### Overall Confidence: **70%** (MEDIUM-HIGH)
|
||||
|
||||
**Reasoning**:
|
||||
- Phase 20.5 deliverables are achievable (high confidence)
|
||||
- Phase 20.6+ depends on learnings from 20.5 (medium confidence)
|
||||
- Fallback options exist if needed (risk mitigation)
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Why This is Worth It
|
||||
|
||||
### Short-term (Phase 20.5)
|
||||
|
||||
1. **HostBridge API**: Clean boundary between Rust and Hakorune
|
||||
2. **`op_eq` in Hakorune**: Fixes recursion bugs, improves correctness
|
||||
3. **VM PoC**: Demonstrates feasibility of Pure Hakorune vision
|
||||
|
||||
### Medium-term (Phase 20.6-15.81)
|
||||
|
||||
4. **VM Core Complete**: Hakorune can run itself
|
||||
5. **Collections in Hakorune**: Everything is Box (truly)
|
||||
6. **Single Codebase**: All semantics defined once (in Hakorune)
|
||||
|
||||
### Long-term (Phase 20.8+)
|
||||
|
||||
7. **Rust Minimal**: Only C-ABI bridge (~100 lines)
|
||||
8. **True Self-Hosting**: Hakorune IS Hakorune (not just compiles)
|
||||
9. **Ultimate Box Theory**: Realized in its purest form
|
||||
|
||||
---
|
||||
|
||||
## 📚 Document Evolution
|
||||
|
||||
### Original Documents (Preserved)
|
||||
|
||||
- `/phase-20.5/README.md` (original plan) → **UPDATED**
|
||||
- `/phase-20.5/MILESTONE.md` (original milestones) → **UPDATED**
|
||||
- `/phase-20.5/C_CODE_GENERATOR_DESIGN.md` → **ARCHIVED** (not implemented)
|
||||
- `/phase-20.5/BOOTSTRAP_CHAIN_ANALYSIS.md` → **UPDATED** (Pure Hakorune approach added)
|
||||
|
||||
### New Documents (This Reconciliation)
|
||||
|
||||
- `/phase-20.5/STRATEGY_RECONCILIATION.md` → **THIS FILE**
|
||||
- `/phase-20.5/HOSTBRIDGE_API_DESIGN.md` → **NEW** (C-ABI spec)
|
||||
- `/phase-20.5/PURE_HAKORUNE_ROADMAP.md` → **NEW** (Phase 20.5-15.82 plan)
|
||||
- `/phase-20.5/OP_EQ_MIGRATION.md` → **NEW** (equality implementation guide)
|
||||
|
||||
### Updated Documents
|
||||
|
||||
- `/phase-20.5/README.md`: Removed C Generator, added HostBridge/op_eq
|
||||
- `/phase-20.5/MILESTONE.md`: Week-by-week plan updated
|
||||
- `/phase-20.5/BOOTSTRAP_CHAIN_ANALYSIS.md`: Pure Hakorune approach added
|
||||
|
||||
---
|
||||
|
||||
## 🎤 Final Recommendation
|
||||
|
||||
**Adopt Pure Hakorune Strategy** for the following reasons:
|
||||
|
||||
1. **Architectural elegance**: "Rust=floor, Hakorune=house"
|
||||
2. **Long-term maintainability**: Single execution path
|
||||
3. **Reflects learnings**: Incorporates past bug fixes
|
||||
4. **Ultimate Box Theory**: Realizes core philosophy
|
||||
5. **User preference**: tomoaki chose "純 Hakorune 大作戦" ✅
|
||||
|
||||
**Accept longer timeline** (36 weeks) for:
|
||||
- Clean architecture
|
||||
- Minimal technical debt
|
||||
- Future-proof foundation
|
||||
|
||||
**Phase 20.5 (10 weeks)** delivers:
|
||||
- HostBridge API (C-ABI boundary)
|
||||
- `op_eq` in Hakorune (correctness improvement)
|
||||
- VM PoC (feasibility demonstration)
|
||||
|
||||
**Next phases** (15.80-15.82) complete the vision.
|
||||
|
||||
---
|
||||
|
||||
**Status**: APPROVED
|
||||
**Decision Maker**: tomoaki
|
||||
**Implementation**: ChatGPT (lead), Claude (review)
|
||||
**Timeline**: 2025-12-21 → 2026-09-30 (Phase 20.5-15.82)
|
||||
Reference in New Issue
Block a user