diff --git a/agents/anyplot/briefs.py b/agents/anyplot/briefs.py
index 2b4460e243e..d9fbf607fe8 100644
--- a/agents/anyplot/briefs.py
+++ b/agents/anyplot/briefs.py
@@ -10,7 +10,8 @@
 from collections.abc import Iterator, Sequence
 from typing import Any
 
-from .data.roles import DataRole
+from core.spec_roles import DataRole
+
 from .policy import fence
 from .schemas import MAX_TOP_VALUES, Binding, DatasetProfile
 from .session_state import SessionView
diff --git a/agents/anyplot/code/readiness.py b/agents/anyplot/code/readiness.py
index b6e6aaac3f4..eec862d52b6 100644
--- a/agents/anyplot/code/readiness.py
+++ b/agents/anyplot/code/readiness.py
@@ -74,7 +74,9 @@
 from dataclasses import dataclass, field
 from typing import Literal
 
+from core.adaptability import CRITICAL_VALUES
 from core.palette import IMPRINT
+from core.spec_roles import MAP_SPECS
 
 from ..schemas import MAX_NOTE_CHARS
 from .normalise import SUPPORTED_LIBRARIES, measure_canvas
@@ -84,25 +86,7 @@
 
 ReadinessStatus = Literal["blocked", "coupled", "clean"]
 
-MAP_SPECS = frozenset(
-    {
-        "bubble-map-geographic",
-        "cartogram-area-distortion",
-        "choropleth-basic",
-        "contour-map-geographic",
-        "flowmap-origin-destination",
-        "heatmap-geographic",
-        "map-connection-lines",
-        "map-marker-clustered",
-        "map-projections",
-        "map-route-path",
-        "map-tile-background",
-        "map-tilegrid",
-        "scatter-map-geographic",
-    }
-)
 MIN_PALETTE_ENTRIES = 6
-CRITICAL_VALUES = frozenset({1.645, 1.96, 2.326, 2.576, 3.291})
 MAX_SECURITY_REASONS = 5
 MAX_SNIPPET_CHARS = 48
 MAX_LINE_SNIPPET_CHARS = 2 * MAX_SNIPPET_CHARS
diff --git a/agents/anyplot/data/bindings.py b/agents/anyplot/data/bindings.py
index 7964df0b3f6..bc72615093e 100644
--- a/agents/anyplot/data/bindings.py
+++ b/agents/anyplot/data/bindings.py
@@ -41,10 +41,11 @@
 from dataclasses import dataclass, field
 from difflib import SequenceMatcher
 
+from core.spec_roles import DataRole, RoleKind
+
 from ..schemas import Binding, ColumnDtype, ColumnProfile, DatasetProfile
 from .computed import match_score, window_line, window_rank
 from .parse import value_like
-from .roles import DataRole, RoleKind
 from .shape import long_suggestion, takes_labels
 from .signs import has_negative, sign_line
 from .temporal import CAMEL as _CAMEL
diff --git a/agents/anyplot/data/computed.py b/agents/anyplot/data/computed.py
index 186f914ac92..d522cb24275 100644
--- a/agents/anyplot/data/computed.py
+++ b/agents/anyplot/data/computed.py
@@ -29,7 +29,7 @@
 from collections.abc import Iterable
 from dataclasses import replace
 
-from .roles import DataRole
+from core.spec_roles import DataRole
 
 
 COMPUTED_ROLES: dict[str, frozenset[str]] = {
diff --git a/agents/anyplot/data/shape.py b/agents/anyplot/data/shape.py
index 2b8e5b6c139..4b642f71057 100644
--- a/agents/anyplot/data/shape.py
+++ b/agents/anyplot/data/shape.py
@@ -71,12 +71,13 @@
 from dataclasses import dataclass
 from typing import Any
 
+from core.spec_roles import DataRole
+
 from ..language import DEFAULT_LANGUAGE, canonical
 from ..schemas import MAX_ROWS, Binding, ColumnProfile, DatasetProfile
 from .months import fold, named_months
 from .parse import ID_WORDS
 from .prepare import MAX_LONGER_COLUMNS
-from .roles import DataRole
 from .temporal import WORDS, time_keys
 
 
diff --git a/agents/anyplot/data/signs.py b/agents/anyplot/data/signs.py
index d5fcc76a298..fa9b10b5d49 100644
--- a/agents/anyplot/data/signs.py
+++ b/agents/anyplot/data/signs.py
@@ -25,8 +25,9 @@
 from collections.abc import Iterable
 from dataclasses import replace
 
+from core.spec_roles import DataRole
+
 from ..schemas import ColumnProfile
-from .roles import DataRole
 
 
 NON_NEGATIVE_ROLES: frozenset[str] = frozenset(
diff --git a/agents/anyplot/schemas.py b/agents/anyplot/schemas.py
index 3aab0c0c1a8..547a5635012 100644
--- a/agents/anyplot/schemas.py
+++ b/agents/anyplot/schemas.py
@@ -43,6 +43,8 @@
     model_validator,
 )
 
+from core.spec_roles import ROLE_PATTERN
+
 from .language import DEFAULT_LANGUAGE, LANGUAGE_PATTERN
 
 
@@ -158,10 +160,7 @@ def artifact_names(themes: Iterable[str]) -> list[ArtifactName]:
     return names + code_and_data
 
 
-# A role is matched against the spec's `## Data` bullets later; the pattern only keeps
-# arbitrary text out. Digits and capitals are allowed because 21 of 325 specs name
-# roles such as `log2_fold_change`, `lower_95` or `temperature_K`.
-ROLE_PATTERN = r"^[A-Za-z_][A-Za-z0-9_]{0,31}$"
+# ROLE_PATTERN (imported above) lives with the role parser in core/spec_roles.py.
 RENDER_ID_PATTERN = r"^[A-Za-z0-9_-]{1,64}$"
 
 _WHITESPACE = re.compile(r"\s+")
diff --git a/agents/anyplot/session_state.py b/agents/anyplot/session_state.py
index b5b17fd1c2d..db43dd4db7e 100644
--- a/agents/anyplot/session_state.py
+++ b/agents/anyplot/session_state.py
@@ -20,9 +20,10 @@
 
 from pydantic import BaseModel, ConfigDict, Field, model_validator
 
+from core.spec_roles import DataRole, parse_roles
+
 from .data.bindings import BindingCheck, check_bindings, resolve_role
 from .data.computed import mark_computed
-from .data.roles import DataRole, parse_roles
 from .data.signs import mark_non_negative
 from .language import DEFAULT_LANGUAGE, SOURCES, LanguageSource, is_valid
 from .schemas import MAX_CODE_CHARS, Binding, DatasetProfile
diff --git a/agents/main.py b/agents/main.py
index 7c186733dc0..709ebb4c553 100644
--- a/agents/main.py
+++ b/agents/main.py
@@ -135,7 +135,6 @@
 
 from agents.anyplot import agent as agent_module
 from agents.anyplot import telemetry
-from agents.anyplot.code.readiness import MAP_SPECS
 from agents.anyplot.data.bindings import check_bindings, label_siblings
 from agents.anyplot.data.classify import classify_paste
 from agents.anyplot.data.parse import (
@@ -149,7 +148,6 @@
     without_context,
 )
 from agents.anyplot.data.prepare import Operation, PrepareError, apply_operations, with_date_notes
-from agents.anyplot.data.roles import DataRole
 from agents.anyplot.data.shape import long_suggestion
 from agents.anyplot.data.store import StoreFull
 from agents.anyplot.data.transcribe import (
@@ -238,6 +236,7 @@
 )
 from agents.stream import MAX_DONE_ROLES, Translator
 from core.constants import SUPPORTED_LIBRARIES
+from core.spec_roles import MAP_SPECS, DataRole
 
 
 logger = logging.getLogger("anyplot.agents")
diff --git a/automation/scripts/adaptability_check.py b/automation/scripts/adaptability_check.py
new file mode 100644
index 00000000000..d843782f8d5
--- /dev/null
+++ b/automation/scripts/adaptability_check.py
@@ -0,0 +1,2787 @@
+#!/usr/bin/env python3
+"""The adaptability checker as one standard-library file, for the workflow runner.
+
+GENERATED by `uv run python -m core.adaptability_mirror` from core/spec_roles.py and
+core/adaptability.py; edit those modules, never this file. The module docstring of
+core/adaptability.py describes the rules and the record; this copy runs where `core`
+is not importable:
+
+    python3 adaptability_check.py check plots/<spec>/implementations/python/<library>.py
+    python3 adaptability_check.py report plots/
+
+tests/unit/core/test_adaptability_mirror.py keeps it identical to the build.
+"""
+
+from __future__ import annotations
+
+import argparse
+import ast
+import builtins
+import io
+import json
+import random
+import re
+import sys
+import tokenize
+from collections import Counter
+from collections.abc import Callable, Iterable, Iterator, Mapping, Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal
+
+
+# --- core/spec_roles.py ----------------------------------------------------------------------------------
+
+# A role is matched against the spec's `## Data` bullets later; the pattern only keeps
+# arbitrary text out. Digits and capitals are allowed because 21 of 325 specs name
+# roles such as `log2_fold_change`, `lower_95` or `temperature_K`.
+ROLE_PATTERN = r"^[A-Za-z_][A-Za-z0-9_]{0,31}$"
+
+RoleKind = Literal["numeric", "categorical", "datetime", "text", "boolean"]
+
+MAX_ROLE_NAME_CHARS = 32
+MAX_VARIADIC_NAME_CHARS = 30
+
+TYPE_WORDS: dict[str, RoleKind] = {
+    "numeric": "numeric",
+    "numerical": "numeric",
+    "number": "numeric",
+    "numbers": "numeric",
+    "float": "numeric",
+    "floats": "numeric",
+    "double": "numeric",
+    "int": "numeric",
+    "ints": "numeric",
+    "integer": "numeric",
+    "integers": "numeric",
+    "continuous": "numeric",
+    "count": "numeric",
+    "counts": "numeric",
+    "categorical": "categorical",
+    "category": "categorical",
+    "categories": "categorical",
+    "ordinal": "categorical",
+    "nominal": "categorical",
+    "datetime": "datetime",
+    "date": "datetime",
+    "dates": "datetime",
+    "time": "datetime",
+    "timestamp": "datetime",
+    "timestamps": "datetime",
+    "string": "text",
+    "strings": "text",
+    "str": "text",
+    "text": "text",
+    "label": "text",
+    "labels": "text",
+    "boolean": "boolean",
+    "bool": "boolean",
+    "binary": "boolean",
+}
+
+QUALIFIER_WORDS: frozenset[str] = frozenset(
+    {
+        "optional",
+        "required",
+        "array",
+        "arrays",
+        "list",
+        "lists",
+        "of",
+        "or",
+        "and",
+        "d",  # the letter left from "1D", "2D"
+        "matrix",
+        "pair",
+        "pairs",
+        "column",
+        "columns",
+        "metadata",
+        "ordered",
+    }
+)
+
+# Possessive quantifiers (`*+`, `++`) and the run-start lookbehinds keep every
+# pattern linear in the bullet length: nothing after a whitespace or digit run
+# can match inside that run, so there is never anything to backtrack into.
+_HEAD_TOKEN = re.compile(
+    r"\s*+(?:`(?P<code>[^`]++)`|(?P<more>\.\.\.|…)|(?P<range>through|to)\b|(?P<alt>or)\b|(?P<sep>,|/|and\b))",
+    re.IGNORECASE,
+)
+_TAIL = re.compile(r"\s*+(?:\((?P<type>[^)]*+)\))?\s*+(?:[-–—:]++\s*+)?(?P<desc>.*)", re.DOTALL)
+_BOLD = re.compile(r"\*\*(?P<label>[^*]++)\*\*\s*+[-–—:]?\s*+(?P<desc>.*)", re.DOTALL)
+_BOLD_LABEL_END = re.compile(r"(?<!\s)\s++(?:variable|variables|column|columns)$", re.IGNORECASE)
+_DIGITS = frozenset("0123456789")
+_OPTIONAL = re.compile(r"\boptional\b", re.IGNORECASE)
+_WORD = re.compile(r"[a-z]+")
+_BACKTICKED = re.compile(r"`[^`]*`")
+_INVALID_NAME_CHARS = re.compile(r"[^A-Za-z0-9_]+")
+_ROLE_NAME = re.compile(ROLE_PATTERN)
+COMPUTED = re.compile(r"(?:computed|calculated|derived)\b", re.IGNORECASE)
+"""A description that starts so names a value the plot computes from the other roles (`rolling_avg` of
+`line-timeseries-rolling`: "Computed rolling average (e.g., 7-day, 30-day window)"). Only the start counts:
+"values computed as x(t)" or "used to compute distances" describe data. A spec opts a role in by its wording."""
+
+
+@dataclass(frozen=True)
+class DataRole:
+    """One data role a spec declares; `variadic` roles bind `<name>1`, `<name>2`, ..."""
+
+    name: str
+    kinds: tuple[RoleKind, ...]
+    required: bool
+    variadic: bool
+    description: str
+    non_negative: bool = False
+    """Whether the role needs values of 0 or more: set per spec by `signs.mark_non_negative`, never parsed."""
+    computed: bool = False
+    """Whether the plot can compute the role from the data (`rolling_avg`: "Computed rolling average ...", by
+    `COMPUTED`, or listed in `computed.COMPUTED_ROLES`): optional, bound when a column holds it, else the adapter
+    computes it (owner decision of 2026-10-15, "both allowed")."""
+
+    def member(self, index: int) -> str:
+        """The binding role name of the `index`-th (1-based) column of a variadic family."""
+        return f"{self.name}{index}"
+
+
+def parse_roles(data_bullets: list[str]) -> list[DataRole]:
+    """The roles declared by a spec's stored `## Data` bullets, in bullet order."""
+    roles: list[DataRole] = []
+    taken: set[str] = set()
+    for bullet in data_bullets:
+        for role in _parse_bullet(bullet.strip()):
+            if role.name not in taken:
+                taken.add(role.name)
+                roles.append(role)
+    return roles
+
+
+def type_words(type_text: str) -> tuple[tuple[RoleKind, ...], list[str]]:
+    """Kinds from the text inside a bullet's type parentheses, plus the unknown words that made it `text`."""
+    words = _WORD.findall(_BACKTICKED.sub(" ", type_text).lower())
+    kinds = _ordered_kinds(words)
+    if kinds:
+        return kinds, []
+    unknown = [word for word in words if word not in QUALIFIER_WORDS]
+    return (("text",), unknown) if unknown else ((), [])
+
+
+def _ordered_kinds(words: list[str]) -> tuple[RoleKind, ...]:
+    kinds: list[RoleKind] = []
+    for word in words:
+        kind = TYPE_WORDS.get(word)
+        if kind is not None and kind not in kinds:
+            kinds.append(kind)
+    return tuple(kinds)
+
+
+def _parse_bullet(bullet: str) -> list[DataRole]:
+    if bullet.startswith("**"):
+        return _parse_bold(bullet)
+    if not bullet.startswith("`"):
+        return []
+
+    names: list[str] = []
+    more = through = alternative = False
+    position = end = 0
+    while match := _HEAD_TOKEN.match(bullet, position):
+        position = match.end()
+        if match.group("code") is not None:
+            for item in match.group("code").split(","):
+                item = item.strip()
+                if item in ("...", "…"):
+                    more = True
+                elif item:
+                    names.append(item)
+            end = position
+        elif match.group("more"):
+            more, end = True, position
+        elif match.group("range"):
+            through = True
+        elif match.group("alt"):
+            alternative = True
+    tail = _TAIL.match(bullet, end)  # every group is optional, so it always matches
+    type_text = (tail.group("type") or "") if tail else ""
+    description = (tail.group("desc") if tail else "").strip()
+    kinds, _ = type_words(type_text)
+    required = not _OPTIONAL.search(f"{type_text} {description}")
+    computed = bool(COMPUTED.match(description))
+
+    def role(name: str, variadic: bool = False) -> DataRole | None:
+        clean = _clean_name(name, MAX_VARIADIC_NAME_CHARS if variadic else MAX_ROLE_NAME_CHARS)
+        if clean is None:
+            return None
+        return DataRole(
+            name=clean, kinds=kinds, required=required, variadic=variadic, description=description, computed=computed
+        )
+
+    candidates: list[DataRole | None] = []
+    if through and len(names) >= 2 and (family := _range_family(names[0])):
+        candidates.append(role(family, variadic=True))
+    elif more:
+        families: list[str] = []
+        for name in names:
+            family = _without_last_digits(name)
+            if family == name:
+                candidates.append(role(name))
+            elif family and family not in families:
+                families.append(family)
+        candidates.extend(role(family, variadic=True) for family in families)
+    elif alternative and names:
+        candidates.append(role(names[0]))
+    else:
+        candidates.extend(role(name) for name in names)
+    return [candidate for candidate in candidates if candidate is not None]
+
+
+def _range_family(name: str) -> str | None:
+    """The family a range start such as `y1` or `yn` belongs to (`y`); None when the name has no index.
+
+    A trailing digit run is the index, else a trailing `n`; an empty family (`1`, `n`)
+    is no family. Plain string operations keep this linear in the name length.
+    """
+    family = name.rstrip("0123456789")
+    if family == name:
+        family = name[:-1] if name.endswith("n") else ""
+    return family or None
+
+
+def _without_last_digits(name: str) -> str:
+    """`name` without its last ASCII digit run (`y12` is `y`, `a1b2c` is `a1bc`); unchanged without digits."""
+    end = max((index for index, char in enumerate(name) if char in _DIGITS), default=-1) + 1
+    if end == 0:
+        return name
+    start = end
+    while start and name[start - 1] in _DIGITS:
+        start -= 1
+    return name[:start] + name[end:]
+
+
+def _parse_bold(bullet: str) -> list[DataRole]:
+    match = _BOLD.fullmatch(bullet)
+    if not match or not _BOLD_LABEL_END.search(match.group("label").strip()):
+        return []
+    label = _BOLD_LABEL_END.sub("", match.group("label").strip())
+    description = match.group("desc").strip()
+    name = _clean_name("_".join(_WORD.findall(label.lower())), MAX_ROLE_NAME_CHARS)
+    if name is None:
+        return []
+    kinds = _ordered_kinds(_WORD.findall(f"{label} {description}".lower()))
+    required = not _OPTIONAL.search(description)
+    return [DataRole(name=name, kinds=kinds, required=required, variadic=False, description=description)]
+
+
+def _clean_name(name: str, limit: int) -> str | None:
+    clean = _INVALID_NAME_CHARS.sub("_", name.strip())
+    if clean[:1].isdigit():
+        clean = f"_{clean}"
+    clean = clean[:limit]
+    if not any(char.isalnum() for char in clean):
+        return None
+    return clean if _ROLE_NAME.fullmatch(clean) else None
+
+
+# --- the `## Data` section of a specification.md ------------------------------------------
+
+_DATA_SECTION = re.compile(r"## Data\s*\n(.+?)(?=\n##|\Z)", re.DOTALL)
+
+
+def data_bullets(spec_markdown: str) -> list[str]:
+    """The `## Data` bullets of a `specification.md`, as `sync_to_postgres.py` stores them in `Spec.data`.
+
+    One string per line that starts with `- ` or `* ` once stripped, the marker removed;
+    an empty list when the spec has no `## Data` section.
+    """
+    match = _DATA_SECTION.search(spec_markdown)
+    if not match:
+        return []
+    bullets: list[str] = []
+    for line in match.group(1).strip().split("\n"):
+        line = line.strip()
+        if line.startswith(("- ", "* ")):
+            bullets.append(line[2:].strip())
+    return bullets
+
+
+# --- data shape ------------------------------------------------------------------------------
+
+Shape = Literal["table", "matrix", "network", "generated", "excluded"]
+SHAPES: tuple[Shape, ...] = ("table", "matrix", "network", "generated", "excluded")
+
+MAP_SPECS = frozenset(
+    {
+        "bubble-map-geographic",
+        "cartogram-area-distortion",
+        "choropleth-basic",
+        "contour-map-geographic",
+        "flowmap-origin-destination",
+        "heatmap-geographic",
+        "map-connection-lines",
+        "map-marker-clustered",
+        "map-projections",
+        "map-route-path",
+        "map-tile-background",
+        "map-tilegrid",
+        "scatter-map-geographic",
+    }
+)
+"""The 13 map specs: tagged both `plot_type: map` and `data_type: geospatial`. Their implementations
+pull basemaps, tiles or Natural Earth geometry over the network. `scatter-pitch-events` (a sports pitch
+tagged `map`) and `hexbin-map-geographic` (drawn from inline coordinates) are not on the list."""
+
+SHAPE_OVERRIDES: dict[str, tuple[Shape, str]] = {
+    "learning-curve-basic": ("matrix", "train_scores and validation_scores are per-fold score matrices"),
+    "pdp-basic": ("matrix", "the roles name a computed dependence and ICE curve matrix, not observations"),
+    "network-transport-static": ("network", "stations and routes are the node and edge tables"),
+    "upset-basic": ("table", "one row per element with its set memberships"),
+    "venn-labeled-items": ("table", "one row per item with the zone it falls in"),
+    "bifurcation-basic": ("generated", "a simulation of the logistic map over a parameter range"),
+    "chessboard-basic": ("generated", "rows and columns are the board size, not data columns"),
+    "curve-bias-variance-tradeoff": ("generated", "every curve follows from formulas over model complexity"),
+    "heatmap-mandelbrot": ("generated", "the roles are the window and iteration parameters of a fractal"),
+    "line-impurity-comparison": ("generated", "Gini and entropy curves computed from a probability grid"),
+    "line-tanabe-sugano": ("generated", "term energies computed from ligand-field formulas"),
+    "maze-circular": ("generated", "a maze generated from its ring count and seed"),
+    "maze-printable": ("generated", "a maze generated from its size and seed"),
+    "mohr-circle": ("generated", "three stress components define the circle"),
+    "psychrometric-basic": ("generated", "the chart's curves follow from psychrometric formulas"),
+    "tree-phylogenetic": ("generated", "the tree is encoded as a Newick string"),
+}
+"""Specs whose role bullets misfile them (docs/concepts/adaptable-code.md "Data shapes"), with the reason.
+heatmap-correlation and heatmap-clustered need no entry: their `matrix` roles already make them matrices, the
+lenient shape until a spec change retypes them as observations. An entry goes away when the spec pipeline
+retypes the roles so that the rule below files the spec correctly."""
+
+STRUCTURE_ROLES = frozenset({"nodes", "edges"})
+"""Roles that name a network's node or edge table rather than a column."""
+
+_DATA_KINDS = frozenset({"numeric", "categorical", "datetime", "boolean"})
+
+
+def spec_shape(spec_id: str, roles: Sequence[DataRole]) -> Shape:
+    """The data shape of `spec_id` with the parsed `roles` (the module docstring has the rule)."""
+    if spec_id in MAP_SPECS:
+        return "excluded"
+    if spec_id in SHAPE_OVERRIDES:
+        return SHAPE_OVERRIDES[spec_id][0]
+    names = [role.name.lower() for role in roles]
+    if any(name in STRUCTURE_ROLES for name in names):
+        return "network"
+    if any("matrix" in name for name in names):
+        return "matrix"
+    if roles and not any(kind in _DATA_KINDS for role in roles for kind in role.kinds):
+        return "generated"
+    return "table"
+
+
+def is_structure_role(role: DataRole, shape: Shape) -> bool:
+    """A role the shape satisfies without a column constant: a network's node or edge table, a matrix role."""
+    name = role.name.lower()
+    if shape == "network":
+        return name in STRUCTURE_ROLES or name in {"stations", "routes"}
+    if shape == "matrix":
+        return True
+    return False
+
+
+# --- colour-driving role ---------------------------------------------------------------------
+
+COLOR_ROLE_NAMES = frozenset(
+    {
+        "group",
+        "series",
+        "component",
+        "subcategory",
+        "split_group",
+        "fill_category",
+        "hue",
+        "color",
+        "colour",
+        "cluster",
+        "clusters",
+        "compound",
+        "branch",
+        "term",
+    }
+)
+"""Role names that colour the marks by their values: groups, series, stacked components, line identities. Not
+`symbol` or `cohort`: heatmap-periodic-table's element symbol and heatmap-cohort-retention's cohort label
+rows of a heatmap. Not `entity`: slope charts colour their lines by direction, not by entity."""
+COLOR_WORDS = re.compile(r"\b(?:colou?r(?:s|ed|ing)?|hue|legend|series|stacked|stacking|segments?)\b", re.IGNORECASE)
+"""Description words that name a colour encoding of a categorical role ("labels identifying each series",
+"Group identifier for color coding curves", "shown as stacked segments")."""
+_LABEL_KINDS = frozenset({"categorical", "text", "boolean"})
+
+
+def color_role(roles: Sequence[DataRole]) -> DataRole | None:
+    """The spec's colour-driving role, or None for a single-series plot (the module docstring has the rule)."""
+    for role in roles:
+        if not any(kind in _LABEL_KINDS for kind in role.kinds):
+            continue
+        if role.name.lower() in COLOR_ROLE_NAMES or COLOR_WORDS.search(role.description):
+            return role
+    return None
+
+
+# --- core/adaptability.py --------------------------------------------------------------------------------
+
+CHECKER_VERSION = 1
+DEFECT_ID = "CQ-01"
+CODE_RENDER = "code"
+DEFECT_ARROW = "→"
+
+CANONICAL_IMPRINT = ("#009E73", "#C475FD", "#4467A3", "#BD8233", "#AE3030", "#2ABCCD", "#954477", "#99B314")
+"""The Imprint palette in canonical order (core/palette.py `IMPRINT`; a test pins the two)."""
+PALETTE_NAMES = frozenset({"IMPRINT", "IMPRINT_PALETTE"})
+CRITICAL_VALUES = frozenset({1.645, 1.96, 2.326, 2.576, 3.291})
+"""Statistical critical values: data-independent constants in a computation, never sample coordinates."""
+NEUTRAL_VALUES = frozenset({-1.0, 0.0, 1.0})
+FIXED_DOMAINS = ((0.0, 1.0, 0.2), (-1.0, 1.0, 0.2), (0.0, 100.0, 0.1), (0.0, 360.0, 0.1))
+"""Fixed domains as `(low, high, headroom)`: values span one when they reach both bounds within the headroom,
+a share of the domain's width (`set_ylim(-0.15, 1.02)`, `set_ylim(0, 105)`). Unit domains get more headroom:
+a degree or percentage axis padded by more than a tenth is a data range that happens to start near 0."""
+PADDING = 1.5
+"""A literal bound this small beside a computed one is padding (`set_xlim(-0.5, n - 0.5)`), not a coordinate."""
+MIN_COUNT = 3
+"""Counts below this are too common (a pair, a single panel) to tie a literal to the sample."""
+RESOLUTION_COUNT = 50
+"""A `linspace` of this many points or more is a curve's resolution, not a count of the sample."""
+PROSE_WORDS = frozenset(
+    {"total", "other", "others", "all", "none", "mean", "median", "average", "yes", "no", "true", "false"}
+)
+"""Sample values that read as prose ("Total", "Other"): a label equal to one is not tied to the sample."""
+STYLE_WORDS = frozenset(
+    {
+        "center",
+        "centre",
+        "left",
+        "right",
+        "top",
+        "bottom",
+        "middle",
+        "baseline",
+        "none",
+        "auto",
+        "solid",
+        "dash",
+        "dot",
+        "longdash",
+        "dashed",
+        "dotted",
+        "dashdot",
+        "bold",
+        "normal",
+        "italic",
+        "black",
+        "white",
+        "gray",
+        "grey",
+        "red",
+        "green",
+        "blue",
+    }
+)
+"""Alignment, line-style and color words: a block string equal to one configures the chart, not the sample."""
+_PROPERTY_KEY = re.compile(r"^[a-z_][a-z0-9_]*$")
+"""A dict key below the block written like a property name (`{"size": 7}`), not a sample value."""
+
+LIBRARIES = ("matplotlib", "seaborn", "plotly", "altair", "plotnine", "bokeh", "pygal", "letsplot")
+PLOT_MODULES = (
+    "matplotlib",
+    "seaborn",
+    "plotly",
+    "altair",
+    "plotnine",
+    "bokeh",
+    "pygal",
+    "lets_plot",
+    "mpl_toolkits",
+    "squarify",
+    "pywaffle",
+)
+DATA_HELPERS = (
+    "seaborn.load_dataset",
+    "plotly.express.data.",
+    "plotly.data.",
+    "bokeh.sampledata.",
+    "vega_datasets.",
+    "matplotlib.dates.date2num",
+    "matplotlib.dates.num2date",
+    "matplotlib.dates.datestr2num",
+)
+"""Plotting-library calls that produce data, allowed in the block (a prefix ends with a dot)."""
+_MATPLOTLIB_SETUP = (
+    "matplotlib.use",
+    "matplotlib.pyplot.style.use",
+    "matplotlib.style.use",
+    "matplotlib.pyplot.rcParams.update",
+    "matplotlib.rcParams.update",
+    "matplotlib.pyplot.rc",
+    "matplotlib.rc",
+    "matplotlib.pyplot.switch_backend",
+    "matplotlib.font_manager.fontManager.addfont",
+)
+SETUP_CALLS: dict[str, tuple[str, ...]] = {
+    "matplotlib": _MATPLOTLIB_SETUP,
+    "seaborn": (
+        *_MATPLOTLIB_SETUP,
+        "seaborn.set_theme",
+        "seaborn.set_style",
+        "seaborn.set_context",
+        "seaborn.set_palette",
+        "seaborn.set",
+    ),
+    "plotly": ("matplotlib.use", "plotly.io.templates.default.update"),
+    "altair": (
+        "matplotlib.use",
+        "altair.data_transformers.disable_max_rows",
+        "altair.data_transformers.enable",
+        "altair.themes.enable",
+        "altair.themes.register",
+        "altair.theme.enable",
+        "altair.theme.register",
+        "altair.renderers.enable",
+    ),
+    "plotnine": ("matplotlib.use", "plotnine.theme_set", "plotnine.options.set_option"),
+    "bokeh": ("matplotlib.use", "bokeh.io.output_file", "bokeh.plotting.output_file", "bokeh.io.curdoc"),
+    "pygal": ("matplotlib.use",),
+    "letsplot": ("matplotlib.use", "lets_plot.LetsPlot.setup_html", "lets_plot.LetsPlot.set_theme"),
+}
+"""Per library, the calls the head may make before the block (resolved through the imports)."""
+FIGURE_FACTORIES = frozenset(
+    {
+        "matplotlib.pyplot.subplots",
+        "matplotlib.pyplot.figure",
+        "matplotlib.pyplot.subplot",
+        "matplotlib.pyplot.axes",
+        "matplotlib.pyplot.subplot_mosaic",
+        "matplotlib.pyplot.subplot2grid",
+        "plotly.graph_objects.Figure",
+        "plotly.subplots.make_subplots",
+        "altair.Chart",
+        "altair.layer",
+        "altair.hconcat",
+        "altair.vconcat",
+        "altair.concat",
+        "altair.LayerChart",
+        "plotnine.ggplot",
+        "lets_plot.ggplot",
+        "lets_plot.gggrid",
+        "lets_plot.ggbunch",
+        "bokeh.plotting.figure",
+        "bokeh.layouts.gridplot",
+        "bokeh.layouts.column",
+        "bokeh.layouts.row",
+        "seaborn.FacetGrid",
+        "seaborn.PairGrid",
+        "seaborn.JointGrid",
+        "seaborn.catplot",
+        "seaborn.relplot",
+        "seaborn.displot",
+        "seaborn.lmplot",
+        "seaborn.jointplot",
+        "seaborn.pairplot",
+        "seaborn.clustermap",
+    }
+)
+_PYGAL_CHART = re.compile(r"^pygal\.[A-Z]\w*$")
+_PLOTLY_EXPRESS = "plotly.express."
+OUTPUT_CALLS = frozenset(
+    {
+        "savefig",
+        "save",
+        "ggsave",
+        "write_image",
+        "write_html",
+        "export_png",
+        "export_svg",
+        "render_to_png",
+        "render_to_file",
+        "output_file",
+        "show",
+    }
+)
+"""Output calls: every literal inside one is ignored (file names, dpi, scale)."""
+STYLE_KEYWORDS = frozenset(
+    {
+        "ha",
+        "va",
+        "horizontalalignment",
+        "verticalalignment",
+        "multialignment",
+        "marker",
+        "linestyle",
+        "ls",
+        "drawstyle",
+        "loc",
+        "fontweight",
+        "weight",
+        "fontstyle",
+        "style",
+        "family",
+        "fontfamily",
+        "fontname",
+        "font",
+        "cmap",
+        "colormap",
+        "palette",
+        "textcoords",
+        "xycoords",
+        "coords",
+        "how",
+        "join",
+        "kind",
+        "orient",
+        "orientation",
+        "align",
+        "anchor",
+        "baseline",
+        "rotation_mode",
+        "capstyle",
+        "joinstyle",
+        "solid_capstyle",
+        "dash_capstyle",
+        "hatch",
+        "interpolation",
+        "shading",
+        "aspect",
+        "bbox_inches",
+        "format",
+        "fmt",
+        "mode",
+        "barmode",
+        "template",
+        "stat",
+        "method",
+        "position",
+        "legend_position",
+        "units",
+        "x_units",
+        "y_units",
+        "xref",
+        "yref",
+        "axref",
+        "ayref",
+        "textposition",
+        "textinfo",
+        "hoverinfo",
+        "hovermode",
+        "legend",
+        "errorbar",
+        "estimator",
+        "element",
+        "multiple",
+        "inner",
+        "histtype",
+        "where",
+        "type",
+        "side",
+        "location",
+        "dtype",
+        "errors",
+        "freq",
+        "unit",
+        "nonpositive",
+        "rc",
+        "edgecolor",
+        "facecolor",
+        "linecolor",
+        "markeredgecolor",
+        "markerfacecolor",
+        "fill_color",
+        "line_color",
+        "text_color",
+        "background",
+        "background_fill_color",
+        "border_fill_color",
+        "fontFamily",
+        "labelFont",
+        "titleFont",
+        "symbolType",
+        "interpolate",
+        "strokeDash",
+        "shape",
+        "line_dash",
+        "dash",
+        "symbol",
+        "toolbar_location",
+        "sizing_mode",
+        "axis",
+        "which",
+    }
+)
+"""Keywords whose string values style the chart; a sample value never lives there."""
+GENERIC_DATA_KEYWORDS = frozenset(
+    {
+        "range",
+        "range_x",
+        "range_y",
+        "range_z",
+        "range_r",
+        "range_theta",
+        "range_color",
+        "limits",
+        "breaks",
+        "tickvals",
+        "xintercept",
+        "yintercept",
+        "x_range",
+        "y_range",
+        "vmin",
+        "vmax",
+        "vcenter",
+        "zmin",
+        "zmax",
+        "zmid",
+        "clim",
+        "xlim",
+        "ylim",
+        "zlim",
+        "color_continuous_midpoint",
+    }
+)
+"""Keywords that hold data coordinates in any call or dict (plotly ranges, plotnine limits, color bounds)."""
+_AXIS_DATA_KEYWORD = re.compile(r"^[xyz]axis\d*_(?:range|tickvals)$")
+LIMIT_METHODS = frozenset(
+    {
+        "set_xlim",
+        "set_ylim",
+        "set_zlim",
+        "xlim",
+        "ylim",
+        "set_xticks",
+        "set_yticks",
+        "set_zticks",
+        "xticks",
+        "yticks",
+        "set_xbound",
+        "set_ybound",
+        "set_rlim",
+        "set_rmin",
+        "set_rmax",
+        "set_rticks",
+        "set_thetalim",
+        "axis",
+        "set_clim",
+        "clim",
+    }
+)
+"""Calls whose positional arguments are data coordinates (matplotlib, and plotnine and lets-plot `xlim`/`ylim`)."""
+LIMIT_KEYWORDS = frozenset(
+    {"left", "right", "bottom", "top", "xmin", "xmax", "ymin", "ymax", "zmin", "zmax", "ticks", "vmin", "vmax"}
+)
+"""The keywords of a `LIMIT_METHODS` call that hold bounds or tick positions; any other keyword styles."""
+DATA_CALL_ARGS: dict[str, tuple[tuple[int, ...], tuple[str, ...]]] = {
+    "text": ((0, 1), ("x", "y")),
+    "axhline": ((0,), ("y",)),
+    "axvline": ((0,), ("x",)),
+    "axhspan": ((0, 1), ("ymin", "ymax")),
+    "axvspan": ((0, 1), ("xmin", "xmax")),
+    "hlines": ((0, 1, 2), ("y", "xmin", "xmax")),
+    "vlines": ((0, 1, 2), ("x", "ymin", "ymax")),
+    "add_hline": ((0,), ("y",)),
+    "add_vline": ((0,), ("x",)),
+    "add_hrect": ((0, 1), ("y0", "y1")),
+    "add_vrect": ((0, 1), ("x0", "x1")),
+    "add_annotation": ((), ("x", "y")),
+    "add_shape": ((), ("x0", "x1", "y0", "y1")),
+    "annotate": ((), ("x", "y", "xmin", "xmax", "ymin", "ymax", "xend", "yend")),
+    "expand_limits": ((), ("x", "y")),
+    "Range1d": ((0, 1), ("start", "end")),
+    "Span": ((), ("location",)),
+    "BoxAnnotation": ((), ("top", "bottom", "left", "right")),
+    "Label": ((), ("x", "y")),
+    "FixedTicker": ((), ("ticks",)),
+    "Scale": ((), ("domain",)),
+    "Axis": ((), ("values",)),
+}
+"""Per call name, the positional indexes and keywords that hold data coordinates."""
+_GEOM_COORDINATES = ("x", "y", "xend", "yend", "xmin", "xmax", "ymin", "ymax")
+CONTOUR_CALLS = frozenset({"contour", "contourf", "tricontour", "tricontourf"})
+NORM_CALLS: dict[str, tuple[tuple[int, ...], frozenset[str]]] = {
+    "Normalize": ((0, 1), frozenset({"vmin", "vmax"})),
+    "LogNorm": ((0, 1), frozenset({"vmin", "vmax"})),
+    "TwoSlopeNorm": ((0, 1, 2), frozenset({"vcenter", "vmin", "vmax"})),
+    "CenteredNorm": ((0, 1), frozenset({"vcenter", "halfrange"})),
+    "BoundaryNorm": ((0,), frozenset({"boundaries"})),
+    "PowerNorm": ((1, 2), frozenset({"vmin", "vmax"})),
+    "SymLogNorm": ((2, 3), frozenset({"vmin", "vmax"})),
+}
+DATA_ATTRIBUTES = frozenset({"start", "end", "bounds", "ticker", "y_labels", "x_labels", "range"})
+"""Attributes whose literal assignment pins a data coordinate (bokeh ranges and tickers, pygal labels)."""
+PAPER_REFS = ("paper", "domain", "screen", "axes fraction", "figure fraction", "offset points", "offset pixels")
+RANGE_CALLS = frozenset({"range", "arange", "linspace"})
+DATE_CALLS = frozenset({"Timestamp", "datetime", "datetime64", "date", "to_datetime"})
+_DATE_TEXT = re.compile(r"^\d{4}-\d{2}(?:-\d{2})?(?:[ T]\d{2}:\d{2}(?::\d{2})?)?$")
+RANDOM_SIZE_POSITIONS: dict[str, int | None] = {
+    "randn": 0,
+    "rand": 0,
+    "random": 0,
+    "standard_normal": 0,
+    "choice": 1,
+    "poisson": 1,
+    "exponential": 1,
+    "chisquare": 1,
+    "geometric": 1,
+    "standard_t": 1,
+    "weibull": 1,
+    "pareto": 1,
+    "normal": 2,
+    "uniform": 2,
+    "randint": 2,
+    "integers": 2,
+    "binomial": 2,
+    "lognormal": 2,
+    "gamma": 2,
+    "beta": 2,
+    "laplace": 2,
+    "logistic": 2,
+    "gumbel": 2,
+    "vonmises": 2,
+    "multivariate_normal": 2,
+    "triangular": 3,
+    "rvs": None,
+}
+"""Random draws and the position of their size argument (None: `size=` only); the size is a count of the sample."""
+FRAME_CALLS = frozenset({"DataFrame", "read_csv", "load_dataset", "concat", "merge", "melt", "pivot", "pivot_table"})
+"""Calls whose result is a DataFrame: a string subscript of the name they bind reads a column."""
+COMPARISON_METHODS = frozenset({"eq", "ne", "isin"})
+"""Selections of a value: equality and membership. An inequality (`df[RSI] >= 70`, `if w > 7`) applies a
+threshold, which holds for any data (a precision sample of 2026-10-23 found 11 of 11 such hits false)."""
+SELECTION_OPS = (ast.Eq, ast.NotEq, ast.In, ast.NotIn)
+MIN_SAMPLE_CHARS = 2
+"""A one-character sample value ("C", "M") matches too much unrelated code (an SVG path command, a unit)."""
+_STATISTIC = re.compile(r"(?<![\w.])(?:r|R|R²|R\^2|ρ|τ|p|n|μ|σ)\s*(?:=|≈|~|<|>|≤|≥)\s*[-−+]?\.?\d")
+_HEX = re.compile(r"^#[0-9A-Fa-f]{3,8}$")
+_MARKER_TAIL = r"(?:\s*:.*|\s+[-–—].*)?\s*$"
+DATA_MARKER = re.compile(r"^# Data" + _MARKER_TAIL)
+PLOT_MARKER = re.compile(r"^# Plot" + _MARKER_TAIL)
+CONSTANTS_MARKER = re.compile(r"^# Constants" + _MARKER_TAIL)
+ROLE_COMMENT = re.compile(r"^#\s*role\s*:\s*(?P<rest>.*?)\s*$")
+ROLE_NAME = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+EXTRA_ROLE = "extra"
+_ALTAIR_SUFFIX = re.compile(r":[QNOTG]$")
+_ALTAIR_ESCAPE = re.compile(r"\\([.\[\]:\\])")
+_SNIPPET_CHARS = 60
+_MAX_LISTED_LINES = 5
+_BUILTIN_NAMES = frozenset(dir(builtins))
+
+
+@dataclass(frozen=True)
+class RuleClass:
+    """One class of finding: its rule number, the target its defect line names, and whether it is advisory."""
+
+    id: str
+    rule: int
+    target: str
+    advisory: bool = False
+
+
+RULE_CLASSES: dict[str, RuleClass] = {
+    rule.id: rule
+    for rule in (
+        RuleClass(
+            "layout",
+            1,
+            "one block between column-0 # Data and # Plot markers that ends by binding df, with no plotting, styling "
+            "or theme token inside and no plotting call above it",
+        ),
+        RuleClass(
+            "columns",
+            2,
+            "one string constant per required column role above the Data block, each with a trailing "
+            "# role: <role> comment naming a spec role",
+        ),
+        RuleClass("interface", 3, "read only df below the Data block and derive everything else from it"),
+        RuleClass("column-literal", 4, "use the column constant instead of the column name"),
+        # Advisory: 76 of 90 over three samples; the misses are domain vocabulary the block also spells out
+        # (ECG lead names, Venn zones, spectral classes, the 100 % saturation curve).
+        RuleClass("sample-literal", 4, "derive the value from df instead of typing a sample value", advisory=True),
+        # Advisory after the precision samples of 2026-10-23 (PR body): data-coordinate 20 of 30 (annotation
+        # positions in layout units, domain thresholds such as a 95 % variance line, padding), statistic-text
+        # 11 of 30 (thresholds and domain facts: "p < 0.05", "r ≈ 3.57"), count-literal 22 of 30 (domain
+        # grids: a 5 x 5 risk matrix, 7 weekdays, 4 ECG rows).
+        RuleClass(
+            "data-coordinate",
+            4,
+            "derive limits, ticks, reference lines and text positions from df, or name the value in # Constants",
+            advisory=True,
+        ),
+        RuleClass("statistic-text", 4, "compute the statistic from df in an f-string", advisory=True),
+        RuleClass(
+            "df-comparison",
+            4,
+            "select by a rule over df (idxmax, the latest row) or compare with a # Constants threshold",
+        ),
+        RuleClass("count-literal", 4, "count from df (len(df), nunique) instead of typing the count", advisory=True),
+        RuleClass(
+            "palette",
+            5,
+            "list all eight IMPRINT positions in canonical order and look colors up per category "
+            "(IMPRINT[i], dict(zip(groups, IMPRINT)))",
+        ),
+        RuleClass("constants", 6, "keep only values that hold for any data in # Constants", advisory=True),
+    )
+}
+RULE_ORDER = tuple(RULE_CLASSES)
+
+
+@dataclass(frozen=True)
+class Finding:
+    """One violation: its rule class, its line (None for the file as a whole), what was seen and why."""
+
+    cls: str
+    line: int | None
+    observed: str
+    cause: str
+
+    @property
+    def rule(self) -> int:
+        return RULE_CLASSES[self.cls].rule
+
+    @property
+    def advisory(self) -> bool:
+        return RULE_CLASSES[self.cls].advisory
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "rule": self.rule,
+            "class": self.cls,
+            "line": self.line,
+            "observed": self.observed,
+            "cause": self.cause,
+            "advisory": self.advisory,
+        }
+
+
+@dataclass
+class Record:
+    """The checker's result for one source (`to_dict` is the stored form)."""
+
+    shape: Shape
+    color_role: str | None
+    block: tuple[int, int] | None
+    constants: dict[str, str]
+    findings: list[Finding] = field(default_factory=list)
+    version: int = CHECKER_VERSION
+
+    @property
+    def status(self) -> str:
+        """`pass`, `fail` (a finding that is not advisory) or `excluded` (a map spec, never checked)."""
+        if self.shape == "excluded":
+            return "excluded"
+        return "fail" if any(not finding.advisory for finding in self.findings) else "pass"
+
+    def classes(self) -> list[str]:
+        """The rule classes with a finding, in `RULE_ORDER`."""
+        found = {finding.cls for finding in self.findings}
+        return [cls for cls in RULE_ORDER if cls in found]
+
+    def defect_lines(self) -> list[str]:
+        """At most one defect line per rule class (`core.defects.DEFECT_RE` reads each)."""
+        lines: list[str] = []
+        for cls in self.classes():
+            findings = sorted(
+                (finding for finding in self.findings if finding.cls == cls), key=lambda finding: finding.line or 0
+            )
+            lines.append(_defect_line(cls, findings))
+        return lines
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "version": self.version,
+            "status": self.status,
+            "shape": self.shape,
+            "color_role": self.color_role,
+            "block": None if self.block is None else {"start": self.block[0], "end": self.block[1]},
+            "constants": dict(self.constants),
+            "findings": [finding.to_dict() for finding in self.findings],
+            "lines": self.defect_lines(),
+        }
+
+
+def _clause(text: str) -> str:
+    return " ".join(str(text).replace(DEFECT_ARROW, "->").split()).rstrip(". ")
+
+
+def _defect_line(cls: str, findings: Sequence[Finding]) -> str:
+    """`CQ-01 (code): line N <observed>[, and K more at lines ...] → <target>. Likely cause: <cause>.`"""
+    first = findings[0]
+    observed = f"line {first.line} {first.observed}" if first.line is not None else first.observed
+    rest = [finding.line for finding in findings[1:] if finding.line is not None]
+    more = len(findings) - 1
+    if more:
+        shown = ", ".join(str(line) for line in rest[:_MAX_LISTED_LINES])
+        tail = ", …" if len(rest) > _MAX_LISTED_LINES else ""
+        observed += f"; {more} more" + (f" at lines {shown}{tail}" if shown else "")
+    if RULE_CLASSES[cls].advisory:
+        observed = f"(advisory) {observed}"
+    line = f"{DEFECT_ID} ({CODE_RENDER}): {_clause(observed)} {DEFECT_ARROW} {_clause(RULE_CLASSES[cls].target)}."
+    cause = _clause(first.cause)
+    return f"{line} Likely cause: {cause}." if cause else line
+
+
+# --- source model ------------------------------------------------------------------------------
+
+
+@dataclass
+class _Constant:
+    name: str
+    role: str
+    value: ast.expr
+    line: int
+
+
+def _assignment(node: ast.AST) -> tuple[list[ast.expr], ast.expr] | None:
+    """The targets and the value of `x = ...` or of an annotated `x: str = ...`; None for anything else."""
+    if isinstance(node, ast.Assign):
+        return list(node.targets), node.value
+    if isinstance(node, ast.AnnAssign) and node.value is not None:
+        return [node.target], node.value
+    return None
+
+
+def _single_name(node: ast.AST) -> tuple[str, ast.expr] | None:
+    """The name and value of a single-name assignment, annotated or not."""
+    assigned = _assignment(node)
+    if assigned is None or len(assigned[0]) != 1 or not isinstance(assigned[0][0], ast.Name):
+        return None
+    return assigned[0][0].id, assigned[1]
+
+
+@dataclass
+class _Sample:
+    """What the block defines: its values, its record fields, its column names, its data numbers and its counts.
+
+    `strings` are values (list elements, assigned or compared strings); `fields` are the keys of the block's
+    dicts that build no DataFrame and the string subscripts of its records (`node["id"]`), which can be a
+    category map's keys ("Electronics") or a record's field names ("id", "color").
+    """
+
+    strings: set[str] = field(default_factory=set)
+    fields: set[str] = field(default_factory=set)
+    columns: set[str] = field(default_factory=set)
+    numbers: set[float] = field(default_factory=set)
+    counts: set[int] = field(default_factory=set)
+
+
+class _Source:
+    """A parsed source with its comments, markers, imports and zones."""
+
+    def __init__(self, source: str, tree: ast.Module, library: str | None) -> None:
+        self.text = source
+        self.tree = tree
+        self.library = library
+        self.comments = _comments(source)
+        self.markers = {
+            kind: [line for line, col, text in self.comments if col == 0 and pattern.match(text)]
+            for kind, pattern in (("data", DATA_MARKER), ("plot", PLOT_MARKER), ("constants", CONSTANTS_MARKER))
+        }
+        self.aliases, self.star_modules = _imports(tree)
+        self.parents: dict[ast.AST, ast.AST] = {}
+        for node in ast.walk(tree):
+            for child in ast.iter_child_nodes(node):
+                self.parents[child] = node
+        self.defined = _bound_names(tree)
+        data = self.markers["data"]
+        plot = [line for line in self.markers["plot"] if data and line > data[0]]
+        self.block: tuple[int, int] | None = (data[0], plot[0]) if data and plot else None
+        self.figures = self._figure_names()
+
+    # zones ---------------------------------------------------------------------------------
+
+    def head(self) -> list[ast.stmt]:
+        if not self.markers["data"]:
+            return []
+        start = self.markers["data"][0]
+        return [stmt for stmt in self.tree.body if stmt.lineno < start]
+
+    def block_body(self) -> list[ast.stmt]:
+        if self.block is None:
+            return []
+        start, end = self.block
+        return [stmt for stmt in self.tree.body if start < stmt.lineno < end]
+
+    def below(self) -> list[ast.stmt]:
+        if self.block is None:
+            return list(self.tree.body)
+        return [stmt for stmt in self.tree.body if stmt.lineno > self.block[1]]
+
+    def constants_zone(self) -> list[ast.stmt]:
+        markers = self.markers["constants"]
+        if not markers or not self.markers["data"]:
+            return []
+        start, end = markers[0], self.markers["data"][0]
+        return [stmt for stmt in self.tree.body if start < stmt.lineno < end]
+
+    # names and calls -----------------------------------------------------------------------
+
+    def resolve(self, dotted: str) -> str:
+        """`plt.subplots` -> `matplotlib.pyplot.subplots`; a bare name from a star import gets its module."""
+        head, _, rest = dotted.partition(".")
+        if head in self.aliases:
+            base = self.aliases[head]
+        elif head not in self.defined and head not in _BUILTIN_NAMES and self.star_modules:
+            base = f"{self.star_modules[0]}.{head}"
+        else:
+            base = head
+        return f"{base}.{rest}" if rest else base
+
+    def call_root(self, call: ast.Call) -> tuple[str | None, str]:
+        """The base name of a call chain (`alt` in `alt.Chart(df).mark_bar()`) and the innermost call's resolved name."""
+        func: ast.expr = call.func
+        inner = call
+        while True:
+            if isinstance(func, ast.Attribute):
+                func = func.value
+            elif isinstance(func, ast.Call):
+                inner = func
+                func = func.func
+            elif isinstance(func, ast.Subscript):
+                func = func.value
+            else:
+                break
+        root = func.id if isinstance(func, ast.Name) else None
+        dotted = _dotted(inner.func)
+        return root, self.resolve(dotted) if dotted else ""
+
+    def is_plot_module(self, resolved: str) -> bool:
+        return resolved.split(".", 1)[0] in PLOT_MODULES or resolved.startswith("networkx.draw")
+
+    def is_figure_factory(self, resolved: str) -> bool:
+        return (
+            resolved in FIGURE_FACTORIES
+            or (
+                resolved.startswith(_PLOTLY_EXPRESS)
+                and not resolved.startswith(("plotly.express.data", "plotly.express.colors"))
+            )
+            or (bool(_PYGAL_CHART.match(resolved)) and resolved != "pygal.Config")
+        )
+
+    def _figure_names(self) -> set[str]:
+        """Names bound to a figure, axes or chart: by a figure factory or a call on another figure name."""
+        names: set[str] = set()
+        for stmt in self.tree.body:
+            for node in ast.walk(stmt):
+                assigned = _assignment(node)
+                if assigned is None or not isinstance(assigned[1], ast.Call):
+                    continue
+                root, resolved = self.call_root(assigned[1])
+                if self.is_figure_factory(resolved) or (root is not None and root in names):
+                    for target in assigned[0]:
+                        names.update(_target_names(target))
+        return names
+
+    def is_plotting_call(self, call: ast.Call) -> bool:
+        """A call into a plotting library (other than a data helper) or on a figure, axes or chart."""
+        root, resolved = self.call_root(call)
+        if root is not None and root in self.figures:
+            return True
+        if not self.is_plot_module(resolved):
+            return False
+        return not any(
+            resolved.startswith(helper) if helper.endswith(".") else resolved == helper for helper in DATA_HELPERS
+        )
+
+    def setup_calls(self) -> set[str]:
+        if self.library in SETUP_CALLS:
+            return set(SETUP_CALLS[self.library])
+        return {call for calls in SETUP_CALLS.values() for call in calls}
+
+    def snippet(self, node: ast.AST) -> str:
+        return _snippet(ast.get_source_segment(self.text, node) or ast.unparse(node))
+
+    def inside(self, node: ast.AST, kinds: tuple[type, ...]) -> ast.AST | None:
+        current = self.parents.get(node)
+        while current is not None:
+            if isinstance(current, kinds):
+                return current
+            current = self.parents.get(current)
+        return None
+
+
+def _comments(source: str) -> list[tuple[int, int, str]]:
+    """`(line, column, text)` of every comment token."""
+    out: list[tuple[int, int, str]] = []
+    try:
+        for token in tokenize.generate_tokens(io.StringIO(source).readline):
+            if token.type == tokenize.COMMENT:
+                out.append((token.start[0], token.start[1], token.string))
+    except (tokenize.TokenError, IndentationError, SyntaxError):
+        for number, line in enumerate(source.splitlines(), start=1):
+            stripped = line.lstrip()
+            if stripped.startswith("#"):
+                out.append((number, len(line) - len(stripped), stripped))
+    return out
+
+
+def _imports(tree: ast.Module) -> tuple[dict[str, str], list[str]]:
+    """Local name -> imported module or object, and the modules imported with `*`."""
+    aliases: dict[str, str] = {}
+    stars: list[str] = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                if alias.asname:
+                    aliases[alias.asname] = alias.name
+                else:
+                    top = alias.name.split(".")[0]
+                    aliases[top] = top
+        elif isinstance(node, ast.ImportFrom) and node.module and node.level == 0:
+            for alias in node.names:
+                if alias.name == "*":
+                    stars.append(node.module)
+                else:
+                    aliases[alias.asname or alias.name] = f"{node.module}.{alias.name}"
+    plot_stars = [module for module in stars if module.split(".")[0] in PLOT_MODULES]
+    return aliases, plot_stars
+
+
+def _bound_names(tree: ast.Module) -> set[str]:
+    names: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Name) and isinstance(node.ctx, ast.Store):
+            names.add(node.id)
+        elif isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef):
+            names.add(node.name)
+        elif isinstance(node, ast.arg):
+            names.add(node.arg)
+        elif isinstance(node, ast.Import | ast.ImportFrom):
+            for alias in node.names:
+                if alias.name != "*":
+                    names.add((alias.asname or alias.name).split(".")[0])
+    return names
+
+
+def _dotted(node: ast.expr) -> str | None:
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        base = _dotted(node.value)
+        return f"{base}.{node.attr}" if base else None
+    return None
+
+
+def _call_name(call: ast.Call) -> str | None:
+    """The called function's last name: `set_xlim` for `ax.set_xlim(...)`, `range` for `range(...)`."""
+    if isinstance(call.func, ast.Attribute):
+        return call.func.attr
+    if isinstance(call.func, ast.Name):
+        return call.func.id
+    return None
+
+
+def _target_names(target: ast.expr) -> set[str]:
+    if isinstance(target, ast.Name):
+        return {target.id}
+    if isinstance(target, ast.Tuple | ast.List):
+        return {name for element in target.elts for name in _target_names(element)}
+    if isinstance(target, ast.Starred):
+        return _target_names(target.value)
+    return set()
+
+
+def _snippet(text: str) -> str:
+    text = " ".join(text.split())
+    return text if len(text) <= _SNIPPET_CHARS else text[: _SNIPPET_CHARS - 1] + "…"
+
+
+def _names_in(node: ast.AST) -> set[str]:
+    return {child.id for child in ast.walk(node) if isinstance(child, ast.Name)}
+
+
+# --- literal values ------------------------------------------------------------------------------
+
+
+def _number(node: ast.expr) -> float | None:
+    """The value of a numeric literal, a signed one, or arithmetic on literals."""
+    if isinstance(node, ast.Constant):
+        value = node.value
+        return float(value) if isinstance(value, int | float) and not isinstance(value, bool) else None
+    if isinstance(node, ast.UnaryOp) and isinstance(node.op, ast.USub | ast.UAdd):
+        operand = _number(node.operand)
+        if operand is None:
+            return None
+        return -operand if isinstance(node.op, ast.USub) else operand
+    if isinstance(node, ast.BinOp) and isinstance(node.op, ast.Add | ast.Sub | ast.Mult | ast.Div):
+        left, right = _number(node.left), _number(node.right)
+        if left is None or right is None:
+            return None
+        if isinstance(node.op, ast.Add):
+            return left + right
+        if isinstance(node.op, ast.Sub):
+            return left - right
+        if isinstance(node.op, ast.Mult):
+            return left * right
+        return left / right if right else None
+    return None
+
+
+def _literal_values(node: ast.expr) -> list[float | str]:
+    """The literal values `node` places on an axis; a literal date counts as `"date"`."""
+    number = _number(node)
+    if number is not None:
+        return [number]
+    if isinstance(node, ast.Constant) and isinstance(node.value, str) and _DATE_TEXT.match(node.value):
+        return ["date"]
+    if isinstance(node, ast.List | ast.Tuple):
+        return [value for element in node.elts for value in _literal_values(element)]
+    if isinstance(node, ast.Call):
+        name = _call_name(node) or ""
+        if name in RANGE_CALLS and node.args:
+            numbers = [_number(arg) for arg in node.args]
+            if all(value is not None for value in numbers):
+                return [value for value in numbers if value is not None]
+        if name in DATE_CALLS and node.args and all(isinstance(arg, ast.Constant) for arg in node.args):
+            return ["date"]
+    return []
+
+
+def _exempt(values: Sequence[float | str]) -> bool:
+    """Values that fit any data: none at all, only neutral or critical values, or a span of a fixed domain."""
+    if any(value == "date" for value in values):
+        return False
+    numbers = [float(value) for value in values if not isinstance(value, str)]
+    if not numbers:
+        return True
+    if all(value in NEUTRAL_VALUES or abs(value) in CRITICAL_VALUES for value in numbers):
+        return True
+    low, high = min(numbers), max(numbers)
+    for lo, hi, headroom in FIXED_DOMAINS:
+        pad = headroom * (hi - lo)
+        if lo - pad <= low <= lo + pad and hi - pad <= high <= hi + pad:
+            return True
+    return False
+
+
+def _count(node: ast.expr) -> int | None:
+    value = _number(node)
+    return int(value) if value is not None and value == int(value) else None
+
+
+def _range_length(call: ast.Call) -> int | None:
+    """The length of `range`/`arange` of literal ints, or a `linspace`'s point count."""
+    name = _call_name(call)
+    if name == "linspace":
+        num = call.args[2] if len(call.args) > 2 else next((kw.value for kw in call.keywords if kw.arg == "num"), None)
+        return _count(num) if num is not None else None
+    if name not in ("range", "arange"):
+        return None
+    ints = [_count(arg) for arg in call.args]
+    if not ints or any(value is None for value in ints):
+        return None
+    start, stop, step = 0, 0, 1
+    if len(ints) == 1:
+        stop = ints[0] or 0
+    else:
+        start, stop = ints[0] or 0, ints[1] or 0
+        step = (ints[2] or 1) if len(ints) > 2 else 1
+    return max(0, -(-(stop - start) // step)) if step else None
+
+
+# --- the checks --------------------------------------------------------------------------------
+
+
+def check_source(source: str, roles: Sequence[DataRole], shape: Shape, *, library: str | None = None) -> Record:
+    """Check one Python implementation against its spec's roles and data shape."""
+    role = color_role(roles)
+    record = Record(shape=shape, color_role=role.name if role else None, block=None, constants={})
+    if shape == "excluded":
+        return record
+    try:
+        tree = ast.parse(source)
+    except SyntaxError as exc:
+        record.findings.append(Finding("layout", exc.lineno, "does not parse", f"SyntaxError: {exc.msg}"))
+        return record
+    src = _Source(source, tree, library)
+    record.block = src.block
+    findings = record.findings
+    constants = _column_constants(src)
+    record.constants = {constant.role: constant.name for constant in constants if constant.role != EXTRA_ROLE}
+
+    findings.extend(_check_layout(src, shape))
+    findings.extend(_check_columns(src, constants, roles, shape))
+    sample = _sample(src, constants) if src.block is not None else None
+    if sample is not None and shape != "generated":
+        findings.extend(_check_interface(src, shape))
+    findings.extend(_check_literals(src, sample))
+    findings.extend(_check_palette(src, role))
+    if sample is not None:
+        findings.extend(_check_constants_zone(src, sample))
+    return record
+
+
+def _check_layout(src: _Source, shape: Shape) -> list[Finding]:
+    found: list[Finding] = []
+    data = src.markers["data"]
+    if not data:
+        found.append(
+            Finding(
+                "layout",
+                None,
+                "the file has no column-0 # Data marker",
+                "the data generation is not marked as one block",
+            )
+        )
+    elif src.block is None:
+        found.append(
+            Finding(
+                "layout",
+                data[0],
+                "opens the Data block with no column-0 # Plot marker after it",
+                "the plot code is not separated from the data generation",
+            )
+        )
+    if len(data) > 1:
+        found.append(
+            Finding(
+                "layout",
+                data[1],
+                f"opens a second # Data block ({len(data)} markers)",
+                "the data generation is split over several blocks",
+            )
+        )
+    found.extend(_check_head(src))
+    if src.block is None:
+        return found
+    body = src.block_body()
+    if not body:
+        found.append(Finding("layout", src.block[0], "opens an empty Data block", "nothing between the markers"))
+        return found
+    tokens = _theme_tokens(src)
+    for stmt in body:
+        for node in ast.walk(stmt):
+            if isinstance(node, ast.Call) and src.is_plotting_call(node):
+                found.append(
+                    Finding(
+                        "layout",
+                        node.lineno,
+                        f"calls `{src.snippet(node.func)}` inside the Data block",
+                        "a plotting, styling or setup call in the data generation",
+                    )
+                )
+                break
+            if isinstance(node, ast.Name) and isinstance(node.ctx, ast.Load) and node.id in tokens:
+                found.append(
+                    Finding(
+                        "layout",
+                        node.lineno,
+                        f"reads the theme token `{node.id}` inside the Data block",
+                        "styling in the data generation",
+                    )
+                )
+                break
+    if shape != "generated":
+        last = body[-1]
+        if not _binds_df(last):
+            found.append(
+                Finding(
+                    "layout",
+                    last.lineno,
+                    f"ends the Data block with `{src.snippet(last)}`, not a statement that binds df",
+                    "the block does not end in one tidy DataFrame df",
+                )
+            )
+    return found
+
+
+def _check_head(src: _Source) -> list[Finding]:
+    """Above the block: no figure created and no plotting call outside the library's setup calls."""
+    found: list[Finding] = []
+    allowed = src.setup_calls()
+    for stmt in src.head():
+        if isinstance(stmt, ast.Assign | ast.AnnAssign) and isinstance(stmt.value, ast.Call):
+            root, resolved = src.call_root(stmt.value)
+            if src.is_figure_factory(resolved) or (root is not None and root in src.figures):
+                found.append(
+                    Finding(
+                        "layout",
+                        stmt.lineno,
+                        f"creates `{src.snippet(stmt.value.func)}` above the Data block",
+                        "plot code above the data generation",
+                    )
+                )
+        elif isinstance(stmt, ast.Expr) and isinstance(stmt.value, ast.Call):
+            root, resolved = src.call_root(stmt.value)
+            dotted = _dotted(stmt.value.func)
+            full = src.resolve(dotted) if dotted else resolved
+            if full in allowed:
+                continue
+            if (root is not None and root in src.figures) or src.is_plot_module(full):
+                found.append(
+                    Finding(
+                        "layout",
+                        stmt.lineno,
+                        f"calls `{src.snippet(stmt.value.func)}` above the Data block",
+                        "a plotting call in the head that is not one of the library's setup calls",
+                    )
+                )
+    return found
+
+
+def _theme_tokens(src: _Source) -> set[str]:
+    """`THEME`, names the head derives from it, color strings and palettes."""
+    tokens = {"THEME"}
+    changed = True
+    while changed:
+        changed = False
+        for stmt in src.head():
+            assigned = _assignment(stmt)
+            if assigned is None:
+                continue
+            targets, value = assigned
+            names = {name for target in targets for name in _target_names(target)}
+            if not names or names <= tokens:
+                continue
+            hexes = any(
+                isinstance(node, ast.Constant) and isinstance(node.value, str) and _HEX.match(node.value)
+                for node in ast.walk(value)
+            )
+            if hexes or _names_in(value) & tokens:
+                tokens |= names
+                changed = True
+    return tokens
+
+
+def _binds_df(stmt: ast.stmt) -> bool:
+    """`df = ...`, a column or attribute of df set (`df["x"] = ...`), or an in-place call on df."""
+
+    def on_df(target: ast.expr) -> bool:
+        if "df" in _target_names(target):
+            return True
+        while isinstance(target, ast.Subscript | ast.Attribute):  # df["x"], df.loc[:, "x"], df.attrs
+            target = target.value
+        return isinstance(target, ast.Name) and target.id == "df"
+
+    if isinstance(stmt, ast.Assign):
+        return any(on_df(target) for target in stmt.targets)
+    if isinstance(stmt, ast.AnnAssign | ast.AugAssign):
+        return on_df(stmt.target)
+    if isinstance(stmt, ast.Expr) and isinstance(stmt.value, ast.Call):
+        func = stmt.value.func
+        return isinstance(func, ast.Attribute) and isinstance(func.value, ast.Name) and func.value.id == "df"
+    return False
+
+
+def _column_constants(src: _Source) -> list[_Constant]:
+    """Module-level single-name assignments (annotated or not) with a `# role:` comment on one of their lines."""
+    by_line: dict[int, str] = {}
+    for line, col, text in src.comments:
+        if col > 0:
+            match = ROLE_COMMENT.match(text)
+            if match:  # a further comment after the role (`# role: y  # note`) is not part of it
+                by_line[line] = match.group("rest").split("#", 1)[0].strip()
+    constants: list[_Constant] = []
+    for stmt in src.tree.body:
+        single = _single_name(stmt)
+        if single is None:
+            continue
+        end = stmt.end_lineno or stmt.lineno
+        role = next((by_line[line] for line in range(stmt.lineno, end + 1) if line in by_line), None)
+        if role is not None:
+            constants.append(_Constant(single[0], role, single[1], stmt.lineno))
+    return constants
+
+
+def _check_columns(src: _Source, constants: list[_Constant], roles: Sequence[DataRole], shape: Shape) -> list[Finding]:
+    found: list[Finding] = []
+    by_name = {role.name: role for role in roles}
+    seen: dict[str, _Constant] = {}
+    for constant in constants:
+        role_text = constant.role
+        if not ROLE_NAME.match(role_text):
+            found.append(
+                Finding(
+                    "columns",
+                    constant.line,
+                    f"writes the role comment of `{constant.name}` as `# role: {role_text}`",
+                    "a role comment is `# role: <role>` with the role name alone",
+                )
+            )
+            continue
+        role = by_name.get(role_text)
+        if role_text != EXTRA_ROLE and role is None:
+            known = ", ".join(sorted(by_name)) or "none"
+            found.append(
+                Finding(
+                    "columns",
+                    constant.line,
+                    f"names the unknown role `{role_text}` (spec roles: {known})",
+                    f"`{constant.name}` is tagged with a role the spec does not declare",
+                )
+            )
+            continue
+        value = constant.value
+        variadic = role is not None and role.variadic
+        if variadic:
+            ok = isinstance(value, ast.List | ast.Tuple) and all(
+                isinstance(element, ast.Constant) and isinstance(element.value, str) for element in value.elts
+            )
+        else:
+            ok = isinstance(value, ast.Constant) and isinstance(value.value, str)
+        if not ok:
+            wanted = "a list of column-name strings" if variadic else "a column-name string"
+            found.append(
+                Finding(
+                    "columns",
+                    constant.line,
+                    f"assigns `{constant.name}` the value `{src.snippet(value)}`, not {wanted}",
+                    "the agent rewrites the constant's string from its bindings",
+                )
+            )
+        if src.block is not None and constant.line > src.block[0]:
+            found.append(
+                Finding(
+                    "columns",
+                    constant.line,
+                    f"defines the column constant `{constant.name}` below the # Data marker",
+                    "column constants belong above the Data block",
+                )
+            )
+        if role_text != EXTRA_ROLE:
+            if role_text in seen:
+                found.append(
+                    Finding(
+                        "columns",
+                        constant.line,
+                        f"tags `{constant.name}` with the role `{role_text}` that `{seen[role_text].name}` already has",
+                        "two constants for one role",
+                    )
+                )
+            else:
+                seen[role_text] = constant
+    if shape in ("table", "network"):
+        missing = [
+            role.name
+            for role in roles
+            if role.required and not role.computed and not is_structure_role(role, shape) and role.name not in seen
+        ]
+        if missing:
+            found.append(
+                Finding(
+                    "columns",
+                    src.block[0] if src.block else None,
+                    f"has no column constant for the required role{'s' if len(missing) > 1 else ''} "
+                    + ", ".join(f"`{name}`" for name in missing),
+                    "column names are typed where they are used instead of once, above the block",
+                )
+            )
+    return found
+
+
+def _sample(src: _Source, constants: list[_Constant]) -> _Sample:
+    """The strings, column names, data numbers and counts the block defines (constants' values count as columns)."""
+    sample = _Sample()
+    for constant in constants:
+        for node in ast.walk(constant.value):
+            if isinstance(node, ast.Constant) and isinstance(node.value, str):
+                sample.columns.add(node.value)
+    body = src.block_body()
+    frame_dicts: set[str] = set()
+    frames = {"df"}
+    for stmt in body:
+        for node in ast.walk(stmt):
+            if isinstance(node, ast.Call) and _call_name(node) == "DataFrame":
+                for arg in [*node.args[:1], *(kw.value for kw in node.keywords if kw.arg == "data")]:
+                    if isinstance(arg, ast.Name):
+                        frame_dicts.add(arg.id)
+            assigned = _assignment(node)
+            if assigned is not None and isinstance(assigned[1], ast.Call) and _call_name(assigned[1]) in FRAME_CALLS:
+                for target in assigned[0]:
+                    frames |= _target_names(target)
+    for stmt in body:
+        for node in ast.walk(stmt):
+            _sample_node(src, node, sample, frame_dicts, frames)
+    sample.strings = {text for text in sample.strings - sample.columns if text.strip() and not _HEX.match(text)}
+    sample.fields = {text for text in sample.fields - sample.columns if text.strip() and not _HEX.match(text)}
+    sample.counts = {count for count in sample.counts if count >= MIN_COUNT}
+    return sample
+
+
+def _sample_node(src: _Source, node: ast.AST, sample: _Sample, frame_dicts: set[str], frames: set[str]) -> None:
+    if isinstance(node, ast.Dict):
+        parent = src.parents.get(node)
+        is_frame = (
+            (isinstance(parent, ast.Call) and _call_name(parent) in ("DataFrame", "append"))
+            or (isinstance(parent, ast.keyword) and parent.arg == "data")
+            or (
+                isinstance(parent, ast.Assign)
+                and any(name in frame_dicts for t in parent.targets for name in _target_names(t))
+            )
+        )
+        for key, value in zip(node.keys, node.values, strict=True):
+            if isinstance(key, ast.Constant) and isinstance(key.value, str):
+                (sample.columns if is_frame else sample.fields).add(key.value)
+            if isinstance(value, ast.List | ast.Tuple):
+                sample.counts.add(len(value.elts))
+        if len(node.keys) >= MIN_COUNT and not is_frame:
+            sample.counts.add(len(node.keys))
+        return
+    if isinstance(node, ast.List | ast.Tuple | ast.Set):
+        texts = [e.value for e in node.elts if isinstance(e, ast.Constant) and isinstance(e.value, str)]
+        sample.strings.update(texts)
+        sample.counts.add(len(node.elts))
+        if texts:
+            sample.counts.add(len(set(texts)))
+        sample.numbers.update(number for e in node.elts if (number := _number(e)) is not None)
+        parent = src.parents.get(node)
+        if isinstance(parent, ast.keyword) and parent.arg == "columns":
+            sample.columns.update(texts)
+            sample.strings.difference_update(texts)
+        if isinstance(parent, ast.BinOp) and isinstance(parent.op, ast.Mult):
+            factor = _count(parent.right if parent.left is node else parent.left)
+            if factor is not None:
+                sample.counts.update({factor, factor * len(node.elts)})
+        return
+    if isinstance(node, ast.Constant) and isinstance(node.value, str):
+        parent = src.parents.get(node)
+        if isinstance(parent, ast.Assign | ast.Compare | ast.AnnAssign):
+            sample.strings.add(node.value)
+        elif isinstance(parent, ast.Subscript) and parent.slice is node:
+            frame = isinstance(parent.value, ast.Name) and parent.value.id in frames
+            target = isinstance(parent.ctx, ast.Store)
+            (sample.columns if target or frame else sample.fields).add(node.value)
+        return
+    if isinstance(node, ast.keyword) and node.arg and isinstance(src.parents.get(node), ast.Call):
+        call = src.parents[node]
+        if isinstance(call, ast.Call) and _call_name(call) == "assign":
+            sample.columns.add(node.arg)
+        if node.arg == "columns" and isinstance(node.value, ast.Dict):
+            for value in node.value.values:
+                if isinstance(value, ast.Constant) and isinstance(value.value, str):
+                    sample.columns.add(value.value)
+        return
+    if isinstance(node, ast.Call):
+        name = _call_name(node)
+        length = _range_length(node)
+        if length is not None:
+            sample.counts.add(length)
+        if name in RANDOM_SIZE_POSITIONS:
+            size = next((kw.value for kw in node.keywords if kw.arg == "size"), None)
+            position = RANDOM_SIZE_POSITIONS[name]
+            if size is None and position is not None and len(node.args) > position:
+                size = node.args[position]
+            if size is not None:
+                if isinstance(size, ast.Tuple):
+                    sample.counts.update(c for e in size.elts if (c := _count(e)) is not None)
+                elif (count := _count(size)) is not None:
+                    sample.counts.add(count)
+        if name in ("date_range", "period_range"):
+            periods = next((kw.value for kw in node.keywords if kw.arg == "periods"), None)
+            if periods is not None and (count := _count(periods)) is not None:
+                sample.counts.add(count)
+
+
+# rule 3 ---------------------------------------------------------------------------------------
+
+
+def _check_interface(src: _Source, shape: Shape) -> list[Finding]:
+    body = src.block_body()
+    bound: set[str] = set()
+    for stmt in body:
+        bound |= _statement_bindings(stmt)
+    bound -= {"df", "_"}
+    if shape == "network":
+        bound.discard("nodes")
+    if not bound:
+        return []
+    reads = _reads_before_rebinding(src.below(), bound)
+    found: list[Finding] = []
+    for name, line in sorted(reads.items(), key=lambda item: item[1]):
+        found.append(
+            Finding(
+                "interface",
+                line,
+                f"reads `{name}`, which the Data block binds",
+                f"`{name}` is defined in the Data block instead of derived from df below it",
+            )
+        )
+    return found
+
+
+def _statement_bindings(stmt: ast.stmt) -> set[str]:
+    """Names a module-level statement binds at module scope (not inside a function, class or comprehension)."""
+    names: set[str] = set()
+    if isinstance(stmt, ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef):
+        return {stmt.name}
+    if isinstance(stmt, ast.Import | ast.ImportFrom):
+        return {(alias.asname or alias.name).split(".")[0] for alias in stmt.names if alias.name != "*"}
+    for node in _module_scope_nodes(stmt):
+        if isinstance(node, ast.Name) and isinstance(node.ctx, ast.Store):
+            names.add(node.id)
+        elif isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef):
+            names.add(node.name)
+        elif isinstance(node, ast.Import | ast.ImportFrom):
+            names.update((alias.asname or alias.name).split(".")[0] for alias in node.names if alias.name != "*")
+    return names
+
+
+def _module_scope_nodes(node: ast.AST) -> Iterator[ast.AST]:
+    """Every node in `node` that runs in the module's scope: nested functions, lambdas, classes and comprehensions excluded."""
+    yield node
+    for child in ast.iter_child_nodes(node):
+        if isinstance(child, ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef):
+            yield child  # its name binds here; its body does not
+            for decorator in child.decorator_list:
+                yield from _module_scope_nodes(decorator)
+            continue
+        if isinstance(child, ast.Lambda | ast.ListComp | ast.SetComp | ast.DictComp | ast.GeneratorExp):
+            continue
+        yield from _module_scope_nodes(child)
+
+
+def _free_loads(node: ast.AST, local: frozenset[str] = frozenset()) -> Iterator[tuple[str, int]]:
+    """`(name, line)` of every load in `node` that is not bound by an enclosing function, lambda or comprehension."""
+    if isinstance(node, ast.Name):
+        if isinstance(node.ctx, ast.Load) and node.id not in local:
+            yield node.id, node.lineno
+        return
+    if isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef | ast.Lambda):
+        args = node.args
+        params = {a.arg for a in [*args.posonlyargs, *args.args, *args.kwonlyargs]}
+        params |= {a.arg for a in (args.vararg, args.kwarg) if a is not None}
+        for default in [*args.defaults, *(d for d in args.kw_defaults if d is not None)]:
+            yield from _free_loads(default, local)
+        body: list[ast.AST] = list(node.body) if isinstance(node.body, list) else [node.body]
+        assigned = {
+            n.id for part in body for n in ast.walk(part) if isinstance(n, ast.Name) and isinstance(n.ctx, ast.Store)
+        }
+        inner = local | params | assigned
+        if not isinstance(node, ast.Lambda):
+            for decorator in node.decorator_list:
+                yield from _free_loads(decorator, local)
+        for part in body:
+            yield from _free_loads(part, frozenset(inner))
+        return
+    if isinstance(node, ast.ListComp | ast.SetComp | ast.DictComp | ast.GeneratorExp):
+        targets = {name for gen in node.generators for name in _target_names(gen.target)}
+        inner = frozenset(local | targets)
+        for index, gen in enumerate(node.generators):
+            yield from _free_loads(gen.iter, local if index == 0 else inner)
+            for condition in gen.ifs:
+                yield from _free_loads(condition, inner)
+        elements = [node.key, node.value] if isinstance(node, ast.DictComp) else [node.elt]
+        for element in elements:
+            yield from _free_loads(element, inner)
+        return
+    for child in ast.iter_child_nodes(node):
+        yield from _free_loads(child, local)
+
+
+def _reads_before_rebinding(stmts: Sequence[ast.stmt], names: set[str]) -> dict[str, int]:
+    """The first line at which each of `names` is read by `stmts` where not every path has rebound it.
+
+    A name counts as rebound only when every path to the read rebinds it: both branches of an `if`
+    (their sets intersect at the join), never a loop's target or body after the loop (it may run zero
+    times), never a `try` body for its handlers or its `finally`, and never a `match` case after the
+    `match` (no case may apply). `del` unbinds.
+    """
+    hits: dict[str, int] = {}
+
+    def load(node: ast.AST | None, bound: frozenset[str]) -> None:
+        if node is None:
+            return
+        for name, line in _free_loads(node):
+            if name in names and name not in bound and name not in hits:
+                hits[name] = line
+
+    def bound_by(node: ast.AST | None) -> frozenset[str]:
+        return frozenset(_target_names(node)) if isinstance(node, ast.expr) else frozenset()
+
+    def sequence(statements: Iterable[ast.stmt], bound: frozenset[str]) -> frozenset[str]:
+        for stmt in statements:
+            bound = step(stmt, bound)
+        return bound
+
+    def step(stmt: ast.stmt, bound: frozenset[str]) -> frozenset[str]:
+        if isinstance(stmt, ast.For | ast.AsyncFor):
+            load(stmt.iter, bound)
+            sequence(stmt.body, bound | bound_by(stmt.target))
+            return sequence(stmt.orelse, bound)
+        if isinstance(stmt, ast.While):
+            load(stmt.test, bound)
+            sequence(stmt.body, bound)
+            return sequence(stmt.orelse, bound)
+        if isinstance(stmt, ast.If):
+            load(stmt.test, bound)
+            return sequence(stmt.body, bound) & sequence(stmt.orelse, bound)
+        if isinstance(stmt, ast.With | ast.AsyncWith):
+            for item in stmt.items:
+                load(item.context_expr, bound)
+                bound = bound | bound_by(item.optional_vars)
+            return sequence(stmt.body, bound)
+        if isinstance(stmt, ast.Try | ast.TryStar):
+            paths = [sequence(stmt.orelse, sequence(stmt.body, bound))]
+            for handler in stmt.handlers:
+                load(handler.type, bound)
+                paths.append(sequence(handler.body, bound | ({handler.name} if handler.name else set())))
+            joined = frozenset.intersection(*paths)
+            return joined | sequence(stmt.finalbody, bound)
+        if isinstance(stmt, ast.Match):
+            load(stmt.subject, bound)
+            for case in stmt.cases:
+                load(case.guard, bound)
+                sequence(case.body, bound | {n.id for n in ast.walk(case.pattern) if isinstance(n, ast.Name)})
+            return bound
+        if isinstance(stmt, ast.Assign):
+            load(stmt.value, bound)
+            for target in stmt.targets:
+                if not isinstance(target, ast.Name | ast.Tuple | ast.List):
+                    load(target, bound)
+            return bound.union(*(bound_by(target) for target in stmt.targets))
+        if isinstance(stmt, ast.AugAssign):
+            load(stmt.value, bound)
+            load(stmt.target, bound)
+            target = stmt.target  # `scale *= 2` reads `scale` first, though its context is Store
+            if isinstance(target, ast.Name) and target.id in names and target.id not in bound and target.id not in hits:
+                hits[target.id] = target.lineno
+            return bound | bound_by(stmt.target)
+        if isinstance(stmt, ast.AnnAssign):
+            load(stmt.value, bound)
+            return bound | bound_by(stmt.target) if stmt.value is not None else bound
+        if isinstance(stmt, ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef):
+            load(stmt, bound)
+            return bound | {stmt.name}
+        if isinstance(stmt, ast.Import | ast.ImportFrom):
+            return bound | _statement_bindings(stmt)
+        if isinstance(stmt, ast.Delete):
+            return bound - frozenset().union(*(bound_by(target) for target in stmt.targets))
+        load(stmt, bound)
+        return bound
+
+    sequence(stmts, frozenset())
+    return hits
+
+
+# rule 4 ---------------------------------------------------------------------------------------
+
+
+def _altair_field(text: str) -> str:
+    """A Vega-Lite field string as the column it names: type suffix dropped, escapes undone."""
+    return _ALTAIR_ESCAPE.sub(r"\1", _ALTAIR_SUFFIX.sub("", text))
+
+
+def _axes_hidden(src: _Source) -> bool:
+    """The file hides an axis, so its coordinates place a drawing (a Venn, a hemicycle, a ternary frame).
+
+    `ax.axis("off")`, `set_axis_off()`, `theme_void()`, altair's `axis=None`, plotly's `visible=False` on an
+    axis, and bokeh's `p.axis.visible = False`.
+    """
+    for node in ast.walk(src.tree):
+        if isinstance(node, ast.Call):
+            name = _call_name(node)
+            if name in ("set_axis_off", "theme_void"):
+                return True
+            if (
+                name == "axis"
+                and node.args
+                and isinstance(node.args[0], ast.Constant)
+                and node.args[0].value in ("off", False)
+            ):
+                return True
+            for keyword in node.keywords:
+                if not isinstance(keyword.value, ast.Constant):
+                    continue
+                value = keyword.value.value
+                if keyword.arg == "axis" and value is None:
+                    return True
+                if value is False and (
+                    (keyword.arg == "visible" and name in ("update_xaxes", "update_yaxes", "dict"))
+                    or (keyword.arg or "").endswith("axis_visible")
+                ):
+                    return True
+        elif isinstance(node, ast.Assign) and isinstance(node.value, ast.Constant) and node.value.value is False:
+            for target in node.targets:
+                if isinstance(target, ast.Attribute) and target.attr == "visible":
+                    owner = _dotted(target.value) or ""
+                    if owner.endswith(("axis", "xaxis", "yaxis")):
+                        return True
+    return False
+
+
+def _check_literals(src: _Source, sample: _Sample | None) -> list[Finding]:
+    found: list[Finding] = []
+    below = src.below()
+    derived = _df_derived(below) if sample is not None else set()
+    aliases = _literal_aliases(below) if sample is not None else {}
+    coordinates = not _axes_hidden(src)
+    seen_coordinates: set[int] = set()
+    for stmt in below:
+        for node in ast.walk(stmt):
+            if src.inside(node, (ast.JoinedStr,)) is not None or _in_output_call(src, node):
+                continue
+            if isinstance(node, ast.Constant) and isinstance(node.value, str):
+                found.extend(_string_finding(src, node, sample))
+            elif isinstance(node, ast.Call):
+                coordinate = _coordinate_finding(src, node, frames=src.block is not None) if coordinates else None
+                if coordinate is not None and coordinate.line not in seen_coordinates:
+                    seen_coordinates.add(coordinate.line or 0)
+                    found.append(coordinate)
+                if sample is not None:
+                    found.extend(_count_finding(src, node, sample))
+                    found.extend(_method_comparison(src, node, derived, aliases))
+            elif isinstance(node, ast.Assign) and coordinates:
+                attribute = _attribute_coordinate(src, node)
+                if attribute is not None:
+                    found.append(attribute)
+            elif isinstance(node, ast.Subscript) and sample is not None:
+                found.extend(_slice_count(src, node, sample))
+            elif isinstance(node, ast.Compare) and sample is not None:
+                found.extend(_compare_finding(src, node, derived, aliases))
+    return found
+
+
+def _in_output_call(src: _Source, node: ast.AST) -> bool:
+    current: ast.AST | None = node
+    while current is not None:
+        if isinstance(current, ast.Call) and _call_name(current) in OUTPUT_CALLS:
+            return True
+        current = src.parents.get(current)
+    return False
+
+
+def _string_finding(src: _Source, node: ast.Constant, sample: _Sample | None) -> list[Finding]:
+    text = node.value
+    assert isinstance(text, str)
+    if "anyplot.ai" in text:
+        return []
+    parent = src.parents.get(node)
+    if isinstance(parent, ast.keyword) and parent.arg in STYLE_KEYWORDS:
+        return []
+    if isinstance(parent, ast.Expr):
+        return []  # a docstring or a bare string statement
+    found: list[Finding] = []
+    if sample is not None:
+        field_name = _altair_field(text)
+        if text in sample.columns or field_name in sample.columns:
+            found.append(
+                Finding(
+                    "column-literal",
+                    node.lineno,
+                    f"types the column name {text!r}",
+                    f"{src.snippet(parent) if parent is not None else repr(text)} repeats a column name below the Data block",
+                )
+            )
+        elif (
+            (text in sample.strings or (text in sample.fields and not _PROPERTY_KEY.match(text)))
+            and len(text.strip()) >= MIN_SAMPLE_CHARS
+            and text.strip().lower() not in PROSE_WORDS | STYLE_WORDS
+            and not (isinstance(parent, ast.Dict) and node in parent.keys and _PROPERTY_KEY.match(text))
+        ):
+            context = src.snippet(parent) if parent is not None else repr(text)
+            found.append(
+                Finding(
+                    "sample-literal",
+                    node.lineno,
+                    f"uses the literal {text!r}, a value the Data block defines",
+                    f"{context} below the Data block",
+                )
+            )
+    if _STATISTIC.search(text):
+        found.append(
+            Finding(
+                "statistic-text",
+                node.lineno,
+                f"states the statistic {text!r} as text",
+                "a number from the sample typed into a label",
+            )
+        )
+    return found
+
+
+def _coordinate_finding(src: _Source, call: ast.Call, frames: bool) -> Finding | None:
+    """A numeric literal or literal date in a data-coordinate position of `call`.
+
+    `frames` checks the literal data of a `DataFrame` built in the plot code (a reference line's
+    frame in altair); it is off when there is no block, since the data generation is then unknown.
+    """
+    name = _call_name(call)
+    keywords = {kw.arg: kw.value for kw in call.keywords if kw.arg}
+    candidates: list[ast.expr] = []
+    if name in LIMIT_METHODS:
+        # positional bounds and the bound keywords only: `set_xticks(x, labels, fontsize=8)` styles its labels
+        candidates = [*call.args, *(value for key, value in keywords.items() if key in LIMIT_KEYWORDS)]
+        if any(not _literal_values(node) and not isinstance(node, ast.List | ast.Tuple) for node in candidates):
+            # padding beside a computed bound: set_xlim(-0.5, n - 0.5), set_ylim(0, top * 1.1)
+            candidates = [node for node in candidates if not _padding(node)]
+    elif name == "text" and call.args and isinstance(call.args[0], ast.Tuple | ast.List):
+        return None  # PIL's ImageDraw.text((x, y), ...) places pixels, not data
+    elif name == "annotate" and ("xy" in keywords or len(call.args) > 1):
+        # matplotlib's annotate(text, xy, xytext=...); plotnine's annotate("text", x=..., y=...) uses the table below
+        if not _paper_ref(keywords.get("xycoords")):
+            xy = call.args[1] if len(call.args) > 1 else keywords.get("xy")
+            if xy is not None:
+                candidates.append(xy)
+            text_coords = keywords.get("textcoords", keywords.get("xycoords"))
+            if "xytext" in keywords and not _paper_ref(text_coords):
+                candidates.append(keywords["xytext"])
+    elif name in DATA_CALL_ARGS:
+        if name == "text" and _figure_text(src, call, keywords):
+            return None
+        if name in ("add_annotation", "add_shape") and (
+            _paper_ref(keywords.get("xref")) or _paper_ref(keywords.get("yref"))
+        ):
+            return None
+        if name == "Label" and (_paper_ref(keywords.get("x_units")) or _paper_ref(keywords.get("y_units"))):
+            return None
+        positions, names = DATA_CALL_ARGS[name]
+        candidates = [call.args[i] for i in positions if i < len(call.args)]
+        candidates += [keywords[key] for key in names if key in keywords]
+    elif name is not None and name.startswith("geom_"):
+        candidates = [keywords[key] for key in _GEOM_COORDINATES if key in keywords]
+    elif name is not None and name in NORM_CALLS:
+        positions, norm_names = NORM_CALLS[name]
+        candidates = [call.args[i] for i in positions if i < len(call.args)]
+        candidates += [value for key, value in keywords.items() if key in norm_names]
+    elif name == "DataFrame" and frames:
+        candidates = [*call.args[:1], *(value for key, value in keywords.items() if key == "data")]
+        candidates = [_frame_values(node) for node in candidates]
+    visual_range = name == "Scale" or (name or "").startswith("scale_")
+    for key, value in keywords.items():
+        if key == "range" and visual_range:
+            continue  # alt.Scale(range=...) and scale_size(range=...) map to sizes or colors, not data
+        if key in GENERIC_DATA_KEYWORDS or _AXIS_DATA_KEYWORD.match(key):
+            candidates.append(value)
+        elif key == "levels" and name in CONTOUR_CALLS and _number(value) is None:
+            candidates.append(value)
+        elif key == "ticks" and name == "colorbar":
+            candidates.append(value)
+        elif key == "bins" and _number(value) is None:
+            candidates.append(value)
+    for node in call.args + list(keywords.values()):
+        if isinstance(node, ast.Dict):
+            candidates.extend(_dict_coordinates(node))
+    values = [value for node in candidates for value in _literal_values(_without_padding(node))]
+    if not values or _exempt(values):
+        return None
+    shown = ", ".join(_format_value(value) for value in values[:4]) + (", …" if len(values) > 4 else "")
+    return Finding(
+        "data-coordinate",
+        call.lineno,
+        f"places data coordinates by the literal{'s' if len(values) > 1 else ''} {shown}",
+        f"`{src.snippet(call)}` fixes the axis to the sample's range",
+    )
+
+
+def _padding(node: ast.expr) -> bool:
+    """A literal of magnitude `PADDING` or less: padding or a baseline beside a computed bound."""
+    value = _number(node)
+    return value is not None and abs(value) <= PADDING
+
+
+def _without_padding(node: ast.expr) -> ast.expr:
+    """A bound pair with a computed member keeps only its literals beyond `PADDING`: `xlim=(-1.5, n + 0.5)`."""
+    if isinstance(node, ast.Tuple | ast.List) and any(_number(element) is None for element in node.elts):
+        return ast.List(elts=[element for element in node.elts if not _padding(element)], ctx=ast.Load())
+    return node
+
+
+def _frame_values(node: ast.expr) -> ast.expr:
+    """The literal data of a `DataFrame` built below the block, as one list node."""
+    if isinstance(node, ast.Dict):
+        return ast.List(elts=[value for value in node.values if value is not None], ctx=ast.Load())
+    return node
+
+
+def _dict_coordinates(node: ast.Dict) -> list[ast.expr]:
+    out: list[ast.expr] = []
+    for key, value in zip(node.keys, node.values, strict=True):
+        if isinstance(key, ast.Constant) and isinstance(key.value, str):
+            if key.value in GENERIC_DATA_KEYWORDS or _AXIS_DATA_KEYWORD.match(key.value):
+                out.append(value)
+            elif key.value == "ticks" and isinstance(value, ast.List | ast.Tuple):
+                out.append(value)
+    return out
+
+
+def _paper_ref(node: ast.expr | None) -> bool:
+    if isinstance(node, ast.Constant) and isinstance(node.value, str):
+        return any(ref in node.value for ref in PAPER_REFS)
+    if node is not None:
+        dotted = _dotted(node) or ""
+        return dotted.endswith(("transAxes", "transFigure"))
+    return False
+
+
+def _figure_text(src: _Source, call: ast.Call, keywords: Mapping[str, ast.expr]) -> bool:
+    """A `text` call in figure or axes coordinates."""
+    if isinstance(call.func, ast.Attribute):
+        receiver = _dotted(call.func.value) or ""
+        if "fig" in receiver.rsplit(".", 1)[-1].lower():
+            return True
+    transform = keywords.get("transform")
+    return transform is not None and not (_dotted(transform) or "").endswith("transData")
+
+
+def _format_value(value: float | str) -> str:
+    if isinstance(value, str):
+        return value
+    return str(int(value)) if value == int(value) else f"{value:g}"
+
+
+def _attribute_coordinate(src: _Source, node: ast.Assign) -> Finding | None:
+    for target in node.targets:
+        if isinstance(target, ast.Attribute) and target.attr in DATA_ATTRIBUTES:
+            values = _literal_values(node.value)
+            if values and not _exempt(values):
+                shown = ", ".join(_format_value(value) for value in values[:4])
+                return Finding(
+                    "data-coordinate",
+                    node.lineno,
+                    f"sets `{src.snippet(target)}` to the literal {shown}",
+                    "a range or tick list typed for the sample",
+                )
+    return None
+
+
+def _count_finding(src: _Source, call: ast.Call, sample: _Sample) -> list[Finding]:
+    name = _call_name(call)
+    if name not in RANGE_CALLS:
+        return []
+    length = _range_length(call)
+    if length is None or length not in sample.counts:
+        return []
+    if name == "linspace" and length >= RESOLUTION_COUNT:
+        return []
+    return [
+        Finding(
+            "count-literal",
+            call.lineno,
+            f"counts {length} with `{src.snippet(call)}`, a count the Data block defines",
+            "the number of sample rows or categories typed as a literal",
+        )
+    ]
+
+
+def _slice_count(src: _Source, node: ast.Subscript, sample: _Sample) -> list[Finding]:
+    if not isinstance(node.slice, ast.Slice):
+        return []
+    if isinstance(node.value, ast.Name) and node.value.id in PALETTE_NAMES:
+        return []  # the palette rule reports palette slices
+    lower = _count(node.slice.lower) if node.slice.lower is not None else None
+    upper = _count(node.slice.upper) if node.slice.upper is not None else None
+    if lower is None and upper is not None and upper > 0:
+        length = upper
+    elif upper is None and lower is not None and lower < 0:
+        length = -lower
+    elif lower is not None and upper is not None and upper > lower >= 0:
+        length = upper - lower
+    else:
+        return []
+    if length not in sample.counts:
+        return []
+    return [
+        Finding(
+            "count-literal",
+            node.lineno,
+            f"slices {length} items with `{src.snippet(node)}`, a count the Data block defines",
+            "the number of sample rows or categories typed as a literal",
+        )
+    ]
+
+
+def _df_derived(stmts: Sequence[ast.stmt]) -> set[str]:
+    """`df` and the names the plot code derives from it, in order (loop targets over derived values included)."""
+    derived = {"df"}
+    for stmt in stmts:
+        for node in _module_scope_nodes(stmt):
+            assigned = _assignment(node)
+            if assigned is not None and _names_in(assigned[1]) & derived:
+                for target in assigned[0]:
+                    derived |= _target_names(target)
+            elif isinstance(node, ast.For | ast.AsyncFor) and _names_in(node.iter) & derived:
+                derived |= _target_names(node.target)
+            elif isinstance(node, ast.comprehension) and _names_in(node.iter) & derived:
+                derived |= _target_names(node.target)
+        for node in ast.walk(stmt):
+            if isinstance(node, ast.comprehension) and _names_in(node.iter) & derived:
+                derived |= _target_names(node.target)
+    return derived
+
+
+def _literal_aliases(stmts: Sequence[ast.stmt]) -> dict[str, ast.Constant]:
+    """Names bound once, at module level below the block, to a number, string or date literal."""
+    counts: Counter[str] = Counter()
+    values: dict[str, ast.Constant] = {}
+    for stmt in stmts:
+        assigned = _assignment(stmt)
+        if assigned is not None:
+            for target in assigned[0]:
+                for name in _target_names(target):
+                    counts[name] += 1
+            single = _single_name(stmt)
+            if single is not None:
+                value = single[1]
+                if (
+                    isinstance(value, ast.Constant)
+                    and isinstance(value.value, int | float | str)
+                    and not isinstance(value.value, bool)
+                ):
+                    values[single[0]] = value
+        else:
+            for name in _statement_bindings(stmt):
+                counts[name] += 1
+    return {name: value for name, value in values.items() if counts[name] == 1}
+
+
+def _comparison_literal(node: ast.expr, aliases: Mapping[str, ast.Constant]) -> tuple[str, ast.expr] | None:
+    """The literal a comparison operand stands for, as `(shown, literal node)`, or None."""
+    if isinstance(node, ast.Name) and node.id in aliases:
+        literal: ast.expr = aliases[node.id]
+        shown = f"{node.id} = {ast.unparse(literal)}"
+    else:
+        literal = node
+        shown = ast.unparse(node)
+    if isinstance(literal, ast.Constant) and isinstance(literal.value, str):
+        return (shown, literal) if literal.value.strip() else None
+    values = _literal_values(literal)
+    if values and not _exempt(values):
+        return shown, literal
+    if isinstance(literal, ast.List | ast.Tuple | ast.Set) and any(
+        isinstance(e, ast.Constant) and isinstance(e.value, str) for e in literal.elts
+    ):
+        return shown, literal
+    return None
+
+
+def _compare_finding(
+    src: _Source, node: ast.Compare, derived: set[str], aliases: Mapping[str, ast.Constant]
+) -> list[Finding]:
+    if not all(isinstance(op, SELECTION_OPS) for op in node.ops):
+        return []
+    operands = [node.left, *node.comparators]
+    if not any(_names_in(operand) & derived for operand in operands):
+        return []
+    for operand in operands:
+        if _names_in(operand) & derived:
+            continue
+        literal = _comparison_literal(operand, aliases)
+        if literal is not None:
+            return [
+                Finding(
+                    "df-comparison",
+                    node.lineno,
+                    f"compares df with the literal {literal[0]}",
+                    f"`{src.snippet(node)}` selects a sample value",
+                )
+            ]
+    return []
+
+
+def _method_comparison(
+    src: _Source, call: ast.Call, derived: set[str], aliases: Mapping[str, ast.Constant]
+) -> list[Finding]:
+    name = _call_name(call)
+    if name not in COMPARISON_METHODS:
+        return []
+    if not isinstance(call.func, ast.Attribute) or not (_names_in(call.func.value) & derived):
+        return []
+    for arg in call.args:
+        literal = _comparison_literal(arg, aliases)
+        if literal is not None:
+            return [
+                Finding(
+                    "df-comparison",
+                    call.lineno,
+                    f"compares df with the literal {literal[0]}",
+                    f"`{src.snippet(call)}` selects a sample value",
+                )
+            ]
+    return []
+
+
+# rule 5 ---------------------------------------------------------------------------------------
+
+
+def _palette(src: _Source) -> tuple[str, list[str], int] | None:
+    """The module's Imprint palette: its name, its entries and its line."""
+    for stmt in src.tree.body:
+        single = _single_name(stmt)
+        if single is None:
+            continue
+        name, value = single
+        if not isinstance(value, ast.List | ast.Tuple):
+            continue
+        entries = [e.value.upper() for e in value.elts if isinstance(e, ast.Constant) and isinstance(e.value, str)]
+        if name in PALETTE_NAMES or (len(entries) >= 2 and entries[0] == CANONICAL_IMPRINT[0]):
+            return name, entries, stmt.lineno
+    return None
+
+
+def _check_palette(src: _Source, color: DataRole | None) -> list[Finding]:
+    """Rule 5. A missing palette counts only for a required colour role: an optional one may go unused."""
+    found: list[Finding] = []
+    palette = _palette(src)
+    names = set(PALETTE_NAMES) | ({palette[0]} if palette else set())
+    role = color.name if color is not None else None
+    if color is not None:
+        if palette is None:
+            if color.required:
+                found.append(
+                    Finding(
+                        "palette",
+                        None,
+                        f"has no IMPRINT list while the spec's `{role}` role colors the marks",
+                        "colors come from elsewhere than the Imprint palette",
+                    )
+                )
+        else:
+            name, entries, line = palette
+            canonical = [entry.upper() for entry in CANONICAL_IMPRINT]
+            if entries != canonical:
+                what = (
+                    f"lists {len(entries)} of 8 positions"
+                    if entries == canonical[: len(entries)]
+                    else "lists the Imprint colors out of canonical order"
+                )
+                found.append(
+                    Finding("palette", line, f"`{name}` {what}", f"a palette sized to the sample's `{role}` values")
+                )
+    for stmt in src.tree.body:
+        for node in ast.walk(stmt):
+            if isinstance(node, ast.Call) and _call_name(node) == "zip":
+                strict = any(
+                    kw.arg == "strict" and isinstance(kw.value, ast.Constant) and kw.value.value is True
+                    for kw in node.keywords
+                )
+                if strict and any(_names_in(arg) & names and not _sized_slice(arg) for arg in node.args):
+                    found.append(
+                        Finding(
+                            "palette",
+                            node.lineno,
+                            "zips the palette with strict=True, which raises for one more group",
+                            f"`{src.snippet(node)}`",
+                        )
+                    )
+            elif (
+                role is not None
+                and isinstance(node, ast.Subscript)
+                and isinstance(node.value, ast.Name)
+                and node.value.id in names
+                and isinstance(node.slice, ast.Slice)
+                and node.slice.upper is not None
+                and _count(node.slice.upper) is not None
+            ):
+                found.append(
+                    Finding(
+                        "palette",
+                        node.lineno,
+                        f"slices the palette to a fixed size with `{src.snippet(node)}`",
+                        "a literal slice sized to the sample's groups",
+                    )
+                )
+    return found
+
+
+def _sized_slice(node: ast.expr) -> bool:
+    """A palette slice whose length is computed (`IMPRINT[: len(groups)]`): a strict zip over it raises only past eight."""
+    return (
+        isinstance(node, ast.Subscript)
+        and isinstance(node.slice, ast.Slice)
+        and (node.slice.upper is not None and _count(node.slice.upper) is None)
+    )
+
+
+# rule 6 ---------------------------------------------------------------------------------------
+
+
+def _check_constants_zone(src: _Source, sample: _Sample) -> list[Finding]:
+    found: list[Finding] = []
+    for stmt in src.constants_zone():
+        assigned = _assignment(stmt)
+        if assigned is None or any(
+            line
+            for line, col, text in src.comments
+            if col > 0 and ROLE_COMMENT.match(text) and stmt.lineno <= line <= (stmt.end_lineno or stmt.lineno)
+        ):
+            continue
+        value = assigned[1]
+        strings = {
+            node.value for node in ast.walk(value) if isinstance(node, ast.Constant) and isinstance(node.value, str)
+        }
+        numbers = {
+            number
+            for node in ast.walk(value)
+            if isinstance(node, ast.expr)
+            and not isinstance(node, ast.BinOp | ast.UnaryOp)
+            and (number := _number(node)) is not None
+        }
+        shared = sorted(strings & sample.strings)
+        coordinates = sorted(n for n in numbers & sample.numbers if not _exempt([n]))
+        container = isinstance(value, ast.List | ast.Tuple | ast.Set | ast.Dict)
+        if shared and (container or isinstance(value, ast.Constant)):
+            shown = ", ".join(repr(text) for text in shared[:3]) + (", …" if len(shared) > 3 else "")
+            found.append(
+                Finding(
+                    "constants",
+                    stmt.lineno,
+                    f"lists sample values ({shown}) in # Constants",
+                    "sample categories hoisted out of the Data block, or an ordered scale the block also spells out",
+                )
+            )
+        elif container and len(coordinates) >= 2:
+            shown = ", ".join(_format_value(number) for number in coordinates[:3])
+            found.append(
+                Finding(
+                    "constants",
+                    stmt.lineno,
+                    f"lists the sample's data numbers ({shown}) in # Constants",
+                    "data coordinates hoisted out of the Data block",
+                )
+            )
+    return found
+
+
+# --- source mutations --------------------------------------------------------------------------
+
+
+def replace_block(source: str, replacement: str) -> str:
+    """The source with the statements between the `# Data` and `# Plot` markers replaced; the markers stay.
+
+    Raises ValueError when the source has no block.
+    """
+    tree = ast.parse(source)
+    src = _Source(source, tree, None)
+    if src.block is None:
+        raise ValueError("the source has no # Data ... # Plot block")
+    start, end = src.block
+    lines = source.splitlines(keepends=True)
+    body = replacement if replacement.endswith("\n") else replacement + "\n"
+    return "".join(lines[:start]) + body + "\n" + "".join(lines[end - 1 :])
+
+
+def rewrite_constants(source: str, columns: Mapping[str, str | Sequence[str]]) -> str:
+    """The source with each role's column constant set to the column name(s) in `columns` (role -> name).
+
+    Roles without a constant are ignored; a constant whose role is not in `columns` keeps its value.
+    """
+    return _rewrite(source, lambda constant, _: columns.get(constant.role))
+
+
+def rewrite_columns(source: str, renames: Mapping[str, str]) -> str:
+    """The source with every column constant, `# role: extra` included, renamed through `renames` (old -> new).
+
+    A constant whose value (or one of whose list entries) is an old column name gets the new one; any
+    other constant keeps its value. This is how a table with renamed columns reaches columns that no
+    spec role names.
+    """
+
+    def choose(_: _Constant, current: str | list[str] | None) -> str | list[str] | None:
+        if isinstance(current, str):
+            return renames.get(current)
+        if isinstance(current, list) and any(item in renames for item in current):
+            return [renames.get(item, item) for item in current]
+        return None
+
+    return _rewrite(source, choose)
+
+
+def _literal_columns(value: ast.expr) -> str | list[str] | None:
+    """A constant's column name, or its list of names; None for any other value."""
+    if isinstance(value, ast.Constant) and isinstance(value.value, str):
+        return value.value
+    if isinstance(value, ast.List | ast.Tuple) and all(
+        isinstance(item, ast.Constant) and isinstance(item.value, str) for item in value.elts
+    ):
+        return [item.value for item in value.elts if isinstance(item, ast.Constant) and isinstance(item.value, str)]
+    return None
+
+
+def _rewrite(source: str, choose: Callable[[_Constant, str | list[str] | None], str | Sequence[str] | None]) -> str:
+    """Set each column constant's value to `choose(constant, current value)`, unless that is None.
+
+    The new value is written on one line. A role comment inside the old value's span (`SERIES = [  # role: y`
+    over several lines) moves to the end of the statement's last line, so the constant stays a constant.
+    """
+    tree = ast.parse(source)
+    src = _Source(source, tree, None)
+    offsets = _line_offsets(source)
+    role_comments = [
+        (offsets[line - 1] + col, text) for line, col, text in src.comments if col > 0 and ROLE_COMMENT.match(text)
+    ]
+    edits: list[tuple[int, int, str]] = []
+    for constant in _column_constants(src):
+        new = choose(constant, _literal_columns(constant.value))
+        if new is None:
+            continue
+        value = constant.value
+        start = offsets[value.lineno - 1] + _char_offset(source, offsets, value.lineno, value.col_offset)
+        end_line = value.end_lineno or value.lineno
+        end = offsets[end_line - 1] + _char_offset(source, offsets, end_line, value.end_col_offset or 0)
+        text = json.dumps(new if isinstance(new, str) else list(new), ensure_ascii=False)
+        inside = [comment for position, comment in role_comments if start <= position < end]
+        if inside:
+            line_end = source.find("\n", end)
+            line_end = len(source) if line_end == -1 else line_end
+            tail = source[end:line_end].strip()
+            text += f"  {inside[0]}" + (f"  {tail}" if tail else "")
+            end = line_end
+        edits.append((start, end, text))
+    for start, end, text in sorted(edits, reverse=True):
+        source = source[:start] + text + source[end:]
+    return source
+
+
+def _line_offsets(source: str) -> list[int]:
+    offsets = [0]
+    for line in source.splitlines(keepends=True):
+        offsets.append(offsets[-1] + len(line))
+    return offsets
+
+
+def _char_offset(source: str, offsets: Sequence[int], line: int, byte_col: int) -> int:
+    """A column in characters from the AST's UTF-8 byte column."""
+    text = source[offsets[line - 1] : offsets[line] if line < len(offsets) else len(source)]
+    return len(text.encode("utf-8")[:byte_col].decode("utf-8", errors="ignore"))
+
+
+# --- files and CLI -----------------------------------------------------------------------------
+
+
+def library_of(path: Path) -> str | None:
+    """The library a catalogue implementation file belongs to (its stem), or None for another file name."""
+    return path.stem if path.stem in LIBRARIES else None
+
+
+def spec_context(spec_path: Path, spec_id: str | None = None) -> tuple[str, list[DataRole], Shape]:
+    """The spec id, parsed roles and shape of a `specification.md`."""
+    spec_id = spec_id or spec_path.parent.name
+    roles = parse_roles(data_bullets(spec_path.read_text(encoding="utf-8")))
+    return spec_id, roles, spec_shape(spec_id, roles)
+
+
+def check_file(impl_path: Path, spec_path: Path | None = None, *, spec_id: str | None = None) -> Record:
+    """Check a catalogue file; the spec defaults to `plots/<spec>/specification.md` next to it."""
+    if spec_path is None:
+        spec_path = impl_path.parents[2] / "specification.md"
+    _, roles, shape = spec_context(spec_path, spec_id)
+    return check_source(impl_path.read_text(encoding="utf-8"), roles, shape, library=library_of(impl_path))
+
+
+def _implementations(plots: Path, library: str | None) -> list[Path]:
+    pattern = f"*/implementations/python/{library}.py" if library else "*/implementations/python/*.py"
+    return sorted(path for path in plots.glob(pattern) if library_of(path) is not None)
+
+
+def run_report(plots: Path, library: str | None = None) -> list[tuple[Path, Record]]:
+    """The record of every Python implementation under `plots/`."""
+    results: list[tuple[Path, Record]] = []
+    specs: dict[Path, tuple[str, list[DataRole], Shape]] = {}
+    for path in _implementations(plots, library):
+        spec_path = path.parents[2] / "specification.md"
+        if spec_path not in specs:
+            specs[spec_path] = spec_context(spec_path)
+        _, roles, shape = specs[spec_path]
+        results.append((path, check_source(path.read_text(encoding="utf-8"), roles, shape, library=library_of(path))))
+    return results
+
+
+def format_report(results: Sequence[tuple[Path, Record]]) -> str:
+    """Per-library pass/fail counts and, per rule class, the number of files with a finding."""
+    by_library: dict[str, Counter[str]] = {}
+    classes: dict[str, Counter[str]] = {cls: Counter() for cls in RULE_ORDER}
+    shapes: Counter[str] = Counter()
+    for path, record in results:
+        library = library_of(path) or path.stem
+        by_library.setdefault(library, Counter())[record.status] += 1
+        for cls in record.classes():
+            classes[cls][library] += 1
+        if library == "matplotlib":
+            shapes[record.shape] += 1
+    libraries = [lib for lib in LIBRARIES if lib in by_library]
+    out = ["| Library | Files | Pass | Fail | Excluded |", "|---|---|---|---|---|"]
+    totals: Counter[str] = Counter()
+    for lib in libraries:
+        counts = by_library[lib]
+        total = sum(counts.values())
+        totals.update(counts)
+        out.append(f"| {lib} | {total} | {counts['pass']} | {counts['fail']} | {counts['excluded']} |")
+    out.append(f"| **all** | {sum(totals.values())} | {totals['pass']} | {totals['fail']} | {totals['excluded']} |")
+    out += ["", "Files with a finding, per rule class:", ""]
+    out.append("| Rule | Class | " + " | ".join(libraries) + " | All |")
+    out.append("|---|---|" + "---|" * len(libraries) + "---|")
+    for cls in RULE_ORDER:
+        rule = RULE_CLASSES[cls]
+        label = f"{cls} (advisory)" if rule.advisory else cls
+        cells = [str(classes[cls][lib]) for lib in libraries]
+        out.append(f"| {rule.rule} | {label} | " + " | ".join(cells) + f" | {sum(classes[cls].values())} |")
+    if shapes:
+        out += [
+            "",
+            "Specs per shape (one library's files): " + ", ".join(f"{k} {v}" for k, v in sorted(shapes.items())),
+        ]
+    return "\n".join(out)
+
+
+def sample_findings(
+    results: Sequence[tuple[Path, Record]], per_class: int, seed: int, root: Path | None = None
+) -> dict[str, list[str]]:
+    """Per rule class, up to `per_class` findings drawn at random (one per file), as `file:line  observed`."""
+    rng = random.Random(seed)
+    out: dict[str, list[str]] = {}
+    for cls in RULE_ORDER:
+        pool: list[tuple[Path, Finding]] = []
+        for path, record in results:
+            matches = [finding for finding in record.findings if finding.cls == cls]
+            if matches:
+                pool.append((path, rng.choice(matches)))
+        picked = rng.sample(pool, min(per_class, len(pool)))
+        lines = []
+        for path, finding in sorted(picked, key=lambda item: str(item[0])):
+            shown = path.relative_to(root) if root is not None and path.is_relative_to(root) else path
+            where = f"{shown}:{finding.line}" if finding.line is not None else str(shown)
+            lines.append(f"{where}  {finding.observed}")
+        out[cls] = lines
+    return out
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="python -m core.adaptability", description="Check Python implementations against the adaptable-code rules."
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+    check = sub.add_parser("check", help="check one implementation file")
+    check.add_argument("source", type=Path)
+    check.add_argument("--spec", type=Path, default=None, help="specification.md (default: the catalogue's)")
+    check.add_argument("--spec-id", default=None)
+    check.add_argument("--out", type=Path, default=None, help="write the record as JSON here")
+    report = sub.add_parser("report", help="check every Python implementation under plots/")
+    report.add_argument("plots", type=Path)
+    report.add_argument("--library", default=None, choices=LIBRARIES)
+    report.add_argument("--sample", type=int, default=0, help="print N random findings per rule class")
+    report.add_argument("--seed", type=int, default=1)
+    report.add_argument("--json", action="store_true", help="print every record as JSON lines")
+    args = parser.parse_args(argv)
+
+    if args.command == "check":
+        try:
+            record = check_file(args.source, args.spec, spec_id=args.spec_id)
+        except OSError as exc:
+            print(f"::error::adaptability check cannot read its input: {exc}")
+            return 2
+        payload = json.dumps(record.to_dict(), ensure_ascii=False)
+        if args.out is not None:
+            args.out.write_text(payload + "\n", encoding="utf-8")
+        print(payload)
+        for line in record.defect_lines():
+            print(line)
+        return 1 if record.status == "fail" else 0
+
+    results = run_report(args.plots, args.library)
+    if args.json:
+        for path, record in results:
+            print(json.dumps({"file": str(path), **record.to_dict()}, ensure_ascii=False))
+        return 0
+    print(format_report(results))
+    if args.sample:
+        root = args.plots.resolve().parent
+        resolved = [(path.resolve(), record) for path, record in results]
+        for cls, lines in sample_findings(resolved, args.sample, args.seed, root).items():
+            print(f"\n## {cls} ({len(lines)} sampled)\n")
+            for line in lines:
+                print(line)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/changelog.d/adaptability-checker.md b/changelog.d/adaptability-checker.md
new file mode 100644
index 00000000000..da053b7eb7c
--- /dev/null
+++ b/changelog.d/adaptability-checker.md
@@ -0,0 +1,25 @@
+### Added
+
+- **Adaptability checker for Python implementations.** `core/adaptability.py`
+  checks a source against the adaptable-code convention
+  (`docs/concepts/adaptable-code.md`): one `# Data` block that ends in `df`,
+  one column constant per spec role, no sample literals below the block, and
+  the full Imprint palette when a role colors the marks. It writes at most one
+  CQ-01 `(code)` line per rule class, and classes under 90 % precision on a
+  judged sample of 30 are advisory. `python -m core.adaptability report plots/`
+  prints the catalogue baseline, and `automation/scripts/adaptability_check.py`
+  is its generated single-file mirror for the workflow runner. The pipeline
+  does not run it yet, so this changes no score and no workflow. (#12244)
+- **Perturbation tables and render identity for the smoke run.**
+  `core/perturbation.py` builds the tables the smoke run swaps into the block
+  (renamed columns and categories, one more and one fewer group, a single group,
+  a tenth and ten times the rows, scaled values) and the source to run on each.
+  `core/render_identity.py` measures the share of differing pixels between two
+  renders against a bound. (#12244)
+
+### Changed
+
+- **The spec role parser moved to `core/spec_roles.py`.** The agent and the
+  checker now read a spec's `## Data` roles through one parser, which also files
+  each spec as a table, matrix, network, generated or map spec and names its
+  color-driving role. (#12244)
diff --git a/core/adaptability.py b/core/adaptability.py
new file mode 100644
index 00000000000..f4895fcaff5
--- /dev/null
+++ b/core/adaptability.py
@@ -0,0 +1,2456 @@
+"""The adaptability checker: is a Python implementation code that you can point at other data?
+
+The convention (docs/concepts/adaptable-code.md, "The convention") gives a Python
+implementation six zones: the head (imports, theme tokens, the 8-entry `IMPRINT`,
+library setup), an optional `# Constants` zone, one column constant per spec role
+(`MONTH = "Month"  # role: x`), exactly one `# Data` block that ends by binding the
+tidy DataFrame `df`, the plot code below a `# Plot` marker, and the output.
+`check_source` reads a source against the spec's roles (`core/spec_roles.py`) and
+its data shape, and returns a `Record`: a status, the findings, the block's marker
+lines, the role-to-constant map, the colour-driving role and the shape.
+
+The rules (`RULE_CLASSES`; the design's numbering):
+
+1. Layout (`layout`): one block between a column-0 `# Data` marker and the next
+   column-0 `# Plot` marker (the word alone, or followed by a colon or a dash and a
+   hint: `# Data: quarterly sales`, `# Data - ...`), ending in a statement that binds
+   `df` (not for a generated spec), with no plotting, styling or setup call and no
+   theme token inside; above the block no figure is created and no plotting call
+   runs except the library's setup calls (`SETUP_CALLS`).
+2. Columns (`columns`): every required column-valued role has exactly one constant
+   with a trailing `# role: <role>` comment, above the block; no comment names an
+   unknown role (`# role: extra` marks a column no spec role names); every value is
+   a string, or a list of strings for a variadic family. A matrix role, a network's
+   node and edge tables and every role of a generated spec need no constant
+   (`spec_roles.is_structure_role`).
+3. Interface (`interface`): no name bound in the block other than `df` (and a
+   network's `nodes`) is read below it before the plot code rebinds it.
+4. Literals below the block: a string equal to a column constant's value or a column
+   the block names (`column-literal`); a string equal to a sample value the block
+   defines (`sample-literal`); a numeric literal or literal date in a data-coordinate
+   position (`data-coordinate`: limits, ticks, reference lines, data-coordinate text,
+   color-scale bounds and the libraries' equivalents); a statistic written as text
+   (`statistic-text`); a comparison of `df` (or a name derived from it) with a
+   literal, also through one alias bound below the block (`df-comparison`); a count
+   literal equal to a count the block defines, in `range`, `arange`, `linspace` and
+   slice positions only (`count-literal`).
+5. Palette (`palette`): when the spec has a colour-driving role, all eight `IMPRINT`
+   positions in canonical order and no literal slice of the palette; in every spec, no
+   `zip(..., strict=True)` over the palette.
+6. `# Constants` (`constants`, advisory): no list, dict or string in the zone whose
+   values match the block's sample values or data numbers.
+
+No rule flags a literal inside the block. The checker ignores the head, the mandated
+title (any string with "anyplot.ai") and its font-size arithmetic, `savefig` and the
+other output calls, style keywords (`STYLE_KEYWORDS`: `fontsize`, `ha`, `marker`,
+...), offsets in points and axes fractions, f-strings, comments, values that span a
+fixed domain (0 to 1, 0 to 100, -1 to 1, 0 to 360, with up to 10 % headroom), the
+neutral values -1, 0 and 1, and the statistical critical values (`CRITICAL_VALUES`).
+
+A rule class marked advisory produces a finding and a defect line tagged
+"(advisory)" but never fails the record. Without a block, the sample-dependent
+classes (interface, column and sample literals, df comparisons, counts, `# Constants`)
+cannot run; data coordinates and statistics are then checked over the whole file.
+
+`Record.defect_lines` writes at most one line per rule class in the grammar of
+`core/defects.py` (`CQ-01 (code): line N ... → .... Likely cause: ....`), naming the
+first finding and the lines of the others. `replace_block` and `rewrite_constants`
+mutate a source through the markers and the role comments, which is how the agent
+substitutes a user's table and how the perturbation smoke run
+(`core/perturbation.py`) swaps in its tables.
+
+The module uses the standard library only. The workflow runner runs it as the
+single-file mirror `automation/scripts/adaptability_check.py`, which
+`core/adaptability_mirror.py` builds from this file and `core/spec_roles.py`;
+`tests/unit/core/test_adaptability_mirror.py` pins the two.
+
+Usage as CLI::
+
+    python -m core.adaptability check plots/bar-grouped/implementations/python/matplotlib.py
+    python -m core.adaptability report plots/ [--library matplotlib] [--sample 30 --seed 1] [--json]
+
+`check` prints the record as JSON and the defect lines (exit 0 on pass or an
+excluded spec, 1 on fail, 2 when the files cannot be read); `report` runs the
+checker over every Python implementation and prints per-library counts and the
+findings histogram per rule class.
+"""
+
+from __future__ import annotations
+
+import argparse
+import ast
+import builtins
+import io
+import json
+import random
+import re
+import sys
+import tokenize
+from collections import Counter
+from collections.abc import Callable, Iterable, Iterator, Mapping, Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from core.spec_roles import DataRole, Shape, color_role, data_bullets, is_structure_role, parse_roles, spec_shape
+
+
+CHECKER_VERSION = 1
+DEFECT_ID = "CQ-01"
+CODE_RENDER = "code"
+DEFECT_ARROW = "→"
+
+CANONICAL_IMPRINT = ("#009E73", "#C475FD", "#4467A3", "#BD8233", "#AE3030", "#2ABCCD", "#954477", "#99B314")
+"""The Imprint palette in canonical order (core/palette.py `IMPRINT`; a test pins the two)."""
+PALETTE_NAMES = frozenset({"IMPRINT", "IMPRINT_PALETTE"})
+CRITICAL_VALUES = frozenset({1.645, 1.96, 2.326, 2.576, 3.291})
+"""Statistical critical values: data-independent constants in a computation, never sample coordinates."""
+NEUTRAL_VALUES = frozenset({-1.0, 0.0, 1.0})
+FIXED_DOMAINS = ((0.0, 1.0, 0.2), (-1.0, 1.0, 0.2), (0.0, 100.0, 0.1), (0.0, 360.0, 0.1))
+"""Fixed domains as `(low, high, headroom)`: values span one when they reach both bounds within the headroom,
+a share of the domain's width (`set_ylim(-0.15, 1.02)`, `set_ylim(0, 105)`). Unit domains get more headroom:
+a degree or percentage axis padded by more than a tenth is a data range that happens to start near 0."""
+PADDING = 1.5
+"""A literal bound this small beside a computed one is padding (`set_xlim(-0.5, n - 0.5)`), not a coordinate."""
+MIN_COUNT = 3
+"""Counts below this are too common (a pair, a single panel) to tie a literal to the sample."""
+RESOLUTION_COUNT = 50
+"""A `linspace` of this many points or more is a curve's resolution, not a count of the sample."""
+PROSE_WORDS = frozenset(
+    {"total", "other", "others", "all", "none", "mean", "median", "average", "yes", "no", "true", "false"}
+)
+"""Sample values that read as prose ("Total", "Other"): a label equal to one is not tied to the sample."""
+STYLE_WORDS = frozenset(
+    {
+        "center",
+        "centre",
+        "left",
+        "right",
+        "top",
+        "bottom",
+        "middle",
+        "baseline",
+        "none",
+        "auto",
+        "solid",
+        "dash",
+        "dot",
+        "longdash",
+        "dashed",
+        "dotted",
+        "dashdot",
+        "bold",
+        "normal",
+        "italic",
+        "black",
+        "white",
+        "gray",
+        "grey",
+        "red",
+        "green",
+        "blue",
+    }
+)
+"""Alignment, line-style and color words: a block string equal to one configures the chart, not the sample."""
+_PROPERTY_KEY = re.compile(r"^[a-z_][a-z0-9_]*$")
+"""A dict key below the block written like a property name (`{"size": 7}`), not a sample value."""
+
+LIBRARIES = ("matplotlib", "seaborn", "plotly", "altair", "plotnine", "bokeh", "pygal", "letsplot")
+PLOT_MODULES = (
+    "matplotlib",
+    "seaborn",
+    "plotly",
+    "altair",
+    "plotnine",
+    "bokeh",
+    "pygal",
+    "lets_plot",
+    "mpl_toolkits",
+    "squarify",
+    "pywaffle",
+)
+DATA_HELPERS = (
+    "seaborn.load_dataset",
+    "plotly.express.data.",
+    "plotly.data.",
+    "bokeh.sampledata.",
+    "vega_datasets.",
+    "matplotlib.dates.date2num",
+    "matplotlib.dates.num2date",
+    "matplotlib.dates.datestr2num",
+)
+"""Plotting-library calls that produce data, allowed in the block (a prefix ends with a dot)."""
+_MATPLOTLIB_SETUP = (
+    "matplotlib.use",
+    "matplotlib.pyplot.style.use",
+    "matplotlib.style.use",
+    "matplotlib.pyplot.rcParams.update",
+    "matplotlib.rcParams.update",
+    "matplotlib.pyplot.rc",
+    "matplotlib.rc",
+    "matplotlib.pyplot.switch_backend",
+    "matplotlib.font_manager.fontManager.addfont",
+)
+SETUP_CALLS: dict[str, tuple[str, ...]] = {
+    "matplotlib": _MATPLOTLIB_SETUP,
+    "seaborn": (
+        *_MATPLOTLIB_SETUP,
+        "seaborn.set_theme",
+        "seaborn.set_style",
+        "seaborn.set_context",
+        "seaborn.set_palette",
+        "seaborn.set",
+    ),
+    "plotly": ("matplotlib.use", "plotly.io.templates.default.update"),
+    "altair": (
+        "matplotlib.use",
+        "altair.data_transformers.disable_max_rows",
+        "altair.data_transformers.enable",
+        "altair.themes.enable",
+        "altair.themes.register",
+        "altair.theme.enable",
+        "altair.theme.register",
+        "altair.renderers.enable",
+    ),
+    "plotnine": ("matplotlib.use", "plotnine.theme_set", "plotnine.options.set_option"),
+    "bokeh": ("matplotlib.use", "bokeh.io.output_file", "bokeh.plotting.output_file", "bokeh.io.curdoc"),
+    "pygal": ("matplotlib.use",),
+    "letsplot": ("matplotlib.use", "lets_plot.LetsPlot.setup_html", "lets_plot.LetsPlot.set_theme"),
+}
+"""Per library, the calls the head may make before the block (resolved through the imports)."""
+FIGURE_FACTORIES = frozenset(
+    {
+        "matplotlib.pyplot.subplots",
+        "matplotlib.pyplot.figure",
+        "matplotlib.pyplot.subplot",
+        "matplotlib.pyplot.axes",
+        "matplotlib.pyplot.subplot_mosaic",
+        "matplotlib.pyplot.subplot2grid",
+        "plotly.graph_objects.Figure",
+        "plotly.subplots.make_subplots",
+        "altair.Chart",
+        "altair.layer",
+        "altair.hconcat",
+        "altair.vconcat",
+        "altair.concat",
+        "altair.LayerChart",
+        "plotnine.ggplot",
+        "lets_plot.ggplot",
+        "lets_plot.gggrid",
+        "lets_plot.ggbunch",
+        "bokeh.plotting.figure",
+        "bokeh.layouts.gridplot",
+        "bokeh.layouts.column",
+        "bokeh.layouts.row",
+        "seaborn.FacetGrid",
+        "seaborn.PairGrid",
+        "seaborn.JointGrid",
+        "seaborn.catplot",
+        "seaborn.relplot",
+        "seaborn.displot",
+        "seaborn.lmplot",
+        "seaborn.jointplot",
+        "seaborn.pairplot",
+        "seaborn.clustermap",
+    }
+)
+_PYGAL_CHART = re.compile(r"^pygal\.[A-Z]\w*$")
+_PLOTLY_EXPRESS = "plotly.express."
+OUTPUT_CALLS = frozenset(
+    {
+        "savefig",
+        "save",
+        "ggsave",
+        "write_image",
+        "write_html",
+        "export_png",
+        "export_svg",
+        "render_to_png",
+        "render_to_file",
+        "output_file",
+        "show",
+    }
+)
+"""Output calls: every literal inside one is ignored (file names, dpi, scale)."""
+STYLE_KEYWORDS = frozenset(
+    {
+        "ha",
+        "va",
+        "horizontalalignment",
+        "verticalalignment",
+        "multialignment",
+        "marker",
+        "linestyle",
+        "ls",
+        "drawstyle",
+        "loc",
+        "fontweight",
+        "weight",
+        "fontstyle",
+        "style",
+        "family",
+        "fontfamily",
+        "fontname",
+        "font",
+        "cmap",
+        "colormap",
+        "palette",
+        "textcoords",
+        "xycoords",
+        "coords",
+        "how",
+        "join",
+        "kind",
+        "orient",
+        "orientation",
+        "align",
+        "anchor",
+        "baseline",
+        "rotation_mode",
+        "capstyle",
+        "joinstyle",
+        "solid_capstyle",
+        "dash_capstyle",
+        "hatch",
+        "interpolation",
+        "shading",
+        "aspect",
+        "bbox_inches",
+        "format",
+        "fmt",
+        "mode",
+        "barmode",
+        "template",
+        "stat",
+        "method",
+        "position",
+        "legend_position",
+        "units",
+        "x_units",
+        "y_units",
+        "xref",
+        "yref",
+        "axref",
+        "ayref",
+        "textposition",
+        "textinfo",
+        "hoverinfo",
+        "hovermode",
+        "legend",
+        "errorbar",
+        "estimator",
+        "element",
+        "multiple",
+        "inner",
+        "histtype",
+        "where",
+        "type",
+        "side",
+        "location",
+        "dtype",
+        "errors",
+        "freq",
+        "unit",
+        "nonpositive",
+        "rc",
+        "edgecolor",
+        "facecolor",
+        "linecolor",
+        "markeredgecolor",
+        "markerfacecolor",
+        "fill_color",
+        "line_color",
+        "text_color",
+        "background",
+        "background_fill_color",
+        "border_fill_color",
+        "fontFamily",
+        "labelFont",
+        "titleFont",
+        "symbolType",
+        "interpolate",
+        "strokeDash",
+        "shape",
+        "line_dash",
+        "dash",
+        "symbol",
+        "toolbar_location",
+        "sizing_mode",
+        "axis",
+        "which",
+    }
+)
+"""Keywords whose string values style the chart; a sample value never lives there."""
+GENERIC_DATA_KEYWORDS = frozenset(
+    {
+        "range",
+        "range_x",
+        "range_y",
+        "range_z",
+        "range_r",
+        "range_theta",
+        "range_color",
+        "limits",
+        "breaks",
+        "tickvals",
+        "xintercept",
+        "yintercept",
+        "x_range",
+        "y_range",
+        "vmin",
+        "vmax",
+        "vcenter",
+        "zmin",
+        "zmax",
+        "zmid",
+        "clim",
+        "xlim",
+        "ylim",
+        "zlim",
+        "color_continuous_midpoint",
+    }
+)
+"""Keywords that hold data coordinates in any call or dict (plotly ranges, plotnine limits, color bounds)."""
+_AXIS_DATA_KEYWORD = re.compile(r"^[xyz]axis\d*_(?:range|tickvals)$")
+LIMIT_METHODS = frozenset(
+    {
+        "set_xlim",
+        "set_ylim",
+        "set_zlim",
+        "xlim",
+        "ylim",
+        "set_xticks",
+        "set_yticks",
+        "set_zticks",
+        "xticks",
+        "yticks",
+        "set_xbound",
+        "set_ybound",
+        "set_rlim",
+        "set_rmin",
+        "set_rmax",
+        "set_rticks",
+        "set_thetalim",
+        "axis",
+        "set_clim",
+        "clim",
+    }
+)
+"""Calls whose positional arguments are data coordinates (matplotlib, and plotnine and lets-plot `xlim`/`ylim`)."""
+LIMIT_KEYWORDS = frozenset(
+    {"left", "right", "bottom", "top", "xmin", "xmax", "ymin", "ymax", "zmin", "zmax", "ticks", "vmin", "vmax"}
+)
+"""The keywords of a `LIMIT_METHODS` call that hold bounds or tick positions; any other keyword styles."""
+DATA_CALL_ARGS: dict[str, tuple[tuple[int, ...], tuple[str, ...]]] = {
+    "text": ((0, 1), ("x", "y")),
+    "axhline": ((0,), ("y",)),
+    "axvline": ((0,), ("x",)),
+    "axhspan": ((0, 1), ("ymin", "ymax")),
+    "axvspan": ((0, 1), ("xmin", "xmax")),
+    "hlines": ((0, 1, 2), ("y", "xmin", "xmax")),
+    "vlines": ((0, 1, 2), ("x", "ymin", "ymax")),
+    "add_hline": ((0,), ("y",)),
+    "add_vline": ((0,), ("x",)),
+    "add_hrect": ((0, 1), ("y0", "y1")),
+    "add_vrect": ((0, 1), ("x0", "x1")),
+    "add_annotation": ((), ("x", "y")),
+    "add_shape": ((), ("x0", "x1", "y0", "y1")),
+    "annotate": ((), ("x", "y", "xmin", "xmax", "ymin", "ymax", "xend", "yend")),
+    "expand_limits": ((), ("x", "y")),
+    "Range1d": ((0, 1), ("start", "end")),
+    "Span": ((), ("location",)),
+    "BoxAnnotation": ((), ("top", "bottom", "left", "right")),
+    "Label": ((), ("x", "y")),
+    "FixedTicker": ((), ("ticks",)),
+    "Scale": ((), ("domain",)),
+    "Axis": ((), ("values",)),
+}
+"""Per call name, the positional indexes and keywords that hold data coordinates."""
+_GEOM_COORDINATES = ("x", "y", "xend", "yend", "xmin", "xmax", "ymin", "ymax")
+CONTOUR_CALLS = frozenset({"contour", "contourf", "tricontour", "tricontourf"})
+NORM_CALLS: dict[str, tuple[tuple[int, ...], frozenset[str]]] = {
+    "Normalize": ((0, 1), frozenset({"vmin", "vmax"})),
+    "LogNorm": ((0, 1), frozenset({"vmin", "vmax"})),
+    "TwoSlopeNorm": ((0, 1, 2), frozenset({"vcenter", "vmin", "vmax"})),
+    "CenteredNorm": ((0, 1), frozenset({"vcenter", "halfrange"})),
+    "BoundaryNorm": ((0,), frozenset({"boundaries"})),
+    "PowerNorm": ((1, 2), frozenset({"vmin", "vmax"})),
+    "SymLogNorm": ((2, 3), frozenset({"vmin", "vmax"})),
+}
+DATA_ATTRIBUTES = frozenset({"start", "end", "bounds", "ticker", "y_labels", "x_labels", "range"})
+"""Attributes whose literal assignment pins a data coordinate (bokeh ranges and tickers, pygal labels)."""
+PAPER_REFS = ("paper", "domain", "screen", "axes fraction", "figure fraction", "offset points", "offset pixels")
+RANGE_CALLS = frozenset({"range", "arange", "linspace"})
+DATE_CALLS = frozenset({"Timestamp", "datetime", "datetime64", "date", "to_datetime"})
+_DATE_TEXT = re.compile(r"^\d{4}-\d{2}(?:-\d{2})?(?:[ T]\d{2}:\d{2}(?::\d{2})?)?$")
+RANDOM_SIZE_POSITIONS: dict[str, int | None] = {
+    "randn": 0,
+    "rand": 0,
+    "random": 0,
+    "standard_normal": 0,
+    "choice": 1,
+    "poisson": 1,
+    "exponential": 1,
+    "chisquare": 1,
+    "geometric": 1,
+    "standard_t": 1,
+    "weibull": 1,
+    "pareto": 1,
+    "normal": 2,
+    "uniform": 2,
+    "randint": 2,
+    "integers": 2,
+    "binomial": 2,
+    "lognormal": 2,
+    "gamma": 2,
+    "beta": 2,
+    "laplace": 2,
+    "logistic": 2,
+    "gumbel": 2,
+    "vonmises": 2,
+    "multivariate_normal": 2,
+    "triangular": 3,
+    "rvs": None,
+}
+"""Random draws and the position of their size argument (None: `size=` only); the size is a count of the sample."""
+FRAME_CALLS = frozenset({"DataFrame", "read_csv", "load_dataset", "concat", "merge", "melt", "pivot", "pivot_table"})
+"""Calls whose result is a DataFrame: a string subscript of the name they bind reads a column."""
+COMPARISON_METHODS = frozenset({"eq", "ne", "isin"})
+"""Selections of a value: equality and membership. An inequality (`df[RSI] >= 70`, `if w > 7`) applies a
+threshold, which holds for any data (a precision sample of 2026-10-23 found 11 of 11 such hits false)."""
+SELECTION_OPS = (ast.Eq, ast.NotEq, ast.In, ast.NotIn)
+MIN_SAMPLE_CHARS = 2
+"""A one-character sample value ("C", "M") matches too much unrelated code (an SVG path command, a unit)."""
+_STATISTIC = re.compile(r"(?<![\w.])(?:r|R|R²|R\^2|ρ|τ|p|n|μ|σ)\s*(?:=|≈|~|<|>|≤|≥)\s*[-−+]?\.?\d")
+_HEX = re.compile(r"^#[0-9A-Fa-f]{3,8}$")
+_MARKER_TAIL = r"(?:\s*:.*|\s+[-–—].*)?\s*$"
+DATA_MARKER = re.compile(r"^# Data" + _MARKER_TAIL)
+PLOT_MARKER = re.compile(r"^# Plot" + _MARKER_TAIL)
+CONSTANTS_MARKER = re.compile(r"^# Constants" + _MARKER_TAIL)
+ROLE_COMMENT = re.compile(r"^#\s*role\s*:\s*(?P<rest>.*?)\s*$")
+ROLE_NAME = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+EXTRA_ROLE = "extra"
+_ALTAIR_SUFFIX = re.compile(r":[QNOTG]$")
+_ALTAIR_ESCAPE = re.compile(r"\\([.\[\]:\\])")
+_SNIPPET_CHARS = 60
+_MAX_LISTED_LINES = 5
+_BUILTIN_NAMES = frozenset(dir(builtins))
+
+
+@dataclass(frozen=True)
+class RuleClass:
+    """One class of finding: its rule number, the target its defect line names, and whether it is advisory."""
+
+    id: str
+    rule: int
+    target: str
+    advisory: bool = False
+
+
+RULE_CLASSES: dict[str, RuleClass] = {
+    rule.id: rule
+    for rule in (
+        RuleClass(
+            "layout",
+            1,
+            "one block between column-0 # Data and # Plot markers that ends by binding df, with no plotting, styling "
+            "or theme token inside and no plotting call above it",
+        ),
+        RuleClass(
+            "columns",
+            2,
+            "one string constant per required column role above the Data block, each with a trailing "
+            "# role: <role> comment naming a spec role",
+        ),
+        RuleClass("interface", 3, "read only df below the Data block and derive everything else from it"),
+        RuleClass("column-literal", 4, "use the column constant instead of the column name"),
+        # Advisory: 76 of 90 over three samples; the misses are domain vocabulary the block also spells out
+        # (ECG lead names, Venn zones, spectral classes, the 100 % saturation curve).
+        RuleClass("sample-literal", 4, "derive the value from df instead of typing a sample value", advisory=True),
+        # Advisory after the precision samples of 2026-10-23 (PR body): data-coordinate 20 of 30 (annotation
+        # positions in layout units, domain thresholds such as a 95 % variance line, padding), statistic-text
+        # 11 of 30 (thresholds and domain facts: "p < 0.05", "r ≈ 3.57"), count-literal 22 of 30 (domain
+        # grids: a 5 x 5 risk matrix, 7 weekdays, 4 ECG rows).
+        RuleClass(
+            "data-coordinate",
+            4,
+            "derive limits, ticks, reference lines and text positions from df, or name the value in # Constants",
+            advisory=True,
+        ),
+        RuleClass("statistic-text", 4, "compute the statistic from df in an f-string", advisory=True),
+        RuleClass(
+            "df-comparison",
+            4,
+            "select by a rule over df (idxmax, the latest row) or compare with a # Constants threshold",
+        ),
+        RuleClass("count-literal", 4, "count from df (len(df), nunique) instead of typing the count", advisory=True),
+        RuleClass(
+            "palette",
+            5,
+            "list all eight IMPRINT positions in canonical order and look colors up per category "
+            "(IMPRINT[i], dict(zip(groups, IMPRINT)))",
+        ),
+        RuleClass("constants", 6, "keep only values that hold for any data in # Constants", advisory=True),
+    )
+}
+RULE_ORDER = tuple(RULE_CLASSES)
+
+
+@dataclass(frozen=True)
+class Finding:
+    """One violation: its rule class, its line (None for the file as a whole), what was seen and why."""
+
+    cls: str
+    line: int | None
+    observed: str
+    cause: str
+
+    @property
+    def rule(self) -> int:
+        return RULE_CLASSES[self.cls].rule
+
+    @property
+    def advisory(self) -> bool:
+        return RULE_CLASSES[self.cls].advisory
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "rule": self.rule,
+            "class": self.cls,
+            "line": self.line,
+            "observed": self.observed,
+            "cause": self.cause,
+            "advisory": self.advisory,
+        }
+
+
+@dataclass
+class Record:
+    """The checker's result for one source (`to_dict` is the stored form)."""
+
+    shape: Shape
+    color_role: str | None
+    block: tuple[int, int] | None
+    constants: dict[str, str]
+    findings: list[Finding] = field(default_factory=list)
+    version: int = CHECKER_VERSION
+
+    @property
+    def status(self) -> str:
+        """`pass`, `fail` (a finding that is not advisory) or `excluded` (a map spec, never checked)."""
+        if self.shape == "excluded":
+            return "excluded"
+        return "fail" if any(not finding.advisory for finding in self.findings) else "pass"
+
+    def classes(self) -> list[str]:
+        """The rule classes with a finding, in `RULE_ORDER`."""
+        found = {finding.cls for finding in self.findings}
+        return [cls for cls in RULE_ORDER if cls in found]
+
+    def defect_lines(self) -> list[str]:
+        """At most one defect line per rule class (`core.defects.DEFECT_RE` reads each)."""
+        lines: list[str] = []
+        for cls in self.classes():
+            findings = sorted(
+                (finding for finding in self.findings if finding.cls == cls), key=lambda finding: finding.line or 0
+            )
+            lines.append(_defect_line(cls, findings))
+        return lines
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "version": self.version,
+            "status": self.status,
+            "shape": self.shape,
+            "color_role": self.color_role,
+            "block": None if self.block is None else {"start": self.block[0], "end": self.block[1]},
+            "constants": dict(self.constants),
+            "findings": [finding.to_dict() for finding in self.findings],
+            "lines": self.defect_lines(),
+        }
+
+
+def _clause(text: str) -> str:
+    return " ".join(str(text).replace(DEFECT_ARROW, "->").split()).rstrip(". ")
+
+
+def _defect_line(cls: str, findings: Sequence[Finding]) -> str:
+    """`CQ-01 (code): line N <observed>[, and K more at lines ...] → <target>. Likely cause: <cause>.`"""
+    first = findings[0]
+    observed = f"line {first.line} {first.observed}" if first.line is not None else first.observed
+    rest = [finding.line for finding in findings[1:] if finding.line is not None]
+    more = len(findings) - 1
+    if more:
+        shown = ", ".join(str(line) for line in rest[:_MAX_LISTED_LINES])
+        tail = ", …" if len(rest) > _MAX_LISTED_LINES else ""
+        observed += f"; {more} more" + (f" at lines {shown}{tail}" if shown else "")
+    if RULE_CLASSES[cls].advisory:
+        observed = f"(advisory) {observed}"
+    line = f"{DEFECT_ID} ({CODE_RENDER}): {_clause(observed)} {DEFECT_ARROW} {_clause(RULE_CLASSES[cls].target)}."
+    cause = _clause(first.cause)
+    return f"{line} Likely cause: {cause}." if cause else line
+
+
+# --- source model ------------------------------------------------------------------------------
+
+
+@dataclass
+class _Constant:
+    name: str
+    role: str
+    value: ast.expr
+    line: int
+
+
+def _assignment(node: ast.AST) -> tuple[list[ast.expr], ast.expr] | None:
+    """The targets and the value of `x = ...` or of an annotated `x: str = ...`; None for anything else."""
+    if isinstance(node, ast.Assign):
+        return list(node.targets), node.value
+    if isinstance(node, ast.AnnAssign) and node.value is not None:
+        return [node.target], node.value
+    return None
+
+
+def _single_name(node: ast.AST) -> tuple[str, ast.expr] | None:
+    """The name and value of a single-name assignment, annotated or not."""
+    assigned = _assignment(node)
+    if assigned is None or len(assigned[0]) != 1 or not isinstance(assigned[0][0], ast.Name):
+        return None
+    return assigned[0][0].id, assigned[1]
+
+
+@dataclass
+class _Sample:
+    """What the block defines: its values, its record fields, its column names, its data numbers and its counts.
+
+    `strings` are values (list elements, assigned or compared strings); `fields` are the keys of the block's
+    dicts that build no DataFrame and the string subscripts of its records (`node["id"]`), which can be a
+    category map's keys ("Electronics") or a record's field names ("id", "color").
+    """
+
+    strings: set[str] = field(default_factory=set)
+    fields: set[str] = field(default_factory=set)
+    columns: set[str] = field(default_factory=set)
+    numbers: set[float] = field(default_factory=set)
+    counts: set[int] = field(default_factory=set)
+
+
+class _Source:
+    """A parsed source with its comments, markers, imports and zones."""
+
+    def __init__(self, source: str, tree: ast.Module, library: str | None) -> None:
+        self.text = source
+        self.tree = tree
+        self.library = library
+        self.comments = _comments(source)
+        self.markers = {
+            kind: [line for line, col, text in self.comments if col == 0 and pattern.match(text)]
+            for kind, pattern in (("data", DATA_MARKER), ("plot", PLOT_MARKER), ("constants", CONSTANTS_MARKER))
+        }
+        self.aliases, self.star_modules = _imports(tree)
+        self.parents: dict[ast.AST, ast.AST] = {}
+        for node in ast.walk(tree):
+            for child in ast.iter_child_nodes(node):
+                self.parents[child] = node
+        self.defined = _bound_names(tree)
+        data = self.markers["data"]
+        plot = [line for line in self.markers["plot"] if data and line > data[0]]
+        self.block: tuple[int, int] | None = (data[0], plot[0]) if data and plot else None
+        self.figures = self._figure_names()
+
+    # zones ---------------------------------------------------------------------------------
+
+    def head(self) -> list[ast.stmt]:
+        if not self.markers["data"]:
+            return []
+        start = self.markers["data"][0]
+        return [stmt for stmt in self.tree.body if stmt.lineno < start]
+
+    def block_body(self) -> list[ast.stmt]:
+        if self.block is None:
+            return []
+        start, end = self.block
+        return [stmt for stmt in self.tree.body if start < stmt.lineno < end]
+
+    def below(self) -> list[ast.stmt]:
+        if self.block is None:
+            return list(self.tree.body)
+        return [stmt for stmt in self.tree.body if stmt.lineno > self.block[1]]
+
+    def constants_zone(self) -> list[ast.stmt]:
+        markers = self.markers["constants"]
+        if not markers or not self.markers["data"]:
+            return []
+        start, end = markers[0], self.markers["data"][0]
+        return [stmt for stmt in self.tree.body if start < stmt.lineno < end]
+
+    # names and calls -----------------------------------------------------------------------
+
+    def resolve(self, dotted: str) -> str:
+        """`plt.subplots` -> `matplotlib.pyplot.subplots`; a bare name from a star import gets its module."""
+        head, _, rest = dotted.partition(".")
+        if head in self.aliases:
+            base = self.aliases[head]
+        elif head not in self.defined and head not in _BUILTIN_NAMES and self.star_modules:
+            base = f"{self.star_modules[0]}.{head}"
+        else:
+            base = head
+        return f"{base}.{rest}" if rest else base
+
+    def call_root(self, call: ast.Call) -> tuple[str | None, str]:
+        """The base name of a call chain (`alt` in `alt.Chart(df).mark_bar()`) and the innermost call's resolved name."""
+        func: ast.expr = call.func
+        inner = call
+        while True:
+            if isinstance(func, ast.Attribute):
+                func = func.value
+            elif isinstance(func, ast.Call):
+                inner = func
+                func = func.func
+            elif isinstance(func, ast.Subscript):
+                func = func.value
+            else:
+                break
+        root = func.id if isinstance(func, ast.Name) else None
+        dotted = _dotted(inner.func)
+        return root, self.resolve(dotted) if dotted else ""
+
+    def is_plot_module(self, resolved: str) -> bool:
+        return resolved.split(".", 1)[0] in PLOT_MODULES or resolved.startswith("networkx.draw")
+
+    def is_figure_factory(self, resolved: str) -> bool:
+        return (
+            resolved in FIGURE_FACTORIES
+            or (
+                resolved.startswith(_PLOTLY_EXPRESS)
+                and not resolved.startswith(("plotly.express.data", "plotly.express.colors"))
+            )
+            or (bool(_PYGAL_CHART.match(resolved)) and resolved != "pygal.Config")
+        )
+
+    def _figure_names(self) -> set[str]:
+        """Names bound to a figure, axes or chart: by a figure factory or a call on another figure name."""
+        names: set[str] = set()
+        for stmt in self.tree.body:
+            for node in ast.walk(stmt):
+                assigned = _assignment(node)
+                if assigned is None or not isinstance(assigned[1], ast.Call):
+                    continue
+                root, resolved = self.call_root(assigned[1])
+                if self.is_figure_factory(resolved) or (root is not None and root in names):
+                    for target in assigned[0]:
+                        names.update(_target_names(target))
+        return names
+
+    def is_plotting_call(self, call: ast.Call) -> bool:
+        """A call into a plotting library (other than a data helper) or on a figure, axes or chart."""
+        root, resolved = self.call_root(call)
+        if root is not None and root in self.figures:
+            return True
+        if not self.is_plot_module(resolved):
+            return False
+        return not any(
+            resolved.startswith(helper) if helper.endswith(".") else resolved == helper for helper in DATA_HELPERS
+        )
+
+    def setup_calls(self) -> set[str]:
+        if self.library in SETUP_CALLS:
+            return set(SETUP_CALLS[self.library])
+        return {call for calls in SETUP_CALLS.values() for call in calls}
+
+    def snippet(self, node: ast.AST) -> str:
+        return _snippet(ast.get_source_segment(self.text, node) or ast.unparse(node))
+
+    def inside(self, node: ast.AST, kinds: tuple[type, ...]) -> ast.AST | None:
+        current = self.parents.get(node)
+        while current is not None:
+            if isinstance(current, kinds):
+                return current
+            current = self.parents.get(current)
+        return None
+
+
+def _comments(source: str) -> list[tuple[int, int, str]]:
+    """`(line, column, text)` of every comment token."""
+    out: list[tuple[int, int, str]] = []
+    try:
+        for token in tokenize.generate_tokens(io.StringIO(source).readline):
+            if token.type == tokenize.COMMENT:
+                out.append((token.start[0], token.start[1], token.string))
+    except (tokenize.TokenError, IndentationError, SyntaxError):
+        for number, line in enumerate(source.splitlines(), start=1):
+            stripped = line.lstrip()
+            if stripped.startswith("#"):
+                out.append((number, len(line) - len(stripped), stripped))
+    return out
+
+
+def _imports(tree: ast.Module) -> tuple[dict[str, str], list[str]]:
+    """Local name -> imported module or object, and the modules imported with `*`."""
+    aliases: dict[str, str] = {}
+    stars: list[str] = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                if alias.asname:
+                    aliases[alias.asname] = alias.name
+                else:
+                    top = alias.name.split(".")[0]
+                    aliases[top] = top
+        elif isinstance(node, ast.ImportFrom) and node.module and node.level == 0:
+            for alias in node.names:
+                if alias.name == "*":
+                    stars.append(node.module)
+                else:
+                    aliases[alias.asname or alias.name] = f"{node.module}.{alias.name}"
+    plot_stars = [module for module in stars if module.split(".")[0] in PLOT_MODULES]
+    return aliases, plot_stars
+
+
+def _bound_names(tree: ast.Module) -> set[str]:
+    names: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Name) and isinstance(node.ctx, ast.Store):
+            names.add(node.id)
+        elif isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef):
+            names.add(node.name)
+        elif isinstance(node, ast.arg):
+            names.add(node.arg)
+        elif isinstance(node, ast.Import | ast.ImportFrom):
+            for alias in node.names:
+                if alias.name != "*":
+                    names.add((alias.asname or alias.name).split(".")[0])
+    return names
+
+
+def _dotted(node: ast.expr) -> str | None:
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        base = _dotted(node.value)
+        return f"{base}.{node.attr}" if base else None
+    return None
+
+
+def _call_name(call: ast.Call) -> str | None:
+    """The called function's last name: `set_xlim` for `ax.set_xlim(...)`, `range` for `range(...)`."""
+    if isinstance(call.func, ast.Attribute):
+        return call.func.attr
+    if isinstance(call.func, ast.Name):
+        return call.func.id
+    return None
+
+
+def _target_names(target: ast.expr) -> set[str]:
+    if isinstance(target, ast.Name):
+        return {target.id}
+    if isinstance(target, ast.Tuple | ast.List):
+        return {name for element in target.elts for name in _target_names(element)}
+    if isinstance(target, ast.Starred):
+        return _target_names(target.value)
+    return set()
+
+
+def _snippet(text: str) -> str:
+    text = " ".join(text.split())
+    return text if len(text) <= _SNIPPET_CHARS else text[: _SNIPPET_CHARS - 1] + "…"
+
+
+def _names_in(node: ast.AST) -> set[str]:
+    return {child.id for child in ast.walk(node) if isinstance(child, ast.Name)}
+
+
+# --- literal values ------------------------------------------------------------------------------
+
+
+def _number(node: ast.expr) -> float | None:
+    """The value of a numeric literal, a signed one, or arithmetic on literals."""
+    if isinstance(node, ast.Constant):
+        value = node.value
+        return float(value) if isinstance(value, int | float) and not isinstance(value, bool) else None
+    if isinstance(node, ast.UnaryOp) and isinstance(node.op, ast.USub | ast.UAdd):
+        operand = _number(node.operand)
+        if operand is None:
+            return None
+        return -operand if isinstance(node.op, ast.USub) else operand
+    if isinstance(node, ast.BinOp) and isinstance(node.op, ast.Add | ast.Sub | ast.Mult | ast.Div):
+        left, right = _number(node.left), _number(node.right)
+        if left is None or right is None:
+            return None
+        if isinstance(node.op, ast.Add):
+            return left + right
+        if isinstance(node.op, ast.Sub):
+            return left - right
+        if isinstance(node.op, ast.Mult):
+            return left * right
+        return left / right if right else None
+    return None
+
+
+def _literal_values(node: ast.expr) -> list[float | str]:
+    """The literal values `node` places on an axis; a literal date counts as `"date"`."""
+    number = _number(node)
+    if number is not None:
+        return [number]
+    if isinstance(node, ast.Constant) and isinstance(node.value, str) and _DATE_TEXT.match(node.value):
+        return ["date"]
+    if isinstance(node, ast.List | ast.Tuple):
+        return [value for element in node.elts for value in _literal_values(element)]
+    if isinstance(node, ast.Call):
+        name = _call_name(node) or ""
+        if name in RANGE_CALLS and node.args:
+            numbers = [_number(arg) for arg in node.args]
+            if all(value is not None for value in numbers):
+                return [value for value in numbers if value is not None]
+        if name in DATE_CALLS and node.args and all(isinstance(arg, ast.Constant) for arg in node.args):
+            return ["date"]
+    return []
+
+
+def _exempt(values: Sequence[float | str]) -> bool:
+    """Values that fit any data: none at all, only neutral or critical values, or a span of a fixed domain."""
+    if any(value == "date" for value in values):
+        return False
+    numbers = [float(value) for value in values if not isinstance(value, str)]
+    if not numbers:
+        return True
+    if all(value in NEUTRAL_VALUES or abs(value) in CRITICAL_VALUES for value in numbers):
+        return True
+    low, high = min(numbers), max(numbers)
+    for lo, hi, headroom in FIXED_DOMAINS:
+        pad = headroom * (hi - lo)
+        if lo - pad <= low <= lo + pad and hi - pad <= high <= hi + pad:
+            return True
+    return False
+
+
+def _count(node: ast.expr) -> int | None:
+    value = _number(node)
+    return int(value) if value is not None and value == int(value) else None
+
+
+def _range_length(call: ast.Call) -> int | None:
+    """The length of `range`/`arange` of literal ints, or a `linspace`'s point count."""
+    name = _call_name(call)
+    if name == "linspace":
+        num = call.args[2] if len(call.args) > 2 else next((kw.value for kw in call.keywords if kw.arg == "num"), None)
+        return _count(num) if num is not None else None
+    if name not in ("range", "arange"):
+        return None
+    ints = [_count(arg) for arg in call.args]
+    if not ints or any(value is None for value in ints):
+        return None
+    start, stop, step = 0, 0, 1
+    if len(ints) == 1:
+        stop = ints[0] or 0
+    else:
+        start, stop = ints[0] or 0, ints[1] or 0
+        step = (ints[2] or 1) if len(ints) > 2 else 1
+    return max(0, -(-(stop - start) // step)) if step else None
+
+
+# --- the checks --------------------------------------------------------------------------------
+
+
+def check_source(source: str, roles: Sequence[DataRole], shape: Shape, *, library: str | None = None) -> Record:
+    """Check one Python implementation against its spec's roles and data shape."""
+    role = color_role(roles)
+    record = Record(shape=shape, color_role=role.name if role else None, block=None, constants={})
+    if shape == "excluded":
+        return record
+    try:
+        tree = ast.parse(source)
+    except SyntaxError as exc:
+        record.findings.append(Finding("layout", exc.lineno, "does not parse", f"SyntaxError: {exc.msg}"))
+        return record
+    src = _Source(source, tree, library)
+    record.block = src.block
+    findings = record.findings
+    constants = _column_constants(src)
+    record.constants = {constant.role: constant.name for constant in constants if constant.role != EXTRA_ROLE}
+
+    findings.extend(_check_layout(src, shape))
+    findings.extend(_check_columns(src, constants, roles, shape))
+    sample = _sample(src, constants) if src.block is not None else None
+    if sample is not None and shape != "generated":
+        findings.extend(_check_interface(src, shape))
+    findings.extend(_check_literals(src, sample))
+    findings.extend(_check_palette(src, role))
+    if sample is not None:
+        findings.extend(_check_constants_zone(src, sample))
+    return record
+
+
+def _check_layout(src: _Source, shape: Shape) -> list[Finding]:
+    found: list[Finding] = []
+    data = src.markers["data"]
+    if not data:
+        found.append(
+            Finding(
+                "layout",
+                None,
+                "the file has no column-0 # Data marker",
+                "the data generation is not marked as one block",
+            )
+        )
+    elif src.block is None:
+        found.append(
+            Finding(
+                "layout",
+                data[0],
+                "opens the Data block with no column-0 # Plot marker after it",
+                "the plot code is not separated from the data generation",
+            )
+        )
+    if len(data) > 1:
+        found.append(
+            Finding(
+                "layout",
+                data[1],
+                f"opens a second # Data block ({len(data)} markers)",
+                "the data generation is split over several blocks",
+            )
+        )
+    found.extend(_check_head(src))
+    if src.block is None:
+        return found
+    body = src.block_body()
+    if not body:
+        found.append(Finding("layout", src.block[0], "opens an empty Data block", "nothing between the markers"))
+        return found
+    tokens = _theme_tokens(src)
+    for stmt in body:
+        for node in ast.walk(stmt):
+            if isinstance(node, ast.Call) and src.is_plotting_call(node):
+                found.append(
+                    Finding(
+                        "layout",
+                        node.lineno,
+                        f"calls `{src.snippet(node.func)}` inside the Data block",
+                        "a plotting, styling or setup call in the data generation",
+                    )
+                )
+                break
+            if isinstance(node, ast.Name) and isinstance(node.ctx, ast.Load) and node.id in tokens:
+                found.append(
+                    Finding(
+                        "layout",
+                        node.lineno,
+                        f"reads the theme token `{node.id}` inside the Data block",
+                        "styling in the data generation",
+                    )
+                )
+                break
+    if shape != "generated":
+        last = body[-1]
+        if not _binds_df(last):
+            found.append(
+                Finding(
+                    "layout",
+                    last.lineno,
+                    f"ends the Data block with `{src.snippet(last)}`, not a statement that binds df",
+                    "the block does not end in one tidy DataFrame df",
+                )
+            )
+    return found
+
+
+def _check_head(src: _Source) -> list[Finding]:
+    """Above the block: no figure created and no plotting call outside the library's setup calls."""
+    found: list[Finding] = []
+    allowed = src.setup_calls()
+    for stmt in src.head():
+        if isinstance(stmt, ast.Assign | ast.AnnAssign) and isinstance(stmt.value, ast.Call):
+            root, resolved = src.call_root(stmt.value)
+            if src.is_figure_factory(resolved) or (root is not None and root in src.figures):
+                found.append(
+                    Finding(
+                        "layout",
+                        stmt.lineno,
+                        f"creates `{src.snippet(stmt.value.func)}` above the Data block",
+                        "plot code above the data generation",
+                    )
+                )
+        elif isinstance(stmt, ast.Expr) and isinstance(stmt.value, ast.Call):
+            root, resolved = src.call_root(stmt.value)
+            dotted = _dotted(stmt.value.func)
+            full = src.resolve(dotted) if dotted else resolved
+            if full in allowed:
+                continue
+            if (root is not None and root in src.figures) or src.is_plot_module(full):
+                found.append(
+                    Finding(
+                        "layout",
+                        stmt.lineno,
+                        f"calls `{src.snippet(stmt.value.func)}` above the Data block",
+                        "a plotting call in the head that is not one of the library's setup calls",
+                    )
+                )
+    return found
+
+
+def _theme_tokens(src: _Source) -> set[str]:
+    """`THEME`, names the head derives from it, color strings and palettes."""
+    tokens = {"THEME"}
+    changed = True
+    while changed:
+        changed = False
+        for stmt in src.head():
+            assigned = _assignment(stmt)
+            if assigned is None:
+                continue
+            targets, value = assigned
+            names = {name for target in targets for name in _target_names(target)}
+            if not names or names <= tokens:
+                continue
+            hexes = any(
+                isinstance(node, ast.Constant) and isinstance(node.value, str) and _HEX.match(node.value)
+                for node in ast.walk(value)
+            )
+            if hexes or _names_in(value) & tokens:
+                tokens |= names
+                changed = True
+    return tokens
+
+
+def _binds_df(stmt: ast.stmt) -> bool:
+    """`df = ...`, a column or attribute of df set (`df["x"] = ...`), or an in-place call on df."""
+
+    def on_df(target: ast.expr) -> bool:
+        if "df" in _target_names(target):
+            return True
+        while isinstance(target, ast.Subscript | ast.Attribute):  # df["x"], df.loc[:, "x"], df.attrs
+            target = target.value
+        return isinstance(target, ast.Name) and target.id == "df"
+
+    if isinstance(stmt, ast.Assign):
+        return any(on_df(target) for target in stmt.targets)
+    if isinstance(stmt, ast.AnnAssign | ast.AugAssign):
+        return on_df(stmt.target)
+    if isinstance(stmt, ast.Expr) and isinstance(stmt.value, ast.Call):
+        func = stmt.value.func
+        return isinstance(func, ast.Attribute) and isinstance(func.value, ast.Name) and func.value.id == "df"
+    return False
+
+
+def _column_constants(src: _Source) -> list[_Constant]:
+    """Module-level single-name assignments (annotated or not) with a `# role:` comment on one of their lines."""
+    by_line: dict[int, str] = {}
+    for line, col, text in src.comments:
+        if col > 0:
+            match = ROLE_COMMENT.match(text)
+            if match:  # a further comment after the role (`# role: y  # note`) is not part of it
+                by_line[line] = match.group("rest").split("#", 1)[0].strip()
+    constants: list[_Constant] = []
+    for stmt in src.tree.body:
+        single = _single_name(stmt)
+        if single is None:
+            continue
+        end = stmt.end_lineno or stmt.lineno
+        role = next((by_line[line] for line in range(stmt.lineno, end + 1) if line in by_line), None)
+        if role is not None:
+            constants.append(_Constant(single[0], role, single[1], stmt.lineno))
+    return constants
+
+
+def _check_columns(src: _Source, constants: list[_Constant], roles: Sequence[DataRole], shape: Shape) -> list[Finding]:
+    found: list[Finding] = []
+    by_name = {role.name: role for role in roles}
+    seen: dict[str, _Constant] = {}
+    for constant in constants:
+        role_text = constant.role
+        if not ROLE_NAME.match(role_text):
+            found.append(
+                Finding(
+                    "columns",
+                    constant.line,
+                    f"writes the role comment of `{constant.name}` as `# role: {role_text}`",
+                    "a role comment is `# role: <role>` with the role name alone",
+                )
+            )
+            continue
+        role = by_name.get(role_text)
+        if role_text != EXTRA_ROLE and role is None:
+            known = ", ".join(sorted(by_name)) or "none"
+            found.append(
+                Finding(
+                    "columns",
+                    constant.line,
+                    f"names the unknown role `{role_text}` (spec roles: {known})",
+                    f"`{constant.name}` is tagged with a role the spec does not declare",
+                )
+            )
+            continue
+        value = constant.value
+        variadic = role is not None and role.variadic
+        if variadic:
+            ok = isinstance(value, ast.List | ast.Tuple) and all(
+                isinstance(element, ast.Constant) and isinstance(element.value, str) for element in value.elts
+            )
+        else:
+            ok = isinstance(value, ast.Constant) and isinstance(value.value, str)
+        if not ok:
+            wanted = "a list of column-name strings" if variadic else "a column-name string"
+            found.append(
+                Finding(
+                    "columns",
+                    constant.line,
+                    f"assigns `{constant.name}` the value `{src.snippet(value)}`, not {wanted}",
+                    "the agent rewrites the constant's string from its bindings",
+                )
+            )
+        if src.block is not None and constant.line > src.block[0]:
+            found.append(
+                Finding(
+                    "columns",
+                    constant.line,
+                    f"defines the column constant `{constant.name}` below the # Data marker",
+                    "column constants belong above the Data block",
+                )
+            )
+        if role_text != EXTRA_ROLE:
+            if role_text in seen:
+                found.append(
+                    Finding(
+                        "columns",
+                        constant.line,
+                        f"tags `{constant.name}` with the role `{role_text}` that `{seen[role_text].name}` already has",
+                        "two constants for one role",
+                    )
+                )
+            else:
+                seen[role_text] = constant
+    if shape in ("table", "network"):
+        missing = [
+            role.name
+            for role in roles
+            if role.required and not role.computed and not is_structure_role(role, shape) and role.name not in seen
+        ]
+        if missing:
+            found.append(
+                Finding(
+                    "columns",
+                    src.block[0] if src.block else None,
+                    f"has no column constant for the required role{'s' if len(missing) > 1 else ''} "
+                    + ", ".join(f"`{name}`" for name in missing),
+                    "column names are typed where they are used instead of once, above the block",
+                )
+            )
+    return found
+
+
+def _sample(src: _Source, constants: list[_Constant]) -> _Sample:
+    """The strings, column names, data numbers and counts the block defines (constants' values count as columns)."""
+    sample = _Sample()
+    for constant in constants:
+        for node in ast.walk(constant.value):
+            if isinstance(node, ast.Constant) and isinstance(node.value, str):
+                sample.columns.add(node.value)
+    body = src.block_body()
+    frame_dicts: set[str] = set()
+    frames = {"df"}
+    for stmt in body:
+        for node in ast.walk(stmt):
+            if isinstance(node, ast.Call) and _call_name(node) == "DataFrame":
+                for arg in [*node.args[:1], *(kw.value for kw in node.keywords if kw.arg == "data")]:
+                    if isinstance(arg, ast.Name):
+                        frame_dicts.add(arg.id)
+            assigned = _assignment(node)
+            if assigned is not None and isinstance(assigned[1], ast.Call) and _call_name(assigned[1]) in FRAME_CALLS:
+                for target in assigned[0]:
+                    frames |= _target_names(target)
+    for stmt in body:
+        for node in ast.walk(stmt):
+            _sample_node(src, node, sample, frame_dicts, frames)
+    sample.strings = {text for text in sample.strings - sample.columns if text.strip() and not _HEX.match(text)}
+    sample.fields = {text for text in sample.fields - sample.columns if text.strip() and not _HEX.match(text)}
+    sample.counts = {count for count in sample.counts if count >= MIN_COUNT}
+    return sample
+
+
+def _sample_node(src: _Source, node: ast.AST, sample: _Sample, frame_dicts: set[str], frames: set[str]) -> None:
+    if isinstance(node, ast.Dict):
+        parent = src.parents.get(node)
+        is_frame = (
+            (isinstance(parent, ast.Call) and _call_name(parent) in ("DataFrame", "append"))
+            or (isinstance(parent, ast.keyword) and parent.arg == "data")
+            or (
+                isinstance(parent, ast.Assign)
+                and any(name in frame_dicts for t in parent.targets for name in _target_names(t))
+            )
+        )
+        for key, value in zip(node.keys, node.values, strict=True):
+            if isinstance(key, ast.Constant) and isinstance(key.value, str):
+                (sample.columns if is_frame else sample.fields).add(key.value)
+            if isinstance(value, ast.List | ast.Tuple):
+                sample.counts.add(len(value.elts))
+        if len(node.keys) >= MIN_COUNT and not is_frame:
+            sample.counts.add(len(node.keys))
+        return
+    if isinstance(node, ast.List | ast.Tuple | ast.Set):
+        texts = [e.value for e in node.elts if isinstance(e, ast.Constant) and isinstance(e.value, str)]
+        sample.strings.update(texts)
+        sample.counts.add(len(node.elts))
+        if texts:
+            sample.counts.add(len(set(texts)))
+        sample.numbers.update(number for e in node.elts if (number := _number(e)) is not None)
+        parent = src.parents.get(node)
+        if isinstance(parent, ast.keyword) and parent.arg == "columns":
+            sample.columns.update(texts)
+            sample.strings.difference_update(texts)
+        if isinstance(parent, ast.BinOp) and isinstance(parent.op, ast.Mult):
+            factor = _count(parent.right if parent.left is node else parent.left)
+            if factor is not None:
+                sample.counts.update({factor, factor * len(node.elts)})
+        return
+    if isinstance(node, ast.Constant) and isinstance(node.value, str):
+        parent = src.parents.get(node)
+        if isinstance(parent, ast.Assign | ast.Compare | ast.AnnAssign):
+            sample.strings.add(node.value)
+        elif isinstance(parent, ast.Subscript) and parent.slice is node:
+            frame = isinstance(parent.value, ast.Name) and parent.value.id in frames
+            target = isinstance(parent.ctx, ast.Store)
+            (sample.columns if target or frame else sample.fields).add(node.value)
+        return
+    if isinstance(node, ast.keyword) and node.arg and isinstance(src.parents.get(node), ast.Call):
+        call = src.parents[node]
+        if isinstance(call, ast.Call) and _call_name(call) == "assign":
+            sample.columns.add(node.arg)
+        if node.arg == "columns" and isinstance(node.value, ast.Dict):
+            for value in node.value.values:
+                if isinstance(value, ast.Constant) and isinstance(value.value, str):
+                    sample.columns.add(value.value)
+        return
+    if isinstance(node, ast.Call):
+        name = _call_name(node)
+        length = _range_length(node)
+        if length is not None:
+            sample.counts.add(length)
+        if name in RANDOM_SIZE_POSITIONS:
+            size = next((kw.value for kw in node.keywords if kw.arg == "size"), None)
+            position = RANDOM_SIZE_POSITIONS[name]
+            if size is None and position is not None and len(node.args) > position:
+                size = node.args[position]
+            if size is not None:
+                if isinstance(size, ast.Tuple):
+                    sample.counts.update(c for e in size.elts if (c := _count(e)) is not None)
+                elif (count := _count(size)) is not None:
+                    sample.counts.add(count)
+        if name in ("date_range", "period_range"):
+            periods = next((kw.value for kw in node.keywords if kw.arg == "periods"), None)
+            if periods is not None and (count := _count(periods)) is not None:
+                sample.counts.add(count)
+
+
+# rule 3 ---------------------------------------------------------------------------------------
+
+
+def _check_interface(src: _Source, shape: Shape) -> list[Finding]:
+    body = src.block_body()
+    bound: set[str] = set()
+    for stmt in body:
+        bound |= _statement_bindings(stmt)
+    bound -= {"df", "_"}
+    if shape == "network":
+        bound.discard("nodes")
+    if not bound:
+        return []
+    reads = _reads_before_rebinding(src.below(), bound)
+    found: list[Finding] = []
+    for name, line in sorted(reads.items(), key=lambda item: item[1]):
+        found.append(
+            Finding(
+                "interface",
+                line,
+                f"reads `{name}`, which the Data block binds",
+                f"`{name}` is defined in the Data block instead of derived from df below it",
+            )
+        )
+    return found
+
+
+def _statement_bindings(stmt: ast.stmt) -> set[str]:
+    """Names a module-level statement binds at module scope (not inside a function, class or comprehension)."""
+    names: set[str] = set()
+    if isinstance(stmt, ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef):
+        return {stmt.name}
+    if isinstance(stmt, ast.Import | ast.ImportFrom):
+        return {(alias.asname or alias.name).split(".")[0] for alias in stmt.names if alias.name != "*"}
+    for node in _module_scope_nodes(stmt):
+        if isinstance(node, ast.Name) and isinstance(node.ctx, ast.Store):
+            names.add(node.id)
+        elif isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef):
+            names.add(node.name)
+        elif isinstance(node, ast.Import | ast.ImportFrom):
+            names.update((alias.asname or alias.name).split(".")[0] for alias in node.names if alias.name != "*")
+    return names
+
+
+def _module_scope_nodes(node: ast.AST) -> Iterator[ast.AST]:
+    """Every node in `node` that runs in the module's scope: nested functions, lambdas, classes and comprehensions excluded."""
+    yield node
+    for child in ast.iter_child_nodes(node):
+        if isinstance(child, ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef):
+            yield child  # its name binds here; its body does not
+            for decorator in child.decorator_list:
+                yield from _module_scope_nodes(decorator)
+            continue
+        if isinstance(child, ast.Lambda | ast.ListComp | ast.SetComp | ast.DictComp | ast.GeneratorExp):
+            continue
+        yield from _module_scope_nodes(child)
+
+
+def _free_loads(node: ast.AST, local: frozenset[str] = frozenset()) -> Iterator[tuple[str, int]]:
+    """`(name, line)` of every load in `node` that is not bound by an enclosing function, lambda or comprehension."""
+    if isinstance(node, ast.Name):
+        if isinstance(node.ctx, ast.Load) and node.id not in local:
+            yield node.id, node.lineno
+        return
+    if isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef | ast.Lambda):
+        args = node.args
+        params = {a.arg for a in [*args.posonlyargs, *args.args, *args.kwonlyargs]}
+        params |= {a.arg for a in (args.vararg, args.kwarg) if a is not None}
+        for default in [*args.defaults, *(d for d in args.kw_defaults if d is not None)]:
+            yield from _free_loads(default, local)
+        body: list[ast.AST] = list(node.body) if isinstance(node.body, list) else [node.body]
+        assigned = {
+            n.id for part in body for n in ast.walk(part) if isinstance(n, ast.Name) and isinstance(n.ctx, ast.Store)
+        }
+        inner = local | params | assigned
+        if not isinstance(node, ast.Lambda):
+            for decorator in node.decorator_list:
+                yield from _free_loads(decorator, local)
+        for part in body:
+            yield from _free_loads(part, frozenset(inner))
+        return
+    if isinstance(node, ast.ListComp | ast.SetComp | ast.DictComp | ast.GeneratorExp):
+        targets = {name for gen in node.generators for name in _target_names(gen.target)}
+        inner = frozenset(local | targets)
+        for index, gen in enumerate(node.generators):
+            yield from _free_loads(gen.iter, local if index == 0 else inner)
+            for condition in gen.ifs:
+                yield from _free_loads(condition, inner)
+        elements = [node.key, node.value] if isinstance(node, ast.DictComp) else [node.elt]
+        for element in elements:
+            yield from _free_loads(element, inner)
+        return
+    for child in ast.iter_child_nodes(node):
+        yield from _free_loads(child, local)
+
+
+def _reads_before_rebinding(stmts: Sequence[ast.stmt], names: set[str]) -> dict[str, int]:
+    """The first line at which each of `names` is read by `stmts` where not every path has rebound it.
+
+    A name counts as rebound only when every path to the read rebinds it: both branches of an `if`
+    (their sets intersect at the join), never a loop's target or body after the loop (it may run zero
+    times), never a `try` body for its handlers or its `finally`, and never a `match` case after the
+    `match` (no case may apply). `del` unbinds.
+    """
+    hits: dict[str, int] = {}
+
+    def load(node: ast.AST | None, bound: frozenset[str]) -> None:
+        if node is None:
+            return
+        for name, line in _free_loads(node):
+            if name in names and name not in bound and name not in hits:
+                hits[name] = line
+
+    def bound_by(node: ast.AST | None) -> frozenset[str]:
+        return frozenset(_target_names(node)) if isinstance(node, ast.expr) else frozenset()
+
+    def sequence(statements: Iterable[ast.stmt], bound: frozenset[str]) -> frozenset[str]:
+        for stmt in statements:
+            bound = step(stmt, bound)
+        return bound
+
+    def step(stmt: ast.stmt, bound: frozenset[str]) -> frozenset[str]:
+        if isinstance(stmt, ast.For | ast.AsyncFor):
+            load(stmt.iter, bound)
+            sequence(stmt.body, bound | bound_by(stmt.target))
+            return sequence(stmt.orelse, bound)
+        if isinstance(stmt, ast.While):
+            load(stmt.test, bound)
+            sequence(stmt.body, bound)
+            return sequence(stmt.orelse, bound)
+        if isinstance(stmt, ast.If):
+            load(stmt.test, bound)
+            return sequence(stmt.body, bound) & sequence(stmt.orelse, bound)
+        if isinstance(stmt, ast.With | ast.AsyncWith):
+            for item in stmt.items:
+                load(item.context_expr, bound)
+                bound = bound | bound_by(item.optional_vars)
+            return sequence(stmt.body, bound)
+        if isinstance(stmt, ast.Try | ast.TryStar):
+            paths = [sequence(stmt.orelse, sequence(stmt.body, bound))]
+            for handler in stmt.handlers:
+                load(handler.type, bound)
+                paths.append(sequence(handler.body, bound | ({handler.name} if handler.name else set())))
+            joined = frozenset.intersection(*paths)
+            return joined | sequence(stmt.finalbody, bound)
+        if isinstance(stmt, ast.Match):
+            load(stmt.subject, bound)
+            for case in stmt.cases:
+                load(case.guard, bound)
+                sequence(case.body, bound | {n.id for n in ast.walk(case.pattern) if isinstance(n, ast.Name)})
+            return bound
+        if isinstance(stmt, ast.Assign):
+            load(stmt.value, bound)
+            for target in stmt.targets:
+                if not isinstance(target, ast.Name | ast.Tuple | ast.List):
+                    load(target, bound)
+            return bound.union(*(bound_by(target) for target in stmt.targets))
+        if isinstance(stmt, ast.AugAssign):
+            load(stmt.value, bound)
+            load(stmt.target, bound)
+            target = stmt.target  # `scale *= 2` reads `scale` first, though its context is Store
+            if isinstance(target, ast.Name) and target.id in names and target.id not in bound and target.id not in hits:
+                hits[target.id] = target.lineno
+            return bound | bound_by(stmt.target)
+        if isinstance(stmt, ast.AnnAssign):
+            load(stmt.value, bound)
+            return bound | bound_by(stmt.target) if stmt.value is not None else bound
+        if isinstance(stmt, ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef):
+            load(stmt, bound)
+            return bound | {stmt.name}
+        if isinstance(stmt, ast.Import | ast.ImportFrom):
+            return bound | _statement_bindings(stmt)
+        if isinstance(stmt, ast.Delete):
+            return bound - frozenset().union(*(bound_by(target) for target in stmt.targets))
+        load(stmt, bound)
+        return bound
+
+    sequence(stmts, frozenset())
+    return hits
+
+
+# rule 4 ---------------------------------------------------------------------------------------
+
+
+def _altair_field(text: str) -> str:
+    """A Vega-Lite field string as the column it names: type suffix dropped, escapes undone."""
+    return _ALTAIR_ESCAPE.sub(r"\1", _ALTAIR_SUFFIX.sub("", text))
+
+
+def _axes_hidden(src: _Source) -> bool:
+    """The file hides an axis, so its coordinates place a drawing (a Venn, a hemicycle, a ternary frame).
+
+    `ax.axis("off")`, `set_axis_off()`, `theme_void()`, altair's `axis=None`, plotly's `visible=False` on an
+    axis, and bokeh's `p.axis.visible = False`.
+    """
+    for node in ast.walk(src.tree):
+        if isinstance(node, ast.Call):
+            name = _call_name(node)
+            if name in ("set_axis_off", "theme_void"):
+                return True
+            if (
+                name == "axis"
+                and node.args
+                and isinstance(node.args[0], ast.Constant)
+                and node.args[0].value in ("off", False)
+            ):
+                return True
+            for keyword in node.keywords:
+                if not isinstance(keyword.value, ast.Constant):
+                    continue
+                value = keyword.value.value
+                if keyword.arg == "axis" and value is None:
+                    return True
+                if value is False and (
+                    (keyword.arg == "visible" and name in ("update_xaxes", "update_yaxes", "dict"))
+                    or (keyword.arg or "").endswith("axis_visible")
+                ):
+                    return True
+        elif isinstance(node, ast.Assign) and isinstance(node.value, ast.Constant) and node.value.value is False:
+            for target in node.targets:
+                if isinstance(target, ast.Attribute) and target.attr == "visible":
+                    owner = _dotted(target.value) or ""
+                    if owner.endswith(("axis", "xaxis", "yaxis")):
+                        return True
+    return False
+
+
+def _check_literals(src: _Source, sample: _Sample | None) -> list[Finding]:
+    found: list[Finding] = []
+    below = src.below()
+    derived = _df_derived(below) if sample is not None else set()
+    aliases = _literal_aliases(below) if sample is not None else {}
+    coordinates = not _axes_hidden(src)
+    seen_coordinates: set[int] = set()
+    for stmt in below:
+        for node in ast.walk(stmt):
+            if src.inside(node, (ast.JoinedStr,)) is not None or _in_output_call(src, node):
+                continue
+            if isinstance(node, ast.Constant) and isinstance(node.value, str):
+                found.extend(_string_finding(src, node, sample))
+            elif isinstance(node, ast.Call):
+                coordinate = _coordinate_finding(src, node, frames=src.block is not None) if coordinates else None
+                if coordinate is not None and coordinate.line not in seen_coordinates:
+                    seen_coordinates.add(coordinate.line or 0)
+                    found.append(coordinate)
+                if sample is not None:
+                    found.extend(_count_finding(src, node, sample))
+                    found.extend(_method_comparison(src, node, derived, aliases))
+            elif isinstance(node, ast.Assign) and coordinates:
+                attribute = _attribute_coordinate(src, node)
+                if attribute is not None:
+                    found.append(attribute)
+            elif isinstance(node, ast.Subscript) and sample is not None:
+                found.extend(_slice_count(src, node, sample))
+            elif isinstance(node, ast.Compare) and sample is not None:
+                found.extend(_compare_finding(src, node, derived, aliases))
+    return found
+
+
+def _in_output_call(src: _Source, node: ast.AST) -> bool:
+    current: ast.AST | None = node
+    while current is not None:
+        if isinstance(current, ast.Call) and _call_name(current) in OUTPUT_CALLS:
+            return True
+        current = src.parents.get(current)
+    return False
+
+
+def _string_finding(src: _Source, node: ast.Constant, sample: _Sample | None) -> list[Finding]:
+    text = node.value
+    assert isinstance(text, str)
+    if "anyplot.ai" in text:
+        return []
+    parent = src.parents.get(node)
+    if isinstance(parent, ast.keyword) and parent.arg in STYLE_KEYWORDS:
+        return []
+    if isinstance(parent, ast.Expr):
+        return []  # a docstring or a bare string statement
+    found: list[Finding] = []
+    if sample is not None:
+        field_name = _altair_field(text)
+        if text in sample.columns or field_name in sample.columns:
+            found.append(
+                Finding(
+                    "column-literal",
+                    node.lineno,
+                    f"types the column name {text!r}",
+                    f"{src.snippet(parent) if parent is not None else repr(text)} repeats a column name below the Data block",
+                )
+            )
+        elif (
+            (text in sample.strings or (text in sample.fields and not _PROPERTY_KEY.match(text)))
+            and len(text.strip()) >= MIN_SAMPLE_CHARS
+            and text.strip().lower() not in PROSE_WORDS | STYLE_WORDS
+            and not (isinstance(parent, ast.Dict) and node in parent.keys and _PROPERTY_KEY.match(text))
+        ):
+            context = src.snippet(parent) if parent is not None else repr(text)
+            found.append(
+                Finding(
+                    "sample-literal",
+                    node.lineno,
+                    f"uses the literal {text!r}, a value the Data block defines",
+                    f"{context} below the Data block",
+                )
+            )
+    if _STATISTIC.search(text):
+        found.append(
+            Finding(
+                "statistic-text",
+                node.lineno,
+                f"states the statistic {text!r} as text",
+                "a number from the sample typed into a label",
+            )
+        )
+    return found
+
+
+def _coordinate_finding(src: _Source, call: ast.Call, frames: bool) -> Finding | None:
+    """A numeric literal or literal date in a data-coordinate position of `call`.
+
+    `frames` checks the literal data of a `DataFrame` built in the plot code (a reference line's
+    frame in altair); it is off when there is no block, since the data generation is then unknown.
+    """
+    name = _call_name(call)
+    keywords = {kw.arg: kw.value for kw in call.keywords if kw.arg}
+    candidates: list[ast.expr] = []
+    if name in LIMIT_METHODS:
+        # positional bounds and the bound keywords only: `set_xticks(x, labels, fontsize=8)` styles its labels
+        candidates = [*call.args, *(value for key, value in keywords.items() if key in LIMIT_KEYWORDS)]
+        if any(not _literal_values(node) and not isinstance(node, ast.List | ast.Tuple) for node in candidates):
+            # padding beside a computed bound: set_xlim(-0.5, n - 0.5), set_ylim(0, top * 1.1)
+            candidates = [node for node in candidates if not _padding(node)]
+    elif name == "text" and call.args and isinstance(call.args[0], ast.Tuple | ast.List):
+        return None  # PIL's ImageDraw.text((x, y), ...) places pixels, not data
+    elif name == "annotate" and ("xy" in keywords or len(call.args) > 1):
+        # matplotlib's annotate(text, xy, xytext=...); plotnine's annotate("text", x=..., y=...) uses the table below
+        if not _paper_ref(keywords.get("xycoords")):
+            xy = call.args[1] if len(call.args) > 1 else keywords.get("xy")
+            if xy is not None:
+                candidates.append(xy)
+            text_coords = keywords.get("textcoords", keywords.get("xycoords"))
+            if "xytext" in keywords and not _paper_ref(text_coords):
+                candidates.append(keywords["xytext"])
+    elif name in DATA_CALL_ARGS:
+        if name == "text" and _figure_text(src, call, keywords):
+            return None
+        if name in ("add_annotation", "add_shape") and (
+            _paper_ref(keywords.get("xref")) or _paper_ref(keywords.get("yref"))
+        ):
+            return None
+        if name == "Label" and (_paper_ref(keywords.get("x_units")) or _paper_ref(keywords.get("y_units"))):
+            return None
+        positions, names = DATA_CALL_ARGS[name]
+        candidates = [call.args[i] for i in positions if i < len(call.args)]
+        candidates += [keywords[key] for key in names if key in keywords]
+    elif name is not None and name.startswith("geom_"):
+        candidates = [keywords[key] for key in _GEOM_COORDINATES if key in keywords]
+    elif name is not None and name in NORM_CALLS:
+        positions, norm_names = NORM_CALLS[name]
+        candidates = [call.args[i] for i in positions if i < len(call.args)]
+        candidates += [value for key, value in keywords.items() if key in norm_names]
+    elif name == "DataFrame" and frames:
+        candidates = [*call.args[:1], *(value for key, value in keywords.items() if key == "data")]
+        candidates = [_frame_values(node) for node in candidates]
+    visual_range = name == "Scale" or (name or "").startswith("scale_")
+    for key, value in keywords.items():
+        if key == "range" and visual_range:
+            continue  # alt.Scale(range=...) and scale_size(range=...) map to sizes or colors, not data
+        if key in GENERIC_DATA_KEYWORDS or _AXIS_DATA_KEYWORD.match(key):
+            candidates.append(value)
+        elif key == "levels" and name in CONTOUR_CALLS and _number(value) is None:
+            candidates.append(value)
+        elif key == "ticks" and name == "colorbar":
+            candidates.append(value)
+        elif key == "bins" and _number(value) is None:
+            candidates.append(value)
+    for node in call.args + list(keywords.values()):
+        if isinstance(node, ast.Dict):
+            candidates.extend(_dict_coordinates(node))
+    values = [value for node in candidates for value in _literal_values(_without_padding(node))]
+    if not values or _exempt(values):
+        return None
+    shown = ", ".join(_format_value(value) for value in values[:4]) + (", …" if len(values) > 4 else "")
+    return Finding(
+        "data-coordinate",
+        call.lineno,
+        f"places data coordinates by the literal{'s' if len(values) > 1 else ''} {shown}",
+        f"`{src.snippet(call)}` fixes the axis to the sample's range",
+    )
+
+
+def _padding(node: ast.expr) -> bool:
+    """A literal of magnitude `PADDING` or less: padding or a baseline beside a computed bound."""
+    value = _number(node)
+    return value is not None and abs(value) <= PADDING
+
+
+def _without_padding(node: ast.expr) -> ast.expr:
+    """A bound pair with a computed member keeps only its literals beyond `PADDING`: `xlim=(-1.5, n + 0.5)`."""
+    if isinstance(node, ast.Tuple | ast.List) and any(_number(element) is None for element in node.elts):
+        return ast.List(elts=[element for element in node.elts if not _padding(element)], ctx=ast.Load())
+    return node
+
+
+def _frame_values(node: ast.expr) -> ast.expr:
+    """The literal data of a `DataFrame` built below the block, as one list node."""
+    if isinstance(node, ast.Dict):
+        return ast.List(elts=[value for value in node.values if value is not None], ctx=ast.Load())
+    return node
+
+
+def _dict_coordinates(node: ast.Dict) -> list[ast.expr]:
+    out: list[ast.expr] = []
+    for key, value in zip(node.keys, node.values, strict=True):
+        if isinstance(key, ast.Constant) and isinstance(key.value, str):
+            if key.value in GENERIC_DATA_KEYWORDS or _AXIS_DATA_KEYWORD.match(key.value):
+                out.append(value)
+            elif key.value == "ticks" and isinstance(value, ast.List | ast.Tuple):
+                out.append(value)
+    return out
+
+
+def _paper_ref(node: ast.expr | None) -> bool:
+    if isinstance(node, ast.Constant) and isinstance(node.value, str):
+        return any(ref in node.value for ref in PAPER_REFS)
+    if node is not None:
+        dotted = _dotted(node) or ""
+        return dotted.endswith(("transAxes", "transFigure"))
+    return False
+
+
+def _figure_text(src: _Source, call: ast.Call, keywords: Mapping[str, ast.expr]) -> bool:
+    """A `text` call in figure or axes coordinates."""
+    if isinstance(call.func, ast.Attribute):
+        receiver = _dotted(call.func.value) or ""
+        if "fig" in receiver.rsplit(".", 1)[-1].lower():
+            return True
+    transform = keywords.get("transform")
+    return transform is not None and not (_dotted(transform) or "").endswith("transData")
+
+
+def _format_value(value: float | str) -> str:
+    if isinstance(value, str):
+        return value
+    return str(int(value)) if value == int(value) else f"{value:g}"
+
+
+def _attribute_coordinate(src: _Source, node: ast.Assign) -> Finding | None:
+    for target in node.targets:
+        if isinstance(target, ast.Attribute) and target.attr in DATA_ATTRIBUTES:
+            values = _literal_values(node.value)
+            if values and not _exempt(values):
+                shown = ", ".join(_format_value(value) for value in values[:4])
+                return Finding(
+                    "data-coordinate",
+                    node.lineno,
+                    f"sets `{src.snippet(target)}` to the literal {shown}",
+                    "a range or tick list typed for the sample",
+                )
+    return None
+
+
+def _count_finding(src: _Source, call: ast.Call, sample: _Sample) -> list[Finding]:
+    name = _call_name(call)
+    if name not in RANGE_CALLS:
+        return []
+    length = _range_length(call)
+    if length is None or length not in sample.counts:
+        return []
+    if name == "linspace" and length >= RESOLUTION_COUNT:
+        return []
+    return [
+        Finding(
+            "count-literal",
+            call.lineno,
+            f"counts {length} with `{src.snippet(call)}`, a count the Data block defines",
+            "the number of sample rows or categories typed as a literal",
+        )
+    ]
+
+
+def _slice_count(src: _Source, node: ast.Subscript, sample: _Sample) -> list[Finding]:
+    if not isinstance(node.slice, ast.Slice):
+        return []
+    if isinstance(node.value, ast.Name) and node.value.id in PALETTE_NAMES:
+        return []  # the palette rule reports palette slices
+    lower = _count(node.slice.lower) if node.slice.lower is not None else None
+    upper = _count(node.slice.upper) if node.slice.upper is not None else None
+    if lower is None and upper is not None and upper > 0:
+        length = upper
+    elif upper is None and lower is not None and lower < 0:
+        length = -lower
+    elif lower is not None and upper is not None and upper > lower >= 0:
+        length = upper - lower
+    else:
+        return []
+    if length not in sample.counts:
+        return []
+    return [
+        Finding(
+            "count-literal",
+            node.lineno,
+            f"slices {length} items with `{src.snippet(node)}`, a count the Data block defines",
+            "the number of sample rows or categories typed as a literal",
+        )
+    ]
+
+
+def _df_derived(stmts: Sequence[ast.stmt]) -> set[str]:
+    """`df` and the names the plot code derives from it, in order (loop targets over derived values included)."""
+    derived = {"df"}
+    for stmt in stmts:
+        for node in _module_scope_nodes(stmt):
+            assigned = _assignment(node)
+            if assigned is not None and _names_in(assigned[1]) & derived:
+                for target in assigned[0]:
+                    derived |= _target_names(target)
+            elif isinstance(node, ast.For | ast.AsyncFor) and _names_in(node.iter) & derived:
+                derived |= _target_names(node.target)
+            elif isinstance(node, ast.comprehension) and _names_in(node.iter) & derived:
+                derived |= _target_names(node.target)
+        for node in ast.walk(stmt):
+            if isinstance(node, ast.comprehension) and _names_in(node.iter) & derived:
+                derived |= _target_names(node.target)
+    return derived
+
+
+def _literal_aliases(stmts: Sequence[ast.stmt]) -> dict[str, ast.Constant]:
+    """Names bound once, at module level below the block, to a number, string or date literal."""
+    counts: Counter[str] = Counter()
+    values: dict[str, ast.Constant] = {}
+    for stmt in stmts:
+        assigned = _assignment(stmt)
+        if assigned is not None:
+            for target in assigned[0]:
+                for name in _target_names(target):
+                    counts[name] += 1
+            single = _single_name(stmt)
+            if single is not None:
+                value = single[1]
+                if (
+                    isinstance(value, ast.Constant)
+                    and isinstance(value.value, int | float | str)
+                    and not isinstance(value.value, bool)
+                ):
+                    values[single[0]] = value
+        else:
+            for name in _statement_bindings(stmt):
+                counts[name] += 1
+    return {name: value for name, value in values.items() if counts[name] == 1}
+
+
+def _comparison_literal(node: ast.expr, aliases: Mapping[str, ast.Constant]) -> tuple[str, ast.expr] | None:
+    """The literal a comparison operand stands for, as `(shown, literal node)`, or None."""
+    if isinstance(node, ast.Name) and node.id in aliases:
+        literal: ast.expr = aliases[node.id]
+        shown = f"{node.id} = {ast.unparse(literal)}"
+    else:
+        literal = node
+        shown = ast.unparse(node)
+    if isinstance(literal, ast.Constant) and isinstance(literal.value, str):
+        return (shown, literal) if literal.value.strip() else None
+    values = _literal_values(literal)
+    if values and not _exempt(values):
+        return shown, literal
+    if isinstance(literal, ast.List | ast.Tuple | ast.Set) and any(
+        isinstance(e, ast.Constant) and isinstance(e.value, str) for e in literal.elts
+    ):
+        return shown, literal
+    return None
+
+
+def _compare_finding(
+    src: _Source, node: ast.Compare, derived: set[str], aliases: Mapping[str, ast.Constant]
+) -> list[Finding]:
+    if not all(isinstance(op, SELECTION_OPS) for op in node.ops):
+        return []
+    operands = [node.left, *node.comparators]
+    if not any(_names_in(operand) & derived for operand in operands):
+        return []
+    for operand in operands:
+        if _names_in(operand) & derived:
+            continue
+        literal = _comparison_literal(operand, aliases)
+        if literal is not None:
+            return [
+                Finding(
+                    "df-comparison",
+                    node.lineno,
+                    f"compares df with the literal {literal[0]}",
+                    f"`{src.snippet(node)}` selects a sample value",
+                )
+            ]
+    return []
+
+
+def _method_comparison(
+    src: _Source, call: ast.Call, derived: set[str], aliases: Mapping[str, ast.Constant]
+) -> list[Finding]:
+    name = _call_name(call)
+    if name not in COMPARISON_METHODS:
+        return []
+    if not isinstance(call.func, ast.Attribute) or not (_names_in(call.func.value) & derived):
+        return []
+    for arg in call.args:
+        literal = _comparison_literal(arg, aliases)
+        if literal is not None:
+            return [
+                Finding(
+                    "df-comparison",
+                    call.lineno,
+                    f"compares df with the literal {literal[0]}",
+                    f"`{src.snippet(call)}` selects a sample value",
+                )
+            ]
+    return []
+
+
+# rule 5 ---------------------------------------------------------------------------------------
+
+
+def _palette(src: _Source) -> tuple[str, list[str], int] | None:
+    """The module's Imprint palette: its name, its entries and its line."""
+    for stmt in src.tree.body:
+        single = _single_name(stmt)
+        if single is None:
+            continue
+        name, value = single
+        if not isinstance(value, ast.List | ast.Tuple):
+            continue
+        entries = [e.value.upper() for e in value.elts if isinstance(e, ast.Constant) and isinstance(e.value, str)]
+        if name in PALETTE_NAMES or (len(entries) >= 2 and entries[0] == CANONICAL_IMPRINT[0]):
+            return name, entries, stmt.lineno
+    return None
+
+
+def _check_palette(src: _Source, color: DataRole | None) -> list[Finding]:
+    """Rule 5. A missing palette counts only for a required colour role: an optional one may go unused."""
+    found: list[Finding] = []
+    palette = _palette(src)
+    names = set(PALETTE_NAMES) | ({palette[0]} if palette else set())
+    role = color.name if color is not None else None
+    if color is not None:
+        if palette is None:
+            if color.required:
+                found.append(
+                    Finding(
+                        "palette",
+                        None,
+                        f"has no IMPRINT list while the spec's `{role}` role colors the marks",
+                        "colors come from elsewhere than the Imprint palette",
+                    )
+                )
+        else:
+            name, entries, line = palette
+            canonical = [entry.upper() for entry in CANONICAL_IMPRINT]
+            if entries != canonical:
+                what = (
+                    f"lists {len(entries)} of 8 positions"
+                    if entries == canonical[: len(entries)]
+                    else "lists the Imprint colors out of canonical order"
+                )
+                found.append(
+                    Finding("palette", line, f"`{name}` {what}", f"a palette sized to the sample's `{role}` values")
+                )
+    for stmt in src.tree.body:
+        for node in ast.walk(stmt):
+            if isinstance(node, ast.Call) and _call_name(node) == "zip":
+                strict = any(
+                    kw.arg == "strict" and isinstance(kw.value, ast.Constant) and kw.value.value is True
+                    for kw in node.keywords
+                )
+                if strict and any(_names_in(arg) & names and not _sized_slice(arg) for arg in node.args):
+                    found.append(
+                        Finding(
+                            "palette",
+                            node.lineno,
+                            "zips the palette with strict=True, which raises for one more group",
+                            f"`{src.snippet(node)}`",
+                        )
+                    )
+            elif (
+                role is not None
+                and isinstance(node, ast.Subscript)
+                and isinstance(node.value, ast.Name)
+                and node.value.id in names
+                and isinstance(node.slice, ast.Slice)
+                and node.slice.upper is not None
+                and _count(node.slice.upper) is not None
+            ):
+                found.append(
+                    Finding(
+                        "palette",
+                        node.lineno,
+                        f"slices the palette to a fixed size with `{src.snippet(node)}`",
+                        "a literal slice sized to the sample's groups",
+                    )
+                )
+    return found
+
+
+def _sized_slice(node: ast.expr) -> bool:
+    """A palette slice whose length is computed (`IMPRINT[: len(groups)]`): a strict zip over it raises only past eight."""
+    return (
+        isinstance(node, ast.Subscript)
+        and isinstance(node.slice, ast.Slice)
+        and (node.slice.upper is not None and _count(node.slice.upper) is None)
+    )
+
+
+# rule 6 ---------------------------------------------------------------------------------------
+
+
+def _check_constants_zone(src: _Source, sample: _Sample) -> list[Finding]:
+    found: list[Finding] = []
+    for stmt in src.constants_zone():
+        assigned = _assignment(stmt)
+        if assigned is None or any(
+            line
+            for line, col, text in src.comments
+            if col > 0 and ROLE_COMMENT.match(text) and stmt.lineno <= line <= (stmt.end_lineno or stmt.lineno)
+        ):
+            continue
+        value = assigned[1]
+        strings = {
+            node.value for node in ast.walk(value) if isinstance(node, ast.Constant) and isinstance(node.value, str)
+        }
+        numbers = {
+            number
+            for node in ast.walk(value)
+            if isinstance(node, ast.expr)
+            and not isinstance(node, ast.BinOp | ast.UnaryOp)
+            and (number := _number(node)) is not None
+        }
+        shared = sorted(strings & sample.strings)
+        coordinates = sorted(n for n in numbers & sample.numbers if not _exempt([n]))
+        container = isinstance(value, ast.List | ast.Tuple | ast.Set | ast.Dict)
+        if shared and (container or isinstance(value, ast.Constant)):
+            shown = ", ".join(repr(text) for text in shared[:3]) + (", …" if len(shared) > 3 else "")
+            found.append(
+                Finding(
+                    "constants",
+                    stmt.lineno,
+                    f"lists sample values ({shown}) in # Constants",
+                    "sample categories hoisted out of the Data block, or an ordered scale the block also spells out",
+                )
+            )
+        elif container and len(coordinates) >= 2:
+            shown = ", ".join(_format_value(number) for number in coordinates[:3])
+            found.append(
+                Finding(
+                    "constants",
+                    stmt.lineno,
+                    f"lists the sample's data numbers ({shown}) in # Constants",
+                    "data coordinates hoisted out of the Data block",
+                )
+            )
+    return found
+
+
+# --- source mutations --------------------------------------------------------------------------
+
+
+def replace_block(source: str, replacement: str) -> str:
+    """The source with the statements between the `# Data` and `# Plot` markers replaced; the markers stay.
+
+    Raises ValueError when the source has no block.
+    """
+    tree = ast.parse(source)
+    src = _Source(source, tree, None)
+    if src.block is None:
+        raise ValueError("the source has no # Data ... # Plot block")
+    start, end = src.block
+    lines = source.splitlines(keepends=True)
+    body = replacement if replacement.endswith("\n") else replacement + "\n"
+    return "".join(lines[:start]) + body + "\n" + "".join(lines[end - 1 :])
+
+
+def rewrite_constants(source: str, columns: Mapping[str, str | Sequence[str]]) -> str:
+    """The source with each role's column constant set to the column name(s) in `columns` (role -> name).
+
+    Roles without a constant are ignored; a constant whose role is not in `columns` keeps its value.
+    """
+    return _rewrite(source, lambda constant, _: columns.get(constant.role))
+
+
+def rewrite_columns(source: str, renames: Mapping[str, str]) -> str:
+    """The source with every column constant, `# role: extra` included, renamed through `renames` (old -> new).
+
+    A constant whose value (or one of whose list entries) is an old column name gets the new one; any
+    other constant keeps its value. This is how a table with renamed columns reaches columns that no
+    spec role names.
+    """
+
+    def choose(_: _Constant, current: str | list[str] | None) -> str | list[str] | None:
+        if isinstance(current, str):
+            return renames.get(current)
+        if isinstance(current, list) and any(item in renames for item in current):
+            return [renames.get(item, item) for item in current]
+        return None
+
+    return _rewrite(source, choose)
+
+
+def _literal_columns(value: ast.expr) -> str | list[str] | None:
+    """A constant's column name, or its list of names; None for any other value."""
+    if isinstance(value, ast.Constant) and isinstance(value.value, str):
+        return value.value
+    if isinstance(value, ast.List | ast.Tuple) and all(
+        isinstance(item, ast.Constant) and isinstance(item.value, str) for item in value.elts
+    ):
+        return [item.value for item in value.elts if isinstance(item, ast.Constant) and isinstance(item.value, str)]
+    return None
+
+
+def _rewrite(source: str, choose: Callable[[_Constant, str | list[str] | None], str | Sequence[str] | None]) -> str:
+    """Set each column constant's value to `choose(constant, current value)`, unless that is None.
+
+    The new value is written on one line. A role comment inside the old value's span (`SERIES = [  # role: y`
+    over several lines) moves to the end of the statement's last line, so the constant stays a constant.
+    """
+    tree = ast.parse(source)
+    src = _Source(source, tree, None)
+    offsets = _line_offsets(source)
+    role_comments = [
+        (offsets[line - 1] + col, text) for line, col, text in src.comments if col > 0 and ROLE_COMMENT.match(text)
+    ]
+    edits: list[tuple[int, int, str]] = []
+    for constant in _column_constants(src):
+        new = choose(constant, _literal_columns(constant.value))
+        if new is None:
+            continue
+        value = constant.value
+        start = offsets[value.lineno - 1] + _char_offset(source, offsets, value.lineno, value.col_offset)
+        end_line = value.end_lineno or value.lineno
+        end = offsets[end_line - 1] + _char_offset(source, offsets, end_line, value.end_col_offset or 0)
+        text = json.dumps(new if isinstance(new, str) else list(new), ensure_ascii=False)
+        inside = [comment for position, comment in role_comments if start <= position < end]
+        if inside:
+            line_end = source.find("\n", end)
+            line_end = len(source) if line_end == -1 else line_end
+            tail = source[end:line_end].strip()
+            text += f"  {inside[0]}" + (f"  {tail}" if tail else "")
+            end = line_end
+        edits.append((start, end, text))
+    for start, end, text in sorted(edits, reverse=True):
+        source = source[:start] + text + source[end:]
+    return source
+
+
+def _line_offsets(source: str) -> list[int]:
+    offsets = [0]
+    for line in source.splitlines(keepends=True):
+        offsets.append(offsets[-1] + len(line))
+    return offsets
+
+
+def _char_offset(source: str, offsets: Sequence[int], line: int, byte_col: int) -> int:
+    """A column in characters from the AST's UTF-8 byte column."""
+    text = source[offsets[line - 1] : offsets[line] if line < len(offsets) else len(source)]
+    return len(text.encode("utf-8")[:byte_col].decode("utf-8", errors="ignore"))
+
+
+# --- files and CLI -----------------------------------------------------------------------------
+
+
+def library_of(path: Path) -> str | None:
+    """The library a catalogue implementation file belongs to (its stem), or None for another file name."""
+    return path.stem if path.stem in LIBRARIES else None
+
+
+def spec_context(spec_path: Path, spec_id: str | None = None) -> tuple[str, list[DataRole], Shape]:
+    """The spec id, parsed roles and shape of a `specification.md`."""
+    spec_id = spec_id or spec_path.parent.name
+    roles = parse_roles(data_bullets(spec_path.read_text(encoding="utf-8")))
+    return spec_id, roles, spec_shape(spec_id, roles)
+
+
+def check_file(impl_path: Path, spec_path: Path | None = None, *, spec_id: str | None = None) -> Record:
+    """Check a catalogue file; the spec defaults to `plots/<spec>/specification.md` next to it."""
+    if spec_path is None:
+        spec_path = impl_path.parents[2] / "specification.md"
+    _, roles, shape = spec_context(spec_path, spec_id)
+    return check_source(impl_path.read_text(encoding="utf-8"), roles, shape, library=library_of(impl_path))
+
+
+def _implementations(plots: Path, library: str | None) -> list[Path]:
+    pattern = f"*/implementations/python/{library}.py" if library else "*/implementations/python/*.py"
+    return sorted(path for path in plots.glob(pattern) if library_of(path) is not None)
+
+
+def run_report(plots: Path, library: str | None = None) -> list[tuple[Path, Record]]:
+    """The record of every Python implementation under `plots/`."""
+    results: list[tuple[Path, Record]] = []
+    specs: dict[Path, tuple[str, list[DataRole], Shape]] = {}
+    for path in _implementations(plots, library):
+        spec_path = path.parents[2] / "specification.md"
+        if spec_path not in specs:
+            specs[spec_path] = spec_context(spec_path)
+        _, roles, shape = specs[spec_path]
+        results.append((path, check_source(path.read_text(encoding="utf-8"), roles, shape, library=library_of(path))))
+    return results
+
+
+def format_report(results: Sequence[tuple[Path, Record]]) -> str:
+    """Per-library pass/fail counts and, per rule class, the number of files with a finding."""
+    by_library: dict[str, Counter[str]] = {}
+    classes: dict[str, Counter[str]] = {cls: Counter() for cls in RULE_ORDER}
+    shapes: Counter[str] = Counter()
+    for path, record in results:
+        library = library_of(path) or path.stem
+        by_library.setdefault(library, Counter())[record.status] += 1
+        for cls in record.classes():
+            classes[cls][library] += 1
+        if library == "matplotlib":
+            shapes[record.shape] += 1
+    libraries = [lib for lib in LIBRARIES if lib in by_library]
+    out = ["| Library | Files | Pass | Fail | Excluded |", "|---|---|---|---|---|"]
+    totals: Counter[str] = Counter()
+    for lib in libraries:
+        counts = by_library[lib]
+        total = sum(counts.values())
+        totals.update(counts)
+        out.append(f"| {lib} | {total} | {counts['pass']} | {counts['fail']} | {counts['excluded']} |")
+    out.append(f"| **all** | {sum(totals.values())} | {totals['pass']} | {totals['fail']} | {totals['excluded']} |")
+    out += ["", "Files with a finding, per rule class:", ""]
+    out.append("| Rule | Class | " + " | ".join(libraries) + " | All |")
+    out.append("|---|---|" + "---|" * len(libraries) + "---|")
+    for cls in RULE_ORDER:
+        rule = RULE_CLASSES[cls]
+        label = f"{cls} (advisory)" if rule.advisory else cls
+        cells = [str(classes[cls][lib]) for lib in libraries]
+        out.append(f"| {rule.rule} | {label} | " + " | ".join(cells) + f" | {sum(classes[cls].values())} |")
+    if shapes:
+        out += [
+            "",
+            "Specs per shape (one library's files): " + ", ".join(f"{k} {v}" for k, v in sorted(shapes.items())),
+        ]
+    return "\n".join(out)
+
+
+def sample_findings(
+    results: Sequence[tuple[Path, Record]], per_class: int, seed: int, root: Path | None = None
+) -> dict[str, list[str]]:
+    """Per rule class, up to `per_class` findings drawn at random (one per file), as `file:line  observed`."""
+    rng = random.Random(seed)
+    out: dict[str, list[str]] = {}
+    for cls in RULE_ORDER:
+        pool: list[tuple[Path, Finding]] = []
+        for path, record in results:
+            matches = [finding for finding in record.findings if finding.cls == cls]
+            if matches:
+                pool.append((path, rng.choice(matches)))
+        picked = rng.sample(pool, min(per_class, len(pool)))
+        lines = []
+        for path, finding in sorted(picked, key=lambda item: str(item[0])):
+            shown = path.relative_to(root) if root is not None and path.is_relative_to(root) else path
+            where = f"{shown}:{finding.line}" if finding.line is not None else str(shown)
+            lines.append(f"{where}  {finding.observed}")
+        out[cls] = lines
+    return out
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="python -m core.adaptability", description="Check Python implementations against the adaptable-code rules."
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+    check = sub.add_parser("check", help="check one implementation file")
+    check.add_argument("source", type=Path)
+    check.add_argument("--spec", type=Path, default=None, help="specification.md (default: the catalogue's)")
+    check.add_argument("--spec-id", default=None)
+    check.add_argument("--out", type=Path, default=None, help="write the record as JSON here")
+    report = sub.add_parser("report", help="check every Python implementation under plots/")
+    report.add_argument("plots", type=Path)
+    report.add_argument("--library", default=None, choices=LIBRARIES)
+    report.add_argument("--sample", type=int, default=0, help="print N random findings per rule class")
+    report.add_argument("--seed", type=int, default=1)
+    report.add_argument("--json", action="store_true", help="print every record as JSON lines")
+    args = parser.parse_args(argv)
+
+    if args.command == "check":
+        try:
+            record = check_file(args.source, args.spec, spec_id=args.spec_id)
+        except OSError as exc:
+            print(f"::error::adaptability check cannot read its input: {exc}")
+            return 2
+        payload = json.dumps(record.to_dict(), ensure_ascii=False)
+        if args.out is not None:
+            args.out.write_text(payload + "\n", encoding="utf-8")
+        print(payload)
+        for line in record.defect_lines():
+            print(line)
+        return 1 if record.status == "fail" else 0
+
+    results = run_report(args.plots, args.library)
+    if args.json:
+        for path, record in results:
+            print(json.dumps({"file": str(path), **record.to_dict()}, ensure_ascii=False))
+        return 0
+    print(format_report(results))
+    if args.sample:
+        root = args.plots.resolve().parent
+        resolved = [(path.resolve(), record) for path, record in results]
+        for cls, lines in sample_findings(resolved, args.sample, args.seed, root).items():
+            print(f"\n## {cls} ({len(lines)} sampled)\n")
+            for line in lines:
+                print(line)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/core/adaptability_mirror.py b/core/adaptability_mirror.py
new file mode 100644
index 00000000000..29978afd866
--- /dev/null
+++ b/core/adaptability_mirror.py
@@ -0,0 +1,129 @@
+"""Build the single-file mirror of the adaptability checker for the workflow runner.
+
+The pipeline runs its helper scripts from a copy under `$RUNNER_TEMP` with the runner's
+system Python, where `core` is not importable (the pattern of
+`automation/scripts/regen_gate.py`). `automation/scripts/adaptability_check.py` is
+therefore one file: the bodies of `core/spec_roles.py` and `core/adaptability.py`
+verbatim, behind one docstring and the union of their standard-library imports.
+`tests/unit/core/test_adaptability_mirror.py` fails when the file differs from what
+`build_mirror` produces, so a change to either module is followed by::
+
+    uv run python -m core.adaptability_mirror
+
+which rewrites the mirror (`--check` only compares, exit 1 on a difference).
+"""
+
+from __future__ import annotations
+
+import argparse
+import ast
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+SOURCES = (Path("core/spec_roles.py"), Path("core/adaptability.py"))
+MIRROR = Path("automation/scripts/adaptability_check.py")
+
+HEADER = '''#!/usr/bin/env python3
+"""The adaptability checker as one standard-library file, for the workflow runner.
+
+GENERATED by `uv run python -m core.adaptability_mirror` from core/spec_roles.py and
+core/adaptability.py; edit those modules, never this file. The module docstring of
+core/adaptability.py describes the rules and the record; this copy runs where `core`
+is not importable:
+
+    python3 adaptability_check.py check plots/<spec>/implementations/python/<library>.py
+    python3 adaptability_check.py report plots/
+
+tests/unit/core/test_adaptability_mirror.py keeps it identical to the build.
+"""
+'''
+
+
+def _split(path: Path) -> tuple[list[ast.Import | ast.ImportFrom], str]:
+    """A module's import statements (`__future__` and `core` imports dropped) and its body text.
+
+    The body starts after the last top-level import, so the module docstring and imports
+    are left out and every definition, comment and blank line after them is kept.
+    """
+    text = path.read_text(encoding="utf-8")
+    tree = ast.parse(text)
+    imports: list[ast.Import | ast.ImportFrom] = []
+    last = 0
+    for node in tree.body:
+        if isinstance(node, ast.Import | ast.ImportFrom):
+            last = node.end_lineno or node.lineno
+            module = node.module if isinstance(node, ast.ImportFrom) else None
+            if module == "__future__" or (module or "").split(".")[0] == "core":
+                continue
+            imports.append(node)
+        elif isinstance(node, ast.Expr) and isinstance(node.value, ast.Constant) and isinstance(node.value.value, str):
+            continue  # the module docstring
+        else:
+            break
+    body = "\n".join(text.splitlines()[last:]).strip("\n")
+    return imports, body
+
+
+def _name_order(name: str) -> tuple[int, str]:
+    """ruff's isort `order-by-type`: constants, then classes, then everything else."""
+    if name.isupper() and len(name) > 1:
+        return 0, name
+    if name[:1].isupper():
+        return 1, name
+    return 2, name
+
+
+def _merged_imports(nodes: Sequence[ast.Import | ast.ImportFrom]) -> list[str]:
+    """One `import x` line per module and one `from m import a, b` line per module, sorted as ruff sorts them."""
+    plain: set[str] = set()
+    froms: dict[str, set[str]] = {}
+    for node in nodes:
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                plain.add(alias.name if alias.asname is None else f"{alias.name} as {alias.asname}")
+        else:
+            names = froms.setdefault(node.module or "", set())
+            for alias in node.names:
+                names.add(alias.name if alias.asname is None else f"{alias.name} as {alias.asname}")
+    lines = [f"import {module}" for module in sorted(plain)]
+    for module in sorted(froms):
+        ordered = sorted(froms[module], key=lambda item: _name_order(item.split(" as ")[0]))
+        lines.append(f"from {module} import {', '.join(ordered)}")
+    return lines
+
+
+def build_mirror(root: Path = ROOT) -> str:
+    """The mirror's text: header, `__future__`, the merged imports, then each module's body in order."""
+    imports: list[ast.Import | ast.ImportFrom] = []
+    bodies: list[str] = []
+    for source in SOURCES:
+        module_imports, body = _split(root / source)
+        imports.extend(module_imports)
+        rule = "-" * (100 - len(source.as_posix()))
+        bodies.append(f"# --- {source.as_posix()} {rule}\n\n{body}")
+    head = HEADER.rstrip("\n") + "\n\nfrom __future__ import annotations\n\n" + "\n".join(_merged_imports(imports))
+    return "\n\n\n".join([head, *bodies]) + "\n"
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="python -m core.adaptability_mirror", description=__doc__)
+    parser.add_argument("--check", action="store_true", help="compare only; exit 1 when the mirror is stale")
+    args = parser.parse_args(argv)
+    text = build_mirror()
+    target = ROOT / MIRROR
+    if args.check:
+        current = target.read_text(encoding="utf-8") if target.exists() else ""
+        if current != text:
+            print(f"{MIRROR} is stale: run `uv run python -m core.adaptability_mirror`")
+            return 1
+        return 0
+    target.write_text(text, encoding="utf-8")
+    print(f"wrote {MIRROR}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/core/perturbation.py b/core/perturbation.py
new file mode 100644
index 00000000000..2b4c0096c27
--- /dev/null
+++ b/core/perturbation.py
@@ -0,0 +1,317 @@
+"""The perturbation smoke run's pure parts: perturbed tables and the mutated source.
+
+The static checker (`core/adaptability.py`) tests proxies; the smoke run tests the
+property itself (docs/concepts/adaptable-code.md, "Perturbation smoke run"): it
+replaces the `# Data` block with other tables, rewrites the column constants through
+their role comments, and runs the whole file. This module builds the tables from the
+sample `df` and the source text for each run; the runner that executes the file in
+the plotting environment, checks the PNGs on the canvas and looks for stale labels is
+the pipeline's (PR 2).
+
+`perturbations(df, columns, roles, shape)` returns, for a table, in this order:
+
+* `renamed`: every column renamed, one of them with spaces, a unit and a dot
+  (`"Value no. 1 (k EUR)"`), and every categorical column's values renamed
+  (`"Group 1"`, ...). `renames` maps each old column name to its new one, so columns no
+  spec role names (`# role: extra`) follow too; `retired` lists the old category values,
+  so the runner can find a text artist that still shows one.
+* `more_categories` and `fewer_categories`: one more value in every categorical column
+  (the rows of its last value copied under a new label, numbers scaled by 1.1), and one
+  fewer (the rows of its last value dropped), both within eight values and at least one;
+  left out for a table without categorical columns. A colour-driving role whose group
+  count the spec fixes (`fixed_group_count`: a split violin's two halves) keeps its groups.
+* `single_group`: only the rows of the colour-driving role's first value, when the spec
+  allows a single group (`single_group_allowed`).
+* `fewer_rows`: per value of the colour-driving role (or overall), the first
+  `max(2, ceil(n / 10))` rows.
+* `more_rows`: ten copies; copy k continues every numeric column past the sample's range
+  (k times the range plus one step), every datetime column past its last date, and
+  suffixes the values of the categorical columns. The colour-driving role's column keeps
+  its values, numeric codes included (groups 0 and 1 stay two groups).
+* `scaled`: every numeric column times 1,000 plus 100,000.
+
+A matrix (`df` a labeled square DataFrame) gets `renamed` (index and columns), `more`
+and `fewer` (one label added or dropped on both axes) and `scaled`. Generated and
+excluded specs have no table to perturb, and network specs are deferred: their block may
+bind a `nodes` table beside the edge list, whose identifiers must follow the perturbed
+endpoints, which comes with network eligibility (networks are not eligible for the agent in
+phase 1). There is no nullable-dtype perturbation: the agent's loader hands over float64
+with NaN (decision of 2026-10-23).
+
+`smoke_source(source, perturbation, data_path)` is the source to run: the block replaced
+by a `pandas.read_pickle` of the table and every column constant renamed through
+`perturbation.renames`.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+
+import numpy as np
+import pandas as pd
+
+from core.adaptability import replace_block, rewrite_columns
+from core.spec_roles import DataRole, Shape
+
+
+MAX_GROUPS = 8
+"""The palette's eight positions: no perturbation takes a categorical column past them."""
+ROW_FACTOR = 10
+SCALE = 1_000
+SHIFT = 100_000
+NEW_LABEL = "Added"
+_SINGLE_GROUP_WORDS = ("binary", "two ", "pair", "split", "both", "left/right", "versus", " vs")
+
+
+@dataclass(frozen=True)
+class Perturbation:
+    """One table to run the file on: the column each role binds in it, the column renames, the retired labels."""
+
+    name: str
+    description: str
+    df: pd.DataFrame
+    columns: dict[str, str | list[str]]
+    retired: frozenset[str] = field(default_factory=frozenset)
+    renames: dict[str, str] = field(default_factory=dict)
+    """Old column name -> new one, for every renamed column (spec roles and extras alike)."""
+
+
+def fixed_group_count(roles: Sequence[DataRole], color_role: str | None) -> bool:
+    """The spec fixes how many groups its colour-driving role has.
+
+    A boolean role, or one whose description says so ("binary", "two", "pair", "split", "both",
+    "versus"): a split violin or a two-sample comparison needs exactly its two groups.
+    """
+    role = next((role for role in roles if role.name == color_role), None)
+    if role is None:
+        return False
+    if "boolean" in role.kinds:
+        return True
+    text = f" {role.description.lower()} "
+    return any(word in text for word in _SINGLE_GROUP_WORDS)
+
+
+def single_group_allowed(roles: Sequence[DataRole], shape: Shape, color_role: str | None) -> bool:
+    """The single-group perturbation runs on a table whose colour-driving role can hold one value."""
+    return shape == "table" and color_role is not None and not fixed_group_count(roles, color_role)
+
+
+def perturbations(
+    df: pd.DataFrame,
+    columns: Mapping[str, str | Sequence[str]],
+    roles: Sequence[DataRole],
+    shape: Shape,
+    color_role: str | None = None,
+) -> list[Perturbation]:
+    """The perturbed tables for the sample `df`, whose role columns `columns` names (role -> column).
+
+    Empty for a generated, excluded or network spec (the module docstring says why networks wait).
+    """
+    if shape in ("generated", "excluded", "network"):
+        return []
+    if shape == "matrix":
+        return _matrix_perturbations(df, columns)
+    role_columns: dict[str, str | list[str]] = {
+        role: name if isinstance(name, str) else list(name) for role, name in columns.items()
+    }
+    color_value = role_columns.get(color_role) if color_role else None
+    color_column = color_value if isinstance(color_value, str) else None
+    categorical = [name for name in df.columns if _is_categorical(df[name])]
+    fixed = color_column if color_column is not None and fixed_group_count(roles, color_role) else None
+    varied = [name for name in categorical if name != fixed]
+    out = [_renamed(df, role_columns, categorical)]
+    for changed in (_more_categories(df, role_columns, varied), _fewer_categories(df, role_columns, varied)):
+        if len(changed.df) != len(df):  # a table without categorical columns has no categories to change
+            out.append(changed)
+    if color_column is not None and single_group_allowed(roles, shape, color_role):
+        first = df[color_column].dropna().iloc[0] if df[color_column].notna().any() else None
+        single = df[df[color_column] == first].reset_index(drop=True)
+        out.append(
+            Perturbation("single_group", f"only the {color_column!r} value {first!r}", single, dict(role_columns))
+        )
+    out.append(_fewer_rows(df, role_columns, color_column))
+    out.append(_more_rows(df, role_columns, categorical, color_column))
+    out.append(_scaled(df, role_columns))
+    return out
+
+
+def _is_categorical(series: pd.Series) -> bool:
+    return bool(
+        isinstance(series.dtype, pd.CategoricalDtype)
+        or pd.api.types.is_object_dtype(series)
+        or pd.api.types.is_string_dtype(series)
+        or pd.api.types.is_bool_dtype(series)
+    )
+
+
+def _numeric(df: pd.DataFrame) -> list[str]:
+    return [
+        name
+        for name in df.columns
+        if pd.api.types.is_numeric_dtype(df[name]) and not pd.api.types.is_bool_dtype(df[name])
+    ]
+
+
+def _renamed_columns(df: pd.DataFrame) -> dict[str, str]:
+    """Every column renamed; the first numeric one gets spaces, a unit and a dot."""
+    numeric = _numeric(df)
+    unit_column = numeric[0] if numeric else (df.columns[0] if len(df.columns) else None)
+    mapping: dict[str, str] = {}
+    for index, name in enumerate(df.columns, start=1):
+        if name == unit_column:
+            mapping[name] = f"Value no. {index} (k EUR)"
+        else:
+            mapping[name] = f"Column {index} renamed"
+    return mapping
+
+
+def _remap(columns: Mapping[str, str | list[str]], mapping: Mapping[str, str]) -> dict[str, str | list[str]]:
+    out: dict[str, str | list[str]] = {}
+    for role, name in columns.items():
+        out[role] = mapping.get(name, name) if isinstance(name, str) else [mapping.get(item, item) for item in name]
+    return out
+
+
+def _renamed(df: pd.DataFrame, columns: Mapping[str, str | list[str]], categorical: list[str]) -> Perturbation:
+    table = df.copy()
+    retired: set[str] = set()
+    for name in categorical:
+        if pd.api.types.is_bool_dtype(table[name]):
+            continue
+        values = list(dict.fromkeys(table[name].dropna().tolist()))
+        taken = {str(value) for value in values}
+        relabel: dict[object, str] = {}
+        for position, value in enumerate(values, start=1):
+            label = f"{str(name).split(' ')[0].title()} {position}"
+            while label in taken:
+                label += "·"
+            relabel[value] = label
+        retired |= {str(value) for value in values}
+        table[name] = table[name].map(lambda value, relabel=relabel: relabel.get(value, value))
+    mapping = _renamed_columns(table)
+    return Perturbation(
+        "renamed",
+        "columns renamed (one with spaces, a unit and a dot) and category values renamed",
+        table.rename(columns=mapping),
+        _remap(columns, mapping),
+        frozenset(retired),
+        {str(old): new for old, new in mapping.items()},
+    )
+
+
+def _more_categories(df: pd.DataFrame, columns: Mapping[str, str | list[str]], categorical: list[str]) -> Perturbation:
+    table = df.copy()
+    for name in categorical:
+        if pd.api.types.is_bool_dtype(table[name]):
+            continue
+        values = list(dict.fromkeys(table[name].dropna().tolist()))
+        if not values or len(values) >= MAX_GROUPS:
+            continue
+        if isinstance(table[name].dtype, pd.CategoricalDtype):
+            table[name] = table[name].astype(object)  # a new label is no category of the old dtype
+        extra = table[table[name] == values[-1]].copy()
+        extra[name] = f"{NEW_LABEL} {name}"
+        for numeric in _numeric(extra):
+            extra[numeric] = extra[numeric] * 1.1
+        table = pd.concat([table, extra], ignore_index=True)
+    return Perturbation("more_categories", "one more value in every categorical column", table, dict(columns))
+
+
+def _fewer_categories(df: pd.DataFrame, columns: Mapping[str, str | list[str]], categorical: list[str]) -> Perturbation:
+    table = df.copy()
+    for name in categorical:
+        values = list(dict.fromkeys(table[name].dropna().tolist()))
+        if len(values) >= 2:
+            table = table[table[name] != values[-1]]
+    return Perturbation(
+        "fewer_categories", "one fewer value in every categorical column", table.reset_index(drop=True), dict(columns)
+    )
+
+
+def _fewer_rows(df: pd.DataFrame, columns: Mapping[str, str | list[str]], color_column: str | None) -> Perturbation:
+    keep = max(2, math.ceil(len(df) / ROW_FACTOR))
+    if color_column is not None and color_column in df.columns:
+        per_group = max(2, math.ceil(keep / max(1, df[color_column].nunique())))
+        table = df.groupby(color_column, sort=False, dropna=False).head(per_group)
+    else:
+        table = df.head(keep)
+    return Perturbation(
+        "fewer_rows",
+        f"about a tenth of the rows ({len(table)} of {len(df)})",
+        table.reset_index(drop=True),
+        dict(columns),
+    )
+
+
+def _more_rows(
+    df: pd.DataFrame, columns: Mapping[str, str | list[str]], categorical: list[str], color_column: str | None
+) -> Perturbation:
+    # the colour-driving column keeps its values: numeric group codes (0 and 1) must stay two groups
+    numeric = [name for name in _numeric(df) if name != color_column]
+    datetimes = [name for name in df.columns if pd.api.types.is_datetime64_any_dtype(df[name]) and name != color_column]
+    copies = [df.copy()]
+    for k in range(1, ROW_FACTOR):
+        part = df.copy()
+        for name in numeric:
+            values = part[name].astype(float)
+            span = float(values.max() - values.min()) if values.notna().any() else 0.0
+            step = float(np.nanmedian(np.diff(np.sort(values.dropna().unique())))) if values.nunique() > 1 else 1.0
+            part[name] = values + k * (span + step)
+        for name in datetimes:
+            stamps = part[name]
+            ordered = stamps.dropna().sort_values().unique()
+            gap = pd.Series(ordered).diff().median() if len(ordered) > 1 else pd.Timedelta(days=1)
+            part[name] = stamps + k * ((stamps.max() - stamps.min()) + gap)
+        for name in categorical:
+            if name == color_column or pd.api.types.is_bool_dtype(part[name]):
+                continue
+            part[name] = part[name].map(lambda value, k=k: value if pd.isna(value) else f"{value} {k + 1}")
+        copies.append(part)
+    table = pd.concat(copies, ignore_index=True)
+    return Perturbation("more_rows", f"{ROW_FACTOR} times the rows ({len(table)})", table, dict(columns))
+
+
+def _scaled(df: pd.DataFrame, columns: Mapping[str, str | list[str]]) -> Perturbation:
+    table = df.copy()
+    for name in _numeric(table):
+        table[name] = table[name].astype(float) * SCALE + SHIFT
+    return Perturbation("scaled", f"numbers times {SCALE:,} plus {SHIFT:,}", table, dict(columns))
+
+
+def _matrix_perturbations(df: pd.DataFrame, columns: Mapping[str, str | Sequence[str]]) -> list[Perturbation]:
+    roles = {role: name if isinstance(name, str) else list(name) for role, name in columns.items()}
+    labels = [str(label) for label in df.index]
+    relabel = {label: f"Item {position}" for position, label in enumerate(df.index, start=1)}
+    relabel.update(
+        {label: f"Item {position}" for position, label in enumerate(df.columns, start=1) if label not in relabel}
+    )
+    renamed = df.rename(index=relabel, columns=relabel)
+    # the column labels are the matrix's columns: a constant that names one (`# role: extra`) follows it
+    renames = {str(label): relabel[label] for label in df.columns}
+    out = [
+        Perturbation("renamed", "matrix labels renamed", renamed, _remap(roles, renames), frozenset(labels), renames)
+    ]
+    if len(df.index) < MAX_GROUPS and len(df.index) == len(df.columns):
+        bigger = df.copy().astype(float)
+        bigger.loc[NEW_LABEL] = bigger.iloc[-1] * 0.9
+        bigger[NEW_LABEL] = bigger.loc[:, bigger.columns[-1]] * 0.9
+        out.append(Perturbation("more_categories", "one more label on both axes", bigger, dict(roles)))
+    if len(df.index) > 2 and len(df.index) == len(df.columns):
+        out.append(
+            Perturbation("fewer_categories", "one fewer label on both axes", df.iloc[:-1, :-1].copy(), dict(roles))
+        )
+    out.append(
+        Perturbation("scaled", f"numbers times {SCALE:,} plus {SHIFT:,}", df.astype(float) * SCALE + SHIFT, dict(roles))
+    )
+    return out
+
+
+def smoke_source(source: str, perturbation: Perturbation, data_path: str) -> str:
+    """The source with its block replaced by a read of `data_path` (a pickle) and its column constants renamed.
+
+    Every column constant, `# role: extra` included, follows `perturbation.renames`.
+    """
+    block = f"import pandas as pd\n\ndf = pd.read_pickle({data_path!r})"
+    return rewrite_columns(replace_block(source, block), perturbation.renames)
diff --git a/core/render_identity.py b/core/render_identity.py
new file mode 100644
index 00000000000..4f4c35793ac
--- /dev/null
+++ b/core/render_identity.py
@@ -0,0 +1,126 @@
+"""Render identity: how much of a render changed between two PNGs of the same plot.
+
+A decoupling regeneration that only moves the data into the `# Data` block should
+render the same chart. `compare` measures that: the fraction of pixels whose color
+differs between two PNGs of equal size, and a verdict against a bound (default
+`DEFAULT_BOUND`, 0.5 % of the pixels, per theme). PNGs of different sizes are a
+failure, not a diff: the canvas changed, which `core/canvas.py` reports on its own.
+
+A pixel differs when any of its RGBA channels differs by more than `tolerance`
+(default 0: any change counts). Both images are compared in RGBA, so a palette PNG
+and an RGB PNG of the same picture are identical. PIL only.
+
+Usage as CLI (exit 0 within the bound, 1 over it or on a size change, 2 when a file
+cannot be read)::
+
+    python -m core.render_identity old/plot-light.png new/plot-light.png [--bound 0.005]
+    python -m core.render_identity --themes old_dir new_dir [--bound 0.005]
+
+`--themes` compares `plot-light.png` and `plot-dark.png` of the two directories and
+passes only when both themes do.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+from PIL import Image, ImageChops
+
+
+DEFAULT_BOUND = 0.005
+THEMES = ("light", "dark")
+
+
+@dataclass(frozen=True)
+class RenderIdentity:
+    """Two renders compared: their sizes, the share of differing pixels and the verdict against `bound`."""
+
+    old_size: tuple[int, int]
+    new_size: tuple[int, int]
+    differing: int
+    bound: float
+
+    @property
+    def same_size(self) -> bool:
+        return self.old_size == self.new_size
+
+    @property
+    def fraction(self) -> float | None:
+        """The share of differing pixels, None when the sizes differ."""
+        if not self.same_size:
+            return None
+        total = self.new_size[0] * self.new_size[1]
+        return self.differing / total if total else 0.0
+
+    @property
+    def passed(self) -> bool:
+        fraction = self.fraction
+        return fraction is not None and fraction <= self.bound
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "old_size": list(self.old_size),
+            "new_size": list(self.new_size),
+            "differing": self.differing,
+            "fraction": self.fraction,
+            "bound": self.bound,
+            "passed": self.passed,
+        }
+
+
+def differing_pixels(old: Image.Image, new: Image.Image, tolerance: int = 0) -> int:
+    """The number of pixels whose RGBA channels differ by more than `tolerance`; the images must have one size."""
+    if old.size != new.size:
+        raise ValueError(f"the images differ in size: {old.size} and {new.size}")
+    difference = ImageChops.difference(old.convert("RGBA"), new.convert("RGBA"))
+    red, green, blue, alpha = difference.split()
+    largest = ImageChops.lighter(ImageChops.lighter(red, green), ImageChops.lighter(blue, alpha))
+    histogram = largest.histogram()
+    return sum(histogram[tolerance + 1 :])
+
+
+def compare(old_path: Path, new_path: Path, *, bound: float = DEFAULT_BOUND, tolerance: int = 0) -> RenderIdentity:
+    """Compare two PNG files; raises OSError when one cannot be read."""
+    with Image.open(old_path) as old, Image.open(new_path) as new:
+        if old.size != new.size:
+            return RenderIdentity(old.size, new.size, 0, bound)
+        return RenderIdentity(old.size, new.size, differing_pixels(old, new, tolerance), bound)
+
+
+def compare_themes(
+    old_dir: Path, new_dir: Path, *, bound: float = DEFAULT_BOUND, tolerance: int = 0
+) -> dict[str, RenderIdentity]:
+    """`compare` for `plot-light.png` and `plot-dark.png` of two render directories."""
+    return {
+        theme: compare(old_dir / f"plot-{theme}.png", new_dir / f"plot-{theme}.png", bound=bound, tolerance=tolerance)
+        for theme in THEMES
+    }
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="python -m core.render_identity", description=__doc__)
+    parser.add_argument("old", type=Path)
+    parser.add_argument("new", type=Path)
+    parser.add_argument("--themes", action="store_true", help="the arguments are render directories")
+    parser.add_argument("--bound", type=float, default=DEFAULT_BOUND, help="largest passing share of pixels")
+    parser.add_argument("--tolerance", type=int, default=0, help="largest channel difference that is no change")
+    args = parser.parse_args(argv)
+    try:
+        if args.themes:
+            results = compare_themes(args.old, args.new, bound=args.bound, tolerance=args.tolerance)
+        else:
+            results = {"render": compare(args.old, args.new, bound=args.bound, tolerance=args.tolerance)}
+    except OSError as exc:
+        print(f"::error::render_identity cannot read a render: {exc}")
+        return 2
+    print(json.dumps({name: result.to_dict() for name, result in results.items()}))
+    return 0 if all(result.passed for result in results.values()) else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/agents/anyplot/data/roles.py b/core/spec_roles.py
similarity index 57%
rename from agents/anyplot/data/roles.py
rename to core/spec_roles.py
index af36d8cf8bc..0f2213c62fe 100644
--- a/agents/anyplot/data/roles.py
+++ b/core/spec_roles.py
@@ -1,10 +1,16 @@
-"""Data roles from a spec's stored `## Data` bullets.
+"""Data roles from a spec's stored `## Data` bullets, and the data shape they imply.
 
 The input is `Spec.data` (core/database/models.py): the `## Data` bullets as
 `automation/scripts/sync_to_postgres.py` stores them, one string per `- ` or `* `
 line with the marker stripped (nested bullets arrive flattened, continuation lines
-are lost). No ADK import. The parser never raises; a bullet it cannot read as a
-role is skipped.
+are lost); `data_bullets` extracts the same list from a `specification.md`. The
+parser never raises; a bullet it cannot read as a role is skipped.
+
+The module is shared by the agent (bindings, session state) and the adaptability
+checker (`core/adaptability.py`), and it uses the standard library only: the
+checker's single-file mirror, `automation/scripts/adaptability_check.py`, carries
+a verbatim copy of it for the workflow runner's system Python
+(`core/adaptability_mirror.py` builds that file).
 
 A role bullet starts with backticked names, optionally a parenthesised type, then
 a separator (`-`, `–`, `—` or `:`) and a description:
@@ -41,14 +47,38 @@
 variadic family so its members up to `<name>50` still fit, a leading `_` before a
 digit); a name without a letter or digit, or one already taken by an earlier
 bullet, is skipped, so names are unique.
+
+The data shape (`spec_shape`, docs/concepts/adaptable-code.md "Data shapes")
+decides what the adaptable form of an implementation holds, in this order:
+
+* `excluded`: the 13 map specs (`MAP_SPECS`), which fetch geometry over the network.
+* An entry of `SHAPE_OVERRIDES`: a spec whose role bullets misfile it, with the reason.
+* `network`: a role named `nodes` or `edges` (`STRUCTURE_ROLES`). `df` is the edge
+  list, a second `nodes` table holds node attributes.
+* `matrix`: a role whose name contains `matrix`. `df` is a labeled square DataFrame.
+* `generated`: no role carries a numeric, categorical, datetime or boolean kind (only
+  text or untyped roles: encoded text, puzzle grids). The block holds parameters.
+* `table`, the default: every role is a column of one table.
+
+The colour-driving role (`color_role`) is the first categorical or text role whose
+name is one of `COLOR_ROLE_NAMES` or whose description names a colour encoding
+(`COLOR_WORDS`). A spec without one is a single-series plot as far as the palette
+rule is concerned. The rule favours precision: a pie's `category` ("category
+labels") is not detected, so the palette rule stays lenient there.
 """
 
+from __future__ import annotations
+
 import re
+from collections.abc import Sequence
 from dataclasses import dataclass
 from typing import Literal
 
-from ..schemas import ROLE_PATTERN
 
+# A role is matched against the spec's `## Data` bullets later; the pattern only keeps
+# arbitrary text out. Digits and capitals are allowed because 21 of 325 specs name
+# roles such as `log2_fold_change`, `lower_95` or `temperature_K`.
+ROLE_PATTERN = r"^[A-Za-z_][A-Za-z0-9_]{0,31}$"
 
 RoleKind = Literal["numeric", "categorical", "datetime", "text", "boolean"]
 
@@ -292,3 +322,145 @@ def _clean_name(name: str, limit: int) -> str | None:
     if not any(char.isalnum() for char in clean):
         return None
     return clean if _ROLE_NAME.fullmatch(clean) else None
+
+
+# --- the `## Data` section of a specification.md ------------------------------------------
+
+_DATA_SECTION = re.compile(r"## Data\s*\n(.+?)(?=\n##|\Z)", re.DOTALL)
+
+
+def data_bullets(spec_markdown: str) -> list[str]:
+    """The `## Data` bullets of a `specification.md`, as `sync_to_postgres.py` stores them in `Spec.data`.
+
+    One string per line that starts with `- ` or `* ` once stripped, the marker removed;
+    an empty list when the spec has no `## Data` section.
+    """
+    match = _DATA_SECTION.search(spec_markdown)
+    if not match:
+        return []
+    bullets: list[str] = []
+    for line in match.group(1).strip().split("\n"):
+        line = line.strip()
+        if line.startswith(("- ", "* ")):
+            bullets.append(line[2:].strip())
+    return bullets
+
+
+# --- data shape ------------------------------------------------------------------------------
+
+Shape = Literal["table", "matrix", "network", "generated", "excluded"]
+SHAPES: tuple[Shape, ...] = ("table", "matrix", "network", "generated", "excluded")
+
+MAP_SPECS = frozenset(
+    {
+        "bubble-map-geographic",
+        "cartogram-area-distortion",
+        "choropleth-basic",
+        "contour-map-geographic",
+        "flowmap-origin-destination",
+        "heatmap-geographic",
+        "map-connection-lines",
+        "map-marker-clustered",
+        "map-projections",
+        "map-route-path",
+        "map-tile-background",
+        "map-tilegrid",
+        "scatter-map-geographic",
+    }
+)
+"""The 13 map specs: tagged both `plot_type: map` and `data_type: geospatial`. Their implementations
+pull basemaps, tiles or Natural Earth geometry over the network. `scatter-pitch-events` (a sports pitch
+tagged `map`) and `hexbin-map-geographic` (drawn from inline coordinates) are not on the list."""
+
+SHAPE_OVERRIDES: dict[str, tuple[Shape, str]] = {
+    "learning-curve-basic": ("matrix", "train_scores and validation_scores are per-fold score matrices"),
+    "pdp-basic": ("matrix", "the roles name a computed dependence and ICE curve matrix, not observations"),
+    "network-transport-static": ("network", "stations and routes are the node and edge tables"),
+    "upset-basic": ("table", "one row per element with its set memberships"),
+    "venn-labeled-items": ("table", "one row per item with the zone it falls in"),
+    "bifurcation-basic": ("generated", "a simulation of the logistic map over a parameter range"),
+    "chessboard-basic": ("generated", "rows and columns are the board size, not data columns"),
+    "curve-bias-variance-tradeoff": ("generated", "every curve follows from formulas over model complexity"),
+    "heatmap-mandelbrot": ("generated", "the roles are the window and iteration parameters of a fractal"),
+    "line-impurity-comparison": ("generated", "Gini and entropy curves computed from a probability grid"),
+    "line-tanabe-sugano": ("generated", "term energies computed from ligand-field formulas"),
+    "maze-circular": ("generated", "a maze generated from its ring count and seed"),
+    "maze-printable": ("generated", "a maze generated from its size and seed"),
+    "mohr-circle": ("generated", "three stress components define the circle"),
+    "psychrometric-basic": ("generated", "the chart's curves follow from psychrometric formulas"),
+    "tree-phylogenetic": ("generated", "the tree is encoded as a Newick string"),
+}
+"""Specs whose role bullets misfile them (docs/concepts/adaptable-code.md "Data shapes"), with the reason.
+heatmap-correlation and heatmap-clustered need no entry: their `matrix` roles already make them matrices, the
+lenient shape until a spec change retypes them as observations. An entry goes away when the spec pipeline
+retypes the roles so that the rule below files the spec correctly."""
+
+STRUCTURE_ROLES = frozenset({"nodes", "edges"})
+"""Roles that name a network's node or edge table rather than a column."""
+
+_DATA_KINDS = frozenset({"numeric", "categorical", "datetime", "boolean"})
+
+
+def spec_shape(spec_id: str, roles: Sequence[DataRole]) -> Shape:
+    """The data shape of `spec_id` with the parsed `roles` (the module docstring has the rule)."""
+    if spec_id in MAP_SPECS:
+        return "excluded"
+    if spec_id in SHAPE_OVERRIDES:
+        return SHAPE_OVERRIDES[spec_id][0]
+    names = [role.name.lower() for role in roles]
+    if any(name in STRUCTURE_ROLES for name in names):
+        return "network"
+    if any("matrix" in name for name in names):
+        return "matrix"
+    if roles and not any(kind in _DATA_KINDS for role in roles for kind in role.kinds):
+        return "generated"
+    return "table"
+
+
+def is_structure_role(role: DataRole, shape: Shape) -> bool:
+    """A role the shape satisfies without a column constant: a network's node or edge table, a matrix role."""
+    name = role.name.lower()
+    if shape == "network":
+        return name in STRUCTURE_ROLES or name in {"stations", "routes"}
+    if shape == "matrix":
+        return True
+    return False
+
+
+# --- colour-driving role ---------------------------------------------------------------------
+
+COLOR_ROLE_NAMES = frozenset(
+    {
+        "group",
+        "series",
+        "component",
+        "subcategory",
+        "split_group",
+        "fill_category",
+        "hue",
+        "color",
+        "colour",
+        "cluster",
+        "clusters",
+        "compound",
+        "branch",
+        "term",
+    }
+)
+"""Role names that colour the marks by their values: groups, series, stacked components, line identities. Not
+`symbol` or `cohort`: heatmap-periodic-table's element symbol and heatmap-cohort-retention's cohort label
+rows of a heatmap. Not `entity`: slope charts colour their lines by direction, not by entity."""
+COLOR_WORDS = re.compile(r"\b(?:colou?r(?:s|ed|ing)?|hue|legend|series|stacked|stacking|segments?)\b", re.IGNORECASE)
+"""Description words that name a colour encoding of a categorical role ("labels identifying each series",
+"Group identifier for color coding curves", "shown as stacked segments")."""
+_LABEL_KINDS = frozenset({"categorical", "text", "boolean"})
+
+
+def color_role(roles: Sequence[DataRole]) -> DataRole | None:
+    """The spec's colour-driving role, or None for a single-series plot (the module docstring has the rule)."""
+    for role in roles:
+        if not any(kind in _LABEL_KINDS for kind in role.kinds):
+            continue
+        if role.name.lower() in COLOR_ROLE_NAMES or COLOR_WORDS.search(role.description):
+            return role
+    return None
diff --git a/docs/concepts/adaptable-code.md b/docs/concepts/adaptable-code.md
index 8f948f1cec3..de6b1fea8eb 100644
--- a/docs/concepts/adaptable-code.md
+++ b/docs/concepts/adaptable-code.md
@@ -1,6 +1,6 @@
 # Adaptable catalogue code
 
-> **Status (2026-10-23):** PR 1 (the checker) is in progress; the rollout was revised on 2026-10-23 after a second opinion. Nothing is in the pipeline yet.
+> **Status (2026-10-23):** PR 1 (the checker, [#12244](https://github.com/MarkusNeusinger/anyplot/pull/12244)) is in progress; the rollout was revised on 2026-10-23 after a second opinion. Nothing is in the pipeline yet.
 
 This document describes how catalogue implementations become code that you can point at other data: one replaceable data block, columns named once, and plot code that derives everything else from the table. It covers the convention, the checks that enforce it, the pipeline changes, the rollout through a targeted conversion pass and the daily regeneration, and how the planned "Use with my data" agent ([Agent network design](agent-network.md)) uses the result.
 
diff --git a/docs/concepts/agent-network.md b/docs/concepts/agent-network.md
index 54b96184a1f..46bd80204d6 100644
--- a/docs/concepts/agent-network.md
+++ b/docs/concepts/agent-network.md
@@ -450,7 +450,7 @@ agents/anyplot/sub_agents/{adapter.py, reviewer.py}            # relative import
 agents/anyplot/tools/{session.py, catalogue.py}
 agents/anyplot/plugins/{ledger.py, scope_guard.py, budget.py, tool_safety.py}
 agents/anyplot/prompts/{root,adapter,reviewer,scope_judge,data_judge}.md  refusals.yaml
-agents/anyplot/data/{parse.py, roles.py, bindings.py, store.py}           # no ADK import; built
+agents/anyplot/data/{parse.py, bindings.py, store.py}           # no ADK import; built; the role parser lives in core/spec_roles.py
 agents/anyplot/code/{regions.py, normalise.py, readiness.py, edits.py, validate.py, loader.py, export.py}   # no ADK import; built
 agents/anyplot/render/{contract.py, gates.py, png.py, harness.py, serial.py, store.py, watermark.py, runtimes/python.py, backends/{remote.py, local.py, sandbox.py, fake.py}}
 agents/anyplot/render/fonts/{JetBrainsMono-Regular.ttf, JetBrainsMono-Bold.ttf, OFL.txt, README.md}   # SIL OFL 1.1, unmodified
diff --git a/docs/reference/repository.md b/docs/reference/repository.md
index 38d4af09c1d..5ff2a688db7 100644
--- a/docs/reference/repository.md
+++ b/docs/reference/repository.md
@@ -79,11 +79,16 @@ anyplot/
 │
 ├── core/                              # Shared business logic
 │   ├── __init__.py
+│   ├── adaptability.py                # Adaptability checker (adaptable-code convention)
+│   ├── adaptability_mirror.py         # Builds the checker's single-file mirror
 │   ├── canvas.py                      # Canvas gate + PNG auto-reject checks
 │   ├── config.py                      # Configuration (.env-based)
 │   ├── constants.py                   # Library metadata, constants
 │   ├── defects.py                     # Review feedback grammar (defect lines)
 │   ├── images.py                      # Image processing utilities
+│   ├── perturbation.py                # Perturbed tables for the smoke run
+│   ├── render_identity.py             # Pixel difference between two renders
+│   ├── spec_roles.py                  # Data roles, data shape and color role of a spec
 │   ├── utils.py                       # General utilities
 │   ├── database/                      # Database layer
 │   │   ├── __init__.py
@@ -136,8 +141,7 @@ anyplot/
 │       ├── settings.py                # AgentSettings (AGENT_* variables)
 │       ├── data/                      # Deterministic data handling, no ADK import
 │       │   ├── parse.py               # Pasted text -> canonical data.csv + DatasetProfile
-│       │   ├── roles.py               # Data roles from a spec's ## Data bullets
-│       │   ├── bindings.py            # Default role-to-column bindings and their checks
+│       │   ├── bindings.py            # Default role-to-column bindings and their checks (roles: core/spec_roles.py)
 │       │   └── store.py               # Session-scoped in-memory dataset store
 │       └── code/                      # Deterministic code handling, no ADK import
 │           ├── validate.py            # Two-profile AST validator: SECURITY and ADAPTATION
@@ -504,6 +508,11 @@ plt.savefig('plot.png', dpi=300)
 - `database/repositories.py` - Repository pattern for data access
 - `canvas.py` - Canvas gate (3200×1800 or 2400×2400 within ±16 px, the VQ-05 defect line) and the PNG auto-reject checks AR-04 and AR-07; `python -m core.canvas <png>` runs the gate
 - `defects.py` - Review feedback grammar: defect and suggestion lines, the criterion IDs, spec characteristics, and `format_defect`; `automation/scripts/regen_gate.py` keeps a parity-tested copy
+- `spec_roles.py` - Data roles from a spec's `## Data` bullets, the data shape (table, matrix, network, generated, excluded) and the color-driving role; shared by the agent and the adaptability checker
+- `adaptability.py` - Adaptability checker for Python implementations ([Adaptable catalogue code](../concepts/adaptable-code.md)): the record, the CQ-01 defect lines, and the block and constant substitution; `python -m core.adaptability report plots/` prints the catalogue baseline
+- `adaptability_mirror.py` - Builds `automation/scripts/adaptability_check.py`, the checker as one standard-library file; `uv run python -m core.adaptability_mirror` after a change to `adaptability.py` or `spec_roles.py`
+- `perturbation.py` - The perturbation smoke run's tables (renamed, more and fewer categories, one group, fewer and more rows, scaled values) and the source to run on each
+- `render_identity.py` - Share of differing pixels between two renders against a bound (0.5 % per theme); `python -m core.render_identity old.png new.png`
 
 ---
 
@@ -517,6 +526,7 @@ plt.savefig('plot.png', dpi=300)
 - `scripts/label_manager.py` - Label operations and transitions
 - `scripts/workflow_cli.py` - CLI interface for workflow steps
 - `scripts/regen_gate.py` - Regen gate: keeps or replaces a regeneration (used by impl-review.yml)
+- `scripts/adaptability_check.py` - The adaptability checker as one generated standard-library file for the workflow runner (wired into the pipeline by the adaptable-code rules PR)
 - `scripts/regen_writeback.py` - Stores a kept regeneration's re-score as the live implementation's review (used by impl-review.yml and impl-merge.yml)
 - `gcp/budget-guard/` - Cloud Run function that disables the Vertex AI API when its Cloud Billing budget is reached; a deploy unit, not a Python package (see [GCP budget guard](gcp-budget-guard.md))
 
diff --git a/tests/unit/agents/code/test_readiness.py b/tests/unit/agents/code/test_readiness.py
index dddfac59423..4c98843f8d9 100644
--- a/tests/unit/agents/code/test_readiness.py
+++ b/tests/unit/agents/code/test_readiness.py
@@ -6,9 +6,10 @@
 
 from agents.anyplot.code import readiness
 from agents.anyplot.code.normalise import normalise
-from agents.anyplot.code.readiness import MAP_SPECS, Readiness, scan
+from agents.anyplot.code.readiness import Readiness, scan
 from agents.anyplot.code.validate import Finding, validate_security
 from agents.anyplot.schemas import MAX_NOTE_CHARS
+from core.spec_roles import MAP_SPECS
 
 from .conftest import CATALOGUE_FILES, CATALOGUE_NORMALISED, source
 
diff --git a/tests/unit/agents/data/test_bindings.py b/tests/unit/agents/data/test_bindings.py
index 3462bd2d6fc..294cd0affb1 100644
--- a/tests/unit/agents/data/test_bindings.py
+++ b/tests/unit/agents/data/test_bindings.py
@@ -18,9 +18,9 @@
 )
 from agents.anyplot.data.parse import parse_dataset
 from agents.anyplot.data.prepare import Operation, apply_operations
-from agents.anyplot.data.roles import DataRole, RoleKind, parse_roles
 from agents.anyplot.schemas import Binding, ColumnDtype, DatasetProfile
-from tests.unit.agents.data.test_roles import AREA_STACKED, LINE_MULTI
+from core.spec_roles import DataRole, RoleKind, parse_roles
+from tests.unit.core.test_spec_roles import AREA_STACKED, LINE_MULTI
 
 
 OPERATIONS = TypeAdapter(list[Operation])
diff --git a/tests/unit/agents/data/test_computed.py b/tests/unit/agents/data/test_computed.py
index d38ad7dee5d..ebd448649b0 100644
--- a/tests/unit/agents/data/test_computed.py
+++ b/tests/unit/agents/data/test_computed.py
@@ -8,9 +8,9 @@
 from agents.anyplot.data.bindings import check_bindings, default_bindings
 from agents.anyplot.data.computed import ALIASES, COMPUTED_ROLES, name_match, window_line
 from agents.anyplot.data.parse import parse_dataset
-from agents.anyplot.data.roles import DataRole
 from agents.anyplot.dev_fixture import snapshot_from_repo
 from agents.anyplot.schemas import Binding
+from core.spec_roles import DataRole
 
 
 def roles_of(spec_id: str) -> list[DataRole]:
diff --git a/tests/unit/agents/data/test_parse.py b/tests/unit/agents/data/test_parse.py
index 3283d34fe40..8cb830e2d04 100644
--- a/tests/unit/agents/data/test_parse.py
+++ b/tests/unit/agents/data/test_parse.py
@@ -34,7 +34,6 @@
     without_context,
 )
 from agents.anyplot.data.prepare import Operation, apply_operations
-from agents.anyplot.data.roles import DataRole
 from agents.anyplot.opening import NOTES_INSTRUCTION_WARNING, NOTES_REFUSED_WARNING, NOTES_UNCHECKED_WARNING
 from agents.anyplot.schemas import (
     MAX_CELL_CHARS,
@@ -47,6 +46,7 @@
     MAX_TOP_VALUES,
     MAX_WARNINGS,
 )
+from core.spec_roles import DataRole
 
 
 # Named escapes keep invisible and combining characters visible in the source.
diff --git a/tests/unit/agents/data/test_signs.py b/tests/unit/agents/data/test_signs.py
index 16d141faa07..11a8375a0c7 100644
--- a/tests/unit/agents/data/test_signs.py
+++ b/tests/unit/agents/data/test_signs.py
@@ -13,9 +13,9 @@
 
 from agents.anyplot.data.bindings import check_bindings, default_bindings
 from agents.anyplot.data.parse import parse_dataset
-from agents.anyplot.data.roles import DataRole, parse_roles
 from agents.anyplot.data.signs import NON_NEGATIVE_ROLES, has_negative, is_non_negative, mark_non_negative
 from agents.anyplot.schemas import Binding, DatasetProfile
+from core.spec_roles import DataRole, parse_roles
 
 
 PLOTS = Path(__file__).resolve().parents[4] / "plots"
diff --git a/tests/unit/agents/evals/test_make_fixtures.py b/tests/unit/agents/evals/test_make_fixtures.py
index bdad9728a95..4d3fbf7ede8 100644
--- a/tests/unit/agents/evals/test_make_fixtures.py
+++ b/tests/unit/agents/evals/test_make_fixtures.py
@@ -9,13 +9,13 @@
 
 from agents.anyplot.data.bindings import check_bindings
 from agents.anyplot.data.parse import RESPELLED, parse_dataset
-from agents.anyplot.data.roles import parse_roles
 from agents.anyplot.dev_fixture import CASES_DIR, snapshot_from_repo
 from agents.anyplot.opening import assess
 from agents.anyplot.schemas import Binding
 from agents.anyplot.settings import AgentSettings
 from agents.evals import make_fixtures
 from agents.evals.make_fixtures import LIBRARIES, PERTURBATIONS, SMOKE_TAG, SPECS, case_id, render_cases
+from core.spec_roles import parse_roles
 
 
 CASE_KEYS = {"spec_id", "library", "locale", "perturbation", "bindings", "expected", "tags", "source"}
diff --git a/tests/unit/agents/runtime/test_data_questions.py b/tests/unit/agents/runtime/test_data_questions.py
index c40da1cf1f2..784f71fae55 100644
--- a/tests/unit/agents/runtime/test_data_questions.py
+++ b/tests/unit/agents/runtime/test_data_questions.py
@@ -19,7 +19,6 @@
 
 from agents.anyplot.data.parse import parse_dataset
 from agents.anyplot.data.query import MAX_QUERY_COLUMNS, MAX_QUERY_ROWS, run_query
-from agents.anyplot.data.roles import DataRole
 from agents.anyplot.dev_fixture import snapshot_from_repo
 from agents.anyplot.pipeline import (
     EXPECTED_HEADING,
@@ -47,6 +46,7 @@
 from agents.anyplot.settings import get_settings
 from agents.anyplot.tools.session import query_data, query_result, set_bindings
 from agents.main import Runtime, app, get_runtime
+from core.spec_roles import DataRole
 
 from .fakes import SCATTER_PLAN, VERDICT_OK, ScriptedLlm
 from .test_service_flow import (
diff --git a/tests/unit/agents/runtime/test_stream.py b/tests/unit/agents/runtime/test_stream.py
index c76b1f88887..baa31f3d996 100644
--- a/tests/unit/agents/runtime/test_stream.py
+++ b/tests/unit/agents/runtime/test_stream.py
@@ -10,7 +10,6 @@
 from agents.anyplot.data.generate import MAX_SERIES
 from agents.anyplot.data.parse import MAX_CONTEXT_CHARS, PREVIEW_ROWS
 from agents.anyplot.data.prepare import MAX_OPERATIONS
-from agents.anyplot.data.roles import TYPE_WORDS, DataRole
 from agents.anyplot.data.store import StoredDataset
 from agents.anyplot.dataset_versions import dataset_payload
 from agents.anyplot.language import MAX_LANGUAGE_CHARS
@@ -32,6 +31,7 @@
 )
 from agents.main import MAX_ROLE_DESCRIPTION_CHARS, AgentsError, _role_body, check_caller, decode_claims
 from agents.stream import MAX_DONE_EVENT_CHARS, MAX_DONE_ROLES, Translator, sse
+from core.spec_roles import TYPE_WORDS, DataRole
 
 
 def parse(chunk: str) -> tuple[str, dict]:
diff --git a/tests/unit/core/fixtures/adaptability/bar_grouped_matplotlib.py b/tests/unit/core/fixtures/adaptability/bar_grouped_matplotlib.py
new file mode 100644
index 00000000000..4138d5c6c00
--- /dev/null
+++ b/tests/unit/core/fixtures/adaptability/bar_grouped_matplotlib.py
@@ -0,0 +1,78 @@
+"""anyplot.ai
+bar-grouped: Grouped Bar Chart
+Library: matplotlib | Python 3.13
+Quality: pending | Created: 2026-10-23
+"""
+
+import os
+
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
+
+
+# Theme tokens
+THEME = os.getenv("ANYPLOT_THEME", "light")
+PAGE_BG = "#FAF8F1" if THEME == "light" else "#1A1A17"
+INK = "#1A1A17" if THEME == "light" else "#F0EFE8"
+INK_SOFT = "#4A4A44" if THEME == "light" else "#B8B7B0"
+
+# Imprint palette: all eight positions, one per group in order
+IMPRINT = ["#009E73", "#C475FD", "#4467A3", "#BD8233", "#AE3030", "#2ABCCD", "#954477", "#99B314"]
+
+# Constants
+NEAR_TIE = 0.05  # a gap below this share of the tallest bar counts as a near-tie
+
+# Columns: set these to your table's column names
+QUARTER = "Quarter"  # role: category
+PRODUCT_LINE = "Product line"  # role: group
+SALES = "Sales (thousand USD)"  # role: value
+
+# Data: replace this block with your own table, for example df = pd.read_csv("sales.csv")
+df = pd.DataFrame(
+    {
+        QUARTER: ["Q1", "Q2", "Q3", "Q4"] * 3,
+        PRODUCT_LINE: ["Electronics"] * 4 + ["Clothing"] * 4 + ["Home & Garden"] * 4,
+        SALES: [245, 312, 287, 425, 178, 195, 285, 310, 125, 210, 195, 165],
+    }
+)
+
+# Plot: reads only df and the constants above
+table = df.pivot_table(index=QUARTER, columns=PRODUCT_LINE, values=SALES, sort=False)
+values = table.to_numpy(dtype=float)
+x = np.arange(len(table.index))
+width = 0.8 / len(table.columns)
+top = np.nanmax(values)
+
+fig, ax = plt.subplots(figsize=(8, 4.5), dpi=400, facecolor=PAGE_BG)
+ax.set_facecolor(PAGE_BG)
+for i, line in enumerate(table.columns):
+    offset = (i - (len(table.columns) - 1) / 2) * width
+    ax.bar(x + offset, table[line], width, label=line, color=IMPRINT[i], edgecolor=INK_SOFT, linewidth=1.0)
+
+# Callout: the target is chosen by a rule over df and drawn only when the claim holds
+if len(table.columns) > 1:
+    ranked = np.sort(np.where(np.isnan(values), -np.inf, values), axis=1)
+    gaps = ranked[:, -1] - ranked[:, -2]
+    gaps = np.where(np.isfinite(gaps), gaps, np.inf)
+    tie = int(np.argmin(gaps))
+    if gaps[tie] <= NEAR_TIE * top:
+        ax.annotate(
+            f"Near-tie in {table.index[tie]}",
+            xy=(x[tie], ranked[tie, -1]),
+            xytext=(0, 14),
+            textcoords="offset points",
+            ha="center",
+            fontsize=8,
+            color=INK_SOFT,
+            style="italic",
+        )
+
+# Style
+ax.set_title("bar-grouped · python · matplotlib · anyplot.ai", fontsize=13, fontweight="bold", color=INK)
+ax.set_xticks(x, table.index)
+ax.set_xlabel(QUARTER, color=INK)
+ax.set_ylabel(SALES, color=INK)
+ax.set_ylim(0, top * 1.15)
+ax.legend(title=PRODUCT_LINE, fontsize=8)
+plt.savefig(f"plot-{THEME}.png", dpi=400, facecolor=PAGE_BG)
diff --git a/tests/unit/core/fixtures/adaptability/line_basic_seaborn.py b/tests/unit/core/fixtures/adaptability/line_basic_seaborn.py
new file mode 100644
index 00000000000..4f0b306936f
--- /dev/null
+++ b/tests/unit/core/fixtures/adaptability/line_basic_seaborn.py
@@ -0,0 +1,78 @@
+"""anyplot.ai
+line-basic: Basic Line Plot
+Library: seaborn | Python 3.13
+Quality: pending | Created: 2026-10-23
+"""
+
+import os
+
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
+import seaborn as sns
+
+
+# Theme tokens
+THEME = os.getenv("ANYPLOT_THEME", "light")
+PAGE_BG = "#FAF8F1" if THEME == "light" else "#1A1A17"
+ELEVATED_BG = "#FFFDF6" if THEME == "light" else "#242420"
+INK = "#1A1A17" if THEME == "light" else "#F0EFE8"
+INK_SOFT = "#4A4A44" if THEME == "light" else "#B8B7B0"
+BRAND = "#009E73"
+ACCENT = "#C475FD"
+
+sns.set_theme(
+    style="ticks",
+    rc={
+        "figure.facecolor": PAGE_BG,
+        "axes.facecolor": PAGE_BG,
+        "axes.edgecolor": INK_SOFT,
+        "axes.labelcolor": INK,
+        "text.color": INK,
+        "xtick.color": INK_SOFT,
+        "ytick.color": INK_SOFT,
+    },
+)
+
+# Columns: set these to your table's column names
+MONTH = "Month"  # role: x
+TEMPERATURE = "Temperature (°C)"  # role: y
+
+# Data: monthly temperatures over five years; seaborn draws the mean and a 95 % interval
+np.random.seed(42)
+months = np.tile(np.arange(1, 13), 5)
+seasonal = 15 + 12 * np.sin((months - 4) * np.pi / 6)
+df = pd.DataFrame({MONTH: months, TEMPERATURE: seasonal + np.random.randn(months.size) * 2.5})
+
+# Plot: reads only df and the constants above
+means = df.groupby(MONTH, sort=True)[TEMPERATURE].mean()
+peak = means.idxmax()
+
+fig, ax = plt.subplots(figsize=(16, 9), dpi=200, facecolor=PAGE_BG)
+ax.set_facecolor(PAGE_BG)
+sns.lineplot(
+    data=df,
+    x=MONTH,
+    y=TEMPERATURE,
+    ax=ax,
+    linewidth=3,
+    color=BRAND,
+    marker="o",
+    markersize=12,
+    errorbar=("ci", 95),
+    err_kws={"alpha": 0.20},
+    label="Mean with 95 % interval",
+)
+ax.scatter(
+    [peak], [means[peak]], color=ACCENT, s=300, zorder=5, edgecolors=PAGE_BG, linewidth=2.5, label=f"Peak: {peak}"
+)
+
+# Style
+ax.set_title("line-basic · python · seaborn · anyplot.ai", fontsize=24, fontweight="medium", color=INK)
+ax.tick_params(axis="both", labelsize=16, colors=INK_SOFT)
+ax.yaxis.grid(True, alpha=0.10, linewidth=0.8)
+ax.spines[["top", "right"]].set_visible(False)
+legend = ax.legend(fontsize=16, framealpha=1.0)
+legend.get_frame().set_facecolor(ELEVATED_BG)
+legend.get_frame().set_edgecolor(INK_SOFT)
+plt.savefig(f"plot-{THEME}.png", dpi=200, facecolor=PAGE_BG)
diff --git a/tests/unit/core/test_adaptability.py b/tests/unit/core/test_adaptability.py
new file mode 100644
index 00000000000..e97829ae1bc
--- /dev/null
+++ b/tests/unit/core/test_adaptability.py
@@ -0,0 +1,907 @@
+"""Tests for core/adaptability.py: every rule, every ignore class and every false-positive class of the design.
+
+The design is docs/concepts/adaptable-code.md ("The checks"). Each test builds a small
+source around a template that passes every rule, changes one thing, and asserts the
+rule class that fires (or that nothing does, for a false-positive class).
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import textwrap
+from pathlib import Path
+
+import pytest
+
+from core import adaptability
+from core.adaptability import (
+    CANONICAL_IMPRINT,
+    CRITICAL_VALUES,
+    RULE_CLASSES,
+    SETUP_CALLS,
+    Finding,
+    Record,
+    check_file,
+    check_source,
+    format_report,
+    main,
+    replace_block,
+    rewrite_columns,
+    rewrite_constants,
+    run_report,
+    sample_findings,
+)
+from core.defects import DEFECT_RE, defect_ids, defect_target
+from core.palette import IMPRINT
+from core.spec_roles import Shape, parse_roles
+
+
+REPO_ROOT = Path(__file__).resolve().parents[3]
+PLOTS = REPO_ROOT / "plots"
+FIXTURES = Path(__file__).parent / "fixtures" / "adaptability"
+
+BAR_GROUPED = parse_roles(
+    [
+        "`category` (categorical) - Labels for each group of bars on the x-axis",
+        "`group` (categorical) - The different series being compared (creates side-by-side bars)",
+        "`value` (numeric) - Heights of the bars representing the measured quantity",
+    ]
+)
+SCATTER = parse_roles(["`x` (numeric) - horizontal", "`y` (numeric) - vertical"])
+
+HEAD = """\
+import os
+
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
+
+
+THEME = os.getenv("ANYPLOT_THEME", "light")
+PAGE_BG = "#FAF8F1" if THEME == "light" else "#1A1A17"
+INK = "#1A1A17" if THEME == "light" else "#F0EFE8"
+IMPRINT = ["#009E73", "#C475FD", "#4467A3", "#BD8233", "#AE3030", "#2ABCCD", "#954477", "#99B314"]
+
+QUARTER = "Quarter"  # role: category
+PRODUCT_LINE = "Product line"  # role: group
+SALES = "Sales (k USD)"  # role: value
+"""
+
+BLOCK = """
+# Data: quarterly sales
+df = pd.DataFrame(
+    {
+        QUARTER: ["Q1", "Q2", "Q3", "Q4"] * 3,
+        PRODUCT_LINE: ["Electronics"] * 4 + ["Clothing"] * 4 + ["Home & Garden"] * 4,
+        SALES: [245, 312, 287, 425, 178, 195, 285, 310, 125, 210, 195, 165],
+    }
+)
+
+# Plot
+"""
+
+PLOT = """\
+table = df.pivot_table(index=QUARTER, columns=PRODUCT_LINE, values=SALES, sort=False)
+x = np.arange(len(table.index))
+fig, ax = plt.subplots(figsize=(8, 4.5), dpi=400, facecolor=PAGE_BG)
+for i, line in enumerate(table.columns):
+    ax.bar(x + i * 0.2, table[line], 0.2, label=line, color=IMPRINT[i])
+ax.set_title("bar-grouped · python · matplotlib · anyplot.ai", fontsize=13, color=INK)
+"""
+
+TAIL = 'plt.savefig(f"plot-{THEME}.png", dpi=400, facecolor=PAGE_BG)\n'
+
+
+def source(extra: str = "", *, head: str = HEAD, block: str = BLOCK, plot: str = PLOT) -> str:
+    """The passing template with `extra` plot code added before the output."""
+    return head + block + plot + textwrap.dedent(extra) + TAIL
+
+
+def check(code: str, roles=BAR_GROUPED, shape: Shape = "table", library: str | None = "matplotlib") -> Record:
+    return check_source(code, roles, shape, library=library)
+
+
+def found(record: Record, cls: str) -> list[Finding]:
+    return [finding for finding in record.findings if finding.cls == cls]
+
+
+def classes(record: Record) -> set[str]:
+    return {finding.cls for finding in record.findings}
+
+
+class TestTemplate:
+    def test_the_template_passes(self) -> None:
+        record = check(source())
+        assert record.findings == []
+        assert record.status == "pass"
+        assert record.constants == {"category": "QUARTER", "group": "PRODUCT_LINE", "value": "SALES"}
+        assert record.color_role == "group"
+        assert record.block == (17, 26)
+
+    @pytest.mark.parametrize(
+        ("fixture", "spec_id"), [("bar_grouped_matplotlib", "bar-grouped"), ("line_basic_seaborn", "line-basic")]
+    )
+    def test_the_converted_examples_pass(self, fixture: str, spec_id: str) -> None:
+        record = check_file(FIXTURES / f"{fixture}.py", PLOTS / spec_id / "specification.md", spec_id=spec_id)
+        assert record.findings == [], [finding.observed for finding in record.findings]
+        assert record.status == "pass"
+
+    def test_imprint_is_the_canonical_palette(self) -> None:
+        assert list(CANONICAL_IMPRINT) == IMPRINT
+
+    def test_the_agent_reads_the_same_critical_values(self) -> None:
+        from agents.anyplot.code import readiness
+
+        assert readiness.CRITICAL_VALUES is CRITICAL_VALUES
+
+
+class TestLayout:
+    def test_no_data_marker(self) -> None:
+        record = check(source(block=BLOCK.replace("# Data: quarterly sales\n", "")))
+        assert [f.observed for f in found(record, "layout")] == ["the file has no column-0 # Data marker"]
+        assert record.block is None
+
+    def test_no_plot_marker(self) -> None:
+        record = check(source(block=BLOCK.replace("# Plot\n", "")))
+        assert any("no column-0 # Plot marker" in f.observed for f in found(record, "layout"))
+        assert record.block is None
+
+    @pytest.mark.parametrize(
+        "marker",
+        ["# Data", "# Data:", "# Data: quarterly sales", "# Data - quarterly sales", "# Data — quarterly sales"],
+    )
+    def test_marker_forms(self, marker: str) -> None:
+        assert check(source(block=BLOCK.replace("# Data: quarterly sales", marker))).block == (17, 26)
+
+    @pytest.mark.parametrize("marker", ["# Data points", "# Data-driven callouts", "    # Data", "## Data", "# data"])
+    def test_not_a_marker(self, marker: str) -> None:
+        assert check(source(block=BLOCK.replace("# Data: quarterly sales", marker))).block is None
+
+    def test_a_marker_inside_a_string_is_no_marker(self) -> None:
+        code = source(block='NOTE = """\n# Data\n"""\n' + BLOCK.replace("# Data: quarterly sales\n", ""))
+        assert check(code).block is None
+
+    def test_two_data_markers(self) -> None:
+        code = source(block=BLOCK.replace("# Plot\n", "# Data: more\nextra = 1\n# Plot\n"))
+        assert any("second # Data block" in f.observed for f in found(check(code), "layout"))
+
+    def test_an_empty_block(self) -> None:
+        code = source(block="\n# Data\n# Plot\ndf = pd.DataFrame({QUARTER: [], PRODUCT_LINE: [], SALES: []})\n")
+        assert any("empty Data block" in f.observed for f in found(check(code), "layout"))
+
+    def test_the_block_must_end_by_binding_df(self) -> None:
+        code = source(block=BLOCK.replace("\n# Plot", "top = df[SALES].max()\n\n# Plot"))
+        observed = [f.observed for f in found(check(code), "layout")]
+        assert observed == ["ends the Data block with `top = df[SALES].max()`, not a statement that binds df"]
+
+    @pytest.mark.parametrize(
+        "last",
+        [
+            "df = df.sort_values(QUARTER)",
+            "df[QUARTER] = pd.Categorical(df[QUARTER], ordered=True)",
+            "df.loc[:, SALES] = df[SALES].astype(float)",
+            "df.reset_index(drop=True, inplace=True)",
+            "df: pd.DataFrame = df",
+        ],
+    )
+    def test_statements_that_bind_df(self, last: str) -> None:
+        code = source(block=BLOCK.replace("\n# Plot", f"{last}\n\n# Plot"))
+        assert found(check(code), "layout") == []
+
+    def test_a_generated_spec_needs_no_df(self) -> None:
+        code = source(block="\n# Data: QR content\ncontent = 'https://anyplot.ai'\n\n# Plot\n", plot="")
+        record = check(code, roles=parse_roles(["`content` (string) - text"]), shape="generated")
+        assert found(record, "layout") == []
+
+    @pytest.mark.parametrize(
+        "call", ["ax = plt.gca()", "sns.set_theme(style='white')", "colors = plt.cm.viridis(np.linspace(0, 1, 3))"]
+    )
+    def test_plotting_styling_and_setup_calls_inside_the_block(self, call: str) -> None:
+        head = HEAD.replace("import pandas as pd\n", "import pandas as pd\nimport seaborn as sns\n")
+        code = source(head=head, block=BLOCK.replace("df = pd.DataFrame(", f"{call}\ndf = pd.DataFrame(", 1))
+        assert any("inside the Data block" in f.observed for f in found(check(code), "layout"))
+
+    def test_a_data_helper_is_allowed_in_the_block(self) -> None:
+        head = HEAD.replace("import pandas as pd\n", "import pandas as pd\nimport seaborn as sns\n")
+        block = "\n# Data\ndf = sns.load_dataset('tips')\n\n# Plot\n"
+        assert found(check(source(head=head, block=block)), "layout") == []
+
+    def test_a_theme_token_inside_the_block(self) -> None:
+        code = source(block=BLOCK.replace("df = pd.DataFrame(", "edge = INK\ndf = pd.DataFrame(", 1))
+        assert any("theme token `INK`" in f.observed for f in found(check(code), "layout"))
+
+    def test_a_figure_created_above_the_block(self) -> None:
+        code = source(
+            head=HEAD + "fig, ax = plt.subplots()\n",
+            plot=PLOT.replace("fig, ax = plt.subplots(figsize=(8, 4.5), dpi=400, facecolor=PAGE_BG)\n", ""),
+        )
+        assert any("above the Data block" in f.observed for f in found(check(code), "layout"))
+
+    def test_a_drawing_call_above_the_block(self) -> None:
+        code = source(head=HEAD + "plt.figure()\nplt.axhline(0)\n")
+        assert any("calls `plt.figure` above the Data block" in f.observed for f in found(check(code), "layout"))
+
+    def test_the_sys_path_guard_and_seed_are_fine_in_the_head(self) -> None:
+        guard = "import sys\n\nsys.path = [p for p in sys.path if p]\nnp.random.seed(1)\n"
+        assert found(check(source(head=HEAD + guard)), "layout") == []
+
+
+SETUP_CASES = [(library, call) for library, calls in SETUP_CALLS.items() for call in calls]
+SETUP_IMPORTS = {
+    "matplotlib": "import matplotlib\nimport matplotlib.pyplot\n",
+    "seaborn": "import seaborn\n",
+    "plotly": "import plotly.io\n",
+    "altair": "import altair\n",
+    "plotnine": "import plotnine\n",
+    "bokeh": "import bokeh.io\nimport bokeh.plotting\n",
+    "lets_plot": "import lets_plot\n",
+}
+
+
+class TestHeadSetupAllowlist:
+    """The false-positive class "head setup calls": every allowlisted call passes in its library's head."""
+
+    @pytest.mark.parametrize(("library", "call"), SETUP_CASES)
+    def test_each_entry_is_allowed_in_the_head(self, library: str, call: str) -> None:
+        module = call.split(".")[0]
+        head = HEAD + SETUP_IMPORTS.get(module, f"import {module}\n") + f"{call}()\n"
+        record = check(source(head=head), library=library)
+        assert found(record, "layout") == [], (call, [f.observed for f in record.findings])
+
+    @pytest.mark.parametrize(("library", "call"), SETUP_CASES)
+    def test_each_entry_is_a_finding_inside_the_block(self, library: str, call: str) -> None:
+        module = call.split(".")[0]
+        head = HEAD + SETUP_IMPORTS.get(module, f"import {module}\n")
+        block = BLOCK.replace("df = pd.DataFrame(", f"{call}()\ndf = pd.DataFrame(", 1)
+        assert any(
+            "inside the Data block" in f.observed
+            for f in found(check(source(head=head, block=block), library=library), "layout")
+        )
+
+    def test_lets_plot_setup_html_through_a_star_import(self) -> None:
+        head = HEAD + "from lets_plot import *\n\nLetsPlot.setup_html()\n"
+        assert found(check(source(head=head), library="letsplot"), "layout") == []
+
+    def test_another_library_s_setup_call_is_a_finding(self) -> None:
+        head = HEAD + "import seaborn as sns\n\nsns.set_theme()\n"
+        assert found(check(source(head=head), library="matplotlib"), "layout")
+
+
+class TestColumns:
+    def test_missing_constants(self) -> None:
+        head = HEAD.replace('SALES = "Sales (k USD)"  # role: value\n', 'SALES = "Sales (k USD)"\n')
+        observed = [f.observed for f in found(check(source(head=head)), "columns")]
+        assert observed == ["has no column constant for the required role `value`"]
+
+    def test_an_unknown_role(self) -> None:
+        head = HEAD + 'REGION = "Region"  # role: region\n'
+        assert any("unknown role `region`" in f.observed for f in found(check(source(head=head)), "columns"))
+
+    def test_a_malformed_role_comment(self) -> None:
+        head = HEAD.replace("# role: value", "# role: value (sales)")
+        observed = [f.observed for f in found(check(source(head=head)), "columns")]
+        assert any("writes the role comment" in text for text in observed)
+
+    def test_a_value_that_is_not_a_string(self) -> None:
+        head = HEAD.replace('SALES = "Sales (k USD)"', "SALES = 3")
+        assert any("not a column-name string" in f.observed for f in found(check(source(head=head)), "columns"))
+
+    def test_a_duplicate_role(self) -> None:
+        head = HEAD + 'AMOUNT = "Amount"  # role: value\n'
+        assert any("already has" in f.observed for f in found(check(source(head=head)), "columns"))
+
+    def test_a_constant_below_the_marker(self) -> None:
+        block = BLOCK.replace("df = pd.DataFrame(", 'EXTRA = "Note"  # role: extra\ndf = pd.DataFrame(', 1)
+        assert any("below the # Data marker" in f.observed for f in found(check(source(block=block)), "columns"))
+
+    def test_extra_columns_are_allowed(self) -> None:
+        head = HEAD + 'VOLUME = "Volume"  # role: extra\nNOTE = "Note"  # role: extra\n'
+        assert found(check(source(head=head)), "columns") == []
+
+    def test_a_variadic_family_holds_a_list(self) -> None:
+        roles = parse_roles(["`x` (numeric) - time", "`y1, y2, ...` (numeric) - series"])
+        head = HEAD.split("QUARTER =")[0] + 'TIME = "Time"  # role: x\nSERIES = ["North", "South"]  # role: y\n'
+        block = '\n# Data\ndf = pd.DataFrame({TIME: [1, 2], "North": [3, 4], "South": [5, 6]})\n\n# Plot\n'
+        assert found(check(source(head=head, block=block, plot=""), roles=roles), "columns") == []
+        single = head.replace('["North", "South"]', '"North"')
+        assert found(check(source(head=single, block=block, plot=""), roles=roles), "columns")
+
+    def test_annotated_constants_and_palette(self) -> None:
+        """`QUARTER: str = "Quarter"  # role: category` is a constant like the plain form (Gemini review)."""
+        head = HEAD.replace('QUARTER = "Quarter"', 'QUARTER: str = "Quarter"').replace(
+            "IMPRINT = [", "IMPRINT: list[str] = ["
+        )
+        record = check(source(head=head))
+        assert record.findings == []
+        assert record.constants["category"] == "QUARTER"
+        assert 'QUARTER: str = "Region"  # role: category' in rewrite_constants(
+            source(head=head), {"category": "Region"}
+        )
+
+    def test_the_comment_may_sit_on_any_line_of_a_list(self) -> None:
+        roles = parse_roles(["`x` (numeric) - time", "`y1, y2, ...` (numeric) - series"])
+        head = (
+            HEAD.split("QUARTER =")[0]
+            + 'TIME = "Time"  # role: x\nSERIES = [  # role: y\n    "North",\n    "South",\n]\n'
+        )
+        block = '\n# Data\ndf = pd.DataFrame({TIME: [1, 2], "North": [3, 4], "South": [5, 6]})\n\n# Plot\n'
+        record = check(source(head=head, block=block, plot=""), roles=roles)
+        assert record.constants == {"x": "TIME", "y": "SERIES"}
+
+    def test_optional_and_computed_roles_are_not_required(self) -> None:
+        roles = parse_roles(
+            [
+                "`category` (categorical) - labels",
+                "`value` (numeric) - values",
+                "`label` (string, optional) - text",
+                "`rolling` (numeric) - Computed rolling average",
+            ]
+        )
+        head = HEAD.replace('PRODUCT_LINE = "Product line"  # role: group\n', "")
+        block = '\n# Data\ndf = pd.DataFrame({QUARTER: ["Q1"], SALES: [1]})\n\n# Plot\n'
+        assert found(check(source(head=head, block=block, plot=""), roles=roles), "columns") == []
+
+    def test_a_matrix_needs_no_constants(self) -> None:
+        roles = parse_roles(["`variables` (string) - names", "`correlation_matrix` (numeric) - matrix"])
+        head = HEAD.split("QUARTER =")[0]
+        block = (
+            '\n# Data\ndf = pd.DataFrame([[1.0, 0.5], [0.5, 1.0]], index=["a", "b"], columns=["a", "b"])\n\n# Plot\n'
+        )
+        assert found(check(source(head=head, block=block, plot=""), roles=roles, shape="matrix"), "columns") == []
+
+    def test_a_network_needs_constants_for_attributes_only(self) -> None:
+        roles = parse_roles(
+            ["`nodes` (list of dicts) - nodes", "`edges` (list of tuples) - edges", "`weight` (numeric)"]
+        )
+        head = HEAD.split("QUARTER =")[0]
+        block = '\n# Data\ndf = pd.DataFrame({"source": ["a"], "target": ["b"], "w": [1.0]})\n\n# Plot\n'
+        observed = [
+            f.observed
+            for f in found(check(source(head=head, block=block, plot=""), roles=roles, shape="network"), "columns")
+        ]
+        assert observed == ["has no column constant for the required role `weight`"]
+
+
+class TestInterface:
+    def test_a_block_name_read_below(self) -> None:
+        block = BLOCK.replace("df = pd.DataFrame(", 'groups = ["Electronics", "Clothing"]\ndf = pd.DataFrame(', 1)
+        observed = [f.observed for f in found(check(source(block=block, extra="print(groups)\n")), "interface")]
+        assert observed == ["reads `groups`, which the Data block binds"]
+
+    def test_rebinding_before_reading_is_fine(self) -> None:
+        block = BLOCK.replace("df = pd.DataFrame(", "x = 1\ndf = pd.DataFrame(", 1)
+        assert found(check(source(block=block)), "interface") == []  # the template rebinds x below
+
+    def test_loop_targets_parameters_and_comprehensions_shadow(self) -> None:
+        block = BLOCK.replace("df = pd.DataFrame(", "g = 1\nk = 2\nv = 3\ndf = pd.DataFrame(", 1)
+        extra = """\
+        for g in table.columns:
+            print(g)
+        labels = [k for k in table.index]
+        def fmt(v):
+            return f"{v:.0f}"
+        """
+        assert found(check(source(block=block, extra=extra)), "interface") == []
+
+    def test_a_function_reading_a_block_name(self) -> None:
+        block = BLOCK.replace("df = pd.DataFrame(", "scale = 2\ndf = pd.DataFrame(", 1)
+        extra = "def grow(value):\n    return value * scale\n"
+        assert [f.observed for f in found(check(source(block=block, extra=extra)), "interface")] == [
+            "reads `scale`, which the Data block binds"
+        ]
+
+    def test_an_import_inside_the_block_read_below(self) -> None:
+        block = BLOCK.replace("df = pd.DataFrame(", "from scipy import stats\ndf = pd.DataFrame(", 1)
+        assert found(check(source(block=block, extra="print(stats.norm)\n")), "interface")
+
+    def test_a_network_may_bind_nodes(self) -> None:
+        block = BLOCK.replace("df = pd.DataFrame(", 'nodes = pd.DataFrame({"id": ["a"]})\ndf = pd.DataFrame(', 1)
+        assert found(check(source(block=block, extra="print(nodes)\n"), shape="network"), "interface") == []
+        assert found(check(source(block=block, extra="print(nodes)\n")), "interface")
+
+    def test_a_generated_spec_reads_its_parameters(self) -> None:
+        block = "\n# Data\nsize = 21\n\n# Plot\n"
+        code = source(block=block, plot="print(size)\n")
+        assert found(check(code, roles=parse_roles(["`content` (string)"]), shape="generated"), "interface") == []
+
+    SCALE_BLOCK = BLOCK.replace("df = pd.DataFrame(", "scale = 2\ndf = pd.DataFrame(", 1)
+
+    @pytest.mark.parametrize(
+        "extra",
+        [
+            "if len(df) > 3:\n    scale = 1\nprint(scale)\n",  # only one branch rebinds
+            "for _ in range(len(df)):\n    scale = 1\nprint(scale)\n",  # the loop may run zero times
+            "while len(df) > 99:\n    scale = 1\nprint(scale)\n",
+            "try:\n    scale = 1 / len(df)\nexcept ZeroDivisionError:\n    print(scale)\n",  # the handler
+            "scale = 1\ndel scale\nprint(scale)\n",
+            "match len(df):\n    case 0:\n        scale = 1\nprint(scale)\n",
+            "scale *= 2\n",  # an augmented assignment reads its target first (Copilot, second round)
+        ],
+    )
+    def test_a_rebinding_on_some_paths_only(self, extra: str) -> None:
+        """Copilot: a conditional reassignment is no rebinding on the path where it does not run."""
+        assert [f.observed for f in found(check(source(block=self.SCALE_BLOCK, extra=extra)), "interface")] == [
+            "reads `scale`, which the Data block binds"
+        ]
+
+    @pytest.mark.parametrize(
+        "extra",
+        [
+            "if len(df) > 3:\n    scale = 1\nelse:\n    scale = 2\nprint(scale)\n",  # every branch rebinds
+            "for _ in range(3):\n    scale = 1\n    print(scale)\n",  # read inside the body, after the rebinding
+            "try:\n    scale = 1\nexcept ValueError:\n    scale = 2\nprint(scale)\n",
+            "with open(__file__) as scale:\n    print(scale)\n",
+            "scale = 1\nscale *= 2\nprint(scale)\n",  # the augmented target was already rebound
+        ],
+    )
+    def test_a_rebinding_on_every_path(self, extra: str) -> None:
+        assert found(check(source(block=self.SCALE_BLOCK, extra=extra)), "interface") == []
+
+
+class TestColumnAndSampleLiterals:
+    def test_a_column_name_below_the_block(self) -> None:
+        record = check(source(extra='ax.set_xlabel("Quarter")\n'))
+        assert [f.observed for f in found(record, "column-literal")] == ["types the column name 'Quarter'"]
+
+    def test_the_constant_is_fine(self) -> None:
+        assert found(check(source(extra="ax.set_xlabel(QUARTER)\n")), "column-literal") == []
+
+    def test_auto_labels_are_never_demanded(self) -> None:
+        """The false-positive class "auto-labels": no rule asks for set_xlabel when the library titles the axis."""
+        assert check(source()).findings == []
+
+    @pytest.mark.parametrize("field", ['"Sales (k USD):Q"', '"Sales (k USD):N"', '"Sales (k USD):O"'])
+    def test_an_altair_field_string_counts_as_the_column(self, field: str) -> None:
+        assert found(check(source(extra=f"encoding = {field}\n")), "column-literal")
+
+    def test_an_escaped_altair_field_counts_as_the_constant_it_escapes(self) -> None:
+        """The false-positive class "Altair field names": `"U\\\\.S\\\\. sales"` is the column `U.S. sales`."""
+        head = HEAD.replace('"Sales (k USD)"', '"U.S. sales"')
+        assert found(check(source(head=head, extra='y = "U\\\\.S\\\\. sales:Q"\n')), "column-literal")
+        escaped = 'y = SALES.replace(".", "\\\\.")\nchart_y = f"{y}:Q"\n'
+        assert found(check(source(head=head, extra=escaped)), "column-literal") == []
+
+    def test_a_sample_value_below_the_block(self) -> None:
+        record = check(source(extra='q3 = list(table.index).index("Q3")\n'))
+        assert [f.observed for f in found(record, "sample-literal")] == [
+            "uses the literal 'Q3', a value the Data block defines"
+        ]
+
+    def test_category_words_in_prose_are_fine(self) -> None:
+        """A label containing a sample value is prose; only an equal string is tied to the sample."""
+        extra = 'ax.text(0.5, 0.9, "Electronics led every quarter", transform=ax.transAxes)\n'
+        assert found(check(source(extra=extra)), "sample-literal") == []
+
+    @pytest.mark.parametrize("word", ["Total", "Other"])
+    def test_prose_words_equal_to_a_sample_value_are_fine(self, word: str) -> None:
+        block = BLOCK.replace('["Electronics"] * 4', f'["{word}"] * 4')
+        assert found(check(source(block=block, extra=f'ax.set_ylabel("{word}")\n')), "sample-literal") == []
+
+    def test_style_words_and_property_keys_are_fine(self) -> None:
+        block = BLOCK.replace(
+            "df = pd.DataFrame(", 'align = ["center", "left", "right"]\nstyle = {"size": 3}\ndf = pd.DataFrame(', 1
+        )
+        extra = 'marker = {"size": 7}\nposition = "center"\n'
+        assert found(check(source(block=block, extra=extra)), "sample-literal") == []
+
+    def test_one_character_values_are_fine(self) -> None:
+        block = BLOCK.replace('["Q1", "Q2", "Q3", "Q4"]', '["A", "B", "C", "D"]')
+        assert found(check(source(block=block, extra='path = "C"\n')), "sample-literal") == []
+
+    def test_style_keywords_are_ignored(self) -> None:
+        block = BLOCK.replace('["Q1", "Q2", "Q3", "Q4"]', '["upper left", "center", "o", "-"]')
+        extra = 'ax.legend(loc="upper left")\nax.plot([0], [0], marker="o", linestyle="-")\n'
+        assert found(check(source(block=block, extra=extra)), "sample-literal") == []
+
+    def test_the_title_and_the_output_are_ignored(self) -> None:
+        block = BLOCK.replace('["Q1", "Q2", "Q3", "Q4"]', '["plot-light.png", "Q2", "Q3", "Q4"]')
+        extra = 'ax.set_title("Q3 · bar-grouped · anyplot.ai")\nplt.savefig("plot-light.png")\n'
+        assert found(check(source(block=block, extra=extra)), "sample-literal") == []
+
+    def test_literals_inside_the_block_are_never_flagged(self) -> None:
+        assert check(source()).findings == []  # the template's block is full of literals
+
+    def test_record_field_names_are_fine(self) -> None:
+        block = BLOCK.replace("df = pd.DataFrame(", 'meta = {"id": 1, "color": "x"}\ndf = pd.DataFrame(', 1)
+        extra = 'rows = [{"id": 2}]\nkey = rows[0]["id"]\n'
+        assert found(check(source(block=block, extra=extra)), "sample-literal") == []
+
+
+class TestStatisticText:
+    def test_a_typed_statistic(self) -> None:
+        assert found(check(source(extra='ax.text(1, 2, "r = 0.87")\n')), "statistic-text")
+
+    def test_an_f_string_is_computed(self) -> None:
+        extra = 'r = df[SALES].corr(df[SALES])\nax.set_xlabel(f"r = {r:.2f}")\n'
+        assert found(check(source(extra=extra)), "statistic-text") == []
+
+    def test_it_is_advisory(self) -> None:
+        record = check(source(extra='label = "n = 180"\n'))
+        assert found(record, "statistic-text") and record.status == "pass"
+
+
+class TestDataCoordinates:
+    @pytest.mark.parametrize(
+        "line",
+        [
+            "ax.set_ylim(0, 500)",
+            "ax.set_xticks([1, 2, 3, 4])",
+            "ax.axhline(300)",
+            "ax.axvspan(1.5, 2.5)",
+            "ax.annotate('peak', xy=(3, 425))",
+            "ax.text(2, 410, 'note')",
+            "ax.set_xlim(0, 410)",
+            "ax.set_ylim(5, 80)",
+            "ax.set(ylim=(100, 450))",
+            "fig.update_layout(yaxis=dict(range=[100, 450]))",
+            "fig.update_layout(yaxis_range=[100, 450])",
+            "fig.add_hline(y=300)",
+            "scale = alt.Scale(domain=[100, 450])",
+            "scale = scale_y_continuous(limits=(100, 450))",
+            "rng = Range1d(100, 450)",
+            "span = Span(location=300)",
+            "ax.axvline(pd.Timestamp('2024-03-01'))",
+            "levels = ax.contour(table, levels=[100, 200, 300])",
+            "ax.hist(df[SALES], bins=[100, 200, 300, 400])",
+            "norm = Normalize(vmin=100, vmax=450)",
+        ],
+    )
+    def test_literal_coordinates(self, line: str) -> None:
+        assert found(check(source(extra=line + "\n")), "data-coordinate"), line
+
+    def test_an_attribute_assignment(self) -> None:
+        assert found(check(source(extra="p = object()\np.y_range.end = 450\n")), "data-coordinate")
+
+    @pytest.mark.parametrize(
+        "line",
+        [
+            "ax.set_ylim(0, df[SALES].max() * 1.1)",
+            "ax.set_xlim(-0.5, len(table.index) - 0.5)",
+            "ax.set_ylim(0, 1)",
+            "ax.set_ylim(0, 100)",
+            "ax.set_ylim(-0.05, 1.05)",
+            "ax.set_yticks([0, 25, 50, 75, 100])",
+            "ax.set_xticks(range(0, 361, 90))",
+            "ax.set_ylim(-1, 1)",
+            "ax.axhline(0)",
+            "ax.axhline(1.96)",
+            "ax.set_xticks(x, table.index, fontsize=8)",
+            "ax.annotate('peak', xy=(x[0], table.iloc[0, 0]), xytext=(0, 14), textcoords='offset points')",
+            "ax.annotate('peak', xy=(0.5, 0.9), xycoords='axes fraction')",
+            "ax.set_ylim(0, 105)",
+            "ax.set_xlim(-36, 396)",
+            "ax.text(0.02, 0.95, 'note', transform=ax.transAxes)",
+            "fig.text(0.5, 0.02, 'source')",
+            "fig.add_annotation(x=0.5, y=1.1, xref='paper', yref='paper', text='t')",
+            "scale = scale_size(range=(2, 12))",
+            "scale = alt.Scale(range=[50, 400])",
+            "jitter = np.random.default_rng(7).uniform(-0.2, 0.2, len(df))",
+            "low = df[SALES].mean() - 1.96 * df[SALES].std()",
+        ],
+    )
+    def test_ignored_positions(self, line: str) -> None:
+        """Style keywords, offsets in points, axes fractions, fixed domains, computed values, jitter sized from df."""
+        assert found(check(source(extra=line + "\n")), "data-coordinate") == [], line
+
+    def test_hidden_axes_place_a_drawing(self) -> None:
+        assert found(check(source(extra="ax.axis('off')\nax.set_xlim(-8.5, 8.5)\n")), "data-coordinate") == []
+
+    def test_it_is_advisory(self) -> None:
+        record = check(source(extra="ax.set_ylim(100, 450)\n"))
+        assert found(record, "data-coordinate") and record.status == "pass"
+
+    def test_without_a_block_the_whole_file_is_checked(self) -> None:
+        record = check(source(block=BLOCK.replace("# Plot\n", ""), extra="ax.set_ylim(100, 450)\n"))
+        assert found(record, "data-coordinate")
+
+
+class TestDfComparison:
+    def test_a_literal_selection(self) -> None:
+        record = check(source(extra='q3 = df[df[QUARTER] == "Q3"]\n'))
+        assert [f.observed for f in found(record, "df-comparison")] == ["compares df with the literal 'Q3'"]
+        assert record.status == "fail"
+
+    def test_through_one_alias(self) -> None:
+        record = check(source(extra='peak = "Q4"\nq4 = df[df[QUARTER] == peak]\n'))
+        assert [f.observed for f in found(record, "df-comparison")] == ["compares df with the literal peak = 'Q4'"]
+
+    def test_through_a_derived_name(self) -> None:
+        assert found(
+            check(source(extra="hit = [line for line in table.columns if line == 'Clothing']\n")), "df-comparison"
+        )
+
+    def test_isin(self) -> None:
+        assert found(check(source(extra='part = df[df[QUARTER].isin(["Q1", "Q2"])]\n')), "df-comparison")
+
+    @pytest.mark.parametrize(
+        "line",
+        [
+            "big = df[df[SALES] >= 300]",
+            "many = len(df) > 50",
+            "pos = df[df[SALES] > 0]",
+            "first = [i for i, _ in enumerate(table.columns) if i == 0]",
+            'NAMED = "Q3"\n',
+        ],
+    )
+    def test_thresholds_neutral_values_and_constants_are_fine(self, line: str) -> None:
+        assert found(check(source(extra=line + "\n")), "df-comparison") == [], line
+
+    def test_a_constants_threshold_is_fine(self) -> None:
+        head = HEAD.replace("QUARTER =", "# Constants\nHIGHLIGHT_ABOVE = 300\n\nQUARTER =")
+        assert found(check(source(head=head, extra="big = df[df[SALES] == HIGHLIGHT_ABOVE]\n")), "df-comparison") == []
+
+
+class TestCountLiterals:
+    @pytest.mark.parametrize(
+        "line",
+        ["ticks = range(12)", "ticks = np.arange(1, 13)", "top = df.head(12)[:12]", "grid = np.linspace(0, 1, 12)"],
+    )
+    def test_a_count_the_block_defines(self, line: str) -> None:
+        assert found(check(source(extra=line + "\n")), "count-literal"), line
+
+    @pytest.mark.parametrize(
+        "line", ["ticks = range(2)", "grid = np.linspace(0, 1, 200)", "ticks = range(len(df))", "ticks = range(7)"]
+    )
+    def test_small_resolution_computed_and_coincidental_counts_are_fine(self, line: str) -> None:
+        assert found(check(source(extra=line + "\n")), "count-literal") == [], line
+
+    def test_it_is_advisory(self) -> None:
+        record = check(source(extra="ticks = range(12)\n"))
+        assert found(record, "count-literal") and record.status == "pass"
+
+
+class TestPalette:
+    def test_a_short_palette_with_a_colour_role(self) -> None:
+        head = HEAD.replace(', "#BD8233", "#AE3030", "#2ABCCD", "#954477", "#99B314"', "")
+        observed = [f.observed for f in found(check(source(head=head)), "palette")]
+        assert observed == ["`IMPRINT` lists 3 of 8 positions"]
+
+    def test_out_of_order(self) -> None:
+        head = HEAD.replace('"#009E73", "#C475FD"', '"#009E73", "#4467A3"', 1).replace(
+            '"#4467A3", "#BD8233"', '"#C475FD", "#BD8233"'
+        )
+        assert [f.observed for f in found(check(source(head=head)), "palette")] == [
+            "`IMPRINT` lists the Imprint colors out of canonical order"
+        ]
+
+    def test_no_palette_for_a_required_colour_role(self) -> None:
+        head = HEAD.replace("IMPRINT = [", "BRANDS = [").replace('"#009E73", ', '"#123456", ', 1)
+        code = source(head=head, plot=PLOT.replace("IMPRINT[i]", "BRANDS[i]"))
+        assert [f.observed for f in found(check(code), "palette")] == [
+            "has no IMPRINT list while the spec's `group` role colors the marks"
+        ]
+
+    def test_an_optional_colour_role_may_go_unused(self) -> None:
+        roles = parse_roles(
+            ["`x` (numeric) - a", "`y` (numeric) - b", "`category` (categorical, optional) - for color coding"]
+        )
+        head = HEAD.split("IMPRINT =")[0] + 'BRAND = "#009E73"\nX = "x"  # role: x\nY = "y"  # role: y\n'
+        block = "\n# Data\ndf = pd.DataFrame({X: [1, 2], Y: [3, 4]})\n\n# Plot\n"
+        assert found(check(source(head=head, block=block, plot=""), roles=roles), "palette") == []
+
+    def test_a_single_series_plot_may_use_brand_alone(self) -> None:
+        head = HEAD.split("IMPRINT =")[0] + 'BRAND = "#009E73"\nX = "x"  # role: x\nY = "y"  # role: y\n'
+        block = "\n# Data\ndf = pd.DataFrame({X: [1, 2], Y: [3, 4]})\n\n# Plot\n"
+        record = check(source(head=head, block=block, plot="plt.scatter(df[X], df[Y], color=BRAND)\n"), roles=SCATTER)
+        assert record.color_role is None
+        assert found(record, "palette") == []
+
+    def test_a_short_palette_without_a_colour_role_is_fine(self) -> None:
+        head = HEAD.split("IMPRINT =")[0] + 'IMPRINT = ["#009E73", "#C475FD"]\nX = "x"  # role: x\nY = "y"  # role: y\n'
+        block = "\n# Data\ndf = pd.DataFrame({X: [1, 2], Y: [3, 4]})\n\n# Plot\n"
+        assert found(check(source(head=head, block=block, plot=""), roles=SCATTER), "palette") == []
+
+    def test_zip_strict_over_the_palette(self) -> None:
+        extra = "pairs = dict(zip(table.columns, IMPRINT, strict=True))\n"
+        assert [f.observed for f in found(check(source(extra=extra)), "palette")] == [
+            "zips the palette with strict=True, which raises for one more group"
+        ]
+
+    def test_zip_strict_over_a_slice_sized_from_df_is_fine(self) -> None:
+        extra = "pairs = dict(zip(table.columns, IMPRINT[: len(table.columns)], strict=True))\n"
+        assert found(check(source(extra=extra)), "palette") == []
+
+    def test_a_literal_slice(self) -> None:
+        assert any("fixed size" in f.observed for f in found(check(source(extra="colors = IMPRINT[:3]\n")), "palette"))
+
+    def test_a_slice_counted_from_df_is_fine(self) -> None:
+        assert found(check(source(extra="colors = IMPRINT[: len(table.columns)]\n")), "palette") == []
+
+
+class TestConstantsZone:
+    def zone(self, constants: str) -> str:
+        return HEAD.replace("QUARTER =", f"# Constants\n{constants}\n\nQUARTER =")
+
+    def test_hoisted_sample_categories(self) -> None:
+        record = check(source(head=self.zone('ORDER = ["Q1", "Q2", "Q3", "Q4"]')))
+        assert [f.observed for f in found(record, "constants")] == [
+            "lists sample values ('Q1', 'Q2', 'Q3', …) in # Constants"
+        ]
+        assert record.status == "pass"  # advisory
+
+    def test_hoisted_data_numbers(self) -> None:
+        assert found(check(source(head=self.zone("HEIGHTS = [245, 312, 287]"))), "constants")
+
+    def test_thresholds_and_semantic_maps_are_fine(self) -> None:
+        zone = 'RSI_LOW, RSI_HIGH = 30, 70\nTARGET = 300\nSEMANTIC = {"loss": "#AE3030"}'
+        assert found(check(source(head=self.zone(zone))), "constants") == []
+
+    def test_an_ordered_scale_the_block_spells_out_is_reported(self) -> None:
+        """The open question of the design: an ordered scale and hoisted categories look alike, so it is advisory."""
+        block = BLOCK.replace('["Q1", "Q2", "Q3", "Q4"] * 3', "WEEKDAYS[:4] * 3").replace("QUARTER: ", "QUARTER: ")
+        head = self.zone('WEEKDAYS = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]')
+        record = check(
+            source(head=head, block=block.replace("df = pd.DataFrame(", 'days = ["Mon", "Tue"]\ndf = pd.DataFrame(', 1))
+        )
+        assert found(record, "constants") and all(f.advisory for f in found(record, "constants"))
+
+
+class TestRecord:
+    def failing(self) -> Record:
+        head = HEAD.replace(', "#BD8233", "#AE3030", "#2ABCCD", "#954477", "#99B314"', "")
+        return check(
+            source(head=head, extra='ax.set_xlabel("Quarter")\nax.set_xlabel("Product line")\nax.set_ylim(100, 450)\n')
+        )
+
+    def test_status(self) -> None:
+        assert self.failing().status == "fail"
+        assert check(source()).status == "pass"
+        assert check(source(), shape="excluded").status == "excluded"
+        assert check("not python (", shape="excluded").findings == []
+
+    def test_a_syntax_error_is_a_layout_finding(self) -> None:
+        record = check("def broken(:\n")
+        assert record.status == "fail" and record.classes() == ["layout"]
+
+    def test_one_defect_line_per_class(self) -> None:
+        record = self.failing()
+        lines = record.defect_lines()
+        assert len(lines) == len(record.classes()) == 3
+        for line in lines:
+            assert DEFECT_RE.match(line), line
+            assert defect_ids(line) == ["CQ-01"]
+            assert line.startswith("CQ-01 (code): ")
+            assert defect_target(line)
+            assert "Likely cause:" in line
+
+    def test_a_defect_line_names_the_first_line_and_the_others(self) -> None:
+        line = next(line for line in self.failing().defect_lines() if "column name" in line)
+        assert re.search(r"line \d+ types the column name 'Quarter'; 1 more at lines \d+ →", line), line
+
+    def test_advisory_lines_are_marked(self) -> None:
+        line = next(line for line in self.failing().defect_lines() if "data coordinates" in line)
+        assert line.startswith("CQ-01 (code): (advisory) line ")
+
+    def test_to_dict(self) -> None:
+        payload = self.failing().to_dict()
+        assert set(payload) == {"version", "status", "shape", "color_role", "block", "constants", "findings", "lines"}
+        assert payload["block"] == {"start": 17, "end": 26}
+        assert json.loads(json.dumps(payload)) == payload
+        finding = payload["findings"][0]
+        assert set(finding) == {"rule", "class", "line", "observed", "cause", "advisory"}
+
+    def test_every_rule_class_has_a_rule_number_and_target(self) -> None:
+        assert sorted({rule.rule for rule in RULE_CLASSES.values()}) == [1, 2, 3, 4, 5, 6]
+        advisory = {cls for cls, rule in RULE_CLASSES.items() if rule.advisory}
+        assert advisory == {"data-coordinate", "statistic-text", "count-literal", "sample-literal", "constants"}
+
+
+class TestMutations:
+    def test_replace_block_keeps_the_markers(self) -> None:
+        code = replace_block(source(), "df = load_user_data()")
+        assert "# Data: quarterly sales\ndf = load_user_data()\n\n# Plot\n" in code
+        assert "Electronics" not in code
+        assert check(code).block is not None
+
+    def test_replace_block_without_a_block(self) -> None:
+        with pytest.raises(ValueError, match="no # Data"):
+            replace_block(source(block=BLOCK.replace("# Plot\n", "")), "df = 1")
+
+    def test_rewrite_constants(self) -> None:
+        code = rewrite_constants(source(), {"category": "Région", "value": 'Revenue "k" (€)', "unknown": "x"})
+        assert 'QUARTER = "Région"  # role: category' in code
+        assert 'SALES = "Revenue \\"k\\" (€)"  # role: value' in code
+        assert 'PRODUCT_LINE = "Product line"  # role: group' in code
+        assert check(code).constants == check(source()).constants
+
+    def test_rewrite_a_family(self) -> None:
+        code = 'A = "x"  # role: x\nB = ["one", "two"]  # role: y\n'
+        assert rewrite_constants(code, {"y": ["North", "South", "East"]}) == (
+            'A = "x"  # role: x\nB = ["North", "South", "East"]  # role: y\n'
+        )
+
+    def test_a_role_comment_inside_a_multiline_value_survives_twice(self) -> None:
+        """Copilot: replacing the whole span used to delete `# role: y` on the opening line."""
+        roles = parse_roles(["`x` (numeric) - time", "`y1, y2, ...` (numeric) - series"])
+        head = (
+            HEAD.split("QUARTER =")[0]
+            + 'TIME = "Time"  # role: x\nSERIES = [  # role: y\n    "North",\n    "South",\n]\n'
+        )
+        block = '\n# Data\ndf = pd.DataFrame({TIME: [1, 2], "North": [3, 4], "South": [5, 6]})\n\n# Plot\n'
+        code = source(head=head, block=block, plot="")
+        once = rewrite_constants(code, {"y": ["East", "West", "Up"]})
+        assert 'SERIES = ["East", "West", "Up"]  # role: y\n' in once
+        assert check(once, roles=roles).constants == {"x": "TIME", "y": "SERIES"}
+        twice = rewrite_constants(once, {"y": ["A", "B"]})
+        assert 'SERIES = ["A", "B"]  # role: y\n' in twice
+        assert found(check(twice, roles=roles), "columns") == []
+
+    def test_a_trailing_comment_after_the_moved_role_comment_is_kept(self) -> None:
+        code = 'S = [  # role: y\n    "a",\n]  # sample series\n'
+        out = rewrite_constants(code, {"y": ["b"]})
+        assert out == 'S = ["b"]  # role: y  # sample series\n'
+        assert rewrite_constants(out, {"y": ["c"]}) == 'S = ["c"]  # role: y  # sample series\n'
+
+    def test_rewrite_columns_renames_extras_by_their_old_name(self) -> None:
+        code = 'A = "Old A"  # role: x\nNOTE = "Note"  # role: extra\nRANK = "Rank"  # role: extra\nB = ["Note", "B"]  # role: y\n'
+        out = rewrite_columns(code, {"Old A": "New A", "Note": "Memo", "Rank": "Order"})
+        assert out == (
+            'A = "New A"  # role: x\nNOTE = "Memo"  # role: extra\nRANK = "Order"  # role: extra\n'
+            'B = ["Memo", "B"]  # role: y\n'
+        )
+        assert rewrite_columns(code, {}) == code
+
+
+class TestCatalogue:
+    def test_the_two_design_examples(self) -> None:
+        """docs/concepts/adaptable-code.md, "Two typical files"."""
+        bar = check_file(PLOTS / "bar-grouped/implementations/python/matplotlib.py")
+        assert {"layout", "columns", "interface", "sample-literal", "palette"} <= set(bar.classes())
+        assert any("'Q3'" in f.observed for f in found(bar, "sample-literal"))
+        line = check_file(PLOTS / "line-basic/implementations/python/seaborn.py")
+        assert {"columns", "interface", "column-literal", "df-comparison"} <= set(line.classes())
+        assert any("peak_month = 7" in f.observed for f in found(line, "df-comparison"))
+
+    def test_map_specs_are_excluded(self) -> None:
+        assert check_file(PLOTS / "choropleth-basic/implementations/python/plotly.py").status == "excluded"
+
+    def test_every_python_implementation_is_checked_without_an_error(self) -> None:
+        results = run_report(PLOTS)
+        assert len(results) > 2000
+        statuses = {record.status for _, record in results}
+        assert statuses <= {"pass", "fail", "excluded"}
+        for path, record in results:
+            for line in record.defect_lines():
+                assert DEFECT_RE.match(line), (path, line)
+        report = format_report(results)
+        assert "| **all** |" in report and "| 5 | palette |" in report
+        sample = sample_findings(results, 3, seed=1, root=REPO_ROOT)
+        assert set(sample) == set(RULE_CLASSES)
+
+
+class TestCli:
+    def test_check_exit_codes(self, capsys: pytest.CaptureFixture[str], tmp_path: Path) -> None:
+        out = tmp_path / "record.json"
+        spec = PLOTS / "bar-grouped" / "specification.md"
+        assert main(["check", str(FIXTURES / "bar_grouped_matplotlib.py"), "--spec", str(spec), "--out", str(out)]) == 0
+        assert json.loads(out.read_text())["status"] == "pass"
+        assert main(["check", str(PLOTS / "bar-grouped/implementations/python/matplotlib.py")]) == 1
+        printed = capsys.readouterr().out
+        assert "CQ-01 (code):" in printed
+        assert main(["check", str(tmp_path / "missing.py"), "--spec", str(spec)]) == 2
+
+    def test_report(self, capsys: pytest.CaptureFixture[str]) -> None:
+        assert main(["report", str(PLOTS), "--library", "pygal", "--sample", "2"]) == 0
+        printed = capsys.readouterr().out
+        assert "| pygal | 325 |" in printed
+        assert "## layout (2 sampled)" in printed
+
+    def test_report_json(self, capsys: pytest.CaptureFixture[str]) -> None:
+        assert main(["report", str(PLOTS), "--library", "pygal", "--json"]) == 0
+        rows = [json.loads(line) for line in capsys.readouterr().out.splitlines()]
+        assert len(rows) == 325 and all("status" in row for row in rows)
+
+
+def test_the_module_imports_only_the_standard_library_and_spec_roles() -> None:
+    import ast
+    import sys
+
+    tree = ast.parse(Path(adaptability.__file__).read_text(encoding="utf-8"))
+    modules = {
+        (node.module if isinstance(node, ast.ImportFrom) else alias.name).split(".")[0]
+        for node in tree.body
+        if isinstance(node, ast.Import | ast.ImportFrom)
+        for alias in node.names
+    }
+    assert modules - set(sys.stdlib_module_names) == {"core"}
diff --git a/tests/unit/core/test_adaptability_mirror.py b/tests/unit/core/test_adaptability_mirror.py
new file mode 100644
index 00000000000..2f9bf47a55e
--- /dev/null
+++ b/tests/unit/core/test_adaptability_mirror.py
@@ -0,0 +1,118 @@
+"""The single-file mirror `automation/scripts/adaptability_check.py` against `core/adaptability.py`.
+
+The workflow runner runs the checker from a copy with its system Python, where `core`
+is not importable (the pattern of `automation/scripts/regen_gate.py` and
+`tests/unit/core/test_defects.py`). The mirror is generated (`core/adaptability_mirror.py`):
+these tests pin the file to the build, keep it standard-library only, run it with `core`
+out of reach, and compare its records with the module's on a catalogue sample.
+"""
+
+from __future__ import annotations
+
+import ast
+import importlib.util
+import json
+import subprocess
+import sys
+from pathlib import Path
+from types import ModuleType
+
+import pytest
+
+from core import adaptability, spec_roles
+from core.adaptability_mirror import MIRROR, ROOT, SOURCES, build_mirror
+
+
+MIRROR_PATH = ROOT / MIRROR
+PLOTS = ROOT / "plots"
+
+
+def _load_mirror() -> ModuleType:
+    spec = importlib.util.spec_from_file_location("adaptability_check_mirror", MIRROR_PATH)
+    assert spec is not None and spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = module  # dataclasses resolve their annotations through sys.modules
+    spec.loader.exec_module(module)
+    return module
+
+
+@pytest.fixture(scope="module")
+def mirror() -> ModuleType:
+    return _load_mirror()
+
+
+def test_the_mirror_is_the_build() -> None:
+    """A change to core/spec_roles.py or core/adaptability.py needs `uv run python -m core.adaptability_mirror`."""
+    assert MIRROR_PATH.read_text(encoding="utf-8") == build_mirror(), (
+        "automation/scripts/adaptability_check.py is stale: run `uv run python -m core.adaptability_mirror`"
+    )
+
+
+def test_the_mirror_imports_only_the_standard_library() -> None:
+    tree = ast.parse(MIRROR_PATH.read_text(encoding="utf-8"))
+    modules = {
+        (node.module if isinstance(node, ast.ImportFrom) else alias.name).split(".")[0]
+        for node in ast.walk(tree)
+        if isinstance(node, ast.Import | ast.ImportFrom) and (not isinstance(node, ast.ImportFrom) or node.level == 0)
+        for alias in node.names
+    }
+    assert modules <= set(sys.stdlib_module_names) | {"__future__"}, modules - set(sys.stdlib_module_names)
+
+
+def _top_level_names(path: Path) -> list[str]:
+    names: list[str] = []
+    for node in ast.parse(path.read_text(encoding="utf-8")).body:
+        if isinstance(node, ast.FunctionDef | ast.ClassDef):
+            names.append(node.name)
+        elif isinstance(node, ast.Assign):
+            names.extend(target.id for target in node.targets if isinstance(target, ast.Name))
+        elif isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name):
+            names.append(node.target.id)
+    return names
+
+
+def test_every_definition_of_both_modules_is_in_the_mirror(mirror: ModuleType) -> None:
+    for module in (spec_roles, adaptability):
+        missing = [name for name in _top_level_names(Path(module.__file__ or "")) if not hasattr(mirror, name)]
+        assert not missing, (module.__name__, missing)
+
+
+def test_the_two_modules_share_no_top_level_name() -> None:
+    """The mirror concatenates them: a shared name would silently shadow the first module's definition."""
+    shared = set(_top_level_names(Path(spec_roles.__file__ or ""))) & set(
+        _top_level_names(Path(adaptability.__file__ or ""))
+    )
+    assert not shared, shared
+
+
+def test_the_sources_are_the_two_modules() -> None:
+    assert [source.as_posix() for source in SOURCES] == ["core/spec_roles.py", "core/adaptability.py"]
+
+
+@pytest.mark.skipif(not PLOTS.is_dir(), reason="plots/ is not checked out")
+def test_the_mirror_agrees_with_the_module_on_the_catalogue(mirror: ModuleType) -> None:
+    paths = sorted(PLOTS.glob("*/implementations/python/*.py"))[::7]
+    assert len(paths) > 300
+    for path in paths:
+        ours = adaptability.check_file(path).to_dict()
+        theirs = mirror.check_file(path).to_dict()
+        assert ours == theirs, path
+
+
+def test_the_mirror_runs_without_core(tmp_path: Path) -> None:
+    """`python -I` from a directory without `core`: the runner's situation."""
+    copy = tmp_path / "adaptability_check.py"
+    copy.write_text(MIRROR_PATH.read_text(encoding="utf-8"), encoding="utf-8")
+    impl = PLOTS / "bar-grouped/implementations/python/matplotlib.py"
+    result = subprocess.run(
+        [sys.executable, "-I", str(copy), "check", str(impl)],
+        cwd=tmp_path,
+        capture_output=True,
+        text=True,
+        timeout=120,
+        check=False,
+    )
+    assert result.returncode == 1, result.stderr
+    record = json.loads(result.stdout.splitlines()[0])
+    assert record == adaptability.check_file(impl).to_dict()
+    assert any(line.startswith("CQ-01 (code):") for line in result.stdout.splitlines()[1:])
diff --git a/tests/unit/core/test_perturbation.py b/tests/unit/core/test_perturbation.py
new file mode 100644
index 00000000000..ec97add6aa5
--- /dev/null
+++ b/tests/unit/core/test_perturbation.py
@@ -0,0 +1,245 @@
+"""Tests for core/perturbation.py: the perturbed tables and the source the smoke run executes."""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+import pytest
+
+from core.adaptability import check_source
+from core.perturbation import MAX_GROUPS, ROW_FACTOR, SCALE, SHIFT, perturbations, single_group_allowed, smoke_source
+from core.spec_roles import parse_roles
+
+
+FIXTURES = Path(__file__).parent / "fixtures" / "adaptability"
+ROLES = parse_roles(
+    [
+        "`category` (categorical) - Labels for each group of bars on the x-axis",
+        "`group` (categorical) - The different series being compared (creates side-by-side bars)",
+        "`value` (numeric) - Heights of the bars",
+    ]
+)
+COLUMNS = {"category": "Quarter", "group": "Product line", "value": "Sales (thousand USD)"}
+
+
+@pytest.fixture
+def sample() -> pd.DataFrame:
+    return pd.DataFrame(
+        {
+            "Quarter": ["Q1", "Q2", "Q3", "Q4"] * 3,
+            "Product line": ["Electronics"] * 4 + ["Clothing"] * 4 + ["Home & Garden"] * 4,
+            "Sales (thousand USD)": [245, 312, 287, 425, 178, 195, 285, 310, 125, 210, 195, 165],
+        }
+    )
+
+
+class TestTablePerturbations:
+    def test_the_set_and_its_order(self, sample: pd.DataFrame) -> None:
+        names = [item.name for item in perturbations(sample, COLUMNS, ROLES, "table", "group")]
+        assert names == [
+            "renamed",
+            "more_categories",
+            "fewer_categories",
+            "single_group",
+            "fewer_rows",
+            "more_rows",
+            "scaled",
+        ]
+
+    def test_the_sample_is_never_changed(self, sample: pd.DataFrame) -> None:
+        before = sample.copy()
+        perturbations(sample, COLUMNS, ROLES, "table", "group")
+        pd.testing.assert_frame_equal(sample, before)
+
+    def test_renamed(self, sample: pd.DataFrame) -> None:
+        item = perturbations(sample, COLUMNS, ROLES, "table", "group")[0]
+        names = list(item.df.columns)
+        assert not set(names) & set(sample.columns)
+        assert any(" " in name and "." in name and "(" in name for name in names)  # spaces, a unit and a dot
+        assert set(item.columns) == set(COLUMNS)
+        assert all(item.columns[role] in names for role in COLUMNS)
+        assert item.retired == frozenset({"Q1", "Q2", "Q3", "Q4", "Electronics", "Clothing", "Home & Garden"})
+        assert not set(item.df[item.columns["category"]]) & item.retired
+        assert len(item.df) == len(sample)
+
+    def test_more_and_fewer_categories_stay_within_eight(self, sample: pd.DataFrame) -> None:
+        items = {item.name: item for item in perturbations(sample, COLUMNS, ROLES, "table", "group")}
+        more, fewer = items["more_categories"].df, items["fewer_categories"].df
+        assert more["Quarter"].nunique() == 5 and more["Product line"].nunique() == 4
+        assert fewer["Quarter"].nunique() == 3 and fewer["Product line"].nunique() == 2
+        eight = pd.DataFrame(
+            {
+                "Quarter": [f"Q{i}" for i in range(MAX_GROUPS)],
+                "Product line": ["A"] * 8,
+                "Sales (thousand USD)": range(8),
+            }
+        )
+        grown = {i.name: i for i in perturbations(eight, COLUMNS, ROLES, "table", "group")}["more_categories"].df
+        assert grown["Quarter"].nunique() == MAX_GROUPS
+
+    def test_an_ordered_categorical_gains_a_label(self, sample: pd.DataFrame) -> None:
+        sample["Quarter"] = pd.Categorical(sample["Quarter"], ordered=True)
+        more = {i.name: i for i in perturbations(sample, COLUMNS, ROLES, "table", "group")}["more_categories"].df
+        assert more["Quarter"].nunique() == 5
+
+    def test_single_group(self, sample: pd.DataFrame) -> None:
+        single = {i.name: i for i in perturbations(sample, COLUMNS, ROLES, "table", "group")}["single_group"].df
+        assert set(single["Product line"]) == {"Electronics"} and len(single) == 4
+
+    def test_fewer_rows_keeps_every_group(self, sample: pd.DataFrame) -> None:
+        fewer = {i.name: i for i in perturbations(sample, COLUMNS, ROLES, "table", "group")}["fewer_rows"].df
+        assert len(fewer) < len(sample)
+        assert set(fewer["Product line"]) == set(sample["Product line"])
+
+    def test_more_rows_continues_dates_and_numbers(self) -> None:
+        df = pd.DataFrame(
+            {
+                "Date": pd.date_range("2024-01-01", periods=5, freq="D"),
+                "Price": [1.0, 2.0, 3.0, 4.0, 5.0],
+                "Group": ["a"] * 5,
+            }
+        )
+        roles = parse_roles(["`date` (datetime) - day", "`price` (numeric) - price", "`series` (categorical) - line"])
+        columns = {"date": "Date", "price": "Price", "series": "Group"}
+        more = {i.name: i for i in perturbations(df, columns, roles, "table", "series")}["more_rows"].df
+        assert len(more) == ROW_FACTOR * len(df)
+        assert more["Date"].is_unique and more["Date"].is_monotonic_increasing
+        assert more["Price"].is_monotonic_increasing
+        assert set(more["Group"]) == {"a"}  # the colour-driving role keeps its values
+
+    def test_scaled(self, sample: pd.DataFrame) -> None:
+        scaled = {i.name: i for i in perturbations(sample, COLUMNS, ROLES, "table", "group")}["scaled"].df
+        assert scaled["Sales (thousand USD)"].tolist() == [v * SCALE + SHIFT for v in sample["Sales (thousand USD)"]]
+
+    def test_no_category_perturbations_without_categorical_columns(self) -> None:
+        df = pd.DataFrame({"x": np.arange(10.0), "y": np.arange(10.0) ** 2})
+        roles = parse_roles(["`x` (numeric) - x", "`y` (numeric) - y"])
+        names = [item.name for item in perturbations(df, {"x": "x", "y": "y"}, roles, "table")]
+        assert names == ["renamed", "fewer_rows", "more_rows", "scaled"]
+
+    def test_generated_excluded_and_network_specs_have_none(self, sample: pd.DataFrame) -> None:
+        """A network block may bind `nodes` beside the edges; its smoke run waits for network eligibility (Copilot)."""
+        assert perturbations(sample, COLUMNS, ROLES, "generated") == []
+        assert perturbations(sample, COLUMNS, ROLES, "excluded") == []
+        assert perturbations(sample, COLUMNS, ROLES, "network", "group") == []
+
+    def test_a_fixed_two_group_column_keeps_its_groups(self) -> None:
+        """violin-split's binary halves stay two in every perturbation; the axis categories still vary (Copilot)."""
+        roles = parse_roles(
+            [
+                "`category` (string) - group labels for the x-axis",
+                "`value` (numeric) - values",
+                "`split_group` (string/binary) - binary grouping variable for left/right halves",
+            ]
+        )
+        df = pd.DataFrame(
+            {"Dept": ["A", "A", "B", "B", "C", "C"], "Salary": [1.0, 2.0, 3.0, 4.0, 5.0, 6.0], "Gender": ["F", "M"] * 3}
+        )
+        columns = {"category": "Dept", "value": "Salary", "split_group": "Gender"}
+        items = {item.name: item for item in perturbations(df, columns, roles, "table", "split_group")}
+        assert "single_group" not in items
+        for item in items.values():
+            assert item.df[item.columns["split_group"]].nunique() == 2, item.name
+        assert items["more_categories"].df["Dept"].nunique() == 4
+        assert items["fewer_categories"].df["Dept"].nunique() == 2
+
+    def test_numeric_group_codes_stay_groups_in_more_rows(self) -> None:
+        """Groups coded 0 and 1 are a valid binding; ten copies must not make twenty groups (Copilot)."""
+        roles = parse_roles(["`x` (numeric) - x", "`y` (numeric) - y", "`group` (categorical) - series"])
+        df = pd.DataFrame({"x": [1.0, 2.0, 1.0, 2.0], "y": [3.0, 4.0, 5.0, 6.0], "g": [0, 0, 1, 1]})
+        more = {i.name: i for i in perturbations(df, {"x": "x", "y": "y", "group": "g"}, roles, "table", "group")}
+        assert set(more["more_rows"].df["g"]) == {0, 1}
+        assert more["more_rows"].df["x"].nunique() == 2 * ROW_FACTOR
+
+
+class TestSingleGroupRule:
+    def test_a_free_group_role(self) -> None:
+        assert single_group_allowed(ROLES, "table", "group")
+
+    @pytest.mark.parametrize(
+        "bullet",
+        [
+            "`split_group` (string/binary) - binary grouping variable for left/right halves",
+            "`group` (categorical) - the two samples being compared",
+            "`group` (boolean) - treated or not",
+        ],
+    )
+    def test_a_role_that_fixes_its_groups(self, bullet: str) -> None:
+        roles = parse_roles(["`value` (numeric) - v", bullet])
+        assert not single_group_allowed(roles, "table", roles[1].name)
+
+    def test_no_colour_role_or_another_shape(self) -> None:
+        assert not single_group_allowed(ROLES, "table", None)
+        assert not single_group_allowed(ROLES, "matrix", "group")
+        assert not single_group_allowed(ROLES, "network", "group")
+
+
+class TestMatrix:
+    def test_matrix_perturbations_keep_it_square_without_a_fill(self) -> None:
+        labels = ["a", "b", "c"]
+        df = pd.DataFrame(np.eye(3), index=labels, columns=labels)
+        items = {item.name: item for item in perturbations(df, {}, [], "matrix")}
+        assert set(items) == {"renamed", "more_categories", "fewer_categories", "scaled"}
+        assert items["renamed"].retired == frozenset(labels)
+        assert items["more_categories"].df.shape == (4, 4)
+        assert not items["more_categories"].df.isna().to_numpy().any()
+        assert items["fewer_categories"].df.shape == (2, 2)
+
+    def test_an_extra_constant_naming_a_matrix_column_follows_the_rename(self) -> None:
+        """Copilot, second round: `FIRST = "a"  # role: extra` must become the renamed label, or df[FIRST] fails."""
+        labels = ["a", "b", "c"]
+        df = pd.DataFrame(np.eye(3), index=labels, columns=labels)
+        renamed = perturbations(df, {}, [], "matrix")[0]
+        assert renamed.renames == {"a": "Item 1", "b": "Item 2", "c": "Item 3"}
+        source = 'FIRST = "a"  # role: extra\n\n# Data\ndf = None\n\n# Plot\nprint(df[FIRST])\n'
+        constants = _string_constants(smoke_source(source, renamed, "/tmp/matrix.pkl"))
+        assert constants["FIRST"] == "Item 1" and constants["FIRST"] in renamed.df.columns
+
+
+class TestSmokeSource:
+    def test_the_block_is_replaced_and_the_constants_rewritten(self) -> None:
+        source = (FIXTURES / "bar_grouped_matplotlib.py").read_text(encoding="utf-8")
+        item = perturbations(
+            pd.DataFrame({"Quarter": ["Q1"], "Product line": ["A"], "Sales (thousand USD)": [1]}),
+            COLUMNS,
+            ROLES,
+            "table",
+            "group",
+        )[0]
+        code = smoke_source(source, item, "/tmp/table.pkl")
+        ast.parse(code)
+        assert "df = pd.read_pickle('/tmp/table.pkl')" in code
+        assert "Electronics" not in code
+        record = check_source(code, ROLES, "table", library="matplotlib")
+        assert record.findings == []
+        constants = _string_constants(code)
+        assert {constants[name] for name in record.constants.values()} == set(item.columns.values())
+
+    def test_extra_columns_follow_the_renames(self) -> None:
+        """`# role: extra` constants are not role-keyed; the renamed run must still rename them (Copilot)."""
+        source = (FIXTURES / "bar_grouped_matplotlib.py").read_text(encoding="utf-8")
+        source = source.replace(
+            'SALES = "Sales (thousand USD)"  # role: value\n',
+            'SALES = "Sales (thousand USD)"  # role: value\nNOTE = "Note"  # role: extra\nRANK = "Rank"  # role: extra\n',
+        )
+        sample = pd.DataFrame(
+            {"Quarter": ["Q1"], "Product line": ["A"], "Sales (thousand USD)": [1], "Note": ["n"], "Rank": [1]}
+        )
+        item = perturbations(sample, COLUMNS, ROLES, "table", "group")[0]
+        constants = _string_constants(smoke_source(source, item, "/tmp/table.pkl"))
+        assert {constants["NOTE"], constants["RANK"]} <= set(item.df.columns)
+        assert {constants["QUARTER"], constants["PRODUCT_LINE"], constants["SALES"]} <= set(item.df.columns)
+
+
+def _string_constants(code: str) -> dict[str, str]:
+    return {
+        node.targets[0].id: node.value.value
+        for node in ast.parse(code).body
+        if isinstance(node, ast.Assign)
+        and isinstance(node.targets[0], ast.Name)
+        and isinstance(node.value, ast.Constant)
+        and isinstance(node.value.value, str)
+    }
diff --git a/tests/unit/core/test_render_identity.py b/tests/unit/core/test_render_identity.py
new file mode 100644
index 00000000000..4e13aec46d9
--- /dev/null
+++ b/tests/unit/core/test_render_identity.py
@@ -0,0 +1,104 @@
+"""Tests for core/render_identity.py with synthetic images."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+from PIL import Image
+
+from core.render_identity import DEFAULT_BOUND, compare, compare_themes, differing_pixels, main
+
+
+SIZE = (200, 100)  # 20,000 pixels: 0.5 % is 100 pixels
+
+
+def png(path: Path, *, changed: int = 0, size: tuple[int, int] = SIZE, mode: str = "RGB", delta: int = 50) -> Path:
+    """A flat page-colored image with the first `changed` pixels (row-major) shifted by `delta` on red."""
+    image = Image.new("RGB", size, (250, 248, 241))
+    pixels = image.load()
+    assert pixels is not None
+    for index in range(changed):
+        x, y = index % size[0], index // size[0]
+        pixels[x, y] = (250 - delta, 248, 241)
+    if mode == "P":  # an adaptive palette keeps the exact colors; the default web palette would not
+        image = image.convert("P", palette=Image.Palette.ADAPTIVE)
+    elif mode != "RGB":
+        image = image.convert(mode)
+    image.save(path)
+    return path
+
+
+def test_identical_renders(tmp_path: Path) -> None:
+    result = compare(png(tmp_path / "a.png"), png(tmp_path / "b.png"))
+    assert result.fraction == 0.0 and result.passed and result.same_size
+
+
+def test_a_change_within_the_bound(tmp_path: Path) -> None:
+    result = compare(png(tmp_path / "a.png"), png(tmp_path / "b.png", changed=100))
+    assert result.differing == 100
+    assert result.fraction == pytest.approx(DEFAULT_BOUND)
+    assert result.passed
+
+
+def test_a_change_over_the_bound(tmp_path: Path) -> None:
+    result = compare(png(tmp_path / "a.png"), png(tmp_path / "b.png", changed=101))
+    assert result.differing == 101 and not result.passed
+
+
+def test_a_custom_bound(tmp_path: Path) -> None:
+    assert compare(png(tmp_path / "a.png"), png(tmp_path / "b.png", changed=400), bound=0.02).passed
+
+
+def test_a_size_change_is_a_failure_not_a_diff(tmp_path: Path) -> None:
+    result = compare(png(tmp_path / "a.png"), png(tmp_path / "b.png", size=(200, 101)))
+    assert not result.same_size and result.fraction is None and not result.passed
+    assert result.to_dict()["fraction"] is None
+
+
+def test_the_mode_does_not_matter(tmp_path: Path) -> None:
+    rgb, palette = png(tmp_path / "a.png"), png(tmp_path / "b.png", mode="P")
+    assert compare(rgb, palette).differing == 0
+    assert compare(rgb, png(tmp_path / "c.png", mode="RGBA")).differing == 0
+
+
+def test_tolerance(tmp_path: Path) -> None:
+    a, b = png(tmp_path / "a.png"), png(tmp_path / "b.png", changed=300, delta=2)
+    assert compare(a, b).differing == 300
+    assert compare(a, b, tolerance=2).differing == 0
+
+
+def test_differing_pixels_refuses_two_sizes() -> None:
+    with pytest.raises(ValueError, match="differ in size"):
+        differing_pixels(Image.new("RGB", (2, 2)), Image.new("RGB", (3, 2)))
+
+
+def test_both_themes(tmp_path: Path) -> None:
+    old, new = tmp_path / "old", tmp_path / "new"
+    old.mkdir()
+    new.mkdir()
+    for theme in ("light", "dark"):
+        png(old / f"plot-{theme}.png")
+    png(new / "plot-light.png")
+    png(new / "plot-dark.png", changed=500)
+    results = compare_themes(old, new)
+    assert results["light"].passed and not results["dark"].passed
+
+
+def test_cli(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    a, b, c = png(tmp_path / "a.png"), png(tmp_path / "b.png", changed=10), png(tmp_path / "c.png", changed=5000)
+    assert main([str(a), str(b)]) == 0
+    assert json.loads(capsys.readouterr().out)["render"]["differing"] == 10
+    assert main([str(a), str(c)]) == 1
+    capsys.readouterr()
+    assert main([str(a), str(tmp_path / "missing.png")]) == 2
+    old, new = tmp_path / "old", tmp_path / "new"
+    old.mkdir()
+    new.mkdir()
+    for theme in ("light", "dark"):
+        png(old / f"plot-{theme}.png")
+        png(new / f"plot-{theme}.png", changed=3)
+    capsys.readouterr()
+    assert main(["--themes", str(old), str(new)]) == 0
+    assert set(json.loads(capsys.readouterr().out)) == {"light", "dark"}
diff --git a/tests/unit/agents/data/test_roles.py b/tests/unit/core/test_spec_roles.py
similarity index 63%
rename from tests/unit/agents/data/test_roles.py
rename to tests/unit/core/test_spec_roles.py
index 65d1f0fd640..197cfd47d04 100644
--- a/tests/unit/agents/data/test_roles.py
+++ b/tests/unit/core/test_spec_roles.py
@@ -1,15 +1,27 @@
-"""Tests for agents/anyplot/data/roles.py: the `## Data` bullet grammar and a sweep over the catalogue."""
+"""Tests for core/spec_roles.py: the `## Data` bullet grammar, the data shape, the colour role, and catalogue sweeps."""
 
 import re
 from pathlib import Path
 
 import pytest
 
-from agents.anyplot.data.roles import MAX_ROLE_NAME_CHARS, MAX_VARIADIC_NAME_CHARS, DataRole, parse_roles, type_words
-from agents.anyplot.schemas import ROLE_PATTERN
-
-
-REPO_ROOT = Path(__file__).resolve().parents[4]
+from core.spec_roles import (
+    MAP_SPECS,
+    MAX_ROLE_NAME_CHARS,
+    MAX_VARIADIC_NAME_CHARS,
+    ROLE_PATTERN,
+    SHAPE_OVERRIDES,
+    DataRole,
+    color_role,
+    data_bullets,
+    is_structure_role,
+    parse_roles,
+    spec_shape,
+    type_words,
+)
+
+
+REPO_ROOT = Path(__file__).resolve().parents[3]
 PLOTS = REPO_ROOT / "plots"
 
 
@@ -284,3 +296,139 @@ def test_every_catalogue_spec_parses() -> None:
     "Size: 10-200 points per series, 2-6 series recommended",
     "Example: Monthly sales for 3 product lines, daily stock prices for 4 companies",
 ]
+
+
+def _spec_roles(spec_id: str) -> list[DataRole]:
+    return parse_roles(data_bullets((PLOTS / spec_id / "specification.md").read_text(encoding="utf-8")))
+
+
+class TestDataBullets:
+    def test_extracts_the_bullets_of_the_data_section(self) -> None:
+        text = "# t\n\n## Description\n\n- not data\n\n## Data\n\n- `x` (numeric) - a\n* `y` (numeric) - b\nprose\n\n## Notes\n\n- n"
+        assert data_bullets(text) == ["`x` (numeric) - a", "`y` (numeric) - b"]
+
+    def test_no_data_section(self) -> None:
+        assert data_bullets("# t\n\n## Description\n\ntext\n") == []
+
+    @pytest.mark.skipif(not PLOTS.is_dir(), reason="plots/ is not checked out")
+    def test_matches_the_sync_script_on_every_spec(self) -> None:
+        """`Spec.data` comes from sync_to_postgres.py; the checker must read the same bullets from the file."""
+        specs = _catalogue_data_bullets()
+        assert len(specs) > 300
+        for spec_id, bullets in specs:
+            text = (PLOTS / spec_id / "specification.md").read_text(encoding="utf-8")
+            assert data_bullets(text) == bullets, spec_id
+
+
+class TestSpecShape:
+    @staticmethod
+    def roles(*bullets: str) -> list[DataRole]:
+        return parse_roles(list(bullets))
+
+    def test_a_table_is_the_default(self) -> None:
+        roles = self.roles("`category` (categorical) - labels", "`value` (numeric) - heights")
+        assert spec_shape("any-spec", roles) == "table"
+
+    def test_map_specs_are_excluded_whatever_their_roles(self) -> None:
+        roles = self.roles("`lat` (numeric) - latitude", "`lon` (numeric) - longitude")
+        assert len(MAP_SPECS) == 13
+        assert all(spec_shape(spec_id, roles) == "excluded" for spec_id in MAP_SPECS)
+
+    def test_nodes_or_edges_make_a_network(self) -> None:
+        roles = self.roles(
+            "`nodes` (list of dicts) - entities", "`edges` (list of tuples) - links", "`weight` (numeric)"
+        )
+        assert spec_shape("any-network", roles) == "network"
+        assert [is_structure_role(role, "network") for role in roles] == [True, True, False]
+
+    def test_a_matrix_role_makes_a_matrix(self) -> None:
+        roles = self.roles("`variables` (string) - names", "`correlation_matrix` (numeric) - square matrix")
+        assert spec_shape("any-heatmap", roles) == "matrix"
+        assert all(is_structure_role(role, "matrix") for role in roles)
+
+    def test_text_only_roles_make_a_generated_spec(self) -> None:
+        roles = self.roles("`content` (string) - text to encode", "`error_correction` (string) - level")
+        assert spec_shape("any-code", roles) == "generated"
+
+    def test_an_untyped_role_alone_is_generated(self) -> None:
+        assert spec_shape("any-puzzle", self.roles("`grid` (2D array) - the puzzle")) == "generated"
+
+    def test_no_roles_is_a_table(self) -> None:
+        assert spec_shape("any-spec", []) == "table"
+
+    def test_overrides_win_over_the_roles(self) -> None:
+        roles = self.roles("`x` (numeric) - a", "`y` (numeric) - b")
+        for spec_id, (shape, reason) in SHAPE_OVERRIDES.items():
+            assert spec_shape(spec_id, roles) == shape
+            assert reason
+
+    @pytest.mark.skipif(not PLOTS.is_dir(), reason="plots/ is not checked out")
+    def test_every_override_names_a_spec_and_changes_its_shape(self) -> None:
+        """An override that the role rule already agrees with is dead weight; one for a deleted spec is stale."""
+        for spec_id, (shape, _) in SHAPE_OVERRIDES.items():
+            assert (PLOTS / spec_id / "specification.md").is_file(), spec_id
+            roles = _spec_roles(spec_id)
+            without = spec_shape("not-overridden", roles)
+            assert without != shape, (spec_id, shape)
+
+    @pytest.mark.skipif(not PLOTS.is_dir(), reason="plots/ is not checked out")
+    @pytest.mark.parametrize(
+        ("spec_id", "shape"),
+        [
+            ("bar-grouped", "table"),
+            ("line-basic", "table"),
+            ("sankey-basic", "table"),
+            ("candlestick-volume", "table"),
+            ("heatmap-correlation", "matrix"),
+            ("heatmap-clustered", "matrix"),
+            ("network-basic", "network"),
+            ("network-weighted", "network"),
+            ("network-bipartite", "table"),
+            ("qrcode-basic", "generated"),
+            ("sudoku-basic", "generated"),
+            ("line-tanabe-sugano", "generated"),
+            ("choropleth-basic", "excluded"),
+        ],
+    )
+    def test_catalogue_specs(self, spec_id: str, shape: str) -> None:
+        assert spec_shape(spec_id, _spec_roles(spec_id)) == shape
+
+
+class TestColorRole:
+    @staticmethod
+    def color(*bullets: str) -> str | None:
+        role = color_role(parse_roles(list(bullets)))
+        return role.name if role else None
+
+    def test_a_group_role_drives_colour(self) -> None:
+        assert self.color("`category` (categorical) - x labels", "`group` (categorical) - series") == "group"
+
+    def test_a_description_naming_colour(self) -> None:
+        assert self.color("`x` (numeric) - a", "`category` (categorical) - Group identifier for color coding") == (
+            "category"
+        )
+
+    def test_an_axis_category_alone_is_single_series(self) -> None:
+        assert self.color("`category` (categorical) - Labels for each bar", "`value` (numeric) - heights") is None
+
+    def test_numeric_roles_never_drive_the_palette(self) -> None:
+        assert self.color("`color` (numeric) - colour-mapped values") is None
+
+    @pytest.mark.skipif(not PLOTS.is_dir(), reason="plots/ is not checked out")
+    @pytest.mark.parametrize(
+        ("spec_id", "role"),
+        [
+            ("bar-grouped", "group"),
+            ("bar-stacked", "component"),
+            ("area-stacked", "category"),
+            ("line-multi", "series"),
+            ("scatter-embedding", "label"),
+            ("bar-basic", None),
+            ("line-basic", None),
+            ("heatmap-periodic-table", None),
+            ("heatmap-cohort-retention", None),
+        ],
+    )
+    def test_catalogue_specs(self, spec_id: str, role: str | None) -> None:
+        found = color_role(_spec_roles(spec_id))
+        assert (found.name if found else None) == role