# 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
- [x] Canonicalize header path in docs/tools (bridge/ABI_v1/ABI_MAP) and provide compatibility shim.
- [x] Add CI header canonical check (WARN mode).
- [x] Normalize EXE linker diagnostics to short lines.
- [x] Map console/time to direct C ABI (`hako_console_log`, `hako_time_now_ms`).
- [x] Ensure GC externs use direct C ABI (`hako_gc_stats`, `hako_gc_roots_snapshot`).
- [ ] Expand policy doc for extern naming & migration examples (`env.*` → `hako_*`).
- [x] Expand policy doc for extern naming & migration examples (`env.*` → `hako_*`).
- [x] Plan STRICT mode for header canonical check (enable `CI_STRICT=1`) — docs/README に手順追記、集約: `tools/ci/run_local_checks.sh`。
- [x] 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)
- [x] Integration-core parity: env.local.get exists — tools/smokes/v2/profiles/integration-core/env_local_get_exists_core.sh
- [x] Failure diagnostics (EXE): mir_emit_failed — tools/smokes/v2/profiles/quick/llvm/diagnostics_mir_emit_failed_exe.sh