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

docs/private/roadmap/phases/phase-20.9/CHECKLIST.md

@@ -0,0 +1,55 @@
+# Phase 20.9 — Hakorune‑Driven C ABI (Script First)
+
+Status
+- Planning & scaffolding. No behavior change until gates are enabled.
+
+Goals
+- Hakorune→LLVM line can call C ABI directly (Rust optional). Start with GC observability; expand carefully.
+
+Gates
+- Default OFF. Enable via environment/test gates only (no behavior change unless explicitly gated).
+
+Milestones
+
+## 1) ABI Surface (script→C)
+- [x] Define symbol mapping (read‑only GC): `env.gc.stats/0` → `hako_gc_stats`, `env.gc.roots_snapshot/0` → `hako_gc_roots_snapshot` (see ABI_MAP.md)
+- [x] Header prototypes (memory API): `hako_mem_alloc/realloc/free`
+- [x] Header ownership note: `hako_gc_stats()` returns `char*` to be freed by `hako_mem_free()`
+ - [x] (Docs) Alignment guarantee and thread-safety note for memory API — see docs/development/architecture/abi/hakorune-c-abi-bridge.md
+ - [x] (Docs) TLV/flat ABI notes for future control hooks and utilities — see docs/development/architecture/abi/hakorune-c-abi-bridge.md
+- [x] Diagnostics policy: NOT_FOUND/UNSUPPORTED/VALIDATION short lines remain mandatory
+
+## 2) LLVM Lowering (llvmlite)
+- [x] Lower `env.gc.stats/0` → `hako_gc_stats` (bridge i8* → handle)
+- [x] Lower `env.gc.roots_snapshot/0` → `hako_gc_roots_snapshot`
+- [x] Free boxed C string via `hako_mem_free` after boxing (leak防止)
+- [ ] (Optional) Provide `from_i8_string_take(i8*)` to elide a free (future)
+- [x] Canary smokes prepared under gate (see SMOKES.md)
+
+## 3) Control Hooks (gated)
+- [x] Registry entries added for `env.gc.{collect,start,stop}` (SSOT only)
+- [x] Lowering: implement as no‑op or explicit FAIL under gate (no silent fallback)
+- [x] (Docs) Gate: `NYASH_LLVM_GC_CONTROL_FAIL=1` → emit stable message via debug trace and return 0 (dev only)
+
+## 4) Policy Box (Hakorune)
+- [x] GcBox skeleton and `policy_tick()` example (dev only)
+- [ ] Cadence thresholds and logging templates (doc + sample)
+
+## 5) Parity & Safety
+- [x] VM↔LLVM parity for read‑only GC externs (shape equality)
+- [x] Diagnostics parity (short lines + details) for missing handlers/symbols
+
+## 6) C Shim (libc first)
+- [x] Implement `hako_mem_alloc/realloc/free` (libc backed)
+- [x] Implement `hako_gc_stats` / `hako_gc_roots_snapshot` (read‑only, minimal JSON/int)
+- [x] Platform notes (Windows/Unix CRT differences) — prefer `hako_mem_free` only
+
+Docs
+- [x] hakorune-c-abi-bridge.md (this plan)
+- [x] gc/llvm-extern-plan.md (GC read‑only path first)
+- [x] gc/policy-vs-data-plane.md (separation)
+ - [x] phase-20.9/ABI_MAP.md（extern→C symbol）
+ - [x] phase-20.9/SMOKES.md（LLVM canary）
+
+Notes
+- Keep gates OFF by default. Roll out in small, reversible steps.