physverify 0.1.0__py3-none-any.whl

physverify/adapters/three_body.py

@@ -0,0 +1,283 @@
+"""Adapter for three-body-simulation/src (planar three-body problem, G = 1).
+
+Under test:
+  physics.get_derivatives          stepped with physverify's RK4 (mms, reference, patch)
+  integrators.verlet_step          the project's own velocity-Verlet step (second order)
+  integrators.run_verlet_simulation the driver around it
+  integrators.run_simulation       the solve_ivp wrapper (needs SciPy)
+
+The code softens gravity with epsilon = 1e-4, as docs/theory.md allows
+("(r^2 + eps^2)^1.5"), so the reference uses the same softening. The energy
+function in physics.py does not soften; that mismatch is reported separately.
+Verlet has no source-term hook, so there is no MMS check of it (row 25 of the
+audit plan); it is covered by a reference solution, exact invariants and exact
+time reversal instead. The package uses relative imports and SciPy, so it is
+loaded as a package; without SciPy only physics.py is tested.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import math
+import sys
+
+import numpy as np
+
+from ..checks import EXACT, FAIL, PASS, Check, Result
+from ..mms import ManufacturedODE, max_abs_error, zero_source
+from ..order import check_exact, check_order
+from ..problems._common import make_integrate
+from ..steppers import integrate_fixed, rk4
+from ..studies import invariant_study, ode_checks, reference_study
+from . import sibling_project
+
+ENV_VAR = "PHYSVERIFY_THREE_BODY_DIR"
+FOLDER = "three-body-simulation"
+EPS = 1e-4  # softening length used by physics.py
+MASSES = np.array([1.0, 1.0, 1.0])
+
+# Figure-eight initial condition (Chenciner and Montgomery), used only as a smooth, bounded test orbit.
+_X1 = np.array([0.97000436, -0.24308753])
+_V3 = np.array([-0.93240737, -0.86473146])
+Y0_FREE = np.concatenate([_X1, -_X1, [0.0, 0.0], -_V3 / 2, -_V3 / 2, _V3])
+T_END = 1.0
+NS_RK4 = (100, 200, 400, 800)
+NS_VERLET = (200, 400, 800, 1600)
+
+
+def src_dir():
+    return sibling_project(ENV_VAR, FOLDER) / "src"
+
+
+def source_path():
+    return src_dir() / "physics.py"
+
+
+def load():
+    """Import the project's src package under a private name, without writing __pycache__."""
+    name = "three_body_src_under_test"
+    old_flag = sys.dont_write_bytecode
+    sys.dont_write_bytecode = True
+    try:
+        spec = importlib.util.spec_from_file_location(
+            name, src_dir() / "__init__.py", submodule_search_locations=[str(src_dir())]
+        )
+        package = importlib.util.module_from_spec(spec)
+        sys.modules[name] = package
+        try:
+            spec.loader.exec_module(package)
+        except ImportError:
+            # __init__ imports integrators, which needs SciPy; fall back to physics.py alone
+            for key in [k for k in sys.modules if k == name or k.startswith(name + ".")]:
+                sys.modules.pop(key)
+            physics_spec = importlib.util.spec_from_file_location(name + "_physics", source_path())
+            physics = importlib.util.module_from_spec(physics_spec)
+            physics_spec.loader.exec_module(physics)
+            return physics, None
+        return sys.modules[name + ".physics"], sys.modules[name + ".integrators"]
+    finally:
+        sys.dont_write_bytecode = old_flag
+
+
+def rhs_reference(masses=MASSES, eps=EPS):
+    """a_i = sum_j m_j (r_j - r_i) / (|r_j - r_i|^2 + eps^2)^1.5, written pair by pair."""
+    masses = np.asarray(masses, dtype=float)
+
+    def f(t, y):
+        r = y[:6].reshape(3, 2)
+        a = np.zeros((3, 2))
+        for i in range(3):
+            for j in range(i + 1, 3):
+                d = r[j] - r[i]
+                w = (d @ d + eps * eps) ** -1.5
+                a[i] += masses[j] * w * d
+                a[j] -= masses[i] * w * d
+        return np.concatenate([y[6:], a.ravel()])
+
+    return f
+
+
+def energy_reference(y, masses=MASSES, eps=EPS):
+    """Energy of the softened system: the potential is -m_i m_j / sqrt(r^2 + eps^2)."""
+    r = y[:6].reshape(3, 2)
+    v = y[6:].reshape(3, 2)
+    e = 0.5 * float(np.sum(masses * np.sum(v * v, axis=1)))
+    for i in range(3):
+        for j in range(i + 1, 3):
+            d = r[j] - r[i]
+            e -= masses[i] * masses[j] / math.sqrt(d @ d + eps * eps)
+    return e
+
+
+def momentum(y, masses=MASSES):
+    return (masses[:, None] * y[6:].reshape(3, 2)).sum(axis=0)
+
+
+def angular_momentum(y, masses=MASSES):
+    r = y[:6].reshape(3, 2)
+    v = y[6:].reshape(3, 2)
+    return float(np.sum(masses * (r[:, 0] * v[:, 1] - r[:, 1] * v[:, 0])))
+
+
+def manufactured() -> ManufacturedODE:
+    def u(t):
+        pos = [np.cos(t), 0.3 * np.sin(t), -0.8 + 0.2 * np.sin(1.3 * t), 0.9, 0.1 * t, -1.0 + 0.4 * np.cos(t)]
+        vel = [np.sin(0.7 * t), 0.5, -0.3 + 0.1 * t, np.cos(1.1 * t), 0.2, -0.4 * np.sin(t)]
+        return np.array(pos + vel)
+
+    return ManufacturedODE(u, rhs_reference())
+
+
+def verlet_integrate(integrators, masses=MASSES):
+    def integrate(source, y0, t_end, n):
+        if source is not zero_source:
+            raise ValueError("verlet_step has no source-term hook")
+        y = np.array(y0, dtype=float)
+        for _ in range(n):
+            y = integrators.verlet_step(y, masses, t_end / n)
+        return y
+
+    return integrate
+
+
+def _exact_drift(label, integrate, quantity, ns, t_end=T_END, y0=Y0_FREE):
+    def run():
+        q0 = np.atleast_1d(quantity(y0))
+        hs, errs = [], []
+        for n in ns:
+            hs.append(t_end / n)
+            errs.append(float(np.max(np.abs(np.atleast_1d(quantity(integrate(zero_source, y0, t_end, n))) - q0))))
+        return check_exact(hs, errs, scale=max(float(np.max(np.abs(y0))), 1.0))
+
+    return Check("invariant", label, run)
+
+
+def reversibility_check(integrate, ns=NS_VERLET) -> Check:
+    """Velocity Verlet is time-symmetric: forward, flip velocities, forward again, flip: back to the start."""
+
+    def run():
+        hs, errs = [], []
+        for n in ns:
+            y = integrate(zero_source, Y0_FREE, T_END, n)
+            y = np.concatenate([y[:6], -y[6:]])
+            y = integrate(zero_source, y, T_END, n)
+            y = np.concatenate([y[:6], -y[6:]])
+            hs.append(T_END / n)
+            errs.append(max_abs_error(y, Y0_FREE))
+        return check_exact(hs, errs, floor=1e-11, scale=float(np.max(np.abs(Y0_FREE))))
+
+    return Check("patch", "verlet_step time reversal", run)
+
+
+def binary_closure_check(integrators, ns=NS_VERLET) -> Check:
+    """Two unit masses on a circular orbit of separation 1; the third body has zero mass.
+
+    Period T = 2 pi / sqrt(2) up to a softening correction of order eps^2 (about 1e-8),
+    far below the Verlet error at these steps. The orbit must close at second order.
+    """
+    masses = np.array([1.0, 1.0, 0.0])
+    v = math.sqrt(0.5) * (1.0 + EPS * EPS) ** -0.75  # circular speed with softened force
+    y0 = np.array([-0.5, 0.0, 0.5, 0.0, 30.0, 0.0, 0.0, -v, 0.0, v, 0.0, 0.0])
+    omega = 2.0 * v  # angular speed of each body about the centre
+    period = 2.0 * math.pi / omega
+    integrate = verlet_integrate(integrators, masses)
+
+    def run():
+        hs, errs = [], []
+        for n in ns:
+            y = integrate(zero_source, y0, period, n)
+            hs.append(period / n)
+            errs.append(max_abs_error(y[[0, 1, 2, 3, 6, 7, 8, 9]], y0[[0, 1, 2, 3, 6, 7, 8, 9]]))
+        return check_order(hs, errs, 2.0)
+
+    return Check("limit", "verlet_step two-body circular orbit closes after one period", run)
+
+
+def driver_end_time_check(integrators, ns=NS_VERLET) -> Check:
+    """run_verlet_simulation((0, T), dt) should return the state at T, at Verlet's second order."""
+    y_ref = integrate_fixed(rhs_reference(), Y0_FREE, 0.0, T_END, 16 * max(ns), rk4)
+
+    def run():
+        hs, errs, last = [], [], []
+        for n in ns:
+            times, states = integrators.run_verlet_simulation(Y0_FREE, MASSES, (0.0, T_END), T_END / n)
+            hs.append(T_END / n)
+            errs.append(max_abs_error(states[:, -1], y_ref))
+            last.append(float(times[-1]))
+        result = check_order(hs, errs, 2.0, scale=float(np.max(np.abs(y_ref))))
+        result.message += f"; last time returned {last[0]:.6g} for t_end = {T_END:g}, dt = {hs[0]:.3g}"
+        return result
+
+    return Check("reference", "run_verlet_simulation final state at t_end", run)
+
+
+def energy_function_check(physics) -> Check:
+    """physics.calculate_energy against the softened energy that the dynamics conserves."""
+
+    def run():
+        e_code = float(physics.calculate_energy(Y0_FREE, MASSES)[0])
+        e_soft = energy_reference(Y0_FREE)
+        diff = abs(e_code - e_soft)
+        if diff <= 1e-12:
+            return Result(EXACT, f"matches the softened energy (diff {diff:.1e})")
+        return Result(
+            FAIL,
+            f"differs from the energy the softened dynamics conserves by {diff:.2g} "
+            f"(relative {diff / abs(e_soft):.1g}): potential is not softened",
+        )
+
+    return Check("invariant", "calculate_energy is the conserved quantity", run)
+
+
+def solve_ivp_check(integrators, physics) -> Check:
+    def run():
+        t_end = 2.0
+        y_ref = integrate_fixed(rhs_reference(), Y0_FREE, 0.0, t_end, 20000, rk4)
+        sol = integrators.run_simulation(physics.get_derivatives, (0.0, t_end), Y0_FREE, MASSES)
+        err = max_abs_error(sol.y[:, -1], y_ref)
+        if err <= 1e-7:
+            return Result(PASS, f"default rtol=1e-9 reaches {err:.1e} at t = {t_end:g}")
+        return Result(FAIL, f"error {err:.3g} at default tolerances")
+
+    return Check("reference", "run_simulation (solve_ivp RK45) at default tolerances", run)
+
+
+def checks(loaded=None) -> list[Check]:
+    physics, integrators = loaded or load()
+
+    def rhs(t, y):
+        return np.asarray(physics.get_derivatives(t, np.asarray(y, dtype=float), MASSES), dtype=float)
+
+    rk4_int = make_integrate(rhs, frozenset(), "rk4")
+    out = ode_checks(
+        "get_derivatives + physverify RK4",
+        rk4_int,
+        rhs_ref=rhs_reference(),
+        mms=manufactured(),
+        y0_free=Y0_FREE,
+        t_end=T_END,
+        ns=NS_RK4,
+        order=4.0,
+        quantity=energy_reference,
+        patch=(manufactured().value(0.0), np.array([0.1, -0.2, 0.3, 0.05, -0.1, 0.2] + [0.0] * 6)),
+        integrate_trajectory=make_integrate(rhs, frozenset(), "rk4", trajectory=True),
+    )
+    out.append(energy_function_check(physics))
+    if integrators is None:
+        return out
+    verlet = verlet_integrate(integrators)
+    out += [
+        Check("reference", "verlet_step", lambda: reference_study(verlet, rhs_reference(), Y0_FREE, T_END, NS_VERLET, 2.0)),
+        Check(
+            "invariant",
+            "verlet_step energy",
+            lambda: invariant_study(verlet, energy_reference, Y0_FREE, T_END, NS_VERLET, 2.0),
+        ),
+        _exact_drift("verlet_step total momentum", verlet, momentum, NS_VERLET),
+        _exact_drift("verlet_step angular momentum", verlet, angular_momentum, NS_VERLET),
+        reversibility_check(verlet),
+        binary_closure_check(integrators),
+        driver_end_time_check(integrators),
+        solve_ivp_check(integrators, physics),
+    ]
+    return out

