hakorune/docs/phases/phase-10.1/phase_plan.md

Phase 10.1 – Plugin Unification Path (MIR→JIT/AOT via C ABI)

This plan refines how we leverage the existing plugin system (BID-FFI) to unify JIT and AOT (EXE) paths using a single C ABI surface.

Goals

• Unify calls from JIT and AOT to the same C ABI (nyrt_* / nyplug_*).
• Convert builtin Boxes to Plugin Boxes in small steps (read-only first).
• Produce a minimal standalone EXE via static linking after unification.

Feasibility Summary

• JIT: emit calls to extern "C" symbols (no change in semantics, only target).
• AOT: emit .o with unresolved nyrt_* / nyplug_* and link with libnyrt.a + plugin .a.
• Compatibility: guard with NYASH_USE_PLUGIN_BUILTINS and keep HostCall fallback.

Phase Breakdown

10.1: Plugin PoC + C ABI base (1 week)

• Deliverables:
  • Minimal headers: nyrt.h (runtime), nyplug_array.h (ArrayBox plugin).
  • ArrayBox as a plugin (cdylib + staticlib), ABI version functions.
  • VM loader integration and NYASH_USE_PLUGIN_BUILTINS switch.
  • Smoke: new/len/push/get working via plugin.
• DoD:
  • Array plugin works on VM path; perf regression ≤10% on micro bench.

10.2: JIT Lowering unification (Array first) (1–1.5 weeks)

• Deliverables:
  • IRBuilder: emit_plugin_invoke(type_id, method_id, args, sig).
  • LowerCore BoxCall for Array routes to plugin_invoke (events/stats intact).
  • Feature-flagged enablement: NYASH_USE_PLUGIN_BUILTINS=1.
• DoD:
  • JIT execution of Array read/write (policy-constrained) via plugin path.
  • Behavior parity with HostCall; no regressions on CI smoke.

10.2b: JIT Coverage Unblockers (0.5–1 week)

• Goal:
  • Remove practical blockers so plugin_invoke can be exercised in typical Nyash functions and .o can be produced.
• Deliverables:
  • Lowering for NewBox of pluginized builtins → translate new <Box>() to plugin birth() via emit_plugin_invoke(type_id, 0, argc=1 recvr-param) with appropriate handle threading.
  • Treat Print/Debug as no-op/hostcall for v0 to avoid function-wide skip.
  • Keep conservative skip policy by default; document NYASH_AOT_ALLOW_UNSUPPORTED=1 for validation-only .o emission.
• DoD:
  • Minimal demo function with String.length() compiled by JIT (Cranelift) and .o emitted. Plugin events visible under JIT.

10.3: Broaden plugin coverage + Compatibility (2 weeks)

• Targets: String/Integer/Bool/Map (read-only first).
• Deliverables:
  • Pluginized Boxes and plugin_invoke lowering for BoxCall.
  • HostCall route retained; whitelist-driven co-existence.
  • Added smoke and microbenches comparing HostCall vs Plugin.
• DoD:
  • ≥5 builtin Boxes pluginized; NYASH_USE_PLUGIN_BUILTINS=1 green on smoke.

10.4: AOT/EXE minimal pipeline (2–3 weeks)

• Deliverables:
  • ObjectWriter path to emit .o with unresolved nyrt_*/nyplug_*.
  • libnyrt.a minimal runtime + selected plugin .a.
  • Link scripts and nyc build-aot proof-of-concept.
  • Hello World-level standalone EXE on Linux/macOS.
• DoD:
  • nyc build-aot <file.nyash> -o app runs without JIT/VM.
  • Basic debug info and minimal unwind.

10.5: Python Integration (moved; separate phase)

• Python work is deferred to 10.5 and builds on the plugin/AOT foundation.

Flags & Compatibility

• NYASH_USE_PLUGIN_BUILTINS=1 – enables plugin path for builtin Boxes.
• NYASH_JIT_HOSTCALL=1 – preserves HostCall path for comparison.
• Call conv alignment: x86_64 SysV, aarch64 AAPCS64, Win64.
• ABI version checks: nyrt_abi_version(), nyplug_*_abi_version() hard-fail on mismatch.

Risks & Mitigations

• ABI drift: minimal headers + version checks.
• Linking complexity: start with the smallest set (Array/Print/GC-minimal), expand gradually.
• Performance: keep RO-first; benchmark and fall back to HostCall if needed.
• Windows linkage: prioritize Linux/macOS, then handle Win specifics in a follow-up task.
• JIT coverage: adopt staged lowering (NewBox→birth, Print/Debug no-op) to clear blockers; retain strict skip policy otherwise.

References

• c_abi_unified_design.md
• implementation_steps.md
• ../phase-10.5/ (Python integration)

---

Everything is Plugin → unified paths for JIT and AOT.