carmen-kernels 0.1.0__py3-none-any.whl

carmen/__init__.py

@@ -0,0 +1,7 @@
+"""carmen: a self-correcting harness that gets LLMs to write fast GPU kernels you can trust.
+
+The model (Carmy) is the intelligence; the judge is the truth; correction is the loop
+between them, and memory is that loop's verified residue.
+"""
+
+__version__ = "0.1.0"

carmen/backends/__init__.py

@@ -0,0 +1,11 @@
+from .base import PAD, Adapter, Kernel, static_check
+
+
+def get(name: str):
+    if name == "metal":
+        from .metal import MetalAdapter
+        return MetalAdapter()
+    raise KeyError(f"unknown backend {name!r}; available: metal")
+
+
+__all__ = ["PAD", "Adapter", "Kernel", "static_check", "get"]

carmen/backends/base.py

@@ -0,0 +1,102 @@
+"""What a kernel is, and what a chip adapter must provide.
+
+A kernel is Metal (or CUDA, later) *source text* plus launch configs. It is never
+Python: Carmy cannot run code inside the judge, only submit a kernel body.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+from typing import Callable, Protocol
+
+import numpy as np
+
+# Extra elements allocated after the real output. They start as NaN and must stay NaN:
+# a write here means the kernel wrote past the end of its output.
+PAD = 64
+
+MAX_SOURCE_CHARS = 30_000
+MAX_CONFIGS = 6
+BANNED_TOKENS = ("#include", "asm(", "__asm")
+# Loop-unrolling hints are harmless and often faster; any other pragma is refused.
+ALLOWED_PRAGMAS = ("#pragma unroll", "#pragma clang loop")
+
+
+@dataclass
+class Kernel:
+    source: str
+    header: str = ""
+    # Each config maps template constant -> int. "TG" (threads per threadgroup) is required.
+    configs: list[dict[str, int]] = field(default_factory=lambda: [{"TG": 256}])
+    plan: str = ""
+
+    def digest(self) -> str:
+        blob = json.dumps([self.source, self.header], sort_keys=True).encode()
+        return hashlib.sha256(blob).hexdigest()[:12]
+
+    def to_json(self) -> dict:
+        return {"source": self.source, "header": self.header, "configs": self.configs, "plan": self.plan}
+
+    @staticmethod
+    def from_json(d: dict) -> "Kernel":
+        return Kernel(d["source"], d.get("header", ""), d.get("configs") or [{"TG": 256}], d.get("plan", ""))
+
+
+def static_check(kernel: Kernel) -> str | None:
+    """Cheap checks before touching the GPU. Returns an error message or None."""
+    text = kernel.source + "\n" + kernel.header
+    if not kernel.source.strip():
+        return "empty kernel source"
+    if len(text) > MAX_SOURCE_CHARS:
+        return f"kernel is {len(text)} chars; limit is {MAX_SOURCE_CHARS}"
+    for tok in BANNED_TOKENS:
+        if tok in text:
+            return f"banned token {tok!r} (MLX already includes the Metal standard library)"
+    for line in text.splitlines():
+        if line.strip().startswith("#pragma") and not line.strip().startswith(ALLOWED_PRAGMAS):
+            return f"only loop-unrolling pragmas are allowed, got {line.strip()!r}"
+    if not 1 <= len(kernel.configs) <= MAX_CONFIGS:
+        return f"give between 1 and {MAX_CONFIGS} configs"
+    for cfg in kernel.configs:
+        tg = cfg.get("TG")
+        if not isinstance(tg, int) or tg < 32 or tg > 1024 or tg % 32:
+            return f"config {cfg}: TG must be a multiple of 32 between 32 and 1024"
+        for k, v in cfg.items():
+            if not k.isidentifier() or not isinstance(v, int) or not 0 <= v <= 65536:
+                return f"config {cfg}: constants must be identifiers mapped to ints in [0, 65536]"
+    return None
+
+
+class Adapter(Protocol):
+    """The only chip-specific surface. Adding a new chip means writing one of these."""
+
+    name: str
+
+    def chip(self) -> str: ...
+
+    def build(self, op, kernel: Kernel):
+        """Compile the kernel. Raise on compile errors."""
+
+    def upload(self, inputs: dict[str, np.ndarray], dtype: str = "float32"):
+        """Move numpy inputs to the device once, so timing excludes transfers. For bfloat16,
+        inputs arrive as float32 arrays of exact bf16 values and are cast on the device."""
+
+    def launch(self, built, op, config: dict, dev_inputs, rows: int, n: int, dtype: str,
+               inner: int = 1) -> Callable[[], None]:
+        """Return a function that runs the kernel `inner` times back to back and blocks until done.
+        For timing only: must not add work the stock op doesn't do (e.g. no NaN pre-fill)."""
+
+    def run(self, built, op, config: dict, dev_inputs, rows: int, n: int, dtype: str) -> np.ndarray:
+        """Run once; return the flat output (rows * n + PAD elements), NaN-poisoned before launch."""
+
+    def baseline(self, op, dev_inputs) -> Callable[[], np.ndarray]:
+        """Return a function that runs the stock library op, blocks, and returns its output."""
+
+    def baseline_launch(self, op, dev_inputs, inner: int = 1, compiled: bool = False) -> Callable[[], None]:
+        """Return a function that runs the stock library op `inner` times and blocks (for timing).
+        `compiled=True` wraps it in the library's graph compiler (mx.compile), which fuses element-wise ops."""
+
+    def measure_peak_gbps(self) -> float:
+        """Practical memory bandwidth from a copy kernel."""

