# 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.