pbt 0.5.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f0585c0152a9703256b3265830dd9105b33ebc65877555517af3ad643a6b8839
-  data.tar.gz: ac62f147919ac2e68642d70d9e0bb9d2c8010ef54b2aefc4d6c679fe1b9d7197
+  metadata.gz: 3275eafb6d07373c24f422feafa7300962213568a387cd21fbcd648c85de4193
+  data.tar.gz: 7a3b902bb323251050ec023ec8318244d777c0bc2584ad0c8bad2504d93888f0
 SHA512:
-  metadata.gz: 54535a35fa3097b1fe3f4893f83ef9c646598b385c9d4c32f3eb2686aab3727ca22154a87edef748f94090682acee6f7090ecb4d51233e66e861b30bd20df0d3
-  data.tar.gz: e8126c1c5f1b044d83f66b6d0a734783d2843f16f0b24f9a1172797e5b144a630a26c642bfc606f57de9911935f1b25ff0c1d8af48ef92486680c80e264308b0
+  metadata.gz: e72d6278580f540b7d0aad1aefb168c2fbc7a3e64d31a90a4929695b979d3d1c29e3dc06fb22fb0fc6d1aadfc121605176cbee7146e298201f9091c0fa2ea647
+  data.tar.gz: 8967245b883d22dfb00d79b0433acc53502e3e9ecdb07e89bae04002ce413fd67d126f695f4a4e12a965fc7adf171b5cd8e1c9fd3e6d8d28e8ff4444113cbea5

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 ## [Unreleased]
 