carmen/backends/metal.py

@@ -0,0 +1,129 @@
+"""Apple Metal via MLX's mx.fast.metal_kernel. The only file that knows about Metal."""
+
+from __future__ import annotations
+
+import time
+
+import numpy as np
+
+from ..ops.base import SCALAR_INPUTS
+from .base import PAD, Kernel
+
+try:
+    import mlx.core as mx
+except ImportError as e:  # pragma: no cover - only on machines without MLX
+    raise ImportError("the metal backend needs MLX on Apple Silicon: pip install 'carmen-kernels[metal]'") from e
+
+_DTYPES = {"float32": mx.float32, "float16": mx.float16, "bfloat16": mx.bfloat16}
+
+
+def _host(a) -> np.ndarray:
+    """numpy can't hold bfloat16: read it back as float32 (exact)."""
+    return np.array(a.astype(mx.float32) if a.dtype == mx.bfloat16 else a)
+
+COPY_KERNEL = """
+    uint i = thread_position_in_grid.x;
+    if (i < inp_shape[0]) { out[i] = inp[i]; }
+"""
+
+
+class MetalAdapter:
+    name = "metal"
+
+    def chip(self) -> str:
+        info = mx.metal.device_info() if hasattr(mx, "metal") and hasattr(mx.metal, "device_info") else mx.device_info()
+        return str(info.get("device_name", "apple-gpu"))
+
+    def build(self, op, kernel: Kernel):
+        return mx.fast.metal_kernel(
+            name=f"carmen_{op.name}_{kernel.digest()}",
+            input_names=list(op.input_names),
+            output_names=["out"],
+            source=kernel.source,
+            header=kernel.header,
+        )
+
+    def upload(self, inputs, dtype: str = "float32"):
+        def put(k, v):
+            a = mx.array(v)
+            cast = dtype == "bfloat16" and k not in SCALAR_INPUTS and np.asarray(v).dtype.kind == "f"
+            return a.astype(mx.bfloat16) if cast else a  # integer inputs (packed weights) stay as they are
+        return {k: put(k, v) for k, v in inputs.items()}
+
+    def _call(self, built, op, config, dev_inputs, rows, n, dtype, poison: bool = True):
+        grid, threadgroup = op.grid(rows, n, config)
+        template = [("T", _DTYPES[dtype])] + [(k, v) for k, v in config.items()]
+        (out,) = built(
+            inputs=[dev_inputs[name] for name in op.input_names],
+            template=template,
+            # The harness sets the launch shape (one threadgroup per row, or per output tile).
+            # Carmy never picks the grid, which rules out MLX's silent dispatch truncation.
+            grid=grid,
+            threadgroup=threadgroup,
+            output_shapes=[(op.outputs * rows * n + PAD,)],
+            output_dtypes=[_DTYPES[dtype]],
+            # Correctness runs pre-fill the output with NaN so unwritten elements show up.
+            # Timing runs must not: the fill is an extra full write the stock op never pays.
+            **({"init_value": float("nan")} if poison else {}),
+        )
+        return out
+
+    def launch(self, built, op, config, dev_inputs, rows, n, dtype, inner: int = 1):
+        # `inner` launches share one eval, so per-call Python/dispatch overhead is amortized
+        # and the timer sees GPU time, not host time.
+        def go():
+            mx.eval(*[self._call(built, op, config, dev_inputs, rows, n, dtype, poison=False) for _ in range(inner)])
+        return go
+
+    def run(self, built, op, config, dev_inputs, rows, n, dtype):
+        out = self._call(built, op, config, dev_inputs, rows, n, dtype)
+        mx.eval(out)
+        return _host(out)
+
+    def baseline(self, op, dev_inputs):
+        def go():
+            y = op.mlx_baseline(mx, dev_inputs)
+            mx.eval(y)
+            if isinstance(y, (tuple, list)):  # several outputs: stacked, as the reference is
+                return np.concatenate([_host(a).reshape(-1, a.shape[-1]) for a in y])
+            return _host(y)
+        return go
+
+    def baseline_launch(self, op, dev_inputs, inner: int = 1, compiled: bool = False):
+        fn = lambda d: op.mlx_baseline(mx, d)  # noqa: E731
+        if compiled:
+            # mx.compile fuses chains of element-wise ops (e.g. x * scale + mask) into one kernel:
+            # the strongest stock baseline a user gets without writing Metal.
+            # eps is a Python number to the stock op; read it before tracing (no reads inside compile).
+            consts = {"eps": float(dev_inputs["eps"].item())} if "eps" in dev_inputs else {}
+            names = [k for k in dev_inputs if k not in consts]
+            fused = mx.compile(lambda *arrs: op.mlx_baseline(mx, {**dict(zip(names, arrs)), **consts}))
+            fn = lambda d: fused(*[d[k] for k in names])  # noqa: E731
+
+        def go():
+            mx.eval(*[fn(dev_inputs) for _ in range(inner)])
+        return go
+
+    def release(self) -> None:
+        """Hand MLX's cached buffers back to the OS between timing runs."""
+        (mx.clear_cache if hasattr(mx, "clear_cache") else mx.metal.clear_cache)()
+
+    def measure_peak_gbps(self) -> float:
+        n = 64 * 1024 * 1024  # 256 MB of float32
+        kern = mx.fast.metal_kernel(name="carmen_copy", input_names=["inp"], output_names=["out"], source=COPY_KERNEL)
+        inp = mx.random.uniform(shape=(n,))
+        mx.eval(inp)
+
+        def go():
+            (o,) = kern(inputs=[inp], grid=(n, 1, 1), threadgroup=(256, 1, 1),
+                        output_shapes=[(n,)], output_dtypes=[mx.float32])
+            mx.eval(o)
+
+        for _ in range(3):
+            go()
+        best = float("inf")
+        for _ in range(20):
+            t = time.perf_counter()
+            go()
+            best = min(best, time.perf_counter() - t)
+        return 2 * n * 4 / best / 1e9

