foliot 0.1.0__py3-none-any.whl

foliot/__init__.py

@@ -0,0 +1,61 @@
+"""foliot -- a deterministic tick-driven simulation core.
+
+A clock, a queue of scheduled things, a way to look up what to run, and a
+source of addressable randomness. It has never heard of a target, location,
+environment, activity, or combat rule.
+
+The value is in five guarantees, not in the object graph:
+
+1. Same seed, same history.
+2. Reordering the queue cannot change outcomes.
+3. The clock does not drift.
+4. Nothing pending is lost, and nothing is applied twice.
+5. Time is injectable -- ten million ticks run in a unit test.
+
+Everything re-exported here is public API: a moved name is a breaking change.
+Anything not listed in `__all__` is internal and free to move.
+"""
+
+from foliot.actions import (
+    ActionBinding,
+    ActionState,
+    Active,
+    BaseAction,
+    Bound,
+    Suspended,
+    Unbound,
+)
+from foliot.context import FinalizationContext, TickContext, TickFinalizer
+from foliot.drivers import Driver, ManualDriver, RealtimeDriver
+from foliot.effects import Effect
+from foliot.engine import Simulation
+from foliot.ids import EntityId, SuspensionId, Tick
+from foliot.rng import Rng, counter_rng, new_world_seed
+from foliot.stores import MemoryStore, Store, Txn
+
+__all__ = [
+    "ActionBinding",
+    "ActionState",
+    "Active",
+    "BaseAction",
+    "Bound",
+    "Driver",
+    "Effect",
+    "EntityId",
+    "FinalizationContext",
+    "ManualDriver",
+    "MemoryStore",
+    "RealtimeDriver",
+    "Rng",
+    "Simulation",
+    "Store",
+    "Suspended",
+    "SuspensionId",
+    "Tick",
+    "TickContext",
+    "TickFinalizer",
+    "Txn",
+    "Unbound",
+    "counter_rng",
+    "new_world_seed",
+]

foliot/_event_bridge.py

@@ -0,0 +1,7 @@
+"""One internal exception shared across the optional Event boundary."""
+
+__all__ = ["EventConfigurationError"]
+
+
+class EventConfigurationError(RuntimeError):
+    """Event API was used without a matching Event-enabled configuration."""

foliot/actions.py

