hakorune/docs/guides/source-extensions.md

Source Extensions Policy — .nyash vs .hako (Interim)

Intent

• Keep development stable while Hakorune VM (v1 Dispatcher/IR/φ) is brought up.
• Avoid cross‑contamination between frontends; converge at MIR.

Execution Mapping (current)

• .nyash → Nyash VM (Rust): NyashParser → MIR → VM. Full runtime/plugins path.
• .hako → Hakorune VM (v1): JSON v1 Dispatcher/IR/φ（bring‑up coverage; guarded extern）.
• verify (MIR v1) → Hakorune primary, Core fallback for diagnosis.

Resolver/Include/Normalize

• Using: unify to text‑merge (merge_prelude_text). AST prelude merge is retired.
• Include: language‑level unsupported; quick profile treats include as ERROR. Preinclude is test‑harness only（verify の include fallback は撤去済み）。
• Normalize (inline/dev): CRLF→LF, redundant ; } trimmed, tolerant local at line head in Hakorune inline drivers.

Fail‑Fast Guards

• Hako in Nyash VM: rejected by default (Fail‑Fast). Toggle: HAKO_FAIL_FAST_ON_HAKO_IN_NYASH_VM=0 for dev only.
• Extern (Hako provider): HAKO_V1_EXTERN_PROVIDER=1; optional C‑ABI tag/bridge with HAKO_V1_EXTERN_PROVIDER_C_ABI=1 (default OFF).

Why two extensions now?

• Same language intent, but different stability constraints at the frontend boundary:
  • .hako through NyashParser caused parse/timeout/alias issues historically.
  • We intentionally stopped that path and direct .hako to Hakorune VM while it matures.

Migration Plan (phased)

1. P2: IR iteration complete; φ table robust; dispatcher loop scan‑free; extern canaries PASS without harness shim.
2. P3: verify default → Hakorune (Core fallback); document toggles and remove ad‑hoc heuristics.
3. Prep: introduce stable Nyash→MIR v1 emit route to feed Hakorune VM when (and if) we want .nyash on hv1.
4. Deprecation: warn on .nyash (opt‑in), then Fail‑Fast once hv1 parity is sufficient; remove legacy code in a later phase.

Best Practices (now)

• Prefer alias/modules over path using; avoid include in source.
• Keep quotes ASCII ("); avoid trailing semicolons before }.
• For verify, pass JSON via env (NYASH_VERIFY_JSON) and parse last numeric line as rc.
• Inline（-c）ドライバは alias のみで構成（include 不要）。