carmen/bench.py

@@ -0,0 +1,102 @@
+"""`carmen bench`: does the feedback loop beat blind sampling?
+
+For each op, run the loop and the best-of-N control arm the same number of times with the
+same budget (rounds x k Carmy calls, no early stop), each from a fresh memory, and compare:
+
+  - final champion speed (vs MLX, and vs mx.compile(MLX))
+  - round-1 best vs final best: did later rounds add anything?
+  - how many kernels the judge verified
+
+Writes bench.json and a markdown table (bench.md) ready to paste into a README.
+"""
+
+from __future__ import annotations
+
+import json
+import statistics
+import time
+from pathlib import Path
+from typing import Callable
+
+from .events import read_events
+
+MODES = ("loop", "bon")
+
+
+def _curve(run_dir: Path) -> list[float]:
+    """Best verified speedup found in each round (0 when a round verified nothing)."""
+    best: dict[int, float] = {}
+    for e in read_events(run_dir):
+        if e["type"] == "judge_result":
+            best.setdefault(e["round"], 0.0)
+            if e.get("correct") and e.get("speedup"):
+                best[e["round"]] = max(best[e["round"]], e["speedup"])
+    return [best[r] for r in sorted(best)]
+
+
+def run(ops: list[str], *, repeats: int, rounds: int, k: int, root: Path, run_fn: Callable,
+        on_progress: Callable[[str], None] = print, **run_kw) -> dict:
+    root = Path(root)
+    results = []
+    for op in ops:
+        for i in range(repeats):
+            for mode in MODES:
+                tag = f"{op}-{mode}-{i}"
+                on_progress(f"{tag}: cooking ({rounds} rounds x {k} drafts)")
+                sm = run_fn(op, rounds=rounds, k=k, mode=mode, patience=rounds + 1,
+                            runs_dir=root / tag, memory_dir=root / tag / "memory", **run_kw)
+                curve = _curve(Path(sm["run_dir"]))
+                results.append({"op": op, "mode": mode, "repeat": i, "speedup": sm.get("speedup"),
+                                "speedup_compiled": sm.get("speedup_compiled"),
+                                "hidden_speedup": sm.get("hidden_speedup"), "verified": sm["verified"],
+                                "attempts": sm["attempts"], "curve": curve, "run_dir": sm["run_dir"]})
+                on_progress(f"{tag}: best {_x(sm.get('speedup'))}, per round {' '.join(_x(c) for c in curve)}")
+    out = {"when": time.strftime("%Y-%m-%d %H:%M"), "rounds": rounds, "k": k, "repeats": repeats,
+           "results": results, "table": table(results)}
+    root.mkdir(parents=True, exist_ok=True)
+    (root / "bench.json").write_text(json.dumps(out, indent=2, default=float))
+    (root / "bench.md").write_text(markdown(out["table"], rounds, k, repeats))
+    return out
+
+
+def _mean(xs):
+    xs = [x for x in xs if x]
+    return statistics.mean(xs) if xs else None
+
+
+def table(results: list[dict]) -> list[dict]:
+    rows = []
+    for op in dict.fromkeys(r["op"] for r in results):
+        for mode in MODES:
+            rs = [r for r in results if r["op"] == op and r["mode"] == mode]
+            if not rs:
+                continue
+            first = [r["curve"][0] for r in rs if r["curve"]]
+            rows.append({
+                "op": op, "mode": mode, "runs": len(rs),
+                "speedup": _mean(r["speedup"] for r in rs),
+                "speedup_min": min((r["speedup"] or 0 for r in rs), default=0),
+                "speedup_max": max((r["speedup"] or 0 for r in rs), default=0),
+                "speedup_compiled": _mean(r["speedup_compiled"] for r in rs),
+                "hidden_speedup": _mean(r["hidden_speedup"] for r in rs),
+                "round1": _mean(first),
+                "verified": sum(r["verified"] for r in rs), "attempts": sum(r["attempts"] for r in rs),
+            })
+    return rows
+
+
+def _x(v) -> str:
+    return f"{v:.2f}x" if v else "-"
+
+
+def markdown(rows: list[dict], rounds: int, k: int, repeats: int) -> str:
+    lines = [f"Each row: {repeats} run(s) of {rounds} rounds x {k} drafts, fresh memory, no early stop.",
+             "`loop` feeds the judge's results back; `best-of-N` makes the same number of calls blind.", "",
+             "| kernel | mode | speedup vs MLX (mean, range) | vs mx.compile | unseen sizes | round 1 → final | verified |",
+             "|---|---|---|---|---|---|---|"]
+    for r in rows:
+        mode = "loop" if r["mode"] == "loop" else "best-of-N"
+        lines.append(f"| {r['op']} | {mode} | {_x(r['speedup'])} ({_x(r['speedup_min'])}–{_x(r['speedup_max'])}) "
+                     f"| {_x(r['speedup_compiled'])} | {_x(r['hidden_speedup'])} | {_x(r['round1'])} → {_x(r['speedup'])} "
+                     f"| {r['verified']}/{r['attempts']} |")
+    return "\n".join(lines) + "\n"