@@ -0,0 +1,275 @@
+"""Game actions with engine-owned lifecycle bookkeeping.
+
+Every game action that enters foliot's queue inherits `BaseAction`. This is
+deliberately different from the library's structural ports: binding, stable
+identity, and suspension are invariants every game needs and must implement in
+exactly the same way.
+
+An action always has a complete binding value. It starts `Unbound`; the store
+changes it to `Bound(seq, state)` on first successful admission. The same game
+object -- including all subclass fields -- survives every reschedule,
+suspension, and resume, and its `seq` never changes.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Literal
+
+from foliot.context import TickContext
+from foliot.ids import EntityId, SuspensionId, Tick
+
+__all__ = [
+    "ActionBinding",
+    "ActionState",
+    "Active",
+    "BaseAction",
+    "Bound",
+    "Suspended",
+    "Unbound",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class Active:
+    """Queue state of an admitted action that is eligible to run.
+
+    Attributes:
+        due_tick: Future deadline, or `None` for an action due every tick.
+        status: Stable discriminator useful when persisting the state.
+    """
+
+    due_tick: Tick | None
+    status: Literal["active"] = field(default="active", init=False)
+
+
+@dataclass(frozen=True, slots=True)
+class Suspended:
+    """Queue state of an admitted action that is temporarily paused.
+
+    Attributes:
+        suspended_at: Tick at which the pause began.
+        suspended_by: Handle that must be used to resume the action.
+        due_tick: Deadline preserved from the active state, or `None` for a
+            recurring action.
+        status: Stable discriminator useful when persisting the state.
+    """
+
+    suspended_at: Tick
+    suspended_by: SuspensionId
+    due_tick: Tick | None
+    status: Literal["suspended"] = field(default="suspended", init=False)
+
+
+type ActionState = Active | Suspended
+
+
+@dataclass(frozen=True, slots=True)
+class Unbound:
+    """A complete game action that has not entered the queue yet."""
+
+
+@dataclass(frozen=True, slots=True)
+class Bound:
+    """The store-owned metadata of an admitted action.
+
+    `seq` is assigned once, on first admission, and is carried unchanged through
+    every replacement of `state`. It is the action's replay identity, not its
+    position in a due list.
+
+    Attributes:
+        seq: Positive sequence number assigned by the store.
+        state: Current active or suspended queue state.
+    """
+
+    seq: int
+    state: ActionState
+
+
+type ActionBinding = Unbound | Bound
+
+
+class BaseAction[W](ABC):
+    """Mandatory blueprint for every game action entering foliot's queue.
+
+    The base owns only the lifecycle fields foliot needs. Subclasses keep all
+    game-owned payload -- target, poison damage, tick interval, arrival
+    deadline, and so on -- on the same object and implement `process()`.
+
+    Args:
+        entity_id: Opaque identity of the entity that owns the action.
+        suspendable: Whether owner-level suspension requests may pause it.
+    """
+
+    __slots__ = ("_binding", "_entity_id", "_suspendable")
+
+    def __init__(self, entity_id: EntityId, *, suspendable: bool) -> None:
+        self._entity_id = entity_id
+        self._suspendable = suspendable
+        self._binding: ActionBinding = Unbound()
+
+    @property
+    def entity_id(self) -> EntityId:
+        """The entity that owns this queued action."""
+        return self._entity_id
+
+    @property
+    def suspendable(self) -> bool:
+        """Whether an owner-level suspension request may pause this action."""
+        return self._suspendable
+
+    @property
+    def binding(self) -> ActionBinding:
+        """Whether this object has entered the queue, and its metadata if so."""
+        return self._binding
+
+    @property
+    def seq(self) -> int:
+        """Return the permanent sequence number assigned by the store.
+
+        Raises:
+            RuntimeError: If the action has not been admitted yet.
+        """
+        match self._binding:
+            case Bound(seq=seq):
+                return seq
+            case Unbound():
+                raise RuntimeError("an unbound action has no seq")
+
+    @property
+    def state(self) -> ActionState:
+        """Return the active or suspended state of an admitted action.
+
+        Raises:
+            RuntimeError: If the action has not been admitted yet.
+        """
+        match self._binding:
+            case Bound(state=state):
+                return state
+            case Unbound():
+                raise RuntimeError("an unbound action has no state")
+
+    def bind(self, seq: int, state: ActionState, /) -> None:
+        """Bind this object after its first successful store admission.
+
+        Durable stores also use this operation when hydrating an admitted
+        action. Calling it twice would replace the replay identity and is
+        therefore rejected.
+
+        Args:
+            seq: Permanent sequence number allocated by the store.
+            state: Restored active or suspended queue state.
+
+        Raises:
+            RuntimeError: If the action is already bound.
+        """
+        match self._binding:
+            case Unbound():
+                self._binding = Bound(seq, state)
+            case Bound():
+                raise RuntimeError("an action can only be bound once")
+
+    def reschedule(self, due_tick: Tick | None, /) -> None:
+        """Replace an active deadline while preserving the action's `seq`.
+
+        Args:
+            due_tick: New deadline, or `None` for recurring execution.
+
+        Raises:
+            RuntimeError: If the action is unbound or suspended.
+        """
+        match self._binding:
+            case Bound(seq=seq, state=state):
+                match state:
+                    case Active():
+                        self._binding = Bound(seq, Active(due_tick))
+                    case Suspended():
+                        raise RuntimeError("a suspended action cannot be rescheduled")
+            case Unbound():
+                raise RuntimeError("an unbound action must be bound before rescheduling")
+
+    def suspend(self, tick: Tick, by: SuspensionId, /) -> None:
+        """Pause this action, preserving its deadline and replay identity.
+
+        Non-suspendable and already-suspended actions are unchanged.
+
+        Args:
+            tick: Tick at which the pause begins.
+            by: Opaque handle that owes the later resumption.
+
+        Raises:
+            RuntimeError: If the action has not been admitted yet.
+        """
+        if not self._suspendable:
+            return
+
+        match self._binding:
+            case Bound(seq=seq, state=state):
+                match state:
+                    case Active(due_tick=due_tick):
+                        self._binding = Bound(
+                            seq,
+                            Suspended(
+                                suspended_at=tick,
+                                suspended_by=by,
+                                due_tick=due_tick,
+                            ),
+                        )
+                    case Suspended():
+                        pass
+            case Unbound():
+                raise RuntimeError("an unbound action cannot be suspended")
+
+    def resume(self, tick: Tick, /) -> None:
+        """Resume this action and shift its deadlines by the pause length.
+
+        Active actions are unchanged. For a suspended action, the stored
+        deadline is shifted and `on_resume(paused_for)` is called.
+
+        Args:
+            tick: Tick at which the action resumes.
+
+        Raises:
+            RuntimeError: If the action has not been admitted yet.
+        """
+        match self._binding:
+            case Bound(seq=seq, state=state):
+                match state:
+                    case Suspended(suspended_at=suspended_at, due_tick=due_tick):
+                        paused_for = tick - suspended_at
+                        self._binding = Bound(
+                            seq,
+                            Active(
+                                due_tick=None if due_tick is None else due_tick + paused_for,
+                            ),
+                        )
+                        self.on_resume(paused_for)
+                    case Active():
+                        pass
+            case Unbound():
+                raise RuntimeError("an unbound action cannot be resumed")
+
+    def on_resume(self, paused_for: int, /) -> None:  # noqa: B027 - optional hook
+        """React to resumption after `paused_for` logical ticks.
+
+        Override this hook to shift game-owned deadlines such as `arrives_at`.
+        The default implementation does nothing.
+        """
+
+    @abstractmethod
+    def process(self, ctx: TickContext[W], /) -> None:
+        """Describe this occurrence through the collecting context.
+
+        Mutate neither the queue nor persistent world state directly. Use the
+        context to stage effects, schedules, suspension, logs, and completion.
+        """
+        ...
+
+
+def restore_action_binding[W](action: BaseAction[W], binding: ActionBinding, /) -> None:
+    """Restore engine-owned metadata after an in-memory commit failure.
+
+    Internal to foliot and deliberately absent from `__all__`. Consumer stores
+    use their own transaction rollback; only `MemoryStore` needs to restore a
+    Python object that was already mutated while publishing staged commands.
+    """
+    action._binding = binding  # pyright: ignore[reportPrivateUsage] -- same-module rollback

foliot/context.py

@@ -0,0 +1,160 @@
+"""Capabilities supplied to action handlers and tick finalizers.
+
+`TickContext` is deliberately narrow: two things to read and five things to say.
+It is the one object every handler touches, which makes it the one object most
+likely to rot into a service locator -- a `ctx` that can reach everything, used
+by handlers to reach anything. Treat any proposal to add `ctx.store`,
+`ctx.world` or `ctx.entity` as the alarm rather than the feature.
+
+The discipline that keeps it contained: **pass the capability, not the
+context.** A handler that needs a die roll downstream passes `ctx.rng`, never
+`ctx`. Then nothing below `process()` can reach the scheduler, so nothing below
+`process()` can schedule.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol
+
+from foliot.effects import Effect
+from foliot.ids import EntityId, SuspensionId, Tick
+from foliot.rng import Rng
+
+if TYPE_CHECKING:
+    from foliot.actions import BaseAction
+    from foliot.events import EventId
+
+__all__ = ["FinalizationContext", "TickContext", "TickFinalizer"]
+
+
+class TickContext[W](Protocol):
+    """Reads the tick; collects what the handler wants to happen.
+
+    Nothing said to a `TickContext` takes effect when it is said. The engine
+    gives each action a fresh context, and:
+
+    - the handler returns normally -> its collected work joins the tick's pile
+    - the handler raises           -> its context is discarded whole, nothing
+      it said happens, and the engine skips it and carries on
+
+    Only once every due action has been asked does the engine drain the pile:
+    schedules and suspension requests into the queue, effects applied, log
+    lines written. No action can therefore observe another action's effects
+    from the same tick.
+
+    `tick` and `rng` are read-only properties rather than plain annotations: a
+    Protocol written `tick: Tick` demands something *settable*, which a real
+    `Simulation` -- whose tick is computed from the store so that nothing can
+    assign the world's clock -- would fail to satisfy.
+    """
+
+    @property
+    def tick(self) -> Tick: ...
+
+    @property
+    def rng(self) -> Rng:
+        """Already bound to `(world_seed, entity_id, tick, seq)`. Never seed."""
+        ...
+
+    def emit(self, effect: Effect[W], /) -> None:
+        """Stage a game-defined world mutation for the apply phase.
+
+        Args:
+            effect: Object whose `apply(world)` method performs the mutation.
+        """
+        ...
+
+    def schedule(self, action: BaseAction[W], due_tick: Tick | None, /) -> None:
+        """Queue a new action or reschedule an active one.
+
+        Args:
+            action: Action object to admit or reschedule.
+            due_tick: Strictly future deadline, or `None` for execution on
+                every tick.
+
+        Raises:
+            TypeError: If a deadline is not an integer or `None`.
+            ValueError: If a concrete deadline is not later than `tick`.
+        """
+        ...
+
+    def log(self, line: str, /) -> None:
+        """Write one line of narrative for the observer.
+
+        Lines are written in permanent action-sequence order rather than store
+        iteration order.
+
+        Args:
+            line: Complete game-facing narrative line. Foliot does not format
+                or localize it.
+        """
+        ...
+
+    def suspend(
+        self,
+        entity_id: EntityId,
+        /,
+        *,
+        by: SuspensionId | EventId,
+    ) -> None:
+        """Pause an entity's suspendable actions under one waking handle.
+
+        Args:
+            entity_id: Owner whose suspendable actions should pause.
+            by: Stable handle used for the later matching resume.
+        """
+        ...
+
+    def finish(self) -> None:
+        """This action is done; remove it from the queue.
+
+        A scheduled action can stop simply by not rescheduling. A recurring one
+        has no deadline to decline, so it must say so.
+        """
+        ...
+
+
+class FinalizationContext[W](Protocol):
+    """Collect lifecycle work after all normal effects have been applied.
+
+    It deliberately has no RNG or world property. The game receives the
+    post-effect world as the other argument to `TickFinalizer.finalize`, while
+    every requested write still travels through this collecting boundary.
+    """
+
+    @property
+    def tick(self) -> Tick:
+        """Logical tick currently being finalized."""
+        ...
+
+    def emit(self, effect: Effect[W], /) -> None:
+        """Stage one final effect for application in this transaction."""
+        ...
+
+    def schedule(self, action: BaseAction[W], due_tick: Tick | None, /) -> None:
+        """Stage an action for a future tick, or as recurring work."""
+        ...
+
+    def delete(self, action: BaseAction[W], /) -> None:
+        """Remove one action from all future due snapshots."""
+        ...
+
+    def delete_owned_by(self, entity_id: EntityId, /) -> None:
+        """Remove all actions owned by one entity."""
+        ...
+
+    def log(self, line: str, /) -> None:
+        """Append one deterministic journal line for this tick."""
+        ...
+
+
+class TickFinalizer[W](Protocol):
+    """Optional game-owned policy run after a tick's normal effects.
+
+    Use a finalizer for rules that depend on the combined post-effect world,
+    such as death or cleanup. A raised exception aborts the tick transaction.
+    """
+
+    def finalize(self, world: W, ctx: FinalizationContext[W], /) -> None:
+        """Inspect `world` and stage any final lifecycle work in `ctx`."""
+        ...

