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

dstf/authoring/spec_preview.py

@@ -0,0 +1,83 @@
+"""The pending drawer's preview (the owner's ruling Q6 A): a test's entry
+before and after its staged edits, as ``test_spec.json`` will hold it —
+``json.dumps(entry, indent=2)``, the indentation Save writes — diffed line
+by line with ``difflib``, and each line's variable names read by their
+label with the result-file name muted beside it. Pure: stdlib only."""
+
+from __future__ import annotations
+
+import difflib
+import json
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal
+
+if TYPE_CHECKING:
+    from ..backends.types import VariableText
+
+Kind = Literal["same", "add", "del", "gap"]
+
+
+@dataclass(frozen=True)
+class Line:
+    kind: Kind
+    text: str
+
+
+#: What stands between two groups of changes.
+GAP = Line("gap", "…")
+
+
+def _dumped(entry: dict | None) -> list[str]:
+    return json.dumps(entry, indent=2).splitlines() if entry is not None else []
+
+
+def entry_lines(
+    before: dict | None, after: dict | None, context: int = 3
+) -> list[Line]:
+    """The changed lines of ``before`` → ``after`` (None: no entry) with
+    ``context`` equal lines around each group of changes, a :data:`GAP`
+    between two groups, a replaced run as its removed lines then its added
+    ones; ``[]`` when the two are equal. ``autojunk`` is off: in a long
+    tree ``}`` and ``"metric": "nrmse",`` are each more than 1% of the
+    lines, and junking them turned two changed tolerances into some two
+    hundred replaced lines."""
+    a, b = _dumped(before), _dumped(after)
+    matcher = difflib.SequenceMatcher(a=a, b=b, autojunk=False)
+    out: list[Line] = []
+    for n, group in enumerate(matcher.get_grouped_opcodes(context)):
+        if n:
+            out.append(GAP)
+        for tag, i1, i2, j1, j2 in group:
+            if tag == "equal":
+                out += [Line("same", t) for t in a[i1:i2]]
+                continue
+            out += [Line("del", t) for t in a[i1:i2]]
+            out += [Line("add", t) for t in b[j1:j2]]
+    return out
+
+
+#: A JSON string token, escapes included.
+_STRING = re.compile(r'"(?:[^"\\]|\\.)*"')
+
+
+def spans(text: str, texts: Mapping[str, VariableText]) -> list[tuple[str, bool]]:
+    """``text`` as ``(fragment, muted)`` pieces: each JSON string that names
+    a variable of ``texts`` whose label is not its name reads as the label,
+    then the name muted, its quotes dropped; everything else is kept
+    verbatim, so a line with no such name joins back to itself."""
+    out: list[tuple[str, bool]] = []
+    pos = 0
+    for m in _STRING.finditer(text):
+        name = json.loads(m.group())
+        vt = texts.get(name)
+        if vt is None or vt.label == name:
+            continue
+        if m.start() > pos:
+            out.append((text[pos : m.start()], False))
+        out += [(vt.label, False), (" " + name, True)]
+        pos = m.end()
+    if pos < len(text):
+        out.append((text[pos:], False))
+    return out

dstf/authoring/suite_rows.py

