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

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).
+