ecopoesis 0.1.0__py3-none-any.whl

ecopoesis/__init__.py

@@ -0,0 +1,71 @@
+"""SimEarth package exports."""
+
+from .__version__ import __version__  # noqa: F401
+from .cli import main  # noqa: F401
+from .controls import EnvironmentControls
+from .geology import GeologyEngine, GeologyState
+from .life import Life, LifeState, Species, is_habitable
+from .resources import MAX_RESOURCE, ResourceState, Resources
+from .simulation import Simulation
+from .state import SUPPORTED_VERSIONS, SimulationState
+from .terrain import Terrain, TerrainState, ELEVATION_MIN, ELEVATION_MAX
+from .climate import Climate, ClimateState, TEMP_MIN, TEMP_MAX, PRECIP_MIN, PRECIP_MAX
+from .persistence import (
+    Format,
+    CURRENT_SCHEMA,
+    load_simulation,
+    load_simulation_json,
+    load_simulation_protobuf,
+    load_simulation_v1,
+    save_simulation,
+    save_simulation_json,
+    save_simulation_protobuf,
+    save_simulation_v1,
+)
+
+__all__ = [
+    # Package metadata (Slice 11)
+    "__version__",
+    # Simulation core
+    "Simulation",
+    "SimulationState",
+    "SUPPORTED_VERSIONS",
+    # Terrain layer (Slice 3)
+    "Terrain",
+    "TerrainState",
+    "ELEVATION_MIN",
+    "ELEVATION_MAX",
+    # Climate layer (Slice 3)
+    "Climate",
+    "ClimateState",
+    "TEMP_MIN",
+    "TEMP_MAX",
+    "PRECIP_MIN",
+    "PRECIP_MAX",
+    # Life layer (Slice 4)
+    "Life",
+    "LifeState",
+    "Species",
+    "is_habitable",
+    # Resources layer (Slice 6)
+    "Resources",
+    "ResourceState",
+    "MAX_RESOURCE",
+    # Environment controls (Slice 6)
+    "EnvironmentControls",
+    # Geology layer (Slice 7)
+    "GeologyEngine",
+    "GeologyState",
+    # Persistence
+    "Format",
+    "CURRENT_SCHEMA",
+    "save_simulation",
+    "load_simulation",
+    "save_simulation_json",
+    "load_simulation_json",
+    "save_simulation_protobuf",
+    "load_simulation_protobuf",
+    "save_simulation_v1",
+    "load_simulation_v1",
+]
+

ecopoesis/__version__.py

@@ -0,0 +1,9 @@
+"""Single-source-of-truth version for the ecopoesis package.
+
+This file is intentionally minimal so it can be imported from any context
+(including build scripts and runtime) without pulling in heavier dependencies
+like ``ecopoesis.simulation_pb2``.  Both ``pyproject.toml`` and the public
+``ecopoesis.__version__`` re-export should stay in lock-step with this string.
+"""
+
+__version__ = "0.1.0"

