simloom 0.3.0__tar.gz → 0.4.0__tar.gz

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

@@ -7,6 +7,55 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-07-06
+
+### Added
+- **World/fault-matrix fuzzer.** Generated distributed programs (hosts running
+  TCP echo servers and UDP endpoints, clients hitting random peers) while a
+  director executes a random fault script — partitions, heals, asymmetric
+  blocks, crashes, restarts, connection resets, latency/loss, datagram faults —
+  at random virtual times. Properties: run==run==replay byte-identical whatever
+  the faults, and errors are only ever user-level (a replay never misaligns).
+  2,000-case offline campaign, zero divergences.
+- **Adversarial API-misuse suite + hostile-input hardening.** Every misuse is a
+  clean, named error (nested `run()`, coroutine objects, bad bounds, raising
+  monitor predicates/protocol callbacks/`__repr__`s, double-completes), the CLI
+  reports unreadable logs instead of tracebacking, unhashable register values
+  get a clear message, and 100 failing/deadlocking runs leave zero residue.
+- **Unpinned-PYTHONHASHSEED CI job + shrinker properties.** The determinism-
+  critical suites now also run with hash randomization ON (any internal
+  hash-order dependence surfaces as a divergence), and the shrinker is
+  property-tested over fuzzer-generated failures: the minimized tape must still
+  fail with the same error class, deterministically (400-case sweep).
+- **Systematic-verifier cross-validation.** `proven_correct` — the most
+  dangerous claim simloom makes — is cross-checked against random exploration
+  on fuzzer-generated programs: a proof must never coexist with a random
+  failure, every reported witness must replay, and an exhaustive search must
+  find any bug random finds. 400-case offline campaign, zero contradictions.
+- **asyncio semantics-parity fuzzer.** Generated programs with interleaving-
+  independent results must produce exactly what the stock asyncio loop produces
+  — values, exception types, timeouts, shields, gathers, cancellation. Offline:
+  4,000 programs x 3 sim seeds vs `asyncio.run`, zero divergences.
+- **Random-program determinism fuzzer.** Arbitrary generated async programs
+  (queues, locks, events, sleeps, tape draws, task spawning, cancellation) must
+  satisfy run==run==replay byte-identically under both schedulers — deadlocking
+  programs must deadlock identically. Offline campaign: 20,000 programs
+  (~100,000 executions), zero divergences; a randomized slice runs in CI.
+
+### Fixed
+- **Serializability checker: four incompleteness bugs**, found by a
+  differential campaign against an independent brute-force reference (450k+
+  random histories). The checker was always *sound* (no false accusations) but
+  missed ~20% of real violations: (1) incompatible reads — two reads neither of
+  which is a prefix of the other; (2) intra-transaction inconsistencies — a
+  transaction reading its own future append, shrinking reads, or two different
+  pre-transaction states; (3) torn atomic append groups — a read observing part
+  of a transaction's appends; (4) rw anti-dependency edges were only generated
+  for values in the recovered version order, missing cross-key atomicity cycles
+  — now a read precedes the append of *every* value it did not observe. After
+  the fixes: zero disagreements over 450k serializability and 320k
+  linearizability cases; the differential suite is now part of CI.
+
 ## [0.3.0] - 2026-07-06
 
 ### Added
