pbt 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f0585c0152a9703256b3265830dd9105b33ebc65877555517af3ad643a6b8839
-  data.tar.gz: ac62f147919ac2e68642d70d9e0bb9d2c8010ef54b2aefc4d6c679fe1b9d7197
+  metadata.gz: 3f0aceef7e66e5512062e15dc72d8bf97617bf99f8c800b320381ef4e48562ab
+  data.tar.gz: ff29061f4878170a57e1ce919cee6f065548349c876343c376e22047ef63c5c4
 SHA512:
-  metadata.gz: 54535a35fa3097b1fe3f4893f83ef9c646598b385c9d4c32f3eb2686aab3727ca22154a87edef748f94090682acee6f7090ecb4d51233e66e861b30bd20df0d3
-  data.tar.gz: e8126c1c5f1b044d83f66b6d0a734783d2843f16f0b24f9a1172797e5b144a630a26c642bfc606f57de9911935f1b25ff0c1d8af48ef92486680c80e264308b0
+  metadata.gz: 68e5b018aaceebd522d8ef3f7e3837bc469b0a4513fd0e8e4080a01b637ca219694d9605c38752f60eb5cde1ee414c5116c0e153a8077ac1d9f8d28aa8ab3ef5
+  data.tar.gz: 26e75baa90dfe41b0a8b0bcd625e8b39c69480e0a2343daca161ce0100fd6c72386c62d9c0a2afb5072c4baec39b4ccc41b499e650080093fad187791e883c60

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 ## [Unreleased]
 
+## [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

@@ -140,6 +140,99 @@ Pbt.one_of(:a, 1, 0.1).generate(rng)                        # => :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
+    Pbt.nil
+  end
+
+  def applicable?(_state)
+    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` (a `Pbt` arbitrary)
+- `command.applicable?(state)` -> `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.

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
@@ -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/integer_arbitrary.rb

@@ -17,6 +17,10 @@ module Pbt
       # @see Arbitrary#generate
       def generate(rng)
         rng.rand(@min..@max)
+      rescue ArgumentError => e
+        raise EmptyDomainError, e.message if @min > @max
+
+        raise
       end
 
       # @see Arbitrary#shrink

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,455 @@
+# 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)
+        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
+
+        validate_command_signature!(command, :arguments, valid_counts: [0, 1], expectation: "arguments or arguments(state)",
+          context:)
+        validate_command_signature!(command, :applicable?, valid_counts: [1, 2],
+          expectation: "applicable?(state) or applicable?(state, args)", context:)
+      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:)
+        unless arg_aware_command?(command)
+          return NoApplicableArgs unless applicable?(command, state, nil, context:)
+
+          return arbitrary_for(command, state, context:).generate(rng)
+        end
+
+        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:)
+        method = command.method(:arguments)
+
+        if supports_argument_count?(method, 1)
+          command.arguments(state)
+        elsif supports_argument_count?(method, 0)
+          command.arguments
+        else
+          raise_invalid_signature!(command, :arguments, "arguments or arguments(state)", context)
+        end
+      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
+        raise unless state_aware_arg_aware_command?(command)
+
+        NoApplicableArgs
+      end
+
+      # @param command [Object]
+      # @param state [Object]
+      # @param args [Object]
+      # @param context [String]
+      # @return [Boolean]
+      def applicable?(command, state, args, context:)
+        method = command.method(:applicable?)
+
+        if supports_argument_count?(method, 2)
+          command.applicable?(state, args)
+        elsif supports_argument_count?(method, 1)
+          command.applicable?(state)
+        else
+          raise_invalid_signature!(command, :applicable?, "applicable?(state) or applicable?(state, args)", context)
+        end
+      end
+
+      # @param command [Object]
+      # @return [Boolean]
+      def arg_aware_command?(command)
+        supports_argument_count?(command.method(:applicable?), 2)
+      end
+
+      # @param command [Object]
+      # @return [Boolean]
+      def state_aware_arg_aware_command?(command)
+        arg_aware_command?(command) && supports_argument_count?(command.method(:arguments), 1)
+      end
+
+      # @param command [Object]
+      # @param method_name [Symbol]
+      # @param valid_counts [Array<Integer>]
+      # @param expectation [String]
+      # @param context [String]
+      # @return [void]
+      def validate_command_signature!(command, method_name, valid_counts:, expectation:, context:)
+        method = command.method(method_name)
+        return if valid_counts.any? { |count| supports_argument_count?(method, count) }
+
+        raise_invalid_signature!(command, method_name, expectation, context)
+      end
+
+      # @param command [Object]
+      # @param method_name [Symbol]
+      # @param expectation [String]
+      # @param context [String]
+      # @return [void]
+      def raise_invalid_signature!(command, method_name, expectation, context)
+        raise Pbt::InvalidConfiguration,
+          "Pbt.stateful command protocol mismatch for #{command.class} " \
+          "(name=#{safe_command_label(command)}, invalid #{method_name} signature; expected #{expectation}, context=#{context})"
+      end
+
+      # @param method [Method]
+      # @param count [Integer]
+      # @return [Boolean]
+      def supports_argument_count?(method, count)
+        return false if method.parameters.any? { |kind, _name| keyword_parameter?(kind) }
+
+        required = 0
+        optional = 0
+        rest = false
+
+        method.parameters.each do |kind, _name|
+          case kind
+          when :req
+            required += 1
+          when :opt
+            optional += 1
+          when :rest
+            rest = true
+          end
+        end
+
+        return false if count < required
+        return true if rest
+
+        count <= required + optional
+      end
+
+      # @param kind [Symbol]
+      # @return [Boolean]
+      def keyword_parameter?(kind)
+        %i[keyreq key keyrest].include?(kind)
+      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.6.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.6.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.