ecopoesis/_gen_pb2.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python3
+"""Generate simulation_pb2.py from simulation.proto using grpc_tools.protoc."""
+import os
+import sys
+
+PROTO_DIR = os.path.dirname(os.path.abspath(__file__))
+PROTO_FILE = os.path.join(PROTO_DIR, "simulation.proto")
+OUT_DIR = PROTO_DIR
+
+try:
+    from grpc_tools import protoc
+
+    rc = protoc.main(
+        [
+            "grpc_tools.protoc",
+            f"-I{PROTO_DIR}",
+            f"--python_out={OUT_DIR}",
+            PROTO_FILE,
+        ]
+    )
+    if rc != 0:
+        print("protoc returned non-zero exit code:", rc)
+        sys.exit(rc)
+    print(f"Generated simulation_pb2.py in {OUT_DIR}")
+except ImportError:
+    # Fallback: try subprocess protoc binary
+    import subprocess
+
+    result = subprocess.run(
+        ["protoc", f"-I{PROTO_DIR}", f"--python_out={OUT_DIR}", PROTO_FILE],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        print("protoc error:", result.stderr)
+        sys.exit(result.returncode)
+    print(f"Generated simulation_pb2.py in {OUT_DIR}")

ecopoesis/actions.py

@@ -0,0 +1,547 @@
+"""Player actions layer for SimEarth (Slice 9).
+
+A player (or the CLI) can queue ``Action`` records into a ``CommandLog``
+attached to the live ``SimulationState``.  At the start of each tick the
+simulation **drains** every action whose ``action.tick == state.tick``
+**before** the core LCG runs, so the action's effects are baked into
+the per-tick snapshot in the canonical order.
+
+Design contracts
+================
+
+* ``Action`` is a frozen-ish dataclass (mutable ``payload`` dict so the
+  CLI can fill it in-place, but ``tick``/``type``/``rng_cost`` are
+  immutable after construction).  ``rng_cost`` is non-negative; the
+  handler MAY consume up to that many RNG draws if it declares so.
+  ``rng_cost == 0`` (default) is a strict no-RNG contract.
+
+* ``CommandLog`` is the ordered, append-only log of pending actions.
+  ``append(action)`` rejects past-tick submissions with
+  :py:class:`ActionOrderError` — same-tick and future-tick submissions
+  are accepted in submission order (the spec's "out-of-order = strictly
+  past-tick" rule).
+
+* ``Actions`` is the engine — a registry mapping ``type`` strings to
+  handler callables ``Callable[[SimulationState, dict], None]``.  Three
+  handlers ship in this slice: ``seed_life``, ``adjust_controls``, and
+  ``trigger_eruption``.  All three are deterministic and RNG-free
+  (``rng_cost = 0`` by default), so adding them to a run does not
+  perturb the slice-7 RNG budget for any other layer.
+
+* :func:`apply_action` is the top-level entry point used by
+  ``Simulation.advance`` while draining the log: it validates the
+  RNG-cost contract, looks up the handler, and invokes it with
+  ``(state, payload)``.
+
+Why deterministic handlers only?
+================================
+
+The Slice 9 spec requires ``save -> load -> advance(N)`` to be
+byte-identical to a no-save baseline run (same seed, same actions).
+The easiest way to keep that invariant is to mandate that handlers do
+not consume RNG draws unless they explicitly declare so via
+``rng_cost``.  All three built-in handlers declare ``rng_cost = 0`` so
+they are pure functions of the existing state plus their payload — no
+hidden RNG calls, no surprises for downstream snapshots.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Callable
+
+from .controls import EnvironmentControls
+from .life import Species
+from .resources import MAX_RESOURCE
+
+if TYPE_CHECKING:
+    # Imported only for type-checking to break the import cycle:
+    # ``state.py`` imports ``CommandLog`` from this module, and
+    # ``actions.py`` annotates ``SimulationState`` parameters as a
+    # forward reference.  Runtime callers always pass a real
+    # ``SimulationState`` instance so the annotation is purely
+    # cosmetic for IDEs / type-checkers.
+    from .state import SimulationState
+
+
+# --------------------------------------------------------------------------- #
+#  Typed errors                                                                #
+# --------------------------------------------------------------------------- #
+
+
+class UnknownActionError(RuntimeError):
+    """Raised when :func:`apply_action` is given an unregistered ``type``.
+
+    Subclasses :py:class:`RuntimeError` so generic CLI catchers treat it
+    like any other runtime failure but downstream callers can narrow on
+    the exact type without parsing strings.
+    """
+
+
+class ActionOrderError(RuntimeError):
+    """Raised when an action is submitted with a past-tick stamp.
+
+    The Slice 9 spec defines "out-of-order" as strictly past-tick
+    (``action.tick < state.tick``).  Same-tick and future-tick actions
+    are accepted in submission order.
+    """
+
+
+# --------------------------------------------------------------------------- #
+#  Action + CommandLog                                                         #
+# --------------------------------------------------------------------------- #
+
+
+@dataclass(slots=True)
+class Action:
+    """A single player command.
+
+    Parameters
+    ----------
+    tick : int
+        The simulation tick at which this action should be applied.
+        The simulation drains actions whose ``tick`` matches the
+        current tick **at the start of that tick, before the core
+        LCG** runs.  ``tick`` must be ``>= state.tick`` at submission
+        time or :py:class:`ActionOrderError` is raised.
+    type : str
+        The action type — looked up in the :class:`Actions` registry.
+        Unknown types raise :py:class:`UnknownActionError` at apply time.
+    payload : dict
+        Free-form per-type data.  ``seed_life`` expects ``{"species":
+        str, "cells": list[[row, col], ...]}``; ``adjust_controls``
+        expects ``{"temperature_offset": int, "rainfall_offset": int}``;
+        ``trigger_eruption`` expects ``{"cell": [row, col]}`` (optional
+        — defaults to the deterministic origin ``[0, 0]``).  The payload
+        is owned by the action instance after construction; handlers
+        MUST NOT mutate it.
+    rng_cost : int
+        Non-negative declaration of how many RNG draws the handler
+        intends to consume.  The default ``0`` enforces the no-RNG
+        contract: a handler with ``rng_cost == 0`` that calls
+        ``random.Random`` is a contract violation and is rejected by
+        the test suite.
+    """
+
+    tick: int
+    type: str
+    payload: dict = field(default_factory=dict)
+    rng_cost: int = 0
+
+    def __post_init__(self) -> None:
+        # Defensive validation so a malformed Action fails fast (and
+        # before it pollutes a CommandLog).
+        if not isinstance(self.tick, int) or isinstance(self.tick, bool):
+            raise TypeError(f"Action.tick must be int; got {type(self.tick).__name__}")
+        if not isinstance(self.type, str):
+            raise TypeError(f"Action.type must be str; got {type(self.type).__name__}")
+        if not isinstance(self.payload, dict):
+            raise TypeError(f"Action.payload must be dict; got {type(self.payload).__name__}")
+        if not isinstance(self.rng_cost, int) or isinstance(self.rng_cost, bool):
+            raise TypeError(
+                f"Action.rng_cost must be int; got {type(self.rng_cost).__name__}"
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise to a JSON-friendly dict.
+
+        ``payload`` is deep-copied (top level only — handlers MUST treat
+        it as read-only after construction, so the top-level copy is
+        enough to keep callers from accidentally aliasing into the log).
+        """
+        return {
+            "tick": int(self.tick),
+            "type": str(self.type),
+            "payload": {k: v for k, v in self.payload.items()},
+            "rng_cost": int(self.rng_cost),
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Action":
+        """Inverse of :py:meth:`to_dict`.  Missing fields default safely."""
+        return cls(
+            tick=int(data.get("tick", 0)),
+            type=str(data.get("type", "")),
+            payload=dict(data.get("payload") or {}),
+            rng_cost=int(data.get("rng_cost", 0)),
+        )
+
+
+@dataclass(slots=True)
+class CommandLog:
+    """Append-only ordered log of pending player actions.
+
+    Tracks ``current_tick`` (the highest tick the simulation has
+    advanced to so far) so :py:meth:`append` can reject past-tick
+    submissions without the caller having to pass the tick in.  The
+    simulation calls :py:meth:`advance_to` once per tick before draining
+    so the log's internal tick stays in sync with ``SimulationState.tick``.
+
+    Attributes
+    ----------
+    entries : list[Action]
+        The ordered list of pending actions in submission order.
+        ``drain_for_tick`` removes elements as it returns them, so the
+        list shrinks monotonically over the run.
+    current_tick : int
+        The simulation tick the log has been advanced to so far.
+        Initialised to ``0`` so the very first ``apply_command``
+        submission (with ``tick == 1``) is accepted as a future-tick
+        action.
+    """
+
+    entries: list[Action] = field(default_factory=list)
+    current_tick: int = 0
+
+    def append(self, action: Action) -> None:
+        """Append *action* to the log, validating ordering.
+
+        Raises
+        ------
+        ActionOrderError
+            If ``action.tick < self.current_tick`` — the action would
+            never be drained because the simulation has already moved
+            past its target tick.  Same-tick and future-tick
+            submissions are accepted.
+        """
+        if action.tick < self.current_tick:
+            raise ActionOrderError(
+                f"action tick {action.tick} is past current tick {self.current_tick}"
+            )
+        self.entries.append(action)
+
+    def advance_to(self, tick: int) -> None:
+        """Move the log's *current_tick* forward to *tick* (monotonic).
+
+        ``Simulation.advance`` calls this once per tick — *before* the
+        drain — so subsequent ``append`` calls correctly classify same-
+        and future-tick submissions.
+        """
+        if tick > self.current_tick:
+            self.current_tick = tick
+
+    def drain_for_tick(self, tick: int) -> list[Action]:
+        """Return (and remove) all actions whose ``tick == tick``.
+
+        Returned in submission order so the drain is fully deterministic
+        regardless of how the user interleaved future-tick submissions.
+        """
+        kept: list[Action] = []
+        drained: list[Action] = []
+        for action in self.entries:
+            if action.tick == tick:
+                drained.append(action)
+            else:
+                kept.append(action)
+        # Replace in-place to keep the underlying list identity (some
+        # callers cache a reference; cheaper than allocating a fresh
+        # list every tick).
+        self.entries.clear()
+        self.entries.extend(kept)
+        return drained
+
+    def is_empty(self) -> bool:
+        """``True`` when no pending actions remain."""
+        return not self.entries
+
+    def __len__(self) -> int:  # pragma: no cover - convenience
+        return len(self.entries)
+
+    def to_list(self) -> list[Action]:
+        """Return a shallow copy of the entries list (read-only view)."""
+        return list(self.entries)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise to a JSON-friendly dict."""
+        return {
+            "entries": [a.to_dict() for a in self.entries],
+            "current_tick": int(self.current_tick),
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "CommandLog":
+        """Inverse of :py:meth:`to_dict`.  Empty input → empty log."""
+        entries_raw = data.get("entries") or []
+        return cls(
+            entries=[Action.from_dict(d) for d in entries_raw],
+            current_tick=int(data.get("current_tick", 0)),
+        )
+
+
+# --------------------------------------------------------------------------- #
+#  Handler type alias                                                          #
+# --------------------------------------------------------------------------- #
+
+
+# A handler mutates ``state`` in place based on its ``payload`` and
+# returns ``None``.  Handlers MUST be deterministic and MUST NOT consume
+# RNG draws unless ``action.rng_cost > 0`` (the ``apply_action`` entry
+# point enforces that contract at apply time).
+# ``SimulationState`` is a forward reference — the real type lives in
+# ``state.py`` which imports this module for ``CommandLog``.  The alias
+# below uses ``Callable[..., None]`` (which is functionally equivalent
+# at runtime) and the precise signature is documented in the comment
+# for IDEs / type-checkers.
+ActionHandler = Callable[..., None]  # Callable[[SimulationState, dict], None]
+
+
+# --------------------------------------------------------------------------- #
+#  Built-in handlers                                                           #
+# --------------------------------------------------------------------------- #
+
+
+def _initial_population(species_key: str) -> int:
+    """Initial seed population placed on each cell by ``seed_life``.
+
+    Mirrors :func:`ecopoesis.life._initial_population` so the action has
+    the same defaults as the CLI ``--seed-life`` flag.  Mirrored here to
+    avoid an import cycle through ``life.py`` (handlers run during
+    drain, before any per-tick ``Life.advance_tick``).
+    """
+    if species_key == Species.MICROBE.value:
+        return 5
+    if species_key == Species.PLANT.value:
+        return 3
+    raise ValueError(f"Unknown species: {species_key!r}")
+
+
+def _seed_life(state: SimulationState, payload: dict) -> None:
+    """Seed a species' population at the given grid cells.
+
+    Payload
+    -------
+    ``species`` : str
+        Canonical species name (``"MICROBE"`` or ``"PLANT"`` —
+        case-insensitive).  Anything else raises ``ValueError``.
+    ``cells`` : list[tuple[int, int]]
+        ``[row, col]`` coordinates to seed.  Out-of-bounds cells are
+        silently skipped (matches the ``Life.place`` contract).
+
+    Effect
+    ------
+    Ensures ``state.life_state.populations[species]`` exists as a
+    flat ``rows * cols`` grid (default zeros) and bumps each requested
+    cell by ``_initial_population(species)``.  No RNG draws.
+    """
+    species_raw = payload.get("species") or payload.get("seed_life")
+    if not species_raw:
+        raise ValueError("seed_life payload missing 'species'")
+    species_key = str(species_raw).upper()
+    # Normalise via the Species enum so ``"microbe"`` and ``"MICROBE"``
+    # both work, and an unknown name raises ValueError early.
+    try:
+        species_key = Species(species_key).value
+    except ValueError as exc:
+        raise ValueError(f"seed_life: {exc}") from exc
+
+    cells_raw = payload.get("cells") or []
+    if not isinstance(cells_raw, (list, tuple)):
+        raise ValueError("seed_life: 'cells' must be a list of [row, col] pairs")
+
+    life = state.life_state
+    rows, cols = life.rows, life.cols
+    grid = life.populations.get(species_key)
+    if grid is None:
+        grid = [0] * (rows * cols)
+        life.populations[species_key] = grid
+    pop = _initial_population(species_key)
+    for cell in cells_raw:
+        if not isinstance(cell, (list, tuple)) or len(cell) != 2:
+            raise ValueError(f"seed_life: invalid cell entry {cell!r}")
+        r, c = int(cell[0]), int(cell[1])
+        if 0 <= r < rows and 0 <= c < cols:
+            grid[r * cols + c] += pop
+
+
+def _adjust_controls(state: SimulationState, payload: dict) -> None:
+    """Update ``EnvironmentControls`` offsets and apply the delta to climate.
+
+    Payload
+    -------
+    ``temperature_offset`` : int
+        New ``temperature_offset`` value (replaces the old one; not a
+        delta).  Defaults to the existing value when omitted.
+    ``rainfall_offset`` : int
+        New ``rainfall_offset`` value (replaces the old one).  Defaults
+        to the existing value when omitted.
+
+    Effect
+    ------
+    Replaces ``state.controls`` with the new ``EnvironmentControls``
+    instance and applies the **delta** (new − old) to
+    ``state.climate_state`` so existing climate cells pick up the
+    offset change without losing their per-tick perturbation history.
+    No RNG draws.
+    """
+    old = state.controls
+    new_t = int(payload.get("temperature_offset", old.temperature_offset))
+    new_r = int(payload.get("rainfall_offset", old.rainfall_offset))
+    delta_t = new_t - int(old.temperature_offset)
+    delta_r = new_r - int(old.rainfall_offset)
+    if delta_t == 0 and delta_r == 0:
+        # No-op fast path: avoid constructing an EnvironmentControls
+        # and a ClimateState mutation when nothing changed.
+        return
+    # Apply the delta to the climate state.  ``EnvironmentControls.apply``
+    # adds the offset and clamps into the existing climate bounds, so
+    # the new cells stay valid even when the offset is large.
+    delta = EnvironmentControls(
+        temperature_offset=delta_t,
+        rainfall_offset=delta_r,
+    )
+    delta.apply(state.climate_state)
+    state.controls = EnvironmentControls(temperature_offset=new_t, rainfall_offset=new_r)
+
+
+def _trigger_eruption(state: SimulationState, payload: dict) -> None:
+    """Apply one deterministic volcanic eruption deposit.
+
+    Payload
+    -------
+    ``cell`` : list[int, int]
+        ``[row, col]`` coordinate to receive the deposit.  Defaults to
+        ``[0, 0]`` so the action is fully deterministic without any
+        payload.  Out-of-bounds cells are silently skipped (matches
+        the slice-7 eruption contract).
+
+    Effect
+    ------
+    Adds :data:`ecopoesis.geology.ERUPTION_MINERAL_DEPOSIT` minerals to
+    the requested cell, clamped into ``[0, MAX_RESOURCE]``.  No RNG
+    draws.  When ``state.resources_state.minerals`` is empty (the
+    default-constructed state) the deposit is a no-op.
+    """
+    from .geology import ERUPTION_MINERAL_DEPOSIT  # local import: avoids cycles
+
+    cell = payload.get("cell") or [0, 0]
+    if not isinstance(cell, (list, tuple)) or len(cell) != 2:
+        raise ValueError(f"trigger_eruption: invalid cell {cell!r}")
+    r, c = int(cell[0]), int(cell[1])
+    res = state.resources_state
+    rows, cols = res.rows, res.cols
+    if not (0 <= r < rows and 0 <= c < cols):
+        return
+    if not res.minerals:
+        return
+    idx = r * cols + c
+    new_val = res.minerals[idx] + ERUPTION_MINERAL_DEPOSIT
+    if new_val < 0:
+        new_val = 0
+    elif new_val > MAX_RESOURCE:
+        new_val = MAX_RESOURCE
+    res.minerals[idx] = new_val
+
+
+# --------------------------------------------------------------------------- #
+#  Actions engine                                                              #
+# --------------------------------------------------------------------------- #
+
+
+class Actions:
+    """Registry mapping action ``type`` strings to handler callables.
+
+    The default registry ships with three handlers
+    (``seed_life``/``adjust_controls``/``trigger_eruption``); callers
+    may register additional handlers with :py:meth:`register`.  The
+    instance is mutable so tests can swap handlers; the module-level
+    :data:`DEFAULT_ACTIONS` is the singleton used by ``apply_action``
+    and the simulation.
+    """
+
+    def __init__(self) -> None:
+        self._handlers: dict[str, ActionHandler] = {}
+
+    def register(self, name: str, handler: ActionHandler) -> None:
+        """Register *handler* under *name*.  Overwrites any existing entry."""
+        if not isinstance(name, str) or not name:
+            raise ValueError(f"action name must be a non-empty string; got {name!r}")
+        if not callable(handler):
+            raise TypeError(f"action handler for {name!r} must be callable")
+        self._handlers[name] = handler
+
+    def unregister(self, name: str) -> None:
+        """Remove the handler registered under *name* (no-op if absent)."""
+        self._handlers.pop(name, None)
+
+    def is_known(self, name: str) -> bool:
+        """``True`` when a handler is registered under *name*."""
+        return name in self._handlers
+
+    def known_types(self) -> list[str]:
+        """Return a snapshot of the registered handler names (sorted)."""
+        return sorted(self._handlers)
+
+    def apply(self, state: SimulationState, action: Action) -> None:
+        """Apply *action* to *state* via the registered handler.
+
+        Raises
+        ------
+        UnknownActionError
+            If no handler is registered for ``action.type``.
+        """
+        handler = self._handlers.get(action.type)
+        if handler is None:
+            raise UnknownActionError(f"unknown action type: {action.type!r}")
+        handler(state, action.payload)
+
+
+# Module-level singleton — the canonical registry used by
+# ``apply_action`` and the simulation.  Tests can mutate it (register /
+# unregister) and reset to the defaults with :func:`_install_defaults`.
+DEFAULT_ACTIONS = Actions()
+
+
+def _install_defaults(actions: Actions = DEFAULT_ACTIONS) -> Actions:
+    """Install the three built-in handlers on *actions* (idempotent)."""
+    actions.register("seed_life", _seed_life)
+    actions.register("adjust_controls", _adjust_controls)
+    actions.register("trigger_eruption", _trigger_eruption)
+    return actions
+
+
+# Eagerly install the defaults at import time so ``apply_action`` works
+# without callers having to remember to wire the registry up.
+_install_defaults()
+
+
+# --------------------------------------------------------------------------- #
+#  apply_action                                                                #
+# --------------------------------------------------------------------------- #
+
+
+def apply_action(state: SimulationState, action: Action) -> None:
+    """Apply *action* to *state* using the registered handler.
+
+    This is the top-level entry point used by
+    ``Simulation.advance`` during the per-tick drain phase.  It is
+    also exposed for direct use by tests and the CLI ``replay``
+    subcommand.
+
+    Contract
+    --------
+    * ``action.rng_cost >= 0`` is validated here (a negative cost is
+      nonsensical and rejected as a ``ValueError``).
+    * ``action.type`` must be registered with :data:`DEFAULT_ACTIONS`
+      — otherwise :py:class:`UnknownActionError` is raised.
+    * The handler runs synchronously with ``(state, action.payload)``
+      as its arguments.  Handlers MUST mutate ``state`` in place and
+      MUST be deterministic unless ``action.rng_cost > 0`` declares
+      otherwise.
+    """
+    if action.rng_cost < 0:
+        raise ValueError(
+            f"Action.rng_cost must be non-negative; got {action.rng_cost}"
+        )
+    DEFAULT_ACTIONS.apply(state, action)
+
+
+__all__ = [
+    "Action",
+    "ActionHandler",
+    "ActionOrderError",
+    "Actions",
+    "CommandLog",
+    "DEFAULT_ACTIONS",
+    "UnknownActionError",
+    "apply_action",
+]