simloom 0.1.0__tar.gz → 0.2.0__tar.gz

{simloom-0.1.0 → simloom-0.2.0}/.gitignore

@@ -20,3 +20,9 @@ BRIEF.md
 
 # OS
 .DS_Store
+
+# Local pre-publication upstream bug drafts — never ship in the package/repo
+reports/
+
+# internal roadmap, never tracked
+docs/roadmap-100x.md

simloom-0.2.0/CHANGELOG.md

@@ -0,0 +1,185 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-06-25
+
+### Added
+- **Phase L — stand-in services: sim-redis.** `world.run_service(SimRedis(),
+  host=, port=)` starts an in-sim RESP server an *unmodified* `redis.asyncio.Redis`
+  client speaks to — SET/GET/DEL/EXISTS/INCR(BY)/DECR(BY) and the
+  WATCH/MULTI/EXEC optimistic-locking transaction (a watched key changing aborts
+  the EXEC). It runs as an ordinary in-sim server, so `world.net` faults apply to
+  the wire: a planted connection reset surfaces to the client as a deterministic,
+  replayable `ConnectionError`. The roadmap's final phase — simloom now tests your
+  logic against a fault-injected dependency with nothing to stand up.
+- **Phase K — consistency checking (finds *wrong answers*, not just crashes).**
+  An Elle-style list-append serializability checker: `world.history` records
+  append/read transactions, `world.check_serializable()` / `assert_serializable()`
+  recover each key's version order from the reads, build the ww/wr/rw dependency
+  graph, and report any cycle (the shortest, so a lost update is a minimal
+  two-step rw cycle) as a `ConsistencyViolation`. A store with a non-atomic
+  read-modify-write is caught under the schedules that lose an update; a locked
+  store always passes; the violation shrinks to the minimal cycle.
+- **Phase J (2,3/3) — the `simloom` trace/diff CLI + `observe`.** A causal log
+  (`run(..., causal=True)`, `result.log.write_to(path)`) is consumed by:
+  `simloom trace LOG --step N` (reconstruct state at any step with its causal
+  stack back to a root), `--grep REGEX` / `--changed NAME` (omniscient queries —
+  the latter returns exactly the steps where an `observe`-d value changed), and
+  `simloom diff A B` (first diverging event between two universes, with a cause
+  classification). `simloom.observe(name, value)` is a no-op outside causal mode
+  (zero digest impact).
+- **Phase J (1/3) — causal event log v2.** Opt-in `causal=True` annotates every
+  `step` with *why it woke*: `woke_by` (the earlier step that scheduled the
+  callback now running — the happens-before edge) and `via` (`timer` vs `soon`).
+  Off by default, so the hot path and the digest are unchanged. The edges
+  satisfy an independent happens-before oracle: causes precede effects, every
+  step traces to a root, and an immediate (`soon`) wakeup runs at the same
+  virtual instant as its cause while a `timer` wakeup runs at or after it.
+- **Phase I (5/5) — TLS in the simulation.** `create_connection(ssl=)` /
+  `create_server(ssl=)` now wrap each protocol in asyncio's own memory-BIO
+  `SSLProtocol` over `SimTransport`, so the handshake runs in-process over the
+  simulated wire. The run is deterministic and replays byte-for-byte even though
+  OpenSSL's RNG is unseeded (the event log records scheduling, not ciphertext).
+  `SimTransport` gained `BufferedProtocol` support (`get_buffer`/`buffer_updated`)
+  to drive SSL, and `loop.sock_connect` + `create_connection(sock=)` are
+  simulated for happy-eyeballs clients. **Gate met:** an unmodified aiohttp HTTPS
+  client hits an unmodified aiohttp HTTPS server in-sim over a pinned cert,
+  replayable byte-for-byte (status 200, deterministic on 3.12/3.13/3.14).
+- **Phase I (4/5) — per-link / per-node shaping.** `world.net.set_link_latency`
+  and `set_link_loss` shape a single directional link (real links are
+  asymmetric); `clog_node_out` / `clog_node_in` shape a node's whole egress /
+  ingress. Precedence: explicit link > node egress > node ingress > global, and
+  the no-override path is byte-identical (the determinism torture is unchanged).
+- **Phase I (3/5) — datagram (UDP) transport.** `loop.create_datagram_endpoint`
+  is now simulated: `SimDatagramTransport` delivers in order and exactly once by
+  default, but `world.net.set_datagram_loss/duplication/reorder(percent)` inject
+  the real UDP faults — packets genuinely dropped, duplicated, or overtaken
+  (every fate a tape draw, so it replays). A naive client that assumes in-order
+  exactly-once delivery is found buggy under faults; a correct one survives.
+- **Phase I (2/5) — world-on-by-default.** A `World` is now attached for every
+  run (network simulated) regardless of whether `main` takes a `world`
+  parameter — killing the arity trap where `async def main():` + a network call
+  produced a confusing escape. Pass `world=False` to restore escape-on-real-
+  network (with an accurate message, not the stale "Phase B" one). `SimServer`
+  gained `async with` / `serve_forever` / blocking `wait_closed` for fidelity.
+- **Phase I (1/5) — `connected_pair`.** `world.connected_pair(client_factory,
+  server_factory)` drives any two `asyncio.Protocol`s against each other over a
+  two-sided simulated connection — no listener, no hand-written stub transport.
+  Both `connection_made` callbacks run before it returns, and the pair carries
+  `world.net` faults (latency/loss/partition/reset) like a real connection.
+  `create_connection` is refactored onto it (behaviour byte-identical).
+- **Systematic deep search — a stateless model checker over the choice tape.**
+  `simloom.explore_systematic(main, max_delays=2)` enumerates every distinct
+  interleaving within a *delay bound* exactly once (a mixed-radix odometer over
+  the tape, reusing FALLBACK replay). Two things random walk and PCT cannot do:
+  it finds a bug needing a specific non-default interleaving *deterministically*
+  (e.g. a check-then-set race the default schedule never hits), and it *proves
+  correctness* — `result.proven_correct` is True when it exhausts the space with
+  no failure. Delay bounding (Emmi/Qadeer/Rakamarić) keeps it tractable without
+  the happens-before tracking full partial-order reduction needs; found failures
+  replay and shrink like any tape. Available as `@simloom.test(systematic=True,
+  max_delays=2)` — bounded verification as an ordinary pytest test: the test
+  passes as a proof up to the bound, or fails deterministically with a shrunk,
+  replayable witness interleaving.
+- **Phase H (3/3) — soak testing.** `simloom.soak(main, count=, shards=, shard=,
+  checkpoint=)` runs continuous, shardable, resumable exploration. Sharding is by
+  stride, so shards are disjoint and complete by construction; the checkpoint
+  records each shard's cursor (atomic write), so a killed soak resumes from its
+  next unrun seed — none skipped, none repeated.
+- **Phase H (2/4) — interleaving fingerprints + regression corpus.**
+  `interleaving_edges`/`fingerprint` summarise a run by its `(prev_callback,
+  callback)` step edges; `InterleavingCorpus` accumulates the global edge set
+  and keeps the tapes that first reached new edges. This is the feedback
+  substrate for coverage-guided search: sparse novelty (most runs add no edges)
+  is the steering signal.
+- **Phase H (1/4) — PCT auto-horizon.** `scheduler="pct:auto"` measures the
+  scheduling horizon `k` from a probe run instead of the broken `k=4096`
+  default (whose change points land past a small test's end and never fire,
+  degrading PCT to a fixed priority schedule). pct:auto finds the
+  ordering/starvation bugs the default misses; the resolved descriptor is
+  concrete and replayable.
+- **Phase G (1/2) — the determinism boundary.** Opt-in `virtual_time=True`
+  redirects `time.time`/`monotonic`/`perf_counter` (+`_ns`) to the virtual
+  clock; `seed_randomness=True` seeds the global `random`, `os.urandom`,
+  `secrets`/`SystemRandom`, and `uuid.uuid4` from one tape draw. Both default
+  ON under `@simloom.test` and are always restored (even on a crashed run).
+  An unmodified asyncio library that reads the clock and rolls randomness now
+  replays byte-for-byte.
+- **Phase G (2/2) — per-test determinism self-check.** `run(check_determinism=
+  True)` / `@simloom.test(check_determinism=True)` / `pytest --simloom-check-
+  determinism` run a seed twice and raise `SimloomNondeterminismError` locating
+  the first diverging event if the two universes differ — catching
+  nondeterminism the tape cannot control (identity-ordered iteration, a stray
+  real clock/RNG, threads doing real work).
+- **Phase G (3/3) — boundary registry + PYTHONHASHSEED auto-pin.**
+  `simloom.boundary()` is a machine-readable table of every real-world API and
+  what simloom does there (detected / simulated / patched / documented); a test
+  cross-checks it against the actual escape sites so the honesty contract cannot
+  drift. `simloom.pin_hashseed()` (and `pytest --simloom-pin-hashseed`) re-execs
+  with `PYTHONHASHSEED=0` if unpinned, so cross-process seed/tape replay is sound.
+- **Phase F — property monitors (oracles).** `world.always` / `world.eventually`
+  / `world.leads_to` (and module-level `simloom.always`/`eventually`/`leads_to`)
+  assert safety and liveness properties over the deterministic step sequence;
+  `world.assert_converged` checks replica equality. A new livelock oracle
+  (`SimLivelockError`) catches busy-but-stuck spins the deadlock oracle cannot
+  see. Violations surface as `InvariantViolation` and are found/shrunk/replayed
+  like any failure. Passing monitors are zero-perturbation (byte-identical
+  digest); liveness deadlines fire at exactly their virtual time and never mask
+  a `SimDeadlockError`. This turns simloom from "finds crashes" into "finds
+  wrong and stuck behaviour."
+
+## [0.1.0] - 2026-06-13
+
+First public release. The deterministic core, simulated world, fault matrix,
+explorer, shrinker, and pytest plugin are all present and exercised by a
+10,000-seed determinism torture in CI.
+
+### Added
+- Project scaffold: `src/` layout, strict mypy, ruff, pytest + hypothesis, CI.
+- Phase 0 feasibility spikes under `spikes/`.
+- **Phase A core**: the choice tape (`Tape`, labeled bounded draws, strict/fallback
+  replay, versioned JSON serialization), the deterministic event loop (`SimLoop`)
+  with virtual time, loop-owned task naming, escape detection
+  (`EscapedSimulationError`), deadlock reporting (`SimDeadlockError`), controlled
+  GC, and deterministic teardown; `run()`/`replay()` entry points returning
+  `RunResult` with a sha256 universe digest; event log format v1
+  (`docs/event-log.md`); honesty doc (`docs/determinism.md`); 10,000-seed
+  determinism-torture CI job.
+- **Phase B world**: simulated network behind the loop primitives (in-memory
+  transports with FIFO stream guarantees, `SimServer`, strict `SimDNS`, tape-driven
+  latency and loss-as-retransmission-delay), `World`/`Host` with power-cut crash
+  semantics and entry-factory restart, `SimDisk` with honest fsync. Gate: unmodified
+  aiohttp + httpx exchanging requests over the lossy simulated network, replayable
+  byte-for-byte (`tests/test_world_http.py`).
+- **Phase C faults + buggify**: partition/heal (hold-and-release, streams never
+  corrupt), asymmetric block, connection-reset injection, partition-aware connects,
+  torn/lost/flushed unsynced writes on crash; `simloom.sometimes`/`draw`/`reached`
+  with `RunResult.coverage`. Gate: the toy Raft torture suite
+  (`tests/test_raft_demo.py`) catches a planted double-vote bug via exploration and
+  replays it exactly; the correct implementation survives.
+- **Phase D explorer + shrinker**: `simloom.explore` (random walk or PCT scheduling,
+  serial or multiprocess, failure corpus + coverage union), `simloom.shrink`
+  (deviations-first greedy minimization with re-recorded candidates and zero-refill
+  fallback; human-readable `describe()`), `PCT`/`RandomWalk` strategies with
+  replay-matched recording. Gate: the benchmark bug zoo measures find rates — PCT
+  finds the starvation-class bug a random walk never does (0 vs 151 of 400 seeds),
+  and random dominates shallow races; both results asserted in CI.
+- **Phase E pytest plugin**: `@simloom.test(runs=N)` turns an async test into a
+  seed-exploring simulation test — failures are shrunk, written to `.sim/failures/`
+  as replayable artifacts, and reported with seed + re-run command + minimal
+  schedule. Options: `--simloom-seed`, `--simloom-runs`, `--simloom-tape`,
+  `--simloom-no-shrink`; `require_coverage` for per-test sometimes-assertions.
+- **Examples + demo #4**: `examples/toy_raft.py` (runnable) and
+  `examples/bpo42130.py` — the historical `asyncio.wait_for` cancellation-swallowing
+  race (bpo-42130) reproduced deterministically from a seed; the modern stdlib
+  survives the identical torture. Launch-post draft in `docs/launch-post.md`.
+
+[Unreleased]: https://github.com/mandipadk/simloom/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/mandipadk/simloom/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/mandipadk/simloom/releases/tag/v0.1.0

