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

Phase 20.9 Tasks & Rules — C ABI Kernel

Status: Active (Phase 20.9)

Objectives

• Stabilize LLVM→C ABI execution (EXE/JIT) with Fail‑Fast diagnostics.
• Migrate C ABI kernel to lang/c-abi/ with clear ownership & contracts.
• Codify rules for extern mapping and diagnostics.

Rules (Box‑First / Fail‑Fast)

• Canonical Header:
  • Use lang/c-abi/include/hako_hostbridge.h as the single source of truth.
  • include/hako_hostbridge.h is a compatibility shim only.
  • CI: run tools/ci/check_header_canonical.sh (WARN now; STRICT later).
• Extern Mapping:
  • Avoid dotted C symbols in AOT (e.g., env.console.log). Map to direct C symbols (hako_console_log).
  • Policy: script extern → unified name in C ABI (hako_*).
  • GC/time/mem/console: hako_gc_stats/hako_gc_roots_snapshot/hako_mem_*/hako_console_log/hako_time_now_ms.
• Diagnostics (short, stable):
  • Missing symbol (EXE): SMOKES_ERR: symbol_missing[:<name>].
  • MIR emit failure: SMOKES_ERR: mir_emit_failed.
  • Compiler/link fail (other): SMOKES_ERR: llvm_compile_failed.
  • VM invalid extern: normalized to SMOKES_ERR: invalid_inst ....

Work Items

• Canonicalize header path in docs/tools (bridge/ABI_v1/ABI_MAP) and provide compatibility shim.
• Add CI header canonical check (WARN mode).
• Normalize EXE linker diagnostics to short lines.
• Map console/time to direct C ABI (hako_console_log, hako_time_now_ms).
• Ensure GC externs use direct C ABI (hako_gc_stats, hako_gc_roots_snapshot).
• Expand policy doc for extern naming & migration examples (env.* → hako_*).
• Expand policy doc for extern naming & migration examples (env.* → hako_*).
• Plan STRICT mode for header canonical check (enable CI_STRICT=1) — docs/README に手順追記、集約: tools/ci/run_local_checks.sh。
• Add a lint to flag dotted C symbol emission in AOT IR (future) — stub: tools/ci/checks/aot_dotted_symbol_check.sh (WARN; STRICT later).

Proposed C API Additions (pending)

• hako_env_local_get(const char* key) -> char* [landed]
  • Returns a newly allocated UTF‑8 string of the environment value or NULL if not found.
  • Ownership: caller must free via hako_mem_free().
  • Diagnostics: on NULL, set TLS hako_last_error to a short, stable reason (NOT_FOUND or VALIDATION). LLVM lowering emits warn NOT_FOUND.
  • Thread‑safety: required.
  • Notes: prefer NULL + short diagnostic over empty string. Avoid CRT mismatch.

References

• README.md, PLAN.md, CHECKLIST.md, SMOKES.md
• tools/ci/check_header_canonical.sh
• tools/smokes/v2/lib/llvm_exec.sh

Smokes/Parity (added in this phase)

• Integration-core parity: env.local.get exists — tools/smokes/v2/profiles/integration-core/env_local_get_exists_core.sh
• Failure diagnostics (EXE): mir_emit_failed — tools/smokes/v2/profiles/quick/llvm/diagnostics_mir_emit_failed_exe.sh