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

dstf/authoring/shell/widgets.py

@@ -0,0 +1,188 @@
+"""`Action`: a button whose label is its caption and whose disabled state
+carries the sentence that says why and what enables it, beside it
+(DESIGN.md "Disabled states explain themselves": never a bare grey
+button). The header's Save / Discard / Export and every capability's
+button at a placement are Actions; `IconAction` is one drawn as an
+icon, its caption or its reason the tooltip."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from nicegui import ui
+from nicegui.elements.mixins.text_element import TextElement
+
+
+class Action:
+    def __init__(
+        self,
+        on_click: Callable[[], None],
+        *,
+        props: str,
+        marker: str,
+        why: bool = True,
+        filled: bool = False,
+    ) -> None:
+        #: `filled`: `unelevated` while enabled, `flat` while disabled —
+        #: Quasar's disabled only dims a filled button, and the header's
+        #: Save read as the page's active primary action at 0 pending
+        #: edits. Its colour stays, so disabled it reads as Discard does.
+        self.filled = filled
+        with ui.row().classes("items-center no-wrap gap-2") as self.container:
+            self.button = ui.button(on_click=on_click).props(props).mark(marker)
+            self.why: ui.label | None = (
+                ui.label().classes("dstf-why").mark(f"{marker}:why") if why else None
+            )
+
+    def set(self, caption: str, reason: str | None) -> None:
+        """``reason`` None enables the button; a sentence disables it and is
+        shown beside it (when this Action carries a why-line)."""
+        self.button.set_text(caption)
+        if reason is None:
+            self.button.enable()
+        else:
+            self.button.disable()
+        if self.filled:
+            if reason is None:
+                self.button.props(remove="flat", add="unelevated")
+            else:
+                self.button.props(remove="unelevated", add="flat")
+        if self.why is not None:
+            self.why.set_text(reason or "")
+            self.why.set_visibility(reason is not None)
+
+
+class IconAction:
+    """An Action drawn as an icon button: the caption — or, disabled, the
+    sentence that says why — is its tooltip and its accessible name (an
+    icon's ligature text is not a name). A disabled Quasar button takes no
+    pointer events, so the tooltip sits on a span around it (as Remove
+    plot's does)."""
+
+    def __init__(self, on_click: Callable[[], None], *, icon: str, marker: str) -> None:
+        with ui.element("span").classes("dstf-icon-action") as self.container:
+            self.button = (
+                ui.button(icon=icon, on_click=on_click)
+                .props("outline dense")
+                .mark(marker)
+            )
+            self.tip = ui.tooltip("").mark(f"{marker}:tip")
+
+    def set(self, caption: str, reason: str | None) -> None:
+        text = caption if reason is None else reason
+        self.tip.set_text(text)
+        self.button.props["aria-label"] = text
+        self.button.update()
+        if reason is None:
+            self.button.enable()
+        else:
+            self.button.disable()
+
+
+class MenuAction:
+    """An Action drawn as an item of a bar's ⋮ menu: its caption the item's
+    text (in a label: a menu item has no text of its own to set).
+    Disabled, it reads ``label`` — the action's plain name — over the
+    sentence that says why: its caption counts what it would act on, and
+    with nothing to act on the menu offered "Accept 0 results as
+    baselines" and "Queue 0 (1 already queued)", their reasons a hover
+    away."""
+
+    def __init__(
+        self, on_click: Callable[[], None], *, marker: str, label: str
+    ) -> None:
+        self.label = label
+        self.button = (
+            ui.menu_item(on_click=on_click)
+            .props('role="menuitem"')
+            .classes("dstf-menu-action")
+            .mark(marker)
+        )
+        with self.button, ui.item_section():
+            self.text = ui.label().classes("dstf-menu-name")
+            self.why = ui.label().classes("dstf-why").mark(f"{marker}:why")
+        self.why.set_visibility(False)
+
+    def set(self, caption: str, reason: str | None) -> None:
+        self.text.set_text(caption if reason is None else self.label)
+        self.why.set_text(reason or "")
+        self.why.set_visibility(reason is not None)
+        if reason is None:
+            self.button.enable()
+        else:
+            self.button.disable()
+
+
+class Pill:
+    """The tinted status pill of a criterion or a tree node (DESIGN.md
+    "Status badges": tinted inside a page, filled only in the header). It
+    repaints in place — a verdict that flips must not cost the row it sits
+    in."""
+
+    def __init__(self, status: str, marker: str) -> None:
+        self.label = ui.label().classes("dstf-pill").mark(marker)
+        self.status = ""
+        self.set(status)
+
+    def set(self, status: str, text: str | None = None) -> None:
+        if self.status:
+            self.label.classes(remove=f"dstf-pill-{self.status}")
+        self.status = status
+        self.label.classes(add=f"dstf-pill-{status}")
+        self.label.set_text(text if text is not None else status)
+
+
+#: How much of a label with no index the tail keeps (Q20).
+TAIL_CHARS = 12
+
+
+def middle_split(text: str) -> tuple[str, str]:
+    """``(head, tail)``: the tail is the text from the last ``[`` — the
+    index says which element — or its last `TAIL_CHARS` characters when it
+    has none, or when that ``[`` is further back than that: a tail from
+    ``volume[1]`` on took the width and hid the head (D140, Q20)."""
+    at = text.rfind("[")
+    if at == -1 or len(text) - at > TAIL_CHARS:
+        at = max(0, len(text) - TAIL_CHARS)
+    return text[:at], text[at:]
+
+
+class _Part(TextElement):
+    """A span of text: not a `ui.label`, whose `div` would break the line."""
+
+    def __init__(self, cls: str) -> None:
+        super().__init__(tag="span", text="")
+        self.classes(cls)
+
+
+class MiddleCut(ui.element):
+    """A variable label cut in the MIDDLE (D140, Q20): the head — what the
+    variable is — ellipsized, the tail — which element — whole. Both are
+    inline-blocks in an inline-block (never a flex pair: HIGH 6 of the
+    plan's review), the head's width capped at the element's less the
+    tail's ``--tail`` (its length in ``ch``), so the element's innerText,
+    a copy of it and its accessible name are the whole label; its title is
+    too. ``text`` / ``set_text`` as a label's, so a reader of ``.text`` is
+    unchanged. Model ids keep their start cut (the Tests drawer)."""
+
+    def __init__(self, text: str = "") -> None:
+        super().__init__("span")
+        self.classes("dstf-mid")
+        with self:
+            self.head = _Part("dstf-mid-head")
+            self.tail = _Part("dstf-mid-tail")
+        self.text = ""
+        self.set_text(text)
+
+    def set_text(self, text: str) -> None:
+        # A repaint of the text it has sends nothing, as a label's does.
+        if text == self.text and "title" in self.props:
+            return
+        self.text = text
+        head, tail = middle_split(text)
+        self.head.set_text(head)
+        self.tail.set_text(tail)
+        self.style(f"--tail: {len(tail)}ch")
+        # On the props dict: a label can hold a `"`.
+        self.props["title"] = text
+        self.update()

dstf/authoring/situation.py

@@ -0,0 +1,287 @@
+"""A test's situation, as the Test page's status strip says it: what state
+the test is in, the tone the strip is drawn in, and the one sentence that
+says it. Pure — no Session, no UI: the page reads the inputs, this decides.
+
+The situations are checked in :class:`Situation`'s order; the first that
+applies wins (a test the queue holds before pending edits, edits before
+anything the last scoring said).
+
+There is no state for edits to the simulation settings (the owner's ruling
+Q2 A drew one): ``/simulation`` is not stageable — `patch_apply`'s default
+whitelist is ``/comparison``, ``/metrics`` and ``/plots``, and widening it
+changes ``spec-update``, a seam another repository relies on. It waits for
+a simulation-settings editor."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from ..backends.pool import ItemState
+from ..comparison.tree_spec import tree_variables
+from ..reporting.status import FAIL, NO_REF, NOT_RUN, PASS, SIM_FAIL
+from .capabilities import plural
+from .live_rows import CANCELLED, NOT_AVAILABLE
+from .queue_rows import one_line
+
+if TYPE_CHECKING:
+    from ..backends.types import TestResult
+    from ..discovery.test_registry import TestModel
+    from .live_rows import Partial
+    from .queue_rows import QueueRow
+
+
+class Situation(Enum):
+    #: the simulation queue holds the test, waiting (D150)
+    QUEUED = "queued"
+    RUNNING = "running"
+    EDITS = "edits"
+    #: pending edits whose criteria name a variable the last run did not
+    #: record: Queue is the one next action, Save is quiet (the owner's O1)
+    EDITS_NEW = "edits_new"
+    SCORING_FAILED = "scoring_failed"
+    WAITING = "waiting"
+    #: its last run in the queue was stopped: it has no result, and the
+    #: one before was replaced when that run started
+    CANCELLED = "cancelled"
+    #: the queue could not start it — no worker could start: the
+    #: backend's message; its last result stands
+    START_FAILED = "start_failed"
+    NO_RESULT = "no_result"
+    SIM_FAIL = "sim_fail"
+    #: saved criteria name a variable the last run did not record: a
+    #: baseline accepted now would not hold it (the owner's O3)
+    NEW_VARIABLES = "new_variables"
+    NO_REF = "no_ref"
+    #: the comparison refused the test (`reporting.status.refusal`): it
+    #: fails with a reason and nothing scored, and accepting does not
+    #: clear it — no capability names this as its next action
+    REFUSED = "refused"
+    FAIL = "fail"
+    SIMULATE_ONLY = "simulate_only"
+    PASS = "pass"
+
+
+@dataclass(frozen=True)
+class Strip:
+    situation: Situation
+    tone: str  # "grey" | "red" | "amber"
+    sentence: str
+    #: A line under the strip, said once: why a running test's page shows
+    #: no growing trace (D151). Empty for every other strip.
+    note: str = ""
+    #: What the sentence is one line of — a failed run's message in full,
+    #: shown on hover. Empty where the sentence is the whole of it.
+    tip: str = ""
+
+
+_ACCEPT_IT = "If the new behaviour is right, accept it as the baseline."
+
+#: What a failed run's strip ends with: its one next action.
+_FIX_IT = "fix the model or its settings, then queue it again."
+#: The comparator's words for a failed run that said nothing of why.
+_NO_REASON = "Simulation failed"
+
+
+def _why(failure: str | None) -> str:
+    """A failed run's own reason as one line with no full stop — the
+    backend's message, as the Suite table's Message column has it — or
+    ``""`` where the run recorded none."""
+    line = one_line(failure or "").rstrip(".")
+    return "" if line == _NO_REASON else line
+
+
+#: The strip of a test whose run was cancelled (D150).
+CANCELLED_SENTENCE = (
+    "Cancelled — no result (its earlier result was replaced when the run started)."
+)
+
+#: Between the EDITS count and what the edits do to the verdict — in the
+#: strip's sentence and on the pending drawer's line under each test.
+SEP = " · "
+
+
+def verdict_phrase(status: str | None, saved_status: str | None) -> str:
+    """What the edits do to the verdict: the EDITS clause after the count,
+    and the pending drawer's verdict line."""
+    if saved_status is None:
+        return f"a new entry, scored {status or '…'}"
+    if status == saved_status:
+        return f"verdict stays {status}"
+    return f"verdict would change {saved_status} → {status or '…'}"
+
+
+def unrecorded_variables(
+    test: TestModel | None, result: TestResult | None, diagnostics: Iterable[str]
+) -> list[str]:
+    """The variables ``test``'s criteria name (`tree_variables`, the rule
+    every backend tracks by) that ``result`` does not hold. ``[]`` without
+    a result: there is nothing to rerun FOR yet. ``[]`` for a FAILED one,
+    which holds no variables: every criterion's would count, and a rerun
+    asked for to score them over a simulation that fails."""
+    if test is None or result is None or not result.success:
+        return []
+    have = {v.name for v in result.variables}
+    return [
+        n for n in tree_variables(test.metric_tree_spec, diagnostics) if n not in have
+    ]
+
+
+def new_variables(
+    test: TestModel | None, result: TestResult | None, diagnostics: Iterable[str]
+) -> int:
+    """How many variables only a rerun records: those of
+    :func:`unrecorded_variables`. A variable the result FILE holds is not
+    one of them — `Session.stage` re-reads the model when a criterion names
+    it (the owner's O2), so the result holds it by the time this counts.
+    0 for a simulate-only test: nothing is ever scored there, so no
+    variable is one a rerun would score (never NEW_VARIABLES or
+    EDITS_NEW)."""
+    if test is not None and test.simulate_only:
+        return 0
+    return len(unrecorded_variables(test, result, diagnostics))
+
+
+def _queue_it(n: int) -> str:
+    return f"queue the test to score {'it' if n == 1 else 'them'}"
+
+
+def strip_for(
+    *,
+    queue: QueueRow | None = None,
+    edits: int = 0,
+    status: str | None = None,
+    saved_status: str | None = None,
+    has_result: bool = False,
+    loading: bool = False,
+    scoring_failed: bool = False,
+    simulate_only: bool = False,
+    fails: int = 0,
+    criteria: int = 0,
+    advisory: int = 0,
+    new_variables: int = 0,
+    refused: str | None = None,
+    partial: Partial | None = None,
+    failure: str | None = None,
+) -> Strip:
+    """The strip for one test. ``queue`` is its row in the simulation
+    queue (`queue_rows.queue_row`), None when the queue lists no item of
+    it; ``edits`` its pending ops; ``status`` / ``saved_status`` the
+    classifier's word for the comparison as edited / as saved (None while
+    unscored, or — saved — for an entry the loaded spec does not have;
+    ``reporting.status.SCORING_FAILED`` — saved — when scoring the saved
+    spec raised);
+    ``has_result`` whether the last run finished it; ``loading`` whether
+    the project is still being read — an unscored test is then waiting for
+    it, never without a result, which may not be read yet; ``fails`` /
+    ``criteria`` / ``advisory`` its leaves failing, in all, and failing
+    inside a warn; ``new_variables`` the variables its criteria name that
+    the last run did not record (:func:`new_variables`); ``refused`` why
+    the comparison refused the test (`reporting.status.refusal`), or None;
+    ``partial`` what its last run left when it did not finish
+    (`Session.partial`), or None; ``failure`` the message its comparison
+    carries (`TestComparison.error_message`) — for a failed run the
+    backend's own, read back from the run's stored result, so it is there
+    after the queue's row is cleared and after the tool is started again."""
+    S = Situation
+    if queue is not None and queue.state is ItemState.WAITING:
+        return Strip(S.QUEUED, "grey", f"Queued — {queue.words}")
+    if queue is not None and queue.state is ItemState.RUNNING:
+        where = f" on worker {queue.worker}" if queue.worker is not None else ""
+        if queue.cancelling:
+            # A stop was asked and it has not ended yet (`QueueRow`).
+            return Strip(S.RUNNING, "grey", f"Cancelling{where}…")
+        # How far its result file has got, where the backend has a live
+        # view (D151); its seconds, and the line that says why, where not.
+        if queue.progress is not None:
+            return Strip(S.RUNNING, "grey", f"Running{where} — {queue.progress}")
+        return Strip(
+            S.RUNNING,
+            "grey",
+            f"Running{where} — {queue.elapsed or 0:.0f} s",
+            note=NOT_AVAILABLE,
+        )
+    if edits:
+        sentence = f"{plural(edits, 'unsaved edit')}{SEP}{verdict_phrase(status, saved_status)}"
+        if new_variables:
+            new = f"{plural(new_variables, 'new variable')}: {_queue_it(new_variables)}"
+            return Strip(S.EDITS_NEW, "amber", f"{sentence}{SEP}{new}")
+        return Strip(S.EDITS, "amber", sentence)
+    if scoring_failed:
+        return Strip(S.SCORING_FAILED, "red", "Scoring failed; the tree card says why.")
+    if status is None and (has_result or loading):
+        return Strip(S.WAITING, "grey", "Scoring…")
+    if partial is not None and status in (None, NOT_RUN, SIM_FAIL):
+        # Its last run did not finish and left a partial result (D151):
+        # where it stopped, and that nothing of it is scored. A cancel is
+        # nobody's failure; a timeout and a crash are the test's.
+        if partial.how == CANCELLED:
+            return Strip(S.CANCELLED, "grey", partial.sentence)
+        why = _why(failure) if status == SIM_FAIL else ""
+        return Strip(
+            S.SIM_FAIL,
+            "red",
+            f"{partial.sentence}. {why} — {_FIX_IT}" if why else partial.sentence,
+            tip=(failure or "") if why else "",
+        )
+    if queue is not None and queue.state is ItemState.CANCELLED:
+        return Strip(S.CANCELLED, "grey", CANCELLED_SENTENCE)
+    if queue is not None and queue.state is ItemState.FAILED and not queue.started:
+        said = queue.message or ""
+        return Strip(S.START_FAILED, "red", one_line(said) or queue.words, tip=said)
+    # NOT RUN is the classifier's word for this situation (D145): the
+    # header's badge and the strip say one thing. A SIM_FAIL is a run that
+    # reached a verdict, and reads as one below.
+    if status == NOT_RUN or (not has_result and status is None):
+        return Strip(S.NO_RESULT, "grey", "No result yet — queue it to simulate it.")
+    if status == SIM_FAIL:
+        # The backend's own reason, not only that it failed: it was on the
+        # queue's row alone, and Clear finished took it away.
+        why = _why(failure)
+        if why:
+            return Strip(S.SIM_FAIL, "red", f"{why} — {_FIX_IT}", tip=failure or "")
+        return Strip(
+            S.SIM_FAIL,
+            "red",
+            f"The simulation failed. {_FIX_IT[0].upper()}{_FIX_IT[1:]}",
+        )
+    if refused and status == FAIL:
+        # Before NEW_VARIABLES: a rerun records the variable, and the test
+        # is refused all the same. The reason, never "accept it": accepting
+        # keeps the reference's comparison settings, the refusal with them.
+        # A reason that ends its own sentence (`… did you mean "max_value"?`)
+        # is not given a second stop.
+        stop = "" if refused.endswith(("?", "!", ".")) else "."
+        return Strip(S.REFUSED, "red", f"Not scored: {refused}{stop}")
+    if new_variables:
+        return Strip(
+            S.NEW_VARIABLES,
+            "amber",
+            f"{plural(new_variables, 'new variable')} the last run did not "
+            f"record: {_queue_it(new_variables)}.",
+        )
+    if status == NO_REF:
+        return Strip(
+            S.NO_REF, "amber", "No baseline yet — accept this result as the first one."
+        )
+    if status == FAIL:
+        if fails:
+            what = f"Fails {fails} of {plural(criteria, 'criterion', 'criteria')}."
+        else:
+            what = "Fails against its baseline."
+        return Strip(S.FAIL, "red", f"{what} {_ACCEPT_IT}")
+    assert status == PASS, status
+    if simulate_only:
+        # The classifier's PASS for a test whose criterion is "it ran".
+        return Strip(
+            S.SIMULATE_ONLY, "grey", "Simulate-only: it runs, and nothing is compared."
+        )
+    if advisory:
+        return Strip(
+            S.PASS,
+            "grey",
+            f"Passes against its baseline, with {plural(advisory, 'advisory failure')}.",
+        )
+    return Strip(S.PASS, "grey", "Passes against its baseline.")

dstf/authoring/spec_document.py

@@ -0,0 +1,215 @@
+"""The spec as the Session holds it: the document as loaded, its content
+hash, and the ops staged against it."""
+
+from __future__ import annotations
+
+import copy
+import hashlib
+from collections import Counter
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from ..config import ConfigError
+from ..discovery.patch_apply import apply_patch_to_document
+from ..discovery.spec_parser import spec_document_from_bytes
+
+
+@dataclass(frozen=True)
+class PatchOp:
+    """One RFC 6902 op against one model's spec entry. ``path`` is relative
+    to the entry, as ``apply_patch`` reads it."""
+
+    model_id: str
+    op: str  # "add" | "replace" | "remove"
+    path: str
+    value: Any = None
+    #: The ``add /metrics`` `Session.stage` prepends to a flat entry's first
+    #: per-leaf edit: the implicit tree written out, scoring the same. The
+    #: pending drawer diffs against the saved entry WITH it (`preview_base`)
+    #: so an edit reads as itself, not as the whole tree added; and while
+    #: the entry's ``metrics`` is this tree and nothing more, the ops that
+    #: wrote it are no edit — they are dropped, whatever else is pending
+    #: but an edit of the ``variable_overrides`` the tree is built from
+    #: (`Session.stage`). Not part of the op: not in `raw()`, not in its
+    #: equality.
+    materializes: bool = field(default=False, compare=False)
+    #: An ``add /metrics`` that is an EDIT of the tree its entry scores by,
+    #: given whole — one gesture on a folded criteria row (D152,
+    #: `family_rows.as_one`) — rather than a new tree: `Session.stage`
+    #: writes a flat entry's implicit tree out first, marked, exactly as
+    #: for a per-leaf op, so the preview diffs the edit against that tree
+    #: and says Save writes it. Not part of the op, as ``materializes``.
+    edits_tree: bool = field(default=False, compare=False)
+    #: What the op did, in words, for the preview to say above its entry's
+    #: diff — ``(key, sentence)`` pairs: where a later op replaces this one
+    #: (`Session.stage`), a sentence under the same key replaces its
+    #: sentence and any other is kept, so a value typed over is one line
+    #: and two gestures are two. Not part of the op.
+    notes: tuple[tuple[str, str], ...] = field(default=(), compare=False)
+    #: Which act of the user's staged it (`Session.stage` numbers its
+    #: calls): one Ctrl+click on a flat test's plot is two ops — the tree
+    #: written out, and the row — and one edit; so is an add over twenty
+    #: Indices, and a change of a folded row's twenty criteria. An op that
+    #: supersedes the last one keeps that one's number: a value typed over
+    #: is the same edit. None for an op nothing staged (a test's own list):
+    #: it counts as itself (`edit_counts`). Not part of the op.
+    gesture: int | None = field(default=None, compare=False)
+
+    def raw(self) -> dict:
+        """The op as ``apply_patch`` and the envelope carry it."""
+        raw: dict = {"op": self.op, "path": self.path}
+        if self.op != "remove":
+            raw["value"] = copy.deepcopy(self.value)
+        return raw
+
+
+def edit_counts(pending: Iterable[PatchOp]) -> Counter[str]:
+    """By model, how many EDITS ``pending`` holds of its entry: the things
+    a person did (`PatchOp.gesture`), not the ops they took. The ONE count
+    — the header's ``N pending edits``, Save's caption, the Suite's Edits
+    cell, the Tests drawer's mark, the strip's ``N unsaved edits`` and the
+    preview's ``N edits`` all read it, so no two of them can disagree."""
+    edits = {
+        (op.model_id, ("op", index) if op.gesture is None else op.gesture)
+        for index, op in enumerate(pending)
+    }
+    return Counter(model_id for model_id, _ in edits)
+
+
+def edit_count(pending: Iterable[PatchOp]) -> int:
+    """How many edits ``pending`` holds in all (`edit_counts`)."""
+    return sum(edit_counts(pending).values())
+
+
+def content_hash(path: Path) -> str | None:
+    """SHA-256 of the file's bytes; ``None`` when it does not exist."""
+    try:
+        return hashlib.sha256(path.read_bytes()).hexdigest()
+    except FileNotFoundError:
+        return None
+
+
+def json_equal(a: Any, b: Any) -> bool:
+    """Whether ``a`` and ``b`` are one JSON value: objects by their members
+    in any order, arrays in order, numbers by value (``1`` is ``1.0``), and
+    ``true`` is no number — Python's ``==`` calls ``True`` and ``1`` equal."""
+    if isinstance(a, bool) or isinstance(b, bool):
+        return isinstance(a, bool) and isinstance(b, bool) and a == b
+    if isinstance(a, dict) and isinstance(b, dict):
+        return a.keys() == b.keys() and all(json_equal(a[k], b[k]) for k in a)
+    if isinstance(a, list) and isinstance(b, list):
+        return len(a) == len(b) and all(json_equal(x, y) for x, y in zip(a, b))
+    if isinstance(a, (dict, list)) or isinstance(b, (dict, list)):
+        return False
+    return bool(a == b)
+
+
+@dataclass
+class SpecDocument:
+    path: Path
+    loaded: dict  # as read; never mutated
+    content_hash: str | None  # of the bytes ``loaded`` came from
+    pending: list[PatchOp] = field(default_factory=list)
+    #: ``(len(pending), document)`` — the last replay, reused while pending
+    #: only grows (the Session never edits an op in place; it replaces the
+    #: document). A rescore over every test is then one replay, not one per
+    #: test.
+    _effective_cache: tuple[int, dict] | None = field(
+        default=None, repr=False, compare=False
+    )
+
+    @classmethod
+    def load(cls, path: Path) -> SpecDocument:
+        """Read ``path`` once: the hash and the document come from the same
+        bytes. A missing file is the empty document; one that is no spec —
+        no UTF-8 text, no JSON, a non-object root, a non-list ``tests`` — is
+        a :class:`ConfigError` (``spec_parser.spec_document_from_bytes``,
+        the one decoder every command reads the file through), because the
+        Session must not save over a file it could not read. A Save writes
+        a file read with a BOM back without it."""
+        try:
+            raw = path.read_bytes()
+        except FileNotFoundError:
+            return cls(path=path, loaded={"tests": []}, content_hash=None)
+        except OSError as e:
+            raise ConfigError(f"{path}: {e}") from e
+        data = spec_document_from_bytes(raw, str(path))
+        return cls(path=path, loaded=data, content_hash=hashlib.sha256(raw).hexdigest())
+
+    def on_disk_changed(self) -> bool:
+        return content_hash(self.path) != self.content_hash
+
+    def grouped(self) -> list[tuple[str, list[dict]]]:
+        """Pending ops as ``(model_id, raw ops)`` groups: models in
+        first-seen order, ops in staging order."""
+        groups: dict[str, list[dict]] = {}
+        for op in self.pending:
+            groups.setdefault(op.model_id, []).append(op.raw())
+        return list(groups.items())
+
+    def saved_entry(self, model_id: str) -> dict | None:
+        """The model's entry as LOADED — whatever is pending — as a copy the
+        caller may keep; ``None`` when the loaded document has no entry for
+        it (a pending op may be creating one)."""
+        from ..discovery.spec_update import spec_entry
+
+        entry = spec_entry(self.loaded, model_id)
+        return copy.deepcopy(entry) if entry is not None else None
+
+    def as_saved(self, model_id: str) -> bool:
+        """Whether the model's entry with the pending ops applied is the
+        one the file holds (:func:`json_equal`): ops that put it back are no
+        edit of it. A model the file has no entry for is as saved while its
+        entry would hold its model and nothing else — an entry that says
+        nothing (a tree added to an annotation-only test, then removed).
+        The document's half of the rule: a ``metrics`` member that is the
+        tree the saved entry already scores by is no edit either, and only
+        the Session knows that tree — it takes those ops out before asking
+        this (`Session._its_tree_written_out`)."""
+        from ..discovery.spec_update import spec_entry
+
+        bare = {"model": model_id}
+        return json_equal(
+            self.entry(model_id) or bare, spec_entry(self.loaded, model_id) or bare
+        )
+
+    def preview_base(self, model_id: str) -> dict | None:
+        """What the pending drawer diffs the model's entry against: the
+        saved entry with the model's materializing ops applied (a new entry
+        starts as ``{"model": model_id}``), a copy; with none of them, the
+        saved entry (``None`` for a new one)."""
+        from ..discovery.spec_update import spec_entry
+
+        ops = [
+            op.raw()
+            for op in self.pending
+            if op.model_id == model_id and op.materializes
+        ]
+        if not ops:
+            return self.saved_entry(model_id)
+        data = copy.deepcopy(self.loaded)
+        apply_patch_to_document(data, model_id, ops)
+        return copy.deepcopy(spec_entry(data, model_id))
+
+    def effective(self) -> dict:
+        """A copy of ``loaded`` with every pending op applied."""
+        return copy.deepcopy(self._effective())
+
+    def entry(self, model_id: str) -> dict | None:
+        """The model's entry in the effective document — read it, never
+        edit it (it is the cached replay)."""
+        from ..discovery.spec_update import spec_entry
+
+        return spec_entry(self._effective(), model_id)
+
+    def _effective(self) -> dict:
+        n = len(self.pending)
+        if self._effective_cache is not None and self._effective_cache[0] == n:
+            return self._effective_cache[1]
+        data = copy.deepcopy(self.loaded)
+        for model_id, ops in self.grouped():
+            apply_patch_to_document(data, model_id, ops)
+        self._effective_cache = (n, data)
+        return data