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

ABI Mapping — Script Externs to C Symbols (Phase 20.9)

Mapping (read‑only first)

• env.gc.stats/0 → hako_gc_stats() → returns char* (JSON). Caller must free via hako_mem_free().
• env.gc.roots_snapshot/0 → hako_gc_roots_snapshot() → returns int64_t.

Console (utilities)

• env.console.log/1 → hako_console_log(const char*) → returns int64_t(0)
• env.console.warn/1 → hako_console_warn(const char*) → returns int64_t(0)
• env.console.error/1 → hako_console_error(const char*) → returns int64_t(0)

Future/Gated

• env.gc.collect/0 → hako_gc_collect() → void
• env.gc.start/0 → hako_gc_start() → void
• env.gc.stop/0 → hako_gc_stop() → void

String Bridging (LLVM harness)

• Boxing i8* → handle: nyash.box.from_i8_string(i8*) -> i64

• Pointer out of handle: nyash.string.to_i8p_h(i64) -> i8*

• Plan (optional): provide hako_string_from_i8/hako_string_to_i8p as direct shims later.

• Ownership & Diagnostics

• char* returns are newly allocated by callee; caller owns and frees via hako_mem_free().

• On error, return NULL (for char*) or sentinel and set hako_last_error with stable short lines (NOT_FOUND/UNSUPPORTED/VALIDATION).

Env/Local

• env.local.get/1 → hako_env_local_get(const char*) → returns char* (UTF‑8). Caller must free via hako_mem_free().
  • Missing key: returns NULL, sets TLS hako_last_error to NOT_FOUND.
  • LLVM lowering emits a short warn NOT_FOUND and boxes NULL as handle 0.

Notes

• Header (canonical): lang/c-abi/include/hako_hostbridge.h contains the prototypes.
• Compatibility shim remains at include/hako_hostbridge.h (includes the canonical header).
• Lowering: src/llvm_py/instructions/mir_call.py binds the externs under --backend llvm.