unicode-logic-kit 0.31.0__py3-none-any.whl

unicode_logic_kit/fol/_free_parameters.py

@@ -0,0 +1,105 @@
+"""A free variable is a parameter of the problem: one unknown element, the same everywhere.
+
+The consequence relation the kit reads is the assignment-wise one of the textbooks:
+``Γ ⊨ φ`` iff every structure AND assignment that satisfies ``Γ`` satisfies ``φ``. A
+variable that is free in a premise or in the conclusion therefore names ONE element,
+the same in every formula of the problem. It is not a universally quantified variable
+of its own formula: ``P(x) ⊢ P(alpha)`` is not valid (universe ``{0, 1}``, ``x`` ↦ 1,
+``alpha`` ↦ 0, ``P`` = ``{1}``), while ``P(x) ⊢ ∃y P(y)`` and ``∀y P(y) ⊢ P(x)`` are.
+
+A route that has no free variables of its own (a resolution prover, a model finder, a
+writer for a target that closes every formula) reads this by replacing every free
+variable of the whole problem by a constant, before it does anything else:
+``Γ(x) ⊨ φ(x)`` assignment-wise iff ``Γ(c) ⊨ φ(c)`` for a constant ``c`` that no
+symbol of the problem has. :func:`parameterize` does that, once, for every route that
+needs it. For a problem with no premise the reading coincides with the universal
+closure of the conclusion.
+"""
+
+from typing import Dict, Iterable, List, Sequence, Tuple
+
+from ._identifiers import symbol_names
+from .nodes import Node, Constant, SortedConstant, Variable, free_variables, substitute
+
+__all__ = ["free_parameter_names", "parameterize"]
+
+
+def _free_names(formula: Node) -> frozenset:
+    """The names of the object variables that are free in ``formula``."""
+    return frozenset(v.name for v in free_variables(formula) if isinstance(v, Variable))
+
+
+def free_parameter_names(formulas: Iterable[Node]) -> Tuple[str, ...]:
+    """The names of the variables that are free in at least one of ``formulas``, sorted.
+
+    A variable is free in a formula when no quantifier, counting quantifier,
+    cardinality term or IF-logic binder of that formula binds it; a name that is bound
+    in one formula and free in another is in the result. A lambda-bound variable is not
+    an object variable and is never in it.
+    """
+    names: set = set()
+    for formula in formulas:
+        names |= _free_names(formula)
+    return tuple(sorted(names))
+
+
+def parameterize(formulas: Sequence[Node], *, avoid: Iterable[str] = (),
+                 after_variables: bool = False) -> Tuple[List[Node], Dict[str, Constant]]:
+    """Replace every free variable of ``formulas`` by a constant, the same one in all of them.
+
+    Returns ``(closed, parameters)``: the formulas with every free occurrence of a
+    variable replaced, and a mapping from each variable's name to the constant that
+    stands for it. A variable that is bound inside a formula is left alone there (the
+    substitution is capture-avoiding), and a name that is free in one formula and bound
+    in another is replaced only where it is free. Formulas without a free variable
+    come back as they are.
+
+    By default the constants are minted (``_p0``, ``_p1``, …) and none of them has the
+    spelling of any name that ``formulas`` carry -- a predicate, function, constant,
+    sort, variable or nominal -- nor of any name in ``avoid``, so no constant of the
+    problem is captured by a parameter. Pass ``avoid`` for names of a vocabulary the
+    problem will be read together with.
+
+    With ``after_variables=True`` the constant carries the variable's own name, so that
+    a structure found for the closed formulas reports the parameter under the name the
+    caller wrote. A parameter that would then have the name of a constant of the
+    problem (``Constant('x')`` next to a free variable ``x``: the Unicode text tells the
+    two apart, ``P(x) ∧ Q('x')``, but a structure holds one entry per name) cannot be
+    told from that constant in a table keyed by name, so it is refused.
+
+    Raises:
+        NotImplementedError: ``after_variables`` is true and a free variable has the
+            name of a constant (plain or sorted) of ``formulas``.
+    """
+    formulas = list(formulas)
+    free_per_formula = [_free_names(formula) for formula in formulas]
+    names = sorted(set().union(*free_per_formula)) if free_per_formula else []
+    if not names:
+        return formulas, {}
+    parameters: Dict[str, Constant] = {}
+    if after_variables:
+        constants = {node.name for formula in formulas for node in formula.walk()
+                     if isinstance(node, (Constant, SortedConstant))}
+        for name in names:
+            if name in constants:
+                raise NotImplementedError(
+                    f"a free variable {name!r} and a constant {name!r} are in one problem: "
+                    "a structure holds one entry per name, so the parameter that stands "
+                    "for the variable could not be told from the constant. Rename one of "
+                    "them.")
+            parameters[name] = Constant(name)
+    else:
+        taken = set(symbol_names(*formulas)) | set(avoid)
+        index = 0
+        for name in names:
+            while f"_p{index}" in taken:
+                index += 1
+            parameters[name] = Constant(f"_p{index}")
+            taken.add(f"_p{index}")
+            index += 1
+    closed = []
+    for formula, free in zip(formulas, free_per_formula):
+        for name in sorted(free):
+            formula = substitute(formula, Variable(name), parameters[name])
+        closed.append(formula)
+    return closed, parameters

