flakepl 0.3.1__py3-none-any.whl

flake/epistemic.py

@@ -0,0 +1,2068 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Iterable, Mapping
+
+from .agent import Agent
+from .dynamic import (
+    ActionModel,
+    DynamicEvent,
+    PublicAnnouncement,
+)
+from .explorer import StateSpace
+from .formula import (
+    And,
+    Atom,
+    Formula,
+    Not,
+    Or,
+)
+from .observation import (
+    Observation,
+    ObservationBuilder,
+)
+from .propositions import Proposition
+from .runtime import Configuration
+from .temporal import (
+    Always,
+    Eventually,
+    Next,
+    Until,
+)
+
+
+# ============================================================================
+# World types
+# ============================================================================
+
+
+@dataclass(frozen=True, slots=True)
+class ProductWorld:
+    """
+    World generated by a dynamic epistemic product update.
+
+    A ProductWorld is a pair:
+
+        (base world, executed event)
+
+    The base Configuration represents the physical world.
+    The event represents the epistemic action that occurred.
+    """
+
+    world: Configuration
+    event: str
+
+    def __repr__(self) -> str:
+        return (
+            f"ProductWorld("
+            f"world={self.world!r}, "
+            f"event={self.event!r}"
+            f")"
+        )
+
+
+World = Configuration | ProductWorld
+
+
+def _configuration(
+    world: World,
+) -> Configuration:
+    """
+    Extract the underlying physical configuration.
+    """
+
+    if isinstance(
+        world,
+        ProductWorld,
+    ):
+        return world.world
+
+    return world
+
+
+# ============================================================================
+# Epistemic operators
+# ============================================================================
+
+
+@dataclass(frozen=True, slots=True)
+class Knowledge(Formula):
+    """
+    K_i φ
+
+    Agent i knows φ.
+    """
+
+    agent: str
+    operand: Formula
+
+    def __post_init__(self) -> None:
+        if not self.agent.strip():
+            raise ValueError(
+                "Knowledge agent must not be empty"
+            )
+
+    def __repr__(self) -> str:
+        return (
+            f"K_{self.agent}({self.operand!r})"
+        )
+
+
+def K(
+    agent: str | Agent,
+    operand: Formula,
+) -> Knowledge:
+    """
+    Factory for K_i φ.
+    """
+
+    name = (
+        agent.name
+        if isinstance(
+            agent,
+            Agent,
+        )
+        else agent
+    )
+
+    return Knowledge(
+        agent=name,
+        operand=operand,
+    )
+
+
+# ============================================================================
+# Group operators
+# ============================================================================
+
+
+def _normalize_group(
+    agents: (
+        str
+        | Agent
+        | Iterable[str | Agent]
+    ),
+) -> tuple[str, ...]:
+    if isinstance(
+        agents,
+        Agent,
+    ):
+        values = (
+            agents.name,
+        )
+
+    elif isinstance(
+        agents,
+        str,
+    ):
+        values = (
+            agents,
+        )
+
+    else:
+        values = tuple(
+            agent.name
+            if isinstance(
+                agent,
+                Agent,
+            )
+            else agent
+            for agent in agents
+        )
+
+    if not values:
+        raise ValueError(
+            "An epistemic group must not be empty"
+        )
+
+    result: list[str] = []
+
+    for name in values:
+        if not isinstance(
+            name,
+            str,
+        ):
+            raise TypeError(
+                "Agent names must be strings or Agent objects"
+            )
+
+        name = name.strip()
+
+        if not name:
+            raise ValueError(
+                "Agent name must not be empty"
+            )
+
+        if name not in result:
+            result.append(
+                name
+            )
+
+    return tuple(result)
+
+
+@dataclass(frozen=True, slots=True)
+class EveryoneKnows(Formula):
+    """
+    E_A φ
+
+    Every agent in A knows φ.
+    """
+
+    agents: tuple[str, ...]
+    operand: Formula
+
+    def __repr__(self) -> str:
+        group = ",".join(
+            self.agents
+        )
+
+        return (
+            f"E_{{{group}}}({self.operand!r})"
+        )
+
+
+def E(
+    agents: (
+        str
+        | Agent
+        | Iterable[str | Agent]
+    ),
+    operand: Formula,
+) -> EveryoneKnows:
+    return EveryoneKnows(
+        agents=_normalize_group(
+            agents
+        ),
+        operand=operand,
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class DistributedKnowledge(Formula):
+    """
+    D_A φ
+
+    Distributed knowledge of a group.
+    """
+
+    agents: tuple[str, ...]
+    operand: Formula
+
+    def __repr__(self) -> str:
+        group = ",".join(
+            self.agents
+        )
+
+        return (
+            f"D_{{{group}}}({self.operand!r})"
+        )
+
+
+def D(
+    agents: (
+        str
+        | Agent
+        | Iterable[str | Agent]
+    ),
+    operand: Formula,
+) -> DistributedKnowledge:
+    return DistributedKnowledge(
+        agents=_normalize_group(
+            agents
+        ),
+        operand=operand,
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class CommonKnowledge(Formula):
+    """
+    C_A φ
+
+    Common knowledge in a group.
+    """
+
+    agents: tuple[str, ...]
+    operand: Formula
+
+    def __repr__(self) -> str:
+        group = ",".join(
+            self.agents
+        )
+
+        return (
+            f"C_{{{group}}}({self.operand!r})"
+        )
+
+
+def C(
+    agents: (
+        str
+        | Agent
+        | Iterable[str | Agent]
+    ),
+    operand: Formula,
+) -> CommonKnowledge:
+    return CommonKnowledge(
+        agents=_normalize_group(
+            agents
+        ),
+        operand=operand,
+    )
+
+
+# ============================================================================
+# Observation mapping
+# ============================================================================
+
+
+ObservationMap = Mapping[
+    str | Agent,
+    Observation,
+]
+
+
+def _normalize_observations(
+    observations: (
+        ObservationMap
+        | ObservationBuilder
+    ),
+    agent_names: Iterable[str],
+) -> dict[
+    str,
+    Observation,
+]:
+    names = tuple(
+        agent_names
+    )
+
+    if isinstance(
+        observations,
+        ObservationBuilder,
+    ):
+        return observations.build(
+            names
+        )
+
+    result: dict[
+        str,
+        Observation,
+    ] = {}
+
+    for key, observation in observations.items():
+        name = (
+            key.name
+            if isinstance(
+                key,
+                Agent,
+            )
+            else key
+        )
+
+        if not isinstance(
+            name,
+            str,
+        ):
+            raise TypeError(
+                "Observation keys must be strings or Agent objects"
+            )
+
+        name = name.strip()
+
+        if not name:
+            raise ValueError(
+                "Observation agent name must not be empty"
+            )
+
+        if name in result:
+            raise ValueError(
+                f"Duplicate observation "
+                f"for agent {name!r}"
+            )
+
+        result[name] = observation
+
+    expected = set(
+        names
+    )
+    actual = set(
+        result
+    )
+
+    missing = expected - actual
+    extra = actual - expected
+
+    if missing:
+        missing_text = ", ".join(
+            sorted(missing)
+        )
+
+        raise ValueError(
+            f"Missing observations for agents: "
+            f"{missing_text}"
+        )
+
+    if extra:
+        extra_text = ", ".join(
+            sorted(extra)
+        )
+
+        raise ValueError(
+            f"Observations defined for unknown agents: "
+            f"{extra_text}"
+        )
+
+    return result
+
+
+# ============================================================================
+# Epistemic relation overrides
+# ============================================================================
+
+
+RelationMap = Mapping[
+    str,
+    Mapping[
+        World,
+        Iterable[World],
+    ],
+]
+
+
+def _normalize_relation_overrides(
+    relations: RelationMap | None,
+    worlds: tuple[World, ...],
+    agent_names: tuple[str, ...],
+) -> dict[
+    str,
+    dict[
+        World,
+        tuple[World, ...],
+    ],
+]:
+    if relations is None:
+        return {}
+
+    world_set = set(
+        worlds
+    )
+
+    agent_set = set(
+        agent_names
+    )
+
+    result: dict[
+        str,
+        dict[
+            World,
+            tuple[World, ...],
+        ],
+    ] = {}
+
+    for agent, relation in relations.items():
+        if agent not in agent_set:
+            raise ValueError(
+                f"Unknown agent {agent!r} "
+                f"in relation override"
+            )
+
+        source_map: dict[
+            World,
+            tuple[World, ...],
+        ] = {}
+
+        for source, targets in relation.items():
+            if source not in world_set:
+                raise ValueError(
+                    "Relation override contains "
+                    "an unknown source world"
+                )
+
+            target_tuple = tuple(
+                targets
+            )
+
+            for target in target_tuple:
+                if target not in world_set:
+                    raise ValueError(
+                        "Relation override contains "
+                        "an unknown target world"
+                    )
+
+            source_map[source] = target_tuple
+
+        result[agent] = source_map
+
+    return result
+
+
+# ============================================================================
+# Epistemic model
+# ============================================================================
+
+
+class EpistemicModel:
+    """
+    Finite epistemic model.
+
+    Standard models derive R_i from observations:
+
+        w R_i v  iff  h_i(w) = h_i(v)
+
+    Dynamic epistemic product updates can install explicit
+    relation overrides:
+
+        (w,e) R_i' (v,f)
+
+        iff
+
+            w R_i v
+
+        and
+
+            e R_i^A f
+
+    Temporal operators require a transition structure when
+    one is available.
+
+    If no StateSpace is attached, the model is treated as a
+    static model with implicit stuttering:
+
+        w -> w
+
+    This makes temporal queries such as G(phi) meaningful for
+    a purely epistemic snapshot.
+    """
+
+    def __init__(
+        self,
+        worlds: Iterable[World],
+        observations: (
+            ObservationMap
+            | ObservationBuilder
+        ),
+        actual: World,
+        propositions: (
+            Iterable[Proposition]
+            | Mapping[str, Proposition]
+            | None
+        ) = None,
+        state_space: StateSpace | None = None,
+        relations: RelationMap | None = None,
+    ) -> None:
+        world_tuple = tuple(
+            worlds
+        )
+
+        if not world_tuple:
+            raise ValueError(
+                "EpistemicModel requires at least one world"
+            )
+
+        if actual not in world_tuple:
+            raise ValueError(
+                "Actual world must belong to worlds"
+            )
+
+        if (
+            state_space is not None
+            and any(
+                not isinstance(
+                    world,
+                    Configuration,
+                )
+                for world in world_tuple
+            )
+        ):
+            raise ValueError(
+                "StateSpace can only be attached "
+                "to Configuration worlds"
+            )
+
+        reference_configuration = (
+            _configuration(
+                world_tuple[0]
+            )
+        )
+
+        reference_agents = tuple(
+            reference_configuration.agents
+        )
+
+        reference_names = tuple(
+            agent.name
+            for agent in reference_agents
+        )
+
+        reference_name_set = set(
+            reference_names
+        )
+
+        for world in world_tuple:
+            current_names = {
+                agent.name
+                for agent in _configuration(
+                    world
+                ).agents
+            }
+
+            if current_names != reference_name_set:
+                raise ValueError(
+                    "All epistemic worlds must contain "
+                    "the same agents"
+                )
+
+        if state_space is not None:
+            state_space_states = set(
+                state_space.states
+            )
+
+            if not set(
+                world_tuple
+            ).issubset(
+                state_space_states
+            ):
+                raise ValueError(
+                    "All epistemic worlds must belong "
+                    "to the attached StateSpace"
+                )
+
+        self._worlds = world_tuple
+        self._actual = actual
+
+        self._agents = reference_agents
+        self._agent_names = reference_names
+
+        self._observations = (
+            _normalize_observations(
+                observations,
+                self._agent_names,
+            )
+        )
+
+        self._propositions = (
+            self._normalize_propositions(
+                propositions
+            )
+        )
+
+        self._state_space = state_space
+
+        self._relation_overrides = (
+            _normalize_relation_overrides(
+                relations,
+                world_tuple,
+                self._agent_names,
+            )
+        )
+
+        self._successors_map = (
+            self._build_successors_map(
+                state_space
+            )
+            if state_space is not None
+            else {}
+        )
+
+    # ---------------------------------------------------------------------
+    # Construction
+    # ---------------------------------------------------------------------
+
+    @classmethod
+    def from_state_space(
+        cls,
+        state_space: StateSpace,
+        observations: (
+            ObservationMap
+            | ObservationBuilder
+        ),
+        actual: Configuration | None = None,
+        propositions: (
+            Iterable[Proposition]
+            | Mapping[str, Proposition]
+            | None
+        ) = None,
+    ) -> "EpistemicModel":
+        if not state_space.initials:
+            raise ValueError(
+                "StateSpace must contain at least one initial"
+            )
+
+        if actual is None:
+            if len(
+                state_space.initials
+            ) != 1:
+                raise ValueError(
+                    "actual must be specified when the state "
+                    "space has multiple initial worlds"
+                )
+
+            actual = state_space.initials[0]
+
+        return cls(
+            worlds=state_space.states,
+            observations=observations,
+            actual=actual,
+            propositions=propositions,
+            state_space=state_space,
+        )
+
+    # ---------------------------------------------------------------------
+    # Public properties
+    # ---------------------------------------------------------------------
+
+    @property
+    def worlds(
+        self,
+    ) -> tuple[World, ...]:
+        return self._worlds
+
+    @property
+    def actual(
+        self,
+    ) -> World:
+        return self._actual
+
+    @property
+    def agents(
+        self,
+    ) -> tuple[Agent, ...]:
+        return self._agents
+
+    @property
+    def propositions(
+        self,
+    ) -> Mapping[str, Proposition]:
+        return self._propositions
+
+    @property
+    def state_space(
+        self,
+    ) -> StateSpace | None:
+        return self._state_space
+
+    # ---------------------------------------------------------------------
+    # Agent helpers
+    # ---------------------------------------------------------------------
+
+    def _require_agent(
+        self,
+        agent: str | Agent,
+    ) -> str:
+        name = (
+            agent.name
+            if isinstance(
+                agent,
+                Agent,
+            )
+            else agent
+        )
+
+        if name not in self._agent_names:
+            raise ValueError(
+                f"Unknown agent {name!r}"
+            )
+
+        return name
+
+    # ---------------------------------------------------------------------
+    # Observation
+    # ---------------------------------------------------------------------
+
+    def observe(
+        self,
+        agent: str | Agent,
+        world: World,
+    ):
+        name = self._require_agent(
+            agent
+        )
+
+        if world not in self._worlds:
+            raise ValueError(
+                "World does not belong "
+                "to the epistemic model"
+            )
+
+        runtime_agent = (
+            _configuration(
+                world
+            ).agent(
+                name
+            )
+        )
+
+        value = self._observations[name](
+            runtime_agent,
+            _configuration(
+                world
+            ),
+        )
+
+        hash(value)
+
+        return value
+
+    # ---------------------------------------------------------------------
+    # Accessibility
+    # ---------------------------------------------------------------------
+
+    def accessible(
+        self,
+        agent: str | Agent,
+        world: World,
+    ) -> tuple[World, ...]:
+        """
+        Return worlds accessible for an agent.
+
+        Ordinary models use observation equality.
+
+        Product-update models use explicit product relations.
+        """
+
+        name = self._require_agent(
+            agent
+        )
+
+        if world not in self._worlds:
+            raise ValueError(
+                "World does not belong "
+                "to the epistemic model"
+            )
+
+        override = (
+            self._relation_overrides.get(
+                name
+            )
+        )
+
+        if override is not None:
+            return override.get(
+                world,
+                (),
+            )
+
+        target_observation = (
+            self.observe(
+                name,
+                world,
+            )
+        )
+
+        return tuple(
+            candidate
+            for candidate in self._worlds
+            if self.observe(
+                name,
+                candidate,
+            )
+            == target_observation
+        )
+
+    # ---------------------------------------------------------------------
+    # Distributed knowledge
+    # ---------------------------------------------------------------------
+
+    def distributed_accessible(
+        self,
+        agents: (
+            str
+            | Agent
+            | Iterable[str | Agent]
+        ),
+        world: World,
+    ) -> tuple[World, ...]:
+        """
+        Return the intersection of individual epistemic
+        accessibility relations:
+
+            R_DA = ⋂ R_i
+
+        This uses accessible() so product-update relations
+        remain fully respected.
+        """
+
+        group = _normalize_group(
+            agents
+        )
+
+        for agent in group:
+            self._require_agent(
+                agent
+            )
+
+        if world not in self._worlds:
+            raise ValueError(
+                "World does not belong "
+                "to the epistemic model"
+            )
+
+        accessible_sets = [
+            set(
+                self.accessible(
+                    agent,
+                    world,
+                )
+            )
+            for agent in group
+        ]
+
+        if not accessible_sets:
+            return ()
+
+        intersection = accessible_sets[0]
+
+        for accessible_set in accessible_sets[1:]:
+            intersection &= accessible_set
+
+        return tuple(
+            candidate
+            for candidate in self._worlds
+            if candidate in intersection
+        )
+
+    # ---------------------------------------------------------------------
+    # Common knowledge
+    # ---------------------------------------------------------------------
+
+    def common_knowledge_closure(
+        self,
+        agents: (
+            str
+            | Agent
+            | Iterable[str | Agent]
+        ),
+        world: World,
+    ) -> tuple[World, ...]:
+        """
+        Reflexive-transitive closure:
+
+            (⋃ R_i)*
+        """
+
+        group = _normalize_group(
+            agents
+        )
+
+        for agent in group:
+            self._require_agent(
+                agent
+            )
+
+        if world not in self._worlds:
+            raise ValueError(
+                "World does not belong "
+                "to the epistemic model"
+            )
+
+        visited: set[World] = {
+            world
+        }
+
+        queue: list[World] = [
+            world
+        ]
+
+        while queue:
+            current = queue.pop(
+                0
+            )
+
+            for agent in group:
+                for candidate in self.accessible(
+                    agent,
+                    current,
+                ):
+                    if candidate not in visited:
+                        visited.add(
+                            candidate
+                        )
+                        queue.append(
+                            candidate
+                        )
+
+        return tuple(
+            candidate
+            for candidate in self._worlds
+            if candidate in visited
+        )
+
+    # ---------------------------------------------------------------------
+    # Dynamic update API
+    # ---------------------------------------------------------------------
+
+    def update(
+        self,
+        event: DynamicEvent,
+    ) -> "EpistemicModel":
+        """
+        Apply a dynamic epistemic event.
+
+        The current model is never mutated.
+        """
+
+        return event.apply(
+            self
+        )
+
+    def announce(
+        self,
+        formula: Formula,
+    ) -> "EpistemicModel":
+        """
+        Apply a public announcement.
+        """
+
+        return self.update(
+            PublicAnnouncement(
+                formula
+            )
+        )
+
+    def product_update(
+        self,
+        action_model: ActionModel,
+    ) -> "EpistemicModel":
+        """
+        Apply an epistemic ActionModel.
+        """
+
+        return self._apply_action_model(
+            action_model
+        )
+
+    # ---------------------------------------------------------------------
+    # Product update
+    # ---------------------------------------------------------------------
+
+    def _apply_action_model(
+        self,
+        action_model: ActionModel,
+    ) -> "EpistemicModel":
+        """
+        Construct the product model:
+
+            M ⊗ A
+
+        with worlds:
+
+            (w, e)
+
+        for every executable world/event pair.
+
+        Product accessibility is:
+
+            (w,e) R_i' (v,f)
+
+            iff
+
+                w R_i v
+
+            and
+
+                e R_i^A f
+        """
+
+        enabled_pairs: list[
+            tuple[World, str]
+        ] = []
+
+        enabled_pair_set: set[
+            tuple[World, str]
+        ] = set()
+
+        for world in self._worlds:
+            for action_event in action_model.events:
+                if action_event.enabled(
+                    self,
+                    world,
+                ):
+                    pair = (
+                        world,
+                        action_event.name,
+                    )
+
+                    enabled_pairs.append(
+                        pair
+                    )
+
+                    enabled_pair_set.add(
+                        pair
+                    )
+
+        if not enabled_pairs:
+            raise ValueError(
+                "ActionModel has no executable "
+                "world/event pairs"
+            )
+
+        actual_pair = (
+            self._actual,
+            action_model.actual,
+        )
+
+        if actual_pair not in enabled_pair_set:
+            raise ValueError(
+                "Actual action event is not executable "
+                "in the actual world"
+            )
+
+        product_worlds = tuple(
+            ProductWorld(
+                world=world,
+                event=event_name,
+            )
+            for world, event_name
+            in enabled_pairs
+        )
+
+        pair_to_product: dict[
+            tuple[World, str],
+            ProductWorld,
+        ] = {
+            (
+                product.world,
+                product.event,
+            ): product
+            for product in product_worlds
+        }
+
+        actual_product = pair_to_product[
+            actual_pair
+        ]
+
+        relation_overrides: dict[
+            str,
+            dict[
+                ProductWorld,
+                tuple[
+                    ProductWorld,
+                    ...,
+                ],
+            ],
+        ] = {}
+
+        for agent in self._agent_names:
+            source_map: dict[
+                ProductWorld,
+                tuple[
+                    ProductWorld,
+                    ...,
+                ],
+            ] = {}
+
+            for product_world in product_worlds:
+                base_world = (
+                    product_world.world
+                )
+
+                event_name = (
+                    product_world.event
+                )
+
+                base_accessible = (
+                    self.accessible(
+                        agent,
+                        base_world,
+                    )
+                )
+
+                event_accessible = (
+                    action_model.accessible(
+                        agent,
+                        event_name,
+                    )
+                )
+
+                targets: list[
+                    ProductWorld
+                ] = []
+
+                for candidate_base in base_accessible:
+                    for candidate_event in event_accessible:
+                        candidate_pair = (
+                            candidate_base,
+                            candidate_event,
+                        )
+
+                        if (
+                            candidate_pair
+                            not in enabled_pair_set
+                        ):
+                            continue
+
+                        candidate_product = (
+                            pair_to_product[
+                                candidate_pair
+                            ]
+                        )
+
+                        if (
+                            candidate_product
+                            not in targets
+                        ):
+                            targets.append(
+                                candidate_product
+                            )
+
+                source_map[
+                    product_world
+                ] = tuple(
+                    targets
+                )
+
+            relation_overrides[
+                agent
+            ] = source_map
+
+        return EpistemicModel(
+            worlds=product_worlds,
+            observations=self._observations,
+            actual=actual_product,
+            propositions=self._propositions,
+            state_space=None,
+            relations=relation_overrides,
+        )
+
+    # ---------------------------------------------------------------------
+    # Public announcement
+    # ---------------------------------------------------------------------
+
+    def _apply_public_announcement(
+        self,
+        formula: Formula,
+    ) -> "EpistemicModel":
+        """
+        Restrict the current model to worlds where formula holds.
+
+            M | φ
+        """
+
+        retained_worlds = tuple(
+            world
+            for world in self._worlds
+            if self.check(
+                formula,
+                at=world,
+            )
+        )
+
+        if self._actual not in retained_worlds:
+            raise ValueError(
+                "Public announcement is false "
+                "in the actual world"
+            )
+
+        if not retained_worlds:
+            raise ValueError(
+                "Public announcement removed all worlds"
+            )
+
+        updated_state_space = (
+            self._restrict_state_space(
+                retained_worlds
+            )
+            if self._state_space is not None
+            else None
+        )
+
+        updated_relations = (
+            self._restrict_relations(
+                retained_worlds
+            )
+            if self._relation_overrides
+            else None
+        )
+
+        return EpistemicModel(
+            worlds=retained_worlds,
+            observations=self._observations,
+            actual=self._actual,
+            propositions=self._propositions,
+            state_space=updated_state_space,
+            relations=updated_relations,
+        )
+
+    def _restrict_state_space(
+        self,
+        retained_worlds: tuple[World, ...],
+    ) -> StateSpace:
+        """
+        Restrict attached StateSpace to retained worlds.
+        """
+
+        if self._state_space is None:
+            raise ValueError(
+                "Cannot restrict a missing StateSpace"
+            )
+
+        retained = set(
+            retained_worlds
+        )
+
+        initials = tuple(
+            initial
+            for initial in self._state_space.initials
+            if initial in retained
+        )
+
+        if not initials:
+            raise ValueError(
+                "Public announcement removed all "
+                "initial worlds from the StateSpace"
+            )
+
+        transitions = tuple(
+            transition
+            for transition
+            in self._state_space.transitions
+            if (
+                transition.source in retained
+                and transition.target in retained
+            )
+        )
+
+        return StateSpace(
+            initials=initials,
+            states=retained_worlds,
+            transitions=transitions,
+        )
+
+    def _restrict_relations(
+        self,
+        retained_worlds: tuple[World, ...],
+    ) -> dict[
+        str,
+        dict[
+            World,
+            tuple[World, ...],
+        ],
+    ]:
+        retained = set(
+            retained_worlds
+        )
+
+        result: dict[
+            str,
+            dict[
+                World,
+                tuple[World, ...],
+            ],
+        ] = {}
+
+        for agent, relation in (
+            self._relation_overrides.items()
+        ):
+            filtered: dict[
+                World,
+                tuple[World, ...],
+            ] = {}
+
+            for source, targets in (
+                relation.items()
+            ):
+                if source not in retained:
+                    continue
+
+                filtered[
+                    source
+                ] = tuple(
+                    target
+                    for target in targets
+                    if target in retained
+                )
+
+            result[
+                agent
+            ] = filtered
+
+        return result
+
+    # ---------------------------------------------------------------------
+    # State-space helpers
+    # ---------------------------------------------------------------------
+
+    @staticmethod
+    def _build_successors_map(
+        state_space: StateSpace,
+    ) -> dict[
+        Configuration,
+        tuple[Configuration, ...],
+    ]:
+        states = tuple(
+            state_space.states
+        )
+
+        state_set = set(
+            states
+        )
+
+        result_lists: dict[
+            Configuration,
+            list[Configuration],
+        ] = {
+            state: []
+            for state in states
+        }
+
+        for transition in (
+            state_space.transitions
+        ):
+            source = transition.source
+            target = transition.target
+
+            if source not in state_set:
+                raise ValueError(
+                    "StateSpace transition source is not "
+                    "present in StateSpace.states"
+                )
+
+            if target not in state_set:
+                raise ValueError(
+                    "StateSpace transition target is not "
+                    "present in StateSpace.states"
+                )
+
+            if target not in result_lists[
+                source
+            ]:
+                result_lists[
+                    source
+                ].append(
+                    target
+                )
+
+        return {
+            source: tuple(
+                targets
+            )
+            for source, targets
+            in result_lists.items()
+        }
+
+    def successors(
+        self,
+        world: World,
+    ) -> tuple[World, ...]:
+        """
+        Return temporal successors.
+
+        For a model with StateSpace, return actual transition
+        successors.
+
+        For a static epistemic snapshot without StateSpace,
+        use implicit stuttering:
+
+            w -> w
+        """
+
+        if world not in self._worlds:
+            raise ValueError(
+                "World does not belong "
+                "to the epistemic model"
+            )
+
+        # Static epistemic model:
+        #
+        #     w -> w -> w -> ...
+        #
+        # This allows temporal formulas such as G(phi)
+        # to express state-invariant properties over a
+        # snapshot model.
+        if self._state_space is None:
+            return (
+                world,
+            )
+
+        if not isinstance(
+            world,
+            Configuration,
+        ):
+            raise ValueError(
+                "ProductWorld does not currently "
+                "have StateSpace temporal successors"
+            )
+
+        return self._successors_map[
+            world
+        ]
+
+    def _temporal_successors(
+        self,
+        world: World,
+    ) -> tuple[World, ...]:
+        successors = self.successors(
+            world
+        )
+
+        if successors:
+            return successors
+
+        # Terminal state:
+        #
+        #     w -> w
+        #
+        return (
+            world,
+        )
+
+    # ---------------------------------------------------------------------
+    # Propositions
+    # ---------------------------------------------------------------------
+
+    @staticmethod
+    def _normalize_propositions(
+        propositions: (
+            Iterable[Proposition]
+            | Mapping[
+                str,
+                Proposition
+                | Callable[[Configuration], bool],
+            ]
+            | None
+        ),
+    ) -> dict[
+        str,
+        Proposition,
+    ]:
+        if propositions is None:
+            return {}
+
+        if isinstance(
+            propositions,
+            Mapping,
+        ):
+            result: dict[str, Proposition] = {}
+
+            for name, proposition in propositions.items():
+                if not isinstance(name, str) or not name:
+                    raise ValueError(
+                        "Proposition names must be non-empty strings"
+                    )
+
+                if isinstance(
+                    proposition,
+                    Proposition,
+                ):
+                    result[name] = proposition
+                    continue
+
+                if callable(proposition):
+                    result[name] = Proposition(
+                        name,
+                        proposition,
+                    )
+                    continue
+
+                raise TypeError(
+                    "Proposition mappings must contain Proposition"
+                    " objects or callables"
+                )
+
+            return result
+
+        result = {}
+
+        for proposition in propositions:
+            if not isinstance(
+                proposition,
+                Proposition,
+            ):
+                raise TypeError(
+                    "Iterable propositions must contain Proposition objects"
+                )
+
+            result[
+                proposition.name
+            ] = proposition
+
+        return result
+
+    def proposition_holds(
+        self,
+        name: str,
+        world: World,
+    ) -> bool:
+        proposition = self._propositions.get(
+            name
+        )
+
+        configuration = _configuration(
+            world
+        )
+
+        if proposition is not None:
+            return proposition.holds(
+                configuration
+            )
+
+        return (
+            configuration.state.get(
+                name
+            )
+            is True
+        )
+
+    # ---------------------------------------------------------------------
+    # Temporal fixed points
+    # ---------------------------------------------------------------------
+
+    def _eventually_set(
+        self,
+        operand: Formula,
+        cache: dict[
+            tuple[Formula, World],
+            bool,
+        ],
+    ) -> set[World]:
+        satisfying = {
+            world
+            for world in self._worlds
+            if self._check(
+                operand,
+                world,
+                cache,
+            )
+        }
+
+        changed = True
+
+        while changed:
+            changed = False
+
+            for world in self._worlds:
+                if world in satisfying:
+                    continue
+
+                successors = (
+                    self._temporal_successors(
+                        world
+                    )
+                )
+
+                if all(
+                    successor in satisfying
+                    for successor in successors
+                ):
+                    satisfying.add(
+                        world
+                    )
+
+                    changed = True
+
+        return satisfying
+
+    def _always_set(
+        self,
+        operand: Formula,
+        cache: dict[
+            tuple[Formula, World],
+            bool,
+        ],
+    ) -> set[World]:
+        satisfying = set(
+            self._worlds
+        )
+
+        changed = True
+
+        while changed:
+            changed = False
+
+            for world in tuple(
+                satisfying
+            ):
+                if not self._check(
+                    operand,
+                    world,
+                    cache,
+                ):
+                    satisfying.remove(
+                        world
+                    )
+
+                    changed = True
+
+                    continue
+
+                successors = (
+                    self._temporal_successors(
+                        world
+                    )
+                )
+
+                if any(
+                    successor
+                    not in satisfying
+                    for successor
+                    in successors
+                ):
+                    satisfying.remove(
+                        world
+                    )
+
+                    changed = True
+
+        return satisfying
+
+    def _until_set(
+        self,
+        left: Formula,
+        right: Formula,
+        cache: dict[
+            tuple[Formula, World],
+            bool,
+        ],
+    ) -> set[World]:
+        satisfying = {
+            world
+            for world in self._worlds
+            if self._check(
+                right,
+                world,
+                cache,
+            )
+        }
+
+        changed = True
+
+        while changed:
+            changed = False
+
+            for world in self._worlds:
+                if world in satisfying:
+                    continue
+
+                if not self._check(
+                    left,
+                    world,
+                    cache,
+                ):
+                    continue
+
+                successors = (
+                    self._temporal_successors(
+                        world
+                    )
+                )
+
+                if all(
+                    successor in satisfying
+                    for successor in successors
+                ):
+                    satisfying.add(
+                        world
+                    )
+
+                    changed = True
+
+        return satisfying
+
+    # ---------------------------------------------------------------------
+    # Model checking
+    # ---------------------------------------------------------------------
+
+    def check(
+        self,
+        formula: Formula,
+        at: World | None = None,
+    ) -> bool:
+        world = (
+            self._actual
+            if at is None
+            else at
+        )
+
+        if world not in self._worlds:
+            raise ValueError(
+                "World does not belong "
+                "to the epistemic model"
+            )
+
+        cache: dict[
+            tuple[Formula, World],
+            bool,
+        ] = {}
+
+        return self._check(
+            formula,
+            world,
+            cache,
+        )
+
+    def _check(
+        self,
+        formula: Formula,
+        world: World,
+        cache: dict[
+            tuple[Formula, World],
+            bool,
+        ],
+    ) -> bool:
+        key = (
+            formula,
+            world,
+        )
+
+        if key in cache:
+            return cache[key]
+
+        # -----------------------------------------------------------------
+        # Atom
+        # -----------------------------------------------------------------
+
+        if isinstance(
+            formula,
+            Atom,
+        ):
+            result = self.proposition_holds(
+                formula.name,
+                world,
+            )
+
+        # -----------------------------------------------------------------
+        # Boolean
+        # -----------------------------------------------------------------
+
+        elif isinstance(
+            formula,
+            Not,
+        ):
+            result = not self._check(
+                formula.operand,
+                world,
+                cache,
+            )
+
+        elif isinstance(
+            formula,
+            And,
+        ):
+            result = (
+                self._check(
+                    formula.left,
+                    world,
+                    cache,
+                )
+                and self._check(
+                    formula.right,
+                    world,
+                    cache,
+                )
+            )
+
+        elif isinstance(
+            formula,
+            Or,
+        ):
+            result = (
+                self._check(
+                    formula.left,
+                    world,
+                    cache,
+                )
+                or self._check(
+                    formula.right,
+                    world,
+                    cache,
+                )
+            )
+
+        # -----------------------------------------------------------------
+        # Temporal
+        # -----------------------------------------------------------------
+
+        elif isinstance(
+            formula,
+            Next,
+        ):
+            successors = (
+                self._temporal_successors(
+                    world
+                )
+            )
+
+            result = all(
+                self._check(
+                    formula.operand,
+                    successor,
+                    cache,
+                )
+                for successor in successors
+            )
+
+        elif isinstance(
+            formula,
+            Eventually,
+        ):
+            satisfying = (
+                self._eventually_set(
+                    formula.operand,
+                    cache,
+                )
+            )
+
+            for candidate in self._worlds:
+                cache[
+                    (
+                        formula,
+                        candidate,
+                    )
+                ] = (
+                    candidate
+                    in satisfying
+                )
+
+            result = (
+                world
+                in satisfying
+            )
+
+        elif isinstance(
+            formula,
+            Always,
+        ):
+            satisfying = (
+                self._always_set(
+                    formula.operand,
+                    cache,
+                )
+            )
+
+            for candidate in self._worlds:
+                cache[
+                    (
+                        formula,
+                        candidate,
+                    )
+                ] = (
+                    candidate
+                    in satisfying
+                )
+
+            result = (
+                world
+                in satisfying
+            )
+
+        elif isinstance(
+            formula,
+            Until,
+        ):
+            satisfying = (
+                self._until_set(
+                    formula.left,
+                    formula.right,
+                    cache,
+                )
+            )
+
+            for candidate in self._worlds:
+                cache[
+                    (
+                        formula,
+                        candidate,
+                    )
+                ] = (
+                    candidate
+                    in satisfying
+                )
+
+            result = (
+                world
+                in satisfying
+            )
+
+        # -----------------------------------------------------------------
+        # Knowledge
+        # -----------------------------------------------------------------
+
+        elif isinstance(
+            formula,
+            Knowledge,
+        ):
+            result = all(
+                self._check(
+                    formula.operand,
+                    candidate,
+                    cache,
+                )
+                for candidate in self.accessible(
+                    formula.agent,
+                    world,
+                )
+            )
+
+        # -----------------------------------------------------------------
+        # Everyone knows
+        # -----------------------------------------------------------------
+
+        elif isinstance(
+            formula,
+            EveryoneKnows,
+        ):
+            result = all(
+                self._check(
+                    Knowledge(
+                        agent=agent,
+                        operand=formula.operand,
+                    ),
+                    world,
+                    cache,
+                )
+                for agent
+                in formula.agents
+            )
+
+        # -----------------------------------------------------------------
+        # Distributed knowledge
+        # -----------------------------------------------------------------
+
+        elif isinstance(
+            formula,
+            DistributedKnowledge,
+        ):
+            result = all(
+                self._check(
+                    formula.operand,
+                    candidate,
+                    cache,
+                )
+                for candidate
+                in self.distributed_accessible(
+                    formula.agents,
+                    world,
+                )
+            )
+
+        # -----------------------------------------------------------------
+        # Common knowledge
+        # -----------------------------------------------------------------
+
+        elif isinstance(
+            formula,
+            CommonKnowledge,
+        ):
+            result = all(
+                self._check(
+                    formula.operand,
+                    candidate,
+                    cache,
+                )
+                for candidate
+                in self.common_knowledge_closure(
+                    formula.agents,
+                    world,
+                )
+            )
+
+        else:
+            raise TypeError(
+                f"Unsupported formula type: "
+                f"{type(formula).__name__}"
+            )
+
+        cache[key] = result
+
+        return result