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/checklists/mirbuilder_jsonfrag_defaultization.md

@@ -0,0 +1,40 @@
+# MirBuilder JsonFrag Defaultization Checklist
+
+Purpose: define clear, testable conditions to move the JsonFrag-based MirBuilder path from opt-in to default without changing observable behavior.
+
+Scope
+- Loop lowers (simple / sum_bc / count_param) via `loop_opts_adapter.build2`.
+- Normalizer seam: `hako.mir.builder.internal.jsonfrag_normalizer`.
+
+Toggles (dev-only, default OFF)
+- `HAKO_MIR_BUILDER_LOOP_JSONFRAG=1` — enable JsonFrag minimal MIR assembly.
+- `HAKO_MIR_BUILDER_JSONFRAG_NORMALIZE=1` — apply normalization pass (phi/ret/const; incremental).
+- `HAKO_MIR_BUILDER_SKIP_LOOPS=1` — canary guard to bypass loop lowers (safety valve; must remain honored).
+- `HAKO_MIR_BUILDER_NORMALIZE_TAG=1` — emit normalization tag lines; default is quiet (no tag).
+
+Acceptance Criteria
+- Green on quick representative smokes and phase2231 canary.
+- Tag observability present only when opt-in flags are set:
+  - `[mirbuilder/internal/loop:jsonfrag]` when JsonFrag path is taken.
+  - `[mirbuilder/normalize:jsonfrag:pass]` when normalization is applied.
+- Parity: JsonFrag+Normalizer output is semantically identical to the default path (no diff in verification runners, exit code parity).
+- Rollback: removing toggles restores legacy path immediately with zero residual side effects.
+
+Verification Steps
+1) Enable JsonFrag path for loop lowers and run quick smokes:
+   - `HAKO_MIR_BUILDER_LOOP_JSONFRAG=1 tools/smokes/v2/run.sh --profile quick`
+2) Enable Normalizer additionally and re-run:
+   - `HAKO_MIR_BUILDER_LOOP_JSONFRAG=1 HAKO_MIR_BUILDER_JSONFRAG_NORMALIZE=1 tools/smokes/v2/run.sh --profile quick`
+3) Observe tags in logs (only when toggles ON), confirm absence when OFF.
+4) Use `tools/smokes/v2/lib/mir_canary.sh` helpers to extract MIR and assert key tokens as needed.
+5) Heavy EXE/AOT reps present: consider `--timeout 120` for `--profile quick` when NORMALIZE=1.
+
+Rollback Plan
+- Disable toggles to revert (`export` unset or set to `0`). No code removal required.
+- If unexpected diffs appear, capture `[mirbuilder/*]` tags from logs and attach to CURRENT_TASK.md for follow-up.
+
+Notes
+- Normalizer is introduced as a pass-through seam first; refine in small, guarded steps (phi alignment, ret normalization, const folding) while keeping default OFF.
+- Do not change default behavior or widen scope during this phase; prioritize stability and diagnostics.
+- f64 canonicalization is shared via `selfhost.shared.json.utils.json_number_canonical`; prefer reusing this utility instead of local string hacking.
+- Dev helpers: `enable_mirbuilder_dev_env` can inject NORMALIZE via `SMOKES_DEV_NORMALIZE=1` (profile-based injection example provided in comments).