unicode_logic_kit/fol/_ho_nodes.py

@@ -0,0 +1,448 @@
+"""Third-order AST: a predicate standing in ARGUMENT position, and its typing.
+
+Second-order syntax lets a predicate variable be *bound* (``∀P φ``); it still
+only ever appears as the HEAD of an application, ``P(x)``. Third-order syntax
+adds the one thing that is genuinely a level up: a predicate whose ARGUMENT is
+itself a predicate — ``Positive(G)``, ``Essence(G, x)``,
+``Positive(λx. ¬G(x))``. No amount of extra quantification reaches that; it is a
+change to the argument layer, which is why it needs its own node
+(:class:`PredicateTerm`), its own grammar modes (``third_order`` /
+``third_order_modal``, see ``_MODE_ATOM_ARGS`` in ``_fol_nodes.py``) and its own
+typing pass (:func:`analyse_signatures`).
+
+**The node.** ``PredicateTerm(name)`` is a leaf that occupies an argument slot
+and denotes the property/relation the name stands for — not a truth value. It is
+deliberately *not* an ``Atom`` with zero arguments: ``P`` as a nullary atom is a
+proposition, ``PredicateTerm("P")`` is the predicate itself, and conflating them
+is exactly the type error the third order exists to make visible. Its ``name``
+field is spelled like ``Variable.name`` / ``Constant.name`` / ``LambdaVar.name``
+so the shared term renderers reach it by the same path.
+
+Every first-order back-end refuses it, for the same reason
+``SecondOrderQuantifier`` does: a property argument has no first-order or
+SMT-LIB reading. The HOL exporters are where it goes
+(:mod:`unicode_logic_kit.hol.thirdorder`,
+:mod:`unicode_logic_kit.hol.ho_modal`).
+
+**The typing pass.** A predicate's argument slots are not annotated in the
+surface syntax, so what each slot holds — an individual, or a property of arity
+k — is *inferred*, and the inference has to run over a whole theory rather than
+one formula: ``Positive(Phi)`` alone says nothing about Phi's arity, while
+``Positive(G)`` together with ``G(x)`` elsewhere in the same axiom set fixes it
+at 1. :func:`analyse_signatures` takes any number of formulas and returns one
+:class:`Signatures` for all of them: it collects the constraints (an application
+fixes its head's arity; a λ-argument fixes its slot's arity by binder depth; a
+PredicateTerm links its own arity to its slot's) and closes them under
+propagation until nothing moves.
+
+Three ways that can fail, all raised rather than papered over: a predicate applied
+at two different arities (``ConflictingArityError``, shared with the second-order
+inference), a slot used once for an individual and once for a property
+(:class:`MixedSlotError`), and a slot that would have to hold a property of
+PROPERTIES (:class:`NestedPropertySlotError`): ``Meta(Pos) ∧ Pos(G)`` makes ``Pos`` a
+predicate of properties and puts it in a slot of ``Meta``, a fourth-order typing that
+a slot type ``("p", k)`` (a relation on individuals) cannot state.
+
+One way it can be *underdetermined*: a slot no evidence ever reaches — e.g.
+``∀Phi (Positive(Phi) → □Positive(Phi))`` read entirely on its own, where Phi is
+never applied and shares its slot with nothing that is. Such a slot defaults to
+a property of arity **1**, because argument position is what makes it a property
+slot at all and 1 is the only reading on which the formula says what it is
+plainly meant to say; arity 0 would silently retype it as a predicate over
+PROPOSITIONS. The default is recorded in :attr:`Signatures.defaulted` so a
+caller that would rather refuse than guess can see exactly which slots were
+guessed — the HOL exporters print them as a comment in the emitted theory.
+"""
+
+from dataclasses import dataclass
+from typing import Dict, FrozenSet, List, Sequence, Set, Tuple
+
+from ._fol_nodes import (
+    Node, Z3Env, NODE_CLASSES, Atom, PARSER_OPS, ParserOp, parser_ops_for_mode,
+)
+from ._so_nodes import (
+    SecondOrderQuantifier, ConflictingArityError, _infer_so_arity,
+)
+from ._truth_constants import truth_value
+from .naming import ParsingError
+
+
+_NO_EXPORT = (
+    "A predicate in argument position (third order) has no first-order or "
+    "SMT-LIB reading: its argument denotes a PROPERTY, not an individual. Use "
+    "the HOL exporters (hol.thirdorder / hol.ho_modal) instead."
+)
+
+
+@dataclass(frozen=True)
+class PredicateTerm(Node):
+    """A predicate name occupying an argument slot — the third-order term.
+
+    ``name`` is the predicate's name as written. The node denotes the property
+    (or relation) itself, so it is a TERM, not a formula: ``Positive(G)``
+    parses to ``Atom("Positive", [PredicateTerm("G")])``, whereas ``Positive``
+    applied to the *proposition* G would be ``Atom("Positive", [Atom("G", [])])``.
+
+    The node carries no arity of its own. What arity the property has is a
+    property of the whole theory, not of this occurrence, and is answered by
+    :func:`analyse_signatures`.
+    """
+
+    name: str
+
+    def _tree_parts(self):
+        """Return the ``PredicateTerm: G`` label and no children (it is a leaf)."""
+        return f"PredicateTerm: {self.name}", []
+
+    def to_dict(self):
+        """Serialise to dict with type tag and predicate name."""
+        return {"_type": "PredicateTerm", "name": self.name}
+
+    @staticmethod
+    def from_dict(d):
+        """Deserialise a PredicateTerm from a dict produced by to_dict."""
+        return PredicateTerm(d["name"])
+
+    def to_z3(self, env: Z3Env = None):
+        """Reject Z3 export: a property argument is not SMT-expressible."""
+        raise NotImplementedError(_NO_EXPORT)
+
+    def to_prover9(self) -> str:
+        """Reject Prover9 export: a property argument is not first-order."""
+        raise NotImplementedError(_NO_EXPORT)
+
+    def to_tptp(self) -> str:
+        """Reject TPTP (FOF) export: a property argument is not first-order."""
+        raise NotImplementedError(_NO_EXPORT)
+
+
+NODE_CLASSES.update({"PredicateTerm": PredicateTerm})
+
+
+# =========================
+# Signature inference
+# =========================
+
+
+class MixedSlotError(ParsingError):
+    """Raised when one argument slot is used for both an individual and a property.
+
+    ``Loves(x, y)`` and ``Loves(x, G)`` cannot both be right: the second slot
+    would have to hold an individual and a property at once. Subclasses
+    ParsingError so a caller catching the parser's error type also catches this.
+    """
+
+    def __init__(self, predicate: str, position: int):
+        message = (
+            f"TYPE_ERROR: argument slot {position} of '{predicate}' is used "
+            f"both for an individual and for a predicate; a slot holds one or "
+            f"the other, not both."
+        )
+        self.args = (message,)
+
+    def __str__(self):
+        return self.args[0]
+
+
+class NestedPropertySlotError(ParsingError):
+    """Raised when a property slot would hold a predicate that itself takes a property.
+
+    A slot that holds a predicate is typed as a property of INDIVIDUALS, of the arity of that
+    predicate. ``Meta(Pos)`` together with ``Pos(G)`` breaks that: ``Pos`` takes a property,
+    so it is a predicate of properties, and what ``Meta`` takes is then a property of
+    properties (a fourth-order typing). The typing cannot state it, so it is refused instead of
+    being typed as if ``Pos`` were a property of individuals. Subclasses ParsingError, like
+    :class:`MixedSlotError`.
+    """
+
+    def __init__(self, host: str, host_position: int, occupant: str, occupant_position: int):
+        message = (
+            f"TYPE_ERROR: '{host}' takes the predicate '{occupant}' as a property in "
+            f"argument slot {host_position}, but '{occupant}' itself takes a property in its "
+            f"argument slot {occupant_position}: '{host}' would be a predicate of predicates "
+            f"of properties (fourth order or higher). A property slot holds a relation on "
+            f"individuals only, so this is refused rather than typed as if '{occupant}' were "
+            f"a property of individuals."
+        )
+        self.args = (message,)
+
+    def __str__(self):
+        return self.args[0]
+
+
+#: What one argument slot holds. ``"i"`` is an individual; ``("p", k)`` is a
+#: property/relation of arity ``k``.
+INDIVIDUAL = "i"
+
+
+@dataclass(frozen=True)
+class Signatures:
+    """The result of :func:`analyse_signatures` over one or more formulas.
+
+    ``arity`` maps every predicate NAME that is applied (or reached by
+    propagation) to its arity. ``slots`` maps a predicate name to its argument
+    signature — a tuple with one entry per position, each either
+    :data:`INDIVIDUAL` or ``("p", k)`` for a property of arity ``k``.
+    ``defaulted`` names the ``(predicate, position)`` pairs whose property arity
+    no evidence fixed and which therefore defaulted to 1.
+    """
+
+    arity: Dict[str, int]
+    slots: Dict[str, Tuple[object, ...]]
+    defaulted: FrozenSet[Tuple[str, int]]
+
+    def is_third_order(self) -> bool:
+        """True iff some predicate takes a property argument (i.e. the theory really is third order)."""
+        return any(s != INDIVIDUAL for sig in self.slots.values() for s in sig)
+
+    def property_slots(self) -> List[Tuple[str, int, int]]:
+        """Return ``(predicate, position, arity)`` for every property-holding slot, sorted."""
+        out = []
+        for pred in sorted(self.slots):
+            for pos, kind in enumerate(self.slots[pred]):
+                if kind != INDIVIDUAL:
+                    out.append((pred, pos, kind[1]))
+        return out
+
+
+def _lambda_depth(node: Node) -> int:
+    """Return how many leading λ binders ``node`` has (0 if it is not a Lambda).
+
+    ``λx. λy. φ`` is a binary relation, so its depth IS the arity of the
+    property it denotes. Imported lazily: Lambda lives in _msfl_nodes, which
+    imports this module's dependencies rather than the other way round.
+    """
+    from ._msfl_nodes import Lambda
+    depth = 0
+    while isinstance(node, Lambda):
+        depth += 1
+        node = node.body
+    return depth
+
+
+def analyse_signatures(formulas: Sequence[Node]) -> Signatures:
+    """Infer every predicate's arity and argument signature across ``formulas``.
+
+    Runs over the formulas TOGETHER, because that is the scope on which the
+    answer is determined: ``Positive(Phi)`` in one axiom and ``Phi(x)`` in
+    another jointly fix Phi's arity at 1, and neither does so alone.
+
+    Raises ConflictingArityError if a predicate is applied at two arities,
+    :class:`MixedSlotError` if one slot holds an individual in one place and a
+    property in another, and :class:`NestedPropertySlotError` if a predicate that
+    stands in a property slot itself takes a property (a property of properties,
+    which the typing cannot state). A property slot that no evidence reaches defaults to
+    arity 1 and is listed in the result's ``defaulted`` — see this module's
+    docstring for why 1 and not 0.
+    """
+    app_arity: Dict[str, Set[int]] = {}
+    # slot_kind[(pred, pos)] is INDIVIDUAL, or ("p", None) until its arity is known.
+    slot_kind: Dict[Tuple[str, int], object] = {}
+    # Which predicate NAMES occupy which slots (a slot may be occupied by several).
+    slot_occupants: Dict[Tuple[str, int], Set[str]] = {}
+    # Property arities pinned directly by a λ-argument's binder depth.
+    slot_lambda_arity: Dict[Tuple[str, int], Set[int]] = {}
+
+    def note_slot(pred: str, pos: int, kind: object) -> None:
+        prev = slot_kind.get((pred, pos))
+        if prev is None:
+            slot_kind[(pred, pos)] = kind
+            return
+        prev_is_prop = prev != INDIVIDUAL
+        now_is_prop = kind != INDIVIDUAL
+        if prev_is_prop != now_is_prop:
+            raise MixedSlotError(pred, pos)
+
+    def visit(node: Node) -> None:
+        if isinstance(node, Atom) and truth_value(node) is None:
+            # (`$true` / `$false` are constants, not predicates: nothing to type.)
+            app_arity.setdefault(node.predicate, set()).add(len(node.args))
+            for pos, arg in enumerate(node.args):
+                if isinstance(arg, PredicateTerm):
+                    note_slot(node.predicate, pos, ("p", None))
+                    slot_occupants.setdefault((node.predicate, pos), set()).add(arg.name)
+                elif _lambda_depth(arg) > 0:
+                    note_slot(node.predicate, pos, ("p", None))
+                    slot_lambda_arity.setdefault((node.predicate, pos), set()).add(
+                        _lambda_depth(arg))
+                else:
+                    note_slot(node.predicate, pos, INDIVIDUAL)
+        for child in node._child_nodes():
+            visit(child)
+
+    for formula in formulas:
+        visit(formula)
+
+    # An application fixes its head's arity outright; two different arities for
+    # one name is the same error the second-order inference already raises.
+    arity: Dict[str, int] = {}
+    for pred, arities in app_arity.items():
+        if len(arities) > 1:
+            raise ConflictingArityError(pred, sorted(arities))
+        arity[pred] = next(iter(arities))
+
+    # A λ-argument pins its slot's arity directly.
+    slot_arity: Dict[Tuple[str, int], int] = {}
+    for slot, depths in slot_lambda_arity.items():
+        if len(depths) > 1:
+            raise ConflictingArityError(f"{slot[0]}[{slot[1]}]", sorted(depths))
+        slot_arity[slot] = next(iter(depths))
+
+    # A predicate that sits in a property slot is typed as a property of INDIVIDUALS (a slot
+    # type is ("p", k), a relation on individuals). One that takes a property itself is a
+    # predicate of properties, and the slot would have to hold a property of properties.
+    property_position: Dict[str, int] = {}
+    for (name, position), kind in sorted(slot_kind.items()):
+        if kind != INDIVIDUAL:
+            property_position.setdefault(name, position)
+    for (host, host_position), occupants in sorted(slot_occupants.items()):
+        for occupant in sorted(occupants):
+            if occupant in property_position:
+                raise NestedPropertySlotError(host, host_position, occupant,
+                                              property_position[occupant])
+
+    # Close under propagation: a known predicate arity fixes every slot it sits
+    # in, and a known slot arity fixes every predicate sitting in it.
+    changed = True
+    while changed:
+        changed = False
+        for slot, occupants in slot_occupants.items():
+            known = {arity[p] for p in occupants if p in arity}
+            if slot in slot_arity:
+                known.add(slot_arity[slot])
+            if len(known) > 1:
+                raise ConflictingArityError(f"{slot[0]}[{slot[1]}]", sorted(known))
+            if not known:
+                continue
+            value = next(iter(known))
+            if slot_arity.get(slot) != value:
+                slot_arity[slot] = value
+                changed = True
+            for p in occupants:
+                if arity.get(p) != value:
+                    if p in arity:
+                        raise ConflictingArityError(p, sorted({arity[p], value}))
+                    arity[p] = value
+                    changed = True
+
+    # Whatever propagation never reached is a property slot with no evidence.
+    defaulted: Set[Tuple[str, int]] = set()
+    for slot, kind in slot_kind.items():
+        if kind == INDIVIDUAL:
+            continue
+        if slot not in slot_arity:
+            slot_arity[slot] = 1
+            defaulted.add(slot)
+            for p in slot_occupants.get(slot, ()):
+                arity.setdefault(p, 1)
+
+    slots: Dict[str, Tuple[object, ...]] = {}
+    for pred, n in arity.items():
+        sig = []
+        for pos in range(n):
+            kind = slot_kind.get((pred, pos), INDIVIDUAL)
+            sig.append(INDIVIDUAL if kind == INDIVIDUAL
+                       else ("p", slot_arity[(pred, pos)]))
+        slots[pred] = tuple(sig)
+
+    return Signatures(arity, slots, frozenset(defaulted))
+
+
+def has_property_argument(node: Node) -> bool:
+    """True iff some predicate application in ``node`` has a property argument.
+
+    That is the syntactic marker of third order — a PredicateTerm or a
+    λ-abstraction sitting in an argument slot. Used to keep the second-order
+    path exactly as it was: a formula without one is answered by the cheaper
+    application-scan, unchanged, and pays nothing for the richer inference.
+    """
+    if isinstance(node, Atom):
+        for arg in node.args:
+            if isinstance(arg, PredicateTerm) or _lambda_depth(arg) > 0:
+                return True
+    return any(has_property_argument(child) for child in node._child_nodes())
+
+
+def infer_bound_arity(body: Node, predname: str) -> int:
+    """Infer a third-order-bound predicate variable's arity from ``body``.
+
+    The third-order counterpart of ``_so_nodes._infer_so_arity``: it answers the
+    same question, but has one more source of evidence to consult, because in a
+    third-order formula ``predname`` may never be applied at all and still be a
+    property — ``∀Phi (Positive(Phi) → □Positive(Phi))``. Delegates to
+    :func:`analyse_signatures`, whose propagation covers both cases; falls back
+    to 0 for a name that genuinely occurs nowhere, matching the second-order
+    reading of an unapplied predicate variable as propositional.
+
+    A body with no property argument at all IS a second-order body, and is sent
+    straight to ``_infer_so_arity`` — same answer, same cost, and the
+    second-order mode's behaviour is then unchanged by construction rather than
+    by inspection.
+
+    Shadowing follows ``_infer_so_arity``: an inner binder over the SAME name
+    starts a fresh binding, so its scope is cut out before the analysis.
+    """
+    if not has_property_argument(body):
+        return _infer_so_arity(body, predname)
+    pruned = _prune_shadowed(body, predname)
+    signatures = analyse_signatures([pruned])
+    return signatures.arity.get(predname, 0)
+
+
+def _prune_shadowed(node: Node, predname: str) -> Node:
+    """Replace every subformula that rebinds ``predname`` with a constant-true stand-in.
+
+    The inner binder's scope must not contribute evidence about the OUTER
+    binding, so it is cut away before the signature analysis runs. The stand-in
+    is a zero-argument atom under a reserved name that no source formula can
+    spell (it contains a space), so it cannot collide with a real predicate.
+    """
+    if isinstance(node, SecondOrderQuantifier) and node.predicate == predname:
+        return Atom("shadowed scope", [])
+    return node.map_children(lambda child: _prune_shadowed(child, predname))
+
+
+# =========================
+# Grammar-mode assembly
+# =========================
+#
+# The two third-order modes are not a new operator set — they are an EXISTING
+# operator set over the widened argument layer. ``third_order`` is the
+# second-order mode's operators; ``third_order_modal`` is those plus the whole
+# modal family. Rather than re-registering ~40 ParserOps (which would drift the
+# moment an operator is added to one mode and not the other), each is CLONED
+# from its sources, so the third-order modes accept exactly what their base
+# modes accept, by construction. ``tests/test_third_order.py`` pins that
+# correspondence.
+
+
+def _clone_parser_ops(target: str, sources: Sequence[str]) -> List[ParserOp]:
+    """Register into ``target`` a copy of every ParserOp of the ``sources``, deduped.
+
+    Two source modes overlap (the classical connectives and the first-order
+    quantifier are registered for both ``modal`` and ``second_order``); an
+    operator is taken from whichever source names it first and skipped
+    afterwards, keyed on the parse-level identity that matters —
+    ``(level, rule_alias, grammar, only_name)``. Appends to PARSER_OPS and
+    returns what was appended.
+    """
+    seen = set()
+    added: List[ParserOp] = []
+    for source in sources:
+        for op in parser_ops_for_mode(source):
+            key = (op.level, op.rule_alias, op.grammar, op.only_name)
+            if key in seen:
+                continue
+            seen.add(key)
+            clone = ParserOp(target, op.level, op.terminal_name, op.terminal_def,
+                             op.grammar, op.rule_alias, op.transform,
+                             op.node_class, op.only_name)
+            PARSER_OPS.append(clone)
+            added.append(clone)
+    return added
+
+
+# NOT called here. Cloning has to happen after EVERY module that registers an
+# operator for a source mode has run -- _hybrid_nodes registers @i / nominals
+# for "modal" and is imported after this module's own dependencies -- so the
+# call site is nodes.py, which is the one place that controls that order.