pyvm: split op handlers into ops_core/ops_box/ops_ctrl; add ops_flow + intrinsic; delegate vm.py without behavior change

net-plugin: modularize constants (consts.rs) and sockets (sockets.rs); remove legacy commented socket code; fix unused imports
mir: move instruction unit tests to tests/mir_instruction_unit.rs (file lean-up); no semantic changes
runner/pyvm: ensure using pre-strip; misc docs updates

Build: cargo build ok; legacy cfg warnings remain as before

docs/reference/constraints.md

@@ -0,0 +1,58 @@
+# Nyash Constraints & Temporary Limitations
+
+This is a living index of known constraints. Each entry includes status and references to tests and code. Update this file when a constraint is added or lifted.
+
+Legend
+- Status: Stable | Temporary | Resolved | Experimental
+- Impact: VM / LLVM / PyVM / Macro / Parser
+
+Entries
+
+## CF-JOIN-0001 — If-join PHI variables limit
+- Status: Resolved
+- Summary: If-join used to effectively handle at most two same‑name variable assignments per join when emitting PHI groups.
+- Impact: LLVM harness (PHI wiring)
+- Fix: Finalize‑PHI wiring + join result observation; normalized to handle N variables.
+- Tests: `tools/test/smoke/llvm/ir_phi_hygiene_if_phi_ret.sh`, `tools/test/smoke/mir/hints_join_result_three_vars_smoke.sh`
+- Notes: Keep IR hygiene smokes minimal in CI; more exhaustive coverage can run locally.
+
+## CF-PHI-0002 — Empty PHI sanitize switch
+- Status: Temporary
+- Summary: Text‑level sanitizer drops empty PHI rows before LLVM parse.
+- Impact: LLVM harness only
+- Gate: `NYASH_LLVM_SANITIZE_EMPTY_PHI=1`
+- Exit criteria: PHI wiring guarantees no empty PHIs across Loop/If/Match; remove sanitize path.
+- Tests: `tools/test/smoke/llvm/ir_phi_empty_check.sh`
+
+## CF-LOOP-0006 — Nested bare blocks with break/continue in loops
+- Status: Resolved
+- Summary: Previously, a `break`/`continue` inside a nested bare block (`{ ... }`) within a loop could bypass loop-aware lowering in certain cases.
+- Impact: MIR builder (LoopBuilder vs generic block handling)
+- Fix: LoopBuilder now lowers `Program` nodes by recursing through statements with termination checks; `break/continue` inside nested blocks route to the loop header/exit uniformly.
+- Tests: `tools/test/smoke/macro/loop_nested_block_break_output_smoke.sh`
+
+## CF-MATCH-0003 — Scrutinee single evaluation
+- Status: Stable
+- Summary: Scrutinee is evaluated once and stored in a gensym (e.g., `__ny_match_scrutinee_X`).
+- Impact: Parser/Normalizer/All backends
+- Tests: `tools/test/golden/macro/match_literal_basic.expanded.json`, output smokes under `tools/test/smoke/macro/`.
+- Notes: Golden comparison may normalize gensym names in the future to reduce brittleness.
+
+## EXC-PFX-0004 — Postfix catch/cleanup precedence
+- Status: Stable (Stage‑3 gate for parser acceptance)
+- Summary: Postfix attaches to the immediately preceding expression (call/chain) and stops further chaining. Normalizes to a single TryCatch.
+- Impact: Parser/Normalizer/All backends
+- Gate: `NYASH_PARSER_STAGE3=1` (direct parsing); `NYASH_CATCH_NEW=1` (sugar normalization)
+- Tests: `tools/test/smoke/macro/expr_postfix_catch_cleanup_output_smoke.sh`, `tools/test/smoke/mir/hints_scope_trycatch_smoke.sh`, `src/tests/parser_expr_postfix_catch.rs`
+
+## MACRO-CAPS-0005 — Macro sandbox capabilities (io/net/env)
+- Status: Stable MVP
+- Summary: Macro child runs in a sandbox. Only minimal boxes and console externs allowed. IO/NET require caps; env access controlled via ctx/env.
+- Impact: PyVM macro child / Macro runner
+- Env: `NYASH_MACRO_CAP_{IO,NET,ENV}`; `NYASH_MACRO_SANDBOX=1`
+- Tests: macro goldens/smokes; env‑tag demo (`tools/test/golden/macro/env_tag_string_user_macro_golden.sh`)
+
+How to add an entry
+1) Allocate an ID with a prefix domain (CF/EXC/MACRO/RES/…)
+2) Fill status, impact, gates, tests
+3) Reference PR/commit in the change log (optional)