mirbuilder: integrate Normalizer (toggle), add tag-quiet mode, share f64 canonicalization; expand canaries; doc updates for quick timeout + dev toggles; Phase 21.5 optimization readiness

docs/architecture/RINGS.md

@@ -0,0 +1,39 @@
+# Runtime Rings Architecture (ring0 / ring1 / ring2)
+
+Purpose: clarify responsibilities and naming for core runtime layers, and make provider selection and diagnostics consistent without large code moves.
+
+Overview
+- ring0 (Kernel): Core executor/runner/host-bridge. Responsible for fail-fast and process orchestration. No direct business logic of boxes.
+- ring1 (Core Providers): Minimal, trusted, always-available providers (static). Example: FileBox Core-RO (open/read/close). Small, reproducible, and safe to enable under fail-fast.
+- ring2 (Plugins): Dynamic, featureful providers. Swappable and extensible. Example: Array/Map plugins, full-feature FileBox plugin.
+
+Mapping (current repo)
+- ring0: src/ring0/ (facade + guard; re-exports are deferred). Existing core remains under src/*; ring0 is a conceptual anchor.
+- ring1: src/providers/ring1/ (facade + guard). Concrete code still lives where it is; ring1 hosts documentation and future home for static providers.
+- ring2: plugins/ (dynamic shared libraries, as before).
+
+Selection Policy (Auto mode)
+- Global: `HAKO_PROVIDER_POLICY=strict-plugin-first|safe-core-first|static-preferred`
+  - strict-plugin-first (default): prefer dynamic/plugin; fallback to ring1 when allowed.
+  - safe-core-first/static-preferred: prefer ring1 (static) when available; fallback to plugin.
+- Per box (example: FileBox)
+  - `NYASH_FILEBOX_MODE=auto|ring1|plugin-only`
+  - `NYASH_FILEBOX_ALLOW_FALLBACK=0|1` (narrow dev override)
+
+Diagnostics (stderr, quiet when JSON_ONLY=1)
+- Selection: `[provider/select:<Box> ring=<0|1|plugin> src=<static|dynamic>]`
+- Fail-Fast block: `[failfast/provider/<box>:<reason>]`
+
+Design Invariants
+- ring0 must not depend on ring2. ring1 contains only minimal stable capabilities.
+- Fallback is disallowed by default (Fail-Fast). Allow only via per-box override or JSON_ONLY quiet pipe.
+
+Migration Plan (small steps)
+1) Add facades and guards (this change).
+2) Keep existing code paths; introduce provider policy (done for FileBox).
+3) Gradually move minimal static providers under `src/providers/ring1/` (no behavior change).
+4) Add canaries to assert selection tags under different policies.
+
+Notes on Naming
+- Historical names like "builtin" referred to in-tree providers. To avoid confusion, use ring terms: ring0 (kernel), ring1 (core providers), ring2 (plugins).
+