@@ -0,0 +1,99 @@
+"""A Suite row from the Session: the row model's ``TestRow``
+(``reporting.rows``) built from what the Session holds — its comparison
+through ``summary_fields`` (the numbers the report's sidecar carries,
+computed the same way), the result's timing, the test's provenance, its
+staged edits and its place in the simulation queue. In process: a sidecar is the
+full-resolution context, one JSON parse per test. No UI framework here
+(the Session tier)."""
+
+from __future__ import annotations
+
+from collections.abc import Collection, Iterable, Mapping
+from dataclasses import replace
+from typing import TYPE_CHECKING
+
+from ..backends.pool import ItemState
+from ..reporting.rows import TestRow, summary_fields
+from ..reporting.status import (
+    QUEUED,
+    RUNNING,
+    SCORING_FAILED,
+    SIM_FAIL,
+    scored_status,
+)
+from .spec_document import edit_counts
+
+if TYPE_CHECKING:
+    from .session import Session
+
+
+def _edits(session: Session) -> Mapping[str, int]:
+    return edit_counts(session.spec.pending)
+
+
+def suite_row(
+    session: Session,
+    model_id: str,
+    *,
+    failed: Collection[str] = (),
+    edits: Mapping[str, int] | None = None,
+) -> TestRow:
+    """One Suite row. A test the queue holds reads QUEUED or RUNNING,
+    whatever else is true of it — QUEUED from the click on, while the
+    click's read of the library is still out (`Session.checking`); then the
+    comparison — CANCELLED where it
+    has no result because its run in the queue was stopped (until that
+    row is cleared); then a scoring failure the open announced (``failed`` —
+    the shell's set, kept until the next open, so a model a later rescore
+    scored reads its verdict, not the failure); else the row waits for its
+    verdict. ``edits`` is the pending-edit count per model; ``suite_rows``
+    counts it once for every row."""
+    counts = _edits(session) if edits is None else edits
+    project = session.project
+    test = project.test(model_id) if project is not None else None
+    row = TestRow(
+        model_id=model_id,
+        field_sources=dict(test.field_sources) if test is not None else {},
+        edits=counts.get(model_id, 0),
+    )
+    state = session.queue_state(model_id)
+    comp = session.comparisons.get(model_id)
+    if state is ItemState.WAITING or model_id in session.checking:
+        return replace(row, status=QUEUED)
+    if state is ItemState.RUNNING:
+        return replace(row, status=RUNNING)
+    if comp is not None:
+        result = project.results.get(model_id) if project is not None else None
+        s = summary_fields(
+            comp,
+            stats=result.statistics if result is not None else None,
+            ref_id=f"ref_{comp.test_id}" if comp.test_id else None,
+            field_sources=row.field_sources,
+        )
+        return replace(
+            row,
+            status=scored_status(s["status"], cancelled=state is ItemState.CANCELLED),
+            ref_id=s["ref_id"],
+            worst_score=s["worst_nrmse"],
+            n_unscored=s["n_unscored"],
+            n_vars=s["n_vars"],
+            n_vars_passed=s["n_vars_passed"],
+            n_warnings=s["n_warnings"],
+            translation_wall=s["translation_wall"],
+            sim_wall=s["sim_wall"],
+            sim_cpu=s["sim_cpu"],
+            total_wall=s["total_wall"],
+            message=comp.error_message,
+        )
+    if model_id in failed:
+        return replace(row, status=SIM_FAIL, message=f"{SCORING_FAILED} (see the log)")
+    return replace(row, waiting=True)
+
+
+def suite_rows(
+    session: Session, model_ids: Iterable[str], *, failed: Collection[str] = ()
+) -> list[TestRow]:
+    """The rows of ``model_ids``, in that order; the edits counted once."""
+    counts = _edits(session)
+    failed_set = set(failed)
+    return [suite_row(session, m, failed=failed_set, edits=counts) for m in model_ids]

dstf/authoring/tree_move.py

