hakorune/docs/private/roadmap/phases/phase-20.26/PLAN.md

Phase 20.26 — Final Rust Consolidation + hakmem (Plan)

Purpose

• Consolidate remaining Rust lines to Floor-only responsibilities and move legacy backends to archive with deprecations.
• Keep day-to-day defaults unchanged and green; all flips are opt-in and guarded.

Scope (Phase 20.26)

• Deprecate and archive legacy Rust LLVM (inkwell) backend; prefer ny-llvmc (llvmlite harness).
• Keep Rust as Floor (CLI, I/O, process, FFI) and shift decision/normalization to Hakorune boxes where feasible.
• Add small helper gates for memory (hakmem) without changing defaults.

Non-Goals

• No default behavior changes for users. No removal of legacy code without a full deprecation window (1 release).
• No broad refactor of working paths outside agreed guardrails.

Workstreams

1. Deprecation warnings (inkwell)

   • Print a one-time deprecate banner when feature llvm-inkwell-legacy path executes.
   • Docs: mark inkwell as legacy and point to ny-llvmc.

2. Archive and gate (inkwell)

   • Move src/backend/llvm/compiler/** → archive/legacy/llvm-inkwell/** (paths preserved via #[path] when feature active).
   • Keep feature gates and tests green; no behavior change.

3. Runner plan adoption (thin)

   • Introduce RunnerPlanBuilder in lang: build a plan (decision only). Rust applies the plan.
   • Start as opt-in (HAKO_RUNNER_PLAN=1), no behavior change by default.
   • v0: action ExecuteCore/ExecuteVM を適用（Gate‑C/VM）。ExecuteNyLlvmc/Boxes は advisory（将来拡張）。

4. hakmem integration (gate only)

   • Keep libc as default allocator. Provide --mem hakmem/HAKO_C_ABI_ALLOC=hakmem placeholder route.
   • No functional switch yet; only routing and docs.

Milestones

• M1 (A): Deprecation banner + docs scaffold + CURRENT_TASK updated
• M2 (B): Archive move, feature-gated paths compile; quick stays green
• M3 (C): RunnerPlan opt-in wiring; no default change
• M4 (D): hakmem gate documented and observed (no default flip)

Risks & Mitigations

• Risk: Path drift between archived code and callers → Mitigate with #[path] glue and feature tests.
• Risk: Surprise behavior changes → Keep all flips opt-in; add stable tags; Fail-Fast on ambiguity.

Toggles (ENV/CLI)

• --vm-backend llvm|vm|mir (ENV: HAKO_VM_BACKEND) — unchanged
• HAKO_LLVM_USE_HARNESS=1 — prefer ny-llvmc harness path
• HAKO_C_ABI_ALLOC={libc|hakmem} — allocator gate (default: libc)
• HAKO_RUNNER_PLAN=1 — opt-in RunnerPlan path (decision in lang; v0 は ExecuteCore/ExecuteVM のみ適用)

Acceptance (Phase 20.26 complete)

• quick/integration green with defaults unchanged
• inkwell path prints deprecate banner when used; harness path preferred in docs
• legacy LLVM code archived and feature-gated; build remains green
• docs updated (README/PLAN/CHECKLIST, env toggles, migration notes)