hakorune/docs/ENV_VARS.md

Environment Variables — Quick Reference (Phase 22.1)

This document lists the environment flags introduced or used by the Phase 22.1 work. Defaults are OFF and behavior remains unchanged unless noted.

• NYASH_JSON_ONLY=0|1

  • Quiet JSON pipelines: suppresses RC: and routine logs on stdout (diagnostics still go to stderr).
  • Used by Stage‑B → Program(JSON) emit to keep the output clean for downstream processing.

• HAKO_USING_SSOT=0|1

  • Enables the SSOT resolver gate in the runner pipeline.
  • When ON, resolution first consults the SSOT bridge (modules-only MVP). If not resolved, it falls back to the existing resolver.
  • Trace: set NYASH_RESOLVE_TRACE=1 to see [using/ssot] tags.

• HAKO_USING_SSOT_HAKO=0|1

  • Optional: within the SSOT bridge, call the Hako box UsingResolveSSOTBox.resolve(name, ctx) via the VM.
  • MVP passes { modules, using_paths, cwd } in ctx (modules is consulted). IO is not performed in the box.
  • Requires nyash binary present; guard remains OFF by default.

Relative inference (SSOT)

• Default OFF: HAKO_USING_SSOT_RELATIVE=1 enables a minimal relative candidate synthesis (cwd → using_paths). When multiple candidates exist and NYASH_USING_STRICT=1, resolution delegates to legacy resolver (behavior unchanged).
• Ambiguous list size: HAKO_USING_SSOT_RELATIVE_AMBIG_FIRST_N=<N> customizes how many candidates are shown in trace (default 3, bounded 1–10).

Notes on SSOT ctx (expansion plan)

• The bridge constructs a context with:

  • modules (Map<String,String>) — exact name → path mapping
  • using_paths (Array) — resolution bases (MVP: hint only)
  • cwd (String) — caller’s directory (MVP: hint only)

• Hako box will progressively leverage using_paths/cwd for relative inference (planned; defaults remain unchanged until enabled).

• HAKO_TLV_SHIM=0|1

  • Enables an identity TLV round‑trip at the end of argument encoding for plugin calls.
  • Requires building with --features tlv-shim to link the optional crate nyash-tlv.
  • Default OFF; when OFF, the buffer is returned unchanged.

• tlv-shim (Cargo feature)

  • cargo build --features tlv-shim links the optional nyash-tlv crate.
  • Without this feature, HAKO_TLV_SHIM=1 has no effect and the original path is used.

TLV shim diagnostics

• HAKO_TLV_SHIM_TRACE=0|1
  • When 1 (with tlv-shim feature), emit a concise trace tag [tlv/shim:<Box>.<method>] for shimmed calls.
  • Default: minimal noise（MapBox.set のみ）。詳細な対象はフィルタで拡張。
• HAKO_TLV_SHIM_FILTER=
  • Filter which calls are traced（例: MapBox.set,ArrayBox.push）。<Box>.<method> または method のみで一致。
  • 未設定時は最小（MapBox.set のみ）。
• HAKO_TLV_SHIM_TRACE_DETAIL=0|1
  • When 1, emits [tlv/shim:detail argc=N].

Examples (TLV trace)

• HAKO_TLV_SHIM=1 HAKO_TLV_SHIM_TRACE=1 HAKO_TLV_SHIM_FILTER=ArrayBox.push
• HAKO_TLV_SHIM=1 HAKO_TLV_SHIM_TRACE=1 HAKO_TLV_SHIM_FILTER=MapBox.get
• HAKO_TLV_SHIM=1 HAKO_TLV_SHIM_TRACE=1 HAKO_TLV_SHIM_FILTER=ArrayBox.push,MapBox.get (複数指定)
• HAKO_SHOW_CALL_LOGS=1 HAKO_CALL_TRACE=1 HAKO_CALL_TRACE_FILTER=env.console.log（テストランナーのフィルタ無効＋extern だけ観測）

Core Thinning I (Phase 22.2) — Plugin C wrapper (design hook)

• HAKO_PLUGIN_LOADER_C_WRAP=0|1
  • When 1, emits a design-stage tag [cwrap:invoke:<Box>.<method>] at the plugin invocation site and then proceeds with the normal path.
  • Default OFF; no behavior change.
• HAKO_PLUGIN_LOADER_C_WRAP_FILTER=
  • Filter for cwrap tags（例: MapBox.set,ArrayBox.push）。<Box>.<method> または method のみで一致。

