selfhost(pyvm): MiniVmPrints – prefer JSON route early-return (ok==1) to avoid fallback loops; keep default behavior unchanged elsewhere

docs/guides/README.md

@@ -2,6 +2,9 @@
 
 Nyashプログラミング言語の利用者向けガイドとチュートリアルです。
 
+Quick Links
+- Docsの書き方（小さく・リンク駆動・3層）: contributing-docs.md
+
 ## 🚀 はじめに
 - `getting-started.md` - Nyashを始めるためのクイックガイド
 
@@ -27,4 +30,4 @@ Nyashプログラミング言語の利用者向けガイドとチュートリア
 1. `getting-started.md` から始める
 2. `tutorials/` のチュートリアルを順番に
 3. `examples/` で実践的なコードを学ぶ
-4. 特定用途（WASM等）は各ガイドへ
+4. 特定用途（WASM等）は各ガイドへ

docs/guides/box-design-checklist.md

@@ -0,0 +1,41 @@
+# Box Design Checklist (docs-only)
+
+Use this checklist when introducing a new Box or evolving an existing one.
+
+## Lifecycle
+- Define birth parameters and side effects (allocation, registration).
+- State machine: initial → running → closed → fini; reentrancy rules.
+- `fini()` idempotent; post-fini methods: error vs no-op.
+
+## Ownership & Sharing
+- Who owns the resource? Is there a LeaseBox form?
+- Mutation boundaries (single-thread/Actor only?).
+- Cross-thread usage: mailbox-only or direct allowed?
+
+## Concurrency
+- Blocking APIs: provide `try_*` and `*_timeout(ms)`.
+- Cancellation: accept CancelToken/Deadline; ensure prompt unblock.
+- Busy-wait forbidden; document waiting strategy (Phase‑0 cooperative / later OS).
+
+## Close Semantics
+- What does `close()` mean? Which ops fail after close?
+- Draining behavior and End marker shape.
+- Double close and use-after-close handling.
+
+## Observability
+- Events to emit (op, ok, extra fields) and Box ID.
+- Env toggles (e.g., `NYASH_*_TRACE=1`).
+- Expected order/causality in traces.
+
+## Capabilities & Affinity
+- External authorities needed (fs/net/io/thread).
+- Thread affinity constraints (creator thread / any / Actor only).
+
+## Performance
+- Hot vs cold paths; offer ThinBox where needed.
+- Complexity of operations; backpressure strategy.
+
+## Errors & Types
+- Error shape (Bool/Option/Result) and consistency with ecosystem.
+- Type expectations (runtime tags vs future static types).
+

docs/guides/box-patterns.md

@@ -0,0 +1,49 @@
+# Box Patterns (dev guide; docs-only)
+
+Status: design notes to standardize reusable Box idioms. No runtime/spec change during the feature‑pause.
+
+## OwnershipBox / LeaseBox
+- Intent: make ownership vs borrowing explicit for resource Boxes.
+- Rules
+  - OwnershipBox owns the underlying handle; calls `fini()` on drop.
+  - LeaseBox references an owned Box without taking responsibility to `fini()`.
+  - Upgrading a lease to ownership must be explicit (and validated).
+- Smells avoided: double-close, leaked handles, implicit transfer.
+
+## CancelTokenBox / DeadlineBox
+- Intent: structured cancellation and time limits across waiting APIs.
+- Rules
+  - Token can be passed to blocking APIs (Channel/Select/Waiter) to abort waits.
+  - DeadlineBox wraps an absolute time; APIs accept either `token` or `deadline`.
+  - Cancellation is idempotent; multiple cancel calls are safe.
+- Effects
+  - Waiting ops return promptly with a well-typed cancel/timeout indicator.
+
+## CapabilityBox
+- Intent: define minimal authority (I/O, net, thread, fs) explicitly.
+- Rules
+  - Boxes that access external capabilities must declare the capability dependency.
+  - Tests can substitute Noop/Mock capability Boxes.
+- Effects
+  - Principle of least privilege; easier sandboxing and auditing.
+
+## AffinityBox
+- Intent: encode thread/runtime affinity constraints.
+- Rules
+  - Annotate Boxes that must be used on their creator thread or via Actor mailbox.
+  - Violations produce early, explicit errors (not UB).
+- Effects
+  - Predictable behavior across concurrency boundaries.
+
+## ObservableBox
+- Intent: unify tracing/metrics hooks.
+- Rules
+  - Emit JSONL events with `ts`, `box_id`, `op`, `ok`, and domain-specific fields.
+  - Allow opt-in (`NYASH_*_TRACE=1`) and keep logs stable for tooling.
+- Effects
+  - Cross-cutting visibility with one schema; simpler troubleshooting.
+
+## Composition Tips
+- Separate hot/cold paths: ThinBox (hot) vs RichBox (full) to avoid overhead on the critical path.
+- Prefer immutable handles + message passing across threads (Actor) to avoid races.
+- Keep `birth/fini` idempotent; document post-fini behavior (no-op vs error).

