wunderspec 0.128.7__tar.gz → 0.129.2__tar.gz

{wunderspec-0.128.7 → wunderspec-0.129.2}/.flake8

@@ -2,5 +2,6 @@
 max-line-length = 88
 extend-ignore = E203, E501
 per-file-ignores = 
+    examples/*:E266,F403,F405
     tests/*:F401,F841
     wunderspec/lang.py:E721

wunderspec-0.129.2/.github/workflows/build.yml

@@ -0,0 +1,34 @@
+name: Build
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v5
+
+    - name: Set up Python
+      uses: actions/setup-python@v6
+      with:
+        python-version: "3.12"
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v8.1.0
+      with:
+        enable-cache: true
+        cache-suffix: build
+
+    - name: Build package
+      run: uv build
+
+    - name: Upload build artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: dist
+        path: dist/

wunderspec-0.129.2/.github/workflows/convert-to-tla.yml

@@ -0,0 +1,78 @@
+name: Convert to TLA+
+
+env:
+  APALACHE_VERSION: "0.57.0"
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  convert-to-tla:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v5
+
+    - name: Set up Python
+      uses: actions/setup-python@v6
+      with:
+        python-version: "3.12"
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v8.1.0
+      with:
+        enable-cache: true
+        cache-suffix: convert-to-tla
+
+    - name: Install project
+      run: uv sync --locked
+
+    - name: Set up Java
+      uses: actions/setup-java@v5
+      with:
+        distribution: 'temurin'
+        java-version: '17'
+
+    - name: Cache tla2tools.jar
+      id: cache-tla2tools
+      uses: actions/cache@v5
+      with:
+        path: tla2tools.jar
+        key: tla2tools-v1.8.0
+
+    - name: Download tla2tools.jar
+      if: steps.cache-tla2tools.outputs.cache-hit != 'true'
+      run: wget -q https://github.com/tlaplus/tlaplus/releases/download/v1.8.0/tla2tools.jar
+
+    - name: Cache Apalache
+      id: cache-apalache
+      uses: actions/cache@v5
+      with:
+        path: apalache-${{ env.APALACHE_VERSION }}
+        key: apalache-v${{ env.APALACHE_VERSION }}
+
+    - name: Download Apalache
+      if: steps.cache-apalache.outputs.cache-hit != 'true'
+      run: |
+        curl -fsSL "https://github.com/apalache-mc/apalache/releases/download/v${APALACHE_VERSION}/apalache-${APALACHE_VERSION}.tgz" -o apalache.tgz
+        tar -xzf apalache.tgz
+        rm apalache.tgz
+
+    - name: Add Apalache to PATH
+      run: echo "$PWD/apalache-${APALACHE_VERSION}/bin" >> "$GITHUB_PATH"
+
+    - name: Convert examples to TLA+
+      run: uv run python scripts/convert_examples_to_tla.py
+
+    - name: Run Apalache typecheck on generated specs
+      run: |
+        set -euo pipefail
+        mkdir -p .apalache-out/build
+        cd .build
+        for f in *.tla; do
+          echo "=== Typechecking $f ==="
+          apalache-mc typecheck --out-dir="../.apalache-out/build/$(basename "${f%.tla}")" "$f"
+        done

wunderspec-0.129.2/.github/workflows/lint.yml

@@ -0,0 +1,40 @@
+name: Lint
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v5
+
+    - name: Set up Python
+      uses: actions/setup-python@v6
+      with:
+        python-version: "3.12"
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v8.1.0
+      with:
+        enable-cache: true
+        cache-suffix: lint
+
+    - name: Install project
+      run: uv sync --locked --group dev
+
+    - name: Check code formatting with Black
+      run: uv run black --check --diff .
+
+    - name: Check import sorting with isort
+      run: uv run isort --check-only --diff .
+
+    - name: Lint with flake8
+      run: uv run flake8 wunderspec examples scripts
+
+    - name: Type check with mypy
+      run: uv run mypy wunderspec

wunderspec-0.129.2/.github/workflows/run-examples.yml

@@ -0,0 +1,31 @@
+name: Run Examples
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  run-examples:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v5
+
+    - name: Set up Python
+      uses: actions/setup-python@v6
+      with:
+        python-version: "3.12"
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v8.1.0
+      with:
+        enable-cache: true
+        cache-suffix: run-examples
+
+    - name: Install project
+      run: uv sync --locked
+
+    - name: Run examples
+      run: uv run python scripts/run_examples.py

{wunderspec-0.128.7 → wunderspec-0.129.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wunderspec
-Version: 0.128.7
+Version: 0.129.2
 Summary: Protocol specifications as Python code
 Author: Igor Konnov, Thomas Pani
 License-File: LICENSE
@@ -74,8 +74,8 @@ commands are not included in this package.
 
 ## 4. Release Provenance
 
-- Release tag: `v0.128.7`
-- Source commit: `ad5ef3606668d6720f41fc18dbb1cd86c682cbd7`
+- Release tag: `v0.129.2`
+- Source commit: `f60e52f632281f5cbb2d1a382ea49b10750d2f4d`
 
 See [tests/README.md](https://github.com/wunderspec/wunderspec/blob/main/tests/README.md)
 for the development test log captured at release time.

{wunderspec-0.128.7 → wunderspec-0.129.2}/README.md

@@ -58,8 +58,8 @@ commands are not included in this package.
 
 ## 4. Release Provenance
 
-- Release tag: `v0.128.7`
-- Source commit: `ad5ef3606668d6720f41fc18dbb1cd86c682cbd7`
+- Release tag: `v0.129.2`
+- Source commit: `f60e52f632281f5cbb2d1a382ea49b10750d2f4d`
 
 See [tests/README.md](https://github.com/wunderspec/wunderspec/blob/main/tests/README.md)
 for the development test log captured at release time.

{wunderspec-0.128.7 → wunderspec-0.129.2}/examples/examples.yaml

@@ -49,6 +49,9 @@ examples:
   - file: producer_consumer.py
     instances: small medium
     invariants: non_negative capacity_bound type_invariant
+  - file: sloppy_counter.py
+    instances: n2_batch3_8bit n4_batch4_8bit
+    invariants: accounting local_shards_bounded approximation_bound
   - file: minimmit.py
     instances: n6_t1_f0
     invariants: agreement

wunderspec-0.129.2/examples/sloppy_counter.py

@@ -0,0 +1,137 @@
+"""
+Multiprocessor sharded counter using one percpu_counter-style counter.
+These counters are usually used for fast statistics counters.
+
+Inspired by the LWN discussion of Linux's ``percpu_counter``:
+https://lwn.net/Articles/170003/
+
+Igor Konnov, 2026
+"""
+
+from wunderspec import (
+    And,
+    Expr,
+    Or,
+    Param,
+    Set,
+    StateVar,
+    Tuple,
+    Val,
+    coverage,
+    example,
+    instance,
+    invariant,
+    state,
+)
+from wunderspec.expr import SetExpr
+from wunderspec.machine import Context, MachineStateBase, action
+
+
+@state
+class SloppyCounterState(MachineStateBase):
+    N: Param[int]  # the total number of CPUs
+    BATCH: Param[int]  # the maximal lag before syncing
+    WORD_WIDTH: Param[int]  # the number of bits in the CPU word
+    global_count: StateVar[int]  # the global atomic_t counter
+    local_count: StateVar[dict[int, int]]  # one local counter per CPU
+    ghost_count: StateVar[int]  # the exact counter by observer
+
+
+def cpus(s: SloppyCounterState) -> SetExpr:
+    return Set(Val(1), ..., s.N)
+
+
+def local_total(s: SloppyCounterState) -> Expr:
+    return s.local_count.reduce(lambda acc, _cpu, count: acc + count, Val(0))  # type: ignore
+
+
+def max_slop(s: SloppyCounterState) -> Expr:
+    """The maximum counter slop over all CPUs"""
+    return s.N * (s.BATCH - 1)
+
+
+@action(init=True)
+def init(c: Context[SloppyCounterState]):
+    s = c.state
+    s.global_count = Val(0)
+    s.local_count = cpus(s).map_to(lambda _: Val(0))
+    s.ghost_count = Val(0)
+
+
+@action(inline=False)
+def increment(c: Context[SloppyCounterState], cpu: Expr):
+    """Increment the sloppy counter"""
+    s = c.state
+    # the observer keeps track of the precise value
+    s.ghost_count = (s.ghost_count + 1) % (2**s.WORD_WIDTH)
+    next_local = s.local_count[cpu] + 1
+    keep_local, propagate = c.split(next_local < s.BATCH)
+
+    with keep_local:  # cheap local increment
+        s.local_count[cpu] = next_local
+
+    with propagate:  # expensive atomic increase
+        s.global_count = (s.global_count + next_local) % (2**s.WORD_WIDTH)
+        s.local_count[cpu] = 0
+
+
+@action
+def step(c: Context[SloppyCounterState]):
+    with c.one_of(cpus(c.state), "cpu") as cpu:
+        increment(c, cpu)
+
+
+@invariant
+def accounting(s: SloppyCounterState) -> Expr:
+    return s.ghost_count == (s.global_count + local_total(s)) % (2**s.WORD_WIDTH)
+
+
+@invariant
+def local_shards_bounded(s: SloppyCounterState) -> Expr:
+    return cpus(s).forall(
+        lambda cpu: And(
+            s.local_count[cpu] >= 0,
+            s.local_count[cpu] < s.BATCH,
+        )
+    )
+
+
+@invariant
+def approximation_bound(s: SloppyCounterState) -> Expr:
+    return Or(
+        And(  # no overflow of ghost_count
+            s.global_count <= s.ghost_count,
+            s.ghost_count <= s.global_count + max_slop(s),
+        ),
+        s.ghost_count <= (s.global_count + max_slop(s)) % (2**s.WORD_WIDTH),
+    )
+
+
+@example
+def sloppy_read_possible(s: SloppyCounterState) -> Expr:
+    return s.global_count < s.ghost_count
+
+
+@coverage
+def state_cov(s: SloppyCounterState) -> Expr:
+    return Tuple(s.global_count, s.local_count, s.ghost_count)
+
+
+@instance
+def n2_batch3_8bit() -> SloppyCounterState:
+    return SloppyCounterState(N=2, BATCH=3, WORD_WIDTH=8)
+
+
+@instance
+def n2_batch3_16bit() -> SloppyCounterState:
+    return SloppyCounterState(N=2, BATCH=3, WORD_WIDTH=16)
+
+
+@instance
+def n2_batch100_32bit() -> SloppyCounterState:
+    return SloppyCounterState(N=2, BATCH=100, WORD_WIDTH=32)
+
+
+@instance
+def n4_batch4_8bit() -> SloppyCounterState:
+    return SloppyCounterState(N=4, BATCH=4, WORD_WIDTH=8)

{wunderspec-0.128.7 → wunderspec-0.129.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "wunderspec"
-version = "0.128.7"
+version = "0.129.2"
 description = "Protocol specifications as Python code"
 authors = [
     {name = "Igor Konnov"},
@@ -38,7 +38,7 @@ dev = [
     "markdown-pytest>=0.3.2,<0.4.0",
     "mypy>=1.0.0,<2.0.0",
     "pyright>=1.1.400,<2.0.0",
-    "pytest>=9.0.2,<10.0.0",
+    "pytest>=8.0.0,<9.0.0",
     "pytest-codeblocks>=0.17.0,<0.18.0",
     "pytest-cov>=6.0.0,<7.0.0",
 ]

wunderspec-0.129.2/scripts/__init__.py

@@ -0,0 +1 @@
+"""Repository maintenance scripts."""

wunderspec-0.129.2/scripts/_spec_utils.py

@@ -0,0 +1,190 @@
+"""Shared AST helpers for wunderspec example scripts."""
+
+import ast
+import re
+from pathlib import Path
+from typing import Any, TypedDict
+
+import yaml  # type: ignore[import-untyped]
+
+
+class ExampleConfigRow(TypedDict):
+    file: str
+    instances: list[str]
+    invariants_auto: bool
+    invariants: list[str]
+    examples_auto: bool
+    examples: list[str]
+    example_run_seeds: dict[str, int]
+    example_run_max_samples: dict[str, int]
+    timeout: int | None
+
+
+def _find_decorated_names(spec_path: Path, decorator_id: str) -> list[str]:
+    """Return names of functions decorated with ``@decorator_id`` in *spec_path*.
+
+    Uses AST inspection so the module is never imported (avoids dependency
+    issues with spec-local imports such as ``from simple_ponzi import *``).
+    """
+    tree = ast.parse(spec_path.read_text())
+    names: list[str] = []
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            for decorator in node.decorator_list:
+                if isinstance(decorator, ast.Name) and decorator.id == decorator_id:
+                    names.append(node.name)
+    return names
+
+
+def find_invariant_names(spec_path: Path) -> set[str]:
+    """Return the names of functions decorated with ``@invariant`` in *spec_path*."""
+    return set(_find_decorated_names(spec_path, "invariant"))
+
+
+def find_example_names(spec_path: Path) -> set[str]:
+    """Return the names of functions decorated with ``@example`` in *spec_path*."""
+    return set(_find_decorated_names(spec_path, "example"))
+
+
+def find_coverage_names(spec_path: Path) -> set[str]:
+    """Return the names of functions decorated with ``@coverage`` in *spec_path*."""
+    return set(_find_decorated_names(spec_path, "coverage"))
+
+
+def find_init_action_name(spec_path: Path) -> str:
+    """Return the name of the ``@action(init=True)`` function, or ``"init"``."""
+    tree = ast.parse(spec_path.read_text())
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            for decorator in node.decorator_list:
+                if isinstance(decorator, ast.Call):
+                    func = decorator.func
+                    if isinstance(func, ast.Name) and func.id == "action":
+                        for kw in decorator.keywords:
+                            if (
+                                kw.arg == "init"
+                                and isinstance(kw.value, ast.Constant)
+                                and kw.value.value is True
+                            ):
+                                return node.name
+    return "init"
+
+
+_STEP_NAME_RE = re.compile(r"^(Next|step|Step|.*_next|.*Next)$")
+
+
+def find_step_action_name(spec_path: Path, init_name: str) -> str:
+    """Return the name of the bare ``@action`` (non-init, single-param) function.
+
+    Only considers names matching: Next, step, Step, *_next, *Next.
+    Falls back to ``"step"`` if none is found.
+    """
+    tree = ast.parse(spec_path.read_text())
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        if node.name == init_name:
+            continue
+        if not _STEP_NAME_RE.match(node.name):
+            continue
+        if len(node.args.args) != 1:
+            continue
+        for decorator in node.decorator_list:
+            if isinstance(decorator, ast.Name) and decorator.id == "action":
+                return node.name
+    return "step"
+
+
+def load_examples_config(config_path: Path) -> list[ExampleConfigRow]:
+    """Load examples YAML config.
+
+    Expected shape:
+
+    examples:
+      - file: spec.py
+        instances: inst_a inst_b   # or a YAML list
+        invariants: inv_x inv_y    # or a YAML list; omit for auto-discovery
+        examples: ex_a ex_b        # or a YAML list; omit for auto-discovery
+        example_run_seeds:         # optional mapping example -> integer seed
+          ex_b: 123
+        example_run_max_samples:   # optional mapping example -> integer
+          ex_b: 300
+        timeout: 30                # optional wall-clock cap (seconds) per run
+    """
+
+    def _to_tokens(raw: Any, key: str, file_label: str) -> list[str]:
+        if raw is None:
+            return []
+        if isinstance(raw, str):
+            return raw.split()
+        if isinstance(raw, list) and all(isinstance(x, str) for x in raw):
+            return raw
+        raise ValueError(
+            f"{config_path}: '{key}' in '{file_label}' must be a string or list[str]"
+        )
+
+    def _to_optional_int(raw: Any, key: str, file_label: str) -> int | None:
+        if raw is None:
+            return None
+        if isinstance(raw, int) and not isinstance(raw, bool):
+            return raw
+        raise ValueError(f"{config_path}: '{key}' in '{file_label}' must be an integer")
+
+    def _to_str_int_map(raw: Any, key: str, file_label: str) -> dict[str, int]:
+        if raw is None:
+            return {}
+        if not isinstance(raw, dict):
+            raise ValueError(
+                f"{config_path}: '{key}' in '{file_label}' must be a mapping[str, int]"
+            )
+        out: dict[str, int] = {}
+        for k, v in raw.items():
+            if not isinstance(k, str) or not isinstance(v, int):
+                raise ValueError(
+                    f"{config_path}: '{key}' in '{file_label}' must be a mapping[str, int]"
+                )
+            out[k] = v
+        return out
+
+    data = yaml.safe_load(config_path.read_text(encoding="utf-8"))
+    if not isinstance(data, dict):
+        raise ValueError(f"{config_path}: root must be a mapping")
+    examples = data.get("examples")
+    if not isinstance(examples, list) or not examples:
+        raise ValueError(f"{config_path}: 'examples' must be a non-empty list")
+
+    rows: list[ExampleConfigRow] = []
+    for entry in examples:
+        if not isinstance(entry, dict):
+            raise ValueError(f"{config_path}: each example entry must be a mapping")
+        spec_file = entry.get("file")
+        if not isinstance(spec_file, str) or not spec_file.strip():
+            raise ValueError(
+                f"{config_path}: each example must define non-empty 'file'"
+            )
+        spec_file = spec_file.strip()
+        rows.append(
+            {
+                "file": spec_file,
+                "instances": _to_tokens(entry.get("instances"), "instances", spec_file),
+                "invariants_auto": "invariants" not in entry,
+                "invariants": _to_tokens(
+                    entry.get("invariants"), "invariants", spec_file
+                ),
+                "examples_auto": "examples" not in entry,
+                "examples": _to_tokens(entry.get("examples"), "examples", spec_file),
+                "example_run_seeds": _to_str_int_map(
+                    entry.get("example_run_seeds"),
+                    "example_run_seeds",
+                    spec_file,
+                ),
+                "example_run_max_samples": _to_str_int_map(
+                    entry.get("example_run_max_samples"),
+                    "example_run_max_samples",
+                    spec_file,
+                ),
+                "timeout": _to_optional_int(entry.get("timeout"), "timeout", spec_file),
+            }
+        )
+
+    return rows