docs: restore docs/private/roadmap from 7b4908f9 (Phase 20.31)

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

@@ -0,0 +1,34 @@
+# 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`.

docs/private/roadmap/phases/phase-20.9/CHECKLIST.md

@@ -0,0 +1,55 @@
+# Phase 20.9 — Hakorune‑Driven C ABI (Script First)
+
+Status
+- Planning & scaffolding. No behavior change until gates are enabled.
+
+Goals
+- Hakorune→LLVM line can call C ABI directly (Rust optional). Start with GC observability; expand carefully.
+
+Gates
+- Default OFF. Enable via environment/test gates only (no behavior change unless explicitly gated).
+
+Milestones
+
+## 1) ABI Surface (script→C)
+- [x] Define symbol mapping (read‑only GC): `env.gc.stats/0` → `hako_gc_stats`, `env.gc.roots_snapshot/0` → `hako_gc_roots_snapshot` (see ABI_MAP.md)
+- [x] Header prototypes (memory API): `hako_mem_alloc/realloc/free`
+- [x] Header ownership note: `hako_gc_stats()` returns `char*` to be freed by `hako_mem_free()`
+ - [x] (Docs) Alignment guarantee and thread-safety note for memory API — see docs/development/architecture/abi/hakorune-c-abi-bridge.md
+ - [x] (Docs) TLV/flat ABI notes for future control hooks and utilities — see docs/development/architecture/abi/hakorune-c-abi-bridge.md
+- [x] Diagnostics policy: NOT_FOUND/UNSUPPORTED/VALIDATION short lines remain mandatory
+
+## 2) LLVM Lowering (llvmlite)
+- [x] Lower `env.gc.stats/0` → `hako_gc_stats` (bridge i8* → handle)
+- [x] Lower `env.gc.roots_snapshot/0` → `hako_gc_roots_snapshot`
+- [x] Free boxed C string via `hako_mem_free` after boxing (leak防止)
+- [ ] (Optional) Provide `from_i8_string_take(i8*)` to elide a free (future)
+- [x] Canary smokes prepared under gate (see SMOKES.md)
+
+## 3) Control Hooks (gated)
+- [x] Registry entries added for `env.gc.{collect,start,stop}` (SSOT only)
+- [x] Lowering: implement as no‑op or explicit FAIL under gate (no silent fallback)
+- [x] (Docs) Gate: `NYASH_LLVM_GC_CONTROL_FAIL=1` → emit stable message via debug trace and return 0 (dev only)
+
+## 4) Policy Box (Hakorune)
+- [x] GcBox skeleton and `policy_tick()` example (dev only)
+- [ ] Cadence thresholds and logging templates (doc + sample)
+
+## 5) Parity & Safety
+- [x] VM↔LLVM parity for read‑only GC externs (shape equality)
+- [x] Diagnostics parity (short lines + details) for missing handlers/symbols
+
+## 6) C Shim (libc first)
+- [x] Implement `hako_mem_alloc/realloc/free` (libc backed)
+- [x] Implement `hako_gc_stats` / `hako_gc_roots_snapshot` (read‑only, minimal JSON/int)
+- [x] Platform notes (Windows/Unix CRT differences) — prefer `hako_mem_free` only
+
+Docs
+- [x] hakorune-c-abi-bridge.md (this plan)
+- [x] gc/llvm-extern-plan.md (GC read‑only path first)
+- [x] gc/policy-vs-data-plane.md (separation)
+ - [x] phase-20.9/ABI_MAP.md（extern→C symbol）
+ - [x] phase-20.9/SMOKES.md（LLVM canary）
+
+Notes
+- Keep gates OFF by default. Roll out in small, reversible steps.

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

@@ -0,0 +1,41 @@
+# 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
+- [x] stats/roots_snapshot canaries PASS under LLVM with provided symbols
+- [x] GcBox.stats()/roots_snapshot() return same shapes across VM/LLVM
+- [x] collect/start/stop are defined, gated, and do not silently succeed
+- [x] 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

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

@@ -0,0 +1,48 @@
+# 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.

docs/private/roadmap/phases/phase-20.9/SMOKES.md

