docs: restore docs/private/roadmap from 7b4908f9 (Phase 20.31)
This commit is contained in:
nyash-codex
393
docs/private/roadmap/phases/phase-20.7/CHECKLIST.md
Normal file
393
docs/private/roadmap/phases/phase-20.7/CHECKLIST.md
Normal file
@ -0,0 +1,393 @@
|
||||
# Phase 20.7: Collections in Hakorune - Implementation Checklist（2025‑10 反映）
|
||||
|
||||
**Duration**: 8 weeks (2026-05-25 → 2026-07-19)
|
||||
**Status**: PLANNED（Router/正規化/BootLock は先行導入済み）
|
||||
|
||||
## 進捗スナップショット（2025‑10）
|
||||
- [x] Router: ABI 基本フック `NYASH_ABI_BASIC_ON` を導入（既定OFF）
|
||||
- [x] Core Extern 正規化: `NYASH_NORMALIZE_CORE_EXTERN=1` 既定ON
|
||||
- [x] Verifier: `NYASH_VERIFY_CORE_EXTERN=1` で strict チェック（Fail‑Fast）
|
||||
- [x] Boot/Lock: LockOnly/Auto で決定性維持（order/libraries に基づくロード）
|
||||
> 観測メモ: quick=既定ON、integration=first wave 既定ON。integration 部分実行（Extern len/ModuleFunction canonical/Box equals）で緑確認。残りは48h観測窓でノイズ監視（perf目安≥70%）。
|
||||
|
||||
## 段階ON（Pilot → Rollout）
|
||||
1) quick（pilot）
|
||||
- [x] `NYASH_ABI_BASIC_ON=1` で String.length/len/size → Array.size/push → Map.size/has/get/set の順に導通（quick/env 既定ON）
|
||||
- [x] スモーク緑化（VM/LLVM）：parity 変化なし（pilot 緑）
|
||||
2) integration（rollout）
|
||||
- [x] 同順で段階ON（first wave: String/Array 反映。env 既定ON）
|
||||
- [ ] perf ≥ 70% / 回帰無し確認（観測継続）
|
||||
3) AOT（任意検証）
|
||||
- [ ] 文字列長の意味論（bytes）でパリティ（VM=bytes）。AOT 実装差を吸収
|
||||
- [ ] FFI dynamic の前提満たす場合のみ実行
|
||||
|
||||
---
|
||||
|
||||
## Week 1: MapBox Foundation
|
||||
|
||||
### Data Structures
|
||||
- [ ] Design bucket storage (chaining or open addressing)
|
||||
- [ ] Implement hash function for Symbol type
|
||||
- [ ] Implement hash function for Int type
|
||||
- [ ] Implement hash function for String type (FNV-1a or similar)
|
||||
- [ ] Design collision resolution strategy
|
||||
|
||||
### Core Operations
|
||||
- [ ] Implement `MapBox._hash(key)` internal method
|
||||
- [ ] Implement `MapBox.set(key, value)` method
|
||||
- [ ] Implement `MapBox.get(key)` method
|
||||
- [ ] Implement basic resizing logic (load factor > 0.75)
|
||||
- [ ] Implement bucket allocation/deallocation
|
||||
|
||||
### Tests
|
||||
- [ ] Test basic set operation (10 test cases)
|
||||
- [ ] Test basic get operation (10 test cases)
|
||||
- [ ] Test hash collision handling (5 test cases)
|
||||
- [ ] Test resizing behavior (3 test cases)
|
||||
- [ ] Test empty map edge cases (3 test cases)
|
||||
|
||||
### Documentation
|
||||
- [ ] Document bucket storage design
|
||||
- [ ] Document hash functions (Symbol/Int/String)
|
||||
- [ ] Document collision resolution strategy
|
||||
- [ ] Document resizing algorithm
|
||||
|
||||
---
|
||||
|
||||
## Week 2: Deterministic Hashing & Key Order
|
||||
|
||||
### Hash Strategy
|
||||
- [ ] Implement deterministic Symbol hash (use symbol ID)
|
||||
- [ ] Implement deterministic Int hash (use integer value)
|
||||
- [ ] Implement deterministic String hash (stable UTF-8 algorithm)
|
||||
- [ ] Test hash stability (same key → same bucket, 100 runs)
|
||||
|
||||
### Key Normalization
|
||||
- [ ] Implement type detection (Symbol vs Int vs String)
|
||||
- [ ] Implement unified comparison function (`compare_keys`)
|
||||
- [ ] Implement stable sort for mixed-type keys
|
||||
- [ ] Verify key comparison order: Symbol < Int < String
|
||||
|
||||
### Deterministic Iteration
|
||||
- [ ] Implement `MapBox.keys()` method (returns sorted keys)
|
||||
- [ ] Implement `MapBox.values()` method (returns values in key order)
|
||||
- [ ] Implement provenance tracking (plugin_id, version)
|
||||
- [ ] Verify iteration order stability (same input → same output, 10 runs)
|
||||
|
||||
### Tests
|
||||
- [ ] Test mixed-type key insertion (Symbol, Int, String) (10 test cases)
|
||||
- [ ] Test deterministic iteration order (20 test cases)
|
||||
- [ ] Test key order: Symbol < Int < String (5 test cases)
|
||||
- [ ] Test hash stability across runs (10 test cases)
|
||||
- [ ] Test provenance tracking (3 test cases)
|
||||
|
||||
### Documentation
|
||||
- [ ] Document deterministic hash strategy
|
||||
- [ ] Document key comparison order (Symbol < Int < String)
|
||||
- [ ] Document provenance tracking design
|
||||
|
||||
---
|
||||
|
||||
## Week 3: Advanced MapBox Operations
|
||||
|
||||
### Remove Operation
|
||||
- [ ] Implement `MapBox.remove(key)` method
|
||||
- [ ] Implement bucket chain repair (if using chaining)
|
||||
- [ ] Implement size decrement logic
|
||||
- [ ] Handle remove of non-existent key (return NullBox)
|
||||
|
||||
### Query Operations
|
||||
- [ ] Implement `MapBox.has(key)` method
|
||||
- [ ] Implement `MapBox.size()` method
|
||||
- [ ] Handle edge cases (empty map, single element)
|
||||
- [ ] Verify O(1) average time complexity
|
||||
|
||||
### Boundary Checks (Fail-Fast)
|
||||
- [ ] Reject ValueBox keys (panic with clear message)
|
||||
- [ ] Reject ValueBox values (panic with clear message)
|
||||
- [ ] Ensure DataBox-only inputs
|
||||
- [ ] Implement entry point unpack logic
|
||||
|
||||
### Tests
|
||||
- [ ] Test remove operation (15 test cases)
|
||||
- [ ] Test remove non-existent key (5 test cases)
|
||||
- [ ] Test has operation (10 test cases)
|
||||
- [ ] Test size operation (10 test cases)
|
||||
- [ ] Test edge cases (empty map, single element) (5 test cases)
|
||||
- [ ] Test ValueBox rejection (Fail-Fast) (5 test cases)
|
||||
|
||||
### Documentation
|
||||
- [ ] Document remove operation design
|
||||
- [ ] Document ValueBox/DataBox boundary enforcement
|
||||
- [ ] Document Fail-Fast error messages
|
||||
|
||||
---
|
||||
|
||||
## Week 4: MapBox Golden Tests & Performance
|
||||
|
||||
### Golden Test Suite
|
||||
- [ ] Create 50+ test cases for MapBox
|
||||
- [ ] Compare Rust-MapBox vs Hako-MapBox output
|
||||
- [ ] Verify identical output for all test cases
|
||||
- [ ] Test deterministic behavior (same input → same output, 10 runs per test)
|
||||
- [ ] Test key order stability (Symbol < Int < String)
|
||||
|
||||
### Deterministic Verification
|
||||
- [ ] Run each test 10 times, verify identical output
|
||||
- [ ] Test with 1,000+ keys (mixed types)
|
||||
- [ ] Verify provenance tracking in golden tests
|
||||
- [ ] Verify iteration order matches Rust-MapBox
|
||||
|
||||
### Performance Baseline
|
||||
- [ ] Measure set operation time (per 1,000 operations)
|
||||
- [ ] Measure get operation time (per 1,000 operations)
|
||||
- [ ] Measure remove operation time (per 1,000 operations)
|
||||
- [ ] Compare against Rust-MapBox
|
||||
- [ ] Verify performance ≥ 70% of Rust-MapBox
|
||||
- [ ] Profile hot paths (hash function, collision resolution)
|
||||
|
||||
### Documentation
|
||||
- [ ] Document MapBox API reference
|
||||
- [ ] Document usage examples (basic, advanced)
|
||||
- [ ] Document performance characteristics (O(1) average, O(n) worst case)
|
||||
- [ ] Document golden test results
|
||||
- [ ] Document performance benchmarks
|
||||
|
||||
### Week 4 Milestone Review
|
||||
- [ ] All MapBox methods implemented in Pure Hakorune
|
||||
- [ ] Golden tests: 50+ test cases PASS
|
||||
- [ ] Deterministic key order verified
|
||||
- [ ] Performance ≥ 70% of Rust-MapBox
|
||||
- [ ] Ready to proceed to ArrayBox implementation
|
||||
|
||||
---
|
||||
|
||||
## Week 5: ArrayBox Foundation
|
||||
|
||||
### Data Structures
|
||||
- [ ] Design RawBufferBox for storage
|
||||
- [ ] Implement capacity expansion strategy (2x growth)
|
||||
- [ ] Implement bounds checking logic
|
||||
- [ ] Design element addressing (index → buffer offset)
|
||||
|
||||
### Core Operations
|
||||
- [ ] Implement `ArrayBox.push(value)` method
|
||||
- [ ] Implement `ArrayBox.pop()` method
|
||||
- [ ] Implement capacity doubling logic
|
||||
- [ ] Handle empty array edge cases
|
||||
|
||||
### Tests
|
||||
- [ ] Test basic push operation (10 test cases)
|
||||
- [ ] Test basic pop operation (10 test cases)
|
||||
- [ ] Test capacity expansion (grow from 0 → 1 → 2 → 4 → 8) (5 test cases)
|
||||
- [ ] Test empty array edge cases (5 test cases)
|
||||
- [ ] Test push/pop sequence (10 test cases)
|
||||
|
||||
### Documentation
|
||||
- [ ] Document RawBufferBox design
|
||||
- [ ] Document capacity expansion strategy
|
||||
- [ ] Document push/pop algorithms
|
||||
|
||||
---
|
||||
|
||||
## Week 6: Index Operations & Fail-Fast
|
||||
|
||||
### Index Access
|
||||
- [ ] Implement `ArrayBox.get(index)` method
|
||||
- [ ] Implement `ArrayBox.set(index, value)` method
|
||||
- [ ] Implement bounds checking (index < 0 or index ≥ size)
|
||||
- [ ] Verify O(1) time complexity
|
||||
|
||||
### Fail-Fast Boundaries
|
||||
- [ ] Out-of-bounds access → RuntimeError (not panic)
|
||||
- [ ] Negative index → RuntimeError with clear message
|
||||
- [ ] Reject ValueBox elements (panic with clear message)
|
||||
- [ ] Ensure DataBox-only inputs
|
||||
|
||||
### Tests
|
||||
- [ ] Test valid index access (20 test cases)
|
||||
- [ ] Test out-of-bounds access (10 test cases)
|
||||
- [ ] Test negative index handling (5 test cases)
|
||||
- [ ] Test get/set sequence (10 test cases)
|
||||
- [ ] Test ValueBox rejection (Fail-Fast) (5 test cases)
|
||||
|
||||
### Documentation
|
||||
- [ ] Document index access design
|
||||
- [ ] Document bounds checking strategy
|
||||
- [ ] Document Fail-Fast error messages
|
||||
|
||||
---
|
||||
|
||||
## Week 7: Advanced ArrayBox Operations
|
||||
|
||||
### Slice Operation
|
||||
- [ ] Implement `ArrayBox.slice(start, end)` method
|
||||
- [ ] Return new ArrayBox with elements [start, end)
|
||||
- [ ] Handle edge cases (start > end, negative indices)
|
||||
- [ ] Handle out-of-bounds start/end (clamp or error)
|
||||
|
||||
### Concat Operation
|
||||
- [ ] Implement `ArrayBox.concat(other)` method
|
||||
- [ ] Create new ArrayBox with combined elements
|
||||
- [ ] Efficient memory allocation (pre-allocate total size)
|
||||
- [ ] Handle empty array concatenation
|
||||
|
||||
### ValueBox/DataBox Boundaries
|
||||
- [ ] Reject ValueBox elements in push/set (Fail-Fast)
|
||||
- [ ] Ensure DataBox-only inputs
|
||||
- [ ] Implement entry/exit point unpack logic
|
||||
- [ ] Clear error messages for boundary violations
|
||||
|
||||
### Tests
|
||||
- [ ] Test slice operation (15 test cases)
|
||||
- [ ] Test slice edge cases (start > end, out-of-bounds) (5 test cases)
|
||||
- [ ] Test concat operation (10 test cases)
|
||||
- [ ] Test concat empty arrays (3 test cases)
|
||||
- [ ] Test ValueBox/DataBox boundaries (5 test cases)
|
||||
|
||||
### Documentation
|
||||
- [ ] Document slice operation design
|
||||
- [ ] Document concat operation design
|
||||
- [ ] Document ValueBox/DataBox boundary enforcement
|
||||
|
||||
---
|
||||
|
||||
## Week 8: ArrayBox Golden Tests & Performance
|
||||
|
||||
### Golden Test Suite
|
||||
- [ ] Create 50+ test cases for ArrayBox
|
||||
- [ ] Compare Rust-ArrayBox vs Hako-ArrayBox output
|
||||
- [ ] Verify identical output for all test cases
|
||||
- [ ] Test bounds checking Fail-Fast behavior
|
||||
- [ ] Test slice/concat operations
|
||||
|
||||
### Performance Baseline
|
||||
- [ ] Measure push operation time (per 1,000 operations)
|
||||
- [ ] Measure pop operation time (per 1,000 operations)
|
||||
- [ ] Measure get operation time (per 1,000 operations)
|
||||
- [ ] Measure set operation time (per 1,000 operations)
|
||||
- [ ] Compare against Rust-ArrayBox
|
||||
- [ ] Verify performance ≥ 70% of Rust-ArrayBox
|
||||
- [ ] Profile hot paths (bounds checks, capacity expansion)
|
||||
|
||||
### Large-Scale Tests
|
||||
- [ ] Test 10,000 element array (push all, get all)
|
||||
- [ ] Stress test capacity expansion (0 → 10,000)
|
||||
- [ ] Measure memory usage (verify no leaks)
|
||||
- [ ] Test slice on large array (10,000 elements)
|
||||
- [ ] Test concat on large arrays (5,000 + 5,000)
|
||||
|
||||
### Documentation
|
||||
- [ ] Document ArrayBox API reference
|
||||
- [ ] Document usage examples (basic, advanced)
|
||||
- [ ] Document performance characteristics (O(1) amortized, O(n) worst case)
|
||||
- [ ] Document golden test results
|
||||
- [ ] Document performance benchmarks
|
||||
|
||||
### Week 8 Milestone Review
|
||||
- [ ] All ArrayBox methods implemented in Pure Hakorune
|
||||
- [ ] Golden tests: 50+ test cases PASS
|
||||
- [ ] Bounds checking Fail-Fast verified
|
||||
- [ ] Performance ≥ 70% of Rust-ArrayBox
|
||||
- [ ] Large-scale tests (10,000 elements) PASS
|
||||
|
||||
---
|
||||
|
||||
## Phase 20.7 Final Verification
|
||||
|
||||
### Combined Golden Tests
|
||||
- [ ] Run all MapBox golden tests (50+ cases)
|
||||
- [ ] Run all ArrayBox golden tests (50+ cases)
|
||||
- [ ] Verify 100+ total test cases PASS
|
||||
- [ ] Verify deterministic behavior across all tests
|
||||
- [ ] Verify ValueBox/DataBox boundaries enforced
|
||||
|
||||
### Performance Validation
|
||||
- [ ] MapBox performance ≥ 70% of Rust-MapBox
|
||||
- [ ] ArrayBox performance ≥ 70% of Rust-ArrayBox
|
||||
- [ ] Large-scale tests (10,000 elements) practical speed
|
||||
- [ ] No memory leaks detected
|
||||
|
||||
### Integration Tests
|
||||
- [ ] Test MapBox with ArrayBox values
|
||||
- [ ] Test ArrayBox with MapBox elements
|
||||
- [ ] Test nested collections (Map of Arrays, Array of Maps)
|
||||
- [ ] Test with selfhost compiler (use collections in compiler code)
|
||||
|
||||
### Documentation Complete
|
||||
- [ ] README.md finalized (Phase 20.7 overview)
|
||||
- [ ] PLAN.md finalized (implementation details)
|
||||
- [ ] INDEX.md updated (all references correct)
|
||||
- [ ] CHECKLIST.md completed (this file)
|
||||
- [ ] API reference complete (MapBox, ArrayBox)
|
||||
- [ ] Performance benchmarks documented
|
||||
|
||||
### Readiness for Phase 20.8
|
||||
- [ ] Collections ready for GC root scanning
|
||||
- [ ] Reference tracking infrastructure in place
|
||||
- [ ] Deterministic iteration verified (for mark phase)
|
||||
- [ ] No Rust dependencies (except HostBridge)
|
||||
|
||||
---
|
||||
|
||||
## Phase 20.7 Success Criteria (Final)
|
||||
|
||||
### Mandatory (✅ All must be checked)
|
||||
- [ ] MapBox/ArrayBox fully in Pure Hakorune
|
||||
- [ ] No Rust dependencies (except HostBridge)
|
||||
- [ ] Golden tests: 100+ test cases PASS
|
||||
- [ ] Rust-Collections vs Hako-Collections: 100% parity
|
||||
- [ ] Deterministic behavior verified (Symbol < Int < String)
|
||||
- [ ] Iteration order stable
|
||||
- [ ] Provenance tracking works
|
||||
- [ ] Performance ≥ 70% of Rust-Collections
|
||||
- [ ] Basic operations (set/get/push/pop) O(1) average time
|
||||
- [ ] Large-scale data (10,000 elements) practical speed
|
||||
|
||||
### Excluded (⚠️ NOT in Phase 20.7)
|
||||
- [ ] Confirmed: GC not implemented (deferred to Phase 20.8)
|
||||
- [ ] Confirmed: No optimization beyond basic implementation
|
||||
- [ ] Confirmed: Single-threaded only (no concurrency)
|
||||
- [ ] Confirmed: In-memory only (no persistence)
|
||||
|
||||
---
|
||||
|
||||
**Status**: PLANNED
|
||||
**All Checkboxes**: Uncompleted ([ ])
|
||||
**Review Date**: Week 4 (2026-06-22), Week 8 (2026-07-19)
|
||||
**Phase End Date**: 2026-07-19
|
||||
## C‑ABI Bridge (Basic boxes)
|
||||
|
||||
### Flags & Wiring
|
||||
- [ ] Add and document flags: `NYASH_ABI_BASIC_ON`, `NYASH_ABI_BUILTIN_LINK`
|
||||
- [ ] Router: MirCall(Constructor/Method) → rt_boxcall → ABI dispatch（flag gate）
|
||||
- [ ] Built‑in preset: enable static link + LTO（Two‑Layer Exportで inline）
|
||||
|
||||
### Parity Tests (VM/LLVM/Hako)
|
||||
- [ ] String.length/indexOf/substring parity（3×3 cases）
|
||||
- [ ] Array.push/size/get/set/slice parity（5×3 cases）
|
||||
- [ ] Map.set/get/keys/values/size parity（5×3 cases）
|
||||
- [ ] Unknown Box / Capability violation → Fail‑Fast diagnostic fixed
|
||||
|
||||
### Performance
|
||||
- [ ] Benchmark ABI path vs Rust path（≥ 70% target）
|
||||
- [ ] Collect baseline for quick/integration presets
|
||||
|
||||
### Pilot Rollout（段階ON）
|
||||
- [ ] Week 1（quick）: String.length → ABI ON（48h 観測）
|
||||
- [ ] Week 2（quick）: Array.size/push → 追加 ON（48h 観測）
|
||||
- [ ] Week 3‑4（quick）: Map.set/get → 追加 ON（観測）
|
||||
- [ ] Week 5: integration へ横展開（String/Array/Map）
|
||||
- [ ] Week 6‑7: 性能/診断の最終調整
|
||||
- [ ] Week 8: 既定ON 判定／またはロールバック継続
|
||||
|
||||
### Diagnostics / Safety
|
||||
- [ ] `NYASH_ABI_BASIC_DIAG=1` の実装（既定OFF）とログ整形
|
||||
- [ ] retain/release リーク・ガード（テスト専用）
|
||||
- [ ] ロールバック手順の docs 固定（flags=0）
|
||||
|
||||
### CI Matrix（最小拡張）
|
||||
- [ ] quick（ABI ON）ジョブ追加
|
||||
- [ ] 既存 quick/integration（ABI OFF）緑維持
|
||||
|
||||
---
|
||||
Reference in New Issue
Block a user