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

dstf/authoring/builtin/enqueue.py

@@ -0,0 +1,144 @@
+"""Queue (D150; brief §3.6): SUITE and TEST placements. The selected tests
+are appended to the Session's simulation queue — one per tool process,
+first in, first out — as an ``Enqueue``.
+
+The capability starts nothing itself: the Session owns the queue and the
+pool it runs on, reads each result back as its test ends and rescores that
+test alone. A test already queued or running is not queued twice, and the
+caption says how many of the selection that leaves out.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from ...backends.pool import ItemState
+from ..capabilities import Emphasis, Enqueue, Panel, Placement, plural
+from ..situation import Situation
+from ..spec_document import edit_counts
+
+if TYPE_CHECKING:
+    from ..session import SessionView
+
+# NO module-level `nicegui` import: `import dstf.authoring` runs
+# register_builtins(), and the Session must import without the extra.
+
+#: The states of a test the queue already holds.
+_HELD = (ItemState.WAITING, ItemState.RUNNING)
+
+
+def _models(s: SessionView) -> tuple[list[str], list[str]]:
+    """The selected models in project order — the order the queue takes —
+    as ``(to queue, already queued or running)``."""
+    project = s.project
+    if project is None:
+        return [], []
+    selection = s.selection.tests
+    new: list[str] = []
+    held: list[str] = []
+    for test in project.tests:
+        if test.model_id in selection:
+            (held if s.queue_state(test.model_id) in _HELD else new).append(
+                test.model_id
+            )
+    return new, held
+
+
+class EnqueueTests:
+    """The selected tests appended to the simulation queue. Named for what
+    it does, not "queue": that word is the shell's for the queue itself,
+    and the shell names no capability (D129)."""
+
+    name = "enqueue"
+    label = "Queue"
+    placements = frozenset({Placement.SUITE, Placement.TEST})
+    #: drawn as this icon where a bar draws icons (the Suite toolbar)
+    icon = "playlist_add"
+    #: the Test page's strip: the next action when there is no result to
+    #: read, a criterion names a variable the last run did not record, or
+    #: its last run was cancelled or could not start; in the ⋮ while edits
+    #: are pending (their next action is Save) and while the queue holds
+    #: the test (the strip's own Remove or Cancel is the action then)
+    emphasis = {
+        Situation.SIM_FAIL: Emphasis.NEXT,
+        Situation.NO_RESULT: Emphasis.NEXT,
+        Situation.CANCELLED: Emphasis.NEXT,
+        Situation.START_FAILED: Emphasis.NEXT,
+        Situation.EDITS: Emphasis.MENU,
+        Situation.EDITS_NEW: Emphasis.NEXT,
+        Situation.NEW_VARIABLES: Emphasis.NEXT,
+        Situation.QUEUED: Emphasis.MENU,
+        Situation.RUNNING: Emphasis.MENU,
+    }
+
+    def available(self, s: SessionView) -> bool | str:
+        if s.project is None:
+            return "no project open"
+        if not s.selection.tests:
+            return "Queue needs a selection"
+        refusal = s.queue_refusal
+        if refusal is not None:
+            # The backend cannot run one test at a time, or cannot be built
+            # here: its own sentence, from the first attempt on.
+            return refusal
+        new, held = _models(s)
+        if not new and held:
+            if len(held) == 1:
+                doing = (
+                    "running"
+                    if s.queue_state(held[0]) is ItemState.RUNNING
+                    else "queued"
+                )
+                return f"{held[0]} is already {doing}"
+            return f"all {len(held)} selected tests are already queued or running"
+        return True
+
+    def caption(self, s: SessionView) -> str:
+        """The count, how many of the selection the queue already holds
+        ("Queue 3 (2 already queued)") and the selection's unsaved edits
+        (brief §3.6: a run uses the spec with pending edits applied, and
+        the button says so) — as they stand when each test STARTS, which is
+        when the queue takes a test's settings. One test whose last run in
+        the queue was cancelled or failed reads "Queue again". No backend:
+        the header shows it (owner ruling, 2026-09-26); the panel names
+        it."""
+        new, held = _models(s)
+        again = (ItemState.CANCELLED, ItemState.FAILED)
+        if len(new) == 1 and not held and s.queue_state(new[0]) in again:
+            return "Queue again"
+        notes = []
+        if held:
+            notes.append(f"{len(held)} already queued")
+        models = set(new)
+        counts = edit_counts(s.pending)
+        edits = sum(counts[model_id] for model_id in models)
+        if edits:
+            notes.append(
+                f"with {plural(edits, 'unsaved edit')}, as they stand when each starts"
+            )
+        return f"Queue {len(new)}" + (f" ({'; '.join(notes)})" if notes else "")
+
+    def panel(self, s: SessionView, ui_panel: Panel) -> None:
+        from nicegui import ui
+
+        project = s.project
+        assert project is not None  # `available` greys the button without one
+        ui.label(f"runs through {project.config.backend_name}").classes("text-xs").mark(
+            "queue-backend"
+        )
+        new, held = _models(s)
+        for model_id in new:
+            ui.label(model_id).classes("text-xs")
+        for model_id in held:
+            ui.label(f"{model_id} · already in the queue").classes(
+                "text-xs text-secondary"
+            )
+        ui.button(self.caption(s), on_click=lambda: ui_panel.submit()).props(
+            "dense no-caps"
+        )
+
+    def act(self, s: SessionView, **inputs: Any) -> Enqueue:
+        if s.project is None:
+            raise ValueError("no project open")
+        new, _held = _models(s)
+        return Enqueue(models=tuple(new))

dstf/authoring/capabilities.py

@@ -0,0 +1,463 @@
+"""The capability contract (two-tier design, §4.6).
+
+A capability is a plug-in the authoring shell draws at the placements it
+names: it reads a :class:`SessionView`, builds its controls in a
+:class:`Panel` the shell provides, and returns an :class:`Outcome`. **The Session applies outcomes;
+a capability applies nothing.** It holds a view only, so the enforcement
+is structural. Registration goes through the single ``dstf.plugins``
+entry-point group: a plug-in module calls :func:`register_capability` on
+import exactly as it calls ``register_metric``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Hashable, Sequence
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from ..storage.reference_store import ReferenceStore
+    from .session import SessionView
+    from .spec_document import PatchOp
+
+
+class Placement(Enum):
+    """Where a capability attaches (brief §3.2; D129): the Suite page's
+    batch bar, the Test page's status strip, a plot card's criteria header,
+    the open criterion's editor, a tree node's place in the tree, a row of
+    the Statistics card and a statistics criterion's editor there. A capability
+    names the frozenset it attaches at; the shell draws it at each and knows
+    no capability by name. The tab strip this replaces listed one tab per
+    ``Scope``; the scopes' selection rules (TESTS needs a selection, LEAF a
+    leaf) are now what ``available`` answers for the page's selection.
+
+    SUITE and TEST are a button carrying the capability's ``caption``, its
+    panel in a dialog; VARIABLE, CRITERION, NODE and STATISTIC are inline —
+    the panel is built straight into the plot's criteria header (for the
+    plot's first tracked variable, its rows opening under the header), the
+    criterion's editor, beside a tree node as that node's controls, or at
+    the end of a Statistics row no criterion reads yet (the selection's
+    ``quantity`` is the row's), with no button and no heading.
+    STATISTIC_CRITERION is the editor of a criterion scored through a
+    statistic, under its Statistics row: CRITERION's with no plot, so a
+    capability that needs one is not offered there. TREE_CRITERION is the
+    editor of any criterion opened under its row in the criteria tree
+    (U5): CRITERION's with no plot, like STATISTIC_CRITERION — the plot's
+    own editor is a link away. FAMILY_CRITERION is the editor of a folded
+    criteria row (D152): one criterion on several elements of an array,
+    every one of them named by the selection's ``leaf_paths`` (``leaf_path``
+    the first) — CRITERION's with no plot again, since nothing is dragged
+    for twenty criteria at once, so a capability that edits ONE leaf is not
+    offered there. At VARIABLE and
+    CRITERION ``Panel.figure`` is the plot's hook, subscribed for as long as
+    the panel is drawn; elsewhere a subscription raises."""
+
+    SUITE = "suite"
+    TEST = "test"
+    VARIABLE = "variable"
+    CRITERION = "criterion"
+    NODE = "node"
+    STATISTIC = "statistic"
+    STATISTIC_CRITERION = "statistic-criterion"
+    TREE_CRITERION = "tree-criterion"
+    FAMILY_CRITERION = "family-criterion"
+
+
+class Emphasis(Enum):
+    """How a bar that is told the page's situation draws a capability
+    (``Capability.emphasis``): NEXT is the one next action, drawn filled;
+    MENU goes into the bar's ⋮ menu. A situation a capability does not
+    name draws it quiet."""
+
+    NEXT = "next"
+    MENU = "menu"
+
+
+def plural(count: int, noun: str, many: str | None = None) -> str:
+    """``"2 tests"``, ``"1 test"``: the count and its noun for a caption. A
+    regular plural adds ``s``; ``many`` spells one that does not
+    (``plural(2, "new entry", "new entries")``)."""
+    if count == 1:
+        return f"{count} {noun}"
+    return f"{count} {many}" if many is not None else f"{count} {noun}s"
+
+
+@dataclass(frozen=True, kw_only=True)
+class Patch:
+    """Ops to stage; the Session rescores their models."""
+
+    ops: list[PatchOp]
+
+
+@dataclass(frozen=True, kw_only=True)
+class StoreWrite:
+    """A write against the reference store; results reload afterwards.
+    ``models`` names what it touches: a queued or running one refuses it.
+
+    ``run`` returns the one line the queue panel shows — what the write did,
+    including what it refused and why — or ``None`` when there is nothing
+    to say. A partial write has no other way to report its skips, and
+    raising after some baselines were stored would mislead."""
+
+    run: Callable[[ReferenceStore], str | None]
+    models: frozenset[str]
+
+
+@dataclass(frozen=True, kw_only=True)
+class Enqueue:
+    """Tests for the simulation queue (D150), in the order to run them. The
+    Session appends them — a test already queued or running is skipped —
+    and each result is read back and rescored as its test ends. A queued
+    test runs with the spec as it stands when it STARTS, pending edits
+    applied."""
+
+    models: tuple[str, ...]
+
+
+@dataclass(frozen=True, kw_only=True)
+class Artifact:
+    """Something written outside the spec and the store; shown as a link."""
+
+    paths: list[Path]
+    label: str
+
+
+@dataclass(frozen=True, kw_only=True)
+class OpenProject:
+    config_path: Path
+    work_dir: Path | None = None  # the run's work dir, when not the default
+
+
+Outcome = Patch | StoreWrite | Enqueue | Artifact | OpenProject | None
+
+
+class FigureHook(Protocol):
+    """ONE plot card's figure, as a capability may subscribe to it. There is
+    a hook per card — the plot a VARIABLE panel (its criteria header) or a
+    CRITERION editor sits under — not one figure for the page.
+
+    ``on(kind, handler)`` calls ``handler(primitive_id, payload)``:
+
+    - ``plotly_click`` / ``plotly_selected``: the id of the first point whose
+      trace ``meta.kind`` is ``"handle"``, else of the first point
+      (``customdata``, then ``meta.id``, then ``curveNumber``), with the event
+      payload — under x-unified hover a click lists every trace at that x.
+    - ``plotly_relayout`` moving shapes: once PER SHAPE, the payload being
+      that shape's keys without their ``shapes[N].`` prefix
+      (``{"y0": 6.0, "y1": 6.0}`` for a line; ``{"xanchor": 4.0, "yanchor":
+      2.99, "path": "M …"}`` for a ring), in data coordinates.
+      Plotly's payload never names the shape; the shell resolves the id from
+      the rendered figure's ``layout.shapes[N].name``, ``""`` when it cannot.
+      The shell does not interpret positions: the capability does, from the
+      handle's primitive type (a Marker's ring moves only by
+      ``xanchor``/``yanchor``).
+      A relayout mixing shape keys with others is a shape relayout.
+    - Any other relayout (a zoom): once, with id ``""`` and the raw payload.
+    - ``dstf_move`` (D149): a handle HELD on the plot, at most about 15
+      times a second — once per shape, with the payload its release would
+      carry (so a capability reads both with one function) plus ``drag``,
+      the number of the drag it is of; or once with id ``""`` and
+      ``{"end": True}`` for a drag that ended without a release. A move is
+      a preview: nothing is to be staged from it. One that arrives after
+      its drag's release is dropped by the shell.
+    - ``dstf_click`` (D149): a click on the plot that is no drag, no
+      double-click and on no draggable shape — id ``""`` and ``{"xaxis",
+      "yaxis", "x", "y", "xrange", "yrange", "ctrl", "shift", "alt",
+      "meta"}``: the axes of the panel under the pointer, the position in
+      them and what they showed.
+    - A release's and a move's per-shape payload also carries ``visible``,
+      ``{"x": span, "y": span}``: what the shape's axes showed at the
+      press, which a placed value is snapped by.
+
+    Handler semantics: each shape index is dispatched in turn, ascending,
+    from its own snapshot of the handlers, taken when that shape's dispatch
+    starts. A handler registered since the snapshot is not called for that
+    shape; one removed since the snapshot (its panel rebuilt) is skipped,
+    checked by identity. A handler registered twice is called twice. A
+    handler that raises ENDS the relayout: later handlers and later shapes
+    are not dispatched, the exception propagates, and the shell still
+    re-sends the figure so the plot snaps back."""
+
+    def on(self, kind: str, handler: Callable[[str, dict], None]) -> None: ...
+
+
+class Panel(Protocol):
+    """A container the capability owns entirely (the shell's
+    ``ShellPanel``). ``figure`` is the plot the panel is drawn beside, as a
+    capability subscribes to it — what Edit on plot reads its drags from.
+
+    ``kept`` is a dict of the panel's own that OUTLIVES the panel: what its
+    controls show that the spec does not hold — a required cell cleared to
+    be retyped, a tolerance with one side typed — and that a rebuild from
+    the spec alone would lose. A panel is rebuilt by edits it did not make
+    (a drag on the plot, another panel's submit), and is never told: it
+    writes there as its controls change and reads it back when it is
+    built. The host hands the same dict to every build of this capability's
+    panel for the same node of the same test, re-keys it when a tree edit
+    moves the node, and drops it — the panel is then rebuilt on an empty
+    one — with the node, and when an edit that is not this tab's lands on
+    the test: a Discard, a Save, another tab's. The record is the browser
+    tab's: it outlives the page. The criterion editor under a plot keeps
+    one; every other host — a dialog, a row, the criterion editors under a
+    tree row and under a Statistics row — hands a fresh dict to every
+    build (`tests/test_capability_conformance.py` holds both)."""
+
+    figure: FigureHook
+    kept: dict[Any, Any]
+
+    @property
+    def can_place(self) -> bool:
+        """Whether this panel is beside a plot whose clicks it may take
+        (D149): the criterion editor under a plot, and no other host."""
+        ...
+
+    def place_button(self, pointer: Hashable, label: str) -> None:
+        """Draw a ⌖ for what this panel calls ``pointer`` — into the
+        current slot; a number field's ``append`` slot is the place — that
+        ARMS it (D149): the next plain click on the plot is handed to
+        `on_place` with that ``pointer``. ``label`` is what the hint line
+        says is being set. Draw one only where a click can set the thing in
+        the state it is in. The builtins name a field by its keys into the
+        leaf (``("tolerance", "upper")``) and a table's row by its table
+        and index (``("points", 3)``). One is armed on a page at a time;
+        pressing ⌖ again, Esc, closing the editor, `disarm` and any edit of
+        the test disarm. Draws nothing where `can_place` is false."""
+        ...
+
+    def disarm(self) -> None:
+        """Nothing of this editor is armed any more: for a panel to call
+        when what a ⌖ named has moved under it without an edit saying so —
+        a table's row added or removed, its fields swapped for another
+        mode's. A no-op where `can_place` is false."""
+        ...
+
+    def on_place(self, handler: Callable[[Hashable, dict], bool]) -> None:
+        """``handler(pointer, click)`` is called when the plot is clicked
+        while a field THIS panel drew a ⌖ for is armed — ``click`` is the
+        ``dstf_click`` payload with ``label``, the armed ⌖'s, beside it. It
+        returns whether the click went through
+        (`submit`'s answer): then the field is disarmed; refused, it stays
+        armed, and the refusal is said under the plot. Registers nothing
+        where the panel is beside no plot."""
+        ...
+
+    def preview(self, leaf: dict | None, revision: int = 0) -> None:
+        """Hand every panel of this editor the leaf a handle held on the
+        plot WOULD write (D149), or None when it is over — each shows it in
+        its own fields (`on_preview`), and nothing is staged. ``revision``
+        is the drag's number, the same for every move of one drag. A no-op
+        where the panel is beside no plot."""
+        ...
+
+    def on_preview(self, handler: Callable[[dict | None, int], None]) -> None:
+        """``handler(leaf, revision)`` is called with what any panel of
+        this editor handed `preview`. Registers nothing where the panel is
+        beside no plot."""
+        ...
+
+    def submit(self, **inputs: Any) -> bool:
+        """Hand the capability's inputs to the shell, which calls ``act`` and
+        applies the outcome; an exception shows with the panel — above an
+        inline one, in the dialog of a placement that is a button. Returns
+        whether it went through: ``False`` when ``act`` or the apply
+        raised. A form row closes on ``True`` and only then — refused, it
+        stays open with what was typed, and the refusal shows under the
+        node's row, above the form."""
+        ...
+
+    def row(self, title: str, build: Callable[[Callable[[], None]], None]) -> None:
+        """Open a form row below the row this panel is drawn in, titled
+        ``title``. ``build(close)`` draws its content — fields, a sentence,
+        its buttons; ``close`` takes the row away — after a ``submit`` that
+        went through, never before it (a refused act keeps the row and
+        what was typed in it). ONE thing is open at a time on a page: this
+        closes any other row and the criterion editor. While it is open,
+        ``build`` is called AGAIN, into an emptied row, when an edit staged
+        elsewhere moves the node the panel is for — a form never shows a
+        value the node no longer has — and it closes with the host, when
+        its row is hidden, and when its node is gone. In a dialog (a
+        placement that is a button) the form is drawn in the dialog, below
+        the panel. A panel with no row to open one under — the criterion
+        editor — raises."""
+        ...
+
+    def retitle(self, title: str) -> None:
+        """Say the title of the form row this panel opened again — a form
+        whose subject follows a choice made in it (the add form's `Add a
+        criterion for pipe.T[1:20]` follows its Indices). The row keeps it
+        when the page builds it again. A no-op while no row of this
+        panel's is open, and where a form is drawn in a dialog."""
+        ...
+
+    def lead(self, build: Callable[[], None]) -> None:
+        """Draw ``build()`` in the node's lead place — beside its status,
+        where its kind is read (a combinator's kind dropdown). The place is
+        emptied first, and with the panel; while it holds something the
+        row's text leaves the kind out. A row without one (a leaf's, a
+        criteria row's) raises, like ``row`` where there is no row."""
+        ...
+
+    def reveal(self, leaf_path: str) -> None:
+        """Show that criterion's editor once the page has drawn it — after
+        an add, the new criterion. A no-op where no page reveals criteria:
+        a dialog, the criterion editor."""
+        ...
+
+    @property
+    def can_move(self) -> bool:
+        """Whether the host offers moving the node this panel is drawn for
+        (U4, V2): a tree card's row, and nowhere else — a plot's criteria
+        row hosts the same NODE placement and moves nothing."""
+        ...
+
+    def movable(
+        self,
+        on_drop: Callable[[str, str], None],
+        zones: Callable[[], dict[str, dict[str, str | None]]] | None = None,
+    ) -> bool:
+        """Take part in the host's drag (U4) where it offers moving
+        (`can_move`); elsewhere register nothing and return False.
+        ``on_drop(src_path, zone)`` is called when a node is dropped on
+        this panel's row — ``zone`` is ``before`` (the row's top half) or
+        ``onto`` (its bottom half; the root's whole row). ``zones`` makes
+        the row draggable: called once at the start of a drag from it, it
+        answers ``{row path: {zone: reason}}`` — ``None`` allowed, ``""``
+        where the node already is, else the sentence refusing it — which
+        the page draws over every row while dragging, with no round trip
+        to the server."""
+        ...
+
+    def on_click(self, handler: Callable[[], None]) -> bool:
+        """What a click on the row this panel is drawn in does (U5, Q6):
+        ``handler()``, called when the row itself is clicked — or, from the
+        keyboard, Enter or Space on it — never a control inside it. Offered
+        by the tree card's GROUP rows (a combinator's) and nowhere else
+        (`can_move`'s rule): a criterion's row — a plot's criteria row or
+        the tree's — has a click of its own, its editor. Elsewhere it
+        registers nothing and returns False. One per row; a later call
+        replaces it, and it goes with the panel."""
+        ...
+
+    def moved(self, node_path: str, text: str, paths: dict[str, str]) -> None:
+        """A move just went through (U4, V4): every open editor and form row
+        on the page closes NOW — two criteria on one variable trading
+        places move no shape, and an editor left open would show the other
+        one — and once the tree is redrawn ``node_path``'s row is brought
+        into view with ``text`` as one line under it, until the next form,
+        editor or edit. ``paths`` is every node the move kept, its path
+        before -> after (`Moved.paths`): what the page keys by a node's
+        path follows it, as for `edited`. A no-op where no page shows the
+        tree."""
+        ...
+
+    def edited(self, paths: dict[str, str]) -> None:
+        """Any other edit of the tree just went through: ``paths`` is every
+        node it kept, its path before -> after (`tree_move.path_map`) — an
+        add or a remove shifts the siblings after it, a wrap pushes its node
+        one level down, an unwrap lifts its children. What the page keys by
+        a node's path follows it (the tree card's folded groups, U5 R1);
+        a node not in it is gone. A no-op where no page shows the tree."""
+        ...
+
+
+@runtime_checkable
+class Capability(Protocol):
+    """A plug-in the shell draws at its placements. It MAY also declare
+    ``icon`` (a Material icon name): a bar that draws icons (the Suite
+    toolbar) draws it as that icon, its caption the tooltip; one without
+    keeps its text button. Not a protocol member — a runtime-checkable
+    protocol requires every member, and most capabilities have no icon —
+    so the shell reads it with ``getattr``.
+
+    It MAY also declare ``emphasis``, read the same way: a mapping from a
+    :class:`~dstf.authoring.situation.Situation` to :attr:`Emphasis.NEXT`
+    — drawn filled, the page's one next action — or :attr:`Emphasis.MENU`
+    — drawn in the bar's ⋮ menu; a situation it does not name draws it
+    quiet. Only a bar the page tells its situation reads it (the Test
+    page's status strip); every other bar draws today's outlined button."""
+
+    name: str
+    label: str
+    placements: frozenset[Placement]
+
+    def available(self, s: SessionView) -> bool | str:
+        """``True``, or ``False`` / the sentence saying why it is unavailable
+        and what would enable it ("Accept needs a selection", "FakeLib.A is
+        already queued"). The greyed button carries it where the
+        placement draws one; at CRITERION, NODE, STATISTIC and
+        STATISTIC_CRITERION it is shown in the panel's place."""
+        ...
+
+    def caption(self, s: SessionView) -> str:
+        """The button's label: its object, its effect and a count
+        ("Accept 2 results as baselines"). At zero it still says what it
+        would do; ``available`` then carries the sentence. The inline
+        placements (CRITERION, NODE, STATISTIC, STATISTIC_CRITERION) draw
+        no button and never read it."""
+        ...
+
+    def panel(self, s: SessionView, ui: Panel) -> None: ...
+
+    def act(self, s: SessionView, **inputs: Any) -> Outcome | Sequence[Outcome]:
+        """What this capability's inputs DO, as an outcome the Session
+        applies — a Patch, a StoreWrite, an Enqueue, an Artifact, an OpenProject,
+        or a sequence of them.
+
+        Returning ``None`` means nothing happened: the host applies
+        nothing, leaves a dialog open (there is nothing to close over) and
+        rebuilds no panel. It is a real answer — every plot sends
+        ``{"autosize": true}`` at mount, and a subscribing panel answers
+        that with None — but it is a silent one, so a capability that
+        returns None on purpose says why in its own panel."""
+        ...
+
+
+_CAPABILITIES: dict[str, Capability] = {}
+
+
+def register_capability(cap: Capability) -> Capability:
+    """Register ``cap`` under its name; returns it. Loud on a duplicate —
+    two capabilities sharing a name would make the shell's button order
+    depend on import order — and on a shape the shell cannot draw."""
+    if not isinstance(cap, Capability):
+        missing = [
+            a
+            for a in (
+                "name",
+                "label",
+                "placements",
+                "available",
+                "caption",
+                "panel",
+                "act",
+            )
+            if not hasattr(cap, a)
+        ]
+        raise TypeError(
+            f"{cap!r} is not a Capability: missing {', '.join(missing) or 'a method'}"
+        )
+    placements = cap.placements
+    if (
+        not isinstance(placements, frozenset)
+        or not placements
+        or not all(isinstance(p, Placement) for p in placements)
+    ):
+        raise TypeError(
+            f"capability {cap.name!r}: placements must be a non-empty frozenset of "
+            f"Placement, got {placements!r}"
+        )
+    if cap.name in _CAPABILITIES:
+        raise ValueError(f"capability {cap.name!r} is already registered")
+    _CAPABILITIES[cap.name] = cap
+    return cap
+
+
+def registered_capabilities() -> tuple[Capability, ...]:
+    """Every registered capability, in registration order."""
+    return tuple(_CAPABILITIES.values())
+
+
+def _reset_for_tests() -> None:
+    _CAPABILITIES.clear()