+## [0.7.0] - 2026-04-04
+
+- [Breaking change] Simplify stateful command protocol: `arguments` must now accept `state` parameter, and `applicable?` must now accept both `state` and `args` parameters
+- Make `rng` optional in all arbitrary `generate` methods with default `Random.new` [#44](https://github.com/ohbarye/pbt/pull/44)
+- Mark stateful testing API as stable (no longer experimental)
+
+## [0.6.0] - 2026-03-15
+
+- Add experimental `Pbt.stateful` API for model-based stateful property testing [#38](https://github.com/ohbarye/pbt/pull/38)
+- Support state-aware and arg-aware stateful command protocols, including argument shrinking and generation edge cases [#40](https://github.com/ohbarye/pbt/pull/40)
+- Validate stateful model/command contracts more consistently and improve diagnostics [#39](https://github.com/ohbarye/pbt/pull/39)
+- Add Ruby 4.0 to CI test matrix
+
 ## [0.5.1] - 2025-06-29
 
 - Fix `IntegerArbitrary#shrink` to respect min/max bounds [#36](https://github.com/ohbarye/pbt/pull/36)

data/CLAUDE.md

@@ -0,0 +1,104 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+PBT (Property-Based Testing) is a Ruby gem that provides property-based testing capabilities with experimental features for parallel test execution using Ractor. The gem allows developers to specify properties that code should satisfy and automatically generates test cases to verify these properties.
+
+## Development Commands
+
+### Setup
+```bash
+bundle install
+```
+
+### Testing
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run a specific test file
+bundle exec rspec spec/path/to/spec.rb
+
+# Run tests matching a pattern
+bundle exec rspec -e "pattern"
+```
+
+### Linting
+```bash
+# Check code style
+bundle exec rake standard
+
+# Auto-fix code style issues
+bundle exec rake standard:fix
+```
+
+### Combined Testing and Linting
+```bash
+# Default rake task runs both tests and linting
+bundle exec rake
+```
+
+### Benchmarking
+```bash
+# Run all benchmarks
+bundle exec rake benchmark:all
+
+# Run specific benchmark categories
+bundle exec rake benchmark:success:simple
+bundle exec rake benchmark:success:cpu_bound
+bundle exec rake benchmark:success:io_bound
+bundle exec rake benchmark:failure:simple
+```
+
+### Building and Releasing
+```bash
+# Build the gem
+bundle exec rake build
+
+# Install locally
+bundle exec rake install
+
+# Release to RubyGems (maintainers only)
+bundle exec rake release
+```
+
+## Architecture
+
+### Core Components
+
+1. **Arbitrary** (`lib/pbt/arbitrary/`)
+   - Base classes and modules for generating random values
+   - Implements various arbitraries: integer, array, tuple, hash, etc.
+   - Each arbitrary knows how to generate values and shrink them
+
+2. **Check** (`lib/pbt/check/`)
+   - `Property`: Defines properties to test
+   - `Runner`: Executes properties with different concurrency methods
+   - `Configuration`: Global and per-run configuration
+   - `Tosser`: Manages the generation and shrinking process
+
+3. **Reporter** (`lib/pbt/reporter/`)
+   - Handles test result reporting
+   - Provides verbose mode for detailed output
+
+### Key Design Patterns
+
+- **Shrinking**: When a test fails, PBT attempts to find the minimal failing case by systematically reducing the input
+- **Concurrency**: Supports both serial (`:none`) and parallel (`:ractor`) execution
+- **Configuration**: Uses both global configuration and per-assertion overrides
+
+### Testing Approach
+
+The codebase uses RSpec for testing and follows these patterns:
+- Unit tests for each arbitrary type in `spec/pbt/arbitrary/`
+- Integration tests in `spec/e2e/`
+- Property-based tests are used to test the library itself
+
+### Important Notes
+
+- Ruby 3.1+ is required due to Ractor usage
+- When using `:ractor` worker, be aware of Ractor limitations (no shared state, limited object sharing)
+- The gem uses Standard Ruby for code style (configured in `.standard.yml`)
+- CI runs tests against Ruby 3.1, 3.2, 3.3, and 3.4

data/README.md

@@ -34,7 +34,7 @@ Add this line to your application's Gemfile and run `bundle install`.
 gem 'pbt'
 ```
 
-Off course you can install with `gem intstall pbt`.
+Of course you can install with `gem install pbt`.
 
 ## Basic Usage
 
@@ -108,38 +108,134 @@ There are many built-in arbitraries in `Pbt`. You can use them to generate rando
 #### Primitives
 
 ```ruby
-rng = Random.new
+Pbt.integer.generate                  # => 42
+Pbt.integer(min: -1, max: 8).generate # => Integer between -1 and 8
 
-Pbt.integer.generate(rng)                  # => 42
-Pbt.integer(min: -1, max: 8).generate(rng) # => Integer between -1 and 8
+Pbt.symbol.generate                   # => :atq
 
-Pbt.symbol.generate(rng)                   # => :atq
+Pbt.ascii_char.generate               # => "a"
+Pbt.ascii_string.generate             # => "aagjZfao"
 
-Pbt.ascii_char.generate(rng)               # => "a"
-Pbt.ascii_string.generate(rng)             # => "aagjZfao"
+Pbt.boolean.generate                  # => true or false
+Pbt.constant(42).generate             # => 42 always
+```
+
+You can also pass a custom random number generator if needed:
 
-Pbt.boolean.generate(rng)                  # => true or false
-Pbt.constant(42).generate(rng)             # => 42 always
+```ruby
+rng = Random.new(42) # with a specific seed for reproducibility
+Pbt.integer.generate(rng)
 ```
 
 #### Composites
 
 ```ruby
-rng = Random.new
+Pbt.array(Pbt.integer).generate                        # => [121, -13141, 9825]
+Pbt.array(Pbt.integer, max: 1, empty: true).generate   # => [] or [42] etc.
 
-Pbt.array(Pbt.integer).generate(rng)                        # => [121, -13141, 9825]
-Pbt.array(Pbt.integer, max: 1, empty: true).generate(rng)   # => [] or [42] etc.
+Pbt.tuple(Pbt.symbol, Pbt.integer).generate            # => [:atq, 42]
 
-Pbt.tuple(Pbt.symbol, Pbt.integer).generate(rng)            # => [:atq, 42]
+Pbt.fixed_hash(x: Pbt.symbol, y: Pbt.integer).generate # => {x: :atq, y: 42}
+Pbt.hash(Pbt.symbol, Pbt.integer).generate             # => {atq: 121, ygab: -1142}
 
-Pbt.fixed_hash(x: Pbt.symbol, y: Pbt.integer).generate(rng) # => {x: :atq, y: 42}
-Pbt.hash(Pbt.symbol, Pbt.integer).generate(rng)             # => {atq: 121, ygab: -1142}
-
-Pbt.one_of(:a, 1, 0.1).generate(rng)                        # => :a or 1 or 0.1
+Pbt.one_of(:a, 1, 0.1).generate                        # => :a or 1 or 0.1
 ````
 
 See [ArbitraryMethods](https://github.com/ohbarye/pbt/blob/main/lib/pbt/arbitrary/arbitrary_methods.rb) module for more details.
 
+## Stateful Testing (Experimental)
+
+`Pbt` also provides an experimental stateful property API for model-based / command-based testing.
+It is designed as a property-compatible object (`generate`, `shrink`, `run`) so it works with the existing runner (`Pbt.assert` / `Pbt.check`) without changing the runner API.
+
+This API is still experimental. Expect interface refinements and behavior changes in future releases.
+
+### Minimal usage
+
+```ruby
+class CounterModel
+  def initialize
+    @inc = IncrementCommand.new
+  end
+
+  def initial_state
+    0
+  end
+
+  def commands(_state)
+    [@inc]
+  end
+end
+
+class IncrementCommand
+  def name
+    :increment
+  end
+
+  def arguments(_state)
+    Pbt.nil
+  end
+
+  def applicable?(_state, _args)
+    true
+  end
+
+  def next_state(state, _args)
+    state + 1
+  end
+
+  def run!(sut, _args)
+    sut.increment
+  end
+
+  def verify!(before_state:, after_state:, args: _, result:, sut:)
+    raise "unexpected result" unless result == after_state
+    raise "state mismatch" unless after_state == before_state + 1
+    raise "sut mismatch" unless sut.value == after_state
+  end
+end
+
+class Counter
+  attr_reader :value
+
+  def initialize
+    @value = 0
+  end
+
+  def increment
+    @value += 1
+  end
+end
+
+Pbt.assert do
+  Pbt.stateful(
+    model: CounterModel.new,
+    sut: -> { Counter.new },
+    max_steps: 20
+  )
+end
+```
+
+### Expected interfaces
+
+`Pbt.stateful(model:, sut:, max_steps:)` expects the following duck-typed interfaces:
+
+- `model.initial_state`
+- `model.commands(state)` -> `Array<command>`
+- `command.name`
+- `command.arguments(state)` (a `Pbt` arbitrary, may depend on current model state)
+- `command.applicable?(state, args)` -> `true` / `false`
+- `command.next_state(state, args)` -> next model state
+- `command.run!(sut, args)` -> command result
+- `command.verify!(before_state:, after_state:, args:, result:, sut:)`
+
+### Current limitations (MVP)
+
+- `Pbt.stateful` runs sequentially by default, even if the global worker is `:ractor`.
+- You can still pass `worker: :none` explicitly if you want to make that choice obvious in a test.
+- `worker: :ractor` is currently unsupported and raises `Pbt::InvalidConfiguration`.
+- Shrinking supports shorter prefixes and command-argument shrinking (using `command.arguments.shrink(args)`).
+
 ## What if property-based tests fail?
 
 Once a test fails it's time to debug. `Pbt` provides some features to help you debug.
@@ -328,7 +424,7 @@ Once this project finishes the following, we will release v1.0.0.
 - [ ] Statistics feature to aggregate generated values
 - [ ] Decide DSL
 - [ ] Try Fiber
-- [ ] Stateful property-based testing
+- [x] Stateful property-based testing (experimental, via `Pbt.stateful`)
 
 ## Development
 

data/lib/pbt/arbitrary/arbitrary.rb

@@ -2,6 +2,8 @@
 
 module Pbt
   module Arbitrary
+    class EmptyDomainError < ArgumentError; end
+
     # Abstract class for generating random values on type `T`.
     #
     # @abstract
@@ -9,9 +11,9 @@ module Pbt
       # Generate a value of type `T`, based on the provided random number generator.
       #
       # @abstract
-      # @param rng [Random] Random number generator.
+      # @param rng [Random] Random number generator. Defaults to a new Random instance.
       # @return [Object] Random value of type `T`.
-      def generate(rng)
+      def generate(rng = Random.new)
         raise NotImplementedError
       end
 
@@ -29,7 +31,7 @@ module Pbt
       #
       # @example
       #   integer_generator = Pbt.integer
-      #   num_str_generator = integer_arb.map(->(n){ n.to_s }, ->(s) {s.to_i})
+      #   num_str_generator = integer_generator.map(->(n){ n.to_s }, ->(s) {s.to_i})
       #
       # @param mapper [Proc] Proc to map generated values. Mainly used for generation.
       # @param unmapper [Proc] Proc to unmap generated values. Used for shrinking.
@@ -45,8 +47,8 @@ module Pbt
       #
       # @example
       #   integer_generator = Pbt.integer
-      #   even_integer_generator = integer_arb.filter { |x| x.even? }
-      #   # or `integer_arb.filter(&:even?)`
+      #   even_integer_generator = integer_generator.filter { |x| x.even? }
+      #   # or `integer_generator.filter(&:even?)`
       #
       # @param refinement [Proc] Predicate proc to test each produced element. Return true to keep the element, false otherwise.
       # @return [FilterArbitrary] New arbitrary filtered using `refinement`.

data/lib/pbt/arbitrary/array_arbitrary.rb

@@ -20,7 +20,7 @@ module Pbt
       end
 
       # @see Arbitrary#generate
-      def generate(rng)
+      def generate(rng = Random.new)
         length = @length_arb.generate(rng)
         length.times.map { @value_arb.generate(rng) }
       end

data/lib/pbt/arbitrary/choose_arbitrary.rb

@@ -10,7 +10,7 @@ module Pbt
       end
 
       # @see Arbitrary#generate
-      def generate(rng)
+      def generate(rng = Random.new)
         rng.rand(@range)
       end
 

data/lib/pbt/arbitrary/constant_arbitrary.rb

@@ -10,7 +10,7 @@ module Pbt
       end
 
       # @see Arbitrary#generate
-      def generate(rng)
+      def generate(rng = Random.new)
         @val
       end
 

data/lib/pbt/arbitrary/filter_arbitrary.rb

@@ -12,7 +12,7 @@ module Pbt
       end
 
       # @see Arbitrary#generate
-      def generate(rng)
+      def generate(rng = Random.new)
         loop do
           val = @arb.generate(rng)
           return val if @refinement.call(val)

data/lib/pbt/arbitrary/fixed_hash_arbitrary.rb

@@ -11,7 +11,7 @@ module Pbt
       end
 
       # @see Arbitrary#generate
-      def generate(rng)
+      def generate(rng = Random.new)
         values = @arb.generate(rng)
         @keys.zip(values).to_h
       end

data/lib/pbt/arbitrary/integer_arbitrary.rb

@@ -15,8 +15,12 @@ module Pbt
       end
 
       # @see Arbitrary#generate
-      def generate(rng)
+      def generate(rng = Random.new)
         rng.rand(@min..@max)
+      rescue ArgumentError => e
+        raise EmptyDomainError, e.message if @min > @max
+
+        raise
       end
 
       # @see Arbitrary#shrink

data/lib/pbt/arbitrary/map_arbitrary.rb

@@ -14,7 +14,7 @@ module Pbt
       end
 
       # @see Arbitrary#generate
-      def generate(rng)
+      def generate(rng = Random.new)
         @mapper.call(@arb.generate(rng))
       end
 

data/lib/pbt/arbitrary/one_of_arbitrary.rb

@@ -11,7 +11,7 @@ module Pbt
       end
 
       # @see Arbitrary#generate
-      def generate(rng)
+      def generate(rng = Random.new)
         @choices[@idx_arb.generate(rng)]
       end
 

data/lib/pbt/arbitrary/tuple_arbitrary.rb

@@ -10,7 +10,7 @@ module Pbt
       end
 
       # @see Arbitrary#generate
-      def generate(rng)
+      def generate(rng = Random.new)
         @arbs.map { |arb| arb.generate(rng) }
       end
 

data/lib/pbt/check/property.rb

@@ -16,7 +16,7 @@ module Pbt
       #
       # @param rng [Random] Random number generator.
       # @return [Object]
-      def generate(rng)
+      def generate(rng = Random.new)
         @arb.generate(rng)
       end
 

data/lib/pbt/check/runner_methods.rb

@@ -36,6 +36,10 @@ module Pbt
         property = property.call
         config = Pbt.configuration.to_h.merge(options.to_h)
 
+        if property.respond_to?(:stateful?) && property.stateful? && !options.key?(:worker)
+          config[:worker] = :none
+        end
+
         initial_values = toss(property, config[:seed])
         source_values = Enumerator.new(config[:num_runs]) do |y|
           config[:num_runs].times do
@@ -115,14 +119,35 @@ module Pbt
         runner.map.with_index { |val, index|
           Case.new(val:, index:, ractor: property.run_in_ractor(val))
         }.each do |c|
-          c.ractor.take
+          wait_ractor_result(c.ractor)
           runner.handle_result(c)
         rescue => e
-          c.exception = e.cause # Ractor error is wrapped in a Ractor::RemoteError. We need to get the cause.
+          c.exception = unwrap_ractor_exception(e)
           runner.handle_result(c)
           break # Ignore the rest of the cases. Just pick up the first failure.
         end
       end
+
+      # Ractor errors can wrap the original exception in a `cause` (e.g. `Ractor::RemoteError`).
+      # If no cause exists, keep the original exception instance.
+      #
+      # @param error [Exception]
+      # @return [Exception]
+      def unwrap_ractor_exception(error)
+        error.cause || error
+      end
+
+      # Ruby 4 removed Ractor#take in favor of Ractor#value.
+      #
+      # @param ractor [Ractor]
+      # @return [Object]
+      def wait_ractor_result(ractor)
+        if ractor.respond_to?(:value)
+          ractor.value
+        else
+          ractor.take
+        end
+      end
     end
   end
 end

data/lib/pbt/stateful/property.rb

@@ -0,0 +1,357 @@
+# frozen_string_literal: true
+
+module Pbt
+  module Stateful
+    # Property-compatible wrapper for command-based stateful testing.
+    # It provides `generate`, `shrink` and `run`, so existing runners can execute it.
+    class Property
+      ARG_AWARE_GENERATION_ATTEMPTS = 5
+
+      REQUIRED_COMMAND_METHODS = %i[
+        name
+        arguments
+        applicable?
+        next_state
+        run!
+        verify!
+      ].freeze
+
+      Step = Struct.new(:command, :args, keyword_init: true) do
+        def inspect
+          "#<Pbt::Stateful::Step command=#{command_label}, args=#{args.inspect}>"
+        end
+
+        private
+
+        def command_label
+          if command.respond_to?(:name)
+            command.name.inspect
+          else
+            command.class.name || command.class.inspect
+          end
+        end
+      end
+
+      # @param model [Object]
+      # @param sut [Proc]
+      # @param max_steps [Integer]
+      def initialize(model:, sut:, max_steps:)
+        validate_model!(model)
+        raise Pbt::InvalidConfiguration, "sut must be callable" unless sut.respond_to?(:call)
+        raise Pbt::InvalidConfiguration, "max_steps must be an Integer" unless max_steps.is_a?(Integer)
+        raise Pbt::InvalidConfiguration, "max_steps must be non-negative" if max_steps.negative?
+
+        @model = model
+        @sut_factory = sut
+        @max_steps = max_steps
+      end
+
+      # Generate a sequence of commands valid for the current model state.
+      #
+      # @param rng [Random]
+      # @return [Array<Step>]
+      def generate(rng = Random.new)
+        length = rng.rand(0..@max_steps)
+        state = @model.initial_state
+        sequence = []
+
+        length.times do
+          candidates = generate_candidates_for(state, rng, context: "generate")
+          break if candidates.empty?
+
+          command, args = candidates[rng.rand(candidates.length)]
+          sequence << Step.new(command:, args:)
+          state = command.next_state(state, args)
+        end
+
+        sequence
+      end
+
+      # Shrink a sequence by trying shorter prefixes first.
+      #
+      # @param sequence [Array<Hash, Step>]
+      # @return [Enumerator<Array<Hash, Step>>]
+      def shrink(sequence)
+        Enumerator.new do |y|
+          seen = {}
+          state = @model.initial_state
+
+          (sequence.length - 1).downto(0) do |length|
+            yield_shrink_candidate(y, seen, sequence.first(length))
+          end
+
+          sequence.each_with_index do |step, index|
+            command, args = unpack_step(step)
+            validate_command_protocol!(command, state:, context: "shrink step #{index}")
+            break unless applicable?(command, state, args, context: "shrink step #{index}")
+
+            arbitrary_for(command, state, context: "shrink step #{index}").shrink(args).each do |shrunk_args|
+              candidate = replace_step(sequence, index, command:, args: shrunk_args)
+              next unless valid_sequence?(candidate)
+
+              yield_shrink_candidate(y, seen, candidate)
+            end
+
+            state = command.next_state(state, args)
+          end
+        end
+      end
+
+      # @return [Boolean]
+      def stateful?
+        true
+      end
+
+      # Stateful properties currently require sequential execution because the model,
+      # commands and SUT factory are ordinary Ruby objects and are not guaranteed to be
+      # Ractor-shareable.
+      #
+      # @param _sequence [Array<Hash, Step>]
+      # @raise [Pbt::InvalidConfiguration]
+      def run_in_ractor(_sequence)
+        raise Pbt::InvalidConfiguration, "Pbt.stateful does not support worker: :ractor yet; use worker: :none"
+      end
+
+      # Run the command sequence against a fresh SUT and verify each step.
+      #
+      # @param sequence [Array<Hash, Step>]
+      # @return [void]
+      def run(sequence)
+        state = @model.initial_state
+        sut = @sut_factory.call
+
+        sequence.each_with_index do |step, index|
+          command, args = unpack_step(step)
+          validate_command_protocol!(command, state:, context: "run step #{index}")
+
+          unless applicable?(command, state, args, context: "run step #{index}")
+            raise "invalid stateful sequence at step #{index}: #{command_name(command)}"
+          end
+
+          before_state = state
+
+          begin
+            after_state = command.next_state(before_state, args)
+            result = command.run!(sut, args)
+            command.verify!(
+              before_state:,
+              after_state:,
+              args:,
+              result:,
+              sut:
+            )
+          rescue Exception => e # standard:disable Lint/RescueException:
+            raise e.class,
+              "stateful step #{index} (#{command_name(command)}): #{e.message} [args=#{args.inspect}]",
+              e.backtrace
+          end
+
+          state = after_state
+        end
+      end
+
+      private
+
+      # @param step [Hash, Step]
+      # @return [Array<Object, Object>]
+      def unpack_step(step)
+        case step
+        in Step(command:, args:)
+          [command, args]
+        in {command:, args:}
+          [command, args]
+        else
+          raise ArgumentError, "invalid stateful step: #{step.inspect}"
+        end
+      end
+
+      # @param command [Object]
+      # @return [String]
+      def command_name(command)
+        command.respond_to?(:name) ? command.name.to_s : (command.class.name || command.class.inspect)
+      end
+
+      # @param model [Object]
+      # @return [void]
+      def validate_model!(model)
+        missing_methods = %i[initial_state commands].reject { |method_name| model.respond_to?(method_name) }
+        return if missing_methods.empty?
+
+        raise Pbt::InvalidConfiguration,
+          "Pbt.stateful model must respond to #{missing_methods.join(", ")}"
+      end
+
+      # @param state [Object]
+      # @param context [String]
+      # @return [Array<Object>]
+      def commands_for(state, context:)
+        commands = @model.commands(state)
+
+        unless commands.is_a?(Array)
+          raise Pbt::InvalidConfiguration,
+            "Pbt.stateful model.commands(state) must return Array, got #{commands.class} (context=#{context})"
+        end
+
+        commands.each { |command| validate_command_protocol!(command, state:, context:) }
+        commands
+      end
+
+      # @param command [Object]
+      # @param state [Object]
+      # @param context [String]
+      # @return [void]
+      def validate_command_protocol!(command, state:, context:)
+        missing_methods = REQUIRED_COMMAND_METHODS.reject { |method_name| command.respond_to?(method_name) }
+        unless missing_methods.empty?
+          raise Pbt::InvalidConfiguration,
+            "Pbt.stateful command protocol mismatch for #{command.class} " \
+            "(name=#{safe_command_label(command)}, missing: #{missing_methods.join(", ")}, context=#{context})"
+        end
+      end
+
+      # @param command [Object]
+      # @param arguments [Object]
+      # @param context [String]
+      # @return [void]
+      def validate_arguments_protocol!(command, arguments, context:)
+        missing_methods = %i[generate shrink].reject { |method_name| arguments.respond_to?(method_name) }
+        return if missing_methods.empty?
+
+        raise Pbt::InvalidConfiguration,
+          "Pbt.stateful command arguments protocol mismatch for #{command.class} " \
+          "(name=#{safe_command_label(command)}, missing: #{missing_methods.join(", ")}, context=#{context})"
+      end
+
+      # @param command [Object]
+      # @return [String]
+      def safe_command_label(command)
+        command.respond_to?(:name) ? command.name.inspect : "<unknown>"
+      end
+
+      # @param state [Object]
+      # @param rng [Random]
+      # @param context [String]
+      # @return [Array<Array<Object, Object>>]
+      def generate_candidates_for(state, rng, context:)
+        commands_for(state, context:).filter_map do |command|
+          args = generate_applicable_args(command, state, rng, context:)
+          next if args.equal?(NoApplicableArgs)
+
+          [command, args]
+        end
+      end
+
+      # @param command [Object]
+      # @param state [Object]
+      # @param rng [Random]
+      # @param context [String]
+      # @return [Object]
+      def generate_applicable_args(command, state, rng, context:)
+        arbitrary = arbitrary_for(command, state, context:)
+
+        ARG_AWARE_GENERATION_ATTEMPTS.times do
+          args = generate_args_for(command, arbitrary, rng)
+          return NoApplicableArgs if args.equal?(NoApplicableArgs)
+
+          return args if applicable?(command, state, args, context:)
+        end
+
+        NoApplicableArgs
+      end
+
+      # @param command [Object]
+      # @param state [Object]
+      # @param context [String]
+      # @return [Object]
+      def arguments_for(command, state, context:)
+        command.arguments(state)
+      end
+
+      # @param command [Object]
+      # @param state [Object]
+      # @param context [String]
+      # @return [Object]
+      def arbitrary_for(command, state, context:)
+        arguments = arguments_for(command, state, context:)
+        validate_arguments_protocol!(command, arguments, context:)
+        arguments
+      end
+
+      # @param command [Object]
+      # @param arbitrary [Object]
+      # @param rng [Random]
+      # @return [Object]
+      def generate_args_for(command, arbitrary, rng)
+        arbitrary.generate(rng)
+      rescue Pbt::Arbitrary::EmptyDomainError
+        NoApplicableArgs
+      end
+
+      # @param command [Object]
+      # @param state [Object]
+      # @param args [Object]
+      # @param context [String]
+      # @return [Boolean]
+      def applicable?(command, state, args, context:)
+        command.applicable?(state, args)
+      end
+
+      # @param sequence [Array<Hash, Step>]
+      # @param index [Integer]
+      # @param command [Object]
+      # @param args [Object]
+      # @return [Array<Hash, Step>]
+      def replace_step(sequence, index, command:, args:)
+        candidate = sequence.dup
+        candidate[index] = rebuild_step(sequence[index], command:, args:)
+        candidate
+      end
+
+      # @param step [Hash, Step]
+      # @param command [Object]
+      # @param args [Object]
+      # @return [Hash, Step]
+      def rebuild_step(step, command:, args:)
+        case step
+        in Step
+          Step.new(command:, args:)
+        in Hash
+          {command:, args:}
+        else
+          raise ArgumentError, "invalid stateful step: #{step.inspect}"
+        end
+      end
+
+      # @param sequence [Array<Hash, Step>]
+      # @return [Boolean]
+      def valid_sequence?(sequence)
+        state = @model.initial_state
+
+        sequence.each do |step|
+          command, args = unpack_step(step)
+          return false unless applicable?(command, state, args, context: "validate sequence")
+
+          state = command.next_state(state, args)
+        end
+
+        true
+      rescue
+        false
+      end
+
+      # @param y [Enumerator::Yielder]
+      # @param seen [Hash{Array<Hash, Step> => true}]
+      # @param candidate [Array<Hash, Step>]
+      # @return [void]
+      def yield_shrink_candidate(y, seen, candidate)
+        return if seen[candidate]
+
+        seen[candidate] = true
+        y << candidate
+      end
+
+      NoApplicableArgs = Object.new
+      private_constant :NoApplicableArgs
+    end
+  end
+end

data/lib/pbt/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Pbt
-  VERSION = "0.5.1"
+  VERSION = "0.7.0"
 end

data/lib/pbt.rb

@@ -5,6 +5,7 @@ require_relative "pbt/arbitrary/arbitrary_methods"
 require_relative "pbt/check/runner_methods"
 require_relative "pbt/check/property"
 require_relative "pbt/check/configuration"
+require_relative "pbt/stateful/property"
 
 module Pbt
   # Represents a property-based test failure.
@@ -44,6 +45,29 @@ module Pbt
     Check::Property.new(arb, &predicate)
   end
 
+  # Create a stateful property-based test backed by a model and a SUT factory.
+  # The returned object is compatible with `Pbt.assert` / `Pbt.check`.
+  #
+  # The model object is expected to provide:
+  # - `initial_state`
+  # - `commands(state)` -> Array of command objects
+  #
+  # Each command object is expected to provide:
+  # - `name`
+  # - `arguments` (an arbitrary) or `arguments(state)`
+  # - `applicable?(state)` -> bool or `applicable?(state, args)` -> bool
+  # - `next_state(state, args)`
+  # - `run!(sut, args)` -> result
+  # - `verify!(before_state:, after_state:, args:, result:, sut:)`
+  #
+  # @param model [Object]
+  # @param sut [Proc] Factory proc that returns a fresh SUT per run.
+  # @param max_steps [Integer]
+  # @return [Pbt::Stateful::Property]
+  def self.stateful(model:, sut:, max_steps: 20)
+    Stateful::Property.new(model:, sut:, max_steps:)
+  end
+
   class << self
     private
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pbt
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.7.0
 platform: ruby
 authors:
 - ohbarye
@@ -18,6 +18,7 @@ files:
 - ".rspec"
 - ".standard.yml"
 - CHANGELOG.md
+- CLAUDE.md
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
 - README.md
@@ -50,6 +51,7 @@ files:
 - lib/pbt/reporter/run_details.rb
 - lib/pbt/reporter/run_details_reporter.rb
 - lib/pbt/reporter/run_execution.rb
+- lib/pbt/stateful/property.rb
 - lib/pbt/version.rb
 - sig/pbt.rbs
 homepage: https://github.com/ohbarye/pbt
@@ -73,7 +75,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Property-Based Testing tool for Ruby, utilizing Ractor for parallelizing
   test cases.