docs/guides/contributing-docs.md

@@ -0,0 +1,34 @@
+# Contributing Docs — Small, Linked, 3‑Layer
+
+Status: Stable  |  Updated: 2025‑09‑21  |  Scope: Docs structure/policy
+
+TL;DR
+- Keep docs small. Use 3 layers: Overview → Reference → Details.
+- No duplication: overview links to the single canonical reference.
+- Every page shows Status/Updated/Scope and has a short summary.
+
+Layers
+- Overview (design one‑pager)
+  - What/Why/How in bullets, ≤1 page; links to Reference/Details/Guides.
+- Reference (docs/reference/)
+  - Canonical spec: invariants, API, acceptance rules. Precise and stable.
+- Details (docs/design/ or docs/development/…)
+  - Background, alternatives, rationale. Optional; link from overview only.
+
+Authoring Rules
+- One canonical spec per topic (in reference/). Others must link to it.
+- Each directory has a README.md that points to its key one‑pagers.
+- Cross‑links go under “See also” (≤3 items, relative paths).
+
+One‑pager Template
+- Title / Status / Updated / Scope
+- TL;DR (3–5 lines)
+- What (spec bullets)
+- How (integration points, ownership boundaries)
+- Links (Reference / Details / Guides)
+- Notes (constraints / future work)
+
+Examples
+- Using→Loader overview: docs/design/using-loader-integration.md
+- Mini‑VM roadmap: docs/development/roadmap/phases/phase-17-loopform-selfhost/MINI_VM_ROADMAP.md
+

docs/guides/core-principles.md

@@ -1,6 +1,6 @@
 # Nyash Core Principles — Minimal Syntax, Zero Runtime, Visual Flow
 
-Status: design-only during freeze (no implementation changes)
+Status: design-only during the feature‑pause (no implementation changes)
 
 Core (one page summary)
 - Minimal syntax: `{ … }` + `->` + `|args|` or `_` for flow; guard chains as the canonical first-match form. No new `match` construct; normalize instead.
@@ -32,12 +32,12 @@ Observability (spec hooks; design-only)
 - `NYASH_SCOPE_TRACE=1|json`: enter/exit + captures (JSONL: `sid`, `caps`, `ret`).
 - `NYASH_FLOW_TRACE=1`: desugared steps like `t0=B0(); t1=B1(t0);`.
 
-Runtime/API additions (docs-only at freeze)
+Runtime/API additions (docs-only during the feature‑pause)
 - `StringBox/Utf8Cursor`: `toDigitOrNull(base=10)`, `toIntOrNull()` — compile to simple comparisons/arithmetic.
 - Guard sugar: Range (`'0'..'9'`) and CharClass (`Digit`, `AZ`, `az`, `Alnum`, `Space`) — compile to bound checks.
 
-Acceptance & guardrails (freeze)
-- “No new grammar beyond sugar” and “no new VM opcodes” as hard rules during freeze.
+Acceptance & guardrails (feature‑pause)
+- “No new grammar beyond sugar” and “no new VM opcodes” as hard rules during the feature‑pause.
 - Golden texts (Ny → MIR fragments) to lock compatibility where practical.
 - Lint proposals are documentation-only: single-use scope, long `->` chains, duplicated side effects.
 
@@ -46,4 +46,3 @@ Related docs
 - design/flow-blocks.md — arrow flow + anonymous blocks
 - reference/language/match-guards.md — guard chains + range/charclass sugar
 - reference/language/strings.md — UTF‑8 first; proposed digit helpers
-

docs/guides/dev-local-alias.md

@@ -0,0 +1,31 @@
+# Dev Sugar: @name = expr as local declaration
+
+Status: dev-only, pre-expand sugar (no spec change)
+
+Goal
+- Speed up local declarations during development without impacting readability in shared code.
+
+Syntax (dev sugar)
+- Line-head only:
+  - `@name = expr` → `local name = expr`
+  - `@name: Type = expr` → `local name: Type = expr`
+
+Rules
+- Valid only at line start (leading spaces allowed). Inside expressions it is ignored.
+- Declaration-only: not allowed for reassignments; use `name = expr` for assignments.
+- Semantics are identical to `local` (scope/cleanup unchanged). Zero runtime cost.
+
+Enablement
+- Use the provided pre-expander script for dev: `tools/dev/at_local_preexpand.sh`.
+- Example:
+  - `tools/dev/at_local_preexpand.sh apps/tests/dev_sugar/at_local_basic.nyash > /tmp/out.nyash`
+  - `NYASH_VM_USE_PY=1 ./target/release/nyash --backend vm /tmp/out.nyash`
+
+Style
+- Shared/committed code: prefer explicit `local` (nyfmt may normalize @ to `local`).
+- Dev/repl/prototype: `@` is acceptable to reduce noise.
+
+Notes
+- This is a text pre-expansion; it does not change the parser or MIR.
+- The pattern is conservative to avoid collisions with comments and inline usages.
+