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

Phase 20.9 Plan — Rust‑less Kernel (Script→C ABI)

Milestones

1. C‑ABI Surface (read‑only first)

• Add/confirm header declarations:
  • hako_gc_stats() -> char* (caller frees with free())
  • hako_gc_roots_snapshot() -> int64_t
  • (Future/gated) hako_gc_collect/start/stop -> void
• Notes: Prototypes exist for GC; extend for console/time/string as needed.

2. LLVM Lowering (llvmlite)

• Lower env.gc.stats/0 → hako_gc_stats (bridge i8* → handle via boxer)
• Lower env.gc.roots_snapshot/0 → hako_gc_roots_snapshot
• Keep control hooks for later (gated, no‑op/Fail‑Fast).

3. GcBox Policy (Hakorune)

• Wrap read‑only calls; add lightweight cadence/log formatting (dev gate).
• Provide sample policy_tick() usage in docs.

4. Canary Smokes (gated)

• LLVM canaries (read‑only): SMOKES_GC_ENV_LLVM=1
  • stats expects JSON with keys, roots_snapshot expects integer
• VM parity exists via adapter; LLVM confirms script→C ABI path.

5. Diagnostics Parity

• Maintain short lines for NOT_FOUND/UNSUPPORTED/VALIDATION on both VM and LLVM.
• Ensure canaries fail with short lines when symbols missing (gate remains OFF by default).

Acceptance Checklist

• stats/roots_snapshot canaries PASS under LLVM with provided symbols
• GcBox.stats()/roots_snapshot() return same shapes across VM/LLVM
• collect/start/stop are defined, gated, and do not silently succeed
• Docs updated (bridge plan/roadmap/usage) and gates documented

Rollback

• Remove/disable C shims; LLVM canaries remain gated OFF; VM path unaffected.

Links

• ./CHECKLIST.md, ./README.md
• ../../../development/architecture/abi/hakorune-c-abi-bridge.md
• ../../../development/architecture/gc/llvm-extern-plan.md