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

Phase 20.9 — Rust‑less Kernel via Hakorune → LLVM → C ABI

Goal

• Remove Rust from the runtime execution path (kernel) by driving calls from Hakorune scripts through the LLVM line to a thin C ABI.
• Keep plugins/HostBridge/loader in Rust (unchanged). Only the kernel path becomes Rust‑optional.

Scope (this phase)

• Read‑only GC externs: env.gc.stats/0 (JSON string), env.gc.roots_snapshot/0 (i64).
• Utilities (minimal): console log/warn/error, time (now_ms), local env (env.local.get), string bridging (handle ⇄ i8*).
• Control hooks (collect/start/stop): defined + gated; may be no‑ops or Fail‑Fast until implemented.

Out‑of‑Scope (keep Rust)

• Plugin loader/registries, HostBridge v1 router, high‑level Box/Type systems.

Why

• Thin‑Rust policy: keep data plane (traversal/barriers/safepoints) out of the critical policy loop.
• Self‑hosting: make collection cadence/logging scriptable in Hakorune (GcBox).

Key Docs

• Checklist: ./CHECKLIST.md
• Tasks & Rules: ./TASKS.md
• C‑ABI bridge plan: ../../../development/architecture/abi/hakorune-c-abi-bridge.md
• LLVM extern plan (GC): ../../../development/architecture/gc/llvm-extern-plan.md
• Policy vs Data Plane: ../../../development/architecture/gc/policy-vs-data-plane.md

Acceptance (MVP)

• Hakorune call("env.gc.stats/0") and call("env.gc.roots_snapshot/0") reach C symbols under --backend llvm (gated canaries PASS).
• GcBox.stats()/roots_snapshot() return same shape across VM/LLVM (read‑only parity). PASS
• collect/start/stop exist as gated calls; do not silently fallback; emit short diagnostics. PASS

Gates & Safety

• All new paths default OFF; enable via smoke gates/environment.
• Diagnostics use short, stable lines (NOT_FOUND/UNSUPPORTED/VALIDATION). Quiet mode suppresses short lines.
• In EXE mode, linker diagnostics are normalized to short lines (SMOKES_ERR: symbol_missing[:name]); set SMOKES_KEEP_LD=1 to keep full LD output.
• CI STRICT: tooling scripts accept CI_STRICT=1 to upgrade WARN to FAIL (e.g., header path canonical check, dotted symbol check).

STRICT Plan (flip criteria)

• Stage 1 (current): WARN-only
  • Scripts: tools/ci/check_header_canonical.sh, tools/ci/checks/aot_dotted_symbol_check.sh
  • Aggregator: tools/ci/run_local_checks.sh (use locally; no GitHub integration yet)
• Stage 2 (pre‑flip): Dry-run in CI for ≥1 サイクル、false positive を除去
• Stage 3 (flip to STRICT): CI_STRICT=1 で FAIL に昇格
  • 前提: ドキュメント/修正例が揃い、既知の例外が0件

Risks & Rollback

• Ownership/memory rules (char* free) must be strictly documented and adhered.
• If LLVM canary fails (symbols missing), keep gates OFF; VM path remains unaffected.
• Rollback is trivial: remove/disable C shims; VM continues to function.