seedloop 0.3.0__tar.gz

seedloop-0.3.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,152 @@
+# 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/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "seedloop"
+description = "Deterministic simulation testing for Python asyncio."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Vojtěch Klíma", email = "vojtechklima02@gmail.com" }]
+keywords = ["asyncio", "testing", "determinism", "simulation", "concurrency"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Testing",
+    "Typing :: Typed",
+]
+dynamic = ["version"]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/klimavojtech2002/seedloop"
+Repository = "https://github.com/klimavojtech2002/seedloop"
+Issues = "https://github.com/klimavojtech2002/seedloop/issues"
+Changelog = "https://github.com/klimavojtech2002/seedloop/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+dev = ["ruff>=0.6", "mypy>=1.10", "pytest>=8", "pytest-timeout>=2"]
+
+[tool.setuptools.dynamic]
+version = { attr = "seedloop.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+files = ["src", "tests"]
+exclude = ['(^|/)(\.venv|build|dist|\.eggs)/']
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+# A simulated run can livelock on a loop bug; cap every test so a hang fails fast instead of
+# blocking CI. The suite otherwise runs in virtual time and finishes in milliseconds.
+timeout = 30

seedloop-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

seedloop-0.3.0/src/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-0.3.0/src/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-0.3.0/src/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)