carmen/broken.py

@@ -0,0 +1,213 @@
+"""Seeded broken kernels: how we measure the judge.
+
+Each mutant is the golden kernel with one realistic bug, grouped into the fault
+families from "Measuring the Checker" (Du et al., arXiv 2609.22220): boundary,
+precision, sync, indexing, semantic. A strong judge kills all of them and never
+rejects the golden kernel. Every mutant here is designed to be *actually* wrong
+on some legal input; `carmen broken` reports which ones get through.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from .backends import Kernel
+
+GOLDEN_DIR = Path(__file__).resolve().parent / "golden"
+
+
+@dataclass(frozen=True)
+class Mutant:
+    name: str
+    family: str
+    old: str
+    new: str
+    why: str
+    every: bool = False  # replace every occurrence, not just the first
+
+
+MUTANTS = [
+    Mutant("no_max_subtraction", "precision", "metal::exp(float(xr[i]) - m)", "metal::exp(float(xr[i]))",
+           "exp overflows for large inputs"),
+    Mutant("fp16_accumulate", "precision", "float s = 0.0f;", "half s = 0.0h;",
+           "sum loses precision on long rows"),
+    Mutant("store_through_half", "precision", "o[i] = T(", "o[i] = T((half)",
+           "fp32 outputs rounded to fp16 (escapes allclose 1e-2)"),
+    Mutant("tail_write_dropped", "boundary", "for (int i = tid; i < n; i += TG) { o[i]",
+           "for (int i = tid; i < n - 1; i += TG) { o[i]", "last element never written"),
+    Mutant("tail_sum_dropped", "boundary", "for (int i = tid; i < n; i += TG) { s +=",
+           "for (int i = tid; i < n - 1; i += TG) { s +=", "last element missing from the sum"),
+    Mutant("max_start_at_one", "boundary", "for (int i = tid; i < n; i += TG) { m =",
+           "for (int i = tid + 1; i < n; i += TG) { m =", "first element of each thread skipped in max"),
+    Mutant("barrier_removed", "sync",
+           "if (lane == 0) { shared[0] = v; }\n}\nthreadgroup_barrier(mem_flags::mem_threadgroup);\nm = shared[0];",
+           "if (lane == 0) { shared[0] = v; }\n}\nm = shared[0];", "race: threads read the max before it is written"),
+    Mutant("partial_simd_reduce", "indexing", "(lane < n_sg) ? shared[lane] : 0.0f",
+           "(lane < n_sg / 2) ? shared[lane] : 0.0f", "half the simdgroups dropped from the sum"),
+    Mutant("wrong_row_stride", "indexing", "device T* o = out + row * n;", "device T* o = out + row * (n - 1);",
+           "rows overlap in the output"),
+    Mutant("max_sentinel_zero", "semantic", "float m = -INFINITY;", "float m = 0.0f;",
+           "all-negative rows underflow to 0/0"),
+    Mutant("sum_uses_local_max", "semantic", "m = shared[0];\nthreadgroup_barrier(mem_flags::mem_threadgroup);\n\n// 2.",
+           "threadgroup_barrier(mem_flags::mem_threadgroup);\n\n// 2.", "each simdgroup normalizes with its own max"),
+    Mutant("divide_by_n", "semantic", "/ s)", "/ float(n))", "normalizes by n instead of the sum"),
+]
+
+
+# The norms share one golden-kernel skeleton (sum, reduce, rsqrt, write), so one list covers both.
+NORM_MUTANTS = [
+    Mutant("fp16_accumulate", "precision", "float s = 0.0f;", "half s = 0.0h;",
+           "sum kept in half: overflows or drifts on big or offset rows"),
+    Mutant("store_through_half", "precision", "o[i] = T(", "o[i] = T((half)",
+           "fp32 outputs rounded to fp16 (escapes allclose 1e-2)"),
+    Mutant("tail_write_dropped", "boundary", "for (int i = tid; i < n; i += TG) { o[i]",
+           "for (int i = tid; i < n - 1; i += TG) { o[i]", "last element never written"),
+    Mutant("tail_sum_dropped", "boundary", "for (int i = tid; i < n; i += TG) { s +=",
+           "for (int i = tid; i < n - 1; i += TG) { s +=", "last element missing from the sum"),
+    Mutant("barrier_removed", "sync",
+           "if (lane == 0) { shared[0] = v; }\n}\nthreadgroup_barrier(mem_flags::mem_threadgroup);\n",
+           "if (lane == 0) { shared[0] = v; }\n}\n", "race: threads read the sum before it is written"),
+    Mutant("partial_simd_reduce", "indexing", "(lane < n_sg) ? shared[lane] : 0.0f",
+           "(lane < n_sg / 2) ? shared[lane] : 0.0f", "half the simdgroups dropped from the sum"),
+    Mutant("wrong_row_stride", "indexing", "device T* o = out + row * n;", "device T* o = out + row * (n - 1);",
+           "rows overlap in the output"),
+    Mutant("eps_dropped", "semantic", "+ eps)", ")", "no eps: zero rows divide by zero, tiny rows blow up"),
+    Mutant("divide_by_n_minus_1", "semantic", "shared[0] / float(n)", "shared[0] / float(n - 1)",
+           "averages over n - 1 instead of n"),
+    Mutant("weight_ignored", "semantic", " * float(w[i])", "", "learned weight never applied"),
+]
+
+# matmul has its own skeleton (tiles, K loop), so its own bugs.
+MATMUL_MUTANTS = [
+    Mutant("fp16_accumulate", "precision", "float acc = 0.0f;", "half acc = 0.0h;",
+           "dot products summed in half: drifts on long K"),
+    Mutant("store_through_half", "precision", "out[r * N + c] = T(acc);", "out[r * N + c] = T((half)acc);",
+           "fp32 outputs rounded to fp16"),
+    Mutant("k_tail_dropped", "boundary", "k < K; ++k", "k < K - 1; ++k", "last term of every dot product missing"),
+    Mutant("last_column_unwritten", "boundary", "if (r < M && c < N)", "if (r < M && c < N - 1)",
+           "the right edge of the output is never written"),
+    Mutant("k_starts_at_one", "boundary", "int k = 0; k < K", "int k = 1; k < K", "first term of every dot product missing"),
+    Mutant("wrong_leading_dim", "indexing", "a[r * K + k]", "a[r * N + k]",
+           "A indexed with N instead of K: right only when the matrices are square"),
+    Mutant("b_transposed", "indexing", "b[k * N + c]", "b[c * K + k]", "B read as if transposed"),
+    Mutant("tile_axes_swapped", "indexing", "int r = ty * BM + e / BN;\n    int c = tx * BN + e % BN;",
+           "int r = tx * BM + e / BN;\n    int c = ty * BN + e % BN;",
+           "grid x and y swapped: right only when the tile grid is square"),
+]
+
+# attention: the causal boundary, the cache offset, the softmax and the scale.
+ATTENTION_MUTANTS = [
+    Mutant("no_max_subtraction", "precision", "metal::exp(SCORE(i, j) - m)", "metal::exp(SCORE(i, j))",
+           "exp overflows on large scores", every=True),
+    Mutant("fp16_accumulate", "precision", "float acc = 0.0f;", "half acc = 0.0h;",
+           "the weighted sum of v kept in half: drifts on long sequences"),
+    Mutant("causal_excludes_self", "boundary", "i + (Lk - Lq));", "i + (Lk - Lq) - 1);",
+           "each query can't see its own key"),
+    Mutant("causal_peeks_ahead", "boundary", "i + (Lk - Lq));", "i + (Lk - Lq) + 1);",
+           "each query sees one future key"),
+    Mutant("head_dim_tail_dropped", "boundary", "d < D; d += TG", "d < D - 1; d += TG",
+           "the last output column is never written"),
+    Mutant("cache_offset_ignored", "indexing", "metal::min(Lk - 1, i + (Lk - Lq))", "metal::min(Lk - 1, i)",
+           "causal mask aligned top-left: right only when Lq == Lk"),
+    Mutant("v_read_transposed", "indexing", "v[j * D + d]", "v[d * Lk + j]", "v read as if transposed"),
+    Mutant("barrier_removed", "sync",
+           "if (lane == 0) { shared[0] = x; }\n    }\n    threadgroup_barrier(mem_flags::mem_threadgroup);\n    m = shared[0];",
+           "if (lane == 0) { shared[0] = x; }\n    }\n    m = shared[0];", "race: threads read the max before it is written"),
+    Mutant("scale_missing", "semantic", "* scl)", ")", "scores not divided by sqrt(D)"),
+    Mutant("not_normalized", "semantic", "T(acc / l)", "T(acc)", "weighted sum never divided by the softmax total"),
+]
+
+_SHARED_NORM = [m for m in NORM_MUTANTS if m.name not in ("eps_dropped", "wrong_row_stride")]
+
+MUTANTS_BY_OP = {
+    "residual_rmsnorm": _SHARED_NORM + [
+        Mutant("eps_dropped", "semantic", "+ eps[0])", ")", "no eps: zero rows divide by zero"),
+        Mutant("eps_hardcoded", "semantic", "+ eps[0])", "+ 1e-5f)", "eps fixed at Llama's 1e-5: wrong for Qwen's 1e-6"),
+        Mutant("residual_tail_unwritten", "boundary", "for (int i = tid; i < n; i += TG) { hsum[i]",
+               "for (int i = tid; i < n - 1; i += TG) { hsum[i]", "last element of h never written"),
+        Mutant("y_overwrites_h", "indexing", "device T* o = out + (rows + row) * n;", "device T* o = out + row * n;",
+               "y written over h: the residual is lost"),
+        Mutant("residual_not_added", "semantic", "hsum[i] = T(float(xr[i]) + float(rr[i]));", "hsum[i] = T(float(xr[i]));",
+               "h is x alone: the block's output never joins the residual"),
+    ],
+    "attention": ATTENTION_MUTANTS,
+    "mlp_up": [
+        Mutant("fp16_accumulate", "precision", "float g = 0.0f, u = 0.0f;", "half g = 0.0h, u = 0.0h;",
+               "dot products summed in half: long rows lose precision"),
+        Mutant("silu_overflows", "precision", "T(g / (1.0f + metal::exp(-g)) * u)",
+               "T(metal::exp(g) / (1.0f + metal::exp(g)) * g * u)", "silu as e^g/(1+e^g): inf/inf = NaN for big g"),
+        Mutant("bias_dropped", "semantic", "+ bgv) * hn;", ") * hn;", "gate weights lose their per-group bias"),
+        Mutant("nibble_order_reversed", "indexing", "float((qg >> (4 * t)) & 0xFu)", "float((qg >> (4 * (7 - t))) & 0xFu)",
+               "reads the 8 values of a word highest-first"),
+        Mutant("wrong_group", "indexing", "const int grp = j * groups + k0 / 64;", "const int grp = j * groups + k0 / 128;",
+               "scale and bias from the wrong group once K > 64"),
+        Mutant("last_column_dropped", "boundary", "if (j >= n) { break; }", "if (j >= n - 1) { break; }",
+               "the last output column is never written"),
+        Mutant("last_word_dropped", "boundary", "for (int wd = lane; wd < words; wd += 32)",
+               "for (int wd = lane; wd < words - 1; wd += 32)", "the last 8 values of K are left out of the dot product"),
+        Mutant("eps_dropped", "semantic", "+ eps[0])", ")", "no eps: a zero row divides by zero"),
+        Mutant("residual_not_added", "semantic", "const float hn = (float(xr[k]) + float(rr[k]))",
+               "const float hn = (float(xr[k]))", "the matmuls see x, not x + res"),
+        Mutant("barrier_removed", "sync", "threadgroup_barrier(mem_flags::mem_threadgroup);\nconst float inv",
+               "const float inv", "race: threads read the sum before it is written"),
+        Mutant("partial_simd_reduce", "indexing", "(lane < n_sg) ? shared[lane]", "(lane < n_sg / 2) ? shared[lane]",
+               "half the simdgroups dropped from the norm's sum"),
+        Mutant("wrong_row_stride", "indexing", "out[row * n + j]", "out[row * (n - 1) + j]", "rows overlap in the output"),
+        Mutant("gate_up_swapped", "semantic", "T(g / (1.0f + metal::exp(-g)) * u)", "T(u / (1.0f + metal::exp(-u)) * g)",
+               "silu applied to up instead of gate"),
+    ],
+    "mlp_down": [
+        Mutant("fp16_accumulate", "precision", "float acc = 0.0f;", "half acc = 0.0h;",
+               "dot product summed in half: long rows lose precision"),
+        Mutant("bias_dropped", "semantic", "+ bv) *", ") *", "weights lose their per-group bias"),
+        Mutant("nibble_order_reversed", "indexing", "(q >> (4 * t))", "(q >> (4 * (7 - t)))",
+               "reads the 8 values of a word highest-first"),
+        Mutant("wrong_group", "indexing", "const int grp = j * groups + k0 / 64;", "const int grp = j * groups + k0 / 128;",
+               "scale and bias from the wrong group once K > 64"),
+        Mutant("last_column_dropped", "boundary", "if (j >= n) { break; }", "if (j >= n - 1) { break; }",
+               "the last output column is never written"),
+        Mutant("last_word_dropped", "boundary", "for (int wd = lane; wd < words; wd += 32)",
+               "for (int wd = lane; wd < words - 1; wd += 32)", "the last 8 values of K are left out of the dot product"),
+        Mutant("residual_dropped", "semantic", "float(x[row * n + j]) + float(res[row * n + j]) + acc",
+               "float(x[row * n + j]) + acc", "the attention output never joins the residual stream"),
+        Mutant("wrong_act_row", "indexing", "auto ar = act + row * K;", "auto ar = act + row * (K - 8);",
+               "rows after the first read the wrong activations"),
+    ],
+    "matmul": MATMUL_MUTANTS,
+    "layernorm": NORM_MUTANTS,
+    "rmsnorm": NORM_MUTANTS,
+    "add_rmsnorm": NORM_MUTANTS + [
+        Mutant("residual_dropped_on_write", "semantic", "o[i] = T((float(xr[i]) + float(rr[i])) * inv",
+               "o[i] = T(float(xr[i]) * inv", "normalizes x + res but writes x, not the sum"),
+    ],
+}
+
+
+def has_golden(op: str) -> bool:
+    return (GOLDEN_DIR / f"{op}.metal").exists()
+
+
+GOLDEN_CONFIGS = {"matmul": [{"TG": 256, "BM": 32, "BN": 32}], "attention": [{"TG": 64, "BQ": 1}],
+                  "mlp_up": [{"TG": 256, "BN": 8}], "mlp_down": [{"TG": 256, "BN": 8}]}
+
+
+def golden(op: str) -> Kernel:
+    path = GOLDEN_DIR / f"{op}.metal"
+    header = GOLDEN_DIR / f"{op}.header.metal"
+    configs = GOLDEN_CONFIGS.get(op, [{"TG": 256}])
+    return Kernel(path.read_text(), header.read_text() if header.exists() else "",
+                  configs=[dict(c) for c in configs], plan="golden reference kernel")
+
+
+def mutants(op: str) -> list[tuple[Mutant, Kernel]]:
+    base = golden(op).source
+    out = []
+    for m in MUTANTS_BY_OP.get(op, MUTANTS):
+        old = m.old.replace("float(xr[i])", "(float(xr[i]) * scl + float(mr[i]))") if op == "masked_softmax" else m.old
+        new = m.new.replace("float(xr[i])", "(float(xr[i]) * scl + float(mr[i]))") if op == "masked_softmax" else m.new
+        if old not in base:
+            raise ValueError(f"mutant {m.name} does not apply to the {op} golden kernel")
+        g = golden(op)
+        out.append((m, Kernel(base.replace(old, new, -1 if m.every else 1), g.header, configs=g.configs, plan=m.why)))
+    return out