dynamic-systems-testing-framework 1.0.1__py3-none-any.whl

dstf/discovery/patch_apply.py

@@ -0,0 +1,308 @@
+"""RFC 6902 JSON-Patch applier with whitelist + unknown-key preservation.
+
+Used by ``dstf spec-update`` (through :mod:`spec_update`) and the authoring
+Session to apply small, scoped edits to ``test_spec.json`` without
+clobbering hand-authored fields. The ops arrive in the envelope
+:mod:`patch_envelope` reads; one model's ops look like::
+
+    [
+      {"op": "replace", "path": "/comparison/tolerance", "value": 1e-3},
+      {"op": "add",     "path": "/comparison/variable_overrides/v/tube_rel",
+       "value": 0.02}
+    ]
+
+Paths are RFC 6901 JSON-Pointers **relative to the matched test entry**
+(so `/comparison/...`, `/metrics/...` and `/plots/...`, not `/tests/3/...`). A path
+whitelist constrains which subtrees the applier will touch — an editor
+is not allowed to mutate arbitrary structure.
+
+This module is self-contained: no external JSON-Patch / JSON-Pointer
+libraries. The surface is small (replace/add/remove on a single path
+each), so the RFC 6901 unescape rules fit in ~10 lines.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+import logging
+from pathlib import Path
+from typing import Any
+
+from ..storage.ref_index import _atomic_write_text
+
+logger = logging.getLogger(__name__)
+
+
+class PatchError(Exception):
+    """Raised when a patch cannot be applied cleanly."""
+
+    def __init__(
+        self, message: str, path: str | None = None, *, reason: str | None = None
+    ):
+        self.path = path
+        #: The plain sentence a person reads: ``str()`` keeps the op and the
+        #: pointer for the CLI, the tool shows this beside the edit it came
+        #: from (`authoring.errors.user_text`).
+        self.reason = reason if reason is not None else message
+        super().__init__(f"{path}: {message}" if path else message)
+
+
+_SUPPORTED_OPS = {"replace", "add", "remove"}
+
+#: The subtrees of a test entry an editor may touch. One constant, shared by
+#: both entry points below, so the two cannot drift.
+DEFAULT_WHITELIST: tuple[str, ...] = ("/comparison", "/metrics", "/plots")
+
+
+def apply_patch_to_document(
+    data: dict,
+    model_id: str,
+    patch_ops: list[dict],
+    *,
+    whitelist: tuple[str, ...] = DEFAULT_WHITELIST,
+) -> dict:
+    """Apply ``patch_ops`` to the entry in the parsed document ``data`` that
+    matches ``model_id`` (created if absent), in place. Returns ``data``.
+    Raises :class:`PatchError` naming the failing op. The authoring
+    Session's in-memory document goes through here; the disk path is
+    :func:`apply_patch`."""
+    entry = _find_or_create_entry(data, model_id)
+    for i, op in enumerate(patch_ops):
+        try:
+            _apply_one_op(entry, op, whitelist)
+        except PatchError as e:
+            raise PatchError(
+                f"patch_ops[{i}] ({op!r}): {e}",
+                path=e.path,
+                reason=e.reason,
+            ) from None
+    return data
+
+
+def apply_patch(
+    spec_path: Path,
+    model_id: str,
+    patch_ops: list[dict],
+    *,
+    whitelist: tuple[str, ...] = DEFAULT_WHITELIST,
+    write: bool = True,
+) -> dict:
+    """Apply ``patch_ops`` to the entry in ``spec_path`` matching ``model_id``.
+
+    Returns the (mutated) spec dict. When ``write=True`` (default), also
+    persists it back to disk preserving key order. Raise :class:`PatchError`
+    on any issue; the caller (CLI) surfaces the message and aborts without
+    writing if the dry-run path signals invalidity.
+    """
+    data = apply_patch_to_document(
+        load_spec_document(spec_path), model_id, patch_ops, whitelist=whitelist
+    )
+    if write:
+        spec_path.parent.mkdir(parents=True, exist_ok=True)
+        # review 2026-07-06 (finding 31): atomic — an interrupted patch must
+        # not leave the user's spec truncated.
+        _atomic_write_text(spec_path, json.dumps(data, indent=2) + "\n")
+    return data
+
+
+def load_spec_document(spec_path: Path) -> dict:
+    """The spec document a patch is applied to: the file's
+    (``spec_parser.read_spec_document`` — the one reader, a
+    :class:`~dstf.config.ConfigError` for a file that is no spec), or the
+    empty document when there is no file yet."""
+    from .spec_parser import read_spec_document
+
+    data = read_spec_document(spec_path)
+    return {"tests": []} if data is None else data
+
+
+# ---------------------------------------------------------------------------
+# Internals
+# ---------------------------------------------------------------------------
+
+
+def _find_or_create_entry(data: dict, model_id: str) -> dict:
+    matches = [
+        entry
+        for entry in data["tests"]
+        if isinstance(entry, dict) and entry.get("model") == model_id
+    ]
+    if len(matches) > 1:
+        # review 2026-07-06 finding 51: duplicates — first entry wins
+        # everywhere (discovery + edit helpers use the same rule); warn so
+        # the user notices the dead entries.
+        logger.warning(
+            "test_spec has %d duplicate entries for model '%s'; "
+            "patching the first — remove the duplicates",
+            len(matches),
+            model_id,
+        )
+    if matches:
+        return matches[0]
+    entry = {"model": model_id}
+    data["tests"].append(entry)
+    return entry
+
+
+def _apply_one_op(entry: dict, op: dict, whitelist: tuple[str, ...]) -> None:
+    op_name = op.get("op")
+    path = op.get("path")
+    if op_name not in _SUPPORTED_OPS:
+        raise PatchError(
+            f"unsupported op {op_name!r} (supported: {sorted(_SUPPORTED_OPS)})",
+            path=path,
+        )
+    if not isinstance(path, str) or not path.startswith("/"):
+        raise PatchError(
+            "'path' must be an RFC 6901 JSON-Pointer starting with /", path=path
+        )
+    if not any(path == w or path.startswith(w + "/") for w in whitelist):
+        raise PatchError(
+            f"path not in whitelist {whitelist}",
+            path=path,
+        )
+    tokens = _split_pointer(path)
+    if op_name == "remove":
+        _remove_at(entry, tokens, path)
+        return
+    if "value" not in op:
+        raise PatchError(f"{op_name!r} requires 'value'", path=path)
+    # A copy: the document never shares an object with the op that put it
+    # there. Written in by reference, a later op of the same patch edits the
+    # earlier op's own value — and the list a caller still holds is then no
+    # longer the patch it gave: applied again (a replay, a second document)
+    # it does those later ops twice.
+    value = copy.deepcopy(op["value"])
+    if op_name == "replace":
+        _set_at(entry, tokens, value, path, must_exist=True)
+    elif op_name == "add":
+        _set_at(entry, tokens, value, path, must_exist=False)
+
+
+def _split_pointer(pointer: str) -> list[str]:
+    """RFC 6901: split on '/' after a leading slash; unescape ~1 → / and ~0 → ~."""
+    if pointer == "":
+        return []
+    if not pointer.startswith("/"):
+        raise PatchError("JSON-Pointer must start with /", path=pointer)
+    raw = pointer[1:].split("/")
+    # Order matters: ~1 before ~0 per RFC 6901.
+    return [seg.replace("~1", "/").replace("~0", "~") for seg in raw]
+
+
+def _set_at(
+    obj: Any, tokens: list[str], value: Any, path: str, *, must_exist: bool
+) -> None:
+    if not tokens:
+        raise PatchError("empty path points at the entry root; refuse", path=path)
+    *parents, last = tokens
+    cur = obj
+    for i, tok in enumerate(parents):
+        next_token = parents[i + 1] if i + 1 < len(parents) else last
+        cur = _descend(
+            cur, tok, path, create_missing=not must_exist, next_token=next_token
+        )
+    if isinstance(cur, list):
+        idx = _list_index(cur, last, path, allow_append=not must_exist)
+        if idx > len(cur) or (must_exist and idx >= len(cur)):
+            raise PatchError(
+                f"list index {idx} out of range (len {len(cur)})", path=path
+            )
+        if must_exist:
+            cur[idx] = value
+        else:
+            # review 2026-07-06 finding 49: RFC 6902 `add` on an existing
+            # array index INSERTS before it (it used to replace, silently
+            # destroying a sibling leaf); idx == len(cur) appends, matching
+            # the '-' token.
+            cur.insert(idx, value)
+    elif isinstance(cur, dict):
+        if must_exist and last not in cur:
+            raise PatchError(
+                f"key {last!r} not present (use 'add' for new keys)", path=path
+            )
+        cur[last] = value
+    else:
+        raise PatchError(
+            f"cannot set on non-container {type(cur).__name__}",
+            path=path,
+        )
+
+
+def _remove_at(obj: Any, tokens: list[str], path: str) -> None:
+    if not tokens:
+        raise PatchError("empty path points at the entry root; refuse", path=path)
+    *parents, last = tokens
+    cur = obj
+    for tok in parents:
+        cur = _descend(cur, tok, path, create_missing=False)
+    if isinstance(cur, list):
+        idx = _list_index(cur, last, path, allow_append=False)
+        if idx >= len(cur):
+            raise PatchError(f"list index {idx} out of range", path=path)
+        del cur[idx]
+    elif isinstance(cur, dict):
+        if last not in cur:
+            raise PatchError(f"key {last!r} not present", path=path)
+        del cur[last]
+    else:
+        raise PatchError(
+            f"cannot remove from non-container {type(cur).__name__}",
+            path=path,
+        )
+
+
+def _descend(
+    cur: Any,
+    tok: str,
+    path: str,
+    *,
+    create_missing: bool,
+    next_token: str | None = None,
+) -> Any:
+    if isinstance(cur, list):
+        idx = _list_index(cur, tok, path, allow_append=False)
+        if idx >= len(cur):
+            raise PatchError(f"list index {idx} out of range", path=path)
+        return cur[idx]
+    if isinstance(cur, dict):
+        if tok not in cur:
+            if not create_missing:
+                raise PatchError(
+                    f"key {tok!r} not present (use 'add' for new keys)",
+                    path=path,
+                )
+            # review 2026-07-06 finding 49: never auto-create a dict where
+            # the path expects an ARRAY — a per-leaf op like
+            # /metrics/children/0/... against a spec without a metrics tree
+            # used to silently create {"children": {"0": ...}}, which the
+            # tree validator then rejects. Fail loudly instead.
+            if next_token is not None and (next_token == "-" or next_token.isdigit()):
+                raise PatchError(
+                    f"key {tok!r} not present and the next token "
+                    f"{next_token!r} is an array index — refusing to "
+                    f"auto-create a dict in place of an array (the test "
+                    f"entry likely has no explicit 'metrics' tree yet)",
+                    path=path,
+                )
+            cur[tok] = {}
+        return cur[tok]
+    raise PatchError(
+        f"cannot descend into {type(cur).__name__}",
+        path=path,
+    )
+
+
+def _list_index(cur: list, tok: str, path: str, *, allow_append: bool) -> int:
+    if tok == "-":
+        if not allow_append:
+            raise PatchError("'-' (append) not allowed on non-add op", path=path)
+        return len(cur)
+    try:
+        idx = int(tok)
+    except ValueError:
+        raise PatchError(f"list index {tok!r} must be an integer", path=path) from None
+    if idx < 0:
+        raise PatchError(f"list index {idx} must be non-negative", path=path)
+    return idx

dstf/discovery/patch_envelope.py

@@ -0,0 +1,63 @@
+"""The JSON-Patch envelope ``dstf spec-update`` reads and the authoring
+Session's ``export`` writes.
+
+Two shapes are read — ``{"model": ..., "patch": [...]}`` because files in
+that shape exist (the reporter's export panel wrote them until D125), and
+``{"patches": [{"model": ..., "patch": [...]}, ...]}`` because a tool that
+spans tests needs one. Only the second is written. Old data, not old code.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from ..config import ConfigError
+
+_SHAPES = (
+    '{"model": "<model id>", "patch": [<RFC 6902 op>, ...]} or '
+    '{"patches": [{"model": ..., "patch": [...]}, ...]}'
+)
+
+
+@dataclass(frozen=True)
+class ModelPatch:
+    """One model's ops, in order. Paths are relative to the model's entry."""
+
+    model_id: str
+    ops: list[dict]
+
+
+def parse_envelope(data: object, *, label: str) -> list[ModelPatch]:
+    """Read either envelope form into ``ModelPatch`` groups, in file order.
+    Anything else raises :class:`ConfigError` naming both forms."""
+    if isinstance(data, dict) and "patches" in data and "model" in data:
+        raise _bad(label, "both a 'model' and a 'patches' key — say which")
+    if isinstance(data, dict) and "patches" in data:
+        groups = data["patches"]
+        if not isinstance(groups, list):
+            raise _bad(label, f"'patches' of type {type(groups).__name__}")
+        return [_group(g, label) for g in groups]
+    if isinstance(data, dict) and "model" in data:
+        return [_group(data, label)]
+    raise _bad(label, "neither a 'model' nor a 'patches' key")
+
+
+def build_envelope(groups: Sequence[ModelPatch]) -> dict:
+    """The multi-model form, and only that form."""
+    return {"patches": [{"model": g.model_id, "patch": list(g.ops)} for g in groups]}
+
+
+def _group(raw: object, label: str) -> ModelPatch:
+    if not isinstance(raw, dict) or not raw.get("model"):
+        raise _bad(label, "a group without a 'model'")
+    ops = raw.get("patch")
+    if not isinstance(ops, list):
+        raise _bad(label, f"a 'patch' of type {type(ops).__name__}")
+    return ModelPatch(str(raw["model"]), ops)
+
+
+def _bad(label: str, got: str) -> ConfigError:
+    return ConfigError(
+        f"{label}: not a JSON-Patch envelope — expected {_SHAPES}, got {got}"
+    )

dstf/discovery/plots.py

@@ -0,0 +1,318 @@
+"""The optional ``plots`` key of a ``test_spec.json`` entry, and the plots
+both tiers draw.
+
+A test's plots are DERIVED from its criteria tree (:func:`derive_plots`):
+one plot per scored variable or array family, where the tree first names
+it. The key holds only a person's extras — each entry one variable and the
+``context`` series drawn grey beside it. An entry on a scored variable
+decorates that variable's plot; an entry on an unscored one is a WATCH
+plot, after the derived ones, in list order. Absent and ``[]`` both mean no
+extras (``[]`` is kept as the key's value, so a writer can tell it from an
+absent key); ``null`` is refused. Read by both tiers, ignored by scoring.
+The parser refuses what it does not know, so a typo is loud. No I/O here:
+the spec parser, the patch validator, the Session and the report all call
+in.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Collection, Iterable, Sequence
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from ..backends.types import is_glob_pattern
+
+if TYPE_CHECKING:
+    from ..backends.types import TestResult
+    from ..comparison.tree_spec import LeafSpec, SpecNode
+    from .test_registry import TestModel
+
+
+class PlotsSpecError(ValueError):
+    """A ``plots`` value the parser refuses; the message starts with where."""
+
+
+@dataclass(frozen=True)
+class PlotExtra:
+    """One entry of the ``plots`` key: a variable and its context series.
+    Scored, it decorates that variable's derived plot; unscored, it is a
+    watch plot."""
+
+    var: str
+    context: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True, kw_only=True)
+class ResolvedPlot:
+    """One plot as a tier draws it. ``subject`` is one variable or the
+    members of one array family (by index); ``context`` the grey, unscored
+    series beside it; ``watch`` a plot no criterion names; ``missing`` the
+    subject and context names the result lacks."""
+
+    index: int
+    subject: tuple[str, ...]
+    context: tuple[str, ...] = ()
+    watch: bool = False
+    missing: tuple[str, ...] = ()
+    kind: str = "time"
+
+    @property
+    def series(self) -> tuple[str, ...]:
+        """Every name the plot draws — the subject, then the context —
+        missing ones included: a reader checks ``missing``."""
+        return self.subject + self.context
+
+
+def _unknown(obj: dict, known: set[str], at: str) -> None:
+    """Refuse a key nothing reads, in the words every other part of the
+    spec is refused with (``strict_keys.unknown_field``). Imported late:
+    the comparison package reaches back into discovery."""
+    from ..comparison.strict_keys import unknown_field
+
+    problem = unknown_field(obj, known)
+    if problem is not None:
+        raise PlotsSpecError(f"{at}: {problem}")
+
+
+def _one_name(value: object, at: str, what: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise PlotsSpecError(f"{at}: must be a non-empty string")
+    if is_glob_pattern(value):
+        raise PlotsSpecError(f"{at}: {value!r} is a pattern; {what} one variable")
+    return value
+
+
+def parse_plots(raw: object, *, path: str = "plots") -> tuple[PlotExtra, ...]:
+    if not isinstance(raw, list):
+        raise PlotsSpecError(f"{path}: must be a list of plot extras")
+    extras: list[PlotExtra] = []
+    for i, entry in enumerate(raw):
+        at = f"{path}[{i}]"
+        if not isinstance(entry, dict):
+            raise PlotsSpecError(f"{at}: must be an object")
+        _unknown(entry, {"var", "context"}, at)
+        var = _one_name(entry.get("var"), f"{at}.var", "an entry names")
+        if any(e.var == var for e in extras):
+            raise PlotsSpecError(f"{at}.var: {var!r} already has an entry")
+        context_raw = entry.get("context", [])
+        if not isinstance(context_raw, list):
+            raise PlotsSpecError(f"{at}.context: must be a list of names")
+        context: list[str] = []
+        for j, one in enumerate(context_raw):
+            c_at = f"{at}.context[{j}]"
+            name = _one_name(one, c_at, "a context series names")
+            if name == var:
+                raise PlotsSpecError(f"{c_at}: {name!r} is the plot's own variable")
+            if name in context:
+                raise PlotsSpecError(f"{c_at}: {name!r} is already in the context")
+            context.append(name)
+        extras.append(PlotExtra(var, tuple(context)))
+    return tuple(extras)
+
+
+def plots_to_raw(extras: Sequence[PlotExtra]) -> list[dict]:
+    """The JSON a writer stores: ``context`` only when there is some."""
+    return [
+        {"var": e.var, **({"context": list(e.context)} if e.context else {})}
+        for e in extras
+    ]
+
+
+def tree_leaves(spec: SpecNode | None) -> list[LeafSpec] | None:
+    """The leaves of ``spec`` that name a series of the result, depth
+    first; ``None`` for no tree. A stored-scalar leaf (a string
+    ``quantity``) names a statistic, not a series, and has no plot.
+
+    Walks the SPEC, never the materialized tree: the Session's plots are
+    painted before any baseline is read."""
+    if spec is None:
+        return None
+    from ..comparison.tree_spec import LeafSpec, resolves_a_variable
+
+    out: list[LeafSpec] = []
+
+    def walk(node: SpecNode) -> None:
+        if isinstance(node, LeafSpec):
+            if resolves_a_variable(node):
+                out.append(node)
+            return
+        for child in node.children:
+            walk(child)
+
+    walk(spec)
+    return out
+
+
+def plot_leaves(test: TestModel, compared: Sequence[str]) -> list[LeafSpec] | None:
+    """The leaves a test's plots derive from, in tree order: its authored
+    ``metrics`` tree — even with nothing compared yet, a test with no
+    baseline: the tree names what will be scored — else the implicit tree of
+    what was ``compared``; ``None`` with neither (one plot per tracked
+    variable, the owner's ruling O2). ONE rule, for the tool's
+    `Session.plots` and the report."""
+    from ..comparison.tree_spec import synthesize_implicit_tree
+
+    if test.metric_tree_spec is not None:
+        return tree_leaves(test.metric_tree_spec)
+    if not compared:
+        return None
+    return tree_leaves(
+        synthesize_implicit_tree(
+            list(compared), variable_overrides=test.variable_overrides
+        )
+    )
+
+
+def derive_plots(
+    leaves: Sequence[LeafSpec] | None,
+    extras: Sequence[PlotExtra],
+    *,
+    tracked: Sequence[str],
+    unit_tests: Collection[str] = (),
+    available: Iterable[str] | None = None,
+) -> tuple[ResolvedPlot, ...]:
+    """The plots both tiers draw for one test.
+
+    ``leaves`` are the tree's (:func:`plot_leaves`), in depth-first order;
+    ``None`` (no tree: nothing scored) derives from the ``tracked`` names
+    instead. Their variables fold into array families by RESULT-FILE NAME
+    (the :mod:`~dstf.figures.families` rule over the names: ``pipe.T[1]`` ..
+    ``pipe.T[4]`` are one plot), with no scale check — except the
+    ``unit_tests`` names, each its own plot whatever its expression (the
+    owner's ruling O3: a UnitTests element is a test quantity of its own,
+    and `check_atm`'s local ``x`` holds 1 Pa in atm beside 1 atm in Pa).
+    One plot per family or lone variable, where the tree first names it — a
+    family where the tree first names any member.
+
+    Each extra on a member of a derived subject adds its context there;
+    every other extra is a watch plot, after the derived ones, in list
+    order.
+
+    ``available`` is every name the plots can be drawn from — the result
+    file's listing and the result's own variables — or ``None`` when it
+    cannot be listed: nothing is missing then."""
+    from ..figures.families import group_families
+
+    if leaves is None:
+        order = list(dict.fromkeys(n for n in tracked if n))
+    else:
+        order = list(dict.fromkeys(leaf.variable for leaf in leaves if leaf.variable))
+    apart = set(unit_tests)
+    family_of: dict[str, tuple[str, ...]] = {
+        name: (name,) for name in order if name in apart
+    }
+    for _, members in group_families([n for n in order if n not in apart]):
+        for name in members:
+            family_of[name] = tuple(members)
+    subjects = list(dict.fromkeys(family_of[name] for name in order))
+    member_of = {name: i for i, subject in enumerate(subjects) for name in subject}
+    context: list[list[str]] = [[] for _ in subjects]
+    watch: list[PlotExtra] = []
+    for extra in extras:
+        at = member_of.get(extra.var)
+        if at is None:
+            watch.append(extra)
+            continue
+        for name in extra.context:
+            if name not in subjects[at] and name not in context[at]:
+                context[at].append(name)
+    have = None if available is None else set(available)
+    rows = [(s, tuple(c), False) for s, c in zip(subjects, context)]
+    rows += [((e.var,), e.context, True) for e in watch]
+    return tuple(
+        ResolvedPlot(
+            index=i,
+            subject=subject,
+            context=ctx,
+            watch=is_watch,
+            missing=tuple(
+                n for n in subject + ctx if have is not None and n not in have
+            ),
+        )
+        for i, (subject, ctx, is_watch) in enumerate(rows)
+    )
+
+
+def plots_of_test(
+    test: TestModel,
+    compared: Sequence[str],
+    result: TestResult | None,
+    *,
+    listed: Iterable[str] | None,
+) -> tuple[ResolvedPlot, ...]:
+    """The plots of one test — ONE rule, called by the tool's
+    `Session.plots` and the report's `plot_inputs`, so both tiers draw the
+    same list.
+
+    The leaves are :func:`plot_leaves`', the tracked names
+    :func:`tracked_names`', the extras the entry's ``plots`` key. Which
+    names are UnitTests elements — never folded (O3) — is asked of every
+    leaf AND every tracked name: a leaf the result does not carry is an
+    element all the same.
+
+    ``listed`` is the result FILE's names, or ``None`` when it was not
+    listed (the report lists it only for a test with extras). A name the
+    result in memory carries is never missing — the file's listing may be
+    filtered; with no listing, what the result carries is all the plots can
+    draw, and a leaf it lacks is missing. With no result either, nothing is
+    missing.
+
+    A run that FAILED has no plots, extras included (O2, literally): what a
+    backend wrote before it stopped is a partial file, not the test's
+    plots."""
+    from .unit_tests import is_unit_test_variable
+
+    if result is not None and not result.success:
+        return ()
+    leaves = plot_leaves(test, compared)
+    tracked = tracked_names(compared, result)
+    names = [*(leaf.variable for leaf in leaves or ()), *tracked]
+    available: list[str] | None = None
+    if result is not None:
+        available = [v.name for v in result.variables if v.name]
+    if listed is not None:
+        available = [*listed, *(available or ())]
+    return derive_plots(
+        leaves,
+        tuple(test.plots or ()),
+        tracked=tracked,
+        unit_tests=[n for n in names if is_unit_test_variable(test, n)],
+        available=available,
+    )
+
+
+def tracked_names(scored: Sequence[str], result: object) -> list[str]:
+    """The variables a test HAS a plot for by default, in the order both
+    tiers draw them: what the comparison scored, then the rest of the loaded
+    result's, de-duplicated. ONE rule, called by the tool's `Session.tracked`
+    and by the report's `plot_inputs` — the two drew different default
+    layouts (the report one plot per scored variable, the tool the union),
+    and the owner's ruling is that both tiers draw the same plots.
+
+    Every name here is the result file's (a UnitTests variable's is
+    ``<instance>.x[i]``) and nothing relabels it, so a variable the tree
+    scores and the result carries is one name and is listed once — listing
+    the same trajectory under two spellings drew it twice (the 3b review). A
+    result variable with no name has nothing to plot by and is skipped; a
+    tree leaf's variable, on the other hand, is listed whether or not the
+    result carries it, because ``scored`` is what the test's author wrote.
+
+    A result of a simulation that FAILED contributes nothing: what a backend
+    wrote before it stopped is a partial file, not the test's plots, and the
+    page drew a card per half-written variable (the final review).
+
+    ``scored`` comes first even when the tree's order differs from the
+    result file's. The result's own come in its order — the spec's
+    patterns' order (`resolve_variable_patterns`: explicit names as
+    written, a glob's matches in the file's order), never sorted."""
+    names = [name for name in scored if name]
+    have = set(names)
+    out = list(dict.fromkeys(names))
+    if not getattr(result, "success", True):
+        return out
+    for var in getattr(result, "variables", None) or ():
+        if not var.name or var.name in have:
+            continue
+        have.add(var.name)
+        out.append(var.name)
+    return out