@@ -0,0 +1,41 @@
+# Phase 20.9 — LLVM Canary Smokes
+
+Purpose
+- Verify wiring of script externs → C symbols (read‑only GC) on the LLVM line under gates.
+
+Gates
+- `SMOKES_GC_ENV_LLVM=1` — enables GC canaries for LLVM.
+
+Tests
+- `tools/smokes/v2/profiles/quick/core/gc_env_stats_llvm.sh`
+  - Expects JSON containing `"safepoints"`.
+- `tools/smokes/v2/profiles/quick/core/gc_env_roots_snapshot_llvm.sh`
+  - Expects a single integer line.
+- Utilities (gate: `SMOKES_UTILS_LLVM=1`)
+  - `tools/smokes/v2/profiles/quick/core/console_warn_error_llvm.sh` — expects `warn-line` and `error-line` in output
+  - `tools/smokes/v2/profiles/quick/core/env_local_get_llvm.sh` — expects value of `SMOKES_ENV_LOCAL_GET`
+  - `tools/smokes/v2/profiles/quick/core/env_local_get_missing_llvm.sh` — expects short warn `NOT_FOUND` (stderr), handle remains `0`
+  - `tools/smokes/v2/profiles/quick/llvm/time_now_ms_exe.sh` — EXE canary; prints plausible ms value (> 2000-01-01)
+  - `tools/smokes/v2/profiles/quick/llvm/diagnostics_mir_emit_failed_exe.sh` — EXE compile path emits `SMOKES_ERR: mir_emit_failed`
+  - Parity:
+    - `tools/smokes/v2/profiles/quick/llvm/parity_console_warn_error_vm_llvm.sh`
+    - `tools/smokes/v2/profiles/quick/llvm/parity_env_local_get_vm_llvm.sh`
+
+- Integration‑core（代表）
+  - `tools/smokes/v2/profiles/integration-core/utils_console_warn_error_core.sh` — VM↔LLVM warn/error parity
+  - `tools/smokes/v2/profiles/integration-core/utils_env_local_get_missing_core.sh` — VM↔LLVM env.local.get missing parity
+  - `tools/smokes/v2/profiles/integration-core/env_local_get_exists_core.sh` — VM↔LLVM env.local.get exists parity
+
+Prereqs
+- `hako_gc_stats` / `hako_gc_roots_snapshot` symbols must be available (linked) when using the harness.
+- If not present, keep gates OFF (tests remain SKIP).
+
+- Notes
+- VM path has read‑only handlers for observability; LLVM canaries are wiring checks only in 20.8/20.9.
+- Utilities: console.warn/error write to stderr; filters normalize noise and do not assert order.
+- `env.local.get` (missing): current behavior prints `0` (boxed handle=0). Future work may use short diagnostics.
+- When LLVM harness compilation fails, smokes now emit stable short lines:
+  - `SMOKES_ERR: mir_emit_failed` (MIR JSON emission)
+  - `SMOKES_ERR: llvm_compile_failed` (ny-llvmc compilation/link)
+  - `SMOKES_ERR: llvm_exe_missing` (post-compile artifact missing)
+  Use `SMOKES_KEEP_LD=1` to keep linker diagnostics.

docs/private/roadmap/phases/phase-20.9/STRUCTURE.md

@@ -0,0 +1,19 @@
+# Phase 20.9 — Structure (Lang Line)
+
+Decision
+- Introduce `lang/` at the repository root to host the C ABI kernel and related artifacts (no Rust here).
+- Keep Rust engine/crates under `crates/` and `src/` untouched. The `lang` line is a separate box.
+
+Layout
+- `lang/` — top-level
+  - `c-abi/` — headers and libc-backed shim for canaries
+    - `README.md` — responsibilities and contracts
+  - `README.md` — scope and principles
+
+Rationale
+- Clear separation of concerns: script-driven ABI vs. Rust runtime internals.
+- Makes it easy to package/link the C shim with external harnesses without dragging Rust sources.
+
+Notes
+- Migration is incremental: existing headers/shims remain in `include/` and `c/abi/` until references are updated.
+- CI/docs should point to `lang/c-abi` once stabilized; older paths deprecated after a grace period.

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

@@ -0,0 +1,51 @@
+# 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