Core Thinning I (Phase 22.2) — C-core probe (design hook)

• HAKO_C_CORE_ENABLE=0|1
  • When 1, emits a tag [c-core:invoke:<Box>.<method>] and (when built with feature c-core) calls a thin C probe (nyash-c-core) before proceeding with the normal path.
  • Default OFF; behavior unchanged.
• HAKO_C_CORE_TARGETS=
  • Targets to probe（例: MapBox.set,ArrayBox.push）。未設定時は MapBox.set のみ。
  • Build note: enable C-core with cargo build --release -p nyash-rust --features c-core.
  • Examples:
    • HAKO_C_CORE_ENABLE=1 HAKO_C_CORE_TARGETS=ArrayBox.push
    • HAKO_C_CORE_ENABLE=1 HAKO_C_CORE_TARGETS=ArrayBox.len,ArrayBox.length

Related toggles used by smokes/tools (for parity with runner/test wrappers):

Call/route unified trace (optional)

• HAKO_CALL_TRACE=0|1
  • When ON, emits [call:<target>.<method>] for both plugin calls and extern calls.
  • Default OFF; logs go to stderr.
• HAKO_CALL_TRACE_FILTER=
  • Restrict [call:] logs to specific targets.
  • Matches <target>.<method> or bare method.
  • Examples:
    • HAKO_CALL_TRACE_FILTER=MapBox.set (method-only)
    • HAKO_CALL_TRACE_FILTER=env.console.log,MapBox.set (mix target+method)
• HAKO_SHOW_CALL_LOGS=0|1
  • When 1, test runner disables its default log filter so [call:] traces appear in output.
• NYASH_PARSER_STAGE3=1, HAKO_PARSER_STAGE3=1, NYASH_PARSER_ALLOW_SEMICOLON=1
• NYASH_ENTRY_ALLOW_TOPLEVEL_MAIN=1
• NYASH_DISABLE_NY_COMPILER=1, HAKO_DISABLE_NY_COMPILER=1

LLVM backend selector (builder wrapper)

• NYASH_LLVM_BACKEND=auto|crate|llvmlite|native

  • Selects the backend used by tools/ny_mir_builder.sh for --emit obj|exe.
  • Default: auto（優先順位: crate（ny-llvmc が存在すれば既定）→ native（llc がある場合）／llvmlite は明示指定時のみ）。
  • crate: ./target/release/ny-llvmc を使用（cargo build -p nyash-llvm-compiler --release）。推奨の本線（EXE/AOT）。
  • llvmlite: Python ハーネス tools/llvmlite_harness.py（内部用途。外部から使う場合は明示指定）
  • native: 将来の Hako‑native builder 用に予約。
  • --emit exe のリンク追加ライブラリは HAKO_AOT_LDFLAGS で渡す（例: -static）。ny‑llvmc は --libs 経由で受理。
  • 備考: crate 経路では ny_main の戻り値（i64）がプロセスの終了コードに反映（rc mapping）。

• NYASH_LLVM_NATIVE_TRACE=0|1

  • When 1, dumps the native IR to stderr for debugging.
  • Used with native backend to inspect generated LLVM IR before optimization.
  • Default OFF; only active when NYASH_LLVM_BACKEND=native is set.

• HAKO_LLVM_CANARY_NORMALIZE=0|1

  • 開発/カナリア専用の正規化スイッチ。1 のとき、最小の JSON 形状差（schema_version=1 → "1.0"、blocks.inst → instructions、const の ty/value 包装）を自動補正してからビルドします。
  • 既定は 0（無効）。既存ツールの挙動は変わりません。NYASH_CLI_VERBOSE=1 のとき形状ヒントを [ny-llvmc/hint] で出力します。

Name mapping note (EXE link convenience)

• nyash.console.* は C リンク時にシンボル名 nyash_console_* に正規化される（ドット→アンダースコア）。
  • 例: externcall nyash.console.log(i8*) → C シンボル nyash_console_log。
  • 最小 C ランタイム（Phase 22.3）の nyash-kernel-min-c は nyash_console_log(char*) を提供（設計段階）。

Kernel Minimal C Runtime (Phase 22.3 — design)

• NYASH_KERNEL_C_MIN=0|1
  • Reserved toggle for enabling the minimal C runtime shims（design‑stage; defaults OFF）
  • Build: cargo build --release -p nyash-kernel-min-c（not linked by default）

ENV consolidation (aliases)

