seedloop 0.3.0__py3-none-any.whl

seedloop/__init__.py

@@ -0,0 +1,41 @@
+"""seedloop — deterministic simulation testing for Python asyncio.
+
+Write a scenario against a :class:`World`, then ``check`` it across many seeds; a failing seed is
+the reproduction — ``replay`` it to debug. The deterministic core (loop, virtual clock, seeded
+entropy), the simulated network with fault injection (loss, duplication, partitions), the invariant
+API, and the non-determinism auditor are in place; a worked Raft demo ships in ``seedloop.demos``.
+"""
+
+from seedloop._audit import audit_mode
+from seedloop._entropy import ensure_hash_seed
+from seedloop._net import Address, Endpoint, Message, Transport
+from seedloop._run import CheckResult, Scenario, check, replay
+from seedloop._world import Node, World
+from seedloop.errors import (
+    BoundaryError,
+    DeadlockError,
+    EntropyLeakError,
+    InvariantError,
+    SeedloopError,
+)
+
+__all__ = [
+    "Address",
+    "BoundaryError",
+    "CheckResult",
+    "DeadlockError",
+    "Endpoint",
+    "EntropyLeakError",
+    "InvariantError",
+    "Message",
+    "Node",
+    "Scenario",
+    "SeedloopError",
+    "Transport",
+    "World",
+    "audit_mode",
+    "check",
+    "ensure_hash_seed",
+    "replay",
+]
+__version__ = "0.3.0"

seedloop/_audit.py

@@ -0,0 +1,107 @@
+"""The non-determinism auditor: runtime tripwires for uncontrolled entropy (ADR-0008).
+
+A run is a pure function of its seed only if every entropy source it touches is the World's seeded
+one. The loop already rejects the I/O boundary (``run_in_executor``, real sockets, DNS) in every
+mode. This adds an opt-in *audit mode* that closes the Python-level entropy sources the loop does
+not see: real wall-clock time, the unseeded global ``random``, ``os.urandom``/``secrets``, and a
+bare ``threading.Thread``. In audit mode each raises instead of running, so a leak is a loud,
+reproducible failure on the seed that hit it — the boundary enforced, not just stated (scope.md).
+
+The tripwires patch only module-level entry points, never ``random.Random`` itself, so the World's
+seeded ``rng`` keeps working; they are pure raises that touch no entropy and leave a clean run's
+timeline unchanged; and they are restored on exit even on error.
+
+Like any monkeypatch (and the CSPRNG shim), a tripwire catches a call that looks the name up at call
+time — ``time.monotonic()``, ``random.random()`` — but not a reference bound *before* audit started
+(``from time import monotonic`` then ``monotonic()``). The common attribute-call form is caught; the
+same C-level caveat as ``scope.md`` applies below Python.
+"""
+
+from __future__ import annotations
+
+import os
+import random
+import threading
+import time
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from typing import Any
+
+from seedloop.errors import BoundaryError, EntropyLeakError
+
+# Real-time entry points (the loop owns virtual time via loop.time(), so any direct call is a leak).
+_REAL_TIME = ("time", "monotonic", "perf_counter", "time_ns", "monotonic_ns", "perf_counter_ns")
+
+# Every entropy-drawing module-level `random` function — the *complete* set on the global unseeded
+# instance, not a subset, so a leak through any (e.g. expovariate for latency jitter) is caught.
+# These are module functions; `random.Random` instances such as the seeded rng are untouched.
+_RANDOM_FUNCS = (
+    "random",
+    "uniform",
+    "triangular",
+    "randint",
+    "randrange",
+    "choice",
+    "choices",
+    "shuffle",
+    "sample",
+    "getrandbits",
+    "randbytes",
+    "betavariate",
+    "expovariate",
+    "gammavariate",
+    "gauss",
+    "lognormvariate",
+    "normalvariate",
+    "vonmisesvariate",
+    "paretovariate",
+    "weibullvariate",
+    "binomialvariate",  # 3.12+
+)
+
+# Each tripwire is (module, attribute, display name). hasattr-guarded so a name absent on a given
+# interpreter is skipped rather than crashing the patcher. os.urandom and the random._urandom alias
+# that secrets draws through are intercepted too.
+_ENTROPY_SURFACES: list[tuple[Any, str, str]] = [
+    *((time, name, f"time.{name}") for name in _REAL_TIME if hasattr(time, name)),
+    (os, "urandom", "os.urandom"),
+    (random, "_urandom", "secrets/os.urandom"),
+    *((random, name, f"random.{name}") for name in _RANDOM_FUNCS if hasattr(random, name)),
+]
+
+
+def _entropy_tripwire(source: str) -> Callable[..., Any]:
+    def tripwire(*_args: Any, **_kwargs: Any) -> Any:
+        raise EntropyLeakError(source)
+
+    return tripwire
+
+
+def _thread_tripwire(*_args: Any, **_kwargs: Any) -> Any:
+    raise BoundaryError(
+        "threading.Thread (a real thread) cannot be made deterministic and is out of scope in a "
+        "simulated run (see docs/scope.md)"
+    )
+
+
+@contextmanager
+def audit_mode() -> Iterator[None]:
+    """Trip on uncontrolled entropy for the duration of the context.
+
+    Inside the context, real time, the unseeded global ``random``, ``os.urandom``/``secrets``, and
+    ``threading.Thread.start`` raise (``EntropyLeakError`` for entropy, ``BoundaryError`` for the
+    thread) instead of running. The World's seeded ``rng`` and virtual clock are unaffected. Use it
+    via ``check(..., audit=True)`` / ``replay(..., audit=True)``, or directly to wrap your own run.
+    All patches are restored on exit, even on error.
+    """
+    saved = [(mod, attr, getattr(mod, attr)) for mod, attr, _ in _ENTROPY_SURFACES]
+    saved_thread_start = threading.Thread.start
+    for mod, attr, name in _ENTROPY_SURFACES:
+        setattr(mod, attr, _entropy_tripwire(name))
+    threading.Thread.start = _thread_tripwire  # type: ignore[method-assign]
+    try:
+        yield
+    finally:
+        for mod, attr, original in saved:
+            setattr(mod, attr, original)
+        threading.Thread.start = saved_thread_start  # type: ignore[method-assign]

seedloop/_entropy.py