physverify/agent.py

@@ -0,0 +1,265 @@
+"""Connect physverify to an AI coding assistant: a Claude Code hook and a minimal MCP server.
+
+Both are thin layers over `physverify.report` (the same code as `physverify run`),
+and the core works without them.
+
+Hook (`physverify hook`)
+    For Claude Code's PostToolUse event. It reads the event JSON on stdin. After
+    an edit to a .py file it runs the project's specs, and when a check fails it
+    prints a summary on stderr and exits 2, which Claude Code passes back to the
+    assistant. Otherwise it exits 0 and prints nothing. See docs/agent.md.
+
+MCP server (`physverify mcp`)
+    Model Context Protocol over stdio (newline-delimited JSON-RPC 2.0), with one
+    tool, `run_checks`, that takes spec paths and returns the JSON report. It is
+    written with the standard library only, so it has no extra dependency; it
+    implements the parts of the protocol a tool server needs, not the whole
+    specification. It serves both protocol eras on the same process:
+      - legacy (2025-11-25 and earlier): the client opens with `initialize`;
+      - modern (2026-07-28): no handshake, every request carries its protocol
+        version in `_meta`, and `server/discover` reports what the server supports.
+    A request that carries the modern `_meta` version is served the modern way; an
+    `initialize` request selects legacy behaviour.
+
+Specs are found in this order: `[tool.physverify] specs = [...]` in the nearest
+pyproject.toml, otherwise every verify_*.py under the project folder (skipping
+hidden folders, virtual environments and build output).
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+SKIP_DIRS = {"venv", ".venv", "env", "node_modules", "build", "dist", "__pycache__", "site-packages"}
+MAX_REPORTED = 10
+
+
+def find_project_root(start: Path) -> Path:
+    start = start.resolve()
+    for folder in [start, *start.parents]:
+        if (folder / "pyproject.toml").is_file() or (folder / ".git").exists():
+            return folder
+    return start
+
+
+def find_specs(root: Path) -> list[Path]:
+    root = Path(root)
+    pyproject = root / "pyproject.toml"
+    if pyproject.is_file():
+        try:
+            import tomllib
+
+            config = tomllib.loads(pyproject.read_text(encoding="utf-8")).get("tool", {}).get("physverify", {})
+        except Exception:
+            config = {}
+        if config.get("specs"):
+            return [(root / s).resolve() for s in config["specs"]]
+    specs = []
+    for path in sorted(root.rglob("verify_*.py")):
+        parts = path.relative_to(root).parts[:-1]
+        if any(p.startswith(".") or p in SKIP_DIRS for p in parts):
+            continue
+        specs.append(path)
+    return specs
+
+
+def run_specs(specs) -> dict:
+    """Run every spec; returns the JSON report as a dict, with load errors listed separately.
+
+    Anything the code under test prints goes to stderr, so that it cannot corrupt
+    the MCP stream on stdout.
+    """
+    import contextlib
+
+    from .report import load_spec, run_checks, to_json
+
+    outcomes, load_errors = [], []
+    with contextlib.redirect_stdout(sys.stderr):
+        for spec in specs:
+            try:
+                outcomes += run_checks(load_spec(spec))
+            except Exception as exc:
+                load_errors.append({"spec": str(spec), "error": f"{type(exc).__name__}: {exc}"})
+    report = json.loads(to_json(outcomes, ", ".join(str(s) for s in specs)))
+    report["load_errors"] = load_errors
+    return report
+
+
+def failure_summary(report: dict) -> str:
+    failed = [c for c in report["checks"] if not c["ok"]]
+    lines = [f"physverify: {len(failed)} of {report['summary']['total']} checks did not pass."]
+    for c in failed[:MAX_REPORTED]:
+        lines.append(f"- {c['status']} [{c['family']}] {c['label']}: {c['message']}")
+    if len(failed) > MAX_REPORTED:
+        lines.append(f"- ... and {len(failed) - MAX_REPORTED} more")
+    for e in report["load_errors"]:
+        lines.append(f"- could not load {e['spec']}: {e['error']}")
+    lines.append("Run `physverify run <spec> --html report.html` for convergence plots.")
+    return "\n".join(lines)
+
+
+def hook_main(stdin=None, stderr=None) -> int:
+    stdin = stdin or sys.stdin
+    stderr = stderr or sys.stderr
+    try:
+        event = json.load(stdin)
+    except (json.JSONDecodeError, ValueError):
+        return 0  # not a hook event; never block the assistant on our own input problem
+    tool_input = event.get("tool_input") or {}
+    edited = tool_input.get("file_path") or tool_input.get("notebook_path") or ""
+    if edited and not edited.endswith(".py"):
+        return 0
+    cwd = Path(event.get("cwd") or ".")
+    root = find_project_root(Path(edited).parent if edited else cwd)
+    specs = find_specs(root)
+    if not specs:
+        return 0
+    report = run_specs(specs)
+    if report["summary"]["not_ok"] or report["load_errors"]:
+        print(failure_summary(report), file=stderr)
+        return 2
+    return 0
+
+
+# --- MCP server ---
+
+MODERN_VERSION = "2026-07-28"
+LEGACY_VERSIONS = ("2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05")  # newest first
+
+META_VERSION = "io.modelcontextprotocol/protocolVersion"
+META_CAPABILITIES = "io.modelcontextprotocol/clientCapabilities"
+META_SERVER_INFO = "io.modelcontextprotocol/serverInfo"
+
+INVALID_PARAMS = -32602
+METHOD_NOT_FOUND = -32601
+UNSUPPORTED_PROTOCOL_VERSION = -32022
+
+CACHE_HINTS = {"ttlMs": 300_000, "cacheScope": "public"}  # the tool list does not change while the server runs
+INSTRUCTIONS = (
+    "Run physverify checks on physics simulation code after writing or editing it. "
+    "The tool executes the project's verify_*.py spec files (Python), so use it only on projects you trust."
+)
+
+TOOLS = [
+    {
+        "name": "run_checks",
+        "description": (
+            "Run physverify verification checks (manufactured solutions, order of convergence, "
+            "invariants, limits, exactness) on physics simulation code. Takes spec files that "
+            "define checks(); with no specs given, finds verify_*.py files under `project`. "
+            "Returns a JSON report: per check family, label, status (PASS, EXACT, FAIL, "
+            "INCONCLUSIVE, ERROR), message, observed and expected order, step sizes and errors."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "specs": {"type": "array", "items": {"type": "string"}, "description": "spec file paths"},
+                "project": {"type": "string", "description": "project folder to search for verify_*.py"},
+            },
+        },
+    }
+]
+
+
+def _error(msg_id, code: int, message: str, data=None) -> dict:
+    error = {"code": code, "message": message}
+    if data is not None:
+        error["data"] = data
+    return {"jsonrpc": "2.0", "id": msg_id, "error": error}
+
+
+def _run_checks_tool(arguments: dict) -> dict:
+    """The tools/call result body (content and isError), identical in both protocol eras."""
+    specs = [Path(s) for s in arguments.get("specs") or []]
+    if not specs:
+        specs = find_specs(Path(arguments.get("project") or "."))
+    if not specs:
+        return {"content": [{"type": "text", "text": "No spec files found (verify_*.py defining checks())."}], "isError": True}
+    report = run_specs(specs)
+    failed = bool(report["summary"]["not_ok"] or report["load_errors"])
+    text = (failure_summary(report) + "\n\n" if failed else "") + json.dumps(report, indent=2)
+    return {"content": [{"type": "text", "text": text}], "isError": False}
+
+
+def handle(message: dict):
+    """Answer one JSON-RPC message; returns the response dict, or None for a notification."""
+    from . import __version__
+
+    method = message.get("method")
+    msg_id = message.get("id")
+    if msg_id is None:
+        return None  # notifications (initialized, cancelled, ...) need no answer
+    params = message.get("params") or {}
+    meta = params.get("_meta") if isinstance(params.get("_meta"), dict) else {}
+    server_info = {"name": "physverify", "version": __version__}
+
+    def ok(result):
+        return {"jsonrpc": "2.0", "id": msg_id, "result": result}
+
+    # Legacy era: the handshake. `initialize` always selects legacy behaviour.
+    if method == "initialize":
+        requested = params.get("protocolVersion")
+        version = requested if requested in LEGACY_VERSIONS else LEGACY_VERSIONS[0]
+        return ok({"protocolVersion": version, "capabilities": {"tools": {}}, "serverInfo": server_info})
+
+    # Modern era: no handshake; the request itself says which version it speaks.
+    # `server/discover` exists only in this era, so it is always treated as modern.
+    if META_VERSION in meta or method == "server/discover":
+        requested = meta.get(META_VERSION)
+        if requested is None or META_CAPABILITIES not in meta:
+            return _error(msg_id, INVALID_PARAMS, f"missing required _meta field: {META_VERSION!r} and {META_CAPABILITIES!r} are required on every request")
+        if requested != MODERN_VERSION:
+            return _error(msg_id, UNSUPPORTED_PROTOCOL_VERSION, "Unsupported protocol version", {"supported": [MODERN_VERSION], "requested": requested})
+
+        def modern(result, cacheable=False):
+            body = {"resultType": "complete", **result, "_meta": {META_SERVER_INFO: server_info}}
+            if cacheable:
+                body.update(CACHE_HINTS)
+            return ok(body)
+
+        if method == "server/discover":
+            return modern({"supportedVersions": [MODERN_VERSION], "capabilities": {"tools": {}}, "instructions": INSTRUCTIONS}, cacheable=True)
+        if method == "ping":
+            return modern({})
+        if method == "tools/list":
+            return modern({"tools": TOOLS}, cacheable=True)
+        if method == "tools/call":
+            if params.get("name") != "run_checks":
+                return _error(msg_id, INVALID_PARAMS, f"unknown tool {params.get('name')!r}")
+            return modern(_run_checks_tool(params.get("arguments") or {}))
+        return _error(msg_id, METHOD_NOT_FOUND, f"method not found: {method}")
+
+    # Legacy era, after the handshake: results carry no resultType or cache hints.
+    if method == "ping":
+        return ok({})
+    if method == "tools/list":
+        return ok({"tools": TOOLS})
+    if method == "tools/call":
+        if params.get("name") != "run_checks":
+            return _error(msg_id, INVALID_PARAMS, f"unknown tool {params.get('name')!r}")
+        return ok(_run_checks_tool(params.get("arguments") or {}))
+    return _error(msg_id, METHOD_NOT_FOUND, f"method not found: {method}")
+
+
+def mcp_main(stdin=None, stdout=None) -> int:
+    stdin = stdin or sys.stdin
+    stdout = stdout or sys.stdout
+    for line in stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            message = json.loads(line)
+        except json.JSONDecodeError:
+            response = {"jsonrpc": "2.0", "id": None, "error": {"code": -32700, "message": "parse error"}}
+        else:
+            try:
+                response = handle(message)
+            except Exception as exc:  # keep the server alive; report the failure to the client
+                response = {"jsonrpc": "2.0", "id": message.get("id"), "error": {"code": -32603, "message": f"{type(exc).__name__}: {exc}"}}
+        if response is not None:
+            stdout.write(json.dumps(response) + "\n")
+            stdout.flush()
+    return 0

physverify/checks.py

@@ -0,0 +1,59 @@
+"""Result types shared by every check."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable
+
+import numpy as np
+
+PASS = "PASS"
+FAIL = "FAIL"
+EXACT = "EXACT"  # error below the noise floor at every resolution
+INCONCLUSIVE = "INCONCLUSIVE"
+ERROR = "ERROR"  # the code under test raised an exception
+
+FAMILIES = ("mms", "reference", "invariant", "limit", "patch")
+
+
+@dataclass
+class Result:
+    status: str
+    message: str = ""
+
+    @property
+    def ok(self) -> bool:
+        return self.status in (PASS, EXACT)
+
+
+@dataclass
+class OrderResult(Result):
+    expected: float = float("nan")
+    fitted: float = float("nan")
+    hs: tuple = ()
+    errors: tuple = ()
+
+
+@dataclass
+class Check:
+    """One runnable check. `family` says which kind of evidence it gives:
+
+    mms        manufactured-solution order study against an independent reference operator
+    reference  comparison with an independently written reference solution
+    invariant  drift of a conserved quantity as the resolution is refined
+    limit      a known limiting case (analytic range, normal-mode frequencies, ...)
+    patch      a manufactured solution the scheme should reproduce exactly (to round-off),
+               so any error at all is a bug, whatever its order
+    """
+
+    family: str
+    label: str
+    run: Callable[[], Result]
+
+
+def run_check(check: Check) -> Result:
+    try:
+        with np.errstate(all="ignore"):  # a buggy code may overflow; the order check reports non-finite errors
+            return check.run()
+    except Exception as exc:  # the code under test may crash; that is a finding too
+        return Result(ERROR, f"{type(exc).__name__}: {exc}")