foliot/drivers.py

@@ -0,0 +1,172 @@
+"""Pacing strategies for the simulation loop.
+
+`process_tick()` never waits. That split is the whole reason the same code path
+runs at one tick per second in production and at ten million ticks per second in
+a test: only the driver differs. Hardcoding `time.sleep` into the loop makes the
+library untestable, and it is felt immediately.
+
+`ManualDriver` advances without waiting. `RealtimeDriver` paces the same loop
+against a monotonic, absolute cadence and skips wall-clock slots after an
+overrun without skipping logical ticks.
+"""
+
+import logging
+import math
+import time
+from dataclasses import dataclass
+from typing import Protocol
+
+from foliot.ids import Tick
+
+__all__ = ["Driver", "ManualDriver", "RealtimeDriver"]
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class Driver(Protocol):
+    """Structural pacing contract consumed by `Simulation.run()`."""
+
+    def wait_for(self, tick: Tick, /) -> None:
+        """Block until `tick` should begin.
+
+        `ManualDriver` returns at once. `RealtimeDriver` sleeps toward an
+        absolute cadence target -- `start + slot * duration` -- never a
+        relative one. Cadence slots may be skipped after an overrun; logical
+        ticks may not.
+        """
+        ...
+
+    def should_continue(self, tick: Tick, /) -> bool:
+        """Whether the next unfinished `tick` should be processed."""
+        ...
+
+
+@dataclass(frozen=True, slots=True)
+class ManualDriver:
+    """Run immediately through an inclusive target tick.
+
+    Args:
+        until_tick: Last logical tick to process. Must be non-negative.
+
+    Raises:
+        TypeError: If `until_tick` is not an integer or is a boolean.
+        ValueError: If `until_tick` is negative.
+    """
+
+    until_tick: Tick
+
+    def __post_init__(self) -> None:
+        if type(self.until_tick) is not int:
+            raise TypeError("until_tick must be an int, not bool")
+        if self.until_tick < 0:
+            raise ValueError("until_tick must be non-negative")
+
+    def wait_for(self, tick: Tick, /) -> None:
+        """Return immediately; manual time never sleeps."""
+        del tick
+
+    def should_continue(self, tick: Tick, /) -> bool:
+        """Include `until_tick`, then stop at the following tick."""
+        return tick <= self.until_tick
+
+
+class RealtimeDriver:
+    """Run continuously on a fixed monotonic cadence.
+
+    The object is intentionally stateful: it remembers one run's cadence
+    anchor, current wall-clock slot, and most recently started logical tick.
+    Create a new driver to establish a fresh cadence after restart.
+
+    Args:
+        tick_seconds: Positive finite number of seconds between cadence slots.
+            Whole and fractional values are supported.
+
+    Raises:
+        TypeError: If `tick_seconds` is not an integer or float, or is a
+            boolean.
+        ValueError: If it is zero, negative, infinite, NaN, or too large to
+            represent as a finite float.
+    """
+
+    __slots__ = (
+        "_cadence_start",
+        "_slot",
+        "_started_at",
+        "_started_tick",
+        "_tick_seconds",
+    )
+
+    def __init__(self, tick_seconds: float) -> None:
+        if type(tick_seconds) not in (int, float):
+            raise TypeError("tick_seconds must be an int or float, not bool")
+        try:
+            normalized = float(tick_seconds)
+        except OverflowError as error:
+            raise ValueError("tick_seconds must be finite and greater than zero") from error
+        if not math.isfinite(normalized) or normalized <= 0.0:
+            raise ValueError("tick_seconds must be finite and greater than zero")
+
+        self._tick_seconds = normalized
+        self._cadence_start: float | None = None
+        self._slot = 0
+        self._started_at: float | None = None
+        self._started_tick: Tick | None = None
+
+    @property
+    def tick_seconds(self) -> float:
+        """Seconds between wall-clock cadence slots."""
+        return self._tick_seconds
+
+    def wait_for(self, tick: Tick, /) -> None:
+        """Wait until `tick` may begin on this run's absolute cadence."""
+        now = self._now()
+        if self._cadence_start is None:
+            self._cadence_start = now
+            self._started_at = now
+            self._started_tick = tick
+            return
+
+        cadence_start = self._cadence_start
+        started_at = self._started_at
+        started_tick = self._started_tick
+        assert started_at is not None
+        assert started_tick is not None
+
+        next_slot = self._slot + 1
+        slot = max(next_slot, math.ceil((now - cadence_start) / self._tick_seconds))
+        deadline = cadence_start + slot * self._tick_seconds
+        while deadline < now:
+            slot += 1
+            deadline = cadence_start + slot * self._tick_seconds
+
+        missed_slots = slot - next_slot
+        if missed_slots:
+            _LOGGER.warning(
+                "realtime tick overran cadence: tick=%s processing_seconds=%.9g "
+                "tick_seconds=%.9g missed_slots=%s",
+                started_tick,
+                now - started_at,
+                self._tick_seconds,
+                missed_slots,
+            )
+
+        remaining = deadline - now
+        if remaining > 0.0:
+            self._sleep(remaining)
+
+        self._slot = slot
+        self._started_at = self._now()
+        self._started_tick = tick
+
+    def should_continue(self, tick: Tick, /) -> bool:
+        """Run until the surrounding application interrupts the loop."""
+        del tick
+        return True
+
+    def _now(self) -> float:
+        """Return monotonic time; overridden only by foliot's private tests."""
+        return time.monotonic()
+
+    def _sleep(self, seconds: float, /) -> None:
+        """Sleep in real time; overridden only by foliot's private tests."""
+        time.sleep(seconds)