@@ -0,0 +1,96 @@
+"""Seeded entropy: per-component sub-streams, a CSPRNG shim, and a hash-seed launcher.
+
+A run is a pure function of its seed, so every source of randomness must derive from it. The root
+seed is split into independent named sub-streams (ADR-0009) so adding a draw in one component does
+not perturb another's sequence. The CSPRNG shim routes ``os.urandom``/``secrets`` to a seeded
+source for the duration of a run, and the launcher pins ``PYTHONHASHSEED`` before the interpreter
+starts so set/dict iteration order is fixed (ADR-0010).
+
+Verified against the interpreter during design: shimming ``os.urandom`` alone does *not* control
+``secrets``/``random``, because ``random`` binds ``from os import urandom as _urandom`` at import —
+so the shim patches ``random._urandom`` too; and two child processes launched with the same
+``PYTHONHASHSEED`` hash identically while a different value differs.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import random
+import sys
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+
+_REEXEC_GUARD = "_SEEDLOOP_HASHSEED_REEXEC"
+
+
+def substream(root_seed: int, label: str) -> random.Random:
+    """Derive an independent, reproducible ``random.Random`` for a named component.
+
+    The stream is a pure function of ``(root_seed, label)``. Derivation hashes the canonical text
+    ``f"{root_seed}:{label}"`` with ``blake2b`` — never the builtin ``hash()``, which is randomized
+    per process — so the same pair yields the same stream in every process, and any ``int`` seed
+    works (negative, or larger than 64 bits).
+    """
+    digest = hashlib.blake2b(f"{root_seed}:{label}".encode(), digest_size=32).digest()
+    return random.Random(int.from_bytes(digest, "big"))
+
+
+@contextmanager
+def csprng_shim(stream: random.Random) -> Iterator[None]:
+    """Route ``os.urandom`` and ``secrets`` to ``stream`` for the duration of the context.
+
+    Patches both ``os.urandom`` and the ``random._urandom`` alias that ``secrets`` draws through;
+    restores both originals on exit, even on error. Scoped to a single run; runs do not overlap in
+    one process.
+    """
+    seeded = _seeded_urandom(stream)
+    orig_os = os.urandom
+    orig_random = random._urandom  # type: ignore[attr-defined]  # private alias secrets draws through
+    os.urandom = seeded
+    random._urandom = seeded  # type: ignore[attr-defined]
+    try:
+        yield
+    finally:
+        os.urandom = orig_os
+        random._urandom = orig_random  # type: ignore[attr-defined]
+
+
+def _seeded_urandom(stream: random.Random) -> Callable[[int], bytes]:
+    def seeded_urandom(n: int) -> bytes:
+        return stream.getrandbits(n * 8).to_bytes(n, "big") if n else b""
+
+    return seeded_urandom
+
+
+def hash_seed_for(root_seed: int) -> int:
+    """The ``PYTHONHASHSEED`` value (0..4294967295) a run pins, derived from its root seed."""
+    digest = hashlib.blake2b(f"{root_seed}:hashseed".encode(), digest_size=4).digest()
+    return int.from_bytes(digest, "big")
+
+
+def ensure_hash_seed(root_seed: int) -> None:
+    """Ensure the interpreter runs with the run's pinned ``PYTHONHASHSEED``.
+
+    ``PYTHONHASHSEED`` is read once at interpreter start, so it cannot be set from inside a run;
+    this re-runs the interpreter with the pinned value when needed. If already pinned, returns and
+    the caller proceeds in-process. Otherwise it launches a pinned child running the same command
+    and does not return — on POSIX by replacing the process (``execve``), on Windows (no true
+    ``exec``) by spawning a child and exiting with its return code. A guard env var prevents
+    infinite recursion.
+    """
+    target = str(hash_seed_for(root_seed))
+    if os.environ.get(_REEXEC_GUARD) == target or os.environ.get("PYTHONHASHSEED") == target:
+        return  # already pinned (our child, or started correctly); proceed in-process
+    child_env = dict(os.environ, PYTHONHASHSEED=target, **{_REEXEC_GUARD: target})
+    # sys.orig_argv is the full original command (including -c / -m and their payload), so the
+    # child re-runs exactly what the parent ran; reconstructing from sys.argv would drop -c code.
+    argv = [sys.executable, *sys.orig_argv[1:]]
+    if os.name == "posix":
+        os.execve(sys.executable, argv, child_env)
+    else:
+        # Windows has no in-place exec; spawn a pinned child and propagate its exit code.
+        import subprocess
+
+        completed = subprocess.run(argv, env=child_env)
+        sys.exit(completed.returncode)

seedloop/_loop.py

@@ -0,0 +1,165 @@
+"""The deterministic event loop.
+
+``asyncio``'s loop is already single-threaded and its scheduling is deterministic by
+construction; the one nondeterministic seam is the I/O poll (``selector.select()``). seedloop
+subclasses :class:`asyncio.BaseEventLoop` and overrides only ``_run_once`` to remove that poll
+(ADR-0013): the ready queue is drained in faithful ``call_soon`` FIFO order (ADR-0012), and the
+real-I/O surface is rejected rather than run (``docs/scope.md``).
+
+Time is virtual: ``loop.time()`` starts at 0 and never advances by waiting. When every task is
+blocked, the loop jumps the clock to the next scheduled timer (the autojump of ADR-0005), so a
+ten-second ``sleep`` resolves instantly. Timers live in a heap keyed ``(when, seq)``, so equal
+deadlines fire in scheduling order — a deterministic tie-break CPython's ``TimerHandle`` (ordered by
+deadline alone) lacks. ``BaseEventLoop`` (unlike ``BaseSelectorEventLoop``) creates no selector and
+no self-pipe, so no real socket exists in the loop.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import heapq
+from collections.abc import Callable
+from typing import Any, NoReturn
+
+from seedloop.errors import BoundaryError, DeadlockError
+
+
+class DeterministicLoop(asyncio.BaseEventLoop):
+    """A single-threaded ``asyncio`` loop with no real I/O and a virtual clock."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._sl_time = 0.0  # virtual monotonic time; advanced only by the autojump
+        # Timer heap of (when, seq, handle); the monotonic seq is the deterministic tie-break,
+        # so equal deadlines fire in scheduling order.
+        self._sl_timers: list[tuple[float, int, asyncio.TimerHandle]] = []
+        self._sl_timer_seq = 0
+        # Optional hook the World uses to check invariants after each step; None by default, so a
+        # run without invariants is unchanged. It may raise to fail the run.
+        self._sl_after_step: Callable[[], None] | None = None
+
+    def time(self) -> float:
+        return self._sl_time
+
+    def call_at(  # type: ignore[override]
+        self, when: float, callback: Any, *args: Any, context: Any = None
+    ) -> asyncio.TimerHandle:
+        self._check_closed()  # type: ignore[attr-defined]  # BaseEventLoop guard, not in the stubs
+        timer = asyncio.TimerHandle(when, callback, args, self, context)
+        heapq.heappush(self._sl_timers, (when, self._sl_timer_seq, timer))
+        self._sl_timer_seq += 1
+        return timer
+
+    def call_later(  # type: ignore[override]
+        self, delay: float, callback: Any, *args: Any, context: Any = None
+    ) -> asyncio.TimerHandle:
+        return self.call_at(self._sl_time + delay, callback, *args, context=context)
+
+    def _timer_handle_cancelled(self, handle: asyncio.TimerHandle) -> None:
+        # Cancelled timers are tombstoned and skipped when popped; no count bookkeeping needed.
+        pass
+
+    def _run_once(self) -> None:
+        # Deterministic replacement for BaseEventLoop._run_once: no select(), no real I/O. When
+        # nothing is ready, advance virtual time to the next timer (autojump); then promote every
+        # timer now due and run the ready batch in faithful FIFO order (ADR-0012).
+        ready: Any = self._ready  # type: ignore[attr-defined]  # BaseEventLoop's ready deque
+        if not ready:
+            self._purge_cancelled_timers()
+            if self._sl_timers:
+                self._sl_time = max(self._sl_time, self._sl_timers[0][0])  # jump forward only
+            elif not self._stopping:  # type: ignore[attr-defined]  # BaseEventLoop stop flag
+                raise DeadlockError(
+                    "the run is quiescent: every task is blocked and no timer is scheduled to "
+                    "wake one"
+                )
+        self._fire_due_timers()
+        # Run the batch ready at step start in registration order; callbacks scheduled mid-batch
+        # run on the next step (the len() bound), matching CPython.
+        for _ in range(len(ready)):
+            handle = ready.popleft()
+            if not handle.cancelled():
+                handle._run()
+        if self._sl_after_step is not None:
+            self._sl_after_step()  # check invariants; may raise to fail the run
+
+    def _fire_due_timers(self) -> None:
+        # Promote every timer whose deadline has arrived (<= the clock) to the ready queue.
+        ready = self._ready  # type: ignore[attr-defined]
+        while self._sl_timers and self._sl_timers[0][0] <= self._sl_time:
+            handle = heapq.heappop(self._sl_timers)[2]
+            if not handle.cancelled():
+                ready.append(handle)
+
+    def _purge_cancelled_timers(self) -> None:
+        # Drop cancelled timers from the heap head so the earliest entry is a live deadline.
+        while self._sl_timers and self._sl_timers[0][2].cancelled():
+            heapq.heappop(self._sl_timers)
+
+    # --- boundary: operations that cannot be made deterministic are rejected (ADR-0002) ---
+
+    def _reject(self, what: str) -> NoReturn:
+        raise BoundaryError(
+            f"{what} cannot be made deterministic and is out of scope inside a simulated run "
+            f"(see docs/scope.md)"
+        )
+
+    def run_in_executor(self, *args: Any, **kwargs: Any) -> NoReturn:  # type: ignore[override]
+        self._reject("run_in_executor (real threads)")
+
+    def call_soon_threadsafe(self, *args: Any, **kwargs: Any) -> NoReturn:  # type: ignore[override]
+        self._reject("call_soon_threadsafe (another thread)")
+
+    def add_reader(self, *args: Any, **kwargs: Any) -> NoReturn:  # type: ignore[override]
+        self._reject("add_reader (real I/O)")
+
+    def add_writer(self, *args: Any, **kwargs: Any) -> NoReturn:  # type: ignore[override]
+        self._reject("add_writer (real I/O)")
+
+    async def sock_recv(self, *args: Any, **kwargs: Any) -> NoReturn:
+        self._reject("sock_recv (real socket)")
+
+    async def sock_sendall(self, *args: Any, **kwargs: Any) -> NoReturn:
+        self._reject("sock_sendall (real socket)")
+
+    async def sock_connect(self, *args: Any, **kwargs: Any) -> NoReturn:
+        self._reject("sock_connect (real socket)")
+
+    async def getaddrinfo(self, *args: Any, **kwargs: Any) -> NoReturn:
+        self._reject("getaddrinfo (real DNS)")
+
+    async def getnameinfo(self, *args: Any, **kwargs: Any) -> NoReturn:
+        self._reject("getnameinfo (real DNS)")
+
+    async def create_connection(self, *args: Any, **kwargs: Any) -> NoReturn:
+        self._reject("create_connection (real socket)")
+
+    async def create_server(self, *args: Any, **kwargs: Any) -> NoReturn:
+        self._reject("create_server (real socket)")
+
+    async def create_datagram_endpoint(self, *args: Any, **kwargs: Any) -> NoReturn:
+        # BaseEventLoop's version opens and binds a real UDP socket before failing; reject first.
+        self._reject("create_datagram_endpoint (real socket)")
+
+    async def connect_read_pipe(self, *args: Any, **kwargs: Any) -> NoReturn:
+        self._reject("connect_read_pipe (real pipe)")
+
+    async def connect_write_pipe(self, *args: Any, **kwargs: Any) -> NoReturn:
+        self._reject("connect_write_pipe (real pipe)")
+
+    async def subprocess_exec(self, *args: Any, **kwargs: Any) -> NoReturn:
+        self._reject("subprocess_exec (real subprocess)")
+
+    async def subprocess_shell(self, *args: Any, **kwargs: Any) -> NoReturn:
+        self._reject("subprocess_shell (real subprocess)")
+
+    def add_signal_handler(self, *args: Any, **kwargs: Any) -> NoReturn:  # type: ignore[override]
+        self._reject("add_signal_handler (real signals)")
+
+    # _process_events and _write_to_self are abstract on BaseEventLoop. We never poll and never
+    # need a cross-thread wakeup, so both are inert.
+    def _process_events(self, event_list: Any) -> None:
+        pass
+
+    def _write_to_self(self) -> None:
+        pass

seedloop/_net.py

@@ -0,0 +1,190 @@
+"""The simulated network: messages delivered as seeded timer events, with faults.
+
+A message in flight is an ordinary timer on the loop's heap (``docs/network.md``). ``send`` draws a
+latency from the seed's ``"net"`` sub-stream and schedules a delivery at ``now + latency``; ``recv``
+blocks in virtual time until a message is queued. Reordering is emergent — two messages sent close
+together draw independent latencies, so arrival order can differ from send order, reproducibly.
+
+Faults — loss, duplication, and partitions — are drawn from the seed's ``"faults"`` sub-stream
+(independent of ``"net"``, so enabling a fault does not shift surviving messages' latencies). An
+endpoint can opt into a reliable, ordered channel. No real socket exists; the "network" is queues
+and timers.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections import deque
+from random import Random
+from typing import Protocol, runtime_checkable
+
+from seedloop._trace import Timeline
+from seedloop.errors import SeedloopError
+
+Address = int  # a node's address on the simulated network
+Message = object  # an opaque payload; seedloop schedules and orders it, never inspects it
+
+# Default per-message latency range, in virtual seconds. Wide enough that two near-simultaneous
+# sends can reorder.
+_LAT_MIN = 0.001
+_LAT_MAX = 0.020
+
+
+@runtime_checkable
+class Endpoint(Protocol):
+    """A node's bound handle on the network."""
+
+    address: Address
+
+    async def send(self, dst: Address, msg: Message) -> None: ...
+    async def recv(self) -> tuple[Address, Message]: ...
+
+
+class Transport:
+    """The simulated network behind ``world.net``."""
+
+    def __init__(
+        self,
+        loop: asyncio.AbstractEventLoop,
+        net_rng: Random,
+        faults_rng: Random,
+        timeline: Timeline,
+    ) -> None:
+        self._loop = loop
+        self._net = net_rng
+        self._faults = faults_rng
+        self._timeline = timeline
+        self._endpoints: dict[Address, _Endpoint] = {}
+        self._next_mid = 0  # monotonic message id — the stable timeline identity, not Python id()
+        self._partition: list[set[Address]] | None = None  # groups; None means full connectivity
+        self._reliable_clock: dict[
+            tuple[Address, Address], float
+        ] = {}  # per-link FIFO delivery time
+
+    def bind(
+        self,
+        address: Address,
+        *,
+        reliable: bool = False,
+        loss: float = 0.0,
+        duplicate: float = 0.0,
+    ) -> Endpoint:
+        """Give a node an endpoint at ``address``.
+
+        ``loss``/``duplicate`` are per-message probabilities on this endpoint's outgoing links;
+        ``reliable=True`` gives no-loss, in-order delivery (and ignores loss/duplicate).
+        Binding the same address twice is an error.
+        """
+        if address in self._endpoints:
+            raise SeedloopError(f"address {address} is already bound")
+        if not 0.0 <= loss <= 1.0:
+            raise SeedloopError(f"loss must be a probability in [0, 1], got {loss}")
+        if not 0.0 <= duplicate <= 1.0:
+            raise SeedloopError(f"duplicate must be a probability in [0, 1], got {duplicate}")
+        endpoint = _Endpoint(self, address, reliable=reliable, loss=loss, duplicate=duplicate)
+        self._endpoints[address] = endpoint
+        return endpoint
+
+    def partition(self, *groups: set[Address]) -> None:
+        """Split the network: nodes in different groups cannot reach each other until ``heal``.
+
+        A node in no listed group stays connected to everyone (it is not partitioned away).
+        """
+        self._partition = [set(g) for g in groups]
+
+    def heal(self) -> None:
+        """Restore full connectivity."""
+        self._partition = None
+
+    def _reachable(self, src: Address, dst: Address) -> bool:
+        if self._partition is None:
+            return True
+        gs = next((g for g in self._partition if src in g), None)
+        gd = next((g for g in self._partition if dst in g), None)
+        if gs is None or gd is None:
+            return True  # an unpartitioned node reaches everyone
+        return gs is gd
+
+    def _send(self, endpoint: _Endpoint, dst: Address, msg: Message) -> None:
+        src = endpoint.address
+        mid = self._next_mid
+        self._next_mid += 1
+        self._timeline.record((self._loop.time(), "send", mid, src, dst))
+        if endpoint._reliable:
+            self._schedule_reliable(mid, src, dst, msg)
+            return
+        if endpoint._loss > 0.0 and self._faults.random() < endpoint._loss:
+            self._timeline.record((self._loop.time(), "drop", mid, src, dst))
+            return
+        self._schedule_delivery(mid, src, dst, msg)
+        if endpoint._duplicate > 0.0 and self._faults.random() < endpoint._duplicate:
+            self._timeline.record((self._loop.time(), "duplicate", mid, src, dst))
+            self._schedule_delivery(mid, src, dst, msg)
+
+    def _schedule_delivery(self, mid: int, src: Address, dst: Address, msg: Message) -> None:
+        latency = self._net.uniform(_LAT_MIN, _LAT_MAX)
+        self._loop.call_later(latency, self._deliver, mid, src, dst, msg)
+
+    def _schedule_reliable(self, mid: int, src: Address, dst: Address, msg: Message) -> None:
+        # Non-decreasing delivery times per (src, dst); equal times fire in send order via the timer
+        # (when, seq) tie-break — so a reliable link delivers in order, with no loss or duplication.
+        latency = self._net.uniform(_LAT_MIN, _LAT_MAX)
+        key = (src, dst)
+        when = max(self._loop.time() + latency, self._reliable_clock.get(key, 0.0))
+        self._reliable_clock[key] = when
+        self._loop.call_at(when, self._deliver, mid, src, dst, msg)
+
+    def _deliver(self, mid: int, src: Address, dst: Address, msg: Message) -> None:
+        if not self._reachable(src, dst):
+            # Reachability is evaluated when the delivery fires, not at send: a partition opened in
+            # flight cuts the message; one that healed in time lets it through.
+            self._timeline.record((self._loop.time(), "drop-partitioned", mid, src, dst))
+            return
+        self._timeline.record((self._loop.time(), "deliver", mid, src, dst))
+        endpoint = self._endpoints.get(dst)
+        if endpoint is None:
+            return  # datagram to an unbound address is dropped, like sending into the void
+        endpoint._enqueue((src, msg))
+
+
+class _Endpoint:
+    """Concrete endpoint: a receive queue, an optional waiter, and its outgoing-link policy."""
+
+    def __init__(
+        self,
+        transport: Transport,
+        address: Address,
+        *,
+        reliable: bool,
+        loss: float,
+        duplicate: float,
+    ) -> None:
+        self.address = address
+        self._transport = transport
+        self._reliable = reliable
+        self._loss = loss
+        self._duplicate = duplicate
+        self._queue: deque[tuple[Address, Message]] = deque()
+        self._waiter: asyncio.Future[None] | None = None
+
+    async def send(self, dst: Address, msg: Message) -> None:
+        # Schedules a delivery and returns immediately; it does not block on delivery.
+        self._transport._send(self, dst, msg)
+
+    async def recv(self) -> tuple[Address, Message]:
+        if self._waiter is not None:
+            # One endpoint has one logical receiver; a second concurrent recv would orphan the
+            # first's waiter. Fail loudly rather than corrupt delivery silently.
+            raise SeedloopError("concurrent recv on one endpoint is not supported")
+        while not self._queue:
+            self._waiter = self._transport._loop.create_future()
+            try:
+                await self._waiter
+            finally:
+                self._waiter = None
+        return self._queue.popleft()
+
+    def _enqueue(self, item: tuple[Address, Message]) -> None:
+        self._queue.append(item)
+        if self._waiter is not None and not self._waiter.done():
+            self._waiter.set_result(None)

seedloop/_run.py

@@ -0,0 +1,88 @@
+"""Running scenarios: ``check`` sweeps seeds, ``replay`` reproduces one.
+
+The contract (ADR-0003): a run is a pure function of its seed, so a failing seed *is* the
+reproduction. ``check`` runs a scenario once per seed and reports the first failing seed; ``replay``
+rebuilds that exact run. A fresh :class:`World` is built per seed with no shared mutable state, so
+one run cannot bleed into the next.
+
+``check``/``replay`` do not pin ``PYTHONHASHSEED`` (ADR-0015): the launcher re-runs the whole
+interpreter, which is wrong to trigger implicitly from inside a test runner. The guarantee instead
+rests on library code never depending on hash order; a user whose own code does can call
+``seedloop.ensure_hash_seed`` at their entry point.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Iterable, Sequence
+from dataclasses import dataclass
+from typing import Literal
+
+from seedloop._audit import audit_mode
+from seedloop._entropy import csprng_shim, substream
+from seedloop._world import World
+
+Scenario = Callable[[World], Awaitable[None]]
+
+
+@dataclass(frozen=True)
+class CheckResult:
+    """The outcome of a seed sweep."""
+
+    checked: int  # how many seeds ran
+    failing_seed: int | None  # first failing seed, or None if all passed
+    error: Exception | None  # the exception that seed raised, or None
+
+
+def _run_one(scenario: Scenario, seed: int, *, audit: bool = False) -> Sequence[object]:
+    """Run ``scenario`` for one seed and return its recorded timeline.
+
+    Normally the CSPRNG shim is installed for the run and removed after, so ``os.urandom`` and
+    ``secrets`` draw from the seed without leaking the seeded source into later runs. With
+    ``audit=True`` the non-determinism auditor runs instead: uncontrolled entropy (real time, the
+    unseeded global ``random``, ``os.urandom``/``secrets``, a real thread) raises rather than being
+    seeded or run, so a leak fails on this seed (ADR-0008).
+    """
+    world = World(seed)
+    context = audit_mode() if audit else csprng_shim(substream(seed, "csprng"))
+    with context:
+        world._drive(scenario(world))
+    return world.timeline
+
+
+def check(
+    scenario: Scenario,
+    *,
+    seeds: int | Iterable[int] = 1000,
+    on_failure: Literal["raise", "return"] = "raise",
+    audit: bool = False,
+) -> CheckResult:
+    """Run ``scenario`` once per seed; report the first seed that fails.
+
+    ``seeds=N`` runs seeds ``0..N-1``; an iterable runs exactly those seeds. The first run that
+    raises — an ``assert``, a ``SeedloopError``, or any exception from the scenario — is the
+    failure. With ``on_failure="raise"`` the exception is re-raised tagged with its seed; with
+    ``"return"`` the sweep stops and returns the :class:`CheckResult`. With ``audit=True`` the
+    non-determinism auditor runs each seed: an uncontrolled entropy source fails it (ADR-0008).
+    """
+    seed_iter: Iterable[int] = range(seeds) if isinstance(seeds, int) else seeds
+    checked = 0
+    for seed in seed_iter:
+        checked += 1
+        try:
+            _run_one(scenario, seed, audit=audit)
+        except Exception as error:
+            # Only a scenario *failure* is caught; KeyboardInterrupt/SystemExit propagate so a
+            # long sweep stays abortable (and is never mis-tagged as a failing seed).
+            error.add_note(f"seedloop: failing seed={seed} (replay with seedloop.replay)")
+            if on_failure == "raise":
+                raise
+            return CheckResult(checked=checked, failing_seed=seed, error=error)
+    return CheckResult(checked=checked, failing_seed=None, error=None)
+
+
+def replay(scenario: Scenario, *, seed: int, audit: bool = False) -> None:
+    """Rebuild the exact run for ``seed`` and run it once, re-raising any failure.
+
+    ``audit=True`` reproduces the run under the non-determinism auditor (ADR-0008).
+    """
+    _run_one(scenario, seed, audit=audit)

seedloop/_trace.py

@@ -0,0 +1,29 @@
+"""The timeline: an append-only record of a run's events.
+
+Determinism is proven by replay — running the same scenario twice must produce an identical
+timeline (``docs/testing.md``). This slice records the events a scenario chooses to log; later
+slices add scheduled network and fault events with stable identities.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+
+class Timeline:
+    """An ordered, append-only log of events for one run."""
+
+    def __init__(self) -> None:
+        self._events: list[object] = []
+
+    def record(self, event: object) -> None:
+        """Append one event to the timeline."""
+        self._events.append(event)
+
+    @property
+    def events(self) -> Sequence[object]:
+        """The events recorded so far, in order (a read-only snapshot)."""
+        return tuple(self._events)
+
+    def __repr__(self) -> str:
+        return f"Timeline({self._events!r})"

seedloop/_world.py

@@ -0,0 +1,112 @@
+"""The World: everything for one deterministic run, derived from one seed.
+
+A run is a pure function of its seed. The World assembles the deterministic loop, the virtual clock,
+and the seeded entropy into one object, exposes the user's seeded ``rng`` and the virtual clock, and
+records a timeline so two runs of a seed can be compared. Users do not construct a World;
+``check``/``replay`` build it and pass it to the scenario.
+
+Scheduling stays faithful FIFO (ADR-0012), so the seed's observable effect is ``rng``, timer timing,
+and the simulated network's delivery timing — not callback order.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable
+from typing import Protocol, runtime_checkable
+
+from seedloop._entropy import substream
+from seedloop._loop import DeterministicLoop
+from seedloop._net import Transport
+from seedloop._trace import Timeline
+from seedloop.errors import InvariantError
+
+
+@runtime_checkable
+class Node(Protocol):
+    """User code the World can start: any object with an async ``run``."""
+
+    async def run(self) -> None: ...
+
+
+class World:
+    """One deterministic run, all derived from ``seed``."""
+
+    def __init__(self, seed: int) -> None:
+        self.seed = seed
+        self.rng = substream(seed, "user")  # the user's entropy; never the global random
+        self._loop = DeterministicLoop()
+        self._timeline = Timeline()
+        self._started: list[asyncio.Task[None]] = []
+        self._invariants: list[tuple[str, Callable[[], bool]]] = []
+        self.net = Transport(
+            self._loop, substream(seed, "net"), substream(seed, "faults"), self._timeline
+        )
+
+    def now(self) -> float:
+        """Current virtual time in seconds (advances by autojump, never by real waiting)."""
+        return self._loop.time()
+
+    def record(self, event: object) -> None:
+        """Append an event to the run's timeline, stamped with the current virtual time.
+
+        The timeline is the artifact that proves determinism: two runs of a seed must record an
+        identical sequence. A scenario records the decisions whose reproducibility it cares about.
+        """
+        self._timeline.record((self._loop.time(), event))
+
+    def always(self, predicate: Callable[[], bool], *, name: str) -> None:
+        """Register a safety property that must hold throughout the run.
+
+        ``predicate`` is evaluated after every step (not during teardown); the first step where it
+        is false raises ``InvariantError(name)``, which ``check`` reports. It must be pure and
+        read-only — a predicate that mutates state or draws entropy would break determinism. A
+        started node's body runs a step after ``start``, so a predicate over node state sees its
+        initial value on the first check.
+        """
+        self._invariants.append((name, predicate))
+        self._loop._sl_after_step = self._check_invariants  # check from the next step on
+
+    def _check_invariants(self) -> None:
+        for name, predicate in self._invariants:
+            if not predicate():
+                raise InvariantError(name, self._loop.time())
+
+    def start(self, *nodes: Node) -> None:
+        """Schedule each node's ``run()`` coroutine as a task on the loop.
+
+        A started node that raises fails the run (its exception surfaces from the run), rather than
+        being orphaned and silently logged — a failure the seed must report.
+        """
+        for node in nodes:
+            self._started.append(self._loop.create_task(node.run()))
+
+    @property
+    def timeline(self) -> tuple[object, ...]:
+        """The recorded timeline so far (a read-only snapshot)."""
+        return tuple(self._timeline.events)
+
+    def _drive(self, main: Awaitable[None]) -> None:
+        """Run the scenario to completion, surface any started-node failure, then close the loop."""
+        try:
+            self._loop.run_until_complete(main)
+            # The scenario finished without raising; surface the first started node that failed
+            # (a crashed node would otherwise be an orphaned task, only logged).
+            for task in self._started:
+                exc = task.exception() if task.done() and not task.cancelled() else None
+                if exc is not None:
+                    raise exc
+        finally:
+            # Invariants describe the logical run, not cancellation cleanup — stop checking them
+            # before teardown, so a node mutating observed state in its cancel handler cannot raise
+            # a spurious InvariantError (and cannot mask the real failure raised above).
+            self._loop._sl_after_step = None
+            # Cancel every task still pending — started nodes and any the scenario spawned — and let
+            # the cancellations process, so the loop closes without "Task was destroyed but it is
+            # pending" warnings (a node loop that never returns, or a recv stuck under a fault).
+            pending = [t for t in asyncio.all_tasks(self._loop) if not t.done()]
+            for task in pending:
+                task.cancel()
+            if pending:
+                self._loop.run_until_complete(asyncio.gather(*pending, return_exceptions=True))
+            self._loop.close()

seedloop/demos/__init__.py

@@ -0,0 +1 @@
+"""Worked demos that run real protocols under seedloop."""

seedloop/demos/raft.py

@@ -0,0 +1,181 @@
+"""A small Raft leader election, run under seedloop — the worked proof.
+
+This is election only (terms, ``RequestVote``, majority, heartbeats); log replication, persistence,
+and membership changes are out of scope. It exists to demonstrate one thing end to end: seedloop
+finds a real class of consensus bug and replays it from a seed.
+
+The bug is a deliberate, labelled toggle, not a claimed discovery in canonical Raft. With
+``buggy=True`` a node omits the single-vote-per-term rule, so it can grant a vote to two candidates
+in the same term; in a three-node cluster that lets both reach a majority and become leader in one
+term — split-brain, the exact failure the majority rule exists to prevent. With ``buggy=False`` the
+rule is enforced and the same seed sweep finds no violation. That two-sided result is the proof: the
+violation is the toggled flaw, not an accident of the harness.
+
+Run it:  ``python -m seedloop.demos.raft``
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+from typing import cast
+
+import seedloop
+from seedloop import World
+
+FOLLOWER, CANDIDATE, LEADER = "follower", "candidate", "leader"
+
+# Election timeouts are drawn from world.rng (so the seed owns the race); the leader's heartbeat is
+# faster than any election timeout, so a stable leader suppresses new elections.
+_ELECTION_MIN, _ELECTION_MAX = 0.15, 0.30
+_HEARTBEAT = 0.05
+
+
+class RaftNode:
+    """One node's election logic, sans-I/O against ``world.net``."""
+
+    def __init__(self, world: World, addr: int, peers: list[int], *, buggy: bool) -> None:
+        self._world = world
+        self._ep = world.net.bind(addr)
+        self.addr = addr
+        self._peers = peers
+        self._all = len(peers) + 1
+        self._buggy = buggy
+        self.term = 0
+        self.role = FOLLOWER
+        self._voted_for: int | None = None
+        self._votes: set[int] = set()
+
+    def _election_timeout(self) -> float:
+        return self._world.rng.uniform(_ELECTION_MIN, _ELECTION_MAX)
+
+    async def _broadcast(self, msg: object) -> None:
+        for p in self._peers:
+            await self._ep.send(p, msg)
+
+    def _adopt_newer_term(self, term: int) -> None:
+        # Only a strictly higher term resets the vote — a node votes at most once per term, so
+        # stepping down within the same term must NOT clear who it already voted for.
+        if term > self.term:
+            self.term = term
+            self.role = FOLLOWER
+            self._voted_for = None
+            self._votes = set()
+
+    async def run(self) -> None:
+        while True:
+            timeout = _HEARTBEAT if self.role == LEADER else self._election_timeout()
+            try:
+                src, msg = await asyncio.wait_for(self._ep.recv(), timeout=timeout)
+            except TimeoutError:
+                if self.role == LEADER:
+                    await self._broadcast(("heartbeat", self.term, self.addr))
+                else:
+                    await self._begin_election()
+                continue
+            await self._handle(src, msg)
+
+    async def _begin_election(self) -> None:
+        self.term += 1
+        self.role = CANDIDATE
+        self._voted_for = self.addr
+        self._votes = {self.addr}  # vote for self
+        await self._broadcast(("request_vote", self.term, self.addr))
+
+    async def _handle(self, src: int, msg: object) -> None:
+        fields = cast("tuple[object, ...]", msg)
+        kind = fields[0]
+        if kind == "request_vote":
+            await self._on_request_vote(src, cast("int", fields[1]))
+        elif kind == "vote":
+            await self._on_vote(
+                cast("int", fields[1]), cast("int", fields[2]), cast("bool", fields[3])
+            )
+        elif kind == "heartbeat":
+            self._on_heartbeat(cast("int", fields[1]))
+
+    async def _on_request_vote(self, src: int, term: int) -> None:
+        self._adopt_newer_term(term)
+        grant = False
+        # The bug: the correct rule grants at most one vote per term (`_voted_for` guard); the buggy
+        # path drops the guard, so a node can vote for two candidates in one term.
+        if (
+            term == self.term
+            and self.role != LEADER
+            and (self._buggy or self._voted_for in (None, src))
+        ):
+            grant = True
+            self._voted_for = src
+        await self._ep.send(src, ("vote", self.term, self.addr, grant))
+
+    async def _on_vote(self, term: int, voter: int, granted: bool) -> None:
+        if term == self.term and self.role == CANDIDATE and granted:
+            self._votes.add(voter)  # distinct voters; a majority of them elects
+            if len(self._votes) > self._all // 2:  # a majority elects
+                self.role = LEADER
+                await self._broadcast(("heartbeat", self.term, self.addr))
+
+    def _on_heartbeat(self, term: int) -> None:
+        self._adopt_newer_term(term)
+        if term == self.term and self.role != FOLLOWER:
+            self.role = FOLLOWER  # a leader exists this term; step down but keep our vote
+
+
+def leaders_by_term(nodes: list[RaftNode]) -> dict[int, set[int]]:
+    """Map each term to the set of nodes that currently believe they lead it."""
+    out: dict[int, set[int]] = {}
+    for node in nodes:
+        if node.role == LEADER:
+            out.setdefault(node.term, set()).add(node.addr)
+    return out
+
+
+def at_most_one_leader_per_term(nodes: list[RaftNode]) -> bool:
+    """Raft's election-safety property: no term ever has two leaders."""
+    return all(len(leaders) <= 1 for leaders in leaders_by_term(nodes).values())
+
+
+def election_scenario(*, buggy: bool, nodes: int = 3, seconds: float = 3.0) -> seedloop.Scenario:
+    """A scenario that runs a cluster and asserts election safety throughout."""
+
+    async def scenario(world: World) -> None:
+        addrs = list(range(nodes))
+        cluster = [RaftNode(world, a, [p for p in addrs if p != a], buggy=buggy) for a in addrs]
+        for node in cluster:
+            world.start(node)
+        world.always(
+            lambda: at_most_one_leader_per_term(cluster), name="at-most-one-leader-per-term"
+        )
+        await asyncio.sleep(seconds)  # let elections run; the invariant is checked each step
+
+    return scenario
+
+
+def find_split_brain(seeds: int = 200) -> int | None:
+    """Sweep the buggy election for a seed that violates election safety; None if none found."""
+    result = seedloop.check(election_scenario(buggy=True), seeds=seeds, on_failure="return")
+    return result.failing_seed
+
+
+def main() -> None:
+    print("seedloop Raft election demo - hunting for split-brain\n")
+    seed = find_split_brain()
+    if seed is None:
+        print("no split-brain found in the swept seeds (try more seeds)")
+        sys.exit(1)  # the proof did not reproduce — fail loudly (CI runs this)
+    print(f"buggy election: split-brain found at seed={seed}")
+    print(f"  reproduce it:  seedloop.replay(election_scenario(buggy=True), seed={seed})")
+    try:
+        seedloop.replay(election_scenario(buggy=True), seed=seed)
+    except seedloop.InvariantError as exc:
+        print(f"  replay reproduces it: {exc}")
+    clean = seedloop.check(election_scenario(buggy=False), seeds=200, on_failure="return")
+    verdict = (
+        "no violation" if clean.failing_seed is None else f"FAILED at seed={clean.failing_seed}"
+    )
+    print(f"\ncorrect election (single-vote rule enforced): {verdict} over the same 200 seeds")
+    print("-> the violation is the toggled flaw, not the harness.")
+
+
+if __name__ == "__main__":
+    main()

seedloop/errors.py

@@ -0,0 +1,57 @@
+"""Exceptions seedloop raises.
+
+One specific exception per failure mode; nothing is swallowed. The hierarchy is rooted at
+``SeedloopError`` so everything seedloop raises can be caught with a single class.
+"""
+
+from __future__ import annotations
+
+
+class SeedloopError(Exception):
+    """Base class for every error seedloop raises."""
+
+
+class BoundaryError(SeedloopError):
+    """A simulated run reached outside the determinism boundary.
+
+    Real threads, ``run_in_executor``, subprocesses, real sockets, and cross-thread wakeups
+    cannot be made deterministic, so they are rejected rather than run silently (``docs/scope.md``).
+    """
+
+
+class DeadlockError(SeedloopError):
+    """The run cannot progress and nothing is scheduled to wake it.
+
+    A real ``asyncio`` program would hang here; a simulated run raises instead of spinning, so
+    the deadlock is a visible failure tied to the seed that produced it.
+    """
+
+
+class InvariantError(SeedloopError):
+    """An ``always(...)`` invariant was violated during a run.
+
+    A continuous safety property (e.g. "at most one leader") that must hold throughout, checked
+    after every step; the first step where it is false raises this, which ``check`` reports as the
+    failure. Carries the invariant's ``name`` and the virtual ``time`` of the violation.
+    """
+
+    def __init__(self, name: str, time: float) -> None:
+        super().__init__(f"invariant {name!r} violated at t={time}")
+        self.name = name
+        self.time = time
+
+
+class EntropyLeakError(BoundaryError):
+    """An uncontrolled entropy source was touched inside a simulated run.
+
+    In audit mode the non-determinism auditor raises this when code reaches for real
+    ``os.urandom``/``secrets``, real time, or the unseeded global ``random`` instead of the World's
+    seeded source (``docs/decisions.md`` ADR-0008). Carries the offending ``source``.
+    """
+
+    def __init__(self, source: str) -> None:
+        super().__init__(
+            f"uncontrolled entropy source {source!r} used inside a run; route it through the seed "
+            f"(world.rng) or the virtual clock — see docs/scope.md"
+        )
+        self.source = source

seedloop-0.3.0.dist-info/METADATA

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: seedloop
+Version: 0.3.0
+Summary: Deterministic simulation testing for Python asyncio.
+Author-email: Vojtěch Klíma <vojtechklima02@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/klimavojtech2002/seedloop
+Project-URL: Repository, https://github.com/klimavojtech2002/seedloop
+Project-URL: Issues, https://github.com/klimavojtech2002/seedloop/issues
+Project-URL: Changelog, https://github.com/klimavojtech2002/seedloop/blob/main/CHANGELOG.md
+Keywords: asyncio,testing,determinism,simulation,concurrency
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-timeout>=2; extra == "dev"
+Dynamic: license-file
+
+# seedloop
+
+Deterministic simulation testing for Python. Run your concurrent async logic through thousands of
+controlled, reproducible timelines — varying message timing and delivery order, injecting network
+faults, partitions, and delays — to surface the rare concurrency bug that shows up once in a million
+runs, and replay it exactly from a seed.
+
+It brings the FoundationDB / TigerBeetle / Antithesis style of reliability testing — until now living
+only in Rust, C++, and Java — to Python's `asyncio`, as a `pip`-installable library.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+## The problem
+
+Concurrency bugs are the worst bugs. A protocol or state machine works in every test, then once a
+week in CI a test fails, and nobody can reproduce it — because the failure depended on an exact
+interleaving of events, a message arriving late, a partition healing at the wrong moment. You cannot
+fix what you cannot reproduce, so these bugs are patched by guesswork and survive for years.
+
+Deterministic simulation testing (DST) inverts this. It takes total control of every source of
+nondeterminism — scheduling order, time, randomness, the network — and drives them all from a single
+seed. The same seed produces the same timeline, so the same bug, every time. You explore thousands of
+seeds to hunt for failures, and when one is found, the seed *is* the reproduction: replay it and the
+bug happens again, deterministically, every run.
+
+This is how FoundationDB reached its reliability record. It exists as a polished library in Rust
+(`madsim`, `turmoil`). In Python — where a great deal of distributed and protocol code is written — it
+does not exist at all. `seedloop` is that library.
+
+## What you do with it
+
+You write your protocol or algorithm against an abstract transport (the
+[sans-I/O](https://sans-io.readthedocs.io/) style), and `seedloop` runs it inside a deterministic
+world it fully controls. A test looks like this (`World`, `check`, `replay`, the network `world.net`
+with loss/duplication/partitions, the `world.always` invariant API, and the `audit=True`
+non-determinism auditor are all implemented; the seed-scheduled `world.run_for` fault schedule is the
+next phase, specified in [docs/api.md](docs/api.md)):
+
+```python
+import seedloop
+
+async def scenario(world: seedloop.World) -> None:
+    # Spin up your nodes; they send messages through the simulated network.
+    nodes = [RaftNode(addr, world.net) for addr in range(5)]
+    world.start(*nodes)
+
+    # State the invariant that must hold at every step, not just at the end.
+    world.always(lambda: at_most_one_leader(nodes), name="at-most-one-leader")
+
+    # Inject chaos the seed decides the details of.
+    await world.run_for(seconds=10, faults=[world.partition(), world.slow_link()])
+
+# Hunt across 10,000 seeded timelines; on failure, print the seed.
+seedloop.check(scenario, seeds=10_000)
+# A failing run prints:  seed=4823  → replay with seedloop.replay(scenario, seed=4823)
+```
+
+`seedloop.replay(scenario, seed=4823)` re-runs that exact timeline, deterministically, as many times
+as you need to debug it. The full API is in [docs/api.md](docs/api.md).
+
+## The worked proof: a Raft split-brain, found and replayed
+
+A small Raft leader election ships as a demo. With a deliberate, labelled flaw — a node that omits the
+single-vote-per-term rule — a seed sweep finds the timing where two nodes both win an election in the
+same term (split-brain), and replays it from the seed. The corrected election passes the same sweep, so
+the violation is the toggled flaw, not the harness: in a three-node cluster the shared third voter can
+only break the tie once under the single-vote rule, so one candidate gets two votes and the other one —
+never two leaders.
+
+```
+$ python -m seedloop.demos.raft
+seedloop Raft election demo - hunting for split-brain
+
+buggy election: split-brain found at seed=7
+  reproduce it:  seedloop.replay(election_scenario(buggy=True), seed=7)
+  replay reproduces it: invariant 'at-most-one-leader-per-term' violated at t=0.229...
+correct election (single-vote rule enforced): no violation over the same 200 seeds
+-> the violation is the toggled flaw, not the harness.
+```
+
+The election logic is in [`src/seedloop/demos/raft.py`](src/seedloop/demos/raft.py). It is election only
+(terms, `RequestVote`, majority, heartbeats) — log replication, persistence, and membership changes are
+out of scope.
+
+## What it does
+
+- A **deterministic event loop** that makes `asyncio` task scheduling reproducible and drives the I/O
+  seam — where nondeterminism actually enters — from the seed.
+- A **virtual clock** — `sleep` and timeouts advance simulated time instantly; no run is slower for
+  testing a 10-second scenario.
+- **Seeded randomness** everywhere, so a run is a pure function of its seed.
+- A **simulated network** with seeded latency, reordering, message loss, and partitions.
+- **Fault injection** driven by the seed, so chaos is reproducible rather than random.
+- **Invariants** — `world.always(...)` checks a continuous safety property at every step.
+- A **non-determinism auditor** — `audit=True` turns any uncontrolled entropy source into a loud,
+  reproducible failure, so the determinism boundary is enforced, not just stated.
+- **Seed replay** — the whole point: any failure reduces to a single integer you can replay forever.
+
+## Scope — what it tests, and what it deliberately does not
+
+The honesty in this section is the point. `seedloop` makes your async *logic* deterministic; it does
+not make your *infrastructure* deterministic, and it does not pretend to. The full boundary, and the engineering reasons behind it, are in
+[docs/scope.md](docs/scope.md). In short:
+
+- **It is for** pure-Python async code that talks to an abstract transport: consensus (Raft/Paxos),
+  replication, gossip, CRDTs, custom wire protocols, schedulers, retry/backoff/circuit-breaker logic,
+  rate limiters — code where the *logic* holds the concurrency bugs.
+- **It is not for** I/O-heavy applications bound to real drivers. Real threads, `multiprocessing`,
+  `uvloop`, and C-extension drivers (`asyncpg`, `grpcio`) are explicitly out of scope, because their
+  scheduling cannot be controlled from Python — the same wall that stops deterministic testing in Go.
+  `seedloop` tests your algorithm, not your database driver.
+
+Choosing this boundary deliberately — rather than promising determinism it cannot deliver — is what
+keeps the guarantee real.
+
+## Status
+
+The planned build is **complete through v0.3.0**: the deterministic core (custom event loop, virtual
+clock with autojump, seeded entropy, the `World` / `check` / `replay` API), the simulated network with
+fault injection (loss, duplication, partitions), the `world.always` invariant API, the non-determinism
+auditor (`audit=True`), and the worked Raft demo (which runs today) — so `asyncio` runs are reproducible
+and instant, a partition- or timing-dependent bug replays identically from its seed, and an uncontrolled
+entropy source fails loudly under audit. Deferred: the seed-scheduled `world.run_for` fault schedule and
+an optional Hypothesis integration (`seedloop[hypothesis]`). The full API target is in
+[docs/api.md](docs/api.md) and the phased build in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+
+## Why it exists
+
+There is no `pip`-installable deterministic simulation testing framework for Python `asyncio` — the
+capability lives in Rust (`madsim`, `turmoil`), C++ (FoundationDB), Java (OpenDST), and behind a
+commercial hypervisor (Antithesis), but not in Python. Meanwhile the discipline is rising fast among
+serious engineers (Antithesis raised a $105M round led by Jane Street to standardize DST; AWS has
+codified deterministic and formal methods as standing practice). As one of its proponents puts it:
+*writing code is no longer the bottleneck — making sure it does the right thing is.* `seedloop` is a
+tool for exactly that, in the language that lacked it.
+
+## Documentation
+
+The design is specified before the code:
+
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — how `asyncio` is made deterministic, and the phased build.
+- [docs/api.md](docs/api.md) — the public API: `World`, `check`/`replay`, the transport, faults.
+- [docs/internals.md](docs/internals.md) — the loop, virtual clock, entropy control, network and fault scheduling.
+- [docs/network.md](docs/network.md) — the simulated transport and fault model.
+- [docs/scope.md](docs/scope.md) — the determinism boundary: what is controlled and what is not.
+- [docs/testing.md](docs/testing.md) — how determinism is proven by replay.
+- [docs/decisions.md](docs/decisions.md) — the decision records (ADRs).
+- [docs/glossary.md](docs/glossary.md) — the vocabulary.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

seedloop-0.3.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+seedloop/__init__.py,sha256=v0u4D7SHFXW-Jo_FGEJbr9GhtXy4jhtOLwW8QvIQDhM,1191
+seedloop/_audit.py,sha256=FH0go-ybFodw1h3AIr3IRim3kPUPMAc-U2KFC0z6P0o,4517
+seedloop/_entropy.py,sha256=4ZZfXN4HsZ9EiZ3024-zxjvbXR2XWaxQxqT2MQEXGP8,4499
+seedloop/_loop.py,sha256=UT0lh6lawusSogsmXvAJ52AwG7tK0W0OYizGpt3rZ-s,7885
+seedloop/_net.py,sha256=GqywpytBmLuPLtpB8KJpCbotYsl-OLXnjNkt0LFKwg0,7979
+seedloop/_run.py,sha256=OPZQgCN5f9IG4xN_E616s_YhP0UAn2M7dSVvpePx31c,3911
+seedloop/_trace.py,sha256=TEfJGP0E5M5Y1L-MEvPOsBb6QR3moZH49z5CloMOmkk,921
+seedloop/_world.py,sha256=Pn9mTP4yu8PsmhX6hdIPwuknjJsyd_dsUJZBBXn9qHM,5253
+seedloop/errors.py,sha256=absRq_4jWgzLlxIOBcJwMGYenlldml2p3maJVGwYbfI,2168
+seedloop/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+seedloop/demos/__init__.py,sha256=7ux1hd1HRarZjNPHN3cELwwBXo7dHR-NTuCkKOVMdEs,59
+seedloop/demos/raft.py,sha256=FUl06jOu-8axF4nplkOmZCZZEaW01O4UqN6ZpKPnS10,7520
+seedloop-0.3.0.dist-info/licenses/LICENSE,sha256=bq78RJMIno1EDrCmF4-Q6E8TqWGPk12dM1yauYtEGqM,1072
+seedloop-0.3.0.dist-info/METADATA,sha256=A4-L13cM1e35LrMNKYK5hKA_uIvEis9jRIDJrB1HAlg,10201
+seedloop-0.3.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+seedloop-0.3.0.dist-info/top_level.txt,sha256=CDWSLLQIpYsE2ds0ATOpEYX_eQUGUjng4tE8l2sO9MA,9
+seedloop-0.3.0.dist-info/RECORD,,

seedloop-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

seedloop-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vojtěch Klíma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

seedloop-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+seedloop