docs: restore docs/private/roadmap from 7b4908f9 (Phase 20.31)
This commit is contained in:
nyash-codex
565
docs/private/roadmap/phases/phase-20.6/CHECKLIST.md
Normal file
565
docs/private/roadmap/phases/phase-20.6/CHECKLIST.md
Normal file
@ -0,0 +1,565 @@
|
||||
# Phase 20.6 — Checklist
|
||||
|
||||
**Status**: Planning
|
||||
**Duration**: 12 weeks (2026-03-01 → 2026-05-24)
|
||||
|
||||
---
|
||||
|
||||
## 進捗スナップショット（2025‑10 反映）
|
||||
|
||||
済（実装/統合）
|
||||
- [x] MirCall 正規化（Callee=Method/ModuleFunction/Extern/Constructor）
|
||||
- [x] NewBox→Constructor 既定ON（Builder/Optimizer 統一）
|
||||
- [x] Static Box “me” 注入を Rewrite へ移設 + Verifier で違反 Fail‑Fast
|
||||
- [x] LoopForm（quick 既定ON／PHI 安定）
|
||||
- [x] Boot/Lock（Zero‑Box Boot）: `--frozen`/`--lock`/`--lock-verify`/`--lock-diff`
|
||||
- [x] PluginLoader v2: BootPlan 優先で探索撤退（TOML I/O 抑止）
|
||||
- [x] Lock Diff: libraries/plugins/order と先頭不一致/位置ズレ表示
|
||||
- [x] ValueIdAllocator 常時ON（ValueIdGenerator 撤退）
|
||||
- [x] スモーク刷新（quick/integration）: 旧仕様/プラグイン依存スモークを opsサマリ or Hako最小コードへ置換し、全緑化
|
||||
|
||||
残（20.6 範囲：設計/文書中心・挙動不変）
|
||||
- [ ] memory ops（load/store/copy）最終仕様と Golden 設計
|
||||
- [ ] typeop（cast/check）最終仕様と Verifier 規約の整合
|
||||
- [ ] unaryop（not/neg）表記の確定（Mir JSON v1 への反映）
|
||||
- [ ] PublishedKnown と `/arity` 規約の明記（Builder/VM の使い分け）
|
||||
- [ ] Box Eq/Ne 統一経路（Enum.equals / nyrt.ops.op_eq）の記述強化
|
||||
- [ ] Boot/Lock 運用 CLI 例を PLAN/INDEX にも併記
|
||||
|
||||
---
|
||||
|
||||
## Phase B Complete: VM Core (Week 1-6)
|
||||
|
||||
### Week 1-2: Memory Operations (2026-03-01 - 03-14)
|
||||
|
||||
#### Implementation
|
||||
|
||||
- [ ] Design memory operation handlers
|
||||
- [ ] Implement `load_handler.hako`
|
||||
- [ ] Load value from memory
|
||||
- [ ] Handle invalid memory addresses
|
||||
- [ ] Result-based error handling
|
||||
- [ ] Implement `store_handler.hako`
|
||||
- [ ] Store value to memory
|
||||
- [ ] Handle memory overflow
|
||||
- [ ] Result-based error handling
|
||||
- [ ] Implement `copy_handler.hako`
|
||||
- [ ] Copy value between registers
|
||||
- [ ] Handle invalid register IDs
|
||||
- [ ] Result-based error handling
|
||||
|
||||
#### Testing
|
||||
|
||||
- [ ] Create test suite: `tests/golden/phase-b/memory/`
|
||||
- [ ] `test_load_basic.hako` - Basic load operation
|
||||
- [ ] `test_store_basic.hako` - Basic store operation
|
||||
- [ ] `test_copy_basic.hako` - Basic copy operation
|
||||
- [ ] `test_load_invalid_address.hako` - Error handling
|
||||
- [ ] `test_store_overflow.hako` - Error handling
|
||||
- [ ] `test_memory_aliasing.hako` - Multiple references
|
||||
- [ ] `test_load_store_cycle.hako` - Load after store
|
||||
- [ ] `test_copy_chain.hako` - Multiple copies
|
||||
- [ ] `test_memory_edge_cases.hako` - Edge cases
|
||||
- [ ] `test_memory_stress.hako` - Stress test
|
||||
|
||||
#### Integration
|
||||
|
||||
- [ ] Update instruction dispatcher to handle new ops
|
||||
- [ ] Run Golden Tests for memory operations
|
||||
- [ ] Measure performance vs Rust-VM
|
||||
- [ ] Document memory operation design
|
||||
|
||||
---
|
||||
|
||||
### Week 3-4: Unified Call (MirCall) (2026-03-15 - 03-28)
|
||||
|
||||
#### Implementation
|
||||
|
||||
- [ ] Design unified MirCall handler
|
||||
- [ ] Implement `mir_call_handler.hako`（単一エントリ）
|
||||
- [ ] Callee::Method（受領者付き）
|
||||
- [ ] Callee::ModuleFunction("Box.method/arity")
|
||||
- [ ] Callee::Extern("iface.method")
|
||||
- [ ] Callee::Constructor{box_type}
|
||||
- [ ] Result-based error handling / Effect tracking
|
||||
|
||||
#### Testing
|
||||
|
||||
- [ ] Create test suite: `tests/golden/phase-b/calls/`
|
||||
- [ ] `test_method_call.hako` - Method
|
||||
- [ ] `test_module_function_call.hako` - Module function
|
||||
- [ ] `test_closure_call_basic.hako` - Basic closure
|
||||
- [ ] `test_closure_call_capture.hako` - Closure with capture
|
||||
- [ ] `test_extern_call_time.hako` - External call (time)
|
||||
- [ ] `test_extern_call_array_size.hako` - External call (array.size)
|
||||
- [ ] `test_constructor_call.hako` - Constructor callee
|
||||
- [ ] `test_call_recursion.hako` - Recursive call
|
||||
- [ ] `test_call_nested.hako` - Nested calls
|
||||
- [ ] `test_call_with_complex_args.hako` - Complex arguments
|
||||
- [ ] `test_call_error_handling.hako` - Error propagation
|
||||
- [ ] `test_mircall_all_variants.hako` - All MirCall variants
|
||||
|
||||
#### Integration
|
||||
|
||||
- [ ] Update instruction dispatcher to handle call ops
|
||||
- [ ] Run Golden Tests for call operations
|
||||
- [ ] Measure call performance vs Rust-VM
|
||||
- [ ] Document MirCall unification design
|
||||
|
||||
---
|
||||
|
||||
### Week 5: Type Operations (2026-03-29 - 04-04)
|
||||
|
||||
#### Implementation
|
||||
|
||||
- [ ] Design type operation handlers
|
||||
- [ ] Implement `typeop_handler.hako`
|
||||
- [ ] Type checking (is_a?)
|
||||
- [ ] Type casting (as)
|
||||
- [ ] Type comparison
|
||||
- [ ] Result-based error handling
|
||||
（Box creation は MirCall::Constructor に統一）
|
||||
|
||||
#### Testing
|
||||
|
||||
- [ ] Create test suite: `tests/golden/phase-b/types/`
|
||||
- [ ] `test_typeop_check.hako` - Type checking
|
||||
- [ ] `test_typeop_cast.hako` - Type casting
|
||||
- [ ] `test_typeop_compare.hako` - Type comparison
|
||||
- [ ] `test_typeop_invalid.hako` - Invalid type operation
|
||||
- [ ] `test_constructor_basic.hako` - Constructor callee
|
||||
- [ ] `test_constructor_birth_lifecycle.hako` - Birth method call
|
||||
- [ ] `test_type_operations_stress.hako` - Stress test
|
||||
|
||||
#### Integration
|
||||
|
||||
- [ ] Update instruction dispatcher to handle type ops
|
||||
- [ ] Run Golden Tests for type operations
|
||||
- [ ] Measure type operation performance
|
||||
- [ ] Document type system design
|
||||
|
||||
---
|
||||
|
||||
### Week 6: Control Optimizations + Golden Tests (2026-04-05 - 04-11)
|
||||
|
||||
#### Implementation
|
||||
|
||||
- [ ] Implement `barrier_handler.hako`
|
||||
- [ ] GC barrier semantics
|
||||
- [ ] Memory ordering
|
||||
- [ ] Implement `safepoint_handler.hako`
|
||||
- [ ] GC safepoint semantics
|
||||
- [ ] Stack scanning preparation
|
||||
- [ ] Implement `loopform_handler.hako`
|
||||
- [ ] Loop detection hint
|
||||
- [ ] Optimization metadata
|
||||
- [ ] Implement `unaryop_handler.hako`
|
||||
- [ ] Unary negation
|
||||
- [ ] Logical NOT
|
||||
- [ ] Result-based error handling
|
||||
|
||||
#### Golden Test Suite (100+ tests)
|
||||
|
||||
##### Arithmetic (10 tests)
|
||||
- [ ] `test_arithmetic_add.hako`
|
||||
- [ ] `test_arithmetic_sub.hako`
|
||||
- [ ] `test_arithmetic_mul.hako`
|
||||
- [ ] `test_arithmetic_div.hako`
|
||||
- [ ] `test_arithmetic_mod.hako`
|
||||
- [ ] `test_arithmetic_overflow.hako`
|
||||
- [ ] `test_arithmetic_underflow.hako`
|
||||
- [ ] `test_arithmetic_divide_by_zero.hako`
|
||||
- [ ] `test_arithmetic_complex.hako`
|
||||
- [ ] `test_arithmetic_stress.hako`
|
||||
|
||||
##### Control Flow (10 tests)
|
||||
- [ ] `test_control_if_else.hako`
|
||||
- [ ] `test_control_loop.hako`
|
||||
- [ ] `test_control_nested_loop.hako`
|
||||
- [ ] `test_control_branch.hako`
|
||||
- [ ] `test_control_jump.hako`
|
||||
- [ ] `test_control_phi_simple.hako`
|
||||
- [ ] `test_control_phi_complex.hako`
|
||||
- [ ] `test_control_early_return.hako`
|
||||
- [ ] `test_control_break_continue.hako`
|
||||
- [ ] `test_control_stress.hako`
|
||||
|
||||
##### Collections (10 tests)
|
||||
- [ ] `test_collections_array_ops.hako`
|
||||
- [ ] `test_collections_map_ops.hako`
|
||||
- [ ] `test_collections_array_iteration.hako`
|
||||
- [ ] `test_collections_map_iteration.hako`
|
||||
- [ ] `test_collections_nested_arrays.hako`
|
||||
- [ ] `test_collections_nested_maps.hako`
|
||||
- [ ] `test_collections_mixed.hako`
|
||||
- [ ] `test_collections_large_array.hako`
|
||||
- [ ] `test_collections_large_map.hako`
|
||||
- [ ] `test_collections_stress.hako`
|
||||
|
||||
##### Recursion (5 tests)
|
||||
- [ ] `test_recursion_factorial.hako`
|
||||
- [ ] `test_recursion_fibonacci.hako`
|
||||
- [ ] `test_recursion_ackermann.hako`
|
||||
- [ ] `test_recursion_mutual.hako`
|
||||
- [ ] `test_recursion_deep.hako`
|
||||
|
||||
##### Closures (5 tests)
|
||||
- [ ] `test_closures_capture.hako`
|
||||
- [ ] `test_closures_nested.hako`
|
||||
- [ ] `test_closures_multiple_capture.hako`
|
||||
- [ ] `test_closures_return_closure.hako`
|
||||
- [ ] `test_closures_closure_chain.hako`
|
||||
|
||||
##### Strings (10 tests)
|
||||
- [ ] `test_strings_concat.hako`
|
||||
- [ ] `test_strings_substring.hako`
|
||||
- [ ] `test_strings_length.hako`
|
||||
- [ ] `test_strings_compare.hako`
|
||||
- [ ] `test_strings_empty.hako`
|
||||
- [ ] `test_strings_unicode.hako`
|
||||
- [ ] `test_strings_escape.hako`
|
||||
- [ ] `test_strings_long.hako`
|
||||
- [ ] `test_strings_interpolation.hako`
|
||||
- [ ] `test_strings_stress.hako`
|
||||
|
||||
##### Types (10 tests)
|
||||
- [ ] `test_types_check.hako`
|
||||
- [ ] `test_types_cast.hako`
|
||||
- [ ] `test_types_newbox.hako`
|
||||
- [ ] `test_types_inheritance.hako`
|
||||
- [ ] `test_types_polymorphism.hako`
|
||||
- [ ] `test_types_interface.hako`
|
||||
- [ ] `test_types_null_handling.hako`
|
||||
- [ ] `test_types_error_propagation.hako`
|
||||
- [ ] `test_types_complex.hako`
|
||||
- [ ] `test_types_stress.hako`
|
||||
|
||||
##### Memory (10 tests)
|
||||
- [ ] `test_memory_load.hako`
|
||||
- [ ] `test_memory_store.hako`
|
||||
- [ ] `test_memory_copy.hako`
|
||||
- [ ] `test_memory_aliasing.hako`
|
||||
- [ ] `test_memory_stack.hako`
|
||||
- [ ] `test_memory_heap.hako`
|
||||
- [ ] `test_memory_gc_barrier.hako`
|
||||
- [ ] `test_memory_gc_safepoint.hako`
|
||||
- [ ] `test_memory_leak_check.hako`
|
||||
- [ ] `test_memory_stress.hako`
|
||||
|
||||
##### Complex (30 tests)
|
||||
- [ ] `test_complex_mini_compiler.hako`
|
||||
- [ ] `test_complex_json_parser.hako`
|
||||
- [ ] `test_complex_expression_evaluator.hako`
|
||||
- [ ] `test_complex_state_machine.hako`
|
||||
- [ ] `test_complex_tree_traversal.hako`
|
||||
- [ ] `test_complex_graph_algorithm.hako`
|
||||
- [ ] `test_complex_sorting.hako`
|
||||
- [ ] `test_complex_searching.hako`
|
||||
- [ ] `test_complex_pattern_matching.hako`
|
||||
- [ ] `test_complex_regex.hako`
|
||||
- [ ] `test_complex_http_parser.hako`
|
||||
- [ ] `test_complex_csv_parser.hako`
|
||||
- [ ] `test_complex_xml_parser.hako`
|
||||
- [ ] `test_complex_markdown_parser.hako`
|
||||
- [ ] `test_complex_code_formatter.hako`
|
||||
- [ ] `test_complex_calculator.hako`
|
||||
- [ ] `test_complex_interpreter.hako`
|
||||
- [ ] `test_complex_vm_simulator.hako`
|
||||
- [ ] `test_complex_assembler.hako`
|
||||
- [ ] `test_complex_disassembler.hako`
|
||||
- [ ] `test_complex_profiler.hako`
|
||||
- [ ] `test_complex_debugger.hako`
|
||||
- [ ] `test_complex_optimizer.hako`
|
||||
- [ ] `test_complex_code_generator.hako`
|
||||
- [ ] `test_complex_type_checker.hako`
|
||||
- [ ] `test_complex_linter.hako`
|
||||
- [ ] `test_complex_test_framework.hako`
|
||||
- [ ] `test_complex_build_system.hako`
|
||||
- [ ] `test_complex_package_manager.hako`
|
||||
- [ ] `test_complex_stress_all.hako`
|
||||
|
||||
#### Performance Measurement
|
||||
|
||||
- [ ] Run all Golden Tests (100+)
|
||||
- [ ] Measure Hako-VM vs Rust-VM performance
|
||||
- [ ] Generate performance report
|
||||
- [ ] Verify: Hako-VM ≥ 50% of Rust-VM
|
||||
|
||||
#### Week 6 Deliverables
|
||||
|
||||
- [ ] All 16 MIR instructions implemented
|
||||
- [ ] 100+ Golden Tests ALL PASS
|
||||
- [ ] Performance report complete
|
||||
- [ ] Phase B completion report
|
||||
|
||||
---
|
||||
|
||||
## Phase C: Dispatch Unification (Week 7-12)
|
||||
|
||||
### Week 7-8: Resolver Integration (2026-04-12 - 04-25)
|
||||
|
||||
#### Design
|
||||
|
||||
- [ ] Finalize Resolver architecture
|
||||
- [ ] Design MethodHandle structure
|
||||
- [ ] Design type registry structure
|
||||
- [ ] Review with ChatGPT/Claude
|
||||
|
||||
#### Implementation
|
||||
|
||||
- [ ] Implement `resolver_box.hako`
|
||||
- [ ] `lookup(type_id, method, arity) -> MethodHandle`
|
||||
- [ ] Type registry initialization
|
||||
- [ ] Method registration API
|
||||
- [ ] Fail-Fast for unknown methods
|
||||
- [ ] Implement `method_handle_box.hako`
|
||||
- [ ] Handle storage (implementation + metadata)
|
||||
- [ ] Arity information
|
||||
- [ ] Type information
|
||||
- [ ] Implement `type_registry_box.hako`
|
||||
- [ ] Type registration
|
||||
- [ ] Method registry per type
|
||||
- [ ] Lookup optimization
|
||||
|
||||
#### Testing
|
||||
|
||||
- [ ] Create test suite: `tests/golden/phase-c/resolver/`
|
||||
- [ ] `test_resolver_lookup_success.hako` - Successful lookup
|
||||
- [ ] `test_resolver_lookup_failure.hako` - Fail-Fast behavior
|
||||
- [ ] `test_resolver_arity_mismatch.hako` - Arity check
|
||||
- [ ] `test_resolver_type_not_found.hako` - Unknown type
|
||||
- [ ] `test_resolver_method_not_found.hako` - Unknown method
|
||||
- [ ] `test_resolver_registration.hako` - Type registration
|
||||
- [ ] `test_resolver_override.hako` - Method override
|
||||
- [ ] `test_resolver_inheritance.hako` - Method inheritance
|
||||
- [ ] `test_resolver_multiple_types.hako` - Multiple types
|
||||
- [ ] `test_resolver_performance.hako` - Lookup performance
|
||||
- [ ] `test_resolver_edge_cases.hako` (10 tests) - Edge cases
|
||||
|
||||
#### Integration
|
||||
|
||||
- [ ] Integrate Resolver with call_handler
|
||||
- [ ] Run integration tests (20 tests)
|
||||
- [ ] Measure lookup performance
|
||||
- [ ] Document Resolver design
|
||||
|
||||
---
|
||||
|
||||
### Week 9-10: CallableBox Refactoring (2026-04-26 - 05-09)
|
||||
|
||||
#### Design
|
||||
|
||||
- [ ] Finalize CallableBox architecture
|
||||
- [ ] Design NoOperatorGuard mechanism
|
||||
- [ ] Design macro desugaring strategy
|
||||
- [ ] Review with ChatGPT/Claude
|
||||
|
||||
#### Implementation
|
||||
|
||||
- [ ] Implement `exec_box.hako`
|
||||
- [ ] `call_by_handle(handle, args, guard)`
|
||||
- [ ] Argument validation
|
||||
- [ ] NoOperatorGuard integration
|
||||
- [ ] Error handling
|
||||
- [ ] Implement `no_operator_guard_box.hako`
|
||||
- [ ] Guard activation/deactivation
|
||||
- [ ] Recursion prevention (for op_eq, etc.)
|
||||
- [ ] Thread-local state (if needed)
|
||||
- [ ] Implement macro desugaring (compiler side)
|
||||
- [ ] `arr.push(value)` → `Callable.ref_method(arr, :push, 1).call([value])`
|
||||
- [ ] Operator desugaring (e.g., `a + b` → `Callable.ref_operator(a, :+, 1).call([b])`)
|
||||
|
||||
#### Testing
|
||||
|
||||
- [ ] Create test suite: `tests/golden/phase-c/callable/`
|
||||
- [ ] `test_callable_call_by_handle.hako` - Basic call
|
||||
- [ ] `test_callable_no_operator_guard.hako` - Guard mechanism
|
||||
- [ ] `test_callable_recursion_prevention.hako` - Prevent re-entry
|
||||
- [ ] `test_callable_arity_validation.hako` - Arity check
|
||||
- [ ] `test_callable_error_propagation.hako` - Error handling
|
||||
- [ ] `test_macro_desugar_method.hako` - Method desugaring
|
||||
- [ ] `test_macro_desugar_operator.hako` - Operator desugaring
|
||||
- [ ] `test_macro_desugar_chain.hako` - Method chaining
|
||||
- [ ] `test_macro_desugar_nested.hako` - Nested calls
|
||||
- [ ] `test_callable_performance.hako` - Call performance
|
||||
- [ ] `test_callable_edge_cases.hako` (15 tests) - Edge cases
|
||||
|
||||
#### Integration
|
||||
|
||||
- [ ] Integrate ExecBox with Resolver
|
||||
- [ ] Update compiler for macro desugaring
|
||||
- [ ] Run integration tests (25 tests)
|
||||
- [ ] Measure call overhead
|
||||
- [ ] Document CallableBox design
|
||||
|
||||
---
|
||||
|
||||
### Week 11: Universal Route Minimization (2026-05-10 - 05-16)
|
||||
|
||||
#### Removal Tasks
|
||||
|
||||
- [ ] Identify all special-case dispatch code
|
||||
- [ ] Remove Global function special case
|
||||
- [ ] Remove Box method special case
|
||||
- [ ] Remove Closure special case
|
||||
- [ ] Remove Constructor special case
|
||||
- [ ] Remove Module function special case
|
||||
- [ ] Remove hardcoded method tables
|
||||
- [ ] Remove fallback implementations
|
||||
|
||||
#### Unification Tasks
|
||||
|
||||
- [ ] All calls go through Resolver.lookup
|
||||
- [ ] All invocations go through ExecBox.call_by_handle
|
||||
- [ ] Verify Fail-Fast for unknown methods
|
||||
- [ ] Verify no silent fallbacks
|
||||
|
||||
#### Testing
|
||||
|
||||
- [ ] Create test suite: `tests/golden/phase-c/unification/`
|
||||
- [ ] `test_unification_no_global_special_case.hako` - No special case
|
||||
- [ ] `test_unification_no_box_special_case.hako` - No special case
|
||||
- [ ] `test_unification_no_closure_special_case.hako` - No special case
|
||||
- [ ] `test_unification_no_constructor_special_case.hako` - No special case
|
||||
- [ ] `test_unification_no_module_special_case.hako` - No special case
|
||||
- [ ] `test_unification_fail_fast_unknown_method.hako` - Fail-Fast
|
||||
- [ ] `test_unification_fail_fast_wrong_arity.hako` - Fail-Fast
|
||||
- [ ] `test_unification_no_fallback.hako` - No fallback
|
||||
- [ ] `test_unification_all_paths.hako` (22 tests) - All code paths
|
||||
|
||||
#### Codebase Cleanup
|
||||
|
||||
- [ ] Remove unused code
|
||||
- [ ] Simplify control flow
|
||||
- [ ] Consolidate error handling
|
||||
- [ ] Update documentation
|
||||
|
||||
#### Integration
|
||||
|
||||
- [ ] Run all Golden Tests again (100+)
|
||||
- [ ] Verify no regressions
|
||||
- [ ] Measure performance (should be same or better)
|
||||
- [ ] Document route minimization
|
||||
|
||||
---
|
||||
|
||||
## C‑ABI Unification (design only in 20.6)
|
||||
|
||||
### Documents / Flags
|
||||
- [ ] Draft ABI header spec（hako_abi_v1: TypeId/Handle/Result/Dispatch/Allocator）
|
||||
- [ ] Two‑Layer Export policy（Stable ABI / Inlinable API）を docs に追加
|
||||
- [ ] env docs に flags を追記: `NYASH_ABI_BASIC_ON`, `NYASH_ABI_BUILTIN_LINK`
|
||||
- [ ] Build presets（default/embedded/research）を記載
|
||||
|
||||
### Verification
|
||||
- [ ] フラグOFFで quick/integration 緑（挙動不変）
|
||||
- [ ] CI は ABI フラグ非依存（導入のみ）
|
||||
|
||||
---
|
||||
|
||||
### Week 12: Integration + Documentation (2026-05-17 - 05-24)
|
||||
|
||||
#### Integration Testing
|
||||
|
||||
- [ ] Re-run all Golden Tests (155+ tests)
|
||||
- [ ] Phase B tests: 50 tests
|
||||
- [ ] Phase C tests: 75 tests
|
||||
- [ ] Integration tests: 30 tests
|
||||
- [ ] Verify 100% PASS rate
|
||||
- [ ] Run stress tests
|
||||
- [ ] Run regression tests
|
||||
|
||||
#### Performance Testing
|
||||
|
||||
- [ ] Run benchmark suite
|
||||
- [ ] Measure Hako-VM vs Rust-VM
|
||||
- [ ] Verify: Hako-VM ≥ 50% of Rust-VM
|
||||
- [ ] Generate performance report
|
||||
- [ ] Identify bottlenecks (for Phase 20.7)
|
||||
|
||||
#### Documentation
|
||||
|
||||
- [ ] **VM Core Complete Reference**
|
||||
- [ ] All 16 instructions documented
|
||||
- [ ] Control flow patterns
|
||||
- [ ] Memory model
|
||||
- [ ] Error handling
|
||||
- [ ] **Dispatch Unification Design Doc**
|
||||
- [ ] Resolver architecture
|
||||
- [ ] CallableBox design
|
||||
- [ ] NoOperatorGuard mechanism
|
||||
- [ ] Macro desugaring strategy
|
||||
- [ ] **Performance Report**
|
||||
- [ ] Benchmark results
|
||||
- [ ] Performance comparison
|
||||
- [ ] Bottleneck analysis
|
||||
- [ ] Optimization recommendations
|
||||
- [ ] **Phase 20.6 Completion Report**
|
||||
- [ ] Summary of achievements
|
||||
- [ ] Lessons learned
|
||||
- [ ] Known issues
|
||||
- [ ] Recommendations for Phase 20.7
|
||||
- [ ] **Phase 20.7 Planning Doc**
|
||||
- [ ] Collections in Hakorune
|
||||
- [ ] MapBox implementation plan
|
||||
- [ ] ArrayBox implementation plan
|
||||
- [ ] Deterministic behavior design
|
||||
|
||||
#### Code Review
|
||||
|
||||
- [ ] Self-review complete
|
||||
- [ ] ChatGPT review complete
|
||||
- [ ] Claude review complete
|
||||
- [ ] Address all review comments
|
||||
|
||||
#### CI Integration
|
||||
|
||||
- [ ] All Golden Tests passing in CI
|
||||
- [ ] Performance benchmarks in CI
|
||||
- [ ] Documentation builds in CI
|
||||
- [ ] Release notes prepared
|
||||
|
||||
---
|
||||
|
||||
## Summary Checklist
|
||||
|
||||
### Phase B Complete (Week 1-6)
|
||||
|
||||
- [ ] All 16 MIR instructions implemented
|
||||
- [ ] 50+ Golden Tests for Phase B
|
||||
- [ ] Performance: Hako-VM ≥ 50% of Rust-VM
|
||||
- [ ] Phase B completion report
|
||||
|
||||
### Phase C Complete (Week 7-12)
|
||||
|
||||
- [ ] Resolver.lookup implemented
|
||||
- [ ] ExecBox.call_by_handle implemented
|
||||
- [ ] Special-case dispatch removed
|
||||
- [ ] 75+ Golden Tests for Phase C
|
||||
- [ ] Phase C completion report
|
||||
|
||||
### Overall Phase 20.6
|
||||
|
||||
- [ ] 155+ Golden Tests ALL PASS
|
||||
- [ ] Dispatch unified (single path)
|
||||
- [ ] Performance verified (≥ 50%)
|
||||
- [ ] Documentation complete
|
||||
- [ ] Phase 20.7 planned
|
||||
- [ ] Phase 20.6 completion report submitted
|
||||
|
||||
### Completion (2025‑10)
|
||||
- Acceptance 達成:
|
||||
- quick/integration 緑（AOT canaries 含む）
|
||||
- Gate‑C Strict の代表負例が安定（診断文言固定）
|
||||
- 実施メモ:
|
||||
- quick: BlockBuilder/JsonEmit 依存の古いスモークを opsサマリ化（非プラグイン・純粋）。
|
||||
- integration: 自己ホストM2 parity を Hakoコード直書きのVM/LLVM 比較に刷新。
|
||||
- FFI‑C: devゲート（HAKO_FFI_C_STRICT）導入。既定は無効、検証時のみ厳格Fail‑Fastを確認。
|
||||
|
||||
---
|
||||
|
||||
**Created**: 2025-10-14
|
||||
**Last Updated**: 2025-10-14
|
||||
**Status**: Planning
|
||||
**Total Tasks**: 200+ checkboxes
|
||||
**All Uncompleted**: [ ] (ready for execution)
|
||||
464
docs/private/roadmap/phases/phase-20.6/INDEX.md
Normal file
464
docs/private/roadmap/phases/phase-20.6/INDEX.md
Normal file
@ -0,0 +1,464 @@
|
||||
# Phase 20.6 — Index
|
||||
|
||||
**VM Core Complete + Dispatch Unification**
|
||||
|
||||
Status: Planning
|
||||
Duration: 12 weeks (2026-03-01 - 2026-05-24)
|
||||
Prerequisite: Phase 20.5 complete
|
||||
|
||||
---
|
||||
|
||||
## 📚 Documentation Structure
|
||||
|
||||
### Core Documents
|
||||
|
||||
1. **[README.md](README.md)** ⭐ START HERE (日本語)
|
||||
- Phase overview and goals
|
||||
- Architecture overview (16 instructions + Dispatch)
|
||||
- Weekly breakdown (Week 1-12)
|
||||
- Success criteria and DoD
|
||||
- Risk mitigation
|
||||
|
||||
2. **[PLAN.md](PLAN.md)** (English)
|
||||
- Executive summary (5 lines)
|
||||
- Phase breakdown (Phase B + Phase C)
|
||||
- Week-by-week implementation plan
|
||||
- Golden Test strategy
|
||||
- CI integration
|
||||
|
||||
3. **[CHECKLIST.md](CHECKLIST.md)**
|
||||
- Week 1-6: VM Core Complete tasks
|
||||
- Week 7-12: Dispatch Unification tasks
|
||||
- Golden Test checklist (100+ tests)
|
||||
- Documentation checklist
|
||||
|
||||
4. **[COMPLETION_REPORT.md](COMPLETION_REPORT.md)** (Week 12 deliverable)
|
||||
- Phase 20.6 results
|
||||
- Performance measurements
|
||||
- Lessons learned
|
||||
- Phase 20.7 recommendations
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Quick Reference
|
||||
|
||||
### What is Phase 20.6? (5-line summary)
|
||||
|
||||
1. **Goal**: Complete Hakorune VM Core (16 MIR instructions) + Unify Dispatch (single Resolver path).
|
||||
2. **Strategy**: Phase B (Week 1-6) = All instructions; Phase C (Week 7-12) = Resolver integration.
|
||||
3. **Verification**: Golden Tests (100+ cases) ensure Rust-VM vs Hako-VM 100% output parity.
|
||||
4. **Performance**: Target ≥ 50% of Rust-VM speed (acceptable for PoC, optimize later).
|
||||
5. **Policy**: Fail-Fast (unknown methods → RuntimeError), no special-case dispatch, Everything is Box.
|
||||
|
||||
### Key Deliverables
|
||||
|
||||
**Phase B Complete (Week 1-6)**:
|
||||
1. **MIR Core + Unified Call (MirCall)** in Hakorune:
|
||||
- const, binop, compare, jump, branch, phi, ret ✅ (from 20.5)
|
||||
- MirCall(callee=Method|ModuleFunction|Extern|Constructor) ⬜ (Week 3-4)
|
||||
- load, store, copy, typeop ⬜ (Week 1-2, 5)
|
||||
- barrier, safepoint, loopform, unaryop ⬜ (Week 6)
|
||||
|
||||
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
|
||||
|
||||
---
|
||||
|
||||
## 📊 Timeline at a Glance
|
||||
|
||||
| Weeks | Focus | Deliverable |
|
||||
|-------|-------|-------------|
|
||||
| 1-2 | Memory Operations | load, store, copy working |
|
||||
| 3-4 | Unified Call | MirCall(callee=Method/Module/Extern/Constructor) working |
|
||||
| 5 | Type Operations | typeop working（newはConstructor経由） |
|
||||
| 6 | Control + Golden Tests | All 16 instructions + 100 tests PASS |
|
||||
| 7-8 | Resolver Integration | Resolver.lookup working |
|
||||
| 9-10 | CallableBox Refactoring | ExecBox.call_by_handle working |
|
||||
| 11 | Route Minimization | Special-case dispatch removed |
|
||||
| 12 | Integration + Docs | Phase complete, Phase 20.7 planned |
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Architecture Overview
|
||||
|
||||
### Phase B: MIR Core + Unified Call
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ Phase 20.5 Complete (5 instructions)│
|
||||
│ ✅ const, ret, jump, branch, phi │
|
||||
│ ✅ binop (Add/Sub/Mul/Div/Mod) │
|
||||
│ ✅ compare (Eq/Ne/Lt/Le/Gt/Ge) │
|
||||
├─────────────────────────────────────┤
|
||||
│ Phase 20.6 Additions (11 instructions)
|
||||
│ ⬜ load, store, copy (Week 1-2) │
|
||||
│ ⬜ MirCall (Week 3-4) │
|
||||
│ ⬜ typeop（newはConstructor） (Week 5)│
|
||||
│ ⬜ barrier, safepoint, loopform, │
|
||||
│ unaryop (Week 6) │
|
||||
└─────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Phase C: Dispatch Unification
|
||||
|
||||
```
|
||||
Before (multiple dispatch paths):
|
||||
┌────────────────────────────────────┐
|
||||
│ Method Call Dispatch │
|
||||
│ ├─ Global Function (special) │
|
||||
│ ├─ Box Method (special) │
|
||||
│ ├─ Closure (special) │
|
||||
│ ├─ Constructor (special) │
|
||||
│ └─ Module Function (special) │
|
||||
└────────────────────────────────────┘
|
||||
|
||||
After (single dispatch path):
|
||||
┌────────────────────────────────────┐
|
||||
│ Unified Resolver Path │
|
||||
│ │
|
||||
│ Resolver.lookup(type_id, method, arity)
|
||||
│ ↓ │
|
||||
│ MethodHandle │
|
||||
│ ↓ │
|
||||
│ ExecBox.call_by_handle( │
|
||||
│ handle, args, NoOperatorGuard)│
|
||||
└────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Test Strategy Overview
|
||||
|
||||
### Golden Test Pyramid
|
||||
|
||||
```
|
||||
/\
|
||||
/ \ Integration (30 tests)
|
||||
/____\ Complex scenarios
|
||||
/ \
|
||||
/ \ Functional (70 tests)
|
||||
/__________\ Individual instruction tests
|
||||
/ \
|
||||
/ \ Unit (per-handler)
|
||||
/________________\ Each handler has dedicated tests
|
||||
```
|
||||
|
||||
### Test Categories
|
||||
|
||||
1. **Memory Operations** (10 tests):
|
||||
- load, store, copy
|
||||
- Memory aliasing
|
||||
- Edge cases
|
||||
|
||||
2. **Method Calls** (15 tests):
|
||||
- call (Global/Module/Closure)
|
||||
- boxcall
|
||||
- externcall
|
||||
|
||||
3. **Type Operations** (10 tests):
|
||||
- typeop
|
||||
- newbox
|
||||
|
||||
4. **Control Flow** (15 tests):
|
||||
- barrier, safepoint, loopform
|
||||
- Branch/jump combinations
|
||||
|
||||
5. **Resolver** (20 tests):
|
||||
- lookup success/failure
|
||||
- Arity mismatches
|
||||
- Type not found
|
||||
|
||||
6. **Callable** (25 tests):
|
||||
- call_by_handle
|
||||
- NoOperatorGuard
|
||||
- Macro desugaring
|
||||
|
||||
7. **Integration** (30 tests):
|
||||
- Arithmetic
|
||||
- Control flow
|
||||
- Collections
|
||||
- Recursion
|
||||
- Closures
|
||||
- Strings
|
||||
|
||||
**Total**: 100+ Golden Tests
|
||||
|
||||
---
|
||||
|
||||
## 📦 Implementation Structure
|
||||
|
||||
```
|
||||
Phase 20.6 Planning:
|
||||
docs/private/roadmap/phases/phase-20.6/
|
||||
├── INDEX.md # ← You are here
|
||||
├── README.md # Phase overview (日本語)
|
||||
├── PLAN.md # Execution plan (English)
|
||||
├── CHECKLIST.md # Week-by-week checklist
|
||||
└── COMPLETION_REPORT.md # (Week 12 deliverable)
|
||||
|
||||
Hakorune VM Implementation:
|
||||
selfhost/hakorune-vm/
|
||||
├── handlers/ # Week 1-6 deliverables
|
||||
│ ├── load_handler.hako # Week 1-2
|
||||
│ ├── store_handler.hako # Week 1-2
|
||||
│ ├── copy_handler.hako # Week 1-2
|
||||
│ ├── call_handler.hako # Week 3-4 (Unified MirCall)
|
||||
│ ├── boxcall_handler.hako # Week 3-4
|
||||
│ ├── externcall_handler.hako # Week 3-4
|
||||
│ ├── typeop_handler.hako # Week 5
|
||||
│ ├── newbox_handler.hako # Week 5
|
||||
│ ├── barrier_handler.hako # Week 6
|
||||
│ ├── safepoint_handler.hako # Week 6
|
||||
│ ├── loopform_handler.hako # Week 6
|
||||
│ └── unaryop_handler.hako # Week 6
|
||||
├── resolver/ # Week 7-8 deliverables
|
||||
│ ├── resolver_box.hako
|
||||
│ ├── method_handle_box.hako
|
||||
│ └── type_registry_box.hako
|
||||
├── callable/ # Week 9-10 deliverables
|
||||
│ ├── exec_box.hako
|
||||
│ ├── no_operator_guard_box.hako
|
||||
│ └── macro_desugar.hako
|
||||
└── tests/ # Week 1-12
|
||||
├── golden/ # 100+ tests
|
||||
│ ├── phase-b/ # Week 1-6
|
||||
│ │ ├── memory/ # 10 tests
|
||||
│ │ ├── calls/ # 15 tests
|
||||
│ │ ├── types/ # 10 tests
|
||||
│ │ └── control/ # 15 tests
|
||||
│ ├── phase-c/ # Week 7-12
|
||||
│ │ ├── resolver/ # 20 tests
|
||||
│ │ ├── callable/ # 25 tests
|
||||
│ │ └── unification/ # 30 tests
|
||||
│ └── integration/ # Week 12
|
||||
│ ├── arithmetic.hako
|
||||
│ ├── control_flow.hako
|
||||
│ ├── collections.hako
|
||||
│ ├── recursion.hako
|
||||
│ ├── strings.hako
|
||||
│ └── closures.hako
|
||||
└── benchmark/ # Performance tests
|
||||
├── benchmark_suite.sh
|
||||
└── performance_report.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Quick Start (After Phase Complete)
|
||||
|
||||
### Run Golden Tests
|
||||
|
||||
```bash
|
||||
# Run all Golden Tests
|
||||
bash tools/golden_test_hakorune_vm.sh
|
||||
|
||||
# Expected output:
|
||||
# ✅ phase-b/memory: 10/10 PASS
|
||||
# ✅ phase-b/calls: 15/15 PASS
|
||||
# ✅ phase-b/types: 10/10 PASS
|
||||
# ✅ phase-b/control: 15/15 PASS
|
||||
# ✅ phase-c/resolver: 20/20 PASS
|
||||
# ✅ phase-c/callable: 25/25 PASS
|
||||
# ✅ phase-c/unification: 30/30 PASS
|
||||
# ✅ integration: 30/30 PASS
|
||||
# ────────────────────────────────────
|
||||
# Total: 155/155 PASS (100%)
|
||||
```
|
||||
|
||||
### Run Performance Benchmark
|
||||
|
||||
```bash
|
||||
# Benchmark Hako-VM vs Rust-VM
|
||||
bash tools/benchmark_hakorune_vm.sh
|
||||
|
||||
# Expected output:
|
||||
# Test: arithmetic.hako
|
||||
# Rust-VM: 1.2s
|
||||
# Hako-VM: 2.1s (57% speed) ✅
|
||||
#
|
||||
# Test: control_flow.hako
|
||||
# Rust-VM: 0.8s
|
||||
# Hako-VM: 1.5s (53% speed) ✅
|
||||
#
|
||||
# Average: Hako-VM = 55% of Rust-VM ✅
|
||||
# Memory: 180MB (< 200MB target) ✅
|
||||
```
|
||||
|
||||
### Use Unified Dispatch
|
||||
|
||||
```bash
|
||||
# Run program with unified dispatch
|
||||
./target/release/hako --backend vm program.hako
|
||||
|
||||
# Debug Resolver
|
||||
HAKO_RESOLVER_TRACE=1 ./target/release/hako --backend vm program.hako
|
||||
|
||||
# Output:
|
||||
# [resolver] lookup type_id=42 method="push" arity=1 → handle=0x123
|
||||
# [exec] call_by_handle handle=0x123 args=[value] → OK
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Prerequisites
|
||||
|
||||
### From Phase 20.5
|
||||
|
||||
- [x] HostBridge API complete
|
||||
- [x] op_eq Migration complete (NoOperatorGuard)
|
||||
- [x] VM Foundations PoC complete (5 instructions)
|
||||
- [x] Golden Test infrastructure ready
|
||||
|
||||
### For Phase 20.6
|
||||
|
||||
- [ ] Week 1: Memory operation design approved
|
||||
- [ ] Week 3: Method call design approved (Unified MirCall)
|
||||
- [ ] Week 7: Resolver design approved
|
||||
- [ ] Week 9: CallableBox design approved
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Success Criteria Summary
|
||||
|
||||
### Technical
|
||||
|
||||
- [ ] All 16 MIR instructions working
|
||||
- [ ] Control flow complete (branch, phi, loopform)
|
||||
- [ ] Golden Tests: 100+ cases ALL PASS
|
||||
- [ ] Dispatch unified (single Resolver path)
|
||||
- [ ] Special-case dispatch removed
|
||||
|
||||
### Performance
|
||||
|
||||
- [ ] Hako-VM ≥ 50% of Rust-VM speed ✅
|
||||
- [ ] Memory usage < 200MB ✅
|
||||
- [ ] Compile time < 10s (small programs) ✅
|
||||
|
||||
### Quality
|
||||
|
||||
- [ ] Test coverage: All instructions covered
|
||||
- [ ] Documentation: Complete architecture docs
|
||||
- [ ] Code review: ChatGPT + Claude approved
|
||||
- [ ] CI: All tests passing
|
||||
|
||||
---
|
||||
|
||||
## 📚 Related Phases
|
||||
|
||||
### Previous
|
||||
|
||||
- [Phase 20.5 - VM Foundations](../phase-20.5/)
|
||||
- HostBridge API
|
||||
- op_eq Migration
|
||||
- VM Foundations PoC (5 instructions)
|
||||
|
||||
### Next
|
||||
|
||||
- **Phase 20.7 - Collections in Hakorune** (8 weeks, 2026-05-25 → 2026-07-19)
|
||||
- MapBox in Hakorune
|
||||
- ArrayBox in Hakorune
|
||||
- Deterministic iteration order
|
||||
- Performance: ≥ 70% of Rust-Collections
|
||||
|
||||
### Parallel
|
||||
|
||||
- [Phase 15.78 - Frozen UX Polish](../phase-15.78/)
|
||||
- Distribution packaging
|
||||
- Doctor improvements
|
||||
|
||||
---
|
||||
|
||||
## 💬 Communication
|
||||
|
||||
### Weekly Sync Points
|
||||
|
||||
- **Monday**: Week start, goal setting
|
||||
- **Wednesday**: Mid-week progress check
|
||||
- **Friday**: Week review, performance measurement
|
||||
|
||||
### Issue Tracking
|
||||
|
||||
- Use GitHub issues with label `phase-20.6`
|
||||
- Prefix: `[20.6]` in commit messages
|
||||
- Milestone: `Phase 20.6 - VM Core Complete`
|
||||
|
||||
### Review Process
|
||||
|
||||
- Each week: Self-review + Golden Tests
|
||||
- Week 6, 12: Full review with ChatGPT/Claude
|
||||
- Blocking issues: Immediate escalation
|
||||
|
||||
---
|
||||
|
||||
## 🔗 External Resources
|
||||
|
||||
### Reference Implementations
|
||||
|
||||
- **Rust VM**: `/src/backend/mir_interpreter/` (reference implementation)
|
||||
- **MIR Spec**: [INSTRUCTION_SET.md](../../../../reference/mir/INSTRUCTION_SET.md)
|
||||
- **Phase 20.5 Roadmap**: [PURE_HAKORUNE_ROADMAP.md](../phase-20.5/PURE_HAKORUNE_ROADMAP.md)
|
||||
|
||||
### Related Documents
|
||||
|
||||
- [Hakorune VM Discovery](../phase-20.5/HAKORUNE_VM_DISCOVERY.md) - VM implementation analysis
|
||||
- [HostBridge API Design](../phase-20.5/HOSTBRIDGE_API_DESIGN.md) - C-ABI boundary
|
||||
- [Op_eq Migration](../phase-20.5/OP_EQ_MIGRATION.md) - NoOperatorGuard pattern
|
||||
|
||||
---
|
||||
|
||||
## 📝 Notes
|
||||
|
||||
### Naming Conventions
|
||||
|
||||
- **Phase B**: VM Core Complete (Week 1-6)
|
||||
- **Phase C**: Dispatch Unification (Week 7-12)
|
||||
- **Golden Tests**: Rust-VM vs Hako-VM parity tests
|
||||
- **Resolver**: Single resolution path for all method calls
|
||||
|
||||
### File Naming
|
||||
|
||||
- Handlers: `{instruction}_handler.hako`
|
||||
- Tests: `test_{feature}_{case}.hako`
|
||||
- Golden outputs: `{test}_rust.txt`, `{test}_hako.txt`
|
||||
|
||||
### Verification
|
||||
|
||||
- Use `diff` for exact output comparison
|
||||
- Use Golden Test script for automation
|
||||
- Use benchmark script for performance measurement
|
||||
|
||||
---
|
||||
|
||||
**Created**: 2025-10-14
|
||||
**Last Updated**: 2025-10-14
|
||||
**Status**: Planning (Phase not yet started)
|
||||
**Phase Start**: 2026-03-01
|
||||
**Phase End**: 2026-05-24
|
||||
**Next Review**: 2026-03-01 (Phase start)
|
||||
5. **ABI（design only）**
|
||||
- Phase 20.6 では C‑ABI の SSOT/ポリシー/フラグを追加（挙動は不変）
|
||||
- 実装切替（String/Array/Map）は Phase 20.7 で段階導入
|
||||
615
docs/private/roadmap/phases/phase-20.6/PLAN.md
Normal file
615
docs/private/roadmap/phases/phase-20.6/PLAN.md
Normal file
@ -0,0 +1,615 @@
|
||||
# Phase 20.6 — Execution Plan (VM Core Complete + Dispatch Unification)
|
||||
|
||||
**Status**: Planning
|
||||
**Duration**: 12 weeks (2026-03-01 → 2026-05-24)
|
||||
**Prerequisite**: Phase 20.5 complete (VM Foundations PoC + op_eq Migration)
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary (5 lines)
|
||||
|
||||
1. **Goal**: Complete Hakorune VM Core (16 MIR instructions) + Unify Dispatch (single Resolver path).
|
||||
2. **Strategy**: Phase B (Week 1-6) = All instructions; Phase C (Week 7-12) = Resolver integration.
|
||||
3. **Verification**: Golden Tests (100+ cases) ensure Rust-VM vs Hako-VM 100% output parity.
|
||||
4. **Performance**: Target ≥ 50% of Rust-VM speed (acceptable for PoC, optimize later).
|
||||
5. **Policy**: Fail-Fast (unknown methods → RuntimeError), no special-case dispatch, Everything is Box.
|
||||
|
||||
---
|
||||
|
||||
## Phase Breakdown
|
||||
|
||||
### Phase B Complete: VM Core (Week 1-6)
|
||||
|
||||
**Objective**: Implement MIR core ops and unify calls via MirCall in Hakorune.
|
||||
|
||||
#### Week 1-2: Memory Operations (2026-03-01 - 03-14)
|
||||
|
||||
**Instructions**:
|
||||
- `load`: Load value from memory
|
||||
- `store`: Store value to memory
|
||||
- `copy`: Copy value between registers
|
||||
|
||||
**Deliverables**:
|
||||
- [ ] `load_handler.hako` implementation
|
||||
- [ ] `store_handler.hako` implementation
|
||||
- [ ] `copy_handler.hako` implementation
|
||||
- [ ] 10 test cases (memory operations)
|
||||
|
||||
**Testing**:
|
||||
```bash
|
||||
# Memory operation tests
|
||||
tests/golden/phase-b/memory/
|
||||
├── test_load_store.hako
|
||||
├── test_copy_register.hako
|
||||
├── test_memory_aliasing.hako
|
||||
└── ... (7 more)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### Week 3-4: Unified Call (MirCall) (2026-03-15 - 03-28)
|
||||
|
||||
**Semantics**:
|
||||
- MirCall with typed Callee variants:
|
||||
- `Callee::Method`（受領者付きメソッド）
|
||||
- `Callee::ModuleFunction("Box.method/arity")`
|
||||
- `Callee::Extern("iface.method")`
|
||||
- `Callee::Constructor{box_type}`（new はここへ統一）
|
||||
|
||||
**Deliverables**:
|
||||
- [ ] `mir_call_handler.hako`（単一エントリ）実装
|
||||
- [ ] Callee::Method/ModuleFunction/Extern/Constructor 分岐
|
||||
- [ ] 受領者/引数の素材化（Fail‑Fast）
|
||||
- [ ] 15 テスト（MirCall：Method/Module/Extern/Constructor）
|
||||
|
||||
**Testing**:
|
||||
```bash
|
||||
# MirCall tests
|
||||
tests/golden/phase-b/calls/
|
||||
├── test_method_call.hako
|
||||
├── test_module_function.hako
|
||||
├── test_closure_call.hako
|
||||
├── test_extern_call.hako
|
||||
├── test_constructor_call.hako
|
||||
└── ... (10 more)
|
||||
```
|
||||
|
||||
**Key Design**:
|
||||
```hakorune
|
||||
// Unified MirCall handler (call instruction)
|
||||
static box MirCallHandlerBox {
|
||||
handle(inst_json, regs, mem) {
|
||||
local callee_type = extract_callee_type(inst_json)
|
||||
|
||||
return match callee_type {
|
||||
"Global" => me._handle_global(inst_json, regs)
|
||||
"ModuleFunction" => me._handle_module(inst_json, regs)
|
||||
"Closure" => me._handle_closure(inst_json, regs, mem)
|
||||
_ => Result.Err("Unknown callee type")
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### Week 5: Type Operations (2026-03-29 - 04-04)
|
||||
|
||||
**Instructions**:
|
||||
- `typeop`: Type conversion/checking
|
||||
（Box生成は MirCall::Constructor に統一し、ここでは扱わない）
|
||||
|
||||
**Deliverables**:
|
||||
- [ ] `typeop_handler.hako` implementation
|
||||
- [ ] 10 test cases (type operations)
|
||||
|
||||
**Testing**:
|
||||
```bash
|
||||
# Type operation tests
|
||||
tests/golden/phase-b/types/
|
||||
├── test_type_check.hako
|
||||
├── test_type_cast.hako
|
||||
└── ... (6 more)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### Week 6: Control Flow Optimizations + Golden Tests (2026-04-05 - 04-11)
|
||||
|
||||
**Instructions**:
|
||||
- `barrier`: GC barrier
|
||||
- `safepoint`: GC safepoint
|
||||
- `loopform`: Loop detection hint
|
||||
- `unaryop`: Unary operations
|
||||
|
||||
**Golden Test Suite** (100+ tests):
|
||||
```bash
|
||||
tests/golden/hakorune-vm/
|
||||
├── arithmetic/ # 10 tests (add, mul, div, mod, ...)
|
||||
├── control_flow/ # 10 tests (if, loop, branch, ...)
|
||||
├── collections/ # 10 tests (array, map operations)
|
||||
├── recursion/ # 5 tests (factorial, fibonacci, ...)
|
||||
├── closures/ # 5 tests (capture, nested, ...)
|
||||
├── strings/ # 10 tests (concat, substring, ...)
|
||||
├── types/ # 10 tests (type checks, casts)
|
||||
├── memory/ # 10 tests (load, store, aliasing)
|
||||
└── complex/ # 30 tests (integration scenarios)
|
||||
```
|
||||
|
||||
**Deliverables**:
|
||||
- [ ] Remaining instruction implementations
|
||||
- [ ] Golden Test Suite complete (100+ tests)
|
||||
- [ ] Performance measurement: Hako-VM ≥ 50% of Rust-VM
|
||||
|
||||
**Golden Test Execution**:
|
||||
```bash
|
||||
# Run Golden Tests
|
||||
bash tools/golden_test_hakorune_vm.sh
|
||||
|
||||
# Expected output:
|
||||
# ✅ arithmetic: 10/10 PASS
|
||||
# ✅ control_flow: 10/10 PASS
|
||||
# ✅ collections: 10/10 PASS
|
||||
# ✅ recursion: 5/5 PASS
|
||||
# ✅ closures: 5/5 PASS
|
||||
# ✅ strings: 10/10 PASS
|
||||
# ✅ types: 10/10 PASS
|
||||
# ✅ memory: 10/10 PASS
|
||||
# ✅ complex: 30/30 PASS
|
||||
# ────────────────────────────
|
||||
# Total: 100/100 PASS (100%)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase C: Dispatch Unification (Week 7-12)
|
||||
|
||||
**Objective**: Unify all method calls through single Resolver path.
|
||||
|
||||
#### Week 7-8: Resolver Integration (2026-04-12 - 04-25)
|
||||
|
||||
**Goal**: Implement `Resolver.lookup(type_id, method, arity) -> MethodHandle`
|
||||
|
||||
**Design**:
|
||||
```hakorune
|
||||
// Resolver: Single resolution path for all method calls
|
||||
static box ResolverBox {
|
||||
_method_registry: MapBox // type_id -> method_name -> MethodHandle
|
||||
|
||||
// Main entry point
|
||||
lookup(type_id: IntegerBox,
|
||||
method: StringBox,
|
||||
arity: IntegerBox) {
|
||||
// 1. Search type registry
|
||||
local type_methods = me._method_registry.get(type_id)
|
||||
if type_methods.is_null() {
|
||||
return Result.Err("Unknown type: " + type_id)
|
||||
}
|
||||
|
||||
// 2. Lookup method by name + arity
|
||||
local method_key = method + "/" + arity
|
||||
local handle = type_methods.get(method_key)
|
||||
if handle.is_null() {
|
||||
// Fail-Fast: No fallback
|
||||
return Result.Err("Method not found: " + method_key)
|
||||
}
|
||||
|
||||
return Result.Ok(handle)
|
||||
}
|
||||
|
||||
// Registration (called at startup)
|
||||
register_type(type_id: IntegerBox,
|
||||
methods: MapBox) {
|
||||
me._method_registry.set(type_id, methods)
|
||||
}
|
||||
}
|
||||
|
||||
---
|
||||
|
||||
## C‑ABI Unification (design‑only in 20.6)
|
||||
|
||||
### Goals
|
||||
- Provide SSOT for Basic boxes (String/Array/Map/Int/Bool/Null/Void) via C‑ABI so both Rust VM and Hako VM call the same implementation.
|
||||
- Do not change behavior in 20.6 (flags default OFF). Implementation rollout is in 20.7.
|
||||
|
||||
### Deliverables (20.6)
|
||||
- [ ] ABI header draft (`docs/abi/hako_abi_v1.md` or `include/hako_abi_v1.h`): TypeId/Handle/Result/Dispatch/Allocator minimal set
|
||||
- [ ] Two‑Layer Export policy document (Stable ABI + Inlinable API)
|
||||
- [ ] Flags documented: `NYASH_ABI_BASIC_ON`, `NYASH_ABI_BUILTIN_LINK`
|
||||
- [ ] Build presets documented: default/embedded/research
|
||||
- [ ] No runtime behavior change (flags remain OFF)
|
||||
|
||||
### Acceptance Criteria
|
||||
- Quick/Integration remain green with flags OFF
|
||||
- Docs provide rollback and gating policy; CI does not depend on ABI flags yet
|
||||
|
||||
### Out of Scope (move to 20.7)
|
||||
- Actual ABI binding for String/Array/Map
|
||||
- Router rewrite to call ABI by default
|
||||
- Performance validation under ABI path
|
||||
```
|
||||
|
||||
**Deliverables**:
|
||||
- [ ] `resolver_box.hako` implementation
|
||||
- [ ] `method_handle_box.hako` implementation
|
||||
- [ ] Type registry initialization
|
||||
- [ ] 20 integration tests
|
||||
|
||||
**Testing**:
|
||||
```bash
|
||||
tests/golden/phase-c/resolver/
|
||||
├── test_lookup_success.hako
|
||||
├── test_lookup_failure.hako (Fail-Fast)
|
||||
├── test_arity_mismatch.hako
|
||||
├── test_type_not_found.hako
|
||||
└── ... (16 more)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### Week 9-10: CallableBox Refactoring (2026-04-26 - 05-09)
|
||||
|
||||
**Goal**: Single entry point for all invocations.
|
||||
|
||||
**Design**:
|
||||
```hakorune
|
||||
// ExecBox: Unified invocation
|
||||
static box ExecBox {
|
||||
call_by_handle(handle: MethodHandleBox,
|
||||
args: ArrayBox,
|
||||
guard: NoOperatorGuard) {
|
||||
// 1. Extract implementation from handle
|
||||
local impl_func = handle.get_implementation()
|
||||
|
||||
// 2. Validate arguments
|
||||
local expected_arity = handle.get_arity()
|
||||
if args.size() != expected_arity {
|
||||
return Result.Err("Arity mismatch")
|
||||
}
|
||||
|
||||
// 3. NoOperatorGuard prevents recursion (e.g., in op_eq)
|
||||
if guard.is_active() {
|
||||
// Prevent re-entry
|
||||
return Result.Err("Recursive operator call")
|
||||
}
|
||||
|
||||
// 4. Invoke
|
||||
guard.activate()
|
||||
local result = impl_func.call(args)
|
||||
guard.deactivate()
|
||||
|
||||
return result
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Macro Desugaring**:
|
||||
```hakorune
|
||||
// Before (user code):
|
||||
local result = arr.push(value)
|
||||
|
||||
// After (desugared by compiler):
|
||||
local method_ref = Callable.ref_method(arr, :push, 1)
|
||||
local result = method_ref.call([value])
|
||||
|
||||
// Which internally calls:
|
||||
// Resolver.lookup(arr.type_id, "push", 1) -> handle
|
||||
// ExecBox.call_by_handle(handle, [value], NoOperatorGuard)
|
||||
```
|
||||
|
||||
**Deliverables**:
|
||||
- [ ] `exec_box.hako` implementation
|
||||
- [ ] `no_operator_guard_box.hako` implementation
|
||||
- [ ] Macro desugaring implementation (compiler side)
|
||||
- [ ] 25 test cases
|
||||
|
||||
**Testing**:
|
||||
```bash
|
||||
tests/golden/phase-c/callable/
|
||||
├── test_call_by_handle.hako
|
||||
├── test_no_operator_guard.hako
|
||||
├── test_macro_desugar_method.hako
|
||||
├── test_macro_desugar_operator.hako
|
||||
└── ... (21 more)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### Week 11: Universal Route Minimization (2026-05-10 - 05-16)
|
||||
|
||||
**Goal**: Remove all special-case dispatch, delegate everything to Resolver.
|
||||
|
||||
**Before (multiple dispatch paths)**:
|
||||
```rust
|
||||
// Rust VM (old approach)
|
||||
match call_type {
|
||||
Global => dispatch_global(...),
|
||||
BoxMethod => dispatch_box_method(...),
|
||||
Closure => dispatch_closure(...),
|
||||
Constructor => dispatch_constructor(...),
|
||||
ModuleFunction => dispatch_module_function(...),
|
||||
// 5 different code paths!
|
||||
}
|
||||
```
|
||||
|
||||
**After (single dispatch path)**:
|
||||
```hakorune
|
||||
// Hakorune VM (unified approach)
|
||||
// All calls:
|
||||
local handle = Resolver.lookup(type_id, method, arity)
|
||||
local result = ExecBox.call_by_handle(handle, args, NoOperatorGuard)
|
||||
|
||||
// No special cases!
|
||||
```
|
||||
|
||||
**Removal List**:
|
||||
- ❌ Remove: Special-case dispatch (Global/Box/Closure/Constructor/Module)
|
||||
- ❌ Remove: Hardcoded method tables
|
||||
- ❌ Remove: Fallback implementations (use Fail-Fast instead)
|
||||
|
||||
**Deliverables**:
|
||||
- [ ] Special-case dispatch removal complete
|
||||
- [ ] Codebase cleanup (reduce complexity)
|
||||
- [ ] 30 edge case tests (ensure Fail-Fast works)
|
||||
|
||||
**Testing**:
|
||||
```bash
|
||||
tests/golden/phase-c/unification/
|
||||
├── test_no_global_special_case.hako
|
||||
├── test_no_box_special_case.hako
|
||||
├── test_fail_fast_unknown_method.hako
|
||||
├── test_fail_fast_wrong_arity.hako
|
||||
└── ... (26 more)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### Week 12: Integration + Documentation (2026-05-17 - 05-24)
|
||||
|
||||
**Goal**: Phase 20.6 completion report.
|
||||
|
||||
**Integration Testing**:
|
||||
- [ ] Re-run all Golden Tests (100+ tests ALL PASS)
|
||||
- [ ] Performance testing (≥ 50% of Rust-VM)
|
||||
- [ ] Stress testing (large programs)
|
||||
- [ ] Regression testing (no breakage)
|
||||
|
||||
**Performance Benchmark**:
|
||||
```bash
|
||||
# Benchmark script
|
||||
bash tools/benchmark_hakorune_vm.sh
|
||||
|
||||
# Expected output:
|
||||
# Rust-VM: 10.2s
|
||||
# Hako-VM: 18.5s (55% of Rust-VM) ✅
|
||||
# Memory: 180MB (< 200MB target) ✅
|
||||
```
|
||||
|
||||
**Documentation**:
|
||||
- [ ] VM Core Complete Reference
|
||||
- [ ] Dispatch Unification Design Doc
|
||||
- [ ] Performance Report
|
||||
- [ ] Phase 20.6 Completion Report
|
||||
- [ ] Phase 20.7 Planning Doc
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria (DoD)
|
||||
|
||||
### Technical
|
||||
|
||||
1. **VM Core Complete**:
|
||||
- [ ] All 16 MIR instructions working
|
||||
- [ ] Control flow complete (branch, phi, loopform)
|
||||
- [ ] Memory operations complete (load, store, copy)
|
||||
|
||||
2. **Golden Tests**:
|
||||
- [ ] 100+ test cases ALL PASS
|
||||
- [ ] Rust-VM vs Hako-VM: 100% output match
|
||||
- [ ] Edge cases covered
|
||||
|
||||
3. **Dispatch Unified**:
|
||||
- [ ] All method calls go through Resolver
|
||||
- [ ] Special-case dispatch completely removed
|
||||
- [ ] Fail-Fast verified (unknown methods → immediate error)
|
||||
|
||||
### Performance
|
||||
|
||||
- [ ] **Hako-VM ≥ 50% of Rust-VM** (execution speed)
|
||||
- [ ] **Memory usage**: < 200MB (typical programs)
|
||||
- [ ] **Compile time**: < 10s (small programs)
|
||||
|
||||
### Quality
|
||||
|
||||
- [ ] **Test coverage**: All instructions and control paths covered
|
||||
- [ ] **Documentation**: Architecture, design, migration guide complete
|
||||
- [ ] **Code review**: Approved by ChatGPT + Claude
|
||||
|
||||
---
|
||||
|
||||
## Risk Mitigation
|
||||
|
||||
### Risk 1: Implementation Complexity
|
||||
|
||||
**Issue**: Implementing all 16 instructions is complex.
|
||||
|
||||
**Impact**: HIGH
|
||||
|
||||
**Mitigation**:
|
||||
- Use Rust VM as reference implementation
|
||||
- Incremental implementation (2-4 instructions/week)
|
||||
- Dedicated test suite per instruction
|
||||
- Golden Tests catch bugs early
|
||||
|
||||
### Risk 2: Dispatch Unification Difficulty
|
||||
|
||||
**Issue**: Removing special cases has wide impact.
|
||||
|
||||
**Impact**: MEDIUM
|
||||
|
||||
**Mitigation**:
|
||||
- Gradual migration: Add new code → Test → Remove old code
|
||||
- Implement and test Resolver first
|
||||
- Feature flag for toggle
|
||||
- Strengthen regression tests
|
||||
|
||||
### Risk 3: Performance Degradation
|
||||
|
||||
**Issue**: Hako-VM may be slower than Rust-VM.
|
||||
|
||||
**Impact**: MEDIUM
|
||||
|
||||
**Mitigation**:
|
||||
- Initial target: 50% (acceptable)
|
||||
- Weekly benchmark measurements
|
||||
- Early bottleneck identification
|
||||
- Optimization deferred to Phase 20.7
|
||||
|
||||
### Risk 4: Golden Test Mismatches
|
||||
|
||||
**Issue**: Rust-VM and Hako-VM outputs may differ.
|
||||
|
||||
**Impact**: HIGH
|
||||
|
||||
**Mitigation**:
|
||||
- Ensure determinism (JSON normalization, sorted keys)
|
||||
- Replace float operations with integers
|
||||
- Eliminate randomness (timestamps, PIDs)
|
||||
- Detailed diff logging
|
||||
|
||||
---
|
||||
|
||||
## Test Strategy
|
||||
|
||||
### Golden Test Framework
|
||||
|
||||
**Goal**: Prove Hakorune-VM produces identical output to Rust-VM.
|
||||
|
||||
**Test Suite Structure**:
|
||||
```
|
||||
tests/golden/
|
||||
├── phase-b/ # Week 1-6 (VM Core)
|
||||
│ ├── memory/ # 10 tests (load, store, copy)
|
||||
│ ├── calls/ # 15 tests (call, boxcall, externcall)
|
||||
│ ├── types/ # 10 tests (typeop, newbox)
|
||||
│ └── control/ # 15 tests (barrier, safepoint, loopform)
|
||||
├── phase-c/ # Week 7-12 (Dispatch)
|
||||
│ ├── resolver/ # 20 tests (lookup, registration)
|
||||
│ ├── callable/ # 25 tests (call_by_handle, guard)
|
||||
│ └── unification/ # 30 tests (edge cases, Fail-Fast)
|
||||
└── integration/ # Week 12
|
||||
├── 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
|
||||
```
|
||||
|
||||
**Verification Script**:
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# tools/golden_test_hakorune_vm.sh
|
||||
|
||||
for test in tests/golden/**/*.hako; do
|
||||
echo "Testing: $test"
|
||||
|
||||
# Run on Rust VM
|
||||
./hako --backend vm-rust "$test" > /tmp/rust_out.txt 2>&1
|
||||
rust_exit=$?
|
||||
|
||||
# Run on Hakorune VM
|
||||
./hako --backend vm "$test" > /tmp/hako_out.txt 2>&1
|
||||
hako_exit=$?
|
||||
|
||||
# Compare outputs
|
||||
if diff /tmp/rust_out.txt /tmp/hako_out.txt && [ $rust_exit -eq $hako_exit ]; then
|
||||
echo " ✅ PASS"
|
||||
else
|
||||
echo " ❌ FAIL"
|
||||
exit 1
|
||||
fi
|
||||
done
|
||||
|
||||
echo "✅ All Golden Tests PASSED!"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## CI Integration
|
||||
|
||||
```yaml
|
||||
# .github/workflows/golden_tests.yml
|
||||
name: Golden Tests (Phase 20.6)
|
||||
on: [push, pull_request]
|
||||
|
||||
jobs:
|
||||
golden-tests:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
|
||||
- name: Build Hakorune
|
||||
run: cargo build --release
|
||||
|
||||
- name: Run Golden Tests
|
||||
run: bash tools/golden_test_hakorune_vm.sh
|
||||
|
||||
- name: Performance Benchmark
|
||||
run: |
|
||||
bash tools/benchmark_hakorune_vm.sh
|
||||
# Verify: Hako-VM ≥ 50% of Rust-VM
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
### From Phase 20.5
|
||||
|
||||
- [x] HostBridge API (C-ABI boundary)
|
||||
- [x] op_eq Migration (NoOperatorGuard)
|
||||
- [x] VM Foundations PoC (5 instructions)
|
||||
|
||||
### For Phase 20.6
|
||||
|
||||
- [ ] Resolver design finalized (Week 7)
|
||||
- [ ] MethodHandle design finalized (Week 7)
|
||||
- [ ] Golden Test infrastructure ready (Week 1)
|
||||
- [ ] Benchmark infrastructure ready (Week 1)
|
||||
|
||||
---
|
||||
|
||||
## Next Steps (Actionable)
|
||||
|
||||
1. **Week 1 Preparation** (before 2026-03-01):
|
||||
- [ ] Lock Golden Test list (100+ tests)
|
||||
- [ ] Set up test infrastructure
|
||||
- [ ] Prepare benchmark suite
|
||||
- [ ] Review Phase 20.5 deliverables
|
||||
|
||||
2. **Week 1-6 Execution**:
|
||||
- [ ] Implement instructions incrementally
|
||||
- [ ] Run Golden Tests continuously
|
||||
- [ ] Measure performance weekly
|
||||
|
||||
3. **Week 7-12 Execution**:
|
||||
- [ ] Implement Resolver + CallableBox
|
||||
- [ ] Remove special-case dispatch
|
||||
- [ ] Verify Fail-Fast behavior
|
||||
|
||||
4. **Week 12 Completion**:
|
||||
- [ ] All Golden Tests PASS
|
||||
- [ ] Performance ≥ 50% verified
|
||||
- [ ] Documentation complete
|
||||
- [ ] Phase 20.7 planning doc ready
|
||||
|
||||
---
|
||||
|
||||
**Created**: 2025-10-14
|
||||
**Phase Start**: 2026-03-01
|
||||
**Phase End**: 2026-05-24
|
||||
**Duration**: 12 weeks
|
||||
**Prerequisite**: Phase 20.5 complete
|
||||
**Success**: VM Core Complete + Dispatch Unified ✅
|
||||
452
docs/private/roadmap/phases/phase-20.6/README.md
Normal file
452
docs/private/roadmap/phases/phase-20.6/README.md
Normal file
@ -0,0 +1,452 @@
|
||||
# Phase 20.6 - VM Core Complete (Phase B+C 完全達成)
|
||||
|
||||
**期間**: 2026-03-01 - 2026-05-24 (12週間)
|
||||
**状態**: Planning（前提の一部は既に実装済み／統合済み）
|
||||
**前提**: Phase 20.5完了 (VM Foundations PoC + op_eq Migration)
|
||||
|
||||
---
|
||||
|
||||
## 🎯 このフェーズで実現すること
|
||||
|
||||
**"Hakorune VM Core 完全実装 + Dispatch統一"**
|
||||
|
||||
現状の前提更新（2025‑10 時点）
|
||||
- MirCall 正規化は導入済み（Callee=Method/ModuleFunction/Extern/Constructor）。NewBox→Constructor は既定ON。
|
||||
- Static Box の “me 注入” は Builder→Rewrite へ移設済み。Verifier で違反を Fail‑Fast。
|
||||
- LoopForm は quick プロファイルで既定ON、代表系は緑（PHI 形状の安定化済み）。
|
||||
- Boot/Lock（Zero‑Box Boot）導入済み：`--frozen`（LockOnly）/ `--lock` / `--lock-verify` / `--lock-diff` 完備。PluginLoader は BootPlan 優先で探索撤退。
|
||||
|
||||
### フェーズの位置づけ
|
||||
|
||||
Phase 20.6は**Pure Hakorune Roadmap**における2つの重要フェーズを完了します:
|
||||
|
||||
1. **Phase B Complete (Week 1-6)**: VM Core in Hakorune
|
||||
- 全16個のMIR命令を実装
|
||||
- 制御フロー（分岐、PHI、ループ）完全対応
|
||||
- Golden Tests: Rust-VM vs Hako-VM 100%一致
|
||||
|
||||
2. **Phase C (Week 7-12)**: Dispatch Unification
|
||||
- Resolver統合（すべてのメソッド呼び出しを統一）
|
||||
- CallableBoxリファクタリング
|
||||
- Universal Route Minimization（特殊ケース排除）
|
||||
|
||||
---
|
||||
|
||||
## 💡 背景と動機
|
||||
|
||||
### Phase 20.5での達成内容
|
||||
|
||||
Phase 20.5で以下を完了:
|
||||
- ✅ HostBridge API (C-ABI境界)
|
||||
- ✅ op_eq Migration (Hakoruneで実装)
|
||||
- ✅ VM Foundations PoC (5命令: const, binop, compare, jump, ret)
|
||||
|
||||
### Phase 20.6での拡張
|
||||
|
||||
Phase 20.6では:
|
||||
1. **VM Core Complete**: 5命令 → 16命令へ拡張
|
||||
2. **制御フロー強化**: branch, phi, loopform対応
|
||||
3. **メモリ操作**: load, store, copy対応
|
||||
4. **メソッド呼び出し**: call, boxcall, externcall対応
|
||||
5. **Dispatch統一**: Resolverによる単一解決経路
|
||||
|
||||
---
|
||||
|
||||
## 🔗 C-ABI 統一（設計のみ・実装は20.7）
|
||||
|
||||
目的
|
||||
- 基本箱（String/Array/Map ほか）を C-ABI で単一起点化し、Rust VM と Hakorune VM の双方が同じ実装を叩ける状態を設計先行で整備する。
|
||||
- Phase 20.6 では SSOT（仕様・ヘッダ・旗振り）を置き、挙動は不変（既定OFF）。実装切替は 20.7 で行う。
|
||||
|
||||
設計方針（Two‑Layer Export）
|
||||
- Stable ABI（外向け）: `extern "C"` の安定シンボル（new/free/retain/dispatch/size/get/set 等）
|
||||
- Inlinable API（内向け）: `#[inline(always)]` な crate 内 API。内蔵時は Known/Rewrite で直呼びに最適化
|
||||
- 既定: Meta は内蔵（ABI互換を保つ実装様式）、Basic はプラグイン（WASM/embedded は内蔵プラグイン）
|
||||
|
||||
フラグ（設計追加のみ・既定OFF）
|
||||
- `NYASH_ABI_BASIC_ON=0|1` … 基本箱を ABI 経路に切替（20.7 で使用開始）
|
||||
- `NYASH_ABI_BUILTIN_LINK=0|1` … 内蔵プラグイン静的リンク（LTO/inline 最適化用）
|
||||
|
||||
受け入れ基準（20.6）
|
||||
- ヘッダ/SSOT 文書/flags が追加されても quick/integration の結果が不変（既定OFF）
|
||||
- ドキュメント: 設計、運用ポリシー、ロールバック手順、ビルドプリセット（default/embedded/research）を記載
|
||||
- CLI/起動: Boot/Lock の運用を併記（Dev=自動生成/差分、Frozen=LockOnly）。ABI 導入後も決定性を損なわないこと。
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ アーキテクチャ概要
|
||||
|
||||
### Phase B: VM Core Complete (Week 1-6)
|
||||
|
||||
```
|
||||
【16個のMIR命令】
|
||||
┌─────────────────────────────────────┐
|
||||
│ 基本値・制御 (5命令) │
|
||||
│ ✅ const, ret, jump, branch, phi │ ← Phase 20.5完了
|
||||
├─────────────────────────────────────┤
|
||||
│ 演算 (6命令) │
|
||||
│ ✅ binop (Add/Sub/Mul/Div/Mod) │ ← Phase 20.5完了
|
||||
│ ✅ compare (Eq/Ne/Lt/Le/Gt/Ge) │ ← Phase 20.5完了
|
||||
│ ⬜ unaryop │ ← Phase 20.6追加
|
||||
├─────────────────────────────────────┤
|
||||
│ 呼び出し（MirCallに統一） │
|
||||
│ ⬜ MirCall(callee=…) │ ← Phase 20.6追加
|
||||
│ - Callee::Method │
|
||||
│ - Callee::ModuleFunction │
|
||||
│ - Callee::Extern │
|
||||
│ - Callee::Constructor │
|
||||
├─────────────────────────────────────┤
|
||||
│ メモリ・型 │
|
||||
│ ⬜ load, store, copy │ ← Phase 20.6追加
|
||||
│ ⬜ typeop │ ← Phase 20.6追加
|
||||
│ （new は MirCall::Constructor） │
|
||||
├─────────────────────────────────────┤
|
||||
│ 制御最適化 (3命令) │
|
||||
│ ⬜ barrier, safepoint, loopform │ ← Phase 20.6追加
|
||||
└─────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Phase C: Dispatch Unification (Week 7-12)
|
||||
|
||||
```
|
||||
【現状: 複数の解決経路】
|
||||
┌────────────────────────────────────┐
|
||||
│ Method Call Dispatch │
|
||||
│ ├─ Global Function (特殊ケース) │
|
||||
│ ├─ Box Method (特殊ケース) │
|
||||
│ ├─ Closure (特殊ケース) │
|
||||
│ ├─ Constructor (特殊ケース) │
|
||||
│ └─ Module Function (特殊ケース) │
|
||||
└────────────────────────────────────┘
|
||||
↓ Phase C統一
|
||||
┌────────────────────────────────────┐
|
||||
│ Unified Resolver Path │
|
||||
│ │
|
||||
│ Resolver.lookup(type_id, method, arity)
|
||||
│ ↓ │
|
||||
│ MethodHandle │
|
||||
│ ↓ │
|
||||
│ ExecBox.call_by_handle( │
|
||||
│ handle, args, NoOperatorGuard)│
|
||||
└────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**重要な設計原則**:
|
||||
- **単一解決経路**: すべての呼び出しは MirCall の Callee で表現
|
||||
- BoxCall/ExternCall/NewBox といったレガシー命令は導入しない（すべて MirCall）
|
||||
- **Fail‑Fast**: 未知メソッド/外部IF は即エラー（フォールバック禁止）
|
||||
- **特殊ケース排除**: 疑似メソッドや多重ディスパッチ経路を撤去
|
||||
|
||||
---
|
||||
|
||||
## 📊 週次計画 (Week 1-12)
|
||||
|
||||
### Phase B Complete: VM Core (Week 1-6)
|
||||
|
||||
#### Week 1-2: メモリ操作命令 (2026-03-01 - 03-14)
|
||||
|
||||
**目標**: load, store, copy実装
|
||||
|
||||
**実装対象**:
|
||||
```hakorune
|
||||
// load: メモリから値をロード
|
||||
// store: メモリに値を保存
|
||||
// copy: レジスタ間のコピー
|
||||
```
|
||||
|
||||
**成果物**:
|
||||
- [ ] `load_handler.hako` 実装
|
||||
- [ ] `store_handler.hako` 実装
|
||||
- [ ] `copy_handler.hako` 実装
|
||||
- [ ] テスト: 10ケース (メモリ操作基本)
|
||||
|
||||
#### Week 3-4: メソッド呼び出し命令 (2026-03-15 - 03-28)
|
||||
|
||||
**目標**: call, boxcall, externcall実装
|
||||
|
||||
**実装対象**:
|
||||
```hakorune
|
||||
// call: 関数呼び出し (Global/Module/Closure)
|
||||
// boxcall: Boxメソッド呼び出し
|
||||
// externcall: 外部関数呼び出し (nyrt.time等)
|
||||
```
|
||||
|
||||
**成果物**:
|
||||
- [ ] `call_handler.hako` 実装 (Unified MirCall)
|
||||
- [ ] `boxcall_handler.hako` 実装
|
||||
- [ ] `externcall_handler.hako` 実装
|
||||
- [ ] テスト: 15ケース (呼び出し基本)
|
||||
|
||||
#### Week 5: 型操作命令 (2026-03-29 - 04-04)
|
||||
|
||||
**目標**: typeop, newbox実装
|
||||
|
||||
**実装対象**:
|
||||
```hakorune
|
||||
// typeop: 型変換・型チェック
|
||||
// newbox: Box生成
|
||||
```
|
||||
|
||||
**成果物**:
|
||||
- [ ] `typeop_handler.hako` 実装
|
||||
- [ ] `newbox_handler.hako` 実装
|
||||
- [ ] テスト: 10ケース (型操作基本)
|
||||
|
||||
#### Week 6: 制御最適化命令 + Golden Tests (2026-04-05 - 04-11)
|
||||
|
||||
**目標**: 残り命令 + Golden Testing完了
|
||||
|
||||
**実装対象**:
|
||||
```hakorune
|
||||
// barrier: GC barrier
|
||||
// safepoint: GC safepoint
|
||||
// loopform: ループ検出ヒント
|
||||
// unaryop: 単項演算
|
||||
```
|
||||
|
||||
**Golden Tests**:
|
||||
- [ ] 算術演算: 10ケース
|
||||
- [ ] 制御フロー: 10ケース
|
||||
- [ ] コレクション操作: 10ケース
|
||||
- [ ] 再帰: 5ケース
|
||||
- [ ] クロージャ: 5ケース
|
||||
- [ ] 文字列操作: 10ケース
|
||||
- [ ] 型操作: 10ケース
|
||||
- [ ] メモリ操作: 10ケース
|
||||
- [ ] 複合ケース: 30ケース
|
||||
|
||||
**合計**: 100個のGolden Tests
|
||||
|
||||
**成果物**:
|
||||
- [ ] 残り命令実装完了
|
||||
- [ ] Golden Test Suite完成 (100+ tests)
|
||||
- [ ] パフォーマンス測定: Hako-VM ≥ 50% of Rust-VM
|
||||
|
||||
---
|
||||
|
||||
### Phase C: Dispatch Unification (Week 7-12)
|
||||
|
||||
#### Week 7-8: Resolver統合 (2026-04-12 - 04-25)
|
||||
|
||||
**目標**: Resolver.lookup実装 + 統合
|
||||
|
||||
**実装内容**:
|
||||
```hakorune
|
||||
// Resolver: すべてのメソッド呼び出しを統一
|
||||
static box ResolverBox {
|
||||
// type_id, method, arity → MethodHandle
|
||||
lookup(type_id: IntegerBox,
|
||||
method: StringBox,
|
||||
arity: IntegerBox) {
|
||||
// 1. 型情報から適切なハンドラーを検索
|
||||
// 2. メソッドシグネチャ検証
|
||||
// 3. MethodHandle返却
|
||||
// 4. 見つからない場合 → RuntimeError (Fail-Fast)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**成果物**:
|
||||
- [ ] `resolver_box.hako` 実装
|
||||
- [ ] `method_handle_box.hako` 実装
|
||||
- [ ] 統合テスト: 20ケース
|
||||
|
||||
#### Week 9-10: CallableBox Refactoring (2026-04-26 - 05-09)
|
||||
|
||||
**目標**: 単一呼び出しエントリーポイント実装
|
||||
|
||||
**実装内容**:
|
||||
```hakorune
|
||||
// CallableBox: すべての呼び出しを統一
|
||||
static box ExecBox {
|
||||
call_by_handle(handle: MethodHandleBox,
|
||||
args: ArrayBox,
|
||||
guard: NoOperatorGuard) {
|
||||
// 1. ハンドルから実装取得
|
||||
// 2. 引数検証
|
||||
// 3. NoOperatorGuardで再帰防止
|
||||
// 4. 実行
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**マクロデシュガー**:
|
||||
```hakorune
|
||||
// Before: arr.push(value)
|
||||
// After: Callable.ref_method(arr, :push, 1).call([value])
|
||||
```
|
||||
|
||||
**成果物**:
|
||||
- [ ] `exec_box.hako` 実装
|
||||
- [ ] `no_operator_guard_box.hako` 実装
|
||||
- [ ] マクロデシュガー実装
|
||||
- [ ] テスト: 25ケース
|
||||
|
||||
#### Week 11: Universal Route Minimization (2026-05-10 - 05-16)
|
||||
|
||||
**目標**: 疑似メソッド実装削除
|
||||
|
||||
**削除対象**:
|
||||
- ❌ 特殊ケースdispatch (Global/Box/Closure/Constructor/Module)
|
||||
- ❌ ハードコードされたメソッドテーブル
|
||||
- ❌ フォールバック実装
|
||||
|
||||
**実装内容**:
|
||||
- ✅ すべてResolver経由
|
||||
- ✅ 未知メソッド → RuntimeError (Fail-Fast)
|
||||
- ✅ 単一コードパス
|
||||
|
||||
**成果物**:
|
||||
- [ ] 特殊ケース削除完了
|
||||
- [ ] コードベース整理
|
||||
- [ ] テスト: 30ケース (エッジケース)
|
||||
|
||||
#### Week 12: 統合テスト + ドキュメント (2026-05-17 - 05-24)
|
||||
|
||||
**目標**: Phase 20.6完了報告
|
||||
|
||||
**統合テスト**:
|
||||
- [ ] Golden Tests再実行 (100+ tests ALL PASS)
|
||||
- [ ] パフォーマンステスト (≥ 50% of Rust-VM)
|
||||
- [ ] ストレステスト (大規模プログラム)
|
||||
- [ ] リグレッションテスト
|
||||
|
||||
**ドキュメント**:
|
||||
- [ ] VM Core完全リファレンス
|
||||
- [ ] Dispatch Unification設計書
|
||||
- [ ] パフォーマンスレポート
|
||||
- [ ] Phase 20.6完了報告書
|
||||
- [ ] Phase 20.7計画書
|
||||
|
||||
---
|
||||
|
||||
## 🏆 成功基準 (DoD)
|
||||
|
||||
### 技術的基準
|
||||
|
||||
1. **VM Core Complete**:
|
||||
- [ ] 全16個のMIR命令が動作
|
||||
- [ ] 制御フロー完全対応 (branch, phi, loopform)
|
||||
- [ ] メモリ操作完全対応 (load, store, copy)
|
||||
|
||||
2. **Golden Tests**:
|
||||
- [ ] 100個以上のテストケースすべてPASS
|
||||
- [ ] Rust-VM vs Hako-VM: 100%出力一致
|
||||
- [ ] エッジケース網羅
|
||||
|
||||
3. **Dispatch Unified**:
|
||||
- [ ] すべてのメソッド呼び出しがResolver経由
|
||||
- [ ] 特殊ケースdispatch完全削除
|
||||
- [ ] Fail-Fast動作確認 (未知メソッド→即エラー)
|
||||
|
||||
### パフォーマンス基準
|
||||
|
||||
- [ ] **Hako-VM ≥ 50% of Rust-VM** (実行速度)
|
||||
- [ ] **メモリ使用量**: < 200MB (通常プログラム)
|
||||
- [ ] **コンパイル時間**: < 10s (小規模プログラム)
|
||||
|
||||
### 品質基準
|
||||
|
||||
- [ ] **テストカバレッジ**: すべての命令・制御パスをカバー
|
||||
- [ ] **ドキュメント**: アーキテクチャ・設計・移行ガイド完備
|
||||
- [ ] **コードレビュー**: ChatGPT + Claude承認済み
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ リスク & 対策
|
||||
|
||||
### リスク1: 実装複雑性
|
||||
|
||||
**問題**: 16命令すべての実装は複雑
|
||||
|
||||
**影響**: HIGH
|
||||
|
||||
**対策**:
|
||||
- Rust VMを参照実装として利用
|
||||
- 週次で段階的実装 (2-4命令/週)
|
||||
- 各命令に専用テストスイート
|
||||
- Golden Testsで早期バグ検出
|
||||
|
||||
### リスク2: Dispatch統一の難易度
|
||||
|
||||
**問題**: 既存の特殊ケース削除は影響範囲が大きい
|
||||
|
||||
**影響**: MEDIUM
|
||||
|
||||
**対策**:
|
||||
- 段階的移行: 新コード追加 → テスト → 旧コード削除
|
||||
- Resolverを先に実装・テスト
|
||||
- フィーチャーフラグで切り替え可能に
|
||||
- リグレッションテスト強化
|
||||
|
||||
### リスク3: パフォーマンス劣化
|
||||
|
||||
**問題**: Hako-VMがRust-VMより遅い可能性
|
||||
|
||||
**影響**: MEDIUM
|
||||
|
||||
**対策**:
|
||||
- 初期目標: 50% (許容範囲)
|
||||
- 週次でベンチマーク測定
|
||||
- ボトルネック早期特定
|
||||
- 最適化はPhase 20.7以降
|
||||
|
||||
### リスク4: Golden Tests不一致
|
||||
|
||||
**問題**: Rust-VMとHako-VMで出力が異なる可能性
|
||||
|
||||
**影響**: HIGH
|
||||
|
||||
**対策**:
|
||||
- 決定性保証 (JSON正規化、ソート済みキー)
|
||||
- 浮動小数点演算は整数で代替
|
||||
- ランダム性排除 (タイムスタンプ、PID等)
|
||||
- 差分詳細ログ
|
||||
|
||||
---
|
||||
|
||||
## 📚 関連リソース
|
||||
|
||||
### Phase 20.6ドキュメント
|
||||
|
||||
- **[INDEX.md](INDEX.md)** - ドキュメント構造
|
||||
- **[PLAN.md](PLAN.md)** - 実行計画 (English)
|
||||
- **[CHECKLIST.md](CHECKLIST.md)** - 週次チェックリスト
|
||||
|
||||
### 前後のフェーズ
|
||||
|
||||
- **前**: [Phase 20.5 - VM Foundations](../phase-20.5/)
|
||||
- **次**: [Phase 20.7 - Collections in Hakorune](../phase-20.7/) (予定)
|
||||
|
||||
### 参照ドキュメント
|
||||
|
||||
- [Pure Hakorune Roadmap](../phase-20.5/PURE_HAKORUNE_ROADMAP.md) - 全体計画
|
||||
- [MIR Instruction Set](../../../../reference/mir/INSTRUCTION_SET.md) - MIR命令仕様
|
||||
- [Hakorune VM Discovery](../phase-20.5/HAKORUNE_VM_DISCOVERY.md) - VM発見レポート
|
||||
|
||||
---
|
||||
|
||||
## 🎉 成功後の世界
|
||||
|
||||
### Phase 20.6完了後（22週間累計、2026-05-24）:
|
||||
|
||||
1. **VM Core Complete**: 全16個のMIR命令が動作
|
||||
2. **Golden Tests PASS**: 100%一致保証
|
||||
3. **Dispatch Unified**: 単一解決経路確立
|
||||
4. **パフォーマンス達成**: ≥ 50% of Rust-VM
|
||||
5. **ドキュメント完備**: 完全なアーキテクチャドキュメント
|
||||
|
||||
### 次のステップ (Phase 20.7):
|
||||
|
||||
- **Collections in Hakorune**: MapBox/ArrayBoxのHakorune実装
|
||||
- **Deterministic Behavior**: 決定性保証（イテレーション順序等）
|
||||
- **Performance Optimization**: 70%目標
|
||||
|
||||
---
|
||||
|
||||
**作成日**: 2025-10-14
|
||||
**Phase開始予定**: 2026-03-01
|
||||
**Phase終了予定**: 2026-05-24
|
||||
**想定期間**: 12週間
|
||||
**前提フェーズ**: Phase 20.5 (VM Foundations PoC)
|
||||
**成果**: VM Core Complete + Dispatch Unification ✅
|
||||
Reference in New Issue
Block a user