• NY compiler path
  • Primary: NYASH_USE_NY_COMPILER=0|1
  • Accepted aliases (deprecated; prints a one‑time warning):
    • NYASH_DISABLE_NY_COMPILER=1 → equivalent to NYASH_USE_NY_COMPILER=0
    • HAKO_DISABLE_NY_COMPILER=1 → equivalent to NYASH_USE_NY_COMPILER=0
• LLVM opt level
  • Primary: NYASH_LLVM_OPT_LEVEL
  • Accepted alias (deprecated; one‑time warning): HAKO_LLVM_OPT_LEVEL
• Gate‑C (Core direct route)
  • Primary: NYASH_GATE_C_CORE
  • Accepted alias (deprecated; one‑time warning): HAKO_GATE_C_CORE

Notes

• Primary keys are preferred and will be kept. Aliases remain accepted for a grace period and emit a concise deprecation line once per process. NYASH_FAIL_FAST
• Type: 0|1 (default: 1)
• Purpose: Global Fail‑Fast policy for runtime fallbacks in Rust layer. When 1, prohibits silent or alternate‑route fallbacks and panics with a stable tag (e.g., [failfast/provider/filebox:], [failfast/ssot/]). Set to 0 temporarily during bring‑up or canaries that rely on legacy routes.

Hakorune Stage‑B (include policy)

• VM backend currently does not support include statements in Hako execution. Stage‑B focuses on producing Program(JSON v0) (one‑line) and avoids includes.
• Program(JSON) → MIR(JSON) uses the Rust Gate‑C path by default. Hako MirBuilder is opt‑in and introduced gradually (registry/internal toggles).

MirBuilder toggles (opt‑in)

• HAKO_MIR_BUILDER_INTERNAL=0|1 (default: 1)
  • Enable internal lowers (Return/If/Compare/BinOp/Method minimal). When 0, only delegate path is used (if enabled).
• HAKO_MIR_BUILDER_REGISTRY=0|1 (default: 1)
  • Enable registry‑driven lowering (pattern names like if.compare.intint, return.binop.intint, return.method.arraymap).
• HAKO_MIR_BUILDER_DELEGATE=0|1 (default: 0)
  • Delegate to Runner (--program-json-to-mir) instead of internal lowers. Useful for bring‑up; keep OFF for self‑host canaries.
• HAKO_MIR_BUILDER_SKIP_LOOPS=0|1 (default: 0)
  • Skip heavy loop lowers (lower_loop_sum_bc, lower_loop_count_param, lower_loop_simple) when 1. Diagnostic/bring‑up aid; no behavior change when unset.
• HAKO_MIR_BUILDER_REGISTRY_ONLY=<name> (optional)
  • Restrict registry dispatch to a single pattern name (e.g., return.method.arraymap) for diagnostics.

MirBuilder (min) alias — bring‑up helper

• Module alias: hako.mir.builder.min → lang/src/mir/builder/MirBuilderMinBox.hako
  • Minimal entry that only loads lightweight lowers (e.g., return.method.arraymap, return.int).
  • Tags: emits [mirbuilder/min:<pattern>] on success. Default behavior unchanged; use explicitly in tests/tools.

FileBox provider policy（dev overrides）

• Baseline: FileBox は ring‑1 常備（core‑ro）として登録されます。プラグイン未配置でも panic 経路にはならず、Fail‑Fast が ON の場合は明示タグで失敗します（例: [failfast/provider/filebox:*]）。
• NYASH_FILEBOX_MODE=auto|core-ro|plugin-only — provider selection mode（default auto; with plugins disabled, resolves to core‑ro）
• NYASH_FILEBOX_ALLOW_FALLBACK=0|1 — When 1, allows core‑ro fallback even if Fail‑Fast is ON (use sparingly; defaults OFF).
• JSON pipelines: NYASH_JSON_ONLY=1 also permits core‑ro fallback under Fail‑Fast (quiet structured I/O).

Examples (Fail‑Fast tags and safe overrides)

• Default (Fail‑Fast=1): core‑ro フォールバックを禁止（プロバイダ未設定時に失敗）
  • 例外ログ: [failfast/provider/filebox:auto-fallback-blocked]
  • 実行例:

    # will fail fast without plugins
    ./target/release/hakorune --backend vm apps/tests/filebox_sample.hako
    

• Bring‑up（局所的に許可）: NYASH_FILEBOX_ALLOW_FALLBACK=1 で core‑ro を許可
  • 実行例:

    NYASH_FILEBOX_ALLOW_FALLBACK=1 ./target/release/hakorune --backend vm apps/tests/filebox_sample.hako
    

