Mandip Adhikari
← Index
ProjectJun 2026 — Jul 2026

simloom

simloom swaps asyncio's event loop for a deterministic one, so real async code runs under a seeded scheduler, a virtual clock and a fault-injecting in-memory network. Any failure replays exactly from one seed, and shrinks to the smallest schedule that still breaks.

pip install simloom

Python 3.12 · asyncio · pytest plugin · PyPI · uv

0.5.0 on PyPI · Python 3.12+ · Apache-2.0

10,000
seeds in the CI determinism job
377
test functions
0
runtime dependencies

Why asyncio fits

Every interleaving decision in asyncio happens at an await, under a replaceable event loop. Libraries like aiohttp and redis-py bottom out in loop primitives, so they run inside the simulation unchanged — no forked interpreter, no hypervisor.

CI runs an unmodified aiohttp HTTPS server and client over an in-sim TLS handshake, and redis.asyncio against an in-sim Redis.

One tape, one universe

All nondeterminism comes from a single choice tape: which ready callback runs next, whether a packet drops, how long a link delays. Each decision is a bounded integer draw. The idea is borrowed from Hypothesis's choice sequence, and there is deliberately no second source of randomness.

The loop only consumes a draw when more than one callback is ready. When nothing is ready, the clock jumps straight to the next timer — a simulated hour runs in milliseconds.

        seed
         │
         ▼
┌──────────────┐ draws ┌──────────────────────────────┐
│ choice tape  │◀─────▶│ SimLoop                      │
│              │       │ callback pick · virtual time │
└──────┬───────┘       │ SimNetwork · fault injection │
       │               └──────────────┬───────────────┘
       │                              │ unmodified asyncio code
       │ recorded tape                ▼
       │               oracles: always · eventually ·
       │               serializable · linearizable
       ▼                              │ failure
   replay() ◀──── shrink ◀────────────┘

Search and checking

Search can be a random walk, auto-tuned PCT, or systematic mode — a stateless model checker that enumerates delay-bounded schedules, so a pass is a bounded proof rather than a lucky run.

Oracles go beyond crashes: always/eventually monitors, an Elle-style serializability checker, and a Wing–Gong linearizability checker with Lowe's memoisation that catches stale reads serializability would allow.

Shrinking, and a real CPython bug

The shrinker minimises in shortlex order and re-records every accepted candidate. For schedules it minimises the number of non-FIFO picks — the number a reader actually cares about when reading a failing trace.

examples/bpo42130.py vendors the pre-3.12 asyncio.wait_for and recovers bpo-42130, the race where a cancellation was silently swallowed. The modern stdlib survives the same exploration. CI replays 10,000 seeds twice each and requires the event-log hashes to match.