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.

• 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=llvmlite|crate|native
  • Selects the backend used by tools/ny_mir_builder.sh for --emit obj|exe.
  • Default: llvmlite (Python harness tools/llvmlite_harness.py).
  • crate: uses ./target/release/ny-llvmc (build with cargo build -p nyash-llvm-compiler --release).
  • native: reserved for future Hako-native builder.
  • Linking extras for --emit exe: pass via HAKO_AOT_LDFLAGS (e.g., -static), ny-llvmc consumes --libs.

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）