dstf/authoring/errors.py

@@ -0,0 +1,49 @@
+"""What the tool says when an action fails.
+
+The errors a person can cause — a patch the validator refuses, a drag a
+criterion cannot take, a move the tree refuses, a value out of range, a
+locked spec, a test the queue holds — read as their plain reason: the location is
+already on the screen, beside the row or the plot it came from. The
+validator's refusal of a tree of warnings read "PatchError: validator
+rejected the patched tree: metrics: tree has no leaf targeting 'primary'
+..."; it now reads the sentence alone.
+Anything else is a bug and keeps its class name, so it can be reported.
+"""
+
+from __future__ import annotations
+
+from ..backends.pool import Refused as PoolRefused
+from ..comparison.handles import HandleEditError
+from ..config import ConfigError
+from ..discovery.patch_apply import PatchError
+from .session import QueueError, StaleSpecError
+from .tree_move import MoveRefused
+from .unscorable import Refused as EditorRefused
+
+#: What a person's own edit raises. Shown as its reason and never logged.
+USER_ERRORS: tuple[type[BaseException], ...] = (
+    PatchError,
+    HandleEditError,
+    ConfigError,
+    # The simulation queue's refusals: the Session's and the pool's own.
+    QueueError,
+    PoolRefused,
+    # A move the tree refuses — a Move to… menu or a drag map gone stale
+    # under an edit staged since offers one — is said, not a bug.
+    MoveRefused,
+    # A value an editor will not stage: typed on the way to a good one.
+    EditorRefused,
+    # The spec file changed on disk under the tool: a write from the
+    # loaded one is refused, with the way out in the sentence.
+    StaleSpecError,
+)
+
+
+def user_text(e: BaseException) -> str:
+    """``e`` as the tool shows it: its ``reason`` (else its text) for a
+    person's own error or a ValueError, the class name first for anything
+    else. A ValueError also covers a JSONDecodeError or a numpy shape error
+    from a bug, so a caller that shows one also logs it (see `USER_ERRORS`)."""
+    if isinstance(e, (*USER_ERRORS, ValueError)):
+        return str(getattr(e, "reason", None) or e)
+    return f"{type(e).__name__}: {e}"