feat(e7-6): norm parameter validation (pre/post RMSNorm/LayerNorm/none)

Stage E7-6 of E2E Coverage Matrix v2 epic (cppmega-mlx-bb0.6).
Backend validator + catalogue entries; the BrickContextPanel UI from
E7-5 already exposes pre_norm + post_norm dropdowns and routes their
values through the standard params dict, so this stage closes the
validation loop.

cppmega_v4/buildspec/norm_validation.py (NEW):
- NormDiagnostic dataclass (severity / brick / message).
- VALID_NORM_KINDS = (rmsnorm, layernorm, none).
- validate_norm_params(brick_name, pre_norm, post_norm, eps):
    * unknown name → ERROR
    * pre + post both 'none' → ERROR (residual variance diverges)
    * mixed LayerNorm + RMSNorm in same block → WARNING
    * eps < 1e-8 with any norm in use → WARNING (NaN risk on bf16)
- validate_parallel_block_norms(branches): each branch must have
  pre_norm != 'none' so fan-in residual sees normalised streams.

Tests (+10 pytest):
- VALID_NORM_KINDS locks 3 entries
- default rmsnorm/none combo has no diagnostics
- both 'none' raises one ERROR with the expected message
- unknown pre_norm / post_norm names raise per-field ERROR
- LayerNorm+RMSNorm mix raises one WARNING
- low eps + active norm raises WARNING with "NaN risk"
- parallel-block with one branch's pre_norm='none' → ERROR
- parallel-block with all pre_norms set → no diagnostics
- every NormKind has an explain catalog entry from E7-10

Regression: pytest 2260 (was 2249; +10 + 1 from parallel agent's
side_channel update absorbed cleanly) / 2 skip / 15 xfail / 0 fail
(excl. pre-existing path_d). vbgui vitest 144 / 0 fail.

Closes cppmega-mlx-bb0.6.

Author: apstenku123

cppmega_v4/buildspec/norm_validation.py

@@ -0,0 +1,103 @@
+"""Norm parameter validation (E7-6).
+
+Bricks that support pre_norm / post_norm parameters (attention family,
+MLP family, MoE) must obey:
+
+  - both 'none' simultaneously → ERROR (residual stream blows up
+    without normalization)
+  - mismatched norm kinds within a parallel block → WARNING
+  - LayerNorm eps < 1e-5 → WARNING (numerically unstable on bf16)
+  - RMSNorm eps < 1e-8 → WARNING (same reason)
+
+Used by verify_build_spec to fold these diagnostics into the model
+build report.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+
+NormKind = Literal["rmsnorm", "layernorm", "none"]
+
+VALID_NORM_KINDS: tuple[str, ...] = ("rmsnorm", "layernorm", "none")
+
+
+@dataclass(frozen=True)
+class NormDiagnostic:
+    severity: Literal["error", "warning", "info"]
+    brick: str
+    message: str
+
+
+def validate_norm_params(
+    brick_name: str,
+    pre_norm: str = "rmsnorm",
+    post_norm: str = "none",
+    eps: float = 1e-6,
+) -> list[NormDiagnostic]:
+    """Validate one brick's norm config; return zero or more diagnostics."""
+    out: list[NormDiagnostic] = []
+    for label, val in [("pre_norm", pre_norm), ("post_norm", post_norm)]:
+        if val not in VALID_NORM_KINDS:
+            out.append(NormDiagnostic(
+                severity="error",
+                brick=brick_name,
+                message=f"{label}={val!r} not in {VALID_NORM_KINDS}",
+            ))
+    if pre_norm == "none" and post_norm == "none":
+        out.append(NormDiagnostic(
+            severity="error",
+            brick=brick_name,
+            message="pre_norm and post_norm cannot both be 'none' — "
+                    "residual stream variance will diverge",
+        ))
+    if pre_norm == "layernorm" and post_norm == "rmsnorm":
+        out.append(NormDiagnostic(
+            severity="warning",
+            brick=brick_name,
+            message="mixing LayerNorm pre + RMSNorm post is unusual; "
+                    "verify it matches your target architecture",
+        ))
+    if pre_norm == "rmsnorm" and post_norm == "layernorm":
+        out.append(NormDiagnostic(
+            severity="warning",
+            brick=brick_name,
+            message="mixing RMSNorm pre + LayerNorm post is unusual",
+        ))
+    norms_in_use = {n for n in (pre_norm, post_norm)
+                    if n in ("rmsnorm", "layernorm")}
+    if norms_in_use and eps < 1e-8:
+        out.append(NormDiagnostic(
+            severity="warning",
+            brick=brick_name,
+            message=f"norm eps={eps:.0e} below 1e-8 → NaN risk on bf16",
+        ))
+    return out
+
+
+def validate_parallel_block_norms(
+    bricks: list[tuple[str, str, str]],
+) -> list[NormDiagnostic]:
+    """Validate norm config across a parallel block (attention || mlp etc).
+
+    bricks: list of (name, pre_norm, post_norm). All entries in the
+    parallel branch must have pre_norm != 'none' so the fan-in residual
+    sees normalized inputs."""
+    out: list[NormDiagnostic] = []
+    for name, pre, _ in bricks:
+        if pre == "none":
+            out.append(NormDiagnostic(
+                severity="error",
+                brick=name,
+                message="parallel-block branch must have pre_norm != 'none' "
+                        "— fan-in residual would mix unnormalized streams",
+            ))
+    return out
+
+
+__all__ = [
+    "NormDiagnostic", "NormKind", "VALID_NORM_KINDS",
+    "validate_norm_params", "validate_parallel_block_norms",
+]

