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

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)

• 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)
• Header prototypes (memory API): hako_mem_alloc/realloc/free
• Header ownership note: hako_gc_stats() returns char* to be freed by hako_mem_free()
• (Docs) Alignment guarantee and thread-safety note for memory API — see docs/development/architecture/abi/hakorune-c-abi-bridge.md
• (Docs) TLV/flat ABI notes for future control hooks and utilities — see docs/development/architecture/abi/hakorune-c-abi-bridge.md
• Diagnostics policy: NOT_FOUND/UNSUPPORTED/VALIDATION short lines remain mandatory

2) LLVM Lowering (llvmlite)

• Lower env.gc.stats/0 → hako_gc_stats (bridge i8* → handle)
• Lower env.gc.roots_snapshot/0 → hako_gc_roots_snapshot
• Free boxed C string via hako_mem_free after boxing (leak防止)
• (Optional) Provide from_i8_string_take(i8*) to elide a free (future)
• Canary smokes prepared under gate (see SMOKES.md)

3) Control Hooks (gated)

• Registry entries added for env.gc.{collect,start,stop} (SSOT only)
• Lowering: implement as no‑op or explicit FAIL under gate (no silent fallback)
• (Docs) Gate: NYASH_LLVM_GC_CONTROL_FAIL=1 → emit stable message via debug trace and return 0 (dev only)

4) Policy Box (Hakorune)

• GcBox skeleton and policy_tick() example (dev only)
• Cadence thresholds and logging templates (doc + sample)

5) Parity & Safety

• VM↔LLVM parity for read‑only GC externs (shape equality)
• Diagnostics parity (short lines + details) for missing handlers/symbols

6) C Shim (libc first)

• Implement hako_mem_alloc/realloc/free (libc backed)
• Implement hako_gc_stats / hako_gc_roots_snapshot (read‑only, minimal JSON/int)
• Platform notes (Windows/Unix CRT differences) — prefer hako_mem_free only

Docs

• hakorune-c-abi-bridge.md (this plan)
• gc/llvm-extern-plan.md (GC read‑only path first)
• gc/policy-vs-data-plane.md (separation)
• phase-20.9/ABI_MAP.md（extern→C symbol）
• phase-20.9/SMOKES.md（LLVM canary）

Notes

• Keep gates OFF by default. Roll out in small, reversible steps.