1"""
    2- Authors: Peter Mawhorter
    3- Consulted:
    4- Date: 2022-3-3
    5- Purpose: Core types and tools for dealing with them.
    6
    7This file defines the main types used for processing and storing
    8`DiscreteExploration` objects. Note that the types in `open.py` like
    9`OpenExploration` represent more generic and broadly capable types.
   10
   11Key types defined here are:
   12
   13- `DecisionGraph`: Represents a graph of decisions, including observed
   14    connections to unknown destinations. This works well for games that
   15    focus on rooms with discrete exits where there are few open spaces to
   16    explore, and where pretending that each decision has a discrete set
   17    of options is not too much of a distortion.
   18- `DiscreteExploration`: A list of `DecisionGraph`s with position and
   19    transition information representing exploration over time.
   20"""
   21
   22# TODO: Some way to specify the visibility conditions of a transition,
   23# separately from its traversal conditions? Or at least a way to specify
   24# that a transition is only visible when traversable (like successive
   25# upgrades or warp zone connections).
   26
   27from typing import (
   28    Any, Optional, List, Set, Union, cast, Tuple, Dict, TypedDict,
   29    Sequence, Collection, Literal, get_args, Callable, TypeVar,
   30    Iterator, Generator
   31)
   32
   33import copy
   34import warnings
   35import inspect
   36
   37from . import graphs
   38from . import base
   39from . import utils
   40from . import commands
   41
   42
   43#---------#
   44# Globals #
   45#---------#
   46
   47ENDINGS_DOMAIN = 'endings'
   48"""
   49Domain value for endings.
   50"""
   51
   52TRIGGERS_DOMAIN = 'triggers'
   53"""
   54Domain value for triggers.
   55"""
   56
   57
   58#------------------#
   59# Supporting types #
   60#------------------#
   61
   62
   63LookupResult = TypeVar('LookupResult')
   64"""
   65A type variable for lookup results from the generic
   66`DecisionGraph.localLookup` function.
   67"""
   68
   69LookupLayersList = List[Union[None, int, str]]
   70"""
   71A list of layers to look things up in, consisting of `None` for the
   72starting provided decision set, integers for zone heights, and some
   73custom strings like "fallback" and "all" for fallback sets.
   74"""
   75
   76
   77class DecisionInfo(TypedDict):
   78    """
   79    The information stored per-decision in a `DecisionGraph` includes
   80    the decision name (since the key is a decision ID), the domain, a
   81    tags dictionary, and an annotations list.
   82    """
   83    name: base.DecisionName
   84    domain: base.Domain
   85    tags: Dict[base.Tag, base.TagValue]
   86    annotations: List[base.Annotation]
   87
   88
   89#-----------------------#
   90# Transition properties #
   91#-----------------------#
   92
   93class TransitionProperties(TypedDict, total=False):
   94    """
   95    Represents bundled properties of a transition, including a
   96    requirement, effects, tags, and/or annotations. Does not include the
   97    reciprocal. Has the following slots:
   98
   99    - `'requirement'`: The requirement for the transition. This is
  100        always a `Requirement`, although it might be `ReqNothing` if
  101        nothing special is required.
  102    - `'consequence'`: The `Consequence` of the transition.
  103    - `'tags'`: Any tags applied to the transition (as a dictionary).
  104    - `'annotations'`: A list of annotations applied to the transition.
  105    """
  106    requirement: base.Requirement
  107    consequence: base.Consequence
  108    tags: Dict[base.Tag, base.TagValue]
  109    annotations: List[base.Annotation]
  110
  111
  112def mergeProperties(
  113    a: Optional[TransitionProperties],
  114    b: Optional[TransitionProperties]
  115) -> TransitionProperties:
  116    """
  117    Merges two sets of transition properties, following these rules:
  118
  119    1. Tags and annotations are combined. Annotations from the
  120        second property set are ordered after those from the first.
  121    2. If one of the transitions has a `ReqNothing` instance as its
  122        requirement, we use the other requirement. If both have
  123        complex requirements, we create a new `ReqAll` which
  124        combines them as the requirement.
  125    3. The consequences are merged by placing all of the consequences of
  126        the first transition before those of the second one. This may in
  127        some cases change the net outcome of those consequences,
  128        because not all transition properties are compatible. (Imagine
  129        merging two transitions one of which causes a capability to be
  130        gained and the other of which causes a capability to be lost.
  131        What should happen?).
  132    4. The result will not list a reciprocal.
  133
  134    If either transition is `None`, then a deep copy of the other is
  135    returned. If both are `None`, then an empty transition properties
  136    dictionary is returned, with `ReqNothing` as the requirement, no
  137    effects, no tags, and no annotations.
  138
  139    Deep copies of consequences are always made, so that any `Effects`
  140    applications which edit effects won't end up with entangled effects.
  141    """
  142    if a is None:
  143        if b is None:
  144            return {
  145                "requirement": base.ReqNothing(),
  146                "consequence": [],
  147                "tags": {},
  148                "annotations": []
  149            }
  150        else:
  151            return copy.deepcopy(b)
  152    elif b is None:
  153        return copy.deepcopy(a)
  154    # implicitly neither a or b is None below
  155
  156    result: TransitionProperties = {
  157        "requirement": base.ReqNothing(),
  158        "consequence": copy.deepcopy(a["consequence"] + b["consequence"]),
  159        "tags": a["tags"] | b["tags"],
  160        "annotations": a["annotations"] + b["annotations"]
  161    }
  162
  163    if a["requirement"] == base.ReqNothing():
  164        result["requirement"] = b["requirement"]
  165    elif b["requirement"] == base.ReqNothing():
  166        result["requirement"] = a["requirement"]
  167    else:
  168        result["requirement"] = base.ReqAll(
  169            [a["requirement"], b["requirement"]]
  170        )
  171
  172    return result
  173
  174
  175#---------------------#
  176# Errors and warnings #
  177#---------------------#
  178
  179class TransitionBlockedWarning(Warning):
  180    """
  181    An warning type for indicating that a transition which has been
  182    requested does not have its requirements satisfied by the current
  183    game state.
  184    """
  185    pass
  186
  187
  188class BadStart(ValueError):
  189    """
  190    An error raised when the start method is used improperly.
  191    """
  192    pass
  193
  194
  195class MissingDecisionError(KeyError):
  196    """
  197    An error raised when attempting to use a decision that does not
  198    exist.
  199    """
  200    pass
  201
  202
  203class AmbiguousDecisionSpecifierError(KeyError):
  204    """
  205    An error raised when an ambiguous decision specifier is provided.
  206    Note that if a decision specifier simply doesn't match anything, you
  207    will get a `MissingDecisionError` instead.
  208    """
  209    pass
  210
  211
  212class AmbiguousTransitionError(KeyError):
  213    """
  214    An error raised when an ambiguous transition is specified.
  215    If a transition specifier simply doesn't match anything, you
  216    will get a `MissingTransitionError` instead.
  217    """
  218    pass
  219
  220
  221class MissingTransitionError(KeyError):
  222    """
  223    An error raised when attempting to use a transition that does not
  224    exist.
  225    """
  226    pass
  227
  228
  229class MissingMechanismError(KeyError):
  230    """
  231    An error raised when attempting to use a mechanism that does not
  232    exist.
  233    """
  234    pass
  235
  236
  237class MissingZoneError(KeyError):
  238    """
  239    An error raised when attempting to use a zone that does not exist.
  240    """
  241    pass
  242
  243
  244class InvalidLevelError(ValueError):
  245    """
  246    An error raised when an operation fails because of an invalid zone
  247    level.
  248    """
  249    pass
  250
  251
  252class InvalidDestinationError(ValueError):
  253    """
  254    An error raised when attempting to perform an operation with a
  255    transition but that transition does not lead to a destination that's
  256    compatible with the operation.
  257    """
  258    pass
  259
  260
  261class ExplorationStatusError(ValueError):
  262    """
  263    An error raised when attempting to perform an operation that
  264    requires a previously-visited destination with a decision that
  265    represents a not-yet-visited decision, or vice versa. For
  266    `Situation`s, Exploration states 'unknown', 'hypothesized', and
  267    'noticed' count as "not-yet-visited" while 'exploring' and 'explored'
  268    count as "visited" (see `base.hasBeenVisited`) Meanwhile, in a
  269    `DecisionGraph` where exploration statuses are not present, the
  270    presence or absence of the 'unconfirmed' tag is used to determine
  271    whether something has been confirmed or not.
  272    """
  273    pass
  274
  275
  276WARN_OF_NAME_COLLISIONS = False
  277"""
  278Whether or not to issue warnings when two decision names are the same.
  279"""
  280
  281
  282class DecisionCollisionWarning(Warning):
  283    """
  284    A warning raised when attempting to create a new decision using the
  285    name of a decision that already exists.
  286    """
  287    pass
  288
  289
  290class TransitionCollisionError(ValueError):
  291    """
  292    An error raised when attempting to re-use a transition name for a
  293    new transition, or otherwise when a transition name conflicts with
  294    an already-established transition.
  295    """
  296    pass
  297
  298
  299class MechanismCollisionError(ValueError):
  300    """
  301    An error raised when attempting to re-use a mechanism name at the
  302    same decision where a mechanism with that name already exists.
  303    """
  304    pass
  305
  306
  307class DomainCollisionError(KeyError):
  308    """
  309    An error raised when attempting to create a domain with the same
  310    name as an existing domain.
  311    """
  312    pass
  313
  314
  315class MissingFocalContextError(KeyError):
  316    """
  317    An error raised when attempting to pick out a focal context with a
  318    name that doesn't exist.
  319    """
  320    pass
  321
  322
  323class FocalContextCollisionError(KeyError):
  324    """
  325    An error raised when attempting to create a focal context with the
  326    same name as an existing focal context.
  327    """
  328    pass
  329
  330
  331class InvalidActionError(TypeError):
  332    """
  333    An error raised when attempting to take an exploration action which
  334    is not correctly formed.
  335    """
  336    pass
  337
  338
  339class ImpossibleActionError(ValueError):
  340    """
  341    An error raised when attempting to take an exploration action which
  342    is correctly formed but which specifies an action that doesn't match
  343    up with the graph state.
  344    """
  345    pass
  346
  347
  348class DoubleActionError(ValueError):
  349    """
  350    An error raised when attempting to set up an `ExplorationAction`
  351    when the current situation already has an action specified.
  352    """
  353    pass
  354
  355
  356class InactiveDomainWarning(Warning):
  357    """
  358    A warning used when an inactive domain is referenced but the
  359    operation in progress can still succeed (for example when
  360    deactivating an already-inactive domain).
  361    """
  362
  363
  364class ZoneCollisionError(ValueError):
  365    """
  366    An error raised when attempting to re-use a zone name for a new zone,
  367    or otherwise when a zone name conflicts with an already-established
  368    zone.
  369    """
  370    pass
  371
  372
  373#---------------------#
  374# DecisionGraph class #
  375#---------------------#
  376
  377class DecisionGraph(
  378    graphs.UniqueExitsGraph[base.DecisionID, base.Transition]
  379):
  380    """
  381    Represents a view of the world as a topological graph at a moment in
  382    time. It derives from `networkx.MultiDiGraph`.
  383
  384    Each node (a `Decision`) represents a place in the world where there
  385    are multiple opportunities for travel/action, or a dead end where
  386    you must turn around and go back; typically this is a single room in
  387    a game, but sometimes one room has multiple decision points. Edges
  388    (`Transition`s) represent choices that can be made to travel to
  389    other decision points (e.g., taking the left door), or when they are
  390    self-edges, they represent actions that can be taken within a
  391    location that affect the world or the game state.
  392
  393    Each `Transition` includes a `Effects` dictionary
  394    indicating the effects that it has. Other effects of the transition
  395    that are not simple enough to be included in this format may be
  396    represented in an `DiscreteExploration` by changing the graph in the
  397    next step to reflect further effects of a transition.
  398
  399    In addition to normal transitions between decisions, a
  400    `DecisionGraph` can represent potential transitions which lead to
  401    unknown destinations. These are represented by adding decisions with
  402    the `'unconfirmed'` tag (whose names where not specified begin with
  403    `'_u.'`) with a separate unconfirmed decision for each transition
  404    (although where it's known that two transitions lead to the same
  405    unconfirmed decision, this can be represented as well).
  406
  407    Both nodes and edges can have `Annotation`s associated with them that
  408    include extra details about the explorer's perception of the
  409    situation. They can also have `Tag`s, which represent specific
  410    categories a transition or decision falls into.
  411
  412    Nodes can also be part of one or more `Zones`, and zones can also be
  413    part of other zones, allowing for a hierarchical description of the
  414    underlying space.
  415
  416    Equivalences can be specified to mark that some combination of
  417    capabilities can stand in for another capability.
  418    """
  419    def __init__(self) -> None:
  420        super().__init__()
  421
  422        self.zones: Dict[base.Zone, base.ZoneInfo] = {}
  423        """
  424        Mapping from zone names to zone info
  425        """
  426
  427        self.unknownCount: int = 0
  428        """
  429        Number of unknown decisions that have been created (not number
  430        of current unknown decisions, which is likely lower)
  431        """
  432
  433        self.equivalences: base.Equivalences = {}
  434        """
  435        See `base.Equivalences`. Determines what capabilities and/or
  436        mechanism states can count as active based on alternate
  437        requirements.
  438        """
  439
  440        self.reversionTypes: Dict[str, Set[str]] = {}
  441        """
  442        This tracks shorthand reversion types. See `base.revertedState`
  443        for how these are applied. Keys are custom names and values are
  444        reversion type strings that `base.revertedState` could access.
  445        """
  446
  447        self.nextID: base.DecisionID = 0
  448        """
  449        The ID to use for the next new decision we create.
  450        """
  451
  452        self.nextMechanismID: base.MechanismID = 0
  453        """
  454        ID for the next mechanism.
  455        """
  456
  457        self.mechanisms: Dict[
  458            base.MechanismID,
  459            Tuple[Optional[base.DecisionID], base.MechanismName]
  460        ] = {}
  461        """
  462        Mapping from `MechanismID`s to (`DecisionID`, `MechanismName`)
  463        pairs. For global mechanisms, the `DecisionID` is None.
  464        """
  465
  466        self.globalMechanisms: Dict[
  467            base.MechanismName,
  468            base.MechanismID
  469        ] = {}
  470        """
  471        Global mechanisms
  472        """
  473
  474        self.nameLookup: Dict[base.DecisionName, List[base.DecisionID]] = {}
  475        """
  476        A cache for name -> ID lookups
  477        """
  478
  479    # Note: not hashable
  480
  481    def __eq__(self, other):
  482        """
  483        Equality checker. `DecisionGraph`s can only be equal to other
  484        `DecisionGraph`s, not to other kinds of things.
  485        """
  486        if not isinstance(other, DecisionGraph):
  487            return False
  488        else:
  489            # Checks nodes, edges, and all attached data
  490            if not super().__eq__(other):
  491                return False
  492
  493            # Check unknown count
  494            if self.unknownCount != other.unknownCount:
  495                return False
  496
  497            # Check zones
  498            if self.zones != other.zones:
  499                return False
  500
  501            # Check equivalences
  502            if self.equivalences != other.equivalences:
  503                return False
  504
  505            # Check reversion types
  506            if self.reversionTypes != other.reversionTypes:
  507                return False
  508
  509            # Check mechanisms
  510            if self.nextMechanismID != other.nextMechanismID:
  511                return False
  512
  513            if self.mechanisms != other.mechanisms:
  514                return False
  515
  516            if self.globalMechanisms != other.globalMechanisms:
  517                return False
  518
  519            # Check names:
  520            if self.nameLookup != other.nameLookup:
  521                return False
  522
  523            return True
  524
  525    def listDifferences(
  526        self,
  527        other: 'DecisionGraph'
  528    ) -> Generator[str, None, None]:
  529        """
  530        Generates strings describing differences between this graph and
  531        another graph. This does NOT perform graph matching, so it will
  532        consider graphs different even if they have identical structures
  533        but use different IDs for the nodes in those structures.
  534        """
  535        if not isinstance(other, DecisionGraph):
  536            yield "other is not a graph"
  537        else:
  538            suppress = False
  539            myNodes = set(self.nodes)
  540            theirNodes = set(other.nodes)
  541            for n in myNodes:
  542                if n not in theirNodes:
  543                    suppress = True
  544                    yield (
  545                        f"other graph missing node {n}"
  546                    )
  547                else:
  548                    if self.nodes[n] != other.nodes[n]:
  549                        suppress = True
  550                        yield (
  551                            f"other graph has differences at node {n}:"
  552                            f"\n  Ours:  {self.nodes[n]}"
  553                            f"\nTheirs:  {other.nodes[n]}"
  554                        )
  555                    myDests = self.destinationsFrom(n)
  556                    theirDests = other.destinationsFrom(n)
  557                    for tr in myDests:
  558                        myTo = myDests[tr]
  559                        if tr not in theirDests:
  560                            suppress = True
  561                            yield (
  562                                f"at {self.identityOf(n)}: other graph"
  563                                f" missing transition {tr!r}"
  564                            )
  565                        else:
  566                            theirTo = theirDests[tr]
  567                            if myTo != theirTo:
  568                                suppress = True
  569                                yield (
  570                                    f"at {self.identityOf(n)}: other"
  571                                    f" graph transition {tr!r} leads to"
  572                                    f" {theirTo} instead of {myTo}"
  573                                )
  574                            else:
  575                                myProps = self.edges[n, myTo, tr]  # type:ignore [index] # noqa
  576                                theirProps = other.edges[n, myTo, tr]  # type:ignore [index] # noqa
  577                                if myProps != theirProps:
  578                                    suppress = True
  579                                    yield (
  580                                        f"at {self.identityOf(n)}: other"
  581                                        f" graph transition {tr!r} has"
  582                                        f" different properties:"
  583                                        f"\n  Ours:  {myProps}"
  584                                        f"\nTheirs:  {theirProps}"
  585                                    )
  586            for extra in theirNodes - myNodes:
  587                suppress = True
  588                yield (
  589                    f"other graph has extra node {extra}"
  590                )
  591
  592            # TODO: Fix networkx stubs!
  593            if self.graph != other.graph:  # type:ignore [attr-defined]
  594                suppress = True
  595                yield (
  596                    " different graph attributes:"  # type:ignore [attr-defined]  # noqa
  597                    f"\n  Ours:  {self.graph}"
  598                    f"\nTheirs:  {other.graph}"
  599                )
  600
  601            # Checks any other graph data we might have missed
  602            if not super().__eq__(other) and not suppress:
  603                for attr in dir(self):
  604                    if attr.startswith('__') and attr.endswith('__'):
  605                        continue
  606                    if not hasattr(other, attr):
  607                        yield f"other graph missing attribute: {attr!r}"
  608                    else:
  609                        myVal = getattr(self, attr)
  610                        theirVal = getattr(other, attr)
  611                        if (
  612                            myVal != theirVal
  613                        and not ((callable(myVal) and callable(theirVal)))
  614                        ):
  615                            yield (
  616                                f"other has different val for {attr!r}:"
  617                                f"\n  Ours:  {myVal}"
  618                                f"\nTheirs:  {theirVal}"
  619                            )
  620                for attr in sorted(set(dir(other)) - set(dir(self))):
  621                    yield f"other has extra attribute: {attr!r}"
  622                yield "graph data is different"
  623                # TODO: More detail here!
  624
  625            # Check unknown count
  626            if self.unknownCount != other.unknownCount:
  627                yield "unknown count is different"
  628
  629            # Check zones
  630            if self.zones != other.zones:
  631                yield "zones are different"
  632
  633            # Check equivalences
  634            if self.equivalences != other.equivalences:
  635                yield "equivalences are different"
  636
  637            # Check reversion types
  638            if self.reversionTypes != other.reversionTypes:
  639                yield "reversionTypes are different"
  640
  641            # Check mechanisms
  642            if self.nextMechanismID != other.nextMechanismID:
  643                yield "nextMechanismID is different"
  644
  645            if self.mechanisms != other.mechanisms:
  646                yield "mechanisms are different"
  647
  648            if self.globalMechanisms != other.globalMechanisms:
  649                yield "global mechanisms are different"
  650
  651            # Check names:
  652            if self.nameLookup != other.nameLookup:
  653                for name in self.nameLookup:
  654                    if name not in other.nameLookup:
  655                        yield (
  656                            f"other graph is missing name lookup entry"
  657                            f" for {name!r}"
  658                        )
  659                    else:
  660                        mine = self.nameLookup[name]
  661                        theirs = other.nameLookup[name]
  662                        if theirs != mine:
  663                            yield (
  664                                f"name lookup for {name!r} is {theirs}"
  665                                f" instead of {mine}"
  666                            )
  667                extras = set(other.nameLookup) - set(self.nameLookup)
  668                if extras:
  669                    yield (
  670                        f"other graph has extra name lookup entries:"
  671                        f" {extras}"
  672                    )
  673
  674    def _assignID(self) -> base.DecisionID:
  675        """
  676        Returns the next `base.DecisionID` to use and increments the
  677        next ID counter.
  678        """
  679        result = self.nextID
  680        self.nextID += 1
  681        return result
  682
  683    def _assignMechanismID(self) -> base.MechanismID:
  684        """
  685        Returns the next `base.MechanismID` to use and increments the
  686        next ID counter.
  687        """
  688        result = self.nextMechanismID
  689        self.nextMechanismID += 1
  690        return result
  691
  692    def decisionInfo(self, dID: base.DecisionID) -> DecisionInfo:
  693        """
  694        Retrieves the decision info for the specified decision, as a
  695        live editable dictionary.
  696
  697        For example:
  698
  699        >>> g = DecisionGraph()
  700        >>> g.addDecision('A')
  701        0
  702        >>> g.annotateDecision('A', 'note')
  703        >>> g.decisionInfo(0)
  704        {'name': 'A', 'domain': 'main', 'tags': {}, 'annotations': ['note']}
  705        """
  706        return cast(DecisionInfo, self.nodes[dID])
  707
  708    def resolveDecision(
  709        self,
  710        spec: base.AnyDecisionSpecifier,
  711        zoneHint: Optional[base.Zone] = None,
  712        domainHint: Optional[base.Domain] = None
  713    ) -> base.DecisionID:
  714        """
  715        Given a decision specifier returns the ID associated with that
  716        decision, or raises an `AmbiguousDecisionSpecifierError` or a
  717        `MissingDecisionError` if the specified decision is either
  718        missing or ambiguous. Cannot handle strings that contain domain
  719        and/or zone parts; use
  720        `parsing.ParseFormat.parseDecisionSpecifier` to turn such
  721        strings into `DecisionSpecifier`s if you need to first.
  722
  723        Examples:
  724
  725        >>> g = DecisionGraph()
  726        >>> g.addDecision('A')
  727        0
  728        >>> g.addDecision('B')
  729        1
  730        >>> g.addDecision('C')
  731        2
  732        >>> g.addDecision('A')
  733        3
  734        >>> g.addDecision('B', 'menu')
  735        4
  736        >>> g.createZone('Z', 0)
  737        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
  738 annotations=[])
  739        >>> g.createZone('Z2', 0)
  740        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
  741 annotations=[])
  742        >>> g.createZone('Zup', 1)
  743        ZoneInfo(level=1, parents=set(), contents=set(), tags={},\
  744 annotations=[])
  745        >>> g.addDecisionToZone(0, 'Z')
  746        >>> g.addDecisionToZone(1, 'Z')
  747        >>> g.addDecisionToZone(2, 'Z')
  748        >>> g.addDecisionToZone(3, 'Z2')
  749        >>> g.addZoneToZone('Z', 'Zup')
  750        >>> g.addZoneToZone('Z2', 'Zup')
  751        >>> g.resolveDecision(1)
  752        1
  753        >>> g.resolveDecision('A')
  754        Traceback (most recent call last):
  755        ...
  756        exploration.core.AmbiguousDecisionSpecifierError...
  757        >>> g.resolveDecision('B')
  758        Traceback (most recent call last):
  759        ...
  760        exploration.core.AmbiguousDecisionSpecifierError...
  761        >>> g.resolveDecision('C')
  762        2
  763        >>> g.resolveDecision('A', 'Z')
  764        0
  765        >>> g.resolveDecision('A', zoneHint='Z2')
  766        3
  767        >>> g.resolveDecision('B', domainHint='main')
  768        1
  769        >>> g.resolveDecision('B', None, 'menu')
  770        4
  771        >>> g.resolveDecision('B', zoneHint='Z2')
  772        Traceback (most recent call last):
  773        ...
  774        exploration.core.MissingDecisionError...
  775        >>> g.resolveDecision('A', domainHint='menu')
  776        Traceback (most recent call last):
  777        ...
  778        exploration.core.MissingDecisionError...
  779        >>> g.resolveDecision('A', domainHint='madeup')
  780        Traceback (most recent call last):
  781        ...
  782        exploration.core.MissingDecisionError...
  783        >>> g.resolveDecision('A', zoneHint='madeup')
  784        Traceback (most recent call last):
  785        ...
  786        exploration.core.MissingDecisionError...
  787        """
  788        # Parse it to either an ID or specifier if it's a string:
  789        if isinstance(spec, str):
  790            try:
  791                spec = int(spec)
  792            except ValueError:
  793                pass
  794
  795        # If it's an ID, check for existence:
  796        if isinstance(spec, base.DecisionID):
  797            if spec in self:
  798                return spec
  799            else:
  800                raise MissingDecisionError(
  801                    f"There is no decision with ID {spec!r}."
  802                )
  803        else:
  804            if isinstance(spec, base.DecisionName):
  805                spec = base.DecisionSpecifier(
  806                    domain=None,
  807                    zone=None,
  808                    name=spec
  809                )
  810            elif not isinstance(spec, base.DecisionSpecifier):
  811                raise TypeError(
  812                    f"Specification is not provided as a"
  813                    f" DecisionSpecifier or other valid type. (got type"
  814                    f" {type(spec)})."
  815                )
  816
  817            # Merge domain hints from spec/args
  818            if (
  819                spec.domain is not None
  820            and domainHint is not None
  821            and spec.domain != domainHint
  822            ):
  823                raise ValueError(
  824                    f"Specifier {repr(spec)} includes domain hint"
  825                    f" {repr(spec.domain)} which is incompatible with"
  826                    f" explicit domain hint {repr(domainHint)}."
  827                )
  828            else:
  829                domainHint = spec.domain or domainHint
  830
  831            # Merge zone hints from spec/args
  832            if (
  833                spec.zone is not None
  834            and zoneHint is not None
  835            and spec.zone != zoneHint
  836            ):
  837                raise ValueError(
  838                    f"Specifier {repr(spec)} includes zone hint"
  839                    f" {repr(spec.zone)} which is incompatible with"
  840                    f" explicit zone hint {repr(zoneHint)}."
  841                )
  842            else:
  843                zoneHint = spec.zone or zoneHint
  844
  845            if spec.name not in self.nameLookup:
  846                raise MissingDecisionError(
  847                    f"No decision named {repr(spec.name)}."
  848                )
  849            else:
  850                options = self.nameLookup[spec.name]
  851                if len(options) == 0:
  852                    raise MissingDecisionError(
  853                        f"No decision named {repr(spec.name)}."
  854                    )
  855                filtered = [
  856                    opt
  857                    for opt in options
  858                    if (
  859                        domainHint is None
  860                     or self.domainFor(opt) == domainHint
  861                    ) and (
  862                        zoneHint is None
  863                     or zoneHint in self.zoneAncestors(opt)
  864                    )
  865                ]
  866                if len(filtered) == 1:
  867                    return filtered[0]
  868                else:
  869                    filterDesc = ""
  870                    if domainHint is not None:
  871                        filterDesc += f" in domain {repr(domainHint)}"
  872                    if zoneHint is not None:
  873                        filterDesc += f" in zone {repr(zoneHint)}"
  874                    if len(filtered) == 0:
  875                        raise MissingDecisionError(
  876                            f"No decisions named"
  877                            f" {repr(spec.name)}{filterDesc}."
  878                        )
  879                    else:
  880                        raise AmbiguousDecisionSpecifierError(
  881                            f"There are {len(filtered)} decisions"
  882                            f" named {repr(spec.name)}{filterDesc}."
  883                        )
  884
  885    def getDecision(
  886        self,
  887        decision: base.AnyDecisionSpecifier,
  888        zoneHint: Optional[base.Zone] = None,
  889        domainHint: Optional[base.Domain] = None
  890    ) -> Optional[base.DecisionID]:
  891        """
  892        Works like `resolveDecision` but returns None instead of raising
  893        a `MissingDecisionError` if the specified decision isn't listed.
  894        May still raise an `AmbiguousDecisionSpecifierError`.
  895        """
  896        try:
  897            return self.resolveDecision(
  898                decision,
  899                zoneHint,
  900                domainHint
  901            )
  902        except MissingDecisionError:
  903            return None
  904
  905    def nameFor(
  906        self,
  907        decision: base.AnyDecisionSpecifier
  908    ) -> base.DecisionName:
  909        """
  910        Returns the name of the specified decision. Note that names are
  911        not necessarily unique.
  912
  913        Example:
  914
  915        >>> d = DecisionGraph()
  916        >>> d.addDecision('A')
  917        0
  918        >>> d.addDecision('B')
  919        1
  920        >>> d.addDecision('B')
  921        2
  922        >>> d.nameFor(0)
  923        'A'
  924        >>> d.nameFor(1)
  925        'B'
  926        >>> d.nameFor(2)
  927        'B'
  928        >>> d.nameFor(3)
  929        Traceback (most recent call last):
  930        ...
  931        exploration.core.MissingDecisionError...
  932        """
  933        dID = self.resolveDecision(decision)
  934        return self.nodes[dID]['name']
  935
  936    def shortIdentity(
  937        self,
  938        decision: Optional[base.AnyDecisionSpecifier],
  939        includeZones: bool = True,
  940        alwaysDomain: Optional[bool] = None
  941    ):
  942        """
  943        Returns a string containing the name for the given decision,
  944        prefixed by its level-0 zone(s) and domain. If the value provided
  945        is `None`, it returns the string "(nowhere)".
  946
  947        If `includeZones` is true (the default) then zone information
  948        is included before the decision name.
  949
  950        If `alwaysDomain` is true or false, then the domain information
  951        will always (or never) be included. If it's `None` (the default)
  952        then domain info will only be included for decisions which are
  953        not in the default domain.
  954        """
  955        if decision is None:
  956            return "(nowhere)"
  957        else:
  958            dID = self.resolveDecision(decision)
  959            thisDomain = self.domainFor(dID)
  960            dSpec = ''
  961            zSpec = ''
  962            if (
  963                alwaysDomain is True
  964             or (
  965                    alwaysDomain is None
  966                and thisDomain != base.DEFAULT_DOMAIN
  967                )
  968            ):
  969                dSpec = thisDomain + '//'  # TODO: Don't hardcode this?
  970            if includeZones:
  971                zones = [
  972                    z
  973                    for z in self.zoneParents(dID)
  974                    if self.zones[z].level == 0
  975                ]
  976                if len(zones) == 1:
  977                    zSpec = zones[0] + '::'  # TODO: Don't hardcode this?
  978                elif len(zones) > 1:
  979                    zSpec = '[' + ', '.join(sorted(zones)) + ']::'
  980                # else leave zSpec empty
  981
  982            return f"{dSpec}{zSpec}{self.nameFor(dID)}"
  983
  984    def identityOf(
  985        self,
  986        decision: Optional[base.AnyDecisionSpecifier],
  987        includeZones: bool = True,
  988        alwaysDomain: Optional[bool] = None
  989    ) -> str:
  990        """
  991        Returns the given node's ID, plus its `shortIdentity` in
  992        parentheses. Arguments are passed through to `shortIdentity`.
  993        """
  994        if decision is None:
  995            return "(nowhere)"
  996        else:
  997            dID = self.resolveDecision(decision)
  998            short = self.shortIdentity(decision, includeZones, alwaysDomain)
  999            return f"{dID} ({short})"
 1000
 1001    def namesListing(
 1002        self,
 1003        decisions: Collection[base.DecisionID],
 1004        includeZones: bool = True,
 1005        indent: int = 2
 1006    ) -> str:
 1007        """
 1008        Returns a multi-line string containing an indented listing of
 1009        the provided decision IDs with their names in parentheses after
 1010        each. Useful for debugging & error messages.
 1011
 1012        Includes level-0 zones where applicable, with a zone separator
 1013        before the decision, unless `includeZones` is set to False. Where
 1014        there are multiple level-0 zones, they're listed together in
 1015        brackets.
 1016
 1017        Uses the string '(none)' when there are no decisions are in the
 1018        list.
 1019
 1020        Set `indent` to something other than 2 to control how much
 1021        indentation is added.
 1022
 1023        For example:
 1024
 1025        >>> g = DecisionGraph()
 1026        >>> g.addDecision('A')
 1027        0
 1028        >>> g.addDecision('B')
 1029        1
 1030        >>> g.addDecision('C')
 1031        2
 1032        >>> g.namesListing(['A', 'C', 'B'])
 1033        '  0 (A)\\n  2 (C)\\n  1 (B)\\n'
 1034        >>> g.namesListing([])
 1035        '  (none)\\n'
 1036        >>> g.createZone('zone', 0)
 1037        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 1038 annotations=[])
 1039        >>> g.createZone('zone2', 0)
 1040        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 1041 annotations=[])
 1042        >>> g.createZone('zoneUp', 1)
 1043        ZoneInfo(level=1, parents=set(), contents=set(), tags={},\
 1044 annotations=[])
 1045        >>> g.addDecisionToZone(0, 'zone')
 1046        >>> g.addDecisionToZone(1, 'zone')
 1047        >>> g.addDecisionToZone(1, 'zone2')
 1048        >>> g.addDecisionToZone(2, 'zoneUp')  # won't be listed: it's level-1
 1049        >>> g.namesListing(['A', 'C', 'B'])
 1050        '  0 (zone::A)\\n  2 (C)\\n  1 ([zone, zone2]::B)\\n'
 1051        """
 1052        ind = ' ' * indent
 1053        if len(decisions) == 0:
 1054            return ind + '(none)\n'
 1055        else:
 1056            result = ''
 1057            for dID in decisions:
 1058                result += ind + self.identityOf(dID, includeZones) + '\n'
 1059            return result
 1060
 1061    def destinationsListing(
 1062        self,
 1063        destinations: Dict[base.Transition, base.DecisionID],
 1064        includeZones: bool = True,
 1065        indent: int = 2
 1066    ) -> str:
 1067        """
 1068        Returns a multi-line string containing an indented listing of
 1069        the provided transitions along with their destinations and the
 1070        names of those destinations in parentheses. Useful for debugging
 1071        & error messages. (Use e.g., `destinationsFrom` to get a
 1072        transitions -> destinations dictionary in the required format.)
 1073
 1074        Uses the string '(no transitions)' when there are no transitions
 1075        in the dictionary.
 1076
 1077        Set `indent` to something other than 2 to control how much
 1078        indentation is added.
 1079
 1080        For example:
 1081
 1082        >>> g = DecisionGraph()
 1083        >>> g.addDecision('A')
 1084        0
 1085        >>> g.addDecision('B')
 1086        1
 1087        >>> g.addDecision('C')
 1088        2
 1089        >>> g.addTransition('A', 'north', 'B', 'south')
 1090        >>> g.addTransition('B', 'east', 'C', 'west')
 1091        >>> g.addTransition('C', 'southwest', 'A', 'northeast')
 1092        >>> g.destinationsListing(g.destinationsFrom('A'))
 1093        '  north to 1 (B)\\n  northeast to 2 (C)\\n'
 1094        >>> g.destinationsListing(g.destinationsFrom('B'))
 1095        '  south to 0 (A)\\n  east to 2 (C)\\n'
 1096        >>> g.destinationsListing({})
 1097        '  (none)\\n'
 1098        >>> g.createZone('zone', 0)
 1099        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 1100 annotations=[])
 1101        >>> g.addDecisionToZone(0, 'zone')
 1102        >>> g.destinationsListing(g.destinationsFrom('B'))
 1103        '  south to 0 (zone::A)\\n  east to 2 (C)\\n'
 1104        """
 1105        ind = ' ' * indent
 1106        if len(destinations) == 0:
 1107            return ind + '(none)\n'
 1108        else:
 1109            result = ''
 1110            for transition, dID in destinations.items():
 1111                line = f"{transition} to {self.identityOf(dID, includeZones)}"
 1112                result += ind + line + '\n'
 1113            return result
 1114
 1115    def domainFor(self, decision: base.AnyDecisionSpecifier) -> base.Domain:
 1116        """
 1117        Returns the domain that a decision belongs to.
 1118        """
 1119        dID = self.resolveDecision(decision)
 1120        return self.nodes[dID]['domain']
 1121
 1122    def allDecisionsInDomain(
 1123        self,
 1124        domain: base.Domain
 1125    ) -> Set[base.DecisionID]:
 1126        """
 1127        Returns the set of all `DecisionID`s for decisions in the
 1128        specified domain.
 1129        """
 1130        return set(dID for dID in self if self.nodes[dID]['domain'] == domain)
 1131
 1132    def destination(
 1133        self,
 1134        decision: base.AnyDecisionSpecifier,
 1135        transition: base.Transition
 1136    ) -> base.DecisionID:
 1137        """
 1138        Overrides base `UniqueExitsGraph.destination` to raise
 1139        `MissingDecisionError` or `MissingTransitionError` as
 1140        appropriate, and to work with an `AnyDecisionSpecifier`.
 1141        """
 1142        dID = self.resolveDecision(decision)
 1143        try:
 1144            return super().destination(dID, transition)
 1145        except KeyError:
 1146            raise MissingTransitionError(
 1147                f"Transition {transition!r} does not exist at decision"
 1148                f" {self.identityOf(dID)}."
 1149            )
 1150
 1151    def getDestination(
 1152        self,
 1153        decision: base.AnyDecisionSpecifier,
 1154        transition: base.Transition,
 1155        default: Any = None
 1156    ) -> Optional[base.DecisionID]:
 1157        """
 1158        Overrides base `UniqueExitsGraph.getDestination` with different
 1159        argument names, since those matter for the edit DSL.
 1160        """
 1161        dID = self.resolveDecision(decision)
 1162        return super().getDestination(dID, transition)
 1163
 1164    def destinationsFrom(
 1165        self,
 1166        decision: base.AnyDecisionSpecifier
 1167    ) -> Dict[base.Transition, base.DecisionID]:
 1168        """
 1169        Override that just changes the type of the exception from a
 1170        `KeyError` to a `MissingDecisionError` when the source does not
 1171        exist.
 1172        """
 1173        dID = self.resolveDecision(decision)
 1174        return super().destinationsFrom(dID)
 1175
 1176    def bothEnds(
 1177        self,
 1178        decision: base.AnyDecisionSpecifier,
 1179        transition: base.Transition
 1180    ) -> Set[base.DecisionID]:
 1181        """
 1182        Returns a set containing the `DecisionID`(s) for both the start
 1183        and end of the specified transition. Raises a
 1184        `MissingDecisionError` or `MissingTransitionError`if the
 1185        specified decision and/or transition do not exist.
 1186
 1187        Note that for actions since the source and destination are the
 1188        same, the set will have only one element.
 1189        """
 1190        dID = self.resolveDecision(decision)
 1191        result = {dID}
 1192        dest = self.destination(dID, transition)
 1193        if dest is not None:
 1194            result.add(dest)
 1195        return result
 1196
 1197    def decisionActions(
 1198        self,
 1199        decision: base.AnyDecisionSpecifier
 1200    ) -> Set[base.Transition]:
 1201        """
 1202        Retrieves the set of self-edges at a decision. Editing the set
 1203        will not affect the graph.
 1204
 1205        Example:
 1206
 1207        >>> g = DecisionGraph()
 1208        >>> g.addDecision('A')
 1209        0
 1210        >>> g.addDecision('B')
 1211        1
 1212        >>> g.addDecision('C')
 1213        2
 1214        >>> g.addAction('A', 'action1')
 1215        >>> g.addAction('A', 'action2')
 1216        >>> g.addAction('B', 'action3')
 1217        >>> sorted(g.decisionActions('A'))
 1218        ['action1', 'action2']
 1219        >>> g.decisionActions('B')
 1220        {'action3'}
 1221        >>> g.decisionActions('C')
 1222        set()
 1223        """
 1224        result = set()
 1225        dID = self.resolveDecision(decision)
 1226        for transition, dest in self.destinationsFrom(dID).items():
 1227            if dest == dID:
 1228                result.add(transition)
 1229        return result
 1230
 1231    def getTransitionProperties(
 1232        self,
 1233        decision: base.AnyDecisionSpecifier,
 1234        transition: base.Transition
 1235    ) -> TransitionProperties:
 1236        """
 1237        Returns a dictionary containing transition properties for the
 1238        specified transition from the specified decision. The properties
 1239        included are:
 1240
 1241        - 'requirement': The requirement for the transition.
 1242        - 'consequence': Any consequence of the transition.
 1243        - 'tags': Any tags applied to the transition.
 1244        - 'annotations': Any annotations on the transition.
 1245
 1246        The reciprocal of the transition is not included.
 1247
 1248        The result is a clone of the stored properties; edits to the
 1249        dictionary will NOT modify the graph.
 1250        """
 1251        dID = self.resolveDecision(decision)
 1252        dest = self.destination(dID, transition)
 1253
 1254        info: TransitionProperties = copy.deepcopy(
 1255            self.edges[dID, dest, transition]  # type:ignore
 1256        )
 1257        return {
 1258            'requirement': info.get('requirement', base.ReqNothing()),
 1259            'consequence': info.get('consequence', []),
 1260            'tags': info.get('tags', {}),
 1261            'annotations': info.get('annotations', [])
 1262        }
 1263
 1264    def setTransitionProperties(
 1265        self,
 1266        decision: base.AnyDecisionSpecifier,
 1267        transition: base.Transition,
 1268        requirement: Optional[base.Requirement] = None,
 1269        consequence: Optional[base.Consequence] = None,
 1270        tags: Optional[Dict[base.Tag, base.TagValue]] = None,
 1271        annotations: Optional[List[base.Annotation]] = None
 1272    ) -> None:
 1273        """
 1274        Sets one or more transition properties all at once. Can be used
 1275        to set the requirement, consequence, tags, and/or annotations.
 1276        Old values are overwritten, although if `None`s are provided (or
 1277        arguments are omitted), corresponding properties are not
 1278        updated.
 1279
 1280        To add tags or annotations to existing tags/annotations instead
 1281        of replacing them, use `tagTransition` or `annotateTransition`
 1282        instead.
 1283        """
 1284        dID = self.resolveDecision(decision)
 1285        if requirement is not None:
 1286            self.setTransitionRequirement(dID, transition, requirement)
 1287        if consequence is not None:
 1288            self.setConsequence(dID, transition, consequence)
 1289        if tags is not None:
 1290            dest = self.destination(dID, transition)
 1291            # TODO: Submit pull request to update MultiDiGraph stubs in
 1292            # types-networkx to include OutMultiEdgeView that accepts
 1293            # from/to/key tuples as indices.
 1294            info = cast(
 1295                TransitionProperties,
 1296                self.edges[dID, dest, transition]  # type:ignore
 1297            )
 1298            info['tags'] = tags
 1299        if annotations is not None:
 1300            dest = self.destination(dID, transition)
 1301            info = cast(
 1302                TransitionProperties,
 1303                self.edges[dID, dest, transition]  # type:ignore
 1304            )
 1305            info['annotations'] = annotations
 1306
 1307    def getTransitionRequirement(
 1308        self,
 1309        decision: base.AnyDecisionSpecifier,
 1310        transition: base.Transition
 1311    ) -> base.Requirement:
 1312        """
 1313        Returns the `Requirement` for accessing a specific transition at
 1314        a specific decision. For transitions which don't have
 1315        requirements, returns a `ReqNothing` instance.
 1316        """
 1317        dID = self.resolveDecision(decision)
 1318        dest = self.destination(dID, transition)
 1319
 1320        info = cast(
 1321            TransitionProperties,
 1322            self.edges[dID, dest, transition]  # type:ignore
 1323        )
 1324
 1325        return info.get('requirement', base.ReqNothing())
 1326
 1327    def setTransitionRequirement(
 1328        self,
 1329        decision: base.AnyDecisionSpecifier,
 1330        transition: base.Transition,
 1331        requirement: Optional[base.Requirement]
 1332    ) -> None:
 1333        """
 1334        Sets the `Requirement` for accessing a specific transition at
 1335        a specific decision. Raises a `KeyError` if the decision or
 1336        transition does not exist.
 1337
 1338        Deletes the requirement if `None` is given as the requirement.
 1339
 1340        Use `parsing.ParseFormat.parseRequirement` first if you have a
 1341        requirement in string format.
 1342
 1343        Does not raise an error if deletion is requested for a
 1344        non-existent requirement, and silently overwrites any previous
 1345        requirement.
 1346        """
 1347        dID = self.resolveDecision(decision)
 1348
 1349        dest = self.destination(dID, transition)
 1350
 1351        info = cast(
 1352            TransitionProperties,
 1353            self.edges[dID, dest, transition]  # type:ignore
 1354        )
 1355
 1356        if requirement is None:
 1357            try:
 1358                del info['requirement']
 1359            except KeyError:
 1360                pass
 1361        else:
 1362            if not isinstance(requirement, base.Requirement):
 1363                raise TypeError(
 1364                    f"Invalid requirement type: {type(requirement)}"
 1365                )
 1366
 1367            info['requirement'] = requirement
 1368
 1369    def getConsequence(
 1370        self,
 1371        decision: base.AnyDecisionSpecifier,
 1372        transition: base.Transition
 1373    ) -> base.Consequence:
 1374        """
 1375        Retrieves the consequence of a transition.
 1376
 1377        A `KeyError` is raised if the specified decision/transition
 1378        combination doesn't exist.
 1379        """
 1380        dID = self.resolveDecision(decision)
 1381
 1382        dest = self.destination(dID, transition)
 1383
 1384        info = cast(
 1385            TransitionProperties,
 1386            self.edges[dID, dest, transition]  # type:ignore
 1387        )
 1388
 1389        return info.get('consequence', [])
 1390
 1391    def addConsequence(
 1392        self,
 1393        decision: base.AnyDecisionSpecifier,
 1394        transition: base.Transition,
 1395        consequence: base.Consequence
 1396    ) -> Tuple[int, int]:
 1397        """
 1398        Adds the given `Consequence` to the consequence list for the
 1399        specified transition, extending that list at the end. Note that
 1400        this does NOT make a copy of the consequence, so it should not
 1401        be used to copy consequences from one transition to another
 1402        without making a deep copy first.
 1403
 1404        A `MissingDecisionError` or a `MissingTransitionError` is raised
 1405        if the specified decision/transition combination doesn't exist.
 1406
 1407        Returns a pair of integers indicating the minimum and maximum
 1408        depth-first-traversal-indices of the added consequence part(s).
 1409        The outer consequence list itself (index 0) is not counted.
 1410
 1411        >>> d = DecisionGraph()
 1412        >>> d.addDecision('A')
 1413        0
 1414        >>> d.addDecision('B')
 1415        1
 1416        >>> d.addTransition('A', 'fwd', 'B', 'rev')
 1417        >>> d.addConsequence('A', 'fwd', [base.effect(gain='sword')])
 1418        (1, 1)
 1419        >>> d.addConsequence('B', 'rev', [base.effect(lose='sword')])
 1420        (1, 1)
 1421        >>> ef = d.getConsequence('A', 'fwd')
 1422        >>> er = d.getConsequence('B', 'rev')
 1423        >>> ef == [base.effect(gain='sword')]
 1424        True
 1425        >>> er == [base.effect(lose='sword')]
 1426        True
 1427        >>> d.addConsequence('A', 'fwd', [base.effect(deactivate=True)])
 1428        (2, 2)
 1429        >>> ef = d.getConsequence('A', 'fwd')
 1430        >>> ef == [base.effect(gain='sword'), base.effect(deactivate=True)]
 1431        True
 1432        >>> d.addConsequence(
 1433        ...     'A',
 1434        ...     'fwd',  # adding to consequence with 3 parts already
 1435        ...     [  # outer list not counted because it merges
 1436        ...         base.challenge(  # 1 part
 1437        ...             None,
 1438        ...             0,
 1439        ...             [base.effect(gain=('flowers', 3))],  # 2 parts
 1440        ...             [base.effect(gain=('flowers', 1))]  # 2 parts
 1441        ...         )
 1442        ...     ]
 1443        ... )  # note indices below are inclusive; indices are 3, 4, 5, 6, 7
 1444        (3, 7)
 1445        """
 1446        dID = self.resolveDecision(decision)
 1447
 1448        dest = self.destination(dID, transition)
 1449
 1450        info = cast(
 1451            TransitionProperties,
 1452            self.edges[dID, dest, transition]  # type:ignore
 1453        )
 1454
 1455        existing = info.setdefault('consequence', [])
 1456        startIndex = base.countParts(existing)
 1457        existing.extend(consequence)
 1458        endIndex = base.countParts(existing) - 1
 1459        return (startIndex, endIndex)
 1460
 1461    def setConsequence(
 1462        self,
 1463        decision: base.AnyDecisionSpecifier,
 1464        transition: base.Transition,
 1465        consequence: base.Consequence
 1466    ) -> None:
 1467        """
 1468        Replaces the transition consequence for the given transition at
 1469        the given decision. Any previous consequence is discarded. See
 1470        `Consequence` for the structure of these. Note that this does
 1471        NOT make a copy of the consequence, do that first to avoid
 1472        effect-entanglement if you're copying a consequence.
 1473
 1474        A `MissingDecisionError` or a `MissingTransitionError` is raised
 1475        if the specified decision/transition combination doesn't exist.
 1476        """
 1477        dID = self.resolveDecision(decision)
 1478
 1479        dest = self.destination(dID, transition)
 1480
 1481        info = cast(
 1482            TransitionProperties,
 1483            self.edges[dID, dest, transition]  # type:ignore
 1484        )
 1485
 1486        info['consequence'] = consequence
 1487
 1488    def addEquivalence(
 1489        self,
 1490        requirement: base.Requirement,
 1491        capabilityOrMechanismState: Union[
 1492            base.Capability,
 1493            Tuple[base.MechanismID, base.MechanismState]
 1494        ]
 1495    ) -> None:
 1496        """
 1497        Adds the given requirement as an equivalence for the given
 1498        capability or the given mechanism state. Note that having a
 1499        capability via an equivalence does not count as actually having
 1500        that capability; it only counts for the purpose of satisfying
 1501        `Requirement`s.
 1502
 1503        Note also that because a mechanism-based requirement looks up
 1504        the specific mechanism locally based on a name, an equivalence
 1505        defined in one location may affect mechanism requirements in
 1506        other locations unless the mechanism name in the requirement is
 1507        zone-qualified to be specific. But in such situations the base
 1508        mechanism would have caused issues in any case.
 1509        """
 1510        self.equivalences.setdefault(
 1511            capabilityOrMechanismState,
 1512            set()
 1513        ).add(requirement)
 1514
 1515    def removeEquivalence(
 1516        self,
 1517        requirement: base.Requirement,
 1518        capabilityOrMechanismState: Union[
 1519            base.Capability,
 1520            Tuple[base.MechanismID, base.MechanismState]
 1521        ]
 1522    ) -> None:
 1523        """
 1524        Removes an equivalence. Raises a `KeyError` if no such
 1525        equivalence existed.
 1526        """
 1527        self.equivalences[capabilityOrMechanismState].remove(requirement)
 1528
 1529    def hasAnyEquivalents(
 1530        self,
 1531        capabilityOrMechanismState: Union[
 1532            base.Capability,
 1533            Tuple[base.MechanismID, base.MechanismState]
 1534        ]
 1535    ) -> bool:
 1536        """
 1537        Returns `True` if the given capability or mechanism state has at
 1538        least one equivalence.
 1539        """
 1540        return capabilityOrMechanismState in self.equivalences
 1541
 1542    def allEquivalents(
 1543        self,
 1544        capabilityOrMechanismState: Union[
 1545            base.Capability,
 1546            Tuple[base.MechanismID, base.MechanismState]
 1547        ]
 1548    ) -> Set[base.Requirement]:
 1549        """
 1550        Returns the set of equivalences for the given capability. This is
 1551        a live set which may be modified (it's probably better to use
 1552        `addEquivalence` and `removeEquivalence` instead...).
 1553        """
 1554        return self.equivalences.setdefault(
 1555            capabilityOrMechanismState,
 1556            set()
 1557        )
 1558
 1559    def reversionType(self, name: str, equivalentTo: Set[str]) -> None:
 1560        """
 1561        Specifies a new reversion type, so that when used in a reversion
 1562        aspects set with a colon before the name, all items in the
 1563        `equivalentTo` value will be added to that set. These may
 1564        include other custom reversion type names (with the colon) but
 1565        take care not to create an equivalence loop which would result
 1566        in a crash.
 1567
 1568        If you re-use the same name, it will override the old equivalence
 1569        for that name.
 1570        """
 1571        self.reversionTypes[name] = equivalentTo
 1572
 1573    def addAction(
 1574        self,
 1575        decision: base.AnyDecisionSpecifier,
 1576        action: base.Transition,
 1577        requires: Optional[base.Requirement] = None,
 1578        consequence: Optional[base.Consequence] = None,
 1579        tags: Optional[Dict[base.Tag, base.TagValue]] = None,
 1580        annotations: Optional[List[base.Annotation]] = None,
 1581    ) -> None:
 1582        """
 1583        Adds the given action as a possibility at the given decision. An
 1584        action is just a self-edge, which can have requirements like any
 1585        edge, and which can have consequences like any edge.
 1586        The optional arguments are given to `setTransitionRequirement`
 1587        and `setConsequence`; see those functions for descriptions
 1588        of what they mean.
 1589
 1590        Raises a `KeyError` if a transition with the given name already
 1591        exists at the given decision.
 1592        """
 1593        if tags is None:
 1594            tags = {}
 1595        if annotations is None:
 1596            annotations = []
 1597
 1598        dID = self.resolveDecision(decision)
 1599
 1600        self.add_edge(
 1601            dID,
 1602            dID,
 1603            key=action,
 1604            tags=tags,
 1605            annotations=annotations
 1606        )
 1607        self.setTransitionRequirement(dID, action, requires)
 1608        if consequence is not None:
 1609            self.setConsequence(dID, action, consequence)
 1610
 1611    def tagDecision(
 1612        self,
 1613        decision: base.AnyDecisionSpecifier,
 1614        tagOrTags: Union[base.Tag, Dict[base.Tag, base.TagValue]],
 1615        tagValue: Union[
 1616            base.TagValue,
 1617            type[base.NoTagValue]
 1618        ] = base.NoTagValue
 1619    ) -> None:
 1620        """
 1621        Adds a tag (or many tags from a dictionary of tags) to a
 1622        decision, using `1` as the value if no value is provided. It's
 1623        a `ValueError` to provide a value when a dictionary of tags is
 1624        provided to set multiple tags at once.
 1625
 1626        Note that certain tags have special meanings:
 1627
 1628        - 'unconfirmed' is used for decisions that represent unconfirmed
 1629            parts of the graph (this is separate from the 'unknown'
 1630            and/or 'hypothesized' exploration statuses, which are only
 1631            tracked in a `DiscreteExploration`, not in a `DecisionGraph`).
 1632            Various methods require this tag and many also add or remove
 1633            it.
 1634        """
 1635        if isinstance(tagOrTags, base.Tag):
 1636            if tagValue is base.NoTagValue:
 1637                tagValue = 1
 1638
 1639            # Not sure why this cast is necessary given the `if` above...
 1640            tagValue = cast(base.TagValue, tagValue)
 1641
 1642            tagOrTags = {tagOrTags: tagValue}
 1643
 1644        elif tagValue is not base.NoTagValue:
 1645            raise ValueError(
 1646                "Provided a dictionary to update multiple tags, but"
 1647                " also a tag value."
 1648            )
 1649
 1650        dID = self.resolveDecision(decision)
 1651
 1652        tagsAlready = self.nodes[dID].setdefault('tags', {})
 1653        tagsAlready.update(tagOrTags)
 1654
 1655    def untagDecision(
 1656        self,
 1657        decision: base.AnyDecisionSpecifier,
 1658        tag: base.Tag
 1659    ) -> Union[base.TagValue, type[base.NoTagValue]]:
 1660        """
 1661        Removes a tag from a decision. Returns the tag's old value if
 1662        the tag was present and got removed, or `NoTagValue` if the tag
 1663        wasn't present.
 1664        """
 1665        dID = self.resolveDecision(decision)
 1666
 1667        target = self.nodes[dID]['tags']
 1668        try:
 1669            return target.pop(tag)
 1670        except KeyError:
 1671            return base.NoTagValue
 1672
 1673    def decisionTags(
 1674        self,
 1675        decision: base.AnyDecisionSpecifier
 1676    ) -> Dict[base.Tag, base.TagValue]:
 1677        """
 1678        Returns the dictionary of tags for a decision. Edits to the
 1679        returned value will be applied to the graph.
 1680        """
 1681        dID = self.resolveDecision(decision)
 1682
 1683        return self.nodes[dID]['tags']
 1684
 1685    def annotateDecision(
 1686        self,
 1687        decision: base.AnyDecisionSpecifier,
 1688        annotationOrAnnotations: Union[
 1689            base.Annotation,
 1690            Sequence[base.Annotation]
 1691        ]
 1692    ) -> None:
 1693        """
 1694        Adds an annotation to a decision's annotations list.
 1695        """
 1696        dID = self.resolveDecision(decision)
 1697
 1698        if isinstance(annotationOrAnnotations, base.Annotation):
 1699            annotationOrAnnotations = [annotationOrAnnotations]
 1700        self.nodes[dID]['annotations'].extend(annotationOrAnnotations)
 1701
 1702    def decisionAnnotations(
 1703        self,
 1704        decision: base.AnyDecisionSpecifier
 1705    ) -> List[base.Annotation]:
 1706        """
 1707        Returns the list of annotations for the specified decision.
 1708        Modifying the list affects the graph.
 1709        """
 1710        dID = self.resolveDecision(decision)
 1711
 1712        return self.nodes[dID]['annotations']
 1713
 1714    def tagTransition(
 1715        self,
 1716        decision: base.AnyDecisionSpecifier,
 1717        transition: base.Transition,
 1718        tagOrTags: Union[base.Tag, Dict[base.Tag, base.TagValue]],
 1719        tagValue: Union[
 1720            base.TagValue,
 1721            type[base.NoTagValue]
 1722        ] = base.NoTagValue
 1723    ) -> None:
 1724        """
 1725        Adds a tag (or each tag from a dictionary) to a transition
 1726        coming out of a specific decision. `1` will be used as the
 1727        default value if a single tag is supplied; supplying a tag value
 1728        when providing a dictionary of multiple tags to update is a
 1729        `ValueError`.
 1730
 1731        Note that certain transition tags have special meanings:
 1732        - 'trigger' causes any actions (but not normal transitions) that
 1733            it applies to to be automatically triggered when
 1734            `advanceSituation` is called and the decision they're
 1735            attached to is active in the new situation (as long as the
 1736            action's requirements are met). This happens once per
 1737            situation; use 'wait' steps to re-apply triggers.
 1738        """
 1739        dID = self.resolveDecision(decision)
 1740
 1741        dest = self.destination(dID, transition)
 1742        if isinstance(tagOrTags, base.Tag):
 1743            if tagValue is base.NoTagValue:
 1744                tagValue = 1
 1745
 1746            # Not sure why this is necessary given the `if` above...
 1747            tagValue = cast(base.TagValue, tagValue)
 1748
 1749            tagOrTags = {tagOrTags: tagValue}
 1750        elif tagValue is not base.NoTagValue:
 1751            raise ValueError(
 1752                "Provided a dictionary to update multiple tags, but"
 1753                " also a tag value."
 1754            )
 1755
 1756        info = cast(
 1757            TransitionProperties,
 1758            self.edges[dID, dest, transition]  # type:ignore
 1759        )
 1760
 1761        info.setdefault('tags', {}).update(tagOrTags)
 1762
 1763    def untagTransition(
 1764        self,
 1765        decision: base.AnyDecisionSpecifier,
 1766        transition: base.Transition,
 1767        tagOrTags: Union[base.Tag, Set[base.Tag]]
 1768    ) -> None:
 1769        """
 1770        Removes a tag (or each tag in a set) from a transition coming out
 1771        of a specific decision. Raises a `KeyError` if (one of) the
 1772        specified tag(s) is not currently applied to the specified
 1773        transition.
 1774        """
 1775        dID = self.resolveDecision(decision)
 1776
 1777        dest = self.destination(dID, transition)
 1778        if isinstance(tagOrTags, base.Tag):
 1779            tagOrTags = {tagOrTags}
 1780
 1781        info = cast(
 1782            TransitionProperties,
 1783            self.edges[dID, dest, transition]  # type:ignore
 1784        )
 1785        tagsAlready = info.setdefault('tags', {})
 1786
 1787        for tag in tagOrTags:
 1788            tagsAlready.pop(tag)
 1789
 1790    def transitionTags(
 1791        self,
 1792        decision: base.AnyDecisionSpecifier,
 1793        transition: base.Transition
 1794    ) -> Dict[base.Tag, base.TagValue]:
 1795        """
 1796        Returns the dictionary of tags for a transition. Edits to the
 1797        returned dictionary will be applied to the graph.
 1798        """
 1799        dID = self.resolveDecision(decision)
 1800
 1801        dest = self.destination(dID, transition)
 1802        info = cast(
 1803            TransitionProperties,
 1804            self.edges[dID, dest, transition]  # type:ignore
 1805        )
 1806        return info.setdefault('tags', {})
 1807
 1808    def annotateTransition(
 1809        self,
 1810        decision: base.AnyDecisionSpecifier,
 1811        transition: base.Transition,
 1812        annotations: Union[base.Annotation, Sequence[base.Annotation]]
 1813    ) -> None:
 1814        """
 1815        Adds an annotation (or a sequence of annotations) to a
 1816        transition's annotations list.
 1817        """
 1818        dID = self.resolveDecision(decision)
 1819
 1820        dest = self.destination(dID, transition)
 1821        if isinstance(annotations, base.Annotation):
 1822            annotations = [annotations]
 1823        info = cast(
 1824            TransitionProperties,
 1825            self.edges[dID, dest, transition]  # type:ignore
 1826        )
 1827        info['annotations'].extend(annotations)
 1828
 1829    def transitionAnnotations(
 1830        self,
 1831        decision: base.AnyDecisionSpecifier,
 1832        transition: base.Transition
 1833    ) -> List[base.Annotation]:
 1834        """
 1835        Returns the annotation list for a specific transition at a
 1836        specific decision. Editing the list affects the graph.
 1837        """
 1838        dID = self.resolveDecision(decision)
 1839
 1840        dest = self.destination(dID, transition)
 1841        info = cast(
 1842            TransitionProperties,
 1843            self.edges[dID, dest, transition]  # type:ignore
 1844        )
 1845        return info['annotations']
 1846
 1847    def annotateZone(
 1848        self,
 1849        zone: base.Zone,
 1850        annotations: Union[base.Annotation, Sequence[base.Annotation]]
 1851    ) -> None:
 1852        """
 1853        Adds an annotation (or many annotations from a sequence) to a
 1854        zone.
 1855
 1856        Raises a `MissingZoneError` if the specified zone does not exist.
 1857        """
 1858        if zone not in self.zones:
 1859            raise MissingZoneError(
 1860                f"Can't add annotation(s) to zone {zone!r} because that"
 1861                f" zone doesn't exist yet."
 1862            )
 1863
 1864        if isinstance(annotations, base.Annotation):
 1865            annotations = [ annotations ]
 1866
 1867        self.zones[zone].annotations.extend(annotations)
 1868
 1869    def zoneAnnotations(self, zone: base.Zone) -> List[base.Annotation]:
 1870        """
 1871        Returns the list of annotations for the specified zone (empty if
 1872        none have been added yet).
 1873        """
 1874        return self.zones[zone].annotations
 1875
 1876    def tagZone(
 1877        self,
 1878        zone: base.Zone,
 1879        tagOrTags: Union[base.Tag, Dict[base.Tag, base.TagValue]],
 1880        tagValue: Union[
 1881            base.TagValue,
 1882            type[base.NoTagValue]
 1883        ] = base.NoTagValue
 1884    ) -> None:
 1885        """
 1886        Adds a tag (or many tags from a dictionary of tags) to a
 1887        zone, using `1` as the value if no value is provided. It's
 1888        a `ValueError` to provide a value when a dictionary of tags is
 1889        provided to set multiple tags at once.
 1890
 1891        Raises a `MissingZoneError` if the specified zone does not exist.
 1892        """
 1893        if zone not in self.zones:
 1894            raise MissingZoneError(
 1895                f"Can't add tag(s) to zone {zone!r} because that zone"
 1896                f" doesn't exist yet."
 1897            )
 1898
 1899        if isinstance(tagOrTags, base.Tag):
 1900            if tagValue is base.NoTagValue:
 1901                tagValue = 1
 1902
 1903            # Not sure why this cast is necessary given the `if` above...
 1904            tagValue = cast(base.TagValue, tagValue)
 1905
 1906            tagOrTags = {tagOrTags: tagValue}
 1907
 1908        elif tagValue is not base.NoTagValue:
 1909            raise ValueError(
 1910                "Provided a dictionary to update multiple tags, but"
 1911                " also a tag value."
 1912            )
 1913
 1914        tagsAlready = self.zones[zone].tags
 1915        tagsAlready.update(tagOrTags)
 1916
 1917    def untagZone(
 1918        self,
 1919        zone: base.Zone,
 1920        tag: base.Tag
 1921    ) -> Union[base.TagValue, type[base.NoTagValue]]:
 1922        """
 1923        Removes a tag from a zone. Returns the tag's old value if the
 1924        tag was present and got removed, or `NoTagValue` if the tag
 1925        wasn't present.
 1926
 1927        Raises a `MissingZoneError` if the specified zone does not exist.
 1928        """
 1929        if zone not in self.zones:
 1930            raise MissingZoneError(
 1931                f"Can't remove tag {tag!r} from zone {zone!r} because"
 1932                f" that zone doesn't exist yet."
 1933            )
 1934        target = self.zones[zone].tags
 1935        try:
 1936            return target.pop(tag)
 1937        except KeyError:
 1938            return base.NoTagValue
 1939
 1940    def zoneTags(
 1941        self,
 1942        zone: base.Zone
 1943    ) -> Dict[base.Tag, base.TagValue]:
 1944        """
 1945        Returns the dictionary of tags for a zone. Edits to the returned
 1946        value will be applied to the graph. Returns an empty tags
 1947        dictionary if called on a zone that didn't have any tags
 1948        previously, but raises a `MissingZoneError` if attempting to get
 1949        tags for a zone which does not exist.
 1950
 1951        For example:
 1952
 1953        >>> g = DecisionGraph()
 1954        >>> g.addDecision('A')
 1955        0
 1956        >>> g.addDecision('B')
 1957        1
 1958        >>> g.createZone('Zone')
 1959        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 1960 annotations=[])
 1961        >>> g.tagZone('Zone', 'color', 'blue')
 1962        >>> g.tagZone(
 1963        ...     'Zone',
 1964        ...     {'shape': 'square', 'color': 'red', 'sound': 'loud'}
 1965        ... )
 1966        >>> g.untagZone('Zone', 'sound')
 1967        'loud'
 1968        >>> g.zoneTags('Zone')
 1969        {'color': 'red', 'shape': 'square'}
 1970        """
 1971        if zone in self.zones:
 1972            return self.zones[zone].tags
 1973        else:
 1974            raise MissingZoneError(
 1975                f"Tags for zone {zone!r} don't exist because that"
 1976                f" zone has not been created yet."
 1977            )
 1978
 1979    def createZone(self, zone: base.Zone, level: int = 0) -> base.ZoneInfo:
 1980        """
 1981        Creates an empty zone with the given name at the given level
 1982        (default 0). Raises a `ZoneCollisionError` if that zone name is
 1983        already in use (at any level), including if it's in use by a
 1984        decision.
 1985
 1986        Raises an `InvalidLevelError` if the level value is less than 0.
 1987
 1988        Returns the `ZoneInfo` for the new blank zone.
 1989
 1990        For example:
 1991
 1992        >>> d = DecisionGraph()
 1993        >>> d.createZone('Z', 0)
 1994        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 1995 annotations=[])
 1996        >>> d.getZoneInfo('Z')
 1997        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 1998 annotations=[])
 1999        >>> d.createZone('Z2', 0)
 2000        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2001 annotations=[])
 2002        >>> d.createZone('Z3', -1)  # level -1 is not valid (must be >= 0)
 2003        Traceback (most recent call last):
 2004        ...
 2005        exploration.core.InvalidLevelError...
 2006        >>> d.createZone('Z2')  # Name Z2 is already in use
 2007        Traceback (most recent call last):
 2008        ...
 2009        exploration.core.ZoneCollisionError...
 2010        """
 2011        if level < 0:
 2012            raise InvalidLevelError(
 2013                "Cannot create a zone with a negative level."
 2014            )
 2015        if zone in self.zones:
 2016            raise ZoneCollisionError(f"Zone {zone!r} already exists.")
 2017        if zone in self:
 2018            raise ZoneCollisionError(
 2019                f"A decision named {zone!r} already exists, so a zone"
 2020                f" with that name cannot be created."
 2021            )
 2022        info: base.ZoneInfo = base.ZoneInfo(
 2023            level=level,
 2024            parents=set(),
 2025            contents=set(),
 2026            tags={},
 2027            annotations=[]
 2028        )
 2029        self.zones[zone] = info
 2030        return info
 2031
 2032    def getZoneInfo(self, zone: base.Zone) -> Optional[base.ZoneInfo]:
 2033        """
 2034        Returns the `ZoneInfo` (level, parents, and contents) for the
 2035        specified zone, or `None` if that zone does not exist.
 2036
 2037        For example:
 2038
 2039        >>> d = DecisionGraph()
 2040        >>> d.createZone('Z', 0)
 2041        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2042 annotations=[])
 2043        >>> d.getZoneInfo('Z')
 2044        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2045 annotations=[])
 2046        >>> d.createZone('Z2', 0)
 2047        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2048 annotations=[])
 2049        >>> d.getZoneInfo('Z2')
 2050        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2051 annotations=[])
 2052        """
 2053        return self.zones.get(zone)
 2054
 2055    def deleteZone(self, zone: base.Zone) -> base.ZoneInfo:
 2056        """
 2057        Deletes the specified zone, returning a `ZoneInfo` object with
 2058        the information on the level, parents, and contents of that zone.
 2059
 2060        Raises a `MissingZoneError` if the zone in question does not
 2061        exist.
 2062
 2063        For example:
 2064
 2065        >>> d = DecisionGraph()
 2066        >>> d.createZone('Z', 0)
 2067        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2068 annotations=[])
 2069        >>> d.getZoneInfo('Z')
 2070        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2071 annotations=[])
 2072        >>> d.deleteZone('Z')
 2073        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2074 annotations=[])
 2075        >>> d.getZoneInfo('Z') is None  # no info any more
 2076        True
 2077        >>> d.deleteZone('Z')  # can't re-delete
 2078        Traceback (most recent call last):
 2079        ...
 2080        exploration.core.MissingZoneError...
 2081        """
 2082        info = self.getZoneInfo(zone)
 2083        if info is None:
 2084            raise MissingZoneError(
 2085                f"Cannot delete zone {zone!r}: it does not exist."
 2086            )
 2087        for sub in info.contents:
 2088            if 'zones' in self.nodes[sub]:
 2089                try:
 2090                    self.nodes[sub]['zones'].remove(zone)
 2091                except KeyError:
 2092                    pass
 2093        del self.zones[zone]
 2094        return info
 2095
 2096    def addDecisionToZone(
 2097        self,
 2098        decision: base.AnyDecisionSpecifier,
 2099        zone: base.Zone
 2100    ) -> None:
 2101        """
 2102        Adds a decision directly to a zone. Should normally only be used
 2103        with level-0 zones. Raises a `MissingZoneError` if the specified
 2104        zone did not already exist.
 2105
 2106        For example:
 2107
 2108        >>> d = DecisionGraph()
 2109        >>> d.addDecision('A')
 2110        0
 2111        >>> d.addDecision('B')
 2112        1
 2113        >>> d.addDecision('C')
 2114        2
 2115        >>> d.createZone('Z', 0)
 2116        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2117 annotations=[])
 2118        >>> d.addDecisionToZone('A', 'Z')
 2119        >>> d.getZoneInfo('Z')
 2120        ZoneInfo(level=0, parents=set(), contents={0}, tags={},\
 2121 annotations=[])
 2122        >>> d.addDecisionToZone('B', 'Z')
 2123        >>> d.getZoneInfo('Z')
 2124        ZoneInfo(level=0, parents=set(), contents={0, 1}, tags={},\
 2125 annotations=[])
 2126        """
 2127        dID = self.resolveDecision(decision)
 2128
 2129        if zone not in self.zones:
 2130            raise MissingZoneError(f"Zone {zone!r} does not exist.")
 2131
 2132        self.zones[zone].contents.add(dID)
 2133        self.nodes[dID].setdefault('zones', set()).add(zone)
 2134
 2135    def removeDecisionFromZone(
 2136        self,
 2137        decision: base.AnyDecisionSpecifier,
 2138        zone: base.Zone
 2139    ) -> bool:
 2140        """
 2141        Removes a decision from a zone if it had been in it, returning
 2142        True if that decision had been in that zone, and False if it was
 2143        not in that zone, including if that zone didn't exist.
 2144
 2145        Note that this only removes a decision from direct zone
 2146        membership. If the decision is a member of one or more zones
 2147        which are (directly or indirectly) sub-zones of the target zone,
 2148        the decision will remain in those zones, and will still be
 2149        indirectly part of the target zone afterwards.
 2150
 2151        Examples:
 2152
 2153        >>> g = DecisionGraph()
 2154        >>> g.addDecision('A')
 2155        0
 2156        >>> g.addDecision('B')
 2157        1
 2158        >>> g.createZone('level0', 0)
 2159        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2160 annotations=[])
 2161        >>> g.createZone('level1', 1)
 2162        ZoneInfo(level=1, parents=set(), contents=set(), tags={},\
 2163 annotations=[])
 2164        >>> g.createZone('level2', 2)
 2165        ZoneInfo(level=2, parents=set(), contents=set(), tags={},\
 2166 annotations=[])
 2167        >>> g.createZone('level3', 3)
 2168        ZoneInfo(level=3, parents=set(), contents=set(), tags={},\
 2169 annotations=[])
 2170        >>> g.addDecisionToZone('A', 'level0')
 2171        >>> g.addDecisionToZone('B', 'level0')
 2172        >>> g.addZoneToZone('level0', 'level1')
 2173        >>> g.addZoneToZone('level1', 'level2')
 2174        >>> g.addZoneToZone('level2', 'level3')
 2175        >>> g.addDecisionToZone('B', 'level2')  # Direct w/ skips
 2176        >>> g.removeDecisionFromZone('A', 'level1')
 2177        False
 2178        >>> g.zoneParents(0)
 2179        {'level0'}
 2180        >>> g.removeDecisionFromZone('A', 'level0')
 2181        True
 2182        >>> g.zoneParents(0)
 2183        set()
 2184        >>> g.removeDecisionFromZone('A', 'level0')
 2185        False
 2186        >>> g.removeDecisionFromZone('B', 'level0')
 2187        True
 2188        >>> g.zoneParents(1)
 2189        {'level2'}
 2190        >>> g.removeDecisionFromZone('B', 'level0')
 2191        False
 2192        >>> g.removeDecisionFromZone('B', 'level2')
 2193        True
 2194        >>> g.zoneParents(1)
 2195        set()
 2196        """
 2197        dID = self.resolveDecision(decision)
 2198
 2199        if zone not in self.zones:
 2200            return False
 2201
 2202        info = self.zones[zone]
 2203        if dID not in info.contents:
 2204            return False
 2205        else:
 2206            info.contents.remove(dID)
 2207            try:
 2208                self.nodes[dID]['zones'].remove(zone)
 2209            except KeyError:
 2210                pass
 2211            return True
 2212
 2213    def addZoneToZone(
 2214        self,
 2215        addIt: base.Zone,
 2216        addTo: base.Zone
 2217    ) -> None:
 2218        """
 2219        Adds a zone to another zone. The `addIt` one must be at a
 2220        strictly lower level than the `addTo` zone, or an
 2221        `InvalidLevelError` will be raised.
 2222
 2223        If the zone to be added didn't already exist, it is created at
 2224        one level below the target zone. Similarly, if the zone being
 2225        added to didn't already exist, it is created at one level above
 2226        the target zone. If neither existed, a `MissingZoneError` will
 2227        be raised.
 2228
 2229        For example:
 2230
 2231        >>> d = DecisionGraph()
 2232        >>> d.addDecision('A')
 2233        0
 2234        >>> d.addDecision('B')
 2235        1
 2236        >>> d.addDecision('C')
 2237        2
 2238        >>> d.createZone('Z', 0)
 2239        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2240 annotations=[])
 2241        >>> d.addDecisionToZone('A', 'Z')
 2242        >>> d.addDecisionToZone('B', 'Z')
 2243        >>> d.getZoneInfo('Z')
 2244        ZoneInfo(level=0, parents=set(), contents={0, 1}, tags={},\
 2245 annotations=[])
 2246        >>> d.createZone('Z2', 0)
 2247        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2248 annotations=[])
 2249        >>> d.addDecisionToZone('B', 'Z2')
 2250        >>> d.addDecisionToZone('C', 'Z2')
 2251        >>> d.getZoneInfo('Z2')
 2252        ZoneInfo(level=0, parents=set(), contents={1, 2}, tags={},\
 2253 annotations=[])
 2254        >>> d.createZone('l1Z', 1)
 2255        ZoneInfo(level=1, parents=set(), contents=set(), tags={},\
 2256 annotations=[])
 2257        >>> d.createZone('l2Z', 2)
 2258        ZoneInfo(level=2, parents=set(), contents=set(), tags={},\
 2259 annotations=[])
 2260        >>> d.addZoneToZone('Z', 'l1Z')
 2261        >>> d.getZoneInfo('Z')
 2262        ZoneInfo(level=0, parents={'l1Z'}, contents={0, 1}, tags={},\
 2263 annotations=[])
 2264        >>> d.getZoneInfo('l1Z')
 2265        ZoneInfo(level=1, parents=set(), contents={'Z'}, tags={},\
 2266 annotations=[])
 2267        >>> d.addZoneToZone('l1Z', 'l2Z')
 2268        >>> d.getZoneInfo('l1Z')
 2269        ZoneInfo(level=1, parents={'l2Z'}, contents={'Z'}, tags={},\
 2270 annotations=[])
 2271        >>> d.getZoneInfo('l2Z')
 2272        ZoneInfo(level=2, parents=set(), contents={'l1Z'}, tags={},\
 2273 annotations=[])
 2274        >>> d.addZoneToZone('Z2', 'l2Z')
 2275        >>> d.getZoneInfo('Z2')
 2276        ZoneInfo(level=0, parents={'l2Z'}, contents={1, 2}, tags={},\
 2277 annotations=[])
 2278        >>> l2i = d.getZoneInfo('l2Z')
 2279        >>> l2i.level
 2280        2
 2281        >>> l2i.parents
 2282        set()
 2283        >>> sorted(l2i.contents)
 2284        ['Z2', 'l1Z']
 2285        >>> d.addZoneToZone('NZ', 'NZ2')
 2286        Traceback (most recent call last):
 2287        ...
 2288        exploration.core.MissingZoneError...
 2289        >>> d.addZoneToZone('Z', 'l1Z2')
 2290        >>> zi = d.getZoneInfo('Z')
 2291        >>> zi.level
 2292        0
 2293        >>> sorted(zi.parents)
 2294        ['l1Z', 'l1Z2']
 2295        >>> sorted(zi.contents)
 2296        [0, 1]
 2297        >>> d.getZoneInfo('l1Z2')
 2298        ZoneInfo(level=1, parents=set(), contents={'Z'}, tags={},\
 2299 annotations=[])
 2300        >>> d.addZoneToZone('NZ', 'l1Z')
 2301        >>> d.getZoneInfo('NZ')
 2302        ZoneInfo(level=0, parents={'l1Z'}, contents=set(), tags={},\
 2303 annotations=[])
 2304        >>> zi = d.getZoneInfo('l1Z')
 2305        >>> zi.level
 2306        1
 2307        >>> zi.parents
 2308        {'l2Z'}
 2309        >>> sorted(zi.contents)
 2310        ['NZ', 'Z']
 2311        """
 2312        # Create one or the other (but not both) if they're missing
 2313        addInfo = self.getZoneInfo(addIt)
 2314        toInfo = self.getZoneInfo(addTo)
 2315        if addInfo is None and toInfo is None:
 2316            raise MissingZoneError(
 2317                f"Cannot add zone {addIt!r} to zone {addTo!r}: neither"
 2318                f" exists already."
 2319            )
 2320
 2321        # Create missing addIt
 2322        elif addInfo is None:
 2323            toInfo = cast(base.ZoneInfo, toInfo)
 2324            newLevel = toInfo.level - 1
 2325            if newLevel < 0:
 2326                raise InvalidLevelError(
 2327                    f"Zone {addTo!r} is at level {toInfo.level} and so"
 2328                    f" a new zone cannot be added underneath it."
 2329                )
 2330            addInfo = self.createZone(addIt, newLevel)
 2331
 2332        # Create missing addTo
 2333        elif toInfo is None:
 2334            addInfo = cast(base.ZoneInfo, addInfo)
 2335            newLevel = addInfo.level + 1
 2336            if newLevel < 0:
 2337                raise InvalidLevelError(
 2338                    f"Zone {addIt!r} is at level {addInfo.level} (!!!)"
 2339                    f" and so a new zone cannot be added above it."
 2340                )
 2341            toInfo = self.createZone(addTo, newLevel)
 2342
 2343        # Now both addInfo and toInfo are defined
 2344        if addInfo.level >= toInfo.level:
 2345            raise InvalidLevelError(
 2346                f"Cannot add zone {addIt!r} at level {addInfo.level}"
 2347                f" to zone {addTo!r} at level {toInfo.level}: zones can"
 2348                f" only contain zones of lower levels."
 2349            )
 2350
 2351        # Now both addInfo and toInfo are defined
 2352        toInfo.contents.add(addIt)
 2353        addInfo.parents.add(addTo)
 2354
 2355    def removeZoneFromZone(
 2356        self,
 2357        removeIt: base.Zone,
 2358        removeFrom: base.Zone
 2359    ) -> bool:
 2360        """
 2361        Removes a zone from a zone if it had been in it, returning True
 2362        if that zone had been in that zone, and False if it was not in
 2363        that zone, including if either zone did not exist.
 2364
 2365        For example:
 2366
 2367        >>> d = DecisionGraph()
 2368        >>> d.createZone('Z', 0)
 2369        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2370 annotations=[])
 2371        >>> d.createZone('Z2', 0)
 2372        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2373 annotations=[])
 2374        >>> d.createZone('l1Z', 1)
 2375        ZoneInfo(level=1, parents=set(), contents=set(), tags={},\
 2376 annotations=[])
 2377        >>> d.createZone('l2Z', 2)
 2378        ZoneInfo(level=2, parents=set(), contents=set(), tags={},\
 2379 annotations=[])
 2380        >>> d.addZoneToZone('Z', 'l1Z')
 2381        >>> d.addZoneToZone('l1Z', 'l2Z')
 2382        >>> d.getZoneInfo('Z')
 2383        ZoneInfo(level=0, parents={'l1Z'}, contents=set(), tags={},\
 2384 annotations=[])
 2385        >>> d.getZoneInfo('l1Z')
 2386        ZoneInfo(level=1, parents={'l2Z'}, contents={'Z'}, tags={},\
 2387 annotations=[])
 2388        >>> d.getZoneInfo('l2Z')
 2389        ZoneInfo(level=2, parents=set(), contents={'l1Z'}, tags={},\
 2390 annotations=[])
 2391        >>> d.removeZoneFromZone('l1Z', 'l2Z')
 2392        True
 2393        >>> d.getZoneInfo('l1Z')
 2394        ZoneInfo(level=1, parents=set(), contents={'Z'}, tags={},\
 2395 annotations=[])
 2396        >>> d.getZoneInfo('l2Z')
 2397        ZoneInfo(level=2, parents=set(), contents=set(), tags={},\
 2398 annotations=[])
 2399        >>> d.removeZoneFromZone('Z', 'l1Z')
 2400        True
 2401        >>> d.getZoneInfo('Z')
 2402        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2403 annotations=[])
 2404        >>> d.getZoneInfo('l1Z')
 2405        ZoneInfo(level=1, parents=set(), contents=set(), tags={},\
 2406 annotations=[])
 2407        >>> d.removeZoneFromZone('Z', 'l1Z')
 2408        False
 2409        >>> d.removeZoneFromZone('Z', 'madeup')
 2410        False
 2411        >>> d.removeZoneFromZone('nope', 'madeup')
 2412        False
 2413        >>> d.removeZoneFromZone('nope', 'l1Z')
 2414        False
 2415        """
 2416        remInfo = self.getZoneInfo(removeIt)
 2417        fromInfo = self.getZoneInfo(removeFrom)
 2418
 2419        if remInfo is None or fromInfo is None:
 2420            return False
 2421
 2422        if removeIt not in fromInfo.contents:
 2423            return False
 2424
 2425        remInfo.parents.remove(removeFrom)
 2426        fromInfo.contents.remove(removeIt)
 2427        return True
 2428
 2429    def decisionsInZone(self, zone: base.Zone) -> Set[base.DecisionID]:
 2430        """
 2431        Returns a set of all decisions included directly in the given
 2432        zone, not counting decisions included via intermediate
 2433        sub-zones (see `allDecisionsInZone` to include those).
 2434
 2435        Raises a `MissingZoneError` if the specified zone does not
 2436        exist.
 2437
 2438        The returned set is a copy, not a live editable set.
 2439
 2440        For example:
 2441
 2442        >>> d = DecisionGraph()
 2443        >>> d.addDecision('A')
 2444        0
 2445        >>> d.addDecision('B')
 2446        1
 2447        >>> d.addDecision('C')
 2448        2
 2449        >>> d.createZone('Z', 0)
 2450        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2451 annotations=[])
 2452        >>> d.addDecisionToZone('A', 'Z')
 2453        >>> d.addDecisionToZone('B', 'Z')
 2454        >>> d.getZoneInfo('Z')
 2455        ZoneInfo(level=0, parents=set(), contents={0, 1}, tags={},\
 2456 annotations=[])
 2457        >>> d.decisionsInZone('Z')
 2458        {0, 1}
 2459        >>> d.createZone('Z2', 0)
 2460        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2461 annotations=[])
 2462        >>> d.addDecisionToZone('B', 'Z2')
 2463        >>> d.addDecisionToZone('C', 'Z2')
 2464        >>> d.getZoneInfo('Z2')
 2465        ZoneInfo(level=0, parents=set(), contents={1, 2}, tags={},\
 2466 annotations=[])
 2467        >>> d.decisionsInZone('Z')
 2468        {0, 1}
 2469        >>> d.decisionsInZone('Z2')
 2470        {1, 2}
 2471        >>> d.createZone('l1Z', 1)
 2472        ZoneInfo(level=1, parents=set(), contents=set(), tags={},\
 2473 annotations=[])
 2474        >>> d.addZoneToZone('Z', 'l1Z')
 2475        >>> d.decisionsInZone('Z')
 2476        {0, 1}
 2477        >>> d.decisionsInZone('l1Z')
 2478        set()
 2479        >>> d.decisionsInZone('madeup')
 2480        Traceback (most recent call last):
 2481        ...
 2482        exploration.core.MissingZoneError...
 2483        >>> zDec = d.decisionsInZone('Z')
 2484        >>> zDec.add(2)  # won't affect the zone
 2485        >>> zDec
 2486        {0, 1, 2}
 2487        >>> d.decisionsInZone('Z')
 2488        {0, 1}
 2489        """
 2490        info = self.getZoneInfo(zone)
 2491        if info is None:
 2492            raise MissingZoneError(f"Zone {zone!r} does not exist.")
 2493
 2494        # Everything that's not a zone must be a decision
 2495        return {
 2496            item
 2497            for item in info.contents
 2498            if isinstance(item, base.DecisionID)
 2499        }
 2500
 2501    def subZones(self, zone: base.Zone) -> Set[base.Zone]:
 2502        """
 2503        Returns the set of all immediate sub-zones of the given zone.
 2504        Will be an empty set if there are no sub-zones; raises a
 2505        `MissingZoneError` if the specified zone does not exit.
 2506
 2507        The returned set is a copy, not a live editable set.
 2508
 2509        For example:
 2510
 2511        >>> d = DecisionGraph()
 2512        >>> d.createZone('Z', 0)
 2513        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2514 annotations=[])
 2515        >>> d.subZones('Z')
 2516        set()
 2517        >>> d.createZone('l1Z', 1)
 2518        ZoneInfo(level=1, parents=set(), contents=set(), tags={},\
 2519 annotations=[])
 2520        >>> d.addZoneToZone('Z', 'l1Z')
 2521        >>> d.subZones('Z')
 2522        set()
 2523        >>> d.subZones('l1Z')
 2524        {'Z'}
 2525        >>> s = d.subZones('l1Z')
 2526        >>> s.add('Q')  # doesn't affect the zone
 2527        >>> sorted(s)
 2528        ['Q', 'Z']
 2529        >>> d.subZones('l1Z')
 2530        {'Z'}
 2531        >>> d.subZones('madeup')
 2532        Traceback (most recent call last):
 2533        ...
 2534        exploration.core.MissingZoneError...
 2535        """
 2536        info = self.getZoneInfo(zone)
 2537        if info is None:
 2538            raise MissingZoneError(f"Zone {zone!r} does not exist.")
 2539
 2540        # Sub-zones will appear in self.zones
 2541        return {
 2542            item
 2543            for item in info.contents
 2544            if isinstance(item, base.Zone)
 2545        }
 2546
 2547    def allDecisionsInZone(self, zone: base.Zone) -> Set[base.DecisionID]:
 2548        """
 2549        Returns a set containing all decisions in the given zone,
 2550        including those included via sub-zones.
 2551
 2552        Raises a `MissingZoneError` if the specified zone does not
 2553        exist.`
 2554
 2555        For example:
 2556
 2557        >>> d = DecisionGraph()
 2558        >>> d.addDecision('A')
 2559        0
 2560        >>> d.addDecision('B')
 2561        1
 2562        >>> d.addDecision('C')
 2563        2
 2564        >>> d.createZone('Z', 0)
 2565        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2566 annotations=[])
 2567        >>> d.addDecisionToZone('A', 'Z')
 2568        >>> d.addDecisionToZone('B', 'Z')
 2569        >>> d.getZoneInfo('Z')
 2570        ZoneInfo(level=0, parents=set(), contents={0, 1}, tags={},\
 2571 annotations=[])
 2572        >>> d.decisionsInZone('Z')
 2573        {0, 1}
 2574        >>> d.allDecisionsInZone('Z')
 2575        {0, 1}
 2576        >>> d.createZone('Z2', 0)
 2577        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2578 annotations=[])
 2579        >>> d.addDecisionToZone('B', 'Z2')
 2580        >>> d.addDecisionToZone('C', 'Z2')
 2581        >>> d.getZoneInfo('Z2')
 2582        ZoneInfo(level=0, parents=set(), contents={1, 2}, tags={},\
 2583 annotations=[])
 2584        >>> d.decisionsInZone('Z')
 2585        {0, 1}
 2586        >>> d.decisionsInZone('Z2')
 2587        {1, 2}
 2588        >>> d.allDecisionsInZone('Z2')
 2589        {1, 2}
 2590        >>> d.createZone('l1Z', 1)
 2591        ZoneInfo(level=1, parents=set(), contents=set(), tags={},\
 2592 annotations=[])
 2593        >>> d.createZone('l2Z', 2)
 2594        ZoneInfo(level=2, parents=set(), contents=set(), tags={},\
 2595 annotations=[])
 2596        >>> d.addZoneToZone('Z', 'l1Z')
 2597        >>> d.addZoneToZone('l1Z', 'l2Z')
 2598        >>> d.addZoneToZone('Z2', 'l2Z')
 2599        >>> d.decisionsInZone('Z')
 2600        {0, 1}
 2601        >>> d.decisionsInZone('Z2')
 2602        {1, 2}
 2603        >>> d.decisionsInZone('l1Z')
 2604        set()
 2605        >>> d.allDecisionsInZone('l1Z')
 2606        {0, 1}
 2607        >>> d.allDecisionsInZone('l2Z')
 2608        {0, 1, 2}
 2609        """
 2610        result: Set[base.DecisionID] = set()
 2611        info = self.getZoneInfo(zone)
 2612        if info is None:
 2613            raise MissingZoneError(f"Zone {zone!r} does not exist.")
 2614
 2615        for item in info.contents:
 2616            if isinstance(item, base.Zone):
 2617                # This can't be an error because of the condition above
 2618                result |= self.allDecisionsInZone(item)
 2619            else:  # it's a decision
 2620                result.add(item)
 2621
 2622        return result
 2623
 2624    def zoneHierarchyLevel(self, zone: base.Zone) -> int:
 2625        """
 2626        Returns the hierarchy level of the given zone, as stored in its
 2627        zone info.
 2628
 2629        By convention, level-0 zones contain decisions directly, and
 2630        higher-level zones contain zones of lower levels. This
 2631        convention is not enforced, and there could be exceptions to it.
 2632
 2633        Raises a `MissingZoneError` if the specified zone does not
 2634        exist.
 2635
 2636        For example:
 2637
 2638        >>> d = DecisionGraph()
 2639        >>> d.createZone('Z', 0)
 2640        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2641 annotations=[])
 2642        >>> d.createZone('l1Z', 1)
 2643        ZoneInfo(level=1, parents=set(), contents=set(), tags={},\
 2644 annotations=[])
 2645        >>> d.createZone('l5Z', 5)
 2646        ZoneInfo(level=5, parents=set(), contents=set(), tags={},\
 2647 annotations=[])
 2648        >>> d.zoneHierarchyLevel('Z')
 2649        0
 2650        >>> d.zoneHierarchyLevel('l1Z')
 2651        1
 2652        >>> d.zoneHierarchyLevel('l5Z')
 2653        5
 2654        >>> d.zoneHierarchyLevel('madeup')
 2655        Traceback (most recent call last):
 2656        ...
 2657        exploration.core.MissingZoneError...
 2658        """
 2659        info = self.getZoneInfo(zone)
 2660        if info is None:
 2661            raise MissingZoneError(f"Zone {zone!r} dose not exist.")
 2662
 2663        return info.level
 2664
 2665    def zoneParents(
 2666        self,
 2667        zoneOrDecision: Union[base.Zone, base.DecisionID]
 2668    ) -> Set[base.Zone]:
 2669        """
 2670        Returns the set of all zones which directly contain the target
 2671        zone or decision.
 2672
 2673        Raises a `MissingDecisionError` if the target is neither a valid
 2674        zone nor a valid decision.
 2675
 2676        Returns a copy, not a live editable set.
 2677
 2678        Example:
 2679
 2680        >>> g = DecisionGraph()
 2681        >>> g.addDecision('A')
 2682        0
 2683        >>> g.addDecision('B')
 2684        1
 2685        >>> g.createZone('level0', 0)
 2686        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2687 annotations=[])
 2688        >>> g.createZone('level1', 1)
 2689        ZoneInfo(level=1, parents=set(), contents=set(), tags={},\
 2690 annotations=[])
 2691        >>> g.createZone('level2', 2)
 2692        ZoneInfo(level=2, parents=set(), contents=set(), tags={},\
 2693 annotations=[])
 2694        >>> g.createZone('level3', 3)
 2695        ZoneInfo(level=3, parents=set(), contents=set(), tags={},\
 2696 annotations=[])
 2697        >>> g.addDecisionToZone('A', 'level0')
 2698        >>> g.addDecisionToZone('B', 'level0')
 2699        >>> g.addZoneToZone('level0', 'level1')
 2700        >>> g.addZoneToZone('level1', 'level2')
 2701        >>> g.addZoneToZone('level2', 'level3')
 2702        >>> g.addDecisionToZone('B', 'level2')  # Direct w/ skips
 2703        >>> sorted(g.zoneParents(0))
 2704        ['level0']
 2705        >>> sorted(g.zoneParents(1))
 2706        ['level0', 'level2']
 2707        """
 2708        if zoneOrDecision in self.zones:
 2709            zoneOrDecision = cast(base.Zone, zoneOrDecision)
 2710            info = cast(base.ZoneInfo, self.getZoneInfo(zoneOrDecision))
 2711            return copy.copy(info.parents)
 2712        elif zoneOrDecision in self:
 2713            return self.nodes[zoneOrDecision].get('zones', set())
 2714        else:
 2715            raise MissingDecisionError(
 2716                f"Name {zoneOrDecision!r} is neither a valid zone nor a"
 2717                f" valid decision."
 2718            )
 2719
 2720    def zoneAncestors(
 2721        self,
 2722        zoneOrDecision: Union[base.Zone, base.DecisionID],
 2723        exclude: Set[base.Zone] = set(),
 2724        atLevel: Optional[int] = None
 2725    ) -> Set[base.Zone]:
 2726        """
 2727        Returns the set of zones which contain the target zone or
 2728        decision, either directly or indirectly. The target is not
 2729        included in the set.
 2730
 2731        Any ones listed in the `exclude` set are also excluded, as are
 2732        any of their ancestors which are not also ancestors of the
 2733        target zone via another path of inclusion.
 2734
 2735        If `atLevel` is not `None`, then only zones at that hierarchy
 2736        level will be included.
 2737
 2738        Raises a `MissingDecisionError` if the target is nether a valid
 2739        zone nor a valid decision.
 2740
 2741        Example:
 2742
 2743        >>> g = DecisionGraph()
 2744        >>> g.addDecision('A')
 2745        0
 2746        >>> g.addDecision('B')
 2747        1
 2748        >>> g.createZone('level0', 0)
 2749        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2750 annotations=[])
 2751        >>> g.createZone('level1', 1)
 2752        ZoneInfo(level=1, parents=set(), contents=set(), tags={},\
 2753 annotations=[])
 2754        >>> g.createZone('level2', 2)
 2755        ZoneInfo(level=2, parents=set(), contents=set(), tags={},\
 2756 annotations=[])
 2757        >>> g.createZone('level3', 3)
 2758        ZoneInfo(level=3, parents=set(), contents=set(), tags={},\
 2759 annotations=[])
 2760        >>> g.addDecisionToZone('A', 'level0')
 2761        >>> g.addDecisionToZone('B', 'level0')
 2762        >>> g.addZoneToZone('level0', 'level1')
 2763        >>> g.addZoneToZone('level1', 'level2')
 2764        >>> g.addZoneToZone('level2', 'level3')
 2765        >>> g.addDecisionToZone('B', 'level2')  # Direct w/ skips
 2766        >>> sorted(g.zoneAncestors(0))
 2767        ['level0', 'level1', 'level2', 'level3']
 2768        >>> sorted(g.zoneAncestors(1))
 2769        ['level0', 'level1', 'level2', 'level3']
 2770        >>> sorted(g.zoneParents(0))
 2771        ['level0']
 2772        >>> sorted(g.zoneParents(1))
 2773        ['level0', 'level2']
 2774        >>> sorted(g.zoneAncestors(0, atLevel=2))
 2775        ['level2']
 2776        >>> sorted(g.zoneAncestors(0, exclude={'level2'}))
 2777        ['level0', 'level1']
 2778        """
 2779        # Copy is important here!
 2780        result = set(self.zoneParents(zoneOrDecision))
 2781        result -= exclude
 2782        for parent in copy.copy(result):
 2783            # Recursively dig up ancestors, but exclude
 2784            # results-so-far to avoid re-enumerating when there are
 2785            # multiple braided inclusion paths.
 2786            result |= self.zoneAncestors(parent, result | exclude, atLevel)
 2787
 2788        if atLevel is not None:
 2789            return {z for z in result if self.zoneHierarchyLevel(z) == atLevel}
 2790        else:
 2791            return result
 2792
 2793    def region(
 2794        self,
 2795        decision: base.DecisionID,
 2796        useLevel: int=1
 2797    ) -> Optional[base.Zone]:
 2798        """
 2799        Returns the 'region' that this decision belongs to. 'Regions'
 2800        are level-1 zones, but when a decision is in multiple level-1
 2801        zones, its region counts as the smallest of those zones in terms
 2802        of total decisions contained, breaking ties by the one with the
 2803        alphabetically earlier name.
 2804
 2805        Always returns a single zone name string, unless the target
 2806        decision is not in any level-1 zones, in which case it returns
 2807        `None`.
 2808
 2809        If `useLevel` is specified, then zones of the specified level
 2810        will be used instead of level-1 zones.
 2811
 2812        Example:
 2813
 2814        >>> g = DecisionGraph()
 2815        >>> g.addDecision('A')
 2816        0
 2817        >>> g.addDecision('B')
 2818        1
 2819        >>> g.addDecision('C')
 2820        2
 2821        >>> g.addDecision('D')
 2822        3
 2823        >>> g.createZone('zoneX', 0)
 2824        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2825 annotations=[])
 2826        >>> g.createZone('regionA', 1)
 2827        ZoneInfo(level=1, parents=set(), contents=set(), tags={},\
 2828 annotations=[])
 2829        >>> g.createZone('zoneY', 0)
 2830        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2831 annotations=[])
 2832        >>> g.createZone('regionB', 1)
 2833        ZoneInfo(level=1, parents=set(), contents=set(), tags={},\
 2834 annotations=[])
 2835        >>> g.createZone('regionC', 1)
 2836        ZoneInfo(level=1, parents=set(), contents=set(), tags={},\
 2837 annotations=[])
 2838        >>> g.createZone('quadrant', 2)
 2839        ZoneInfo(level=2, parents=set(), contents=set(), tags={},\
 2840 annotations=[])
 2841        >>> g.addDecisionToZone('A', 'zoneX')
 2842        >>> g.addDecisionToZone('B', 'zoneY')
 2843        >>> # C is not in any level-1 zones
 2844        >>> g.addDecisionToZone('D', 'zoneX')
 2845        >>> g.addDecisionToZone('D', 'zoneY')  # D is in both
 2846        >>> g.addZoneToZone('zoneX', 'regionA')
 2847        >>> g.addZoneToZone('zoneY', 'regionB')
 2848        >>> g.addZoneToZone('zoneX', 'regionC')  # includes both
 2849        >>> g.addZoneToZone('zoneY', 'regionC')
 2850        >>> g.addZoneToZone('regionA', 'quadrant')
 2851        >>> g.addZoneToZone('regionB', 'quadrant')
 2852        >>> g.addDecisionToZone('C', 'regionC')  # Direct in level-2
 2853        >>> sorted(g.allDecisionsInZone('zoneX'))
 2854        [0, 3]
 2855        >>> sorted(g.allDecisionsInZone('zoneY'))
 2856        [1, 3]
 2857        >>> sorted(g.allDecisionsInZone('regionA'))
 2858        [0, 3]
 2859        >>> sorted(g.allDecisionsInZone('regionB'))
 2860        [1, 3]
 2861        >>> sorted(g.allDecisionsInZone('regionC'))
 2862        [0, 1, 2, 3]
 2863        >>> sorted(g.allDecisionsInZone('quadrant'))
 2864        [0, 1, 3]
 2865        >>> g.region(0)  # for A; region A is smaller than region C
 2866        'regionA'
 2867        >>> g.region(1)  # for B; region B is also smaller than C
 2868        'regionB'
 2869        >>> g.region(2)  # for C
 2870        'regionC'
 2871        >>> g.region(3)  # for D; tie broken alphabetically
 2872        'regionA'
 2873        >>> g.region(0, useLevel=0)  # for A at level 0
 2874        'zoneX'
 2875        >>> g.region(1, useLevel=0)  # for B at level 0
 2876        'zoneY'
 2877        >>> g.region(2, useLevel=0) is None  # for C at level 0 (none)
 2878        True
 2879        >>> g.region(3, useLevel=0)  # for D at level 0; tie
 2880        'zoneX'
 2881        >>> g.region(0, useLevel=2) # for A at level 2
 2882        'quadrant'
 2883        >>> g.region(1, useLevel=2) # for B at level 2
 2884        'quadrant'
 2885        >>> g.region(2, useLevel=2) is None # for C at level 2 (none)
 2886        True
 2887        >>> g.region(3, useLevel=2)  # for D at level 2
 2888        'quadrant'
 2889        """
 2890        relevant = self.zoneAncestors(decision, atLevel=useLevel)
 2891        if len(relevant) == 0:
 2892            return None
 2893        elif len(relevant) == 1:
 2894            for zone in relevant:
 2895                return zone
 2896            return None  # not really necessary but keeps mypy happy
 2897        else:
 2898            # more than one zone ancestor at the relevant hierarchy
 2899            # level: need to measure their sizes
 2900            minSize = None
 2901            candidates = []
 2902            for zone in relevant:
 2903                size = len(self.allDecisionsInZone(zone))
 2904                if minSize is None or size < minSize:
 2905                    candidates = [zone]
 2906                    minSize = size
 2907                elif size == minSize:
 2908                    candidates.append(zone)
 2909            return min(candidates)
 2910
 2911    def zoneEdges(self, zone: base.Zone) -> Optional[
 2912        Tuple[
 2913            Set[Tuple[base.DecisionID, base.Transition]],
 2914            Set[Tuple[base.DecisionID, base.Transition]]
 2915        ]
 2916    ]:
 2917        """
 2918        Given a zone to look at, finds all of the transitions which go
 2919        out of and into that zone, ignoring internal transitions between
 2920        decisions in the zone. This includes all decisions in sub-zones.
 2921        The return value is a pair of sets for outgoing and then
 2922        incoming transitions, where each transition is specified as a
 2923        (sourceID, transitionName) pair.
 2924
 2925        Returns `None` if the target zone isn't yet fully defined.
 2926
 2927        Note that this takes time proportional to *all* edges plus *all*
 2928        nodes in the graph no matter how large or small the zone in
 2929        question is.
 2930
 2931        >>> g = DecisionGraph()
 2932        >>> g.addDecision('A')
 2933        0
 2934        >>> g.addDecision('B')
 2935        1
 2936        >>> g.addDecision('C')
 2937        2
 2938        >>> g.addDecision('D')
 2939        3
 2940        >>> g.addTransition('A', 'up', 'B', 'down')
 2941        >>> g.addTransition('B', 'right', 'C', 'left')
 2942        >>> g.addTransition('C', 'down', 'D', 'up')
 2943        >>> g.addTransition('D', 'left', 'A', 'right')
 2944        >>> g.addTransition('A', 'tunnel', 'C', 'tunnel')
 2945        >>> g.createZone('Z', 0)
 2946        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2947 annotations=[])
 2948        >>> g.createZone('ZZ', 1)
 2949        ZoneInfo(level=1, parents=set(), contents=set(), tags={},\
 2950 annotations=[])
 2951        >>> g.addZoneToZone('Z', 'ZZ')
 2952        >>> g.addDecisionToZone('A', 'Z')
 2953        >>> g.addDecisionToZone('B', 'Z')
 2954        >>> g.addDecisionToZone('D', 'ZZ')
 2955        >>> outgoing, incoming = g.zoneEdges('Z')  # TODO: Sort for testing
 2956        >>> sorted(outgoing)
 2957        [(0, 'right'), (0, 'tunnel'), (1, 'right')]
 2958        >>> sorted(incoming)
 2959        [(2, 'left'), (2, 'tunnel'), (3, 'left')]
 2960        >>> outgoing, incoming = g.zoneEdges('ZZ')
 2961        >>> sorted(outgoing)
 2962        [(0, 'tunnel'), (1, 'right'), (3, 'up')]
 2963        >>> sorted(incoming)
 2964        [(2, 'down'), (2, 'left'), (2, 'tunnel')]
 2965        >>> g.zoneEdges('madeup') is None
 2966        True
 2967        """
 2968        # Find the interior nodes
 2969        try:
 2970            interior = self.allDecisionsInZone(zone)
 2971        except MissingZoneError:
 2972            return None
 2973
 2974        # Set up our result
 2975        results: Tuple[
 2976            Set[Tuple[base.DecisionID, base.Transition]],
 2977            Set[Tuple[base.DecisionID, base.Transition]]
 2978        ] = (set(), set())
 2979
 2980        # Because finding incoming edges requires searching the entire
 2981        # graph anyways, it's more efficient to just consider each edge
 2982        # once.
 2983        for fromDecision in self:
 2984            fromThere = self[fromDecision]
 2985            for toDecision in fromThere:
 2986                for transition in fromThere[toDecision]:
 2987                    sourceIn = fromDecision in interior
 2988                    destIn = toDecision in interior
 2989                    if sourceIn and not destIn:
 2990                        results[0].add((fromDecision, transition))
 2991                    elif destIn and not sourceIn:
 2992                        results[1].add((fromDecision, transition))
 2993
 2994        return results
 2995
 2996    def replaceZonesInHierarchy(
 2997        self,
 2998        target: base.AnyDecisionSpecifier,
 2999        zone: base.Zone,
 3000        level: int
 3001    ) -> None:
 3002        """
 3003        This method replaces one or more zones which contain the
 3004        specified `target` decision with a specific zone, at a specific
 3005        level in the zone hierarchy (see `zoneHierarchyLevel`). If the
 3006        named zone doesn't yet exist, it will be created.
 3007
 3008        To do this, it looks at all zones which contain the target
 3009        decision directly or indirectly (see `zoneAncestors`) and which
 3010        are at the specified level.
 3011
 3012        - Any direct children of those zones which are ancestors of the
 3013            target decision are removed from those zones and placed into
 3014            the new zone instead, regardless of their levels. Indirect
 3015            children are not affected (except perhaps indirectly via
 3016            their parents' ancestors changing).
 3017        - The new zone is placed into every direct parent of those
 3018            zones, regardless of their levels (those parents are by
 3019            definition all ancestors of the target decision).
 3020        - If there were no zones at the target level, every zone at the
 3021            next level down which is an ancestor of the target decision
 3022            (or just that decision if the level is 0) is placed into the
 3023            new zone as a direct child (and is removed from any previous
 3024            parents it had). In this case, the new zone will also be
 3025            added as a sub-zone to every ancestor of the target decision
 3026            at the level above the specified level, if there are any.
 3027            * In this case, if there are no zones at the level below the
 3028                specified level, the highest level of zones smaller than
 3029                that is treated as the level below, down to targeting
 3030                the decision itself.
 3031            * Similarly, if there are no zones at the level above the
 3032                specified level but there are zones at a higher level,
 3033                the new zone will be added to each of the zones in the
 3034                lowest level above the target level that has zones in it.
 3035
 3036        A `MissingDecisionError` will be raised if the specified
 3037        decision is not valid, or if the decision is left as default but
 3038        there is no current decision in the exploration.
 3039
 3040        An `InvalidLevelError` will be raised if the level is less than
 3041        zero.
 3042
 3043        Example:
 3044
 3045        >>> g = DecisionGraph()
 3046        >>> g.addDecision('decision')
 3047        0
 3048        >>> g.addDecision('alternate')
 3049        1
 3050        >>> g.createZone('zone0', 0)
 3051        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 3052 annotations=[])
 3053        >>> g.createZone('zone1', 1)
 3054        ZoneInfo(level=1, parents=set(), contents=set(), tags={},\
 3055 annotations=[])
 3056        >>> g.createZone('zone2.1', 2)
 3057        ZoneInfo(level=2, parents=set(), contents=set(), tags={},\
 3058 annotations=[])
 3059        >>> g.createZone('zone2.2', 2)
 3060        ZoneInfo(level=2, parents=set(), contents=set(), tags={},\
 3061 annotations=[])
 3062        >>> g.createZone('zone3', 3)
 3063        ZoneInfo(level=3, parents=set(), contents=set(), tags={},\
 3064 annotations=[])
 3065        >>> g.addDecisionToZone('decision', 'zone0')
 3066        >>> g.addDecisionToZone('alternate', 'zone0')
 3067        >>> g.addZoneToZone('zone0', 'zone1')
 3068        >>> g.addZoneToZone('zone1', 'zone2.1')
 3069        >>> g.addZoneToZone('zone1', 'zone2.2')
 3070        >>> g.addZoneToZone('zone2.1', 'zone3')
 3071        >>> g.addZoneToZone('zone2.2', 'zone3')
 3072        >>> g.zoneHierarchyLevel('zone0')
 3073        0
 3074        >>> g.zoneHierarchyLevel('zone1')
 3075        1
 3076        >>> g.zoneHierarchyLevel('zone2.1')
 3077        2
 3078        >>> g.zoneHierarchyLevel('zone2.2')
 3079        2
 3080        >>> g.zoneHierarchyLevel('zone3')
 3081        3
 3082        >>> sorted(g.decisionsInZone('zone0'))
 3083        [0, 1]
 3084        >>> sorted(g.zoneAncestors('zone0'))
 3085        ['zone1', 'zone2.1', 'zone2.2', 'zone3']
 3086        >>> g.subZones('zone1')
 3087        {'zone0'}
 3088        >>> g.zoneParents('zone0')
 3089        {'zone1'}
 3090        >>> g.replaceZonesInHierarchy('decision', 'new0', 0)
 3091        >>> g.zoneParents('zone0')
 3092        {'zone1'}
 3093        >>> g.zoneParents('new0')
 3094        {'zone1'}
 3095        >>> sorted(g.zoneAncestors('zone0'))
 3096        ['zone1', 'zone2.1', 'zone2.2', 'zone3']
 3097        >>> sorted(g.zoneAncestors('new0'))
 3098        ['zone1', 'zone2.1', 'zone2.2', 'zone3']
 3099        >>> g.decisionsInZone('zone0')
 3100        {1}
 3101        >>> g.decisionsInZone('new0')
 3102        {0}
 3103        >>> sorted(g.subZones('zone1'))
 3104        ['new0', 'zone0']
 3105        >>> g.zoneParents('new0')
 3106        {'zone1'}
 3107        >>> g.replaceZonesInHierarchy('decision', 'new1', 1)
 3108        >>> sorted(g.zoneAncestors(0))
 3109        ['new0', 'new1', 'zone2.1', 'zone2.2', 'zone3']
 3110        >>> g.subZones('zone1')
 3111        {'zone0'}
 3112        >>> g.subZones('new1')
 3113        {'new0'}
 3114        >>> g.zoneParents('new0')
 3115        {'new1'}
 3116        >>> sorted(g.zoneParents('zone1'))
 3117        ['zone2.1', 'zone2.2']
 3118        >>> sorted(g.zoneParents('new1'))
 3119        ['zone2.1', 'zone2.2']
 3120        >>> g.zoneParents('zone2.1')
 3121        {'zone3'}
 3122        >>> g.zoneParents('zone2.2')
 3123        {'zone3'}
 3124        >>> sorted(g.subZones('zone2.1'))
 3125        ['new1', 'zone1']
 3126        >>> sorted(g.subZones('zone2.2'))
 3127        ['new1', 'zone1']
 3128        >>> sorted(g.allDecisionsInZone('zone2.1'))
 3129        [0, 1]
 3130        >>> sorted(g.allDecisionsInZone('zone2.2'))
 3131        [0, 1]
 3132        >>> g.replaceZonesInHierarchy('decision', 'new2', 2)
 3133        >>> g.zoneParents('zone2.1')
 3134        {'zone3'}
 3135        >>> g.zoneParents('zone2.2')
 3136        {'zone3'}
 3137        >>> g.subZones('zone2.1')
 3138        {'zone1'}
 3139        >>> g.subZones('zone2.2')
 3140        {'zone1'}
 3141        >>> g.subZones('new2')
 3142        {'new1'}
 3143        >>> g.zoneParents('new2')
 3144        {'zone3'}
 3145        >>> g.allDecisionsInZone('zone2.1')
 3146        {1}
 3147        >>> g.allDecisionsInZone('zone2.2')
 3148        {1}
 3149        >>> g.allDecisionsInZone('new2')
 3150        {0}
 3151        >>> sorted(g.subZones('zone3'))
 3152        ['new2', 'zone2.1', 'zone2.2']
 3153        >>> g.zoneParents('zone3')
 3154        set()
 3155        >>> sorted(g.allDecisionsInZone('zone3'))
 3156        [0, 1]
 3157        >>> g.replaceZonesInHierarchy('decision', 'new3', 3)
 3158        >>> sorted(g.subZones('zone3'))
 3159        ['zone2.1', 'zone2.2']
 3160        >>> g.subZones('new3')
 3161        {'new2'}
 3162        >>> g.zoneParents('zone3')
 3163        set()
 3164        >>> g.zoneParents('new3')
 3165        set()
 3166        >>> g.allDecisionsInZone('zone3')
 3167        {1}
 3168        >>> g.allDecisionsInZone('new3')
 3169        {0}
 3170        >>> g.replaceZonesInHierarchy('decision', 'new4', 5)
 3171        >>> g.subZones('new4')
 3172        {'new3'}
 3173        >>> g.zoneHierarchyLevel('new4')
 3174        5
 3175
 3176        Another example of level collapse when trying to replace a zone
 3177        at a level above :
 3178
 3179        >>> g = DecisionGraph()
 3180        >>> g.addDecision('A')
 3181        0
 3182        >>> g.addDecision('B')
 3183        1
 3184        >>> g.createZone('level0', 0)
 3185        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 3186 annotations=[])
 3187        >>> g.createZone('level1', 1)
 3188        ZoneInfo(level=1, parents=set(), contents=set(), tags={},\
 3189 annotations=[])
 3190        >>> g.createZone('level2', 2)
 3191        ZoneInfo(level=2, parents=set(), contents=set(), tags={},\
 3192 annotations=[])
 3193        >>> g.createZone('level3', 3)
 3194        ZoneInfo(level=3, parents=set(), contents=set(), tags={},\
 3195 annotations=[])
 3196        >>> g.addDecisionToZone('B', 'level0')
 3197        >>> g.addZoneToZone('level0', 'level1')
 3198        >>> g.addZoneToZone('level1', 'level2')
 3199        >>> g.addZoneToZone('level2', 'level3')
 3200        >>> g.addDecisionToZone('A', 'level3') # missing some zone levels
 3201        >>> g.zoneHierarchyLevel('level3')
 3202        3
 3203        >>> g.replaceZonesInHierarchy('A', 'newFirst', 1)
 3204        >>> g.zoneHierarchyLevel('newFirst')
 3205        1
 3206        >>> g.decisionsInZone('newFirst')
 3207        {0}
 3208        >>> g.decisionsInZone('level3')
 3209        set()
 3210        >>> sorted(g.allDecisionsInZone('level3'))
 3211        [0, 1]
 3212        >>> g.subZones('newFirst')
 3213        set()
 3214        >>> sorted(g.subZones('level3'))
 3215        ['level2', 'newFirst']
 3216        >>> g.zoneParents('newFirst')
 3217        {'level3'}
 3218        >>> g.replaceZonesInHierarchy('A', 'newSecond', 2)
 3219        >>> g.zoneHierarchyLevel('newSecond')
 3220        2
 3221        >>> g.decisionsInZone('newSecond')
 3222        set()
 3223        >>> g.allDecisionsInZone('newSecond')
 3224        {0}
 3225        >>> g.subZones('newSecond')
 3226        {'newFirst'}
 3227        >>> g.zoneParents('newSecond')
 3228        {'level3'}
 3229        >>> g.zoneParents('newFirst')
 3230        {'newSecond'}
 3231        >>> sorted(g.subZones('level3'))
 3232        ['level2', 'newSecond']
 3233        """
 3234        tID = self.resolveDecision(target)
 3235
 3236        if level < 0:
 3237            raise InvalidLevelError(
 3238                f"Target level must be positive (got {level})."
 3239            )
 3240
 3241        info = self.getZoneInfo(zone)
 3242        if info is None:
 3243            info = self.createZone(zone, level)
 3244        elif level != info.level:
 3245            raise InvalidLevelError(
 3246                f"Target level ({level}) does not match the level of"
 3247                f" the target zone ({zone!r} at level {info.level})."
 3248            )
 3249
 3250        # Collect both parents & ancestors
 3251        parents = self.zoneParents(tID)
 3252        ancestors = set(self.zoneAncestors(tID))
 3253
 3254        # Map from levels to sets of zones from the ancestors pool
 3255        levelMap: Dict[int, Set[base.Zone]] = {}
 3256        highest = -1
 3257        for ancestor in ancestors:
 3258            ancestorLevel = self.zoneHierarchyLevel(ancestor)
 3259            levelMap.setdefault(ancestorLevel, set()).add(ancestor)
 3260            if ancestorLevel > highest:
 3261                highest = ancestorLevel
 3262
 3263        # Figure out if we have target zones to replace or not
 3264        reparentDecision = False
 3265        if level in levelMap:
 3266            # If there are zones at the target level,
 3267            targetZones = levelMap[level]
 3268
 3269            above = set()
 3270            below = set()
 3271
 3272            for replaced in targetZones:
 3273                above |= self.zoneParents(replaced)
 3274                below |= self.subZones(replaced)
 3275                if replaced in parents:
 3276                    reparentDecision = True
 3277
 3278            # Only ancestors should be reparented
 3279            below &= ancestors
 3280
 3281        else:
 3282            # Find levels w/ zones in them above + below
 3283            levelBelow = level - 1
 3284            levelAbove = level + 1
 3285            below = levelMap.get(levelBelow, set())
 3286            above = levelMap.get(levelAbove, set())
 3287
 3288            while len(below) == 0 and levelBelow > 0:
 3289                levelBelow -= 1
 3290                below = levelMap.get(levelBelow, set())
 3291
 3292            if len(below) == 0:
 3293                reparentDecision = True
 3294
 3295            while len(above) == 0 and levelAbove < highest:
 3296                levelAbove += 1
 3297                above = levelMap.get(levelAbove, set())
 3298
 3299        # Handle re-parenting zones below
 3300        for under in below:
 3301            for parent in self.zoneParents(under):
 3302                if parent in ancestors:
 3303                    self.removeZoneFromZone(under, parent)
 3304            self.addZoneToZone(under, zone)
 3305
 3306        # Add this zone to each parent
 3307        for parent in above:
 3308            self.addZoneToZone(zone, parent)
 3309
 3310        # Re-parent the decision itself if necessary
 3311        if reparentDecision:
 3312            # (using set() here to avoid size-change-during-iteration)
 3313            for parent in set(parents):
 3314                self.removeDecisionFromZone(tID, parent)
 3315            self.addDecisionToZone(tID, zone)
 3316
 3317    def getReciprocal(
 3318        self,
 3319        decision: base.AnyDecisionSpecifier,
 3320        transition: base.Transition
 3321    ) -> Optional[base.Transition]:
 3322        """
 3323        Returns the reciprocal edge for the specified transition from the
 3324        specified decision (see `setReciprocal`). Returns
 3325        `None` if no reciprocal has been established for that
 3326        transition, or if that decision or transition does not exist.
 3327        """
 3328        dID = self.resolveDecision(decision)
 3329
 3330        dest = self.getDestination(dID, transition)
 3331        if dest is not None:
 3332            info = cast(
 3333                TransitionProperties,
 3334                self.edges[dID, dest, transition]  # type:ignore
 3335            )
 3336            recip = info.get("reciprocal")
 3337            if recip is not None and not isinstance(recip, base.Transition):
 3338                raise ValueError(f"Invalid reciprocal value: {repr(recip)}")
 3339            return recip
 3340        else:
 3341            return None
 3342
 3343    def setReciprocal(
 3344        self,
 3345        decision: base.AnyDecisionSpecifier,
 3346        transition: base.Transition,
 3347        reciprocal: Optional[base.Transition],
 3348        setBoth: bool = True,
 3349        cleanup: bool = True
 3350    ) -> None:
 3351        """
 3352        Sets the 'reciprocal' transition for a particular transition from
 3353        a particular decision, and removes the reciprocal property from
 3354        any old reciprocal transition.
 3355
 3356        Raises a `MissingDecisionError` or a `MissingTransitionError` if
 3357        the specified decision or transition does not exist.
 3358
 3359        Raises an `InvalidDestinationError` if the reciprocal transition
 3360        does not exist, or if it does exist but does not lead back to
 3361        the decision the transition came from.
 3362
 3363        If `setBoth` is True (the default) then the transition which is
 3364        being identified as a reciprocal will also have its reciprocal
 3365        property set, pointing back to the primary transition being
 3366        modified, and any old reciprocal of that transition will have its
 3367        reciprocal set to None. If you want to create a situation with
 3368        non-exclusive reciprocals, use `setBoth=False`.
 3369
 3370        If `cleanup` is True (the default) then abandoned reciprocal
 3371        transitions (for both edges if `setBoth` was true) have their
 3372        reciprocal properties removed. Set `cleanup` to false if you want
 3373        to retain them, although this will result in non-exclusive
 3374        reciprocal relationships.
 3375
 3376        If the `reciprocal` value is None, this deletes the reciprocal
 3377        value entirely, and if `setBoth` is true, it does this for the
 3378        previous reciprocal edge as well. No error is raised in this case
 3379        when there was not already a reciprocal to delete.
 3380
 3381        Note that one should remove a reciprocal relationship before
 3382        redirecting either edge of the pair in a way that gives it a new
 3383        reciprocal, since otherwise, a later attempt to remove the
 3384        reciprocal with `setBoth` set to True (the default) will end up
 3385        deleting the reciprocal information from the other edge that was
 3386        already modified. There is no way to reliably detect and avoid
 3387        this, because two different decisions could (and often do in
 3388        practice) have transitions with identical names, meaning that the
 3389        reciprocal value will still be the same, but it will indicate a
 3390        different edge in virtue of the destination of the edge changing.
 3391
 3392        ## Example
 3393
 3394        >>> g = DecisionGraph()
 3395        >>> g.addDecision('G')
 3396        0
 3397        >>> g.addDecision('H')
 3398        1
 3399        >>> g.addDecision('I')
 3400        2
 3401        >>> g.addTransition('G', 'up', 'H', 'down')
 3402        >>> g.addTransition('G', 'next', 'H', 'prev')
 3403        >>> g.addTransition('H', 'next', 'I', 'prev')
 3404        >>> g.addTransition('H', 'return', 'G')
 3405        >>> g.setReciprocal('G', 'up', 'next') # Error w/ destinations
 3406        Traceback (most recent call last):
 3407        ...
 3408        exploration.core.InvalidDestinationError...
 3409        >>> g.setReciprocal('G', 'up', 'none') # Doesn't exist
 3410        Traceback (most recent call last):
 3411        ...
 3412        exploration.core.MissingTransitionError...
 3413        >>> g.getReciprocal('G', 'up')
 3414        'down'
 3415        >>> g.getReciprocal('H', 'down')
 3416        'up'
 3417        >>> g.getReciprocal('H', 'return') is None
 3418        True
 3419        >>> g.setReciprocal('G', 'up', 'return')
 3420        >>> g.getReciprocal('G', 'up')
 3421        'return'
 3422        >>> g.getReciprocal('H', 'down') is None
 3423        True
 3424        >>> g.getReciprocal('H', 'return')
 3425        'up'
 3426        >>> g.setReciprocal('H', 'return', None) # remove the reciprocal
 3427        >>> g.getReciprocal('G', 'up') is None
 3428        True
 3429        >>> g.getReciprocal('H', 'down') is None
 3430        True
 3431        >>> g.getReciprocal('H', 'return') is None
 3432        True
 3433        >>> g.setReciprocal('G', 'up', 'down', setBoth=False) # one-way
 3434        >>> g.getReciprocal('G', 'up')
 3435        'down'
 3436        >>> g.getReciprocal('H', 'down') is None
 3437        True
 3438        >>> g.getReciprocal('H', 'return') is None
 3439        True
 3440        >>> g.setReciprocal('H', 'return', 'up', setBoth=False) # non-sym
 3441        >>> g.getReciprocal('G', 'up')
 3442        'down'
 3443        >>> g.getReciprocal('H', 'down') is None
 3444        True
 3445        >>> g.getReciprocal('H', 'return')
 3446        'up'
 3447        >>> g.setReciprocal('H', 'down', 'up') # setBoth not needed
 3448        >>> g.getReciprocal('G', 'up')
 3449        'down'
 3450        >>> g.getReciprocal('H', 'down')
 3451        'up'
 3452        >>> g.getReciprocal('H', 'return') # unchanged
 3453        'up'
 3454        >>> g.setReciprocal('G', 'up', 'return', cleanup=False) # no cleanup
 3455        >>> g.getReciprocal('G', 'up')
 3456        'return'
 3457        >>> g.getReciprocal('H', 'down')
 3458        'up'
 3459        >>> g.getReciprocal('H', 'return') # unchanged
 3460        'up'
 3461        >>> # Cleanup only applies to reciprocal if setBoth is true
 3462        >>> g.setReciprocal('H', 'down', 'up', setBoth=False)
 3463        >>> g.getReciprocal('G', 'up')
 3464        'return'
 3465        >>> g.getReciprocal('H', 'down')
 3466        'up'
 3467        >>> g.getReciprocal('H', 'return') # not cleaned up w/out setBoth
 3468        'up'
 3469        >>> g.setReciprocal('H', 'down', 'up') # with cleanup and setBoth
 3470        >>> g.getReciprocal('G', 'up')
 3471        'down'
 3472        >>> g.getReciprocal('H', 'down')
 3473        'up'
 3474        >>> g.getReciprocal('H', 'return') is None # cleaned up
 3475        True
 3476        """
 3477        dID = self.resolveDecision(decision)
 3478
 3479        dest = self.destination(dID, transition) # possible KeyError
 3480        if reciprocal is None:
 3481            rDest = None
 3482        else:
 3483            rDest = self.getDestination(dest, reciprocal)
 3484
 3485        # Set or delete reciprocal property
 3486        if reciprocal is None:
 3487            # Delete the property
 3488            info = self.edges[dID, dest, transition]  # type:ignore
 3489
 3490            old = info.pop('reciprocal')
 3491            if setBoth:
 3492                rDest = self.getDestination(dest, old)
 3493                if rDest != dID:
 3494                    raise RuntimeError(
 3495                        f"Invalid reciprocal {old!r} for transition"
 3496                        f" {transition!r} from {self.identityOf(dID)}:"
 3497                        f" destination is {rDest}."
 3498                    )
 3499                rInfo = self.edges[dest, dID, old]  # type:ignore
 3500                if 'reciprocal' in rInfo:
 3501                    del rInfo['reciprocal']
 3502        else:
 3503            # Set the property, checking for errors first
 3504            if rDest is None:
 3505                raise MissingTransitionError(
 3506                    f"Reciprocal transition {reciprocal!r} for"
 3507                    f" transition {transition!r} from decision"
 3508                    f" {self.identityOf(dID)} does not exist at"
 3509                    f" decision {self.identityOf(dest)}"
 3510                )
 3511
 3512            if rDest != dID:
 3513                raise InvalidDestinationError(
 3514                    f"Reciprocal transition {reciprocal!r} from"
 3515                    f" decision {self.identityOf(dest)} does not lead"
 3516                    f" back to decision {self.identityOf(dID)}."
 3517                )
 3518
 3519            eProps = self.edges[dID, dest, transition]  # type:ignore [index]
 3520            abandoned = eProps.get('reciprocal')
 3521            eProps['reciprocal'] = reciprocal
 3522            if cleanup and abandoned not in (None, reciprocal):
 3523                aProps = self.edges[dest, dID, abandoned]  # type:ignore
 3524                if 'reciprocal' in aProps:
 3525                    del aProps['reciprocal']
 3526
 3527            if setBoth:
 3528                rProps = self.edges[dest, dID, reciprocal]  # type:ignore
 3529                revAbandoned = rProps.get('reciprocal')
 3530                rProps['reciprocal'] = transition
 3531                # Sever old reciprocal relationship
 3532                if cleanup and revAbandoned not in (None, transition):
 3533                    raProps = self.edges[
 3534                        dID,  # type:ignore
 3535                        dest,
 3536                        revAbandoned
 3537                    ]
 3538                    del raProps['reciprocal']
 3539
 3540    def getReciprocalPair(
 3541        self,
 3542        decision: base.AnyDecisionSpecifier,
 3543        transition: base.Transition
 3544    ) -> Optional[Tuple[base.DecisionID, base.Transition]]:
 3545        """
 3546        Returns a tuple containing both the destination decision ID and
 3547        the transition at that decision which is the reciprocal of the
 3548        specified destination & transition. Returns `None` if no
 3549        reciprocal has been established for that transition, or if that
 3550        decision or transition does not exist.
 3551
 3552        >>> g = DecisionGraph()
 3553        >>> g.addDecision('A')
 3554        0
 3555        >>> g.addDecision('B')
 3556        1
 3557        >>> g.addDecision('C')
 3558        2
 3559        >>> g.addTransition('A', 'up', 'B', 'down')
 3560        >>> g.addTransition('B', 'right', 'C', 'left')
 3561        >>> g.addTransition('A', 'oneway', 'C')
 3562        >>> g.getReciprocalPair('A', 'up')
 3563        (1, 'down')
 3564        >>> g.getReciprocalPair('B', 'down')
 3565        (0, 'up')
 3566        >>> g.getReciprocalPair('B', 'right')
 3567        (2, 'left')
 3568        >>> g.getReciprocalPair('C', 'left')
 3569        (1, 'right')
 3570        >>> g.getReciprocalPair('C', 'up') is None
 3571        True
 3572        >>> g.getReciprocalPair('Q', 'up') is None
 3573        True
 3574        >>> g.getReciprocalPair('A', 'tunnel') is None
 3575        True
 3576        """
 3577        try:
 3578            dID = self.resolveDecision(decision)
 3579        except MissingDecisionError:
 3580            return None
 3581
 3582        reciprocal = self.getReciprocal(dID, transition)
 3583        if reciprocal is None:
 3584            return None
 3585        else:
 3586            destination = self.getDestination(dID, transition)
 3587            if destination is None:
 3588                return None
 3589            else:
 3590                return (destination, reciprocal)
 3591
 3592    def addDecision(
 3593        self,
 3594        name: base.DecisionName,
 3595        domain: Optional[base.Domain] = None,
 3596        tags: Optional[Dict[base.Tag, base.TagValue]] = None,
 3597        annotations: Optional[List[base.Annotation]] = None
 3598    ) -> base.DecisionID:
 3599        """
 3600        Adds a decision to the graph, without any transitions yet. Each
 3601        decision will be assigned an ID so name collisions are allowed,
 3602        but it's usually best to keep names unique at least within each
 3603        zone. If no domain is provided, the `DEFAULT_DOMAIN` will be
 3604        used for the decision's domain. A dictionary of tags and/or a
 3605        list of annotations (strings in both cases) may be provided.
 3606
 3607        Returns the newly-assigned `DecisionID` for the decision it
 3608        created.
 3609
 3610        Emits a `DecisionCollisionWarning` if a decision with the
 3611        provided name already exists and the `WARN_OF_NAME_COLLISIONS`
 3612        global variable is set to `True`.
 3613        """
 3614        # Defaults
 3615        if domain is None:
 3616            domain = base.DEFAULT_DOMAIN
 3617        if tags is None:
 3618            tags = {}
 3619        if annotations is None:
 3620            annotations = []
 3621
 3622        # Error checking
 3623        if name in self.nameLookup and WARN_OF_NAME_COLLISIONS:
 3624            warnings.warn(
 3625                (
 3626                    f"Adding decision {name!r}: Another decision with"
 3627                    f" that name already exists."
 3628                ),
 3629                DecisionCollisionWarning
 3630            )
 3631
 3632        dID = self._assignID()
 3633
 3634        # Add the decision
 3635        self.add_node(
 3636            dID,
 3637            name=name,
 3638            domain=domain,
 3639            tags=tags,
 3640            annotations=annotations
 3641        )
 3642        #TODO: Elide tags/annotations if they're empty?
 3643
 3644        # Track it in our `nameLookup` dictionary
 3645        self.nameLookup.setdefault(name, []).append(dID)
 3646
 3647        return dID
 3648
 3649    def addIdentifiedDecision(
 3650        self,
 3651        dID: base.DecisionID,
 3652        name: base.DecisionName,
 3653        domain: Optional[base.Domain] = None,
 3654        tags: Optional[Dict[base.Tag, base.TagValue]] = None,
 3655        annotations: Optional[List[base.Annotation]] = None
 3656    ) -> None:
 3657        """
 3658        Adds a new decision to the graph using a specific decision ID,
 3659        rather than automatically assigning a new decision ID like
 3660        `addDecision` does. Otherwise works like `addDecision`.
 3661
 3662        Raises a `MechanismCollisionError` if the specified decision ID
 3663        is already in use.
 3664        """
 3665        # Defaults
 3666        if domain is None:
 3667            domain = base.DEFAULT_DOMAIN
 3668        if tags is None:
 3669            tags = {}
 3670        if annotations is None:
 3671            annotations = []
 3672
 3673        # Error checking
 3674        if dID in self.nodes:
 3675            raise MechanismCollisionError(
 3676                f"Cannot add a node with id {dID} and name {name!r}:"
 3677                f" that ID is already used by node {self.identityOf(dID)}"
 3678            )
 3679
 3680        if name in self.nameLookup and WARN_OF_NAME_COLLISIONS:
 3681            warnings.warn(
 3682                (
 3683                    f"Adding decision {name!r}: Another decision with"
 3684                    f" that name already exists."
 3685                ),
 3686                DecisionCollisionWarning
 3687            )
 3688
 3689        # Add the decision
 3690        self.add_node(
 3691            dID,
 3692            name=name,
 3693            domain=domain,
 3694            tags=tags,
 3695            annotations=annotations
 3696        )
 3697        #TODO: Elide tags/annotations if they're empty?
 3698
 3699        # Track it in our `nameLookup` dictionary
 3700        self.nameLookup.setdefault(name, []).append(dID)
 3701
 3702    def addTransition(
 3703        self,
 3704        fromDecision: base.AnyDecisionSpecifier,
 3705        name: base.Transition,
 3706        toDecision: base.AnyDecisionSpecifier,
 3707        reciprocal: Optional[base.Transition] = None,
 3708        tags: Optional[Dict[base.Tag, base.TagValue]] = None,
 3709        annotations: Optional[List[base.Annotation]] = None,
 3710        revTags: Optional[Dict[base.Tag, base.TagValue]] = None,
 3711        revAnnotations: Optional[List[base.Annotation]] = None,
 3712        requires: Optional[base.Requirement] = None,
 3713        consequence: Optional[base.Consequence] = None,
 3714        revRequires: Optional[base.Requirement] = None,
 3715        revConsequece: Optional[base.Consequence] = None
 3716    ) -> None:
 3717        """
 3718        Adds a transition connecting two decisions. A specifier for each
 3719        decision is required, as is a name for the transition. If a
 3720        `reciprocal` is provided, a reciprocal edge will be added in the
 3721        opposite direction using that name; by default only the specified
 3722        edge is added. A `TransitionCollisionError` will be raised if the
 3723        `reciprocal` matches the name of an existing edge at the
 3724        destination decision.
 3725
 3726        Both decisions must already exist, or a `MissingDecisionError`
 3727        will be raised.
 3728
 3729        A dictionary of tags and/or a list of annotations may be
 3730        provided. Tags and/or annotations for the reverse edge may also
 3731        be specified if one is being added.
 3732
 3733        The `requires`, `consequence`, `revRequires`, and `revConsequece`
 3734        arguments specify requirements and/or consequences of the new
 3735        outgoing and reciprocal edges.
 3736        """
 3737        # Defaults
 3738        if tags is None:
 3739            tags = {}
 3740        if annotations is None:
 3741            annotations = []
 3742        if revTags is None:
 3743            revTags = {}
 3744        if revAnnotations is None:
 3745            revAnnotations = []
 3746
 3747        # Error checking
 3748        fromID = self.resolveDecision(fromDecision)
 3749        toID = self.resolveDecision(toDecision)
 3750
 3751        # Note: have to check this first so we don't add the forward edge
 3752        # and then error out after a side effect!
 3753        if (
 3754            reciprocal is not None
 3755        and self.getDestination(toDecision, reciprocal) is not None
 3756        ):
 3757            raise TransitionCollisionError(
 3758                f"Cannot add a transition from"
 3759                f" {self.identityOf(fromDecision)} to"
 3760                f" {self.identityOf(toDecision)} with reciprocal edge"
 3761                f" {reciprocal!r}: {reciprocal!r} is already used as an"
 3762                f" edge name at {self.identityOf(toDecision)}."
 3763            )
 3764
 3765        # Add the edge
 3766        self.add_edge(
 3767            fromID,
 3768            toID,
 3769            key=name,
 3770            tags=tags,
 3771            annotations=annotations
 3772        )
 3773        self.setTransitionRequirement(fromDecision, name, requires)
 3774        if consequence is not None:
 3775            self.setConsequence(fromDecision, name, consequence)
 3776        if reciprocal is not None:
 3777            # Add the reciprocal edge
 3778            self.add_edge(
 3779                toID,
 3780                fromID,
 3781                key=reciprocal,
 3782                tags=revTags,
 3783                annotations=revAnnotations
 3784            )
 3785            self.setReciprocal(fromID, name, reciprocal)
 3786            self.setTransitionRequirement(
 3787                toDecision,
 3788                reciprocal,
 3789                revRequires
 3790            )
 3791            if revConsequece is not None:
 3792                self.setConsequence(toDecision, reciprocal, revConsequece)
 3793
 3794    def removeTransition(
 3795        self,
 3796        fromDecision: base.AnyDecisionSpecifier,
 3797        transition: base.Transition,
 3798        removeReciprocal=False
 3799    ) -> Union[
 3800        TransitionProperties,
 3801        Tuple[TransitionProperties, TransitionProperties]
 3802    ]:
 3803        """
 3804        Removes a transition. If `removeReciprocal` is true (False is the
 3805        default) any reciprocal transition will also be removed (but no
 3806        error will occur if there wasn't a reciprocal).
 3807
 3808        For each removed transition, *every* transition that targeted
 3809        that transition as its reciprocal will have its reciprocal set to
 3810        `None`, to avoid leaving any invalid reciprocal values.
 3811
 3812        Raises a `KeyError` if either the target decision or the target
 3813        transition does not exist.
 3814
 3815        Returns a transition properties dictionary with the properties
 3816        of the removed transition, or if `removeReciprocal` is true,
 3817        returns a pair of such dictionaries for the target transition
 3818        and its reciprocal.
 3819
 3820        ## Example
 3821
 3822        >>> g = DecisionGraph()
 3823        >>> g.addDecision('A')
 3824        0
 3825        >>> g.addDecision('B')
 3826        1
 3827        >>> g.addTransition('A', 'up', 'B', 'down', tags={'wide'})
 3828        >>> g.addTransition('A', 'in', 'B', 'out') # we won't touch this
 3829        >>> g.addTransition('A', 'next', 'B')
 3830        >>> g.setReciprocal('A', 'next', 'down', setBoth=False)
 3831        >>> p = g.removeTransition('A', 'up')
 3832        >>> p['tags']
 3833        {'wide'}
 3834        >>> g.destinationsFrom('A')
 3835        {'in': 1, 'next': 1}
 3836        >>> g.destinationsFrom('B')
 3837        {'down': 0, 'out': 0}
 3838        >>> g.getReciprocal('B', 'down') is None
 3839        True
 3840        >>> g.getReciprocal('A', 'next') # Asymmetrical left over
 3841        'down'
 3842        >>> g.getReciprocal('A', 'in') # not affected
 3843        'out'
 3844        >>> g.getReciprocal('B', 'out') # not affected
 3845        'in'
 3846        >>> # Now with removeReciprocal set to True
 3847        >>> g.addTransition('A', 'up', 'B') # add this back in
 3848        >>> g.setReciprocal('A', 'up', 'down') # sets both
 3849        >>> p = g.removeTransition('A', 'up', removeReciprocal=True)
 3850        >>> g.destinationsFrom('A')
 3851        {'in': 1, 'next': 1}
 3852        >>> g.destinationsFrom('B')
 3853        {'out': 0}
 3854        >>> g.getReciprocal('A', 'next') is None
 3855        True
 3856        >>> g.getReciprocal('A', 'in') # not affected
 3857        'out'
 3858        >>> g.getReciprocal('B', 'out') # not affected
 3859        'in'
 3860        >>> g.removeTransition('A', 'none')
 3861        Traceback (most recent call last):
 3862        ...
 3863        exploration.core.MissingTransitionError...
 3864        >>> g.removeTransition('Z', 'nope')
 3865        Traceback (most recent call last):
 3866        ...
 3867        exploration.core.MissingDecisionError...
 3868        """
 3869        # Resolve target ID
 3870        fromID = self.resolveDecision(fromDecision)
 3871
 3872        # raises if either is missing:
 3873        destination = self.destination(fromID, transition)
 3874        reciprocal = self.getReciprocal(fromID, transition)
 3875
 3876        # Get dictionaries of parallel & antiparallel edges to be
 3877        # checked for invalid reciprocals after removing edges
 3878        # Note: these will update live as we remove edges
 3879        allAntiparallel = self[destination][fromID]
 3880        allParallel = self[fromID][destination]
 3881
 3882        # Remove the target edge
 3883        fProps = self.getTransitionProperties(fromID, transition)
 3884        self.remove_edge(fromID, destination, transition)
 3885
 3886        # Clean up any dangling reciprocal values
 3887        for tProps in allAntiparallel.values():
 3888            if tProps.get('reciprocal') == transition:
 3889                del tProps['reciprocal']
 3890
 3891        # Remove the reciprocal if requested
 3892        if removeReciprocal and reciprocal is not None:
 3893            rProps = self.getTransitionProperties(destination, reciprocal)
 3894            self.remove_edge(destination, fromID, reciprocal)
 3895
 3896            # Clean up any dangling reciprocal values
 3897            for tProps in allParallel.values():
 3898                if tProps.get('reciprocal') == reciprocal:
 3899                    del tProps['reciprocal']
 3900
 3901            return (fProps, rProps)
 3902        else:
 3903            return fProps
 3904
 3905    def addMechanism(
 3906        self,
 3907        name: base.MechanismName,
 3908        where: Optional[base.AnyDecisionSpecifier] = None
 3909    ) -> base.MechanismID:
 3910        """
 3911        Creates a new mechanism with the given name at the specified
 3912        decision, returning its assigned ID. If `where` is `None`, it
 3913        creates a global mechanism. Raises a `MechanismCollisionError`
 3914        if a mechanism with the same name already exists at a specified
 3915        decision (or already exists as a global mechanism).
 3916
 3917        Note that if the decision is deleted, the mechanism will be as
 3918        well.
 3919
 3920        Since `MechanismState`s are not tracked by `DecisionGraph`s but
 3921        instead are part of a `State`, the mechanism won't be in any
 3922        particular state, which means it will be treated as being in the
 3923        `base.DEFAULT_MECHANISM_STATE`.
 3924        """
 3925        if where is None:
 3926            mechs = self.globalMechanisms
 3927            dID = None
 3928        else:
 3929            dID = self.resolveDecision(where)
 3930            mechs = self.nodes[dID].setdefault('mechanisms', {})
 3931
 3932        if name in mechs:
 3933            if dID is None:
 3934                raise MechanismCollisionError(
 3935                    f"A global mechanism named {name!r} already exists."
 3936                )
 3937            else:
 3938                raise MechanismCollisionError(
 3939                    f"A mechanism named {name!r} already exists at"
 3940                    f" decision {self.identityOf(dID)}."
 3941                )
 3942
 3943        mID = self._assignMechanismID()
 3944        mechs[name] = mID
 3945        self.mechanisms[mID] = (dID, name)
 3946        return mID
 3947
 3948    def mechanismsAt(
 3949        self,
 3950        decision: base.AnyDecisionSpecifier
 3951    ) -> Dict[base.MechanismName, base.MechanismID]:
 3952        """
 3953        Returns a dictionary mapping mechanism names to their IDs for
 3954        all mechanisms at the specified decision.
 3955        """
 3956        dID = self.resolveDecision(decision)
 3957
 3958        return self.nodes[dID]['mechanisms']
 3959
 3960    def mechanismDetails(
 3961        self,
 3962        mID: base.MechanismID
 3963    ) -> Optional[Tuple[Optional[base.DecisionID], base.MechanismName]]:
 3964        """
 3965        Returns a tuple containing the decision ID and mechanism name
 3966        for the specified mechanism. Returns `None` if there is no
 3967        mechanism with that ID. For global mechanisms, `None` is used in
 3968        place of a decision ID.
 3969        """
 3970        return self.mechanisms.get(mID)
 3971
 3972    def deleteMechanism(self, mID: base.MechanismID) -> None:
 3973        """
 3974        Deletes the specified mechanism.
 3975        """
 3976        name, dID = self.mechanisms.pop(mID)
 3977
 3978        del self.nodes[dID]['mechanisms'][name]
 3979
 3980    def localLookup(
 3981        self,
 3982        startFrom: Union[
 3983            base.AnyDecisionSpecifier,
 3984            Collection[base.AnyDecisionSpecifier]
 3985        ],
 3986        findAmong: Callable[
 3987            ['DecisionGraph', Union[Set[base.DecisionID], str]],
 3988            Optional[LookupResult]
 3989        ],
 3990        fallbackLayerName: Optional[str] = "fallback",
 3991        fallbackToAllDecisions: bool = True
 3992    ) -> Optional[LookupResult]:
 3993        """
 3994        Looks up some kind of result in the graph by starting from a
 3995        base set of decisions and widening the search iteratively based
 3996        on zones. This first searches for result(s) in the set of
 3997        decisions given, then in the set of all decisions which are in
 3998        level-0 zones containing those decisions, then in level-1 zones,
 3999        etc. When it runs out of relevant zones, it will check all
 4000        decisions which are in any domain that a decision from the
 4001        initial search set is in, and then if `fallbackLayerName` is a
 4002        string, it will provide that string instead of a set of decision
 4003        IDs to the `findAmong` function as the next layer to search.
 4004        After the `fallbackLayerName` is used, if
 4005        `fallbackToAllDecisions` is `True` (the default) a final search
 4006        will be run on all decisions in the graph. The provided
 4007        `findAmong` function is called on each successive decision ID
 4008        set, until it generates a non-`None` result. We stop and return
 4009        that non-`None` result as soon as one is generated. But if none
 4010        of the decision sets consulted generate non-`None` results, then
 4011        the entire result will be `None`.
 4012        """
 4013        # Normalize starting decisions to a set
 4014        if isinstance(startFrom, (int, str, base.DecisionSpecifier)):
 4015            startFrom = set([startFrom])
 4016
 4017        # Resolve decision IDs; convert to list
 4018        searchArea: Union[Set[base.DecisionID], str] = set(
 4019            self.resolveDecision(spec) for spec in startFrom
 4020        )
 4021
 4022        # Find all ancestor zones & all relevant domains
 4023        allAncestors = set()
 4024        relevantDomains = set()
 4025        for startingDecision in searchArea:
 4026            allAncestors |= self.zoneAncestors(startingDecision)
 4027            relevantDomains.add(self.domainFor(startingDecision))
 4028
 4029        # Build layers dictionary
 4030        ancestorLayers: Dict[int, Set[base.Zone]] = {}
 4031        for zone in allAncestors:
 4032            info = self.getZoneInfo(zone)
 4033            assert info is not None
 4034            level = info.level
 4035            ancestorLayers.setdefault(level, set()).add(zone)
 4036
 4037        searchLayers: LookupLayersList = (
 4038            cast(LookupLayersList, [None])
 4039          + cast(LookupLayersList, sorted(ancestorLayers.keys()))
 4040          + cast(LookupLayersList, ["domains"])
 4041        )
 4042        if fallbackLayerName is not None:
 4043            searchLayers.append("fallback")
 4044
 4045        if fallbackToAllDecisions:
 4046            searchLayers.append("all")
 4047
 4048        # Continue our search through zone layers
 4049        for layer in searchLayers:
 4050            # Update search area on subsequent iterations
 4051            if layer == "domains":
 4052                searchArea = set()
 4053                for relevant in relevantDomains:
 4054                    searchArea |= self.allDecisionsInDomain(relevant)
 4055            elif layer == "fallback":
 4056                assert fallbackLayerName is not None
 4057                searchArea = fallbackLayerName
 4058            elif layer == "all":
 4059                searchArea = set(self.nodes)
 4060            elif layer is not None:
 4061                layer = cast(int, layer)  # must be an integer
 4062                searchZones = ancestorLayers[layer]
 4063                searchArea = set()
 4064                for zone in searchZones:
 4065                    searchArea |= self.allDecisionsInZone(zone)
 4066            # else it's the first iteration and we use the starting
 4067            # searchArea
 4068
 4069            searchResult: Optional[LookupResult] = findAmong(
 4070                self,
 4071                searchArea
 4072            )
 4073
 4074            if searchResult is not None:
 4075                return searchResult
 4076
 4077        # Didn't find any non-None results.
 4078        return None
 4079
 4080    @staticmethod
 4081    def uniqueMechanismFinder(name: base.MechanismName) -> Callable[
 4082        ['DecisionGraph', Union[Set[base.DecisionID], str]],
 4083        Optional[base.MechanismID]
 4084    ]:
 4085        """
 4086        Returns a search function that looks for the given mechanism ID,
 4087        suitable for use with `localLookup`. The finder will raise a
 4088        `MechanismCollisionError` if it finds more than one mechanism
 4089        with the specified name at the same level of the search.
 4090        """
 4091        def namedMechanismFinder(
 4092            graph: 'DecisionGraph',
 4093            searchIn: Union[Set[base.DecisionID], str]
 4094        ) -> Optional[base.MechanismID]:
 4095            """
 4096            Generated finder function for `localLookup` to find a unique
 4097            mechanism by name.
 4098            """
 4099            candidates: List[base.DecisionID] = []
 4100
 4101            if searchIn == "fallback":
 4102                if name in graph.globalMechanisms:
 4103                    candidates = [graph.globalMechanisms[name]]
 4104
 4105            else:
 4106                assert isinstance(searchIn, set)
 4107                for dID in searchIn:
 4108                    mechs = graph.nodes[dID].get('mechanisms', {})
 4109                    if name in mechs:
 4110                        candidates.append(mechs[name])
 4111
 4112            if len(candidates) > 1:
 4113                raise MechanismCollisionError(
 4114                    f"There are {len(candidates)} mechanisms named {name!r}"
 4115                    f" in the search area ({len(searchIn)} decisions(s))."
 4116                )
 4117            elif len(candidates) == 1:
 4118                return candidates[0]
 4119            else:
 4120                return None
 4121
 4122        return namedMechanismFinder
 4123
 4124    def lookupMechanism(
 4125        self,
 4126        startFrom: Union[
 4127            base.AnyDecisionSpecifier,
 4128            Collection[base.AnyDecisionSpecifier]
 4129        ],
 4130        name: base.MechanismName
 4131    ) -> base.MechanismID:
 4132        """
 4133        Looks up the mechanism with the given name 'closest' to the
 4134        given decision or set of decisions. First it looks for a
 4135        mechanism with that name that's at one of those decisions. Then
 4136        it starts looking in level-0 zones which contain any of them,
 4137        then in level-1 zones, and so on. If it finds two mechanisms
 4138        with the target name during the same search pass, it raises a
 4139        `MechanismCollisionError`, but if it finds one it returns it.
 4140        Raises a `MissingMechanismError` if there is no mechanisms with
 4141        that name among global mechanisms (searched after the last
 4142        applicable level of zones) or anywhere in the graph (which is the
 4143        final level of search after checking global mechanisms).
 4144
 4145        For example:
 4146
 4147        >>> d = DecisionGraph()
 4148        >>> d.addDecision('A')
 4149        0
 4150        >>> d.addDecision('B')
 4151        1
 4152        >>> d.addDecision('C')
 4153        2
 4154        >>> d.addDecision('D')
 4155        3
 4156        >>> d.addDecision('E')
 4157        4
 4158        >>> d.addMechanism('switch', 'A')
 4159        0
 4160        >>> d.addMechanism('switch', 'B')
 4161        1
 4162        >>> d.addMechanism('switch', 'C')
 4163        2
 4164        >>> d.addMechanism('lever', 'D')
 4165        3
 4166        >>> d.addMechanism('lever', None)  # global
 4167        4
 4168        >>> d.createZone('Z1', 0)
 4169        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 4170 annotations=[])
 4171        >>> d.createZone('Z2', 0)
 4172        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 4173 annotations=[])
 4174        >>> d.createZone('Zup', 1)
 4175        ZoneInfo(level=1, parents=set(), contents=set(), tags={},\
 4176 annotations=[])
 4177        >>> d.addDecisionToZone('A', 'Z1')
 4178        >>> d.addDecisionToZone('B', 'Z1')
 4179        >>> d.addDecisionToZone('C', 'Z2')
 4180        >>> d.addDecisionToZone('D', 'Z2')
 4181        >>> d.addDecisionToZone('E', 'Z1')
 4182        >>> d.addZoneToZone('Z1', 'Zup')
 4183        >>> d.addZoneToZone('Z2', 'Zup')
 4184        >>> d.lookupMechanism(set(), 'switch')  # 3x among all decisions
 4185        Traceback (most recent call last):
 4186        ...
 4187        exploration.core.MechanismCollisionError...
 4188        >>> d.lookupMechanism(set(), 'lever')  # 1x global > 1x all
 4189        4
 4190        >>> d.lookupMechanism({'D'}, 'lever')  # local
 4191        3
 4192        >>> d.lookupMechanism({'A'}, 'lever')  # found at D via Zup
 4193        3
 4194        >>> d.lookupMechanism({'A', 'D'}, 'lever')  # local again
 4195        3
 4196        >>> d.lookupMechanism({'A'}, 'switch')  # local
 4197        0
 4198        >>> d.lookupMechanism({'B'}, 'switch')  # local
 4199        1
 4200        >>> d.lookupMechanism({'C'}, 'switch')  # local
 4201        2
 4202        >>> d.lookupMechanism({'A', 'B'}, 'switch')  # ambiguous
 4203        Traceback (most recent call last):
 4204        ...
 4205        exploration.core.MechanismCollisionError...
 4206        >>> d.lookupMechanism({'A', 'B', 'C'}, 'switch')  # ambiguous
 4207        Traceback (most recent call last):
 4208        ...
 4209        exploration.core.MechanismCollisionError...
 4210        >>> d.lookupMechanism({'B', 'D'}, 'switch')  # not ambiguous
 4211        1
 4212        >>> d.lookupMechanism({'E', 'D'}, 'switch')  # ambiguous at L0 zone
 4213        Traceback (most recent call last):
 4214        ...
 4215        exploration.core.MechanismCollisionError...
 4216        >>> d.lookupMechanism({'E'}, 'switch')  # ambiguous at L0 zone
 4217        Traceback (most recent call last):
 4218        ...
 4219        exploration.core.MechanismCollisionError...
 4220        >>> d.lookupMechanism({'D'}, 'switch')  # found at L0 zone
 4221        2
 4222        """
 4223        result = self.localLookup(
 4224            startFrom,
 4225            DecisionGraph.uniqueMechanismFinder(name)
 4226        )
 4227        if result is None:
 4228            raise MissingMechanismError(
 4229                f"No mechanism named {name!r}"
 4230            )
 4231        else:
 4232            return result
 4233
 4234    def resolveMechanism(
 4235        self,
 4236        specifier: base.AnyMechanismSpecifier,
 4237        startFrom: Union[
 4238            None,
 4239            base.AnyDecisionSpecifier,
 4240            Collection[base.AnyDecisionSpecifier]
 4241        ] = None
 4242    ) -> base.MechanismID:
 4243        """
 4244        Works like `lookupMechanism`, except it accepts a
 4245        `base.AnyMechanismSpecifier` which may have position information
 4246        baked in, and so the `startFrom` information is optional. If
 4247        position information isn't specified in the mechanism specifier
 4248        and startFrom is not provided, the mechanism is searched for at
 4249        the global scope and then in the entire graph. On the other
 4250        hand, if the specifier includes any position information, the
 4251        startFrom value provided here will be ignored.
 4252        """
 4253        if isinstance(specifier, base.MechanismID):
 4254            return specifier
 4255
 4256        elif isinstance(specifier, base.MechanismName):
 4257            if startFrom is None:
 4258                startFrom = set()
 4259            return self.lookupMechanism(startFrom, specifier)
 4260
 4261        elif isinstance(specifier, tuple) and len(specifier) == 4:
 4262            domain, zone, decision, mechanism = specifier
 4263            if domain is None and zone is None and decision is None:
 4264                if startFrom is None:
 4265                    startFrom = set()
 4266                return self.lookupMechanism(startFrom, mechanism)
 4267
 4268            elif decision is not None:
 4269                startFrom = {
 4270                    self.resolveDecision(
 4271                        base.DecisionSpecifier(domain, zone, decision)
 4272                    )
 4273                }
 4274                return self.lookupMechanism(startFrom, mechanism)
 4275
 4276            else:  # decision is None but domain and/or zone aren't
 4277                startFrom = set()
 4278                if zone is not None:
 4279                    baseStart = self.allDecisionsInZone(zone)
 4280                else:
 4281                    baseStart = set(self)
 4282
 4283                if domain is None:
 4284                    startFrom = baseStart
 4285                else:
 4286                    for dID in baseStart:
 4287                        if self.domainFor(dID) == domain:
 4288                            startFrom.add(dID)
 4289                return self.lookupMechanism(startFrom, mechanism)
 4290
 4291        else:
 4292            raise TypeError(
 4293                f"Invalid mechanism specifier: {repr(specifier)}"
 4294                f"\n(Must be a mechanism ID, mechanism name, or"
 4295                f" mechanism specifier tuple)"
 4296            )
 4297
 4298    def walkConsequenceMechanisms(
 4299        self,
 4300        consequence: base.Consequence,
 4301        searchFrom: Set[base.DecisionID]
 4302    ) -> Generator[base.MechanismID, None, None]:
 4303        """
 4304        Yields each requirement in the given `base.Consequence`,
 4305        including those in `base.Condition`s, `base.ConditionalSkill`s
 4306        within `base.Challenge`s, and those set or toggled by
 4307        `base.Effect`s. The `searchFrom` argument specifies where to
 4308        start searching for mechanisms, since requirements include them
 4309        by name, not by ID.
 4310        """
 4311        for part in base.walkParts(consequence):
 4312            if isinstance(part, dict):
 4313                if 'skills' in part:  # a Challenge
 4314                    for cSkill in part['skills'].walk():
 4315                        if isinstance(cSkill, base.ConditionalSkill):
 4316                            yield from self.walkRequirementMechanisms(
 4317                                cSkill.requirement,
 4318                                searchFrom
 4319                            )
 4320                elif 'condition' in part:  # a Condition
 4321                    yield from self.walkRequirementMechanisms(
 4322                        part['condition'],
 4323                        searchFrom
 4324                    )
 4325                elif 'value' in part:  # an Effect
 4326                    val = part['value']
 4327                    if part['type'] == 'set':
 4328                        if (
 4329                            isinstance(val, tuple)
 4330                        and len(val) == 2
 4331                        and isinstance(val[1], base.State)
 4332                        ):
 4333                            yield from self.walkRequirementMechanisms(
 4334                                base.ReqMechanism(val[0], val[1]),
 4335                                searchFrom
 4336                            )
 4337                    elif part['type'] == 'toggle':
 4338                        if isinstance(val, tuple):
 4339                            assert len(val) == 2
 4340                            yield from self.walkRequirementMechanisms(
 4341                                base.ReqMechanism(val[0], '_'),
 4342                                  # state part is ignored here
 4343                                searchFrom
 4344                            )
 4345
 4346    def walkRequirementMechanisms(
 4347        self,
 4348        req: base.Requirement,
 4349        searchFrom: Set[base.DecisionID]
 4350    ) -> Generator[base.MechanismID, None, None]:
 4351        """
 4352        Given a requirement, yields any mechanisms mentioned in that
 4353        requirement, in depth-first traversal order.
 4354        """
 4355        for part in req.walk():
 4356            if isinstance(part, base.ReqMechanism):
 4357                mech = part.mechanism
 4358                yield self.resolveMechanism(
 4359                    mech,
 4360                    startFrom=searchFrom
 4361                )
 4362
 4363    def addUnexploredEdge(
 4364        self,
 4365        fromDecision: base.AnyDecisionSpecifier,
 4366        name: base.Transition,
 4367        destinationName: Optional[base.DecisionName] = None,
 4368        reciprocal: Optional[base.Transition] = 'return',
 4369        toDomain: Optional[base.Domain] = None,
 4370        placeInZone: Optional[base.Zone] = None,
 4371        tags: Optional[Dict[base.Tag, base.TagValue]] = None,
 4372        annotations: Optional[List[base.Annotation]] = None,
 4373        revTags: Optional[Dict[base.Tag, base.TagValue]] = None,
 4374        revAnnotations: Optional[List[base.Annotation]] = None,
 4375        requires: Optional[base.Requirement] = None,
 4376        consequence: Optional[base.Consequence] = None,
 4377        revRequires: Optional[base.Requirement] = None,
 4378        revConsequece: Optional[base.Consequence] = None
 4379    ) -> base.DecisionID:
 4380        """
 4381        Adds a transition connecting to a new decision named `'_u.-n-'`
 4382        where '-n-' is the number of unknown decisions (named or not)
 4383        that have ever been created in this graph (or using the
 4384        specified destination name if one is provided). This represents
 4385        a transition to an unknown destination. The destination node
 4386        gets tagged 'unconfirmed'.
 4387
 4388        This also adds a reciprocal transition in the reverse direction,
 4389        unless `reciprocal` is set to `None`. The reciprocal will use
 4390        the provided name (default is 'return'). The new decision will
 4391        be in the same domain as the decision it's connected to, unless
 4392        `toDecision` is specified, in which case it will be in that
 4393        domain.
 4394
 4395        The new decision will not be placed into any zones, unless
 4396        `placeInZone` is specified, in which case it will be placed into
 4397        that zone. If that zone needs to be created, it will be created
 4398        at level 0; in that case that zone will be added to any
 4399        grandparent zones of the decision we're branching off of. If
 4400        `placeInZone` is set to `base.DefaultZone`, then the new
 4401        decision will be placed into each parent zone of the decision
 4402        we're branching off of, as long as the new decision is in the
 4403        same domain as the decision we're branching from (otherwise only
 4404        an explicit `placeInZone` would apply).
 4405
 4406        The ID of the decision that was created is returned.
 4407
 4408        A `MissingDecisionError` will be raised if the starting decision
 4409        does not exist, a `TransitionCollisionError` will be raised if
 4410        it exists but already has a transition with the given name, and a
 4411        `DecisionCollisionWarning` will be issued if a decision with the
 4412        specified destination name already exists (won't happen when
 4413        using an automatic name).
 4414
 4415        Lists of tags and/or annotations (strings in both cases) may be
 4416        provided. These may also be provided for the reciprocal edge.
 4417
 4418        Similarly, requirements and/or consequences for either edge may
 4419        be provided.
 4420
 4421        ## Example
 4422
 4423        >>> g = DecisionGraph()
 4424        >>> g.addDecision('A')
 4425        0
 4426        >>> g.addUnexploredEdge('A', 'up')
 4427        1
 4428        >>> g.nameFor(1)
 4429        '_u.0'
 4430        >>> g.decisionTags(1)
 4431        {'unconfirmed': 1}
 4432        >>> g.addUnexploredEdge('A', 'right', 'B')
 4433        2
 4434        >>> g.nameFor(2)
 4435        'B'
 4436        >>> g.decisionTags(2)
 4437        {'unconfirmed': 1}
 4438        >>> g.addUnexploredEdge('A', 'down', None, 'up')
 4439        3
 4440        >>> g.nameFor(3)
 4441        '_u.2'
 4442        >>> g.addUnexploredEdge(
 4443        ...    '_u.0',
 4444        ...    'beyond',
 4445        ...    toDomain='otherDomain',
 4446        ...    tags={'fast':1},
 4447        ...    revTags={'slow':1},
 4448        ...    annotations=['comment'],
 4449        ...    revAnnotations=['one', 'two'],
 4450        ...    requires=base.ReqCapability('dash'),
 4451        ...    revRequires=base.ReqCapability('super dash'),
 4452        ...    consequence=[base.effect(gain='super dash')],
 4453        ...    revConsequece=[base.effect(lose='super dash')]
 4454        ... )
 4455        4
 4456        >>> g.nameFor(4)
 4457        '_u.3'
 4458        >>> g.domainFor(4)
 4459        'otherDomain'
 4460        >>> g.transitionTags('_u.0', 'beyond')
 4461        {'fast': 1}
 4462        >>> g.transitionAnnotations('_u.0', 'beyond')
 4463        ['comment']
 4464        >>> g.getTransitionRequirement('_u.0', 'beyond')
 4465        ReqCapability('dash')
 4466        >>> e = g.getConsequence('_u.0', 'beyond')
 4467        >>> e == [base.effect(gain='super dash')]
 4468        True
 4469        >>> g.transitionTags('_u.3', 'return')
 4470        {'slow': 1}
 4471        >>> g.transitionAnnotations('_u.3', 'return')
 4472        ['one', 'two']
 4473        >>> g.getTransitionRequirement('_u.3', 'return')
 4474        ReqCapability('super dash')
 4475        >>> e = g.getConsequence('_u.3', 'return')
 4476        >>> e == [base.effect(lose='super dash')]
 4477        True
 4478        """
 4479        # Defaults
 4480        if tags is None:
 4481            tags = {}
 4482        if annotations is None:
 4483            annotations = []
 4484        if revTags is None:
 4485            revTags = {}
 4486        if revAnnotations is None:
 4487            revAnnotations = []
 4488
 4489        # Resolve ID
 4490        fromID = self.resolveDecision(fromDecision)
 4491        if toDomain is None:
 4492            toDomain = self.domainFor(fromID)
 4493
 4494        if name in self.destinationsFrom(fromID):
 4495            raise TransitionCollisionError(
 4496                f"Cannot add a new edge {name!r}:"
 4497                f" {self.identityOf(fromDecision)} already has an"
 4498                f" outgoing edge with that name."
 4499            )
 4500
 4501        if destinationName in self.nameLookup and WARN_OF_NAME_COLLISIONS:
 4502            warnings.warn(
 4503                (
 4504                    f"Cannot add a new unexplored node"
 4505                    f" {destinationName!r}: A decision with that name"
 4506                    f" already exists.\n(Leave destinationName as None"
 4507                    f" to use an automatic name.)"
 4508                ),
 4509                DecisionCollisionWarning
 4510            )
 4511
 4512        # Create the new unexplored decision and add the edge
 4513        if destinationName is None:
 4514            toName = '_u.' + str(self.unknownCount)
 4515        else:
 4516            toName = destinationName
 4517        self.unknownCount += 1
 4518        newID = self.addDecision(toName, domain=toDomain)
 4519        self.addTransition(
 4520            fromID,
 4521            name,
 4522            newID,
 4523            tags=tags,
 4524            annotations=annotations
 4525        )
 4526        self.setTransitionRequirement(fromID, name, requires)
 4527        if consequence is not None:
 4528            self.setConsequence(fromID, name, consequence)
 4529
 4530        # Add it to a zone if requested
 4531        if (
 4532            placeInZone == base.DefaultZone
 4533        and toDomain == self.domainFor(fromID)
 4534        ):
 4535            # Add to each parent of the from decision
 4536            for parent in self.zoneParents(fromID):
 4537                self.addDecisionToZone(newID, parent)
 4538        elif placeInZone is not None:
 4539            # Otherwise add it to one specific zone, creating that zone
 4540            # at level 0 if necessary
 4541            assert isinstance(placeInZone, base.Zone)
 4542            if self.getZoneInfo(placeInZone) is None:
 4543                self.createZone(placeInZone, 0)
 4544                # Add new zone to each grandparent of the from decision
 4545                for parent in self.zoneParents(fromID):
 4546                    for grandparent in self.zoneParents(parent):
 4547                        self.addZoneToZone(placeInZone, grandparent)
 4548            self.addDecisionToZone(newID, placeInZone)
 4549
 4550        # Create the reciprocal edge
 4551        if reciprocal is not None:
 4552            self.addTransition(
 4553                newID,
 4554                reciprocal,
 4555                fromID,
 4556                tags=revTags,
 4557                annotations=revAnnotations
 4558            )
 4559            self.setTransitionRequirement(newID, reciprocal, revRequires)
 4560            if revConsequece is not None:
 4561                self.setConsequence(newID, reciprocal, revConsequece)
 4562            # Set as a reciprocal
 4563            self.setReciprocal(fromID, name, reciprocal)
 4564
 4565        # Tag the destination as 'unconfirmed'
 4566        self.tagDecision(newID, 'unconfirmed')
 4567
 4568        # Return ID of new destination
 4569        return newID
 4570
 4571    def retargetTransition(
 4572        self,
 4573        fromDecision: base.AnyDecisionSpecifier,
 4574        transition: base.Transition,
 4575        newDestination: base.AnyDecisionSpecifier,
 4576        swapReciprocal=True,
 4577        errorOnNameColision=True
 4578    ) -> Optional[base.Transition]:
 4579        """
 4580        Given a particular decision and a transition at that decision,
 4581        changes that transition so that it goes to the specified new
 4582        destination instead of wherever it was connected to before. If
 4583        the new destination is the same as the old one, no changes are
 4584        made.
 4585
 4586        If `swapReciprocal` is set to True (the default) then any
 4587        reciprocal edge at the old destination will be deleted, and a
 4588        new reciprocal edge from the new destination with equivalent
 4589        properties to the original reciprocal will be created, pointing
 4590        to the origin of the specified transition. If `swapReciprocal`
 4591        is set to False, then the reciprocal relationship with any old
 4592        reciprocal edge will be removed, but the old reciprocal edge
 4593        will not be changed.
 4594
 4595        Note that if `errorOnNameColision` is True (the default), then
 4596        if the reciprocal transition has the same name as a transition
 4597        which already exists at the new destination node, a
 4598        `TransitionCollisionError` will be thrown. However, if it is set
 4599        to False, the reciprocal transition will be renamed with a suffix
 4600        to avoid any possible name collisions. Either way, the name of
 4601        the reciprocal transition (possibly just changed) will be
 4602        returned, or None if there was no reciprocal transition.
 4603
 4604        ## Example
 4605
 4606        >>> g = DecisionGraph()
 4607        >>> for fr, to, nm in [
 4608        ...     ('A', 'B', 'up'),
 4609        ...     ('A', 'B', 'up2'),
 4610        ...     ('B', 'A', 'down'),
 4611        ...     ('B', 'B', 'self'),
 4612        ...     ('B', 'C', 'next'),
 4613        ...     ('C', 'B', 'prev')
 4614        ... ]:
 4615        ...     if g.getDecision(fr) is None:
 4616        ...        g.addDecision(fr)
 4617        ...     if g.getDecision(to) is None:
 4618        ...         g.addDecision(to)
 4619        ...     g.addTransition(fr, nm, to)
 4620        0
 4621        1
 4622        2
 4623        >>> g.setReciprocal('A', 'up', 'down')
 4624        >>> g.setReciprocal('B', 'next', 'prev')
 4625        >>> g.destination('A', 'up')
 4626        1
 4627        >>> g.destination('B', 'down')
 4628        0
 4629        >>> g.retargetTransition('A', 'up', 'C')
 4630        'down'
 4631        >>> g.destination('A', 'up')
 4632        2
 4633        >>> g.getDestination('B', 'down') is None
 4634        True
 4635        >>> g.destination('C', 'down')
 4636        0
 4637        >>> g.addTransition('A', 'next', 'B')
 4638        >>> g.addTransition('B', 'prev', 'A')
 4639        >>> g.setReciprocal('A', 'next', 'prev')
 4640        >>> # Can't swap a reciprocal in a way that would collide names
 4641        >>> g.getReciprocal('C', 'prev')
 4642        'next'
 4643        >>> g.retargetTransition('C', 'prev', 'A')
 4644        Traceback (most recent call last):
 4645        ...
 4646        exploration.core.TransitionCollisionError...
 4647        >>> g.retargetTransition('C', 'prev', 'A', swapReciprocal=False)
 4648        'next'
 4649        >>> g.destination('C', 'prev')
 4650        0
 4651        >>> g.destination('A', 'next') # not changed
 4652        1
 4653        >>> # Reciprocal relationship is severed:
 4654        >>> g.getReciprocal('C', 'prev') is None
 4655        True
 4656        >>> g.getReciprocal('B', 'next') is None
 4657        True
 4658        >>> # Swap back so we can do another demo
 4659        >>> g.retargetTransition('C', 'prev', 'B', swapReciprocal=False)
 4660        >>> # Note return value was None here because there was no reciprocal
 4661        >>> g.setReciprocal('C', 'prev', 'next')
 4662        >>> # Swap reciprocal by renaming it
 4663        >>> g.retargetTransition('C', 'prev', 'A', errorOnNameColision=False)
 4664        'next.1'
 4665        >>> g.getReciprocal('C', 'prev')
 4666        'next.1'
 4667        >>> g.destination('C', 'prev')
 4668        0
 4669        >>> g.destination('A', 'next.1')
 4670        2
 4671        >>> g.destination('A', 'next')
 4672        1
 4673        >>> # Note names are the same but these are from different nodes
 4674        >>> g.getReciprocal('A', 'next')
 4675        'prev'
 4676        >>> g.getReciprocal('A', 'next.1')
 4677        'prev'
 4678        """
 4679        fromID = self.resolveDecision(fromDecision)
 4680        newDestID = self.resolveDecision(newDestination)
 4681
 4682        # Figure out the old destination of the transition we're swapping
 4683        oldDestID = self.destination(fromID, transition)
 4684        reciprocal = self.getReciprocal(fromID, transition)
 4685
 4686        # If thew new destination is the same, we don't do anything!
 4687        if oldDestID == newDestID:
 4688            return reciprocal
 4689
 4690        # First figure out reciprocal business so we can error out
 4691        # without making changes if we need to
 4692        if swapReciprocal and reciprocal is not None:
 4693            reciprocal = self.rebaseTransition(
 4694                oldDestID,
 4695                reciprocal,
 4696                newDestID,
 4697                swapReciprocal=False,
 4698                errorOnNameColision=errorOnNameColision
 4699            )
 4700
 4701        # Handle the forward transition...
 4702        # Find the transition properties
 4703        tProps = self.getTransitionProperties(fromID, transition)
 4704
 4705        # Delete the edge
 4706        self.removeEdgeByKey(fromID, transition)
 4707
 4708        # Add the new edge
 4709        self.addTransition(fromID, transition, newDestID)
 4710
 4711        # Reapply the transition properties
 4712        self.setTransitionProperties(fromID, transition, **tProps)
 4713
 4714        # Handle the reciprocal transition if there is one...
 4715        if reciprocal is not None:
 4716            if not swapReciprocal:
 4717                # Then sever the relationship, but only if that edge
 4718                # still exists (we might be in the middle of a rebase)
 4719                check = self.getDestination(oldDestID, reciprocal)
 4720                if check is not None:
 4721                    self.setReciprocal(
 4722                        oldDestID,
 4723                        reciprocal,
 4724                        None,
 4725                        setBoth=False # Other transition was deleted already
 4726                    )
 4727            else:
 4728                # Establish new reciprocal relationship
 4729                self.setReciprocal(
 4730                    fromID,
 4731                    transition,
 4732                    reciprocal
 4733                )
 4734
 4735        return reciprocal
 4736
 4737    def rebaseTransition(
 4738        self,
 4739        fromDecision: base.AnyDecisionSpecifier,
 4740        transition: base.Transition,
 4741        newBase: base.AnyDecisionSpecifier,
 4742        swapReciprocal=True,
 4743        errorOnNameColision=True
 4744    ) -> base.Transition:
 4745        """
 4746        Given a particular destination and a transition at that
 4747        destination, changes that transition's origin to a new base
 4748        decision. If the new source is the same as the old one, no
 4749        changes are made.
 4750
 4751        If `swapReciprocal` is set to True (the default) then any
 4752        reciprocal edge at the destination will be retargeted to point
 4753        to the new source so that it can remain a reciprocal. If
 4754        `swapReciprocal` is set to False, then the reciprocal
 4755        relationship with any old reciprocal edge will be removed, but
 4756        the old reciprocal edge will not be otherwise changed.
 4757
 4758        Note that if `errorOnNameColision` is True (the default), then
 4759        if the transition has the same name as a transition which
 4760        already exists at the new source node, a
 4761        `TransitionCollisionError` will be raised. However, if it is set
 4762        to False, the transition will be renamed with a suffix to avoid
 4763        any possible name collisions. Either way, the (possibly new) name
 4764        of the transition that was rebased will be returned.
 4765
 4766        ## Example
 4767
 4768        >>> g = DecisionGraph()
 4769        >>> for fr, to, nm in [
 4770        ...     ('A', 'B', 'up'),
 4771        ...     ('A', 'B', 'up2'),
 4772        ...     ('B', 'A', 'down'),
 4773        ...     ('B', 'B', 'self'),
 4774        ...     ('B', 'C', 'next'),
 4775        ...     ('C', 'B', 'prev')
 4776        ... ]:
 4777        ...     if g.getDecision(fr) is None:
 4778        ...        g.addDecision(fr)
 4779        ...     if g.getDecision(to) is None:
 4780        ...         g.addDecision(to)
 4781        ...     g.addTransition(fr, nm, to)
 4782        0
 4783        1
 4784        2
 4785        >>> g.setReciprocal('A', 'up', 'down')
 4786        >>> g.setReciprocal('B', 'next', 'prev')
 4787        >>> g.destination('A', 'up')
 4788        1
 4789        >>> g.destination('B', 'down')
 4790        0
 4791        >>> g.rebaseTransition('B', 'down', 'C')
 4792        'down'
 4793        >>> g.destination('A', 'up')
 4794        2
 4795        >>> g.getDestination('B', 'down') is None
 4796        True
 4797        >>> g.destination('C', 'down')
 4798        0
 4799        >>> g.addTransition('A', 'next', 'B')
 4800        >>> g.addTransition('B', 'prev', 'A')
 4801        >>> g.setReciprocal('A', 'next', 'prev')
 4802        >>> # Can't rebase in a way that would collide names
 4803        >>> g.rebaseTransition('B', 'next', 'A')
 4804        Traceback (most recent call last):
 4805        ...
 4806        exploration.core.TransitionCollisionError...
 4807        >>> g.rebaseTransition('B', 'next', 'A', errorOnNameColision=False)
 4808        'next.1'
 4809        >>> g.destination('C', 'prev')
 4810        0
 4811        >>> g.destination('A', 'next') # not changed
 4812        1
 4813        >>> # Collision is avoided by renaming
 4814        >>> g.destination('A', 'next.1')
 4815        2
 4816        >>> # Swap without reciprocal
 4817        >>> g.getReciprocal('A', 'next.1')
 4818        'prev'
 4819        >>> g.getReciprocal('C', 'prev')
 4820        'next.1'
 4821        >>> g.rebaseTransition('A', 'next.1', 'B', swapReciprocal=False)
 4822        'next.1'
 4823        >>> g.getReciprocal('C', 'prev') is None
 4824        True
 4825        >>> g.destination('C', 'prev')
 4826        0
 4827        >>> g.getDestination('A', 'next.1') is None
 4828        True
 4829        >>> g.destination('A', 'next')
 4830        1
 4831        >>> g.destination('B', 'next.1')
 4832        2
 4833        >>> g.getReciprocal('B', 'next.1') is None
 4834        True
 4835        >>> # Rebase in a way that creates a self-edge
 4836        >>> g.rebaseTransition('A', 'next', 'B')
 4837        'next'
 4838        >>> g.getDestination('A', 'next') is None
 4839        True
 4840        >>> g.destination('B', 'next')
 4841        1
 4842        >>> g.destination('B', 'prev') # swapped as a reciprocal
 4843        1
 4844        >>> g.getReciprocal('B', 'next') # still reciprocals
 4845        'prev'
 4846        >>> g.getReciprocal('B', 'prev')
 4847        'next'
 4848        >>> # And rebasing of a self-edge also works
 4849        >>> g.rebaseTransition('B', 'prev', 'A')
 4850        'prev'
 4851        >>> g.destination('A', 'prev')
 4852        1
 4853        >>> g.destination('B', 'next')
 4854        0
 4855        >>> g.getReciprocal('B', 'next') # still reciprocals
 4856        'prev'
 4857        >>> g.getReciprocal('A', 'prev')
 4858        'next'
 4859        >>> # We've effectively reversed this edge/reciprocal pair
 4860        >>> # by rebasing twice
 4861        """
 4862        fromID = self.resolveDecision(fromDecision)
 4863        newBaseID = self.resolveDecision(newBase)
 4864
 4865        # If thew new base is the same, we don't do anything!
 4866        if newBaseID == fromID:
 4867            return transition
 4868
 4869        # First figure out reciprocal business so we can swap it later
 4870        # without making changes if we need to
 4871        destination = self.destination(fromID, transition)
 4872        reciprocal = self.getReciprocal(fromID, transition)
 4873        # Check for an already-deleted reciprocal
 4874        if (
 4875            reciprocal is not None
 4876        and self.getDestination(destination, reciprocal) is None
 4877        ):
 4878            reciprocal = None
 4879
 4880        # Handle the base swap...
 4881        # Find the transition properties
 4882        tProps = self.getTransitionProperties(fromID, transition)
 4883
 4884        # Check for a collision
 4885        targetDestinations = self.destinationsFrom(newBaseID)
 4886        if transition in targetDestinations:
 4887            if errorOnNameColision:
 4888                raise TransitionCollisionError(
 4889                    f"Cannot rebase transition {transition!r} from"
 4890                    f" {self.identityOf(fromDecision)}: it would be a"
 4891                    f" duplicate transition name at the new base"
 4892                    f" decision {self.identityOf(newBase)}."
 4893                )
 4894            else:
 4895                # Figure out a good fresh name
 4896                newName = utils.uniqueName(
 4897                    transition,
 4898                    targetDestinations
 4899                )
 4900        else:
 4901            newName = transition
 4902
 4903        # Delete the edge
 4904        self.removeEdgeByKey(fromID, transition)
 4905
 4906        # Add the new edge
 4907        self.addTransition(newBaseID, newName, destination)
 4908
 4909        # Reapply the transition properties
 4910        self.setTransitionProperties(newBaseID, newName, **tProps)
 4911
 4912        # Handle the reciprocal transition if there is one...
 4913        if reciprocal is not None:
 4914            if not swapReciprocal:
 4915                # Then sever the relationship
 4916                self.setReciprocal(
 4917                    destination,
 4918                    reciprocal,
 4919                    None,
 4920                    setBoth=False # Other transition was deleted already
 4921                )
 4922            else:
 4923                # Otherwise swap the reciprocal edge
 4924                self.retargetTransition(
 4925                    destination,
 4926                    reciprocal,
 4927                    newBaseID,
 4928                    swapReciprocal=False
 4929                )
 4930
 4931                # And establish a new reciprocal relationship
 4932                self.setReciprocal(
 4933                    newBaseID,
 4934                    newName,
 4935                    reciprocal
 4936                )
 4937
 4938        # Return the new name in case it was changed
 4939        return newName
 4940
 4941    # TODO: zone merging!
 4942
 4943    # TODO: Double-check that exploration vars get updated when this is
 4944    # called!
 4945    def mergeDecisions(
 4946        self,
 4947        merge: base.AnyDecisionSpecifier,
 4948        mergeInto: base.AnyDecisionSpecifier,
 4949        errorOnNameColision=True
 4950    ) -> Dict[base.Transition, base.Transition]:
 4951        """
 4952        Merges two decisions, deleting the first after transferring all
 4953        of its incoming and outgoing edges to target the second one,
 4954        whose name is retained. The second decision will be added to any
 4955        zones that the first decision was a member of. If either decision
 4956        does not exist, a `MissingDecisionError` will be raised. If
 4957        `merge` and `mergeInto` are the same, then nothing will be
 4958        changed.
 4959
 4960        Unless `errorOnNameColision` is set to False, a
 4961        `TransitionCollisionError` will be raised if the two decisions
 4962        have outgoing transitions with the same name. If
 4963        `errorOnNameColision` is set to False, then such edges will be
 4964        renamed using a suffix to avoid name collisions, with edges
 4965        connected to the second decision retaining their original names
 4966        and edges that were connected to the first decision getting
 4967        renamed.
 4968
 4969        Any mechanisms located at the first decision will be moved to the
 4970        merged decision.
 4971
 4972        The tags and annotations of the merged decision are added to the
 4973        tags and annotations of the merge target. If there are shared
 4974        tags, the values from the merge target will override those of
 4975        the merged decision. If this is undesired behavior, clear/edit
 4976        the tags/annotations of the merged decision before the merge.
 4977
 4978        The 'unconfirmed' tag is treated specially: if both decisions have
 4979        it it will be retained, but otherwise it will be dropped even if
 4980        one of the situations had it before.
 4981
 4982        The domain of the second decision is retained.
 4983
 4984        Returns a dictionary mapping each original transition name to
 4985        its new name in cases where transitions get renamed; this will
 4986        be empty when no re-naming occurs, including when
 4987        `errorOnNameColision` is True. If there were any transitions
 4988        connecting the nodes that were merged, these become self-edges
 4989        of the merged node (and may be renamed if necessary).
 4990        Note that all renamed transitions were originally based on the
 4991        first (merged) node, since transitions of the second (merge
 4992        target) node are not renamed.
 4993
 4994        ## Example
 4995
 4996        >>> g = DecisionGraph()
 4997        >>> for fr, to, nm in [
 4998        ...     ('A', 'B', 'up'),
 4999        ...     ('A', 'B', 'up2'),
 5000        ...     ('B', 'A', 'down'),
 5001        ...     ('B', 'B', 'self'),
 5002        ...     ('B', 'C', 'next'),
 5003        ...     ('C', 'B', 'prev'),
 5004        ...     ('A', 'C', 'right')
 5005        ... ]:
 5006        ...     if g.getDecision(fr) is None:
 5007        ...        g.addDecision(fr)
 5008        ...     if g.getDecision(to) is None:
 5009        ...         g.addDecision(to)
 5010        ...     g.addTransition(fr, nm, to)
 5011        0
 5012        1
 5013        2
 5014        >>> g.getDestination('A', 'up')
 5015        1
 5016        >>> g.getDestination('B', 'down')
 5017        0
 5018        >>> sorted(g)
 5019        [0, 1, 2]
 5020        >>> g.setReciprocal('A', 'up', 'down')
 5021        >>> g.setReciprocal('B', 'next', 'prev')
 5022        >>> g.mergeDecisions('C', 'B')
 5023        {}
 5024        >>> g.destinationsFrom('A')
 5025        {'up': 1, 'up2': 1, 'right': 1}
 5026        >>> g.destinationsFrom('B')
 5027        {'down': 0, 'self': 1, 'prev': 1, 'next': 1}
 5028        >>> 'C' in g
 5029        False
 5030        >>> g.mergeDecisions('A', 'A') # does nothing
 5031        {}
 5032        >>> # Can't merge non-existent decision
 5033        >>> g.mergeDecisions('A', 'Z')
 5034        Traceback (most recent call last):
 5035        ...
 5036        exploration.core.MissingDecisionError...
 5037        >>> g.mergeDecisions('Z', 'A')
 5038        Traceback (most recent call last):
 5039        ...
 5040        exploration.core.MissingDecisionError...
 5041        >>> # Can't merge decisions w/ shared edge names
 5042        >>> g.addDecision('D')
 5043        3
 5044        >>> g.addTransition('D', 'next', 'A')
 5045        >>> g.addTransition('A', 'prev', 'D')
 5046        >>> g.setReciprocal('D', 'next', 'prev')
 5047        >>> g.mergeDecisions('D', 'B') # both have a 'next' transition
 5048        Traceback (most recent call last):
 5049        ...
 5050        exploration.core.TransitionCollisionError...
 5051        >>> # Auto-rename colliding edges
 5052        >>> g.mergeDecisions('D', 'B', errorOnNameColision=False)
 5053        {'next': 'next.1'}
 5054        >>> g.destination('B', 'next') # merge target unchanged
 5055        1
 5056        >>> g.destination('B', 'next.1') # merged decision name changed
 5057        0
 5058        >>> g.destination('B', 'prev') # name unchanged (no collision)
 5059        1
 5060        >>> g.getReciprocal('B', 'next') # unchanged (from B)
 5061        'prev'
 5062        >>> g.getReciprocal('B', 'next.1') # from A
 5063        'prev'
 5064        >>> g.getReciprocal('A', 'prev') # from B
 5065        'next.1'
 5066
 5067        ## Folding four nodes into a 2-node loop
 5068
 5069        >>> g = DecisionGraph()
 5070        >>> g.addDecision('X')
 5071        0
 5072        >>> g.addDecision('Y')
 5073        1
 5074        >>> g.addTransition('X', 'next', 'Y', 'prev')
 5075        >>> g.addDecision('preX')
 5076        2
 5077        >>> g.addDecision('postY')
 5078        3
 5079        >>> g.addTransition('preX', 'next', 'X', 'prev')
 5080        >>> g.addTransition('Y', 'next', 'postY', 'prev')
 5081        >>> g.mergeDecisions('preX', 'Y', errorOnNameColision=False)
 5082        {'next': 'next.1'}
 5083        >>> g.destinationsFrom('X')
 5084        {'next': 1, 'prev': 1}
 5085        >>> g.destinationsFrom('Y')
 5086        {'prev': 0, 'next': 3, 'next.1': 0}
 5087        >>> 2 in g
 5088        False
 5089        >>> g.destinationsFrom('postY')
 5090        {'prev': 1}
 5091        >>> g.mergeDecisions('postY', 'X', errorOnNameColision=False)
 5092        {'prev': 'prev.1'}
 5093        >>> g.destinationsFrom('X')
 5094        {'next': 1, 'prev': 1, 'prev.1': 1}
 5095        >>> g.destinationsFrom('Y') # order 'cause of 'next' re-target
 5096        {'prev': 0, 'next.1': 0, 'next': 0}
 5097        >>> 2 in g
 5098        False
 5099        >>> 3 in g
 5100        False
 5101        >>> # Reciprocals are tangled...
 5102        >>> g.getReciprocal(0, 'prev')
 5103        'next.1'
 5104        >>> g.getReciprocal(0, 'prev.1')
 5105        'next'
 5106        >>> g.getReciprocal(1, 'next')
 5107        'prev.1'
 5108        >>> g.getReciprocal(1, 'next.1')
 5109        'prev'
 5110        >>> # Note: one merge cannot handle both extra transitions
 5111        >>> # because their reciprocals are crossed (e.g., prev.1 <-> next)
 5112        >>> # (It would merge both edges but the result would retain
 5113        >>> # 'next.1' instead of retaining 'next'.)
 5114        >>> g.mergeTransitions('X', 'prev.1', 'prev', mergeReciprocal=False)
 5115        >>> g.mergeTransitions('Y', 'next.1', 'next', mergeReciprocal=True)
 5116        >>> g.destinationsFrom('X')
 5117        {'next': 1, 'prev': 1}
 5118        >>> g.destinationsFrom('Y')
 5119        {'prev': 0, 'next': 0}
 5120        >>> # Reciprocals were salvaged in second merger
 5121        >>> g.getReciprocal('X', 'prev')
 5122        'next'
 5123        >>> g.getReciprocal('Y', 'next')
 5124        'prev'
 5125
 5126        ## Merging with tags/requirements/annotations/consequences
 5127
 5128        >>> g = DecisionGraph()
 5129        >>> g.addDecision('X')
 5130        0
 5131        >>> g.addDecision('Y')
 5132        1
 5133        >>> g.addDecision('Z')
 5134        2
 5135        >>> g.addTransition('X', 'next', 'Y', 'prev')
 5136        >>> g.addTransition('X', 'down', 'Z', 'up')
 5137        >>> g.tagDecision('X', 'tag0', 1)
 5138        >>> g.tagDecision('Y', 'tag1', 10)
 5139        >>> g.tagDecision('Y', 'unconfirmed')
 5140        >>> g.tagDecision('Z', 'tag1', 20)
 5141        >>> g.tagDecision('Z', 'tag2', 30)
 5142        >>> g.tagTransition('X', 'next', 'ttag1', 11)
 5143        >>> g.tagTransition('Y', 'prev', 'ttag2', 22)
 5144        >>> g.tagTransition('X', 'down', 'ttag3', 33)
 5145        >>> g.tagTransition('Z', 'up', 'ttag4', 44)
 5146        >>> g.annotateDecision('Y', 'annotation 1')
 5147        >>> g.annotateDecision('Z', 'annotation 2')
 5148        >>> g.annotateDecision('Z', 'annotation 3')
 5149        >>> g.annotateTransition('Y', 'prev', 'trans annotation 1')
 5150        >>> g.annotateTransition('Y', 'prev', 'trans annotation 2')
 5151        >>> g.annotateTransition('Z', 'up', 'trans annotation 3')
 5152        >>> g.setTransitionRequirement(
 5153        ...     'X',
 5154        ...     'next',
 5155        ...     base.ReqCapability('power')
 5156        ... )
 5157        >>> g.setTransitionRequirement(
 5158        ...     'Y',
 5159        ...     'prev',
 5160        ...     base.ReqTokens('token', 1)
 5161        ... )
 5162        >>> g.setTransitionRequirement(
 5163        ...     'X',
 5164        ...     'down',
 5165        ...     base.ReqCapability('power2')
 5166        ... )
 5167        >>> g.setTransitionRequirement(
 5168        ...     'Z',
 5169        ...     'up',
 5170        ...     base.ReqTokens('token2', 2)
 5171        ... )
 5172        >>> g.setConsequence(
 5173        ...     'Y',
 5174        ...     'prev',
 5175        ...     [base.effect(gain="power2")]
 5176        ... )
 5177        >>> g.mergeDecisions('Y', 'Z')
 5178        {}
 5179        >>> g.destination('X', 'next')
 5180        2
 5181        >>> g.destination('X', 'down')
 5182        2
 5183        >>> g.destination('Z', 'prev')
 5184        0
 5185        >>> g.destination('Z', 'up')
 5186        0
 5187        >>> g.decisionTags('X')
 5188        {'tag0': 1}
 5189        >>> g.decisionTags('Z')  # note that 'unconfirmed' is removed
 5190        {'tag1': 20, 'tag2': 30}
 5191        >>> g.transitionTags('X', 'next')
 5192        {'ttag1': 11}
 5193        >>> g.transitionTags('X', 'down')
 5194        {'ttag3': 33}
 5195        >>> g.transitionTags('Z', 'prev')
 5196        {'ttag2': 22}
 5197        >>> g.transitionTags('Z', 'up')
 5198        {'ttag4': 44}
 5199        >>> g.decisionAnnotations('Z')
 5200        ['annotation 2', 'annotation 3', 'annotation 1']
 5201        >>> g.transitionAnnotations('Z', 'prev')
 5202        ['trans annotation 1', 'trans annotation 2']
 5203        >>> g.transitionAnnotations('Z', 'up')
 5204        ['trans annotation 3']
 5205        >>> g.getTransitionRequirement('X', 'next')
 5206        ReqCapability('power')
 5207        >>> g.getTransitionRequirement('Z', 'prev')
 5208        ReqTokens('token', 1)
 5209        >>> g.getTransitionRequirement('X', 'down')
 5210        ReqCapability('power2')
 5211        >>> g.getTransitionRequirement('Z', 'up')
 5212        ReqTokens('token2', 2)
 5213        >>> g.getConsequence('Z', 'prev') == [
 5214        ...     {
 5215        ...         'type': 'gain',
 5216        ...         'applyTo': 'active',
 5217        ...         'value': 'power2',
 5218        ...         'charges': None,
 5219        ...         'delay': None,
 5220        ...         'hidden': False
 5221        ...     }
 5222        ... ]
 5223        True
 5224
 5225        ## Merging into node without tags
 5226
 5227        >>> g = DecisionGraph()
 5228        >>> g.addDecision('X')
 5229        0
 5230        >>> g.addDecision('Y')
 5231        1
 5232        >>> g.tagDecision('Y', 'unconfirmed')  # special handling
 5233        >>> g.tagDecision('Y', 'tag', 'value')
 5234        >>> g.mergeDecisions('Y', 'X')
 5235        {}
 5236        >>> g.decisionTags('X')
 5237        {'tag': 'value'}
 5238        >>> 0 in g  # Second argument remains
 5239        True
 5240        >>> 1 in g  # First argument is deleted
 5241        False
 5242        """
 5243        # Resolve IDs
 5244        mergeID = self.resolveDecision(merge)
 5245        mergeIntoID = self.resolveDecision(mergeInto)
 5246
 5247        # Create our result as an empty dictionary
 5248        result: Dict[base.Transition, base.Transition] = {}
 5249
 5250        # Short-circuit if the two decisions are the same
 5251        if mergeID == mergeIntoID:
 5252            return result
 5253
 5254        # MissingDecisionErrors from here if either doesn't exist
 5255        allNewOutgoing = set(self.destinationsFrom(mergeID))
 5256        allOldOutgoing = set(self.destinationsFrom(mergeIntoID))
 5257        # Find colliding transition names
 5258        collisions = allNewOutgoing & allOldOutgoing
 5259        if len(collisions) > 0 and errorOnNameColision:
 5260            raise TransitionCollisionError(
 5261                f"Cannot merge decision {self.identityOf(merge)} into"
 5262                f" decision {self.identityOf(mergeInto)}: the decisions"
 5263                f" share {len(collisions)} transition names:"
 5264                f" {collisions}\n(Note that errorOnNameColision was set"
 5265                f" to True, set it to False to allow the operation by"
 5266                f" renaming half of those transitions.)"
 5267            )
 5268
 5269        # Record zones that will have to change after the merge
 5270        zoneParents = self.zoneParents(mergeID)
 5271
 5272        # First, swap all incoming edges, along with their reciprocals
 5273        # This will include self-edges, which will be retargeted and
 5274        # whose reciprocals will be rebased in the process, leading to
 5275        # the possibility of a missing edge during the loop
 5276        for source, incoming in self.allEdgesTo(mergeID):
 5277            # Skip this edge if it was already swapped away because it's
 5278            # a self-loop with a reciprocal whose reciprocal was
 5279            # processed earlier in the loop
 5280            if incoming not in self.destinationsFrom(source):
 5281                continue
 5282
 5283            # Find corresponding outgoing edge
 5284            outgoing = self.getReciprocal(source, incoming)
 5285
 5286            # Swap both edges to new destination
 5287            newOutgoing = self.retargetTransition(
 5288                source,
 5289                incoming,
 5290                mergeIntoID,
 5291                swapReciprocal=True,
 5292                errorOnNameColision=False # collisions were detected above
 5293            )
 5294            # Add to our result if the name of the reciprocal was
 5295            # changed
 5296            if (
 5297                outgoing is not None
 5298            and newOutgoing is not None
 5299            and outgoing != newOutgoing
 5300            ):
 5301                result[outgoing] = newOutgoing
 5302
 5303        # Next, swap any remaining outgoing edges (which didn't have
 5304        # reciprocals, or they'd already be swapped, unless they were
 5305        # self-edges previously). Note that in this loop, there can't be
 5306        # any self-edges remaining, although there might be connections
 5307        # between the merging nodes that need to become self-edges
 5308        # because they used to be a self-edge that was half-retargeted
 5309        # by the previous loop.
 5310        # Note: a copy is used here to avoid iterating over a changing
 5311        # dictionary
 5312        for stillOutgoing in copy.copy(self.destinationsFrom(mergeID)):
 5313            newOutgoing = self.rebaseTransition(
 5314                mergeID,
 5315                stillOutgoing,
 5316                mergeIntoID,
 5317                swapReciprocal=True,
 5318                errorOnNameColision=False # collisions were detected above
 5319            )
 5320            if stillOutgoing != newOutgoing:
 5321                result[stillOutgoing] = newOutgoing
 5322
 5323        # At this point, there shouldn't be any remaining incoming or
 5324        # outgoing edges!
 5325        assert self.degree(mergeID) == 0
 5326
 5327        # Merge tags & annotations
 5328        # Note that these operations affect the underlying graph
 5329        destTags = self.decisionTags(mergeIntoID)
 5330        destUnvisited = 'unconfirmed' in destTags
 5331        sourceTags = self.decisionTags(mergeID)
 5332        sourceUnvisited = 'unconfirmed' in sourceTags
 5333        # Copy over only new tags, leaving existing tags alone
 5334        for key in sourceTags:
 5335            if key not in destTags:
 5336                destTags[key] = sourceTags[key]
 5337
 5338        if int(destUnvisited) + int(sourceUnvisited) == 1:
 5339            del destTags['unconfirmed']
 5340
 5341        self.decisionAnnotations(mergeIntoID).extend(
 5342            self.decisionAnnotations(mergeID)
 5343        )
 5344
 5345        # Transfer zones
 5346        for zone in zoneParents:
 5347            self.addDecisionToZone(mergeIntoID, zone)
 5348
 5349        # Delete the old node
 5350        self.removeDecision(mergeID)
 5351
 5352        return result
 5353
 5354    def removeDecision(self, decision: base.AnyDecisionSpecifier) -> None:
 5355        """
 5356        Deletes the specified decision from the graph, updating
 5357        attendant structures like zones. Note that the ID of the deleted
 5358        node will NOT be reused, unless it's specifically provided to
 5359        `addIdentifiedDecision`.
 5360
 5361        For example:
 5362
 5363        >>> dg = DecisionGraph()
 5364        >>> dg.addDecision('A')
 5365        0
 5366        >>> dg.addDecision('B')
 5367        1
 5368        >>> list(dg)
 5369        [0, 1]
 5370        >>> 1 in dg
 5371        True
 5372        >>> 'B' in dg.nameLookup
 5373        True
 5374        >>> dg.removeDecision('B')
 5375        >>> 1 in dg
 5376        False
 5377        >>> list(dg)
 5378        [0]
 5379        >>> 'B' in dg.nameLookup
 5380        False
 5381        >>> dg.addDecision('C')  # doesn't re-use ID
 5382        2
 5383        """
 5384        dID = self.resolveDecision(decision)
 5385
 5386        # Remove the target from all zones:
 5387        for zone in self.zones:
 5388            self.removeDecisionFromZone(dID, zone)
 5389
 5390        # Remove the node but record the current name
 5391        name = self.nodes[dID]['name']
 5392        self.remove_node(dID)
 5393
 5394        # Clean up the nameLookup entry
 5395        luInfo = self.nameLookup[name]
 5396        luInfo.remove(dID)
 5397        if len(luInfo) == 0:
 5398            self.nameLookup.pop(name)
 5399
 5400        # TODO: Clean up edges?
 5401
 5402    def renameDecision(
 5403        self,
 5404        decision: base.AnyDecisionSpecifier,
 5405        newName: base.DecisionName
 5406    ):
 5407        """
 5408        Renames a decision. The decision retains its old ID.
 5409
 5410        Generates a `DecisionCollisionWarning` if a decision using the new
 5411        name already exists and `WARN_OF_NAME_COLLISIONS` is enabled.
 5412
 5413        Example:
 5414
 5415        >>> g = DecisionGraph()
 5416        >>> g.addDecision('one')
 5417        0
 5418        >>> g.addDecision('three')
 5419        1
 5420        >>> g.addTransition('one', '>', 'three')
 5421        >>> g.addTransition('three', '<', 'one')
 5422        >>> g.tagDecision('three', 'hi')
 5423        >>> g.annotateDecision('three', 'note')
 5424        >>> g.destination('one', '>')
 5425        1
 5426        >>> g.destination('three', '<')
 5427        0
 5428        >>> g.renameDecision('three', 'two')
 5429        >>> g.resolveDecision('one')
 5430        0
 5431        >>> g.resolveDecision('two')
 5432        1
 5433        >>> g.resolveDecision('three')
 5434        Traceback (most recent call last):
 5435        ...
 5436        exploration.core.MissingDecisionError...
 5437        >>> g.destination('one', '>')
 5438        1
 5439        >>> g.nameFor(1)
 5440        'two'
 5441        >>> g.getDecision('three') is None
 5442        True
 5443        >>> g.destination('two', '<')
 5444        0
 5445        >>> g.decisionTags('two')
 5446        {'hi': 1}
 5447        >>> g.decisionAnnotations('two')
 5448        ['note']
 5449        """
 5450        dID = self.resolveDecision(decision)
 5451
 5452        if newName in self.nameLookup and WARN_OF_NAME_COLLISIONS:
 5453            warnings.warn(
 5454                (
 5455                    f"Can't rename {self.identityOf(decision)} as"
 5456                    f" {newName!r} because a decision with that name"
 5457                    f" already exists."
 5458                ),
 5459                DecisionCollisionWarning
 5460            )
 5461
 5462        # Update name in node
 5463        oldName = self.nodes[dID]['name']
 5464        self.nodes[dID]['name'] = newName
 5465
 5466        # Update nameLookup entries
 5467        oldNL = self.nameLookup[oldName]
 5468        oldNL.remove(dID)
 5469        if len(oldNL) == 0:
 5470            self.nameLookup.pop(oldName)
 5471        self.nameLookup.setdefault(newName, []).append(dID)
 5472
 5473    def mergeTransitions(
 5474        self,
 5475        fromDecision: base.AnyDecisionSpecifier,
 5476        merge: base.Transition,
 5477        mergeInto: base.Transition,
 5478        mergeReciprocal=True
 5479    ) -> None:
 5480        """
 5481        Given a decision and two transitions that start at that decision,
 5482        merges the first transition into the second transition, combining
 5483        their transition properties (using `mergeProperties`) and
 5484        deleting the first transition. By default any reciprocal of the
 5485        first transition is also merged into the reciprocal of the
 5486        second, although you can set `mergeReciprocal` to `False` to
 5487        disable this in which case the old reciprocal will lose its
 5488        reciprocal relationship, even if the transition that was merged
 5489        into does not have a reciprocal.
 5490
 5491        If the two names provided are the same, nothing will happen.
 5492
 5493        If the two transitions do not share the same destination, they
 5494        cannot be merged, and an `InvalidDestinationError` will result.
 5495        Use `retargetTransition` beforehand to ensure that they do if you
 5496        want to merge transitions with different destinations.
 5497
 5498        A `MissingDecisionError` or `MissingTransitionError` will result
 5499        if the decision or either transition does not exist.
 5500
 5501        If merging reciprocal properties was requested and the first
 5502        transition does not have a reciprocal, then no reciprocal
 5503        properties change. However, if the second transition does not
 5504        have a reciprocal and the first does, the first transition's
 5505        reciprocal will be set to the reciprocal of the second
 5506        transition, and that transition will not be deleted as usual.
 5507
 5508        ## Example
 5509
 5510        >>> g = DecisionGraph()
 5511        >>> g.addDecision('A')
 5512        0
 5513        >>> g.addDecision('B')
 5514        1
 5515        >>> g.addTransition('A', 'up', 'B')
 5516        >>> g.addTransition('B', 'down', 'A')
 5517        >>> g.setReciprocal('A', 'up', 'down')
 5518        >>> # Merging a transition with no reciprocal
 5519        >>> g.addTransition('A', 'up2', 'B')
 5520        >>> g.mergeTransitions('A', 'up2', 'up')
 5521        >>> g.getDestination('A', 'up2') is None
 5522        True
 5523        >>> g.getDestination('A', 'up')
 5524        1
 5525        >>> # Merging a transition with a reciprocal & tags
 5526        >>> g.addTransition('A', 'up2', 'B')
 5527        >>> g.addTransition('B', 'down2', 'A')
 5528        >>> g.setReciprocal('A', 'up2', 'down2')
 5529        >>> g.tagTransition('A', 'up2', 'one')
 5530        >>> g.tagTransition('B', 'down2', 'two')
 5531        >>> g.mergeTransitions('B', 'down2', 'down')
 5532        >>> g.getDestination('A', 'up2') is None
 5533        True
 5534        >>> g.getDestination('A', 'up')
 5535        1
 5536        >>> g.getDestination('B', 'down2') is None
 5537        True
 5538        >>> g.getDestination('B', 'down')
 5539        0
 5540        >>> # Merging requirements uses ReqAll (i.e., 'and' logic)
 5541        >>> g.addTransition('A', 'up2', 'B')
 5542        >>> g.setTransitionProperties(
 5543        ...     'A',
 5544        ...     'up2',
 5545        ...     requirement=base.ReqCapability('dash')
 5546        ... )
 5547        >>> g.setTransitionProperties('A', 'up',
 5548        ...     requirement=base.ReqCapability('slide'))
 5549        >>> g.mergeTransitions('A', 'up2', 'up')
 5550        >>> g.getDestination('A', 'up2') is None
 5551        True
 5552        >>> repr(g.getTransitionRequirement('A', 'up'))
 5553        "ReqAll([ReqCapability('dash'), ReqCapability('slide')])"
 5554        >>> # Errors if destinations differ, or if something is missing
 5555        >>> g.mergeTransitions('A', 'down', 'up')
 5556        Traceback (most recent call last):
 5557        ...
 5558        exploration.core.MissingTransitionError...
 5559        >>> g.mergeTransitions('Z', 'one', 'two')
 5560        Traceback (most recent call last):
 5561        ...
 5562        exploration.core.MissingDecisionError...
 5563        >>> g.addDecision('C')
 5564        2
 5565        >>> g.addTransition('A', 'down', 'C')
 5566        >>> g.mergeTransitions('A', 'down', 'up')
 5567        Traceback (most recent call last):
 5568        ...
 5569        exploration.core.InvalidDestinationError...
 5570        >>> # Merging a reciprocal onto an edge that doesn't have one
 5571        >>> g.addTransition('A', 'down2', 'C')
 5572        >>> g.addTransition('C', 'up2', 'A')
 5573        >>> g.setReciprocal('A', 'down2', 'up2')
 5574        >>> g.tagTransition('C', 'up2', 'narrow')
 5575        >>> g.getReciprocal('A', 'down') is None
 5576        True
 5577        >>> g.mergeTransitions('A', 'down2', 'down')
 5578        >>> g.getDestination('A', 'down2') is None
 5579        True
 5580        >>> g.getDestination('A', 'down')
 5581        2
 5582        >>> g.getDestination('C', 'up2')
 5583        0
 5584        >>> g.getReciprocal('A', 'down')
 5585        'up2'
 5586        >>> g.getReciprocal('C', 'up2')
 5587        'down'
 5588        >>> g.transitionTags('C', 'up2')
 5589        {'narrow': 1}
 5590        >>> # Merging without a reciprocal
 5591        >>> g.addTransition('C', 'up', 'A')
 5592        >>> g.mergeTransitions('C', 'up2', 'up', mergeReciprocal=False)
 5593        >>> g.getDestination('C', 'up2') is None
 5594        True
 5595        >>> g.getDestination('C', 'up')
 5596        0
 5597        >>> g.transitionTags('C', 'up') # tag gets merged
 5598        {'narrow': 1}
 5599        >>> g.getDestination('A', 'down')
 5600        2
 5601        >>> g.getReciprocal('A', 'down') is None
 5602        True
 5603        >>> g.getReciprocal('C', 'up') is None
 5604        True
 5605        >>> # Merging w/ normal reciprocals
 5606        >>> g.addDecision('D')
 5607        3
 5608        >>> g.addDecision('E')
 5609        4
 5610        >>> g.addTransition('D', 'up', 'E', 'return')
 5611        >>> g.addTransition('E', 'down', 'D')
 5612        >>> g.mergeTransitions('E', 'return', 'down')
 5613        >>> g.getDestination('D', 'up')
 5614        4
 5615        >>> g.getDestination('E', 'down')
 5616        3
 5617        >>> g.getDestination('E', 'return') is None
 5618        True
 5619        >>> g.getReciprocal('D', 'up')
 5620        'down'
 5621        >>> g.getReciprocal('E', 'down')
 5622        'up'
 5623        >>> # Merging w/ weird reciprocals
 5624        >>> g.addTransition('E', 'return', 'D')
 5625        >>> g.setReciprocal('E', 'return', 'up', setBoth=False)
 5626        >>> g.getReciprocal('D', 'up')
 5627        'down'
 5628        >>> g.getReciprocal('E', 'down')
 5629        'up'
 5630        >>> g.getReciprocal('E', 'return') # shared
 5631        'up'
 5632        >>> g.mergeTransitions('E', 'return', 'down')
 5633        >>> g.getDestination('D', 'up')
 5634        4
 5635        >>> g.getDestination('E', 'down')
 5636        3
 5637        >>> g.getDestination('E', 'return') is None
 5638        True
 5639        >>> g.getReciprocal('D', 'up')
 5640        'down'
 5641        >>> g.getReciprocal('E', 'down')
 5642        'up'
 5643        """
 5644        fromID = self.resolveDecision(fromDecision)
 5645
 5646        # Short-circuit in the no-op case
 5647        if merge == mergeInto:
 5648            return
 5649
 5650        # These lines will raise a MissingDecisionError or
 5651        # MissingTransitionError if needed
 5652        dest1 = self.destination(fromID, merge)
 5653        dest2 = self.destination(fromID, mergeInto)
 5654
 5655        if dest1 != dest2:
 5656            raise InvalidDestinationError(
 5657                f"Cannot merge transition {merge!r} into transition"
 5658                f" {mergeInto!r} from decision"
 5659                f" {self.identityOf(fromDecision)} because their"
 5660                f" destinations are different ({self.identityOf(dest1)}"
 5661                f" and {self.identityOf(dest2)}).\nNote: you can use"
 5662                f" `retargetTransition` to change the destination of a"
 5663                f" transition."
 5664            )
 5665
 5666        # Find and the transition properties
 5667        props1 = self.getTransitionProperties(fromID, merge)
 5668        props2 = self.getTransitionProperties(fromID, mergeInto)
 5669        merged = mergeProperties(props1, props2)
 5670        # Note that this doesn't change the reciprocal:
 5671        self.setTransitionProperties(fromID, mergeInto, **merged)
 5672
 5673        # Merge the reciprocal properties if requested
 5674        # Get reciprocal to merge into
 5675        reciprocal = self.getReciprocal(fromID, mergeInto)
 5676        # Get reciprocal that needs cleaning up
 5677        altReciprocal = self.getReciprocal(fromID, merge)
 5678        # If the reciprocal to be merged actually already was the
 5679        # reciprocal to merge into, there's nothing to do here
 5680        if altReciprocal != reciprocal:
 5681            if not mergeReciprocal:
 5682                # In this case, we sever the reciprocal relationship if
 5683                # there is a reciprocal
 5684                if altReciprocal is not None:
 5685                    self.setReciprocal(dest1, altReciprocal, None)
 5686                    # By default setBoth takes care of the other half
 5687            else:
 5688                # In this case, we try to merge reciprocals
 5689                # If altReciprocal is None, we don't need to do anything
 5690                if altReciprocal is not None:
 5691                    # Was there already a reciprocal or not?
 5692                    if reciprocal is None:
 5693                        # altReciprocal becomes the new reciprocal and is
 5694                        # not deleted
 5695                        self.setReciprocal(
 5696                            fromID,
 5697                            mergeInto,
 5698                            altReciprocal
 5699                        )
 5700                    else:
 5701                        # merge reciprocal properties
 5702                        props1 = self.getTransitionProperties(
 5703                            dest1,
 5704                            altReciprocal
 5705                        )
 5706                        props2 = self.getTransitionProperties(
 5707                            dest2,
 5708                            reciprocal
 5709                        )
 5710                        merged = mergeProperties(props1, props2)
 5711                        self.setTransitionProperties(
 5712                            dest1,
 5713                            reciprocal,
 5714                            **merged
 5715                        )
 5716
 5717                        # delete the old reciprocal transition
 5718                        self.remove_edge(dest1, fromID, altReciprocal)
 5719
 5720        # Delete the old transition (reciprocal deletion/severance is
 5721        # handled above if necessary)
 5722        self.remove_edge(fromID, dest1, merge)
 5723
 5724    def isConfirmed(self, decision: base.AnyDecisionSpecifier) -> bool:
 5725        """
 5726        Returns `True` or `False` depending on whether or not the
 5727        specified decision has been confirmed. Uses the presence or
 5728        absence of the 'unconfirmed' tag to determine this.
 5729
 5730        Note: 'unconfirmed' is used instead of 'confirmed' so that large
 5731        graphs with many confirmed nodes will be smaller when saved.
 5732        """
 5733        dID = self.resolveDecision(decision)
 5734
 5735        return 'unconfirmed' not in self.nodes[dID]['tags']
 5736
 5737    def replaceUnconfirmed(
 5738        self,
 5739        fromDecision: base.AnyDecisionSpecifier,
 5740        transition: base.Transition,
 5741        connectTo: Optional[base.AnyDecisionSpecifier] = None,
 5742        reciprocal: Optional[base.Transition] = None,
 5743        requirement: Optional[base.Requirement] = None,
 5744        applyConsequence: Optional[base.Consequence] = None,
 5745        placeInZone: Optional[base.Zone] = None,
 5746        forceNew: bool = False,
 5747        tags: Optional[Dict[base.Tag, base.TagValue]] = None,
 5748        annotations: Optional[List[base.Annotation]] = None,
 5749        revRequires: Optional[base.Requirement] = None,
 5750        revConsequence: Optional[base.Consequence] = None,
 5751        revTags: Optional[Dict[base.Tag, base.TagValue]] = None,
 5752        revAnnotations: Optional[List[base.Annotation]] = None,
 5753        decisionTags: Optional[Dict[base.Tag, base.TagValue]] = None,
 5754        decisionAnnotations: Optional[List[base.Annotation]] = None
 5755    ) -> Tuple[
 5756        Dict[base.Transition, base.Transition],
 5757        Dict[base.Transition, base.Transition]
 5758    ]:
 5759        """
 5760        Given a decision and an edge name in that decision, where the
 5761        named edge leads to a decision with an unconfirmed exploration
 5762        state (see `isConfirmed`), renames the unexplored decision on
 5763        the other end of that edge using the given `connectTo` name, or
 5764        if a decision using that name already exists, merges the
 5765        unexplored decision into that decision. If `connectTo` is a
 5766        `DecisionSpecifier` whose target doesn't exist, it will be
 5767        treated as just a name, but if it's an ID and it doesn't exist,
 5768        you'll get a `MissingDecisionError`. If a `reciprocal` is provided,
 5769        a reciprocal edge will be added using that name connecting the
 5770        `connectTo` decision back to the original decision. If this
 5771        transition already exists, it must also point to a node which is
 5772        also unexplored, and which will also be merged into the
 5773        `fromDecision` node.
 5774
 5775        If `connectTo` is not given (or is set to `None` explicitly)
 5776        then the name of the unexplored decision will not be changed,
 5777        unless that name has the form `'_u.-n-'` where `-n-` is a positive
 5778        integer (i.e., the form given to automatically-named unknown
 5779        nodes). In that case, the name will be changed to `'_x.-n-'` using
 5780        the same number, or a higher number if that name is already taken.
 5781
 5782        If the destination is being renamed or if the destination's
 5783        exploration state counts as unexplored, the exploration state of
 5784        the destination will be set to 'exploring'.
 5785
 5786        If a `placeInZone` is specified, the destination will be placed
 5787        directly into that zone (even if it already existed and has zone
 5788        information), and it will be removed from any other zones it had
 5789        been a direct member of. If `placeInZone` is set to
 5790        `base.DefaultZone`, then the destination will be placed into
 5791        each zone which is a direct parent of the origin, but only if
 5792        the destination is not an already-explored existing decision AND
 5793        it is not already in any zones (in those cases no zone changes
 5794        are made). This will also remove it from any previous zones it
 5795        had been a part of. If `placeInZone` is left as `None` (the
 5796        default) no zone changes are made.
 5797
 5798        If `placeInZone` is specified and that zone didn't already exist,
 5799        it will be created as a new level-0 zone and will be added as a
 5800        sub-zone of each zone that's a direct parent of any level-0 zone
 5801        that the origin is a member of.
 5802
 5803        If `forceNew` is specified, then the destination will just be
 5804        renamed, even if another decision with the same name already
 5805        exists. It's an error to use `forceNew` with a decision ID as
 5806        the destination.
 5807
 5808        Any additional edges pointing to or from the unknown node(s)
 5809        being replaced will also be re-targeted at the now-discovered
 5810        known destination(s) if necessary. These edges will retain their
 5811        reciprocal names, or if this would cause a name clash, they will
 5812        be renamed with a suffix (see `retargetTransition`).
 5813
 5814        The return value is a pair of dictionaries mapping old names to
 5815        new ones that just includes the names which were changed. The
 5816        first dictionary contains renamed transitions that are outgoing
 5817        from the new destination node (which used to be outgoing from
 5818        the unexplored node). The second dictionary contains renamed
 5819        transitions that are outgoing from the source node (which used
 5820        to be outgoing from the unexplored node attached to the
 5821        reciprocal transition; if there was no reciprocal transition
 5822        specified then this will always be an empty dictionary).
 5823
 5824        An `ExplorationStatusError` will be raised if the destination
 5825        of the specified transition counts as visited (see
 5826        `hasBeenVisited`). An `ExplorationStatusError` will also be
 5827        raised if the `connectTo`'s `reciprocal` transition does not lead
 5828        to an unconfirmed decision (it's okay if this second transition
 5829        doesn't exist). A `TransitionCollisionError` will be raised if
 5830        the unconfirmed destination decision already has an outgoing
 5831        transition with the specified `reciprocal` which does not lead
 5832        back to the `fromDecision`.
 5833
 5834        The transition properties (requirement, consequences, tags,
 5835        and/or annotations) of the replaced transition will be copied
 5836        over to the new transition. Transition properties from the
 5837        reciprocal transition will also be copied for the newly created
 5838        reciprocal edge. Properties for any additional edges to/from the
 5839        unknown node will also be copied.
 5840
 5841        Also, any transition properties on existing forward or reciprocal
 5842        edges from the destination node with the indicated reverse name
 5843        will be merged with those from the target transition. Note that
 5844        this merging process may introduce corruption of complex
 5845        transition consequences. TODO: Fix that!
 5846
 5847        Any tags and annotations are added to copied tags/annotations,
 5848        but specified requirements, and/or consequences will replace
 5849        previous requirements/consequences, rather than being added to
 5850        them.
 5851
 5852        ## Example
 5853
 5854        >>> g = DecisionGraph()
 5855        >>> g.addDecision('A')
 5856        0
 5857        >>> g.addUnexploredEdge('A', 'up')
 5858        1
 5859        >>> g.destination('A', 'up')
 5860        1
 5861        >>> g.destination('_u.0', 'return')
 5862        0
 5863        >>> g.replaceUnconfirmed('A', 'up', 'B', 'down')
 5864        ({}, {})
 5865        >>> g.destination('A', 'up')
 5866        1
 5867        >>> g.nameFor(1)
 5868        'B'
 5869        >>> g.destination('B', 'down')
 5870        0
 5871        >>> g.getDestination('B', 'return') is None
 5872        True
 5873        >>> '_u.0' in g.nameLookup
 5874        False
 5875        >>> g.getReciprocal('A', 'up')
 5876        'down'
 5877        >>> g.getReciprocal('B', 'down')
 5878        'up'
 5879        >>> # Two unexplored edges to the same node:
 5880        >>> g.addDecision('C')
 5881        2
 5882        >>> g.addTransition('B', 'next', 'C')
 5883        >>> g.addTransition('C', 'prev', 'B')
 5884        >>> g.setReciprocal('B', 'next', 'prev')
 5885        >>> g.addUnexploredEdge('A', 'next', 'D', 'prev')
 5886        3
 5887        >>> g.addTransition('C', 'down', 'D')
 5888        >>> g.addTransition('D', 'up', 'C')
 5889        >>> g.setReciprocal('C', 'down', 'up')
 5890        >>> g.replaceUnconfirmed('C', 'down')
 5891        ({}, {})
 5892        >>> g.destination('C', 'down')
 5893        3
 5894        >>> g.destination('A', 'next')
 5895        3
 5896        >>> g.destinationsFrom('D')
 5897        {'prev': 0, 'up': 2}
 5898        >>> g.decisionTags('D')
 5899        {}
 5900        >>> # An unexplored transition which turns out to connect to a
 5901        >>> # known decision, with name collisions
 5902        >>> g.addUnexploredEdge('D', 'next', reciprocal='prev')
 5903        4
 5904        >>> g.tagDecision('_u.2', 'wet')
 5905        >>> g.addUnexploredEdge('B', 'next', reciprocal='prev') # edge taken
 5906        Traceback (most recent call last):
 5907        ...
 5908        exploration.core.TransitionCollisionError...
 5909        >>> g.addUnexploredEdge('A', 'prev', reciprocal='next')
 5910        5
 5911        >>> g.tagDecision('_u.3', 'dry')
 5912        >>> # Add transitions that will collide when merged
 5913        >>> g.addUnexploredEdge('_u.2', 'up') # collides with A/up
 5914        6
 5915        >>> g.addUnexploredEdge('_u.3', 'prev') # collides with D/prev
 5916        7
 5917        >>> g.getReciprocal('A', 'prev')
 5918        'next'
 5919        >>> g.replaceUnconfirmed('A', 'prev', 'D', 'next') # two gone
 5920        ({'prev': 'prev.1'}, {'up': 'up.1'})
 5921        >>> g.destination('A', 'prev')
 5922        3
 5923        >>> g.destination('D', 'next')
 5924        0
 5925        >>> g.getReciprocal('A', 'prev')
 5926        'next'
 5927        >>> g.getReciprocal('D', 'next')
 5928        'prev'
 5929        >>> # Note that further unexplored structures are NOT merged
 5930        >>> # even if they match against existing structures...
 5931        >>> g.destination('A', 'up.1')
 5932        6
 5933        >>> g.destination('D', 'prev.1')
 5934        7
 5935        >>> '_u.2' in g.nameLookup
 5936        False
 5937        >>> '_u.3' in g.nameLookup
 5938        False
 5939        >>> g.decisionTags('D') # tags are merged
 5940        {'dry': 1}
 5941        >>> g.decisionTags('A')
 5942        {'wet': 1}
 5943        >>> # Auto-renaming an anonymous unexplored node
 5944        >>> g.addUnexploredEdge('B', 'out')
 5945        8
 5946        >>> g.replaceUnconfirmed('B', 'out')
 5947        ({}, {})
 5948        >>> '_u.6' in g
 5949        False
 5950        >>> g.destination('B', 'out')
 5951        8
 5952        >>> g.nameFor(8)
 5953        '_x.6'
 5954        >>> g.destination('_x.6', 'return')
 5955        1
 5956        >>> # Placing a node into a zone
 5957        >>> g.addUnexploredEdge('B', 'through')
 5958        9
 5959        >>> g.getDecision('E') is None
 5960        True
 5961        >>> g.replaceUnconfirmed(
 5962        ...     'B',
 5963        ...     'through',
 5964        ...     'E',
 5965        ...     'back',
 5966        ...     placeInZone='Zone'
 5967        ... )
 5968        ({}, {})
 5969        >>> g.getDecision('E')
 5970        9
 5971        >>> g.destination('B', 'through')
 5972        9
 5973        >>> g.destination('E', 'back')
 5974        1
 5975        >>> g.zoneParents(9)
 5976        {'Zone'}
 5977        >>> g.addUnexploredEdge('E', 'farther')
 5978        10
 5979        >>> g.replaceUnconfirmed(
 5980        ...     'E',
 5981        ...     'farther',
 5982        ...     'F',
 5983        ...     'closer',
 5984        ...     placeInZone=base.DefaultZone
 5985        ... )
 5986        ({}, {})
 5987        >>> g.destination('E', 'farther')
 5988        10
 5989        >>> g.destination('F', 'closer')
 5990        9
 5991        >>> g.zoneParents(10)
 5992        {'Zone'}
 5993        >>> g.addUnexploredEdge('F', 'backwards', placeInZone='Enoz')
 5994        11
 5995        >>> g.replaceUnconfirmed(
 5996        ...     'F',
 5997        ...     'backwards',
 5998        ...     'G',
 5999        ...     'forwards',
 6000        ...     placeInZone=base.DefaultZone
 6001        ... )
 6002        ({}, {})
 6003        >>> g.destination('F', 'backwards')
 6004        11
 6005        >>> g.destination('G', 'forwards')
 6006        10
 6007        >>> g.zoneParents(11)  # not changed since it already had a zone
 6008        {'Enoz'}
 6009        >>> # TODO: forceNew example
 6010        """
 6011
 6012        # Defaults
 6013        if tags is None:
 6014            tags = {}
 6015        if annotations is None:
 6016            annotations = []
 6017        if revTags is None:
 6018            revTags = {}
 6019        if revAnnotations is None:
 6020            revAnnotations = []
 6021        if decisionTags is None:
 6022            decisionTags = {}
 6023        if decisionAnnotations is None:
 6024            decisionAnnotations = []
 6025
 6026        # Resolve source
 6027        fromID = self.resolveDecision(fromDecision)
 6028
 6029        # Figure out destination decision
 6030        oldUnexplored = self.destination(fromID, transition)
 6031        if self.isConfirmed(oldUnexplored):
 6032            raise ExplorationStatusError(
 6033                f"Transition {transition!r} from"
 6034                f" {self.identityOf(fromDecision)} does not lead to an"
 6035                f" unconfirmed decision (it leads to"
 6036                f" {self.identityOf(oldUnexplored)} which is not tagged"
 6037                f" 'unconfirmed')."
 6038            )
 6039
 6040        # Resolve destination
 6041        newName: Optional[base.DecisionName] = None
 6042        connectID: Optional[base.DecisionID] = None
 6043        if forceNew:
 6044            if isinstance(connectTo, base.DecisionID):
 6045                raise TypeError(
 6046                    f"connectTo cannot be a decision ID when forceNew"
 6047                    f" is True. Got: {self.identityOf(connectTo)}"
 6048                )
 6049            elif isinstance(connectTo, base.DecisionSpecifier):
 6050                newName = connectTo.name
 6051            elif isinstance(connectTo, base.DecisionName):
 6052                newName = connectTo
 6053            elif connectTo is None:
 6054                oldName = self.nameFor(oldUnexplored)
 6055                if (
 6056                    oldName.startswith('_u.')
 6057                and oldName[3:].isdigit()
 6058                ):
 6059                    newName = utils.uniqueName('_x.' + oldName[3:], self)
 6060                else:
 6061                    newName = oldName
 6062            else:
 6063                raise TypeError(
 6064                    f"Invalid connectTo value: {connectTo!r}"
 6065                )
 6066        elif connectTo is not None:
 6067            try:
 6068                connectID = self.resolveDecision(connectTo)
 6069                # leave newName as None
 6070            except MissingDecisionError:
 6071                if isinstance(connectTo, int):
 6072                    raise
 6073                elif isinstance(connectTo, base.DecisionSpecifier):
 6074                    newName = connectTo.name
 6075                    # The domain & zone are ignored here
 6076                else:  # Must just be a string
 6077                    assert isinstance(connectTo, str)
 6078                    newName = connectTo
 6079        else:
 6080            # If connectTo name wasn't specified, use current name of
 6081            # unknown node unless it's a default name
 6082            oldName = self.nameFor(oldUnexplored)
 6083            if (
 6084                oldName.startswith('_u.')
 6085            and oldName[3:].isdigit()
 6086            ):
 6087                newName = utils.uniqueName('_x.' + oldName[3:], self)
 6088            else:
 6089                newName = oldName
 6090
 6091        # One or the other should be valid at this point
 6092        assert connectID is not None or newName is not None
 6093
 6094        # Check that the old unknown doesn't have a reciprocal edge that
 6095        # would collide with the specified return edge
 6096        if reciprocal is not None:
 6097            revFromUnknown = self.getDestination(oldUnexplored, reciprocal)
 6098            if revFromUnknown not in (None, fromID):
 6099                raise TransitionCollisionError(
 6100                    f"Transition {reciprocal!r} from"
 6101                    f" {self.identityOf(oldUnexplored)} exists and does"
 6102                    f" not lead back to {self.identityOf(fromDecision)}"
 6103                    f" (it leads to {self.identityOf(revFromUnknown)})."
 6104                )
 6105
 6106        # Remember old reciprocal edge for future merging in case
 6107        # it's not reciprocal
 6108        oldReciprocal = self.getReciprocal(fromID, transition)
 6109
 6110        # Apply any new tags or annotations, or create a new node
 6111        needsZoneInfo = False
 6112        if connectID is not None:
 6113            # Before applying tags, check if we need to error out
 6114            # because of a reciprocal edge that points to a known
 6115            # destination:
 6116            if reciprocal is not None:
 6117                otherOldUnknown: Optional[
 6118                    base.DecisionID
 6119                ] = self.getDestination(
 6120                    connectID,
 6121                    reciprocal
 6122                )
 6123                if (
 6124                    otherOldUnknown is not None
 6125                and self.isConfirmed(otherOldUnknown)
 6126                ):
 6127                    raise ExplorationStatusError(
 6128                        f"Reciprocal transition {reciprocal!r} from"
 6129                        f" {self.identityOf(connectTo)} does not lead"
 6130                        f" to an unconfirmed decision (it leads to"
 6131                        f" {self.identityOf(otherOldUnknown)})."
 6132                    )
 6133            self.tagDecision(connectID, decisionTags)
 6134            self.annotateDecision(connectID, decisionAnnotations)
 6135            # Still needs zone info if the place we're connecting to was
 6136            # unconfirmed up until now, since unconfirmed nodes don't
 6137            # normally get zone info when they're created.
 6138            if not self.isConfirmed(connectID):
 6139                needsZoneInfo = True
 6140
 6141            # First, merge the old unknown with the connectTo node...
 6142            destRenames = self.mergeDecisions(
 6143                oldUnexplored,
 6144                connectID,
 6145                errorOnNameColision=False
 6146            )
 6147        else:
 6148            needsZoneInfo = True
 6149            if len(self.zoneParents(oldUnexplored)) > 0:
 6150                needsZoneInfo = False
 6151            assert newName is not None
 6152            self.renameDecision(oldUnexplored, newName)
 6153            connectID = oldUnexplored
 6154            # In this case there can't be an other old unknown
 6155            otherOldUnknown = None
 6156            destRenames = {}  # empty
 6157
 6158        # Check for domain mismatch to stifle zone updates:
 6159        fromDomain = self.domainFor(fromID)
 6160        if connectID is None:
 6161            destDomain = self.domainFor(oldUnexplored)
 6162        else:
 6163            destDomain = self.domainFor(connectID)
 6164
 6165        # Stifle zone updates if there's a mismatch
 6166        if fromDomain != destDomain:
 6167            needsZoneInfo = False
 6168
 6169        # Records renames that happen at the source (from node)
 6170        sourceRenames = {}  # empty for now
 6171
 6172        assert connectID is not None
 6173
 6174        # Apply the new zone if there is one
 6175        if placeInZone is not None:
 6176            if placeInZone == base.DefaultZone:
 6177                # When using DefaultZone, changes are only made for new
 6178                # destinations which don't already have any zones and
 6179                # which are in the same domain as the departing node:
 6180                # they get placed into each zone parent of the source
 6181                # decision.
 6182                if needsZoneInfo:
 6183                    # Remove destination from all current parents
 6184                    removeFrom = set(self.zoneParents(connectID))  # copy
 6185                    for parent in removeFrom:
 6186                        self.removeDecisionFromZone(connectID, parent)
 6187                    # Add it to parents of origin
 6188                    for parent in self.zoneParents(fromID):
 6189                        self.addDecisionToZone(connectID, parent)
 6190            else:
 6191                placeInZone = cast(base.Zone, placeInZone)
 6192                # Create the zone if it doesn't already exist
 6193                if self.getZoneInfo(placeInZone) is None:
 6194                    self.createZone(placeInZone, 0)
 6195                    # Add it to each grandparent of the from decision
 6196                    for parent in self.zoneParents(fromID):
 6197                        for grandparent in self.zoneParents(parent):
 6198                            self.addZoneToZone(placeInZone, grandparent)
 6199                # Remove destination from all current parents
 6200                for parent in set(self.zoneParents(connectID)):
 6201                    self.removeDecisionFromZone(connectID, parent)
 6202                # Add it to the specified zone
 6203                self.addDecisionToZone(connectID, placeInZone)
 6204
 6205        # Next, if there is a reciprocal name specified, we do more...
 6206        if reciprocal is not None:
 6207            # Figure out what kind of merging needs to happen
 6208            if otherOldUnknown is None:
 6209                if revFromUnknown is None:
 6210                    # Just create the desired reciprocal transition, which
 6211                    # we know does not already exist
 6212                    self.addTransition(connectID, reciprocal, fromID)
 6213                    otherOldReciprocal = None
 6214                else:
 6215                    # Reciprocal exists, as revFromUnknown
 6216                    otherOldReciprocal = None
 6217            else:
 6218                otherOldReciprocal = self.getReciprocal(
 6219                    connectID,
 6220                    reciprocal
 6221                )
 6222                # we need to merge otherOldUnknown into our fromDecision
 6223                sourceRenames = self.mergeDecisions(
 6224                    otherOldUnknown,
 6225                    fromID,
 6226                    errorOnNameColision=False
 6227                )
 6228                # Unvisited tag after merge only if both were
 6229
 6230            # No matter what happened we ensure the reciprocal
 6231            # relationship is set up:
 6232            self.setReciprocal(fromID, transition, reciprocal)
 6233
 6234            # Now we might need to merge some transitions:
 6235            # - Any reciprocal of the target transition should be merged
 6236            #   with reciprocal (if it was already reciprocal, that's a
 6237            #   no-op).
 6238            # - Any reciprocal of the reciprocal transition from the target
 6239            #   node (leading to otherOldUnknown) should be merged with
 6240            #   the target transition, even if it shared a name and was
 6241            #   renamed as a result.
 6242            # - If reciprocal was renamed during the initial merge, those
 6243            #   transitions should be merged.
 6244
 6245            # Merge old reciprocal into reciprocal
 6246            if oldReciprocal is not None:
 6247                oldRev = destRenames.get(oldReciprocal, oldReciprocal)
 6248                if self.getDestination(connectID, oldRev) is not None:
 6249                    # Note that we don't want to auto-merge the reciprocal,
 6250                    # which is the target transition
 6251                    self.mergeTransitions(
 6252                        connectID,
 6253                        oldRev,
 6254                        reciprocal,
 6255                        mergeReciprocal=False
 6256                    )
 6257                    # Remove it from the renames map
 6258                    if oldReciprocal in destRenames:
 6259                        del destRenames[oldReciprocal]
 6260
 6261            # Merge reciprocal reciprocal from otherOldUnknown
 6262            if otherOldReciprocal is not None:
 6263                otherOldRev = sourceRenames.get(
 6264                    otherOldReciprocal,
 6265                    otherOldReciprocal
 6266                )
 6267                # Note that the reciprocal is reciprocal, which we don't
 6268                # need to merge
 6269                self.mergeTransitions(
 6270                    fromID,
 6271                    otherOldRev,
 6272                    transition,
 6273                    mergeReciprocal=False
 6274                )
 6275                # Remove it from the renames map
 6276                if otherOldReciprocal in sourceRenames:
 6277                    del sourceRenames[otherOldReciprocal]
 6278
 6279            # Merge any renamed reciprocal onto reciprocal
 6280            if reciprocal in destRenames:
 6281                extraRev = destRenames[reciprocal]
 6282                self.mergeTransitions(
 6283                    connectID,
 6284                    extraRev,
 6285                    reciprocal,
 6286                    mergeReciprocal=False
 6287                )
 6288                # Remove it from the renames map
 6289                del destRenames[reciprocal]
 6290
 6291        # Accumulate new tags & annotations for the transitions
 6292        self.tagTransition(fromID, transition, tags)
 6293        self.annotateTransition(fromID, transition, annotations)
 6294
 6295        if reciprocal is not None:
 6296            self.tagTransition(connectID, reciprocal, revTags)
 6297            self.annotateTransition(connectID, reciprocal, revAnnotations)
 6298
 6299        # Override copied requirement/consequences for the transitions
 6300        if requirement is not None:
 6301            self.setTransitionRequirement(
 6302                fromID,
 6303                transition,
 6304                requirement
 6305            )
 6306        if applyConsequence is not None:
 6307            self.setConsequence(
 6308                fromID,
 6309                transition,
 6310                applyConsequence
 6311            )
 6312
 6313        if reciprocal is not None:
 6314            if revRequires is not None:
 6315                self.setTransitionRequirement(
 6316                    connectID,
 6317                    reciprocal,
 6318                    revRequires
 6319                )
 6320            if revConsequence is not None:
 6321                self.setConsequence(
 6322                    connectID,
 6323                    reciprocal,
 6324                    revConsequence
 6325                )
 6326
 6327        # Remove 'unconfirmed' tag if it was present
 6328        self.untagDecision(connectID, 'unconfirmed')
 6329
 6330        # Final checks
 6331        assert self.getDestination(fromDecision, transition) == connectID
 6332        useConnect: base.AnyDecisionSpecifier
 6333        useRev: Optional[str]
 6334        if connectTo is None:
 6335            useConnect = connectID
 6336        else:
 6337            useConnect = connectTo
 6338        if reciprocal is None:
 6339            useRev = self.getReciprocal(fromDecision, transition)
 6340        else:
 6341            useRev = reciprocal
 6342        if useRev is not None:
 6343            try:
 6344                assert self.getDestination(useConnect, useRev) == fromID
 6345            except AmbiguousDecisionSpecifierError:
 6346                assert self.getDestination(connectID, useRev) == fromID
 6347
 6348        # Return our final rename dictionaries
 6349        return (destRenames, sourceRenames)
 6350
 6351    def endingID(self, name: base.DecisionName) -> base.DecisionID:
 6352        """
 6353        Returns the decision ID for the ending with the specified name.
 6354        Endings are disconnected decisions in the `ENDINGS_DOMAIN`; they
 6355        don't normally include any zone information. If no ending with
 6356        the specified name already existed, then a new ending with that
 6357        name will be created and its Decision ID will be returned.
 6358
 6359        If a new decision is created, it will be tagged as unconfirmed.
 6360
 6361        Note that endings mostly aren't special: they're normal
 6362        decisions in a separate singular-focalized domain. However, some
 6363        parts of the exploration and journal machinery treat them
 6364        differently (in particular, taking certain actions via
 6365        `advanceSituation` while any decision in the `ENDINGS_DOMAIN` is
 6366        active is an error.
 6367        """
 6368        # Create our new ending decision if we need to
 6369        try:
 6370            endID = self.resolveDecision(
 6371                base.DecisionSpecifier(ENDINGS_DOMAIN, None, name)
 6372            )
 6373        except MissingDecisionError:
 6374            # Create a new decision for the ending
 6375            endID = self.addDecision(name, domain=ENDINGS_DOMAIN)
 6376            # Tag it as unconfirmed
 6377            self.tagDecision(endID, 'unconfirmed')
 6378
 6379        return endID
 6380
 6381    def triggerGroupID(self, name: base.DecisionName) -> base.DecisionID:
 6382        """
 6383        Given the name of a trigger group, returns the ID of the special
 6384        node representing that trigger group in the `TRIGGERS_DOMAIN`.
 6385        If the specified group didn't already exist, it will be created.
 6386
 6387        Trigger group decisions are not special: they just exist in a
 6388        separate spreading-focalized domain and have a few API methods to
 6389        access them, but all the normal decision-related API methods
 6390        still work. Their intended use is for sets of global triggers,
 6391        by attaching actions with the 'trigger' tag to them and then
 6392        activating or deactivating them as needed.
 6393        """
 6394        result = self.getDecision(
 6395            base.DecisionSpecifier(TRIGGERS_DOMAIN, None, name)
 6396        )
 6397        if result is None:
 6398            return self.addDecision(name, domain=TRIGGERS_DOMAIN)
 6399        else:
 6400            return result
 6401
 6402    @staticmethod
 6403    def example(which: Literal['simple', 'abc']) -> 'DecisionGraph':
 6404        """
 6405        Returns one of a number of example decision graphs, depending on
 6406        the string given. It returns a fresh copy each time. The graphs
 6407        are:
 6408
 6409        - 'simple': Three nodes named 'A', 'B', and 'C' with IDs 0, 1,
 6410            and 2, each connected to the next in the sequence by a
 6411            'next' transition with reciprocal 'prev'. In other words, a
 6412            simple little triangle. There are no tags, annotations,
 6413            requirements, consequences, mechanisms, or equivalences.
 6414        - 'abc': A more complicated 3-node setup that introduces a
 6415            little bit of everything. In this graph, we have the same
 6416            three nodes, but different transitions:
 6417
 6418                * From A you can go 'left' to B with reciprocal 'right'.
 6419                * From A you can also go 'up_left' to B with reciprocal
 6420                    'up_right'. These transitions both require the
 6421                    'grate' mechanism (which is at decision A) to be in
 6422                    state 'open'.
 6423                * From A you can go 'down' to C with reciprocal 'up'.
 6424
 6425            (In this graph, B and C are not directly connected to each
 6426            other.)
 6427
 6428            The graph has two level-0 zones 'zoneA' and 'zoneB', along
 6429            with a level-1 zone 'upZone'. Decisions A and C are in
 6430            zoneA while B is in zoneB; zoneA is in upZone, but zoneB is
 6431            not.
 6432
 6433            The decision A has annotation:
 6434
 6435                'This is a multi-word "annotation."'
 6436
 6437            The transition 'down' from A has annotation:
 6438
 6439                "Transition 'annotation.'"
 6440
 6441            Decision B has tags 'b' with value 1 and 'tag2' with value
 6442            '"value"'.
 6443
 6444            Decision C has tag 'aw"ful' with value "ha'ha'".
 6445
 6446            Transition 'up' from C has tag 'fast' with value 1.
 6447
 6448            At decision C there are actions 'grab_helmet' and
 6449            'pull_lever'.
 6450
 6451            The 'grab_helmet' transition requires that you don't have
 6452            the 'helmet' capability, and gives you that capability,
 6453            deactivating with delay 3.
 6454
 6455            The 'pull_lever' transition requires that you do have the
 6456            'helmet' capability, and takes away that capability, but it
 6457            also gives you 1 token, and if you have 2 tokens (before
 6458            getting the one extra), it sets the 'grate' mechanism (which
 6459            is a decision A) to state 'open' and deactivates.
 6460
 6461            The graph has an equivalence: having the 'helmet' capability
 6462            satisfies requirements for the 'grate' mechanism to be in the
 6463            'open' state.
 6464
 6465        """
 6466        result = DecisionGraph()
 6467        if which == 'simple':
 6468            result.addDecision('A')  # id 0
 6469            result.addDecision('B')  # id 1
 6470            result.addDecision('C')  # id 2
 6471            result.addTransition('A', 'next', 'B', 'prev')
 6472            result.addTransition('B', 'next', 'C', 'prev')
 6473            result.addTransition('C', 'next', 'A', 'prev')
 6474        elif which == 'abc':
 6475            result.addDecision('A')  # id 0
 6476            result.addDecision('B')  # id 1
 6477            result.addDecision('C')  # id 2
 6478            result.createZone('zoneA', 0)
 6479            result.createZone('zoneB', 0)
 6480            result.createZone('upZone', 1)
 6481            result.addZoneToZone('zoneA', 'upZone')
 6482            result.addDecisionToZone('A', 'zoneA')
 6483            result.addDecisionToZone('B', 'zoneB')
 6484            result.addDecisionToZone('C', 'zoneA')
 6485            result.addTransition('A', 'left', 'B', 'right')
 6486            result.addTransition('A', 'up_left', 'B', 'up_right')
 6487            result.addTransition('A', 'down', 'C', 'up')
 6488            result.setTransitionRequirement(
 6489                'A',
 6490                'up_left',
 6491                base.ReqMechanism('grate', 'open')
 6492            )
 6493            result.setTransitionRequirement(
 6494                'B',
 6495                'up_right',
 6496                base.ReqMechanism('grate', 'open')
 6497            )
 6498            result.annotateDecision('A', 'This is a multi-word "annotation."')
 6499            result.annotateTransition('A', 'down', "Transition 'annotation.'")
 6500            result.tagDecision('B', 'b')
 6501            result.tagDecision('B', 'tag2', '"value"')
 6502            result.tagDecision('C', 'aw"ful', "ha'ha")
 6503            result.tagTransition('C', 'up', 'fast')
 6504            result.addMechanism('grate', 'A')
 6505            result.addAction(
 6506                'C',
 6507                'grab_helmet',
 6508                base.ReqNot(base.ReqCapability('helmet')),
 6509                [
 6510                    base.effect(gain='helmet'),
 6511                    base.effect(deactivate=True, delay=3)
 6512                ]
 6513            )
 6514            result.addAction(
 6515                'C',
 6516                'pull_lever',
 6517                base.ReqCapability('helmet'),
 6518                [
 6519                    base.effect(lose='helmet'),
 6520                    base.effect(gain=('token', 1)),
 6521                    base.condition(
 6522                        base.ReqTokens('token', 2),
 6523                        [
 6524                            base.effect(set=('grate', 'open')),
 6525                            base.effect(deactivate=True)
 6526                        ]
 6527                    )
 6528                ]
 6529            )
 6530            result.addEquivalence(
 6531                base.ReqCapability('helmet'),
 6532                (0, 'open')
 6533            )
 6534        else:
 6535            raise ValueError(f"Invalid example name: {which!r}")
 6536
 6537        return result
 6538
 6539
 6540#---------------------------#
 6541# DiscreteExploration class #
 6542#---------------------------#
 6543
 6544def emptySituation() -> base.Situation:
 6545    """
 6546    Creates and returns an empty situation: A situation that has an
 6547    empty `DecisionGraph`, an empty `State`, a 'pending' decision type
 6548    with `None` as the action taken, no tags, and no annotations.
 6549    """
 6550    return base.Situation(
 6551        graph=DecisionGraph(),
 6552        state=base.emptyState(),
 6553        type='pending',
 6554        action=None,
 6555        saves={},
 6556        tags={},
 6557        annotations=[]
 6558    )
 6559
 6560
 6561class DiscreteExploration:
 6562    """
 6563    A list of `Situations` each of which contains a `DecisionGraph`
 6564    representing exploration over time, with `States` containing
 6565    `FocalContext` information for each step and 'taken' values for the
 6566    transition selected (at a particular decision) in that step. Each
 6567    decision graph represents a new state of the world (and/or new
 6568    knowledge about a persisting state of the world), and the 'taken'
 6569    transition in one situation transition indicates which option was
 6570    selected, or what event happened to cause update(s). Depending on the
 6571    resolution, it could represent a close record of every decision made
 6572    or a more coarse set of snapshots from gameplay with more time in
 6573    between.
 6574
 6575    The steps of the exploration can also be tagged and annotated (see
 6576    `tagStep` and `annotateStep`).
 6577
 6578    It also holds a `layouts` field that includes zero or more
 6579    `base.Layout`s by name.
 6580
 6581    When a new `DiscreteExploration` is created, it starts out with an
 6582    empty `Situation` that contains an empty `DecisionGraph`. Use the
 6583    `start` method to name the starting decision point and set things up
 6584    for other methods.
 6585
 6586    Tracking of player goals and destinations is also planned (see the
 6587    `quest`, `progress`, `complete`, `destination`, and `arrive` methods).
 6588    TODO: That
 6589    """
 6590    def __init__(self) -> None:
 6591        self.situations: List[base.Situation] = [
 6592            base.Situation(
 6593                graph=DecisionGraph(),
 6594                state=base.emptyState(),
 6595                type='pending',
 6596                action=None,
 6597                saves={},
 6598                tags={},
 6599                annotations=[]
 6600            )
 6601        ]
 6602        self.layouts: Dict[str, base.Layout] = {}
 6603
 6604    # Note: not hashable
 6605
 6606    def __eq__(self, other):
 6607        """
 6608        Equality checker. `DiscreteExploration`s can only be equal to
 6609        other `DiscreteExploration`s, not to other kinds of things.
 6610        """
 6611        if not isinstance(other, DiscreteExploration):
 6612            return False
 6613        else:
 6614            return self.situations == other.situations
 6615
 6616    @staticmethod
 6617    def fromGraph(
 6618        graph: DecisionGraph,
 6619        state: Optional[base.State] = None
 6620    ) -> 'DiscreteExploration':
 6621        """
 6622        Creates an exploration which has just a single step whose graph
 6623        is the entire specified graph, with the specified decision as
 6624        the primary decision (if any). The graph is copied, so that
 6625        changes to the exploration will not modify it. A starting state
 6626        may also be specified if desired, although if not an empty state
 6627        will be used (a provided starting state is NOT copied, but used
 6628        directly).
 6629
 6630        Example:
 6631
 6632        >>> g = DecisionGraph()
 6633        >>> g.addDecision('Room1')
 6634        0
 6635        >>> g.addDecision('Room2')
 6636        1
 6637        >>> g.addTransition('Room1', 'door', 'Room2', 'door')
 6638        >>> e = DiscreteExploration.fromGraph(g)
 6639        >>> len(e)
 6640        1
 6641        >>> e.getSituation().graph == g
 6642        True
 6643        >>> e.getActiveDecisions()
 6644        set()
 6645        >>> e.primaryDecision() is None
 6646        True
 6647        >>> e.observe('Room1', 'hatch')
 6648        2
 6649        >>> e.getSituation().graph == g
 6650        False
 6651        >>> e.getSituation().graph.destinationsFrom('Room1')
 6652        {'door': 1, 'hatch': 2}
 6653        >>> g.destinationsFrom('Room1')
 6654        {'door': 1}
 6655        """
 6656        result = DiscreteExploration()
 6657        result.situations[0] = base.Situation(
 6658            graph=copy.deepcopy(graph),
 6659            state=base.emptyState() if state is None else state,
 6660            type='pending',
 6661            action=None,
 6662            saves={},
 6663            tags={},
 6664            annotations=[]
 6665        )
 6666        return result
 6667
 6668    def __len__(self) -> int:
 6669        """
 6670        The 'length' of an exploration is the number of steps.
 6671        """
 6672        return len(self.situations)
 6673
 6674    def __getitem__(self, i: int) -> base.Situation:
 6675        """
 6676        Indexing an exploration returns the situation at that step.
 6677        """
 6678        return self.situations[i]
 6679
 6680    def __iter__(self) -> Iterator[base.Situation]:
 6681        """
 6682        Iterating over an exploration yields each `Situation` in order.
 6683        """
 6684        for i in range(len(self)):
 6685            yield self[i]
 6686
 6687    def getSituation(self, step: int = -1) -> base.Situation:
 6688        """
 6689        Returns a `base.Situation` named tuple detailing the state of
 6690        the exploration at a given step (or at the current step if no
 6691        argument is given). Note that this method works the same
 6692        way as indexing the exploration: see `__getitem__`.
 6693
 6694        Raises an `IndexError` if asked for a step that's out-of-range.
 6695        """
 6696        return self[step]
 6697
 6698    def primaryDecision(self, step: int = -1) -> Optional[base.DecisionID]:
 6699        """
 6700        Returns the current primary `base.DecisionID`, or the primary
 6701        decision from a specific step if one is specified. This may be
 6702        `None` for some steps, but mostly it's the destination of the
 6703        transition taken in the previous step.
 6704        """
 6705        return self[step].state['primaryDecision']
 6706
 6707    def effectiveCapabilities(
 6708        self,
 6709        step: int = -1
 6710    ) -> base.CapabilitySet:
 6711        """
 6712        Returns the effective capability set for the specified step
 6713        (default is the last/current step). See
 6714        `base.effectiveCapabilities`.
 6715        """
 6716        return base.effectiveCapabilitySet(self.getSituation(step).state)
 6717
 6718    def getCommonContext(
 6719        self,
 6720        step: Optional[int] = None
 6721    ) -> base.FocalContext:
 6722        """
 6723        Returns the common `FocalContext` at the specified step, or at
 6724        the current step if no argument is given. Raises an `IndexError`
 6725        if an invalid step is specified.
 6726        """
 6727        if step is None:
 6728            step = -1
 6729        state = self.getSituation(step).state
 6730        return state['common']
 6731
 6732    def getActiveContext(
 6733        self,
 6734        step: Optional[int] = None
 6735    ) -> base.FocalContext:
 6736        """
 6737        Returns the active `FocalContext` at the specified step, or at
 6738        the current step if no argument is provided. Raises an
 6739        `IndexError` if an invalid step is specified.
 6740        """
 6741        if step is None:
 6742            step = -1
 6743        state = self.getSituation(step).state
 6744        return state['contexts'][state['activeContext']]
 6745
 6746    def addFocalContext(self, name: base.FocalContextName) -> None:
 6747        """
 6748        Adds a new empty focal context to our set of focal contexts (see
 6749        `emptyFocalContext`). Use `setActiveContext` to swap to it.
 6750        Raises a `FocalContextCollisionError` if the name is already in
 6751        use.
 6752        """
 6753        contextMap = self.getSituation().state['contexts']
 6754        if name in contextMap:
 6755            raise FocalContextCollisionError(
 6756                f"Cannot add focal context {name!r}: a focal context"
 6757                f" with that name already exists."
 6758            )
 6759        contextMap[name] = base.emptyFocalContext()
 6760
 6761    def setActiveContext(self, which: base.FocalContextName) -> None:
 6762        """
 6763        Sets the active context to the named focal context, creating it
 6764        if it did not already exist (makes changes to the current
 6765        situation only). Does not add an exploration step (use
 6766        `advanceSituation` with a 'swap' action for that).
 6767        """
 6768        state = self.getSituation().state
 6769        contextMap = state['contexts']
 6770        if which not in contextMap:
 6771            self.addFocalContext(which)
 6772        state['activeContext'] = which
 6773
 6774    def createDomain(
 6775        self,
 6776        name: base.Domain,
 6777        focalization: base.DomainFocalization = 'singular',
 6778        makeActive: bool = False,
 6779        inCommon: Union[bool, Literal["both"]] = "both"
 6780    ) -> None:
 6781        """
 6782        Creates a new domain with the given focalization type, in either
 6783        the common context (`inCommon` = `True`) the active context
 6784        (`inCommon` = `False`) or both (the default; `inCommon` = 'both').
 6785        The domain's focalization will be set to the given
 6786        `focalization` value (default 'singular') and it will have no
 6787        active decisions. Raises a `DomainCollisionError` if a domain
 6788        with the specified name already exists.
 6789
 6790        Creates the domain in the current situation.
 6791
 6792        If `makeActive` is set to `True` (default is `False`) then the
 6793        domain will be made active in whichever context(s) it's created
 6794        in.
 6795        """
 6796        now = self.getSituation()
 6797        state = now.state
 6798        modify = []
 6799        if inCommon in (True, "both"):
 6800            modify.append(('common', state['common']))
 6801        if inCommon in (False, "both"):
 6802            acName = state['activeContext']
 6803            modify.append(
 6804                ('current ({repr(acName)})', state['contexts'][acName])
 6805            )
 6806
 6807        for (fcType, fc) in modify:
 6808            if name in fc['focalization']:
 6809                raise DomainCollisionError(
 6810                    f"Cannot create domain {repr(name)} because a"
 6811                    f" domain with that name already exists in the"
 6812                    f" {fcType} focal context."
 6813                )
 6814            fc['focalization'][name] = focalization
 6815            if makeActive:
 6816                fc['activeDomains'].add(name)
 6817            if focalization == "spreading":
 6818                fc['activeDecisions'][name] = set()
 6819            elif focalization == "plural":
 6820                fc['activeDecisions'][name] = {}
 6821            else:
 6822                fc['activeDecisions'][name] = None
 6823
 6824    def activateDomain(
 6825        self,
 6826        domain: base.Domain,
 6827        activate: bool = True,
 6828        inContext: base.ContextSpecifier = "active"
 6829    ) -> None:
 6830        """
 6831        Sets the given domain as active (or inactive if 'activate' is
 6832        given as `False`) in the specified context (default "active").
 6833
 6834        Modifies the current situation.
 6835        """
 6836        fc: base.FocalContext
 6837        if inContext == "active":
 6838            fc = self.getActiveContext()
 6839        elif inContext == "common":
 6840            fc = self.getCommonContext()
 6841
 6842        if activate:
 6843            fc['activeDomains'].add(domain)
 6844        else:
 6845            try:
 6846                fc['activeDomains'].remove(domain)
 6847            except KeyError:
 6848                pass
 6849
 6850    def createTriggerGroup(
 6851        self,
 6852        name: base.DecisionName
 6853    ) -> base.DecisionID:
 6854        """
 6855        Creates a new trigger group with the given name, returning the
 6856        decision ID for that trigger group. If this is the first trigger
 6857        group being created, also creates the `TRIGGERS_DOMAIN` domain
 6858        as a spreading-focalized domain that's active in the common
 6859        context (but does NOT set the created trigger group as an active
 6860        decision in that domain).
 6861
 6862        You can use 'goto' effects to activate trigger domains via
 6863        consequences, and 'retreat' effects to deactivate them.
 6864
 6865        Creating a second trigger group with the same name as another
 6866        results in a `ValueError`.
 6867
 6868        TODO: Retreat effects
 6869        """
 6870        ctx = self.getCommonContext()
 6871        if TRIGGERS_DOMAIN not in ctx['focalization']:
 6872            self.createDomain(
 6873                TRIGGERS_DOMAIN,
 6874                focalization='spreading',
 6875                makeActive=True,
 6876                inCommon=True
 6877            )
 6878
 6879        graph = self.getSituation().graph
 6880        if graph.getDecision(
 6881            base.DecisionSpecifier(TRIGGERS_DOMAIN, None, name)
 6882        ) is not None:
 6883            raise ValueError(
 6884                f"Cannot create trigger group {name!r}: a trigger group"
 6885                f" with that name already exists."
 6886            )
 6887
 6888        return self.getSituation().graph.triggerGroupID(name)
 6889
 6890    def toggleTriggerGroup(
 6891        self,
 6892        name: base.DecisionName,
 6893        setActive: Union[bool, None] = None
 6894    ):
 6895        """
 6896        Toggles whether the specified trigger group (a decision in the
 6897        `TRIGGERS_DOMAIN`) is active or not. Pass `True` or `False` as
 6898        the `setActive` argument (instead of the default `None`) to set
 6899        the state directly instead of toggling it.
 6900
 6901        Note that trigger groups are decisions in a spreading-focalized
 6902        domain, so they can be activated or deactivated by the 'goto'
 6903        and 'retreat' effects as well.
 6904
 6905        This does not affect whether the `TRIGGERS_DOMAIN` itself is
 6906        active (normally it would always be active).
 6907
 6908        Raises a `MissingDecisionError` if the specified trigger group
 6909        does not exist yet, including when the entire `TRIGGERS_DOMAIN`
 6910        does not exist. Raises a `KeyError` if the target group exists
 6911        but the `TRIGGERS_DOMAIN` has not been set up properly.
 6912        """
 6913        ctx = self.getCommonContext()
 6914        tID = self.getSituation().graph.resolveDecision(
 6915            base.DecisionSpecifier(TRIGGERS_DOMAIN, None, name)
 6916        )
 6917        activeGroups = ctx['activeDecisions'][TRIGGERS_DOMAIN]
 6918        assert isinstance(activeGroups, set)
 6919        if tID in activeGroups:
 6920            if setActive is not True:
 6921                activeGroups.remove(tID)
 6922        else:
 6923            if setActive is not False:
 6924                activeGroups.add(tID)
 6925
 6926    def getActiveDecisions(
 6927        self,
 6928        step: Optional[int] = None,
 6929        inCommon: Union[bool, Literal["both"]] = "both"
 6930    ) -> Set[base.DecisionID]:
 6931        """
 6932        Returns the set of active decisions at the given step index, or
 6933        at the current step if no step is specified. Raises an
 6934        `IndexError` if the step index is out of bounds (see `__len__`).
 6935        May return an empty set if no decisions are active.
 6936
 6937        If `inCommon` is set to "both" (the default) then decisions
 6938        active in either the common or active context are returned. Set
 6939        it to `True` or `False` to return only decisions active in the
 6940        common (when `True`) or  active (when `False`) context.
 6941        """
 6942        if step is None:
 6943            step = -1
 6944        state = self.getSituation(step).state
 6945        if inCommon == "both":
 6946            return base.combinedDecisionSet(state)
 6947        elif inCommon is True:
 6948            return base.activeDecisionSet(state['common'])
 6949        elif inCommon is False:
 6950            return base.activeDecisionSet(
 6951                state['contexts'][state['activeContext']]
 6952            )
 6953        else:
 6954            raise ValueError(
 6955                f"Invalid inCommon value {repr(inCommon)} (must be"
 6956                f" 'both', True, or False)."
 6957            )
 6958
 6959    def setActiveDecisionsAtStep(
 6960        self,
 6961        step: int,
 6962        domain: base.Domain,
 6963        activate: Union[
 6964            base.DecisionID,
 6965            Dict[base.FocalPointName, Optional[base.DecisionID]],
 6966            Set[base.DecisionID]
 6967        ],
 6968        inCommon: bool = False
 6969    ) -> None:
 6970        """
 6971        Changes the activation status of decisions in the active
 6972        `FocalContext` at the specified step, for the specified domain
 6973        (see `currentActiveContext`). Does this without adding an
 6974        exploration step, which is unusual: normally you should use
 6975        another method like `warp` to update active decisions.
 6976
 6977        Note that this does not change which domains are active, and
 6978        setting active decisions in inactive domains does not make those
 6979        decisions active overall.
 6980
 6981        Which decisions to activate or deactivate are specified as
 6982        either a single `DecisionID`, a list of them, or a set of them,
 6983        depending on the `DomainFocalization` setting in the selected
 6984        `FocalContext` for the specified domain. A `TypeError` will be
 6985        raised if the wrong kind of decision information is provided. If
 6986        the focalization context does not have any focalization value for
 6987        the domain in question, it will be set based on the kind of
 6988        active decision information specified.
 6989
 6990        A `MissingDecisionError` will be raised if a decision is
 6991        included which is not part of the current `DecisionGraph`.
 6992        The provided information will overwrite the previous active
 6993        decision information.
 6994
 6995        If `inCommon` is set to `True`, then decisions are activated or
 6996        deactivated in the common context, instead of in the active
 6997        context.
 6998
 6999        Example:
 7000
 7001        >>> e = DiscreteExploration()
 7002        >>> e.getActiveDecisions()
 7003        set()
 7004        >>> graph = e.getSituation().graph
 7005        >>> graph.addDecision('A')
 7006        0
 7007        >>> graph.addDecision('B')
 7008        1
 7009        >>> graph.addDecision('C')
 7010        2
 7011        >>> e.setActiveDecisionsAtStep(0, 'main', 0)
 7012        >>> e.getActiveDecisions()
 7013        {0}
 7014        >>> e.setActiveDecisionsAtStep(0, 'main', 1)
 7015        >>> e.getActiveDecisions()
 7016        {1}
 7017        >>> graph = e.getSituation().graph
 7018        >>> graph.addDecision('One', domain='numbers')
 7019        3
 7020        >>> graph.addDecision('Two', domain='numbers')
 7021        4
 7022        >>> graph.addDecision('Three', domain='numbers')
 7023        5
 7024        >>> graph.addDecision('Bear', domain='animals')
 7025        6
 7026        >>> graph.addDecision('Spider', domain='animals')
 7027        7
 7028        >>> graph.addDecision('Eel', domain='animals')
 7029        8
 7030        >>> ac = e.getActiveContext()
 7031        >>> ac['focalization']['numbers'] = 'plural'
 7032        >>> ac['focalization']['animals'] = 'spreading'
 7033        >>> ac['activeDecisions']['numbers'] = {'a': None, 'b': None}
 7034        >>> ac['activeDecisions']['animals'] = set()
 7035        >>> cc = e.getCommonContext()
 7036        >>> cc['focalization']['numbers'] = 'plural'
 7037        >>> cc['focalization']['animals'] = 'spreading'
 7038        >>> cc['activeDecisions']['numbers'] = {'z': None}
 7039        >>> cc['activeDecisions']['animals'] = set()
 7040        >>> e.setActiveDecisionsAtStep(0, 'numbers', {'a': 3, 'b': 3})
 7041        >>> e.getActiveDecisions()
 7042        {1}
 7043        >>> e.activateDomain('numbers')
 7044        >>> e.getActiveDecisions()
 7045        {1, 3}
 7046        >>> e.setActiveDecisionsAtStep(0, 'numbers', {'a': 4, 'b': None})
 7047        >>> e.getActiveDecisions()
 7048        {1, 4}
 7049        >>> # Wrong domain for the decision ID:
 7050        >>> e.setActiveDecisionsAtStep(0, 'main', 3)
 7051        Traceback (most recent call last):
 7052        ...
 7053        ValueError...
 7054        >>> # Wrong domain for one of the decision IDs:
 7055        >>> e.setActiveDecisionsAtStep(0, 'numbers', {'a': 2, 'b': None})
 7056        Traceback (most recent call last):
 7057        ...
 7058        ValueError...
 7059        >>> # Wrong kind of decision information provided.
 7060        >>> e.setActiveDecisionsAtStep(0, 'numbers', 3)
 7061        Traceback (most recent call last):
 7062        ...
 7063        TypeError...
 7064        >>> e.getActiveDecisions()
 7065        {1, 4}
 7066        >>> e.setActiveDecisionsAtStep(0, 'animals', {6, 7})
 7067        >>> e.getActiveDecisions()
 7068        {1, 4}
 7069        >>> e.activateDomain('animals')
 7070        >>> e.getActiveDecisions()
 7071        {1, 4, 6, 7}
 7072        >>> e.setActiveDecisionsAtStep(0, 'animals', {8})
 7073        >>> e.getActiveDecisions()
 7074        {8, 1, 4}
 7075        >>> e.setActiveDecisionsAtStep(1, 'main', 2)  # invalid step
 7076        Traceback (most recent call last):
 7077        ...
 7078        IndexError...
 7079        >>> e.setActiveDecisionsAtStep(0, 'novel', 0)  # domain mismatch
 7080        Traceback (most recent call last):
 7081        ...
 7082        ValueError...
 7083
 7084        Example of active/common contexts:
 7085
 7086        >>> e = DiscreteExploration()
 7087        >>> graph = e.getSituation().graph
 7088        >>> graph.addDecision('A')
 7089        0
 7090        >>> graph.addDecision('B')
 7091        1
 7092        >>> e.activateDomain('main', inContext="common")
 7093        >>> e.setActiveDecisionsAtStep(0, 'main', 0, inCommon=True)
 7094        >>> e.getActiveDecisions()
 7095        {0}
 7096        >>> e.setActiveDecisionsAtStep(0, 'main', None)
 7097        >>> e.getActiveDecisions()
 7098        {0}
 7099        >>> # (Still active since it's active in the common context)
 7100        >>> e.setActiveDecisionsAtStep(0, 'main', 1)
 7101        >>> e.getActiveDecisions()
 7102        {0, 1}
 7103        >>> e.setActiveDecisionsAtStep(0, 'main', 1, inCommon=True)
 7104        >>> e.getActiveDecisions()
 7105        {1}
 7106        >>> e.setActiveDecisionsAtStep(0, 'main', None, inCommon=True)
 7107        >>> e.getActiveDecisions()
 7108        {1}
 7109        >>> # (Still active since it's active in the active context)
 7110        >>> e.setActiveDecisionsAtStep(0, 'main', None)
 7111        >>> e.getActiveDecisions()
 7112        set()
 7113        """
 7114        now = self.getSituation(step)
 7115        graph = now.graph
 7116        if inCommon:
 7117            context = self.getCommonContext(step)
 7118        else:
 7119            context = self.getActiveContext(step)
 7120
 7121        defaultFocalization: base.DomainFocalization = 'singular'
 7122        if isinstance(activate, base.DecisionID):
 7123            defaultFocalization = 'singular'
 7124        elif isinstance(activate, dict):
 7125            defaultFocalization = 'plural'
 7126        elif isinstance(activate, set):
 7127            defaultFocalization = 'spreading'
 7128        elif domain not in context['focalization']:
 7129            raise TypeError(
 7130                f"Domain {domain!r} has no focalization in the"
 7131                f" {'common' if inCommon else 'active'} context,"
 7132                f" and the specified position doesn't imply one."
 7133            )
 7134
 7135        focalization = base.getDomainFocalization(
 7136            context,
 7137            domain,
 7138            defaultFocalization
 7139        )
 7140
 7141        # Check domain & existence of decision(s) in question
 7142        if activate is None:
 7143            pass
 7144        elif isinstance(activate, base.DecisionID):
 7145            if activate not in graph:
 7146                raise MissingDecisionError(
 7147                    f"There is no decision {activate} at step {step}."
 7148                )
 7149            if graph.domainFor(activate) != domain:
 7150                raise ValueError(
 7151                    f"Can't set active decisions in domain {domain!r}"
 7152                    f" to decision {graph.identityOf(activate)} because"
 7153                    f" that decision is in actually in domain"
 7154                    f" {graph.domainFor(activate)!r}."
 7155                )
 7156        elif isinstance(activate, dict):
 7157            for fpName, pos in activate.items():
 7158                if pos is None:
 7159                    continue
 7160                if pos not in graph:
 7161                    raise MissingDecisionError(
 7162                        f"There is no decision {pos} at step {step}."
 7163                    )
 7164                if graph.domainFor(pos) != domain:
 7165                    raise ValueError(
 7166                        f"Can't set active decision for focal point"
 7167                        f" {fpName!r} in domain {domain!r}"
 7168                        f" to decision {graph.identityOf(pos)} because"
 7169                        f" that decision is in actually in domain"
 7170                        f" {graph.domainFor(pos)!r}."
 7171                    )
 7172        elif isinstance(activate, set):
 7173            for pos in activate:
 7174                if pos not in graph:
 7175                    raise MissingDecisionError(
 7176                        f"There is no decision {pos} at step {step}."
 7177                    )
 7178                if graph.domainFor(pos) != domain:
 7179                    raise ValueError(
 7180                        f"Can't set {graph.identityOf(pos)} as an"
 7181                        f" active decision in domain {domain!r} to"
 7182                        f" decision because that decision is in"
 7183                        f" actually in domain {graph.domainFor(pos)!r}."
 7184                    )
 7185        else:
 7186            raise TypeError(
 7187                f"Domain {domain!r} has no focalization in the"
 7188                f" {'common' if inCommon else 'active'} context,"
 7189                f" and the specified position doesn't imply one:"
 7190                f"\n{activate!r}"
 7191            )
 7192
 7193        if focalization == 'singular':
 7194            if activate is None or isinstance(activate, base.DecisionID):
 7195                if activate is not None:
 7196                    targetDomain = graph.domainFor(activate)
 7197                    if activate not in graph:
 7198                        raise MissingDecisionError(
 7199                            f"There is no decision {activate} in the"
 7200                            f" graph at step {step}."
 7201                        )
 7202                    elif targetDomain != domain:
 7203                        raise ValueError(
 7204                            f"At step {step}, decision {activate} cannot"
 7205                            f" be the active decision for domain"
 7206                            f" {repr(domain)} because it is in a"
 7207                            f" different domain ({repr(targetDomain)})."
 7208                        )
 7209                context['activeDecisions'][domain] = activate
 7210            else:
 7211                raise TypeError(
 7212                    f"{'Common' if inCommon else 'Active'} focal"
 7213                    f" context at step {step} has {repr(focalization)}"
 7214                    f" focalization for domain {repr(domain)}, so the"
 7215                    f" active decision must be a single decision or"
 7216                    f" None.\n(You provided: {repr(activate)})"
 7217                )
 7218        elif focalization == 'plural':
 7219            if (
 7220                isinstance(activate, dict)
 7221            and all(
 7222                    isinstance(k, base.FocalPointName)
 7223                    for k in activate.keys()
 7224                )
 7225            and all(
 7226                    v is None or isinstance(v, base.DecisionID)
 7227                    for v in activate.values()
 7228                )
 7229            ):
 7230                for v in activate.values():
 7231                    if v is not None:
 7232                        targetDomain = graph.domainFor(v)
 7233                        if v not in graph:
 7234                            raise MissingDecisionError(
 7235                                f"There is no decision {v} in the graph"
 7236                                f" at step {step}."
 7237                            )
 7238                        elif targetDomain != domain:
 7239                            raise ValueError(
 7240                                f"At step {step}, decision {activate}"
 7241                                f" cannot be an active decision for"
 7242                                f" domain {repr(domain)} because it is"
 7243                                f" in a different domain"
 7244                                f" ({repr(targetDomain)})."
 7245                            )
 7246                context['activeDecisions'][domain] = activate
 7247            else:
 7248                raise TypeError(
 7249                    f"{'Common' if inCommon else 'Active'} focal"
 7250                    f" context at step {step} has {repr(focalization)}"
 7251                    f" focalization for domain {repr(domain)}, so the"
 7252                    f" active decision must be a dictionary mapping"
 7253                    f" focal point names to decision IDs (or Nones)."
 7254                    f"\n(You provided: {repr(activate)})"
 7255                )
 7256        elif focalization == 'spreading':
 7257            if (
 7258                isinstance(activate, set)
 7259            and all(isinstance(x, base.DecisionID) for x in activate)
 7260            ):
 7261                for x in activate:
 7262                    targetDomain = graph.domainFor(x)
 7263                    if x not in graph:
 7264                        raise MissingDecisionError(
 7265                            f"There is no decision {x} in the graph"
 7266                            f" at step {step}."
 7267                        )
 7268                    elif targetDomain != domain:
 7269                        raise ValueError(
 7270                            f"At step {step}, decision {activate}"
 7271                            f" cannot be an active decision for"
 7272                            f" domain {repr(domain)} because it is"
 7273                            f" in a different domain"
 7274                            f" ({repr(targetDomain)})."
 7275                        )
 7276                context['activeDecisions'][domain] = activate
 7277            else:
 7278                raise TypeError(
 7279                    f"{'Common' if inCommon else 'Active'} focal"
 7280                    f" context at step {step} has {repr(focalization)}"
 7281                    f" focalization for domain {repr(domain)}, so the"
 7282                    f" active decision must be a set of decision IDs"
 7283                    f"\n(You provided: {repr(activate)})"
 7284                )
 7285        else:
 7286            raise RuntimeError(
 7287                f"Invalid focalization value {repr(focalization)} for"
 7288                f" domain {repr(domain)} at step {step}."
 7289            )
 7290
 7291    def movementAtStep(self, step: int = -1) -> Tuple[
 7292        Union[base.DecisionID, Set[base.DecisionID], None],
 7293        Optional[base.Transition],
 7294        Union[base.DecisionID, Set[base.DecisionID], None]
 7295    ]:
 7296        """
 7297        Given a step number, returns information about the starting
 7298        decision, transition taken, and destination decision for that
 7299        step. Not all steps have all of those, so some items may be
 7300        `None`.
 7301
 7302        For steps where there is no action, where a decision is still
 7303        pending, or where the action type is 'focus', 'swap', 'focalize',
 7304        or 'revertTo', the result will be `(None, None, None)`, unless a
 7305        primary decision is available in which case the first item in the
 7306        tuple will be that decision. For 'start' actions, the starting
 7307        position and transition will be `None` (again unless the step had
 7308        a primary decision) but the destination will be the ID of the
 7309        node started at. For 'revertTo' actions, the destination will be
 7310        the primary decision of the state reverted to, if available.
 7311
 7312        Also, if the action taken has multiple potential or actual start
 7313        or end points, these may be sets of decision IDs instead of
 7314        single IDs.
 7315
 7316        Note that the primary decision of the starting state is usually
 7317        used as the from-decision, but in some cases an action dictates
 7318        taking a transition from a different decision, and this function
 7319        will return that decision as the from-decision.
 7320
 7321        TODO: Examples!
 7322
 7323        TODO: Account for bounce/follow/goto effects!!!
 7324        """
 7325        now = self.getSituation(step)
 7326        action = now.action
 7327        graph = now.graph
 7328        primary = now.state['primaryDecision']
 7329
 7330        if action is None:
 7331            return (primary, None, None)
 7332
 7333        aType = action[0]
 7334        fromID: Optional[base.DecisionID]
 7335        destID: Optional[base.DecisionID]
 7336        transition: base.Transition
 7337        outcomes: List[bool]
 7338
 7339        if aType in ('noAction', 'focus', 'swap', 'focalize'):
 7340            return (primary, None, None)
 7341        elif aType == 'start':
 7342            assert len(action) == 7
 7343            where = cast(
 7344                Union[
 7345                    base.DecisionID,
 7346                    Dict[base.FocalPointName, base.DecisionID],
 7347                    Set[base.DecisionID]
 7348                ],
 7349                action[1]
 7350            )
 7351            if isinstance(where, dict):
 7352                where = set(where.values())
 7353            return (primary, None, where)
 7354        elif aType in ('take', 'explore'):
 7355            if (
 7356                (len(action) == 4 or len(action) == 7)
 7357            and isinstance(action[2], base.DecisionID)
 7358            ):
 7359                fromID = action[2]
 7360                assert isinstance(action[3], tuple)
 7361                transition, outcomes = action[3]
 7362                if (
 7363                    action[0] == "explore"
 7364                and isinstance(action[4], base.DecisionID)
 7365                ):
 7366                    destID = action[4]
 7367                else:
 7368                    destID = graph.getDestination(fromID, transition)
 7369                return (fromID, transition, destID)
 7370            elif (
 7371                (len(action) == 3 or len(action) == 6)
 7372            and isinstance(action[1], tuple)
 7373            and isinstance(action[2], base.Transition)
 7374            and len(action[1]) == 3
 7375            and action[1][0] in get_args(base.ContextSpecifier)
 7376            and isinstance(action[1][1], base.Domain)
 7377            and isinstance(action[1][2], base.FocalPointName)
 7378            ):
 7379                fromID = base.resolvePosition(now, action[1])
 7380                if fromID is None:
 7381                    raise InvalidActionError(
 7382                        f"{aType!r} action at step {step} has position"
 7383                        f" {action[1]!r} which cannot be resolved to a"
 7384                        f" decision."
 7385                    )
 7386                transition, outcomes = action[2]
 7387                if (
 7388                    action[0] == "explore"
 7389                and isinstance(action[3], base.DecisionID)
 7390                ):
 7391                    destID = action[3]
 7392                else:
 7393                    destID = graph.getDestination(fromID, transition)
 7394                return (fromID, transition, destID)
 7395            else:
 7396                raise InvalidActionError(
 7397                    f"Malformed {aType!r} action:\n{repr(action)}"
 7398                )
 7399        elif aType == 'warp':
 7400            if len(action) != 3:
 7401                raise InvalidActionError(
 7402                    f"Malformed 'warp' action:\n{repr(action)}"
 7403                )
 7404            dest = action[2]
 7405            assert isinstance(dest, base.DecisionID)
 7406            if action[1] in get_args(base.ContextSpecifier):
 7407                # Unspecified starting point; find active decisions in
 7408                # same domain if primary is None
 7409                if primary is not None:
 7410                    return (primary, None, dest)
 7411                else:
 7412                    toDomain = now.graph.domainFor(dest)
 7413                    # TODO: Could check destination focalization here...
 7414                    active = self.getActiveDecisions(step)
 7415                    sameDomain = set(
 7416                        dID
 7417                        for dID in active
 7418                        if now.graph.domainFor(dID) == toDomain
 7419                    )
 7420                    if len(sameDomain) == 1:
 7421                        return (
 7422                            list(sameDomain)[0],
 7423                            None,
 7424                            dest
 7425                        )
 7426                    else:
 7427                        return (
 7428                            sameDomain,
 7429                            None,
 7430                            dest
 7431                        )
 7432            else:
 7433                if (
 7434                    not isinstance(action[1], tuple)
 7435                or not len(action[1]) == 3
 7436                or not action[1][0] in get_args(base.ContextSpecifier)
 7437                or not isinstance(action[1][1], base.Domain)
 7438                or not isinstance(action[1][2], base.FocalPointName)
 7439                ):
 7440                    raise InvalidActionError(
 7441                        f"Malformed 'warp' action:\n{repr(action)}"
 7442                    )
 7443                return (
 7444                    base.resolvePosition(now, action[1]),
 7445                    None,
 7446                    dest
 7447                )
 7448        elif aType == 'revertTo':
 7449            assert len(action) == 3  # type, save slot, & aspects
 7450            if primary is not None:
 7451                cameFrom = primary
 7452            nextSituation = self.getSituation(step + 1)
 7453            wentTo = nextSituation.state['primaryDecision']
 7454            return (primary, None, wentTo)
 7455        else:
 7456            raise InvalidActionError(
 7457                f"Action taken had invalid action type {repr(aType)}:"
 7458                f"\n{repr(action)}"
 7459            )
 7460
 7461    def latestStepWithDecision(
 7462        self,
 7463        dID: base.DecisionID,
 7464        startFrom: int = -1
 7465    ) -> int:
 7466        """
 7467        Scans backwards through exploration steps until it finds a graph
 7468        that contains a decision with the specified ID, and returns the
 7469        step number of that step. Instead of starting from the last step,
 7470        you can tell it to start from a different step (either positive
 7471        or negative index) via `startFrom`. Raises a
 7472        `MissingDecisionError` if there is no such step.
 7473        """
 7474        if startFrom < 0:
 7475            startFrom = len(self) + startFrom
 7476        for step in range(startFrom, -1, -1):
 7477            graph = self.getSituation(step).graph
 7478            try:
 7479                return step
 7480            except MissingDecisionError:
 7481                continue
 7482        raise MissingDecisionError(
 7483            f"Decision {dID!r} does not exist at any step of the"
 7484            f" exploration."
 7485        )
 7486
 7487    def latestDecisionInfo(self, dID: base.DecisionID) -> DecisionInfo:
 7488        """
 7489        Looks up decision info for the given decision in the latest step
 7490        in which that decision exists (which will usually be the final
 7491        exploration step, unless the decision was merged or otherwise
 7492        removed along the way). This will raise a `MissingDecisionError`
 7493        only if there is no step at which the specified decision exists.
 7494        """
 7495        for step in range(len(self) - 1, -1, -1):
 7496            graph = self.getSituation(step).graph
 7497            try:
 7498                return graph.decisionInfo(dID)
 7499            except MissingDecisionError:
 7500                continue
 7501        raise MissingDecisionError(
 7502            f"Decision {dID!r} does not exist at any step of the"
 7503            f" exploration."
 7504        )
 7505
 7506    def latestTransitionProperties(
 7507        self,
 7508        dID: base.DecisionID,
 7509        transition: base.Transition
 7510    ) -> TransitionProperties:
 7511        """
 7512        Looks up transition properties for the transition with the given
 7513        name outgoing from the decision with the given ID, in the latest
 7514        step in which a transiiton with that name from that decision
 7515        exists (which will usually be the final exploration step, unless
 7516        transitions get removed/renamed along the way). Note that because
 7517        a transition can be deleted and later added back (unlike
 7518        decisions where an ID will not be re-used), it's possible there
 7519        are two or more different transitions that meet the
 7520        specifications at different points in time, and this will always
 7521        return the properties of the last of them. This will raise a
 7522        `MissingDecisionError` if there is no step at which the specified
 7523        decision exists, and a `MissingTransitionError` if the target
 7524        decision exists at some step but never has a transition with the
 7525        specified name.
 7526        """
 7527        sawDecision: Optional[int] = None
 7528        for step in range(len(self) - 1, -1, -1):
 7529            graph = self.getSituation(step).graph
 7530            try:
 7531                return graph.getTransitionProperties(dID, transition)
 7532            except (MissingDecisionError, MissingTransitionError) as e:
 7533                if (
 7534                    sawDecision is None
 7535                and isinstance(e, MissingTransitionError)
 7536                ):
 7537                    sawDecision = step
 7538                continue
 7539        if sawDecision is None:
 7540            raise MissingDecisionError(
 7541                f"Decision {dID!r} does not exist at any step of the"
 7542                f" exploration."
 7543            )
 7544        else:
 7545            raise MissingTransitionError(
 7546                f"Decision {dID!r} does exist (last seen at step"
 7547                f" {sawDecision}) but it never has an outgoing"
 7548                f" transition named {transition!r}."
 7549            )
 7550
 7551    def tagStep(
 7552        self,
 7553        tagOrTags: Union[base.Tag, Dict[base.Tag, base.TagValue]],
 7554        tagValue: Union[
 7555            base.TagValue,
 7556            type[base.NoTagValue]
 7557        ] = base.NoTagValue,
 7558        step: int = -1
 7559    ) -> None:
 7560        """
 7561        Adds a tag (or multiple tags) to the current step, or to a
 7562        specific step if `n` is given as an integer rather than the
 7563        default `None`. A tag value should be supplied when a tag is
 7564        given (unless you want to use the default of `1`), but it's a
 7565        `ValueError` to supply a tag value when a dictionary of tags to
 7566        update is provided.
 7567        """
 7568        if isinstance(tagOrTags, base.Tag):
 7569            if tagValue is base.NoTagValue:
 7570                tagValue = 1
 7571
 7572            # Not sure why this is necessary...
 7573            tagValue = cast(base.TagValue, tagValue)
 7574
 7575            self.getSituation(step).tags.update({tagOrTags: tagValue})
 7576        else:
 7577            self.getSituation(step).tags.update(tagOrTags)
 7578
 7579    def annotateStep(
 7580        self,
 7581        annotationOrAnnotations: Union[
 7582            base.Annotation,
 7583            Sequence[base.Annotation]
 7584        ],
 7585        step: Optional[int] = None
 7586    ) -> None:
 7587        """
 7588        Adds an annotation to the current exploration step, or to a
 7589        specific step if `n` is given as an integer rather than the
 7590        default `None`.
 7591        """
 7592        if step is None:
 7593            step = -1
 7594        if isinstance(annotationOrAnnotations, base.Annotation):
 7595            self.getSituation(step).annotations.append(
 7596                annotationOrAnnotations
 7597            )
 7598        else:
 7599            self.getSituation(step).annotations.extend(
 7600                annotationOrAnnotations
 7601            )
 7602
 7603    def hasCapability(
 7604        self,
 7605        capability: base.Capability,
 7606        step: Optional[int] = None,
 7607        inCommon: Union[bool, Literal['both']] = "both"
 7608    ) -> bool:
 7609        """
 7610        Returns True if the player currently had the specified
 7611        capability, at the specified exploration step, and False
 7612        otherwise. Checks the current state if no step is given. Does
 7613        NOT return true if the game state means that the player has an
 7614        equivalent for that capability (see
 7615        `hasCapabilityOrEquivalent`).
 7616
 7617        Normally, `inCommon` is set to 'both' by default and so if
 7618        either the common `FocalContext` or the active one has the
 7619        capability, this will return `True`. `inCommon` may instead be
 7620        set to `True` or `False` to ask about just the common (or
 7621        active) focal context.
 7622        """
 7623        state = self.getSituation().state
 7624        commonCapabilities = state['common']['capabilities']\
 7625            ['capabilities']  # noqa
 7626        activeCapabilities = state['contexts'][state['activeContext']]\
 7627            ['capabilities']['capabilities']  # noqa
 7628
 7629        if inCommon == 'both':
 7630            return (
 7631                capability in commonCapabilities
 7632             or capability in activeCapabilities
 7633            )
 7634        elif inCommon is True:
 7635            return capability in commonCapabilities
 7636        elif inCommon is False:
 7637            return capability in activeCapabilities
 7638        else:
 7639            raise ValueError(
 7640                f"Invalid inCommon value (must be False, True, or"
 7641                f" 'both'; got {repr(inCommon)})."
 7642            )
 7643
 7644    def hasCapabilityOrEquivalent(
 7645        self,
 7646        capability: base.Capability,
 7647        step: Optional[int] = None,
 7648        location: Optional[Set[base.DecisionID]] = None
 7649    ) -> bool:
 7650        """
 7651        Works like `hasCapability`, but also returns `True` if the
 7652        player counts as having the specified capability via an equivalence
 7653        that's part of the current graph. As with `hasCapability`, the
 7654        optional `step` argument is used to specify which step to check,
 7655        with the current step being used as the default.
 7656
 7657        The `location` set can specify where to start looking for
 7658        mechanisms; if left unspecified active decisions for that step
 7659        will be used.
 7660        """
 7661        if step is None:
 7662            step = -1
 7663        if location is None:
 7664            location = self.getActiveDecisions(step)
 7665        situation = self.getSituation(step)
 7666        return base.hasCapabilityOrEquivalent(
 7667            capability,
 7668            base.RequirementContext(
 7669                state=situation.state,
 7670                graph=situation.graph,
 7671                searchFrom=location
 7672            )
 7673        )
 7674
 7675    def gainCapabilityNow(
 7676        self,
 7677        capability: base.Capability,
 7678        inCommon: bool = False
 7679    ) -> None:
 7680        """
 7681        Modifies the current game state to add the specified `Capability`
 7682        to the player's capabilities. No changes are made to the current
 7683        graph.
 7684
 7685        If `inCommon` is set to `True` (default is `False`) then the
 7686        capability will be added to the common `FocalContext` and will
 7687        therefore persist even when a focal context switch happens.
 7688        Normally, it will be added to the currently-active focal
 7689        context.
 7690        """
 7691        state = self.getSituation().state
 7692        if inCommon:
 7693            context = state['common']
 7694        else:
 7695            context = state['contexts'][state['activeContext']]
 7696        context['capabilities']['capabilities'].add(capability)
 7697
 7698    def loseCapabilityNow(
 7699        self,
 7700        capability: base.Capability,
 7701        inCommon: Union[bool, Literal['both']] = "both"
 7702    ) -> None:
 7703        """
 7704        Modifies the current game state to remove the specified `Capability`
 7705        from the player's capabilities. Does nothing if the player
 7706        doesn't already have that capability.
 7707
 7708        By default, this removes the capability from both the common
 7709        capabilities set and the active `FocalContext`'s capabilities
 7710        set, so that afterwards the player will definitely not have that
 7711        capability. However, if you set `inCommon` to either `True` or
 7712        `False`, it will remove the capability from just the common
 7713        capabilities set (if `True`) or just the active capabilities set
 7714        (if `False`). In these cases, removing the capability from just
 7715        one capability set will not actually remove it in terms of the
 7716        `hasCapability` result if it had been present in the other set.
 7717        Set `inCommon` to "both" to use the default behavior explicitly.
 7718        """
 7719        now = self.getSituation()
 7720        if inCommon in ("both", True):
 7721            context = now.state['common']
 7722            try:
 7723                context['capabilities']['capabilities'].remove(capability)
 7724            except KeyError:
 7725                pass
 7726        elif inCommon in ("both", False):
 7727            context = now.state['contexts'][now.state['activeContext']]
 7728            try:
 7729                context['capabilities']['capabilities'].remove(capability)
 7730            except KeyError:
 7731                pass
 7732        else:
 7733            raise ValueError(
 7734                f"Invalid inCommon value (must be False, True, or"
 7735                f" 'both'; got {repr(inCommon)})."
 7736            )
 7737
 7738    def tokenCountNow(self, tokenType: base.Token) -> Optional[int]:
 7739        """
 7740        Returns the number of tokens the player currently has of a given
 7741        type. Returns `None` if the player has never acquired or lost
 7742        tokens of that type.
 7743
 7744        This method adds together tokens from the common and active
 7745        focal contexts.
 7746        """
 7747        state = self.getSituation().state
 7748        commonContext = state['common']
 7749        activeContext = state['contexts'][state['activeContext']]
 7750        base = commonContext['capabilities']['tokens'].get(tokenType)
 7751        if base is None:
 7752            return activeContext['capabilities']['tokens'].get(tokenType)
 7753        else:
 7754            return base + activeContext['capabilities']['tokens'].get(
 7755                tokenType,
 7756                0
 7757            )
 7758
 7759    def adjustTokensNow(
 7760        self,
 7761        tokenType: base.Token,
 7762        amount: int,
 7763        inCommon: bool = False
 7764    ) -> None:
 7765        """
 7766        Modifies the current game state to add the specified number of
 7767        `Token`s of the given type to the player's tokens. No changes are
 7768        made to the current graph. Reduce the number of tokens by
 7769        supplying a negative amount; note that negative token amounts
 7770        are possible.
 7771
 7772        By default, the number of tokens for the current active
 7773        `FocalContext` will be adjusted. However, if `inCommon` is set
 7774        to `True`, then the number of tokens for the common context will
 7775        be adjusted instead.
 7776        """
 7777        # TODO: Custom token caps!
 7778        state = self.getSituation().state
 7779        if inCommon:
 7780            context = state['common']
 7781        else:
 7782            context = state['contexts'][state['activeContext']]
 7783        tokens = context['capabilities']['tokens']
 7784        tokens[tokenType] = tokens.get(tokenType, 0) + amount
 7785
 7786    def setTokensNow(
 7787        self,
 7788        tokenType: base.Token,
 7789        amount: int,
 7790        inCommon: bool = False
 7791    ) -> None:
 7792        """
 7793        Modifies the current game state to set number of `Token`s of the
 7794        given type to a specific amount, regardless of the old value. No
 7795        changes are made to the current graph.
 7796
 7797        By default this sets the number of tokens for the active
 7798        `FocalContext`. But if you set `inCommon` to `True`, it will
 7799        set the number of tokens in the common context instead.
 7800        """
 7801        # TODO: Custom token caps!
 7802        state = self.getSituation().state
 7803        if inCommon:
 7804            context = state['common']
 7805        else:
 7806            context = state['contexts'][state['activeContext']]
 7807        context['capabilities']['tokens'][tokenType] = amount
 7808
 7809    def lookupMechanism(
 7810        self,
 7811        mechanism: base.MechanismName,
 7812        step: Optional[int] = None,
 7813        where: Union[
 7814            Tuple[base.AnyDecisionSpecifier, Optional[base.Transition]],
 7815            Collection[base.AnyDecisionSpecifier],
 7816            None
 7817        ] = None
 7818    ) -> base.MechanismID:
 7819        """
 7820        Looks up a mechanism ID by name, in the graph for the specified
 7821        step. The `where` argument specifies where to start looking,
 7822        which helps disambiguate. It can be a tuple with a decision
 7823        specifier and `None` to start from a single decision, or with a
 7824        decision specifier and a transition name to start from either
 7825        end of that transition. It can also be `None` to look at global
 7826        mechanisms and then all decisions directly, although this
 7827        increases the chance of a `MechanismCollisionError`. Finally, it
 7828        can be some other non-tuple collection of decision specifiers to
 7829        start from that set.
 7830
 7831        If no step is specified, uses the current step.
 7832        """
 7833        if step is None:
 7834            step = -1
 7835        situation = self.getSituation(step)
 7836        graph = situation.graph
 7837        searchFrom: Collection[base.AnyDecisionSpecifier]
 7838        if where is None:
 7839            searchFrom = set()
 7840        elif isinstance(where, tuple):
 7841            if len(where) != 2:
 7842                raise ValueError(
 7843                    f"Mechanism lookup location was a tuple with an"
 7844                    f" invalid length (must be length-2 if it's a"
 7845                    f" tuple):\n  {repr(where)}"
 7846                )
 7847            where = cast(
 7848                Tuple[base.AnyDecisionSpecifier, Optional[base.Transition]],
 7849                where
 7850            )
 7851            if where[1] is None:
 7852                searchFrom = {graph.resolveDecision(where[0])}
 7853            else:
 7854                searchFrom = graph.bothEnds(where[0], where[1])
 7855        else:  # must be a collection of specifiers
 7856            searchFrom = cast(Collection[base.AnyDecisionSpecifier], where)
 7857        return graph.lookupMechanism(searchFrom, mechanism)
 7858
 7859    def mechanismState(
 7860        self,
 7861        mechanism: base.AnyMechanismSpecifier,
 7862        where: Optional[Set[base.DecisionID]] = None,
 7863        step: int = -1
 7864    ) -> Optional[base.MechanismState]:
 7865        """
 7866        Returns the current state for the specified mechanism (or the
 7867        state at the specified step if a step index is given). `where`
 7868        may be provided as a set of decision IDs to indicate where to
 7869        search for the named mechanism, or a mechanism ID may be provided
 7870        in the first place. Mechanism states are properties of a `State`
 7871        but are not associated with focal contexts.
 7872        """
 7873        situation = self.getSituation(step)
 7874        mID = situation.graph.resolveMechanism(mechanism, startFrom=where)
 7875        return situation.state['mechanisms'].get(
 7876            mID,
 7877            base.DEFAULT_MECHANISM_STATE
 7878        )
 7879
 7880    def setMechanismStateNow(
 7881        self,
 7882        mechanism: base.AnyMechanismSpecifier,
 7883        toState: base.MechanismState,
 7884        where: Optional[Set[base.DecisionID]] = None
 7885    ) -> None:
 7886        """
 7887        Sets the state of the specified mechanism to the specified
 7888        state. Mechanisms can only be in one state at once, so this
 7889        removes any previous states for that mechanism (note that via
 7890        equivalences multiple mechanism states can count as active).
 7891
 7892        The mechanism can be any kind of mechanism specifier (see
 7893        `base.AnyMechanismSpecifier`). If it's not a mechanism ID and
 7894        doesn't have its own position information, the 'where' argument
 7895        can be used to hint where to search for the mechanism.
 7896        """
 7897        now = self.getSituation()
 7898        mID = now.graph.resolveMechanism(mechanism, startFrom=where)
 7899        if mID is None:
 7900            raise MissingMechanismError(
 7901                f"Couldn't find mechanism for {repr(mechanism)}."
 7902            )
 7903        now.state['mechanisms'][mID] = toState
 7904
 7905    def skillLevel(
 7906        self,
 7907        skill: base.Skill,
 7908        step: Optional[int] = None
 7909    ) -> Optional[base.Level]:
 7910        """
 7911        Returns the skill level the player had in a given skill at a
 7912        given step, or for the current step if no step is specified.
 7913        Returns `None` if the player had never acquired or lost levels
 7914        in that skill before the specified step (skill level would count
 7915        as 0 in that case).
 7916
 7917        This method adds together levels from the common and active
 7918        focal contexts.
 7919        """
 7920        if step is None:
 7921            step = -1
 7922        state = self.getSituation(step).state
 7923        commonContext = state['common']
 7924        activeContext = state['contexts'][state['activeContext']]
 7925        base = commonContext['capabilities']['skills'].get(skill)
 7926        if base is None:
 7927            return activeContext['capabilities']['skills'].get(skill)
 7928        else:
 7929            return base + activeContext['capabilities']['skills'].get(
 7930                skill,
 7931                0
 7932            )
 7933
 7934    def adjustSkillLevelNow(
 7935        self,
 7936        skill: base.Skill,
 7937        levels: base.Level,
 7938        inCommon: bool = False
 7939    ) -> None:
 7940        """
 7941        Modifies the current game state to add the specified number of
 7942        `Level`s of the given skill. No changes are made to the current
 7943        graph. Reduce the skill level by supplying negative levels; note
 7944        that negative skill levels are possible.
 7945
 7946        By default, the skill level for the current active
 7947        `FocalContext` will be adjusted. However, if `inCommon` is set
 7948        to `True`, then the skill level for the common context will be
 7949        adjusted instead.
 7950        """
 7951        # TODO: Custom level caps?
 7952        state = self.getSituation().state
 7953        if inCommon:
 7954            context = state['common']
 7955        else:
 7956            context = state['contexts'][state['activeContext']]
 7957        skills = context['capabilities']['skills']
 7958        skills[skill] = skills.get(skill, 0) + levels
 7959
 7960    def setSkillLevelNow(
 7961        self,
 7962        skill: base.Skill,
 7963        level: base.Level,
 7964        inCommon: bool = False
 7965    ) -> None:
 7966        """
 7967        Modifies the current game state to set `Skill` `Level` for the
 7968        given skill, regardless of the old value. No changes are made to
 7969        the current graph.
 7970
 7971        By default this sets the skill level for the active
 7972        `FocalContext`. But if you set `inCommon` to `True`, it will set
 7973        the skill level in the common context instead.
 7974        """
 7975        # TODO: Custom level caps?
 7976        state = self.getSituation().state
 7977        if inCommon:
 7978            context = state['common']
 7979        else:
 7980            context = state['contexts'][state['activeContext']]
 7981        skills = context['capabilities']['skills']
 7982        skills[skill] = level
 7983
 7984    def updateRequirementNow(
 7985        self,
 7986        decision: base.AnyDecisionSpecifier,
 7987        transition: base.Transition,
 7988        requirement: Optional[base.Requirement]
 7989    ) -> None:
 7990        """
 7991        Updates the requirement for a specific transition in a specific
 7992        decision. Use `None` to remove the requirement for that edge.
 7993        """
 7994        if requirement is None:
 7995            requirement = base.ReqNothing()
 7996        self.getSituation().graph.setTransitionRequirement(
 7997            decision,
 7998            transition,
 7999            requirement
 8000        )
 8001
 8002    def isTraversable(
 8003        self,
 8004        decision: base.AnyDecisionSpecifier,
 8005        transition: base.Transition,
 8006        step: int = -1
 8007    ) -> bool:
 8008        """
 8009        Returns True if the specified transition from the specified
 8010        decision had its requirement satisfied by the game state at the
 8011        specified step (or at the current step if no step is specified).
 8012        Raises an `IndexError` if the specified step doesn't exist, and
 8013        a `KeyError` if the decision or transition specified does not
 8014        exist in the `DecisionGraph` at that step.
 8015        """
 8016        situation = self.getSituation(step)
 8017        req = situation.graph.getTransitionRequirement(decision, transition)
 8018        ctx = base.contextForTransition(situation, decision, transition)
 8019        fromID = situation.graph.resolveDecision(decision)
 8020        return (
 8021            req.satisfied(ctx)
 8022        and (fromID, transition) not in situation.state['deactivated']
 8023        )
 8024
 8025    def applyTransitionEffect(
 8026        self,
 8027        whichEffect: base.EffectSpecifier,
 8028        moveWhich: Optional[base.FocalPointName] = None
 8029    ) -> Optional[base.DecisionID]:
 8030        """
 8031        Applies an effect attached to a transition, taking charges and
 8032        delay into account based on the current `Situation`.
 8033        Modifies the effect's trigger count (but may not actually
 8034        trigger the effect if the charges and/or delay values indicate
 8035        not to; see `base.doTriggerEffect`).
 8036
 8037        If a specific focal point in a plural-focalized domain is
 8038        triggering the effect, the focal point name should be specified
 8039        via `moveWhich` so that goto `Effect`s can know which focal
 8040        point to move when it's not explicitly specified in the effect.
 8041        TODO: Test this!
 8042
 8043        Returns None most of the time, but if a 'goto', 'bounce', or
 8044        'follow' effect was applied, it returns the decision ID for that
 8045        effect's destination, which would override a transition's normal
 8046        destination. If it returns a destination ID, then the exploration
 8047        state will already have been updated to set the position there,
 8048        and further position updates are not needed.
 8049
 8050        Note that transition effects which update active decisions will
 8051        also update the exploration status of those decisions to
 8052        'exploring' if they had been in an unvisited status (see
 8053        `updatePosition` and `hasBeenVisited`).
 8054
 8055        Note: callers should immediately update situation-based variables
 8056        that might have been changes by a 'revert' effect.
 8057        """
 8058        now = self.getSituation()
 8059        effect, triggerCount = base.doTriggerEffect(now, whichEffect)
 8060        if triggerCount is not None:
 8061            return self.applyExtraneousEffect(
 8062                effect,
 8063                where=whichEffect[:2],
 8064                moveWhich=moveWhich
 8065            )
 8066        else:
 8067            return None
 8068
 8069    def applyExtraneousEffect(
 8070        self,
 8071        effect: base.Effect,
 8072        where: Optional[
 8073            Tuple[base.AnyDecisionSpecifier, Optional[base.Transition]]
 8074        ] = None,
 8075        moveWhich: Optional[base.FocalPointName] = None,
 8076        challengePolicy: base.ChallengePolicy = "specified"
 8077    ) -> Optional[base.DecisionID]:
 8078        """
 8079        Applies a single extraneous effect to the state & graph,
 8080        *without* accounting for charges or delay values, since the
 8081        effect is not part of the graph (use `applyTransitionEffect` to
 8082        apply effects that are attached to transitions, which is almost
 8083        always the function you should be using). An associated
 8084        transition for the extraneous effect can be supplied using the
 8085        `where` argument, and effects like 'deactivate' and 'edit' will
 8086        affect it (but the effect's charges and delay values will still
 8087        be ignored).
 8088
 8089        If the effect would change the destination of a transition, the
 8090        altered destination ID is returned: 'bounce' effects return the
 8091        provided decision part of `where`, 'goto' effects return their
 8092        target, and 'follow' effects return the destination followed to
 8093        (possibly via chained follows in the extreme case). In all other
 8094        cases, `None` is returned indicating no change to a normal
 8095        destination.
 8096
 8097        If a specific focal point in a plural-focalized domain is
 8098        triggering the effect, the focal point name should be specified
 8099        via `moveWhich` so that goto `Effect`s can know which focal
 8100        point to move when it's not explicitly specified in the effect.
 8101        TODO: Test this!
 8102
 8103        Note that transition effects which update active decisions will
 8104        also update the exploration status of those decisions to
 8105        'exploring' if they had been in an unvisited status and will
 8106        remove any 'unconfirmed' tag they might still have (see
 8107        `updatePosition` and `hasBeenVisited`).
 8108
 8109        The given `challengePolicy` is applied when traversing further
 8110        transitions due to 'follow' effects.
 8111
 8112        Note: Anyone calling `applyExtraneousEffect` should update any
 8113        situation-based variables immediately after the call, as a
 8114        'revert' effect may have changed the current graph and/or state.
 8115        """
 8116        typ = effect['type']
 8117        value = effect['value']
 8118        applyTo = effect['applyTo']
 8119        inCommon = applyTo == 'common'
 8120
 8121        now = self.getSituation()
 8122
 8123        if where is not None:
 8124            if where[1] is not None:
 8125                searchFrom = now.graph.bothEnds(where[0], where[1])
 8126            else:
 8127                searchFrom = {now.graph.resolveDecision(where[0])}
 8128        else:
 8129            searchFrom = None
 8130
 8131        # Note: Delay and charges are ignored!
 8132
 8133        if typ in ("gain", "lose"):
 8134            value = cast(
 8135                Union[
 8136                    base.Capability,
 8137                    Tuple[base.Token, base.TokenCount],
 8138                    Tuple[Literal['skill'], base.Skill, base.Level],
 8139                ],
 8140                value
 8141            )
 8142            if isinstance(value, base.Capability):
 8143                if typ == "gain":
 8144                    self.gainCapabilityNow(value, inCommon)
 8145                else:
 8146                    self.loseCapabilityNow(value, inCommon)
 8147            elif len(value) == 2:  # must be a token, amount pair
 8148                token, amount = cast(
 8149                    Tuple[base.Token, base.TokenCount],
 8150                    value
 8151                )
 8152                if typ == "lose":
 8153                    amount *= -1
 8154                self.adjustTokensNow(token, amount, inCommon)
 8155            else:  # must be a 'skill', skill, level triple
 8156                _, skill, levels = cast(
 8157                    Tuple[Literal['skill'], base.Skill, base.Level],
 8158                    value
 8159                )
 8160                if typ == "lose":
 8161                    levels *= -1
 8162                self.adjustSkillLevelNow(skill, levels, inCommon)
 8163
 8164        elif typ == "set":
 8165            value = cast(
 8166                Union[
 8167                    Tuple[base.Token, base.TokenCount],
 8168                    Tuple[base.AnyMechanismSpecifier, base.MechanismState],
 8169                    Tuple[Literal['skill'], base.Skill, base.Level],
 8170                ],
 8171                value
 8172            )
 8173            if len(value) == 2:  # must be a token or mechanism pair
 8174                if isinstance(value[1], base.TokenCount):  # token
 8175                    token, amount = cast(
 8176                        Tuple[base.Token, base.TokenCount],
 8177                        value
 8178                    )
 8179                    self.setTokensNow(token, amount, inCommon)
 8180                else: # mechanism
 8181                    mechanism, state = cast(
 8182                        Tuple[
 8183                            base.AnyMechanismSpecifier,
 8184                            base.MechanismState
 8185                        ],
 8186                        value
 8187                    )
 8188                    self.setMechanismStateNow(mechanism, state, searchFrom)
 8189            else:  # must be a 'skill', skill, level triple
 8190                _, skill, level = cast(
 8191                    Tuple[Literal['skill'], base.Skill, base.Level],
 8192                    value
 8193                )
 8194                self.setSkillLevelNow(skill, level, inCommon)
 8195
 8196        elif typ == "toggle":
 8197            # Length-1 list just toggles a capability on/off based on current
 8198            # state (not attending to equivalents):
 8199            if isinstance(value, List):  # capabilities list
 8200                value = cast(List[base.Capability], value)
 8201                if len(value) == 0:
 8202                    raise ValueError(
 8203                        "Toggle effect has empty capabilities list."
 8204                    )
 8205                if len(value) == 1:
 8206                    capability = value[0]
 8207                    if self.hasCapability(capability, inCommon=False):
 8208                        self.loseCapabilityNow(capability, inCommon=False)
 8209                    else:
 8210                        self.gainCapabilityNow(capability)
 8211                else:
 8212                    # Otherwise toggle all powers off, then one on,
 8213                    # based on the first capability that's currently on.
 8214                    # Note we do NOT count equivalences.
 8215
 8216                    # Find first capability that's on:
 8217                    firstIndex: Optional[int] = None
 8218                    for i, capability in enumerate(value):
 8219                        if self.hasCapability(capability):
 8220                            firstIndex = i
 8221                            break
 8222
 8223                    # Turn them all off:
 8224                    for capability in value:
 8225                        self.loseCapabilityNow(capability, inCommon=False)
 8226                        # TODO: inCommon for the check?
 8227
 8228                    if firstIndex is None:
 8229                        self.gainCapabilityNow(value[0])
 8230                    else:
 8231                        self.gainCapabilityNow(
 8232                            value[(firstIndex + 1) % len(value)]
 8233                        )
 8234            else:  # must be a mechanism w/ states list
 8235                mechanism, states = cast(
 8236                    Tuple[
 8237                        base.AnyMechanismSpecifier,
 8238                        List[base.MechanismState]
 8239                    ],
 8240                    value
 8241                )
 8242                currentState = self.mechanismState(mechanism, where=searchFrom)
 8243                if len(states) == 1:
 8244                    if currentState == states[0]:
 8245                        # default alternate state
 8246                        self.setMechanismStateNow(
 8247                            mechanism,
 8248                            base.DEFAULT_MECHANISM_STATE,
 8249                            searchFrom
 8250                        )
 8251                    else:
 8252                        self.setMechanismStateNow(
 8253                            mechanism,
 8254                            states[0],
 8255                            searchFrom
 8256                        )
 8257                else:
 8258                    # Find our position in the list, if any
 8259                    try:
 8260                        currentIndex = states.index(cast(str, currentState))
 8261                        # Cast here just because we know that None will
 8262                        # raise a ValueError but we'll catch it, and we
 8263                        # want to suppress the mypy warning about the
 8264                        # option
 8265                    except ValueError:
 8266                        currentIndex = len(states) - 1
 8267                    # Set next state in list as current state
 8268                    nextIndex = (currentIndex + 1) % len(states)
 8269                    self.setMechanismStateNow(
 8270                        mechanism,
 8271                        states[nextIndex],
 8272                        searchFrom
 8273                    )
 8274
 8275        elif typ == "deactivate":
 8276            if where is None or where[1] is None:
 8277                raise ValueError(
 8278                    "Can't apply a deactivate effect without specifying"
 8279                    " which transition it applies to."
 8280                )
 8281
 8282            decision, transition = cast(
 8283                Tuple[base.AnyDecisionSpecifier, base.Transition],
 8284                where
 8285            )
 8286
 8287            dID = now.graph.resolveDecision(decision)
 8288            now.state['deactivated'].add((dID, transition))
 8289
 8290        elif typ == "edit":
 8291            value = cast(List[List[commands.Command]], value)
 8292            # If there are no blocks, do nothing
 8293            if len(value) > 0:
 8294                # Apply the first block of commands and then rotate the list
 8295                scope: commands.Scope = {}
 8296                if where is not None:
 8297                    here: base.DecisionID = now.graph.resolveDecision(
 8298                        where[0]
 8299                    )
 8300                    outwards: Optional[base.Transition] = where[1]
 8301                    scope['@'] = here
 8302                    scope['@t'] = outwards
 8303                    if outwards is not None:
 8304                        reciprocal = now.graph.getReciprocal(here, outwards)
 8305                        destination = now.graph.getDestination(here, outwards)
 8306                    else:
 8307                        reciprocal = None
 8308                        destination = None
 8309                    scope['@r'] = reciprocal
 8310                    scope['@d'] = destination
 8311                self.runCommandBlock(value[0], scope)
 8312                value.append(value.pop(0))
 8313
 8314        elif typ == "goto":
 8315            if isinstance(value, base.DecisionSpecifier):
 8316                target: base.AnyDecisionSpecifier = value
 8317                # use moveWhich provided as argument
 8318            elif isinstance(value, tuple):
 8319                target, moveWhich = cast(
 8320                    Tuple[base.AnyDecisionSpecifier, base.FocalPointName],
 8321                    value
 8322                )
 8323            else:
 8324                target = cast(base.AnyDecisionSpecifier, value)
 8325                # use moveWhich provided as argument
 8326
 8327            destID = now.graph.resolveDecision(target)
 8328            base.updatePosition(now, destID, applyTo, moveWhich)
 8329            return destID
 8330
 8331        elif typ == "bounce":
 8332            # Just need to let the caller know they should cancel
 8333            if where is None:
 8334                raise ValueError(
 8335                    "Can't apply a 'bounce' effect without a position"
 8336                    " to apply it from."
 8337                )
 8338            return now.graph.resolveDecision(where[0])
 8339
 8340        elif typ == "follow":
 8341            if where is None:
 8342                raise ValueError(
 8343                    f"Can't follow transition {value!r} because there"
 8344                    f" is no position information when applying the"
 8345                    f" effect."
 8346                )
 8347            if where[1] is not None:
 8348                followFrom = now.graph.getDestination(where[0], where[1])
 8349                if followFrom is None:
 8350                    raise ValueError(
 8351                        f"Can't follow transition {value!r} because the"
 8352                        f" position information specifies transition"
 8353                        f" {where[1]!r} from decision"
 8354                        f" {now.graph.identityOf(where[0])} but that"
 8355                        f" transition does not exist."
 8356                    )
 8357            else:
 8358                followFrom = now.graph.resolveDecision(where[0])
 8359
 8360            following = cast(base.Transition, value)
 8361
 8362            followTo = now.graph.getDestination(followFrom, following)
 8363
 8364            if followTo is None:
 8365                raise ValueError(
 8366                    f"Can't follow transition {following!r} because"
 8367                    f" that transition doesn't exist at the specified"
 8368                    f" destination {now.graph.identityOf(followFrom)}."
 8369                )
 8370
 8371            if self.isTraversable(followFrom, following):  # skip if not
 8372                # Perform initial position update before following new
 8373                # transition:
 8374                base.updatePosition(
 8375                    now,
 8376                    followFrom,
 8377                    applyTo,
 8378                    moveWhich
 8379                )
 8380
 8381                # Apply consequences of followed transition
 8382                fullFollowTo = self.applyTransitionConsequence(
 8383                    followFrom,
 8384                    following,
 8385                    moveWhich,
 8386                    challengePolicy
 8387                )
 8388
 8389                # Now update to end of followed transition
 8390                if fullFollowTo is None:
 8391                    base.updatePosition(
 8392                        now,
 8393                        followTo,
 8394                        applyTo,
 8395                        moveWhich
 8396                    )
 8397                    fullFollowTo = followTo
 8398
 8399                # Skip the normal update: we've taken care of that plus more
 8400                return fullFollowTo
 8401            else:
 8402                # Normal position updates still applies since follow
 8403                # transition wasn't possible
 8404                return None
 8405
 8406        elif typ == "save":
 8407            assert isinstance(value, base.SaveSlot)
 8408            now.saves[value] = copy.deepcopy((now.graph, now.state))
 8409
 8410        else:
 8411            raise ValueError(f"Invalid effect type {typ!r}.")
 8412
 8413        return None  # default return value if we didn't return above
 8414
 8415    def applyExtraneousConsequence(
 8416        self,
 8417        consequence: base.Consequence,
 8418        where: Optional[
 8419            Tuple[base.AnyDecisionSpecifier, Optional[base.Transition]]
 8420        ] = None,
 8421        moveWhich: Optional[base.FocalPointName] = None
 8422    ) -> Optional[base.DecisionID]:
 8423        """
 8424        Applies an extraneous consequence not associated with a
 8425        transition. Unlike `applyTransitionConsequence`, the provided
 8426        `base.Consequence` must already have observed outcomes (see
 8427        `base.observeChallengeOutcomes`). Returns the decision ID for a
 8428        decision implied by a goto, follow, or bounce effect, or `None`
 8429        if no effect implies a destination.
 8430
 8431        The `where` and `moveWhich` optional arguments specify which
 8432        decision and/or transition to use as the application position,
 8433        and/or which focal point to move. This affects mechanism lookup
 8434        as well as the end position when 'follow' effects are used.
 8435        Specifically:
 8436
 8437        - A 'follow' trigger will search for transitions to follow from
 8438            the destination of the specified transition, or if only a
 8439            decision was supplied, from that decision.
 8440        - Mechanism lookups will start with both ends of the specified
 8441            transition as their search field (or with just the specified
 8442            decision if no transition is included).
 8443
 8444        'bounce' effects will cause an error unless position information
 8445        is provided, and will set the position to the base decision
 8446        provided in `where`.
 8447
 8448        Note: callers should update any situation-based variables
 8449        immediately after calling this as a 'revert' effect could change
 8450        the current graph and/or state and other changes could get lost
 8451        if they get applied to a stale graph/state.
 8452
 8453        # TODO: Examples for goto and follow effects.
 8454        """
 8455        now = self.getSituation()
 8456        searchFrom = set()
 8457        if where is not None:
 8458            if where[1] is not None:
 8459                searchFrom = now.graph.bothEnds(where[0], where[1])
 8460            else:
 8461                searchFrom = {now.graph.resolveDecision(where[0])}
 8462
 8463        context = base.RequirementContext(
 8464            state=now.state,
 8465            graph=now.graph,
 8466            searchFrom=searchFrom
 8467        )
 8468
 8469        effectIndices = base.observedEffects(context, consequence)
 8470        destID = None
 8471        for index in effectIndices:
 8472            effect = base.consequencePart(consequence, index)
 8473            if not isinstance(effect, dict) or 'value' not in effect:
 8474                raise RuntimeError(
 8475                    f"Invalid effect index {index}: Consequence part at"
 8476                    f" that index is not an Effect. Got:\n{effect}"
 8477                )
 8478            effect = cast(base.Effect, effect)
 8479            destID = self.applyExtraneousEffect(
 8480                effect,
 8481                where,
 8482                moveWhich
 8483            )
 8484            # technically this variable is not used later in this
 8485            # function, but the `applyExtraneousEffect` call means it
 8486            # needs an update, so we're doing that in case someone later
 8487            # adds code to this function that uses 'now' after this
 8488            # point.
 8489            now = self.getSituation()
 8490
 8491        return destID
 8492
 8493    def applyTransitionConsequence(
 8494        self,
 8495        decision: base.AnyDecisionSpecifier,
 8496        transition: base.AnyTransition,
 8497        moveWhich: Optional[base.FocalPointName] = None,
 8498        policy: base.ChallengePolicy = "specified",
 8499        fromIndex: Optional[int] = None,
 8500        toIndex: Optional[int] = None
 8501    ) -> Optional[base.DecisionID]:
 8502        """
 8503        Applies the effects of the specified transition to the current
 8504        graph and state, possibly overriding observed outcomes using
 8505        outcomes specified as part of a `base.TransitionWithOutcomes`.
 8506
 8507        The `where` and `moveWhich` function serve the same purpose as
 8508        for `applyExtraneousEffect`. If `where` is `None`, then the
 8509        effects will be applied as extraneous effects, meaning that
 8510        their delay and charges values will be ignored and their trigger
 8511        count will not be tracked. If `where` is supplied
 8512
 8513        Returns either None to indicate that the position update for the
 8514        transition should apply as usual, or a decision ID indicating
 8515        another destination which has already been applied by a
 8516        transition effect.
 8517
 8518        If `fromIndex` and/or `toIndex` are specified, then only effects
 8519        which have indices between those two (inclusive) will be
 8520        applied, and other effects will neither apply nor be updated in
 8521        any way. Note that `onlyPart` does not override the challenge
 8522        policy: if the effects in the specified part are not applied due
 8523        to a challenge outcome, they still won't happen, including
 8524        challenge outcomes outside of that part. Also, outcomes for
 8525        challenges of the entire consequence are re-observed if the
 8526        challenge policy implies it.
 8527
 8528        Note: Anyone calling this should update any situation-based
 8529        variables immediately after the call, as a 'revert' effect may
 8530        have changed the current graph and/or state.
 8531        """
 8532        now = self.getSituation()
 8533        dID = now.graph.resolveDecision(decision)
 8534
 8535        transitionName, outcomes = base.nameAndOutcomes(transition)
 8536
 8537        searchFrom = set()
 8538        searchFrom = now.graph.bothEnds(dID, transitionName)
 8539
 8540        context = base.RequirementContext(
 8541            state=now.state,
 8542            graph=now.graph,
 8543            searchFrom=searchFrom
 8544        )
 8545
 8546        consequence = now.graph.getConsequence(dID, transitionName)
 8547
 8548        # Make sure that challenge outcomes are known
 8549        if policy != "specified":
 8550            base.resetChallengeOutcomes(consequence)
 8551        useUp = outcomes[:]
 8552        base.observeChallengeOutcomes(
 8553            context,
 8554            consequence,
 8555            location=searchFrom,
 8556            policy=policy,
 8557            knownOutcomes=useUp
 8558        )
 8559        if len(useUp) > 0:
 8560            raise ValueError(
 8561                f"More outcomes specified than challenges observed in"
 8562                f" consequence:\n{consequence}"
 8563                f"\nRemaining outcomes:\n{useUp}"
 8564            )
 8565
 8566        # Figure out which effects apply, and apply each of them
 8567        effectIndices = base.observedEffects(context, consequence)
 8568        if fromIndex is None:
 8569            fromIndex = 0
 8570
 8571        altDest = None
 8572        for index in effectIndices:
 8573            if (
 8574                index >= fromIndex
 8575            and (toIndex is None or index <= toIndex)
 8576            ):
 8577                thisDest = self.applyTransitionEffect(
 8578                    (dID, transitionName, index),
 8579                    moveWhich
 8580                )
 8581                if thisDest is not None:
 8582                    altDest = thisDest
 8583                # TODO: What if this updates state with 'revert' to a
 8584                # graph that doesn't contain the same effects?
 8585                # TODO: Update 'now' and 'context'?!
 8586        return altDest
 8587
 8588    def allDecisions(self) -> List[base.DecisionID]:
 8589        """
 8590        Returns the list of all decisions which existed at any point
 8591        within the exploration. Example:
 8592
 8593        >>> ex = DiscreteExploration()
 8594        >>> ex.start('A')
 8595        0
 8596        >>> ex.observe('A', 'right')
 8597        1
 8598        >>> ex.explore('right', 'B', 'left')
 8599        1
 8600        >>> ex.observe('B', 'right')
 8601        2
 8602        >>> ex.allDecisions()  # 'A', 'B', and the unnamed 'right of B'
 8603        [0, 1, 2]
 8604        """
 8605        seen = set()
 8606        result = []
 8607        for situation in self:
 8608            for decision in situation.graph:
 8609                if decision not in seen:
 8610                    result.append(decision)
 8611                    seen.add(decision)
 8612
 8613        return result
 8614
 8615    def allExploredDecisions(self) -> List[base.DecisionID]:
 8616        """
 8617        Returns the list of all decisions which existed at any point
 8618        within the exploration, excluding decisions whose highest
 8619        exploration status was `noticed` or lower. May still include
 8620        decisions which don't exist in the final situation's graph due to
 8621        things like decision merging. Example:
 8622
 8623        >>> ex = DiscreteExploration()
 8624        >>> ex.start('A')
 8625        0
 8626        >>> ex.observe('A', 'right')
 8627        1
 8628        >>> ex.explore('right', 'B', 'left')
 8629        1
 8630        >>> ex.observe('B', 'right')
 8631        2
 8632        >>> graph = ex.getSituation().graph
 8633        >>> graph.addDecision('C')  # add isolated decision; doesn't set status
 8634        3
 8635        >>> ex.hasBeenVisited('C')
 8636        False
 8637        >>> ex.allExploredDecisions()
 8638        [0, 1]
 8639        >>> ex.setExplorationStatus('C', 'exploring')
 8640        >>> ex.allExploredDecisions()  # 2 is the decision right from 'B'
 8641        [0, 1, 3]
 8642        >>> ex.setExplorationStatus('A', 'explored')
 8643        >>> ex.allExploredDecisions()
 8644        [0, 1, 3]
 8645        >>> ex.setExplorationStatus('A', 'unknown')
 8646        >>> # remains visisted in an earlier step
 8647        >>> ex.allExploredDecisions()
 8648        [0, 1, 3]
 8649        >>> ex.setExplorationStatus('C', 'unknown')  # not explored earlier
 8650        >>> ex.allExploredDecisions()  # 2 is the decision right from 'B'
 8651        [0, 1]
 8652        """
 8653        seen = set()
 8654        result = []
 8655        for situation in self:
 8656            graph = situation.graph
 8657            for decision in graph:
 8658                if (
 8659                    decision not in seen
 8660                and base.hasBeenVisited(situation, decision)
 8661                ):
 8662                    result.append(decision)
 8663                    seen.add(decision)
 8664
 8665        return result
 8666
 8667    def allVisitedDecisions(self) -> List[base.DecisionID]:
 8668        """
 8669        Returns the list of all decisions which existed at any point
 8670        within the exploration and which were visited at least once.
 8671        Orders them in the same order they were visited in.
 8672
 8673        Usually all of these decisions will be present in the final
 8674        situation's graph, but sometimes merging or other factors means
 8675        there might be some that won't be. Being present on the game
 8676        state's 'active' list in a step for its domain is what counts as
 8677        "being visited," which means that nodes which were passed through
 8678        directly via a 'follow' effect won't be counted, for example.
 8679
 8680        This should usually correspond with the absence of the
 8681        'unconfirmed' tag.
 8682
 8683        Example:
 8684
 8685        >>> ex = DiscreteExploration()
 8686        >>> ex.start('A')
 8687        0
 8688        >>> ex.observe('A', 'right')
 8689        1
 8690        >>> ex.explore('right', 'B', 'left')
 8691        1
 8692        >>> ex.observe('B', 'right')
 8693        2
 8694        >>> ex.getSituation().graph.addDecision('C')  # add isolated decision
 8695        3
 8696        >>> av = ex.allVisitedDecisions()
 8697        >>> av
 8698        [0, 1]
 8699        >>> all(  # no decisions in the 'visited' list are tagged
 8700        ...     'unconfirmed' not in ex.getSituation().graph.decisionTags(d)
 8701        ...     for d in av
 8702        ... )
 8703        True
 8704        >>> graph = ex.getSituation().graph
 8705        >>> 'unconfirmed' in graph.decisionTags(0)
 8706        False
 8707        >>> 'unconfirmed' in graph.decisionTags(1)
 8708        False
 8709        >>> 'unconfirmed' in graph.decisionTags(2)
 8710        True
 8711        >>> 'unconfirmed' in graph.decisionTags(3)  # not tagged; not explored
 8712        False
 8713        """
 8714        seen = set()
 8715        result = []
 8716        for step in range(len(self)):
 8717            active = self.getActiveDecisions(step)
 8718            for dID in active:
 8719                if dID not in seen:
 8720                    result.append(dID)
 8721                    seen.add(dID)
 8722
 8723        return result
 8724
 8725    def allTransitions(self) -> List[
 8726        Tuple[base.DecisionID, base.Transition, base.DecisionID]
 8727    ]:
 8728        """
 8729        Returns the list of all transitions which existed at any point
 8730        within the exploration, as 3-tuples with source decision ID,
 8731        transition name, and destination decision ID. Note that since
 8732        transitions can be deleted or re-targeted, and a transition name
 8733        can be re-used after being deleted, things can get messy in the
 8734        edges cases. When the same transition name is used in different
 8735        steps with different decision targets, we end up including each
 8736        possible source-transition-destination triple. Example:
 8737
 8738        >>> ex = DiscreteExploration()
 8739        >>> ex.start('A')
 8740        0
 8741        >>> ex.observe('A', 'right')
 8742        1
 8743        >>> ex.explore('right', 'B', 'left')
 8744        1
 8745        >>> ex.observe('B', 'right')
 8746        2
 8747        >>> ex.wait()  # leave behind a step where 'B' has a 'right'
 8748        >>> ex.primaryDecision(0)
 8749        >>> ex.primaryDecision(1)
 8750        0
 8751        >>> ex.primaryDecision(2)
 8752        1
 8753        >>> ex.primaryDecision(3)
 8754        1
 8755        >>> len(ex)
 8756        4
 8757        >>> ex[3].graph.removeDecision(2)  # delete 'right of B'
 8758        >>> ex.observe('B', 'down')
 8759        3
 8760        >>> # Decisions are: 'A', 'B', and the unnamed 'right of B'
 8761        >>> # (now-deleted), and the unnamed 'down from B'
 8762        >>> ex.allDecisions()
 8763        [0, 1, 2, 3]
 8764        >>> for tr in ex.allTransitions():
 8765        ...     print(tr)
 8766        ...
 8767        (0, 'right', 1)
 8768        (1, 'return', 0)
 8769        (1, 'left', 0)
 8770        (1, 'right', 2)
 8771        (2, 'return', 1)
 8772        (1, 'down', 3)
 8773        (3, 'return', 1)
 8774        >>> # Note transitions from now-deleted nodes, and 'return'
 8775        >>> # transitions for unexplored nodes before they get explored
 8776        """
 8777        seen = set()
 8778        result = []
 8779        for situation in self:
 8780            graph = situation.graph
 8781            for (src, dst, transition) in graph.allEdges():  # type:ignore
 8782                trans = (src, transition, dst)
 8783                if trans not in seen:
 8784                    result.append(trans)
 8785                    seen.add(trans)
 8786
 8787        return result
 8788
 8789    def start(
 8790        self,
 8791        decision: base.AnyDecisionSpecifier,
 8792        startCapabilities: Optional[base.CapabilitySet] = None,
 8793        setMechanismStates: Optional[
 8794            Dict[base.MechanismID, base.MechanismState]
 8795        ] = None,
 8796        setCustomState: Optional[dict] = None,
 8797        decisionType: base.DecisionType = "imposed"
 8798    ) -> base.DecisionID:
 8799        """
 8800        Sets the initial position information for a newly-relevant
 8801        domain for the current focal context. Creates a new decision
 8802        if the decision is specified by name or `DecisionSpecifier` and
 8803        that decision doesn't already exist. Returns the decision ID for
 8804        the newly-placed decision (or for the specified decision if it
 8805        already existed).
 8806
 8807        Raises a `BadStart` error if the current focal context already
 8808        has position information for the specified domain.
 8809
 8810        - The given `startCapabilities` replaces any existing
 8811            capabilities for the current focal context, although you can
 8812            leave it as the default `None` to avoid that and retain any
 8813            capabilities that have been set up already.
 8814        - The given `setMechanismStates` and `setCustomState`
 8815            dictionaries override all previous mechanism states & custom
 8816            states in the new situation. Leave these as the default
 8817            `None` to maintain those states.
 8818        - If created, the decision will be placed in the DEFAULT_DOMAIN
 8819            domain unless it's specified as a `base.DecisionSpecifier`
 8820            with a domain part, in which case that domain is used.
 8821        - If specified as a `base.DecisionSpecifier` with a zone part
 8822            and a new decision needs to be created, the decision will be
 8823            added to that zone, creating it at level 0 if necessary,
 8824            although otherwise no zone information will be changed.
 8825        - Resets the decision type to "pending" and the action taken to
 8826            `None`. Sets the decision type of the previous situation to
 8827            'imposed' (or the specified `decisionType`) and sets an
 8828            appropriate 'start' action for that situation.
 8829        - Tags the step with 'start'.
 8830        - Even in a plural- or spreading-focalized domain, you still need
 8831            to pick one decision to start at.
 8832        """
 8833        now = self.getSituation()
 8834
 8835        startID = now.graph.getDecision(decision)
 8836        zone = None
 8837        domain = base.DEFAULT_DOMAIN
 8838        if startID is None:
 8839            if isinstance(decision, base.DecisionID):
 8840                raise MissingDecisionError(
 8841                    f"Cannot start at decision {decision} because no"
 8842                    f" decision with that ID exists. Supply a name or"
 8843                    f" DecisionSpecifier if you need the start decision"
 8844                    f" to be created automatically."
 8845                )
 8846            elif isinstance(decision, base.DecisionName):
 8847                decision = base.DecisionSpecifier(
 8848                    domain=None,
 8849                    zone=None,
 8850                    name=decision
 8851                )
 8852            startID = now.graph.addDecision(
 8853                decision.name,
 8854                domain=decision.domain
 8855            )
 8856            zone = decision.zone
 8857            if decision.domain is not None:
 8858                domain = decision.domain
 8859
 8860        if zone is not None:
 8861            if now.graph.getZoneInfo(zone) is None:
 8862                now.graph.createZone(zone, 0)
 8863            now.graph.addDecisionToZone(startID, zone)
 8864
 8865        action: base.ExplorationAction = (
 8866            'start',
 8867            startID,
 8868            startID,
 8869            domain,
 8870            startCapabilities,
 8871            setMechanismStates,
 8872            setCustomState
 8873        )
 8874
 8875        self.advanceSituation(action, decisionType)
 8876
 8877        return startID
 8878
 8879    def hasBeenVisited(
 8880        self,
 8881        decision: base.AnyDecisionSpecifier,
 8882        step: int = -1
 8883    ):
 8884        """
 8885        Returns whether or not the specified decision has been visited in
 8886        the specified step (default current step).
 8887        """
 8888        return base.hasBeenVisited(self.getSituation(step), decision)
 8889
 8890    def setExplorationStatus(
 8891        self,
 8892        decision: base.AnyDecisionSpecifier,
 8893        status: base.ExplorationStatus,
 8894        upgradeOnly: bool = False
 8895    ):
 8896        """
 8897        Updates the current exploration status of a specific decision in
 8898        the current situation. If `upgradeOnly` is true (default is
 8899        `False` then the update will only apply if the new exploration
 8900        status counts as 'more-explored' than the old one (see
 8901        `base.moreExplored`).
 8902        """
 8903        base.setExplorationStatus(
 8904            self.getSituation(),
 8905            decision,
 8906            status,
 8907            upgradeOnly
 8908        )
 8909
 8910    def getExplorationStatus(
 8911        self,
 8912        decision: base.AnyDecisionSpecifier,
 8913        step: int = -1
 8914    ):
 8915        """
 8916        Returns the exploration status of the specified decision at the
 8917        specified step (default is last step). Decisions whose
 8918        exploration status has never been set will have a default status
 8919        of 'unknown'.
 8920        """
 8921        situation = self.getSituation(step)
 8922        dID = situation.graph.resolveDecision(decision)
 8923        return situation.state['exploration'].get(dID, 'unknown')
 8924
 8925    def deduceTransitionDetailsAtStep(
 8926        self,
 8927        step: int,
 8928        transition: base.Transition,
 8929        fromDecision: Optional[base.AnyDecisionSpecifier] = None,
 8930        whichFocus: Optional[base.FocalPointSpecifier] = None,
 8931        inCommon: Union[bool, Literal["auto"]] = "auto"
 8932    ) -> Tuple[
 8933        base.ContextSpecifier,
 8934        base.DecisionID,
 8935        base.DecisionID,
 8936        Optional[base.FocalPointSpecifier]
 8937    ]:
 8938        """
 8939        Given just a transition name which the player intends to take in
 8940        a specific step, deduces the `ContextSpecifier` for which
 8941        context should be updated, the source and destination
 8942        `DecisionID`s for the transition, and if the destination
 8943        decision's domain is plural-focalized, the `FocalPointName`
 8944        specifying which focal point should be moved.
 8945
 8946        Because many of those things are ambiguous, you may get an
 8947        `AmbiguousTransitionError` when things are underspecified, and
 8948        there are options for specifying some of the extra information
 8949        directly:
 8950
 8951        - `fromDecision` may be used to specify the source decision.
 8952        - `whichFocus` may be used to specify the focal point (within a
 8953            particular context/domain) being updated. When focal point
 8954            ambiguity remains and this is unspecified, the
 8955            alphabetically-earliest relevant focal point will be used
 8956            (either among all focal points which activate the source
 8957            decision, if there are any, or among all focal points for
 8958            the entire domain of the destination decision).
 8959        - `inCommon` (a `ContextSpecifier`) may be used to specify which
 8960            context to update. The default of "auto" will cause the
 8961            active context to be selected unless it does not activate
 8962            the source decision, in which case the common context will
 8963            be selected.
 8964
 8965        A `MissingDecisionError` will be raised if there are no current
 8966        active decisions (e.g., before `start` has been called), and a
 8967        `MissingTransitionError` will be raised if the listed transition
 8968        does not exist from any active decision (or from the specified
 8969        decision if `fromDecision` is used).
 8970        """
 8971        now = self.getSituation(step)
 8972        active = self.getActiveDecisions(step)
 8973        if len(active) == 0:
 8974            raise MissingDecisionError(
 8975                f"There are no active decisions from which transition"
 8976                f" {repr(transition)} could be taken at step {step}."
 8977            )
 8978
 8979        # All source/destination decision pairs for transitions with the
 8980        # given transition name.
 8981        allDecisionPairs: Dict[base.DecisionID, base.DecisionID] = {}
 8982
 8983        # TODO: When should we be trimming the active decisions to match
 8984        # any alterations to the graph?
 8985        for dID in active:
 8986            outgoing = now.graph.destinationsFrom(dID)
 8987            if transition in outgoing:
 8988                allDecisionPairs[dID] = outgoing[transition]
 8989
 8990        if len(allDecisionPairs) == 0:
 8991            raise MissingTransitionError(
 8992                f"No transitions named {repr(transition)} are outgoing"
 8993                f" from active decisions at step {step}."
 8994                f"\nActive decisions are:"
 8995                f"\n{now.graph.namesListing(active)}"
 8996            )
 8997
 8998        if (
 8999            fromDecision is not None
 9000        and fromDecision not in allDecisionPairs
 9001        ):
 9002            raise MissingTransitionError(
 9003                f"{fromDecision} was specified as the source decision"
 9004                f" for traversing transition {repr(transition)} but"
 9005                f" there is no transition of that name from that"
 9006                f" decision at step {step}."
 9007                f"\nValid source decisions are:"
 9008                f"\n{now.graph.namesListing(allDecisionPairs)}"
 9009            )
 9010        elif fromDecision is not None:
 9011            fromID = now.graph.resolveDecision(fromDecision)
 9012            destID = allDecisionPairs[fromID]
 9013            fromDomain = now.graph.domainFor(fromID)
 9014        elif len(allDecisionPairs) == 1:
 9015            fromID, destID = list(allDecisionPairs.items())[0]
 9016            fromDomain = now.graph.domainFor(fromID)
 9017        else:
 9018            fromID = None
 9019            destID = None
 9020            fromDomain = None
 9021            # Still ambiguous; resolve this below
 9022
 9023        # Use whichFocus if provided
 9024        if whichFocus is not None:
 9025            # Type/value check for whichFocus
 9026            if (
 9027                not isinstance(whichFocus, tuple)
 9028             or len(whichFocus) != 3
 9029             or whichFocus[0] not in ("active", "common")
 9030             or not isinstance(whichFocus[1], base.Domain)
 9031             or not isinstance(whichFocus[2], base.FocalPointName)
 9032            ):
 9033                raise ValueError(
 9034                    f"Invalid whichFocus value {repr(whichFocus)}."
 9035                    f"\nMust be a length-3 tuple with 'active' or 'common'"
 9036                    f" as the first element, a Domain as the second"
 9037                    f" element, and a FocalPointName as the third"
 9038                    f" element."
 9039                )
 9040
 9041            # Resolve focal point specified
 9042            fromID = base.resolvePosition(
 9043                now,
 9044                whichFocus
 9045            )
 9046            if fromID is None:
 9047                raise MissingTransitionError(
 9048                    f"Focal point {repr(whichFocus)} was specified as"
 9049                    f" the transition source, but that focal point does"
 9050                    f" not have a position."
 9051                )
 9052            else:
 9053                destID = now.graph.destination(fromID, transition)
 9054                fromDomain = now.graph.domainFor(fromID)
 9055
 9056        elif fromID is None:  # whichFocus is None, so it can't disambiguate
 9057            raise AmbiguousTransitionError(
 9058                f"Transition {repr(transition)} was selected for"
 9059                f" disambiguation, but there are multiple transitions"
 9060                f" with that name from currently-active decisions, and"
 9061                f" neither fromDecision nor whichFocus adequately"
 9062                f" disambiguates the specific transition taken."
 9063                f"\nValid source decisions at step {step} are:"
 9064                f"\n{now.graph.namesListing(allDecisionPairs)}"
 9065            )
 9066
 9067        # At this point, fromID, destID, and fromDomain have
 9068        # been resolved.
 9069        if fromID is None or destID is None or fromDomain is None:
 9070            raise RuntimeError(
 9071                f"One of fromID, destID, or fromDomain was None after"
 9072                f" disambiguation was finished:"
 9073                f"\nfromID: {fromID}, destID: {destID}, fromDomain:"
 9074                f" {repr(fromDomain)}"
 9075            )
 9076
 9077        # Now figure out which context activated the source so we know
 9078        # which focal point we're moving:
 9079        context = self.getActiveContext()
 9080        active = base.activeDecisionSet(context)
 9081        using: base.ContextSpecifier = "active"
 9082        if fromID not in active:
 9083            context = self.getCommonContext(step)
 9084            using = "common"
 9085
 9086        destDomain = now.graph.domainFor(destID)
 9087        if (
 9088            whichFocus is None
 9089        and base.getDomainFocalization(context, destDomain) == 'plural'
 9090        ):
 9091            # Need to figure out which focal point is moving; use the
 9092            # alphabetically earliest one that's positioned at the
 9093            # fromID, or just the earliest one overall if none of them
 9094            # are there.
 9095            contextFocalPoints: Dict[
 9096                base.FocalPointName,
 9097                Optional[base.DecisionID]
 9098            ] = cast(
 9099                Dict[base.FocalPointName, Optional[base.DecisionID]],
 9100                context['activeDecisions'][destDomain]
 9101            )
 9102            if not isinstance(contextFocalPoints, dict):
 9103                raise RuntimeError(
 9104                    f"Active decisions specifier for domain"
 9105                    f" {repr(destDomain)} with plural focalization has"
 9106                    f" a non-dictionary value."
 9107                )
 9108
 9109            if fromDomain == destDomain:
 9110                focalCandidates = [
 9111                    fp
 9112                    for fp, pos in contextFocalPoints.items()
 9113                    if pos == fromID
 9114                ]
 9115            else:
 9116                focalCandidates = list(contextFocalPoints)
 9117
 9118            whichFocus = (using, destDomain, min(focalCandidates))
 9119
 9120        # Now whichFocus has been set if it wasn't already specified;
 9121        # might still be None if it's not relevant.
 9122        return (using, fromID, destID, whichFocus)
 9123
 9124    def advanceSituation(
 9125        self,
 9126        action: base.ExplorationAction,
 9127        decisionType: base.DecisionType = "active",
 9128        challengePolicy: base.ChallengePolicy = "specified"
 9129    ) -> Tuple[base.Situation, Set[base.DecisionID]]:
 9130        """
 9131        Given an `ExplorationAction`, sets that as the action taken in
 9132        the current situation, and adds a new situation with the results
 9133        of that action. A `DoubleActionError` will be raised if the
 9134        current situation already has an action specified, and/or has a
 9135        decision type other than 'pending'. By default the type of the
 9136        decision will be 'active' but another `DecisionType` can be
 9137        specified via the `decisionType` parameter.
 9138
 9139        If the action specified is `('noAction',)`, then the new
 9140        situation will be a copy of the old one; this represents waiting
 9141        or being at an ending (a decision type other than 'pending'
 9142        should be used).
 9143
 9144        Although `None` can appear as the action entry in situations
 9145        with pending decisions, you cannot call `advanceSituation` with
 9146        `None` as the action.
 9147
 9148        If the action includes taking a transition whose requirements
 9149        are not satisfied, the transition will still be taken (and any
 9150        consequences applied) but a `TransitionBlockedWarning` will be
 9151        issued.
 9152
 9153        A `ChallengePolicy` may be specified, the default is 'specified'
 9154        which requires that outcomes are pre-specified. If any other
 9155        policy is set, the challenge outcomes will be reset before
 9156        re-resolving them according to the provided policy.
 9157
 9158        The new situation will have decision type 'pending' and `None`
 9159        as the action.
 9160
 9161        The new situation created as a result of the action is returned,
 9162        along with the set of destination decision IDs, including
 9163        possibly a modified destination via 'bounce', 'goto', and/or
 9164        'follow' effects. For actions that don't have a destination, the
 9165        second part of the returned tuple will be an empty set. Multiple
 9166        IDs may be in the set when using a start action in a plural- or
 9167        spreading-focalized domain, for example.
 9168
 9169        If the action updates active decisions (including via transition
 9170        effects) this will also update the exploration status of those
 9171        decisions to 'exploring' if they had been in an unvisited
 9172        status (see `updatePosition` and `hasBeenVisited`). This
 9173        includes decisions traveled through but not ultimately arrived
 9174        at via 'follow' effects.
 9175
 9176        If any decisions are active in the `ENDINGS_DOMAIN`, attempting
 9177        to 'warp', 'explore', 'take', or 'start' will raise an
 9178        `InvalidActionError`.
 9179        """
 9180        now = self.getSituation()
 9181        if now.type != 'pending' or now.action is not None:
 9182            raise DoubleActionError(
 9183                f"Attempted to take action {repr(action)} at step"
 9184                f" {len(self) - 1}, but an action and/or decision type"
 9185                f" had already been specified:"
 9186                f"\nAction: {repr(now.action)}"
 9187                f"\nType: {repr(now.type)}"
 9188            )
 9189
 9190        # Update the now situation to add in the decision type and
 9191        # action taken:
 9192        revised = base.Situation(
 9193            now.graph,
 9194            now.state,
 9195            decisionType,
 9196            action,
 9197            now.saves,
 9198            now.tags,
 9199            now.annotations
 9200        )
 9201        self.situations[-1] = revised
 9202
 9203        # Separate update process when reverting (this branch returns)
 9204        if (
 9205            action is not None
 9206        and isinstance(action, tuple)
 9207        and len(action) == 3
 9208        and action[0] == 'revertTo'
 9209        and isinstance(action[1], base.SaveSlot)
 9210        and isinstance(action[2], set)
 9211        and all(isinstance(x, str) for x in action[2])
 9212        ):
 9213            _, slot, aspects = action
 9214            if slot not in now.saves:
 9215                raise KeyError(
 9216                    f"Cannot load save slot {slot!r} because no save"
 9217                    f" data has been established for that slot."
 9218                )
 9219            load = now.saves[slot]
 9220            rGraph, rState = base.revertedState(
 9221                (now.graph, now.state),
 9222                load,
 9223                aspects
 9224            )
 9225            reverted = base.Situation(
 9226                graph=rGraph,
 9227                state=rState,
 9228                type='pending',
 9229                action=None,
 9230                saves=copy.deepcopy(now.saves),
 9231                tags={},
 9232                annotations=[]
 9233            )
 9234            self.situations.append(reverted)
 9235            # Apply any active triggers (edits reverted)
 9236            self.applyActiveTriggers()
 9237            # Figure out destinations set to return
 9238            newDestinations = set()
 9239            newPr = rState['primaryDecision']
 9240            if newPr is not None:
 9241                newDestinations.add(newPr)
 9242            return (reverted, newDestinations)
 9243
 9244        # TODO: These deep copies are expensive time-wise. Can we avoid
 9245        # them? Probably not.
 9246        newGraph = copy.deepcopy(now.graph)
 9247        newState = copy.deepcopy(now.state)
 9248        newSaves = copy.copy(now.saves)  # a shallow copy
 9249        newTags: Dict[base.Tag, base.TagValue] = {}
 9250        newAnnotations: List[base.Annotation] = []
 9251        updated = base.Situation(
 9252            graph=newGraph,
 9253            state=newState,
 9254            type='pending',
 9255            action=None,
 9256            saves=newSaves,
 9257            tags=newTags,
 9258            annotations=newAnnotations
 9259        )
 9260
 9261        targetContext: base.FocalContext
 9262
 9263        # Now that action effects have been imprinted into the updated
 9264        # situation, append it to our situations list
 9265        self.situations.append(updated)
 9266
 9267        # Figure out effects of the action:
 9268        if action is None:
 9269            raise InvalidActionError(
 9270                "None cannot be used as an action when advancing the"
 9271                " situation."
 9272            )
 9273
 9274        aLen = len(action)
 9275
 9276        destIDs = set()
 9277
 9278        if (
 9279            action[0] in ('start', 'take', 'explore', 'warp')
 9280        and any(
 9281                newGraph.domainFor(d) == ENDINGS_DOMAIN
 9282                for d in self.getActiveDecisions()
 9283            )
 9284        ):
 9285            activeEndings = [
 9286                d
 9287                for d in self.getActiveDecisions()
 9288                if newGraph.domainFor(d) == ENDINGS_DOMAIN
 9289            ]
 9290            raise InvalidActionError(
 9291                f"Attempted to {action[0]!r} while an ending was"
 9292                f" active. Active endings are:"
 9293                f"\n{newGraph.namesListing(activeEndings)}"
 9294            )
 9295
 9296        if action == ('noAction',):
 9297            # No updates needed
 9298            pass
 9299
 9300        elif (
 9301            not isinstance(action, tuple)
 9302         or (action[0] not in get_args(base.ExplorationActionType))
 9303         or not (2 <= aLen <= 7)
 9304        ):
 9305            raise InvalidActionError(
 9306                f"Invalid ExplorationAction tuple (must be a tuple that"
 9307                f" starts with an ExplorationActionType and has 2-6"
 9308                f" entries if it's not ('noAction',)):"
 9309                f"\n{repr(action)}"
 9310            )
 9311
 9312        elif action[0] == 'start':
 9313            (
 9314                _,
 9315                positionSpecifier,
 9316                primary,
 9317                domain,
 9318                capabilities,
 9319                mechanismStates,
 9320                customState
 9321            ) = cast(
 9322                Tuple[
 9323                    Literal['start'],
 9324                    Union[
 9325                        base.DecisionID,
 9326                        Dict[base.FocalPointName, base.DecisionID],
 9327                        Set[base.DecisionID]
 9328                    ],
 9329                    Optional[base.DecisionID],
 9330                    base.Domain,
 9331                    Optional[base.CapabilitySet],
 9332                    Optional[Dict[base.MechanismID, base.MechanismState]],
 9333                    Optional[dict]
 9334                ],
 9335                action
 9336            )
 9337            targetContext = newState['contexts'][
 9338                newState['activeContext']
 9339            ]
 9340
 9341            targetFocalization = base.getDomainFocalization(
 9342                targetContext,
 9343                domain
 9344            )  # sets up 'singular' as default if
 9345
 9346            # Check if there are any already-active decisions.
 9347            if targetContext['activeDecisions'][domain] is not None:
 9348                raise BadStart(
 9349                    f"Cannot start in domain {repr(domain)} because"
 9350                    f" that domain already has a position. 'start' may"
 9351                    f" only be used with domains that don't yet have"
 9352                    f" any position information."
 9353                )
 9354
 9355            # Make the domain active
 9356            if domain not in targetContext['activeDomains']:
 9357                targetContext['activeDomains'].add(domain)
 9358
 9359            # Check position info matches focalization type and update
 9360            # exploration statuses
 9361            if isinstance(positionSpecifier, base.DecisionID):
 9362                if targetFocalization != 'singular':
 9363                    raise BadStart(
 9364                        f"Invalid position specifier"
 9365                        f" {repr(positionSpecifier)} (type"
 9366                        f" {type(positionSpecifier)}). Domain"
 9367                        f" {repr(domain)} has {targetFocalization}"
 9368                        f" focalization."
 9369                    )
 9370                base.setExplorationStatus(
 9371                    updated,
 9372                    positionSpecifier,
 9373                    'exploring',
 9374                    upgradeOnly=True
 9375                )
 9376                destIDs.add(positionSpecifier)
 9377            elif isinstance(positionSpecifier, dict):
 9378                if targetFocalization != 'plural':
 9379                    raise BadStart(
 9380                        f"Invalid position specifier"
 9381                        f" {repr(positionSpecifier)} (type"
 9382                        f" {type(positionSpecifier)}). Domain"
 9383                        f" {repr(domain)} has {targetFocalization}"
 9384                        f" focalization."
 9385                    )
 9386                destIDs |= set(positionSpecifier.values())
 9387            elif isinstance(positionSpecifier, set):
 9388                if targetFocalization != 'spreading':
 9389                    raise BadStart(
 9390                        f"Invalid position specifier"
 9391                        f" {repr(positionSpecifier)} (type"
 9392                        f" {type(positionSpecifier)}). Domain"
 9393                        f" {repr(domain)} has {targetFocalization}"
 9394                        f" focalization."
 9395                    )
 9396                destIDs |= positionSpecifier
 9397            else:
 9398                raise TypeError(
 9399                    f"Invalid position specifier"
 9400                    f" {repr(positionSpecifier)} (type"
 9401                    f" {type(positionSpecifier)}). It must be a"
 9402                    f" DecisionID, a dictionary from FocalPointNames to"
 9403                    f" DecisionIDs, or a set of DecisionIDs, according"
 9404                    f" to the focalization of the relevant domain."
 9405                )
 9406
 9407            # Put specified position(s) in place
 9408            # TODO: This cast is really silly...
 9409            targetContext['activeDecisions'][domain] = cast(
 9410                Union[
 9411                    None,
 9412                    base.DecisionID,
 9413                    Dict[base.FocalPointName, Optional[base.DecisionID]],
 9414                    Set[base.DecisionID]
 9415                ],
 9416                positionSpecifier
 9417            )
 9418
 9419            # Set primary decision
 9420            newState['primaryDecision'] = primary
 9421
 9422            # Set capabilities
 9423            if capabilities is not None:
 9424                targetContext['capabilities'] = capabilities
 9425
 9426            # Set mechanism states
 9427            if mechanismStates is not None:
 9428                newState['mechanisms'] = mechanismStates
 9429
 9430            # Set custom state
 9431            if customState is not None:
 9432                newState['custom'] = customState
 9433
 9434        elif action[0] in ('explore', 'take', 'warp'):  # similar handling
 9435            assert (
 9436                len(action) == 3
 9437             or len(action) == 4
 9438             or len(action) == 6
 9439             or len(action) == 7
 9440            )
 9441            # Set up necessary variables
 9442            cSpec: base.ContextSpecifier = "active"
 9443            fromID: Optional[base.DecisionID] = None
 9444            takeTransition: Optional[base.Transition] = None
 9445            outcomes: List[bool] = []
 9446            destID: base.DecisionID  # No starting value as it's not optional
 9447            moveInDomain: Optional[base.Domain] = None
 9448            moveWhich: Optional[base.FocalPointName] = None
 9449
 9450            # Figure out target context
 9451            if isinstance(action[1], str):
 9452                if action[1] not in get_args(base.ContextSpecifier):
 9453                    raise InvalidActionError(
 9454                        f"Action specifies {repr(action[1])} context,"
 9455                        f" but that's not a valid context specifier."
 9456                        f" The valid options are:"
 9457                        f"\n{repr(get_args(base.ContextSpecifier))}"
 9458                    )
 9459                else:
 9460                    cSpec = cast(base.ContextSpecifier, action[1])
 9461            else:  # Must be a `FocalPointSpecifier`
 9462                cSpec, moveInDomain, moveWhich = cast(
 9463                    base.FocalPointSpecifier,
 9464                    action[1]
 9465                )
 9466                assert moveInDomain is not None
 9467
 9468            # Grab target context to work in
 9469            if cSpec == 'common':
 9470                targetContext = newState['common']
 9471            else:
 9472                targetContext = newState['contexts'][
 9473                    newState['activeContext']
 9474                ]
 9475
 9476            # Check focalization of the target domain
 9477            if moveInDomain is not None:
 9478                fType = base.getDomainFocalization(
 9479                    targetContext,
 9480                    moveInDomain
 9481                )
 9482                if (
 9483                    (
 9484                        isinstance(action[1], str)
 9485                    and fType == 'plural'
 9486                    ) or (
 9487                        not isinstance(action[1], str)
 9488                    and fType != 'plural'
 9489                    )
 9490                ):
 9491                    raise ImpossibleActionError(
 9492                        f"Invalid ExplorationAction (moves in"
 9493                        f" plural-focalized domains must include a"
 9494                        f" FocalPointSpecifier, while moves in"
 9495                        f" non-plural-focalized domains must not."
 9496                        f" Domain {repr(moveInDomain)} is"
 9497                        f" {fType}-focalized):"
 9498                        f"\n{repr(action)}"
 9499                    )
 9500
 9501            if action[0] == "warp":
 9502                # It's a warp, so destination is specified directly
 9503                if not isinstance(action[2], base.DecisionID):
 9504                    raise TypeError(
 9505                        f"Invalid ExplorationAction tuple (third part"
 9506                        f" must be a decision ID for 'warp' actions):"
 9507                        f"\n{repr(action)}"
 9508                    )
 9509                else:
 9510                    destID = cast(base.DecisionID, action[2])
 9511
 9512            elif aLen == 4 or aLen == 7:
 9513                # direct 'take' or 'explore'
 9514                fromID = cast(base.DecisionID, action[2])
 9515                takeTransition, outcomes = cast(
 9516                    base.TransitionWithOutcomes,
 9517                    action[3]  # type: ignore [misc]
 9518                )
 9519                if (
 9520                    not isinstance(fromID, base.DecisionID)
 9521                 or not isinstance(takeTransition, base.Transition)
 9522                ):
 9523                    raise InvalidActionError(
 9524                        f"Invalid ExplorationAction tuple (for 'take' or"
 9525                        f" 'explore', if the length is 4/7, parts 2-4"
 9526                        f" must be a context specifier, a decision ID, and a"
 9527                        f" transition name. Got:"
 9528                        f"\n{repr(action)}"
 9529                    )
 9530
 9531                try:
 9532                    destID = newGraph.destination(fromID, takeTransition)
 9533                except MissingDecisionError:
 9534                    raise ImpossibleActionError(
 9535                        f"Invalid ExplorationAction: move from decision"
 9536                        f" {fromID} is invalid because there is no"
 9537                        f" decision with that ID in the current"
 9538                        f" graph."
 9539                        f"\nValid decisions are:"
 9540                        f"\n{newGraph.namesListing(newGraph)}"
 9541                    )
 9542                except MissingTransitionError:
 9543                    valid = newGraph.destinationsFrom(fromID)
 9544                    listing = newGraph.destinationsListing(valid)
 9545                    raise ImpossibleActionError(
 9546                        f"Invalid ExplorationAction: move from decision"
 9547                        f" {newGraph.identityOf(fromID)}"
 9548                        f" along transition {repr(takeTransition)} is"
 9549                        f" invalid because there is no such transition"
 9550                        f" at that decision."
 9551                        f"\nValid transitions there are:"
 9552                        f"\n{listing}"
 9553                    )
 9554                targetActive = targetContext['activeDecisions']
 9555                if moveInDomain is not None:
 9556                    activeInDomain = targetActive[moveInDomain]
 9557                    if (
 9558                        (
 9559                            isinstance(activeInDomain, base.DecisionID)
 9560                        and fromID != activeInDomain
 9561                        )
 9562                     or (
 9563                            isinstance(activeInDomain, set)
 9564                        and fromID not in activeInDomain
 9565                        )
 9566                     or (
 9567                            isinstance(activeInDomain, dict)
 9568                        and fromID not in activeInDomain.values()
 9569                        )
 9570                    ):
 9571                        raise ImpossibleActionError(
 9572                            f"Invalid ExplorationAction: move from"
 9573                            f" decision {fromID} is invalid because"
 9574                            f" that decision is not active in domain"
 9575                            f" {repr(moveInDomain)} in the current"
 9576                            f" graph."
 9577                            f"\nValid decisions are:"
 9578                            f"\n{newGraph.namesListing(newGraph)}"
 9579                        )
 9580
 9581            elif aLen == 3 or aLen == 6:
 9582                # 'take' or 'explore' focal point
 9583                # We know that moveInDomain is not None here.
 9584                assert moveInDomain is not None
 9585                if not isinstance(action[2], base.Transition):
 9586                    raise InvalidActionError(
 9587                        f"Invalid ExplorationAction tuple (for 'take'"
 9588                        f" actions if the second part is a"
 9589                        f" FocalPointSpecifier the third part must be a"
 9590                        f" transition name):"
 9591                        f"\n{repr(action)}"
 9592                    )
 9593
 9594                takeTransition, outcomes = cast(
 9595                    base.TransitionWithOutcomes,
 9596                    action[2]
 9597                )
 9598                targetActive = targetContext['activeDecisions']
 9599                activeInDomain = cast(
 9600                    Dict[base.FocalPointName, Optional[base.DecisionID]],
 9601                    targetActive[moveInDomain]
 9602                )
 9603                if (
 9604                    moveInDomain is not None
 9605                and (
 9606                        not isinstance(activeInDomain, dict)
 9607                     or moveWhich not in activeInDomain
 9608                    )
 9609                ):
 9610                    raise ImpossibleActionError(
 9611                        f"Invalid ExplorationAction: move of focal"
 9612                        f" point {repr(moveWhich)} in domain"
 9613                        f" {repr(moveInDomain)} is invalid because"
 9614                        f" that domain does not have a focal point"
 9615                        f" with that name."
 9616                    )
 9617                fromID = activeInDomain[moveWhich]
 9618                if fromID is None:
 9619                    raise ImpossibleActionError(
 9620                        f"Invalid ExplorationAction: move of focal"
 9621                        f" point {repr(moveWhich)} in domain"
 9622                        f" {repr(moveInDomain)} is invalid because"
 9623                        f" that focal point does not have a position"
 9624                        f" at this step."
 9625                    )
 9626                try:
 9627                    destID = newGraph.destination(fromID, takeTransition)
 9628                except MissingDecisionError:
 9629                    raise ImpossibleActionError(
 9630                        f"Invalid exploration state: focal point"
 9631                        f" {repr(moveWhich)} in domain"
 9632                        f" {repr(moveInDomain)} specifies decision"
 9633                        f" {fromID} as the current position, but"
 9634                        f" that decision does not exist!"
 9635                    )
 9636                except MissingTransitionError:
 9637                    valid = newGraph.destinationsFrom(fromID)
 9638                    listing = newGraph.destinationsListing(valid)
 9639                    raise ImpossibleActionError(
 9640                        f"Invalid ExplorationAction: move of focal"
 9641                        f" point {repr(moveWhich)} in domain"
 9642                        f" {repr(moveInDomain)} along transition"
 9643                        f" {repr(takeTransition)} is invalid because"
 9644                        f" that focal point is at decision"
 9645                        f" {newGraph.identityOf(fromID)} and that"
 9646                        f" decision does not have an outgoing"
 9647                        f" transition with that name.\nValid"
 9648                        f" transitions from that decision are:"
 9649                        f"\n{listing}"
 9650                    )
 9651
 9652            else:
 9653                raise InvalidActionError(
 9654                    f"Invalid ExplorationAction: unrecognized"
 9655                    f" 'explore', 'take' or 'warp' format:"
 9656                    f"\n{action}"
 9657                )
 9658
 9659            # If we're exploring, update information for the destination
 9660            if action[0] == 'explore':
 9661                zone = cast(Optional[base.Zone], action[-1])
 9662                recipName = cast(Optional[base.Transition], action[-2])
 9663                destOrName = cast(
 9664                    Union[base.DecisionName, base.DecisionID, None],
 9665                    action[-3]
 9666                )
 9667                if isinstance(destOrName, base.DecisionID):
 9668                    destID = destOrName
 9669
 9670                if fromID is None or takeTransition is None:
 9671                    raise ImpossibleActionError(
 9672                        f"Invalid ExplorationAction: exploration"
 9673                        f" has unclear origin decision or transition."
 9674                        f" Got:\n{action}"
 9675                    )
 9676
 9677                currentDest = newGraph.destination(fromID, takeTransition)
 9678                if not newGraph.isConfirmed(currentDest):
 9679                    newGraph.replaceUnconfirmed(
 9680                        fromID,
 9681                        takeTransition,
 9682                        destOrName,
 9683                        recipName,
 9684                        placeInZone=zone,
 9685                        forceNew=not isinstance(destOrName, base.DecisionID)
 9686                    )
 9687                else:
 9688                    # Otherwise, since the destination already existed
 9689                    # and was hooked up at the right decision, no graph
 9690                    # edits need to be made, unless we need to rename
 9691                    # the reciprocal.
 9692                    # TODO: Do we care about zones here?
 9693                    if recipName is not None:
 9694                        oldReciprocal = newGraph.getReciprocal(
 9695                            fromID,
 9696                            takeTransition
 9697                        )
 9698                        if (
 9699                            oldReciprocal is not None
 9700                        and oldReciprocal != recipName
 9701                        ):
 9702                            newGraph.addTransition(
 9703                                destID,
 9704                                recipName,
 9705                                fromID,
 9706                                None
 9707                            )
 9708                            newGraph.setReciprocal(
 9709                                destID,
 9710                                recipName,
 9711                                takeTransition,
 9712                                setBoth=True
 9713                            )
 9714                            newGraph.mergeTransitions(
 9715                                destID,
 9716                                oldReciprocal,
 9717                                recipName
 9718                            )
 9719
 9720            # If we are moving along a transition, check requirements
 9721            # and apply transition effects *before* updating our
 9722            # position, and check that they don't cancel the normal
 9723            # position update
 9724            finalDest = None
 9725            if takeTransition is not None:
 9726                assert fromID is not None  # both or neither
 9727                if not self.isTraversable(fromID, takeTransition):
 9728                    req = now.graph.getTransitionRequirement(
 9729                        fromID,
 9730                        takeTransition
 9731                    )
 9732                    # TODO: Alter warning message if transition is
 9733                    # deactivated vs. requirement not satisfied
 9734                    warnings.warn(
 9735                        (
 9736                            f"The requirements for transition"
 9737                            f" {takeTransition!r} from decision"
 9738                            f" {now.graph.identityOf(fromID)} are"
 9739                            f" not met at step {len(self) - 1} (or that"
 9740                            f" transition has been deactivated):\n{req}"
 9741                        ),
 9742                        TransitionBlockedWarning
 9743                    )
 9744
 9745                # Apply transition consequences to our new state and
 9746                # figure out if we need to skip our normal update or not
 9747                finalDest = self.applyTransitionConsequence(
 9748                    fromID,
 9749                    (takeTransition, outcomes),
 9750                    moveWhich,
 9751                    challengePolicy
 9752                )
 9753
 9754            # Check moveInDomain
 9755            destDomain = newGraph.domainFor(destID)
 9756            if moveInDomain is not None and moveInDomain != destDomain:
 9757                raise ImpossibleActionError(
 9758                    f"Invalid ExplorationAction: move specified"
 9759                    f" domain {repr(moveInDomain)} as the domain of"
 9760                    f" the focal point to move, but the destination"
 9761                    f" of the move is {now.graph.identityOf(destID)}"
 9762                    f" which is in domain {repr(destDomain)}, so focal"
 9763                    f" point {repr(moveWhich)} cannot be moved there."
 9764                )
 9765
 9766            # Now that we know where we're going, update position
 9767            # information (assuming it wasn't already set):
 9768            if finalDest is None:
 9769                finalDest = destID
 9770                base.updatePosition(
 9771                    updated,
 9772                    destID,
 9773                    cSpec,
 9774                    moveWhich
 9775                )
 9776
 9777            destIDs.add(finalDest)
 9778
 9779        elif action[0] == "focus":
 9780            # Figure out target context
 9781            action = cast(
 9782                Tuple[
 9783                    Literal['focus'],
 9784                    base.ContextSpecifier,
 9785                    Set[base.Domain],
 9786                    Set[base.Domain]
 9787                ],
 9788                action
 9789            )
 9790            contextSpecifier: base.ContextSpecifier = action[1]
 9791            if contextSpecifier == 'common':
 9792                targetContext = newState['common']
 9793            else:
 9794                targetContext = newState['contexts'][
 9795                    newState['activeContext']
 9796                ]
 9797
 9798            # Just need to swap out active domains
 9799            goingOut, comingIn = cast(
 9800                Tuple[Set[base.Domain], Set[base.Domain]],
 9801                action[2:]
 9802            )
 9803            if (
 9804                not isinstance(goingOut, set)
 9805             or not isinstance(comingIn, set)
 9806             or not all(isinstance(d, base.Domain) for d in goingOut)
 9807             or not all(isinstance(d, base.Domain) for d in comingIn)
 9808            ):
 9809                raise InvalidActionError(
 9810                    f"Invalid ExplorationAction tuple (must have 4"
 9811                    f" parts if the first part is 'focus' and"
 9812                    f" the third and fourth parts must be sets of"
 9813                    f" domains):"
 9814                    f"\n{repr(action)}"
 9815                )
 9816            activeSet = targetContext['activeDomains']
 9817            for dom in goingOut:
 9818                try:
 9819                    activeSet.remove(dom)
 9820                except KeyError:
 9821                    warnings.warn(
 9822                        (
 9823                            f"Domain {repr(dom)} was deactivated at"
 9824                            f" step {len(self)} but it was already"
 9825                            f" inactive at that point."
 9826                        ),
 9827                        InactiveDomainWarning
 9828                    )
 9829            # TODO: Also warn for doubly-activated domains?
 9830            activeSet |= comingIn
 9831
 9832            # destIDs remains empty in this case
 9833
 9834        elif action[0] == 'swap':  # update which `FocalContext` is active
 9835            newContext = cast(base.FocalContextName, action[1])
 9836            if newContext not in newState['contexts']:
 9837                raise MissingFocalContextError(
 9838                    f"'swap' action with target {repr(newContext)} is"
 9839                    f" invalid because no context with that name"
 9840                    f" exists."
 9841                )
 9842            newState['activeContext'] = newContext
 9843
 9844            # destIDs remains empty in this case
 9845
 9846        elif action[0] == 'focalize':  # create new `FocalContext`
 9847            newContext = cast(base.FocalContextName, action[1])
 9848            if newContext in newState['contexts']:
 9849                raise FocalContextCollisionError(
 9850                    f"'focalize' action with target {repr(newContext)}"
 9851                    f" is invalid because a context with that name"
 9852                    f" already exists."
 9853                )
 9854            newState['contexts'][newContext] = base.emptyFocalContext()
 9855            newState['activeContext'] = newContext
 9856
 9857            # destIDs remains empty in this case
 9858
 9859        # revertTo is handled above
 9860        else:
 9861            raise InvalidActionError(
 9862                f"Invalid ExplorationAction tuple (first item must be"
 9863                f" an ExplorationActionType, and tuple must be length-1"
 9864                f" if the action type is 'noAction'):"
 9865                f"\n{repr(action)}"
 9866            )
 9867
 9868        # Apply any active triggers
 9869        followTo = self.applyActiveTriggers()
 9870        if followTo is not None:
 9871            destIDs.add(followTo)
 9872            # TODO: Re-work to work with multiple position updates in
 9873            # different focal contexts, domains, and/or for different
 9874            # focal points in plural-focalized domains.
 9875
 9876        return (updated, destIDs)
 9877
 9878    def applyActiveTriggers(self) -> Optional[base.DecisionID]:
 9879        """
 9880        Finds all actions with the 'trigger' tag attached to currently
 9881        active decisions, and applies their effects if their requirements
 9882        are met (ordered by decision-ID with ties broken alphabetically
 9883        by action name).
 9884
 9885        'bounce', 'goto' and 'follow' effects may apply. However, any
 9886        new triggers that would be activated because of decisions
 9887        reached by such effects will not apply. Note that 'bounce'
 9888        effects update position to the decision where the action was
 9889        attached, which is usually a no-op. This function returns the
 9890        decision ID of the decision reached by the last decision-moving
 9891        effect applied, or `None` if no such effects triggered.
 9892
 9893        TODO: What about situations where positions are updated in
 9894        multiple domains or multiple foal points in a plural domain are
 9895        independently updated?
 9896
 9897        TODO: Tests for this!
 9898        """
 9899        active = self.getActiveDecisions()
 9900        now = self.getSituation()
 9901        graph = now.graph
 9902        finalFollow = None
 9903        for decision in sorted(active):
 9904            for action in graph.decisionActions(decision):
 9905                if (
 9906                    'trigger' in graph.transitionTags(decision, action)
 9907                and self.isTraversable(decision, action)
 9908                ):
 9909                    followTo = self.applyTransitionConsequence(
 9910                        decision,
 9911                        action
 9912                    )
 9913                    if followTo is not None:
 9914                        # TODO: How will triggers interact with
 9915                        # plural-focalized domains? Probably need to fix
 9916                        # this to detect moveWhich based on which focal
 9917                        # points are at the decision where the transition
 9918                        # is, and then apply this to each of them?
 9919                        base.updatePosition(now, followTo)
 9920                        finalFollow = followTo
 9921
 9922        return finalFollow
 9923
 9924    def explore(
 9925        self,
 9926        transition: base.AnyTransition,
 9927        destination: Union[base.DecisionName, base.DecisionID, None],
 9928        reciprocal: Optional[base.Transition] = None,
 9929        zone: Optional[base.Zone] = base.DefaultZone,
 9930        fromDecision: Optional[base.AnyDecisionSpecifier] = None,
 9931        whichFocus: Optional[base.FocalPointSpecifier] = None,
 9932        inCommon: Union[bool, Literal["auto"]] = "auto",
 9933        decisionType: base.DecisionType = "active",
 9934        challengePolicy: base.ChallengePolicy = "specified"
 9935    ) -> base.DecisionID:
 9936        """
 9937        Adds a new situation to the exploration representing the
 9938        traversal of the specified transition (possibly with outcomes
 9939        specified for challenges among that transitions consequences).
 9940        Uses `deduceTransitionDetailsAtStep` to figure out from the
 9941        transition name which specific transition is taken (and which
 9942        focal point is updated if necessary). This uses the
 9943        `fromDecision`, `whichFocus`, and `inCommon` optional
 9944        parameters, and also determines whether to update the common or
 9945        the active `FocalContext`. Sets the exploration status of the
 9946        decision explored to 'exploring'. Returns the decision ID for
 9947        the destination reached, accounting for goto/bounce/follow
 9948        effects that might have triggered.
 9949
 9950        The `destination` will be used to name the newly-explored
 9951        decision, except when it's a `DecisionID`, in which case that
 9952        decision must be unvisited, and we'll connect the specified
 9953        transition to that decision.
 9954
 9955        The focalization of the destination domain in the context to be
 9956        updated determines how active decisions are changed:
 9957
 9958        - If the destination domain is focalized as 'single', then in
 9959            the subsequent `Situation`, the destination decision will
 9960            become the single active decision in that domain.
 9961        - If it's focalized as 'plural', then one of the
 9962            `FocalPointName`s for that domain will be moved to activate
 9963            that decision; which one can be specified using `whichFocus`
 9964            or if left unspecified, will be deduced: if the starting
 9965            decision is in the same domain, then the
 9966            alphabetically-earliest focal point which is at the starting
 9967            decision will be moved. If the starting position is in a
 9968            different domain, then the alphabetically earliest focal
 9969            point among all focal points in the destination domain will
 9970            be moved.
 9971        - If it's focalized as 'spreading', then the destination
 9972            decision will be added to the set of active decisions in
 9973            that domain, without removing any.
 9974
 9975        The transition named must have been pointing to an unvisited
 9976        decision (see `hasBeenVisited`), and the name of that decision
 9977        will be updated if a `destination` value is given (a
 9978        `DecisionCollisionWarning` will be issued if the destination
 9979        name is a duplicate of another name in the graph, although this
 9980        is not an error). Additionally:
 9981
 9982        - If a `reciprocal` name is specified, the reciprocal transition
 9983            will be renamed using that name, or created with that name if
 9984            it didn't already exist. If reciprocal is left as `None` (the
 9985            default) then no change will be made to the reciprocal
 9986            transition, and it will not be created if it doesn't exist.
 9987        - If a `zone` is specified, the newly-explored decision will be
 9988            added to that zone (and that zone will be created at level 0
 9989            if it didn't already exist). If `zone` is set to `None` then
 9990            it will not be added to any new zones. If `zone` is left as
 9991            the default (the `base.DefaultZone` value) then the explored
 9992            decision will be added to each zone that the decision it was
 9993            explored from is a part of. If a zone needs to be created,
 9994            that zone will be added as a sub-zone of each zone which is a
 9995            parent of a zone that directly contains the origin decision.
 9996        - An `ExplorationStatusError` will be raised if the specified
 9997            transition leads to a decision whose `ExplorationStatus` is
 9998            'exploring' or higher (i.e., `hasBeenVisited`). (Use
 9999            `returnTo` instead to adjust things when a transition to an
10000            unknown destination turns out to lead to an already-known
10001            destination.)
10002        - A `TransitionBlockedWarning` will be issued if the specified
10003            transition is not traversable given the current game state
10004            (but in that last case the step will still be taken).
10005        - By default, the decision type for the new step will be
10006            'active', but a `decisionType` value can be specified to
10007            override that.
10008        - By default, the 'mostLikely' `ChallengePolicy` will be used to
10009            resolve challenges in the consequence of the transition
10010            taken, but an alternate policy can be supplied using the
10011            `challengePolicy` argument.
10012        """
10013        now = self.getSituation()
10014
10015        transitionName, outcomes = base.nameAndOutcomes(transition)
10016
10017        # Deduce transition details from the name + optional specifiers
10018        (
10019            using,
10020            fromID,
10021            destID,
10022            whichFocus
10023        ) = self.deduceTransitionDetailsAtStep(
10024            -1,
10025            transitionName,
10026            fromDecision,
10027            whichFocus,
10028            inCommon
10029        )
10030
10031        # Issue a warning if the destination name is already in use
10032        if destination is not None:
10033            if isinstance(destination, base.DecisionName):
10034                try:
10035                    existingID = now.graph.resolveDecision(destination)
10036                    collision = existingID != destID
10037                except MissingDecisionError:
10038                    collision = False
10039                except AmbiguousDecisionSpecifierError:
10040                    collision = True
10041
10042                if collision and WARN_OF_NAME_COLLISIONS:
10043                    warnings.warn(
10044                        (
10045                            f"The destination name {repr(destination)} is"
10046                            f" already in use when exploring transition"
10047                            f" {repr(transition)} from decision"
10048                            f" {now.graph.identityOf(fromID)} at step"
10049                            f" {len(self) - 1}."
10050                        ),
10051                        DecisionCollisionWarning
10052                    )
10053
10054        # TODO: Different terminology for "exploration state above
10055        # noticed" vs. "DG thinks it's been visited"...
10056        if (
10057            self.hasBeenVisited(destID)
10058        ):
10059            raise ExplorationStatusError(
10060                f"Cannot explore to decision"
10061                f" {now.graph.identityOf(destID)} because it has"
10062                f" already been visited. Use returnTo instead of"
10063                f" explore when discovering a connection back to a"
10064                f" previously-explored decision."
10065            )
10066
10067        if (
10068            isinstance(destination, base.DecisionID)
10069        and self.hasBeenVisited(destination)
10070        ):
10071            raise ExplorationStatusError(
10072                f"Cannot explore to decision"
10073                f" {now.graph.identityOf(destination)} because it has"
10074                f" already been visited. Use returnTo instead of"
10075                f" explore when discovering a connection back to a"
10076                f" previously-explored decision."
10077            )
10078
10079        actionTaken: base.ExplorationAction = (
10080            'explore',
10081            using,
10082            fromID,
10083            (transitionName, outcomes),
10084            destination,
10085            reciprocal,
10086            zone
10087        )
10088        if whichFocus is not None:
10089            # A move-from-specific-focal-point action
10090            actionTaken = (
10091                'explore',
10092                whichFocus,
10093                (transitionName, outcomes),
10094                destination,
10095                reciprocal,
10096                zone
10097            )
10098
10099        # Advance the situation, applying transition effects and
10100        # updating the destination decision.
10101        _, finalDest = self.advanceSituation(
10102            actionTaken,
10103            decisionType,
10104            challengePolicy
10105        )
10106
10107        # TODO: Is this assertion always valid?
10108        assert len(finalDest) == 1
10109        return next(x for x in finalDest)
10110
10111    def returnTo(
10112        self,
10113        transition: base.AnyTransition,
10114        destination: base.AnyDecisionSpecifier,
10115        reciprocal: Optional[base.Transition] = None,
10116        fromDecision: Optional[base.AnyDecisionSpecifier] = None,
10117        whichFocus: Optional[base.FocalPointSpecifier] = None,
10118        inCommon: Union[bool, Literal["auto"]] = "auto",
10119        decisionType: base.DecisionType = "active",
10120        challengePolicy: base.ChallengePolicy = "specified"
10121    ) -> base.DecisionID:
10122        """
10123        Adds a new graph to the exploration that replaces the given
10124        transition at the current position (which must lead to an unknown
10125        node, or a `MissingDecisionError` will result). The new
10126        transition will connect back to the specified destination, which
10127        must already exist (or a different `ValueError` will be raised).
10128        Returns the decision ID for the destination reached.
10129
10130        Deduces transition details using the optional `fromDecision`,
10131        `whichFocus`, and `inCommon` arguments in addition to the
10132        `transition` value; see `deduceTransitionDetailsAtStep`.
10133
10134        If a `reciprocal` transition is specified, that transition must
10135        either not already exist in the destination decision or lead to
10136        an unknown region; it will be replaced (or added) as an edge
10137        leading back to the current position.
10138
10139        The `decisionType` and `challengePolicy` optional arguments are
10140        used for `advanceSituation`.
10141
10142        A `TransitionBlockedWarning` will be issued if the requirements
10143        for the transition are not met, but the step will still be taken.
10144        Raises a `MissingDecisionError` if there is no current
10145        transition.
10146        """
10147        now = self.getSituation()
10148
10149        transitionName, outcomes = base.nameAndOutcomes(transition)
10150
10151        # Deduce transition details from the name + optional specifiers
10152        (
10153            using,
10154            fromID,
10155            destID,
10156            whichFocus
10157        ) = self.deduceTransitionDetailsAtStep(
10158            -1,
10159            transitionName,
10160            fromDecision,
10161            whichFocus,
10162            inCommon
10163        )
10164
10165        # Replace with connection to existing destination
10166        destID = now.graph.resolveDecision(destination)
10167        if not self.hasBeenVisited(destID):
10168            raise ExplorationStatusError(
10169                f"Cannot return to decision"
10170                f" {now.graph.identityOf(destID)} because it has NOT"
10171                f" already been at least partially explored. Use"
10172                f" explore instead of returnTo when discovering a"
10173                f" connection to a previously-unexplored decision."
10174            )
10175
10176        now.graph.replaceUnconfirmed(
10177            fromID,
10178            transitionName,
10179            destID,
10180            reciprocal
10181        )
10182
10183        # A move-from-decision action
10184        actionTaken: base.ExplorationAction = (
10185            'take',
10186            using,
10187            fromID,
10188            (transitionName, outcomes)
10189        )
10190        if whichFocus is not None:
10191            # A move-from-specific-focal-point action
10192            actionTaken = ('take', whichFocus, (transitionName, outcomes))
10193
10194        # Next, advance the situation, applying transition effects
10195        _, finalDest = self.advanceSituation(
10196            actionTaken,
10197            decisionType,
10198            challengePolicy
10199        )
10200
10201        assert len(finalDest) == 1
10202        return next(x for x in finalDest)
10203
10204    def takeAction(
10205        self,
10206        action: base.AnyTransition,
10207        requires: Optional[base.Requirement] = None,
10208        consequence: Optional[base.Consequence] = None,
10209        fromDecision: Optional[base.AnyDecisionSpecifier] = None,
10210        whichFocus: Optional[base.FocalPointSpecifier] = None,
10211        inCommon: Union[bool, Literal["auto"]] = "auto",
10212        decisionType: base.DecisionType = "active",
10213        challengePolicy: base.ChallengePolicy = "specified"
10214    ) -> base.DecisionID:
10215        """
10216        Adds a new graph to the exploration based on taking the given
10217        action, which must be a self-transition in the graph. If the
10218        action does not already exist in the graph, it will be created.
10219        Either way if requirements and/or a consequence are supplied,
10220        the requirements and consequence of the action will be updated
10221        to match them, and those are the requirements/consequence that
10222        will count.
10223
10224        Returns the decision ID for the decision reached, which normally
10225        is the same action you were just at, but which might be altered
10226        by goto, bounce, and/or follow effects.
10227
10228        Issues a `TransitionBlockedWarning` if the current game state
10229        doesn't satisfy the requirements for the action.
10230
10231        The `fromDecision`, `whichFocus`, and `inCommon` arguments are
10232        used for `deduceTransitionDetailsAtStep`, while `decisionType`
10233        and `challengePolicy` are used for `advanceSituation`.
10234
10235        When an action is being created, `fromDecision` (or
10236        `whichFocus`) must be specified, since the source decision won't
10237        be deducible from the transition name. Note that if a transition
10238        with the given name exists from *any* active decision, it will
10239        be used instead of creating a new action (possibly resulting in
10240        an error if it's not a self-loop transition). Also, you may get
10241        an `AmbiguousTransitionError` if several transitions with that
10242        name exist; in that case use `fromDecision` and/or `whichFocus`
10243        to disambiguate.
10244        """
10245        now = self.getSituation()
10246        graph = now.graph
10247
10248        actionName, outcomes = base.nameAndOutcomes(action)
10249
10250        try:
10251            (
10252                using,
10253                fromID,
10254                destID,
10255                whichFocus
10256            ) = self.deduceTransitionDetailsAtStep(
10257                -1,
10258                actionName,
10259                fromDecision,
10260                whichFocus,
10261                inCommon
10262            )
10263
10264            if destID != fromID:
10265                raise ValueError(
10266                    f"Cannot take action {repr(action)} because it's a"
10267                    f" transition to another decision, not an action"
10268                    f" (use explore, returnTo, and/or retrace instead)."
10269                )
10270
10271        except MissingTransitionError:
10272            using = 'active'
10273            if inCommon is True:
10274                using = 'common'
10275
10276            if fromDecision is not None:
10277                fromID = graph.resolveDecision(fromDecision)
10278            elif whichFocus is not None:
10279                maybeFromID = base.resolvePosition(now, whichFocus)
10280                if maybeFromID is None:
10281                    raise MissingDecisionError(
10282                        f"Focal point {repr(whichFocus)} was specified"
10283                        f" in takeAction but that focal point doesn't"
10284                        f" have a position."
10285                    )
10286                else:
10287                    fromID = maybeFromID
10288            else:
10289                raise AmbiguousTransitionError(
10290                    f"Taking action {repr(action)} is ambiguous because"
10291                    f" the source decision has not been specified via"
10292                    f" either fromDecision or whichFocus, and we"
10293                    f" couldn't find an existing action with that name."
10294                )
10295
10296            # Since the action doesn't exist, add it:
10297            graph.addAction(fromID, actionName, requires, consequence)
10298
10299        # Update the transition requirement/consequence if requested
10300        # (before the action is taken)
10301        if requires is not None:
10302            graph.setTransitionRequirement(fromID, actionName, requires)
10303        if consequence is not None:
10304            graph.setConsequence(fromID, actionName, consequence)
10305
10306        # A move-from-decision action
10307        actionTaken: base.ExplorationAction = (
10308            'take',
10309            using,
10310            fromID,
10311            (actionName, outcomes)
10312        )
10313        if whichFocus is not None:
10314            # A move-from-specific-focal-point action
10315            actionTaken = ('take', whichFocus, (actionName, outcomes))
10316
10317        _, finalDest = self.advanceSituation(
10318            actionTaken,
10319            decisionType,
10320            challengePolicy
10321        )
10322
10323        assert len(finalDest) in (0, 1)
10324        if len(finalDest) == 1:
10325            return next(x for x in finalDest)
10326        else:
10327            return fromID
10328
10329    def retrace(
10330        self,
10331        transition: base.AnyTransition,
10332        fromDecision: Optional[base.AnyDecisionSpecifier] = None,
10333        whichFocus: Optional[base.FocalPointSpecifier] = None,
10334        inCommon: Union[bool, Literal["auto"]] = "auto",
10335        decisionType: base.DecisionType = "active",
10336        challengePolicy: base.ChallengePolicy = "specified"
10337    ) -> base.DecisionID:
10338        """
10339        Adds a new graph to the exploration based on taking the given
10340        transition, which must already exist and which must not lead to
10341        an unknown region. Returns the ID of the destination decision,
10342        accounting for goto, bounce, and/or follow effects.
10343
10344        Issues a `TransitionBlockedWarning` if the current game state
10345        doesn't satisfy the requirements for the transition.
10346
10347        The `fromDecision`, `whichFocus`, and `inCommon` arguments are
10348        used for `deduceTransitionDetailsAtStep`, while `decisionType`
10349        and `challengePolicy` are used for `advanceSituation`.
10350        """
10351        now = self.getSituation()
10352
10353        transitionName, outcomes = base.nameAndOutcomes(transition)
10354
10355        (
10356            using,
10357            fromID,
10358            destID,
10359            whichFocus
10360        ) = self.deduceTransitionDetailsAtStep(
10361            -1,
10362            transitionName,
10363            fromDecision,
10364            whichFocus,
10365            inCommon
10366        )
10367
10368        visited = self.hasBeenVisited(destID)
10369        confirmed = now.graph.isConfirmed(destID)
10370        if not confirmed:
10371            raise ExplorationStatusError(
10372                f"Cannot retrace transition {transition!r} from"
10373                f" decision {now.graph.identityOf(fromID)} because it"
10374                f" leads to an unconfirmed decision.\nUse"
10375                f" `DiscreteExploration.explore` and provide"
10376                f" destination decision details instead."
10377            )
10378        if not visited:
10379            raise ExplorationStatusError(
10380                f"Cannot retrace transition {transition!r} from"
10381                f" decision {now.graph.identityOf(fromID)} because it"
10382                f" leads to an unvisited decision.\nUse"
10383                f" `DiscreteExploration.explore` and provide"
10384                f" destination decision details instead."
10385            )
10386
10387        # A move-from-decision action
10388        actionTaken: base.ExplorationAction = (
10389            'take',
10390            using,
10391            fromID,
10392            (transitionName, outcomes)
10393        )
10394        if whichFocus is not None:
10395            # A move-from-specific-focal-point action
10396            actionTaken = ('take', whichFocus, (transitionName, outcomes))
10397
10398        _, finalDest = self.advanceSituation(
10399            actionTaken,
10400            decisionType,
10401        challengePolicy
10402    )
10403
10404        assert len(finalDest) == 1
10405        return next(x for x in finalDest)
10406
10407    def warp(
10408        self,
10409        destination: base.AnyDecisionSpecifier,
10410        consequence: Optional[base.Consequence] = None,
10411        domain: Optional[base.Domain] = None,
10412        zone: Optional[base.Zone] = base.DefaultZone,
10413        whichFocus: Optional[base.FocalPointSpecifier] = None,
10414        inCommon: Union[bool] = False,
10415        decisionType: base.DecisionType = "active",
10416        challengePolicy: base.ChallengePolicy = "specified"
10417    ) -> base.DecisionID:
10418        """
10419        Adds a new graph to the exploration that's a copy of the current
10420        graph, with the position updated to be at the destination without
10421        actually creating a transition from the old position to the new
10422        one. Returns the ID of the decision warped to (accounting for
10423        any goto or follow effects triggered).
10424
10425        Any provided consequences are applied, but are not associated
10426        with any transition (so any delays and charges are ignored, and
10427        'bounce' effects don't actually cancel the warp). 'goto' or
10428        'follow' effects might change the warp destination; 'follow'
10429        effects take the original destination as their starting point.
10430        Any mechanisms mentioned in extra consequences will be found
10431        based on the destination. Outcomes in supplied challenges should
10432        be pre-specified, or else they will be resolved with the
10433        `challengePolicy`.
10434
10435        `whichFocus` may be specified when the destination domain's
10436        focalization is 'plural' but for 'singular' or 'spreading'
10437        destination domains it is not allowed. `inCommon` determines
10438        whether the common or the active focal context is updated
10439        (default is to update the active context). The `decisionType`
10440        and `challengePolicy` are used for `advanceSituation`.
10441
10442        - If the destination did not already exist, it will be created.
10443            Initially, it will be disconnected from all other decisions.
10444            In this case, the `domain` value can be used to put it in a
10445            non-default domain.
10446        - The position is set to the specified destination, and if a
10447            `consequence` is specified it is applied. Note that
10448            'deactivate' effects are NOT allowed, and 'edit' effects
10449            must establish their own transition target because there is
10450            no transition that the effects are being applied to.
10451        - If the destination had been unexplored, its exploration status
10452            will be set to 'exploring'.
10453        - If a `zone` is specified, the destination will be added to that
10454            zone (even if the destination already existed) and that zone
10455            will be created (as a level-0 zone) if need be. If `zone` is
10456            set to `None`, then no zone will be applied. If `zone` is
10457            left as the default (`base.DefaultZone`) and the
10458            focalization of the destination domain is 'singular' or
10459            'plural' and the destination is newly created and there is
10460            an origin and the origin is in the same domain as the
10461            destination, then the destination will be added to all zones
10462            that the origin was a part of if the destination is newly
10463            created, but otherwise the destination will not be added to
10464            any zones. If the specified zone has to be created and
10465            there's an origin decision, it will be added as a sub-zone
10466            to all parents of zones directly containing the origin, as
10467            long as the origin is in the same domain as the destination.
10468        """
10469        now = self.getSituation()
10470        graph = now.graph
10471
10472        fromID: Optional[base.DecisionID]
10473
10474        new = False
10475        try:
10476            destID = graph.resolveDecision(destination)
10477        except MissingDecisionError:
10478            if isinstance(destination, tuple):
10479                # just the name; ignore zone/domain
10480                destination = destination[-1]
10481
10482            if not isinstance(destination, base.DecisionName):
10483                raise TypeError(
10484                    f"Warp destination {repr(destination)} does not"
10485                    f" exist, and cannot be created as it is not a"
10486                    f" decision name."
10487                )
10488            destID = graph.addDecision(destination, domain)
10489            graph.tagDecision(destID, 'unconfirmed')
10490            self.setExplorationStatus(destID, 'unknown')
10491            new = True
10492
10493        using: base.ContextSpecifier
10494        if inCommon:
10495            targetContext = self.getCommonContext()
10496            using = "common"
10497        else:
10498            targetContext = self.getActiveContext()
10499            using = "active"
10500
10501        destDomain = graph.domainFor(destID)
10502        targetFocalization = base.getDomainFocalization(
10503            targetContext,
10504            destDomain
10505        )
10506        if targetFocalization == 'singular':
10507            targetActive = targetContext['activeDecisions']
10508            if destDomain in targetActive:
10509                fromID = cast(
10510                    base.DecisionID,
10511                    targetContext['activeDecisions'][destDomain]
10512                )
10513            else:
10514                fromID = None
10515        elif targetFocalization == 'plural':
10516            if whichFocus is None:
10517                raise AmbiguousTransitionError(
10518                    f"Warping to {repr(destination)} is ambiguous"
10519                    f" becuase domain {repr(destDomain)} has plural"
10520                    f" focalization, and no whichFocus value was"
10521                    f" specified."
10522                )
10523
10524            fromID = base.resolvePosition(
10525                self.getSituation(),
10526                whichFocus
10527            )
10528        else:
10529            fromID = None
10530
10531        # Handle zones
10532        if zone == base.DefaultZone:
10533            if (
10534                new
10535            and fromID is not None
10536            and graph.domainFor(fromID) == destDomain
10537            ):
10538                for prevZone in graph.zoneParents(fromID):
10539                    graph.addDecisionToZone(destination, prevZone)
10540            # Otherwise don't update zones
10541        elif zone is not None:
10542            # Newness is ignored when a zone is specified
10543            zone = cast(base.Zone, zone)
10544            # Create the zone at level 0 if it didn't already exist
10545            if graph.getZoneInfo(zone) is None:
10546                graph.createZone(zone, 0)
10547                # Add the newly created zone to each 2nd-level parent of
10548                # the previous decision if there is one and it's in the
10549                # same domain
10550                if (
10551                    fromID is not None
10552                and graph.domainFor(fromID) == destDomain
10553                ):
10554                    for prevZone in graph.zoneParents(fromID):
10555                        for prevUpper in graph.zoneParents(prevZone):
10556                            graph.addZoneToZone(zone, prevUpper)
10557            # Finally add the destination to the (maybe new) zone
10558            graph.addDecisionToZone(destID, zone)
10559        # else don't touch zones
10560
10561        # Encode the action taken
10562        actionTaken: base.ExplorationAction
10563        if whichFocus is None:
10564            actionTaken = (
10565                'warp',
10566                using,
10567                destID
10568            )
10569        else:
10570            actionTaken = (
10571                'warp',
10572                whichFocus,
10573                destID
10574            )
10575
10576        # Advance the situation
10577        _, finalDests = self.advanceSituation(
10578            actionTaken,
10579            decisionType,
10580            challengePolicy
10581        )
10582        now = self.getSituation()  # updating just in case
10583
10584        assert len(finalDests) == 1
10585        finalDest = next(x for x in finalDests)
10586
10587        # Apply additional consequences:
10588        if consequence is not None:
10589            altDest = self.applyExtraneousConsequence(
10590                consequence,
10591                where=(destID, None),
10592                # TODO: Mechanism search from both ends?
10593                moveWhich=(
10594                    whichFocus[-1]
10595                    if whichFocus is not None
10596                    else None
10597                )
10598            )
10599            if altDest is not None:
10600                finalDest = altDest
10601            now = self.getSituation()  # updating just in case
10602
10603        return finalDest
10604
10605    def wait(
10606        self,
10607        consequence: Optional[base.Consequence] = None,
10608        decisionType: base.DecisionType = "active",
10609        challengePolicy: base.ChallengePolicy = "specified"
10610    ) -> Optional[base.DecisionID]:
10611        """
10612        Adds a wait step. If a consequence is specified, it is applied,
10613        although it will not have any position/transition information
10614        available during resolution/application.
10615
10616        A decision type other than "active" and/or a challenge policy
10617        other than "specified" can be included (see `advanceSituation`).
10618
10619        The "pending" decision type may not be used, a `ValueError` will
10620        result. This allows None as the action for waiting while
10621        preserving the pending/None type/action combination for
10622        unresolved situations.
10623
10624        If a goto or follow effect in the applied consequence implies a
10625        position update, this will return the new destination ID;
10626        otherwise it will return `None`. Triggering a 'bounce' effect
10627        will be an error, because there is no position information for
10628        the effect.
10629        """
10630        if decisionType == "pending":
10631            raise ValueError(
10632                "The 'pending' decision type may not be used for"
10633                " wait actions."
10634            )
10635        self.advanceSituation(('noAction',), decisionType, challengePolicy)
10636        now = self.getSituation()
10637        if consequence is not None:
10638            if challengePolicy != "specified":
10639                base.resetChallengeOutcomes(consequence)
10640            observed = base.observeChallengeOutcomes(
10641                base.RequirementContext(
10642                    state=now.state,
10643                    graph=now.graph,
10644                    searchFrom=set()
10645                ),
10646                consequence,
10647                location=None,  # No position info
10648                policy=challengePolicy,
10649                knownOutcomes=None  # bake outcomes into the consequence
10650            )
10651            # No location information since we might have multiple
10652            # active decisions and there's no indication of which one
10653            # we're "waiting at."
10654            finalDest = self.applyExtraneousConsequence(observed)
10655            now = self.getSituation()  # updating just in case
10656
10657            return finalDest
10658        else:
10659            return None
10660
10661    def revert(
10662        self,
10663        slot: base.SaveSlot = base.DEFAULT_SAVE_SLOT,
10664        aspects: Optional[Set[str]] = None,
10665        decisionType: base.DecisionType = "active"
10666    ) -> None:
10667        """
10668        Reverts the game state to a previously-saved game state (saved
10669        via a 'save' effect). The save slot name and set of aspects to
10670        revert are required. By default, all aspects except the graph
10671        are reverted.
10672        """
10673        if aspects is None:
10674            aspects = set()
10675
10676        action: base.ExplorationAction = ("revertTo", slot, aspects)
10677
10678        self.advanceSituation(action, decisionType)
10679
10680    def observeAll(
10681        self,
10682        where: base.AnyDecisionSpecifier,
10683        *transitions: Union[
10684            base.Transition,
10685            Tuple[base.Transition, base.AnyDecisionSpecifier],
10686            Tuple[
10687                base.Transition,
10688                base.AnyDecisionSpecifier,
10689                base.Transition
10690            ]
10691        ]
10692    ) -> List[base.DecisionID]:
10693        """
10694        Observes one or more new transitions, applying changes to the
10695        current graph. The transitions can be specified in one of three
10696        ways:
10697
10698        1. A transition name. The transition will be created and will
10699            point to a new unexplored node.
10700        2. A pair containing a transition name and a destination
10701            specifier. If the destination does not exist it will be
10702            created as an unexplored node, although in that case the
10703            decision specifier may not be an ID.
10704        3. A triple containing a transition name, a destination
10705            specifier, and a reciprocal name. Works the same as the pair
10706            case but also specifies the name for the reciprocal
10707            transition.
10708
10709        The new transitions are outgoing from specified decision.
10710
10711        Yields the ID of each decision connected to, whether those are
10712        new or existing decisions.
10713        """
10714        now = self.getSituation()
10715        fromID = now.graph.resolveDecision(where)
10716        result = []
10717        for entry in transitions:
10718            if isinstance(entry, base.Transition):
10719                result.append(self.observe(fromID, entry))
10720            else:
10721                result.append(self.observe(fromID, *entry))
10722        return result
10723
10724    def observe(
10725        self,
10726        where: base.AnyDecisionSpecifier,
10727        transition: base.Transition,
10728        destination: Optional[base.AnyDecisionSpecifier] = None,
10729        reciprocal: Optional[base.Transition] = None
10730    ) -> base.DecisionID:
10731        """
10732        Observes a single new outgoing transition from the specified
10733        decision. If specified the transition connects to a specific
10734        destination and/or has a specific reciprocal. The specified
10735        destination will be created if it doesn't exist, or where no
10736        destination is specified, a new unexplored decision will be
10737        added. The ID of the decision connected to is returned.
10738
10739        Sets the exploration status of the observed destination to
10740        "noticed" if a destination is specified and needs to be created
10741        (but not when no destination is specified).
10742
10743        For example:
10744
10745        >>> e = DiscreteExploration()
10746        >>> e.start('start')
10747        0
10748        >>> e.observe('start', 'up')
10749        1
10750        >>> g = e.getSituation().graph
10751        >>> g.destinationsFrom('start')
10752        {'up': 1}
10753        >>> e.getExplorationStatus(1)  # not given a name: assumed unknown
10754        'unknown'
10755        >>> e.observe('start', 'left', 'A')
10756        2
10757        >>> g.destinationsFrom('start')
10758        {'up': 1, 'left': 2}
10759        >>> g.nameFor(2)
10760        'A'
10761        >>> e.getExplorationStatus(2)  # given a name: noticed
10762        'noticed'
10763        >>> e.observe('start', 'up2', 1)
10764        1
10765        >>> g.destinationsFrom('start')
10766        {'up': 1, 'left': 2, 'up2': 1}
10767        >>> e.getExplorationStatus(1)  # existing decision: status unchanged
10768        'unknown'
10769        >>> e.observe('start', 'right', 'B', 'left')
10770        3
10771        >>> g.destinationsFrom('start')
10772        {'up': 1, 'left': 2, 'up2': 1, 'right': 3}
10773        >>> g.nameFor(3)
10774        'B'
10775        >>> e.getExplorationStatus(3)  # new + name -> noticed
10776        'noticed'
10777        >>> e.observe('start', 'right')  # repeat transition name
10778        Traceback (most recent call last):
10779        ...
10780        exploration.core.TransitionCollisionError...
10781        >>> e.observe('start', 'right2', 'B', 'left')  # repeat reciprocal
10782        Traceback (most recent call last):
10783        ...
10784        exploration.core.TransitionCollisionError...
10785        >>> g = e.getSituation().graph
10786        >>> g.createZone('Z', 0)
10787        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
10788 annotations=[])
10789        >>> g.addDecisionToZone('start', 'Z')
10790        >>> e.observe('start', 'down', 'C', 'up')
10791        4
10792        >>> g.destinationsFrom('start')
10793        {'up': 1, 'left': 2, 'up2': 1, 'right': 3, 'down': 4}
10794        >>> g.identityOf('C')
10795        '4 (C)'
10796        >>> g.zoneParents(4)  # not in any zones, 'cause still unexplored
10797        set()
10798        >>> e.observe(
10799        ...     'C',
10800        ...     'right',
10801        ...     base.DecisionSpecifier('main', 'Z2', 'D'),
10802        ... )  # creates zone
10803        5
10804        >>> g.destinationsFrom('C')
10805        {'up': 0, 'right': 5}
10806        >>> g.destinationsFrom('D')  # default reciprocal name
10807        {'return': 4}
10808        >>> g.identityOf('D')
10809        '5 (Z2::D)'
10810        >>> g.zoneParents(5)
10811        {'Z2'}
10812        """
10813        now = self.getSituation()
10814        fromID = now.graph.resolveDecision(where)
10815
10816        kwargs: Dict[
10817            str,
10818            Union[base.Transition, base.DecisionName, None]
10819        ] = {}
10820        if reciprocal is not None:
10821            kwargs['reciprocal'] = reciprocal
10822
10823        if destination is not None:
10824            try:
10825                destID = now.graph.resolveDecision(destination)
10826                now.graph.addTransition(
10827                    fromID,
10828                    transition,
10829                    destID,
10830                    reciprocal
10831                )
10832                return destID
10833            except MissingDecisionError:
10834                if isinstance(destination, base.DecisionSpecifier):
10835                    kwargs['toDomain'] = destination.domain
10836                    kwargs['placeInZone'] = destination.zone
10837                    kwargs['destinationName'] = destination.name
10838                elif isinstance(destination, base.DecisionName):
10839                    kwargs['destinationName'] = destination
10840                else:
10841                    assert isinstance(destination, base.DecisionID)
10842                    # We got to except by failing to resolve, so it's an
10843                    # invalid ID
10844                    raise
10845
10846        result = now.graph.addUnexploredEdge(
10847            fromID,
10848            transition,
10849            **kwargs  # type: ignore [arg-type]
10850        )
10851        if 'destinationName' in kwargs:
10852            self.setExplorationStatus(result, 'noticed', upgradeOnly=True)
10853        return result
10854
10855    def observeMechanisms(
10856        self,
10857        where: Optional[base.AnyDecisionSpecifier],
10858        *mechanisms: Union[
10859            base.MechanismName,
10860            Tuple[base.MechanismName, base.MechanismState]
10861        ]
10862    ) -> List[base.MechanismID]:
10863        """
10864        Adds one or more mechanisms to the exploration's current graph,
10865        located at the specified decision. Global mechanisms can be
10866        added by using `None` for the location. Mechanisms are named, or
10867        a (name, state) tuple can be used to set them into a specific
10868        state. Mechanisms not set to a state will be in the
10869        `base.DEFAULT_MECHANISM_STATE`.
10870        """
10871        now = self.getSituation()
10872        result = []
10873        for mSpec in mechanisms:
10874            setState = None
10875            if isinstance(mSpec, base.MechanismName):
10876                result.append(now.graph.addMechanism(mSpec, where))
10877            elif (
10878                isinstance(mSpec, tuple)
10879            and len(mSpec) == 2
10880            and isinstance(mSpec[0], base.MechanismName)
10881            and isinstance(mSpec[1], base.MechanismState)
10882            ):
10883                result.append(now.graph.addMechanism(mSpec[0], where))
10884                setState = mSpec[1]
10885            else:
10886                raise TypeError(
10887                    f"Invalid mechanism: {repr(mSpec)} (must be a"
10888                    f" mechanism name or a (name, state) tuple."
10889                )
10890
10891            if setState:
10892                self.setMechanismStateNow(result[-1], setState)
10893
10894        return result
10895
10896    def reZone(
10897        self,
10898        zone: base.Zone,
10899        where: base.AnyDecisionSpecifier,
10900        replace: Union[base.Zone, int] = 0
10901    ) -> None:
10902        """
10903        Alters the current graph without adding a new exploration step.
10904
10905        Calls `DecisionGraph.replaceZonesInHierarchy` targeting the
10906        specified decision. Note that per the logic of that method, ALL
10907        zones at the specified hierarchy level are replaced, even if a
10908        specific zone to replace is specified here.
10909
10910        TODO: not that?
10911
10912        The level value is either specified via `replace` (default 0) or
10913        deduced from the zone provided as the `replace` value using
10914        `DecisionGraph.zoneHierarchyLevel`.
10915        """
10916        now = self.getSituation()
10917
10918        if isinstance(replace, int):
10919            level = replace
10920        else:
10921            level = now.graph.zoneHierarchyLevel(replace)
10922
10923        now.graph.replaceZonesInHierarchy(where, zone, level)
10924
10925    def runCommand(
10926        self,
10927        command: commands.Command,
10928        scope: Optional[commands.Scope] = None,
10929        line: int = -1
10930    ) -> commands.CommandResult:
10931        """
10932        Runs a single `Command` applying effects to the exploration, its
10933        current graph, and the provided execution context, and returning
10934        a command result, which contains the modified scope plus
10935        optional skip and label values (see `CommandResult`). This
10936        function also directly modifies the scope you give it. Variable
10937        references in the command are resolved via entries in the
10938        provided scope. If no scope is given, an empty one is created.
10939
10940        A line number may be supplied for use in error messages; if left
10941        out line -1 will be used.
10942
10943        Raises an error if the command is invalid.
10944
10945        For commands that establish a value as the 'current value', that
10946        value will be stored in the '_' variable. When this happens, the
10947        old contents of '_' are stored in '__' first, and the old
10948        contents of '__' are discarded. Note that non-automatic
10949        assignment to '_' does not move the old value to '__'.
10950        """
10951        try:
10952            if scope is None:
10953                scope = {}
10954
10955            skip: Union[int, str, None] = None
10956            label: Optional[str] = None
10957
10958            if command.command == 'val':
10959                command = cast(commands.LiteralValue, command)
10960                result = commands.resolveValue(command.value, scope)
10961                commands.pushCurrentValue(scope, result)
10962
10963            elif command.command == 'empty':
10964                command = cast(commands.EstablishCollection, command)
10965                collection = commands.resolveVarName(command.collection, scope)
10966                commands.pushCurrentValue(
10967                    scope,
10968                    {
10969                        'list': [],
10970                        'tuple': (),
10971                        'set': set(),
10972                        'dict': {},
10973                    }[collection]
10974                )
10975
10976            elif command.command == 'append':
10977                command = cast(commands.AppendValue, command)
10978                target = scope['_']
10979                addIt = commands.resolveValue(command.value, scope)
10980                if isinstance(target, list):
10981                    target.append(addIt)
10982                elif isinstance(target, tuple):
10983                    scope['_'] = target + (addIt,)
10984                elif isinstance(target, set):
10985                    target.add(addIt)
10986                elif isinstance(target, dict):
10987                    raise TypeError(
10988                        "'append' command cannot be used with a"
10989                        " dictionary. Use 'set' instead."
10990                    )
10991                else:
10992                    raise TypeError(
10993                        f"Invalid current value for 'append' command."
10994                        f" The current value must be a list, tuple, or"
10995                        f" set, but it was a '{type(target).__name__}'."
10996                    )
10997
10998            elif command.command == 'set':
10999                command = cast(commands.SetValue, command)
11000                target = scope['_']
11001                where = commands.resolveValue(command.location, scope)
11002                what = commands.resolveValue(command.value, scope)
11003                if isinstance(target, list):
11004                    if not isinstance(where, int):
11005                        raise TypeError(
11006                            f"Cannot set item in list: index {where!r}"
11007                            f" is not an integer."
11008                        )
11009                    target[where] = what
11010                elif isinstance(target, tuple):
11011                    if not isinstance(where, int):
11012                        raise TypeError(
11013                            f"Cannot set item in tuple: index {where!r}"
11014                            f" is not an integer."
11015                        )
11016                    if not (
11017                        0 <= where < len(target)
11018                    or -1 >= where >= -len(target)
11019                    ):
11020                        raise IndexError(
11021                            f"Cannot set item in tuple at index"
11022                            f" {where}: Tuple has length {len(target)}."
11023                        )
11024                    scope['_'] = target[:where] + (what,) + target[where + 1:]
11025                elif isinstance(target, set):
11026                    if what:
11027                        target.add(where)
11028                    else:
11029                        try:
11030                            target.remove(where)
11031                        except KeyError:
11032                            pass
11033                elif isinstance(target, dict):
11034                    target[where] = what
11035
11036            elif command.command == 'pop':
11037                command = cast(commands.PopValue, command)
11038                target = scope['_']
11039                if isinstance(target, list):
11040                    result = target.pop()
11041                    commands.pushCurrentValue(scope, result)
11042                elif isinstance(target, tuple):
11043                    result = target[-1]
11044                    updated = target[:-1]
11045                    scope['__'] = updated
11046                    scope['_'] = result
11047                else:
11048                    raise TypeError(
11049                        f"Cannot 'pop' from a {type(target).__name__}"
11050                        f" (current value must be a list or tuple)."
11051                    )
11052
11053            elif command.command == 'get':
11054                command = cast(commands.GetValue, command)
11055                target = scope['_']
11056                where = commands.resolveValue(command.location, scope)
11057                if isinstance(target, list):
11058                    if not isinstance(where, int):
11059                        raise TypeError(
11060                            f"Cannot get item from list: index"
11061                            f" {where!r} is not an integer."
11062                        )
11063                elif isinstance(target, tuple):
11064                    if not isinstance(where, int):
11065                        raise TypeError(
11066                            f"Cannot get item from tuple: index"
11067                            f" {where!r} is not an integer."
11068                        )
11069                elif isinstance(target, set):
11070                    result = where in target
11071                    commands.pushCurrentValue(scope, result)
11072                elif isinstance(target, dict):
11073                    result = target[where]
11074                    commands.pushCurrentValue(scope, result)
11075                else:
11076                    result = getattr(target, where)
11077                    commands.pushCurrentValue(scope, result)
11078
11079            elif command.command == 'remove':
11080                command = cast(commands.RemoveValue, command)
11081                target = scope['_']
11082                where = commands.resolveValue(command.location, scope)
11083                if isinstance(target, (list, tuple)):
11084                    # this cast is not correct but suppresses warnings
11085                    # given insufficient narrowing by MyPy
11086                    target = cast(Tuple[Any, ...], target)
11087                    if not isinstance(where, int):
11088                        raise TypeError(
11089                            f"Cannot remove item from list or tuple:"
11090                            f" index {where!r} is not an integer."
11091                        )
11092                    scope['_'] = target[:where] + target[where + 1:]
11093                elif isinstance(target, set):
11094                    target.remove(where)
11095                elif isinstance(target, dict):
11096                    del target[where]
11097                else:
11098                    raise TypeError(
11099                        f"Cannot use 'remove' on a/an"
11100                        f" {type(target).__name__}."
11101                    )
11102
11103            elif command.command == 'op':
11104                command = cast(commands.ApplyOperator, command)
11105                left = commands.resolveValue(command.left, scope)
11106                right = commands.resolveValue(command.right, scope)
11107                op = command.op
11108                if op == '+':
11109                    result = left + right
11110                elif op == '-':
11111                    result = left - right
11112                elif op == '*':
11113                    result = left * right
11114                elif op == '/':
11115                    result = left / right
11116                elif op == '//':
11117                    result = left // right
11118                elif op == '**':
11119                    result = left ** right
11120                elif op == '%':
11121                    result = left % right
11122                elif op == '^':
11123                    result = left ^ right
11124                elif op == '|':
11125                    result = left | right
11126                elif op == '&':
11127                    result = left & right
11128                elif op == 'and':
11129                    result = left and right
11130                elif op == 'or':
11131                    result = left or right
11132                elif op == '<':
11133                    result = left < right
11134                elif op == '>':
11135                    result = left > right
11136                elif op == '<=':
11137                    result = left <= right
11138                elif op == '>=':
11139                    result = left >= right
11140                elif op == '==':
11141                    result = left == right
11142                elif op == 'is':
11143                    result = left is right
11144                else:
11145                    raise RuntimeError("Invalid operator '{op}'.")
11146
11147                commands.pushCurrentValue(scope, result)
11148
11149            elif command.command == 'unary':
11150                command = cast(commands.ApplyUnary, command)
11151                value = commands.resolveValue(command.value, scope)
11152                op = command.op
11153                if op == '-':
11154                    result = -value
11155                elif op == '~':
11156                    result = ~value
11157                elif op == 'not':
11158                    result = not value
11159
11160                commands.pushCurrentValue(scope, result)
11161
11162            elif command.command == 'assign':
11163                command = cast(commands.VariableAssignment, command)
11164                varname = commands.resolveVarName(command.varname, scope)
11165                value = commands.resolveValue(command.value, scope)
11166                scope[varname] = value
11167
11168            elif command.command == 'delete':
11169                command = cast(commands.VariableDeletion, command)
11170                varname = commands.resolveVarName(command.varname, scope)
11171                del scope[varname]
11172
11173            elif command.command == 'load':
11174                command = cast(commands.LoadVariable, command)
11175                varname = commands.resolveVarName(command.varname, scope)
11176                commands.pushCurrentValue(scope, scope[varname])
11177
11178            elif command.command == 'call':
11179                command = cast(commands.FunctionCall, command)
11180                function = command.function
11181                if function.startswith('$'):
11182                    function = commands.resolveValue(function, scope)
11183
11184                toCall: Callable
11185                args: Tuple[str, ...]
11186                kwargs: Dict[str, Any]
11187
11188                if command.target == 'builtin':
11189                    toCall = commands.COMMAND_BUILTINS[function]
11190                    args = (scope['_'],)
11191                    kwargs = {}
11192                    if toCall == round:
11193                        if 'ndigits' in scope:
11194                            kwargs['ndigits'] = scope['ndigits']
11195                    elif toCall == range and args[0] is None:
11196                        start = scope.get('start', 0)
11197                        stop = scope['stop']
11198                        step = scope.get('step', 1)
11199                        args = (start, stop, step)
11200
11201                else:
11202                    if command.target == 'stored':
11203                        toCall = function
11204                    elif command.target == 'graph':
11205                        toCall = getattr(self.getSituation().graph, function)
11206                    elif command.target == 'exploration':
11207                        toCall = getattr(self, function)
11208                    else:
11209                        raise TypeError(
11210                            f"Invalid call target '{command.target}'"
11211                            f" (must be one of 'builtin', 'stored',"
11212                            f" 'graph', or 'exploration'."
11213                        )
11214
11215                    # Fill in arguments via kwargs defined in scope
11216                    args = ()
11217                    kwargs = {}
11218                    signature = inspect.signature(toCall)
11219                    # TODO: Maybe try some type-checking here?
11220                    for argName, param in signature.parameters.items():
11221                        if param.kind == inspect.Parameter.VAR_POSITIONAL:
11222                            if argName in scope:
11223                                args = args + tuple(scope[argName])
11224                            # Else leave args as-is
11225                        elif param.kind == inspect.Parameter.KEYWORD_ONLY:
11226                            # These must have a default
11227                            if argName in scope:
11228                                kwargs[argName] = scope[argName]
11229                        elif param.kind == inspect.Parameter.VAR_KEYWORD:
11230                            # treat as a dictionary
11231                            if argName in scope:
11232                                argsToUse = scope[argName]
11233                                if not isinstance(argsToUse, dict):
11234                                    raise TypeError(
11235                                        f"Variable '{argName}' must"
11236                                        f" hold a dictionary when"
11237                                        f" calling function"
11238                                        f" '{toCall.__name__} which"
11239                                        f" uses that argument as a"
11240                                        f" keyword catchall."
11241                                    )
11242                                kwargs.update(scope[argName])
11243                        else:  # a normal parameter
11244                            if argName in scope:
11245                                args = args + (scope[argName],)
11246                            elif param.default == inspect.Parameter.empty:
11247                                raise TypeError(
11248                                    f"No variable named '{argName}' has"
11249                                    f" been defined to supply the"
11250                                    f" required parameter with that"
11251                                    f" name for function"
11252                                    f" '{toCall.__name__}'."
11253                                )
11254
11255                result = toCall(*args, **kwargs)
11256                commands.pushCurrentValue(scope, result)
11257
11258            elif command.command == 'skip':
11259                command = cast(commands.SkipCommands, command)
11260                doIt = commands.resolveValue(command.condition, scope)
11261                if doIt:
11262                    skip = commands.resolveValue(command.amount, scope)
11263                    if not isinstance(skip, (int, str)):
11264                        raise TypeError(
11265                            f"Skip amount must be an integer or a label"
11266                            f" name (got {skip!r})."
11267                        )
11268
11269            elif command.command == 'label':
11270                command = cast(commands.Label, command)
11271                label = commands.resolveValue(command.name, scope)
11272                if not isinstance(label, str):
11273                    raise TypeError(
11274                        f"Label name must be a string (got {label!r})."
11275                    )
11276
11277            else:
11278                raise ValueError(
11279                    f"Invalid command type: {command.command!r}"
11280                )
11281        except ValueError as e:
11282            raise commands.CommandValueError(command, line, e)
11283        except TypeError as e:
11284            raise commands.CommandTypeError(command, line, e)
11285        except IndexError as e:
11286            raise commands.CommandIndexError(command, line, e)
11287        except KeyError as e:
11288            raise commands.CommandKeyError(command, line, e)
11289        except Exception as e:
11290            raise commands.CommandOtherError(command, line, e)
11291
11292        return (scope, skip, label)
11293
11294    def runCommandBlock(
11295        self,
11296        block: List[commands.Command],
11297        scope: Optional[commands.Scope] = None
11298    ) -> commands.Scope:
11299        """
11300        Runs a list of commands, using the given scope (or creating a new
11301        empty scope if none was provided). Returns the scope after
11302        running all of the commands, which may also edit the exploration
11303        and/or the current graph of course.
11304
11305        Note that if a skip command would skip past the end of the
11306        block, execution will end. If a skip command would skip before
11307        the beginning of the block, execution will start from the first
11308        command.
11309
11310        Example:
11311
11312        >>> e = DiscreteExploration()
11313        >>> scope = e.runCommandBlock([
11314        ...    commands.command('assign', 'decision', "'START'"),
11315        ...    commands.command('call', 'exploration', 'start'),
11316        ...    commands.command('assign', 'where', '$decision'),
11317        ...    commands.command('assign', 'transition', "'left'"),
11318        ...    commands.command('call', 'exploration', 'observe'),
11319        ...    commands.command('assign', 'transition', "'right'"),
11320        ...    commands.command('call', 'exploration', 'observe'),
11321        ...    commands.command('call', 'graph', 'destinationsFrom'),
11322        ...    commands.command('call', 'builtin', 'print'),
11323        ...    commands.command('assign', 'transition', "'right'"),
11324        ...    commands.command('assign', 'destination', "'EastRoom'"),
11325        ...    commands.command('call', 'exploration', 'explore'),
11326        ... ])
11327        {'left': 1, 'right': 2}
11328        >>> scope['decision']
11329        'START'
11330        >>> scope['where']
11331        'START'
11332        >>> scope['_']  # result of 'explore' call is dest ID
11333        2
11334        >>> scope['transition']
11335        'right'
11336        >>> scope['destination']
11337        'EastRoom'
11338        >>> g = e.getSituation().graph
11339        >>> len(e)
11340        3
11341        >>> len(g)
11342        3
11343        >>> g.namesListing(g)
11344        '  0 (START)\\n  1 (_u.0)\\n  2 (EastRoom)\\n'
11345        """
11346        if scope is None:
11347            scope = {}
11348
11349        labelPositions: Dict[str, List[int]] = {}
11350
11351        # Keep going until we've exhausted the commands list
11352        index = 0
11353        while index < len(block):
11354
11355            # Execute the next command
11356            scope, skip, label = self.runCommand(
11357                block[index],
11358                scope,
11359                index + 1
11360            )
11361
11362            # Increment our index, or apply a skip
11363            if skip is None:
11364                index = index + 1
11365
11366            elif isinstance(skip, int):  # Integer skip value
11367                if skip < 0:
11368                    index += skip
11369                    if index < 0:  # can't skip before the start
11370                        index = 0
11371                else:
11372                    index += skip + 1  # may end loop if we skip too far
11373
11374            else:  # must be a label name
11375                if skip in labelPositions:  # an established label
11376                    # We jump to the last previous index, or if there
11377                    # are none, to the first future index.
11378                    prevIndices = [
11379                        x
11380                        for x in labelPositions[skip]
11381                        if x < index
11382                    ]
11383                    futureIndices = [
11384                        x
11385                        for x in labelPositions[skip]
11386                        if x >= index
11387                    ]
11388                    if len(prevIndices) > 0:
11389                        index = max(prevIndices)
11390                    else:
11391                        index = min(futureIndices)
11392                else:  # must be a forward-reference
11393                    for future in range(index + 1, len(block)):
11394                        inspect = block[future]
11395                        if inspect.command == 'label':
11396                            inspect = cast(commands.Label, inspect)
11397                            if inspect.name == skip:
11398                                index = future
11399                                break
11400                    else:
11401                        raise KeyError(
11402                            f"Skip command indicated a jump to label"
11403                            f" {skip!r} but that label had not already"
11404                            f" been defined and there is no future"
11405                            f" label with that name either (future"
11406                            f" labels based on variables cannot be"
11407                            f" skipped to from above as their names"
11408                            f" are not known yet)."
11409                        )
11410
11411            # If there's a label, record it
11412            if label is not None:
11413                labelPositions.setdefault(label, []).append(index)
11414
11415            # And now the while loop continues, or ends if we're at the
11416            # end of the commands list.
11417
11418        # Return the scope object.
11419        return scope
11420
11421    @staticmethod
11422    def example() -> 'DiscreteExploration':
11423        """
11424        Returns a little example exploration. Has a few decisions
11425        including one that's unexplored, and uses a few steps to explore
11426        them.
11427
11428        >>> e = DiscreteExploration.example()
11429        >>> len(e)
11430        7
11431        >>> def pg(n):
11432        ...     print(e[n].graph.namesListing(e[n].graph))
11433        >>> pg(0)
11434          0 (House)
11435        <BLANKLINE>
11436        >>> pg(1)
11437          0 (House)
11438          1 (_u.0)
11439          2 (_u.1)
11440          3 (_u.2)
11441        <BLANKLINE>
11442        >>> pg(2)
11443          0 (House)
11444          1 (_u.0)
11445          2 (_u.1)
11446          3 (Yard)
11447          4 (_u.3)
11448          5 (_u.4)
11449        <BLANKLINE>
11450        >>> pg(3)
11451          0 (House)
11452          1 (_u.0)
11453          2 (_u.1)
11454          3 (Yard)
11455          4 (_u.3)
11456          5 (_u.4)
11457        <BLANKLINE>
11458        >>> pg(4)
11459          0 (House)
11460          1 (_u.0)
11461          2 (Cellar)
11462          3 (Yard)
11463          5 (_u.4)
11464        <BLANKLINE>
11465        >>> pg(5)
11466          0 (House)
11467          1 (_u.0)
11468          2 (Cellar)
11469          3 (Yard)
11470          5 (_u.4)
11471        <BLANKLINE>
11472        >>> pg(6)
11473          0 (House)
11474          1 (_u.0)
11475          2 (Cellar)
11476          3 (Yard)
11477          5 (Lane)
11478        <BLANKLINE>
11479        """
11480        result = DiscreteExploration()
11481        result.start("House")
11482        result.observeAll("House", "ladder", "stairsDown", "frontDoor")
11483        result.explore("frontDoor", "Yard", "frontDoor")
11484        result.observe("Yard", "cellarDoors")
11485        result.observe("Yard", "frontGate")
11486        result.retrace("frontDoor")
11487        result.explore("stairsDown", "Cellar", "stairsUp")
11488        result.observe("Cellar", "stairsOut")
11489        result.returnTo("stairsOut", "Yard", "cellarDoors")
11490        result.explore("frontGate", "Lane", "redGate")
11491        return result