@@ -0,0 +1,516 @@
+"""Moving a subtree of a raw metrics tree (U4): the whole new tree, or the
+one sentence saying why not. UI-free and pure: the Edit tree capability
+stages the tree `plan_move` returns as ONE ``add /metrics`` op, and lists
+every place a node can go from `move_destinations`.
+
+The owner's rulings it implements: a move that empties a combinator
+removes it, up the tree (D2); a ``k-of-n`` whose ``k`` exceeds its
+criteria lowers ``k``, a weight leaves a ``weighted`` with its child and a
+node moved into one gets weight 1 — each said in the move's notes (D3); a
+move that puts under an ``or`` or a ``k-of-n`` a child that can never fail
+is refused (D4, by D142's reason: it would pass its parent with nothing
+else passing). Only a pairing the move MAKES is refused — a tree as it is
+stays as it is.
+"""
+
+from __future__ import annotations
+
+import copy
+import re
+from collections.abc import Callable, Iterator, Mapping, Sequence
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal
+
+from ..comparison.validator import BaselineRoleLookup
+from .tree_pointer import node_or_none
+
+if TYPE_CHECKING:
+    from .spec_document import PatchOp
+
+ROOT = "/metrics"
+
+# V5's sentences, in the order they are checked (a move that changes
+# nothing is None between INTO_ITSELF and INTO_WARN), the validator's last.
+ROOT_REFUSAL = "The root holds the whole tree: move what is in it instead."
+INTO_ITSELF = "A criterion group can't move into itself."
+INTO_WARN = (
+    "A warning holds exactly one criterion or group: drop onto it to wrap "
+    "both in `and`."
+)
+WARN_UNDER = (
+    "A warning passes whatever it scores: under or / k-of-n it would pass its "
+    "parent with nothing else passing."
+)
+#: Not the tree's refusal but the drag's: one that started on rows rebuilt
+#: before its drop (`TreeCard.dropped`), whose paths name another tree.
+TREE_CHANGED = "The tree changed while you dragged: try again."
+
+#: The place a node already is, as `move_destinations` lists it.
+WHERE_IT_IS = "where it is"
+#: A place before a combinator's child, as `move_destinations` says it:
+#: this, a space, and that child's text (the menu cuts that in its middle).
+BEFORE = "before"
+
+#: The combinators a child that can never fail may not newly sit under.
+_NO_FREE_PASS_UNDER = ("or", "k-of-n")
+
+
+@dataclass(frozen=True)
+class Dest:
+    """Where a node goes. ``at``: into the combinator at ``path``, before
+    the child at ``index`` as the tree is NOW, before the move (``None``:
+    at its end). ``onto``: onto the node at ``path`` — a criterion is
+    wrapped with the moved node in an ``and`` (it first), a combinator
+    takes it at its end."""
+
+    kind: Literal["at", "onto"]
+    path: str
+    index: int | None = None
+
+
+@dataclass(frozen=True)
+class Moved:
+    tree: dict  # the whole new tree: what `add /metrics` stages
+    path: str  # where the moved node is in it
+    notes: tuple[str, ...]  # what else changed: "k 3 → 2", ...
+    #: Every node the move kept: its path before -> its path in ``tree``.
+    #: A move shifts its old and new siblings too; what is keyed by a
+    #: node's path (the tree card's folded groups, U5 R1) follows this.
+    paths: dict[str, str]
+
+
+class MoveRefused(ValueError):
+    """``str()`` is the one sentence the row shows (V5)."""
+
+
+def validator_for(role_of: BaselineRoleLookup) -> Callable[[dict], None]:
+    """What a move's new tree must pass: the parser, then the D66 roles —
+    raising `MoveRefused` with the text `Session.stage`'s refusal shows (the
+    parser's message without its path; the validator's joined)."""
+    from ..comparison.tree_spec import MetricSpecError, parse_metric_tree
+    from ..comparison.validator import validate_tree
+
+    def validate(raw: dict) -> None:
+        try:
+            spec = parse_metric_tree(raw)
+        except MetricSpecError as e:
+            raise MoveRefused(e.message) from e
+        errors = validate_tree(spec, role_of)
+        if errors:
+            raise MoveRefused(" ".join(e.message for e in errors))
+
+    return validate
+
+
+def _parent(path: str) -> tuple[str, int]:
+    parent, index = path.rsplit("/children/", 1)
+    return parent, int(index)
+
+
+def _inside(path: str, src: str) -> bool:
+    return path == src or path.startswith(src + "/")
+
+
+def _index_of(kids: list, node: dict) -> int:
+    return next(i for i, k in enumerate(kids) if k is node)
+
+
+def _nodes(tree: dict) -> Iterator[dict]:
+    yield tree
+    for child in tree.get("children") or []:
+        yield from _nodes(child)
+
+
+def _paths(tree: dict, path: str = ROOT) -> Iterator[tuple[int, str]]:
+    """``(id(node), path)`` for every node of ``tree``."""
+    yield id(tree), path
+    for i, child in enumerate(tree.get("children") or []):
+        yield from _paths(child, f"{path}/children/{i}")
+
+
+def _path_of(tree: dict, node: dict, path: str = ROOT) -> str | None:
+    if tree is node:
+        return path
+    for i, child in enumerate(tree.get("children") or []):
+        found = _path_of(child, node, f"{path}/children/{i}")
+        if found is not None:
+            return found
+    return None
+
+
+def always_passes(node: dict) -> bool:
+    """Can this node never fail, whatever its criteria score? A ``warn``
+    cannot; a combinator can by its children (an ``and`` all, an ``or``
+    any, a ``k-of-n`` at least k of them); a ``weighted`` sum and a
+    criterion can always fail."""
+    kind = node.get("combinator")
+    kids = node.get("children") or []
+    if kind == "warn":
+        return True
+    if kind == "and":
+        return bool(kids) and all(always_passes(c) for c in kids)
+    if kind == "or":
+        return any(always_passes(c) for c in kids)
+    if kind == "k-of-n":
+        k = node.get("k")
+        return isinstance(k, int) and sum(always_passes(c) for c in kids) >= k
+    return False
+
+
+def _free_passes(tree: dict) -> Iterator[tuple[dict, dict]]:
+    """Every ``(parent, child)`` of ``tree`` with an ``or`` / ``k-of-n``
+    parent and a child that can never fail."""
+    for node in _nodes(tree):
+        if node.get("combinator") in _NO_FREE_PASS_UNDER:
+            for child in node.get("children") or []:
+                if always_passes(child):
+                    yield node, child
+
+
+def _same_place(tree: dict, src: str, dest: Dest) -> bool:
+    """Is ``dest`` where the node at ``src`` already is — before itself,
+    before the child after it, or the end when it is last?"""
+    parent, i = _parent(src)
+    if dest.path != parent:
+        return False
+    holder = node_or_none(tree, parent)
+    assert holder is not None  # the parent of a node that exists
+    n = len(holder["children"])
+    index = dest.index if dest.kind == "at" else None
+    if index is None or index >= n:
+        return i == n - 1
+    return index in (i, i + 1)
+
+
+def plan_move(
+    tree: dict,
+    src: str,
+    dest: Dest,
+    *,
+    validate: Callable[[dict], None] | None = None,
+) -> Moved | None:
+    """The whole new tree with the node at ``src`` moved to ``dest``, or
+    None when it would stay where it is. `MoveRefused` says why a move
+    cannot be made; ``validate`` (`validator_for`) is checked last."""
+    if src == ROOT:
+        raise MoveRefused(ROOT_REFUSAL)
+    if _inside(dest.path, src):
+        raise MoveRefused(INTO_ITSELF)
+    if node_or_none(tree, src) is None:
+        raise ValueError(f"{src} names no node")
+    target = node_or_none(tree, dest.path)
+    if target is None:
+        raise ValueError(f"{dest.path} names no node")
+    wrap = dest.kind == "onto" and "combinator" not in target
+    if not wrap and "combinator" not in target:
+        raise ValueError(f"{dest.path} is a criterion: nothing goes in it")
+    if not wrap and _same_place(tree, src, dest):
+        return None
+    if not wrap and target["combinator"] == "warn":
+        raise MoveRefused(INTO_WARN)
+
+    new = copy.deepcopy(tree)
+    # Each new node beside the one it was copied from, so a pairing D4
+    # finds is compared with the old tree by reference. The new node is
+    # held in the value too: a pruned dict freed mid-move would free its
+    # id() for the wrap's new `and`.
+    origin = {id(n): (n, o) for o, n in zip(_nodes(tree), _nodes(new))}
+    notes: list[str] = []
+    # Everything the move names, resolved BEFORE anything shifts: the dicts
+    # themselves are the identities (a removal renumbers a list, never
+    # replaces the dicts in it).
+    moved = node_or_none(new, src)
+    old_parent_path, old_index = _parent(src)
+    old_parent = node_or_none(new, old_parent_path)
+    into = node_or_none(new, dest.path)
+    assert moved is not None and old_parent is not None and into is not None
+    chain = [old_parent]
+    path = old_parent_path
+    while path != ROOT:
+        path = _parent(path)[0]
+        up = node_or_none(new, path)
+        assert up is not None
+        chain.append(up)
+    holder = node_or_none(new, _parent(dest.path)[0]) if wrap else None
+    if wrap:
+        assert holder is not None  # a criterion at the root holds no src
+        anchor = None
+    else:
+        kids = into["children"]
+        index = dest.index if dest.kind == "at" else None
+        anchor = kids[index] if index is not None and index < len(kids) else None
+
+    # Out: the node leaves its parent; its weight goes with it — said,
+    # unless it only moves among the same weighted's children.
+    del old_parent["children"][old_index]
+    weight = _drop_weight(old_parent, old_index)
+    if weight is not None and into is not old_parent:
+        notes.append(_went(weight))
+    # In, BEFORE any repair: the destination then holds the node, so the
+    # prune below never removes it nor anything holding it, and a place
+    # before a combinator the prune removes is where that combinator was.
+    if holder is not None:
+        at = _index_of(holder["children"], into)
+        holder["children"][at] = {"combinator": "and", "children": [into, moved]}
+    else:
+        kids = into["children"]
+        at = len(kids) if anchor is None else _index_of(kids, anchor)
+        kids.insert(at, moved)
+        if into.get("combinator") == "weighted" and isinstance(
+            into.get("weights"), list
+        ):
+            if into is old_parent and weight is not None:
+                # A reorder among one weighted's children: the weight
+                # travels with its child, and nothing else changed.
+                into["weights"].insert(at, weight)
+            else:
+                into["weights"].insert(at, 1)
+                notes.append("weight 1 given")
+    # The source's side, repaired upward: an emptied combinator goes (D2)
+    # — the root never empties, it holds the destination — then every
+    # k-of-n that lost a child lowers k to its criteria (D3).
+    for node, up in zip(chain, chain[1:]):
+        if node["children"]:
+            break
+        i = _index_of(up["children"], node)
+        del up["children"][i]
+        notes.append(f"the empty {node['combinator']} was removed")
+        pruned = _drop_weight(up, i)
+        if pruned is not None:
+            notes.append(_went(pruned))
+    for node in chain:
+        k, n = node.get("k"), len(node["children"])
+        if node.get("combinator") == "k-of-n" and n and isinstance(k, int) and k > n:
+            node["k"] = n
+            notes.append(f"k {k} → {n}")
+
+    if not wrap and new == tree:
+        # Two equal siblings trading places: the tree is as it was, and a
+        # pending edit that changes nothing is no edit.
+        return None
+
+    # D4, by D142's reason: a child that can never fail under an `or` or
+    # a `k-of-n` is refused where the move made that pairing; one the old
+    # tree already had is left as it is.
+    for parent, child in _free_passes(new):
+        old_parent_of = origin.get(id(parent))
+        old_child_of = origin.get(id(child))
+        was = (
+            old_parent_of is not None
+            and old_child_of is not None
+            and old_parent_of[0] is parent
+            and old_child_of[0] is child
+            and any(c is old_child_of[1] for c in old_parent_of[1]["children"])
+            and always_passes(old_child_of[1])
+        )
+        if not was:
+            raise MoveRefused(WARN_UNDER)
+    if validate is not None:
+        validate(new)
+    where = _path_of(new, moved)
+    assert where is not None
+    # Each kept node by its copy (`origin`): a node the move removed (D2)
+    # is in no path of ``new``, the wrap's new `and` in no path of ``tree``.
+    before, after = dict(_paths(tree)), dict(_paths(new))
+    paths = {
+        before[id(old)]: after[key] for key, (_, old) in origin.items() if key in after
+    }
+    return Moved(tree=new, path=where, notes=tuple(notes), paths=paths)
+
+
+#: A JSON pointer that names a node of the tree, not one of its fields: the
+#: root, or a child at an index or at the end (``-``).
+_NODE_PATH = re.compile(rf"{ROOT}(/children/(\d+|-))*")
+
+
+def path_map(tree: dict, ops: Sequence[PatchOp]) -> dict[str, str]:
+    """Every node of ``tree`` that ``ops`` keep: its path before -> after
+    (U5 R1) — what is keyed by a node's path follows it. Not by comparing
+    the trees on both sides of a stage: the Session stages a copy, so no
+    node is the same object on both. By the ops' own semantics, over
+    ``tree`` as the edit read it: an add at an index shifts the siblings
+    after it, a remove drops its subtree and shifts them back, a replace (an
+    add at the root) puts its value where the node was — and a node of
+    ``tree`` that an op's value CARRIES (a wrap's child, an unwrap's
+    children, the root leaf an add pairs with the new one) is that node,
+    found by identity: `EditTree.act` builds its values from the very tree
+    it read. A copy is a new node — a move's whole new tree is one, which is
+    why a move reports `Moved.paths`. An op on a field (``/k``,
+    ``/combinator``) moves no node."""
+    was = {key: path for key, path in _paths(tree)}
+
+    def shadow(node: dict) -> dict:
+        return {
+            "was": was.get(id(node)),
+            "children": [shadow(c) for c in node.get("children") or []],
+        }
+
+    root = shadow(tree)
+    for op in ops:
+        if not _NODE_PATH.fullmatch(op.path):
+            continue
+        if op.path == ROOT:
+            if op.op != "remove":
+                root = shadow(op.value)
+            continue
+        parent_path, index = op.path.rsplit("/children/", 1)
+        parent = root
+        for i in parent_path[len(ROOT) :].split("/children/")[1:]:
+            parent = parent["children"][int(i)]
+        kids = parent["children"]
+        at = len(kids) if index == "-" else int(index)
+        if op.op == "remove":
+            del kids[at]
+        elif op.op == "add":
+            kids.insert(at, shadow(op.value))
+        elif op.op == "replace":
+            kids[at] = shadow(op.value)
+        else:
+            raise ValueError(f"{op.op!r} is no op an edit of the tree stages")
+    out: dict[str, str] = {}
+
+    def walk(node: dict, path: str) -> None:
+        if node["was"] is not None:
+            out[node["was"]] = path
+        for i, child in enumerate(node["children"]):
+            walk(child, f"{path}/children/{i}")
+
+    walk(root, ROOT)
+    return out
+
+
+def _drop_weight(node: dict, index: int) -> float | None:
+    """A ``weighted`` node's weight at ``index``, taken out with its child."""
+    if node.get("combinator") != "weighted":
+        return None
+    weights = node.get("weights")
+    if not isinstance(weights, list) or index >= len(weights):
+        return None
+    return weights.pop(index)
+
+
+def _went(weight: object) -> str:
+    """The note for a weight that left its ``weighted`` with its child."""
+    text = format(weight, "g") if isinstance(weight, (int, float)) else str(weight)
+    return f"weight {text} went with it"
+
+
+def _view(node: dict, names: Mapping[str, str]) -> dict:
+    """The raw node as `tree_text` reads a `tree_view` node: a criterion's
+    label is what the page reads for its variable."""
+    if "combinator" not in node:
+        return {"kind": "leaf", "label": names.get(node.get("variable", "")), **node}
+    return {
+        **node,
+        "kind": "combinator",
+        "children": [_view(c, names) for c in node.get("children") or []],
+    }
+
+
+def move_destinations(
+    tree: dict,
+    src: str,
+    *,
+    validate: Callable[[dict], None] | None = None,
+    names: Mapping[str, str] | None = None,
+) -> list[tuple[str, str, Dest, str | None]]:
+    """Every place the node at ``src`` can go, in tree order, as ``(text,
+    where, dest, reason)``: a combinator's (``text``) positions between its
+    children's rows — "before" the row there, the drag's own word, and "at
+    the end" — and a criterion's "wrap both in and". ``names`` is each
+    variable's text as the page reads it (`SessionView.labels`). Where two
+    siblings read the same, "before" either would not say which: their
+    places are numbered instead ("at 2").
+
+    The places beside the node read as ONE row, "where it is" (reason None;
+    the caller greys it: `plan_move` gives None). The node's own row is
+    not listed; the places in its own subtree are, with their refusal."""
+    from .tree_text import node_text
+
+    names = names or {}
+    rows: list[tuple[str, str, Dest, str | None]] = []
+    here = False
+
+    def one(text: str, where: str, dest: Dest) -> None:
+        nonlocal here
+        try:
+            planned = plan_move(tree, src, dest, validate=validate)
+        except MoveRefused as e:
+            rows.append((text, where, dest, str(e)))
+            return
+        if planned is None:
+            if not here:
+                here = True
+                rows.append((text, WHERE_IT_IS, dest, None))
+            return
+        rows.append((text, where, dest, None))
+
+    def walk(node: dict, path: str) -> None:
+        text = node_text(_view(node, names))
+        if path == ROOT:
+            text += " (root)"
+        if "combinator" not in node:
+            if path != src:
+                one(text, "wrap both in and", Dest("onto", path))
+            return
+        kids = node.get("children") or []
+        befores = [node_text(_view(child, names)) for child in kids]
+        for i, child in enumerate(kids):
+            before = befores[i]
+            unique = befores.count(before) == 1
+            where = f"{BEFORE} {before}" if unique else f"at {i + 1}"
+            one(text, where, Dest("at", path, i))
+            walk(child, f"{path}/children/{i}")
+        one(text, "at the end", Dest("at", path, None))
+
+    walk(tree, ROOT)
+    return rows
+
+
+#: A drag's zones on a row (D1 as amended by the owner): its top half is
+#: before it, its bottom half onto it — no "after": every pixel line means
+#: one place. To put a node last at an outer level, drop onto that outer
+#: combinator. The root has only "onto": nothing sits beside it.
+ZONES = ("before", "onto")
+
+
+def zone_dest(path: str, zone: str) -> Dest | None:
+    """The destination a drop in ``zone`` of ``path``'s row means: before
+    it among its siblings, or onto it (a criterion: wrap both in ``and``;
+    a combinator: its end). None for a zone the row has not got."""
+    if zone == "onto":
+        return Dest("onto", path)
+    if zone == "before" and path != ROOT:
+        parent, index = _parent(path)
+        return Dest("at", parent, index)
+    return None
+
+
+def zone_map(
+    tree: dict, src: str, *, validate: Callable[[dict], None] | None = None
+) -> dict[str, dict[str, str | None]]:
+    """``{row path: {zone: reason}}`` over every row of ``tree`` for a drag
+    of the node at ``src``: ``None`` allowed, ``""`` where it already is,
+    else the sentence that refuses it. The page asks once per drag and
+    draws every zone from the answer, with no round trip while dragging:
+    it grows with the square of the tree (134 nodes ~0.2 s)."""
+    out: dict[str, dict[str, str | None]] = {}
+
+    def walk(node: dict, path: str) -> None:
+        zones: dict[str, str | None] = {}
+        for zone in ZONES:
+            dest = zone_dest(path, zone)
+            if dest is None:
+                continue
+            try:
+                planned = plan_move(tree, src, dest, validate=validate)
+            except MoveRefused as e:
+                zones[zone] = str(e)
+                continue
+            zones[zone] = "" if planned is None else None
+        out[path] = zones
+        for i, child in enumerate(node.get("children") or []):
+            walk(child, f"{path}/children/{i}")
+
+    walk(tree, ROOT)
+    return out