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<String>) — 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=<CommaSeparatedList>
  - 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=<CommaSeparatedList>
  - 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=<CommaSeparatedList>
  - 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=<CommaSeparatedList>
  - 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]`
  - 実行例:
    ```sh
    # will fail fast without plugins
    ./target/release/hakorune --backend vm apps/tests/filebox_sample.hako
    ```
- Bring‑up（局所的に許可）: `NYASH_FILEBOX_ALLOW_FALLBACK=1` で core‑ro を許可
  - 実行例:
    ```sh
    NYASH_FILEBOX_ALLOW_FALLBACK=1 ./target/release/hakorune --backend vm apps/tests/filebox_sample.hako
    ```
- JSON パイプ（静音）: `NYASH_JSON_ONLY=1` を併用して整形済み JSON のみを stdout に出す
  - 実行例:
    ```sh
    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.
  - 用途: 最適化の誤変換切り分けや、退行時の一時回避（既定不変）。