• JSON パイプ（静音）: NYASH_JSON_ONLY=1 を併用して整形済み JSON のみを stdout に出す
  • 実行例:

    NYASH_JSON_ONLY=1 NYASH_FILEBOX_ALLOW_FALLBACK=1 ./target/release/hakorune --backend vm apps/tests/emit_program_json.hako
    

Provider policy（共通）

• HAKO_PROVIDER_POLICY=strict-plugin-first|safe-core-first|static-preferred
  • Auto モード時の選択ポリシーを制御（既定: strict-plugin-first）。
  • safe-core-first/static-preferred は ring‑1（静的/core‑ro）を優先、利用不可時のみプラグインにフォールバック。
• Box個別のモード指定（例: FileBox）
  • <BOX>_MODE=auto|ring1|plugin-only（例: NYASH_FILEBOX_MODE）
  • <BOX>_ALLOW_FALLBACK=0|1（Fail‑Fast 例外。局所許可）
  • 既存の FileBox 変数はそのまま有効。共通パターンとして今後は他Boxにも拡張予定。

Selfhost‑first wrapper toggles (Stage‑B → MirBuilder)

• HAKO_SELFHOST_BUILDER_FIRST=0|1 (default: 0)
  • When 1, tools like tools/hakorune_emit_mir.sh try Stage‑B → MirBuilder(Hako) first, and only fall back to the Rust delegate when necessary.
• HAKO_SELFHOST_NO_DELEGATE=0|1 (default: 0)
  • When 1, forbids delegate fallback in the wrapper. If the Hako MirBuilder fails, the wrapper fails fast (useful to validate the self‑host path). VM/AOT fast-path toggles (bench/dev only)
• NYASH_VM_FAST=0|1
  • Enables small VM micro-optimizations used in micro-benchmarks (no behavior changes in normal runs):
    • new StringBox("const") fast path (registry bypass when safe)
    • StringBox.length/size returning i64 directly (avoid boxing)
  • Default OFF.
• NYASH_LLVM_FAST=0|1
  • Enables AOT lowering tweaks in ny-llvmc (opt-in, benches only):
    • StringBox.length/size lowered to extern helper returning i64 (no boxing)
  • Default OFF. Guarded in ny-llvmc; legacy lowering remains default.

MirBuilder toggles (trace and JsonFrag)

• HAKO_MIR_BUILDER_TRACE=0|1 (default: 0)
  • When 1, emits concise builder tags like [mirbuilder/internal/*] from Hako lowers. Errors remain visible regardless; this flag controls informational tags.
• HAKO_MIR_BUILDER_LOOP_JSONFRAG=0|1 (default: 0)
  • Enable JsonFrag minimal MIR assembly in loop adapters/lowers (structure observation only).
• HAKO_MIR_BUILDER_JSONFRAG_NORMALIZE=0|1 (default: 0)
  • Normalize JsonFrag output for stable canaries (const grouping, phi placement, numeric canonicalization).
• HAKO_MIR_BUILDER_LOOP_RETURN=string|map (default: string)
  • Controls the return type of the loop adapter JsonFrag path. string returns MIR(JSON) text; map returns a MapBox like { mir: <string> }.

Provider diagnostics

• HAKO_PROVIDER_TRACE=0|1 (default: 0)
  • When 1, forces provider selection tags like [provider/select:FileBox ring=1 src=static] to appear even under NYASH_JSON_ONLY=1. EXE argv bridge (crate backend)
• NYASH_EXE_ARGV=0|1
  • When 1, the ny-llvmc entry wrapper calls nyash.env.argv_get() to obtain an ArrayBox of process arguments and passes it to Main.main(args).
  • Default OFF（互換維持）。OFF の場合は空の ArrayBox が渡されます。
  • VM 実行は従来どおり環境変数経由（NYASH_SCRIPT_ARGS_HEX_JSON / NYASH_SCRIPT_ARGS_JSON / NYASH_ARGV）で受け取り、Main.main(args) に配列を渡します。
• MIR optimizer dev gate
• NYASH_MIR_DISABLE_OPT=0|1 (alias: HAKO_MIR_DISABLE_OPT)
  • When 1, disables all MIR optimizer passes (diagnostics only). Default OFF.
  • 用途: 最適化の誤変換切り分けや、退行時の一時回避（既定不変）。