@@ -211,7 +260,8 @@ 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.3.0...HEAD
+[Unreleased]: https://github.com/mandipadk/simloom/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/mandipadk/simloom/compare/v0.3.0...v0.4.0
 [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.3.0 → simloom-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simloom
-Version: 0.3.0
+Version: 0.4.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
@@ -256,6 +256,23 @@ double-vote bug and exploration elects two leaders in one term in ~1 seed of 5;
 version survives, with coverage counters proving the faults actually fired.
 → `examples/toy_raft.py`
 
+## The harness is tested harder than your code
+
+A correctness tool's worst failure mode is *false confidence*, so simloom attacks itself
+the way it attacks your code. Beyond the 10,000-seed determinism torture, every CI run:
+
+- **differentially validates both consistency checkers** against independent brute-force
+  references (the offline campaign — 450k+ serializability and 320k+ linearizability
+  histories — found and fixed four checker incompleteness bugs before you ever saw them);
+- **fuzzes determinism with generated programs** — random workers, queues, locks,
+  cancellation, fault scripts against hosts and the network — every one must satisfy
+  `run == run == replay` byte-for-byte (20k programs + 2k fault-scripted worlds offline);
+- **checks semantics parity against stock asyncio** — programs with interleaving-
+  independent results must behave identically on the real loop (4k programs offline);
+- **cross-validates every `proven_correct` claim** against random exploration, runs the
+  determinism-critical suites with `PYTHONHASHSEED` *unpinned*, property-tests the
+  shrinker, and asserts every API misuse is a clean, named error.
+
 ## Honesty first
 
 A determinism claim is only as good as its disclosed limits. simloom raises a loud error

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

@@ -220,6 +220,23 @@ double-vote bug and exploration elects two leaders in one term in ~1 seed of 5;
 version survives, with coverage counters proving the faults actually fired.
 → `examples/toy_raft.py`
 
+## The harness is tested harder than your code
+
+A correctness tool's worst failure mode is *false confidence*, so simloom attacks itself
+the way it attacks your code. Beyond the 10,000-seed determinism torture, every CI run:
+
+- **differentially validates both consistency checkers** against independent brute-force
+  references (the offline campaign — 450k+ serializability and 320k+ linearizability
+  histories — found and fixed four checker incompleteness bugs before you ever saw them);
+- **fuzzes determinism with generated programs** — random workers, queues, locks,
+  cancellation, fault scripts against hosts and the network — every one must satisfy
+  `run == run == replay` byte-for-byte (20k programs + 2k fault-scripted worlds offline);
+- **checks semantics parity against stock asyncio** — programs with interleaving-
+  independent results must behave identically on the real loop (4k programs offline);
+- **cross-validates every `proven_correct` claim** against random exploration, runs the
+  determinism-critical suites with `PYTHONHASHSEED` *unpinned*, property-tests the
+  shrinker, and asserts every API misuse is a clean, named error.
+
 ## Honesty first
 
 A determinism claim is only as good as its disclosed limits. simloom raises a loud error

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

@@ -234,7 +234,11 @@ def main(argv: Sequence[str] | None = None) -> int:
     diff.set_defaults(func=_cmd_diff)
 
     args = parser.parse_args(argv)
-    result: int = args.func(args)
+    try:
+        result: int = args.func(args)
+    except OSError as exc:
+        print(f"error: {exc}")
+        return 2
     return result
 
 

{simloom-0.3.0 → simloom-0.4.0}/src/simloom/_consistency.py

@@ -145,6 +145,103 @@ class _Graph:
             self.types[(u, v)] = kind
 
 
+def _is_prefix(shorter: list[Any], longer: list[Any]) -> bool:
+    return len(shorter) <= len(longer) and longer[: len(shorter)] == shorter
+
+
+def _intra_transaction_violation(txn: Transaction) -> str | None:
+    """In a serial order a transaction executes atomically: outside state is
+    frozen while it runs. So every read of key k must observe exactly
+    ``base + (this transaction's own prior appends to k)`` where ``base`` — the
+    pre-transaction state — is the same for all of the transaction's reads of k
+    and cannot contain the transaction's own (globally unique) values."""
+    own_values = {op.value for op in txn.ops if op.f == "append"}
+    appended_so_far: dict[str, list[Any]] = {}
+    base_of: dict[str, list[Any]] = {}
+    for op in txn.ops:
+        if op.f == "append":
+            appended_so_far.setdefault(op.key, []).append(op.value)
+            continue
+        observed = list(op.value)
+        own = appended_so_far.get(op.key, [])
+        if own and observed[len(observed) - len(own) :] != own:
+            return (
+                f"transaction {txn.index} read {observed!r} from {op.key!r}, which does "
+                f"not end with its own prior appends {own!r}"
+            )
+        base = observed[: len(observed) - len(own)] if own else observed
+        if any(value in own_values for value in base):
+            return (
+                f"transaction {txn.index} read {observed!r} from {op.key!r} containing "
+                f"a value it had not appended yet"
+            )
+        if op.key in base_of and base_of[op.key] != base:
+            return (
+                f"transaction {txn.index} observed two different pre-transaction states "
+                f"for {op.key!r}: {base_of[op.key]!r} and {base!r}"
+            )
+        base_of[op.key] = base
+    return None
+
+
+def _torn_transaction_violation(txns: tuple[Transaction, ...]) -> str | None:
+    """A transaction executes atomically, so its appends to a key land in the
+    serial sequence as one contiguous block — and states only exist at
+    transaction boundaries. A read observing *any* of a transaction's appends
+    to a key must therefore observe *all* of them, contiguously and in order.
+
+    An external read observing a torn slice of another transaction (or its
+    values out of order) can never be explained by any serial order. A
+    transaction's *own* mid-flight reads legitimately see a prefix of its own
+    appends; those are validated by ``_intra_transaction_violation`` instead.
+    """
+    appends_of: dict[tuple[int, str], list[Any]] = {}
+    appender: dict[tuple[str, Any], int] = {}
+    for txn in txns:
+        for op in txn.ops:
+            if op.f == "append":
+                appends_of.setdefault((txn.index, op.key), []).append(op.value)
+                appender[(op.key, op.value)] = txn.index
+    for txn in txns:
+        for op in txn.ops:
+            if op.f != "read":
+                continue
+            observed = list(op.value)
+            for writer in {appender.get((op.key, v)) for v in observed}:
+                if writer is None or writer == txn.index:
+                    continue  # unknown value, or an own-read (checked elsewhere)
+                block = appends_of[(writer, op.key)]
+                positions = [i for i, v in enumerate(observed) if v in set(block)]
+                if [observed[i] for i in positions] != block or positions != list(
+                    range(positions[0], positions[0] + len(block))
+                ):
+                    return (
+                        f"transaction {txn.index} read {observed!r} from {op.key!r}: it "
+                        f"observes a torn slice of transaction {writer}'s atomic appends "
+                        f"{block!r}"
+                    )
+    return None
+
+
+def _incompatible_reads_violation(txns: tuple[Transaction, ...]) -> str | None:
+    """A key's list only ever grows, so every read is a prefix of the final
+    sequence — any two reads of the same key must be prefix-related."""
+    reads_by_key: dict[str, list[list[Any]]] = {}
+    for txn in txns:
+        for op in txn.ops:
+            if op.f == "read":
+                reads_by_key.setdefault(op.key, []).append(list(op.value))
+    for key, reads in reads_by_key.items():
+        reads.sort(key=len)
+        for i in range(len(reads) - 1):
+            if not _is_prefix(reads[i], reads[i + 1]):
+                return (
+                    f"incompatible reads of {key!r}: {reads[i]!r} and {reads[i + 1]!r} "
+                    f"(neither is a prefix of the other, impossible for an append-only list)"
+                )
+    return None
+
+
 def check_serializable(history: History) -> SerializabilityResult:
     """Check a list-append history for serializability (Elle-style). Returns a
     result whose ``cycle`` (with per-edge ``edge_types``) witnesses any
@@ -153,40 +250,59 @@ def check_serializable(history: History) -> SerializabilityResult:
     if not txns:
         return SerializabilityResult(ok=True, message="empty history is serializable")
 
+    # 0. Sound structural pre-checks: reads that no serial order can explain,
+    #    regardless of transaction ordering (found by differential testing
+    #    against a brute-force reference — see tests/test_adversarial_checkers.py).
+    for txn in txns:
+        reason = _intra_transaction_violation(txn)
+        if reason is not None:
+            return SerializabilityResult(ok=False, message=f"serializability violation: {reason}")
+    reason = _incompatible_reads_violation(txns)
+    if reason is not None:
+        return SerializabilityResult(ok=False, message=f"serializability violation: {reason}")
+    reason = _torn_transaction_violation(txns)
+    if reason is not None:
+        return SerializabilityResult(ok=False, message=f"serializability violation: {reason}")
+
     # 1. Recover each key's version order from the longest read that observed it,
     #    and which transaction appended each (unique) value.
     version_order: dict[str, list[Any]] = {}
     appender: dict[Any, int] = {}
+    appends_by_key: dict[str, list[Any]] = {}
     for txn in txns:
         for op in txn.ops:
             if op.f == "append":
                 appender[op.value] = txn.index
+                appends_by_key.setdefault(op.key, []).append(op.value)
             elif op.f == "read":
                 observed = list(op.value)
                 if op.key not in version_order or len(observed) > len(version_order[op.key]):
                     version_order[op.key] = observed
 
     graph = _Graph()
-    for key, order in version_order.items():
-        index_of = {v: i for i, v in enumerate(order)}
+    for order in version_order.values():
         # 2. ww edges along the version order.
         for i in range(len(order) - 1):
             a, b = appender.get(order[i]), appender.get(order[i + 1])
             if a is not None and b is not None:
                 graph.add(a, b, "ww")
-        # 3. wr and rw edges from each read of this key.
-        for txn in txns:
-            for op in txn.ops:
-                if op.f != "read" or op.key != key:
-                    continue
-                observed = list(op.value)
-                for v in observed:  # wr: the writer of an observed value precedes us
-                    w = appender.get(v)
-                    if w is not None:
-                        graph.add(w, txn.index, "wr")
-                # rw: we precede the writer of every version we did NOT see
-                last_seen = index_of.get(observed[-1], -1) if observed else -1
-                for v in order[last_seen + 1 :]:
+    # 3. wr and rw edges from every read. The rw rule is deliberately broader
+    #    than the version order: an append is never un-observed (the list only
+    #    grows), so a read that does NOT contain value v must precede v's
+    #    append — even if v was never observed by any read. (The narrow
+    #    version-order-only rule missed cross-key atomicity cycles; found by
+    #    differential testing against a brute-force reference.)
+    for txn in txns:
+        for op in txn.ops:
+            if op.f != "read":
+                continue
+            observed_set = set(op.value)
+            for v in op.value:  # wr: the writer of an observed value precedes us
+                w = appender.get(v)
+                if w is not None:
+                    graph.add(w, txn.index, "wr")
+            for v in appends_by_key.get(op.key, ()):
+                if v not in observed_set:
                     w = appender.get(v)
                     if w is not None:
                         graph.add(txn.index, w, "rw")

{simloom-0.3.0 → simloom-0.4.0}/src/simloom/_linearizability.py

@@ -194,9 +194,15 @@ def _check_key(
         if is_terminal(remaining):
             return None
         marker = (remaining, state)
-        if marker in seen:
-            continue
-        seen.add(marker)
+        try:
+            if marker in seen:
+                continue
+            seen.add(marker)
+        except TypeError as exc:
+            raise TypeError(
+                f"register values must be hashable for linearizability checking "
+                f"(the search memoises on them); got {state!r}"
+            ) from exc
         if len(seen) > max_states:
             raise RuntimeError(
                 f"linearizability search exceeded {max_states} states on key {key!r}; "

{simloom-0.3.0 → simloom-0.4.0}/src/simloom/_version.py

@@ -5,4 +5,4 @@ Single source of truth: pyproject.toml reads ``__version__`` from this file
 tag matches it. Bump here, tag ``vX.Y.Z``, publish.
 """
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"