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