simloom 0.2.0__tar.gz → 0.3.0__tar.gz

{simloom-0.2.0 → simloom-0.3.0}/CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-07-06
+
+### Added
+- **Time-travel debugging v1.** `run(..., debug=True)` (implies `causal=True`)
+  installs a `sys.monitoring` recorder over *user code*: every line executed,
+  every local-variable change (`name = repr`, address-scrubbed and truncated),
+  and every call/return with arguments and values — all keyed to the scheduler
+  step that ran them. `simloom debug LOG` answers omniscient queries over the
+  recording: `--step N` (the code that ran during a step), `--var x` (the full
+  timeline of a variable — a lost update's double stale read is one query),
+  `--fn name` (calls/returns). Stdlib/site-packages/simloom are filtered out and
+  their monitoring locations disabled after first sight; debug runs are
+  deterministic and replay exactly.
+- **Stand-in services: sim-nats.** `world.run_service(SimNats(), host=, port=)`
+  starts an in-sim NATS broker an *unmodified* `nats-py` client speaks to —
+  publish/subscribe with subject wildcards (`*`/`>`), request/reply, and queue
+  groups. Which member of a queue group receives each message is a **tape
+  draw**, so exploration covers every delivery assignment a real broker could
+  make (measured: distinct worker assignments across seeds, exactly-once per
+  message on all of them). Wire faults (partition the broker away) surface as
+  deterministic, replayable timeouts.
+- **Wing-Gong linearizability checking.** `world.registers` records
+  read/write/cas operations (invoke/complete pairs, so real-time precedence is
+  exact); `world.check_linearizable()` / `assert_linearizable()` run Wing &
+  Gong's algorithm with memoisation. Stricter than serializability: the order
+  must respect real time, so a *stale read* is caught even when a serial order
+  could excuse it. Pending (crashed) operations are handled the Jepsen way —
+  they may or may not have taken effect, and both worlds are explored. Keys are
+  independent registers (linearizability is local), and a violation reports the
+  deepest valid prefix plus exactly which operation cannot take effect and why.
+
 ## [0.2.0] - 2026-06-25
 
 ### Added
@@ -180,6 +211,7 @@ explorer, shrinker, and pytest plugin are all present and exercised by a
   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
+[Unreleased]: https://github.com/mandipadk/simloom/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/mandipadk/simloom/compare/v0.2.0...v0.3.0
 [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.2.0 → simloom-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simloom
-Version: 0.2.0
+Version: 0.3.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
@@ -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: nats-py>=2.9; extra == 'spikes'
 Requires-Dist: redis>=5.0; extra == 'spikes'
 Description-Content-Type: text/markdown
 
@@ -197,8 +198,10 @@ faults injected, replayable byte-for-byte from a seed.
   (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.
+- **🧩 Stand-in services** — `world.run_service(...)` gives you an in-sim **Redis**
+  (SET/GET, WATCH/MULTI/EXEC, for unmodified redis-py) and an in-sim **NATS** broker
+  (pub/sub, wildcards, queue groups, for unmodified nats-py) — with wire faults applied,
+  and queue-group delivery choices explored from the tape.
 
 **Break it.** Explore the schedules and faults your laptop never will.
 
@@ -218,8 +221,10 @@ faults injected, replayable byte-for-byte from a seed.
   *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.
+  (`world.check_serializable`) reports the cyclic read/write dependency behind a lost
+  update, and a Wing-Gong **linearizability** checker (`world.check_linearizable`)
+  catches the stale read serializability would excuse — including may-or-may-not-have-
+  applied writes from crashed clients.
 
 **Reproduce & debug it.**
 
@@ -227,9 +232,11 @@ faults injected, replayable byte-for-byte from a seed.
   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.
+- **🕰 Causal trace & time travel** — record with `causal=True` and walk it: `simloom trace
+  LOG --step N` reconstructs state and the *happens-before stack* that woke it; `simloom
+  diff A B` finds the first divergence between two universes. Record with `debug=True`
+  and query **everything**: `simloom debug LOG --var balance` prints every value a local
+  variable ever held — a lost update's double stale read is one query.
 - **🚨 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.

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

@@ -162,8 +162,10 @@ faults injected, replayable byte-for-byte from a seed.
   (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.
+- **🧩 Stand-in services** — `world.run_service(...)` gives you an in-sim **Redis**
+  (SET/GET, WATCH/MULTI/EXEC, for unmodified redis-py) and an in-sim **NATS** broker
+  (pub/sub, wildcards, queue groups, for unmodified nats-py) — with wire faults applied,
+  and queue-group delivery choices explored from the tape.
 
 **Break it.** Explore the schedules and faults your laptop never will.
 
@@ -183,8 +185,10 @@ faults injected, replayable byte-for-byte from a seed.
   *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.
+  (`world.check_serializable`) reports the cyclic read/write dependency behind a lost
+  update, and a Wing-Gong **linearizability** checker (`world.check_linearizable`)
+  catches the stale read serializability would excuse — including may-or-may-not-have-
+  applied writes from crashed clients.
 
 **Reproduce & debug it.**
 
@@ -192,9 +196,11 @@ faults injected, replayable byte-for-byte from a seed.
   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.
+- **🕰 Causal trace & time travel** — record with `causal=True` and walk it: `simloom trace
+  LOG --step N` reconstructs state and the *happens-before stack* that woke it; `simloom
+  diff A B` finds the first divergence between two universes. Record with `debug=True`
+  and query **everything**: `simloom debug LOG --var balance` prints every value a local
+  variable ever held — a lost update's double stale read is one query.
 - **🚨 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.

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

@@ -51,6 +51,7 @@ spikes = [
     "aiohttp>=3.11",
     "httpx>=0.28",
     "redis>=5.0",
+    "nats-py>=2.9",
 ]
 
 [project.scripts]

{simloom-0.2.0 → simloom-0.3.0}/src/simloom/__init__.py

@@ -27,12 +27,18 @@ from ._eventlog import EVENT_LOG_FORMAT_VERSION, EventLog
 from ._explore import Exploration, Failure, explore
 from ._fingerprint import CorpusEntry, InterleavingCorpus, fingerprint, interleaving_edges
 from ._hashseed import is_pinned, pin_hashseed
+from ._linearizability import (
+    LinCall,
+    LinearizabilityResult,
+    RegisterHistory,
+    check_linearizable,
+)
 from ._loop import SimLoop
 from ._monitors import always, eventually, leads_to
 from ._net import SimDatagramTransport, SimNetwork, SimServer, SimTransport
 from ._run import RunResult, replay, run
 from ._sched import PCT, RandomWalk
-from ._services import SimRedis
+from ._services import SimNats, SimRedis
 from ._shrink import ShrinkResult, shrink
 from ._soak import SoakReport, soak
 from ._systematic import SystematicResult, explore_systematic
@@ -58,8 +64,11 @@ __all__ = [
     "Host",
     "InterleavingCorpus",
     "InvariantViolation",
+    "LinCall",
+    "LinearizabilityResult",
     "MisalignmentPolicy",
     "RandomWalk",
+    "RegisterHistory",
     "RunResult",
     "SerializabilityResult",
     "Settings",
@@ -69,6 +78,7 @@ __all__ = [
     "SimDisk",
     "SimLivelockError",
     "SimLoop",
+    "SimNats",
     "SimNetwork",
     "SimRedis",
     "SimServer",
@@ -85,6 +95,7 @@ __all__ = [
     "__version__",
     "always",
     "boundary",
+    "check_linearizable",
     "check_serializable",
     "draw",
     "eventually",

{simloom-0.2.0 → simloom-0.3.0}/src/simloom/_cli.py

@@ -139,6 +139,77 @@ def _cmd_diff(args: argparse.Namespace) -> int:
     return 1
 
 
+def var_timeline(events: Sequence[Event], name: str) -> list[Event]:
+    """Every point a local variable (debug mode) or observed value changed."""
+    out: list[Event] = []
+    for event in events:
+        if event.get("kind") == "trace" and name in (event.get("changed") or {}):
+            out.append(event)
+        elif event.get("kind") == "trace" and event.get("event") == "call":
+            if name in (event.get("args") or {}):
+                out.append(event)
+        elif event.get("kind") == "observe" and event.get("name") == name:
+            out.append(event)
+    return out
+
+
+def _format_trace(event: Event, name: str | None = None) -> str:
+    step = event.get("step")
+    prefix = f"step {step:>4}" if step is not None else "step    -"
+    kind = event.get("event")
+    if kind == "call":
+        args = ", ".join(f"{k}={v}" for k, v in (event.get("args") or {}).items())
+        return f"{prefix}  → {event.get('fn')}({args})"
+    if kind == "return":
+        return f"{prefix}  ← {event.get('fn')} returned {event.get('value')}"
+    if kind == "unwind":
+        return f"{prefix}  ✗ {event.get('fn')} raised {event.get('error')}"
+    location = f"{event.get('file', '?')}:{event.get('line', '?')}"
+    if name is not None:
+        value = (event.get("changed") or {}).get(name, (event.get("args") or {}).get(name))
+        return f"{prefix}  {location}  {name} = {value}"
+    changed = event.get("changed")
+    suffix = "  " + ", ".join(f"{k}={v}" for k, v in changed.items()) if changed else ""
+    return f"{prefix}  {location}{suffix}"
+
+
+def _cmd_debug(args: argparse.Namespace) -> int:
+    _header, events = load_log(args.log)
+    traces = [e for e in events if e.get("kind") == "trace"]
+    if not traces:
+        print("no trace events: record with run(..., debug=True)")
+        return 2
+    if args.var is not None:
+        for event in var_timeline(events, args.var):
+            if event.get("kind") == "observe":
+                print(f"step {event.get('step')!s:>4}  observe  {args.var} = {event.get('value')}")
+            else:
+                print(_format_trace(event, args.var))
+        return 0
+    if args.fn is not None:
+        for event in traces:
+            if event.get("event") in ("call", "return", "unwind") and args.fn in str(
+                event.get("fn", "")
+            ):
+                print(_format_trace(event))
+        return 0
+    if args.step is not None:
+        during = [e for e in traces if e.get("step") == args.step]
+        print(f"=== user code executed during step {args.step} ({len(during)} events) ===")
+        for event in during:
+            print(_format_trace(event))
+        return 0
+    kinds: dict[str, int] = {}
+    for event in traces:
+        kinds[str(event.get("event"))] = kinds.get(str(event.get("event")), 0) + 1
+    steps = {e.get("step") for e in traces if e.get("step") is not None}
+    print(
+        f"{len(traces)} trace events across {len(steps)} steps "
+        f"({', '.join(f'{k}: {v}' for k, v in sorted(kinds.items()))})"
+    )
+    return 0
+
+
 def main(argv: Sequence[str] | None = None) -> int:
     parser = argparse.ArgumentParser(prog="simloom", description="simloom debugging tools")
     sub = parser.add_subparsers(dest="command", required=True)
@@ -150,6 +221,13 @@ def main(argv: Sequence[str] | None = None) -> int:
     trace.add_argument("--changed", default=None, help="steps where an observed value changed")
     trace.set_defaults(func=_cmd_trace)
 
+    debug = sub.add_parser("debug", help="omniscient queries over a debug-mode log")
+    debug.add_argument("log", help="a JSONL event log recorded with debug=True")
+    debug.add_argument("--step", type=int, default=None, help="code executed during step N")
+    debug.add_argument("--var", default=None, help="full timeline of a local variable")
+    debug.add_argument("--fn", default=None, help="calls/returns of a function (substring)")
+    debug.set_defaults(func=_cmd_debug)
+
     diff = sub.add_parser("diff", help="first divergence between two event logs")
     diff.add_argument("a", help="first JSONL event log")
     diff.add_argument("b", help="second JSONL event log")

simloom-0.3.0/src/simloom/_debugger.py

@@ -0,0 +1,173 @@
+"""The omniscient recorder behind ``run(..., debug=True)`` — time-travel
+debugging v1.
+
+A deterministic replay means a failure can be re-run *any number of times*, so
+a debugger does not need to step forward gingerly: record **everything** once,
+then query the recording. Under ``debug=True`` (which implies ``causal=True``),
+a ``sys.monitoring`` recorder captures user code as it executes:
+
+- every **line** executed, tagged with the scheduler step that ran it,
+- every **local variable change**, as ``name = repr`` at the line it changed,
+- every function **call** (with its arguments) and **return** (with its value).
+
+The ``simloom debug`` CLI then answers the questions a debugger session is
+really made of, over the whole run at once: *what code ran during step N* (with
+its happens-before stack from the causal log), *every value ``x`` ever held and
+where it changed*, *every call/return of a function*.
+
+Only user code is recorded — the stdlib, site-packages, and simloom itself are
+filtered out (and their monitoring locations disabled after first sight, so
+the overhead concentrates on the code being debugged). Recording emits log
+events only; it never draws from the tape or schedules callbacks, so a debug
+run is deterministic and replays exactly (its digest differs from a non-debug
+run — it contains more events — but is stable across debug runs).
+
+Caveat, stated honestly: values are captured with ``repr``, so a user
+``__repr__`` runs during recording. Reprs are truncated to keep the log sane.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+import sysconfig
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ._loop import SimLoop
+
+_REPR_LIMIT = 120
+
+#: Default object reprs embed memory addresses, which differ run to run; the
+#: event log is address-free by design (determinism rule), so scrub them.
+_ADDRESS = re.compile(r" at 0x[0-9a-fA-F]+")
+
+_STDLIB = sysconfig.get_paths()["stdlib"]
+_PURELIB = sysconfig.get_paths()["purelib"]
+_PLATLIB = sysconfig.get_paths()["platlib"]
+_SIMLOOM = os.path.dirname(os.path.abspath(__file__))
+_EXCLUDED_PREFIXES = tuple({_STDLIB, _PURELIB, _PLATLIB, _SIMLOOM})
+
+
+def _short(value: object) -> str:
+    try:
+        text = repr(value)
+    except Exception:
+        text = f"<unreprable {type(value).__name__}>"
+    text = _ADDRESS.sub(" at 0x…", text)
+    if len(text) > _REPR_LIMIT:
+        text = text[: _REPR_LIMIT - 3] + "..."
+    return text
+
+
+def _is_user_code(filename: str) -> bool:
+    if filename.startswith("<"):
+        # "<stdin>", "<string>", pytester bodies — user; "<frozen importlib...>" — not.
+        return not filename.startswith("<frozen")
+    return not filename.startswith(_EXCLUDED_PREFIXES)
+
+
+class Recorder:
+    """Installs sys.monitoring callbacks for the duration of one run."""
+
+    def __init__(self, loop: SimLoop) -> None:
+        self._loop = loop
+        self._tool: int | None = None
+        #: id(frame) -> {name: repr} — value snapshots for live user frames.
+        #: Cleared on return/unwind, so frame-id reuse cannot cross-contaminate.
+        self._locals: dict[int, dict[str, str]] = {}
+
+    # -- lifecycle ---------------------------------------------------------
+
+    def install(self) -> None:
+        monitoring = sys.monitoring
+        for tool in (5, 4, 3, 2, 1):  # first free tool id, avoiding pdb's 0
+            if monitoring.get_tool(tool) is None:
+                monitoring.use_tool_id(tool, "simloom-debugger")
+                self._tool = tool
+                break
+        if self._tool is None:  # pragma: no cover — five tools already active
+            raise RuntimeError("no free sys.monitoring tool id for the simloom debugger")
+        events = monitoring.events
+        monitoring.register_callback(self._tool, events.PY_START, self._on_start)
+        monitoring.register_callback(self._tool, events.PY_RETURN, self._on_return)
+        monitoring.register_callback(self._tool, events.PY_UNWIND, self._on_unwind)
+        monitoring.register_callback(self._tool, events.LINE, self._on_line)
+        monitoring.set_events(
+            self._tool, events.PY_START | events.PY_RETURN | events.PY_UNWIND | events.LINE
+        )
+
+    def uninstall(self) -> None:
+        if self._tool is None:
+            return
+        monitoring = sys.monitoring
+        monitoring.set_events(self._tool, 0)
+        for event in (
+            monitoring.events.PY_START,
+            monitoring.events.PY_RETURN,
+            monitoring.events.PY_UNWIND,
+            monitoring.events.LINE,
+        ):
+            monitoring.register_callback(self._tool, event, None)
+        monitoring.free_tool_id(self._tool)
+        monitoring.restart_events()  # re-arm locations we DISABLEd
+        self._tool = None
+        self._locals.clear()
+
+    # -- callbacks ----------------------------------------------------------
+
+    def _emit(self, event: str, **fields: Any) -> None:
+        self._loop._log.emit(
+            "trace", t=self._loop._now, step=self._loop._current_step, event=event, **fields
+        )
+
+    def _on_start(self, code: Any, offset: int) -> Any:
+        if not _is_user_code(code.co_filename):
+            return sys.monitoring.DISABLE
+        frame = sys._getframe(1)
+        snapshot = {name: _short(value) for name, value in frame.f_locals.items()}
+        self._locals[id(frame)] = snapshot
+        self._emit(
+            "call",
+            fn=code.co_qualname,
+            file=code.co_filename,
+            line=code.co_firstlineno,
+            args=dict(snapshot),
+        )
+        return None
+
+    def _on_line(self, code: Any, line: int) -> Any:
+        if not _is_user_code(code.co_filename):
+            return sys.monitoring.DISABLE
+        frame = sys._getframe(1)
+        snapshot = self._locals.get(id(frame))
+        if snapshot is None:  # frame started before the recorder was installed
+            snapshot = {}
+            self._locals[id(frame)] = snapshot
+        changed: dict[str, str] = {}
+        for name, value in frame.f_locals.items():
+            text = _short(value)
+            if snapshot.get(name) != text:
+                snapshot[name] = text
+                changed[name] = text
+        fields: dict[str, Any] = {"file": code.co_filename, "line": line}
+        if changed:
+            fields["changed"] = changed
+        self._emit("line", **fields)
+        return None
+
+    def _on_return(self, code: Any, offset: int, retval: Any) -> None:
+        if not _is_user_code(code.co_filename):
+            return  # PY_RETURN locations for non-user code stay armed; cheap no-op
+        frame = sys._getframe(1)
+        self._locals.pop(id(frame), None)
+        self._emit("return", fn=code.co_qualname, value=_short(retval))
+
+    def _on_unwind(self, code: Any, offset: int, exc: BaseException) -> None:
+        # PY_UNWIND cannot be DISABLEd; filter and move on.
+        if not _is_user_code(code.co_filename):
+            return
+        frame = sys._getframe(1)
+        self._locals.pop(id(frame), None)
+        self._emit("unwind", fn=code.co_qualname, error=type(exc).__name__)

{simloom-0.2.0 → simloom-0.3.0}/src/simloom/_errors.py

@@ -68,7 +68,7 @@ class SimLivelockError(SimloomError):
 
 
 class ConsistencyViolation(SimloomError):
-    """A recorded operation history is not serializable.
+    """A recorded operation history is not serializable (or not linearizable).
 
     The store returned a *wrong answer*, not a crash: a read saw a stale or
     impossible value. ``cycle`` is the dependency cycle that witnesses it, with