AotPrep collections_hot matmul tuning and bench tweaks

docs/guides/exception-handling.md

@@ -2,11 +2,35 @@ Exception Handling — Postfix catch / cleanup (Stage‑3)
 
 Summary
 - Nyash adopts a flatter, postfix-first exception style:
-  - try is deprecated. Use postfix `catch` and `cleanup` instead.
+  - There is no `try` statement in the language spec. Use postfix `catch` and `cleanup` instead.
   - `catch` = handle exceptions from the immediately preceding expression/call.
   - `cleanup` = always-run finalization (formerly finally), regardless of success or failure.
 - This matches the language’s scope unification and keeps blocks shallow and readable.
 
+Spec Clarifications (Stage‑3)
+- Acceptance gates and profiles
+  - Expression‑postfix: `NYASH_PARSER_STAGE3=1` enables `expr catch(...) {..} cleanup {..}` on calls/chains.
+  - Block‑postfix: `NYASH_BLOCK_CATCH=1` or Stage‑3 enables `{ ... } catch(...) {..} cleanup {..}` (standalone block statement)。
+  - Method‑postfix: `NYASH_METHOD_CATCH=1` or Stage‑3 enables method body postfix on the most recent method.
+- Cardinality and order
+  - Postfix (expr/block/method): at most one `catch` and at most one `cleanup` — in this order. A second `catch` after postfix is a parse error. Multiple `cleanup` are not allowed.
+  - Legacy compatibility: some builds may still accept the historical `try { ... } catch ... cleanup ...` form, but it is not part of the language spec and will be disabled by default. Prefer postfix forms.
+- Binding and chaining
+  - Postfix binds to the immediately preceding expression (the last call in a chain) or to the just‑parsed block/method body. It does not extend to the entire statement unless parentheses are used.
+  - After constructing the postfix `TryCatch`, further method chaining on that expression is not accepted.
+- Semantics and control‑flow
+  - `cleanup` (finally) always runs, regardless of success/failure of the try part.
+  - `return` inside the try part is deferred until after `cleanup` executes. This is implemented by the MIR builder as a deferred return slot/jump to the `cleanup`/exit block.
+  - `return` inside `cleanup` is disallowed by default; enable with `NYASH_CLEANUP_ALLOW_RETURN=1`.
+  - `throw` inside `cleanup` is disallowed by default; enable with `NYASH_CLEANUP_ALLOW_THROW=1`.
+  - `break/continue` inside `cleanup` are allowed (no special guard); use with care. Cleanup executes before the loop transfer takes effect.
+  - Nested cleanup follows lexical unwinding order (inner cleanup runs before outer cleanup).
+  - If no `catch` is present, thrown exceptions still trigger `cleanup`, then propagate outward.
+- Diagnostics
+  - Method‑postfix: duplicate postfix after a method body is a parse error: "duplicate postfix catch/cleanup after method".
+  - Block‑postfix: a standalone postfix without a preceding block is a parse error: "catch/cleanup must follow a try block or standalone block".
+  - Expression‑postfix: only one `catch` is accepted at expression level; a second `catch` triggers a parse error.
+
 Status
 - Phase 1: normalization sugar（既存）
   - `NYASH_CATCH_NEW=1` でコア正規化パスが有効化。
@@ -63,6 +87,14 @@ Semantics
 - cleanup is always executed regardless of success/failure (formerly finally).
 - Multiple catch blocks match by type in order; the first match is taken.
 - In loops, `break/continue` cooperate with cleanup: cleanup is run before leaving the scope.
+ - Return deferral: A `return` in the try section defers until after cleanup. `return`/`throw` inside cleanup are disabled by default; see env toggles below.
+
+Environment toggles
+- `NYASH_PARSER_STAGE3=1`: Enable Stage‑3 syntax (postfix catch/cleanup for expressions; also gates others by default)
+- `NYASH_BLOCK_CATCH=1`: Allow block‑postfix (independent of Stage‑3 if needed)
+- `NYASH_METHOD_CATCH=1`: Allow method‑postfix (independent of Stage‑3 if needed)
+- `NYASH_CLEANUP_ALLOW_RETURN=1`: Permit `return` inside cleanup (default: off)
+- `NYASH_CLEANUP_ALLOW_THROW=1`: Permit `throw` inside cleanup (default: off)
 
 Migration notes
 - try is deprecated: prefer postfix `catch/cleanup`.