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 MissingTransitionWarning(Warning):
  230    """
  231    Softer form of a `MissingTransitionError`.
  232    """
  233    pass
  234
  235
  236class MissingMechanismWarning(Warning):
  237    """
  238    A warning to use when attempting look up a mechanism name but no
  239    mechanism is found. Use `MissingMechanismError` instead if the issue
  240    is an error.
  241    """
  242    pass
  243
  244
  245class MissingMechanismError(KeyError):
  246    """
  247    An error raised when attempting to use a mechanism that does not
  248    exist.
  249    """
  250    pass
  251
  252
  253class MissingZoneError(KeyError):
  254    """
  255    An error raised when attempting to use a zone that does not exist.
  256    """
  257    pass
  258
  259
  260class InvalidLevelError(ValueError):
  261    """
  262    An error raised when an operation fails because of an invalid zone
  263    level.
  264    """
  265    pass
  266
  267
  268class InvalidDestinationError(ValueError):
  269    """
  270    An error raised when attempting to perform an operation with a
  271    transition but that transition does not lead to a destination that's
  272    compatible with the operation.
  273    """
  274    pass
  275
  276
  277class ExplorationStatusError(ValueError):
  278    """
  279    An error raised when attempting to perform an operation that
  280    requires a previously-visited destination with a decision that
  281    represents a not-yet-visited decision, or vice versa. For
  282    `Situation`s, Exploration states 'unknown', 'hypothesized', and
  283    'noticed' count as "not-yet-visited" while 'exploring' and 'explored'
  284    count as "visited" (see `base.hasBeenVisited`) Meanwhile, in a
  285    `DecisionGraph` where exploration statuses are not present, the
  286    presence or absence of the 'unconfirmed' tag is used to determine
  287    whether something has been confirmed or not.
  288    """
  289    pass
  290
  291
  292WARN_OF_NAME_COLLISIONS = False
  293"""
  294Whether or not to issue warnings when two decision names are the same.
  295"""
  296
  297
  298class DecisionCollisionWarning(Warning):
  299    """
  300    A warning raised when attempting to create a new decision using the
  301    name of a decision that already exists.
  302    """
  303    pass
  304
  305
  306class TransitionCollisionError(ValueError):
  307    """
  308    An error raised when attempting to re-use a transition name for a
  309    new transition, or otherwise when a transition name conflicts with
  310    an already-established transition.
  311    """
  312    pass
  313
  314
  315class TransitionCollisionWarning(Warning):
  316    """
  317    Softer form of a `TransitionCollisionError`.
  318    """
  319    pass
  320
  321
  322class AmbiguousMechanismWarning(Warning):
  323    """
  324    An warning to use when a mechanism reference is potentially
  325    ambiguous. Use `AmbiguousMechanismError` instead if the issue is an
  326    error.
  327    """
  328    pass
  329
  330
  331class AmbiguousMechanismError(ValueError):
  332    """
  333    An error raised when attempting look up a mechanism name but more
  334    than one mechanism shares that name within an applicable search
  335    region.
  336    """
  337    pass
  338
  339
  340class MechanismCollisionError(ValueError):
  341    """
  342    An error raised when attempting to re-use a mechanism name at the
  343    same decision where a mechanism with that name already exists.
  344    """
  345    pass
  346
  347
  348class DecisionCollisionError(ValueError):
  349    """
  350    An error raised when attempting to re-use a decision ID.
  351    """
  352    pass
  353
  354
  355class DomainCollisionError(KeyError):
  356    """
  357    An error raised when attempting to create a domain with the same
  358    name as an existing domain.
  359    """
  360    pass
  361
  362
  363class MissingFocalContextError(KeyError):
  364    """
  365    An error raised when attempting to pick out a focal context with a
  366    name that doesn't exist.
  367    """
  368    pass
  369
  370
  371class FocalContextCollisionError(KeyError):
  372    """
  373    An error raised when attempting to create a focal context with the
  374    same name as an existing focal context.
  375    """
  376    pass
  377
  378
  379class InvalidActionError(TypeError):
  380    """
  381    An error raised when attempting to take an exploration action which
  382    is not correctly formed.
  383    """
  384    pass
  385
  386
  387class ImpossibleActionError(ValueError):
  388    """
  389    An error raised when attempting to take an exploration action which
  390    is correctly formed but which specifies an action that doesn't match
  391    up with the graph state.
  392    """
  393    pass
  394
  395
  396class DoubleActionError(ValueError):
  397    """
  398    An error raised when attempting to set up an `ExplorationAction`
  399    when the current situation already has an action specified.
  400    """
  401    pass
  402
  403
  404class InactiveDomainWarning(Warning):
  405    """
  406    A warning used when an inactive domain is referenced but the
  407    operation in progress can still succeed (for example when
  408    deactivating an already-inactive domain).
  409    """
  410
  411
  412class ZoneCollisionError(ValueError):
  413    """
  414    An error raised when attempting to re-use a zone name for a new zone,
  415    or otherwise when a zone name conflicts with an already-established
  416    zone.
  417    """
  418    pass
  419
  420
  421class InvalidMechanismSpecifierWarning(Warning):
  422    """
  423    A warning used when a mechanism specifier includes both a numerical
  424    decision ID and superfluous domain/zone parts (which get ignored).
  425    """
  426
  427
  428#---------------------#
  429# DecisionGraph class #
  430#---------------------#
  431
  432class DecisionGraph(
  433    graphs.UniqueExitsGraph[base.DecisionID, base.Transition]
  434):
  435    """
  436    Represents a view of the world as a topological graph at a moment in
  437    time. It derives from `networkx.MultiDiGraph`.
  438
  439    Each node (a `Decision`) represents a place in the world where there
  440    are multiple opportunities for travel/action, or a dead end where
  441    you must turn around and go back; typically this is a single room in
  442    a game, but sometimes one room has multiple decision points. Edges
  443    (`Transition`s) represent choices that can be made to travel to
  444    other decision points (e.g., taking the left door), or when they are
  445    self-edges, they represent actions that can be taken within a
  446    location that affect the world or the game state.
  447
  448    Each `Transition` includes a `Effects` dictionary
  449    indicating the effects that it has. Other effects of the transition
  450    that are not simple enough to be included in this format may be
  451    represented in an `DiscreteExploration` by changing the graph in the
  452    next step to reflect further effects of a transition.
  453
  454    In addition to normal transitions between decisions, a
  455    `DecisionGraph` can represent potential transitions which lead to
  456    unknown destinations. These are represented by adding decisions with
  457    the `'unconfirmed'` tag (whose names where not specified begin with
  458    `'_u.'`) with a separate unconfirmed decision for each transition
  459    (although where it's known that two transitions lead to the same
  460    unconfirmed decision, this can be represented as well).
  461
  462    Both nodes and edges can have `Annotation`s associated with them that
  463    include extra details about the explorer's perception of the
  464    situation. They can also have `Tag`s, which represent specific
  465    categories a transition or decision falls into.
  466
  467    Nodes can also be part of one or more `Zones`, and zones can also be
  468    part of other zones, allowing for a hierarchical description of the
  469    underlying space.
  470
  471    Equivalences can be specified to mark that some combination of
  472    capabilities can stand in for another capability.
  473    """
  474    def __init__(self) -> None:
  475        super().__init__()
  476
  477        self.zones: Dict[base.Zone, base.ZoneInfo] = {}
  478        """
  479        Mapping from zone names to zone info
  480        """
  481
  482        self.unknownCount: int = 0
  483        """
  484        Number of unknown decisions that have been created (not number
  485        of current unknown decisions, which is likely lower)
  486        """
  487
  488        self.equivalences: base.Equivalences = {}
  489        """
  490        See `base.Equivalences`. Determines what capabilities and/or
  491        mechanism states can count as active based on alternate
  492        requirements.
  493        """
  494
  495        self.reversionTypes: Dict[str, Set[str]] = {}
  496        """
  497        This tracks shorthand reversion types. See `base.revertedState`
  498        for how these are applied. Keys are custom names and values are
  499        reversion type strings that `base.revertedState` could access.
  500        """
  501
  502        self.nextID: base.DecisionID = 0
  503        """
  504        The ID to use for the next new decision we create.
  505        """
  506
  507        self.nextMechanismID: base.MechanismID = 0
  508        """
  509        ID for the next mechanism.
  510        """
  511
  512        self.mechanisms: Dict[
  513            base.MechanismID,
  514            Tuple[Optional[base.DecisionID], base.MechanismName]
  515        ] = {}
  516        """
  517        Mapping from `MechanismID`s to (`DecisionID`, `MechanismName`)
  518        pairs. For global mechanisms, the `DecisionID` is None.
  519        """
  520
  521        self.globalMechanisms: Dict[
  522            base.MechanismName,
  523            base.MechanismID
  524        ] = {}
  525        """
  526        Global mechanisms
  527        """
  528
  529        self.nameLookup: Dict[base.DecisionName, List[base.DecisionID]] = {}
  530        """
  531        A cache for name -> ID lookups
  532        """
  533
  534    # Note: not hashable
  535
  536    def __eq__(self, other):
  537        """
  538        Equality checker. `DecisionGraph`s can only be equal to other
  539        `DecisionGraph`s, not to other kinds of things.
  540        """
  541        if not isinstance(other, DecisionGraph):
  542            return False
  543        else:
  544            # Checks nodes, edges, and all attached data
  545            if not super().__eq__(other):
  546                return False
  547
  548            # Check unknown count
  549            if self.unknownCount != other.unknownCount:
  550                return False
  551
  552            # Check zones
  553            if self.zones != other.zones:
  554                return False
  555
  556            # Check equivalences
  557            if self.equivalences != other.equivalences:
  558                return False
  559
  560            # Check reversion types
  561            if self.reversionTypes != other.reversionTypes:
  562                return False
  563
  564            # Check mechanisms
  565            if self.nextMechanismID != other.nextMechanismID:
  566                return False
  567
  568            if self.mechanisms != other.mechanisms:
  569                return False
  570
  571            if self.globalMechanisms != other.globalMechanisms:
  572                return False
  573
  574            # Check names:
  575            if self.nameLookup != other.nameLookup:
  576                return False
  577
  578            return True
  579
  580    def listDifferences(
  581        self,
  582        other: 'DecisionGraph'
  583    ) -> Generator[str, None, None]:
  584        """
  585        Generates strings describing differences between this graph and
  586        another graph. This does NOT perform graph matching, so it will
  587        consider graphs different even if they have identical structures
  588        but use different IDs for the nodes in those structures.
  589        """
  590        if not isinstance(other, DecisionGraph):
  591            yield "other is not a graph"
  592        else:
  593            suppress = False
  594            myNodes = set(self.nodes)
  595            theirNodes = set(other.nodes)
  596            for n in myNodes:
  597                if n not in theirNodes:
  598                    suppress = True
  599                    yield (
  600                        f"other graph missing node {n}"
  601                    )
  602                else:
  603                    if self.nodes[n] != other.nodes[n]:
  604                        suppress = True
  605                        yield (
  606                            f"other graph has differences at node {n}:"
  607                            f"\n  Ours:  {self.nodes[n]}"
  608                            f"\nTheirs:  {other.nodes[n]}"
  609                        )
  610                    myDests = self.destinationsFrom(n)
  611                    theirDests = other.destinationsFrom(n)
  612                    for tr in myDests:
  613                        myTo = myDests[tr]
  614                        if tr not in theirDests:
  615                            suppress = True
  616                            yield (
  617                                f"at {self.identityOf(n)}: other graph"
  618                                f" missing transition {tr!r}"
  619                            )
  620                        else:
  621                            theirTo = theirDests[tr]
  622                            if myTo != theirTo:
  623                                suppress = True
  624                                yield (
  625                                    f"at {self.identityOf(n)}: other"
  626                                    f" graph transition {tr!r} leads to"
  627                                    f" {theirTo} instead of {myTo}"
  628                                )
  629                            else:
  630                                myProps = self.edges[n, myTo, tr]  # type:ignore [index] # noqa
  631                                theirProps = other.edges[n, myTo, tr]  # type:ignore [index] # noqa
  632                                if myProps != theirProps:
  633                                    suppress = True
  634                                    yield (
  635                                        f"at {self.identityOf(n)}: other"
  636                                        f" graph transition {tr!r} has"
  637                                        f" different properties:"
  638                                        f"\n  Ours:  {myProps}"
  639                                        f"\nTheirs:  {theirProps}"
  640                                    )
  641            for extra in theirNodes - myNodes:
  642                suppress = True
  643                yield (
  644                    f"other graph has extra node {extra}"
  645                )
  646
  647            # TODO: Fix networkx stubs!
  648            if self.graph != other.graph:  # type:ignore [attr-defined]
  649                suppress = True
  650                yield (
  651                    " different graph attributes:"  # type:ignore [attr-defined]  # noqa
  652                    f"\n  Ours:  {self.graph}"
  653                    f"\nTheirs:  {other.graph}"
  654                )
  655
  656            # Checks any other graph data we might have missed
  657            if not super().__eq__(other) and not suppress:
  658                for attr in dir(self):
  659                    if attr.startswith('__') and attr.endswith('__'):
  660                        continue
  661                    if not hasattr(other, attr):
  662                        yield f"other graph missing attribute: {attr!r}"
  663                    else:
  664                        myVal = getattr(self, attr)
  665                        theirVal = getattr(other, attr)
  666                        if (
  667                            myVal != theirVal
  668                        and not ((callable(myVal) and callable(theirVal)))
  669                        ):
  670                            yield (
  671                                f"other has different val for {attr!r}:"
  672                                f"\n  Ours:  {myVal}"
  673                                f"\nTheirs:  {theirVal}"
  674                            )
  675                for attr in sorted(set(dir(other)) - set(dir(self))):
  676                    yield f"other has extra attribute: {attr!r}"
  677                yield "graph data is different"
  678                # TODO: More detail here!
  679
  680            # Check unknown count
  681            if self.unknownCount != other.unknownCount:
  682                yield "unknown count is different"
  683
  684            # Check zones
  685            if self.zones != other.zones:
  686                yield "zones are different"
  687
  688            # Check equivalences
  689            if self.equivalences != other.equivalences:
  690                yield "equivalences are different"
  691
  692            # Check reversion types
  693            if self.reversionTypes != other.reversionTypes:
  694                yield "reversionTypes are different"
  695
  696            # Check mechanisms
  697            if self.nextMechanismID != other.nextMechanismID:
  698                yield "nextMechanismID is different"
  699
  700            if self.mechanisms != other.mechanisms:
  701                yield "mechanisms are different"
  702
  703            if self.globalMechanisms != other.globalMechanisms:
  704                yield "global mechanisms are different"
  705
  706            # Check names:
  707            if self.nameLookup != other.nameLookup:
  708                for name in self.nameLookup:
  709                    if name not in other.nameLookup:
  710                        yield (
  711                            f"other graph is missing name lookup entry"
  712                            f" for {name!r}"
  713                        )
  714                    else:
  715                        mine = self.nameLookup[name]
  716                        theirs = other.nameLookup[name]
  717                        if theirs != mine:
  718                            yield (
  719                                f"name lookup for {name!r} is {theirs}"
  720                                f" instead of {mine}"
  721                            )
  722                extras = set(other.nameLookup) - set(self.nameLookup)
  723                if extras:
  724                    yield (
  725                        f"other graph has extra name lookup entries:"
  726                        f" {extras}"
  727                    )
  728
  729    def _assignID(self) -> base.DecisionID:
  730        """
  731        Returns the next `base.DecisionID` to use and increments the
  732        next ID counter.
  733        """
  734        result = self.nextID
  735        self.nextID += 1
  736        return result
  737
  738    def _assignMechanismID(self) -> base.MechanismID:
  739        """
  740        Returns the next `base.MechanismID` to use and increments the
  741        next ID counter.
  742        """
  743        result = self.nextMechanismID
  744        self.nextMechanismID += 1
  745        return result
  746
  747    def decisionInfo(self, dID: base.DecisionID) -> DecisionInfo:
  748        """
  749        Retrieves the decision info for the specified decision, as a
  750        live editable dictionary.
  751
  752        For example:
  753
  754        >>> g = DecisionGraph()
  755        >>> g.addDecision('A')
  756        0
  757        >>> g.annotateDecision('A', 'note')
  758        >>> g.decisionInfo(0)
  759        {'name': 'A', 'domain': 'main', 'tags': {}, 'annotations': ['note']}
  760        """
  761        return cast(DecisionInfo, self.nodes[dID])
  762
  763    def resolveDecisions(
  764        self,
  765        spec: base.AnyDecisionSpecifier,
  766        zoneHint: Optional[base.Zone] = None,
  767        domainHint: Optional[base.Domain] = None
  768    ) -> Set[base.DecisionID]:
  769        """
  770        Works like `resolveDecision`, except that it returns a set of
  771        decision IDs. Where `resolveDecision` would raise an
  772        `AmbiguousDecisionSpecifierError`, it instead returns a set with
  773        multiple IDs. Where `resolveDecision` would raise a
  774        `MissingDecisionError`, it instead returns an empty set.
  775
  776        Examples:
  777
  778        >>> g = DecisionGraph()
  779        >>> g.addDecision('A')
  780        0
  781        >>> g.addDecision('B')
  782        1
  783        >>> g.addDecision('C')
  784        2
  785        >>> g.addDecision('A')
  786        3
  787        >>> g.addDecision('B', 'menu')
  788        4
  789        >>> g.createZone('Z', 0)
  790        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
  791 annotations=[])
  792        >>> g.createZone('Z2', 0)
  793        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
  794 annotations=[])
  795        >>> g.createZone('Zup', 1)
  796        ZoneInfo(level=1, parents=set(), contents=set(), tags={},\
  797 annotations=[])
  798        >>> g.addDecisionToZone(0, 'Z')
  799        >>> g.addDecisionToZone(1, 'Z')
  800        >>> g.addDecisionToZone(2, 'Z')
  801        >>> g.addDecisionToZone(3, 'Z2')
  802        >>> g.addZoneToZone('Z', 'Zup')
  803        >>> g.addZoneToZone('Z2', 'Zup')
  804        >>> g.resolveDecisions(1)
  805        {1}
  806        >>> g.resolveDecisions('A')
  807        {0, 3}
  808        >>> g.resolveDecisions('B')
  809        {1, 4}
  810        >>> g.resolveDecisions('C')
  811        {2}
  812        >>> g.resolveDecisions('A', 'Z')
  813        {0}
  814        >>> g.resolveDecisions('A', zoneHint='Z2')
  815        {3}
  816        >>> g.resolveDecisions('B', domainHint='main')
  817        {1}
  818        >>> g.resolveDecisions('B', None, 'menu')
  819        {4}
  820        >>> g.resolveDecisions('B', zoneHint='Z2')
  821        set()
  822        >>> g.resolveDecisions('A', domainHint='menu')
  823        set()
  824        >>> g.resolveDecisions('A', domainHint='madeup')
  825        set()
  826        >>> g.resolveDecisions('A', zoneHint='madeup')
  827        set()
  828        >>> g.resolveDecisions(17)
  829        set()
  830        """
  831        # Parse it to either an ID or specifier if it's a string:
  832        if isinstance(spec, str):
  833            try:
  834                spec = int(spec)
  835            except ValueError:
  836                pass
  837
  838        # If it's an ID, check for existence:
  839        if isinstance(spec, base.DecisionID):
  840            if spec in self:
  841                return { spec }
  842            else:
  843                return set()
  844        else:
  845            if isinstance(spec, base.DecisionName):
  846                spec = base.DecisionSpecifier(
  847                    domain=None,
  848                    zone=None,
  849                    name=spec
  850                )
  851            elif not isinstance(spec, base.DecisionSpecifier):
  852                raise TypeError(
  853                    f"Specification is not provided as a"
  854                    f" DecisionSpecifier or other valid type. (got type"
  855                    f" {type(spec)})."
  856                )
  857
  858            # Merge domain hints from spec/args
  859            if (
  860                spec.domain is not None
  861            and domainHint is not None
  862            and spec.domain != domainHint
  863            ):
  864                raise ValueError(
  865                    f"Specifier {repr(spec)} includes domain hint"
  866                    f" {repr(spec.domain)} which is incompatible with"
  867                    f" explicit domain hint {repr(domainHint)}."
  868                )
  869            else:
  870                domainHint = spec.domain or domainHint
  871
  872            # Merge zone hints from spec/args
  873            if (
  874                spec.zone is not None
  875            and zoneHint is not None
  876            and spec.zone != zoneHint
  877            ):
  878                raise ValueError(
  879                    f"Specifier {repr(spec)} includes zone hint"
  880                    f" {repr(spec.zone)} which is incompatible with"
  881                    f" explicit zone hint {repr(zoneHint)}."
  882                )
  883            else:
  884                zoneHint = spec.zone or zoneHint
  885
  886            if spec.name not in self.nameLookup:
  887                return set()
  888            else:
  889                options = self.nameLookup[spec.name]
  890                if len(options) == 0:
  891                    return set()
  892                return {
  893                    opt
  894                    for opt in options
  895                    if (
  896                        domainHint is None
  897                     or self.domainFor(opt) == domainHint
  898                    ) and (
  899                        zoneHint is None
  900                     or zoneHint in self.zoneAncestors(opt)
  901                    )
  902                }
  903
  904    def resolveDecision(
  905        self,
  906        spec: base.AnyDecisionSpecifier,
  907        zoneHint: Optional[base.Zone] = None,
  908        domainHint: Optional[base.Domain] = None
  909    ) -> base.DecisionID:
  910        """
  911        Given a decision specifier returns the ID associated with that
  912        decision, or raises an `AmbiguousDecisionSpecifierError` or a
  913        `MissingDecisionError` if the specified decision is either
  914        missing or ambiguous. Cannot handle strings that contain domain
  915        and/or zone parts; use
  916        `parsing.ParseFormat.parseDecisionSpecifier` to turn such
  917        strings into `DecisionSpecifier`s if you need to first.
  918
  919        Examples:
  920
  921        >>> g = DecisionGraph()
  922        >>> g.addDecision('A')
  923        0
  924        >>> g.addDecision('B')
  925        1
  926        >>> g.addDecision('C')
  927        2
  928        >>> g.addDecision('A')
  929        3
  930        >>> g.addDecision('B', 'menu')
  931        4
  932        >>> g.createZone('Z', 0)
  933        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
  934 annotations=[])
  935        >>> g.createZone('Z2', 0)
  936        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
  937 annotations=[])
  938        >>> g.createZone('Zup', 1)
  939        ZoneInfo(level=1, parents=set(), contents=set(), tags={},\
  940 annotations=[])
  941        >>> g.addDecisionToZone(0, 'Z')
  942        >>> g.addDecisionToZone(1, 'Z')
  943        >>> g.addDecisionToZone(2, 'Z')
  944        >>> g.addDecisionToZone(3, 'Z2')
  945        >>> g.addZoneToZone('Z', 'Zup')
  946        >>> g.addZoneToZone('Z2', 'Zup')
  947        >>> g.resolveDecision(1)
  948        1
  949        >>> g.resolveDecision('A')
  950        Traceback (most recent call last):
  951        ...
  952        exploration.core.AmbiguousDecisionSpecifierError...
  953        >>> g.resolveDecision('B')
  954        Traceback (most recent call last):
  955        ...
  956        exploration.core.AmbiguousDecisionSpecifierError...
  957        >>> g.resolveDecision('C')
  958        2
  959        >>> g.resolveDecision('A', 'Z')
  960        0
  961        >>> g.resolveDecision('A', zoneHint='Z2')
  962        3
  963        >>> g.resolveDecision('B', domainHint='main')
  964        1
  965        >>> g.resolveDecision('B', None, 'menu')
  966        4
  967        >>> g.resolveDecision('B', zoneHint='Z2')
  968        Traceback (most recent call last):
  969        ...
  970        exploration.core.MissingDecisionError...
  971        >>> g.resolveDecision('A', domainHint='menu')
  972        Traceback (most recent call last):
  973        ...
  974        exploration.core.MissingDecisionError...
  975        >>> g.resolveDecision('A', domainHint='madeup')
  976        Traceback (most recent call last):
  977        ...
  978        exploration.core.MissingDecisionError...
  979        >>> g.resolveDecision('A', zoneHint='madeup')
  980        Traceback (most recent call last):
  981        ...
  982        exploration.core.MissingDecisionError...
  983        """
  984        options = self.resolveDecisions(spec, zoneHint, domainHint)
  985        if len(options) == 0:  # zero options: decision doesn't exist
  986            if (
  987                (isinstance(spec, str) and spec.isdigit())
  988             or isinstance(spec, int)
  989            ):
  990                raise MissingDecisionError(
  991                    f"There is no decision with ID {int(spec)}."
  992                )
  993            elif isinstance(spec, str):
  994                if spec not in self.nameLookup:
  995                    raise MissingDecisionError(
  996                        f"There is no decision named {spec!r}."
  997                    )
  998                else:
  999                    filterDesc = ""
 1000                    if domainHint is not None:
 1001                        filterDesc += f" in domain {repr(domainHint)}"
 1002                    if zoneHint is not None:
 1003                        filterDesc += f" in zone {repr(zoneHint)}"
 1004                    raise MissingDecisionError(
 1005                        f"There is at least one decision named {spec!r},"
 1006                        f" but there are none {filterDesc}."
 1007                    )
 1008            else:
 1009                assert isinstance(spec, base.DecisionSpecifier)
 1010                if spec.name not in self.nameLookup:
 1011                    raise MissingDecisionError(
 1012                        f"There is no decision named {spec.name!r}."
 1013                    )
 1014                else:
 1015                    filterDesc = ""
 1016                    domainHint = domainHint or spec.domain
 1017                    zoneHint = zoneHint or spec.zone
 1018                    if domainHint is not None:
 1019                        filterDesc += f" in domain {repr(domainHint)}"
 1020                    if zoneHint is not None:
 1021                        filterDesc += f" in zone {repr(zoneHint)}"
 1022                    raise MissingDecisionError(
 1023                        f"There is at least one decision matching {spec!r},"
 1024                        f" but there are none {filterDesc}."
 1025                    )
 1026        elif len(options) > 1:  # multiple options: specifier was ambiguous
 1027            assert not isinstance(spec, int)  # couldn't be ambiguous
 1028            if isinstance(spec, str):
 1029                assert not spec.isdigit()  # couldn't be ambiguous
 1030                raise AmbiguousDecisionSpecifierError(
 1031                    f"There are {len(options)} decisions named"
 1032                    f" {repr(spec)}."
 1033                )
 1034            else:
 1035                assert isinstance(spec, base.DecisionSpecifier)
 1036                filterDesc = ""
 1037                domainHint = domainHint or spec.domain
 1038                zoneHint = zoneHint or spec.zone
 1039                if domainHint is not None:
 1040                    filterDesc += f" in domain {repr(domainHint)}"
 1041                if zoneHint is not None:
 1042                    filterDesc += f" in zone {repr(zoneHint)}"
 1043                raise AmbiguousDecisionSpecifierError(
 1044                    f"There are {len(options)} decisions named"
 1045                    f" {repr(spec.name)}{filterDesc}."
 1046                )
 1047        else:  # only 1 option: successfully resolved to unique decision
 1048            return list(options)[0]
 1049
 1050    def getDecision(
 1051        self,
 1052        decision: base.AnyDecisionSpecifier,
 1053        zoneHint: Optional[base.Zone] = None,
 1054        domainHint: Optional[base.Domain] = None
 1055    ) -> Optional[base.DecisionID]:
 1056        """
 1057        Works like `resolveDecision` but returns None instead of raising
 1058        a `MissingDecisionError` if the specified decision isn't listed.
 1059        May still raise an `AmbiguousDecisionSpecifierError`.
 1060        """
 1061        try:
 1062            return self.resolveDecision(
 1063                decision,
 1064                zoneHint,
 1065                domainHint
 1066            )
 1067        except MissingDecisionError:
 1068            return None
 1069
 1070    def nameFor(
 1071        self,
 1072        decision: base.AnyDecisionSpecifier
 1073    ) -> base.DecisionName:
 1074        """
 1075        Returns the name of the specified decision. Note that names are
 1076        not necessarily unique.
 1077
 1078        Example:
 1079
 1080        >>> d = DecisionGraph()
 1081        >>> d.addDecision('A')
 1082        0
 1083        >>> d.addDecision('B')
 1084        1
 1085        >>> d.addDecision('B')
 1086        2
 1087        >>> d.nameFor(0)
 1088        'A'
 1089        >>> d.nameFor(1)
 1090        'B'
 1091        >>> d.nameFor(2)
 1092        'B'
 1093        >>> d.nameFor(3)
 1094        Traceback (most recent call last):
 1095        ...
 1096        exploration.core.MissingDecisionError...
 1097        """
 1098        dID = self.resolveDecision(decision)
 1099        return self.nodes[dID]['name']
 1100
 1101    def shortIdentity(
 1102        self,
 1103        decision: Optional[base.AnyDecisionSpecifier],
 1104        includeZones: bool = True,
 1105        alwaysDomain: Optional[bool] = None
 1106    ):
 1107        """
 1108        Returns a string containing the name for the given decision,
 1109        prefixed by its level-0 zone(s) and domain. If the value provided
 1110        is `None`, it returns the string "(nowhere)". This is not
 1111        necessarily unique.
 1112
 1113        If `includeZones` is true (the default) then zone information
 1114        is included before the decision name.
 1115
 1116        If `alwaysDomain` is true or false, then the domain information
 1117        will always (or never) be included. If it's `None` (the default)
 1118        then domain info will only be included for decisions which are
 1119        not in the default domain.
 1120
 1121        This string is NOT necessarily valid input to
 1122        `parsing.ParseFormat.parseDecisionSpecifier` (see
 1123        `journal.JournalObserver.identifyingString` for a function that
 1124        can generate that).
 1125        """
 1126        if decision is None:
 1127            return "(nowhere)"
 1128        else:
 1129            dID = self.resolveDecision(decision)
 1130            thisDomain = self.domainFor(dID)
 1131            dSpec = ''
 1132            zSpec = ''
 1133            if (
 1134                alwaysDomain is True
 1135             or (
 1136                    alwaysDomain is None
 1137                and thisDomain != base.DEFAULT_DOMAIN
 1138                )
 1139            ):
 1140                dSpec = thisDomain + '//'  # TODO: Don't hardcode this?
 1141            if includeZones:
 1142                zones = [
 1143                    z
 1144                    for z in self.zoneParents(dID)
 1145                    if self.zones[z].level == 0
 1146                ]
 1147                if len(zones) == 1:
 1148                    zSpec = zones[0] + '::'  # TODO: Don't hardcode this?
 1149                elif len(zones) > 1:
 1150                    zSpec = '[' + ', '.join(sorted(zones)) + ']::'
 1151                # else leave zSpec empty
 1152
 1153            return f"{dSpec}{zSpec}{self.nameFor(dID)}"
 1154
 1155    def identityOf(
 1156        self,
 1157        decision: Optional[base.AnyDecisionSpecifier],
 1158        includeZones: bool = True,
 1159        alwaysDomain: Optional[bool] = None
 1160    ) -> str:
 1161        """
 1162        Returns the given node's ID, plus its `shortIdentity` in
 1163        parentheses. Arguments are passed through to `shortIdentity`.
 1164        """
 1165        if decision is None:
 1166            return "(nowhere)"
 1167        else:
 1168            dID = self.resolveDecision(decision)
 1169            short = self.shortIdentity(decision, includeZones, alwaysDomain)
 1170            return f"{dID} ({short})"
 1171
 1172    def namesListing(
 1173        self,
 1174        decisions: Collection[base.DecisionID],
 1175        includeZones: bool = True,
 1176        indent: int = 2
 1177    ) -> str:
 1178        """
 1179        Returns a multi-line string containing an indented listing of
 1180        the provided decision IDs with their names in parentheses after
 1181        each. Useful for debugging & error messages.
 1182
 1183        Includes level-0 zones where applicable, with a zone separator
 1184        before the decision, unless `includeZones` is set to False. Where
 1185        there are multiple level-0 zones, they're listed together in
 1186        brackets.
 1187
 1188        Uses the string '(none)' when there are no decisions are in the
 1189        list.
 1190
 1191        Set `indent` to something other than 2 to control how much
 1192        indentation is added.
 1193
 1194        For example:
 1195
 1196        >>> g = DecisionGraph()
 1197        >>> g.addDecision('A')
 1198        0
 1199        >>> g.addDecision('B')
 1200        1
 1201        >>> g.addDecision('C')
 1202        2
 1203        >>> g.namesListing(['A', 'C', 'B'])
 1204        '  0 (A)\\n  2 (C)\\n  1 (B)\\n'
 1205        >>> g.namesListing([])
 1206        '  (none)\\n'
 1207        >>> g.createZone('zone', 0)
 1208        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 1209 annotations=[])
 1210        >>> g.createZone('zone2', 0)
 1211        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 1212 annotations=[])
 1213        >>> g.createZone('zoneUp', 1)
 1214        ZoneInfo(level=1, parents=set(), contents=set(), tags={},\
 1215 annotations=[])
 1216        >>> g.addDecisionToZone(0, 'zone')
 1217        >>> g.addDecisionToZone(1, 'zone')
 1218        >>> g.addDecisionToZone(1, 'zone2')
 1219        >>> g.addDecisionToZone(2, 'zoneUp')  # won't be listed: it's level-1
 1220        >>> g.namesListing(['A', 'C', 'B'])
 1221        '  0 (zone::A)\\n  2 (C)\\n  1 ([zone, zone2]::B)\\n'
 1222        """
 1223        ind = ' ' * indent
 1224        if len(decisions) == 0:
 1225            return ind + '(none)\n'
 1226        else:
 1227            result = ''
 1228            for dID in decisions:
 1229                result += ind + self.identityOf(dID, includeZones) + '\n'
 1230            return result
 1231
 1232    def destinationsListing(
 1233        self,
 1234        destinations: Dict[base.Transition, base.DecisionID],
 1235        includeZones: bool = True,
 1236        indent: int = 2
 1237    ) -> str:
 1238        """
 1239        Returns a multi-line string containing an indented listing of
 1240        the provided transitions along with their destinations and the
 1241        names of those destinations in parentheses. Useful for debugging
 1242        & error messages. (Use e.g., `destinationsFrom` to get a
 1243        transitions -> destinations dictionary in the required format.)
 1244
 1245        Uses the string '(no transitions)' when there are no transitions
 1246        in the dictionary.
 1247
 1248        Set `indent` to something other than 2 to control how much
 1249        indentation is added.
 1250
 1251        For example:
 1252
 1253        >>> g = DecisionGraph()
 1254        >>> g.addDecision('A')
 1255        0
 1256        >>> g.addDecision('B')
 1257        1
 1258        >>> g.addDecision('C')
 1259        2
 1260        >>> g.addTransition('A', 'north', 'B', 'south')
 1261        >>> g.addTransition('B', 'east', 'C', 'west')
 1262        >>> g.addTransition('C', 'southwest', 'A', 'northeast')
 1263        >>> g.destinationsListing(g.destinationsFrom('A'))
 1264        '  north to 1 (B)\\n  northeast to 2 (C)\\n'
 1265        >>> g.destinationsListing(g.destinationsFrom('B'))
 1266        '  south to 0 (A)\\n  east to 2 (C)\\n'
 1267        >>> g.destinationsListing({})
 1268        '  (none)\\n'
 1269        >>> g.createZone('zone', 0)
 1270        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 1271 annotations=[])
 1272        >>> g.addDecisionToZone(0, 'zone')
 1273        >>> g.destinationsListing(g.destinationsFrom('B'))
 1274        '  south to 0 (zone::A)\\n  east to 2 (C)\\n'
 1275        """
 1276        ind = ' ' * indent
 1277        if len(destinations) == 0:
 1278            return ind + '(none)\n'
 1279        else:
 1280            result = ''
 1281            for transition, dID in destinations.items():
 1282                line = f"{transition} to {self.identityOf(dID, includeZones)}"
 1283                result += ind + line + '\n'
 1284            return result
 1285
 1286    def domainFor(self, decision: base.AnyDecisionSpecifier) -> base.Domain:
 1287        """
 1288        Returns the domain that a decision belongs to.
 1289        """
 1290        dID = self.resolveDecision(decision)
 1291        return self.nodes[dID]['domain']
 1292
 1293    def allDecisionsInDomain(
 1294        self,
 1295        domain: base.Domain
 1296    ) -> Set[base.DecisionID]:
 1297        """
 1298        Returns the set of all `DecisionID`s for decisions in the
 1299        specified domain.
 1300        """
 1301        return set(dID for dID in self if self.nodes[dID]['domain'] == domain)
 1302
 1303    def destination(
 1304        self,
 1305        decision: base.AnyDecisionSpecifier,
 1306        transition: base.Transition
 1307    ) -> base.DecisionID:
 1308        """
 1309        Overrides base `UniqueExitsGraph.destination` to raise
 1310        `MissingDecisionError` or `MissingTransitionError` as
 1311        appropriate, and to work with an `AnyDecisionSpecifier`.
 1312        """
 1313        dID = self.resolveDecision(decision)
 1314        try:
 1315            return super().destination(dID, transition)
 1316        except KeyError:
 1317            raise MissingTransitionError(
 1318                f"Transition {transition!r} does not exist at decision"
 1319                f" {self.identityOf(dID)}."
 1320            )
 1321
 1322    def getDestination(
 1323        self,
 1324        decision: base.AnyDecisionSpecifier,
 1325        transition: base.Transition,
 1326        default: Any = None
 1327    ) -> Optional[base.DecisionID]:
 1328        """
 1329        Overrides base `UniqueExitsGraph.getDestination` with different
 1330        argument names, since those matter for the edit DSL.
 1331        """
 1332        dID = self.resolveDecision(decision)
 1333        return super().getDestination(dID, transition)
 1334
 1335    def destinationsFrom(
 1336        self,
 1337        decision: base.AnyDecisionSpecifier
 1338    ) -> Dict[base.Transition, base.DecisionID]:
 1339        """
 1340        Override that just changes the type of the exception from a
 1341        `KeyError` to a `MissingDecisionError` when the source does not
 1342        exist.
 1343        """
 1344        dID = self.resolveDecision(decision)
 1345        return super().destinationsFrom(dID)
 1346
 1347    def newTransitionNameFrom(
 1348        self,
 1349        decision: base.AnyDecisionSpecifier,
 1350        baseName: base.Transition
 1351    ) -> base.Transition:
 1352        """
 1353        Given a decision and a desired transition name, returns a
 1354        transition name that doesn't match any existing transition from
 1355        the specified destination. Returns the given name as-is if it
 1356        doesn't collide with an existing transition name, otherwise
 1357        appends a number to it, starting with 2. Note that a number will
 1358        be appended even if the base name already has a number at the
 1359        end, so for example if a decision already has 'up' and 'up2' as
 1360        options, asking for a new transition based on 'up' will give
 1361        'up3', but asking for a new transition based on 'up2' will give
 1362        'up22'.
 1363
 1364        Some examples:
 1365
 1366        >>> g = DecisionGraph()
 1367        >>> g.addDecision('A')
 1368        0
 1369        >>> g.newTransitionNameFrom('A', 'up')
 1370        'up'
 1371        >>> g.addDecision('B')
 1372        1
 1373        >>> g.addTransition('A', 'up', 'B')
 1374        >>> g.newTransitionNameFrom('A', 'up')
 1375        'up2'
 1376        >>> g.addTransition('A', 'up2', 'B')
 1377        >>> g.newTransitionNameFrom('A', 'up')
 1378        'up3'
 1379        >>> g.newTransitionNameFrom('A', 'up2')  # suffixes not parsed
 1380        'up22'
 1381        """
 1382        already = self.destinationsFrom(decision)
 1383        candidate = baseName
 1384        i = 2
 1385        while candidate in already:
 1386            candidate = baseName + str(i)
 1387            i += 1
 1388        return candidate 
 1389
 1390    def bothEnds(
 1391        self,
 1392        decision: base.AnyDecisionSpecifier,
 1393        transition: base.Transition
 1394    ) -> Set[base.DecisionID]:
 1395        """
 1396        Returns a set containing the `DecisionID`(s) for both the start
 1397        and end of the specified transition. Raises a
 1398        `MissingDecisionError` or `MissingTransitionError`if the
 1399        specified decision and/or transition do not exist.
 1400
 1401        Note that for actions since the source and destination are the
 1402        same, the set will have only one element.
 1403        """
 1404        dID = self.resolveDecision(decision)
 1405        result = {dID}
 1406        dest = self.destination(dID, transition)
 1407        if dest is not None:
 1408            result.add(dest)
 1409        return result
 1410
 1411    def decisionActions(
 1412        self,
 1413        decision: base.AnyDecisionSpecifier
 1414    ) -> Set[base.Transition]:
 1415        """
 1416        Retrieves the set of self-edges at a decision. Editing the set
 1417        will not affect the graph.
 1418
 1419        Example:
 1420
 1421        >>> g = DecisionGraph()
 1422        >>> g.addDecision('A')
 1423        0
 1424        >>> g.addDecision('B')
 1425        1
 1426        >>> g.addDecision('C')
 1427        2
 1428        >>> g.addAction('A', 'action1')
 1429        >>> g.addAction('A', 'action2')
 1430        >>> g.addAction('B', 'action3')
 1431        >>> sorted(g.decisionActions('A'))
 1432        ['action1', 'action2']
 1433        >>> g.decisionActions('B')
 1434        {'action3'}
 1435        >>> g.decisionActions('C')
 1436        set()
 1437        """
 1438        result = set()
 1439        dID = self.resolveDecision(decision)
 1440        for transition, dest in self.destinationsFrom(dID).items():
 1441            if dest == dID:
 1442                result.add(transition)
 1443        return result
 1444
 1445    def getTransitionProperties(
 1446        self,
 1447        decision: base.AnyDecisionSpecifier,
 1448        transition: base.Transition
 1449    ) -> TransitionProperties:
 1450        """
 1451        Returns a dictionary containing transition properties for the
 1452        specified transition from the specified decision. The properties
 1453        included are:
 1454
 1455        - 'requirement': The requirement for the transition.
 1456        - 'consequence': Any consequence of the transition.
 1457        - 'tags': Any tags applied to the transition.
 1458        - 'annotations': Any annotations on the transition.
 1459
 1460        The reciprocal of the transition is not included.
 1461
 1462        The result is a clone of the stored properties; edits to the
 1463        dictionary will NOT modify the graph.
 1464        """
 1465        dID = self.resolveDecision(decision)
 1466        dest = self.destination(dID, transition)
 1467
 1468        info: TransitionProperties = copy.deepcopy(
 1469            self.edges[dID, dest, transition]  # type:ignore
 1470        )
 1471        return {
 1472            'requirement': info.get('requirement', base.ReqNothing()),
 1473            'consequence': info.get('consequence', []),
 1474            'tags': info.get('tags', {}),
 1475            'annotations': info.get('annotations', [])
 1476        }
 1477
 1478    def setTransitionProperties(
 1479        self,
 1480        decision: base.AnyDecisionSpecifier,
 1481        transition: base.Transition,
 1482        requirement: Optional[base.Requirement] = None,
 1483        consequence: Optional[base.Consequence] = None,
 1484        tags: Optional[Dict[base.Tag, base.TagValue]] = None,
 1485        annotations: Optional[List[base.Annotation]] = None
 1486    ) -> None:
 1487        """
 1488        Sets one or more transition properties all at once. Can be used
 1489        to set the requirement, consequence, tags, and/or annotations.
 1490        Old values are overwritten, although if `None`s are provided (or
 1491        arguments are omitted), corresponding properties are not
 1492        updated.
 1493
 1494        To add tags or annotations to existing tags/annotations instead
 1495        of replacing them, use `tagTransition` or `annotateTransition`
 1496        instead.
 1497        """
 1498        dID = self.resolveDecision(decision)
 1499        if requirement is not None:
 1500            self.setTransitionRequirement(dID, transition, requirement)
 1501        if consequence is not None:
 1502            self.setConsequence(dID, transition, consequence)
 1503        if tags is not None:
 1504            dest = self.destination(dID, transition)
 1505            # TODO: Submit pull request to update MultiDiGraph stubs in
 1506            # types-networkx to include OutMultiEdgeView that accepts
 1507            # from/to/key tuples as indices.
 1508            info = cast(
 1509                TransitionProperties,
 1510                self.edges[dID, dest, transition]  # type:ignore
 1511            )
 1512            info['tags'] = tags
 1513        if annotations is not None:
 1514            dest = self.destination(dID, transition)
 1515            info = cast(
 1516                TransitionProperties,
 1517                self.edges[dID, dest, transition]  # type:ignore
 1518            )
 1519            info['annotations'] = annotations
 1520
 1521    def getTransitionRequirement(
 1522        self,
 1523        decision: base.AnyDecisionSpecifier,
 1524        transition: base.Transition
 1525    ) -> base.Requirement:
 1526        """
 1527        Returns the `Requirement` for accessing a specific transition at
 1528        a specific decision. For transitions which don't have
 1529        requirements, returns a `ReqNothing` instance.
 1530        """
 1531        dID = self.resolveDecision(decision)
 1532        dest = self.destination(dID, transition)
 1533
 1534        info = cast(
 1535            TransitionProperties,
 1536            self.edges[dID, dest, transition]  # type:ignore
 1537        )
 1538
 1539        return info.get('requirement', base.ReqNothing())
 1540
 1541    def setTransitionRequirement(
 1542        self,
 1543        decision: base.AnyDecisionSpecifier,
 1544        transition: base.Transition,
 1545        requirement: Optional[base.Requirement]
 1546    ) -> None:
 1547        """
 1548        Sets the `Requirement` for accessing a specific transition at
 1549        a specific decision. Raises a `KeyError` if the decision or
 1550        transition does not exist.
 1551
 1552        Deletes the requirement if `None` is given as the requirement.
 1553
 1554        Use `parsing.ParseFormat.parseRequirement` first if you have a
 1555        requirement in string format.
 1556
 1557        Does not raise an error if deletion is requested for a
 1558        non-existent requirement, and silently overwrites any previous
 1559        requirement.
 1560        """
 1561        dID = self.resolveDecision(decision)
 1562
 1563        dest = self.destination(dID, transition)
 1564
 1565        info = cast(
 1566            TransitionProperties,
 1567            self.edges[dID, dest, transition]  # type:ignore
 1568        )
 1569
 1570        if requirement is None:
 1571            try:
 1572                del info['requirement']
 1573            except KeyError:
 1574                pass
 1575        else:
 1576            if not isinstance(requirement, base.Requirement):
 1577                raise TypeError(
 1578                    f"Invalid requirement type: {type(requirement)}"
 1579                )
 1580
 1581            info['requirement'] = requirement
 1582
 1583    def getConsequence(
 1584        self,
 1585        decision: base.AnyDecisionSpecifier,
 1586        transition: base.Transition
 1587    ) -> base.Consequence:
 1588        """
 1589        Retrieves the consequence of a transition.
 1590
 1591        A `KeyError` is raised if the specified decision/transition
 1592        combination doesn't exist.
 1593        """
 1594        dID = self.resolveDecision(decision)
 1595
 1596        dest = self.destination(dID, transition)
 1597
 1598        info = cast(
 1599            TransitionProperties,
 1600            self.edges[dID, dest, transition]  # type:ignore
 1601        )
 1602
 1603        return info.get('consequence', [])
 1604
 1605    def addConsequence(
 1606        self,
 1607        decision: base.AnyDecisionSpecifier,
 1608        transition: base.Transition,
 1609        consequence: base.Consequence
 1610    ) -> Tuple[int, int]:
 1611        """
 1612        Adds the given `Consequence` to the consequence list for the
 1613        specified transition, extending that list at the end. Note that
 1614        this does NOT make a copy of the consequence, so it should not
 1615        be used to copy consequences from one transition to another
 1616        without making a deep copy first.
 1617
 1618        A `MissingDecisionError` or a `MissingTransitionError` is raised
 1619        if the specified decision/transition combination doesn't exist.
 1620
 1621        Returns a pair of integers indicating the minimum and maximum
 1622        depth-first-traversal-indices of the added consequence part(s)
 1623        (inclusive).
 1624
 1625        The outer consequence list itself (index 0) is not counted.
 1626
 1627        >>> d = DecisionGraph()
 1628        >>> d.addDecision('A')
 1629        0
 1630        >>> d.addDecision('B')
 1631        1
 1632        >>> d.addTransition('A', 'fwd', 'B', 'rev')
 1633        >>> d.addConsequence('A', 'fwd', [base.effect(gain='sword')])
 1634        (1, 1)
 1635        >>> d.addConsequence('B', 'rev', [base.effect(lose='sword')])
 1636        (1, 1)
 1637        >>> ef = d.getConsequence('A', 'fwd')
 1638        >>> er = d.getConsequence('B', 'rev')
 1639        >>> ef == [base.effect(gain='sword')]
 1640        True
 1641        >>> er == [base.effect(lose='sword')]
 1642        True
 1643        >>> d.addConsequence('A', 'fwd', [base.effect(deactivate=True)])
 1644        (2, 2)
 1645        >>> ef = d.getConsequence('A', 'fwd')
 1646        >>> ef == [base.effect(gain='sword'), base.effect(deactivate=True)]
 1647        True
 1648        >>> d.addConsequence(
 1649        ...     'A',
 1650        ...     'fwd',  # adding to consequence with 3 parts already
 1651        ...     [  # outer list not counted because it merges
 1652        ...         base.challenge(  # 1 part
 1653        ...             None,
 1654        ...             0,
 1655        ...             [base.effect(gain=('flowers', 3))],  # 2 parts
 1656        ...             [base.effect(gain=('flowers', 1))]  # 2 parts
 1657        ...         )
 1658        ...     ]
 1659        ... )  # note indices below are inclusive; indices are 3, 4, 5, 6, 7
 1660        (3, 7)
 1661        """
 1662        dID = self.resolveDecision(decision)
 1663
 1664        dest = self.destination(dID, transition)
 1665
 1666        info = cast(
 1667            TransitionProperties,
 1668            self.edges[dID, dest, transition]  # type:ignore
 1669        )
 1670
 1671        existing = info.setdefault('consequence', [])
 1672        startIndex = base.countParts(existing)
 1673        existing.extend(consequence)
 1674        endIndex = base.countParts(existing) - 1
 1675        return (startIndex, endIndex)
 1676
 1677    def setConsequence(
 1678        self,
 1679        decision: base.AnyDecisionSpecifier,
 1680        transition: base.Transition,
 1681        consequence: base.Consequence
 1682    ) -> None:
 1683        """
 1684        Replaces the transition consequence for the given transition at
 1685        the given decision. Any previous consequence is discarded. See
 1686        `Consequence` for the structure of these. Note that this does
 1687        NOT make a copy of the consequence, do that first to avoid
 1688        effect-entanglement if you're copying a consequence.
 1689
 1690        A `MissingDecisionError` or a `MissingTransitionError` is raised
 1691        if the specified decision/transition combination doesn't exist.
 1692        """
 1693        dID = self.resolveDecision(decision)
 1694
 1695        dest = self.destination(dID, transition)
 1696
 1697        info = cast(
 1698            TransitionProperties,
 1699            self.edges[dID, dest, transition]  # type:ignore
 1700        )
 1701
 1702        info['consequence'] = consequence
 1703
 1704    def addEquivalence(
 1705        self,
 1706        requirement: base.Requirement,
 1707        capabilityOrMechanismState: Union[
 1708            base.Capability,
 1709            Tuple[base.MechanismID, base.MechanismState]
 1710        ]
 1711    ) -> None:
 1712        """
 1713        Adds the given requirement as an equivalence for the given
 1714        capability or the given mechanism state. Note that having a
 1715        capability via an equivalence does not count as actually having
 1716        that capability; it only counts for the purpose of satisfying
 1717        `Requirement`s.
 1718
 1719        Note also that because a mechanism-based requirement looks up
 1720        the specific mechanism locally based on a name, an equivalence
 1721        defined in one location may affect mechanism requirements in
 1722        other locations unless the mechanism name in the requirement is
 1723        zone-qualified to be specific. But in such situations the base
 1724        mechanism would have caused issues in any case.
 1725        """
 1726        self.equivalences.setdefault(
 1727            capabilityOrMechanismState,
 1728            set()
 1729        ).add(requirement)
 1730
 1731    def removeEquivalence(
 1732        self,
 1733        requirement: base.Requirement,
 1734        capabilityOrMechanismState: Union[
 1735            base.Capability,
 1736            Tuple[base.MechanismID, base.MechanismState]
 1737        ]
 1738    ) -> None:
 1739        """
 1740        Removes an equivalence. Raises a `KeyError` if no such
 1741        equivalence existed.
 1742        """
 1743        self.equivalences[capabilityOrMechanismState].remove(requirement)
 1744
 1745    def hasAnyEquivalents(
 1746        self,
 1747        capabilityOrMechanismState: Union[
 1748            base.Capability,
 1749            Tuple[base.MechanismID, base.MechanismState]
 1750        ]
 1751    ) -> bool:
 1752        """
 1753        Returns `True` if the given capability or mechanism state has at
 1754        least one equivalence.
 1755        """
 1756        return capabilityOrMechanismState in self.equivalences
 1757
 1758    def allEquivalents(
 1759        self,
 1760        capabilityOrMechanismState: Union[
 1761            base.Capability,
 1762            Tuple[base.MechanismID, base.MechanismState]
 1763        ]
 1764    ) -> Set[base.Requirement]:
 1765        """
 1766        Returns the set of equivalences for the given capability. This is
 1767        a live set which may be modified (it's probably better to use
 1768        `addEquivalence` and `removeEquivalence` instead...).
 1769        """
 1770        return self.equivalences.setdefault(
 1771            capabilityOrMechanismState,
 1772            set()
 1773        )
 1774
 1775    def reversionType(self, name: str, equivalentTo: Set[str]) -> None:
 1776        """
 1777        Specifies a new reversion type, so that when used in a reversion
 1778        aspects set with a colon before the name, all items in the
 1779        `equivalentTo` value will be added to that set. These may
 1780        include other custom reversion type names (with the colon) but
 1781        take care not to create an equivalence loop which would result
 1782        in a crash.
 1783
 1784        If you re-use the same name, it will override the old equivalence
 1785        for that name.
 1786        """
 1787        self.reversionTypes[name] = equivalentTo
 1788
 1789    def addAction(
 1790        self,
 1791        decision: base.AnyDecisionSpecifier,
 1792        action: base.Transition,
 1793        requires: Optional[base.Requirement] = None,
 1794        consequence: Optional[base.Consequence] = None,
 1795        tags: Optional[Dict[base.Tag, base.TagValue]] = None,
 1796        annotations: Optional[List[base.Annotation]] = None,
 1797    ) -> None:
 1798        """
 1799        Adds the given action as a possibility at the given decision. An
 1800        action is just a self-edge, which can have requirements like any
 1801        edge, and which can have consequences like any edge.
 1802        The optional arguments are given to `setTransitionRequirement`
 1803        and `setConsequence`; see those functions for descriptions
 1804        of what they mean.
 1805
 1806        Raises a `KeyError` if a transition with the given name already
 1807        exists at the given decision.
 1808        """
 1809        if tags is None:
 1810            tags = {}
 1811        if annotations is None:
 1812            annotations = []
 1813
 1814        dID = self.resolveDecision(decision)
 1815
 1816        self.add_edge(
 1817            dID,
 1818            dID,
 1819            key=action,
 1820            tags=tags,
 1821            annotations=annotations
 1822        )
 1823        self.setTransitionRequirement(dID, action, requires)
 1824        if consequence is not None:
 1825            self.setConsequence(dID, action, consequence)
 1826
 1827    def tagDecision(
 1828        self,
 1829        decision: base.AnyDecisionSpecifier,
 1830        tagOrTags: Union[base.Tag, Dict[base.Tag, base.TagValue]],
 1831        tagValue: Union[
 1832            base.TagValue,
 1833            type[base.NoTagValue]
 1834        ] = base.NoTagValue
 1835    ) -> None:
 1836        """
 1837        Adds a tag (or many tags from a dictionary of tags) to a
 1838        decision, using `1` as the value if no value is provided. It's
 1839        a `ValueError` to provide a value when a dictionary of tags is
 1840        provided to set multiple tags at once.
 1841
 1842        Note that certain tags have special meanings:
 1843
 1844        - 'unconfirmed' is used for decisions that represent unconfirmed
 1845            parts of the graph (this is separate from the 'unknown'
 1846            and/or 'hypothesized' exploration statuses, which are only
 1847            tracked in a `DiscreteExploration`, not in a `DecisionGraph`).
 1848            Various methods require this tag and many also add or remove
 1849            it.
 1850        """
 1851        if isinstance(tagOrTags, base.Tag):
 1852            if tagValue is base.NoTagValue:
 1853                tagValue = 1
 1854
 1855            # Not sure why this cast is necessary given the `if` above...
 1856            tagValue = cast(base.TagValue, tagValue)
 1857
 1858            tagOrTags = {tagOrTags: tagValue}
 1859
 1860        elif tagValue is not base.NoTagValue:
 1861            raise ValueError(
 1862                "Provided a dictionary to update multiple tags, but"
 1863                " also a tag value."
 1864            )
 1865
 1866        dID = self.resolveDecision(decision)
 1867
 1868        tagsAlready = self.nodes[dID].setdefault('tags', {})
 1869        tagsAlready.update(tagOrTags)
 1870
 1871    def untagDecision(
 1872        self,
 1873        decision: base.AnyDecisionSpecifier,
 1874        tag: base.Tag
 1875    ) -> Union[base.TagValue, type[base.NoTagValue]]:
 1876        """
 1877        Removes a tag from a decision. Returns the tag's old value if
 1878        the tag was present and got removed, or `NoTagValue` if the tag
 1879        wasn't present.
 1880        """
 1881        dID = self.resolveDecision(decision)
 1882
 1883        target = self.nodes[dID]['tags']
 1884        try:
 1885            return target.pop(tag)
 1886        except KeyError:
 1887            return base.NoTagValue
 1888
 1889    def decisionTags(
 1890        self,
 1891        decision: base.AnyDecisionSpecifier
 1892    ) -> Dict[base.Tag, base.TagValue]:
 1893        """
 1894        Returns the dictionary of tags for a decision. Edits to the
 1895        returned value will be applied to the graph.
 1896        """
 1897        dID = self.resolveDecision(decision)
 1898
 1899        return self.nodes[dID]['tags']
 1900
 1901    def annotateDecision(
 1902        self,
 1903        decision: base.AnyDecisionSpecifier,
 1904        annotationOrAnnotations: Union[
 1905            base.Annotation,
 1906            Sequence[base.Annotation]
 1907        ]
 1908    ) -> None:
 1909        """
 1910        Adds an annotation to a decision's annotations list.
 1911        """
 1912        dID = self.resolveDecision(decision)
 1913
 1914        if isinstance(annotationOrAnnotations, base.Annotation):
 1915            annotationOrAnnotations = [annotationOrAnnotations]
 1916        self.nodes[dID]['annotations'].extend(annotationOrAnnotations)
 1917
 1918    def decisionAnnotations(
 1919        self,
 1920        decision: base.AnyDecisionSpecifier
 1921    ) -> List[base.Annotation]:
 1922        """
 1923        Returns the list of annotations for the specified decision.
 1924        Modifying the list affects the graph.
 1925        """
 1926        dID = self.resolveDecision(decision)
 1927
 1928        return self.nodes[dID]['annotations']
 1929
 1930    def tagTransition(
 1931        self,
 1932        decision: base.AnyDecisionSpecifier,
 1933        transition: base.Transition,
 1934        tagOrTags: Union[base.Tag, Dict[base.Tag, base.TagValue]],
 1935        tagValue: Union[
 1936            base.TagValue,
 1937            type[base.NoTagValue]
 1938        ] = base.NoTagValue
 1939    ) -> None:
 1940        """
 1941        Adds a tag (or each tag from a dictionary) to a transition
 1942        coming out of a specific decision. `1` will be used as the
 1943        default value if a single tag is supplied; supplying a tag value
 1944        when providing a dictionary of multiple tags to update is a
 1945        `ValueError`.
 1946
 1947        Note that certain transition tags have special meanings:
 1948        - 'trigger' causes any actions (but not normal transitions) that
 1949            it applies to to be automatically triggered when
 1950            `advanceSituation` is called and the decision they're
 1951            attached to is active in the new situation (as long as the
 1952            action's requirements are met). This happens once per
 1953            situation; use 'wait' steps to re-apply triggers.
 1954        """
 1955        dID = self.resolveDecision(decision)
 1956
 1957        dest = self.destination(dID, transition)
 1958        if isinstance(tagOrTags, base.Tag):
 1959            if tagValue is base.NoTagValue:
 1960                tagValue = 1
 1961
 1962            # Not sure why this is necessary given the `if` above...
 1963            tagValue = cast(base.TagValue, tagValue)
 1964
 1965            tagOrTags = {tagOrTags: tagValue}
 1966        elif tagValue is not base.NoTagValue:
 1967            raise ValueError(
 1968                "Provided a dictionary to update multiple tags, but"
 1969                " also a tag value."
 1970            )
 1971
 1972        info = cast(
 1973            TransitionProperties,
 1974            self.edges[dID, dest, transition]  # type:ignore
 1975        )
 1976
 1977        info.setdefault('tags', {}).update(tagOrTags)
 1978
 1979    def untagTransition(
 1980        self,
 1981        decision: base.AnyDecisionSpecifier,
 1982        transition: base.Transition,
 1983        tagOrTags: Union[base.Tag, Set[base.Tag]]
 1984    ) -> None:
 1985        """
 1986        Removes a tag (or each tag in a set) from a transition coming out
 1987        of a specific decision. Raises a `KeyError` if (one of) the
 1988        specified tag(s) is not currently applied to the specified
 1989        transition.
 1990        """
 1991        dID = self.resolveDecision(decision)
 1992
 1993        dest = self.destination(dID, transition)
 1994        if isinstance(tagOrTags, base.Tag):
 1995            tagOrTags = {tagOrTags}
 1996
 1997        info = cast(
 1998            TransitionProperties,
 1999            self.edges[dID, dest, transition]  # type:ignore
 2000        )
 2001        tagsAlready = info.setdefault('tags', {})
 2002
 2003        for tag in tagOrTags:
 2004            tagsAlready.pop(tag)
 2005
 2006    def transitionTags(
 2007        self,
 2008        decision: base.AnyDecisionSpecifier,
 2009        transition: base.Transition
 2010    ) -> Dict[base.Tag, base.TagValue]:
 2011        """
 2012        Returns the dictionary of tags for a transition. Edits to the
 2013        returned dictionary will be applied to the graph.
 2014        """
 2015        dID = self.resolveDecision(decision)
 2016
 2017        dest = self.destination(dID, transition)
 2018        info = cast(
 2019            TransitionProperties,
 2020            self.edges[dID, dest, transition]  # type:ignore
 2021        )
 2022        return info.setdefault('tags', {})
 2023
 2024    def annotateTransition(
 2025        self,
 2026        decision: base.AnyDecisionSpecifier,
 2027        transition: base.Transition,
 2028        annotations: Union[base.Annotation, Sequence[base.Annotation]]
 2029    ) -> None:
 2030        """
 2031        Adds an annotation (or a sequence of annotations) to a
 2032        transition's annotations list.
 2033        """
 2034        dID = self.resolveDecision(decision)
 2035
 2036        dest = self.destination(dID, transition)
 2037        if isinstance(annotations, base.Annotation):
 2038            annotations = [annotations]
 2039        info = cast(
 2040            TransitionProperties,
 2041            self.edges[dID, dest, transition]  # type:ignore
 2042        )
 2043        info['annotations'].extend(annotations)
 2044
 2045    def transitionAnnotations(
 2046        self,
 2047        decision: base.AnyDecisionSpecifier,
 2048        transition: base.Transition
 2049    ) -> List[base.Annotation]:
 2050        """
 2051        Returns the annotation list for a specific transition at a
 2052        specific decision. Editing the list affects the graph.
 2053        """
 2054        dID = self.resolveDecision(decision)
 2055
 2056        dest = self.destination(dID, transition)
 2057        info = cast(
 2058            TransitionProperties,
 2059            self.edges[dID, dest, transition]  # type:ignore
 2060        )
 2061        return info['annotations']
 2062
 2063    def annotateZone(
 2064        self,
 2065        zone: base.Zone,
 2066        annotations: Union[base.Annotation, Sequence[base.Annotation]]
 2067    ) -> None:
 2068        """
 2069        Adds an annotation (or many annotations from a sequence) to a
 2070        zone.
 2071
 2072        Raises a `MissingZoneError` if the specified zone does not exist.
 2073        """
 2074        if zone not in self.zones:
 2075            raise MissingZoneError(
 2076                f"Can't add annotation(s) to zone {zone!r} because that"
 2077                f" zone doesn't exist yet."
 2078            )
 2079
 2080        if isinstance(annotations, base.Annotation):
 2081            annotations = [ annotations ]
 2082
 2083        self.zones[zone].annotations.extend(annotations)
 2084
 2085    def zoneAnnotations(self, zone: base.Zone) -> List[base.Annotation]:
 2086        """
 2087        Returns the list of annotations for the specified zone (empty if
 2088        none have been added yet).
 2089        """
 2090        return self.zones[zone].annotations
 2091
 2092    def tagZone(
 2093        self,
 2094        zone: base.Zone,
 2095        tagOrTags: Union[base.Tag, Dict[base.Tag, base.TagValue]],
 2096        tagValue: Union[
 2097            base.TagValue,
 2098            type[base.NoTagValue]
 2099        ] = base.NoTagValue
 2100    ) -> None:
 2101        """
 2102        Adds a tag (or many tags from a dictionary of tags) to a
 2103        zone, using `1` as the value if no value is provided. It's
 2104        a `ValueError` to provide a value when a dictionary of tags is
 2105        provided to set multiple tags at once.
 2106
 2107        Raises a `MissingZoneError` if the specified zone does not exist.
 2108        """
 2109        if zone not in self.zones:
 2110            raise MissingZoneError(
 2111                f"Can't add tag(s) to zone {zone!r} because that zone"
 2112                f" doesn't exist yet."
 2113            )
 2114
 2115        if isinstance(tagOrTags, base.Tag):
 2116            if tagValue is base.NoTagValue:
 2117                tagValue = 1
 2118
 2119            # Not sure why this cast is necessary given the `if` above...
 2120            tagValue = cast(base.TagValue, tagValue)
 2121
 2122            tagOrTags = {tagOrTags: tagValue}
 2123
 2124        elif tagValue is not base.NoTagValue:
 2125            raise ValueError(
 2126                "Provided a dictionary to update multiple tags, but"
 2127                " also a tag value."
 2128            )
 2129
 2130        tagsAlready = self.zones[zone].tags
 2131        tagsAlready.update(tagOrTags)
 2132
 2133    def untagZone(
 2134        self,
 2135        zone: base.Zone,
 2136        tag: base.Tag
 2137    ) -> Union[base.TagValue, type[base.NoTagValue]]:
 2138        """
 2139        Removes a tag from a zone. Returns the tag's old value if the
 2140        tag was present and got removed, or `NoTagValue` if the tag
 2141        wasn't present.
 2142
 2143        Raises a `MissingZoneError` if the specified zone does not exist.
 2144        """
 2145        if zone not in self.zones:
 2146            raise MissingZoneError(
 2147                f"Can't remove tag {tag!r} from zone {zone!r} because"
 2148                f" that zone doesn't exist yet."
 2149            )
 2150        target = self.zones[zone].tags
 2151        try:
 2152            return target.pop(tag)
 2153        except KeyError:
 2154            return base.NoTagValue
 2155
 2156    def zoneTags(
 2157        self,
 2158        zone: base.Zone
 2159    ) -> Dict[base.Tag, base.TagValue]:
 2160        """
 2161        Returns the dictionary of tags for a zone. Edits to the returned
 2162        value will be applied to the graph. Returns an empty tags
 2163        dictionary if called on a zone that didn't have any tags
 2164        previously, but raises a `MissingZoneError` if attempting to get
 2165        tags for a zone which does not exist.
 2166
 2167        For example:
 2168
 2169        >>> g = DecisionGraph()
 2170        >>> g.addDecision('A')
 2171        0
 2172        >>> g.addDecision('B')
 2173        1
 2174        >>> g.createZone('Zone')
 2175        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2176 annotations=[])
 2177        >>> g.tagZone('Zone', 'color', 'blue')
 2178        >>> g.tagZone(
 2179        ...     'Zone',
 2180        ...     {'shape': 'square', 'color': 'red', 'sound': 'loud'}
 2181        ... )
 2182        >>> g.untagZone('Zone', 'sound')
 2183        'loud'
 2184        >>> g.zoneTags('Zone')
 2185        {'color': 'red', 'shape': 'square'}
 2186        """
 2187        if zone in self.zones:
 2188            return self.zones[zone].tags
 2189        else:
 2190            raise MissingZoneError(
 2191                f"Tags for zone {zone!r} don't exist because that"
 2192                f" zone has not been created yet."
 2193            )
 2194
 2195    def createZone(self, zone: base.Zone, level: int = 0) -> base.ZoneInfo:
 2196        """
 2197        Creates an empty zone with the given name at the given level
 2198        (default 0). Raises a `ZoneCollisionError` if that zone name is
 2199        already in use (at any level), including if it's in use by a
 2200        decision.
 2201
 2202        Raises an `InvalidLevelError` if the level value is less than 0.
 2203
 2204        Returns the `ZoneInfo` for the new blank zone.
 2205
 2206        For example:
 2207
 2208        >>> d = DecisionGraph()
 2209        >>> d.createZone('Z', 0)
 2210        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2211 annotations=[])
 2212        >>> d.getZoneInfo('Z')
 2213        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2214 annotations=[])
 2215        >>> d.createZone('Z2', 0)
 2216        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2217 annotations=[])
 2218        >>> d.createZone('Z3', -1)  # level -1 is not valid (must be >= 0)
 2219        Traceback (most recent call last):
 2220        ...
 2221        exploration.core.InvalidLevelError...
 2222        >>> d.createZone('Z2')  # Name Z2 is already in use
 2223        Traceback (most recent call last):
 2224        ...
 2225        exploration.core.ZoneCollisionError...
 2226        """
 2227        if level < 0:
 2228            raise InvalidLevelError(
 2229                "Cannot create a zone with a negative level."
 2230            )
 2231        if zone in self.zones:
 2232            raise ZoneCollisionError(f"Zone {zone!r} already exists.")
 2233        if zone in self:
 2234            raise ZoneCollisionError(
 2235                f"A decision named {zone!r} already exists, so a zone"
 2236                f" with that name cannot be created."
 2237            )
 2238        info: base.ZoneInfo = base.ZoneInfo(
 2239            level=level,
 2240            parents=set(),
 2241            contents=set(),
 2242            tags={},
 2243            annotations=[]
 2244        )
 2245        self.zones[zone] = info
 2246        return info
 2247
 2248    def getZoneInfo(self, zone: base.Zone) -> Optional[base.ZoneInfo]:
 2249        """
 2250        Returns the `ZoneInfo` (level, parents, and contents) for the
 2251        specified zone, or `None` if that zone does not exist.
 2252
 2253        For example:
 2254
 2255        >>> d = DecisionGraph()
 2256        >>> d.createZone('Z', 0)
 2257        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2258 annotations=[])
 2259        >>> d.getZoneInfo('Z')
 2260        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2261 annotations=[])
 2262        >>> d.createZone('Z2', 0)
 2263        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2264 annotations=[])
 2265        >>> d.getZoneInfo('Z2')
 2266        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2267 annotations=[])
 2268        """
 2269        return self.zones.get(zone)
 2270
 2271    def deleteZone(self, zone: base.Zone) -> base.ZoneInfo:
 2272        """
 2273        Deletes the specified zone, returning a `ZoneInfo` object with
 2274        the information on the level, parents, and contents of that zone.
 2275
 2276        Raises a `MissingZoneError` if the zone in question does not
 2277        exist.
 2278
 2279        The zone will be removed as a child/parent of any zones that used
 2280        to contain it or be contained in it.
 2281
 2282        For example:
 2283
 2284        >>> d = DecisionGraph()
 2285        >>> d.createZone('Z', 0)
 2286        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2287 annotations=[])
 2288        >>> d.getZoneInfo('Z')
 2289        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2290 annotations=[])
 2291        >>> d.deleteZone('Z')
 2292        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2293 annotations=[])
 2294        >>> d.getZoneInfo('Z') is None  # no info any more
 2295        True
 2296        >>> d.deleteZone('Z')  # can't re-delete
 2297        Traceback (most recent call last):
 2298        ...
 2299        exploration.core.MissingZoneError...
 2300        """
 2301        info = self.getZoneInfo(zone)
 2302        if info is None:
 2303            raise MissingZoneError(
 2304                f"Cannot delete zone {zone!r}: it does not exist."
 2305            )
 2306        for sub in info.contents:
 2307            if 'zones' in self.nodes[sub]:
 2308                try:
 2309                    self.nodes[sub]['zones'].remove(zone)
 2310                except KeyError:
 2311                    pass
 2312        del self.zones[zone]
 2313        # Clean up child/contents info in ALL other zones
 2314        for otherZoneInfo in self.zones.values():
 2315            if zone in otherZoneInfo.parents:
 2316                otherZoneInfo.parents.remove(zone)
 2317            if zone in otherZoneInfo.contents:
 2318                otherZoneInfo.contents.remove(zone)
 2319        return info
 2320
 2321    def addDecisionToZone(
 2322        self,
 2323        decision: base.AnyDecisionSpecifier,
 2324        zone: base.Zone
 2325    ) -> None:
 2326        """
 2327        Adds a decision directly to a zone. Should normally only be used
 2328        with level-0 zones. Raises a `MissingZoneError` if the specified
 2329        zone did not already exist.
 2330
 2331        For example:
 2332
 2333        >>> d = DecisionGraph()
 2334        >>> d.addDecision('A')
 2335        0
 2336        >>> d.addDecision('B')
 2337        1
 2338        >>> d.addDecision('C')
 2339        2
 2340        >>> d.createZone('Z', 0)
 2341        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2342 annotations=[])
 2343        >>> d.addDecisionToZone('A', 'Z')
 2344        >>> d.getZoneInfo('Z')
 2345        ZoneInfo(level=0, parents=set(), contents={0}, tags={},\
 2346 annotations=[])
 2347        >>> d.addDecisionToZone('B', 'Z')
 2348        >>> d.getZoneInfo('Z')
 2349        ZoneInfo(level=0, parents=set(), contents={0, 1}, tags={},\
 2350 annotations=[])
 2351        """
 2352        dID = self.resolveDecision(decision)
 2353
 2354        if zone not in self.zones:
 2355            raise MissingZoneError(f"Zone {zone!r} does not exist.")
 2356
 2357        self.zones[zone].contents.add(dID)
 2358        self.nodes[dID].setdefault('zones', set()).add(zone)
 2359
 2360    def removeDecisionFromZone(
 2361        self,
 2362        decision: base.AnyDecisionSpecifier,
 2363        zone: base.Zone,
 2364        thorough: bool = False
 2365    ) -> bool:
 2366        """
 2367        Removes a decision from a zone if it had been in it, returning
 2368        True if that decision had been in that zone, and False if it was
 2369        not in that zone, including if that zone didn't exist.
 2370
 2371        Note that this only removes a decision from direct zone
 2372        membership. If the decision is a member of one or more zones
 2373        which are (directly or indirectly) sub-zones of the target zone,
 2374        the decision will remain in those zones, and will still be
 2375        indirectly part of the target zone afterwards. You can set
 2376        `thorough` to True to also remove the decision from any immediate
 2377        parents which are descendants of the specified zone, thereby
 2378        ensuring that it isn't afterwards even indirectly included in
 2379        that zone, even though this may affect membership in multiple
 2380        zones at different levels.
 2381
 2382        When 'thorough' is used the result is True even if the decision
 2383        had been an indirect member of the target zone; without it,
 2384        False is returned for indirect members.
 2385
 2386        Examples:
 2387
 2388        >>> g = DecisionGraph()
 2389        >>> g.addDecision('A')
 2390        0
 2391        >>> g.addDecision('B')
 2392        1
 2393        >>> g.createZone('level0', 0)
 2394        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2395 annotations=[])
 2396        >>> g.createZone('level1', 1)
 2397        ZoneInfo(level=1, parents=set(), contents=set(), tags={},\
 2398 annotations=[])
 2399        >>> g.createZone('level2', 2)
 2400        ZoneInfo(level=2, parents=set(), contents=set(), tags={},\
 2401 annotations=[])
 2402        >>> g.createZone('level3', 3)
 2403        ZoneInfo(level=3, parents=set(), contents=set(), tags={},\
 2404 annotations=[])
 2405        >>> g.addDecisionToZone('A', 'level0')
 2406        >>> g.addDecisionToZone('B', 'level0')
 2407        >>> g.addZoneToZone('level0', 'level1')
 2408        >>> g.addZoneToZone('level1', 'level2')
 2409        >>> g.addZoneToZone('level2', 'level3')
 2410        >>> g.addDecisionToZone('B', 'level2')  # Direct w/ skips
 2411        >>> g.removeDecisionFromZone('A', 'level1')
 2412        False
 2413        >>> g.zoneParents(0)
 2414        {'level0'}
 2415        >>> g.removeDecisionFromZone('A', 'level0')
 2416        True
 2417        >>> g.zoneParents(0)
 2418        set()
 2419        >>> g.removeDecisionFromZone('A', 'level0')
 2420        False
 2421        >>> g.removeDecisionFromZone('B', 'level0')
 2422        True
 2423        >>> g.zoneParents(1)
 2424        {'level2'}
 2425        >>> g.removeDecisionFromZone('B', 'level0')
 2426        False
 2427        >>> g.removeDecisionFromZone('B', 'level2')
 2428        True
 2429        >>> g.zoneParents(1)
 2430        set()
 2431
 2432        Example of 'thorough' argument:
 2433
 2434        >>> g = DecisionGraph()
 2435        >>> g.addDecision('A')
 2436        0
 2437        >>> g.addDecision('B')
 2438        1
 2439        >>> g.addDecision('C')
 2440        2
 2441        >>> g.createZone('level0', 0)
 2442        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2443 annotations=[])
 2444        >>> g.createZone('level1', 1)
 2445        ZoneInfo(level=1, parents=set(), contents=set(), tags={},\
 2446 annotations=[])
 2447        >>> g.addDecisionToZone('A', 'level0')
 2448        >>> g.addDecisionToZone('B', 'level0')
 2449        >>> g.addDecisionToZone('C', 'level0')
 2450        >>> g.addDecisionToZone('B', 'level1')  # also direct
 2451        >>> g.addDecisionToZone('C', 'level1')  # also direct
 2452        >>> g.addZoneToZone('level0', 'level1')
 2453        >>> g.removeDecisionFromZone('A', 'level1')  # indirect member
 2454        False
 2455        >>> g.allDecisionsInZone('level1')  # A is still in there indirectly
 2456        {0, 1, 2}
 2457        >>> g.removeDecisionFromZone('A', 'level1', True)
 2458        True
 2459        >>> g.allDecisionsInZone('level1')  # A is now gone
 2460        {1, 2}
 2461        >>> g.zoneParents(0)  # removed from 'level0'
 2462        set()
 2463        >>> g.removeDecisionFromZone('B', 'level1')  # not thorough
 2464        True
 2465        >>> g.allDecisionsInZone('level1')  # B still there indirectly
 2466        {1, 2}
 2467        >>> g.removeDecisionFromZone('B', 'level1', True)  # thorough
 2468        True
 2469        >>> g.allDecisionsInZone('level1')  # now gone
 2470        {2}
 2471        >>> g.removeDecisionFromZone('C', 'level1', True)  # 1st time
 2472        True
 2473        >>> g.allDecisionsInZone('level1')  # now gone
 2474        set()
 2475        """
 2476        dID = self.resolveDecision(decision)
 2477
 2478        if zone not in self.zones:
 2479            return False
 2480
 2481        if thorough:
 2482            parents = self.nodes[dID]['zones']  # editable reference
 2483            discard = set()
 2484            for parentZone in parents:
 2485                if parentZone == zone:
 2486                    info = self.zones[parentZone]
 2487                    info.contents.remove(dID)
 2488                    discard.add(zone)
 2489                elif zone in self.zoneAncestors(parentZone):
 2490                    info = self.zones[parentZone]
 2491                    info.contents.remove(dID)
 2492                    discard.add(parentZone)
 2493            if discard:
 2494                for indirectZone in discard:
 2495                    parents.remove(indirectZone)
 2496                return True
 2497            else:
 2498                return False
 2499        else:
 2500            info = self.zones[zone]
 2501            if dID not in info.contents:
 2502                return False
 2503            else:
 2504                info.contents.remove(dID)
 2505                try:
 2506                    self.nodes[dID]['zones'].remove(zone)
 2507                except KeyError:
 2508                    pass
 2509                return True
 2510
 2511    def addZoneToZone(
 2512        self,
 2513        addIt: base.Zone,
 2514        addTo: base.Zone
 2515    ) -> None:
 2516        """
 2517        Adds a zone to another zone. The `addIt` one must be at a
 2518        strictly lower level than the `addTo` zone, or an
 2519        `InvalidLevelError` will be raised.
 2520
 2521        If the zone to be added didn't already exist, it is created at
 2522        one level below the target zone. Similarly, if the zone being
 2523        added to didn't already exist, it is created at one level above
 2524        the target zone. If neither existed, a `MissingZoneError` will
 2525        be raised.
 2526
 2527        For example:
 2528
 2529        >>> d = DecisionGraph()
 2530        >>> d.addDecision('A')
 2531        0
 2532        >>> d.addDecision('B')
 2533        1
 2534        >>> d.addDecision('C')
 2535        2
 2536        >>> d.createZone('Z', 0)
 2537        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2538 annotations=[])
 2539        >>> d.addDecisionToZone('A', 'Z')
 2540        >>> d.addDecisionToZone('B', 'Z')
 2541        >>> d.getZoneInfo('Z')
 2542        ZoneInfo(level=0, parents=set(), contents={0, 1}, tags={},\
 2543 annotations=[])
 2544        >>> d.createZone('Z2', 0)
 2545        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2546 annotations=[])
 2547        >>> d.addDecisionToZone('B', 'Z2')
 2548        >>> d.addDecisionToZone('C', 'Z2')
 2549        >>> d.getZoneInfo('Z2')
 2550        ZoneInfo(level=0, parents=set(), contents={1, 2}, tags={},\
 2551 annotations=[])
 2552        >>> d.createZone('l1Z', 1)
 2553        ZoneInfo(level=1, parents=set(), contents=set(), tags={},\
 2554 annotations=[])
 2555        >>> d.createZone('l2Z', 2)
 2556        ZoneInfo(level=2, parents=set(), contents=set(), tags={},\
 2557 annotations=[])
 2558        >>> d.addZoneToZone('Z', 'l1Z')
 2559        >>> d.getZoneInfo('Z')
 2560        ZoneInfo(level=0, parents={'l1Z'}, contents={0, 1}, tags={},\
 2561 annotations=[])
 2562        >>> d.getZoneInfo('l1Z')
 2563        ZoneInfo(level=1, parents=set(), contents={'Z'}, tags={},\
 2564 annotations=[])
 2565        >>> d.addZoneToZone('l1Z', 'l2Z')
 2566        >>> d.getZoneInfo('l1Z')
 2567        ZoneInfo(level=1, parents={'l2Z'}, contents={'Z'}, tags={},\
 2568 annotations=[])
 2569        >>> d.getZoneInfo('l2Z')
 2570        ZoneInfo(level=2, parents=set(), contents={'l1Z'}, tags={},\
 2571 annotations=[])
 2572        >>> d.addZoneToZone('Z2', 'l2Z')
 2573        >>> d.getZoneInfo('Z2')
 2574        ZoneInfo(level=0, parents={'l2Z'}, contents={1, 2}, tags={},\
 2575 annotations=[])
 2576        >>> l2i = d.getZoneInfo('l2Z')
 2577        >>> l2i.level
 2578        2
 2579        >>> l2i.parents
 2580        set()
 2581        >>> sorted(l2i.contents)
 2582        ['Z2', 'l1Z']
 2583        >>> d.addZoneToZone('NZ', 'NZ2')
 2584        Traceback (most recent call last):
 2585        ...
 2586        exploration.core.MissingZoneError...
 2587        >>> d.addZoneToZone('Z', 'l1Z2')
 2588        >>> zi = d.getZoneInfo('Z')
 2589        >>> zi.level
 2590        0
 2591        >>> sorted(zi.parents)
 2592        ['l1Z', 'l1Z2']
 2593        >>> sorted(zi.contents)
 2594        [0, 1]
 2595        >>> d.getZoneInfo('l1Z2')
 2596        ZoneInfo(level=1, parents=set(), contents={'Z'}, tags={},\
 2597 annotations=[])
 2598        >>> d.addZoneToZone('NZ', 'l1Z')
 2599        >>> d.getZoneInfo('NZ')
 2600        ZoneInfo(level=0, parents={'l1Z'}, contents=set(), tags={},\
 2601 annotations=[])
 2602        >>> zi = d.getZoneInfo('l1Z')
 2603        >>> zi.level
 2604        1
 2605        >>> zi.parents
 2606        {'l2Z'}
 2607        >>> sorted(zi.contents)
 2608        ['NZ', 'Z']
 2609        """
 2610        # Create one or the other (but not both) if they're missing
 2611        addInfo = self.getZoneInfo(addIt)
 2612        toInfo = self.getZoneInfo(addTo)
 2613        if addInfo is None and toInfo is None:
 2614            raise MissingZoneError(
 2615                f"Cannot add zone {addIt!r} to zone {addTo!r}: neither"
 2616                f" exists already."
 2617            )
 2618
 2619        # Create missing addIt
 2620        elif addInfo is None:
 2621            toInfo = cast(base.ZoneInfo, toInfo)
 2622            newLevel = toInfo.level - 1
 2623            if newLevel < 0:
 2624                raise InvalidLevelError(
 2625                    f"Zone {addTo!r} is at level {toInfo.level} and so"
 2626                    f" a new zone cannot be added underneath it."
 2627                )
 2628            addInfo = self.createZone(addIt, newLevel)
 2629
 2630        # Create missing addTo
 2631        elif toInfo is None:
 2632            addInfo = cast(base.ZoneInfo, addInfo)
 2633            newLevel = addInfo.level + 1
 2634            if newLevel < 0:
 2635                raise InvalidLevelError(
 2636                    f"Zone {addIt!r} is at level {addInfo.level} (!!!)"
 2637                    f" and so a new zone cannot be added above it."
 2638                )
 2639            toInfo = self.createZone(addTo, newLevel)
 2640
 2641        # Now both addInfo and toInfo are defined
 2642        if addInfo.level >= toInfo.level:
 2643            raise InvalidLevelError(
 2644                f"Cannot add zone {addIt!r} at level {addInfo.level}"
 2645                f" to zone {addTo!r} at level {toInfo.level}: zones can"
 2646                f" only contain zones of lower levels."
 2647            )
 2648
 2649        # Now both addInfo and toInfo are defined
 2650        toInfo.contents.add(addIt)
 2651        addInfo.parents.add(addTo)
 2652
 2653    def removeZoneFromZone(
 2654        self,
 2655        removeIt: base.Zone,
 2656        removeFrom: base.Zone
 2657    ) -> bool:
 2658        """
 2659        Removes a zone from a zone if it had been in it, returning True
 2660        if that zone had been in that zone, and False if it was not in
 2661        that zone, including if either zone did not exist.
 2662
 2663        For example:
 2664
 2665        >>> d = DecisionGraph()
 2666        >>> d.createZone('Z', 0)
 2667        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2668 annotations=[])
 2669        >>> d.createZone('Z2', 0)
 2670        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2671 annotations=[])
 2672        >>> d.createZone('l1Z', 1)
 2673        ZoneInfo(level=1, parents=set(), contents=set(), tags={},\
 2674 annotations=[])
 2675        >>> d.createZone('l2Z', 2)
 2676        ZoneInfo(level=2, parents=set(), contents=set(), tags={},\
 2677 annotations=[])
 2678        >>> d.addZoneToZone('Z', 'l1Z')
 2679        >>> d.addZoneToZone('l1Z', 'l2Z')
 2680        >>> d.getZoneInfo('Z')
 2681        ZoneInfo(level=0, parents={'l1Z'}, contents=set(), tags={},\
 2682 annotations=[])
 2683        >>> d.getZoneInfo('l1Z')
 2684        ZoneInfo(level=1, parents={'l2Z'}, contents={'Z'}, tags={},\
 2685 annotations=[])
 2686        >>> d.getZoneInfo('l2Z')
 2687        ZoneInfo(level=2, parents=set(), contents={'l1Z'}, tags={},\
 2688 annotations=[])
 2689        >>> d.removeZoneFromZone('l1Z', 'l2Z')
 2690        True
 2691        >>> d.getZoneInfo('l1Z')
 2692        ZoneInfo(level=1, parents=set(), contents={'Z'}, tags={},\
 2693 annotations=[])
 2694        >>> d.getZoneInfo('l2Z')
 2695        ZoneInfo(level=2, parents=set(), contents=set(), tags={},\
 2696 annotations=[])
 2697        >>> d.removeZoneFromZone('Z', 'l1Z')
 2698        True
 2699        >>> d.getZoneInfo('Z')
 2700        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2701 annotations=[])
 2702        >>> d.getZoneInfo('l1Z')
 2703        ZoneInfo(level=1, parents=set(), contents=set(), tags={},\
 2704 annotations=[])
 2705        >>> d.removeZoneFromZone('Z', 'l1Z')
 2706        False
 2707        >>> d.removeZoneFromZone('Z', 'madeup')
 2708        False
 2709        >>> d.removeZoneFromZone('nope', 'madeup')
 2710        False
 2711        >>> d.removeZoneFromZone('nope', 'l1Z')
 2712        False
 2713        """
 2714        remInfo = self.getZoneInfo(removeIt)
 2715        fromInfo = self.getZoneInfo(removeFrom)
 2716
 2717        if remInfo is None or fromInfo is None:
 2718            return False
 2719
 2720        if removeIt not in fromInfo.contents:
 2721            return False
 2722
 2723        remInfo.parents.remove(removeFrom)
 2724        fromInfo.contents.remove(removeIt)
 2725        return True
 2726
 2727    def decisionsInZone(self, zone: base.Zone) -> Set[base.DecisionID]:
 2728        """
 2729        Returns a set of all decisions included directly in the given
 2730        zone, not counting decisions included via intermediate
 2731        sub-zones (see `allDecisionsInZone` to include those).
 2732
 2733        Raises a `MissingZoneError` if the specified zone does not
 2734        exist.
 2735
 2736        The returned set is a copy, not a live editable set.
 2737
 2738        For example:
 2739
 2740        >>> d = DecisionGraph()
 2741        >>> d.addDecision('A')
 2742        0
 2743        >>> d.addDecision('B')
 2744        1
 2745        >>> d.addDecision('C')
 2746        2
 2747        >>> d.createZone('Z', 0)
 2748        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2749 annotations=[])
 2750        >>> d.addDecisionToZone('A', 'Z')
 2751        >>> d.addDecisionToZone('B', 'Z')
 2752        >>> d.getZoneInfo('Z')
 2753        ZoneInfo(level=0, parents=set(), contents={0, 1}, tags={},\
 2754 annotations=[])
 2755        >>> d.decisionsInZone('Z')
 2756        {0, 1}
 2757        >>> d.createZone('Z2', 0)
 2758        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2759 annotations=[])
 2760        >>> d.addDecisionToZone('B', 'Z2')
 2761        >>> d.addDecisionToZone('C', 'Z2')
 2762        >>> d.getZoneInfo('Z2')
 2763        ZoneInfo(level=0, parents=set(), contents={1, 2}, tags={},\
 2764 annotations=[])
 2765        >>> d.decisionsInZone('Z')
 2766        {0, 1}
 2767        >>> d.decisionsInZone('Z2')
 2768        {1, 2}
 2769        >>> d.createZone('l1Z', 1)
 2770        ZoneInfo(level=1, parents=set(), contents=set(), tags={},\
 2771 annotations=[])
 2772        >>> d.addZoneToZone('Z', 'l1Z')
 2773        >>> d.decisionsInZone('Z')
 2774        {0, 1}
 2775        >>> d.decisionsInZone('l1Z')
 2776        set()
 2777        >>> d.decisionsInZone('madeup')
 2778        Traceback (most recent call last):
 2779        ...
 2780        exploration.core.MissingZoneError...
 2781        >>> zDec = d.decisionsInZone('Z')
 2782        >>> zDec.add(2)  # won't affect the zone
 2783        >>> zDec
 2784        {0, 1, 2}
 2785        >>> d.decisionsInZone('Z')
 2786        {0, 1}
 2787        """
 2788        info = self.getZoneInfo(zone)
 2789        if info is None:
 2790            raise MissingZoneError(f"Zone {zone!r} does not exist.")
 2791
 2792        # Everything that's not a zone must be a decision
 2793        return {
 2794            item
 2795            for item in info.contents
 2796            if isinstance(item, base.DecisionID)
 2797        }
 2798
 2799    def subZones(self, zone: base.Zone) -> Set[base.Zone]:
 2800        """
 2801        Returns the set of all immediate sub-zones of the given zone.
 2802        Will be an empty set if there are no sub-zones; raises a
 2803        `MissingZoneError` if the specified zone does not exit.
 2804
 2805        The returned set is a copy, not a live editable set.
 2806
 2807        For example:
 2808
 2809        >>> d = DecisionGraph()
 2810        >>> d.createZone('Z', 0)
 2811        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2812 annotations=[])
 2813        >>> d.subZones('Z')
 2814        set()
 2815        >>> d.createZone('l1Z', 1)
 2816        ZoneInfo(level=1, parents=set(), contents=set(), tags={},\
 2817 annotations=[])
 2818        >>> d.addZoneToZone('Z', 'l1Z')
 2819        >>> d.subZones('Z')
 2820        set()
 2821        >>> d.subZones('l1Z')
 2822        {'Z'}
 2823        >>> s = d.subZones('l1Z')
 2824        >>> s.add('Q')  # doesn't affect the zone
 2825        >>> sorted(s)
 2826        ['Q', 'Z']
 2827        >>> d.subZones('l1Z')
 2828        {'Z'}
 2829        >>> d.subZones('madeup')
 2830        Traceback (most recent call last):
 2831        ...
 2832        exploration.core.MissingZoneError...
 2833        """
 2834        info = self.getZoneInfo(zone)
 2835        if info is None:
 2836            raise MissingZoneError(f"Zone {zone!r} does not exist.")
 2837
 2838        # Sub-zones will appear in self.zones
 2839        return {
 2840            item
 2841            for item in info.contents
 2842            if isinstance(item, base.Zone)
 2843        }
 2844
 2845    def allDecisionsInZone(self, zone: base.Zone) -> Set[base.DecisionID]:
 2846        """
 2847        Returns a set containing all decisions in the given zone,
 2848        including those included via sub-zones.
 2849
 2850        Raises a `MissingZoneError` if the specified zone does not
 2851        exist.`
 2852
 2853        For example:
 2854
 2855        >>> d = DecisionGraph()
 2856        >>> d.addDecision('A')
 2857        0
 2858        >>> d.addDecision('B')
 2859        1
 2860        >>> d.addDecision('C')
 2861        2
 2862        >>> d.createZone('Z', 0)
 2863        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2864 annotations=[])
 2865        >>> d.addDecisionToZone('A', 'Z')
 2866        >>> d.addDecisionToZone('B', 'Z')
 2867        >>> d.getZoneInfo('Z')
 2868        ZoneInfo(level=0, parents=set(), contents={0, 1}, tags={},\
 2869 annotations=[])
 2870        >>> d.decisionsInZone('Z')
 2871        {0, 1}
 2872        >>> d.allDecisionsInZone('Z')
 2873        {0, 1}
 2874        >>> d.createZone('Z2', 0)
 2875        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2876 annotations=[])
 2877        >>> d.addDecisionToZone('B', 'Z2')
 2878        >>> d.addDecisionToZone('C', 'Z2')
 2879        >>> d.getZoneInfo('Z2')
 2880        ZoneInfo(level=0, parents=set(), contents={1, 2}, tags={},\
 2881 annotations=[])
 2882        >>> d.decisionsInZone('Z')
 2883        {0, 1}
 2884        >>> d.decisionsInZone('Z2')
 2885        {1, 2}
 2886        >>> d.allDecisionsInZone('Z2')
 2887        {1, 2}
 2888        >>> d.createZone('l1Z', 1)
 2889        ZoneInfo(level=1, parents=set(), contents=set(), tags={},\
 2890 annotations=[])
 2891        >>> d.createZone('l2Z', 2)
 2892        ZoneInfo(level=2, parents=set(), contents=set(), tags={},\
 2893 annotations=[])
 2894        >>> d.addZoneToZone('Z', 'l1Z')
 2895        >>> d.addZoneToZone('l1Z', 'l2Z')
 2896        >>> d.addZoneToZone('Z2', 'l2Z')
 2897        >>> d.decisionsInZone('Z')
 2898        {0, 1}
 2899        >>> d.decisionsInZone('Z2')
 2900        {1, 2}
 2901        >>> d.decisionsInZone('l1Z')
 2902        set()
 2903        >>> d.allDecisionsInZone('l1Z')
 2904        {0, 1}
 2905        >>> d.allDecisionsInZone('l2Z')
 2906        {0, 1, 2}
 2907        """
 2908        result: Set[base.DecisionID] = set()
 2909        info = self.getZoneInfo(zone)
 2910        if info is None:
 2911            raise MissingZoneError(f"Zone {zone!r} does not exist.")
 2912
 2913        for item in info.contents:
 2914            if isinstance(item, base.Zone):
 2915                # This can't be an error because of the condition above
 2916                result |= self.allDecisionsInZone(item)
 2917            else:  # it's a decision
 2918                result.add(item)
 2919
 2920        return result
 2921
 2922    def zoneHierarchyLevel(self, zone: base.Zone) -> int:
 2923        """
 2924        Returns the hierarchy level of the given zone, as stored in its
 2925        zone info.
 2926
 2927        By convention, level-0 zones contain decisions directly, and
 2928        higher-level zones contain zones of lower levels. This
 2929        convention is not enforced, and there could be exceptions to it.
 2930
 2931        Raises a `MissingZoneError` if the specified zone does not
 2932        exist.
 2933
 2934        For example:
 2935
 2936        >>> d = DecisionGraph()
 2937        >>> d.createZone('Z', 0)
 2938        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2939 annotations=[])
 2940        >>> d.createZone('l1Z', 1)
 2941        ZoneInfo(level=1, parents=set(), contents=set(), tags={},\
 2942 annotations=[])
 2943        >>> d.createZone('l5Z', 5)
 2944        ZoneInfo(level=5, parents=set(), contents=set(), tags={},\
 2945 annotations=[])
 2946        >>> d.zoneHierarchyLevel('Z')
 2947        0
 2948        >>> d.zoneHierarchyLevel('l1Z')
 2949        1
 2950        >>> d.zoneHierarchyLevel('l5Z')
 2951        5
 2952        >>> d.zoneHierarchyLevel('madeup')
 2953        Traceback (most recent call last):
 2954        ...
 2955        exploration.core.MissingZoneError...
 2956        """
 2957        info = self.getZoneInfo(zone)
 2958        if info is None:
 2959            raise MissingZoneError(f"Zone {zone!r} dose not exist.")
 2960
 2961        return info.level
 2962
 2963    def zoneParents(
 2964        self,
 2965        zoneOrDecision: Union[base.Zone, base.DecisionID]
 2966    ) -> Set[base.Zone]:
 2967        """
 2968        Returns the set of all zones which directly contain the target
 2969        zone or decision.
 2970
 2971        Raises a `MissingDecisionError` if the target is neither a valid
 2972        zone nor a valid decision.
 2973
 2974        Returns a copy, not a live editable set.
 2975
 2976        Example:
 2977
 2978        >>> g = DecisionGraph()
 2979        >>> g.addDecision('A')
 2980        0
 2981        >>> g.addDecision('B')
 2982        1
 2983        >>> g.createZone('level0', 0)
 2984        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 2985 annotations=[])
 2986        >>> g.createZone('level1', 1)
 2987        ZoneInfo(level=1, parents=set(), contents=set(), tags={},\
 2988 annotations=[])
 2989        >>> g.createZone('level2', 2)
 2990        ZoneInfo(level=2, parents=set(), contents=set(), tags={},\
 2991 annotations=[])
 2992        >>> g.createZone('level3', 3)
 2993        ZoneInfo(level=3, parents=set(), contents=set(), tags={},\
 2994 annotations=[])
 2995        >>> g.addDecisionToZone('A', 'level0')
 2996        >>> g.addDecisionToZone('B', 'level0')
 2997        >>> g.addZoneToZone('level0', 'level1')
 2998        >>> g.addZoneToZone('level1', 'level2')
 2999        >>> g.addZoneToZone('level2', 'level3')
 3000        >>> g.addDecisionToZone('B', 'level2')  # Direct w/ skips
 3001        >>> sorted(g.zoneParents(0))
 3002        ['level0']
 3003        >>> sorted(g.zoneParents(1))
 3004        ['level0', 'level2']
 3005        """
 3006        if zoneOrDecision in self.zones:
 3007            zoneOrDecision = cast(base.Zone, zoneOrDecision)
 3008            info = cast(base.ZoneInfo, self.getZoneInfo(zoneOrDecision))
 3009            return copy.copy(info.parents)
 3010        elif zoneOrDecision in self:
 3011            return self.nodes[zoneOrDecision].get('zones', set())
 3012        else:
 3013            raise MissingDecisionError(
 3014                f"Name {zoneOrDecision!r} is neither a valid zone nor a"
 3015                f" valid decision."
 3016            )
 3017
 3018    def zoneAncestors(
 3019        self,
 3020        zoneOrDecision: Union[base.Zone, base.DecisionID],
 3021        exclude: Set[base.Zone] = set(),
 3022        atLevel: Optional[int] = None
 3023    ) -> Set[base.Zone]:
 3024        """
 3025        Returns the set of zones which contain the target zone or
 3026        decision, either directly or indirectly. The target is not
 3027        included in the set.
 3028
 3029        Any ones listed in the `exclude` set are also excluded, as are
 3030        any of their ancestors which are not also ancestors of the
 3031        target zone via another path of inclusion.
 3032
 3033        If `atLevel` is not `None`, then only zones at that hierarchy
 3034        level will be included.
 3035
 3036        Raises a `MissingDecisionError` if the target is nether a valid
 3037        zone nor a valid decision.
 3038
 3039        Example:
 3040
 3041        >>> g = DecisionGraph()
 3042        >>> g.addDecision('A')
 3043        0
 3044        >>> g.addDecision('B')
 3045        1
 3046        >>> g.createZone('level0', 0)
 3047        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 3048 annotations=[])
 3049        >>> g.createZone('level1', 1)
 3050        ZoneInfo(level=1, parents=set(), contents=set(), tags={},\
 3051 annotations=[])
 3052        >>> g.createZone('level2', 2)
 3053        ZoneInfo(level=2, parents=set(), contents=set(), tags={},\
 3054 annotations=[])
 3055        >>> g.createZone('level3', 3)
 3056        ZoneInfo(level=3, parents=set(), contents=set(), tags={},\
 3057 annotations=[])
 3058        >>> g.addDecisionToZone('A', 'level0')
 3059        >>> g.addDecisionToZone('B', 'level0')
 3060        >>> g.addZoneToZone('level0', 'level1')
 3061        >>> g.addZoneToZone('level1', 'level2')
 3062        >>> g.addZoneToZone('level2', 'level3')
 3063        >>> g.addDecisionToZone('B', 'level2')  # Direct w/ skips
 3064        >>> sorted(g.zoneAncestors(0))
 3065        ['level0', 'level1', 'level2', 'level3']
 3066        >>> sorted(g.zoneAncestors(1))
 3067        ['level0', 'level1', 'level2', 'level3']
 3068        >>> sorted(g.zoneParents(0))
 3069        ['level0']
 3070        >>> sorted(g.zoneParents(1))
 3071        ['level0', 'level2']
 3072        >>> sorted(g.zoneAncestors(0, atLevel=2))
 3073        ['level2']
 3074        >>> sorted(g.zoneAncestors(0, exclude={'level2'}))
 3075        ['level0', 'level1']
 3076        """
 3077        # Copy is important here!
 3078        result = set(self.zoneParents(zoneOrDecision))
 3079        result -= exclude
 3080        for parent in copy.copy(result):
 3081            # Recursively dig up ancestors, but exclude
 3082            # results-so-far to avoid re-enumerating when there are
 3083            # multiple braided inclusion paths.
 3084            result |= self.zoneAncestors(parent, result | exclude, atLevel)
 3085
 3086        if atLevel is not None:
 3087            return {
 3088                z for z in result if self.zoneHierarchyLevel(z) == atLevel
 3089            }
 3090        else:
 3091            return result
 3092
 3093    def region(
 3094        self,
 3095        decision: base.DecisionID,
 3096        useLevel: int=1
 3097    ) -> Optional[base.Zone]:
 3098        """
 3099        Returns the 'region' that this decision belongs to. 'Regions'
 3100        are level-1 zones, but when a decision is in multiple level-1
 3101        zones, its region counts as the smallest of those zones in terms
 3102        of total decisions contained, breaking ties by the one with the
 3103        alphabetically earlier name.
 3104
 3105        Always returns a single zone name string, unless the target
 3106        decision is not in any level-1 zones, in which case it returns
 3107        `None`.
 3108
 3109        If `useLevel` is specified, then zones of the specified level
 3110        will be used instead of level-1 zones.
 3111
 3112        Example:
 3113
 3114        >>> g = DecisionGraph()
 3115        >>> g.addDecision('A')
 3116        0
 3117        >>> g.addDecision('B')
 3118        1
 3119        >>> g.addDecision('C')
 3120        2
 3121        >>> g.addDecision('D')
 3122        3
 3123        >>> g.createZone('zoneX', 0)
 3124        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 3125 annotations=[])
 3126        >>> g.createZone('regionA', 1)
 3127        ZoneInfo(level=1, parents=set(), contents=set(), tags={},\
 3128 annotations=[])
 3129        >>> g.createZone('zoneY', 0)
 3130        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 3131 annotations=[])
 3132        >>> g.createZone('regionB', 1)
 3133        ZoneInfo(level=1, parents=set(), contents=set(), tags={},\
 3134 annotations=[])
 3135        >>> g.createZone('regionC', 1)
 3136        ZoneInfo(level=1, parents=set(), contents=set(), tags={},\
 3137 annotations=[])
 3138        >>> g.createZone('quadrant', 2)
 3139        ZoneInfo(level=2, parents=set(), contents=set(), tags={},\
 3140 annotations=[])
 3141        >>> g.addDecisionToZone('A', 'zoneX')
 3142        >>> g.addDecisionToZone('B', 'zoneY')
 3143        >>> # C is not in any level-1 zones
 3144        >>> g.addDecisionToZone('D', 'zoneX')
 3145        >>> g.addDecisionToZone('D', 'zoneY')  # D is in both
 3146        >>> g.addZoneToZone('zoneX', 'regionA')
 3147        >>> g.addZoneToZone('zoneY', 'regionB')
 3148        >>> g.addZoneToZone('zoneX', 'regionC')  # includes both
 3149        >>> g.addZoneToZone('zoneY', 'regionC')
 3150        >>> g.addZoneToZone('regionA', 'quadrant')
 3151        >>> g.addZoneToZone('regionB', 'quadrant')
 3152        >>> g.addDecisionToZone('C', 'regionC')  # Direct in level-2
 3153        >>> sorted(g.allDecisionsInZone('zoneX'))
 3154        [0, 3]
 3155        >>> sorted(g.allDecisionsInZone('zoneY'))
 3156        [1, 3]
 3157        >>> sorted(g.allDecisionsInZone('regionA'))
 3158        [0, 3]
 3159        >>> sorted(g.allDecisionsInZone('regionB'))
 3160        [1, 3]
 3161        >>> sorted(g.allDecisionsInZone('regionC'))
 3162        [0, 1, 2, 3]
 3163        >>> sorted(g.allDecisionsInZone('quadrant'))
 3164        [0, 1, 3]
 3165        >>> g.region(0)  # for A; region A is smaller than region C
 3166        'regionA'
 3167        >>> g.region(1)  # for B; region B is also smaller than C
 3168        'regionB'
 3169        >>> g.region(2)  # for C
 3170        'regionC'
 3171        >>> g.region(3)  # for D; tie broken alphabetically
 3172        'regionA'
 3173        >>> g.region(0, useLevel=0)  # for A at level 0
 3174        'zoneX'
 3175        >>> g.region(1, useLevel=0)  # for B at level 0
 3176        'zoneY'
 3177        >>> g.region(2, useLevel=0) is None  # for C at level 0 (none)
 3178        True
 3179        >>> g.region(3, useLevel=0)  # for D at level 0; tie
 3180        'zoneX'
 3181        >>> g.region(0, useLevel=2) # for A at level 2
 3182        'quadrant'
 3183        >>> g.region(1, useLevel=2) # for B at level 2
 3184        'quadrant'
 3185        >>> g.region(2, useLevel=2) is None # for C at level 2 (none)
 3186        True
 3187        >>> g.region(3, useLevel=2)  # for D at level 2
 3188        'quadrant'
 3189        """
 3190        relevant = self.zoneAncestors(decision, atLevel=useLevel)
 3191        if len(relevant) == 0:
 3192            return None
 3193        elif len(relevant) == 1:
 3194            for zone in relevant:
 3195                return zone
 3196            return None  # not really necessary but keeps mypy happy
 3197        else:
 3198            # more than one zone ancestor at the relevant hierarchy
 3199            # level: need to measure their sizes
 3200            minSize = None
 3201            candidates = []
 3202            for zone in relevant:
 3203                size = len(self.allDecisionsInZone(zone))
 3204                if minSize is None or size < minSize:
 3205                    candidates = [zone]
 3206                    minSize = size
 3207                elif size == minSize:
 3208                    candidates.append(zone)
 3209            return min(candidates)
 3210
 3211    def zoneEdges(self, zone: base.Zone) -> Optional[
 3212        Tuple[
 3213            Set[Tuple[base.DecisionID, base.Transition]],
 3214            Set[Tuple[base.DecisionID, base.Transition]]
 3215        ]
 3216    ]:
 3217        """
 3218        Given a zone to look at, finds all of the transitions which go
 3219        out of and into that zone, ignoring internal transitions between
 3220        decisions in the zone. This includes all decisions in sub-zones.
 3221        The return value is a pair of sets for outgoing and then
 3222        incoming transitions, where each transition is specified as a
 3223        (sourceID, transitionName) pair.
 3224
 3225        Returns `None` if the target zone isn't yet fully defined.
 3226
 3227        Note that this takes time proportional to *all* edges plus *all*
 3228        nodes in the graph no matter how large or small the zone in
 3229        question is.
 3230
 3231        >>> g = DecisionGraph()
 3232        >>> g.addDecision('A')
 3233        0
 3234        >>> g.addDecision('B')
 3235        1
 3236        >>> g.addDecision('C')
 3237        2
 3238        >>> g.addDecision('D')
 3239        3
 3240        >>> g.addTransition('A', 'up', 'B', 'down')
 3241        >>> g.addTransition('B', 'right', 'C', 'left')
 3242        >>> g.addTransition('C', 'down', 'D', 'up')
 3243        >>> g.addTransition('D', 'left', 'A', 'right')
 3244        >>> g.addTransition('A', 'tunnel', 'C', 'tunnel')
 3245        >>> g.createZone('Z', 0)
 3246        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 3247 annotations=[])
 3248        >>> g.createZone('ZZ', 1)
 3249        ZoneInfo(level=1, parents=set(), contents=set(), tags={},\
 3250 annotations=[])
 3251        >>> g.addZoneToZone('Z', 'ZZ')
 3252        >>> g.addDecisionToZone('A', 'Z')
 3253        >>> g.addDecisionToZone('B', 'Z')
 3254        >>> g.addDecisionToZone('D', 'ZZ')
 3255        >>> outgoing, incoming = g.zoneEdges('Z')  # TODO: Sort for testing
 3256        >>> sorted(outgoing)
 3257        [(0, 'right'), (0, 'tunnel'), (1, 'right')]
 3258        >>> sorted(incoming)
 3259        [(2, 'left'), (2, 'tunnel'), (3, 'left')]
 3260        >>> outgoing, incoming = g.zoneEdges('ZZ')
 3261        >>> sorted(outgoing)
 3262        [(0, 'tunnel'), (1, 'right'), (3, 'up')]
 3263        >>> sorted(incoming)
 3264        [(2, 'down'), (2, 'left'), (2, 'tunnel')]
 3265        >>> g.zoneEdges('madeup') is None
 3266        True
 3267        """
 3268        # Find the interior nodes
 3269        try:
 3270            interior = self.allDecisionsInZone(zone)
 3271        except MissingZoneError:
 3272            return None
 3273
 3274        # Set up our result
 3275        results: Tuple[
 3276            Set[Tuple[base.DecisionID, base.Transition]],
 3277            Set[Tuple[base.DecisionID, base.Transition]]
 3278        ] = (set(), set())
 3279
 3280        # Because finding incoming edges requires searching the entire
 3281        # graph anyways, it's more efficient to just consider each edge
 3282        # once.
 3283        for fromDecision in self:
 3284            fromThere = self[fromDecision]
 3285            for toDecision in fromThere:
 3286                for transition in fromThere[toDecision]:
 3287                    sourceIn = fromDecision in interior
 3288                    destIn = toDecision in interior
 3289                    if sourceIn and not destIn:
 3290                        results[0].add((fromDecision, transition))
 3291                    elif destIn and not sourceIn:
 3292                        results[1].add((fromDecision, transition))
 3293
 3294        return results
 3295
 3296    def replaceZonesInHierarchy(
 3297        self,
 3298        target: base.AnyDecisionSpecifier,
 3299        zone: base.Zone,
 3300        level: int
 3301    ) -> None:
 3302        """
 3303        This method replaces one or more zones which contain the
 3304        specified `target` decision with a specific zone, at a specific
 3305        level in the zone hierarchy (see `zoneHierarchyLevel`). If the
 3306        named zone doesn't yet exist, it will be created.
 3307
 3308        To do this, it looks at all zones which contain the target
 3309        decision directly or indirectly (see `zoneAncestors`) and which
 3310        are at the specified level.
 3311
 3312        - Any direct children of those zones which are ancestors of the
 3313            target decision are removed from those zones and placed into
 3314            the new zone instead, regardless of their levels. Indirect
 3315            children are not affected (except perhaps indirectly via
 3316            their parents' ancestors changing).
 3317        - The new zone is placed into every direct parent of those
 3318            zones, regardless of their levels (those parents are by
 3319            definition all ancestors of the target decision).
 3320        - If there were no zones at the target level, every zone at the
 3321            next level down which is an ancestor of the target decision
 3322            (or just that decision if the level is 0) is placed into the
 3323            new zone as a direct child (and is removed from any previous
 3324            parents it had). In this case, the new zone will also be
 3325            added as a sub-zone to every ancestor of the target decision
 3326            at the level above the specified level, if there are any.
 3327            * In this case, if there are no zones at the level below the
 3328                specified level, the highest level of zones smaller than
 3329                that is treated as the level below, down to targeting
 3330                the decision itself.
 3331            * Similarly, if there are no zones at the level above the
 3332                specified level but there are zones at a higher level,
 3333                the new zone will be added to each of the zones in the
 3334                lowest level above the target level that has zones in it.
 3335
 3336        A `MissingDecisionError` will be raised if the specified
 3337        decision is not valid, or if the decision is left as default but
 3338        there is no current decision in the exploration.
 3339
 3340        An `InvalidLevelError` will be raised if the level is less than
 3341        zero.
 3342
 3343        Example:
 3344
 3345        >>> g = DecisionGraph()
 3346        >>> g.addDecision('decision')
 3347        0
 3348        >>> g.addDecision('alternate')
 3349        1
 3350        >>> g.createZone('zone0', 0)
 3351        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 3352 annotations=[])
 3353        >>> g.createZone('zone1', 1)
 3354        ZoneInfo(level=1, parents=set(), contents=set(), tags={},\
 3355 annotations=[])
 3356        >>> g.createZone('zone2.1', 2)
 3357        ZoneInfo(level=2, parents=set(), contents=set(), tags={},\
 3358 annotations=[])
 3359        >>> g.createZone('zone2.2', 2)
 3360        ZoneInfo(level=2, parents=set(), contents=set(), tags={},\
 3361 annotations=[])
 3362        >>> g.createZone('zone3', 3)
 3363        ZoneInfo(level=3, parents=set(), contents=set(), tags={},\
 3364 annotations=[])
 3365        >>> g.addDecisionToZone('decision', 'zone0')
 3366        >>> g.addDecisionToZone('alternate', 'zone0')
 3367        >>> g.addZoneToZone('zone0', 'zone1')
 3368        >>> g.addZoneToZone('zone1', 'zone2.1')
 3369        >>> g.addZoneToZone('zone1', 'zone2.2')
 3370        >>> g.addZoneToZone('zone2.1', 'zone3')
 3371        >>> g.addZoneToZone('zone2.2', 'zone3')
 3372        >>> g.zoneHierarchyLevel('zone0')
 3373        0
 3374        >>> g.zoneHierarchyLevel('zone1')
 3375        1
 3376        >>> g.zoneHierarchyLevel('zone2.1')
 3377        2
 3378        >>> g.zoneHierarchyLevel('zone2.2')
 3379        2
 3380        >>> g.zoneHierarchyLevel('zone3')
 3381        3
 3382        >>> sorted(g.decisionsInZone('zone0'))
 3383        [0, 1]
 3384        >>> sorted(g.zoneAncestors('zone0'))
 3385        ['zone1', 'zone2.1', 'zone2.2', 'zone3']
 3386        >>> g.subZones('zone1')
 3387        {'zone0'}
 3388        >>> g.zoneParents('zone0')
 3389        {'zone1'}
 3390        >>> g.replaceZonesInHierarchy('decision', 'new0', 0)
 3391        >>> g.zoneParents('zone0')
 3392        {'zone1'}
 3393        >>> g.zoneParents('new0')
 3394        {'zone1'}
 3395        >>> sorted(g.zoneAncestors('zone0'))
 3396        ['zone1', 'zone2.1', 'zone2.2', 'zone3']
 3397        >>> sorted(g.zoneAncestors('new0'))
 3398        ['zone1', 'zone2.1', 'zone2.2', 'zone3']
 3399        >>> g.decisionsInZone('zone0')
 3400        {1}
 3401        >>> g.decisionsInZone('new0')
 3402        {0}
 3403        >>> sorted(g.subZones('zone1'))
 3404        ['new0', 'zone0']
 3405        >>> g.zoneParents('new0')
 3406        {'zone1'}
 3407        >>> g.replaceZonesInHierarchy('decision', 'new1', 1)
 3408        >>> sorted(g.zoneAncestors(0))
 3409        ['new0', 'new1', 'zone2.1', 'zone2.2', 'zone3']
 3410        >>> g.subZones('zone1')
 3411        {'zone0'}
 3412        >>> g.subZones('new1')
 3413        {'new0'}
 3414        >>> g.zoneParents('new0')
 3415        {'new1'}
 3416        >>> sorted(g.zoneParents('zone1'))
 3417        ['zone2.1', 'zone2.2']
 3418        >>> sorted(g.zoneParents('new1'))
 3419        ['zone2.1', 'zone2.2']
 3420        >>> g.zoneParents('zone2.1')
 3421        {'zone3'}
 3422        >>> g.zoneParents('zone2.2')
 3423        {'zone3'}
 3424        >>> sorted(g.subZones('zone2.1'))
 3425        ['new1', 'zone1']
 3426        >>> sorted(g.subZones('zone2.2'))
 3427        ['new1', 'zone1']
 3428        >>> sorted(g.allDecisionsInZone('zone2.1'))
 3429        [0, 1]
 3430        >>> sorted(g.allDecisionsInZone('zone2.2'))
 3431        [0, 1]
 3432        >>> g.replaceZonesInHierarchy('decision', 'new2', 2)
 3433        >>> g.zoneParents('zone2.1')
 3434        {'zone3'}
 3435        >>> g.zoneParents('zone2.2')
 3436        {'zone3'}
 3437        >>> g.subZones('zone2.1')
 3438        {'zone1'}
 3439        >>> g.subZones('zone2.2')
 3440        {'zone1'}
 3441        >>> g.subZones('new2')
 3442        {'new1'}
 3443        >>> g.zoneParents('new2')
 3444        {'zone3'}
 3445        >>> g.allDecisionsInZone('zone2.1')
 3446        {1}
 3447        >>> g.allDecisionsInZone('zone2.2')
 3448        {1}
 3449        >>> g.allDecisionsInZone('new2')
 3450        {0}
 3451        >>> sorted(g.subZones('zone3'))
 3452        ['new2', 'zone2.1', 'zone2.2']
 3453        >>> g.zoneParents('zone3')
 3454        set()
 3455        >>> sorted(g.allDecisionsInZone('zone3'))
 3456        [0, 1]
 3457        >>> g.replaceZonesInHierarchy('decision', 'new3', 3)
 3458        >>> sorted(g.subZones('zone3'))
 3459        ['zone2.1', 'zone2.2']
 3460        >>> g.subZones('new3')
 3461        {'new2'}
 3462        >>> g.zoneParents('zone3')
 3463        set()
 3464        >>> g.zoneParents('new3')
 3465        set()
 3466        >>> g.allDecisionsInZone('zone3')
 3467        {1}
 3468        >>> g.allDecisionsInZone('new3')
 3469        {0}
 3470        >>> g.replaceZonesInHierarchy('decision', 'new4', 5)
 3471        >>> g.subZones('new4')
 3472        {'new3'}
 3473        >>> g.zoneHierarchyLevel('new4')
 3474        5
 3475
 3476        Another example of level collapse when trying to replace a zone
 3477        at a level above :
 3478
 3479        >>> g = DecisionGraph()
 3480        >>> g.addDecision('A')
 3481        0
 3482        >>> g.addDecision('B')
 3483        1
 3484        >>> g.createZone('level0', 0)
 3485        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 3486 annotations=[])
 3487        >>> g.createZone('level1', 1)
 3488        ZoneInfo(level=1, parents=set(), contents=set(), tags={},\
 3489 annotations=[])
 3490        >>> g.createZone('level2', 2)
 3491        ZoneInfo(level=2, parents=set(), contents=set(), tags={},\
 3492 annotations=[])
 3493        >>> g.createZone('level3', 3)
 3494        ZoneInfo(level=3, parents=set(), contents=set(), tags={},\
 3495 annotations=[])
 3496        >>> g.addDecisionToZone('B', 'level0')
 3497        >>> g.addZoneToZone('level0', 'level1')
 3498        >>> g.addZoneToZone('level1', 'level2')
 3499        >>> g.addZoneToZone('level2', 'level3')
 3500        >>> g.addDecisionToZone('A', 'level3') # missing some zone levels
 3501        >>> g.zoneHierarchyLevel('level3')
 3502        3
 3503        >>> g.replaceZonesInHierarchy('A', 'newFirst', 1)
 3504        >>> g.zoneHierarchyLevel('newFirst')
 3505        1
 3506        >>> g.decisionsInZone('newFirst')
 3507        {0}
 3508        >>> g.decisionsInZone('level3')
 3509        set()
 3510        >>> sorted(g.allDecisionsInZone('level3'))
 3511        [0, 1]
 3512        >>> g.subZones('newFirst')
 3513        set()
 3514        >>> sorted(g.subZones('level3'))
 3515        ['level2', 'newFirst']
 3516        >>> g.zoneParents('newFirst')
 3517        {'level3'}
 3518        >>> g.replaceZonesInHierarchy('A', 'newSecond', 2)
 3519        >>> g.zoneHierarchyLevel('newSecond')
 3520        2
 3521        >>> g.decisionsInZone('newSecond')
 3522        set()
 3523        >>> g.allDecisionsInZone('newSecond')
 3524        {0}
 3525        >>> g.subZones('newSecond')
 3526        {'newFirst'}
 3527        >>> g.zoneParents('newSecond')
 3528        {'level3'}
 3529        >>> g.zoneParents('newFirst')
 3530        {'newSecond'}
 3531        >>> sorted(g.subZones('level3'))
 3532        ['level2', 'newSecond']
 3533        """
 3534        tID = self.resolveDecision(target)
 3535
 3536        if level < 0:
 3537            raise InvalidLevelError(
 3538                f"Target level must be positive (got {level})."
 3539            )
 3540
 3541        info = self.getZoneInfo(zone)
 3542        if info is None:
 3543            info = self.createZone(zone, level)
 3544        elif level != info.level:
 3545            raise InvalidLevelError(
 3546                f"Target level ({level}) does not match the level of"
 3547                f" the target zone ({zone!r} at level {info.level})."
 3548            )
 3549
 3550        # Collect both parents & ancestors
 3551        parents = self.zoneParents(tID)
 3552        ancestors = set(self.zoneAncestors(tID))
 3553
 3554        # Map from levels to sets of zones from the ancestors pool
 3555        levelMap: Dict[int, Set[base.Zone]] = {}
 3556        highest = -1
 3557        for ancestor in ancestors:
 3558            ancestorLevel = self.zoneHierarchyLevel(ancestor)
 3559            levelMap.setdefault(ancestorLevel, set()).add(ancestor)
 3560            if ancestorLevel > highest:
 3561                highest = ancestorLevel
 3562
 3563        # Figure out if we have target zones to replace or not
 3564        reparentDecision = False
 3565        if level in levelMap:
 3566            # If there are zones at the target level,
 3567            targetZones = levelMap[level]
 3568
 3569            above = set()
 3570            below = set()
 3571
 3572            for replaced in targetZones:
 3573                above |= self.zoneParents(replaced)
 3574                below |= self.subZones(replaced)
 3575                if replaced in parents:
 3576                    reparentDecision = True
 3577
 3578            # Only ancestors should be reparented
 3579            below &= ancestors
 3580
 3581        else:
 3582            # Find levels w/ zones in them above + below
 3583            levelBelow = level - 1
 3584            levelAbove = level + 1
 3585            below = levelMap.get(levelBelow, set())
 3586            above = levelMap.get(levelAbove, set())
 3587
 3588            while len(below) == 0 and levelBelow > 0:
 3589                levelBelow -= 1
 3590                below = levelMap.get(levelBelow, set())
 3591
 3592            if len(below) == 0:
 3593                reparentDecision = True
 3594
 3595            while len(above) == 0 and levelAbove < highest:
 3596                levelAbove += 1
 3597                above = levelMap.get(levelAbove, set())
 3598
 3599        # Handle re-parenting zones below
 3600        for under in below:
 3601            for parent in self.zoneParents(under):
 3602                if parent in ancestors:
 3603                    self.removeZoneFromZone(under, parent)
 3604            self.addZoneToZone(under, zone)
 3605
 3606        # Add this zone to each parent
 3607        for parent in above:
 3608            self.addZoneToZone(zone, parent)
 3609
 3610        # Re-parent the decision itself if necessary
 3611        if reparentDecision:
 3612            # (using set() here to avoid size-change-during-iteration)
 3613            for parent in set(parents):
 3614                self.removeDecisionFromZone(tID, parent)
 3615            self.addDecisionToZone(tID, zone)
 3616
 3617    def getReciprocal(
 3618        self,
 3619        decision: base.AnyDecisionSpecifier,
 3620        transition: base.Transition
 3621    ) -> Optional[base.Transition]:
 3622        """
 3623        Returns the reciprocal edge for the specified transition from the
 3624        specified decision (see `setReciprocal`). Returns
 3625        `None` if no reciprocal has been established for that
 3626        transition, or if that decision or transition does not exist.
 3627        """
 3628        dID = self.resolveDecision(decision)
 3629
 3630        dest = self.getDestination(dID, transition)
 3631        if dest is not None:
 3632            info = cast(
 3633                TransitionProperties,
 3634                self.edges[dID, dest, transition]  # type:ignore
 3635            )
 3636            recip = info.get("reciprocal")
 3637            if recip is not None and not isinstance(recip, base.Transition):
 3638                raise ValueError(f"Invalid reciprocal value: {repr(recip)}")
 3639            return recip
 3640        else:
 3641            return None
 3642
 3643    def setReciprocal(
 3644        self,
 3645        decision: base.AnyDecisionSpecifier,
 3646        transition: base.Transition,
 3647        reciprocal: Optional[base.Transition],
 3648        setBoth: bool = True,
 3649        cleanup: bool = True
 3650    ) -> None:
 3651        """
 3652        Sets the 'reciprocal' transition for a particular transition from
 3653        a particular decision, and removes the reciprocal property from
 3654        any old reciprocal transition.
 3655
 3656        Raises a `MissingDecisionError` or a `MissingTransitionError` if
 3657        the specified decision or transition does not exist.
 3658
 3659        Raises an `InvalidDestinationError` if the reciprocal transition
 3660        does not exist, or if it does exist but does not lead back to
 3661        the decision the transition came from.
 3662
 3663        If `setBoth` is True (the default) then the transition which is
 3664        being identified as a reciprocal will also have its reciprocal
 3665        property set, pointing back to the primary transition being
 3666        modified, and any old reciprocal of that transition will have its
 3667        reciprocal set to None. If you want to create a situation with
 3668        non-exclusive reciprocals, use `setBoth=False`.
 3669
 3670        If `cleanup` is True (the default) then abandoned reciprocal
 3671        transitions (for both edges if `setBoth` was true) have their
 3672        reciprocal properties removed. Set `cleanup` to false if you want
 3673        to retain them, although this will result in non-exclusive
 3674        reciprocal relationships.
 3675
 3676        If the `reciprocal` value is None, this deletes the reciprocal
 3677        value entirely, and if `setBoth` is true, it does this for the
 3678        previous reciprocal edge as well. No error is raised in this case
 3679        when there was not already a reciprocal to delete.
 3680
 3681        Note that one should remove a reciprocal relationship before
 3682        redirecting either edge of the pair in a way that gives it a new
 3683        reciprocal, since otherwise, a later attempt to remove the
 3684        reciprocal with `setBoth` set to True (the default) will end up
 3685        deleting the reciprocal information from the other edge that was
 3686        already modified. There is no way to reliably detect and avoid
 3687        this, because two different decisions could (and often do in
 3688        practice) have transitions with identical names, meaning that the
 3689        reciprocal value will still be the same, but it will indicate a
 3690        different edge in virtue of the destination of the edge changing.
 3691
 3692        ## Example
 3693
 3694        >>> g = DecisionGraph()
 3695        >>> g.addDecision('G')
 3696        0
 3697        >>> g.addDecision('H')
 3698        1
 3699        >>> g.addDecision('I')
 3700        2
 3701        >>> g.addTransition('G', 'up', 'H', 'down')
 3702        >>> g.addTransition('G', 'next', 'H', 'prev')
 3703        >>> g.addTransition('H', 'next', 'I', 'prev')
 3704        >>> g.addTransition('H', 'return', 'G')
 3705        >>> g.setReciprocal('G', 'up', 'next') # Error w/ destinations
 3706        Traceback (most recent call last):
 3707        ...
 3708        exploration.core.InvalidDestinationError...
 3709        >>> g.setReciprocal('G', 'up', 'none') # Doesn't exist
 3710        Traceback (most recent call last):
 3711        ...
 3712        exploration.core.MissingTransitionError...
 3713        >>> g.getReciprocal('G', 'up')
 3714        'down'
 3715        >>> g.getReciprocal('H', 'down')
 3716        'up'
 3717        >>> g.getReciprocal('H', 'return') is None
 3718        True
 3719        >>> g.setReciprocal('G', 'up', 'return')
 3720        >>> g.getReciprocal('G', 'up')
 3721        'return'
 3722        >>> g.getReciprocal('H', 'down') is None
 3723        True
 3724        >>> g.getReciprocal('H', 'return')
 3725        'up'
 3726        >>> g.setReciprocal('H', 'return', None) # remove the reciprocal
 3727        >>> g.getReciprocal('G', 'up') is None
 3728        True
 3729        >>> g.getReciprocal('H', 'down') is None
 3730        True
 3731        >>> g.getReciprocal('H', 'return') is None
 3732        True
 3733        >>> g.setReciprocal('G', 'up', 'down', setBoth=False) # one-way
 3734        >>> g.getReciprocal('G', 'up')
 3735        'down'
 3736        >>> g.getReciprocal('H', 'down') is None
 3737        True
 3738        >>> g.getReciprocal('H', 'return') is None
 3739        True
 3740        >>> g.setReciprocal('H', 'return', 'up', setBoth=False) # non-sym
 3741        >>> g.getReciprocal('G', 'up')
 3742        'down'
 3743        >>> g.getReciprocal('H', 'down') is None
 3744        True
 3745        >>> g.getReciprocal('H', 'return')
 3746        'up'
 3747        >>> g.setReciprocal('H', 'down', 'up') # setBoth not needed
 3748        >>> g.getReciprocal('G', 'up')
 3749        'down'
 3750        >>> g.getReciprocal('H', 'down')
 3751        'up'
 3752        >>> g.getReciprocal('H', 'return') # unchanged
 3753        'up'
 3754        >>> g.setReciprocal('G', 'up', 'return', cleanup=False) # no cleanup
 3755        >>> g.getReciprocal('G', 'up')
 3756        'return'
 3757        >>> g.getReciprocal('H', 'down')
 3758        'up'
 3759        >>> g.getReciprocal('H', 'return') # unchanged
 3760        'up'
 3761        >>> # Cleanup only applies to reciprocal if setBoth is true
 3762        >>> g.setReciprocal('H', 'down', 'up', setBoth=False)
 3763        >>> g.getReciprocal('G', 'up')
 3764        'return'
 3765        >>> g.getReciprocal('H', 'down')
 3766        'up'
 3767        >>> g.getReciprocal('H', 'return') # not cleaned up w/out setBoth
 3768        'up'
 3769        >>> g.setReciprocal('H', 'down', 'up') # with cleanup and setBoth
 3770        >>> g.getReciprocal('G', 'up')
 3771        'down'
 3772        >>> g.getReciprocal('H', 'down')
 3773        'up'
 3774        >>> g.getReciprocal('H', 'return') is None # cleaned up
 3775        True
 3776        """
 3777        dID = self.resolveDecision(decision)
 3778
 3779        dest = self.destination(dID, transition) # possible KeyError
 3780        if reciprocal is None:
 3781            rDest = None
 3782        else:
 3783            rDest = self.getDestination(dest, reciprocal)
 3784
 3785        # Set or delete reciprocal property
 3786        if reciprocal is None:
 3787            # Delete the property
 3788            info = self.edges[dID, dest, transition]  # type:ignore
 3789
 3790            old = info.pop('reciprocal')
 3791            if setBoth:
 3792                rDest = self.getDestination(dest, old)
 3793                if rDest != dID:
 3794                    raise RuntimeError(
 3795                        f"Invalid reciprocal {old!r} for transition"
 3796                        f" {transition!r} from {self.identityOf(dID)}:"
 3797                        f" destination is {rDest}."
 3798                    )
 3799                rInfo = self.edges[dest, dID, old]  # type:ignore
 3800                if 'reciprocal' in rInfo:
 3801                    del rInfo['reciprocal']
 3802        else:
 3803            # Set the property, checking for errors first
 3804            if rDest is None:
 3805                raise MissingTransitionError(
 3806                    f"Reciprocal transition {reciprocal!r} for"
 3807                    f" transition {transition!r} from decision"
 3808                    f" {self.identityOf(dID)} does not exist at"
 3809                    f" decision {self.identityOf(dest)}"
 3810                )
 3811
 3812            if rDest != dID:
 3813                raise InvalidDestinationError(
 3814                    f"Reciprocal transition {reciprocal!r} from"
 3815                    f" decision {self.identityOf(dest)} does not lead"
 3816                    f" back to decision {self.identityOf(dID)}."
 3817                )
 3818
 3819            eProps = self.edges[dID, dest, transition]  # type:ignore [index]
 3820            abandoned = eProps.get('reciprocal')
 3821            eProps['reciprocal'] = reciprocal
 3822            if cleanup and abandoned not in (None, reciprocal):
 3823                aProps = self.edges[dest, dID, abandoned]  # type:ignore
 3824                if 'reciprocal' in aProps:
 3825                    del aProps['reciprocal']
 3826
 3827            if setBoth:
 3828                rProps = self.edges[dest, dID, reciprocal]  # type:ignore
 3829                revAbandoned = rProps.get('reciprocal')
 3830                rProps['reciprocal'] = transition
 3831                # Sever old reciprocal relationship
 3832                if cleanup and revAbandoned not in (None, transition):
 3833                    raProps = self.edges[
 3834                        dID,  # type:ignore
 3835                        dest,
 3836                        revAbandoned
 3837                    ]
 3838                    del raProps['reciprocal']
 3839
 3840    def getReciprocalPair(
 3841        self,
 3842        decision: base.AnyDecisionSpecifier,
 3843        transition: base.Transition
 3844    ) -> Optional[Tuple[base.DecisionID, base.Transition]]:
 3845        """
 3846        Returns a tuple containing both the destination decision ID and
 3847        the transition at that decision which is the reciprocal of the
 3848        specified destination & transition. Returns `None` if no
 3849        reciprocal has been established for that transition, or if that
 3850        decision or transition does not exist.
 3851
 3852        >>> g = DecisionGraph()
 3853        >>> g.addDecision('A')
 3854        0
 3855        >>> g.addDecision('B')
 3856        1
 3857        >>> g.addDecision('C')
 3858        2
 3859        >>> g.addTransition('A', 'up', 'B', 'down')
 3860        >>> g.addTransition('B', 'right', 'C', 'left')
 3861        >>> g.addTransition('A', 'oneway', 'C')
 3862        >>> g.getReciprocalPair('A', 'up')
 3863        (1, 'down')
 3864        >>> g.getReciprocalPair('B', 'down')
 3865        (0, 'up')
 3866        >>> g.getReciprocalPair('B', 'right')
 3867        (2, 'left')
 3868        >>> g.getReciprocalPair('C', 'left')
 3869        (1, 'right')
 3870        >>> g.getReciprocalPair('C', 'up') is None
 3871        True
 3872        >>> g.getReciprocalPair('Q', 'up') is None
 3873        True
 3874        >>> g.getReciprocalPair('A', 'tunnel') is None
 3875        True
 3876        """
 3877        try:
 3878            dID = self.resolveDecision(decision)
 3879        except MissingDecisionError:
 3880            return None
 3881
 3882        reciprocal = self.getReciprocal(dID, transition)
 3883        if reciprocal is None:
 3884            return None
 3885        else:
 3886            destination = self.getDestination(dID, transition)
 3887            if destination is None:
 3888                return None
 3889            else:
 3890                return (destination, reciprocal)
 3891
 3892    def addDecision(
 3893        self,
 3894        name: base.DecisionName,
 3895        domain: Optional[base.Domain] = None,
 3896        tags: Optional[Dict[base.Tag, base.TagValue]] = None,
 3897        annotations: Optional[List[base.Annotation]] = None
 3898    ) -> base.DecisionID:
 3899        """
 3900        Adds a decision to the graph, without any transitions yet. Each
 3901        decision will be assigned an ID so name collisions are allowed,
 3902        but it's usually best to keep names unique at least within each
 3903        zone. If no domain is provided, the `DEFAULT_DOMAIN` will be
 3904        used for the decision's domain. A dictionary of tags and/or a
 3905        list of annotations (strings in both cases) may be provided.
 3906
 3907        Returns the newly-assigned `DecisionID` for the decision it
 3908        created.
 3909
 3910        Emits a `DecisionCollisionWarning` if a decision with the
 3911        provided name already exists and the `WARN_OF_NAME_COLLISIONS`
 3912        global variable is set to `True`.
 3913        """
 3914        # Defaults
 3915        if domain is None:
 3916            domain = base.DEFAULT_DOMAIN
 3917        if tags is None:
 3918            tags = {}
 3919        if annotations is None:
 3920            annotations = []
 3921
 3922        # Error checking
 3923        if name in self.nameLookup and WARN_OF_NAME_COLLISIONS:
 3924            warnings.warn(
 3925                (
 3926                    f"Adding decision {name!r}: Another decision with"
 3927                    f" that name already exists."
 3928                ),
 3929                DecisionCollisionWarning
 3930            )
 3931
 3932        dID = self._assignID()
 3933
 3934        # Add the decision
 3935        self.add_node(
 3936            dID,
 3937            name=name,
 3938            domain=domain,
 3939            tags=tags,
 3940            annotations=annotations
 3941        )
 3942        #TODO: Elide tags/annotations if they're empty?
 3943
 3944        # Track it in our `nameLookup` dictionary
 3945        self.nameLookup.setdefault(name, []).append(dID)
 3946
 3947        return dID
 3948
 3949    def addIdentifiedDecision(
 3950        self,
 3951        dID: base.DecisionID,
 3952        name: base.DecisionName,
 3953        domain: Optional[base.Domain] = None,
 3954        tags: Optional[Dict[base.Tag, base.TagValue]] = None,
 3955        annotations: Optional[List[base.Annotation]] = None
 3956    ) -> None:
 3957        """
 3958        Adds a new decision to the graph using a specific decision ID,
 3959        rather than automatically assigning a new decision ID like
 3960        `addDecision` does. Otherwise works like `addDecision`.
 3961
 3962        Raises a `DecisionCollisionError` if the specified decision ID
 3963        is already in use.
 3964        """
 3965        # Defaults
 3966        if domain is None:
 3967            domain = base.DEFAULT_DOMAIN
 3968        if tags is None:
 3969            tags = {}
 3970        if annotations is None:
 3971            annotations = []
 3972
 3973        # Error checking
 3974        if dID in self.nodes:
 3975            raise DecisionCollisionError(
 3976                f"Cannot add a node with id {dID} and name {name!r}:"
 3977                f" that ID is already used by node {self.identityOf(dID)}"
 3978            )
 3979
 3980        if name in self.nameLookup and WARN_OF_NAME_COLLISIONS:
 3981            warnings.warn(
 3982                (
 3983                    f"Adding decision {name!r}: Another decision with"
 3984                    f" that name already exists."
 3985                ),
 3986                DecisionCollisionWarning
 3987            )
 3988
 3989        # Add the decision
 3990        self.add_node(
 3991            dID,
 3992            name=name,
 3993            domain=domain,
 3994            tags=tags,
 3995            annotations=annotations
 3996        )
 3997        #TODO: Elide tags/annotations if they're empty?
 3998
 3999        # Track it in our `nameLookup` dictionary
 4000        self.nameLookup.setdefault(name, []).append(dID)
 4001
 4002    def addTransition(
 4003        self,
 4004        fromDecision: base.AnyDecisionSpecifier,
 4005        name: base.Transition,
 4006        toDecision: base.AnyDecisionSpecifier,
 4007        reciprocal: Optional[base.Transition] = None,
 4008        tags: Optional[Dict[base.Tag, base.TagValue]] = None,
 4009        annotations: Optional[List[base.Annotation]] = None,
 4010        revTags: Optional[Dict[base.Tag, base.TagValue]] = None,
 4011        revAnnotations: Optional[List[base.Annotation]] = None,
 4012        requires: Optional[base.Requirement] = None,
 4013        consequence: Optional[base.Consequence] = None,
 4014        revRequires: Optional[base.Requirement] = None,
 4015        revConsequece: Optional[base.Consequence] = None
 4016    ) -> None:
 4017        """
 4018        Adds a transition connecting two decisions. A specifier for each
 4019        decision is required, as is a name for the transition. If a
 4020        `reciprocal` is provided, a reciprocal edge will be added in the
 4021        opposite direction using that name; by default only the specified
 4022        edge is added. A `TransitionCollisionError` will be raised if the
 4023        `reciprocal` matches the name of an existing edge at the
 4024        destination decision.
 4025
 4026        Both decisions must already exist, or a `MissingDecisionError`
 4027        will be raised.
 4028
 4029        A dictionary of tags and/or a list of annotations may be
 4030        provided. Tags and/or annotations for the reverse edge may also
 4031        be specified if one is being added.
 4032
 4033        The `requires`, `consequence`, `revRequires`, and `revConsequece`
 4034        arguments specify requirements and/or consequences of the new
 4035        outgoing and reciprocal edges.
 4036
 4037        An example:
 4038
 4039        >>> g = DecisionGraph()
 4040        >>> g.addDecision('A')
 4041        0
 4042        >>> g.addDecision('B')
 4043        1
 4044        >>> g.addDecision('C')
 4045        2
 4046        >>> g.addTransition('A', 'up', 'B', 'down')
 4047        >>> g.destinationsFrom('A')
 4048        {'up': 1}
 4049        >>> g.destinationsFrom('B')
 4050        {'down': 0}
 4051        >>> g.addTransition('A', 'right', 'C', 'left')
 4052        >>> g.destinationsFrom('A')
 4053        {'up': 1, 'right': 2}
 4054        >>> g.destinationsFrom('C')
 4055        {'left': 0}
 4056        """
 4057        # Defaults
 4058        if tags is None:
 4059            tags = {}
 4060        if annotations is None:
 4061            annotations = []
 4062        if revTags is None:
 4063            revTags = {}
 4064        if revAnnotations is None:
 4065            revAnnotations = []
 4066
 4067        # Error checking
 4068        fromID = self.resolveDecision(fromDecision)
 4069        toID = self.resolveDecision(toDecision)
 4070
 4071        # Note: have to check this first so we don't add the forward edge
 4072        # and then error out after a side effect!
 4073        if (
 4074            reciprocal is not None
 4075        and self.getDestination(toDecision, reciprocal) is not None
 4076        ):
 4077            raise TransitionCollisionError(
 4078                f"Cannot add a transition from"
 4079                f" {self.identityOf(fromDecision)} to"
 4080                f" {self.identityOf(toDecision)} with reciprocal edge"
 4081                f" {reciprocal!r}: {reciprocal!r} is already used as an"
 4082                f" edge name at {self.identityOf(toDecision)}."
 4083            )
 4084
 4085        # Add the edge
 4086        self.add_edge(
 4087            fromID,
 4088            toID,
 4089            key=name,
 4090            tags=tags,
 4091            annotations=annotations
 4092        )
 4093        self.setTransitionRequirement(fromID, name, requires)
 4094        if consequence is not None:
 4095            self.setConsequence(fromID, name, consequence)
 4096        if reciprocal is not None:
 4097            # Add the reciprocal edge
 4098            self.add_edge(
 4099                toID,
 4100                fromID,
 4101                key=reciprocal,
 4102                tags=revTags,
 4103                annotations=revAnnotations
 4104            )
 4105            self.setReciprocal(fromID, name, reciprocal)
 4106            self.setTransitionRequirement(
 4107                toID,
 4108                reciprocal,
 4109                revRequires
 4110            )
 4111            if revConsequece is not None:
 4112                self.setConsequence(toID, reciprocal, revConsequece)
 4113
 4114    def removeTransition(
 4115        self,
 4116        fromDecision: base.AnyDecisionSpecifier,
 4117        transition: base.Transition,
 4118        removeReciprocal=False
 4119    ) -> Union[
 4120        TransitionProperties,
 4121        Tuple[TransitionProperties, TransitionProperties]
 4122    ]:
 4123        """
 4124        Removes a transition. If `removeReciprocal` is true (False is the
 4125        default) any reciprocal transition will also be removed (but no
 4126        error will occur if there wasn't a reciprocal).
 4127
 4128        For each removed transition, *every* transition that targeted
 4129        that transition as its reciprocal will have its reciprocal set to
 4130        `None`, to avoid leaving any invalid reciprocal values.
 4131
 4132        Raises a `KeyError` if either the target decision or the target
 4133        transition does not exist.
 4134
 4135        Returns a transition properties dictionary with the properties
 4136        of the removed transition, or if `removeReciprocal` is true,
 4137        returns a pair of such dictionaries for the target transition
 4138        and its reciprocal.
 4139
 4140        ## Example
 4141
 4142        >>> g = DecisionGraph()
 4143        >>> g.addDecision('A')
 4144        0
 4145        >>> g.addDecision('B')
 4146        1
 4147        >>> g.addTransition('A', 'up', 'B', 'down', tags={'wide'})
 4148        >>> g.addTransition('A', 'in', 'B', 'out') # we won't touch this
 4149        >>> g.addTransition('A', 'next', 'B')
 4150        >>> g.setReciprocal('A', 'next', 'down', setBoth=False)
 4151        >>> p = g.removeTransition('A', 'up')
 4152        >>> p['tags']
 4153        {'wide'}
 4154        >>> g.destinationsFrom('A')
 4155        {'in': 1, 'next': 1}
 4156        >>> g.destinationsFrom('B')
 4157        {'down': 0, 'out': 0}
 4158        >>> g.getReciprocal('B', 'down') is None
 4159        True
 4160        >>> g.getReciprocal('A', 'next') # Asymmetrical left over
 4161        'down'
 4162        >>> g.getReciprocal('A', 'in') # not affected
 4163        'out'
 4164        >>> g.getReciprocal('B', 'out') # not affected
 4165        'in'
 4166        >>> # Now with removeReciprocal set to True
 4167        >>> g.addTransition('A', 'up', 'B') # add this back in
 4168        >>> g.setReciprocal('A', 'up', 'down') # sets both
 4169        >>> p = g.removeTransition('A', 'up', removeReciprocal=True)
 4170        >>> g.destinationsFrom('A')
 4171        {'in': 1, 'next': 1}
 4172        >>> g.destinationsFrom('B')
 4173        {'out': 0}
 4174        >>> g.getReciprocal('A', 'next') is None
 4175        True
 4176        >>> g.getReciprocal('A', 'in') # not affected
 4177        'out'
 4178        >>> g.getReciprocal('B', 'out') # not affected
 4179        'in'
 4180        >>> g.removeTransition('A', 'none')
 4181        Traceback (most recent call last):
 4182        ...
 4183        exploration.core.MissingTransitionError...
 4184        >>> g.removeTransition('Z', 'nope')
 4185        Traceback (most recent call last):
 4186        ...
 4187        exploration.core.MissingDecisionError...
 4188        """
 4189        # Resolve target ID
 4190        fromID = self.resolveDecision(fromDecision)
 4191
 4192        # raises if either is missing:
 4193        destination = self.destination(fromID, transition)
 4194        reciprocal = self.getReciprocal(fromID, transition)
 4195
 4196        # Get dictionaries of parallel & antiparallel edges to be
 4197        # checked for invalid reciprocals after removing edges
 4198        # Note: these will update live as we remove edges
 4199        allAntiparallel = self[destination][fromID]
 4200        allParallel = self[fromID][destination]
 4201
 4202        # Remove the target edge
 4203        fProps = self.getTransitionProperties(fromID, transition)
 4204        self.remove_edge(fromID, destination, transition)
 4205
 4206        # Clean up any dangling reciprocal values
 4207        for tProps in allAntiparallel.values():
 4208            if tProps.get('reciprocal') == transition:
 4209                del tProps['reciprocal']
 4210
 4211        # Remove the reciprocal if requested
 4212        if removeReciprocal and reciprocal is not None:
 4213            rProps = self.getTransitionProperties(destination, reciprocal)
 4214            self.remove_edge(destination, fromID, reciprocal)
 4215
 4216            # Clean up any dangling reciprocal values
 4217            for tProps in allParallel.values():
 4218                if tProps.get('reciprocal') == reciprocal:
 4219                    del tProps['reciprocal']
 4220
 4221            return (fProps, rProps)
 4222        else:
 4223            return fProps
 4224
 4225    def addMechanism(
 4226        self,
 4227        name: base.MechanismName,
 4228        where: Optional[base.AnyDecisionSpecifier] = None
 4229    ) -> base.MechanismID:
 4230        """
 4231        Creates a new mechanism with the given name at the specified
 4232        decision, returning its assigned ID. If `where` is `None`, it
 4233        creates a global mechanism. Raises a `MechanismCollisionError`
 4234        if a mechanism with the same name already exists at a specified
 4235        decision (or already exists as a global mechanism).
 4236
 4237        Note that if the decision is deleted, the mechanism will be as
 4238        well.
 4239
 4240        Since `MechanismState`s are not tracked by `DecisionGraph`s but
 4241        instead are part of a `State`, the mechanism won't be in any
 4242        particular state, which means it will be treated as being in the
 4243        `base.DEFAULT_MECHANISM_STATE`.
 4244        """
 4245        if where is None:
 4246            mechs = self.globalMechanisms
 4247            dID = None
 4248        else:
 4249            dID = self.resolveDecision(where)
 4250            mechs = self.nodes[dID].setdefault('mechanisms', {})
 4251
 4252        if name in mechs:
 4253            if dID is None:
 4254                raise MechanismCollisionError(
 4255                    f"A global mechanism named {name!r} already exists."
 4256                )
 4257            else:
 4258                raise MechanismCollisionError(
 4259                    f"A mechanism named {name!r} already exists at"
 4260                    f" decision {self.identityOf(dID)}."
 4261                )
 4262
 4263        mID = self._assignMechanismID()
 4264        mechs[name] = mID
 4265        self.mechanisms[mID] = (dID, name)
 4266        return mID
 4267
 4268    def mechanismsAt(
 4269        self,
 4270        decision: base.AnyDecisionSpecifier
 4271    ) -> Dict[base.MechanismName, base.MechanismID]:
 4272        """
 4273        Returns a dictionary mapping mechanism names to their IDs for
 4274        all mechanisms at the specified decision.
 4275        """
 4276        dID = self.resolveDecision(decision)
 4277
 4278        return self.nodes[dID]['mechanisms']
 4279
 4280    def mechanismDetails(
 4281        self,
 4282        mID: base.MechanismID
 4283    ) -> Optional[Tuple[Optional[base.DecisionID], base.MechanismName]]:
 4284        """
 4285        Returns a tuple containing the decision ID and mechanism name
 4286        for the specified mechanism. Returns `None` if there is no
 4287        mechanism with that ID. For global mechanisms, `None` is used in
 4288        place of a decision ID.
 4289        """
 4290        return self.mechanisms.get(mID)
 4291
 4292    def deleteMechanism(self, mID: base.MechanismID) -> None:
 4293        """
 4294        Deletes the specified mechanism.
 4295        """
 4296        name, dID = self.mechanisms.pop(mID)
 4297
 4298        del self.nodes[dID]['mechanisms'][name]
 4299
 4300    def localLookup(
 4301        self,
 4302        startFrom: Union[
 4303            base.AnyDecisionSpecifier,
 4304            Collection[base.AnyDecisionSpecifier]
 4305        ],
 4306        findAmong: Callable[
 4307            ['DecisionGraph', Union[Set[base.DecisionID], str]],
 4308            Optional[LookupResult]
 4309        ],
 4310        fallbackLayerName: Optional[str] = "fallback",
 4311        fallbackToAllDecisions: bool = True
 4312    ) -> Optional[LookupResult]:
 4313        """
 4314        Looks up some kind of result in the graph by starting from a
 4315        base set of decisions and widening the search iteratively based
 4316        on zones. This first searches for result(s) in the set of
 4317        decisions given, then in the set of all decisions which are in
 4318        level-0 zones containing those decisions, then in level-1 zones,
 4319        etc. When it runs out of relevant zones, it will check all
 4320        decisions which are in any domain that a decision from the
 4321        initial search set is in, and then if `fallbackLayerName` is a
 4322        string, it will provide that string instead of a set of decision
 4323        IDs to the `findAmong` function as the next layer to search.
 4324        After the `fallbackLayerName` is used, if
 4325        `fallbackToAllDecisions` is `True` (the default) a final search
 4326        will be run on all decisions in the graph. The provided
 4327        `findAmong` function is called on each successive decision ID
 4328        set, until it generates a non-`None` result. We stop and return
 4329        that non-`None` result as soon as one is generated. But if none
 4330        of the decision sets consulted generate non-`None` results, then
 4331        the entire result will be `None`.
 4332        """
 4333        # Normalize starting decisions to a set
 4334        if isinstance(startFrom, (int, str, base.DecisionSpecifier)):
 4335            startFrom = set([startFrom])
 4336
 4337        # Resolve decision IDs; convert to set
 4338        searchArea: Union[Set[base.DecisionID], str] = set(
 4339            self.resolveDecision(spec) for spec in startFrom
 4340        )
 4341
 4342        # Find all ancestor zones & all relevant domains
 4343        allAncestors = set()
 4344        relevantDomains = set()
 4345        for startingDecision in searchArea:
 4346            allAncestors |= self.zoneAncestors(startingDecision)
 4347            relevantDomains.add(self.domainFor(startingDecision))
 4348
 4349        # Build layers dictionary
 4350        ancestorLayers: Dict[int, Set[base.Zone]] = {}
 4351        for zone in allAncestors:
 4352            info = self.getZoneInfo(zone)
 4353            assert info is not None
 4354            level = info.level
 4355            ancestorLayers.setdefault(level, set()).add(zone)
 4356
 4357        searchLayers: LookupLayersList = (
 4358            cast(LookupLayersList, [None])
 4359          + cast(LookupLayersList, sorted(ancestorLayers.keys()))
 4360          + cast(LookupLayersList, ["domains"])
 4361        )
 4362        if fallbackLayerName is not None:
 4363            searchLayers.append("fallback")
 4364
 4365        if fallbackToAllDecisions:
 4366            searchLayers.append("all")
 4367
 4368        # Continue our search through zone layers
 4369        for layer in searchLayers:
 4370            # Update search area on subsequent iterations
 4371            if layer == "domains":
 4372                searchArea = set()
 4373                for relevant in relevantDomains:
 4374                    searchArea |= self.allDecisionsInDomain(relevant)
 4375            elif layer == "fallback":
 4376                assert fallbackLayerName is not None
 4377                searchArea = fallbackLayerName
 4378            elif layer == "all":
 4379                searchArea = set(self.nodes)
 4380            elif layer is not None:
 4381                layer = cast(int, layer)  # must be an integer
 4382                searchZones = ancestorLayers[layer]
 4383                searchArea = set()
 4384                for zone in searchZones:
 4385                    searchArea |= self.allDecisionsInZone(zone)
 4386            # else it's the first iteration and we use the starting
 4387            # searchArea
 4388
 4389            try:
 4390                searchResult: Optional[LookupResult] = findAmong(
 4391                    self,
 4392                    searchArea
 4393                )
 4394            except Exception as e:
 4395                note = f" (Search started from: {startFrom!r})"
 4396                if hasattr(e, "add_note"):
 4397                    e.add_note(note)
 4398                else:
 4399                    e.args = (e.args[0] + note,) + e.args[1:]
 4400                raise e
 4401
 4402            if searchResult is not None:
 4403                return searchResult
 4404
 4405        # Didn't find any non-None results.
 4406        return None
 4407
 4408    @staticmethod
 4409    def uniqueMechanismFinder(name: base.MechanismName) -> Callable[
 4410        ['DecisionGraph', Union[Set[base.DecisionID], str]],
 4411        Optional[base.MechanismID]
 4412    ]:
 4413        """
 4414        Returns a search function that looks for the given mechanism ID,
 4415        suitable for use with `localLookup`. The finder will raise a
 4416        `AmbiguousMechanismError` if it finds more than one mechanism
 4417        with the specified name at the same level of the search.
 4418        """
 4419        def namedMechanismFinder(
 4420            graph: 'DecisionGraph',
 4421            searchIn: Union[Set[base.DecisionID], str]
 4422        ) -> Optional[base.MechanismID]:
 4423            """
 4424            Generated finder function for `localLookup` to find a unique
 4425            mechanism by name.
 4426            """
 4427            candidates: List[base.MechanismID] = []
 4428
 4429            if searchIn == "fallback":
 4430                if name in graph.globalMechanisms:
 4431                    candidates = [graph.globalMechanisms[name]]
 4432
 4433            else:
 4434                assert isinstance(searchIn, set)
 4435                for dID in searchIn:
 4436                    mechs = graph.nodes[dID].get('mechanisms', {})
 4437                    if name in mechs:
 4438                        candidates.append(mechs[name])
 4439
 4440            if len(candidates) > 1:
 4441                raise AmbiguousMechanismError(
 4442                    f"There are {len(candidates)} mechanisms named {name!r}"
 4443                    f" in the search area ({len(searchIn)} decisions(s))."
 4444                )
 4445            elif len(candidates) == 1:
 4446                return candidates[0]
 4447            else:
 4448                return None
 4449
 4450        return namedMechanismFinder
 4451
 4452    def lookupMechanism(
 4453        self,
 4454        startFrom: Union[
 4455            base.AnyDecisionSpecifier,
 4456            Collection[base.AnyDecisionSpecifier]
 4457        ],
 4458        name: base.MechanismName
 4459    ) -> base.MechanismID:
 4460        """
 4461        Looks up the mechanism with the given name 'closest' to the
 4462        given decision or set of decisions. First it looks for a
 4463        mechanism with that name that's at one of those decisions. Then
 4464        it starts looking in level-0 zones which contain any of them,
 4465        then in level-1 zones, and so on. If it finds two mechanisms
 4466        with the target name during the same search pass, it raises a
 4467        `AmbiguousMechanismError`, but if it finds one it returns it.
 4468        Raises a `MissingMechanismError` if there is no mechanisms with
 4469        that name among global mechanisms (searched after the last
 4470        applicable level of zones) or anywhere in the graph (which is the
 4471        final level of search after checking global mechanisms).
 4472
 4473        For example:
 4474
 4475        >>> d = DecisionGraph()
 4476        >>> d.addDecision('A')
 4477        0
 4478        >>> d.addDecision('B')
 4479        1
 4480        >>> d.addDecision('C')
 4481        2
 4482        >>> d.addDecision('D')
 4483        3
 4484        >>> d.addDecision('E')
 4485        4
 4486        >>> d.addMechanism('switch', 'A')
 4487        0
 4488        >>> d.addMechanism('switch', 'B')
 4489        1
 4490        >>> d.addMechanism('switch', 'C')
 4491        2
 4492        >>> d.addMechanism('lever', 'D')
 4493        3
 4494        >>> d.addMechanism('lever', None)  # global
 4495        4
 4496        >>> d.createZone('Z1', 0)
 4497        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 4498 annotations=[])
 4499        >>> d.createZone('Z2', 0)
 4500        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 4501 annotations=[])
 4502        >>> d.createZone('Zup', 1)
 4503        ZoneInfo(level=1, parents=set(), contents=set(), tags={},\
 4504 annotations=[])
 4505        >>> d.addDecisionToZone('A', 'Z1')
 4506        >>> d.addDecisionToZone('B', 'Z1')
 4507        >>> d.addDecisionToZone('C', 'Z2')
 4508        >>> d.addDecisionToZone('D', 'Z2')
 4509        >>> d.addDecisionToZone('E', 'Z1')
 4510        >>> d.addZoneToZone('Z1', 'Zup')
 4511        >>> d.addZoneToZone('Z2', 'Zup')
 4512        >>> d.lookupMechanism(set(), 'switch')  # 3x among all decisions
 4513        Traceback (most recent call last):
 4514        ...
 4515        exploration.core.AmbiguousMechanismError...
 4516        >>> d.lookupMechanism(set(), 'lever')  # 1x global > 1x all
 4517        4
 4518        >>> d.lookupMechanism({'D'}, 'lever')  # local
 4519        3
 4520        >>> d.lookupMechanism({'A'}, 'lever')  # found at D via Zup
 4521        3
 4522        >>> d.lookupMechanism({'A', 'D'}, 'lever')  # local again
 4523        3
 4524        >>> d.lookupMechanism({'A'}, 'switch')  # local
 4525        0
 4526        >>> d.lookupMechanism({'B'}, 'switch')  # local
 4527        1
 4528        >>> d.lookupMechanism({'C'}, 'switch')  # local
 4529        2
 4530        >>> d.lookupMechanism({'A', 'B'}, 'switch')  # ambiguous
 4531        Traceback (most recent call last):
 4532        ...
 4533        exploration.core.AmbiguousMechanismError...
 4534        >>> d.lookupMechanism({'A', 'B', 'C'}, 'switch')  # ambiguous
 4535        Traceback (most recent call last):
 4536        ...
 4537        exploration.core.AmbiguousMechanismError...
 4538        >>> d.lookupMechanism({'B', 'D'}, 'switch')  # not ambiguous
 4539        1
 4540        >>> d.lookupMechanism({'E', 'D'}, 'switch')  # ambiguous at L0 zone
 4541        Traceback (most recent call last):
 4542        ...
 4543        exploration.core.AmbiguousMechanismError...
 4544        >>> d.lookupMechanism({'E'}, 'switch')  # ambiguous at L0 zone
 4545        Traceback (most recent call last):
 4546        ...
 4547        exploration.core.AmbiguousMechanismError...
 4548        >>> d.lookupMechanism({'D'}, 'switch')  # found at L0 zone
 4549        2
 4550        """
 4551        result = self.localLookup(
 4552            startFrom,
 4553            DecisionGraph.uniqueMechanismFinder(name)
 4554        )
 4555        if result is None:
 4556            raise MissingMechanismError(
 4557                f"No mechanism named {name!r}"
 4558            )
 4559        else:
 4560            return result
 4561
 4562    def resolveMechanism(
 4563        self,
 4564        specifier: base.AnyMechanismSpecifier,
 4565        startFrom: Union[
 4566            None,
 4567            base.AnyDecisionSpecifier,
 4568            Collection[base.AnyDecisionSpecifier]
 4569        ] = None
 4570    ) -> base.MechanismID:
 4571        """
 4572        Works like `lookupMechanism`, except it accepts a
 4573        `base.AnyMechanismSpecifier` which may have position information
 4574        baked in, and so the `startFrom` information is optional. If
 4575        position information isn't specified in the mechanism specifier
 4576        and startFrom is not provided, the mechanism is searched for at
 4577        the global scope and then in the entire graph. On the other
 4578        hand, if the specifier includes any position information, the
 4579        startFrom value provided here will be ignored.
 4580        """
 4581        if isinstance(specifier, base.MechanismID):
 4582            return specifier
 4583
 4584        elif isinstance(specifier, base.MechanismName):
 4585            if startFrom is None:
 4586                startFrom = set()
 4587            return self.lookupMechanism(startFrom, specifier)
 4588
 4589        elif isinstance(specifier, base.MechanismSpecifier):
 4590            domain, zone, decision, mechanism = specifier
 4591            if domain is None and zone is None and decision is None:
 4592                if startFrom is None:
 4593                    startFrom = set()
 4594                return self.lookupMechanism(startFrom, mechanism)
 4595
 4596            elif isinstance(decision, base.DecisionID):
 4597                # Specifying a decision ID restricts the mechanism to
 4598                # appear at exactly that decision and NOT be global...
 4599                if domain is not None or zone is not None:
 4600                    warnings.warn(
 4601                        (
 4602                            f"Mechanism specifier includes domain and/or"
 4603                            f" zone in addition to decision-by-ID:"
 4604                            f" {specifier!r}"
 4605                        ),
 4606                        InvalidMechanismSpecifierWarning
 4607                    )
 4608
 4609                mechs = self.nodes[decision].get('mechanisms', {})
 4610                found = mechs.get(mechanism)
 4611                if found is None:
 4612                    raise MissingMechanismError(
 4613                        f"No mechanism named {mechanism!r} at specific"
 4614                        f" decision {self.identityOf(decision)}"
 4615                    )
 4616                return found
 4617
 4618            elif decision is not None:
 4619                startFrom = self.resolveDecisions(
 4620                    base.DecisionSpecifier(domain, zone, decision)
 4621                )
 4622                return self.lookupMechanism(startFrom, mechanism)
 4623
 4624            else:  # decision is None but domain and/or zone aren't
 4625                startFrom = set()
 4626                if zone is not None:
 4627                    baseStart = self.allDecisionsInZone(zone)
 4628                else:
 4629                    baseStart = set(self)
 4630
 4631                if domain is None:
 4632                    startFrom = baseStart
 4633                else:
 4634                    for dID in baseStart:
 4635                        if self.domainFor(dID) == domain:
 4636                            startFrom.add(dID)
 4637                return self.lookupMechanism(startFrom, mechanism)
 4638
 4639        else:
 4640            raise TypeError(
 4641                f"Invalid mechanism specifier: {repr(specifier)}"
 4642                f"\n(Must be a mechanism ID, mechanism name, or"
 4643                f" mechanism specifier tuple)"
 4644            )
 4645
 4646    def legibleMechanismSpecifier(
 4647        self,
 4648        mID: base.MechanismID,
 4649        minimal: bool = False
 4650    ) -> Union[base.MechanismSpecifier, base.MechanismID]:
 4651        '''
 4652        Given a mechanism ID, returns an unambiguous
 4653        `base.MechanismSpecifier` for that mechanism, including
 4654        domain/zone/decision-name parts as necessary. If there is no
 4655        unambiguous specifier for that mechanism, returns the mechanism
 4656        ID as-is. Also returns the ID as-is if no mechanism with that ID
 4657        exists.
 4658
 4659        Set `minimal` to True (default is `False`) to use a minimal
 4660        unambiguous specifier (more likely to be made ambiguous by
 4661        future decision/mechanism additions).
 4662
 4663        Some examples:
 4664
 4665        >>> g = DecisionGraph()
 4666        >>> g.addDecision('A')
 4667        0
 4668        >>> g.addDecision('B')
 4669        1
 4670        >>> g.addDecision('C')
 4671        2
 4672        >>> g.addDecision('A')
 4673        3
 4674        >>> g.addDecision('C')
 4675        4
 4676        >>> g.createZone('Z', 0)
 4677        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 4678 annotations=[])
 4679        >>> g.createZone('Q', 0)
 4680        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 4681 annotations=[])
 4682        >>> g.addDecisionToZone(0, 'Z')
 4683        >>> g.addDecisionToZone('B', 'Z')
 4684        >>> g.addDecisionToZone(3, 'Q')
 4685        >>> g.addMechanism('global')
 4686        0
 4687        >>> g.addMechanism('door', 0)
 4688        1
 4689        >>> g.addMechanism('door', 2)
 4690        2
 4691        >>> g.addMechanism('block', 2)
 4692        3
 4693        >>> g.addMechanism('lever', 0)
 4694        4
 4695        >>> g.addMechanism('lever', 'B')
 4696        5
 4697        >>> g.addMechanism('door', 3)
 4698        6
 4699        >>> g.addMechanism('block', 4)
 4700        7
 4701        >>> g.legibleMechanismSpecifier(0)
 4702        MechanismSpecifier(domain=None, zone=None, decision=None, name='global')
 4703        >>> g.legibleMechanismSpecifier(1)
 4704        MechanismSpecifier(domain='main', zone='Z', decision='A', name='door')
 4705        >>> g.legibleMechanismSpecifier(2)
 4706        MechanismSpecifier(domain='main', zone=None, decision='C', name='door')
 4707        >>> g.legibleMechanismSpecifier(3)  # ambiguous with 'block' at C[4]
 4708        3
 4709        >>> g.legibleMechanismSpecifier(4)
 4710        MechanismSpecifier(domain='main', zone='Z', decision='A', name='lever')
 4711        >>> g.legibleMechanismSpecifier(5)
 4712        MechanismSpecifier(domain='main', zone='Z', decision='B', name='lever')
 4713        >>> g.legibleMechanismSpecifier(6)
 4714        MechanismSpecifier(domain='main', zone='Q', decision='A', name='door')
 4715        >>> g.legibleMechanismSpecifier(7)  # ambiguous with 'block' at C[2]
 4716        7
 4717        '''
 4718        details = self.mechanismDetails(mID)
 4719        if details is None:
 4720            return mID
 4721        elif not minimal:
 4722            # Go straight to as full a specifier as we can
 4723            dID, mName = details
 4724            if dID is None:
 4725                maybe = base.MechanismSpecifier(None, None, None, mName)
 4726                try:
 4727                    resolved = self.resolveMechanism(maybe)
 4728                    if resolved == mID:
 4729                        return maybe
 4730                    else:
 4731                        return mID
 4732                    # Else got wrong one without specifying more info
 4733                except (
 4734                    AmbiguousMechanismError,
 4735                    AmbiguousDecisionSpecifierError
 4736                ):
 4737                    # Not specific enough
 4738                    return mID
 4739                except MissingMechanismError:
 4740                    # Nothing findable with that name; return mID as-is
 4741                    # Note: This *should* be caught by case above instead I
 4742                    # think, but doesn't hurt to be defensive here
 4743                    return mID
 4744            else:
 4745                # Look up decision's info
 4746                dInfo = self.decisionInfo(dID)
 4747                dName = dInfo["name"]
 4748                dDomain = dInfo["domain"]
 4749
 4750                # Include domain and first zone we can find that's
 4751                # unambiguous
 4752                for zone in self.zoneParents(dID):
 4753                    maybe = base.MechanismSpecifier(
 4754                        dDomain,
 4755                        zone,
 4756                        dName,
 4757                        mName
 4758                    )
 4759                    try:
 4760                        resolved = self.resolveMechanism(maybe)
 4761                        if resolved == mID:
 4762                            return maybe
 4763                        else:
 4764                            # Got wrong one for this zone
 4765                            continue
 4766                    except (
 4767                        AmbiguousMechanismError,
 4768                        AmbiguousDecisionSpecifierError
 4769                    ):
 4770                        # Not specific enough
 4771                        continue
 4772                    except MissingMechanismError:
 4773                        # Shouldn't be possible, but just in case
 4774                        return mID
 4775
 4776                # Try without a zone
 4777                maybe = base.MechanismSpecifier(
 4778                    dDomain,
 4779                    None,
 4780                    dName,
 4781                    mName
 4782                )
 4783                try:
 4784                    resolved = self.resolveMechanism(maybe)
 4785                    if resolved == mID:
 4786                        return maybe
 4787                    else:
 4788                        # Got wrong one; no altenratives
 4789                        return mID
 4790                except (
 4791                    AmbiguousMechanismError,
 4792                    AmbiguousDecisionSpecifierError
 4793                ) as e:
 4794                    # Not specific enough
 4795                    return mID
 4796                except MissingMechanismError:
 4797                    # Shouldn't be possible, but just in case
 4798                    return mID
 4799        else:
 4800            # Minimal requested; details were available
 4801            dID, mName = details
 4802            # First try bare specifier with just name. Should catch
 4803            # global mechanisms as well as unique locals
 4804            maybe = base.MechanismSpecifier(None, None, None, mName)
 4805            try:
 4806                resolved = self.resolveMechanism(maybe)
 4807                if resolved == mID:
 4808                    return maybe
 4809                # Else got wrong one without specifying more info
 4810            except (
 4811                AmbiguousMechanismError,
 4812                AmbiguousDecisionSpecifierError
 4813            ):
 4814                # Not specific enough
 4815                pass
 4816            except MissingMechanismError:
 4817                # Nothing findable with that name; return mID as-is
 4818                # Note: This *should* be caught by case above instead I
 4819                # think, but doesn't hurt to be defensive here
 4820                return mID
 4821
 4822            # A global mechanism we couldn't resolve
 4823            if dID is None:
 4824                return mID
 4825
 4826            # Look up decision's info
 4827            dInfo = self.decisionInfo(dID)
 4828            dName = dInfo["name"]
 4829            dDomain = dInfo["domain"]
 4830
 4831            # Try with just decision name
 4832            maybe = base.MechanismSpecifier(None, None, dName, mName)
 4833            try:
 4834                resolved = self.resolveMechanism(maybe)
 4835                if resolved == mID:
 4836                    return maybe
 4837                # Else got wrong one without specifying more info
 4838            except (
 4839                AmbiguousMechanismError,
 4840                AmbiguousDecisionSpecifierError
 4841            ):
 4842                # Not specific enough
 4843                pass
 4844            except MissingMechanismError:
 4845                # Shouldn't be possible, but just in case
 4846                return mID
 4847
 4848            # Try each possible direct parent zone
 4849            for zone in self.zoneParents(dID):
 4850                maybe = base.MechanismSpecifier(None, zone, dName, mName)
 4851                try:
 4852                    resolved = self.resolveMechanism(maybe)
 4853                    if resolved == mID:
 4854                        return maybe
 4855                    # Else got wrong one without specifying more info
 4856                except (
 4857                    AmbiguousMechanismError,
 4858                    AmbiguousDecisionSpecifierError
 4859                ):
 4860                    # Not specific enough
 4861                    pass
 4862                except MissingMechanismError:
 4863                    # Shouldn't be possible, but just in case
 4864                    return mID
 4865
 4866            # No zones or none specific enough: try adding domain w/
 4867            # each zone
 4868            for zone in self.zoneParents(dID):
 4869                maybe = base.MechanismSpecifier(dDomain, zone, dName, mName)
 4870                try:
 4871                    resolved = self.resolveMechanism(maybe)
 4872                    if resolved == mID:
 4873                        return maybe
 4874                    # Else got wrong one without specifying more info
 4875                except (
 4876                    AmbiguousMechanismError,
 4877                    AmbiguousDecisionSpecifierError
 4878                ):
 4879                    # Not specific enough
 4880                    pass
 4881                except MissingMechanismError:
 4882                    # Shouldn't be possible, but just in case
 4883                    return mID
 4884
 4885            # Nothing but ID is specific enough
 4886            return mID
 4887
 4888    def walkConsequenceMechanisms(
 4889        self,
 4890        consequence: base.Consequence,
 4891        searchFrom: Set[base.DecisionID],
 4892        replaceNames: int = 0
 4893    ) -> Generator[base.MechanismID, None, None]:
 4894        """
 4895        Yields each requirement in the given `base.Consequence`,
 4896        including those in `base.Condition`s, `base.ConditionalSkill`s
 4897        within `base.Challenge`s, and those set or toggled by
 4898        `base.Effect`s. The `searchFrom` argument specifies where to
 4899        start searching for mechanisms, since requirements include them
 4900        by name, not by ID.
 4901
 4902        If `replaceNames` is set to 1, any mechanism names resolved
 4903        during this process will be replaced by full mechanism
 4904        specifiers (see `DecisionGraph.legibleMechanismSpecifier`) that
 4905        include domain and a zone. Note that if the process crashes due
 4906        to an ambiguous mechanism name, requirements up to that point
 4907        will still have been changed.
 4908        
 4909        The default for `replaceNames` (0) will not change any mechanism
 4910        names/specifiers. Setting it to 2 instead of 1 will cause it to
 4911        use the least-specific unambiguous mechanism specifier it can
 4912        find (but note that if you're going to keep adding to the graph,
 4913        such specifiers are more likely to become ambiguous in the
 4914        future).
 4915
 4916        Set `replaceNames` to 3 to replace names with mechanism IDs
 4917        only.
 4918        """
 4919        for (index, part) in base.walkParts(consequence):
 4920            if isinstance(part, dict):
 4921                if 'skills' in part:  # a Challenge
 4922                    part = cast(base.Challenge, part)
 4923                    for cSkill in part['skills'].walk():
 4924                        if isinstance(cSkill, base.ConditionalSkill):
 4925                            yield from self.walkRequirementMechanisms(
 4926                                cSkill.requirement,
 4927                                searchFrom,
 4928                                replaceNames
 4929                            )
 4930                elif 'condition' in part:  # a Condition
 4931                    part = cast(base.Condition, part)
 4932                    yield from self.walkRequirementMechanisms(
 4933                        part['condition'],
 4934                        searchFrom,
 4935                        replaceNames
 4936                    )
 4937                elif 'value' in part:  # an Effect
 4938                    part = cast(base.Effect, part)
 4939                    val = part['value']
 4940                    if part['type'] == 'set':
 4941                        if (
 4942                            isinstance(val, tuple)
 4943                        and len(val) == 2
 4944                        and isinstance(val[1], base.MechanismState)
 4945                        ):
 4946                            resolved = self.resolveMechanism(
 4947                                cast(base.AnyMechanismSpecifier, val[0]),
 4948                                searchFrom
 4949                            )
 4950                            if replaceNames == 1:
 4951                                spec = self.legibleMechanismSpecifier(
 4952                                    resolved,
 4953                                    False
 4954                                )
 4955                            elif replaceNames == 2:
 4956                                spec = self.legibleMechanismSpecifier(
 4957                                    resolved,
 4958                                    True
 4959                                )
 4960                            elif replaceNames == 3:
 4961                                spec = resolved
 4962                            elif replaceNames != 0:
 4963                                raise ValueError(
 4964                                    f"Invalid replaceNames value:"
 4965                                    f" {replaceNames!r}"
 4966                                )
 4967                            if replaceNames > 0:
 4968                                part['value'] = (spec, val[1])
 4969                            yield resolved
 4970                    elif part['type'] == 'toggle':
 4971                        if isinstance(val, tuple):
 4972                            assert len(val) == 2
 4973                            between = cast(List[base.MechanismState], val[1])
 4974                            resolved = self.resolveMechanism(
 4975                                cast(base.AnyMechanismSpecifier, val[0]),
 4976                                searchFrom
 4977                            )
 4978                            if replaceNames == 1:
 4979                                spec = self.legibleMechanismSpecifier(
 4980                                    resolved,
 4981                                    False
 4982                                )
 4983                            elif replaceNames == 2:
 4984                                spec = self.legibleMechanismSpecifier(
 4985                                    resolved,
 4986                                    True
 4987                                )
 4988                            elif replaceNames == 3:
 4989                                spec = resolved
 4990                            elif replaceNames != 0:
 4991                                raise ValueError(
 4992                                    f"Invalid replaceNames value:"
 4993                                    f" {replaceNames!r}"
 4994                                )
 4995                            if replaceNames > 0:
 4996                                part['value'] = (spec, between)
 4997                            yield resolved
 4998            else:
 4999                # Sub-parts will get walked in separate iterations
 5000                pass
 5001
 5002    def walkRequirementMechanisms(
 5003        self,
 5004        req: base.Requirement,
 5005        searchFrom: Set[base.DecisionID],
 5006        replaceNames: int = 0
 5007    ) -> Generator[base.MechanismID, None, None]:
 5008        """
 5009        Given a requirement, yields any mechanisms mentioned in that
 5010        requirement, in depth-first traversal order.
 5011
 5012        If `replaceNames` is 1, 2, or 3 (default is 0) then the
 5013        requirement is actually edited to replace any mechanism names
 5014        with either a specifier or their resolved IDs. See
 5015        `walkConsequenceMechanisms` for `replaceNames` details.
 5016        """
 5017        for part in req.walk():
 5018            if isinstance(part, base.ReqMechanism):
 5019                mech = part.mechanism
 5020                resolved = self.resolveMechanism(
 5021                    mech,
 5022                    startFrom=searchFrom
 5023                )
 5024                if replaceNames in (1, 2, 3):
 5025                    if replaceNames == 1:
 5026                        spec = self.legibleMechanismSpecifier(
 5027                            resolved,
 5028                            False
 5029                        )
 5030                    elif replaceNames == 2:
 5031                        spec = self.legibleMechanismSpecifier(
 5032                            resolved,
 5033                            True
 5034                        )
 5035                    elif replaceNames == 3:
 5036                        spec = resolved
 5037                    part.mechanism = spec
 5038                elif replaceNames != 0:
 5039                    raise ValueError(
 5040                        f"Invalid replaceNames value:"
 5041                        f" {replaceNames!r}"
 5042                    )
 5043                yield resolved
 5044
 5045    def addUnexploredEdge(
 5046        self,
 5047        fromDecision: base.AnyDecisionSpecifier,
 5048        name: base.Transition,
 5049        destinationName: Optional[base.DecisionName] = None,
 5050        reciprocal: Optional[base.Transition] = None,
 5051        toDomain: Optional[base.Domain] = None,
 5052        placeInZone: Optional[base.Zone] = None,
 5053        tags: Optional[Dict[base.Tag, base.TagValue]] = None,
 5054        annotations: Optional[List[base.Annotation]] = None,
 5055        revTags: Optional[Dict[base.Tag, base.TagValue]] = None,
 5056        revAnnotations: Optional[List[base.Annotation]] = None,
 5057        requires: Optional[base.Requirement] = None,
 5058        consequence: Optional[base.Consequence] = None,
 5059        revRequires: Optional[base.Requirement] = None,
 5060        revConsequece: Optional[base.Consequence] = None
 5061    ) -> base.DecisionID:
 5062        """
 5063        Adds a transition connecting to a new decision named `'_u.-n-'`
 5064        where '-n-' is the number of unknown decisions (named or not)
 5065        that have ever been created in this graph (or using the
 5066        specified destination name if one is provided). This represents
 5067        a transition to an unknown destination. The destination node
 5068        gets tagged 'unconfirmed'.
 5069
 5070        This also adds a reciprocal transition in the reverse direction,
 5071        unless `reciprocal` is left as the default `None`. The reciprocal
 5072        will use the provided name. The new decision will be in the same
 5073        domain as the decision it's connected to, unless `toDecision` is
 5074        specified, in which case it will be in that domain.
 5075
 5076        The new decision will not be placed into any zones, unless
 5077        `placeInZone` is specified, in which case it will be placed into
 5078        that zone. If that zone needs to be created, it will be created
 5079        at level 0; in that case that zone will be added to any
 5080        grandparent zones of the decision we're branching off of. If
 5081        `placeInZone` is set to `base.DefaultZone`, then the new
 5082        decision will be placed into each parent zone of the decision
 5083        we're branching off of, as long as the new decision is in the
 5084        same domain as the decision we're branching from (otherwise only
 5085        an explicit `placeInZone` would apply).
 5086
 5087        The ID of the decision that was created is returned.
 5088
 5089        A `MissingDecisionError` will be raised if the starting decision
 5090        does not exist, a `TransitionCollisionError` will be raised if
 5091        it exists but already has a transition with the given name, and a
 5092        `DecisionCollisionWarning` will be issued if a decision with the
 5093        specified destination name already exists (won't happen when
 5094        using an automatic name).
 5095
 5096        Lists of tags and/or annotations (strings in both cases) may be
 5097        provided. These may also be provided for the reciprocal edge.
 5098
 5099        Similarly, requirements and/or consequences for either edge may
 5100        be provided.
 5101
 5102        ## Example
 5103
 5104        >>> g = DecisionGraph()
 5105        >>> g.addDecision('A')
 5106        0
 5107        >>> g.addUnexploredEdge('A', 'up')
 5108        1
 5109        >>> g.nameFor(1)
 5110        '_u.0'
 5111        >>> g.decisionTags(1)
 5112        {'unconfirmed': 1}
 5113        >>> g.getReciprocal('A', 'up') is None
 5114        True
 5115        >>> g.addUnexploredEdge('A', 'right', 'B', 'left')
 5116        2
 5117        >>> g.nameFor(2)
 5118        'B'
 5119        >>> g.decisionTags(2)
 5120        {'unconfirmed': 1}
 5121        >>> g.getReciprocal('A', 'right')
 5122        'left'
 5123        >>> g.addUnexploredEdge('A', 'down', None, 'up')
 5124        3
 5125        >>> g.nameFor(3)
 5126        '_u.2'
 5127        >>> g.addUnexploredEdge(
 5128        ...    '_u.0',
 5129        ...    'beyond',
 5130        ...    None,
 5131        ...    'return',
 5132        ...    toDomain='otherDomain',
 5133        ...    tags={'fast':1},
 5134        ...    revTags={'slow':1},
 5135        ...    annotations=['comment'],
 5136        ...    revAnnotations=['one', 'two'],
 5137        ...    requires=base.ReqCapability('dash'),
 5138        ...    revRequires=base.ReqCapability('super dash'),
 5139        ...    consequence=[base.effect(gain='super dash')],
 5140        ...    revConsequece=[base.effect(lose='super dash')]
 5141        ... )
 5142        4
 5143        >>> g.nameFor(4)
 5144        '_u.3'
 5145        >>> g.domainFor(4)
 5146        'otherDomain'
 5147        >>> g.transitionTags('_u.0', 'beyond')
 5148        {'fast': 1}
 5149        >>> g.transitionAnnotations('_u.0', 'beyond')
 5150        ['comment']
 5151        >>> g.getTransitionRequirement('_u.0', 'beyond')
 5152        ReqCapability('dash')
 5153        >>> e = g.getConsequence('_u.0', 'beyond')
 5154        >>> e == [base.effect(gain='super dash')]
 5155        True
 5156        >>> g.transitionTags('_u.3', 'return')
 5157        {'slow': 1}
 5158        >>> g.transitionAnnotations('_u.3', 'return')
 5159        ['one', 'two']
 5160        >>> g.getTransitionRequirement('_u.3', 'return')
 5161        ReqCapability('super dash')
 5162        >>> e = g.getConsequence('_u.3', 'return')
 5163        >>> e == [base.effect(lose='super dash')]
 5164        True
 5165        """
 5166        # Defaults
 5167        if tags is None:
 5168            tags = {}
 5169        if annotations is None:
 5170            annotations = []
 5171        if revTags is None:
 5172            revTags = {}
 5173        if revAnnotations is None:
 5174            revAnnotations = []
 5175
 5176        # Resolve ID
 5177        fromID = self.resolveDecision(fromDecision)
 5178        if toDomain is None:
 5179            toDomain = self.domainFor(fromID)
 5180
 5181        if name in self.destinationsFrom(fromID):
 5182            raise TransitionCollisionError(
 5183                f"Cannot add a new edge {name!r}:"
 5184                f" {self.identityOf(fromDecision)} already has an"
 5185                f" outgoing edge with that name."
 5186            )
 5187
 5188        if destinationName in self.nameLookup and WARN_OF_NAME_COLLISIONS:
 5189            warnings.warn(
 5190                (
 5191                    f"Cannot add a new unexplored node"
 5192                    f" {destinationName!r}: A decision with that name"
 5193                    f" already exists.\n(Leave destinationName as None"
 5194                    f" to use an automatic name.)"
 5195                ),
 5196                DecisionCollisionWarning
 5197            )
 5198
 5199        # Create the new unexplored decision and add the edge
 5200        if destinationName is None:
 5201            toName = '_u.' + str(self.unknownCount)
 5202        else:
 5203            toName = destinationName
 5204        self.unknownCount += 1
 5205        newID = self.addDecision(toName, domain=toDomain)
 5206        self.addTransition(
 5207            fromID,
 5208            name,
 5209            newID,
 5210            tags=tags,
 5211            annotations=annotations
 5212        )
 5213        self.setTransitionRequirement(fromID, name, requires)
 5214        if consequence is not None:
 5215            self.setConsequence(fromID, name, consequence)
 5216
 5217        # Add it to a zone if requested
 5218        if (
 5219            placeInZone == base.DefaultZone
 5220        and toDomain == self.domainFor(fromID)
 5221        ):
 5222            # Add to each parent of the from decision
 5223            for parent in self.zoneParents(fromID):
 5224                self.addDecisionToZone(newID, parent)
 5225        elif placeInZone is not None:
 5226            # Otherwise add it to one specific zone, creating that zone
 5227            # at level 0 if necessary
 5228            assert isinstance(placeInZone, base.Zone)
 5229            if self.getZoneInfo(placeInZone) is None:
 5230                self.createZone(placeInZone, 0)
 5231                # Add new zone to each grandparent of the from decision
 5232                for parent in self.zoneParents(fromID):
 5233                    for grandparent in self.zoneParents(parent):
 5234                        self.addZoneToZone(placeInZone, grandparent)
 5235            self.addDecisionToZone(newID, placeInZone)
 5236
 5237        # Create the reciprocal edge
 5238        if reciprocal is not None:
 5239            self.addTransition(
 5240                newID,
 5241                reciprocal,
 5242                fromID,
 5243                tags=revTags,
 5244                annotations=revAnnotations
 5245            )
 5246            self.setTransitionRequirement(newID, reciprocal, revRequires)
 5247            if revConsequece is not None:
 5248                self.setConsequence(newID, reciprocal, revConsequece)
 5249            # Set as a reciprocal
 5250            self.setReciprocal(fromID, name, reciprocal)
 5251
 5252        # Tag the destination as 'unconfirmed'
 5253        self.tagDecision(newID, 'unconfirmed')
 5254
 5255        # Return ID of new destination
 5256        return newID
 5257
 5258    def retargetTransition(
 5259        self,
 5260        fromDecision: base.AnyDecisionSpecifier,
 5261        transition: base.Transition,
 5262        newDestination: base.AnyDecisionSpecifier,
 5263        swapReciprocal=True,
 5264        errorOnNameColision=True
 5265    ) -> Optional[base.Transition]:
 5266        """
 5267        Given a particular decision and a transition at that decision,
 5268        changes that transition so that it goes to the specified new
 5269        destination instead of wherever it was connected to before. If
 5270        the new destination is the same as the old one, no changes are
 5271        made.
 5272
 5273        If `swapReciprocal` is set to True (the default) then any
 5274        reciprocal edge at the old destination will be deleted, and a
 5275        new reciprocal edge from the new destination with equivalent
 5276        properties to the original reciprocal will be created, pointing
 5277        to the origin of the specified transition. If `swapReciprocal`
 5278        is set to False, then the reciprocal relationship with any old
 5279        reciprocal edge will be removed, but the old reciprocal edge
 5280        will not be changed.
 5281
 5282        Note that if `errorOnNameColision` is True (the default), then
 5283        if the reciprocal transition has the same name as a transition
 5284        which already exists at the new destination node, a
 5285        `TransitionCollisionError` will be thrown. However, if it is set
 5286        to False, the reciprocal transition will be renamed with a suffix
 5287        to avoid any possible name collisions. Either way, the name of
 5288        the reciprocal transition (possibly just changed) will be
 5289        returned, or None if there was no reciprocal transition.
 5290
 5291        ## Example
 5292
 5293        >>> g = DecisionGraph()
 5294        >>> for fr, to, nm in [
 5295        ...     ('A', 'B', 'up'),
 5296        ...     ('A', 'B', 'up2'),
 5297        ...     ('B', 'A', 'down'),
 5298        ...     ('B', 'B', 'self'),
 5299        ...     ('B', 'C', 'next'),
 5300        ...     ('C', 'B', 'prev')
 5301        ... ]:
 5302        ...     if g.getDecision(fr) is None:
 5303        ...        g.addDecision(fr)
 5304        ...     if g.getDecision(to) is None:
 5305        ...         g.addDecision(to)
 5306        ...     g.addTransition(fr, nm, to)
 5307        0
 5308        1
 5309        2
 5310        >>> g.setReciprocal('A', 'up', 'down')
 5311        >>> g.setReciprocal('B', 'next', 'prev')
 5312        >>> g.destination('A', 'up')
 5313        1
 5314        >>> g.destination('B', 'down')
 5315        0
 5316        >>> g.retargetTransition('A', 'up', 'C')
 5317        'down'
 5318        >>> g.destination('A', 'up')
 5319        2
 5320        >>> g.getDestination('B', 'down') is None
 5321        True
 5322        >>> g.destination('C', 'down')
 5323        0
 5324        >>> g.addTransition('A', 'next', 'B')
 5325        >>> g.addTransition('B', 'prev', 'A')
 5326        >>> g.setReciprocal('A', 'next', 'prev')
 5327        >>> # Can't swap a reciprocal in a way that would collide names
 5328        >>> g.getReciprocal('C', 'prev')
 5329        'next'
 5330        >>> g.retargetTransition('C', 'prev', 'A')
 5331        Traceback (most recent call last):
 5332        ...
 5333        exploration.core.TransitionCollisionError...
 5334        >>> g.retargetTransition('C', 'prev', 'A', swapReciprocal=False)
 5335        'next'
 5336        >>> g.destination('C', 'prev')
 5337        0
 5338        >>> g.destination('A', 'next') # not changed
 5339        1
 5340        >>> # Reciprocal relationship is severed:
 5341        >>> g.getReciprocal('C', 'prev') is None
 5342        True
 5343        >>> g.getReciprocal('B', 'next') is None
 5344        True
 5345        >>> # Swap back so we can do another demo
 5346        >>> g.retargetTransition('C', 'prev', 'B', swapReciprocal=False)
 5347        >>> # Note return value was None here because there was no reciprocal
 5348        >>> g.setReciprocal('C', 'prev', 'next')
 5349        >>> # Swap reciprocal by renaming it
 5350        >>> g.retargetTransition('C', 'prev', 'A', errorOnNameColision=False)
 5351        'next.1'
 5352        >>> g.getReciprocal('C', 'prev')
 5353        'next.1'
 5354        >>> g.destination('C', 'prev')
 5355        0
 5356        >>> g.destination('A', 'next.1')
 5357        2
 5358        >>> g.destination('A', 'next')
 5359        1
 5360        >>> # Note names are the same but these are from different nodes
 5361        >>> g.getReciprocal('A', 'next')
 5362        'prev'
 5363        >>> g.getReciprocal('A', 'next.1')
 5364        'prev'
 5365        """
 5366        fromID = self.resolveDecision(fromDecision)
 5367        newDestID = self.resolveDecision(newDestination)
 5368
 5369        # Figure out the old destination of the transition we're swapping
 5370        oldDestID = self.destination(fromID, transition)
 5371        reciprocal = self.getReciprocal(fromID, transition)
 5372
 5373        # If thew new destination is the same, we don't do anything!
 5374        if oldDestID == newDestID:
 5375            return reciprocal
 5376
 5377        # First figure out reciprocal business so we can error out
 5378        # without making changes if we need to
 5379        if swapReciprocal and reciprocal is not None:
 5380            reciprocal = self.rebaseTransition(
 5381                oldDestID,
 5382                reciprocal,
 5383                newDestID,
 5384                swapReciprocal=False,
 5385                errorOnNameColision=errorOnNameColision
 5386            )
 5387
 5388        # Handle the forward transition...
 5389        # Find the transition properties
 5390        tProps = self.getTransitionProperties(fromID, transition)
 5391
 5392        # Delete the edge
 5393        self.removeEdgeByKey(fromID, transition)
 5394
 5395        # Add the new edge
 5396        self.addTransition(fromID, transition, newDestID)
 5397
 5398        # Reapply the transition properties
 5399        self.setTransitionProperties(fromID, transition, **tProps)
 5400
 5401        # Handle the reciprocal transition if there is one...
 5402        if reciprocal is not None:
 5403            if not swapReciprocal:
 5404                # Then sever the relationship, but only if that edge
 5405                # still exists (we might be in the middle of a rebase)
 5406                check = self.getDestination(oldDestID, reciprocal)
 5407                if check is not None:
 5408                    self.setReciprocal(
 5409                        oldDestID,
 5410                        reciprocal,
 5411                        None,
 5412                        setBoth=False # Other transition was deleted already
 5413                    )
 5414            else:
 5415                # Establish new reciprocal relationship
 5416                self.setReciprocal(
 5417                    fromID,
 5418                    transition,
 5419                    reciprocal
 5420                )
 5421
 5422        return reciprocal
 5423
 5424    def rebaseTransition(
 5425        self,
 5426        fromDecision: base.AnyDecisionSpecifier,
 5427        transition: base.Transition,
 5428        newBase: base.AnyDecisionSpecifier,
 5429        swapReciprocal=True,
 5430        errorOnNameColision=True
 5431    ) -> base.Transition:
 5432        """
 5433        Given a particular destination and a transition at that
 5434        destination, changes that transition's origin to a new base
 5435        decision. If the new source is the same as the old one, no
 5436        changes are made.
 5437
 5438        If `swapReciprocal` is set to True (the default) then any
 5439        reciprocal edge at the destination will be retargeted to point
 5440        to the new source so that it can remain a reciprocal. If
 5441        `swapReciprocal` is set to False, then the reciprocal
 5442        relationship with any old reciprocal edge will be removed, but
 5443        the old reciprocal edge will not be otherwise changed.
 5444
 5445        Note that if `errorOnNameColision` is True (the default), then
 5446        if the transition has the same name as a transition which
 5447        already exists at the new source node, a
 5448        `TransitionCollisionError` will be raised. However, if it is set
 5449        to False, the transition will be renamed with a suffix to avoid
 5450        any possible name collisions. Either way, the (possibly new) name
 5451        of the transition that was rebased will be returned.
 5452
 5453        ## Example
 5454
 5455        >>> g = DecisionGraph()
 5456        >>> for fr, to, nm in [
 5457        ...     ('A', 'B', 'up'),
 5458        ...     ('A', 'B', 'up2'),
 5459        ...     ('B', 'A', 'down'),
 5460        ...     ('B', 'B', 'self'),
 5461        ...     ('B', 'C', 'next'),
 5462        ...     ('C', 'B', 'prev')
 5463        ... ]:
 5464        ...     if g.getDecision(fr) is None:
 5465        ...        g.addDecision(fr)
 5466        ...     if g.getDecision(to) is None:
 5467        ...         g.addDecision(to)
 5468        ...     g.addTransition(fr, nm, to)
 5469        0
 5470        1
 5471        2
 5472        >>> g.setReciprocal('A', 'up', 'down')
 5473        >>> g.setReciprocal('B', 'next', 'prev')
 5474        >>> g.destination('A', 'up')
 5475        1
 5476        >>> g.destination('B', 'down')
 5477        0
 5478        >>> g.rebaseTransition('B', 'down', 'C')
 5479        'down'
 5480        >>> g.destination('A', 'up')
 5481        2
 5482        >>> g.getDestination('B', 'down') is None
 5483        True
 5484        >>> g.destination('C', 'down')
 5485        0
 5486        >>> g.addTransition('A', 'next', 'B')
 5487        >>> g.addTransition('B', 'prev', 'A')
 5488        >>> g.setReciprocal('A', 'next', 'prev')
 5489        >>> # Can't rebase in a way that would collide names
 5490        >>> g.rebaseTransition('B', 'next', 'A')
 5491        Traceback (most recent call last):
 5492        ...
 5493        exploration.core.TransitionCollisionError...
 5494        >>> g.rebaseTransition('B', 'next', 'A', errorOnNameColision=False)
 5495        'next.1'
 5496        >>> g.destination('C', 'prev')
 5497        0
 5498        >>> g.destination('A', 'next') # not changed
 5499        1
 5500        >>> # Collision is avoided by renaming
 5501        >>> g.destination('A', 'next.1')
 5502        2
 5503        >>> # Swap without reciprocal
 5504        >>> g.getReciprocal('A', 'next.1')
 5505        'prev'
 5506        >>> g.getReciprocal('C', 'prev')
 5507        'next.1'
 5508        >>> g.rebaseTransition('A', 'next.1', 'B', swapReciprocal=False)
 5509        'next.1'
 5510        >>> g.getReciprocal('C', 'prev') is None
 5511        True
 5512        >>> g.destination('C', 'prev')
 5513        0
 5514        >>> g.getDestination('A', 'next.1') is None
 5515        True
 5516        >>> g.destination('A', 'next')
 5517        1
 5518        >>> g.destination('B', 'next.1')
 5519        2
 5520        >>> g.getReciprocal('B', 'next.1') is None
 5521        True
 5522        >>> # Rebase in a way that creates a self-edge
 5523        >>> g.rebaseTransition('A', 'next', 'B')
 5524        'next'
 5525        >>> g.getDestination('A', 'next') is None
 5526        True
 5527        >>> g.destination('B', 'next')
 5528        1
 5529        >>> g.destination('B', 'prev') # swapped as a reciprocal
 5530        1
 5531        >>> g.getReciprocal('B', 'next') # still reciprocals
 5532        'prev'
 5533        >>> g.getReciprocal('B', 'prev')
 5534        'next'
 5535        >>> # And rebasing of a self-edge also works
 5536        >>> g.rebaseTransition('B', 'prev', 'A')
 5537        'prev'
 5538        >>> g.destination('A', 'prev')
 5539        1
 5540        >>> g.destination('B', 'next')
 5541        0
 5542        >>> g.getReciprocal('B', 'next') # still reciprocals
 5543        'prev'
 5544        >>> g.getReciprocal('A', 'prev')
 5545        'next'
 5546        >>> # We've effectively reversed this edge/reciprocal pair
 5547        >>> # by rebasing twice
 5548        """
 5549        fromID = self.resolveDecision(fromDecision)
 5550        newBaseID = self.resolveDecision(newBase)
 5551
 5552        # If thew new base is the same, we don't do anything!
 5553        if newBaseID == fromID:
 5554            return transition
 5555
 5556        # First figure out reciprocal business so we can swap it later
 5557        # without making changes if we need to
 5558        destination = self.destination(fromID, transition)
 5559        reciprocal = self.getReciprocal(fromID, transition)
 5560        # Check for an already-deleted reciprocal
 5561        if (
 5562            reciprocal is not None
 5563        and self.getDestination(destination, reciprocal) is None
 5564        ):
 5565            reciprocal = None
 5566
 5567        # Handle the base swap...
 5568        # Find the transition properties
 5569        tProps = self.getTransitionProperties(fromID, transition)
 5570
 5571        # Check for a collision
 5572        targetDestinations = self.destinationsFrom(newBaseID)
 5573        if transition in targetDestinations:
 5574            if errorOnNameColision:
 5575                raise TransitionCollisionError(
 5576                    f"Cannot rebase transition {transition!r} from"
 5577                    f" {self.identityOf(fromDecision)}: it would be a"
 5578                    f" duplicate transition name at the new base"
 5579                    f" decision {self.identityOf(newBase)}."
 5580                )
 5581            else:
 5582                # Figure out a good fresh name
 5583                newName = utils.uniqueName(
 5584                    transition,
 5585                    targetDestinations
 5586                )
 5587        else:
 5588            newName = transition
 5589
 5590        # Delete the edge
 5591        self.removeEdgeByKey(fromID, transition)
 5592
 5593        # Add the new edge
 5594        self.addTransition(newBaseID, newName, destination)
 5595
 5596        # Reapply the transition properties
 5597        self.setTransitionProperties(newBaseID, newName, **tProps)
 5598
 5599        # Handle the reciprocal transition if there is one...
 5600        if reciprocal is not None:
 5601            if not swapReciprocal:
 5602                # Then sever the relationship
 5603                self.setReciprocal(
 5604                    destination,
 5605                    reciprocal,
 5606                    None,
 5607                    setBoth=False # Other transition was deleted already
 5608                )
 5609            else:
 5610                # Otherwise swap the reciprocal edge
 5611                self.retargetTransition(
 5612                    destination,
 5613                    reciprocal,
 5614                    newBaseID,
 5615                    swapReciprocal=False
 5616                )
 5617
 5618                # And establish a new reciprocal relationship
 5619                self.setReciprocal(
 5620                    newBaseID,
 5621                    newName,
 5622                    reciprocal
 5623                )
 5624
 5625        # Return the new name in case it was changed
 5626        return newName
 5627
 5628    # TODO: zone merging!
 5629
 5630    # TODO: Double-check that exploration vars get updated when this is
 5631    # called!
 5632    def mergeDecisions(
 5633        self,
 5634        merge: base.AnyDecisionSpecifier,
 5635        mergeInto: base.AnyDecisionSpecifier,
 5636        errorOnNameColision=True
 5637    ) -> Dict[base.Transition, base.Transition]:
 5638        """
 5639        Merges two decisions, deleting the first after transferring all
 5640        of its incoming and outgoing edges to target the second one,
 5641        whose name is retained. The second decision will be added to any
 5642        zones that the first decision was a member of. If either decision
 5643        does not exist, a `MissingDecisionError` will be raised. If
 5644        `merge` and `mergeInto` are the same, then nothing will be
 5645        changed.
 5646
 5647        Unless `errorOnNameColision` is set to False, a
 5648        `TransitionCollisionError` will be raised if the two decisions
 5649        have outgoing transitions with the same name. If
 5650        `errorOnNameColision` is set to False, then such edges will be
 5651        renamed using a suffix to avoid name collisions, with edges
 5652        connected to the second decision retaining their original names
 5653        and edges that were connected to the first decision getting
 5654        renamed.
 5655
 5656        Any mechanisms located at the first decision will be moved to the
 5657        merged decision.
 5658
 5659        The tags and annotations of the merged decision are added to the
 5660        tags and annotations of the merge target. If there are shared
 5661        tags, the values from the merge target will override those of
 5662        the merged decision. If this is undesired behavior, clear/edit
 5663        the tags/annotations of the merged decision before the merge.
 5664
 5665        The 'unconfirmed' tag is treated specially: if both decisions have
 5666        it it will be retained, but otherwise it will be dropped even if
 5667        one of the situations had it before.
 5668
 5669        The domain of the second decision is retained.
 5670
 5671        Returns a dictionary mapping each original transition name to
 5672        its new name in cases where transitions get renamed; this will
 5673        be empty when no re-naming occurs, including when
 5674        `errorOnNameColision` is True. If there were any transitions
 5675        connecting the nodes that were merged, these become self-edges
 5676        of the merged node (and may be renamed if necessary).
 5677        Note that all renamed transitions were originally based on the
 5678        first (merged) node, since transitions of the second (merge
 5679        target) node are not renamed.
 5680
 5681        ## Example
 5682
 5683        >>> g = DecisionGraph()
 5684        >>> for fr, to, nm in [
 5685        ...     ('A', 'B', 'up'),
 5686        ...     ('A', 'B', 'up2'),
 5687        ...     ('B', 'A', 'down'),
 5688        ...     ('B', 'B', 'self'),
 5689        ...     ('B', 'C', 'next'),
 5690        ...     ('C', 'B', 'prev'),
 5691        ...     ('A', 'C', 'right')
 5692        ... ]:
 5693        ...     if g.getDecision(fr) is None:
 5694        ...        g.addDecision(fr)
 5695        ...     if g.getDecision(to) is None:
 5696        ...         g.addDecision(to)
 5697        ...     g.addTransition(fr, nm, to)
 5698        0
 5699        1
 5700        2
 5701        >>> g.getDestination('A', 'up')
 5702        1
 5703        >>> g.getDestination('B', 'down')
 5704        0
 5705        >>> sorted(g)
 5706        [0, 1, 2]
 5707        >>> g.setReciprocal('A', 'up', 'down')
 5708        >>> g.setReciprocal('B', 'next', 'prev')
 5709        >>> g.mergeDecisions('C', 'B')
 5710        {}
 5711        >>> g.destinationsFrom('A')
 5712        {'up': 1, 'up2': 1, 'right': 1}
 5713        >>> g.destinationsFrom('B')
 5714        {'down': 0, 'self': 1, 'prev': 1, 'next': 1}
 5715        >>> 'C' in g
 5716        False
 5717        >>> g.mergeDecisions('A', 'A') # does nothing
 5718        {}
 5719        >>> # Can't merge non-existent decision
 5720        >>> g.mergeDecisions('A', 'Z')
 5721        Traceback (most recent call last):
 5722        ...
 5723        exploration.core.MissingDecisionError...
 5724        >>> g.mergeDecisions('Z', 'A')
 5725        Traceback (most recent call last):
 5726        ...
 5727        exploration.core.MissingDecisionError...
 5728        >>> # Can't merge decisions w/ shared edge names
 5729        >>> g.addDecision('D')
 5730        3
 5731        >>> g.addTransition('D', 'next', 'A')
 5732        >>> g.addTransition('A', 'prev', 'D')
 5733        >>> g.setReciprocal('D', 'next', 'prev')
 5734        >>> g.mergeDecisions('D', 'B') # both have a 'next' transition
 5735        Traceback (most recent call last):
 5736        ...
 5737        exploration.core.TransitionCollisionError...
 5738        >>> # Auto-rename colliding edges
 5739        >>> g.mergeDecisions('D', 'B', errorOnNameColision=False)
 5740        {'next': 'next.1'}
 5741        >>> g.destination('B', 'next') # merge target unchanged
 5742        1
 5743        >>> g.destination('B', 'next.1') # merged decision name changed
 5744        0
 5745        >>> g.destination('B', 'prev') # name unchanged (no collision)
 5746        1
 5747        >>> g.getReciprocal('B', 'next') # unchanged (from B)
 5748        'prev'
 5749        >>> g.getReciprocal('B', 'next.1') # from A
 5750        'prev'
 5751        >>> g.getReciprocal('A', 'prev') # from B
 5752        'next.1'
 5753
 5754        ## Folding four nodes into a 2-node loop
 5755
 5756        >>> g = DecisionGraph()
 5757        >>> g.addDecision('X')
 5758        0
 5759        >>> g.addDecision('Y')
 5760        1
 5761        >>> g.addTransition('X', 'next', 'Y', 'prev')
 5762        >>> g.addDecision('preX')
 5763        2
 5764        >>> g.addDecision('postY')
 5765        3
 5766        >>> g.addTransition('preX', 'next', 'X', 'prev')
 5767        >>> g.addTransition('Y', 'next', 'postY', 'prev')
 5768        >>> g.mergeDecisions('preX', 'Y', errorOnNameColision=False)
 5769        {'next': 'next.1'}
 5770        >>> g.destinationsFrom('X')
 5771        {'next': 1, 'prev': 1}
 5772        >>> g.destinationsFrom('Y')
 5773        {'prev': 0, 'next': 3, 'next.1': 0}
 5774        >>> 2 in g
 5775        False
 5776        >>> g.destinationsFrom('postY')
 5777        {'prev': 1}
 5778        >>> g.mergeDecisions('postY', 'X', errorOnNameColision=False)
 5779        {'prev': 'prev.1'}
 5780        >>> g.destinationsFrom('X')
 5781        {'next': 1, 'prev': 1, 'prev.1': 1}
 5782        >>> g.destinationsFrom('Y') # order 'cause of 'next' re-target
 5783        {'prev': 0, 'next.1': 0, 'next': 0}
 5784        >>> 2 in g
 5785        False
 5786        >>> 3 in g
 5787        False
 5788        >>> # Reciprocals are tangled...
 5789        >>> g.getReciprocal(0, 'prev')
 5790        'next.1'
 5791        >>> g.getReciprocal(0, 'prev.1')
 5792        'next'
 5793        >>> g.getReciprocal(1, 'next')
 5794        'prev.1'
 5795        >>> g.getReciprocal(1, 'next.1')
 5796        'prev'
 5797        >>> # Note: one merge cannot handle both extra transitions
 5798        >>> # because their reciprocals are crossed (e.g., prev.1 <-> next)
 5799        >>> # (It would merge both edges but the result would retain
 5800        >>> # 'next.1' instead of retaining 'next'.)
 5801        >>> g.mergeTransitions('X', 'prev.1', 'prev', mergeReciprocal=False)
 5802        >>> g.mergeTransitions('Y', 'next.1', 'next', mergeReciprocal=True)
 5803        >>> g.destinationsFrom('X')
 5804        {'next': 1, 'prev': 1}
 5805        >>> g.destinationsFrom('Y')
 5806        {'prev': 0, 'next': 0}
 5807        >>> # Reciprocals were salvaged in second merger
 5808        >>> g.getReciprocal('X', 'prev')
 5809        'next'
 5810        >>> g.getReciprocal('Y', 'next')
 5811        'prev'
 5812
 5813        ## Merging with tags/requirements/annotations/consequences
 5814
 5815        >>> g = DecisionGraph()
 5816        >>> g.addDecision('X')
 5817        0
 5818        >>> g.addDecision('Y')
 5819        1
 5820        >>> g.addDecision('Z')
 5821        2
 5822        >>> g.addTransition('X', 'next', 'Y', 'prev')
 5823        >>> g.addTransition('X', 'down', 'Z', 'up')
 5824        >>> g.tagDecision('X', 'tag0', 1)
 5825        >>> g.tagDecision('Y', 'tag1', 10)
 5826        >>> g.tagDecision('Y', 'unconfirmed')
 5827        >>> g.tagDecision('Z', 'tag1', 20)
 5828        >>> g.tagDecision('Z', 'tag2', 30)
 5829        >>> g.tagTransition('X', 'next', 'ttag1', 11)
 5830        >>> g.tagTransition('Y', 'prev', 'ttag2', 22)
 5831        >>> g.tagTransition('X', 'down', 'ttag3', 33)
 5832        >>> g.tagTransition('Z', 'up', 'ttag4', 44)
 5833        >>> g.annotateDecision('Y', 'annotation 1')
 5834        >>> g.annotateDecision('Z', 'annotation 2')
 5835        >>> g.annotateDecision('Z', 'annotation 3')
 5836        >>> g.annotateTransition('Y', 'prev', 'trans annotation 1')
 5837        >>> g.annotateTransition('Y', 'prev', 'trans annotation 2')
 5838        >>> g.annotateTransition('Z', 'up', 'trans annotation 3')
 5839        >>> g.setTransitionRequirement(
 5840        ...     'X',
 5841        ...     'next',
 5842        ...     base.ReqCapability('power')
 5843        ... )
 5844        >>> g.setTransitionRequirement(
 5845        ...     'Y',
 5846        ...     'prev',
 5847        ...     base.ReqTokens('token', 1)
 5848        ... )
 5849        >>> g.setTransitionRequirement(
 5850        ...     'X',
 5851        ...     'down',
 5852        ...     base.ReqCapability('power2')
 5853        ... )
 5854        >>> g.setTransitionRequirement(
 5855        ...     'Z',
 5856        ...     'up',
 5857        ...     base.ReqTokens('token2', 2)
 5858        ... )
 5859        >>> g.setConsequence(
 5860        ...     'Y',
 5861        ...     'prev',
 5862        ...     [base.effect(gain="power2")]
 5863        ... )
 5864        >>> g.mergeDecisions('Y', 'Z')
 5865        {}
 5866        >>> g.destination('X', 'next')
 5867        2
 5868        >>> g.destination('X', 'down')
 5869        2
 5870        >>> g.destination('Z', 'prev')
 5871        0
 5872        >>> g.destination('Z', 'up')
 5873        0
 5874        >>> g.decisionTags('X')
 5875        {'tag0': 1}
 5876        >>> g.decisionTags('Z')  # note that 'unconfirmed' is removed
 5877        {'tag1': 20, 'tag2': 30}
 5878        >>> g.transitionTags('X', 'next')
 5879        {'ttag1': 11}
 5880        >>> g.transitionTags('X', 'down')
 5881        {'ttag3': 33}
 5882        >>> g.transitionTags('Z', 'prev')
 5883        {'ttag2': 22}
 5884        >>> g.transitionTags('Z', 'up')
 5885        {'ttag4': 44}
 5886        >>> g.decisionAnnotations('Z')
 5887        ['annotation 2', 'annotation 3', 'annotation 1']
 5888        >>> g.transitionAnnotations('Z', 'prev')
 5889        ['trans annotation 1', 'trans annotation 2']
 5890        >>> g.transitionAnnotations('Z', 'up')
 5891        ['trans annotation 3']
 5892        >>> g.getTransitionRequirement('X', 'next')
 5893        ReqCapability('power')
 5894        >>> g.getTransitionRequirement('Z', 'prev')
 5895        ReqTokens('token', 1)
 5896        >>> g.getTransitionRequirement('X', 'down')
 5897        ReqCapability('power2')
 5898        >>> g.getTransitionRequirement('Z', 'up')
 5899        ReqTokens('token2', 2)
 5900        >>> g.getConsequence('Z', 'prev') == [
 5901        ...     {
 5902        ...         'type': 'gain',
 5903        ...         'applyTo': 'active',
 5904        ...         'value': 'power2',
 5905        ...         'charges': None,
 5906        ...         'delay': None,
 5907        ...         'hidden': False
 5908        ...     }
 5909        ... ]
 5910        True
 5911
 5912        ## Merging into node without tags
 5913
 5914        >>> g = DecisionGraph()
 5915        >>> g.addDecision('X')
 5916        0
 5917        >>> g.addDecision('Y')
 5918        1
 5919        >>> g.tagDecision('Y', 'unconfirmed')  # special handling
 5920        >>> g.tagDecision('Y', 'tag', 'value')
 5921        >>> g.mergeDecisions('Y', 'X')
 5922        {}
 5923        >>> g.decisionTags('X')
 5924        {'tag': 'value'}
 5925        >>> 0 in g  # Second argument remains
 5926        True
 5927        >>> 1 in g  # First argument is deleted
 5928        False
 5929        """
 5930        # Resolve IDs
 5931        mergeID = self.resolveDecision(merge)
 5932        mergeIntoID = self.resolveDecision(mergeInto)
 5933
 5934        # Create our result as an empty dictionary
 5935        result: Dict[base.Transition, base.Transition] = {}
 5936
 5937        # Short-circuit if the two decisions are the same
 5938        if mergeID == mergeIntoID:
 5939            return result
 5940
 5941        # MissingDecisionErrors from here if either doesn't exist
 5942        allNewOutgoing = set(self.destinationsFrom(mergeID))
 5943        allOldOutgoing = set(self.destinationsFrom(mergeIntoID))
 5944        # Find colliding transition names
 5945        collisions = allNewOutgoing & allOldOutgoing
 5946        if len(collisions) > 0 and errorOnNameColision:
 5947            raise TransitionCollisionError(
 5948                f"Cannot merge decision {self.identityOf(merge)} into"
 5949                f" decision {self.identityOf(mergeInto)}: the decisions"
 5950                f" share {len(collisions)} transition names:"
 5951                f" {collisions}\n(Note that errorOnNameColision was set"
 5952                f" to True, set it to False to allow the operation by"
 5953                f" renaming half of those transitions.)"
 5954            )
 5955
 5956        # Record zones that will have to change after the merge
 5957        zoneParents = self.zoneParents(mergeID)
 5958
 5959        # First, swap all incoming edges, along with their reciprocals
 5960        # This will include self-edges, which will be retargeted and
 5961        # whose reciprocals will be rebased in the process, leading to
 5962        # the possibility of a missing edge during the loop
 5963        for source, incoming in self.allEdgesTo(mergeID):
 5964            # Skip this edge if it was already swapped away because it's
 5965            # a self-loop with a reciprocal whose reciprocal was
 5966            # processed earlier in the loop
 5967            if incoming not in self.destinationsFrom(source):
 5968                continue
 5969
 5970            # Find corresponding outgoing edge
 5971            outgoing = self.getReciprocal(source, incoming)
 5972
 5973            # Swap both edges to new destination
 5974            newOutgoing = self.retargetTransition(
 5975                source,
 5976                incoming,
 5977                mergeIntoID,
 5978                swapReciprocal=True,
 5979                errorOnNameColision=False # collisions were detected above
 5980            )
 5981            # Add to our result if the name of the reciprocal was
 5982            # changed
 5983            if (
 5984                outgoing is not None
 5985            and newOutgoing is not None
 5986            and outgoing != newOutgoing
 5987            ):
 5988                result[outgoing] = newOutgoing
 5989
 5990        # Next, swap any remaining outgoing edges (which didn't have
 5991        # reciprocals, or they'd already be swapped, unless they were
 5992        # self-edges previously). Note that in this loop, there can't be
 5993        # any self-edges remaining, although there might be connections
 5994        # between the merging nodes that need to become self-edges
 5995        # because they used to be a self-edge that was half-retargeted
 5996        # by the previous loop.
 5997        # Note: a copy is used here to avoid iterating over a changing
 5998        # dictionary
 5999        for stillOutgoing in copy.copy(self.destinationsFrom(mergeID)):
 6000            newOutgoing = self.rebaseTransition(
 6001                mergeID,
 6002                stillOutgoing,
 6003                mergeIntoID,
 6004                swapReciprocal=True,
 6005                errorOnNameColision=False # collisions were detected above
 6006            )
 6007            if stillOutgoing != newOutgoing:
 6008                result[stillOutgoing] = newOutgoing
 6009
 6010        # At this point, there shouldn't be any remaining incoming or
 6011        # outgoing edges!
 6012        assert self.degree(mergeID) == 0
 6013
 6014        # Merge tags & annotations
 6015        # Note that these operations affect the underlying graph
 6016        destTags = self.decisionTags(mergeIntoID)
 6017        destUnvisited = 'unconfirmed' in destTags
 6018        sourceTags = self.decisionTags(mergeID)
 6019        sourceUnvisited = 'unconfirmed' in sourceTags
 6020        # Copy over only new tags, leaving existing tags alone
 6021        for key in sourceTags:
 6022            if key not in destTags:
 6023                destTags[key] = sourceTags[key]
 6024
 6025        if int(destUnvisited) + int(sourceUnvisited) == 1:
 6026            del destTags['unconfirmed']
 6027
 6028        self.decisionAnnotations(mergeIntoID).extend(
 6029            self.decisionAnnotations(mergeID)
 6030        )
 6031
 6032        # Transfer zones
 6033        for zone in zoneParents:
 6034            self.addDecisionToZone(mergeIntoID, zone)
 6035
 6036        # Delete the old node
 6037        self.removeDecision(mergeID)
 6038
 6039        return result
 6040
 6041    def removeDecision(self, decision: base.AnyDecisionSpecifier) -> None:
 6042        """
 6043        Deletes the specified decision from the graph, updating
 6044        attendant structures like zones. Note that the ID of the deleted
 6045        node will NOT be reused, unless it's specifically provided to
 6046        `addIdentifiedDecision`.
 6047
 6048        For example:
 6049
 6050        >>> dg = DecisionGraph()
 6051        >>> dg.addDecision('A')
 6052        0
 6053        >>> dg.addDecision('B')
 6054        1
 6055        >>> list(dg)
 6056        [0, 1]
 6057        >>> 1 in dg
 6058        True
 6059        >>> 'B' in dg.nameLookup
 6060        True
 6061        >>> dg.removeDecision('B')
 6062        >>> 1 in dg
 6063        False
 6064        >>> list(dg)
 6065        [0]
 6066        >>> 'B' in dg.nameLookup
 6067        False
 6068        >>> dg.addDecision('C')  # doesn't re-use ID
 6069        2
 6070        """
 6071        dID = self.resolveDecision(decision)
 6072
 6073        # Remove the target from all zones:
 6074        for zone in self.zones:
 6075            self.removeDecisionFromZone(dID, zone)
 6076
 6077        # Remove the node but record the current name
 6078        name = self.nodes[dID]['name']
 6079        self.remove_node(dID)
 6080
 6081        # Clean up the nameLookup entry
 6082        luInfo = self.nameLookup[name]
 6083        luInfo.remove(dID)
 6084        if len(luInfo) == 0:
 6085            self.nameLookup.pop(name)
 6086
 6087        # TODO: Clean up edges?
 6088
 6089    def renameDecision(
 6090        self,
 6091        decision: base.AnyDecisionSpecifier,
 6092        newName: base.DecisionName
 6093    ):
 6094        """
 6095        Renames a decision. The decision retains its old ID.
 6096
 6097        Generates a `DecisionCollisionWarning` if a decision using the new
 6098        name already exists and `WARN_OF_NAME_COLLISIONS` is enabled.
 6099
 6100        Example:
 6101
 6102        >>> g = DecisionGraph()
 6103        >>> g.addDecision('one')
 6104        0
 6105        >>> g.addDecision('three')
 6106        1
 6107        >>> g.addTransition('one', '>', 'three')
 6108        >>> g.addTransition('three', '<', 'one')
 6109        >>> g.tagDecision('three', 'hi')
 6110        >>> g.annotateDecision('three', 'note')
 6111        >>> g.destination('one', '>')
 6112        1
 6113        >>> g.destination('three', '<')
 6114        0
 6115        >>> g.renameDecision('three', 'two')
 6116        >>> g.resolveDecision('one')
 6117        0
 6118        >>> g.resolveDecision('two')
 6119        1
 6120        >>> g.resolveDecision('three')
 6121        Traceback (most recent call last):
 6122        ...
 6123        exploration.core.MissingDecisionError...
 6124        >>> g.destination('one', '>')
 6125        1
 6126        >>> g.nameFor(1)
 6127        'two'
 6128        >>> g.getDecision('three') is None
 6129        True
 6130        >>> g.destination('two', '<')
 6131        0
 6132        >>> g.decisionTags('two')
 6133        {'hi': 1}
 6134        >>> g.decisionAnnotations('two')
 6135        ['note']
 6136        """
 6137        dID = self.resolveDecision(decision)
 6138
 6139        if newName in self.nameLookup and WARN_OF_NAME_COLLISIONS:
 6140            warnings.warn(
 6141                (
 6142                    f"Can't rename {self.identityOf(decision)} as"
 6143                    f" {newName!r} because a decision with that name"
 6144                    f" already exists."
 6145                ),
 6146                DecisionCollisionWarning
 6147            )
 6148
 6149        # Update name in node
 6150        oldName = self.nodes[dID]['name']
 6151        self.nodes[dID]['name'] = newName
 6152
 6153        # Update nameLookup entries
 6154        oldNL = self.nameLookup[oldName]
 6155        oldNL.remove(dID)
 6156        if len(oldNL) == 0:
 6157            self.nameLookup.pop(oldName)
 6158        self.nameLookup.setdefault(newName, []).append(dID)
 6159
 6160    def renameTransition(
 6161        self,
 6162        fromDecision: base.AnyDecisionSpecifier,
 6163        oldName: base.Transition,
 6164        newName: base.Transition
 6165    ):
 6166        """
 6167        Renames a transition. The transition retains its reciprocal
 6168        association if it had one. The new name must not already exist as
 6169        a transition name at the specified decision (see
 6170        `mergeTransitions` for an alternative), or a
 6171        `TransitionCollisionError` will be raised. Renaming to the same
 6172        name does nothing.
 6173
 6174        Example:
 6175
 6176        >>> g = DecisionGraph()
 6177        >>> g.addDecision('A')
 6178        0
 6179        >>> g.addDecision('B')
 6180        1
 6181        >>> g.addTransition('A', 'right', 'B', 'left')
 6182        >>> g.getDestination('A', 'right')
 6183        1
 6184        >>> g.renameTransition('A', 'right', 'up')
 6185        >>> g.getDestination('A', 'right') is None
 6186        True
 6187        >>> g.getDestination('A', 'up')
 6188        1
 6189        >>> g.getReciprocal('A', 'up')
 6190        'left'
 6191        >>> g.renameTransition('B', 'left', 'left')
 6192        >>> g.getDestination('B', 'left')
 6193        0
 6194        >>> g.addTransition('B', 'down', 'A')
 6195        >>> g.renameTransition('B', 'left', 'down')
 6196        Traceback (most recent call last):
 6197        ...
 6198        exploration.core.TransitionCollisionError...
 6199        >>> g.renameTransition('A', 'madeup', 'any')
 6200        Traceback (most recent call last):
 6201        ...
 6202        exploration.core.MissingTransitionError...
 6203        """
 6204        if oldName == newName:
 6205            return
 6206
 6207        dID = self.resolveDecision(fromDecision)
 6208        dest = self.destination(dID, oldName)
 6209          # this will raise MissingTransitionError if necessary
 6210        if self.getDestination(dID, newName) is not None:
 6211            raise TransitionCollisionError(
 6212                f"Decision {self.shortIdentity(dID)} already has an"
 6213                f" outgoing transition named {newName!r} so you cannot"
 6214                f" rename transition {oldName!r} to that name."
 6215            )
 6216
 6217        # Add a new transition without a reciprocal or any properties
 6218        self.addTransition(dID, newName, dest)
 6219
 6220        # Merge old one into new one, setting new's reciprocal to old's
 6221        self.mergeTransitions(dID, oldName, newName, mergeReciprocal=True)
 6222
 6223    def mergeTransitions(
 6224        self,
 6225        fromDecision: base.AnyDecisionSpecifier,
 6226        merge: base.Transition,
 6227        mergeInto: base.Transition,
 6228        mergeReciprocal=True
 6229    ) -> None:
 6230        """
 6231        Given a decision and two transitions that start at that decision,
 6232        merges the first transition into the second transition, combining
 6233        their transition properties (using `mergeProperties`) and
 6234        deleting the first transition. By default any reciprocal of the
 6235        first transition is also merged into the reciprocal of the
 6236        second, although you can set `mergeReciprocal` to `False` to
 6237        disable this in which case the old reciprocal will lose its
 6238        reciprocal relationship, even if the transition that was merged
 6239        into does not have a reciprocal.
 6240
 6241        If the two names provided are the same, nothing will happen.
 6242
 6243        If the two transitions do not share the same destination, they
 6244        cannot be merged, and an `InvalidDestinationError` will result.
 6245        Use `retargetTransition` beforehand to ensure that they do if you
 6246        want to merge transitions with different destinations.
 6247
 6248        A `MissingDecisionError` or `MissingTransitionError` will result
 6249        if the decision or either transition does not exist.
 6250
 6251        If merging reciprocal properties was requested and the first
 6252        transition does not have a reciprocal, then no reciprocal
 6253        properties change. However, if the second transition does not
 6254        have a reciprocal and the first does, the first transition's
 6255        reciprocal will be set as the reciprocal of the second
 6256        transition, and that transition will not be deleted as usual.
 6257
 6258        ## Example
 6259
 6260        >>> g = DecisionGraph()
 6261        >>> g.addDecision('A')
 6262        0
 6263        >>> g.addDecision('B')
 6264        1
 6265        >>> g.addTransition('A', 'up', 'B')
 6266        >>> g.addTransition('B', 'down', 'A')
 6267        >>> g.setReciprocal('A', 'up', 'down')
 6268        >>> # Merging a transition with no reciprocal
 6269        >>> g.addTransition('A', 'up2', 'B')
 6270        >>> g.mergeTransitions('A', 'up2', 'up')
 6271        >>> g.getDestination('A', 'up2') is None
 6272        True
 6273        >>> g.getDestination('A', 'up')
 6274        1
 6275        >>> # Merging a transition with a reciprocal & tags
 6276        >>> g.addTransition('A', 'up2', 'B')
 6277        >>> g.addTransition('B', 'down2', 'A')
 6278        >>> g.setReciprocal('A', 'up2', 'down2')
 6279        >>> g.tagTransition('A', 'up2', 'one')
 6280        >>> g.tagTransition('B', 'down2', 'two')
 6281        >>> g.mergeTransitions('B', 'down2', 'down')
 6282        >>> g.getDestination('A', 'up2') is None
 6283        True
 6284        >>> g.getDestination('A', 'up')
 6285        1
 6286        >>> g.getDestination('B', 'down2') is None
 6287        True
 6288        >>> g.getDestination('B', 'down')
 6289        0
 6290        >>> # Merging requirements uses ReqAll (i.e., 'and' logic)
 6291        >>> g.addTransition('A', 'up2', 'B')
 6292        >>> g.setTransitionProperties(
 6293        ...     'A',
 6294        ...     'up2',
 6295        ...     requirement=base.ReqCapability('dash')
 6296        ... )
 6297        >>> g.setTransitionProperties('A', 'up',
 6298        ...     requirement=base.ReqCapability('slide'))
 6299        >>> g.mergeTransitions('A', 'up2', 'up')
 6300        >>> g.getDestination('A', 'up2') is None
 6301        True
 6302        >>> repr(g.getTransitionRequirement('A', 'up'))
 6303        "ReqAll([ReqCapability('dash'), ReqCapability('slide')])"
 6304        >>> # Errors if destinations differ, or if something is missing
 6305        >>> g.mergeTransitions('A', 'down', 'up')
 6306        Traceback (most recent call last):
 6307        ...
 6308        exploration.core.MissingTransitionError...
 6309        >>> g.mergeTransitions('Z', 'one', 'two')
 6310        Traceback (most recent call last):
 6311        ...
 6312        exploration.core.MissingDecisionError...
 6313        >>> g.addDecision('C')
 6314        2
 6315        >>> g.addTransition('A', 'down', 'C')
 6316        >>> g.mergeTransitions('A', 'down', 'up')
 6317        Traceback (most recent call last):
 6318        ...
 6319        exploration.core.InvalidDestinationError...
 6320        >>> # Merging a reciprocal onto an edge that doesn't have one
 6321        >>> g.addTransition('A', 'down2', 'C')
 6322        >>> g.addTransition('C', 'up2', 'A')
 6323        >>> g.setReciprocal('A', 'down2', 'up2')
 6324        >>> g.tagTransition('C', 'up2', 'narrow')
 6325        >>> g.getReciprocal('A', 'down') is None
 6326        True
 6327        >>> g.mergeTransitions('A', 'down2', 'down')
 6328        >>> g.getDestination('A', 'down2') is None
 6329        True
 6330        >>> g.getDestination('A', 'down')
 6331        2
 6332        >>> g.getDestination('C', 'up2')
 6333        0
 6334        >>> g.getReciprocal('A', 'down')
 6335        'up2'
 6336        >>> g.getReciprocal('C', 'up2')
 6337        'down'
 6338        >>> g.transitionTags('C', 'up2')
 6339        {'narrow': 1}
 6340        >>> # Merging without a reciprocal
 6341        >>> g.addTransition('C', 'up', 'A')
 6342        >>> g.mergeTransitions('C', 'up2', 'up', mergeReciprocal=False)
 6343        >>> g.getDestination('C', 'up2') is None
 6344        True
 6345        >>> g.getDestination('C', 'up')
 6346        0
 6347        >>> g.transitionTags('C', 'up') # tag gets merged
 6348        {'narrow': 1}
 6349        >>> g.getDestination('A', 'down')
 6350        2
 6351        >>> g.getReciprocal('A', 'down') is None
 6352        True
 6353        >>> g.getReciprocal('C', 'up') is None
 6354        True
 6355        >>> # Merging w/ normal reciprocals
 6356        >>> g.addDecision('D')
 6357        3
 6358        >>> g.addDecision('E')
 6359        4
 6360        >>> g.addTransition('D', 'up', 'E', 'return')
 6361        >>> g.addTransition('E', 'down', 'D')
 6362        >>> g.mergeTransitions('E', 'return', 'down')
 6363        >>> g.getDestination('D', 'up')
 6364        4
 6365        >>> g.getDestination('E', 'down')
 6366        3
 6367        >>> g.getDestination('E', 'return') is None
 6368        True
 6369        >>> g.getReciprocal('D', 'up')
 6370        'down'
 6371        >>> g.getReciprocal('E', 'down')
 6372        'up'
 6373        >>> # Merging w/ weird reciprocals
 6374        >>> g.addTransition('E', 'return', 'D')
 6375        >>> g.setReciprocal('E', 'return', 'up', setBoth=False)
 6376        >>> g.getReciprocal('D', 'up')
 6377        'down'
 6378        >>> g.getReciprocal('E', 'down')
 6379        'up'
 6380        >>> g.getReciprocal('E', 'return') # shared
 6381        'up'
 6382        >>> g.mergeTransitions('E', 'return', 'down')
 6383        >>> g.getDestination('D', 'up')
 6384        4
 6385        >>> g.getDestination('E', 'down')
 6386        3
 6387        >>> g.getDestination('E', 'return') is None
 6388        True
 6389        >>> g.getReciprocal('D', 'up')
 6390        'down'
 6391        >>> g.getReciprocal('E', 'down')
 6392        'up'
 6393        """
 6394        fromID = self.resolveDecision(fromDecision)
 6395
 6396        # Short-circuit in the no-op case
 6397        if merge == mergeInto:
 6398            return
 6399
 6400        # These lines will raise a MissingDecisionError or
 6401        # MissingTransitionError if needed
 6402        dest1 = self.destination(fromID, merge)
 6403        dest2 = self.destination(fromID, mergeInto)
 6404
 6405        if dest1 != dest2:
 6406            raise InvalidDestinationError(
 6407                f"Cannot merge transition {merge!r} into transition"
 6408                f" {mergeInto!r} from decision"
 6409                f" {self.identityOf(fromDecision)} because their"
 6410                f" destinations are different ({self.identityOf(dest1)}"
 6411                f" and {self.identityOf(dest2)}).\nNote: you can use"
 6412                f" `retargetTransition` to change the destination of a"
 6413                f" transition."
 6414            )
 6415
 6416        # Find and the transition properties
 6417        props1 = self.getTransitionProperties(fromID, merge)
 6418        props2 = self.getTransitionProperties(fromID, mergeInto)
 6419        merged = mergeProperties(props1, props2)
 6420        # Note that this doesn't change the reciprocal:
 6421        self.setTransitionProperties(fromID, mergeInto, **merged)
 6422
 6423        # Merge the reciprocal properties if requested
 6424        # Get reciprocal to merge into
 6425        reciprocal = self.getReciprocal(fromID, mergeInto)
 6426        # Get reciprocal that needs cleaning up
 6427        altReciprocal = self.getReciprocal(fromID, merge)
 6428        # If the reciprocal to be merged actually already was the
 6429        # reciprocal to merge into, there's nothing to do here
 6430        if altReciprocal != reciprocal:
 6431            if not mergeReciprocal:
 6432                # In this case, we sever the reciprocal relationship if
 6433                # there is a reciprocal
 6434                if altReciprocal is not None:
 6435                    self.setReciprocal(dest1, altReciprocal, None)
 6436                    # By default setBoth takes care of the other half
 6437            else:
 6438                # In this case, we try to merge reciprocals
 6439                # If altReciprocal is None, we don't need to do anything
 6440                if altReciprocal is not None:
 6441                    # Was there already a reciprocal or not?
 6442                    if reciprocal is None:
 6443                        # altReciprocal becomes the new reciprocal and is
 6444                        # not deleted
 6445                        self.setReciprocal(
 6446                            fromID,
 6447                            mergeInto,
 6448                            altReciprocal
 6449                        )
 6450                    else:
 6451                        # merge reciprocal properties
 6452                        props1 = self.getTransitionProperties(
 6453                            dest1,
 6454                            altReciprocal
 6455                        )
 6456                        props2 = self.getTransitionProperties(
 6457                            dest2,
 6458                            reciprocal
 6459                        )
 6460                        merged = mergeProperties(props1, props2)
 6461                        self.setTransitionProperties(
 6462                            dest1,
 6463                            reciprocal,
 6464                            **merged
 6465                        )
 6466
 6467                        # delete the old reciprocal transition
 6468                        self.remove_edge(dest1, fromID, altReciprocal)
 6469
 6470        # Delete the old transition (reciprocal deletion/severance is
 6471        # handled above if necessary)
 6472        self.remove_edge(fromID, dest1, merge)
 6473
 6474    def renameZone(self, oldName: base.Zone, newName: base.Zone):
 6475        """
 6476        Renames the specified zone. Raises a `ZoneCollisionError` if the
 6477        new name is already taken.
 6478
 6479        Example:
 6480
 6481        >>> g = DecisionGraph()
 6482        >>> g.addDecision("A")
 6483        0
 6484        >>> g.addDecision("B")
 6485        1
 6486        >>> g.createZone('Z', 0)
 6487        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
 6488 annotations=[])
 6489        >>> g.createZone('ZZ', 1)
 6490        ZoneInfo(level=1, parents=set(), contents=set(), tags={},\
 6491 annotations=[])
 6492        >>> g.addZoneToZone("Z", "ZZ")
 6493        >>> g.addDecisionToZone("A", "Z")
 6494        >>> g.renameZone("Z", "Q")
 6495        >>> sorted(g.zoneAncestors(0))
 6496        ['Q', 'ZZ']
 6497        >>> g.decisionsInZone('Z')
 6498        Traceback (most recent call last):
 6499        ...
 6500        exploration.core.MissingZoneError...
 6501        >>> g.decisionsInZone('Q')
 6502        {0}
 6503        """
 6504        if newName in self.zones:
 6505            raise ZoneCollisionError(
 6506               f"Cannot rename zone {oldName!r} to {newName!r} because"
 6507               f" a zone with that new name already exists."
 6508            )
 6509        # Transfer zone info & delete old entry
 6510        self.zones[newName] = self.zones[oldName]
 6511        del self.zones[oldName]
 6512
 6513        # Fix up child/contents info in ALL zones
 6514        for zoneInfo in self.zones.values():
 6515            if oldName in zoneInfo.parents:
 6516                zoneInfo.parents.remove(oldName)
 6517                zoneInfo.parents.add(newName)
 6518            if oldName in zoneInfo.contents:
 6519                zoneInfo.contents.remove(oldName)
 6520                zoneInfo.contents.add(newName)
 6521
 6522        # Fix up decision parent info
 6523        for n in self.nodes():
 6524            zones = self.nodes[n].get('zones')
 6525            if zones is not None:
 6526                if oldName in zones:
 6527                    zones.remove(oldName)
 6528                    zones.add(newName)
 6529
 6530    def isConfirmed(self, decision: base.AnyDecisionSpecifier) -> bool:
 6531        """
 6532        Returns `True` or `False` depending on whether or not the
 6533        specified decision has been confirmed. Uses the presence or
 6534        absence of the 'unconfirmed' tag to determine this.
 6535
 6536        Note: 'unconfirmed' is used instead of 'confirmed' so that large
 6537        graphs with many confirmed nodes will be smaller when saved.
 6538        """
 6539        dID = self.resolveDecision(decision)
 6540
 6541        return 'unconfirmed' not in self.nodes[dID]['tags']
 6542
 6543    def replaceUnconfirmed(
 6544        self,
 6545        fromDecision: base.AnyDecisionSpecifier,
 6546        transition: base.Transition,
 6547        connectTo: Optional[base.AnyDecisionSpecifier] = None,
 6548        reciprocal: Optional[base.Transition] = None,
 6549        requirement: Optional[base.Requirement] = None,
 6550        applyConsequence: Optional[base.Consequence] = None,
 6551        placeInZone: Optional[base.Zone] = None,
 6552        forceNew: bool = False,
 6553        tags: Optional[Dict[base.Tag, base.TagValue]] = None,
 6554        annotations: Optional[List[base.Annotation]] = None,
 6555        revRequires: Optional[base.Requirement] = None,
 6556        revConsequence: Optional[base.Consequence] = None,
 6557        revTags: Optional[Dict[base.Tag, base.TagValue]] = None,
 6558        revAnnotations: Optional[List[base.Annotation]] = None,
 6559        decisionTags: Optional[Dict[base.Tag, base.TagValue]] = None,
 6560        decisionAnnotations: Optional[List[base.Annotation]] = None
 6561    ) -> Tuple[
 6562        Dict[base.Transition, base.Transition],
 6563        Dict[base.Transition, base.Transition]
 6564    ]:
 6565        """
 6566        Given a decision and an edge name in that decision, where the
 6567        named edge leads to a decision with an unconfirmed exploration
 6568        state (see `isConfirmed`), renames the unexplored decision on
 6569        the other end of that edge using the given `connectTo` name, or
 6570        if a decision using that name already exists, merges the
 6571        unexplored decision into that decision. If `connectTo` is a
 6572        `DecisionSpecifier` whose target doesn't exist, it will be
 6573        treated as just a name, but if it's an ID and it doesn't exist,
 6574        you'll get a `MissingDecisionError`. If a `reciprocal` is provided,
 6575        a reciprocal edge will be added using that name connecting the
 6576        `connectTo` decision back to the original decision. If this
 6577        transition already exists, it must also point to a node which is
 6578        also unexplored, and which will also be merged into the
 6579        `fromDecision` node.
 6580
 6581        If `connectTo` is not given (or is set to `None` explicitly)
 6582        then the name of the unexplored decision will not be changed,
 6583        unless that name has the form `'_u.-n-'` where `-n-` is a positive
 6584        integer (i.e., the form given to automatically-named unknown
 6585        nodes). In that case, the name will be changed to `'_x.-n-'` using
 6586        the same number, or a higher number if that name is already taken.
 6587
 6588        If the destination is being renamed or if the destination's
 6589        exploration state counts as unexplored, the exploration state of
 6590        the destination will be set to 'exploring'.
 6591
 6592        If a `placeInZone` is specified, the destination will be placed
 6593        directly into that zone (even if it already existed and has zone
 6594        information), and it will be removed from any other zones it had
 6595        been a direct member of. If `placeInZone` is set to
 6596        `base.DefaultZone`, then the destination will be placed into
 6597        each zone which is a direct parent of the origin, but only if
 6598        the destination is not an already-explored existing decision AND
 6599        it is not already in any zones (in those cases no zone changes
 6600        are made). This will also remove it from any previous zones it
 6601        had been a part of. If `placeInZone` is left as `None` (the
 6602        default) no zone changes are made.
 6603
 6604        If `placeInZone` is specified and that zone didn't already exist,
 6605        it will be created as a new level-0 zone and will be added as a
 6606        sub-zone of each zone that's a direct parent of any level-0 zone
 6607        that the origin is a member of.
 6608
 6609        If `forceNew` is specified, then the destination will just be
 6610        renamed, even if another decision with the same name already
 6611        exists. It's an error to use `forceNew` with a decision ID as
 6612        the destination.
 6613
 6614        Any additional edges pointing to or from the unknown node(s)
 6615        being replaced will also be re-targeted at the now-discovered
 6616        known destination(s) if necessary. These edges will retain their
 6617        reciprocal names, or if this would cause a name clash, they will
 6618        be renamed with a suffix (see `retargetTransition`).
 6619
 6620        The return value is a pair of dictionaries mapping old names to
 6621        new ones that just includes the names which were changed. The
 6622        first dictionary contains renamed transitions that are outgoing
 6623        from the new destination node (which used to be outgoing from
 6624        the unexplored node). The second dictionary contains renamed
 6625        transitions that are outgoing from the source node (which used
 6626        to be outgoing from the unexplored node attached to the
 6627        reciprocal transition; if there was no reciprocal transition
 6628        specified then this will always be an empty dictionary).
 6629
 6630        An `ExplorationStatusError` will be raised if the destination
 6631        of the specified transition counts as visited (see
 6632        `hasBeenVisited`). An `ExplorationStatusError` will also be
 6633        raised if the `connectTo`'s `reciprocal` transition does not lead
 6634        to an unconfirmed decision (it's okay if this second transition
 6635        doesn't exist). A `TransitionCollisionError` will be raised if
 6636        the unconfirmed destination decision already has an outgoing
 6637        transition with the specified `reciprocal` which does not lead
 6638        back to the `fromDecision`.
 6639
 6640        The transition properties (requirement, consequences, tags,
 6641        and/or annotations) of the replaced transition will be copied
 6642        over to the new transition. Transition properties from the
 6643        reciprocal transition will also be copied for the newly created
 6644        reciprocal edge. Properties for any additional edges to/from the
 6645        unknown node will also be copied.
 6646
 6647        Also, any transition properties on existing forward or reciprocal
 6648        edges from the destination node with the indicated reverse name
 6649        will be merged with those from the target transition. Note that
 6650        this merging process may introduce corruption of complex
 6651        transition consequences. TODO: Fix that!
 6652
 6653        Any tags and annotations are added to copied tags/annotations,
 6654        but specified requirements, and/or consequences will replace
 6655        previous requirements/consequences, rather than being added to
 6656        them.
 6657
 6658        ## Example
 6659
 6660        >>> g = DecisionGraph()
 6661        >>> g.addDecision('A')
 6662        0
 6663        >>> g.addUnexploredEdge('A', 'up')
 6664        1
 6665        >>> g.destination('A', 'up')
 6666        1
 6667        >>> g.degree(1)
 6668        1
 6669        >>> g.replaceUnconfirmed('A', 'up', 'B', 'down')
 6670        ({}, {})
 6671        >>> g.destination('A', 'up')
 6672        1
 6673        >>> g.nameFor(1)
 6674        'B'
 6675        >>> g.destination('B', 'down')
 6676        0
 6677        >>> g.getDestination('B', 'return') is None
 6678        True
 6679        >>> '_u.0' in g.nameLookup
 6680        False
 6681        >>> g.getReciprocal('A', 'up')
 6682        'down'
 6683        >>> g.getReciprocal('B', 'down')
 6684        'up'
 6685        >>> # Two unexplored edges to the same node:
 6686        >>> g.addDecision('C')
 6687        2
 6688        >>> g.addTransition('B', 'next', 'C')
 6689        >>> g.addTransition('C', 'prev', 'B')
 6690        >>> g.setReciprocal('B', 'next', 'prev')
 6691        >>> g.addUnexploredEdge('A', 'next', 'D', 'prev')
 6692        3
 6693        >>> g.addTransition('C', 'down', 'D')
 6694        >>> g.addTransition('D', 'up', 'C')
 6695        >>> g.setReciprocal('C', 'down', 'up')
 6696        >>> g.replaceUnconfirmed('C', 'down')
 6697        ({}, {})
 6698        >>> g.destination('C', 'down')
 6699        3
 6700        >>> g.destination('A', 'next')
 6701        3
 6702        >>> g.destinationsFrom('D')
 6703        {'prev': 0, 'up': 2}
 6704        >>> g.decisionTags('D')
 6705        {}
 6706        >>> # An unexplored transition which turns out to connect to a
 6707        >>> # known decision, with name collisions
 6708        >>> g.addUnexploredEdge('D', 'next', reciprocal='prev')
 6709        4
 6710        >>> g.tagDecision('_u.2', 'wet')
 6711        >>> g.addUnexploredEdge('B', 'next', reciprocal='prev') # edge taken
 6712        Traceback (most recent call last):
 6713        ...
 6714        exploration.core.TransitionCollisionError...
 6715        >>> g.addUnexploredEdge('A', 'prev', reciprocal='next')
 6716        5
 6717        >>> g.tagDecision('_u.3', 'dry')
 6718        >>> # Add transitions that will collide when merged
 6719        >>> g.addUnexploredEdge('_u.2', 'up') # collides with A/up
 6720        6
 6721        >>> g.addUnexploredEdge('_u.3', 'prev') # collides with D/prev
 6722        7
 6723        >>> g.getReciprocal('A', 'prev')
 6724        'next'
 6725        >>> g.replaceUnconfirmed('A', 'prev', 'D', 'next') # two gone
 6726        ({'prev': 'prev.1'}, {'up': 'up.1'})
 6727        >>> g.destination('A', 'prev')
 6728        3
 6729        >>> g.destination('D', 'next')
 6730        0
 6731        >>> g.getReciprocal('A', 'prev')
 6732        'next'
 6733        >>> g.getReciprocal('D', 'next')
 6734        'prev'
 6735        >>> # Note that further unexplored structures are NOT merged
 6736        >>> # even if they match against existing structures...
 6737        >>> g.destination('A', 'up.1')
 6738        6
 6739        >>> g.destination('D', 'prev.1')
 6740        7
 6741        >>> '_u.2' in g.nameLookup
 6742        False
 6743        >>> '_u.3' in g.nameLookup
 6744        False
 6745        >>> g.decisionTags('D') # tags are merged
 6746        {'dry': 1}
 6747        >>> g.decisionTags('A')
 6748        {'wet': 1}
 6749        >>> # Auto-renaming an anonymous unexplored node
 6750        >>> g.addUnexploredEdge('B', 'out')
 6751        8
 6752        >>> g.replaceUnconfirmed('B', 'out', None, 'return')
 6753        ({}, {})
 6754        >>> '_u.6' in g
 6755        False
 6756        >>> g.destination('B', 'out')
 6757        8
 6758        >>> g.nameFor(8)
 6759        '_x.6'
 6760        >>> g.destination('_x.6', 'return')
 6761        1
 6762        >>> # Placing a node into a zone
 6763        >>> g.addUnexploredEdge('B', 'through')
 6764        9
 6765        >>> g.getDecision('E') is None
 6766        True
 6767        >>> g.replaceUnconfirmed(
 6768        ...     'B',
 6769        ...     'through',
 6770        ...     'E',
 6771        ...     'back',
 6772        ...     placeInZone='Zone'
 6773        ... )
 6774        ({}, {})
 6775        >>> g.getDecision('E')
 6776        9
 6777        >>> g.destination('B', 'through')
 6778        9
 6779        >>> g.destination('E', 'back')
 6780        1
 6781        >>> g.zoneParents(9)
 6782        {'Zone'}
 6783        >>> g.addUnexploredEdge('E', 'farther')
 6784        10
 6785        >>> g.replaceUnconfirmed(
 6786        ...     'E',
 6787        ...     'farther',
 6788        ...     'F',
 6789        ...     'closer',
 6790        ...     placeInZone=base.DefaultZone
 6791        ... )
 6792        ({}, {})
 6793        >>> g.destination('E', 'farther')
 6794        10
 6795        >>> g.destination('F', 'closer')
 6796        9
 6797        >>> g.zoneParents(10)
 6798        {'Zone'}
 6799        >>> g.addUnexploredEdge('F', 'backwards', placeInZone='Enoz')
 6800        11
 6801        >>> g.replaceUnconfirmed(
 6802        ...     'F',
 6803        ...     'backwards',
 6804        ...     'G',
 6805        ...     'forwards',
 6806        ...     placeInZone=base.DefaultZone
 6807        ... )
 6808        ({}, {})
 6809        >>> g.destination('F', 'backwards')
 6810        11
 6811        >>> g.destination('G', 'forwards')
 6812        10
 6813        >>> g.zoneParents(11)  # not changed since it already had a zone
 6814        {'Enoz'}
 6815        >>> # TODO: forceNew example
 6816        """
 6817
 6818        # Defaults
 6819        if tags is None:
 6820            tags = {}
 6821        if annotations is None:
 6822            annotations = []
 6823        if revTags is None:
 6824            revTags = {}
 6825        if revAnnotations is None:
 6826            revAnnotations = []
 6827        if decisionTags is None:
 6828            decisionTags = {}
 6829        if decisionAnnotations is None:
 6830            decisionAnnotations = []
 6831
 6832        # Resolve source
 6833        fromID = self.resolveDecision(fromDecision)
 6834
 6835        # Figure out destination decision
 6836        oldUnexplored = self.destination(fromID, transition)
 6837        if self.isConfirmed(oldUnexplored):
 6838            raise ExplorationStatusError(
 6839                f"Transition {transition!r} from"
 6840                f" {self.identityOf(fromDecision)} does not lead to an"
 6841                f" unconfirmed decision (it leads to"
 6842                f" {self.identityOf(oldUnexplored)} which is not tagged"
 6843                f" 'unconfirmed')."
 6844            )
 6845
 6846        # Resolve destination
 6847        newName: Optional[base.DecisionName] = None
 6848        connectID: Optional[base.DecisionID] = None
 6849        if forceNew:
 6850            if isinstance(connectTo, base.DecisionID):
 6851                raise TypeError(
 6852                    f"connectTo cannot be a decision ID when forceNew"
 6853                    f" is True. Got: {self.identityOf(connectTo)}"
 6854                )
 6855            elif isinstance(connectTo, base.DecisionSpecifier):
 6856                newName = connectTo.name
 6857            elif isinstance(connectTo, base.DecisionName):
 6858                newName = connectTo
 6859            elif connectTo is None:
 6860                oldName = self.nameFor(oldUnexplored)
 6861                if (
 6862                    oldName.startswith('_u.')
 6863                and oldName[3:].isdigit()
 6864                ):
 6865                    newName = utils.uniqueName('_x.' + oldName[3:], self)
 6866                else:
 6867                    newName = oldName
 6868            else:
 6869                raise TypeError(
 6870                    f"Invalid connectTo value: {connectTo!r}"
 6871                )
 6872        elif connectTo is not None:
 6873            try:
 6874                connectID = self.resolveDecision(connectTo)
 6875                # leave newName as None
 6876            except MissingDecisionError:
 6877                if isinstance(connectTo, int):
 6878                    raise
 6879                elif isinstance(connectTo, base.DecisionSpecifier):
 6880                    newName = connectTo.name
 6881                    # The domain & zone are ignored here
 6882                else:  # Must just be a string
 6883                    assert isinstance(connectTo, str)
 6884                    newName = connectTo
 6885        else:
 6886            # If connectTo name wasn't specified, use current name of
 6887            # unknown node unless it's a default name
 6888            oldName = self.nameFor(oldUnexplored)
 6889            if (
 6890                oldName.startswith('_u.')
 6891            and oldName[3:].isdigit()
 6892            ):
 6893                newName = utils.uniqueName('_x.' + oldName[3:], self)
 6894            else:
 6895                newName = oldName
 6896
 6897        # One or the other should be valid at this point
 6898        assert connectID is not None or newName is not None
 6899
 6900        # Check that the old unknown doesn't have a reciprocal edge that
 6901        # would collide with the specified return edge
 6902        if reciprocal is not None:
 6903            revFromUnknown = self.getDestination(oldUnexplored, reciprocal)
 6904            if revFromUnknown not in (None, fromID):
 6905                raise TransitionCollisionError(
 6906                    f"Transition {reciprocal!r} from"
 6907                    f" {self.identityOf(oldUnexplored)} exists and does"
 6908                    f" not lead back to {self.identityOf(fromDecision)}"
 6909                    f" (it leads to {self.identityOf(revFromUnknown)})."
 6910                )
 6911
 6912        # Remember old reciprocal edge for future merging in case
 6913        # it's not reciprocal
 6914        oldReciprocal = self.getReciprocal(fromID, transition)
 6915
 6916        # Apply any new tags or annotations, or create a new node
 6917        needsZoneInfo = False
 6918        if connectID is not None:
 6919            # Before applying tags, check if we need to error out
 6920            # because of a reciprocal edge that points to a known
 6921            # destination:
 6922            if reciprocal is not None:
 6923                otherOldUnknown: Optional[
 6924                    base.DecisionID
 6925                ] = self.getDestination(
 6926                    connectID,
 6927                    reciprocal
 6928                )
 6929                if (
 6930                    otherOldUnknown is not None
 6931                and self.isConfirmed(otherOldUnknown)
 6932                ):
 6933                    raise ExplorationStatusError(
 6934                        f"Reciprocal transition {reciprocal!r} from"
 6935                        f" {self.identityOf(connectTo)} does not lead"
 6936                        f" to an unconfirmed decision (it leads to"
 6937                        f" {self.identityOf(otherOldUnknown)})."
 6938                    )
 6939            self.tagDecision(connectID, decisionTags)
 6940            self.annotateDecision(connectID, decisionAnnotations)
 6941            # Still needs zone info if the place we're connecting to was
 6942            # unconfirmed up until now, since unconfirmed nodes don't
 6943            # normally get zone info when they're created.
 6944            if not self.isConfirmed(connectID):
 6945                needsZoneInfo = True
 6946
 6947            # First, merge the old unknown with the connectTo node...
 6948            destRenames = self.mergeDecisions(
 6949                oldUnexplored,
 6950                connectID,
 6951                errorOnNameColision=False
 6952            )
 6953        else:
 6954            needsZoneInfo = True
 6955            if len(self.zoneParents(oldUnexplored)) > 0:
 6956                needsZoneInfo = False
 6957            assert newName is not None
 6958            self.renameDecision(oldUnexplored, newName)
 6959            connectID = oldUnexplored
 6960            # In this case there can't be an other old unknown
 6961            otherOldUnknown = None
 6962            destRenames = {}  # empty
 6963
 6964        # Check for domain mismatch to stifle zone updates:
 6965        fromDomain = self.domainFor(fromID)
 6966        if connectID is None:
 6967            destDomain = self.domainFor(oldUnexplored)
 6968        else:
 6969            destDomain = self.domainFor(connectID)
 6970
 6971        # Stifle zone updates if there's a mismatch
 6972        if fromDomain != destDomain:
 6973            needsZoneInfo = False
 6974
 6975        # Records renames that happen at the source (from node)
 6976        sourceRenames = {}  # empty for now
 6977
 6978        assert connectID is not None
 6979
 6980        # Apply the new zone if there is one
 6981        if placeInZone is not None:
 6982            if placeInZone == base.DefaultZone:
 6983                # When using DefaultZone, changes are only made for new
 6984                # destinations which don't already have any zones and
 6985                # which are in the same domain as the departing node:
 6986                # they get placed into each zone parent of the source
 6987                # decision.
 6988                if needsZoneInfo:
 6989                    # Remove destination from all current parents
 6990                    removeFrom = set(self.zoneParents(connectID))  # copy
 6991                    for parent in removeFrom:
 6992                        self.removeDecisionFromZone(connectID, parent)
 6993                    # Add it to parents of origin
 6994                    for parent in self.zoneParents(fromID):
 6995                        self.addDecisionToZone(connectID, parent)
 6996            else:
 6997                placeInZone = cast(base.Zone, placeInZone)
 6998                # Create the zone if it doesn't already exist
 6999                if self.getZoneInfo(placeInZone) is None:
 7000                    self.createZone(placeInZone, 0)
 7001                    # Add it to each grandparent of the from decision
 7002                    for parent in self.zoneParents(fromID):
 7003                        for grandparent in self.zoneParents(parent):
 7004                            self.addZoneToZone(placeInZone, grandparent)
 7005                # Remove destination from all current parents
 7006                for parent in set(self.zoneParents(connectID)):
 7007                    self.removeDecisionFromZone(connectID, parent)
 7008                # Add it to the specified zone
 7009                self.addDecisionToZone(connectID, placeInZone)
 7010
 7011        # Next, if there is a reciprocal name specified, we do more...
 7012        if reciprocal is not None:
 7013            # Figure out what kind of merging needs to happen
 7014            if otherOldUnknown is None:
 7015                if revFromUnknown is None:
 7016                    # Just create the desired reciprocal transition, which
 7017                    # we know does not already exist
 7018                    self.addTransition(connectID, reciprocal, fromID)
 7019                    otherOldReciprocal = None
 7020                else:
 7021                    # Reciprocal exists, as revFromUnknown
 7022                    otherOldReciprocal = None
 7023            else:
 7024                otherOldReciprocal = self.getReciprocal(
 7025                    connectID,
 7026                    reciprocal
 7027                )
 7028                # we need to merge otherOldUnknown into our fromDecision
 7029                sourceRenames = self.mergeDecisions(
 7030                    otherOldUnknown,
 7031                    fromID,
 7032                    errorOnNameColision=False
 7033                )
 7034                # Unvisited tag after merge only if both were
 7035
 7036            # No matter what happened we ensure the reciprocal
 7037            # relationship is set up:
 7038            self.setReciprocal(fromID, transition, reciprocal)
 7039
 7040            # Now we might need to merge some transitions:
 7041            # - Any reciprocal of the target transition should be merged
 7042            #   with reciprocal (if it was already reciprocal, that's a
 7043            #   no-op).
 7044            # - Any reciprocal of the reciprocal transition from the target
 7045            #   node (leading to otherOldUnknown) should be merged with
 7046            #   the target transition, even if it shared a name and was
 7047            #   renamed as a result.
 7048            # - If reciprocal was renamed during the initial merge, those
 7049            #   transitions should be merged.
 7050
 7051            # Merge old reciprocal into reciprocal
 7052            if oldReciprocal is not None:
 7053                oldRev = destRenames.get(oldReciprocal, oldReciprocal)
 7054                if self.getDestination(connectID, oldRev) is not None:
 7055                    # Note that we don't want to auto-merge the reciprocal,
 7056                    # which is the target transition
 7057                    self.mergeTransitions(
 7058                        connectID,
 7059                        oldRev,
 7060                        reciprocal,
 7061                        mergeReciprocal=False
 7062                    )
 7063                    # Remove it from the renames map
 7064                    if oldReciprocal in destRenames:
 7065                        del destRenames[oldReciprocal]
 7066
 7067            # Merge reciprocal reciprocal from otherOldUnknown
 7068            if otherOldReciprocal is not None:
 7069                otherOldRev = sourceRenames.get(
 7070                    otherOldReciprocal,
 7071                    otherOldReciprocal
 7072                )
 7073                # Note that the reciprocal is reciprocal, which we don't
 7074                # need to merge
 7075                self.mergeTransitions(
 7076                    fromID,
 7077                    otherOldRev,
 7078                    transition,
 7079                    mergeReciprocal=False
 7080                )
 7081                # Remove it from the renames map
 7082                if otherOldReciprocal in sourceRenames:
 7083                    del sourceRenames[otherOldReciprocal]
 7084
 7085            # Merge any renamed reciprocal onto reciprocal
 7086            if reciprocal in destRenames:
 7087                extraRev = destRenames[reciprocal]
 7088                self.mergeTransitions(
 7089                    connectID,
 7090                    extraRev,
 7091                    reciprocal,
 7092                    mergeReciprocal=False
 7093                )
 7094                # Remove it from the renames map
 7095                del destRenames[reciprocal]
 7096
 7097        # Accumulate new tags & annotations for the transitions
 7098        self.tagTransition(fromID, transition, tags)
 7099        self.annotateTransition(fromID, transition, annotations)
 7100
 7101        if reciprocal is not None:
 7102            self.tagTransition(connectID, reciprocal, revTags)
 7103            self.annotateTransition(connectID, reciprocal, revAnnotations)
 7104
 7105        # Override copied requirement/consequences for the transitions
 7106        if requirement is not None:
 7107            self.setTransitionRequirement(
 7108                fromID,
 7109                transition,
 7110                requirement
 7111            )
 7112        if applyConsequence is not None:
 7113            self.setConsequence(
 7114                fromID,
 7115                transition,
 7116                applyConsequence
 7117            )
 7118
 7119        if reciprocal is not None:
 7120            if revRequires is not None:
 7121                self.setTransitionRequirement(
 7122                    connectID,
 7123                    reciprocal,
 7124                    revRequires
 7125                )
 7126            if revConsequence is not None:
 7127                self.setConsequence(
 7128                    connectID,
 7129                    reciprocal,
 7130                    revConsequence
 7131                )
 7132
 7133        # Remove 'unconfirmed' tag if it was present
 7134        self.untagDecision(connectID, 'unconfirmed')
 7135
 7136        # Final checks
 7137        assert self.getDestination(fromDecision, transition) == connectID
 7138        useConnect: base.AnyDecisionSpecifier
 7139        useRev: Optional[str]
 7140        if connectTo is None:
 7141            useConnect = connectID
 7142        else:
 7143            useConnect = connectTo
 7144        if reciprocal is None:
 7145            useRev = self.getReciprocal(fromDecision, transition)
 7146        else:
 7147            useRev = reciprocal
 7148        if useRev is not None:
 7149            try:
 7150                assert self.getDestination(useConnect, useRev) == fromID
 7151            except AmbiguousDecisionSpecifierError:
 7152                assert self.getDestination(connectID, useRev) == fromID
 7153
 7154        # Return our final rename dictionaries
 7155        return (destRenames, sourceRenames)
 7156
 7157    def endingID(self, name: base.DecisionName) -> base.DecisionID:
 7158        """
 7159        Returns the decision ID for the ending with the specified name.
 7160        Endings are disconnected decisions in the `ENDINGS_DOMAIN`; they
 7161        don't normally include any zone information. If no ending with
 7162        the specified name already existed, then a new ending with that
 7163        name will be created and its Decision ID will be returned.
 7164
 7165        If a new decision is created, it will be tagged as unconfirmed.
 7166
 7167        Note that endings mostly aren't special: they're normal
 7168        decisions in a separate singular-focalized domain. However, some
 7169        parts of the exploration and journal machinery treat them
 7170        differently (in particular, taking certain actions via
 7171        `advanceSituation` while any decision in the `ENDINGS_DOMAIN` is
 7172        active is an error.
 7173        """
 7174        # Create our new ending decision if we need to
 7175        try:
 7176            endID = self.resolveDecision(
 7177                base.DecisionSpecifier(ENDINGS_DOMAIN, None, name)
 7178            )
 7179        except MissingDecisionError:
 7180            # Create a new decision for the ending
 7181            endID = self.addDecision(name, domain=ENDINGS_DOMAIN)
 7182            # Tag it as unconfirmed
 7183            self.tagDecision(endID, 'unconfirmed')
 7184
 7185        return endID
 7186
 7187    def triggerGroupID(self, name: base.DecisionName) -> base.DecisionID:
 7188        """
 7189        Given the name of a trigger group, returns the ID of the special
 7190        node representing that trigger group in the `TRIGGERS_DOMAIN`.
 7191        If the specified group didn't already exist, it will be created.
 7192
 7193        Trigger group decisions are not special: they just exist in a
 7194        separate spreading-focalized domain and have a few API methods to
 7195        access them, but all the normal decision-related API methods
 7196        still work. Their intended use is for sets of global triggers,
 7197        by attaching actions with the 'trigger' tag to them and then
 7198        activating or deactivating them as needed.
 7199        """
 7200        result = self.getDecision(
 7201            base.DecisionSpecifier(TRIGGERS_DOMAIN, None, name)
 7202        )
 7203        if result is None:
 7204            return self.addDecision(name, domain=TRIGGERS_DOMAIN)
 7205        else:
 7206            return result
 7207
 7208    @staticmethod
 7209    def example(which: Literal['simple', 'abc']) -> 'DecisionGraph':
 7210        """
 7211        Returns one of a number of example decision graphs, depending on
 7212        the string given. It returns a fresh copy each time. The graphs
 7213        are:
 7214
 7215        - 'simple': Three nodes named 'A', 'B', and 'C' with IDs 0, 1,
 7216            and 2, each connected to the next in the sequence by a
 7217            'next' transition with reciprocal 'prev'. In other words, a
 7218            simple little triangle. There are no tags, annotations,
 7219            requirements, consequences, mechanisms, or equivalences.
 7220        - 'abc': A more complicated 3-node setup that introduces a
 7221            little bit of everything. In this graph, we have the same
 7222            three nodes, but different transitions:
 7223
 7224                * From A you can go 'left' to B with reciprocal 'right'.
 7225                * From A you can also go 'up_left' to B with reciprocal
 7226                    'up_right'. These transitions both require the
 7227                    'grate' mechanism (which is at decision A) to be in
 7228                    state 'open'.
 7229                * From A you can go 'down' to C with reciprocal 'up'.
 7230
 7231            (In this graph, B and C are not directly connected to each
 7232            other.)
 7233
 7234            The graph has two level-0 zones 'zoneA' and 'zoneB', along
 7235            with a level-1 zone 'upZone'. Decisions A and C are in
 7236            zoneA while B is in zoneB; zoneA is in upZone, but zoneB is
 7237            not.
 7238
 7239            The decision A has annotation:
 7240
 7241                'This is a multi-word "annotation."'
 7242
 7243            The transition 'down' from A has annotation:
 7244
 7245                "Transition 'annotation.'"
 7246
 7247            Decision B has tags 'b' with value 1 and 'tag2' with value
 7248            '"value"'.
 7249
 7250            Decision C has tag 'aw"ful' with value "ha'ha'".
 7251
 7252            Transition 'up' from C has tag 'fast' with value 1.
 7253
 7254            At decision C there are actions 'grab_helmet' and
 7255            'pull_lever'.
 7256
 7257            The 'grab_helmet' transition requires that you don't have
 7258            the 'helmet' capability, and gives you that capability,
 7259            deactivating with delay 3.
 7260
 7261            The 'pull_lever' transition requires that you do have the
 7262            'helmet' capability, and takes away that capability, but it
 7263            also gives you 1 'token' token, and if you have 2 tokens
 7264            (before getting the one extra), it sets the 'grate' mechanism
 7265            (which is a decision A) to state 'open' and deactivates.
 7266
 7267            The graph has an equivalence: having the 'helmet' capability
 7268            satisfies requirements for the 'grate' mechanism to be in the
 7269            'open' state.
 7270        """
 7271        result = DecisionGraph()
 7272        if which == 'simple':
 7273            result.addDecision('A')  # id 0
 7274            result.addDecision('B')  # id 1
 7275            result.addDecision('C')  # id 2
 7276            result.addTransition('A', 'next', 'B', 'prev')
 7277            result.addTransition('B', 'next', 'C', 'prev')
 7278            result.addTransition('C', 'next', 'A', 'prev')
 7279        elif which == 'abc':
 7280            result.addDecision('A')  # id 0
 7281            result.addDecision('B')  # id 1
 7282            result.addDecision('C')  # id 2
 7283            result.createZone('zoneA', 0)
 7284            result.createZone('zoneB', 0)
 7285            result.createZone('upZone', 1)
 7286            result.addZoneToZone('zoneA', 'upZone')
 7287            result.addDecisionToZone('A', 'zoneA')
 7288            result.addDecisionToZone('B', 'zoneB')
 7289            result.addDecisionToZone('C', 'zoneA')
 7290            result.addTransition('A', 'left', 'B', 'right')
 7291            result.addTransition('A', 'up_left', 'B', 'up_right')
 7292            result.addTransition('A', 'down', 'C', 'up')
 7293            result.setTransitionRequirement(
 7294                'A',
 7295                'up_left',
 7296                base.ReqMechanism('grate', 'open')
 7297            )
 7298            result.setTransitionRequirement(
 7299                'B',
 7300                'up_right',
 7301                base.ReqMechanism('grate', 'open')
 7302            )
 7303            result.annotateDecision('A', 'This is a multi-word "annotation."')
 7304            result.annotateTransition('A', 'down', "Transition 'annotation.'")
 7305            result.tagDecision('B', 'b')
 7306            result.tagDecision('B', 'tag2', '"value"')
 7307            result.tagDecision('C', 'aw"ful', "ha'ha")
 7308            result.tagTransition('C', 'up', 'fast')
 7309            result.addMechanism('grate', 'A')
 7310            result.addAction(
 7311                'C',
 7312                'grab_helmet',
 7313                base.ReqNot(base.ReqCapability('helmet')),
 7314                [
 7315                    base.effect(gain='helmet'),
 7316                    base.effect(deactivate=True, delay=3)
 7317                ]
 7318            )
 7319            result.addAction(
 7320                'C',
 7321                'pull_lever',
 7322                base.ReqCapability('helmet'),
 7323                [
 7324                    base.effect(lose='helmet'),
 7325                    base.effect(gain=('token', 1)),
 7326                    base.condition(
 7327                        base.ReqTokens('token', 2),
 7328                        [
 7329                            base.effect(set=('grate', 'open')),
 7330                            base.effect(deactivate=True)
 7331                        ]
 7332                    )
 7333                ]
 7334            )
 7335            result.addEquivalence(
 7336                base.ReqCapability('helmet'),
 7337                (0, 'open')
 7338            )
 7339        else:
 7340            raise ValueError(f"Invalid example name: {which!r}")
 7341
 7342        return result
 7343
 7344
 7345#---------------------------#
 7346# DiscreteExploration class #
 7347#---------------------------#
 7348
 7349def emptySituation() -> base.Situation:
 7350    """
 7351    Creates and returns an empty situation: A situation that has an
 7352    empty `DecisionGraph`, an empty `State`, a 'pending' decision type
 7353    with `None` as the action taken, no tags, and no annotations.
 7354    """
 7355    return base.Situation(
 7356        graph=DecisionGraph(),
 7357        state=base.emptyState(),
 7358        type='pending',
 7359        action=None,
 7360        saves={},
 7361        tags={},
 7362        annotations=[]
 7363    )
 7364
 7365    pass
 7366
 7367
 7368class DiscreteExploration:
 7369    """
 7370    A list of `Situations` each of which contains a `DecisionGraph`
 7371    representing exploration over time, with `States` containing
 7372    `FocalContext` information for each step and 'taken' values for the
 7373    transition selected (at a particular decision) in that step. Each
 7374    decision graph represents a new state of the world (and/or new
 7375    knowledge about a persisting state of the world), and the 'taken'
 7376    transition in one situation transition indicates which option was
 7377    selected, or what event happened to cause update(s). Depending on the
 7378    resolution, it could represent a close record of every decision made
 7379    or a more coarse set of snapshots from gameplay with more time in
 7380    between.
 7381
 7382    The steps of the exploration can also be tagged and annotated (see
 7383    `tagStep` and `annotateStep`).
 7384
 7385    It also holds a `layouts` field that includes zero or more
 7386    `base.Layout`s by name.
 7387
 7388    When a new `DiscreteExploration` is created, it starts out with an
 7389    empty `Situation` that contains an empty `DecisionGraph`. Use the
 7390    `start` method to name the starting decision point and set things up
 7391    for other methods.
 7392
 7393    Tracking of player goals and destinations is also planned (see the
 7394    `quest`, `progress`, `complete`, `destination`, and `arrive` methods).
 7395    TODO: That
 7396    """
 7397    def __init__(self) -> None:
 7398        self.situations: List[base.Situation] = [
 7399            base.Situation(
 7400                graph=DecisionGraph(),
 7401                state=base.emptyState(),
 7402                type='pending',
 7403                action=None,
 7404                saves={},
 7405                tags={},
 7406                annotations=[]
 7407            )
 7408        ]
 7409        self.layouts: Dict[str, base.Layout] = {}
 7410
 7411    # Note: not hashable
 7412
 7413    def __eq__(self, other):
 7414        """
 7415        Equality checker. `DiscreteExploration`s can only be equal to
 7416        other `DiscreteExploration`s, not to other kinds of things.
 7417        """
 7418        if not isinstance(other, DiscreteExploration):
 7419            return False
 7420        else:
 7421            return self.situations == other.situations
 7422
 7423    @staticmethod
 7424    def fromGraph(
 7425        graph: DecisionGraph,
 7426        state: Optional[base.State] = None
 7427    ) -> 'DiscreteExploration':
 7428        """
 7429        Creates an exploration which has just a single step whose graph
 7430        is the entire specified graph, with the specified decision as
 7431        the primary decision (if any). The graph is copied, so that
 7432        changes to the exploration will not modify it. A starting state
 7433        may also be specified if desired, although if not an empty state
 7434        will be used (a provided starting state is NOT copied, but used
 7435        directly).
 7436
 7437        Example:
 7438
 7439        >>> g = DecisionGraph()
 7440        >>> g.addDecision('Room1')
 7441        0
 7442        >>> g.addDecision('Room2')
 7443        1
 7444        >>> g.addTransition('Room1', 'door', 'Room2', 'door')
 7445        >>> e = DiscreteExploration.fromGraph(g)
 7446        >>> len(e)
 7447        1
 7448        >>> e.getSituation().graph == g
 7449        True
 7450        >>> e.getActiveDecisions()
 7451        set()
 7452        >>> e.primaryDecision() is None
 7453        True
 7454        >>> e.observe('Room1', 'hatch')
 7455        2
 7456        >>> e.getSituation().graph == g
 7457        False
 7458        >>> e.getSituation().graph.destinationsFrom('Room1')
 7459        {'door': 1, 'hatch': 2}
 7460        >>> g.destinationsFrom('Room1')
 7461        {'door': 1}
 7462        """
 7463        result = DiscreteExploration()
 7464        result.situations[0] = base.Situation(
 7465            graph=copy.deepcopy(graph),
 7466            state=base.emptyState() if state is None else state,
 7467            type='pending',
 7468            action=None,
 7469            saves={},
 7470            tags={},
 7471            annotations=[]
 7472        )
 7473        return result
 7474
 7475    def __len__(self) -> int:
 7476        """
 7477        The 'length' of an exploration is the number of steps.
 7478        """
 7479        return len(self.situations)
 7480
 7481    def __getitem__(self, i: int) -> base.Situation:
 7482        """
 7483        Indexing an exploration returns the situation at that step.
 7484        """
 7485        return self.situations[i]
 7486
 7487    def __iter__(self) -> Iterator[base.Situation]:
 7488        """
 7489        Iterating over an exploration yields each `Situation` in order.
 7490        """
 7491        for i in range(len(self)):
 7492            yield self[i]
 7493
 7494    def getSituation(self, step: int = -1) -> base.Situation:
 7495        """
 7496        Returns a `base.Situation` named tuple detailing the state of
 7497        the exploration at a given step (or at the current step if no
 7498        argument is given). Note that this method works the same
 7499        way as indexing the exploration: see `__getitem__`.
 7500
 7501        Raises an `IndexError` if asked for a step that's out-of-range.
 7502        """
 7503        return self[step]
 7504
 7505    def primaryDecision(self, step: int = -1) -> Optional[base.DecisionID]:
 7506        """
 7507        Returns the current primary `base.DecisionID`, or the primary
 7508        decision from a specific step if one is specified. This may be
 7509        `None` for some steps, but mostly it's the destination of the
 7510        transition taken in the previous step.
 7511        """
 7512        return self[step].state['primaryDecision']
 7513
 7514    def effectiveCapabilities(
 7515        self,
 7516        step: int = -1
 7517    ) -> base.CapabilitySet:
 7518        """
 7519        Returns the effective capability set for the specified step
 7520        (default is the last/current step). See
 7521        `base.effectiveCapabilities`.
 7522        """
 7523        return base.effectiveCapabilitySet(self.getSituation(step).state)
 7524
 7525    def getCommonContext(
 7526        self,
 7527        step: Optional[int] = None
 7528    ) -> base.FocalContext:
 7529        """
 7530        Returns the common `FocalContext` at the specified step, or at
 7531        the current step if no argument is given. Raises an `IndexError`
 7532        if an invalid step is specified.
 7533        """
 7534        if step is None:
 7535            step = -1
 7536        state = self.getSituation(step).state
 7537        return state['common']
 7538
 7539    def getActiveContext(
 7540        self,
 7541        step: Optional[int] = None
 7542    ) -> base.FocalContext:
 7543        """
 7544        Returns the active `FocalContext` at the specified step, or at
 7545        the current step if no argument is provided. Raises an
 7546        `IndexError` if an invalid step is specified.
 7547        """
 7548        if step is None:
 7549            step = -1
 7550        state = self.getSituation(step).state
 7551        return state['contexts'][state['activeContext']]
 7552
 7553    def addFocalContext(self, name: base.FocalContextName) -> None:
 7554        """
 7555        Adds a new empty focal context to our set of focal contexts (see
 7556        `emptyFocalContext`). Use `setActiveContext` to swap to it.
 7557        Raises a `FocalContextCollisionError` if the name is already in
 7558        use.
 7559        """
 7560        contextMap = self.getSituation().state['contexts']
 7561        if name in contextMap:
 7562            raise FocalContextCollisionError(
 7563                f"Cannot add focal context {name!r}: a focal context"
 7564                f" with that name already exists."
 7565            )
 7566        contextMap[name] = base.emptyFocalContext()
 7567
 7568    def setActiveContext(self, which: base.FocalContextName) -> None:
 7569        """
 7570        Sets the active context to the named focal context, creating it
 7571        if it did not already exist (makes changes to the current
 7572        situation only). Does not add an exploration step (use
 7573        `advanceSituation` with a 'swap' action for that).
 7574        """
 7575        state = self.getSituation().state
 7576        contextMap = state['contexts']
 7577        if which not in contextMap:
 7578            self.addFocalContext(which)
 7579        state['activeContext'] = which
 7580
 7581    def createDomain(
 7582        self,
 7583        name: base.Domain,
 7584        focalization: base.DomainFocalization = 'singular',
 7585        makeActive: bool = False,
 7586        inCommon: Union[bool, Literal["both"]] = "both"
 7587    ) -> None:
 7588        """
 7589        Creates a new domain with the given focalization type, in either
 7590        the common context (`inCommon` = `True`) the active context
 7591        (`inCommon` = `False`) or both (the default; `inCommon` = 'both').
 7592        The domain's focalization will be set to the given
 7593        `focalization` value (default 'singular') and it will have no
 7594        active decisions. Raises a `DomainCollisionError` if a domain
 7595        with the specified name already exists.
 7596
 7597        Creates the domain in the current situation.
 7598
 7599        If `makeActive` is set to `True` (default is `False`) then the
 7600        domain will be made active in whichever context(s) it's created
 7601        in.
 7602        """
 7603        now = self.getSituation()
 7604        state = now.state
 7605        modify = []
 7606        if inCommon in (True, "both"):
 7607            modify.append(('common', state['common']))
 7608        if inCommon in (False, "both"):
 7609            acName = state['activeContext']
 7610            modify.append(
 7611                ('current ({repr(acName)})', state['contexts'][acName])
 7612            )
 7613
 7614        for (fcType, fc) in modify:
 7615            if name in fc['focalization']:
 7616                raise DomainCollisionError(
 7617                    f"Cannot create domain {repr(name)} because a"
 7618                    f" domain with that name already exists in the"
 7619                    f" {fcType} focal context."
 7620                )
 7621            fc['focalization'][name] = focalization
 7622            if makeActive:
 7623                fc['activeDomains'].add(name)
 7624            if focalization == "spreading":
 7625                fc['activeDecisions'][name] = set()
 7626            elif focalization == "plural":
 7627                fc['activeDecisions'][name] = {}
 7628            else:
 7629                fc['activeDecisions'][name] = None
 7630
 7631    def activateDomain(
 7632        self,
 7633        domain: base.Domain,
 7634        activate: bool = True,
 7635        inContext: base.ContextSpecifier = "active"
 7636    ) -> None:
 7637        """
 7638        Sets the given domain as active (or inactive if 'activate' is
 7639        given as `False`) in the specified context (default "active").
 7640
 7641        Modifies the current situation.
 7642        """
 7643        fc: base.FocalContext
 7644        if inContext == "active":
 7645            fc = self.getActiveContext()
 7646        elif inContext == "common":
 7647            fc = self.getCommonContext()
 7648
 7649        if activate:
 7650            fc['activeDomains'].add(domain)
 7651        else:
 7652            try:
 7653                fc['activeDomains'].remove(domain)
 7654            except KeyError:
 7655                pass
 7656
 7657    def createTriggerGroup(
 7658        self,
 7659        name: base.DecisionName
 7660    ) -> base.DecisionID:
 7661        """
 7662        Creates a new trigger group with the given name, returning the
 7663        decision ID for that trigger group. If this is the first trigger
 7664        group being created, also creates the `TRIGGERS_DOMAIN` domain
 7665        as a spreading-focalized domain that's active in the common
 7666        context (but does NOT set the created trigger group as an active
 7667        decision in that domain).
 7668
 7669        You can use 'goto' effects to activate trigger domains via
 7670        consequences, and 'retreat' effects to deactivate them.
 7671
 7672        Creating a second trigger group with the same name as another
 7673        results in a `ValueError`.
 7674
 7675        TODO: Retreat effects
 7676        """
 7677        ctx = self.getCommonContext()
 7678        if TRIGGERS_DOMAIN not in ctx['focalization']:
 7679            self.createDomain(
 7680                TRIGGERS_DOMAIN,
 7681                focalization='spreading',
 7682                makeActive=True,
 7683                inCommon=True
 7684            )
 7685
 7686        graph = self.getSituation().graph
 7687        if graph.getDecision(
 7688            base.DecisionSpecifier(TRIGGERS_DOMAIN, None, name)
 7689        ) is not None:
 7690            raise ValueError(
 7691                f"Cannot create trigger group {name!r}: a trigger group"
 7692                f" with that name already exists."
 7693            )
 7694
 7695        return self.getSituation().graph.triggerGroupID(name)
 7696
 7697    def toggleTriggerGroup(
 7698        self,
 7699        name: base.DecisionName,
 7700        setActive: Union[bool, None] = None
 7701    ):
 7702        """
 7703        Toggles whether the specified trigger group (a decision in the
 7704        `TRIGGERS_DOMAIN`) is active or not. Pass `True` or `False` as
 7705        the `setActive` argument (instead of the default `None`) to set
 7706        the state directly instead of toggling it.
 7707
 7708        Note that trigger groups are decisions in a spreading-focalized
 7709        domain, so they can be activated or deactivated by the 'goto'
 7710        and 'retreat' effects as well.
 7711
 7712        This does not affect whether the `TRIGGERS_DOMAIN` itself is
 7713        active (normally it would always be active).
 7714
 7715        Raises a `MissingDecisionError` if the specified trigger group
 7716        does not exist yet, including when the entire `TRIGGERS_DOMAIN`
 7717        does not exist. Raises a `KeyError` if the target group exists
 7718        but the `TRIGGERS_DOMAIN` has not been set up properly.
 7719        """
 7720        ctx = self.getCommonContext()
 7721        tID = self.getSituation().graph.resolveDecision(
 7722            base.DecisionSpecifier(TRIGGERS_DOMAIN, None, name)
 7723        )
 7724        activeGroups = ctx['activeDecisions'][TRIGGERS_DOMAIN]
 7725        assert isinstance(activeGroups, set)
 7726        if tID in activeGroups:
 7727            if setActive is not True:
 7728                activeGroups.remove(tID)
 7729        else:
 7730            if setActive is not False:
 7731                activeGroups.add(tID)
 7732
 7733    def getActiveDecisions(
 7734        self,
 7735        step: Optional[int] = None,
 7736        inCommon: Union[bool, Literal["both"]] = "both"
 7737    ) -> Set[base.DecisionID]:
 7738        """
 7739        Returns the set of active decisions at the given step index, or
 7740        at the current step if no step is specified. Raises an
 7741        `IndexError` if the step index is out of bounds (see `__len__`).
 7742        May return an empty set if no decisions are active.
 7743
 7744        If `inCommon` is set to "both" (the default) then decisions
 7745        active in either the common or active context are returned. Set
 7746        it to `True` or `False` to return only decisions active in the
 7747        common (when `True`) or  active (when `False`) context.
 7748        """
 7749        if step is None:
 7750            step = -1
 7751        state = self.getSituation(step).state
 7752        if inCommon == "both":
 7753            return base.combinedDecisionSet(state)
 7754        elif inCommon is True:
 7755            return base.activeDecisionSet(state['common'])
 7756        elif inCommon is False:
 7757            return base.activeDecisionSet(
 7758                state['contexts'][state['activeContext']]
 7759            )
 7760        else:
 7761            raise ValueError(
 7762                f"Invalid inCommon value {repr(inCommon)} (must be"
 7763                f" 'both', True, or False)."
 7764            )
 7765
 7766    def setActiveDecisionsAtStep(
 7767        self,
 7768        step: int,
 7769        domain: base.Domain,
 7770        activate: Union[
 7771            base.DecisionID,
 7772            Dict[base.FocalPointName, Optional[base.DecisionID]],
 7773            Set[base.DecisionID]
 7774        ],
 7775        inCommon: bool = False
 7776    ) -> None:
 7777        """
 7778        Changes the activation status of decisions in the active
 7779        `FocalContext` at the specified step, for the specified domain
 7780        (see `currentActiveContext`). Does this without adding an
 7781        exploration step, which is unusual: normally you should use
 7782        another method like `warp` to update active decisions.
 7783
 7784        Note that this does not change which domains are active, and
 7785        setting active decisions in inactive domains does not make those
 7786        decisions active overall.
 7787
 7788        Which decisions to activate or deactivate are specified as
 7789        either a single `DecisionID`, a list of them, or a set of them,
 7790        depending on the `DomainFocalization` setting in the selected
 7791        `FocalContext` for the specified domain. A `TypeError` will be
 7792        raised if the wrong kind of decision information is provided. If
 7793        the focalization context does not have any focalization value for
 7794        the domain in question, it will be set based on the kind of
 7795        active decision information specified.
 7796
 7797        A `MissingDecisionError` will be raised if a decision is
 7798        included which is not part of the current `DecisionGraph`.
 7799        The provided information will overwrite the previous active
 7800        decision information.
 7801
 7802        If `inCommon` is set to `True`, then decisions are activated or
 7803        deactivated in the common context, instead of in the active
 7804        context.
 7805
 7806        Example:
 7807
 7808        >>> e = DiscreteExploration()
 7809        >>> e.getActiveDecisions()
 7810        set()
 7811        >>> graph = e.getSituation().graph
 7812        >>> graph.addDecision('A')
 7813        0
 7814        >>> graph.addDecision('B')
 7815        1
 7816        >>> graph.addDecision('C')
 7817        2
 7818        >>> e.setActiveDecisionsAtStep(0, 'main', 0)
 7819        >>> e.getActiveDecisions()
 7820        {0}
 7821        >>> e.setActiveDecisionsAtStep(0, 'main', 1)
 7822        >>> e.getActiveDecisions()
 7823        {1}
 7824        >>> graph = e.getSituation().graph
 7825        >>> graph.addDecision('One', domain='numbers')
 7826        3
 7827        >>> graph.addDecision('Two', domain='numbers')
 7828        4
 7829        >>> graph.addDecision('Three', domain='numbers')
 7830        5
 7831        >>> graph.addDecision('Bear', domain='animals')
 7832        6
 7833        >>> graph.addDecision('Spider', domain='animals')
 7834        7
 7835        >>> graph.addDecision('Eel', domain='animals')
 7836        8
 7837        >>> ac = e.getActiveContext()
 7838        >>> ac['focalization']['numbers'] = 'plural'
 7839        >>> ac['focalization']['animals'] = 'spreading'
 7840        >>> ac['activeDecisions']['numbers'] = {'a': None, 'b': None}
 7841        >>> ac['activeDecisions']['animals'] = set()
 7842        >>> cc = e.getCommonContext()
 7843        >>> cc['focalization']['numbers'] = 'plural'
 7844        >>> cc['focalization']['animals'] = 'spreading'
 7845        >>> cc['activeDecisions']['numbers'] = {'z': None}
 7846        >>> cc['activeDecisions']['animals'] = set()
 7847        >>> e.setActiveDecisionsAtStep(0, 'numbers', {'a': 3, 'b': 3})
 7848        >>> e.getActiveDecisions()
 7849        {1}
 7850        >>> e.activateDomain('numbers')
 7851        >>> e.getActiveDecisions()
 7852        {1, 3}
 7853        >>> e.setActiveDecisionsAtStep(0, 'numbers', {'a': 4, 'b': None})
 7854        >>> e.getActiveDecisions()
 7855        {1, 4}
 7856        >>> # Wrong domain for the decision ID:
 7857        >>> e.setActiveDecisionsAtStep(0, 'main', 3)
 7858        Traceback (most recent call last):
 7859        ...
 7860        ValueError...
 7861        >>> # Wrong domain for one of the decision IDs:
 7862        >>> e.setActiveDecisionsAtStep(0, 'numbers', {'a': 2, 'b': None})
 7863        Traceback (most recent call last):
 7864        ...
 7865        ValueError...
 7866        >>> # Wrong kind of decision information provided.
 7867        >>> e.setActiveDecisionsAtStep(0, 'numbers', 3)
 7868        Traceback (most recent call last):
 7869        ...
 7870        TypeError...
 7871        >>> e.getActiveDecisions()
 7872        {1, 4}
 7873        >>> e.setActiveDecisionsAtStep(0, 'animals', {6, 7})
 7874        >>> e.getActiveDecisions()
 7875        {1, 4}
 7876        >>> e.activateDomain('animals')
 7877        >>> e.getActiveDecisions()
 7878        {1, 4, 6, 7}
 7879        >>> e.setActiveDecisionsAtStep(0, 'animals', {8})
 7880        >>> e.getActiveDecisions()
 7881        {8, 1, 4}
 7882        >>> e.setActiveDecisionsAtStep(1, 'main', 2)  # invalid step
 7883        Traceback (most recent call last):
 7884        ...
 7885        IndexError...
 7886        >>> e.setActiveDecisionsAtStep(0, 'novel', 0)  # domain mismatch
 7887        Traceback (most recent call last):
 7888        ...
 7889        ValueError...
 7890
 7891        Example of active/common contexts:
 7892
 7893        >>> e = DiscreteExploration()
 7894        >>> graph = e.getSituation().graph
 7895        >>> graph.addDecision('A')
 7896        0
 7897        >>> graph.addDecision('B')
 7898        1
 7899        >>> e.activateDomain('main', inContext="common")
 7900        >>> e.setActiveDecisionsAtStep(0, 'main', 0, inCommon=True)
 7901        >>> e.getActiveDecisions()
 7902        {0}
 7903        >>> e.setActiveDecisionsAtStep(0, 'main', None)
 7904        >>> e.getActiveDecisions()
 7905        {0}
 7906        >>> # (Still active since it's active in the common context)
 7907        >>> e.setActiveDecisionsAtStep(0, 'main', 1)
 7908        >>> e.getActiveDecisions()
 7909        {0, 1}
 7910        >>> e.setActiveDecisionsAtStep(0, 'main', 1, inCommon=True)
 7911        >>> e.getActiveDecisions()
 7912        {1}
 7913        >>> e.setActiveDecisionsAtStep(0, 'main', None, inCommon=True)
 7914        >>> e.getActiveDecisions()
 7915        {1}
 7916        >>> # (Still active since it's active in the active context)
 7917        >>> e.setActiveDecisionsAtStep(0, 'main', None)
 7918        >>> e.getActiveDecisions()
 7919        set()
 7920        """
 7921        now = self.getSituation(step)
 7922        graph = now.graph
 7923        if inCommon:
 7924            context = self.getCommonContext(step)
 7925        else:
 7926            context = self.getActiveContext(step)
 7927
 7928        defaultFocalization: base.DomainFocalization = 'singular'
 7929        if isinstance(activate, base.DecisionID):
 7930            defaultFocalization = 'singular'
 7931        elif isinstance(activate, dict):
 7932            defaultFocalization = 'plural'
 7933        elif isinstance(activate, set):
 7934            defaultFocalization = 'spreading'
 7935        elif domain not in context['focalization']:
 7936            raise TypeError(
 7937                f"Domain {domain!r} has no focalization in the"
 7938                f" {'common' if inCommon else 'active'} context,"
 7939                f" and the specified position doesn't imply one."
 7940            )
 7941
 7942        focalization = base.getDomainFocalization(
 7943            context,
 7944            domain,
 7945            defaultFocalization
 7946        )
 7947
 7948        # Check domain & existence of decision(s) in question
 7949        if activate is None:
 7950            pass
 7951        elif isinstance(activate, base.DecisionID):
 7952            if activate not in graph:
 7953                raise MissingDecisionError(
 7954                    f"There is no decision {activate} at step {step}."
 7955                )
 7956            if graph.domainFor(activate) != domain:
 7957                raise ValueError(
 7958                    f"Can't set active decisions in domain {domain!r}"
 7959                    f" to decision {graph.identityOf(activate)} because"
 7960                    f" that decision is in actually in domain"
 7961                    f" {graph.domainFor(activate)!r}."
 7962                )
 7963        elif isinstance(activate, dict):
 7964            for fpName, pos in activate.items():
 7965                if pos is None:
 7966                    continue
 7967                if pos not in graph:
 7968                    raise MissingDecisionError(
 7969                        f"There is no decision {pos} at step {step}."
 7970                    )
 7971                if graph.domainFor(pos) != domain:
 7972                    raise ValueError(
 7973                        f"Can't set active decision for focal point"
 7974                        f" {fpName!r} in domain {domain!r}"
 7975                        f" to decision {graph.identityOf(pos)} because"
 7976                        f" that decision is in actually in domain"
 7977                        f" {graph.domainFor(pos)!r}."
 7978                    )
 7979        elif isinstance(activate, set):
 7980            for pos in activate:
 7981                if pos not in graph:
 7982                    raise MissingDecisionError(
 7983                        f"There is no decision {pos} at step {step}."
 7984                    )
 7985                if graph.domainFor(pos) != domain:
 7986                    raise ValueError(
 7987                        f"Can't set {graph.identityOf(pos)} as an"
 7988                        f" active decision in domain {domain!r} to"
 7989                        f" decision because that decision is in"
 7990                        f" actually in domain {graph.domainFor(pos)!r}."
 7991                    )
 7992        else:
 7993            raise TypeError(
 7994                f"Domain {domain!r} has no focalization in the"
 7995                f" {'common' if inCommon else 'active'} context,"
 7996                f" and the specified position doesn't imply one:"
 7997                f"\n{activate!r}"
 7998            )
 7999
 8000        if focalization == 'singular':
 8001            if activate is None or isinstance(activate, base.DecisionID):
 8002                if activate is not None:
 8003                    targetDomain = graph.domainFor(activate)
 8004                    if activate not in graph:
 8005                        raise MissingDecisionError(
 8006                            f"There is no decision {activate} in the"
 8007                            f" graph at step {step}."
 8008                        )
 8009                    elif targetDomain != domain:
 8010                        raise ValueError(
 8011                            f"At step {step}, decision {activate} cannot"
 8012                            f" be the active decision for domain"
 8013                            f" {repr(domain)} because it is in a"
 8014                            f" different domain ({repr(targetDomain)})."
 8015                        )
 8016                context['activeDecisions'][domain] = activate
 8017            else:
 8018                raise TypeError(
 8019                    f"{'Common' if inCommon else 'Active'} focal"
 8020                    f" context at step {step} has {repr(focalization)}"
 8021                    f" focalization for domain {repr(domain)}, so the"
 8022                    f" active decision must be a single decision or"
 8023                    f" None.\n(You provided: {repr(activate)})"
 8024                )
 8025        elif focalization == 'plural':
 8026            if (
 8027                isinstance(activate, dict)
 8028            and all(
 8029                    isinstance(k, base.FocalPointName)
 8030                    for k in activate.keys()
 8031                )
 8032            and all(
 8033                    v is None or isinstance(v, base.DecisionID)
 8034                    for v in activate.values()
 8035                )
 8036            ):
 8037                for v in activate.values():
 8038                    if v is not None:
 8039                        targetDomain = graph.domainFor(v)
 8040                        if v not in graph:
 8041                            raise MissingDecisionError(
 8042                                f"There is no decision {v} in the graph"
 8043                                f" at step {step}."
 8044                            )
 8045                        elif targetDomain != domain:
 8046                            raise ValueError(
 8047                                f"At step {step}, decision {activate}"
 8048                                f" cannot be an active decision for"
 8049                                f" domain {repr(domain)} because it is"
 8050                                f" in a different domain"
 8051                                f" ({repr(targetDomain)})."
 8052                            )
 8053                context['activeDecisions'][domain] = activate
 8054            else:
 8055                raise TypeError(
 8056                    f"{'Common' if inCommon else 'Active'} focal"
 8057                    f" context at step {step} has {repr(focalization)}"
 8058                    f" focalization for domain {repr(domain)}, so the"
 8059                    f" active decision must be a dictionary mapping"
 8060                    f" focal point names to decision IDs (or Nones)."
 8061                    f"\n(You provided: {repr(activate)})"
 8062                )
 8063        elif focalization == 'spreading':
 8064            if (
 8065                isinstance(activate, set)
 8066            and all(isinstance(x, base.DecisionID) for x in activate)
 8067            ):
 8068                for x in activate:
 8069                    targetDomain = graph.domainFor(x)
 8070                    if x not in graph:
 8071                        raise MissingDecisionError(
 8072                            f"There is no decision {x} in the graph"
 8073                            f" at step {step}."
 8074                        )
 8075                    elif targetDomain != domain:
 8076                        raise ValueError(
 8077                            f"At step {step}, decision {activate}"
 8078                            f" cannot be an active decision for"
 8079                            f" domain {repr(domain)} because it is"
 8080                            f" in a different domain"
 8081                            f" ({repr(targetDomain)})."
 8082                        )
 8083                context['activeDecisions'][domain] = activate
 8084            else:
 8085                raise TypeError(
 8086                    f"{'Common' if inCommon else 'Active'} focal"
 8087                    f" context at step {step} has {repr(focalization)}"
 8088                    f" focalization for domain {repr(domain)}, so the"
 8089                    f" active decision must be a set of decision IDs"
 8090                    f"\n(You provided: {repr(activate)})"
 8091                )
 8092        else:
 8093            raise RuntimeError(
 8094                f"Invalid focalization value {repr(focalization)} for"
 8095                f" domain {repr(domain)} at step {step}."
 8096            )
 8097
 8098    def movementAtStep(self, step: int = -1) -> Tuple[
 8099        Union[base.DecisionID, Set[base.DecisionID], None],
 8100        Optional[base.Transition],
 8101        Union[base.DecisionID, Set[base.DecisionID], None]
 8102    ]:
 8103        """
 8104        Given a step number, returns information about the starting
 8105        decision, transition taken, and destination decision for that
 8106        step. Not all steps have all of those, so some items may be
 8107        `None`.
 8108
 8109        For steps where there is no action, where a decision is still
 8110        pending, or where the action type is 'focus', 'swap', 'focalize',
 8111        or 'revertTo', the result will be `(None, None, None)`, unless a
 8112        primary decision is available in which case the first item in the
 8113        tuple will be that decision. For 'start' actions, the starting
 8114        position and transition will be `None` (again unless the step had
 8115        a primary decision) but the destination will be the ID of the
 8116        node started at. For 'revertTo' actions, the destination will be
 8117        the primary decision of the state reverted to, if available.
 8118
 8119        Also, if the action taken has multiple potential or actual start
 8120        or end points, these may be sets of decision IDs instead of
 8121        single IDs.
 8122
 8123        Note that the primary decision of the starting state is usually
 8124        used as the from-decision, but in some cases an action dictates
 8125        taking a transition from a different decision, and this function
 8126        will return that decision as the from-decision.
 8127
 8128        TODO: Examples!
 8129
 8130        TODO: Account for bounce/follow/goto effects!!!
 8131        """
 8132        now = self.getSituation(step)
 8133        action = now.action
 8134        graph = now.graph
 8135        primary = now.state['primaryDecision']
 8136
 8137        if action is None:
 8138            return (primary, None, None)
 8139
 8140        aType = action[0]
 8141        fromID: Optional[base.DecisionID]
 8142        destID: Optional[base.DecisionID]
 8143        transition: base.Transition
 8144        outcomes: List[bool]
 8145
 8146        if aType in ('noAction', 'focus', 'swap', 'focalize'):
 8147            return (primary, None, None)
 8148        elif aType == 'start':
 8149            assert len(action) == 7
 8150            where = cast(
 8151                Union[
 8152                    base.DecisionID,
 8153                    Dict[base.FocalPointName, base.DecisionID],
 8154                    Set[base.DecisionID]
 8155                ],
 8156                action[1]
 8157            )
 8158            if isinstance(where, dict):
 8159                where = set(where.values())
 8160            return (primary, None, where)
 8161        elif aType in ('take', 'explore'):
 8162            if (
 8163                (len(action) == 4 or len(action) == 7)
 8164            and isinstance(action[2], base.DecisionID)
 8165            ):
 8166                fromID = action[2]
 8167                assert isinstance(action[3], tuple)
 8168                transition, outcomes = action[3]
 8169                if (
 8170                    action[0] == "explore"
 8171                and isinstance(action[4], base.DecisionID)
 8172                ):
 8173                    destID = action[4]
 8174                else:
 8175                    destID = graph.getDestination(fromID, transition)
 8176                return (fromID, transition, destID)
 8177            elif (
 8178                (len(action) == 3 or len(action) == 6)
 8179            and isinstance(action[1], tuple)
 8180            and isinstance(action[2], base.Transition)
 8181            and len(action[1]) == 3
 8182            and action[1][0] in get_args(base.ContextSpecifier)
 8183            and isinstance(action[1][1], base.Domain)
 8184            and isinstance(action[1][2], base.FocalPointName)
 8185            ):
 8186                fromID = base.resolvePosition(now.state, action[1])
 8187                if fromID is None:
 8188                    raise InvalidActionError(
 8189                        f"{aType!r} action at step {step} has position"
 8190                        f" {action[1]!r} which cannot be resolved to a"
 8191                        f" decision."
 8192                    )
 8193                transition, outcomes = action[2]
 8194                if (
 8195                    action[0] == "explore"
 8196                and isinstance(action[3], base.DecisionID)
 8197                ):
 8198                    destID = action[3]
 8199                else:
 8200                    destID = graph.getDestination(fromID, transition)
 8201                return (fromID, transition, destID)
 8202            else:
 8203                raise InvalidActionError(
 8204                    f"Malformed {aType!r} action:\n{repr(action)}"
 8205                )
 8206        elif aType == 'warp':
 8207            if len(action) != 3:
 8208                raise InvalidActionError(
 8209                    f"Malformed 'warp' action:\n{repr(action)}"
 8210                )
 8211            dest = action[2]
 8212            assert isinstance(dest, base.DecisionID)
 8213            if action[1] in get_args(base.ContextSpecifier):
 8214                # Unspecified starting point; find active decisions in
 8215                # same domain if primary is None
 8216                if primary is not None:
 8217                    return (primary, None, dest)
 8218                else:
 8219                    toDomain = now.graph.domainFor(dest)
 8220                    # TODO: Could check destination focalization here...
 8221                    active = self.getActiveDecisions(step)
 8222                    sameDomain = set(
 8223                        dID
 8224                        for dID in active
 8225                        if now.graph.domainFor(dID) == toDomain
 8226                    )
 8227                    if len(sameDomain) == 1:
 8228                        return (
 8229                            list(sameDomain)[0],
 8230                            None,
 8231                            dest
 8232                        )
 8233                    else:
 8234                        return (
 8235                            sameDomain,
 8236                            None,
 8237                            dest
 8238                        )
 8239            else:
 8240                if (
 8241                    not isinstance(action[1], tuple)
 8242                or not len(action[1]) == 3
 8243                or not action[1][0] in get_args(base.ContextSpecifier)
 8244                or not isinstance(action[1][1], base.Domain)
 8245                or not isinstance(action[1][2], base.FocalPointName)
 8246                ):
 8247                    raise InvalidActionError(
 8248                        f"Malformed 'warp' action:\n{repr(action)}"
 8249                    )
 8250                return (
 8251                    base.resolvePosition(now.state, action[1]),
 8252                    None,
 8253                    dest
 8254                )
 8255        elif aType == 'revertTo':
 8256            assert len(action) == 3  # type, save slot, & aspects
 8257            if primary is not None:
 8258                cameFrom = primary
 8259            nextSituation = self.getSituation(step + 1)
 8260            wentTo = nextSituation.state['primaryDecision']
 8261            return (primary, None, wentTo)
 8262        else:
 8263            raise InvalidActionError(
 8264                f"Action taken had invalid action type {repr(aType)}:"
 8265                f"\n{repr(action)}"
 8266            )
 8267
 8268    def latestStepWithDecision(
 8269        self,
 8270        dID: base.DecisionID,
 8271        startFrom: int = -1
 8272    ) -> int:
 8273        """
 8274        Scans backwards through exploration steps until it finds a graph
 8275        that contains a decision with the specified ID, and returns the
 8276        step number of that step. Instead of starting from the last step,
 8277        you can tell it to start from a different step (either positive
 8278        or negative index) via `startFrom`. Raises a
 8279        `MissingDecisionError` if there is no such step.
 8280        """
 8281        if startFrom < 0:
 8282            startFrom = len(self) + startFrom
 8283        for step in range(startFrom, -1, -1):
 8284            graph = self.getSituation(step).graph
 8285            try:
 8286                return step
 8287            except MissingDecisionError:
 8288                continue
 8289        raise MissingDecisionError(
 8290            f"Decision {dID!r} does not exist at any step of the"
 8291            f" exploration."
 8292        )
 8293
 8294    def latestDecisionInfo(self, dID: base.DecisionID) -> DecisionInfo:
 8295        """
 8296        Looks up decision info for the given decision in the latest step
 8297        in which that decision exists (which will usually be the final
 8298        exploration step, unless the decision was merged or otherwise
 8299        removed along the way). This will raise a `MissingDecisionError`
 8300        only if there is no step at which the specified decision exists.
 8301        """
 8302        for step in range(len(self) - 1, -1, -1):
 8303            graph = self.getSituation(step).graph
 8304            try:
 8305                return graph.decisionInfo(dID)
 8306            except MissingDecisionError:
 8307                continue
 8308        raise MissingDecisionError(
 8309            f"Decision {dID!r} does not exist at any step of the"
 8310            f" exploration."
 8311        )
 8312
 8313    def latestTransitionProperties(
 8314        self,
 8315        dID: base.DecisionID,
 8316        transition: base.Transition
 8317    ) -> TransitionProperties:
 8318        """
 8319        Looks up transition properties for the transition with the given
 8320        name outgoing from the decision with the given ID, in the latest
 8321        step in which a transiiton with that name from that decision
 8322        exists (which will usually be the final exploration step, unless
 8323        transitions get removed/renamed along the way). Note that because
 8324        a transition can be deleted and later added back (unlike
 8325        decisions where an ID will not be re-used), it's possible there
 8326        are two or more different transitions that meet the
 8327        specifications at different points in time, and this will always
 8328        return the properties of the last of them. This will raise a
 8329        `MissingDecisionError` if there is no step at which the specified
 8330        decision exists, and a `MissingTransitionError` if the target
 8331        decision exists at some step but never has a transition with the
 8332        specified name.
 8333        """
 8334        sawDecision: Optional[int] = None
 8335        for step in range(len(self) - 1, -1, -1):
 8336            graph = self.getSituation(step).graph
 8337            try:
 8338                return graph.getTransitionProperties(dID, transition)
 8339            except (MissingDecisionError, MissingTransitionError) as e:
 8340                if (
 8341                    sawDecision is None
 8342                and isinstance(e, MissingTransitionError)
 8343                ):
 8344                    sawDecision = step
 8345                continue
 8346        if sawDecision is None:
 8347            raise MissingDecisionError(
 8348                f"Decision {dID!r} does not exist at any step of the"
 8349                f" exploration."
 8350            )
 8351        else:
 8352            raise MissingTransitionError(
 8353                f"Decision {dID!r} does exist (last seen at step"
 8354                f" {sawDecision}) but it never has an outgoing"
 8355                f" transition named {transition!r}."
 8356            )
 8357
 8358    def tagStep(
 8359        self,
 8360        tagOrTags: Union[base.Tag, Dict[base.Tag, base.TagValue]],
 8361        tagValue: Union[
 8362            base.TagValue,
 8363            type[base.NoTagValue]
 8364        ] = base.NoTagValue,
 8365        step: int = -1
 8366    ) -> None:
 8367        """
 8368        Adds a tag (or multiple tags) to the current step, or to a
 8369        specific step if `n` is given as an integer rather than the
 8370        default `None`. A tag value should be supplied when a tag is
 8371        given (unless you want to use the default of `1`), but it's a
 8372        `ValueError` to supply a tag value when a dictionary of tags to
 8373        update is provided.
 8374        """
 8375        if isinstance(tagOrTags, base.Tag):
 8376            if tagValue is base.NoTagValue:
 8377                tagValue = 1
 8378
 8379            # Not sure why this is necessary...
 8380            tagValue = cast(base.TagValue, tagValue)
 8381
 8382            self.getSituation(step).tags.update({tagOrTags: tagValue})
 8383        else:
 8384            self.getSituation(step).tags.update(tagOrTags)
 8385
 8386    def annotateStep(
 8387        self,
 8388        annotationOrAnnotations: Union[
 8389            base.Annotation,
 8390            Sequence[base.Annotation]
 8391        ],
 8392        step: Optional[int] = None
 8393    ) -> None:
 8394        """
 8395        Adds an annotation to the current exploration step, or to a
 8396        specific step if `n` is given as an integer rather than the
 8397        default `None`.
 8398        """
 8399        if step is None:
 8400            step = -1
 8401        if isinstance(annotationOrAnnotations, base.Annotation):
 8402            self.getSituation(step).annotations.append(
 8403                annotationOrAnnotations
 8404            )
 8405        else:
 8406            self.getSituation(step).annotations.extend(
 8407                annotationOrAnnotations
 8408            )
 8409
 8410    def hasCapability(
 8411        self,
 8412        capability: base.Capability,
 8413        step: Optional[int] = None,
 8414        inCommon: Union[bool, Literal['both']] = "both"
 8415    ) -> bool:
 8416        """
 8417        Returns True if the player currently had the specified
 8418        capability, at the specified exploration step, and False
 8419        otherwise. Checks the current state if no step is given. Does
 8420        NOT return true if the game state means that the player has an
 8421        equivalent for that capability (see
 8422        `hasCapabilityOrEquivalent`).
 8423
 8424        Normally, `inCommon` is set to 'both' by default and so if
 8425        either the common `FocalContext` or the active one has the
 8426        capability, this will return `True`. `inCommon` may instead be
 8427        set to `True` or `False` to ask about just the common (or
 8428        active) focal context.
 8429        """
 8430        state = self.getSituation().state
 8431        commonCapabilities = state['common']['capabilities']\
 8432            ['capabilities']  # noqa
 8433        activeCapabilities = state['contexts'][state['activeContext']]\
 8434            ['capabilities']['capabilities']  # noqa
 8435
 8436        if inCommon == 'both':
 8437            return (
 8438                capability in commonCapabilities
 8439             or capability in activeCapabilities
 8440            )
 8441        elif inCommon is True:
 8442            return capability in commonCapabilities
 8443        elif inCommon is False:
 8444            return capability in activeCapabilities
 8445        else:
 8446            raise ValueError(
 8447                f"Invalid inCommon value (must be False, True, or"
 8448                f" 'both'; got {repr(inCommon)})."
 8449            )
 8450
 8451    def hasCapabilityOrEquivalent(
 8452        self,
 8453        capability: base.Capability,
 8454        step: Optional[int] = None,
 8455        location: Optional[Set[base.DecisionID]] = None
 8456    ) -> bool:
 8457        """
 8458        Works like `hasCapability`, but also returns `True` if the
 8459        player counts as having the specified capability via an equivalence
 8460        that's part of the current graph. As with `hasCapability`, the
 8461        optional `step` argument is used to specify which step to check,
 8462        with the current step being used as the default.
 8463
 8464        The `location` set can specify where to start looking for
 8465        mechanisms; if left unspecified active decisions for that step
 8466        will be used.
 8467        """
 8468        if step is None:
 8469            step = -1
 8470        if location is None:
 8471            location = self.getActiveDecisions(step)
 8472        situation = self.getSituation(step)
 8473        return base.hasCapabilityOrEquivalent(
 8474            capability,
 8475            base.RequirementContext(
 8476                state=situation.state,
 8477                graph=situation.graph,
 8478                searchFrom=location
 8479            )
 8480        )
 8481
 8482    def gainCapabilityNow(
 8483        self,
 8484        capability: base.Capability,
 8485        inCommon: bool = False
 8486    ) -> None:
 8487        """
 8488        Modifies the current game state to add the specified `Capability`
 8489        to the player's capabilities. No changes are made to the current
 8490        graph.
 8491
 8492        If `inCommon` is set to `True` (default is `False`) then the
 8493        capability will be added to the common `FocalContext` and will
 8494        therefore persist even when a focal context switch happens.
 8495        Normally, it will be added to the currently-active focal
 8496        context.
 8497        """
 8498        state = self.getSituation().state
 8499        if inCommon:
 8500            context = state['common']
 8501        else:
 8502            context = state['contexts'][state['activeContext']]
 8503        context['capabilities']['capabilities'].add(capability)
 8504
 8505    def loseCapabilityNow(
 8506        self,
 8507        capability: base.Capability,
 8508        inCommon: Union[bool, Literal['both']] = "both"
 8509    ) -> None:
 8510        """
 8511        Modifies the current game state to remove the specified `Capability`
 8512        from the player's capabilities. Does nothing if the player
 8513        doesn't already have that capability.
 8514
 8515        By default, this removes the capability from both the common
 8516        capabilities set and the active `FocalContext`'s capabilities
 8517        set, so that afterwards the player will definitely not have that
 8518        capability. However, if you set `inCommon` to either `True` or
 8519        `False`, it will remove the capability from just the common
 8520        capabilities set (if `True`) or just the active capabilities set
 8521        (if `False`). In these cases, removing the capability from just
 8522        one capability set will not actually remove it in terms of the
 8523        `hasCapability` result if it had been present in the other set.
 8524        Set `inCommon` to "both" to use the default behavior explicitly.
 8525        """
 8526        now = self.getSituation()
 8527        if inCommon in ("both", True):
 8528            context = now.state['common']
 8529            try:
 8530                context['capabilities']['capabilities'].remove(capability)
 8531            except KeyError:
 8532                pass
 8533        elif inCommon in ("both", False):
 8534            context = now.state['contexts'][now.state['activeContext']]
 8535            try:
 8536                context['capabilities']['capabilities'].remove(capability)
 8537            except KeyError:
 8538                pass
 8539        else:
 8540            raise ValueError(
 8541                f"Invalid inCommon value (must be False, True, or"
 8542                f" 'both'; got {repr(inCommon)})."
 8543            )
 8544
 8545    def tokenCountNow(self, tokenType: base.Token) -> Optional[int]:
 8546        """
 8547        Returns the number of tokens the player currently has of a given
 8548        type. Returns `None` if the player has never acquired or lost
 8549        tokens of that type.
 8550
 8551        This method adds together tokens from the common and active
 8552        focal contexts.
 8553        """
 8554        state = self.getSituation().state
 8555        commonContext = state['common']
 8556        activeContext = state['contexts'][state['activeContext']]
 8557        base = commonContext['capabilities']['tokens'].get(tokenType)
 8558        if base is None:
 8559            return activeContext['capabilities']['tokens'].get(tokenType)
 8560        else:
 8561            return base + activeContext['capabilities']['tokens'].get(
 8562                tokenType,
 8563                0
 8564            )
 8565
 8566    def adjustTokensNow(
 8567        self,
 8568        tokenType: base.Token,
 8569        amount: int,
 8570        inCommon: bool = False
 8571    ) -> None:
 8572        """
 8573        Modifies the current game state to add the specified number of
 8574        `Token`s of the given type to the player's tokens. No changes are
 8575        made to the current graph. Reduce the number of tokens by
 8576        supplying a negative amount; note that negative token amounts
 8577        are possible.
 8578
 8579        By default, the number of tokens for the current active
 8580        `FocalContext` will be adjusted. However, if `inCommon` is set
 8581        to `True`, then the number of tokens for the common context will
 8582        be adjusted instead.
 8583        """
 8584        # TODO: Custom token caps!
 8585        state = self.getSituation().state
 8586        if inCommon:
 8587            context = state['common']
 8588        else:
 8589            context = state['contexts'][state['activeContext']]
 8590        tokens = context['capabilities']['tokens']
 8591        tokens[tokenType] = tokens.get(tokenType, 0) + amount
 8592
 8593    def setTokensNow(
 8594        self,
 8595        tokenType: base.Token,
 8596        amount: int,
 8597        inCommon: bool = False
 8598    ) -> None:
 8599        """
 8600        Modifies the current game state to set number of `Token`s of the
 8601        given type to a specific amount, regardless of the old value. No
 8602        changes are made to the current graph.
 8603
 8604        By default this sets the number of tokens for the active
 8605        `FocalContext`. But if you set `inCommon` to `True`, it will
 8606        set the number of tokens in the common context instead.
 8607        """
 8608        # TODO: Custom token caps!
 8609        state = self.getSituation().state
 8610        if inCommon:
 8611            context = state['common']
 8612        else:
 8613            context = state['contexts'][state['activeContext']]
 8614        context['capabilities']['tokens'][tokenType] = amount
 8615
 8616    def lookupMechanism(
 8617        self,
 8618        mechanism: base.MechanismName,
 8619        step: Optional[int] = None,
 8620        where: Union[
 8621            Tuple[base.AnyDecisionSpecifier, Optional[base.Transition]],
 8622            Collection[base.AnyDecisionSpecifier],
 8623            None
 8624        ] = None
 8625    ) -> base.MechanismID:
 8626        """
 8627        Looks up a mechanism ID by name, in the graph for the specified
 8628        step. The `where` argument specifies where to start looking,
 8629        which helps disambiguate. It can be a tuple with a decision
 8630        specifier and `None` to start from a single decision, or with a
 8631        decision specifier and a transition name to start from either
 8632        end of that transition. It can also be `None` to look at global
 8633        mechanisms and then all decisions directly, although this
 8634        increases the chance of a `AmbiguousMechanismError`. Finally, it
 8635        can be some other non-tuple collection of decision specifiers to
 8636        start from that set.
 8637
 8638        If no step is specified, uses the current step.
 8639        """
 8640        if step is None:
 8641            step = -1
 8642        situation = self.getSituation(step)
 8643        graph = situation.graph
 8644        searchFrom: Collection[base.AnyDecisionSpecifier]
 8645        if where is None:
 8646            searchFrom = set()
 8647        elif isinstance(where, tuple):
 8648            if len(where) != 2:
 8649                raise ValueError(
 8650                    f"Mechanism lookup location was a tuple with an"
 8651                    f" invalid length (must be length-2 if it's a"
 8652                    f" tuple):\n  {repr(where)}"
 8653                )
 8654            where = cast(
 8655                Tuple[base.AnyDecisionSpecifier, Optional[base.Transition]],
 8656                where
 8657            )
 8658            if where[1] is None:
 8659                searchFrom = {graph.resolveDecision(where[0])}
 8660            else:
 8661                searchFrom = graph.bothEnds(where[0], where[1])
 8662        else:  # must be a collection of specifiers
 8663            searchFrom = cast(Collection[base.AnyDecisionSpecifier], where)
 8664        return graph.lookupMechanism(searchFrom, mechanism)
 8665
 8666    def mechanismState(
 8667        self,
 8668        mechanism: base.AnyMechanismSpecifier,
 8669        where: Optional[Set[base.DecisionID]] = None,
 8670        step: int = -1
 8671    ) -> Optional[base.MechanismState]:
 8672        """
 8673        Returns the current state for the specified mechanism (or the
 8674        state at the specified step if a step index is given). `where`
 8675        may be provided as a set of decision IDs to indicate where to
 8676        search for the named mechanism, or a mechanism ID may be provided
 8677        in the first place. Mechanism states are properties of a `State`
 8678        but are not associated with focal contexts.
 8679        """
 8680        situation = self.getSituation(step)
 8681        mID = situation.graph.resolveMechanism(mechanism, startFrom=where)
 8682        return situation.state['mechanisms'].get(
 8683            mID,
 8684            base.DEFAULT_MECHANISM_STATE
 8685        )
 8686
 8687    def setMechanismStateNow(
 8688        self,
 8689        mechanism: base.AnyMechanismSpecifier,
 8690        toState: base.MechanismState,
 8691        where: Optional[Set[base.DecisionID]] = None
 8692    ) -> None:
 8693        """
 8694        Sets the state of the specified mechanism to the specified
 8695        state. Mechanisms can only be in one state at once, so this
 8696        removes any previous states for that mechanism (note that via
 8697        equivalences multiple mechanism states can count as active).
 8698
 8699        The mechanism can be any kind of mechanism specifier (see
 8700        `base.AnyMechanismSpecifier`). If it's not a mechanism ID and
 8701        doesn't have its own position information, the 'where' argument
 8702        can be used to hint where to search for the mechanism.
 8703        """
 8704        now = self.getSituation()
 8705        mID = now.graph.resolveMechanism(mechanism, startFrom=where)
 8706        now.state['mechanisms'][mID] = toState
 8707
 8708    def skillLevel(
 8709        self,
 8710        skill: base.Skill,
 8711        step: Optional[int] = None
 8712    ) -> Optional[base.Level]:
 8713        """
 8714        Returns the skill level the player had in a given skill at a
 8715        given step, or for the current step if no step is specified.
 8716        Returns `None` if the player had never acquired or lost levels
 8717        in that skill before the specified step (skill level would count
 8718        as 0 in that case).
 8719
 8720        This method adds together levels from the common and active
 8721        focal contexts.
 8722        """
 8723        if step is None:
 8724            step = -1
 8725        state = self.getSituation(step).state
 8726        commonContext = state['common']
 8727        activeContext = state['contexts'][state['activeContext']]
 8728        base = commonContext['capabilities']['skills'].get(skill)
 8729        if base is None:
 8730            return activeContext['capabilities']['skills'].get(skill)
 8731        else:
 8732            return base + activeContext['capabilities']['skills'].get(
 8733                skill,
 8734                0
 8735            )
 8736
 8737    def adjustSkillLevelNow(
 8738        self,
 8739        skill: base.Skill,
 8740        levels: base.Level,
 8741        inCommon: bool = False
 8742    ) -> None:
 8743        """
 8744        Modifies the current game state to add the specified number of
 8745        `Level`s of the given skill. No changes are made to the current
 8746        graph. Reduce the skill level by supplying negative levels; note
 8747        that negative skill levels are possible.
 8748
 8749        By default, the skill level for the current active
 8750        `FocalContext` will be adjusted. However, if `inCommon` is set
 8751        to `True`, then the skill level for the common context will be
 8752        adjusted instead.
 8753        """
 8754        # TODO: Custom level caps?
 8755        state = self.getSituation().state
 8756        if inCommon:
 8757            context = state['common']
 8758        else:
 8759            context = state['contexts'][state['activeContext']]
 8760        skills = context['capabilities']['skills']
 8761        skills[skill] = skills.get(skill, 0) + levels
 8762
 8763    def setSkillLevelNow(
 8764        self,
 8765        skill: base.Skill,
 8766        level: base.Level,
 8767        inCommon: bool = False
 8768    ) -> None:
 8769        """
 8770        Modifies the current game state to set `Skill` `Level` for the
 8771        given skill, regardless of the old value. No changes are made to
 8772        the current graph.
 8773
 8774        By default this sets the skill level for the active
 8775        `FocalContext`. But if you set `inCommon` to `True`, it will set
 8776        the skill level in the common context instead.
 8777        """
 8778        # TODO: Custom level caps?
 8779        state = self.getSituation().state
 8780        if inCommon:
 8781            context = state['common']
 8782        else:
 8783            context = state['contexts'][state['activeContext']]
 8784        skills = context['capabilities']['skills']
 8785        skills[skill] = level
 8786
 8787    def updateRequirementNow(
 8788        self,
 8789        decision: base.AnyDecisionSpecifier,
 8790        transition: base.Transition,
 8791        requirement: Optional[base.Requirement]
 8792    ) -> None:
 8793        """
 8794        Updates the requirement for a specific transition in a specific
 8795        decision. Use `None` to remove the requirement for that edge.
 8796        """
 8797        if requirement is None:
 8798            requirement = base.ReqNothing()
 8799        self.getSituation().graph.setTransitionRequirement(
 8800            decision,
 8801            transition,
 8802            requirement
 8803        )
 8804
 8805    def isTraversable(
 8806        self,
 8807        decision: base.AnyDecisionSpecifier,
 8808        transition: base.Transition,
 8809        step: int = -1
 8810    ) -> bool:
 8811        """
 8812        Returns True if the specified transition from the specified
 8813        decision had its requirement satisfied by the game state at the
 8814        specified step (or at the current step if no step is specified).
 8815        Raises an `IndexError` if the specified step doesn't exist, and
 8816        a `KeyError` if the decision or transition specified does not
 8817        exist in the `DecisionGraph` at that step.
 8818        """
 8819        situation = self.getSituation(step)
 8820        req = situation.graph.getTransitionRequirement(decision, transition)
 8821        ctx = base.contextForTransition(situation, decision, transition)
 8822        fromID = situation.graph.resolveDecision(decision)
 8823        return (
 8824            req.satisfied(ctx)
 8825        and (fromID, transition) not in situation.state['deactivated']
 8826        )
 8827
 8828    def applyTransitionEffect(
 8829        self,
 8830        whichEffect: base.EffectSpecifier,
 8831        moveWhich: Optional[base.FocalPointName] = None
 8832    ) -> Optional[base.DecisionID]:
 8833        """
 8834        Applies an effect attached to a transition, taking charges and
 8835        delay into account based on the current `Situation`.
 8836        Modifies the effect's trigger count (but may not actually
 8837        trigger the effect if the charges and/or delay values indicate
 8838        not to; see `base.doTriggerEffect`).
 8839
 8840        If a specific focal point in a plural-focalized domain is
 8841        triggering the effect, the focal point name should be specified
 8842        via `moveWhich` so that goto `Effect`s can know which focal
 8843        point to move when it's not explicitly specified in the effect.
 8844        TODO: Test this!
 8845
 8846        Returns None most of the time, but if a 'goto', 'bounce', or
 8847        'follow' effect was applied, it returns the decision ID for that
 8848        effect's destination, which would override a transition's normal
 8849        destination. If it returns a destination ID, then the exploration
 8850        state will already have been updated to set the position there,
 8851        and further position updates are not needed.
 8852
 8853        Note that transition effects which update active decisions will
 8854        also update the exploration status of those decisions to
 8855        'exploring' if they had been in an unvisited status (see
 8856        `updatePosition` and `hasBeenVisited`).
 8857
 8858        Note: callers should immediately update situation-based variables
 8859        that might have been changes by a 'revert' effect.
 8860        """
 8861        now = self.getSituation()
 8862        effect, triggerCount = base.doTriggerEffect(
 8863            now.state,
 8864            now.graph,
 8865            whichEffect
 8866        )
 8867        if triggerCount is not None:
 8868            return self.applyExtraneousEffect(
 8869                effect,
 8870                where=whichEffect[:2],
 8871                moveWhich=moveWhich
 8872            )
 8873        else:
 8874            return None
 8875
 8876    def applyExtraneousEffect(
 8877        self,
 8878        effect: base.Effect,
 8879        where: Optional[
 8880            Tuple[base.AnyDecisionSpecifier, Optional[base.Transition]]
 8881        ] = None,
 8882        moveWhich: Optional[base.FocalPointName] = None,
 8883        challengePolicy: base.ChallengePolicy = "specified"
 8884    ) -> Optional[base.DecisionID]:
 8885        """
 8886        Applies a single extraneous effect to the state & graph,
 8887        *without* accounting for charges or delay values, since the
 8888        effect is not part of the graph (use `applyTransitionEffect` to
 8889        apply effects that are attached to transitions, which is almost
 8890        always the function you should be using). An associated
 8891        transition for the extraneous effect can be supplied using the
 8892        `where` argument, and effects like 'deactivate' and 'edit' will
 8893        affect it (but the effect's charges and delay values will still
 8894        be ignored).
 8895
 8896        If the effect would change the destination of a transition, the
 8897        altered destination ID is returned: 'bounce' effects return the
 8898        provided decision part of `where`, 'goto' effects return their
 8899        target, and 'follow' effects return the destination followed to
 8900        (possibly via chained follows in the extreme case). In all other
 8901        cases, `None` is returned indicating no change to a normal
 8902        destination.
 8903
 8904        If a specific focal point in a plural-focalized domain is
 8905        triggering the effect, the focal point name should be specified
 8906        via `moveWhich` so that goto `Effect`s can know which focal
 8907        point to move when it's not explicitly specified in the effect.
 8908        TODO: Test this!
 8909
 8910        Note that transition effects which update active decisions will
 8911        also update the exploration status of those decisions to
 8912        'exploring' if they had been in an unvisited status and will
 8913        remove any 'unconfirmed' tag they might still have (see
 8914        `updatePosition` and `hasBeenVisited`).
 8915
 8916        The given `challengePolicy` is applied when traversing further
 8917        transitions due to 'follow' effects.
 8918
 8919        Note: Anyone calling `applyExtraneousEffect` should update any
 8920        situation-based variables immediately after the call, as a
 8921        'revert' effect may have changed the current graph and/or state.
 8922        """
 8923        typ = effect['type']
 8924        value = effect['value']
 8925        applyTo = effect['applyTo']
 8926        inCommon = applyTo == 'common'
 8927
 8928        now = self.getSituation()
 8929
 8930        if where is not None:
 8931            if where[1] is not None:
 8932                searchFrom = now.graph.bothEnds(where[0], where[1])
 8933            else:
 8934                searchFrom = {now.graph.resolveDecision(where[0])}
 8935        else:
 8936            searchFrom = None
 8937
 8938        # Note: Delay and charges are ignored!
 8939
 8940        # If it's a simple effect, we can use
 8941        # `base.applySimpleEffectToState` to apply it:
 8942        if base.isSimple(effect):
 8943            # TODO: NOT THIS, since it applies only simple effects of
 8944            # followed transitions!!!
 8945            return base.applySimpleEffectToState(
 8946                now.state,
 8947                now.graph,
 8948                effect,
 8949                where,
 8950                moveWhich,
 8951                challengePolicy
 8952            )
 8953        else:
 8954            # TODO: HERE
 8955            if typ == "edit":
 8956                value = cast(List[List[commands.Command]], value)
 8957                # If there are no blocks, do nothing
 8958                if len(value) > 0:
 8959                    # Apply the first block of commands and then rotate the list
 8960                    scope: commands.Scope = {}
 8961                    if where is not None:
 8962                        here: base.DecisionID = now.graph.resolveDecision(
 8963                            where[0]
 8964                        )
 8965                        outwards: Optional[base.Transition] = where[1]
 8966                        scope['@'] = here
 8967                        scope['@t'] = outwards
 8968                        if outwards is not None:
 8969                            reciprocal = now.graph.getReciprocal(
 8970                                here,
 8971                                outwards
 8972                            )
 8973                            destination = now.graph.getDestination(
 8974                                here,
 8975                                outwards
 8976                            )
 8977                        else:
 8978                            reciprocal = None
 8979                            destination = None
 8980                        scope['@r'] = reciprocal
 8981                        scope['@d'] = destination
 8982                    self.runCommandBlock(value[0], scope)
 8983                    value.append(value.pop(0))
 8984
 8985            elif typ == "follow":
 8986                # TODO: Maybe this should remain a non-complex effect?
 8987                if applyTo == "both":
 8988                    raise ValueError(
 8989                        "Can't follow a transition in both common & active"
 8990                        " focal contexts."
 8991                    )
 8992
 8993                if where is None:
 8994                    raise ValueError(
 8995                        f"Can't follow transition {value!r} because there"
 8996                        f" is no position information when applying the"
 8997                        f" effect."
 8998                    )
 8999
 9000                if where[1] is not None:
 9001                    followFrom = now.graph.getDestination(where[0], where[1])
 9002                    if followFrom is None:
 9003                        raise ValueError(
 9004                            f"Can't follow transition {value!r} because the"
 9005                            f" position information specifies transition"
 9006                            f" {where[1]!r} from decision"
 9007                            f" {now.graph.identityOf(where[0])} but that"
 9008                            f" transition does not exist."
 9009                        )
 9010
 9011                else:
 9012                    followFrom = now.graph.resolveDecision(where[0])
 9013
 9014                following = cast(base.Transition, value)
 9015
 9016                followTo = now.graph.getDestination(followFrom, following)
 9017
 9018                if followTo is None:
 9019                    raise ValueError(
 9020                        f"Can't follow transition {following!r} because"
 9021                        f" that transition doesn't exist at the specified"
 9022                        f" destination {now.graph.identityOf(followFrom)}."
 9023                    )
 9024
 9025                if self.isTraversable(followFrom, following):  # skip if not
 9026                    # Perform initial position update before following new
 9027                    # transition:
 9028                    base.updatePosition(
 9029                        now.state,
 9030                        now.graph,
 9031                        followFrom,
 9032                        applyTo,
 9033                        moveWhich
 9034                    )
 9035
 9036                    # Apply consequences of followed transition
 9037                    fullFollowTo = self.applyTransitionConsequence(
 9038                        followFrom,
 9039                        following,
 9040                        moveWhich,
 9041                        challengePolicy
 9042                    )
 9043
 9044                    # Now update to end of followed transition
 9045                    if fullFollowTo is None:
 9046                        base.updatePosition(
 9047                            now.state,
 9048                            now.graph,
 9049                            followTo,
 9050                            applyTo,
 9051                            moveWhich
 9052                        )
 9053                        fullFollowTo = followTo
 9054
 9055                    # Skip the normal update: we've taken care of that
 9056                    # plus more
 9057                    return fullFollowTo
 9058                else:
 9059                    # Normal position updates still applies since follow
 9060                    # transition wasn't possible
 9061                    return None
 9062
 9063            elif typ == "save":
 9064                assert isinstance(value, base.SaveSlot)
 9065                now.saves[value] = copy.deepcopy((now.graph, now.state))
 9066
 9067            else:
 9068                raise ValueError(f"Invalid effect type {typ!r}.")
 9069
 9070        return None  # default return value if we didn't return above
 9071
 9072    def applyExtraneousConsequence(
 9073        self,
 9074        consequence: base.Consequence,
 9075        where: Optional[
 9076            Tuple[base.AnyDecisionSpecifier, Optional[base.Transition]]
 9077        ] = None,
 9078        moveWhich: Optional[base.FocalPointName] = None
 9079    ) -> Optional[base.DecisionID]:
 9080        """
 9081        Applies an extraneous consequence not associated with a
 9082        transition. Unlike `applyTransitionConsequence`, the provided
 9083        `base.Consequence` must already have observed outcomes (see
 9084        `base.observeChallengeOutcomes`). Returns the decision ID for a
 9085        decision implied by a goto, follow, or bounce effect, or `None`
 9086        if no effect implies a destination.
 9087
 9088        The `where` and `moveWhich` optional arguments specify which
 9089        decision and/or transition to use as the application position,
 9090        and/or which focal point to move. This affects mechanism lookup
 9091        as well as the end position when 'follow' effects are used.
 9092        Specifically:
 9093
 9094        - A 'follow' trigger will search for transitions to follow from
 9095            the destination of the specified transition, or if only a
 9096            decision was supplied, from that decision.
 9097        - Mechanism lookups will start with both ends of the specified
 9098            transition as their search field (or with just the specified
 9099            decision if no transition is included).
 9100
 9101        'bounce' effects will cause an error unless position information
 9102        is provided, and will set the position to the base decision
 9103        provided in `where`.
 9104
 9105        Note: callers should update any situation-based variables
 9106        immediately after calling this as a 'revert' effect could change
 9107        the current graph and/or state and other changes could get lost
 9108        if they get applied to a stale graph/state.
 9109
 9110        # TODO: Examples for goto and follow effects.
 9111        """
 9112        now = self.getSituation()
 9113        searchFrom = set()
 9114        if where is not None:
 9115            if where[1] is not None:
 9116                searchFrom = now.graph.bothEnds(where[0], where[1])
 9117            else:
 9118                searchFrom = {now.graph.resolveDecision(where[0])}
 9119
 9120        context = base.RequirementContext(
 9121            state=now.state,
 9122            graph=now.graph,
 9123            searchFrom=searchFrom
 9124        )
 9125
 9126        effectIndices = base.observedEffects(context, consequence)
 9127        destID = None
 9128        for index in effectIndices:
 9129            effect = base.consequencePart(consequence, index)
 9130            if not isinstance(effect, dict) or 'value' not in effect:
 9131                raise RuntimeError(
 9132                    f"Invalid effect index {index}: Consequence part at"
 9133                    f" that index is not an Effect. Got:\n{effect}"
 9134                )
 9135            effect = cast(base.Effect, effect)
 9136            destID = self.applyExtraneousEffect(
 9137                effect,
 9138                where,
 9139                moveWhich
 9140            )
 9141            # technically this variable is not used later in this
 9142            # function, but the `applyExtraneousEffect` call means it
 9143            # needs an update, so we're doing that in case someone later
 9144            # adds code to this function that uses 'now' after this
 9145            # point.
 9146            now = self.getSituation()
 9147
 9148        return destID
 9149
 9150    def applyTransitionConsequence(
 9151        self,
 9152        decision: base.AnyDecisionSpecifier,
 9153        transition: base.AnyTransition,
 9154        moveWhich: Optional[base.FocalPointName] = None,
 9155        policy: base.ChallengePolicy = "specified",
 9156        fromIndex: Optional[int] = None,
 9157        toIndex: Optional[int] = None
 9158    ) -> Optional[base.DecisionID]:
 9159        """
 9160        Applies the effects of the specified transition to the current
 9161        graph and state, possibly overriding observed outcomes using
 9162        outcomes specified as part of a `base.TransitionWithOutcomes`.
 9163
 9164        The `where` and `moveWhich` function serve the same purpose as
 9165        for `applyExtraneousEffect`. If `where` is `None`, then the
 9166        effects will be applied as extraneous effects, meaning that
 9167        their delay and charges values will be ignored and their trigger
 9168        count will not be tracked. If `where` is supplied
 9169
 9170        Returns either None to indicate that the position update for the
 9171        transition should apply as usual, or a decision ID indicating
 9172        another destination which has already been applied by a
 9173        transition effect.
 9174
 9175        If `fromIndex` and/or `toIndex` are specified, then only effects
 9176        which have indices between those two (inclusive) will be
 9177        applied, and other effects will neither apply nor be updated in
 9178        any way. Note that `onlyPart` does not override the challenge
 9179        policy: if the effects in the specified part are not applied due
 9180        to a challenge outcome, they still won't happen, including
 9181        challenge outcomes outside of that part. Also, outcomes for
 9182        challenges of the entire consequence are re-observed if the
 9183        challenge policy implies it.
 9184
 9185        Note: Anyone calling this should update any situation-based
 9186        variables immediately after the call, as a 'revert' effect may
 9187        have changed the current graph and/or state.
 9188        """
 9189        now = self.getSituation()
 9190        dID = now.graph.resolveDecision(decision)
 9191
 9192        transitionName, outcomes = base.nameAndOutcomes(transition)
 9193
 9194        searchFrom = set()
 9195        searchFrom = now.graph.bothEnds(dID, transitionName)
 9196
 9197        context = base.RequirementContext(
 9198            state=now.state,
 9199            graph=now.graph,
 9200            searchFrom=searchFrom
 9201        )
 9202
 9203        consequence = now.graph.getConsequence(dID, transitionName)
 9204
 9205        # Make sure that challenge outcomes are known
 9206        if policy != "specified":
 9207            base.resetChallengeOutcomes(consequence)
 9208        useUp = outcomes[:]
 9209        base.observeChallengeOutcomes(
 9210            context,
 9211            consequence,
 9212            location=searchFrom,
 9213            policy=policy,
 9214            knownOutcomes=useUp
 9215        )
 9216        if len(useUp) > 0:
 9217            raise ValueError(
 9218                f"More outcomes specified than challenges observed in"
 9219                f" consequence:\n{consequence}"
 9220                f"\nRemaining outcomes:\n{useUp}"
 9221            )
 9222
 9223        # Figure out which effects apply, and apply each of them
 9224        effectIndices = base.observedEffects(context, consequence)
 9225        if fromIndex is None:
 9226            fromIndex = 0
 9227
 9228        altDest = None
 9229        for index in effectIndices:
 9230            if (
 9231                index >= fromIndex
 9232            and (toIndex is None or index <= toIndex)
 9233            ):
 9234                thisDest = self.applyTransitionEffect(
 9235                    (dID, transitionName, index),
 9236                    moveWhich
 9237                )
 9238                if thisDest is not None:
 9239                    altDest = thisDest
 9240                # TODO: What if this updates state with 'revert' to a
 9241                # graph that doesn't contain the same effects?
 9242                # TODO: Update 'now' and 'context'?!
 9243        return altDest
 9244
 9245    def allDecisions(self) -> List[base.DecisionID]:
 9246        """
 9247        Returns the list of all decisions which existed at any point
 9248        within the exploration. Example:
 9249
 9250        >>> ex = DiscreteExploration()
 9251        >>> ex.start('A')
 9252        0
 9253        >>> ex.observe('A', 'right')
 9254        1
 9255        >>> ex.explore('right', 'B', 'left')
 9256        1
 9257        >>> ex.observe('B', 'right')
 9258        2
 9259        >>> ex.allDecisions()  # 'A', 'B', and the unnamed 'right of B'
 9260        [0, 1, 2]
 9261        """
 9262        seen = set()
 9263        result = []
 9264        for situation in self:
 9265            for decision in situation.graph:
 9266                if decision not in seen:
 9267                    result.append(decision)
 9268                    seen.add(decision)
 9269
 9270        return result
 9271
 9272    def allExploredDecisions(self) -> List[base.DecisionID]:
 9273        """
 9274        Returns the list of all decisions which existed at any point
 9275        within the exploration, excluding decisions whose highest
 9276        exploration status was `noticed` or lower. May still include
 9277        decisions which don't exist in the final situation's graph due to
 9278        things like decision merging. Example:
 9279
 9280        >>> ex = DiscreteExploration()
 9281        >>> idA = ex.start('A')
 9282        >>> idB = ex.observe('A', 'right')
 9283        >>> ex.explore('right', 'B', 'left') == idB
 9284        True
 9285        >>> idU = ex.observe('B', 'right')
 9286        >>> graph = ex.getSituation().graph
 9287        >>> idC = graph.addDecision('C')  # add isolated decision;
 9288        >>>                               # doesn't set status
 9289        >>> ex.hasBeenVisited('C')
 9290        False
 9291        >>> ex.allExploredDecisions() == [idA, idB]
 9292        True
 9293        >>> ex.setExplorationStatus('C', 'exploring')
 9294        >>> ex.allExploredDecisions() == [idA, idB, idC]
 9295        True
 9296        >>> ex.setExplorationStatus('A', 'explored')
 9297        >>> ex.allExploredDecisions() == [idA, idB, idC]
 9298        True
 9299        >>> ex.setExplorationStatus('A', 'unknown')
 9300        >>> # remains visisted in an earlier step
 9301        >>> ex.allExploredDecisions() == [idA, idB, idC]
 9302        True
 9303        >>> ex.setExplorationStatus('C', 'unknown')  # not explored earlier
 9304        >>> ex.allExploredDecisions() == [idA, idB]
 9305        True
 9306        """
 9307        seen = set()
 9308        result = []
 9309        for situation in self:
 9310            graph = situation.graph
 9311            for decision in graph:
 9312                if (
 9313                    decision not in seen
 9314                and base.hasBeenVisited(situation.state, decision)
 9315                ):
 9316                    result.append(decision)
 9317                    seen.add(decision)
 9318
 9319        return result
 9320
 9321    def allVisitedDecisions(self) -> List[base.DecisionID]:
 9322        """
 9323        Returns the list of all decisions which existed at any point
 9324        within the exploration and which were visited at least once.
 9325        Orders them in the same order they were visited in.
 9326
 9327        Usually all of these decisions will be present in the final
 9328        situation's graph, but sometimes merging or other factors means
 9329        there might be some that won't be. Being present on the game
 9330        state's 'active' list in a step for its domain is what counts as
 9331        "being visited," which means that nodes which were passed through
 9332        directly via a 'follow' effect won't be counted, for example.
 9333
 9334        This should usually correspond with the absence of the
 9335        'unconfirmed' tag.
 9336
 9337        Example:
 9338
 9339        >>> ex = DiscreteExploration()
 9340        >>> ex.start('A')
 9341        0
 9342        >>> ex.observe('A', 'right')
 9343        1
 9344        >>> ex.explore('right', 'B', 'left')
 9345        1
 9346        >>> ex.observe('B', 'right')
 9347        2
 9348        >>> ex.getSituation().graph.addDecision('C')  # add isolated decision
 9349        3
 9350        >>> av = ex.allVisitedDecisions()
 9351        >>> av
 9352        [0, 1]
 9353        >>> all(  # no decisions in the 'visited' list are tagged
 9354        ...     'unconfirmed' not in ex.getSituation().graph.decisionTags(d)
 9355        ...     for d in av
 9356        ... )
 9357        True
 9358        >>> graph = ex.getSituation().graph
 9359        >>> 'unconfirmed' in graph.decisionTags(0)
 9360        False
 9361        >>> 'unconfirmed' in graph.decisionTags(1)
 9362        False
 9363        >>> 'unconfirmed' in graph.decisionTags(2)
 9364        True
 9365        >>> 'unconfirmed' in graph.decisionTags(3)  # not tagged; not explored
 9366        False
 9367        """
 9368        seen = set()
 9369        result = []
 9370        for step in range(len(self)):
 9371            active = self.getActiveDecisions(step)
 9372            for dID in active:
 9373                if dID not in seen:
 9374                    result.append(dID)
 9375                    seen.add(dID)
 9376
 9377        return result
 9378
 9379    def allTransitions(self) -> List[
 9380        Tuple[base.DecisionID, base.Transition, base.DecisionID]
 9381    ]:
 9382        """
 9383        Returns the list of all transitions which existed at any point
 9384        within the exploration, as 3-tuples with source decision ID,
 9385        transition name, and destination decision ID. Note that since
 9386        transitions can be deleted or re-targeted, and a transition name
 9387        can be re-used after being deleted, things can get messy in the
 9388        edges cases (see `allFinalTransitions`). When the same transition
 9389        name is used in different steps with different decision targets,
 9390        we end up including each possible source-transition-destination
 9391        triple. Example:
 9392
 9393        >>> ex = DiscreteExploration()
 9394        >>> ex.start('A')
 9395        0
 9396        >>> ex.observe('A', 'right', None, 'return')
 9397        1
 9398        >>> ex.explore('right', 'B', 'left')
 9399        1
 9400        >>> ex.observe('B', 'right')
 9401        2
 9402        >>> ex.wait()  # leave behind a step where 'B' has a 'right'
 9403        >>> ex.primaryDecision(0)
 9404        >>> ex.primaryDecision(1)
 9405        0
 9406        >>> ex.primaryDecision(2)
 9407        1
 9408        >>> ex.primaryDecision(3)
 9409        1
 9410        >>> len(ex)
 9411        4
 9412        >>> ex[3].graph.removeDecision(2)  # delete 'right of B'
 9413        >>> ex.observe('B', 'down')
 9414        3
 9415        >>> # Decisions are: 'A', 'B', and the unnamed 'right of B'
 9416        >>> # (now-deleted), and the unnamed 'down from B'
 9417        >>> ex.allDecisions()
 9418        [0, 1, 2, 3]
 9419        >>> for tr in ex.allTransitions():
 9420        ...     print(tr)
 9421        ...
 9422        (0, 'right', 1)
 9423        (1, 'return', 0)
 9424        (1, 'left', 0)
 9425        (1, 'right', 2)
 9426        (1, 'down', 3)
 9427        >>> # Note transitions from now-deleted nodes, and 'return'
 9428        >>> # transitions for unexplored nodes before they get explored
 9429        """
 9430        seen = set()
 9431        result = []
 9432        for situation in self:
 9433            graph = situation.graph
 9434            for (src, dst, transition) in graph.allEdges():  # type:ignore
 9435                trans = (src, transition, dst)
 9436                if trans not in seen:
 9437                    result.append(trans)
 9438                    seen.add(trans)
 9439
 9440        return result
 9441
 9442    def allFinalTransitions(self) -> List[
 9443        Tuple[base.DecisionID, base.Transition]
 9444    ]:
 9445        """
 9446        Returns the list of all transitions which exist in the final
 9447        situation's graph, as 2-tuples of source decision ID and
 9448        transition name. Compare `allTransitions` which tracks all
 9449        transitions that existed at any point in the exploration.
 9450        
 9451        Example:
 9452
 9453        >>> ex = DiscreteExploration()
 9454        >>> ex.start('A')
 9455        0
 9456        >>> ex.observe('A', 'right', None, 'return')
 9457        1
 9458        >>> ex.explore('right', 'B', 'left')
 9459        1
 9460        >>> ex.observe('B', 'right')
 9461        2
 9462        >>> ex.wait()  # leave behind a step where 'B' has a 'right'
 9463        >>> ex.primaryDecision(0)
 9464        >>> ex.primaryDecision(1)
 9465        0
 9466        >>> ex.primaryDecision(2)
 9467        1
 9468        >>> ex.primaryDecision(3)
 9469        1
 9470        >>> len(ex)
 9471        4
 9472        >>> ex[3].graph.removeDecision(2)  # delete 'right of B'
 9473        >>> ex.observe('B', 'down')
 9474        3
 9475        >>> # Decisions are: 'A', 'B', and the unnamed 'right of B'
 9476        >>> # (now-deleted), and the unnamed 'down from B'
 9477        >>> ex.allDecisions()
 9478        [0, 1, 2, 3]
 9479        >>> for tr in ex.allFinalTransitions():
 9480        ...     print(tr)
 9481        ...
 9482        (0, 'right')
 9483        (1, 'left')
 9484        (1, 'down')
 9485        >>> # Note only transitions present in final graph
 9486        """
 9487        if len(self) == 0:
 9488            return []
 9489        graph = self[-1].graph;
 9490        result = []
 9491        seen = set()
 9492        for (src, dst, transition) in graph.allEdges():  # type:ignore
 9493            trans = (src, transition)
 9494            if trans not in seen:
 9495                result.append(trans)
 9496                seen.add(trans)
 9497
 9498        return result
 9499
 9500    def start(
 9501        self,
 9502        decision: base.AnyDecisionSpecifier,
 9503        startCapabilities: Optional[base.CapabilitySet] = None,
 9504        setMechanismStates: Optional[
 9505            Dict[base.MechanismID, base.MechanismState]
 9506        ] = None,
 9507        setCustomState: Optional[dict] = None,
 9508        decisionType: base.DecisionType = "imposed"
 9509    ) -> base.DecisionID:
 9510        """
 9511        Sets the initial position information for a newly-relevant
 9512        domain for the current focal context. Creates a new decision
 9513        if the decision is specified by name or `DecisionSpecifier` and
 9514        that decision doesn't already exist. Returns the decision ID for
 9515        the newly-placed decision (or for the specified decision if it
 9516        already existed).
 9517
 9518        Raises a `BadStart` error if the current focal context already
 9519        has position information for the specified domain.
 9520
 9521        - The given `startCapabilities` replaces any existing
 9522            capabilities for the current focal context, although you can
 9523            leave it as the default `None` to avoid that and retain any
 9524            capabilities that have been set up already.
 9525        - The given `setMechanismStates` and `setCustomState`
 9526            dictionaries override all previous mechanism states & custom
 9527            states in the new situation. Leave these as the default
 9528            `None` to maintain those states.
 9529        - If created, the decision will be placed in the DEFAULT_DOMAIN
 9530            domain unless it's specified as a `base.DecisionSpecifier`
 9531            with a domain part, in which case that domain is used.
 9532        - If specified as a `base.DecisionSpecifier` with a zone part
 9533            and a new decision needs to be created, the decision will be
 9534            added to that zone, creating it at level 0 if necessary,
 9535            although otherwise no zone information will be changed.
 9536        - Resets the decision type to "pending" and the action taken to
 9537            `None`. Sets the decision type of the previous situation to
 9538            'imposed' (or the specified `decisionType`) and sets an
 9539            appropriate 'start' action for that situation.
 9540        - Tags the step with 'start'.
 9541        - Even in a plural- or spreading-focalized domain, you still need
 9542            to pick one decision to start at.
 9543        """
 9544        now = self.getSituation()
 9545
 9546        startID = now.graph.getDecision(decision)
 9547        zone = None
 9548        domain = base.DEFAULT_DOMAIN
 9549        if startID is None:
 9550            if isinstance(decision, base.DecisionID):
 9551                raise MissingDecisionError(
 9552                    f"Cannot start at decision {decision} because no"
 9553                    f" decision with that ID exists. Supply a name or"
 9554                    f" DecisionSpecifier if you need the start decision"
 9555                    f" to be created automatically."
 9556                )
 9557            elif isinstance(decision, base.DecisionName):
 9558                decision = base.DecisionSpecifier(
 9559                    domain=None,
 9560                    zone=None,
 9561                    name=decision
 9562                )
 9563            startID = now.graph.addDecision(
 9564                decision.name,
 9565                domain=decision.domain
 9566            )
 9567            zone = decision.zone
 9568            if decision.domain is not None:
 9569                domain = decision.domain
 9570
 9571        if zone is not None:
 9572            if now.graph.getZoneInfo(zone) is None:
 9573                now.graph.createZone(zone, 0)
 9574            now.graph.addDecisionToZone(startID, zone)
 9575
 9576        action: base.ExplorationAction = (
 9577            'start',
 9578            startID,
 9579            startID,
 9580            domain,
 9581            startCapabilities,
 9582            setMechanismStates,
 9583            setCustomState
 9584        )
 9585
 9586        self.advanceSituation(action, decisionType)
 9587
 9588        return startID
 9589
 9590    def hasBeenVisited(
 9591        self,
 9592        decision: base.AnyDecisionSpecifier,
 9593        step: int = -1
 9594    ):
 9595        """
 9596        Returns whether or not the specified decision has been visited in
 9597        or prior to the specified step (default current step).
 9598        """
 9599        situation = self.getSituation(step)
 9600        return base.hasBeenVisited(
 9601            situation.state,
 9602            situation.graph.resolveDecision(decision)
 9603        )
 9604
 9605    def setExplorationStatus(
 9606        self,
 9607        decision: base.AnyDecisionSpecifier,
 9608        status: base.ExplorationStatus,
 9609        upgradeOnly: bool = False
 9610    ):
 9611        """
 9612        Updates the current exploration status of a specific decision in
 9613        the current situation. If `upgradeOnly` is true (default is
 9614        `False` then the update will only apply if the new exploration
 9615        status counts as 'more-explored' than the old one (see
 9616        `base.moreExplored`).
 9617        """
 9618        now = self.getSituation()
 9619        base.setExplorationStatus(
 9620            now.state,
 9621            now.graph.resolveDecision(decision),
 9622            status,
 9623            upgradeOnly
 9624        )
 9625
 9626    def getExplorationStatus(
 9627        self,
 9628        decision: base.AnyDecisionSpecifier,
 9629        step: int = -1
 9630    ):
 9631        """
 9632        Returns the exploration status of the specified decision at the
 9633        specified step (default is last step). Decisions whose
 9634        exploration status has never been set will have a default status
 9635        of 'unknown'.
 9636        """
 9637        situation = self.getSituation(step)
 9638        dID = situation.graph.resolveDecision(decision)
 9639        return base.explorationStatusOf(
 9640            situation.state,
 9641            dID,
 9642            default='unknown'
 9643        )
 9644
 9645    def deduceTransitionDetailsAtStep(
 9646        self,
 9647        step: int,
 9648        transition: base.Transition,
 9649        fromDecision: Optional[base.AnyDecisionSpecifier] = None,
 9650        whichFocus: Optional[base.FocalPointSpecifier] = None,
 9651        inCommon: Union[bool, Literal["auto"]] = "auto"
 9652    ) -> Tuple[
 9653        base.ContextSpecifier,
 9654        base.DecisionID,
 9655        base.DecisionID,
 9656        Optional[base.FocalPointSpecifier]
 9657    ]:
 9658        """
 9659        Given just a transition name which the player intends to take in
 9660        a specific step, deduces the `ContextSpecifier` for which
 9661        context should be updated, the source and destination
 9662        `DecisionID`s for the transition, and if the destination
 9663        decision's domain is plural-focalized, the `FocalPointName`
 9664        specifying which focal point should be moved.
 9665
 9666        Because many of those things are ambiguous, you may get an
 9667        `AmbiguousTransitionError` when things are underspecified, and
 9668        there are options for specifying some of the extra information
 9669        directly:
 9670
 9671        - `fromDecision` may be used to specify the source decision.
 9672        - `whichFocus` may be used to specify the focal point (within a
 9673            particular context/domain) being updated. When focal point
 9674            ambiguity remains and this is unspecified, the
 9675            alphabetically-earliest relevant focal point will be used
 9676            (either among all focal points which activate the source
 9677            decision, if there are any, or among all focal points for
 9678            the entire domain of the destination decision).
 9679        - `inCommon` (a `ContextSpecifier`) may be used to specify which
 9680            context to update. The default of "auto" will cause the
 9681            active context to be selected unless it does not activate
 9682            the source decision, in which case the common context will
 9683            be selected.
 9684
 9685        A `MissingDecisionError` will be raised if there are no current
 9686        active decisions (e.g., before `start` has been called), and a
 9687        `MissingTransitionError` will be raised if the listed transition
 9688        does not exist from any active decision (or from the specified
 9689        decision if `fromDecision` is used).
 9690        """
 9691        now = self.getSituation(step)
 9692        active = self.getActiveDecisions(step)
 9693        if len(active) == 0:
 9694            raise MissingDecisionError(
 9695                f"There are no active decisions from which transition"
 9696                f" {repr(transition)} could be taken at step {step}."
 9697            )
 9698
 9699        # All source/destination decision pairs for transitions with the
 9700        # given transition name.
 9701        allDecisionPairs: Dict[base.DecisionID, base.DecisionID] = {}
 9702
 9703        # TODO: When should we be trimming the active decisions to match
 9704        # any alterations to the graph?
 9705        for dID in active:
 9706            outgoing = now.graph.destinationsFrom(dID)
 9707            if transition in outgoing:
 9708                allDecisionPairs[dID] = outgoing[transition]
 9709
 9710        if len(allDecisionPairs) == 0:
 9711            raise MissingTransitionError(
 9712                f"No transitions named {repr(transition)} are outgoing"
 9713                f" from active decisions at step {step}."
 9714                f"\nActive decisions are:"
 9715                f"\n{now.graph.namesListing(active)}"
 9716            )
 9717
 9718        if (
 9719            fromDecision is not None
 9720        and fromDecision not in allDecisionPairs
 9721        ):
 9722            raise MissingTransitionError(
 9723                f"{fromDecision} was specified as the source decision"
 9724                f" for traversing transition {repr(transition)} but"
 9725                f" there is no transition of that name from that"
 9726                f" decision at step {step}."
 9727                f"\nValid source decisions are:"
 9728                f"\n{now.graph.namesListing(allDecisionPairs)}"
 9729            )
 9730        elif fromDecision is not None:
 9731            fromID = now.graph.resolveDecision(fromDecision)
 9732            destID = allDecisionPairs[fromID]
 9733            fromDomain = now.graph.domainFor(fromID)
 9734        elif len(allDecisionPairs) == 1:
 9735            fromID, destID = list(allDecisionPairs.items())[0]
 9736            fromDomain = now.graph.domainFor(fromID)
 9737        else:
 9738            fromID = None
 9739            destID = None
 9740            fromDomain = None
 9741            # Still ambiguous; resolve this below
 9742
 9743        # Use whichFocus if provided
 9744        if whichFocus is not None:
 9745            # Type/value check for whichFocus
 9746            if (
 9747                not isinstance(whichFocus, tuple)
 9748             or len(whichFocus) != 3
 9749             or whichFocus[0] not in ("active", "common")
 9750             or not isinstance(whichFocus[1], base.Domain)
 9751             or not isinstance(whichFocus[2], base.FocalPointName)
 9752            ):
 9753                raise ValueError(
 9754                    f"Invalid whichFocus value {repr(whichFocus)}."
 9755                    f"\nMust be a length-3 tuple with 'active' or 'common'"
 9756                    f" as the first element, a Domain as the second"
 9757                    f" element, and a FocalPointName as the third"
 9758                    f" element."
 9759                )
 9760
 9761            # Resolve focal point specified
 9762            fromID = base.resolvePosition(
 9763                now.state,
 9764                whichFocus
 9765            )
 9766            if fromID is None:
 9767                raise MissingTransitionError(
 9768                    f"Focal point {repr(whichFocus)} was specified as"
 9769                    f" the transition source, but that focal point does"
 9770                    f" not have a position."
 9771                )
 9772            else:
 9773                destID = now.graph.destination(fromID, transition)
 9774                fromDomain = now.graph.domainFor(fromID)
 9775
 9776        elif fromID is None:  # whichFocus is None, so it can't disambiguate
 9777            raise AmbiguousTransitionError(
 9778                f"Transition {repr(transition)} was selected for"
 9779                f" disambiguation, but there are multiple transitions"
 9780                f" with that name from currently-active decisions, and"
 9781                f" neither fromDecision nor whichFocus adequately"
 9782                f" disambiguates the specific transition taken."
 9783                f"\nValid source decisions at step {step} are:"
 9784                f"\n{now.graph.namesListing(allDecisionPairs)}"
 9785            )
 9786
 9787        # At this point, fromID, destID, and fromDomain have
 9788        # been resolved.
 9789        if fromID is None or destID is None or fromDomain is None:
 9790            raise RuntimeError(
 9791                f"One of fromID, destID, or fromDomain was None after"
 9792                f" disambiguation was finished:"
 9793                f"\nfromID: {fromID}, destID: {destID}, fromDomain:"
 9794                f" {repr(fromDomain)}"
 9795            )
 9796
 9797        # Now figure out which context activated the source so we know
 9798        # which focal point we're moving:
 9799        context = self.getActiveContext()
 9800        active = base.activeDecisionSet(context)
 9801        using: base.ContextSpecifier = "active"
 9802        if fromID not in active:
 9803            context = self.getCommonContext(step)
 9804            using = "common"
 9805
 9806        destDomain = now.graph.domainFor(destID)
 9807        if (
 9808            whichFocus is None
 9809        and base.getDomainFocalization(context, destDomain) == 'plural'
 9810        ):
 9811            # Need to figure out which focal point is moving; use the
 9812            # alphabetically earliest one that's positioned at the
 9813            # fromID, or just the earliest one overall if none of them
 9814            # are there.
 9815            contextFocalPoints: Dict[
 9816                base.FocalPointName,
 9817                Optional[base.DecisionID]
 9818            ] = cast(
 9819                Dict[base.FocalPointName, Optional[base.DecisionID]],
 9820                context['activeDecisions'][destDomain]
 9821            )
 9822            if not isinstance(contextFocalPoints, dict):
 9823                raise RuntimeError(
 9824                    f"Active decisions specifier for domain"
 9825                    f" {repr(destDomain)} with plural focalization has"
 9826                    f" a non-dictionary value."
 9827                )
 9828
 9829            if fromDomain == destDomain:
 9830                focalCandidates = [
 9831                    fp
 9832                    for fp, pos in contextFocalPoints.items()
 9833                    if pos == fromID
 9834                ]
 9835            else:
 9836                focalCandidates = list(contextFocalPoints)
 9837
 9838            whichFocus = (using, destDomain, min(focalCandidates))
 9839
 9840        # Now whichFocus has been set if it wasn't already specified;
 9841        # might still be None if it's not relevant.
 9842        return (using, fromID, destID, whichFocus)
 9843
 9844    def advanceSituation(
 9845        self,
 9846        action: base.ExplorationAction,
 9847        decisionType: base.DecisionType = "active",
 9848        challengePolicy: base.ChallengePolicy = "specified"
 9849    ) -> Tuple[base.Situation, Set[base.DecisionID]]:
 9850        """
 9851        Given an `ExplorationAction`, sets that as the action taken in
 9852        the current situation, and adds a new situation with the results
 9853        of that action. A `DoubleActionError` will be raised if the
 9854        current situation already has an action specified, and/or has a
 9855        decision type other than 'pending'. By default the type of the
 9856        decision will be 'active' but another `DecisionType` can be
 9857        specified via the `decisionType` parameter.
 9858
 9859        If the action specified is `('noAction',)`, then the new
 9860        situation will be a copy of the old one; this represents waiting
 9861        or being at an ending (a decision type other than 'pending'
 9862        should be used).
 9863
 9864        Although `None` can appear as the action entry in situations
 9865        with pending decisions, you cannot call `advanceSituation` with
 9866        `None` as the action.
 9867
 9868        If the action includes taking a transition whose requirements
 9869        are not satisfied, the transition will still be taken (and any
 9870        consequences applied) but a `TransitionBlockedWarning` will be
 9871        issued.
 9872
 9873        A `ChallengePolicy` may be specified, the default is 'specified'
 9874        which requires that outcomes are pre-specified. If any other
 9875        policy is set, the challenge outcomes will be reset before
 9876        re-resolving them according to the provided policy.
 9877
 9878        The new situation will have decision type 'pending' and `None`
 9879        as the action.
 9880
 9881        The new situation created as a result of the action is returned,
 9882        along with the set of destination decision IDs, including
 9883        possibly a modified destination via 'bounce', 'goto', and/or
 9884        'follow' effects. For actions that don't have a destination, the
 9885        second part of the returned tuple will be an empty set. Multiple
 9886        IDs may be in the set when using a start action in a plural- or
 9887        spreading-focalized domain, for example.
 9888
 9889        If the action updates active decisions (including via transition
 9890        effects) this will also update the exploration status of those
 9891        decisions to 'exploring' if they had been in an unvisited
 9892        status (see `updatePosition` and `hasBeenVisited`). This
 9893        includes decisions traveled through but not ultimately arrived
 9894        at via 'follow' effects. These will also lose any 'unconfirmed'
 9895        tags they might have had.
 9896
 9897        If any decisions are active in the `ENDINGS_DOMAIN`, attempting
 9898        to 'warp', 'explore', 'take', or 'start' will raise an
 9899        `InvalidActionError`.
 9900        """
 9901        now = self.getSituation()
 9902        if now.type != 'pending' or now.action is not None:
 9903            raise DoubleActionError(
 9904                f"Attempted to take action {repr(action)} at step"
 9905                f" {len(self) - 1}, but an action and/or decision type"
 9906                f" had already been specified:"
 9907                f"\nAction: {repr(now.action)}"
 9908                f"\nType: {repr(now.type)}"
 9909            )
 9910
 9911        # Update the now situation to add in the decision type and
 9912        # action taken:
 9913        revised = base.Situation(
 9914            now.graph,
 9915            now.state,
 9916            decisionType,
 9917            action,
 9918            now.saves,
 9919            now.tags,
 9920            now.annotations
 9921        )
 9922        self.situations[-1] = revised
 9923
 9924        # Separate update process when reverting (this branch returns)
 9925        if (
 9926            action is not None
 9927        and isinstance(action, tuple)
 9928        and len(action) == 3
 9929        and action[0] == 'revertTo'
 9930        and isinstance(action[1], base.SaveSlot)
 9931        and isinstance(action[2], set)
 9932        and all(isinstance(x, str) for x in action[2])
 9933        ):
 9934            _, slot, aspects = action
 9935            if slot not in now.saves:
 9936                raise KeyError(
 9937                    f"Cannot load save slot {slot!r} because no save"
 9938                    f" data has been established for that slot."
 9939                )
 9940            load = now.saves[slot]
 9941            rGraph, rState = base.revertedState(
 9942                (now.graph, now.state),
 9943                load,
 9944                aspects
 9945            )
 9946            reverted = base.Situation(
 9947                graph=rGraph,
 9948                state=rState,
 9949                type='pending',
 9950                action=None,
 9951                saves=copy.deepcopy(now.saves),
 9952                tags={},
 9953                annotations=[]
 9954            )
 9955            self.situations.append(reverted)
 9956            # Apply any active triggers (edits reverted)
 9957            self.applyActiveTriggers()
 9958            # Figure out destinations set to return
 9959            newDestinations = set()
 9960            newPr = rState['primaryDecision']
 9961            if newPr is not None:
 9962                newDestinations.add(newPr)
 9963            return (reverted, newDestinations)
 9964
 9965        # TODO: These deep copies are expensive time-wise. Can we avoid
 9966        # them? Probably not.
 9967        newGraph = copy.deepcopy(now.graph)
 9968        newState = copy.deepcopy(now.state)
 9969        newSaves = copy.copy(now.saves)  # a shallow copy
 9970        newTags: Dict[base.Tag, base.TagValue] = {}
 9971        newAnnotations: List[base.Annotation] = []
 9972        updated = base.Situation(
 9973            graph=newGraph,
 9974            state=newState,
 9975            type='pending',
 9976            action=None,
 9977            saves=newSaves,
 9978            tags=newTags,
 9979            annotations=newAnnotations
 9980        )
 9981
 9982        targetContext: base.FocalContext
 9983
 9984        # Now that action effects have been imprinted into the updated
 9985        # situation, append it to our situations list
 9986        self.situations.append(updated)
 9987
 9988        # Figure out effects of the action:
 9989        if action is None:
 9990            raise InvalidActionError(
 9991                "None cannot be used as an action when advancing the"
 9992                " situation."
 9993            )
 9994
 9995        aLen = len(action)
 9996
 9997        destIDs = set()
 9998
 9999        if (
10000            action[0] in ('start', 'take', 'explore', 'warp')
10001        and any(
10002                newGraph.domainFor(d) == ENDINGS_DOMAIN
10003                for d in self.getActiveDecisions()
10004            )
10005        ):
10006            activeEndings = [
10007                d
10008                for d in self.getActiveDecisions()
10009                if newGraph.domainFor(d) == ENDINGS_DOMAIN
10010            ]
10011            raise InvalidActionError(
10012                f"Attempted to {action[0]!r} while an ending was"
10013                f" active. Active endings are:"
10014                f"\n{newGraph.namesListing(activeEndings)}"
10015            )
10016
10017        if action == ('noAction',):
10018            # No updates needed
10019            pass
10020
10021        elif (
10022            not isinstance(action, tuple)
10023         or (action[0] not in get_args(base.ExplorationActionType))
10024         or not (2 <= aLen <= 7)
10025        ):
10026            raise InvalidActionError(
10027                f"Invalid ExplorationAction tuple (must be a tuple that"
10028                f" starts with an ExplorationActionType and has 2-6"
10029                f" entries if it's not ('noAction',)):"
10030                f"\n{repr(action)}"
10031            )
10032
10033        elif action[0] == 'start':
10034            (
10035                _,
10036                positionSpecifier,
10037                primary,
10038                domain,
10039                capabilities,
10040                mechanismStates,
10041                customState
10042            ) = cast(
10043                Tuple[
10044                    Literal['start'],
10045                    Union[
10046                        base.DecisionID,
10047                        Dict[base.FocalPointName, base.DecisionID],
10048                        Set[base.DecisionID]
10049                    ],
10050                    Optional[base.DecisionID],
10051                    base.Domain,
10052                    Optional[base.CapabilitySet],
10053                    Optional[Dict[base.MechanismID, base.MechanismState]],
10054                    Optional[dict]
10055                ],
10056                action
10057            )
10058            targetContext = newState['contexts'][
10059                newState['activeContext']
10060            ]
10061
10062            targetFocalization = base.getDomainFocalization(
10063                targetContext,
10064                domain
10065            )  # sets up 'singular' as default if
10066
10067            # Check if there are any already-active decisions.
10068            if targetContext['activeDecisions'][domain] is not None:
10069                raise BadStart(
10070                    f"Cannot start in domain {repr(domain)} because"
10071                    f" that domain already has a position. 'start' may"
10072                    f" only be used with domains that don't yet have"
10073                    f" any position information."
10074                )
10075
10076            # Make the domain active
10077            if domain not in targetContext['activeDomains']:
10078                targetContext['activeDomains'].add(domain)
10079
10080            # Check position info matches focalization type and update
10081            # exploration statuses
10082            if isinstance(positionSpecifier, base.DecisionID):
10083                if targetFocalization != 'singular':
10084                    raise BadStart(
10085                        f"Invalid position specifier"
10086                        f" {repr(positionSpecifier)} (type"
10087                        f" {type(positionSpecifier)}). Domain"
10088                        f" {repr(domain)} has {targetFocalization}"
10089                        f" focalization."
10090                    )
10091                base.setExplorationStatus(
10092                    updated.state,
10093                    updated.graph.resolveDecision(positionSpecifier),
10094                    'exploring',
10095                    upgradeOnly=True
10096                )
10097                destIDs.add(positionSpecifier)
10098            elif isinstance(positionSpecifier, dict):
10099                if targetFocalization != 'plural':
10100                    raise BadStart(
10101                        f"Invalid position specifier"
10102                        f" {repr(positionSpecifier)} (type"
10103                        f" {type(positionSpecifier)}). Domain"
10104                        f" {repr(domain)} has {targetFocalization}"
10105                        f" focalization."
10106                    )
10107                destIDs |= set(positionSpecifier.values())
10108            elif isinstance(positionSpecifier, set):
10109                if targetFocalization != 'spreading':
10110                    raise BadStart(
10111                        f"Invalid position specifier"
10112                        f" {repr(positionSpecifier)} (type"
10113                        f" {type(positionSpecifier)}). Domain"
10114                        f" {repr(domain)} has {targetFocalization}"
10115                        f" focalization."
10116                    )
10117                destIDs |= positionSpecifier
10118            else:
10119                raise TypeError(
10120                    f"Invalid position specifier"
10121                    f" {repr(positionSpecifier)} (type"
10122                    f" {type(positionSpecifier)}). It must be a"
10123                    f" DecisionID, a dictionary from FocalPointNames to"
10124                    f" DecisionIDs, or a set of DecisionIDs, according"
10125                    f" to the focalization of the relevant domain."
10126                )
10127
10128            # Put specified position(s) in place
10129            # TODO: This cast is really silly...
10130            targetContext['activeDecisions'][domain] = cast(
10131                Union[
10132                    None,
10133                    base.DecisionID,
10134                    Dict[base.FocalPointName, Optional[base.DecisionID]],
10135                    Set[base.DecisionID]
10136                ],
10137                positionSpecifier
10138            )
10139
10140            # Set primary decision
10141            newState['primaryDecision'] = primary
10142
10143            # Set capabilities
10144            if capabilities is not None:
10145                targetContext['capabilities'] = capabilities
10146
10147            # Set mechanism states
10148            if mechanismStates is not None:
10149                newState['mechanisms'] = mechanismStates
10150
10151            # Set custom state
10152            if customState is not None:
10153                newState['custom'] = customState
10154
10155        elif action[0] in ('explore', 'take', 'warp'):  # similar handling
10156            assert (
10157                len(action) == 3
10158             or len(action) == 4
10159             or len(action) == 6
10160             or len(action) == 7
10161            )
10162            # Set up necessary variables
10163            cSpec: base.ContextSpecifier = "active"
10164            fromID: Optional[base.DecisionID] = None
10165            takeTransition: Optional[base.Transition] = None
10166            outcomes: List[bool] = []
10167            destID: base.DecisionID  # No starting value as it's not optional
10168            moveInDomain: Optional[base.Domain] = None
10169            moveWhich: Optional[base.FocalPointName] = None
10170
10171            # Figure out target context
10172            if isinstance(action[1], str):
10173                if action[1] not in get_args(base.ContextSpecifier):
10174                    raise InvalidActionError(
10175                        f"Action specifies {repr(action[1])} context,"
10176                        f" but that's not a valid context specifier."
10177                        f" The valid options are:"
10178                        f"\n{repr(get_args(base.ContextSpecifier))}"
10179                    )
10180                else:
10181                    cSpec = cast(base.ContextSpecifier, action[1])
10182            else:  # Must be a `FocalPointSpecifier`
10183                cSpec, moveInDomain, moveWhich = cast(
10184                    base.FocalPointSpecifier,
10185                    action[1]
10186                )
10187                assert moveInDomain is not None
10188
10189            # Grab target context to work in
10190            if cSpec == 'common':
10191                targetContext = newState['common']
10192            else:
10193                targetContext = newState['contexts'][
10194                    newState['activeContext']
10195                ]
10196
10197            # Check focalization of the target domain
10198            if moveInDomain is not None:
10199                fType = base.getDomainFocalization(
10200                    targetContext,
10201                    moveInDomain
10202                )
10203                if (
10204                    (
10205                        isinstance(action[1], str)
10206                    and fType == 'plural'
10207                    ) or (
10208                        not isinstance(action[1], str)
10209                    and fType != 'plural'
10210                    )
10211                ):
10212                    raise ImpossibleActionError(
10213                        f"Invalid ExplorationAction (moves in"
10214                        f" plural-focalized domains must include a"
10215                        f" FocalPointSpecifier, while moves in"
10216                        f" non-plural-focalized domains must not."
10217                        f" Domain {repr(moveInDomain)} is"
10218                        f" {fType}-focalized):"
10219                        f"\n{repr(action)}"
10220                    )
10221
10222            if action[0] == "warp":
10223                # It's a warp, so destination is specified directly
10224                if not isinstance(action[2], base.DecisionID):
10225                    raise TypeError(
10226                        f"Invalid ExplorationAction tuple (third part"
10227                        f" must be a decision ID for 'warp' actions):"
10228                        f"\n{repr(action)}"
10229                    )
10230                else:
10231                    destID = cast(base.DecisionID, action[2])
10232
10233            elif aLen == 4 or aLen == 7:
10234                # direct 'take' or 'explore'
10235                fromID = cast(base.DecisionID, action[2])
10236                takeTransition, outcomes = cast(
10237                    base.TransitionWithOutcomes,
10238                    action[3]  # type: ignore [misc]
10239                )
10240                if (
10241                    not isinstance(fromID, base.DecisionID)
10242                 or not isinstance(takeTransition, base.Transition)
10243                ):
10244                    raise InvalidActionError(
10245                        f"Invalid ExplorationAction tuple (for 'take' or"
10246                        f" 'explore', if the length is 4/7, parts 2-4"
10247                        f" must be a context specifier, a decision ID, and a"
10248                        f" transition name. Got:"
10249                        f"\n{repr(action)}"
10250                    )
10251
10252                try:
10253                    destID = newGraph.destination(fromID, takeTransition)
10254                except MissingDecisionError:
10255                    raise ImpossibleActionError(
10256                        f"Invalid ExplorationAction: move from decision"
10257                        f" {fromID} is invalid because there is no"
10258                        f" decision with that ID in the current"
10259                        f" graph."
10260                        f"\nValid decisions are:"
10261                        f"\n{newGraph.namesListing(newGraph)}"
10262                    )
10263                except MissingTransitionError:
10264                    valid = newGraph.destinationsFrom(fromID)
10265                    listing = newGraph.destinationsListing(valid)
10266                    raise ImpossibleActionError(
10267                        f"Invalid ExplorationAction: move from decision"
10268                        f" {newGraph.identityOf(fromID)}"
10269                        f" along transition {repr(takeTransition)} is"
10270                        f" invalid because there is no such transition"
10271                        f" at that decision."
10272                        f"\nValid transitions there are:"
10273                        f"\n{listing}"
10274                    )
10275                targetActive = targetContext['activeDecisions']
10276                if moveInDomain is not None:
10277                    activeInDomain = targetActive[moveInDomain]
10278                    if (
10279                        (
10280                            isinstance(activeInDomain, base.DecisionID)
10281                        and fromID != activeInDomain
10282                        )
10283                     or (
10284                            isinstance(activeInDomain, set)
10285                        and fromID not in activeInDomain
10286                        )
10287                     or (
10288                            isinstance(activeInDomain, dict)
10289                        and fromID not in activeInDomain.values()
10290                        )
10291                    ):
10292                        raise ImpossibleActionError(
10293                            f"Invalid ExplorationAction: move from"
10294                            f" decision {fromID} is invalid because"
10295                            f" that decision is not active in domain"
10296                            f" {repr(moveInDomain)} in the current"
10297                            f" graph."
10298                            f"\nValid decisions are:"
10299                            f"\n{newGraph.namesListing(newGraph)}"
10300                        )
10301
10302            elif aLen == 3 or aLen == 6:
10303                # 'take' or 'explore' focal point
10304                # We know that moveInDomain is not None here.
10305                assert moveInDomain is not None
10306                if not isinstance(action[2], base.Transition):
10307                    raise InvalidActionError(
10308                        f"Invalid ExplorationAction tuple (for 'take'"
10309                        f" actions if the second part is a"
10310                        f" FocalPointSpecifier the third part must be a"
10311                        f" transition name):"
10312                        f"\n{repr(action)}"
10313                    )
10314
10315                takeTransition, outcomes = cast(
10316                    base.TransitionWithOutcomes,
10317                    action[2]
10318                )
10319                targetActive = targetContext['activeDecisions']
10320                activeInDomain = cast(
10321                    Dict[base.FocalPointName, Optional[base.DecisionID]],
10322                    targetActive[moveInDomain]
10323                )
10324                if (
10325                    moveInDomain is not None
10326                and (
10327                        not isinstance(activeInDomain, dict)
10328                     or moveWhich not in activeInDomain
10329                    )
10330                ):
10331                    raise ImpossibleActionError(
10332                        f"Invalid ExplorationAction: move of focal"
10333                        f" point {repr(moveWhich)} in domain"
10334                        f" {repr(moveInDomain)} is invalid because"
10335                        f" that domain does not have a focal point"
10336                        f" with that name."
10337                    )
10338                fromID = activeInDomain[moveWhich]
10339                if fromID is None:
10340                    raise ImpossibleActionError(
10341                        f"Invalid ExplorationAction: move of focal"
10342                        f" point {repr(moveWhich)} in domain"
10343                        f" {repr(moveInDomain)} is invalid because"
10344                        f" that focal point does not have a position"
10345                        f" at this step."
10346                    )
10347                try:
10348                    destID = newGraph.destination(fromID, takeTransition)
10349                except MissingDecisionError:
10350                    raise ImpossibleActionError(
10351                        f"Invalid exploration state: focal point"
10352                        f" {repr(moveWhich)} in domain"
10353                        f" {repr(moveInDomain)} specifies decision"
10354                        f" {fromID} as the current position, but"
10355                        f" that decision does not exist!"
10356                    )
10357                except MissingTransitionError:
10358                    valid = newGraph.destinationsFrom(fromID)
10359                    listing = newGraph.destinationsListing(valid)
10360                    raise ImpossibleActionError(
10361                        f"Invalid ExplorationAction: move of focal"
10362                        f" point {repr(moveWhich)} in domain"
10363                        f" {repr(moveInDomain)} along transition"
10364                        f" {repr(takeTransition)} is invalid because"
10365                        f" that focal point is at decision"
10366                        f" {newGraph.identityOf(fromID)} and that"
10367                        f" decision does not have an outgoing"
10368                        f" transition with that name.\nValid"
10369                        f" transitions from that decision are:"
10370                        f"\n{listing}"
10371                    )
10372
10373            else:
10374                raise InvalidActionError(
10375                    f"Invalid ExplorationAction: unrecognized"
10376                    f" 'explore', 'take' or 'warp' format:"
10377                    f"\n{action}"
10378                )
10379
10380            # If we're exploring, update information for the destination
10381            if action[0] == 'explore':
10382                zone = cast(Optional[base.Zone], action[-1])
10383                recipName = cast(Optional[base.Transition], action[-2])
10384                destOrName = cast(
10385                    Union[base.DecisionName, base.DecisionID, None],
10386                    action[-3]
10387                )
10388                if isinstance(destOrName, base.DecisionID):
10389                    destID = destOrName
10390
10391                if fromID is None or takeTransition is None:
10392                    raise ImpossibleActionError(
10393                        f"Invalid ExplorationAction: exploration"
10394                        f" has unclear origin decision or transition."
10395                        f" Got:\n{action}"
10396                    )
10397
10398                currentDest = newGraph.destination(fromID, takeTransition)
10399                if not newGraph.isConfirmed(currentDest):
10400                    newGraph.replaceUnconfirmed(
10401                        fromID,
10402                        takeTransition,
10403                        destOrName,
10404                        recipName,
10405                        placeInZone=zone,
10406                        forceNew=not isinstance(destOrName, base.DecisionID)
10407                    )
10408                else:
10409                    # Otherwise, since the destination already existed
10410                    # and was hooked up at the right decision, no graph
10411                    # edits need to be made, unless we need to rename
10412                    # the reciprocal.
10413                    # TODO: Do we care about zones here?
10414                    if recipName is not None:
10415                        oldReciprocal = newGraph.getReciprocal(
10416                            fromID,
10417                            takeTransition
10418                        )
10419                        if (
10420                            oldReciprocal is not None
10421                        and oldReciprocal != recipName
10422                        ):
10423                            newGraph.addTransition(
10424                                destID,
10425                                recipName,
10426                                fromID,
10427                                None
10428                            )
10429                            newGraph.setReciprocal(
10430                                destID,
10431                                recipName,
10432                                takeTransition,
10433                                setBoth=True
10434                            )
10435                            newGraph.mergeTransitions(
10436                                destID,
10437                                oldReciprocal,
10438                                recipName
10439                            )
10440
10441            # If we are moving along a transition, check requirements
10442            # and apply transition effects *before* updating our
10443            # position, and check that they don't cancel the normal
10444            # position update
10445            finalDest = None
10446            if takeTransition is not None:
10447                assert fromID is not None  # both or neither
10448                if not self.isTraversable(fromID, takeTransition):
10449                    if (fromID, takeTransition) in now.state['deactivated']:
10450                        warnings.warn(
10451                            (
10452                                f"The transition {takeTransition!r}"
10453                                f" from decision"
10454                                f" {now.graph.identityOf(fromID)} was"
10455                                f" already deactivated before step"
10456                                f" {len(self) - 1}."
10457                            ),
10458                            TransitionBlockedWarning
10459                        )
10460                    else:
10461                        req = now.graph.getTransitionRequirement(
10462                            fromID,
10463                            takeTransition
10464                        )
10465                        warnings.warn(
10466                            (
10467                                f"The requirements for transition"
10468                                f" {takeTransition!r} from decision"
10469                                f" {now.graph.identityOf(fromID)} are"
10470                                f" not met at step {len(self) - 1}:"
10471                                f"\n{req}"
10472                            ),
10473                            TransitionBlockedWarning
10474                        )
10475
10476                # Apply transition consequences to our new state and
10477                # figure out if we need to skip our normal update or not
10478                finalDest = self.applyTransitionConsequence(
10479                    fromID,
10480                    (takeTransition, outcomes),
10481                    moveWhich,
10482                    challengePolicy
10483                )
10484
10485            # Check moveInDomain
10486            destDomain = newGraph.domainFor(destID)
10487            if moveInDomain is not None and moveInDomain != destDomain:
10488                raise ImpossibleActionError(
10489                    f"Invalid ExplorationAction: move specified"
10490                    f" domain {repr(moveInDomain)} as the domain of"
10491                    f" the focal point to move, but the destination"
10492                    f" of the move is {now.graph.identityOf(destID)}"
10493                    f" which is in domain {repr(destDomain)}, so focal"
10494                    f" point {repr(moveWhich)} cannot be moved there."
10495                )
10496
10497            # Now that we know where we're going, update position
10498            # information (assuming it wasn't already set):
10499            if finalDest is None:
10500                finalDest = destID
10501                base.updatePosition(
10502                    updated.state,
10503                    updated.graph,
10504                    destID,
10505                    cSpec,
10506                    moveWhich
10507                )
10508
10509            destIDs.add(finalDest)
10510
10511        elif action[0] == "focus":
10512            # Figure out target context
10513            action = cast(
10514                Tuple[
10515                    Literal['focus'],
10516                    base.ContextSpecifier,
10517                    Set[base.Domain],
10518                    Set[base.Domain]
10519                ],
10520                action
10521            )
10522            contextSpecifier: base.ContextSpecifier = action[1]
10523            if contextSpecifier == 'common':
10524                targetContext = newState['common']
10525            else:
10526                targetContext = newState['contexts'][
10527                    newState['activeContext']
10528                ]
10529
10530            # Just need to swap out active domains
10531            goingOut, comingIn = cast(
10532                Tuple[Set[base.Domain], Set[base.Domain]],
10533                action[2:]
10534            )
10535            if (
10536                not isinstance(goingOut, set)
10537             or not isinstance(comingIn, set)
10538             or not all(isinstance(d, base.Domain) for d in goingOut)
10539             or not all(isinstance(d, base.Domain) for d in comingIn)
10540            ):
10541                raise InvalidActionError(
10542                    f"Invalid ExplorationAction tuple (must have 4"
10543                    f" parts if the first part is 'focus' and"
10544                    f" the third and fourth parts must be sets of"
10545                    f" domains):"
10546                    f"\n{repr(action)}"
10547                )
10548            activeSet = targetContext['activeDomains']
10549            for dom in goingOut:
10550                try:
10551                    activeSet.remove(dom)
10552                except KeyError:
10553                    warnings.warn(
10554                        (
10555                            f"Domain {repr(dom)} was deactivated at"
10556                            f" step {len(self)} but it was already"
10557                            f" inactive at that point."
10558                        ),
10559                        InactiveDomainWarning
10560                    )
10561            # TODO: Also warn for doubly-activated domains?
10562            activeSet |= comingIn
10563
10564            # destIDs remains empty in this case
10565
10566        elif action[0] == 'swap':  # update which `FocalContext` is active
10567            newContext = cast(base.FocalContextName, action[1])
10568            if newContext not in newState['contexts']:
10569                raise MissingFocalContextError(
10570                    f"'swap' action with target {repr(newContext)} is"
10571                    f" invalid because no context with that name"
10572                    f" exists."
10573                )
10574            newState['activeContext'] = newContext
10575
10576            # destIDs remains empty in this case
10577
10578        elif action[0] == 'focalize':  # create new `FocalContext`
10579            newContext = cast(base.FocalContextName, action[1])
10580            if newContext in newState['contexts']:
10581                raise FocalContextCollisionError(
10582                    f"'focalize' action with target {repr(newContext)}"
10583                    f" is invalid because a context with that name"
10584                    f" already exists."
10585                )
10586            newState['contexts'][newContext] = base.emptyFocalContext()
10587            newState['activeContext'] = newContext
10588
10589            # destIDs remains empty in this case
10590
10591        # revertTo is handled above
10592        else:
10593            raise InvalidActionError(
10594                f"Invalid ExplorationAction tuple (first item must be"
10595                f" an ExplorationActionType, and tuple must be length-1"
10596                f" if the action type is 'noAction'):"
10597                f"\n{repr(action)}"
10598            )
10599
10600        # Apply any active triggers
10601        followTo = self.applyActiveTriggers()
10602        if followTo is not None:
10603            destIDs.add(followTo)
10604            # TODO: Re-work to work with multiple position updates in
10605            # different focal contexts, domains, and/or for different
10606            # focal points in plural-focalized domains.
10607
10608        return (updated, destIDs)
10609
10610    def applyActiveTriggers(self) -> Optional[base.DecisionID]:
10611        """
10612        Finds all actions with the 'trigger' tag attached to currently
10613        active decisions, and applies their effects if their requirements
10614        are met (ordered by decision-ID with ties broken alphabetically
10615        by action name).
10616
10617        'bounce', 'goto' and 'follow' effects may apply. However, any
10618        new triggers that would be activated because of decisions
10619        reached by such effects will not apply. Note that 'bounce'
10620        effects update position to the decision where the action was
10621        attached, which is usually a no-op. This function returns the
10622        decision ID of the decision reached by the last decision-moving
10623        effect applied, or `None` if no such effects triggered.
10624
10625        TODO: What about situations where positions are updated in
10626        multiple domains or multiple foal points in a plural domain are
10627        independently updated?
10628
10629        TODO: Tests for this!
10630        """
10631        active = self.getActiveDecisions()
10632        now = self.getSituation()
10633        graph = now.graph
10634        finalFollow = None
10635        for decision in sorted(active):
10636            for action in sorted(graph.decisionActions(decision)):
10637                if (
10638                    'trigger' in graph.transitionTags(decision, action)
10639                and self.isTraversable(decision, action)
10640                ):
10641                    followTo = self.applyTransitionConsequence(
10642                        decision,
10643                        action
10644                    )
10645                    if followTo is not None:
10646                        # TODO: How will triggers interact with
10647                        # plural-focalized domains? Probably need to fix
10648                        # this to detect moveWhich based on which focal
10649                        # points are at the decision where the transition
10650                        # is, and then apply this to each of them?
10651                        base.updatePosition(now.state, now.graph, followTo)
10652                        finalFollow = followTo
10653
10654        return finalFollow
10655
10656    def explore(
10657        self,
10658        transition: base.AnyTransition,
10659        destination: Union[base.DecisionName, base.DecisionID, None],
10660        reciprocal: Optional[base.Transition] = None,
10661        zone: Optional[base.Zone] = base.DefaultZone,
10662        fromDecision: Optional[base.AnyDecisionSpecifier] = None,
10663        whichFocus: Optional[base.FocalPointSpecifier] = None,
10664        inCommon: Union[bool, Literal["auto"]] = "auto",
10665        decisionType: base.DecisionType = "active",
10666        challengePolicy: base.ChallengePolicy = "specified"
10667    ) -> base.DecisionID:
10668        """
10669        Adds a new situation to the exploration representing the
10670        traversal of the specified transition (possibly with outcomes
10671        specified for challenges among that transitions consequences).
10672        Uses `deduceTransitionDetailsAtStep` to figure out from the
10673        transition name which specific transition is taken (and which
10674        focal point is updated if necessary). This uses the
10675        `fromDecision`, `whichFocus`, and `inCommon` optional
10676        parameters, and also determines whether to update the common or
10677        the active `FocalContext`. Sets the exploration status of the
10678        decision explored to 'exploring'. Returns the decision ID for
10679        the destination reached, accounting for goto/bounce/follow
10680        effects that might have triggered.
10681
10682        If multiple decisions are reached (e.g., in multiple domains,
10683        like you arrive at the destination but also die) it returns the
10684        decision with the highest decision ID (i.e., discovered latest)
10685        among decisions in the same domain as the natural endpoint of the
10686        transition taken, or if there are no such decisions, it returns
10687        the decision with the highest ID out of all newly-arrived-at
10688        decisions.
10689
10690        The `destination` will be used to name the newly-explored
10691        decision, except when it's a `DecisionID`, in which case that
10692        decision must be unvisited, and we'll connect the specified
10693        transition to that decision.
10694
10695        The focalization of the destination domain in the context to be
10696        updated determines how active decisions are changed:
10697
10698        - If the destination domain is focalized as 'single', then in
10699            the subsequent `Situation`, the destination decision will
10700            become the single active decision in that domain.
10701        - If it's focalized as 'plural', then one of the
10702            `FocalPointName`s for that domain will be moved to activate
10703            that decision; which one can be specified using `whichFocus`
10704            or if left unspecified, will be deduced: if the starting
10705            decision is in the same domain, then the
10706            alphabetically-earliest focal point which is at the starting
10707            decision will be moved. If the starting position is in a
10708            different domain, then the alphabetically earliest focal
10709            point among all focal points in the destination domain will
10710            be moved.
10711        - If it's focalized as 'spreading', then the destination
10712            decision will be added to the set of active decisions in
10713            that domain, without removing any.
10714
10715        The transition named must have been pointing to an unvisited
10716        decision (see `hasBeenVisited`), and the name of that decision
10717        will be updated if a `destination` value is given (a
10718        `DecisionCollisionWarning` will be issued if the destination
10719        name is a duplicate of another name in the graph, although this
10720        is not an error). Additionally:
10721
10722        - If a `reciprocal` name is specified, the reciprocal transition
10723            will be renamed using that name, or created with that name if
10724            it didn't already exist. If reciprocal is left as `None` (the
10725            default) then no change will be made to the reciprocal
10726            transition, and it will not be created if it doesn't exist.
10727        - If a `zone` is specified, the newly-explored decision will be
10728            added to that zone (and that zone will be created at level 0
10729            if it didn't already exist). If `zone` is set to `None` then
10730            it will not be added to any new zones. If `zone` is left as
10731            the default (the `base.DefaultZone` value) then the explored
10732            decision will be added to each zone that the decision it was
10733            explored from is a part of. If a zone needs to be created,
10734            that zone will be added as a sub-zone of each zone which is a
10735            parent of a zone that directly contains the origin decision.
10736        - An `ExplorationStatusError` will be raised if the specified
10737            transition leads to a decision whose `ExplorationStatus` is
10738            'exploring' or higher (i.e., `hasBeenVisited`). (Use
10739            `returnTo` instead to adjust things when a transition to an
10740            unknown destination turns out to lead to an already-known
10741            destination.)
10742        - A `TransitionBlockedWarning` will be issued if the specified
10743            transition is not traversable given the current game state
10744            (but in that last case the step will still be taken).
10745        - By default, the decision type for the new step will be
10746            'active', but a `decisionType` value can be specified to
10747            override that.
10748        - By default, the 'mostLikely' `ChallengePolicy` will be used to
10749            resolve challenges in the consequence of the transition
10750            taken, but an alternate policy can be supplied using the
10751            `challengePolicy` argument.
10752        """
10753        now = self.getSituation()
10754
10755        transitionName, outcomes = base.nameAndOutcomes(transition)
10756
10757        # Deduce transition details from the name + optional specifiers
10758        (
10759            using,
10760            fromID,
10761            destID,
10762            whichFocus
10763        ) = self.deduceTransitionDetailsAtStep(
10764            -1,
10765            transitionName,
10766            fromDecision,
10767            whichFocus,
10768            inCommon
10769        )
10770
10771        # Issue a warning if the destination name is already in use
10772        if destination is not None:
10773            if isinstance(destination, base.DecisionName):
10774                try:
10775                    existingID = now.graph.resolveDecision(destination)
10776                    collision = existingID != destID
10777                except MissingDecisionError:
10778                    collision = False
10779                except AmbiguousDecisionSpecifierError:
10780                    collision = True
10781
10782                if collision and WARN_OF_NAME_COLLISIONS:
10783                    warnings.warn(
10784                        (
10785                            f"The destination name {repr(destination)} is"
10786                            f" already in use when exploring transition"
10787                            f" {repr(transition)} from decision"
10788                            f" {now.graph.identityOf(fromID)} at step"
10789                            f" {len(self) - 1}."
10790                        ),
10791                        DecisionCollisionWarning
10792                    )
10793
10794        # TODO: Different terminology for "exploration state above
10795        # noticed" vs. "DG thinks it's been visited"...
10796        if (
10797            self.hasBeenVisited(destID)
10798        ):
10799            frStr = ''
10800            if fromDecision is not None:
10801                frStr = f"from decision {now.graph.identityOf(fromDecision)} "
10802            raise ExplorationStatusError(
10803                f"Cannot explore {frStr}to decision"
10804                f" {now.graph.identityOf(destID)} because it has"
10805                f" already been visited. Use returnTo instead of"
10806                f" explore when discovering a connection back to a"
10807                f" previously-explored decision."
10808            )
10809
10810        if (
10811            isinstance(destination, base.DecisionID)
10812        and self.hasBeenVisited(destination)
10813        ):
10814            frStr = ''
10815            if fromDecision is not None:
10816                frStr = f"from decision {now.graph.identityOf(fromDecision)} "
10817            raise ExplorationStatusError(
10818                f"Cannot explore {frStr}to decision"
10819                f" {now.graph.identityOf(destination)} because it has"
10820                f" already been visited. Use returnTo instead of"
10821                f" explore when discovering a connection back to a"
10822                f" previously-explored decision."
10823            )
10824
10825        actionTaken: base.ExplorationAction = (
10826            'explore',
10827            using,
10828            fromID,
10829            (transitionName, outcomes),
10830            destination,
10831            reciprocal,
10832            zone
10833        )
10834        if whichFocus is not None:
10835            # A move-from-specific-focal-point action
10836            actionTaken = (
10837                'explore',
10838                whichFocus,
10839                (transitionName, outcomes),
10840                destination,
10841                reciprocal,
10842                zone
10843            )
10844
10845        # Advance the situation, applying transition effects and
10846        # updating the destination decision.
10847        _, finalDests = self.advanceSituation(
10848            actionTaken,
10849            decisionType,
10850            challengePolicy
10851        )
10852
10853        return self.mostApplicableDestination(
10854            now.graph,
10855            fromID,
10856            destID,
10857            finalDests
10858        )
10859
10860    def mostApplicableDestination(
10861        self,
10862        graph: DecisionGraph,
10863        fromID: base.DecisionID,
10864        destID: base.DecisionID,
10865        destinationSet: Set[base.DecisionID]
10866    ) -> base.DecisionID:
10867        """
10868        Returns the single decision ID that's "most applicable" as the
10869        destination of an action that moved from the given `fromID`
10870        decision to the given `destID` decision (naively) on the given
10871        `graph` with the given `destinationSet` as the set of newly-active
10872        decisions from an `advanceSituation` call.
10873
10874        `advanceSituation` can return multiple or zero active decisions
10875        (e.g., if you take a transition but then die as a consequence,
10876        you'll be at the destination plus at the death ending in the
10877        endings domain, or if you take a transition with 'follow'
10878        consequences in a spreading-focalized domain).
10879
10880        When multiple decisions are present in the destination set, this
10881        function returns the decision with the highest ID (i.e.,
10882        discovered most recently) that's in the same domain as the
10883        destination decision, or if there are none in that domain, the
10884        one with the highest decision ID overall.
10885
10886        If the destination set is empty, it returns the `fromID`.
10887        """
10888        if len(destinationSet) == 0:
10889            return fromID
10890        elif len(destinationSet) > 1:
10891            # Figure out which destination(s) are in the same domain as
10892            # the natural destination, and return the one with the
10893            # highest ID among those, or the one with the highest ID
10894            # overall if there are none.
10895            destDomain = graph.domainFor(destID)
10896            inSame = [
10897                x
10898                for x in destinationSet
10899                if graph.domainFor(x) == destDomain
10900            ]
10901            if len(inSame) == 0:
10902                return max(destinationSet)
10903            else:
10904                return max(inSame)
10905        else:
10906            return next(x for x in destinationSet)
10907
10908    def returnTo(
10909        self,
10910        transition: base.AnyTransition,
10911        destination: base.AnyDecisionSpecifier,
10912        reciprocal: Optional[base.Transition] = None,
10913        fromDecision: Optional[base.AnyDecisionSpecifier] = None,
10914        whichFocus: Optional[base.FocalPointSpecifier] = None,
10915        inCommon: Union[bool, Literal["auto"]] = "auto",
10916        decisionType: base.DecisionType = "active",
10917        challengePolicy: base.ChallengePolicy = "specified"
10918    ) -> base.DecisionID:
10919        """
10920        Adds a new graph to the exploration that replaces the given
10921        transition at the current position (which must lead to an unknown
10922        node, or a `MissingDecisionError` will result). The new
10923        transition will connect back to the specified destination, which
10924        must already exist (or a different `ValueError` will be raised).
10925        Returns the decision ID for the destination reached.
10926
10927        Deduces transition details using the optional `fromDecision`,
10928        `whichFocus`, and `inCommon` arguments in addition to the
10929        `transition` value; see `deduceTransitionDetailsAtStep`.
10930
10931        If a `reciprocal` transition is specified, that transition must
10932        either not already exist in the destination decision or lead to
10933        an unknown region; it will be replaced (or added) as an edge
10934        leading back to the current position.
10935
10936        The `decisionType` and `challengePolicy` optional arguments are
10937        used for `advanceSituation`.
10938
10939        A `TransitionBlockedWarning` will be issued if the requirements
10940        for the transition are not met, but the step will still be taken.
10941        Raises a `MissingDecisionError` if there is no current
10942        transition.
10943        """
10944        now = self.getSituation()
10945
10946        transitionName, outcomes = base.nameAndOutcomes(transition)
10947
10948        # Deduce transition details from the name + optional specifiers
10949        (
10950            using,
10951            fromID,
10952            destID,
10953            whichFocus
10954        ) = self.deduceTransitionDetailsAtStep(
10955            -1,
10956            transitionName,
10957            fromDecision,
10958            whichFocus,
10959            inCommon
10960        )
10961
10962        # Replace with connection to existing destination
10963        destID = now.graph.resolveDecision(destination)
10964        if not self.hasBeenVisited(destID):
10965            raise ExplorationStatusError(
10966                f"Cannot return to decision"
10967                f" {now.graph.identityOf(destID)} because it has NOT"
10968                f" already been at least partially explored. Use"
10969                f" explore instead of returnTo when discovering a"
10970                f" connection to a previously-unexplored decision."
10971            )
10972
10973        now.graph.replaceUnconfirmed(
10974            fromID,
10975            transitionName,
10976            destID,
10977            reciprocal
10978        )
10979
10980        # A move-from-decision action
10981        actionTaken: base.ExplorationAction = (
10982            'take',
10983            using,
10984            fromID,
10985            (transitionName, outcomes)
10986        )
10987        if whichFocus is not None:
10988            # A move-from-specific-focal-point action
10989            actionTaken = ('take', whichFocus, (transitionName, outcomes))
10990
10991        # Next, advance the situation, applying transition effects
10992        _, finalDests = self.advanceSituation(
10993            actionTaken,
10994            decisionType,
10995            challengePolicy
10996        )
10997
10998        return self.mostApplicableDestination(
10999            now.graph,
11000            fromID,
11001            destID,
11002            finalDests
11003        )
11004
11005    def takeAction(
11006        self,
11007        action: base.AnyTransition,
11008        requires: Optional[base.Requirement] = None,
11009        consequence: Optional[base.Consequence] = None,
11010        fromDecision: Optional[base.AnyDecisionSpecifier] = None,
11011        whichFocus: Optional[base.FocalPointSpecifier] = None,
11012        inCommon: Union[bool, Literal["auto"]] = "auto",
11013        decisionType: base.DecisionType = "active",
11014        challengePolicy: base.ChallengePolicy = "specified"
11015    ) -> base.DecisionID:
11016        """
11017        Adds a new graph to the exploration based on taking the given
11018        action, which must be a self-transition in the graph. If the
11019        action does not already exist in the graph, it will be created.
11020        Either way if requirements and/or a consequence are supplied,
11021        the requirements and consequence of the action will be updated
11022        to match them, and those are the requirements/consequence that
11023        will count.
11024
11025        Returns the decision ID for the decision reached, which normally
11026        is the same action you were just at, but which might be altered
11027        by goto, bounce, and/or follow effects.
11028
11029        Issues a `TransitionBlockedWarning` if the current game state
11030        doesn't satisfy the requirements for the action.
11031
11032        The `fromDecision`, `whichFocus`, and `inCommon` arguments are
11033        used for `deduceTransitionDetailsAtStep`, while `decisionType`
11034        and `challengePolicy` are used for `advanceSituation`.
11035
11036        When an action is being created, `fromDecision` (or
11037        `whichFocus`) must be specified, since the source decision won't
11038        be deducible from the transition name. Note that if a transition
11039        with the given name exists from *any* active decision, it will
11040        be used instead of creating a new action (possibly resulting in
11041        an error if it's not a self-loop transition). Also, you may get
11042        an `AmbiguousTransitionError` if several transitions with that
11043        name exist; in that case use `fromDecision` and/or `whichFocus`
11044        to disambiguate.
11045        """
11046        now = self.getSituation()
11047        graph = now.graph
11048
11049        actionName, outcomes = base.nameAndOutcomes(action)
11050
11051        try:
11052            (
11053                using,
11054                fromID,
11055                destID,
11056                whichFocus
11057            ) = self.deduceTransitionDetailsAtStep(
11058                -1,
11059                actionName,
11060                fromDecision,
11061                whichFocus,
11062                inCommon
11063            )
11064
11065            if destID != fromID:
11066                raise ValueError(
11067                    f"Cannot take action {repr(action)} because it's a"
11068                    f" transition to another decision, not an action"
11069                    f" (use explore, returnTo, and/or retrace instead)."
11070                )
11071
11072        except MissingTransitionError:
11073            using = 'active'
11074            if inCommon is True:
11075                using = 'common'
11076
11077            if fromDecision is not None:
11078                fromID = graph.resolveDecision(fromDecision)
11079            elif whichFocus is not None:
11080                maybeFromID = base.resolvePosition(now.state, whichFocus)
11081                if maybeFromID is None:
11082                    raise MissingDecisionError(
11083                        f"Focal point {repr(whichFocus)} was specified"
11084                        f" in takeAction but that focal point doesn't"
11085                        f" have a position."
11086                    )
11087                else:
11088                    fromID = maybeFromID
11089            else:
11090                raise AmbiguousTransitionError(
11091                    f"Taking action {repr(action)} is ambiguous because"
11092                    f" the source decision has not been specified via"
11093                    f" either fromDecision or whichFocus, and we"
11094                    f" couldn't find an existing action with that name."
11095                )
11096
11097            destID = fromID
11098
11099            # Since the action doesn't exist, add it:
11100            graph.addAction(fromID, actionName, requires, consequence)
11101
11102        # Update the transition requirement/consequence if requested
11103        # (before the action is taken)
11104        if requires is not None:
11105            graph.setTransitionRequirement(fromID, actionName, requires)
11106        if consequence is not None:
11107            graph.setConsequence(fromID, actionName, consequence)
11108
11109        # A move-from-decision action
11110        actionTaken: base.ExplorationAction = (
11111            'take',
11112            using,
11113            fromID,
11114            (actionName, outcomes)
11115        )
11116        if whichFocus is not None:
11117            # A move-from-specific-focal-point action
11118            actionTaken = ('take', whichFocus, (actionName, outcomes))
11119
11120        _, finalDests = self.advanceSituation(
11121            actionTaken,
11122            decisionType,
11123            challengePolicy
11124        )
11125
11126        return self.mostApplicableDestination(
11127            graph,
11128            fromID,
11129            destID,
11130            finalDests
11131        )
11132
11133    def retrace(
11134        self,
11135        transition: base.AnyTransition,
11136        fromDecision: Optional[base.AnyDecisionSpecifier] = None,
11137        whichFocus: Optional[base.FocalPointSpecifier] = None,
11138        inCommon: Union[bool, Literal["auto"]] = "auto",
11139        decisionType: base.DecisionType = "active",
11140        challengePolicy: base.ChallengePolicy = "specified"
11141    ) -> base.DecisionID:
11142        """
11143        Adds a new graph to the exploration based on taking the given
11144        transition, which must already exist and which must not lead to
11145        an unknown region. Returns the ID of the destination decision,
11146        accounting for goto, bounce, and/or follow effects.
11147
11148        Issues a `TransitionBlockedWarning` if the current game state
11149        doesn't satisfy the requirements for the transition.
11150
11151        The `fromDecision`, `whichFocus`, and `inCommon` arguments are
11152        used for `deduceTransitionDetailsAtStep`, while `decisionType`
11153        and `challengePolicy` are used for `advanceSituation`.
11154        """
11155        now = self.getSituation()
11156
11157        transitionName, outcomes = base.nameAndOutcomes(transition)
11158
11159        (
11160            using,
11161            fromID,
11162            destID,
11163            whichFocus
11164        ) = self.deduceTransitionDetailsAtStep(
11165            -1,
11166            transitionName,
11167            fromDecision,
11168            whichFocus,
11169            inCommon
11170        )
11171
11172        visited = self.hasBeenVisited(destID)
11173        confirmed = now.graph.isConfirmed(destID)
11174        if not confirmed:
11175            raise ExplorationStatusError(
11176                f"Cannot retrace transition {transition!r} from"
11177                f" decision {now.graph.identityOf(fromID)} because it"
11178                f" leads to an unconfirmed decision.\nUse"
11179                f" `DiscreteExploration.explore` and provide"
11180                f" destination decision details instead."
11181            )
11182        if not visited:
11183            raise ExplorationStatusError(
11184                f"Cannot retrace transition {transition!r} from"
11185                f" decision {now.graph.identityOf(fromID)} because it"
11186                f" leads to an unvisited decision.\nUse"
11187                f" `DiscreteExploration.explore` and provide"
11188                f" destination decision details instead."
11189            )
11190
11191        # A move-from-decision action
11192        actionTaken: base.ExplorationAction = (
11193            'take',
11194            using,
11195            fromID,
11196            (transitionName, outcomes)
11197        )
11198        if whichFocus is not None:
11199            # A move-from-specific-focal-point action
11200            actionTaken = ('take', whichFocus, (transitionName, outcomes))
11201
11202        _, finalDests = self.advanceSituation(
11203            actionTaken,
11204            decisionType,
11205            challengePolicy
11206        )
11207
11208        return self.mostApplicableDestination(
11209            now.graph,
11210            fromID,
11211            destID,
11212            finalDests
11213        )
11214
11215    def warp(
11216        self,
11217        destination: base.AnyDecisionSpecifier,
11218        consequence: Optional[base.Consequence] = None,
11219        domain: Optional[base.Domain] = None,
11220        zone: Optional[base.Zone] = base.DefaultZone,
11221        whichFocus: Optional[base.FocalPointSpecifier] = None,
11222        inCommon: Union[bool] = False,
11223        decisionType: base.DecisionType = "active",
11224        challengePolicy: base.ChallengePolicy = "specified",
11225        allowNew: bool = False
11226    ) -> base.DecisionID:
11227        """
11228        Adds a new graph to the exploration that's a copy of the current
11229        graph, with the position updated to be at the destination without
11230        actually creating a transition from the old position to the new
11231        one. Returns the ID of the decision warped to (accounting for
11232        any goto or follow effects triggered).
11233
11234        Any provided consequences are applied, but are not associated
11235        with any transition (so any delays and charges are ignored, and
11236        'bounce' effects don't actually cancel the warp). 'goto' or
11237        'follow' effects might change the warp destination; 'follow'
11238        effects take the original destination as their starting point.
11239        Any mechanisms mentioned in extra consequences will be found
11240        based on the destination. Outcomes in supplied challenges should
11241        be pre-specified, or else they will be resolved with the
11242        `challengePolicy`.
11243
11244        `whichFocus` may be specified when the destination domain's
11245        focalization is 'plural' but for 'singular' or 'spreading'
11246        destination domains it is not allowed. `inCommon` determines
11247        whether the common or the active focal context is updated
11248        (default is to update the active context). The `decisionType`
11249        and `challengePolicy` are used for `advanceSituation`.
11250
11251        - If the destination did not already exist, it will be created if
11252            `allowNew` is `True` (default is `False`). If `allowNew` is
11253            `False` and the destination did not already exist, a
11254            `MissingDecisionError` will be raised. Initially, any
11255            newly-created decision will be disconnected from all other
11256            decisions. In this case, the `domain` value can be used to
11257            put it in a non-default domain.
11258        - The position is set to the specified destination, and if a
11259            `consequence` is specified it is applied. Note that
11260            'deactivate' effects are NOT allowed, and 'edit' effects
11261            must establish their own transition target because there is
11262            no transition that the effects are being applied to.
11263        - If the destination had been unexplored, its exploration status
11264            will be set to 'exploring'.
11265        - If a `zone` is specified, the destination will be added to that
11266            zone (even if the destination already existed) and that zone
11267            will be created (as a level-0 zone) if need be. If `zone` is
11268            set to `None`, then no zone will be applied. If `zone` is
11269            left as the default (`base.DefaultZone`) and the
11270            focalization of the destination domain is 'singular' or
11271            'plural' and the destination is newly created and there is
11272            an origin and the origin is in the same domain as the
11273            destination, then the destination will be added to all zones
11274            that the origin was a part of if the destination is newly
11275            created, but otherwise the destination will not be added to
11276            any zones. If the specified zone has to be created and
11277            there's an origin decision, it will be added as a sub-zone
11278            to all parents of zones directly containing the origin, as
11279            long as the origin is in the same domain as the destination.
11280        """
11281        now = self.getSituation()
11282        graph = now.graph
11283
11284        fromID: Optional[base.DecisionID]
11285
11286        new = False
11287        try:
11288            destID = graph.resolveDecision(destination)
11289        except MissingDecisionError:
11290            if not allowNew:
11291                raise
11292
11293            if isinstance(destination, tuple):
11294                # just the name; ignore zone/domain
11295                destination = destination[-1]
11296
11297            if not isinstance(destination, base.DecisionName):
11298                raise TypeError(
11299                    f"Warp destination {repr(destination)} does not"
11300                    f" exist, and cannot be created as it is not a"
11301                    f" decision name."
11302                )
11303            destID = graph.addDecision(destination, domain)
11304            graph.tagDecision(destID, 'unconfirmed')
11305            self.setExplorationStatus(destID, 'unknown')
11306            new = True
11307
11308        using: base.ContextSpecifier
11309        if inCommon:
11310            targetContext = self.getCommonContext()
11311            using = "common"
11312        else:
11313            targetContext = self.getActiveContext()
11314            using = "active"
11315
11316        destDomain = graph.domainFor(destID)
11317        targetFocalization = base.getDomainFocalization(
11318            targetContext,
11319            destDomain
11320        )
11321        if targetFocalization == 'singular':
11322            targetActive = targetContext['activeDecisions']
11323            if destDomain in targetActive:
11324                fromID = cast(
11325                    base.DecisionID,
11326                    targetContext['activeDecisions'][destDomain]
11327                )
11328            else:
11329                fromID = None
11330        elif targetFocalization == 'plural':
11331            if whichFocus is None:
11332                raise AmbiguousTransitionError(
11333                    f"Warping to {repr(destination)} is ambiguous"
11334                    f" becuase domain {repr(destDomain)} has plural"
11335                    f" focalization, and no whichFocus value was"
11336                    f" specified."
11337                )
11338
11339            fromID = base.resolvePosition(
11340                self.getSituation().state,
11341                whichFocus
11342            )
11343        else:
11344            fromID = None
11345
11346        # Handle zones
11347        if zone == base.DefaultZone:
11348            if (
11349                new
11350            and fromID is not None
11351            and graph.domainFor(fromID) == destDomain
11352            ):
11353                for prevZone in graph.zoneParents(fromID):
11354                    graph.addDecisionToZone(destination, prevZone)
11355            # Otherwise don't update zones
11356        elif zone is not None:
11357            # Newness is ignored when a zone is specified
11358            zone = cast(base.Zone, zone)
11359            # Create the zone at level 0 if it didn't already exist
11360            if graph.getZoneInfo(zone) is None:
11361                graph.createZone(zone, 0)
11362                # Add the newly created zone to each 2nd-level parent of
11363                # the previous decision if there is one and it's in the
11364                # same domain
11365                if (
11366                    fromID is not None
11367                and graph.domainFor(fromID) == destDomain
11368                ):
11369                    for prevZone in graph.zoneParents(fromID):
11370                        for prevUpper in graph.zoneParents(prevZone):
11371                            graph.addZoneToZone(zone, prevUpper)
11372            # Finally add the destination to the (maybe new) zone
11373            graph.addDecisionToZone(destID, zone)
11374        # else don't touch zones
11375
11376        # Encode the action taken
11377        actionTaken: base.ExplorationAction
11378        if whichFocus is None:
11379            actionTaken = (
11380                'warp',
11381                using,
11382                destID
11383            )
11384        else:
11385            actionTaken = (
11386                'warp',
11387                whichFocus,
11388                destID
11389            )
11390
11391        # Advance the situation
11392        _, finalDests = self.advanceSituation(
11393            actionTaken,
11394            decisionType,
11395            challengePolicy
11396        )
11397        now = self.getSituation()  # updating just in case
11398
11399        baseID = fromID
11400        if baseID is None:
11401            baseID = destID
11402
11403        finalDest = self.mostApplicableDestination(
11404            now.graph,
11405            baseID,
11406            destID,
11407            finalDests
11408        )
11409
11410        # Apply additional consequences:
11411        if consequence is not None:
11412            altDest = self.applyExtraneousConsequence(
11413                consequence,
11414                where=(destID, None),
11415                # TODO: Mechanism search from both ends?
11416                moveWhich=(
11417                    whichFocus[-1]
11418                    if whichFocus is not None
11419                    else None
11420                )
11421            )
11422            if altDest is not None:
11423                finalDest = altDest
11424            now = self.getSituation()  # updating just in case
11425
11426        return finalDest
11427
11428    def wait(
11429        self,
11430        consequence: Optional[base.Consequence] = None,
11431        decisionType: base.DecisionType = "active",
11432        challengePolicy: base.ChallengePolicy = "specified"
11433    ) -> Optional[base.DecisionID]:
11434        """
11435        Adds a wait step. If a consequence is specified, it is applied,
11436        although it will not have any position/transition information
11437        available during resolution/application.
11438
11439        A decision type other than "active" and/or a challenge policy
11440        other than "specified" can be included (see `advanceSituation`).
11441
11442        The "pending" decision type may not be used, a `ValueError` will
11443        result. This allows None as the action for waiting while
11444        preserving the pending/None type/action combination for
11445        unresolved situations.
11446
11447        If a goto or follow effect in the applied consequence implies a
11448        position update, this will return the new destination ID;
11449        otherwise it will return `None`. Triggering a 'bounce' effect
11450        will be an error, because there is no position information for
11451        the effect.
11452        """
11453        if decisionType == "pending":
11454            raise ValueError(
11455                "The 'pending' decision type may not be used for"
11456                " wait actions."
11457            )
11458        self.advanceSituation(('noAction',), decisionType, challengePolicy)
11459        now = self.getSituation()
11460        if consequence is not None:
11461            if challengePolicy != "specified":
11462                base.resetChallengeOutcomes(consequence)
11463            observed = base.observeChallengeOutcomes(
11464                base.RequirementContext(
11465                    state=now.state,
11466                    graph=now.graph,
11467                    searchFrom=set()
11468                ),
11469                consequence,
11470                location=None,  # No position info
11471                policy=challengePolicy,
11472                knownOutcomes=None  # bake outcomes into the consequence
11473            )
11474            # No location information since we might have multiple
11475            # active decisions and there's no indication of which one
11476            # we're "waiting at."
11477            finalDest = self.applyExtraneousConsequence(observed)
11478            now = self.getSituation()  # updating just in case
11479
11480            return finalDest
11481        else:
11482            return None
11483
11484    def revert(
11485        self,
11486        slot: base.SaveSlot = base.DEFAULT_SAVE_SLOT,
11487        aspects: Optional[Set[str]] = None,
11488        decisionType: base.DecisionType = "active"
11489    ) -> None:
11490        """
11491        Reverts the game state to a previously-saved game state (saved
11492        via a 'save' effect). The save slot name and set of aspects to
11493        revert are required. By default, all aspects except the graph
11494        are reverted.
11495        """
11496        if aspects is None:
11497            aspects = set()
11498
11499        action: base.ExplorationAction = ("revertTo", slot, aspects)
11500
11501        self.advanceSituation(action, decisionType)
11502
11503    def observeAll(
11504        self,
11505        where: base.AnyDecisionSpecifier,
11506        *transitions: Union[
11507            base.Transition,
11508            Tuple[base.Transition, base.AnyDecisionSpecifier],
11509            Tuple[
11510                base.Transition,
11511                base.AnyDecisionSpecifier,
11512                base.Transition
11513            ]
11514        ]
11515    ) -> List[base.DecisionID]:
11516        """
11517        Observes one or more new transitions, applying changes to the
11518        current graph. The transitions can be specified in one of three
11519        ways:
11520
11521        1. A transition name. The transition will be created and will
11522            point to a new unexplored node.
11523        2. A pair containing a transition name and a destination
11524            specifier. If the destination does not exist it will be
11525            created as an unexplored node, although in that case the
11526            decision specifier may not be an ID.
11527        3. A triple containing a transition name, a destination
11528            specifier, and a reciprocal name. Works the same as the pair
11529            case but also specifies the name for the reciprocal
11530            transition.
11531
11532        The new transitions are outgoing from specified decision.
11533
11534        Yields the ID of each decision connected to, whether those are
11535        new or existing decisions.
11536        """
11537        now = self.getSituation()
11538        fromID = now.graph.resolveDecision(where)
11539        result = []
11540        for entry in transitions:
11541            if isinstance(entry, base.Transition):
11542                result.append(self.observe(fromID, entry))
11543            else:
11544                result.append(self.observe(fromID, *entry))
11545        return result
11546
11547    def observe(
11548        self,
11549        where: base.AnyDecisionSpecifier,
11550        transition: base.Transition,
11551        destination: Optional[base.AnyDecisionSpecifier] = None,
11552        reciprocal: Optional[base.Transition] = None
11553    ) -> base.DecisionID:
11554        """
11555        Observes a single new outgoing transition from the specified
11556        decision. If specified the transition connects to a specific
11557        destination and/or has a specific reciprocal. The specified
11558        destination will be created if it doesn't exist, or where no
11559        destination is specified, a new unexplored decision will be
11560        added. The ID of the decision connected to is returned.
11561
11562        Sets the exploration status of the observed destination to
11563        "noticed" if a destination is specified and needs to be created
11564        (but not when no destination is specified).
11565
11566        For example:
11567
11568        >>> e = DiscreteExploration()
11569        >>> e.start('start')
11570        0
11571        >>> e.observe('start', 'up')
11572        1
11573        >>> g = e.getSituation().graph
11574        >>> g.destinationsFrom('start')
11575        {'up': 1}
11576        >>> e.getExplorationStatus(1)  # not given a name: assumed unknown
11577        'unknown'
11578        >>> e.observe('start', 'left', 'A')
11579        2
11580        >>> g.destinationsFrom('start')
11581        {'up': 1, 'left': 2}
11582        >>> g.nameFor(2)
11583        'A'
11584        >>> e.getExplorationStatus(2)  # given a name: noticed
11585        'noticed'
11586        >>> e.observe('start', 'up2', 1)
11587        1
11588        >>> g.destinationsFrom('start')
11589        {'up': 1, 'left': 2, 'up2': 1}
11590        >>> e.getExplorationStatus(1)  # existing decision: status unchanged
11591        'unknown'
11592        >>> e.observe('start', 'right', 'B', 'left')
11593        3
11594        >>> g.destinationsFrom('start')
11595        {'up': 1, 'left': 2, 'up2': 1, 'right': 3}
11596        >>> g.nameFor(3)
11597        'B'
11598        >>> e.getExplorationStatus(3)  # new + name -> noticed
11599        'noticed'
11600        >>> e.observe('start', 'right')  # repeat transition name
11601        Traceback (most recent call last):
11602        ...
11603        exploration.core.TransitionCollisionError...
11604        >>> e.observe('start', 'right2', 'B', 'left')  # repeat reciprocal
11605        Traceback (most recent call last):
11606        ...
11607        exploration.core.TransitionCollisionError...
11608        >>> g = e.getSituation().graph
11609        >>> g.createZone('Z', 0)
11610        ZoneInfo(level=0, parents=set(), contents=set(), tags={},\
11611 annotations=[])
11612        >>> g.addDecisionToZone('start', 'Z')
11613        >>> e.observe('start', 'down', 'C', 'up')
11614        4
11615        >>> g.destinationsFrom('start')
11616        {'up': 1, 'left': 2, 'up2': 1, 'right': 3, 'down': 4}
11617        >>> g.identityOf('C')
11618        '4 (C)'
11619        >>> g.zoneParents(4)  # not in any zones, 'cause still unexplored
11620        set()
11621        >>> e.observe(
11622        ...     'C',
11623        ...     'right',
11624        ...     base.DecisionSpecifier('main', 'Z2', 'D'),
11625        ... )  # creates zone
11626        5
11627        >>> g.destinationsFrom('C')
11628        {'up': 0, 'right': 5}
11629        >>> g.destinationsFrom('D')  # no reciprocal if not specified
11630        {}
11631        >>> g.identityOf('D')
11632        '5 (Z2::D)'
11633        >>> g.zoneParents(5)
11634        {'Z2'}
11635        """
11636        now = self.getSituation()
11637        fromID = now.graph.resolveDecision(where)
11638
11639        kwargs: Dict[
11640            str,
11641            Union[base.Transition, base.DecisionName, None]
11642        ] = {}
11643        if reciprocal is not None:
11644            kwargs['reciprocal'] = reciprocal
11645
11646        if destination is not None:
11647            try:
11648                destID = now.graph.resolveDecision(destination)
11649                now.graph.addTransition(
11650                    fromID,
11651                    transition,
11652                    destID,
11653                    reciprocal
11654                )
11655                return destID
11656            except MissingDecisionError:
11657                if isinstance(destination, base.DecisionSpecifier):
11658                    kwargs['toDomain'] = destination.domain
11659                    kwargs['placeInZone'] = destination.zone
11660                    kwargs['destinationName'] = destination.name
11661                elif isinstance(destination, base.DecisionName):
11662                    kwargs['destinationName'] = destination
11663                else:
11664                    assert isinstance(destination, base.DecisionID)
11665                    # We got to except by failing to resolve, so it's an
11666                    # invalid ID
11667                    raise
11668
11669        result = now.graph.addUnexploredEdge(
11670            fromID,
11671            transition,
11672            **kwargs  # type: ignore [arg-type]
11673        )
11674        if 'destinationName' in kwargs:
11675            self.setExplorationStatus(result, 'noticed', upgradeOnly=True)
11676        return result
11677
11678    def observeMechanisms(
11679        self,
11680        where: Optional[base.AnyDecisionSpecifier],
11681        *mechanisms: Union[
11682            base.MechanismName,
11683            Tuple[base.MechanismName, base.MechanismState]
11684        ]
11685    ) -> List[base.MechanismID]:
11686        """
11687        Adds one or more mechanisms to the exploration's current graph,
11688        located at the specified decision. Global mechanisms can be
11689        added by using `None` for the location. Mechanisms are named, or
11690        a (name, state) tuple can be used to set them into a specific
11691        state. Mechanisms not set to a state will be in the
11692        `base.DEFAULT_MECHANISM_STATE`.
11693        """
11694        now = self.getSituation()
11695        result = []
11696        for mSpec in mechanisms:
11697            setState = None
11698            if isinstance(mSpec, base.MechanismName):
11699                result.append(now.graph.addMechanism(mSpec, where))
11700            elif (
11701                isinstance(mSpec, tuple)
11702            and len(mSpec) == 2
11703            and isinstance(mSpec[0], base.MechanismName)
11704            and isinstance(mSpec[1], base.MechanismState)
11705            ):
11706                result.append(now.graph.addMechanism(mSpec[0], where))
11707                setState = mSpec[1]
11708            else:
11709                raise TypeError(
11710                    f"Invalid mechanism: {repr(mSpec)} (must be a"
11711                    f" mechanism name or a (name, state) tuple."
11712                )
11713
11714            if setState:
11715                self.setMechanismStateNow(result[-1], setState)
11716
11717        return result
11718
11719    def reZone(
11720        self,
11721        zone: Optional[base.Zone],
11722        where: base.AnyDecisionSpecifier,
11723        replace: Union[base.Zone, int] = 0
11724    ) -> None:
11725        """
11726        Alters the current graph without adding a new exploration step.
11727
11728        When given an integer `replace` value, calls
11729        `DecisionGraph.replaceZonesInHierarchy` targeting the
11730        specified decision, replacing ALL zones at the specified
11731        hierarchy level.
11732
11733        If given a zone to replace instead, replaces just that zone by
11734        thoroughly removing the given decision from that zone and then
11735        adding it to the new target zone directly. Thorough removal may
11736        affect membership in other zones...
11737
11738        Use `None` as the zone name to instead remove the current
11739        decision from all zones at the specified hierarchy level, or
11740        from the specified single zone (this uses thorough removal so
11741        may affect membership in lower-level zones).
11742        """
11743        graph = self.getSituation().graph
11744        dID = graph.resolveDecision(where)
11745
11746        if isinstance(replace, int):
11747            # Replace/discard all zones at level
11748            if zone is None:
11749                # Remove from ALL zones at specified level
11750                for escape in graph.zoneAncestors(dID, atLevel=replace):
11751                    graph.removeDecisionFromZone(dID, escape, True)
11752            else:
11753                graph.replaceZonesInHierarchy(dID, zone, replace)
11754        else:
11755            # Replace specific zone
11756            graph.removeDecisionFromZone(dID, replace, True)
11757            if zone is not None:
11758                graph.addDecisionToZone(dID, zone)
11759
11760    def runCommand(
11761        self,
11762        command: commands.Command,
11763        scope: Optional[commands.Scope] = None,
11764        line: int = -1
11765    ) -> commands.CommandResult:
11766        """
11767        Runs a single `Command` applying effects to the exploration, its
11768        current graph, and the provided execution context, and returning
11769        a command result, which contains the modified scope plus
11770        optional skip and label values (see `CommandResult`). This
11771        function also directly modifies the scope you give it. Variable
11772        references in the command are resolved via entries in the
11773        provided scope. If no scope is given, an empty one is created.
11774
11775        A line number may be supplied for use in error messages; if left
11776        out line -1 will be used.
11777
11778        Raises an error if the command is invalid.
11779
11780        For commands that establish a value as the 'current value', that
11781        value will be stored in the '_' variable. When this happens, the
11782        old contents of '_' are stored in '__' first, and the old
11783        contents of '__' are discarded. Note that non-automatic
11784        assignment to '_' does not move the old value to '__'.
11785        """
11786        try:
11787            if scope is None:
11788                scope = {}
11789
11790            skip: Union[int, str, None] = None
11791            label: Optional[str] = None
11792
11793            if command.command == 'val':
11794                command = cast(commands.LiteralValue, command)
11795                result = commands.resolveValue(command.value, scope)
11796                commands.pushCurrentValue(scope, result)
11797
11798            elif command.command == 'empty':
11799                command = cast(commands.EstablishCollection, command)
11800                collection = commands.resolveVarName(command.collection, scope)
11801                commands.pushCurrentValue(
11802                    scope,
11803                    {
11804                        'list': [],
11805                        'tuple': (),
11806                        'set': set(),
11807                        'dict': {},
11808                    }[collection]
11809                )
11810
11811            elif command.command == 'append':
11812                command = cast(commands.AppendValue, command)
11813                target = scope['_']
11814                addIt = commands.resolveValue(command.value, scope)
11815                if isinstance(target, list):
11816                    target.append(addIt)
11817                elif isinstance(target, tuple):
11818                    scope['_'] = target + (addIt,)
11819                elif isinstance(target, set):
11820                    target.add(addIt)
11821                elif isinstance(target, dict):
11822                    raise TypeError(
11823                        "'append' command cannot be used with a"
11824                        " dictionary. Use 'set' instead."
11825                    )
11826                else:
11827                    raise TypeError(
11828                        f"Invalid current value for 'append' command."
11829                        f" The current value must be a list, tuple, or"
11830                        f" set, but it was a '{type(target).__name__}'."
11831                    )
11832
11833            elif command.command == 'set':
11834                command = cast(commands.SetValue, command)
11835                target = scope['_']
11836                where = commands.resolveValue(command.location, scope)
11837                what = commands.resolveValue(command.value, scope)
11838                if isinstance(target, list):
11839                    if not isinstance(where, int):
11840                        raise TypeError(
11841                            f"Cannot set item in list: index {where!r}"
11842                            f" is not an integer."
11843                        )
11844                    target[where] = what
11845                elif isinstance(target, tuple):
11846                    if not isinstance(where, int):
11847                        raise TypeError(
11848                            f"Cannot set item in tuple: index {where!r}"
11849                            f" is not an integer."
11850                        )
11851                    if not (
11852                        0 <= where < len(target)
11853                    or -1 >= where >= -len(target)
11854                    ):
11855                        raise IndexError(
11856                            f"Cannot set item in tuple at index"
11857                            f" {where}: Tuple has length {len(target)}."
11858                        )
11859                    scope['_'] = target[:where] + (what,) + target[where + 1:]
11860                elif isinstance(target, set):
11861                    if what:
11862                        target.add(where)
11863                    else:
11864                        try:
11865                            target.remove(where)
11866                        except KeyError:
11867                            pass
11868                elif isinstance(target, dict):
11869                    target[where] = what
11870
11871            elif command.command == 'pop':
11872                command = cast(commands.PopValue, command)
11873                target = scope['_']
11874                if isinstance(target, list):
11875                    result = target.pop()
11876                    commands.pushCurrentValue(scope, result)
11877                elif isinstance(target, tuple):
11878                    result = target[-1]
11879                    updated = target[:-1]
11880                    scope['__'] = updated
11881                    scope['_'] = result
11882                else:
11883                    raise TypeError(
11884                        f"Cannot 'pop' from a {type(target).__name__}"
11885                        f" (current value must be a list or tuple)."
11886                    )
11887
11888            elif command.command == 'get':
11889                command = cast(commands.GetValue, command)
11890                target = scope['_']
11891                where = commands.resolveValue(command.location, scope)
11892                if isinstance(target, list):
11893                    if not isinstance(where, int):
11894                        raise TypeError(
11895                            f"Cannot get item from list: index"
11896                            f" {where!r} is not an integer."
11897                        )
11898                elif isinstance(target, tuple):
11899                    if not isinstance(where, int):
11900                        raise TypeError(
11901                            f"Cannot get item from tuple: index"
11902                            f" {where!r} is not an integer."
11903                        )
11904                elif isinstance(target, set):
11905                    result = where in target
11906                    commands.pushCurrentValue(scope, result)
11907                elif isinstance(target, dict):
11908                    result = target[where]
11909                    commands.pushCurrentValue(scope, result)
11910                else:
11911                    result = getattr(target, where)
11912                    commands.pushCurrentValue(scope, result)
11913
11914            elif command.command == 'remove':
11915                command = cast(commands.RemoveValue, command)
11916                target = scope['_']
11917                where = commands.resolveValue(command.location, scope)
11918                if isinstance(target, (list, tuple)):
11919                    # this cast is not correct but suppresses warnings
11920                    # given insufficient narrowing by MyPy
11921                    target = cast(Tuple[Any, ...], target)
11922                    if not isinstance(where, int):
11923                        raise TypeError(
11924                            f"Cannot remove item from list or tuple:"
11925                            f" index {where!r} is not an integer."
11926                        )
11927                    scope['_'] = target[:where] + target[where + 1:]
11928                elif isinstance(target, set):
11929                    target.remove(where)
11930                elif isinstance(target, dict):
11931                    del target[where]
11932                else:
11933                    raise TypeError(
11934                        f"Cannot use 'remove' on a/an"
11935                        f" {type(target).__name__}."
11936                    )
11937
11938            elif command.command == 'op':
11939                command = cast(commands.ApplyOperator, command)
11940                left = commands.resolveValue(command.left, scope)
11941                right = commands.resolveValue(command.right, scope)
11942                op = command.op
11943                if op == '+':
11944                    result = left + right
11945                elif op == '-':
11946                    result = left - right
11947                elif op == '*':
11948                    result = left * right
11949                elif op == '/':
11950                    result = left / right
11951                elif op == '//':
11952                    result = left // right
11953                elif op == '**':
11954                    result = left ** right
11955                elif op == '%':
11956                    result = left % right
11957                elif op == '^':
11958                    result = left ^ right
11959                elif op == '|':
11960                    result = left | right
11961                elif op == '&':
11962                    result = left & right
11963                elif op == 'and':
11964                    result = left and right
11965                elif op == 'or':
11966                    result = left or right
11967                elif op == '<':
11968                    result = left < right
11969                elif op == '>':
11970                    result = left > right
11971                elif op == '<=':
11972                    result = left <= right
11973                elif op == '>=':
11974                    result = left >= right
11975                elif op == '==':
11976                    result = left == right
11977                elif op == 'is':
11978                    result = left is right
11979                else:
11980                    raise RuntimeError("Invalid operator '{op}'.")
11981
11982                commands.pushCurrentValue(scope, result)
11983
11984            elif command.command == 'unary':
11985                command = cast(commands.ApplyUnary, command)
11986                value = commands.resolveValue(command.value, scope)
11987                op = command.op
11988                if op == '-':
11989                    result = -value
11990                elif op == '~':
11991                    result = ~value
11992                elif op == 'not':
11993                    result = not value
11994
11995                commands.pushCurrentValue(scope, result)
11996
11997            elif command.command == 'assign':
11998                command = cast(commands.VariableAssignment, command)
11999                varname = commands.resolveVarName(command.varname, scope)
12000                value = commands.resolveValue(command.value, scope)
12001                scope[varname] = value
12002
12003            elif command.command == 'delete':
12004                command = cast(commands.VariableDeletion, command)
12005                varname = commands.resolveVarName(command.varname, scope)
12006                del scope[varname]
12007
12008            elif command.command == 'load':
12009                command = cast(commands.LoadVariable, command)
12010                varname = commands.resolveVarName(command.varname, scope)
12011                commands.pushCurrentValue(scope, scope[varname])
12012
12013            elif command.command == 'call':
12014                command = cast(commands.FunctionCall, command)
12015                function = command.function
12016                if function.startswith('$'):
12017                    function = commands.resolveValue(function, scope)
12018
12019                toCall: Callable
12020                args: Tuple[str, ...]
12021                kwargs: Dict[str, Any]
12022
12023                if command.target == 'builtin':
12024                    toCall = commands.COMMAND_BUILTINS[function]
12025                    args = (scope['_'],)
12026                    kwargs = {}
12027                    if toCall == round:
12028                        if 'ndigits' in scope:
12029                            kwargs['ndigits'] = scope['ndigits']
12030                    elif toCall == range and args[0] is None:
12031                        start = scope.get('start', 0)
12032                        stop = scope['stop']
12033                        step = scope.get('step', 1)
12034                        args = (start, stop, step)
12035
12036                else:
12037                    if command.target == 'stored':
12038                        toCall = function
12039                    elif command.target == 'graph':
12040                        toCall = getattr(self.getSituation().graph, function)
12041                    elif command.target == 'exploration':
12042                        toCall = getattr(self, function)
12043                    else:
12044                        raise TypeError(
12045                            f"Invalid call target '{command.target}'"
12046                            f" (must be one of 'builtin', 'stored',"
12047                            f" 'graph', or 'exploration'."
12048                        )
12049
12050                    # Fill in arguments via kwargs defined in scope
12051                    args = ()
12052                    kwargs = {}
12053                    signature = inspect.signature(toCall)
12054                    # TODO: Maybe try some type-checking here?
12055                    for argName, param in signature.parameters.items():
12056                        if param.kind == inspect.Parameter.VAR_POSITIONAL:
12057                            if argName in scope:
12058                                args = args + tuple(scope[argName])
12059                            # Else leave args as-is
12060                        elif param.kind == inspect.Parameter.KEYWORD_ONLY:
12061                            # These must have a default
12062                            if argName in scope:
12063                                kwargs[argName] = scope[argName]
12064                        elif param.kind == inspect.Parameter.VAR_KEYWORD:
12065                            # treat as a dictionary
12066                            if argName in scope:
12067                                argsToUse = scope[argName]
12068                                if not isinstance(argsToUse, dict):
12069                                    raise TypeError(
12070                                        f"Variable '{argName}' must"
12071                                        f" hold a dictionary when"
12072                                        f" calling function"
12073                                        f" '{toCall.__name__} which"
12074                                        f" uses that argument as a"
12075                                        f" keyword catchall."
12076                                    )
12077                                kwargs.update(scope[argName])
12078                        else:  # a normal parameter
12079                            if argName in scope:
12080                                args = args + (scope[argName],)
12081                            elif param.default == inspect.Parameter.empty:
12082                                raise TypeError(
12083                                    f"No variable named '{argName}' has"
12084                                    f" been defined to supply the"
12085                                    f" required parameter with that"
12086                                    f" name for function"
12087                                    f" '{toCall.__name__}'."
12088                                )
12089
12090                result = toCall(*args, **kwargs)
12091                commands.pushCurrentValue(scope, result)
12092
12093            elif command.command == 'skip':
12094                command = cast(commands.SkipCommands, command)
12095                doIt = commands.resolveValue(command.condition, scope)
12096                if doIt:
12097                    skip = commands.resolveValue(command.amount, scope)
12098                    if not isinstance(skip, (int, str)):
12099                        raise TypeError(
12100                            f"Skip amount must be an integer or a label"
12101                            f" name (got {skip!r})."
12102                        )
12103
12104            elif command.command == 'label':
12105                command = cast(commands.Label, command)
12106                label = commands.resolveValue(command.name, scope)
12107                if not isinstance(label, str):
12108                    raise TypeError(
12109                        f"Label name must be a string (got {label!r})."
12110                    )
12111
12112            else:
12113                raise ValueError(
12114                    f"Invalid command type: {command.command!r}"
12115                )
12116        except ValueError as e:
12117            raise commands.CommandValueError(command, line, e)
12118        except TypeError as e:
12119            raise commands.CommandTypeError(command, line, e)
12120        except IndexError as e:
12121            raise commands.CommandIndexError(command, line, e)
12122        except KeyError as e:
12123            raise commands.CommandKeyError(command, line, e)
12124        except Exception as e:
12125            raise commands.CommandOtherError(command, line, e)
12126
12127        return (scope, skip, label)
12128
12129    def runCommandBlock(
12130        self,
12131        block: List[commands.Command],
12132        scope: Optional[commands.Scope] = None
12133    ) -> commands.Scope:
12134        """
12135        Runs a list of commands, using the given scope (or creating a new
12136        empty scope if none was provided). Returns the scope after
12137        running all of the commands, which may also edit the exploration
12138        and/or the current graph of course.
12139
12140        Note that if a skip command would skip past the end of the
12141        block, execution will end. If a skip command would skip before
12142        the beginning of the block, execution will start from the first
12143        command.
12144
12145        Example:
12146
12147        >>> e = DiscreteExploration()
12148        >>> scope = e.runCommandBlock([
12149        ...    commands.command('assign', 'decision', "'START'"),
12150        ...    commands.command('call', 'exploration', 'start'),
12151        ...    commands.command('assign', 'where', '$decision'),
12152        ...    commands.command('assign', 'transition', "'left'"),
12153        ...    commands.command('call', 'exploration', 'observe'),
12154        ...    commands.command('assign', 'transition', "'right'"),
12155        ...    commands.command('call', 'exploration', 'observe'),
12156        ...    commands.command('call', 'graph', 'destinationsFrom'),
12157        ...    commands.command('call', 'builtin', 'print'),
12158        ...    commands.command('assign', 'transition', "'right'"),
12159        ...    commands.command('assign', 'destination', "'EastRoom'"),
12160        ...    commands.command('call', 'exploration', 'explore'),
12161        ... ])
12162        {'left': 1, 'right': 2}
12163        >>> scope['decision']
12164        'START'
12165        >>> scope['where']
12166        'START'
12167        >>> scope['_']  # result of 'explore' call is dest ID
12168        2
12169        >>> scope['transition']
12170        'right'
12171        >>> scope['destination']
12172        'EastRoom'
12173        >>> g = e.getSituation().graph
12174        >>> len(e)
12175        3
12176        >>> len(g)
12177        3
12178        >>> g.namesListing(g)
12179        '  0 (START)\\n  1 (_u.0)\\n  2 (EastRoom)\\n'
12180        """
12181        if scope is None:
12182            scope = {}
12183
12184        labelPositions: Dict[str, List[int]] = {}
12185
12186        # Keep going until we've exhausted the commands list
12187        index = 0
12188        while index < len(block):
12189
12190            # Execute the next command
12191            scope, skip, label = self.runCommand(
12192                block[index],
12193                scope,
12194                index + 1
12195            )
12196
12197            # Increment our index, or apply a skip
12198            if skip is None:
12199                index = index + 1
12200
12201            elif isinstance(skip, int):  # Integer skip value
12202                if skip < 0:
12203                    index += skip
12204                    if index < 0:  # can't skip before the start
12205                        index = 0
12206                else:
12207                    index += skip + 1  # may end loop if we skip too far
12208
12209            else:  # must be a label name
12210                if skip in labelPositions:  # an established label
12211                    # We jump to the last previous index, or if there
12212                    # are none, to the first future index.
12213                    prevIndices = [
12214                        x
12215                        for x in labelPositions[skip]
12216                        if x < index
12217                    ]
12218                    futureIndices = [
12219                        x
12220                        for x in labelPositions[skip]
12221                        if x >= index
12222                    ]
12223                    if len(prevIndices) > 0:
12224                        index = max(prevIndices)
12225                    else:
12226                        index = min(futureIndices)
12227                else:  # must be a forward-reference
12228                    for future in range(index + 1, len(block)):
12229                        inspect = block[future]
12230                        if inspect.command == 'label':
12231                            inspect = cast(commands.Label, inspect)
12232                            if inspect.name == skip:
12233                                index = future
12234                                break
12235                    else:
12236                        raise KeyError(
12237                            f"Skip command indicated a jump to label"
12238                            f" {skip!r} but that label had not already"
12239                            f" been defined and there is no future"
12240                            f" label with that name either (future"
12241                            f" labels based on variables cannot be"
12242                            f" skipped to from above as their names"
12243                            f" are not known yet)."
12244                        )
12245
12246            # If there's a label, record it
12247            if label is not None:
12248                labelPositions.setdefault(label, []).append(index)
12249
12250            # And now the while loop continues, or ends if we're at the
12251            # end of the commands list.
12252
12253        # Return the scope object.
12254        return scope
12255
12256    @staticmethod
12257    def example() -> 'DiscreteExploration':
12258        """
12259        Returns a little example exploration. Has a few decisions
12260        including one that's unexplored, and uses a few steps to explore
12261        them.
12262
12263        >>> e = DiscreteExploration.example()
12264        >>> len(e)
12265        7
12266        >>> def pg(n):
12267        ...     print(e[n].graph.namesListing(e[n].graph))
12268        >>> pg(0)
12269          0 (House)
12270        <BLANKLINE>
12271        >>> pg(1)
12272          0 (House)
12273          1 (_u.0)
12274          2 (_u.1)
12275          3 (_u.2)
12276        <BLANKLINE>
12277        >>> pg(2)
12278          0 (House)
12279          1 (_u.0)
12280          2 (_u.1)
12281          3 (Yard)
12282          4 (_u.3)
12283          5 (_u.4)
12284        <BLANKLINE>
12285        >>> pg(3)
12286          0 (House)
12287          1 (_u.0)
12288          2 (_u.1)
12289          3 (Yard)
12290          4 (_u.3)
12291          5 (_u.4)
12292        <BLANKLINE>
12293        >>> pg(4)
12294          0 (House)
12295          1 (_u.0)
12296          2 (Cellar)
12297          3 (Yard)
12298          5 (_u.4)
12299        <BLANKLINE>
12300        >>> pg(5)
12301          0 (House)
12302          1 (_u.0)
12303          2 (Cellar)
12304          3 (Yard)
12305          5 (_u.4)
12306        <BLANKLINE>
12307        >>> pg(6)
12308          0 (House)
12309          1 (_u.0)
12310          2 (Cellar)
12311          3 (Yard)
12312          5 (Lane)
12313        <BLANKLINE>
12314        """
12315        result = DiscreteExploration()
12316        result.start("House")
12317        result.observeAll("House", "ladder", "stairsDown", "frontDoor")
12318        result.explore("frontDoor", "Yard", "frontDoor")
12319        result.observe("Yard", "cellarDoors")
12320        result.observe("Yard", "frontGate")
12321        result.retrace("frontDoor")
12322        result.explore("stairsDown", "Cellar", "stairsUp")
12323        result.observe("Cellar", "stairsOut")
12324        result.returnTo("stairsOut", "Yard", "cellarDoors")
12325        result.explore("frontGate", "Lane", "redGate")
12326        return result