{simloom-0.1.0 → simloom-0.2.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: simloom
-Version: 0.1.0
-Summary: Deterministic simulation testing for asyncio: seeded schedules, fault injection, perfect replay.
+Version: 0.2.0
+Summary: Deterministic simulation testing for asyncio: explore every schedule, inject faults, assert properties, prove correctness, and replay any failure from a seed.
 Project-URL: Homepage, https://github.com/mandipadk/simloom
 Project-URL: Repository, https://github.com/mandipadk/simloom
 Project-URL: Documentation, https://github.com/mandipadk/simloom/tree/main/docs
@@ -10,8 +10,8 @@ Project-URL: Issues, https://github.com/mandipadk/simloom/issues
 Author: Mandip Adhikari
 License-Expression: Apache-2.0
 License-File: LICENSE
-Keywords: asyncio,concurrency,deterministic,fault-injection,simulation,testing
-Classifier: Development Status :: 2 - Pre-Alpha
+Keywords: asyncio,chaos-engineering,concurrency,deterministic,fault-injection,model-checking,property-testing,serializability,simulation,testing
+Classifier: Development Status :: 3 - Alpha
 Classifier: Framework :: AsyncIO
 Classifier: Framework :: Pytest
 Classifier: Intended Audience :: Developers
@@ -30,6 +30,7 @@ Requires-Dist: ruff>=0.9; extra == 'dev'
 Provides-Extra: spikes
 Requires-Dist: aiohttp>=3.11; extra == 'spikes'
 Requires-Dist: httpx>=0.28; extra == 'spikes'
+Requires-Dist: redis>=5.0; extra == 'spikes'
 Description-Content-Type: text/markdown
 
 <h1 align="center">simloom</h1>
@@ -56,9 +57,13 @@ state of the art.
 **simloom runs your unmodified asyncio program inside a fully simulated world** — a
 seeded scheduler that owns every interleaving, a virtual clock, an in-memory network
 with injectable latency, loss, partitions, and crashes — and explores thousands of
-hostile schedules looking for the one that breaks your invariants. When it finds one,
-it hands you a **seed** that replays the failure byte-for-byte, forever, and **shrinks**
-it to the minimal schedule that still triggers the bug.
+hostile schedules looking for the one that breaks your invariants. It doesn't just find
+crashes: it asserts **safety and liveness** properties, **proves** correctness by
+exhaustive systematic search, and catches **wrong answers** (a store that returns a stale
+or impossible read) with serializability checking. When it finds a problem, it hands you a
+**seed** that replays the failure byte-for-byte, forever, **shrinks** it to the minimal
+schedule that still triggers the bug, and lets you **walk the causal trace** of what woke
+what.
 
 ```text
 FAILED test_lease_exclusivity — simloom found a failing universe
@@ -126,6 +131,37 @@ async def test_leader_election(world):
     await world.until(lambda: exactly_one_leader(nodes), timeout=120)
 ```
 
+### Beyond crashes
+
+Assert what *should* hold, prove it can't be violated, and catch wrong answers:
+
+```python
+@simloom.test(runs=5000)
+async def test_lease_safety(world):
+    cluster = start_cluster(world)
+    # safety: never two leaders. liveness: one eventually emerges.
+    world.always("≤1 leader", lambda: sum(n.is_leader for n in cluster) <= 1)
+    world.eventually("a leader", lambda: any(n.is_leader for n in cluster), within=120)
+    await world.sleep(300)
+
+@simloom.test(systematic=True, max_delays=3)     # exhaustive, not sampled
+async def test_critical_section():
+    ...                                          # passes ⇒ a bounded PROOF of correctness
+
+@simloom.test(runs=5000)
+async def test_store_is_serializable(world):
+    await run_transactions(world)                # records ops into world.history
+    world.assert_serializable()                  # finds lost updates / write skew, with the cycle
+```
+
+And once it finds something, replay and walk it:
+
+```sh
+pytest --simloom-seed=17 -k lease          # replay the exact failing universe
+simloom trace failure.jsonl --step 42      # reconstruct state + the happens-before stack
+simloom diff run_a.jsonl run_b.jsonl       # first divergence between two universes
+```
+
 ## Why this didn't exist before
 
 Rust has [`loom`](https://github.com/tokio-rs/loom),
@@ -140,32 +176,62 @@ had **nothing**.
 And asyncio is *structurally perfect* for it: every interleaving decision happens at an
 `await`, under a **replaceable event loop**. simloom swaps in a deterministic one — no
 forked interpreter, no hypervisor, no recompilation. Because the ecosystem (aiohttp,
-httpx, the streams API) bottoms out in loop primitives, **real, unmodified libraries run
-inside the simulation**. Our CI runs a genuine aiohttp server against a genuine httpx
-client over the simulated network, with 20% packet loss injected, replayable from a seed.
+httpx, redis, the streams API) bottoms out in loop primitives, **real, unmodified
+libraries run inside the simulation**. Our CI runs an unmodified **aiohttp HTTPS** server
+against an unmodified aiohttp client over a memory-BIO TLS handshake, and an unmodified
+**`redis.asyncio.Redis`** against an in-sim Redis — all over the simulated network, with
+faults injected, replayable byte-for-byte from a seed.
 
 ## What you get
 
-- **🎲 Seeded, exhaustive-ish scheduling** — a single *choice tape* (the Hypothesis
-  trick, applied to schedules) drives every decision. One seed → one exact universe.
-- **⏱ Virtual time** — an hour of simulated `asyncio.sleep` traffic runs in
-  milliseconds. Timeouts and retries are tested at full speed.
-- **🌐 A simulated network** — in-memory transports with tape-driven latency, loss
-  (modeled as TCP retransmit delay — streams never corrupt), partitions, asymmetric
-  blocks, and connection resets.
-- **💥 Honest crashes** — `host.crash()` is a power cut: tasks stop with no `finally`
-  blocks, unsynced disk writes are lost or *torn*, peers see resets. `restart()` brings
-  the host back against its surviving fsynced state.
-- **🔬 Fault injection in your code** — `simloom.sometimes("drop_cache")` is tape-driven
-  inside the sim and a constant `False` in production. Annotate rare branches; explore
-  them.
+**Run it.** Your real asyncio code, unchanged, inside the simulation.
+
+- **🎲 Seeded scheduling** — a single *choice tape* (the Hypothesis trick, applied to
+  schedules) drives every decision. One seed → one exact universe.
+- **⏱ Virtual time** — an hour of simulated `asyncio.sleep` traffic runs in milliseconds;
+  opt-in patching makes `time.time()` and the stdlib RNG tape-driven too, so an unmodified
+  library that timestamps or rolls a random timeout replays byte-for-byte.
+- **🌐 A simulated network** — in-memory streams (loss modeled as TCP retransmit delay —
+  bytes never corrupt), **UDP datagrams** with real loss/reorder/duplication,
+  partitions, asymmetric per-link latency/loss shaping, resets, and **TLS in-sim**
+  (memory-BIO SSL, so aiohttp HTTPS just works).
+- **💥 Honest crashes & disk** — `host.crash()` is a power cut: tasks stop with no
+  `finally` blocks, unsynced disk writes are lost or *torn*, peers see resets.
+- **🧩 Stand-in services** — `world.run_service(SimRedis(), …)` gives you an in-sim Redis
+  (SET/GET, WATCH/MULTI/EXEC) to test your logic against, with wire faults applied.
+
+**Break it.** Explore the schedules and faults your laptop never will.
+
+- **🔬 Fault injection** — `simloom.sometimes("drop_cache")` is tape-driven inside the sim
+  and a constant `False` in production. Annotate rare branches; explore them.
+- **🧭 Pluggable search** — uniform random walk, **`pct:auto`** (auto-tuned
+  [Probabilistic Concurrency Testing](https://www.microsoft.com/en-us/research/publication/a-randomized-scheduler-with-probabilistic-guarantees-of-finding-bugs/)
+  that finds deep-ordering and starvation bugs random walk never hits), and `simloom.soak`
+  (resumable, shardable continuous exploration).
+
+**Check it.** Assertions far past "didn't crash."
+
+- **🛡 Safety & liveness oracles** — `world.always("one leader", …)`,
+  `world.eventually("elects a leader", …, within=120)`, `world.leads_to(…)`, plus a
+  livelock detector and replica-convergence checks.
+- **✅ Prove it** — `@simloom.test(systematic=True)` switches from sampling seeds to
+  *exhaustive* delay-bounded model checking: it finds a deep interleaving bug
+  deterministically, or **passes as a bounded proof of correctness**.
+- **🧾 Find wrong answers** — an Elle-style serializability checker
+  (`world.check_serializable`) catches a store that returns a stale or impossible read —
+  not just one that crashes — and reports the cyclic read/write dependency.
+
+**Reproduce & debug it.**
+
 - **🪓 Automatic shrinking** — failures reduce to the minimal schedule deviation, with a
-  human-readable explanation and a replayable artifact on disk.
-- **🧭 Pluggable search** — a uniform random walk *and* PCT
-  ([Probabilistic Concurrency Testing](https://www.microsoft.com/en-us/research/publication/a-randomized-scheduler-with-probabilistic-guarantees-of-finding-bugs/)),
-  which finds deep ordering and starvation bugs a random walk essentially never hits.
-- **🚨 Escape detection** — touch a real socket, signal, subprocess, or the wall clock
-  from inside the sim and you get an `EscapedSimulationError` at the exact call site
+  replayable artifact on disk.
+- **🔁 Determinism guarantees** — a per-test self-check (run twice, locate the first
+  diverging event), `PYTHONHASHSEED` auto-pin, and a queryable boundary registry.
+- **🕰 Causal trace** — record with `causal=True` and walk it: `simloom trace LOG --step N`
+  reconstructs state and the *happens-before stack* that woke it; `--changed x` is an
+  omniscient query; `simloom diff A B` finds the first divergence between two universes.
+- **🚨 Escape detection** — touch a real socket, signal, subprocess, or (un-patched) wall
+  clock from inside the sim and you get an `EscapedSimulationError` at the exact call site
   instead of silent nondeterminism.
 
 ## It finds real bugs
@@ -187,25 +253,29 @@ version survives, with coverage counters proving the faults actually fired.
 
 A determinism claim is only as good as its disclosed limits. simloom raises a loud error
 when your code reaches outside the simulation, and [`docs/determinism.md`](docs/determinism.md)
-states **exactly** what is and isn't deterministic. Known boundaries: blocking
-C-extension I/O (`psycopg2`, `requests`, grpc's C core) can't run in-sim; direct
-`time.time()` reads bypass the virtual clock; real subprocesses and external servers
-need Python stand-ins. None of these fail silently.
+states **exactly** what is and isn't deterministic — now machine-readable via
+`simloom.boundary()`. Known boundaries: blocking C-extension I/O (`psycopg2`, `requests`,
+grpc's C core) can't run in-sim; a `from time import …` alias or the C-accelerated
+`datetime.now()` isn't redirected by the clock patch; real subprocesses and external
+servers need stand-ins. None of these fail silently — and the per-test determinism
+self-check locates anything that slips through.
 
 ## Status
 
-**Pre-alpha, and built in the open.** The deterministic core, simulated world, fault
-matrix, explorer, shrinker, and pytest plugin all exist and are exercised by a
-10,000-seed determinism torture on every CI run (the harness holds itself to the same
-hostility it applies to your code). The API may still shift before 1.0. If you try it,
+**Alpha, and built in the open.** The deterministic core, the simulated world and fault
+matrix (streams, UDP, TLS, partitions, crashes, torn disk writes), the explorer, shrinker,
+property oracles, systematic verifier, serializability checker, causal-trace CLI, and the
+pytest plugin all exist — exercised by a 10,000-seed determinism torture on every CI run
+(the harness holds itself to the same hostility it applies to your code) across Python
+3.12/3.13/3.14. The API may still shift before 1.0. If you try it,
 [open an issue](https://github.com/mandipadk/simloom/issues) — early feedback shapes it.
 
 ## Learn more
 
 - [`docs/determinism.md`](docs/determinism.md) — the honest boundary of the simulation
 - [`docs/event-log.md`](docs/event-log.md) — the versioned event-log and tape formats
+- [`CHANGELOG.md`](CHANGELOG.md) — every capability, phase by phase
 - [`examples/`](examples/) — the toy Raft and the bpo-42130 reproduction, both runnable
-- [`docs/plan.md`](docs/plan.md) — the architecture and the road to 1.0
 
 ## Development
 

{simloom-0.1.0 → simloom-0.2.0}/README.md

@@ -22,9 +22,13 @@ state of the art.
 **simloom runs your unmodified asyncio program inside a fully simulated world** — a
 seeded scheduler that owns every interleaving, a virtual clock, an in-memory network
 with injectable latency, loss, partitions, and crashes — and explores thousands of
-hostile schedules looking for the one that breaks your invariants. When it finds one,
-it hands you a **seed** that replays the failure byte-for-byte, forever, and **shrinks**
-it to the minimal schedule that still triggers the bug.
+hostile schedules looking for the one that breaks your invariants. It doesn't just find
+crashes: it asserts **safety and liveness** properties, **proves** correctness by
+exhaustive systematic search, and catches **wrong answers** (a store that returns a stale
+or impossible read) with serializability checking. When it finds a problem, it hands you a
+**seed** that replays the failure byte-for-byte, forever, **shrinks** it to the minimal
+schedule that still triggers the bug, and lets you **walk the causal trace** of what woke
+what.
 
 ```text
 FAILED test_lease_exclusivity — simloom found a failing universe
@@ -92,6 +96,37 @@ async def test_leader_election(world):
     await world.until(lambda: exactly_one_leader(nodes), timeout=120)
 ```
 
+### Beyond crashes
+
+Assert what *should* hold, prove it can't be violated, and catch wrong answers:
+
+```python
+@simloom.test(runs=5000)
+async def test_lease_safety(world):
+    cluster = start_cluster(world)
+    # safety: never two leaders. liveness: one eventually emerges.
+    world.always("≤1 leader", lambda: sum(n.is_leader for n in cluster) <= 1)
+    world.eventually("a leader", lambda: any(n.is_leader for n in cluster), within=120)
+    await world.sleep(300)
+
+@simloom.test(systematic=True, max_delays=3)     # exhaustive, not sampled
+async def test_critical_section():
+    ...                                          # passes ⇒ a bounded PROOF of correctness
+
+@simloom.test(runs=5000)
+async def test_store_is_serializable(world):
+    await run_transactions(world)                # records ops into world.history
+    world.assert_serializable()                  # finds lost updates / write skew, with the cycle
+```
+
+And once it finds something, replay and walk it:
+
+```sh
+pytest --simloom-seed=17 -k lease          # replay the exact failing universe
+simloom trace failure.jsonl --step 42      # reconstruct state + the happens-before stack
+simloom diff run_a.jsonl run_b.jsonl       # first divergence between two universes
+```
+
 ## Why this didn't exist before
 
 Rust has [`loom`](https://github.com/tokio-rs/loom),
@@ -106,32 +141,62 @@ had **nothing**.
 And asyncio is *structurally perfect* for it: every interleaving decision happens at an
 `await`, under a **replaceable event loop**. simloom swaps in a deterministic one — no
 forked interpreter, no hypervisor, no recompilation. Because the ecosystem (aiohttp,
-httpx, the streams API) bottoms out in loop primitives, **real, unmodified libraries run
-inside the simulation**. Our CI runs a genuine aiohttp server against a genuine httpx
-client over the simulated network, with 20% packet loss injected, replayable from a seed.
+httpx, redis, the streams API) bottoms out in loop primitives, **real, unmodified
+libraries run inside the simulation**. Our CI runs an unmodified **aiohttp HTTPS** server
+against an unmodified aiohttp client over a memory-BIO TLS handshake, and an unmodified
+**`redis.asyncio.Redis`** against an in-sim Redis — all over the simulated network, with
+faults injected, replayable byte-for-byte from a seed.
 
 ## What you get
 
-- **🎲 Seeded, exhaustive-ish scheduling** — a single *choice tape* (the Hypothesis
-  trick, applied to schedules) drives every decision. One seed → one exact universe.
-- **⏱ Virtual time** — an hour of simulated `asyncio.sleep` traffic runs in
-  milliseconds. Timeouts and retries are tested at full speed.
-- **🌐 A simulated network** — in-memory transports with tape-driven latency, loss
-  (modeled as TCP retransmit delay — streams never corrupt), partitions, asymmetric
-  blocks, and connection resets.
-- **💥 Honest crashes** — `host.crash()` is a power cut: tasks stop with no `finally`
-  blocks, unsynced disk writes are lost or *torn*, peers see resets. `restart()` brings
-  the host back against its surviving fsynced state.
-- **🔬 Fault injection in your code** — `simloom.sometimes("drop_cache")` is tape-driven
-  inside the sim and a constant `False` in production. Annotate rare branches; explore
-  them.
+**Run it.** Your real asyncio code, unchanged, inside the simulation.
+
+- **🎲 Seeded scheduling** — a single *choice tape* (the Hypothesis trick, applied to
+  schedules) drives every decision. One seed → one exact universe.
+- **⏱ Virtual time** — an hour of simulated `asyncio.sleep` traffic runs in milliseconds;
+  opt-in patching makes `time.time()` and the stdlib RNG tape-driven too, so an unmodified
+  library that timestamps or rolls a random timeout replays byte-for-byte.
+- **🌐 A simulated network** — in-memory streams (loss modeled as TCP retransmit delay —
+  bytes never corrupt), **UDP datagrams** with real loss/reorder/duplication,
+  partitions, asymmetric per-link latency/loss shaping, resets, and **TLS in-sim**
+  (memory-BIO SSL, so aiohttp HTTPS just works).
+- **💥 Honest crashes & disk** — `host.crash()` is a power cut: tasks stop with no
+  `finally` blocks, unsynced disk writes are lost or *torn*, peers see resets.
+- **🧩 Stand-in services** — `world.run_service(SimRedis(), …)` gives you an in-sim Redis
+  (SET/GET, WATCH/MULTI/EXEC) to test your logic against, with wire faults applied.
+
+**Break it.** Explore the schedules and faults your laptop never will.
+
+- **🔬 Fault injection** — `simloom.sometimes("drop_cache")` is tape-driven inside the sim
+  and a constant `False` in production. Annotate rare branches; explore them.
+- **🧭 Pluggable search** — uniform random walk, **`pct:auto`** (auto-tuned
+  [Probabilistic Concurrency Testing](https://www.microsoft.com/en-us/research/publication/a-randomized-scheduler-with-probabilistic-guarantees-of-finding-bugs/)
+  that finds deep-ordering and starvation bugs random walk never hits), and `simloom.soak`
+  (resumable, shardable continuous exploration).
+
+**Check it.** Assertions far past "didn't crash."
+
+- **🛡 Safety & liveness oracles** — `world.always("one leader", …)`,
+  `world.eventually("elects a leader", …, within=120)`, `world.leads_to(…)`, plus a
+  livelock detector and replica-convergence checks.
+- **✅ Prove it** — `@simloom.test(systematic=True)` switches from sampling seeds to
+  *exhaustive* delay-bounded model checking: it finds a deep interleaving bug
+  deterministically, or **passes as a bounded proof of correctness**.
+- **🧾 Find wrong answers** — an Elle-style serializability checker
+  (`world.check_serializable`) catches a store that returns a stale or impossible read —
+  not just one that crashes — and reports the cyclic read/write dependency.
+
+**Reproduce & debug it.**
+
 - **🪓 Automatic shrinking** — failures reduce to the minimal schedule deviation, with a
-  human-readable explanation and a replayable artifact on disk.
-- **🧭 Pluggable search** — a uniform random walk *and* PCT
-  ([Probabilistic Concurrency Testing](https://www.microsoft.com/en-us/research/publication/a-randomized-scheduler-with-probabilistic-guarantees-of-finding-bugs/)),
-  which finds deep ordering and starvation bugs a random walk essentially never hits.
-- **🚨 Escape detection** — touch a real socket, signal, subprocess, or the wall clock
-  from inside the sim and you get an `EscapedSimulationError` at the exact call site
+  replayable artifact on disk.
+- **🔁 Determinism guarantees** — a per-test self-check (run twice, locate the first
+  diverging event), `PYTHONHASHSEED` auto-pin, and a queryable boundary registry.
+- **🕰 Causal trace** — record with `causal=True` and walk it: `simloom trace LOG --step N`
+  reconstructs state and the *happens-before stack* that woke it; `--changed x` is an
+  omniscient query; `simloom diff A B` finds the first divergence between two universes.
+- **🚨 Escape detection** — touch a real socket, signal, subprocess, or (un-patched) wall
+  clock from inside the sim and you get an `EscapedSimulationError` at the exact call site
   instead of silent nondeterminism.
 
 ## It finds real bugs
@@ -153,25 +218,29 @@ version survives, with coverage counters proving the faults actually fired.
 
 A determinism claim is only as good as its disclosed limits. simloom raises a loud error
 when your code reaches outside the simulation, and [`docs/determinism.md`](docs/determinism.md)
-states **exactly** what is and isn't deterministic. Known boundaries: blocking
-C-extension I/O (`psycopg2`, `requests`, grpc's C core) can't run in-sim; direct
-`time.time()` reads bypass the virtual clock; real subprocesses and external servers
-need Python stand-ins. None of these fail silently.
+states **exactly** what is and isn't deterministic — now machine-readable via
+`simloom.boundary()`. Known boundaries: blocking C-extension I/O (`psycopg2`, `requests`,
+grpc's C core) can't run in-sim; a `from time import …` alias or the C-accelerated
+`datetime.now()` isn't redirected by the clock patch; real subprocesses and external
+servers need stand-ins. None of these fail silently — and the per-test determinism
+self-check locates anything that slips through.
 
 ## Status
 
-**Pre-alpha, and built in the open.** The deterministic core, simulated world, fault
-matrix, explorer, shrinker, and pytest plugin all exist and are exercised by a
-10,000-seed determinism torture on every CI run (the harness holds itself to the same
-hostility it applies to your code). The API may still shift before 1.0. If you try it,
+**Alpha, and built in the open.** The deterministic core, the simulated world and fault
+matrix (streams, UDP, TLS, partitions, crashes, torn disk writes), the explorer, shrinker,
+property oracles, systematic verifier, serializability checker, causal-trace CLI, and the
+pytest plugin all exist — exercised by a 10,000-seed determinism torture on every CI run
+(the harness holds itself to the same hostility it applies to your code) across Python
+3.12/3.13/3.14. The API may still shift before 1.0. If you try it,
 [open an issue](https://github.com/mandipadk/simloom/issues) — early feedback shapes it.
 
 ## Learn more
 
 - [`docs/determinism.md`](docs/determinism.md) — the honest boundary of the simulation
 - [`docs/event-log.md`](docs/event-log.md) — the versioned event-log and tape formats
+- [`CHANGELOG.md`](CHANGELOG.md) — every capability, phase by phase
 - [`examples/`](examples/) — the toy Raft and the bpo-42130 reproduction, both runnable
-- [`docs/plan.md`](docs/plan.md) — the architecture and the road to 1.0
 
 ## Development
 

{simloom-0.1.0 → simloom-0.2.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "simloom"
 dynamic = ["version"]
-description = "Deterministic simulation testing for asyncio: seeded schedules, fault injection, perfect replay."
+description = "Deterministic simulation testing for asyncio: explore every schedule, inject faults, assert properties, prove correctness, and replay any failure from a seed."
 readme = "README.md"
 requires-python = ">=3.12"
 license = "Apache-2.0"
@@ -14,9 +14,13 @@ keywords = [
     "testing",
     "fault-injection",
     "concurrency",
+    "model-checking",
+    "serializability",
+    "chaos-engineering",
+    "property-testing",
 ]
 classifiers = [
-    "Development Status :: 2 - Pre-Alpha",
+    "Development Status :: 3 - Alpha",
     "Framework :: AsyncIO",
     "Framework :: Pytest",
     "Intended Audience :: Developers",
@@ -46,8 +50,12 @@ dev = [
 spikes = [
     "aiohttp>=3.11",
     "httpx>=0.28",
+    "redis>=5.0",
 ]
 
+[project.scripts]
+simloom = "simloom._cli:main"
+
 [project.entry-points.pytest11]
 simloom = "simloom._pytest_plugin"