hakorune/docs/development/strategies/de-rust-roadmap.md

De‑Rust Roadmap (Phase 21.9+)

Purpose: reduce Rust surface (non‑plugin) while keeping correctness and reversibility. Make Hakorune (Hako) the primary host for parsing/building/executing; keep Rust for kernel/ABI/thin wrappers.

Phases

Phase 0 — Archive (low risk)

• Target: Rust LLVM backend (src/backend/llvm) — deprecated in favor of Python llvmlite.
• Action: move to archive/rust-llvm-backend/ with a clear RESTORE.md.
• Acceptance: cargo build --release (default features) remains green; quick smokes green.
• Revert: git mv archive/rust-llvm-backend/llvm src/backend/.

Phase 1 — Quick Wins (1–2 months)

• hv1_inline → Hako parity (already functionally covered; keep as perf path).
• MIR interpreter parity check; route Primary to Hako VM.
• TLV codec → C shim (FFI) with thin Rust wrapper.
• LLVM wrapper → Hako/C harness (Python stays primary until Hako IR is ready).

Deliverables & Tests

• hv1_inline: parity canaries = phase2037/flow + phase2170/state; add HAKO_VERIFY_DISABLE_INLINE opt-out (optional).
• TLV C shim: round‑trip tests (encode→decode) on representative payloads; FFI error mapping spec.
• MIR interpreter: keep as diagnostic path; parity sample set (const/binop/compare/branch/jump/ret/phi/mir_call minimal).
• LLVM wrapper: unify CLI entry; ensure NYASH_LLVM_USE_HARNESS=1 path stays green.

Phase 2 — Core Thinning (2–4 months)

• Plugin loader thin C wrapper (dlopen/dlsym), unify host ABI.
• Basic boxes (Array/Map/File) small C core (handle‑based), keep Rust shim.
• Resolver/Using: SSOT in Hako; runner uses shared policy.

SSOT for Using/Resolver (summary)

• Resolution order: modules (nyash.toml) → relative path inference → not found (warn) with verbose details.
• Analyzer/HakoCheck follows the same order; runner shares policy helpers. No path‑literal using in strict profiles.

Phase 3 — Long‑haul (3–6 months)

• Python llvmlite → Hako IR builder + C ABI.
• Parser/MIR builder fully Hako‑first; Rust becomes fallback.
• NyKernel minimal C runtime (BoxCall dispatcher + collections + file).

Principles

• Guard everything by env/features; defaults unchanged.
• Keep changes reversible (small diffs, RESTORE docs, fallbacks).
• Test gates: quick smokes + representative hv1/hakovm parity.

Today (suggested)

1. Stage Phase‑0 move as a script (not auto‑run) + RESTORE.md.
2. Add phase docs (docs/private/roadmap/phases/phase-21.9/PLAN.md).
3. Keep CI/dev instructions intact (no build break when features=none).

Test Strategy (gates)

• Quick: tools/smokes/v2/profiles/quick/core/* (phase2037 flow, phase2170 state) — green.
• Verify routing: HAKO_VERIFY_PRIMARY=hakovm (default); hv1_inline perf path parity (env toggles only).
• Build: cargo build --release (default features); LLVM paths are opt‑in.
• Docs: keep RESTORE steps for any archived parts; small diffs, easy rollback.