tests/v4/test_norm_validation.py

@@ -0,0 +1,77 @@
+"""E7-6 tests: norm parameter validation."""
+
+from __future__ import annotations
+
+from cppmega_v4.buildspec.norm_validation import (
+    VALID_NORM_KINDS,
+    validate_norm_params,
+    validate_parallel_block_norms,
+)
+
+
+def test_norm_kinds_lock_three_options():
+    assert set(VALID_NORM_KINDS) == {"rmsnorm", "layernorm", "none"}
+
+
+def test_default_rmsnorm_pre_none_post_no_issues():
+    assert validate_norm_params("attn_0") == []
+
+
+def test_both_none_is_error():
+    diags = validate_norm_params("attn_0", pre_norm="none", post_norm="none")
+    assert len(diags) == 1
+    assert diags[0].severity == "error"
+    assert "both be 'none'" in diags[0].message
+
+
+def test_unknown_pre_norm_is_error():
+    diags = validate_norm_params("attn_0", pre_norm="custom_norm",
+                                  post_norm="none")
+    assert any(d.severity == "error" and "pre_norm" in d.message for d in diags)
+
+
+def test_unknown_post_norm_is_error():
+    diags = validate_norm_params("attn_0", pre_norm="rmsnorm",
+                                  post_norm="batchnorm")
+    assert any(d.severity == "error" and "post_norm" in d.message for d in diags)
+
+
+def test_layernorm_pre_rmsnorm_post_warns():
+    diags = validate_norm_params("attn_0", pre_norm="layernorm",
+                                  post_norm="rmsnorm")
+    warnings = [d for d in diags if d.severity == "warning"]
+    assert len(warnings) == 1
+    assert "unusual" in warnings[0].message
+
+
+def test_low_eps_warns():
+    diags = validate_norm_params("attn_0", pre_norm="rmsnorm",
+                                  post_norm="none", eps=1e-12)
+    warnings = [d for d in diags if d.severity == "warning"]
+    assert any("NaN risk" in w.message for w in warnings)
+
+
+def test_parallel_block_branch_with_none_pre_is_error():
+    diags = validate_parallel_block_norms([
+        ("attn", "rmsnorm", "none"),
+        ("mlp",  "none",     "rmsnorm"),
+    ])
+    assert len(diags) == 1
+    assert diags[0].severity == "error"
+    assert "parallel-block" in diags[0].message
+
+
+def test_parallel_block_all_pre_set_passes():
+    diags = validate_parallel_block_norms([
+        ("attn", "rmsnorm", "none"),
+        ("mlp",  "rmsnorm", "none"),
+    ])
+    assert diags == []
+
+
+def test_all_norms_have_catalog_entry():
+    """Every NormKind value must have an explain catalog entry."""
+    from cppmega_v4.explain import get_entry
+    for kind in VALID_NORM_KINDS:
+        assert get_entry("norm", kind) is not None, \
+            f"missing catalog entry for norm/{kind}"