# Self‑Hosting Quickstart (Phase 15 — Resume)

This note shows how to run the hakorune self‑host compiler MVP to emit AST JSON / MIR(JSON v0) and execute it with the current VM line. The flow keeps defaults unchanged and uses small, opt‑in flags for development.

## Layout
- Compiler MVP: `lang/src/compiler/entry/compiler.hako`（移行済。旧パスは互換のみ）
- Runtime helpers (dev): `apps/selfhost-runtime/`
- Mini‑VM samples (dev): `apps/selfhost/vm/`

## Run the self‑host compiler（Official runner path）
Use the runner’s selfhost pipeline with parent→child ENV forwarding. Defaults stay unchanged; all flags are opt‑in.

Examples (safe, short, quiet):
```
# Emit minimal AST JSON via pipeline v2 (header must contain {"version", "kind"})
NYASH_DISABLE_PLUGINS=1 \
NYASH_USE_NY_COMPILER=1 \
NYASH_NY_COMPILER_MIN_JSON=1 \
NYASH_NY_COMPILER_CHILD_ARGS="--pipeline-v2" \
NYASH_NY_COMPILER_EMIT_ONLY=1 \
NYASH_NY_COMPILER_SKIP_PY=1 \
NYASH_JSON_ONLY=1 \
timeout 5 ./target/release/hakorune --backend vm apps/examples/string_p0.hako

# Emit minimal MIR(JSON v0) (const→ret)
NYASH_DISABLE_PLUGINS=1 \
NYASH_USE_NY_COMPILER=1 \
NYASH_NY_COMPILER_MIN_JSON=1 \
NYASH_NY_COMPILER_CHILD_ARGS="--emit-mir" \
NYASH_NY_COMPILER_EMIT_ONLY=1 \
NYASH_NY_COMPILER_SKIP_PY=1 \
NYASH_JSON_ONLY=1 \
timeout 5 ./target/release/hakorune --backend vm apps/examples/string_p0.hako
```

Parent→child ENV mapping（official）
- `NYASH_NY_COMPILER_MIN_JSON=1` → child gets `-- --min-json`
- `NYASH_SELFHOST_READ_TMP=1`    → child gets `-- --read-tmp` (reads `tmp/ny_parser_input.ny`)
- `NYASH_NY_COMPILER_STAGE3=1`   → child gets `-- --stage3`
- `NYASH_NY_COMPILER_CHILD_ARGS="..."` → child gets extra args verbatim
- `NYASH_EMIT_TRACE=1`           → child gets `-- --emit-trace` (dev trace: 1行だけ [emit] 出力。最後のJSON行は不変)
- `NYASH_PREFER_CFG=1|NYASH_PREFER_CFG2=1` → child gets `-- --prefer-cfg` or `--prefer-cfg2`（CFG優先/材化あり）
- Timeouts / quiet pipe:
  - `NYASH_NY_COMPILER_TIMEOUT_MS=2000`（default）
  - `NYASH_JSON_ONLY=1`（suppress logs, print JSON only）

Direct run (dev only; requires allowing file using):
```
timeout 5 \
  NYASH_DISABLE_PLUGINS=1 NYASH_ENABLE_USING=1 NYASH_ALLOW_USING_FILE=1 NYASH_USING_AST=1 NYASH_JSON_ONLY=1 \
  ./target/release/hakorune --backend vm lang/src/compiler/entry/compiler.hako -- --min-json
  
# Optional: pipeline v2 (emit-only)
timeout 5 \
  NYASH_DISABLE_PLUGINS=1 NYASH_USING=1 NYASH_ALLOW_USING_FILE=1 NYASH_USING_STRATEGY=prelude NYASH_JSON_ONLY=1 \
  ./target/release/hakorune --backend vm lang/src/compiler/entry/compiler.hako -- --min-json --pipeline-v2
```

## Execute MIR(JSON v0)
Use the VM line (Rust) or PyVM harness as needed.

Rust VM (default):
```
./target/release/hakorune --backend vm apps/examples/json_query/main.hako
```

PyVM reference (when verifying parity):
```
NYASH_VM_USE_PY=1 ./target/release/hakorune --backend vm apps/examples/json_query/main.hako
```

LLVM harness (llvmlite):
```
NYASH_LLVM_USE_HARNESS=1 ./target/release/hakorune --backend llvm apps/examples/json_query/main.hako
```

Notes:
- For self‑host emitted JSON, route the file to your runner pipeline or a small loader script (dev only). Keep defaults unchanged in CI (no new jobs required).

## One‑shot dev smoke
Run quick selfhost checks (JSON header, normalization shapes, VM/LLVM parity when available):

```
tools/smokes/v2/run.sh --profile quick --filter '*selfhost*'
```

Notes on normalization
- Emitter delegates to `JsonProgramBox` which ensures stable shapes for Return/If/Loop/Call/Compare/Logical and always appends `meta.usings`.

## Flags (dev)
- Known rewrite default ON (userbox only, strict guards): `NYASH_REWRITE_KNOWN_DEFAULT=0|1`
- Router trace: `NYASH_ROUTER_TRACE=1`
- KPI sampling: `NYASH_DEBUG_KPI_KNOWN=1` (+ `NYASH_DEBUG_SAMPLE_EVERY=N`)
- Local SSA trace: `NYASH_LOCAL_SSA_TRACE=1`

## Acceptance (P6 resume)
- quick/integration remain green.
- Minimal self‑host emit→execute path PASS in a dev job (no CI change).
- No default behavior changes; all diagnostics under env flags.