statecraft 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 55f4ecb6760d01b042ad158351ec8735c3962c70c3a674d3af9d6ba2ecf26fd9
-  data.tar.gz: ecc0c3ac410d67431226ccc8b361ac5d2708c276425153561b0f732ef3aefa53
+  metadata.gz: 5e98ec25e4cfbb6cec172cd1f54ac9362937c967eff450ccda67d414e2dce6d3
+  data.tar.gz: e8f112727ef007ad0d6d3e91e67c122298bbf1d403f09aa9e2aeda56e43545da
 SHA512:
-  metadata.gz: caf25d1b5349c441aa79573e1994b2298ef64fcc4b4b9f6e6b5958827ca03a9bf8275366cf1b128a4cf39f690e6ba9bcad0327b040a51effcf42f5fff9853098
-  data.tar.gz: 7acc79611c73b980a2a932c53d87723068adb1da7ddc61b590477cf84540a904750e9fa7d550d126aa9626f9edcc34538f6aed4aacb611894907148d80e07b63
+  metadata.gz: ed3978c9e0098cfc1ed4a19b933ce2a134e8841385e0e9542c267e43b6095f81c2b97b230a40d04605d0618717b3af289716157c3ab029f85b30886c54a11cb5
+  data.tar.gz: 626c429ccc91fc9f40401e58ab6142b81544684d57890fb0f51cec79d901e6280d06e2a14afb0400bb6d592faf33e5dbab5ef7c09045e4435b8557dd2162fb73

data/README.md

@@ -210,6 +210,70 @@ through untouched: those errors mean "restart the whole transaction", a
 different protocol than the conflict's "continue from clean state", and the
 retry policy belongs to whoever chose the isolation level.
 
+## Stale transitions: versioning against ABA
+
+The CAS above compares the state's *value* — so a state that went away and
+came back (`pending → paid → … → pending`) passes for the state an open
+page rendered minutes ago. That is the ABA problem, and `versioning: true`
+closes it:
+
+<!-- illustrative -->
+```ruby
+class Order < ApplicationRecord
+  state_machine OrderFlow, versioning: true  # the state_version column
+end
+```
+
+With the option every transition compares-and-swaps on the *pair* of state
+and version and increments the version in the same UPDATE — a returned
+state no longer matches, even without any token. `true` names the column
+`<column>_version`; a symbol overrides the name. The column is a plain
+`bigint NOT NULL DEFAULT 0`: `rails g statecraft:machine Order --versioning`
+generates it, and for an existing table one step is enough — on
+PostgreSQL 11+ an `add_column` with a constant default is metadata-only,
+no table rewrite:
+
+<!-- illustrative -->
+```ruby
+add_column :orders, :state_version, :bigint, null: false, default: 0
+```
+
+The user-facing half is the `seen:` token: render the version into the
+form, send it back, and the pipeline refuses the action when the row has
+moved on — `Statecraft::StaleTransition`, a `TransitionConflict` subclass
+carrying `expected_version` and `seen`, published as reason `:stale`:
+
+<!-- illustrative -->
+```erb
+<input type="hidden" name="seen" value="<%= order.state_version %>">
+```
+
+<!-- illustrative -->
+```ruby
+def cancel
+  order = Order.find(params[:id])
+  order.cancel!(metadata: cancel_metadata, seen: params[:seen])
+  redirect_to order_path(order), notice: "Cancelled."
+rescue Statecraft::StaleTransition
+  head :conflict  # the API mapping: 409
+  # a form flow redirects instead:
+  # redirect_to order_path(order),
+  #             alert: "This order changed while the page was open."
+end
+```
+
+`seen:` rides all four surface forms and the helper verbs. A string token
+straight from params is fine — the pipeline normalizes it with `Integer()`,
+and garbage raises `ArgumentError` loudly. The honest limits: staleness
+exists only where a token was given — without `seen:` a version mismatch
+is the ordinary `TransitionConflict`; the early deterministic check runs
+only under `lock: true`, where the reload holds the row's real version —
+without the lock the CAS itself is the check, since a fresh token can
+outrun a stale in-memory record; and `seen:` on a mounting without
+`versioning:` raises a `CompilationError` naming the fix instead of
+silently skipping the protection. Reads stay join-free: the version lives
+on the parent row, right next to the state.
+
 ## Introspection
 
 <!-- illustrative -->
@@ -260,6 +324,51 @@ belong to the application's presentation layer, not to the machine.
 A guard that reads metadata makes `may_*?` depend on the metadata you pass —
 pass the same metadata to `may_*?` that you will collect for `fire!`.
 
+## RSpec matchers
+
+One opt-in require gives your specs matchers over the whole introspection
+surface — RSpec never becomes a runtime dependency of the gem:
+
+<!-- illustrative -->
+```ruby
+# spec_helper.rb, after rspec itself is loaded
+require "statecraft/rspec"
+```
+
+<!-- illustrative -->
+```ruby
+# The record-level questions consult the guards, with the same metadata
+# your production call will carry:
+expect(order).to allow_event(:pay).with_metadata("amount" => 100)
+expect(order).to allow_transition_to(:cancelled).via(:cancel)
+expect(order).to allow_transition_to(:archived).directly
+expect(order).to have_transitioned_to(:paid)  # strictly log-based
+
+# The refusal with its reason — guard names come from refusals_for:
+expect(order).to refuse_event(:cancel).because_of(:customer_cancellable?)
+
+# The class-level pair answers the graph's shape; guards stay untouched:
+expect(OrderFlow).to have_edge(:pending, :cancelled).via(:cancel)
+expect(OrderFlow).to have_initial_state(:pending)
+
+# The transition itself: the state move AND the appended log row,
+# asserted in one expression around fire!/transition_to!:
+expect { order.fire!(:pay, metadata: { "amount" => 100 }) }
+  .to transition(order).from(:pending).to(:paid)
+      .via_event(:pay).with_metadata("amount" => 100)
+```
+
+A failing matcher explains itself with the same introspection the pipeline
+consults: the current state, the edges reachable from it, and the refusing
+guard with its layer. A non-bang call that returned `false` fails the
+`transition` matcher the same way; exceptions of the bang forms fly through
+like with `change` — assert refusals with `refuse_event` or `raise_error`,
+not with the block matcher.
+
+`because_of` carries the same honest limit as `refusals_for` underneath it:
+it names record-layer guards only. An input-reading `guard:` has no name
+there, and the failure message says so instead of guessing.
+
 ## Metadata
 
 Metadata is normalized on pipeline entry with a full JSON round-trip —
@@ -599,7 +708,7 @@ actions over services, guard refusals local to their form:
       @order = Order.find(params[:id])
       authorize! event_name, @order
       @metadata = submitted_metadata
-      @order.fire!(event_name, metadata: @metadata)
+      @order.fire!(event_name, metadata: @metadata, seen: params[:seen].presence)
       redirect_to admin_order_path(@order),
                   notice: "#{event_name} fired: the order is now #{@order[:state]}."
     rescue Statecraft::GuardFailed => error
@@ -623,6 +732,7 @@ possibility-times-permission intersection:
 <!-- readme: preview-pattern -->
 ```erb
 <%= form_with url: preview_admin_order_path(@order), method: :post, local: true do %>
+  <input type="hidden" name="seen" value="<%= @order[:state_version] %>">
   <fieldset>
     <legend>Metadata for the next action</legend>
     <label>
@@ -660,13 +770,12 @@ ActiveSupport::Notifications.subscribe("transition.statecraft") do |_name, _star
   )
 end
 
+# The failure payload names the record, the machine and the reason — it
+# carries no from/to/event keys: the transition never happened.
 ActiveSupport::Notifications.subscribe("transition_failed.statecraft") do |_name, _started, _finished, _id, payload|
   OperationEntry.create!(
     record_class: payload[:record_class],
     record_id: payload[:record_id].to_s,
-    from_state: payload[:from],
-    to_state: payload[:to],
-    event_name: payload[:event],
     outcome: "refused",
     reason: payload[:reason].to_s
   )

data/lib/generators/statecraft/machine/USAGE

@@ -13,8 +13,13 @@ Description:
     migration lands in the migrations_paths configured for that database
     (db/migrate when none is configured).
 
+    With --versioning the migration also adds a state_version column and
+    the mounting carries versioning: true — a tagged CAS that refuses
+    stale seen: tokens with Statecraft::StaleTransition.
+
 Example:
     bin/rails generate statecraft:machine Order
+    bin/rails generate statecraft:machine Order --versioning
     bin/rails generate statecraft:machine Shop::Order
 
     This will create:

data/lib/generators/statecraft/machine/machine_generator.rb

@@ -18,6 +18,10 @@ module Statecraft
 
       source_root File.expand_path("templates", __dir__)
 
+      class_option :versioning, type: :boolean, default: false,
+                                desc: "Add a state_version column and mount with versioning: " \
+                                      "true — a tagged CAS that refuses stale seen: tokens"
+
       def detect_model_presence
         @existing_model = File.exist?(File.join(destination_root, model_file))
       end
@@ -71,7 +75,17 @@ module Statecraft
       end
 
       def mounting_line
-        "  state_machine #{class_name}Flow, changed_at: true, helpers: true, scopes: true\n"
+        "  state_machine #{class_name}Flow, #{mounting_options}\n"
+      end
+
+      def mounting_options
+        options_list = ["changed_at: true"]
+        options_list << "versioning: true" if options[:versioning]
+        (options_list + ["helpers: true", "scopes: true"]).join(", ")
+      end
+
+      def versioning?
+        options[:versioning]
       end
 
       # inject_into_class matches the literal `class <name>` line, so the name

data/lib/generators/statecraft/machine/templates/add_migration.rb.tt

@@ -5,6 +5,9 @@ class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Mi
     add_column :<%= table_name %>, :state, :string, null: false, default: "pending"
     add_index :<%= table_name %>, :state
     add_column :<%= table_name %>, :state_changed_at, :datetime
+<% if versioning? -%>
+    add_column :<%= table_name %>, :state_version, :bigint, null: false, default: 0
+<% end -%>
 
     # The existing table may carry legacy values, so no CHECK constraint is
     # generated here. To add one later without blocking writes:

data/lib/generators/statecraft/machine/templates/create_migration.rb.tt

@@ -5,6 +5,9 @@ class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Mi
     create_table :<%= table_name %> do |t|
       t.string :state, null: false, default: "pending", index: true
       t.datetime :state_changed_at
+<% if versioning? -%>
+      t.bigint :state_version, null: false, default: 0
+<% end -%>
       t.timestamps null: false
     end
 

data/lib/generators/statecraft/machine/templates/model.rb.tt

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class <%= class_name %> < ApplicationRecord
-  state_machine <%= class_name %>Flow, changed_at: true, helpers: true, scopes: true
+  state_machine <%= class_name %>Flow, <%= mounting_options %>
 end

data/lib/statecraft/errors.rb

@@ -38,11 +38,26 @@ module Statecraft
   class TransitionConflict < Error
     attr_reader :record, :expected_from
 
-    def initialize(record:, expected_from:)
+    def initialize(record:, expected_from:, message: nil)
       @record = record
       @expected_from = expected_from
-      super("concurrent update detected for #{record.class.name}##{record.id}: " \
-            "expected state #{expected_from.inspect}, another writer got there first")
+      super(message || "concurrent update detected for #{record.class.name}##{record.id}: " \
+                       "expected state #{expected_from.inspect}, another writer got there first")
+    end
+  end
+
+  # The refusal of a seen: token: the snapshot the caller acted on is no
+  # longer the row's version. A subclass of TransitionConflict, so existing
+  # rescues keep catching it; controllers map it to 409 specifically.
+  class StaleTransition < TransitionConflict
+    attr_reader :expected_version, :seen
+
+    def initialize(record:, expected_from:, expected_version:, seen:)
+      @expected_version = expected_version
+      @seen = seen
+      super(record: record, expected_from: expected_from,
+            message: "stale transition for #{record.class.name}##{record.id}: " \
+                     "the caller saw version #{seen.inspect}, but the row has moved on")
     end
   end
 

data/lib/statecraft/mounting.rb

@@ -10,16 +10,17 @@ module Statecraft
   # in_state?). Everything internal goes through base_class.
   module Mounting
     Configuration = Struct.new(
-      :machine_class, :log_class, :column, :changed_at_column, :touch, :helpers, :scopes,
-      :log_foreign_key,
+      :machine_class, :log_class, :column, :changed_at_column, :version_column, :touch,
+      :helpers, :scopes, :log_foreign_key,
       keyword_init: true
     )
 
-    def state_machine(machine_class, log: nil, column: :state, changed_at: false, touch: true,
-                      helpers: false, scopes: false)
+    def state_machine(machine_class, log: nil, column: :state, changed_at: false,
+                      versioning: false, touch: true, helpers: false, scopes: false)
       Builder.new(
         model: self, machine_class: machine_class, log: log, column: column,
-        changed_at: changed_at, touch: touch, helpers: helpers, scopes: scopes
+        changed_at: changed_at, versioning: versioning, touch: touch,
+        helpers: helpers, scopes: scopes
       ).mount
     end
 
@@ -27,16 +28,20 @@ module Statecraft
     # class hierarchies only — never on the schema and never on a live
     # connection, so mounting is safe at load time.
     class Builder
-      def initialize(model:, machine_class:, log:, column:, changed_at:, touch:, helpers:, scopes:)
+      # rubocop:disable Metrics/ParameterLists -- mirrors state_machine's kwargs one-to-one
+      def initialize(model:, machine_class:, log:, column:, changed_at:, versioning:, touch:,
+                     helpers:, scopes:)
         @model = model
         @machine_class = machine_class
         @log_option = log
         @column = column
         @changed_at = changed_at
+        @versioning = versioning
         @touch = touch
         @helpers = helpers
         @scopes = scopes
       end
+      # rubocop:enable Metrics/ParameterLists
 
       def mount
         assert_not_mounted
@@ -132,6 +137,7 @@ module Statecraft
           log_class: log_class,
           column: @column.to_sym,
           changed_at_column: resolve_changed_at_column,
+          version_column: resolve_version_column,
           touch: @touch,
           helpers: @helpers,
           scopes: @scopes,
@@ -147,6 +153,14 @@ module Statecraft
         end
       end
 
+      def resolve_version_column
+        case @versioning
+        when false then nil
+        when true then :"#{@column}_version"
+        else @versioning.to_sym
+        end
+      end
+
       def store_configuration(configuration)
         model.define_singleton_method(:statecraft_mounting) { configuration }
       end
@@ -163,8 +177,12 @@ module Statecraft
       def define_verbs(graph)
         verbs = Module.new do
           graph.events.each_key do |event_name|
-            define_method("#{event_name}!") { |metadata: {}| fire!(event_name, metadata: metadata) }
-            define_method(event_name) { |metadata: {}| fire(event_name, metadata: metadata) }
+            define_method("#{event_name}!") do |metadata: {}, seen: nil|
+              fire!(event_name, metadata: metadata, seen: seen)
+            end
+            define_method(event_name) do |metadata: {}, seen: nil|
+              fire(event_name, metadata: metadata, seen: seen)
+            end
             define_method("may_#{event_name}?") { |metadata: {}| can_fire?(event_name, metadata: metadata) }
           end
         end

data/lib/statecraft/pipeline/surface.rb

@@ -5,24 +5,24 @@ module Statecraft
     # The record-facing API mixed into the model at mounting time. Bang
     # variants return the created log record; non-bang variants return it too,
     # or false on GuardFailed / InvalidTransition. Programmer errors and
-    # TransitionConflict always raise.
+    # TransitionConflict — StaleTransition included — always raise.
     module Surface
-      def transition_to!(to_state, metadata: {}, bypass_events: false)
-        Pipeline.new(self).direct(to_state, metadata: metadata, bypass_events: bypass_events)
+      def transition_to!(to_state, metadata: {}, bypass_events: false, seen: nil)
+        Pipeline.new(self).direct(to_state, metadata: metadata, bypass_events: bypass_events, seen: seen)
       end
 
-      def transition_to(to_state, metadata: {}, bypass_events: false)
-        transition_to!(to_state, metadata: metadata, bypass_events: bypass_events)
+      def transition_to(to_state, metadata: {}, bypass_events: false, seen: nil)
+        transition_to!(to_state, metadata: metadata, bypass_events: bypass_events, seen: seen)
       rescue GuardFailed, InvalidTransition
         false
       end
 
-      def fire!(event_name, metadata: {})
-        Pipeline.new(self).fire(event_name, metadata: metadata)
+      def fire!(event_name, metadata: {}, seen: nil)
+        Pipeline.new(self).fire(event_name, metadata: metadata, seen: seen)
       end
 
-      def fire(event_name, metadata: {})
-        fire!(event_name, metadata: metadata)
+      def fire(event_name, metadata: {}, seen: nil)
+        fire!(event_name, metadata: metadata, seen: seen)
       rescue GuardFailed, InvalidTransition
         false
       end

data/lib/statecraft/pipeline/versioning.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Statecraft
+  class Pipeline
+    # The tagged half of the CAS: when the mounting carries versioning, every
+    # transition compares-and-swaps on (state, version) and increments the
+    # version in the same UPDATE. A seen: token substitutes the compared
+    # value with what the caller's form actually rendered, and its refusal is
+    # StaleTransition — the 409 of the pipeline.
+    module Versioning
+      private
+
+      def version_column
+        column = configuration.version_column
+        return nil unless column
+
+        unless record.class.column_names.include?(column.to_s)
+          raise CompilationError,
+                "versioning column #{column} does not exist on #{record.class.table_name}; " \
+                "add the column or drop the versioning option"
+        end
+        column
+      end
+
+      def normalize_seen(raw_seen)
+        return nil if raw_seen.nil?
+
+        unless configuration.version_column
+          raise CompilationError,
+                "seen: requires versioning: true on the mounting of #{record.class.name}; " \
+                "add the option or drop the token"
+        end
+        Integer(raw_seen)
+      end
+
+      # What the CAS requires the row's version to be: the caller's seen:
+      # token when given, the in-memory value otherwise — fresh after a lock
+      # reload, synced by the previous link inside a chain.
+      def expected_version
+        @seen || record[version_column]
+      end
+
+      # With a seen: token any versioned refusal is staleness — the caller
+      # acted on a snapshot; without one it is the ordinary conflict of two
+      # writers.
+      def cas_refusal(edge)
+        if @seen
+          StaleTransition.new(record: record, expected_from: edge.from,
+                              expected_version: expected_version, seen: @raw_seen)
+        else
+          TransitionConflict.new(record: record, expected_from: edge.from)
+        end
+      end
+
+      # The same early observation as assert_lock_saw_expected_state, for the
+      # seen: token: the reload holds the row's real version under the lock,
+      # so a mismatched token is a stale snapshot detected deterministically,
+      # before any write.
+      def assert_lock_saw_expected_version(edge)
+        return unless @seen && version_column
+        return if record[version_column] == @seen
+
+        raise StaleTransition.new(record: record, expected_from: edge.from,
+                                  expected_version: @seen, seen: @raw_seen)
+      end
+    end
+  end
+end

data/lib/statecraft/pipeline.rb

@@ -29,6 +29,7 @@ module Statecraft
     MAX_CHAIN_DEPTH = 16
 
     include EdgeResolution
+    include Versioning
 
     def self.transition_stack
       ActiveSupport::IsolatedExecutionState[STACK_KEY] ||= []
@@ -41,15 +42,15 @@ module Statecraft
       @machine_instance = @configuration.machine_class.new
     end
 
-    def direct(to_state, metadata:, bypass_events:)
-      run(metadata) do |current_state|
+    def direct(to_state, metadata:, bypass_events:, seen: nil)
+      run(metadata, seen: seen) do |current_state|
         edge = resolve_direct_edge(current_state, to_state.to_sym, bypass_events)
         [edge, nil, bypass_events]
       end
     end
 
-    def fire(event_name, metadata:)
-      run(metadata) do |current_state|
+    def fire(event_name, metadata:, seen: nil)
+      run(metadata, seen: seen) do |current_state|
         edge = resolve_event_edge(current_state, event_name.to_sym)
         [edge, event_name.to_sym, false]
       end
@@ -59,10 +60,12 @@ module Statecraft
 
     attr_reader :record, :configuration, :graph, :machine_instance
 
-    def run(raw_metadata, &edge_resolver)
+    def run(raw_metadata, seen: nil, &edge_resolver)
       raise UnsavedRecordError.new(record: record) unless record.persisted?
 
       assert_single_column_primary_key
+      @raw_seen = seen
+      @seen = normalize_seen(seen)
       metadata = Metadata.normalize(raw_metadata)
       started_at = Time.current
       begin
@@ -91,6 +94,7 @@ module Statecraft
         case error
         when GuardFailed then [:guard_failed, { guard: error.guard }]
         when InvalidTransition then [:invalid_transition, { requested: error.requested }]
+        when StaleTransition then [:stale, { expected_version: error.expected_version, seen: error.seen }]
         when TransitionConflict then [:conflict, { expected_from: error.expected_from }]
         end
       Instrumentation.publish_failure(
@@ -105,6 +109,7 @@ module Statecraft
           warn_when_row_locking_unavailable
           record.reload(lock: true)
           assert_lock_saw_expected_state(edge)
+          assert_lock_saw_expected_version(edge)
         end
         transition_time = Time.current
         run_guards(edge, event, bypass, metadata)
@@ -204,17 +209,21 @@ module Statecraft
     end
 
     def cas_update!(edge, transition_time)
-      affected_rows = base_class.unscoped
-                                .where(base_class.primary_key => record.id,
-                                       configuration.column => edge.from.to_s)
-                                .update_all(cas_updates(edge, transition_time))
-      raise TransitionConflict.new(record: record, expected_from: edge.from) if affected_rows.zero?
+      scope = base_class.unscoped
+                        .where(base_class.primary_key => record.id,
+                               configuration.column => edge.from.to_s)
+      scope = scope.where(version_column => expected_version) if version_column
+      affected_rows = scope.update_all(cas_updates(edge, transition_time))
+      raise cas_refusal(edge) if affected_rows.zero?
     end
 
     def cas_updates(edge, transition_time)
       updates = { configuration.column => edge.to.to_s }
       updates[:updated_at] = transition_time if touch_updated_at?
       updates[changed_at_column] = transition_time if changed_at_column
+      # The literal is correct by construction: the CAS WHERE guarantees the
+      # row held exactly expected_version, so the memory mirror stays exact.
+      updates[version_column] = expected_version + 1 if version_column
       updates
     end
 

data/lib/statecraft/rspec/allow_event.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Statecraft
+  module RSpec
+    # expect(record).to allow_event(:pay).with_metadata("amount" => 5)
+    #
+    # The can_fire? question, asked with the same metadata the production
+    # call will carry. The failure message walks the layers the pipeline
+    # walks: is the event declared from this state, and if so, which
+    # guards said no.
+    class AllowEvent
+      def initialize(event_name)
+        @event_name = event_name.to_sym
+        @metadata = {}
+      end
+
+      def with_metadata(metadata)
+        @metadata = metadata
+        self
+      end
+
+      def matches?(record)
+        @record = record
+        record.can_fire?(@event_name, metadata: @metadata)
+      end
+
+      def failure_message
+        lines = ["expected #{StateReport.standing(@record)} to allow event #{@event_name.inspect}, but it was refused"]
+        if StateReport.event_declared?(@record, @event_name)
+          lines << StateReport.refusal(@record, @event_name, @metadata)
+        else
+          lines << "event #{@event_name.inspect} is not declared from #{StateReport.current_state(@record).inspect}"
+          lines << StateReport.declared_shape_of(@record)
+        end
+        lines.join("\n  ")
+      end
+
+      def failure_message_when_negated
+        "expected #{StateReport.standing(@record)} not to allow event #{@event_name.inspect}, " \
+          "but the guards passed with metadata #{@metadata.inspect}"
+      end
+
+      def description
+        "allow event #{@event_name.inspect}"
+      end
+    end
+  end
+end

data/lib/statecraft/rspec/allow_transition_to.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Statecraft
+  module RSpec
+    # expect(record).to allow_transition_to(:paid).via(:pay)
+    # expect(record).to allow_transition_to(:archived).directly
+    #
+    # The available_transitions prediction for one target: not only
+    # whether the record can go there, but HOW — via lists the events
+    # whose guards pass, directly asserts the guard-free direct way.
+    class AllowTransitionTo
+      def initialize(target_state)
+        @target_state = target_state.to_sym
+        @expected_via = []
+        @directly = false
+        @metadata = {}
+      end
+
+      def via(*event_names)
+        @expected_via = event_names.map(&:to_sym)
+        self
+      end
+
+      def directly
+        @directly = true
+        self
+      end
+
+      def with_metadata(metadata)
+        @metadata = metadata
+        self
+      end
+
+      def matches?(record)
+        @record = record
+        @availability = record.available_transitions(metadata: @metadata)
+                              .find { |availability| availability.to == @target_state }
+        return false unless @availability
+
+        missing_ways.empty?
+      end
+
+      def failure_message
+        unless @availability
+          return ["expected #{StateReport.standing(@record)} to reach #{@target_state.inspect}, but it cannot",
+                  StateReport.reachable(@record, @metadata),
+                  StateReport.declared_shape_of(@record)].join("\n  ")
+        end
+
+        "expected the way to #{@target_state.inspect} to include #{missing_ways.map(&:inspect).join(", ")}, " \
+          "but it is reachable via #{@availability.via.inspect}"
+      end
+
+      def failure_message_when_negated
+        "expected #{StateReport.standing(@record)} not to reach #{@target_state.inspect}, " \
+          "but it is reachable via #{@availability.via.inspect}"
+      end
+
+      def description
+        "allow a transition to #{@target_state.inspect}"
+      end
+
+      private
+
+      def missing_ways
+        expected = @expected_via + (@directly ? [:direct] : [])
+        expected - @availability.via
+      end
+    end
+  end
+end

data/lib/statecraft/rspec/have_edge.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Statecraft
+  module RSpec
+    # expect(OrderFlow).to have_edge(:pending, :cancelled).via(:cancel)
+    #
+    # The class-level shape question of transitions_from: no guards are
+    # consulted, exactly like the method itself. via asserts that the
+    # named events ride the edge; a bare edge simply has none.
+    class HaveEdge
+      def initialize(from_state, to_state)
+        @from_state = from_state.to_sym
+        @to_state = to_state.to_sym
+        @expected_events = []
+      end
+
+      def via(*event_names)
+        @expected_events = event_names.map(&:to_sym)
+        self
+      end
+
+      def matches?(machine_class)
+        @machine_class = machine_class
+        @edge = machine_class.transitions_from(@from_state)
+                             .find { |descriptor| descriptor[:to] == @to_state }
+        @edge && (@expected_events - @edge[:events]).empty?
+      end
+
+      def failure_message
+        unless @edge
+          return ["expected #{@machine_class.name} to declare an edge #{@from_state.inspect} -> #{@to_state.inspect}",
+                  StateReport.declared_shape(@machine_class, @from_state)].join("\n  ")
+        end
+
+        missing = (@expected_events - @edge[:events]).map(&:inspect).join(", ")
+        "expected the edge #{@from_state.inspect} -> #{@to_state.inspect} to carry #{missing}, " \
+          "but its events are #{@edge[:events].inspect}"
+      end
+
+      def failure_message_when_negated
+        "expected #{@machine_class.name} not to declare the edge #{@from_state.inspect} -> #{@to_state.inspect}, " \
+          "but it does (events: #{@edge[:events].inspect})"
+      end
+
+      def description
+        "have an edge #{@from_state.inspect} -> #{@to_state.inspect}"
+      end
+    end
+  end
+end

data/lib/statecraft/rspec/have_initial_state.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Statecraft
+  module RSpec
+    # expect(OrderFlow).to have_initial_state(:pending)
+    class HaveInitialState
+      def initialize(state_name)
+        @state_name = state_name.to_sym
+      end
+
+      def matches?(machine_class)
+        @machine_class = machine_class
+        machine_class.initial_state == @state_name
+      end
+
+      def failure_message
+        "expected the initial state of #{@machine_class.name} to be #{@state_name.inspect}, " \
+          "but it is #{@machine_class.initial_state.inspect}"
+      end
+
+      def failure_message_when_negated
+        "expected the initial state of #{@machine_class.name} not to be #{@state_name.inspect}, but it is"
+      end
+
+      def description
+        "have the initial state #{@state_name.inspect}"
+      end
+    end
+  end
+end

data/lib/statecraft/rspec/have_transitioned_to.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Statecraft
+  module RSpec
+    # expect(record).to have_transitioned_to(:paid)
+    #
+    # Strictly log-based, like transitioned_to? itself: the question is
+    # about history, never about the current state. The failure message
+    # shows what the log actually holds.
+    class HaveTransitionedTo
+      def initialize(state_name)
+        @state_name = state_name.to_sym
+      end
+
+      def matches?(record)
+        @record = record
+        record.transitioned_to?(@state_name)
+      end
+
+      def failure_message
+        "expected the log of #{StateReport.standing(@record)} to hold a transition to #{@state_name.inspect}, " \
+          "but #{log_contents}"
+      end
+
+      def failure_message_when_negated
+        "expected the log of #{StateReport.standing(@record)} to hold no transition to #{@state_name.inspect}, " \
+          "but it does"
+      end
+
+      def description
+        "have transitioned to #{@state_name.inspect}"
+      end
+
+      private
+
+      def log_contents
+        to_states = @record.history.map(&:to_state)
+        return "the log is empty" if to_states.empty?
+
+        "the log holds transitions to: #{to_states.join(", ")}"
+      end
+    end
+  end
+end

data/lib/statecraft/rspec/matchers.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Statecraft
+  module RSpec
+    # The example-facing surface: requiring statecraft/rspec includes this
+    # module into every example group, so specs call the factories bare.
+    # Record-level matchers consult guards (a prediction with the metadata
+    # you pass); class-level matchers answer the graph's shape only.
+    # rubocop:disable Naming/PredicatePrefix -- have_* is RSpec's matcher idiom, not a predicate
+    module Matchers
+      def allow_event(event_name)
+        AllowEvent.new(event_name)
+      end
+
+      def refuse_event(event_name)
+        RefuseEvent.new(event_name)
+      end
+
+      def allow_transition_to(target_state)
+        AllowTransitionTo.new(target_state)
+      end
+
+      def have_transitioned_to(state_name)
+        HaveTransitionedTo.new(state_name)
+      end
+
+      def have_edge(from_state, to_state)
+        HaveEdge.new(from_state, to_state)
+      end
+
+      def have_initial_state(state_name)
+        HaveInitialState.new(state_name)
+      end
+
+      def transition(record)
+        Transition.new(record)
+      end
+    end
+    # rubocop:enable Naming/PredicatePrefix
+  end
+end

data/lib/statecraft/rspec/refuse_event.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Statecraft
+  module RSpec
+    # expect(record).to refuse_event(:cancel).because_of(:customer_cancellable?)
+    #
+    # The named negation of allow_event: the refusal itself, and — through
+    # because_of — WHO refused. Guard names come from refusals_for, so
+    # because_of sees record-layer guards only; an input-reading guard:
+    # has no name there, and the failure message says so instead of
+    # pretending otherwise.
+    class RefuseEvent
+      def initialize(event_name)
+        @event_name = event_name.to_sym
+        @expected_guards = []
+        @metadata = {}
+      end
+
+      def because_of(*guard_names)
+        @expected_guards = guard_names.map(&:to_sym)
+        self
+      end
+
+      def with_metadata(metadata)
+        @metadata = metadata
+        self
+      end
+
+      def matches?(record)
+        @record = record
+        @allowed = record.can_fire?(@event_name, metadata: @metadata)
+        return false if @allowed
+
+        @refusing_guards = record.refusals_for(@event_name).map(&:guard)
+        (@expected_guards - @refusing_guards).empty?
+      end
+
+      def failure_message
+        if @allowed
+          return "expected #{StateReport.standing(@record)} to refuse event #{@event_name.inspect}, " \
+                 "but the guards passed with metadata #{@metadata.inspect}"
+        end
+
+        missing = (@expected_guards - @refusing_guards).map(&:inspect).join(", ")
+        "expected the refusal of #{@event_name.inspect} to come from #{missing}\n  #{actual_refusers}"
+      end
+
+      def failure_message_when_negated
+        "expected #{StateReport.standing(@record)} to allow event #{@event_name.inspect}, but it was refused\n  " +
+          StateReport.refusal(@record, @event_name, @metadata)
+      end
+
+      def description
+        "refuse event #{@event_name.inspect}"
+      end
+
+      private
+
+      def actual_refusers
+        if @refusing_guards.empty?
+          "but no record-layer guard refused: refusals_for names record-layer guards only, " \
+            "and this refusal came from an input-reading guard: or an undeclared branch"
+        else
+          "but the refusing record-layer guards were: #{@refusing_guards.map(&:inspect).join(", ")}"
+        end
+      end
+    end
+  end
+end

data/lib/statecraft/rspec/state_report.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Statecraft
+  module RSpec
+    # The shared sentences of every failure message: where the record
+    # stands, what the graph declares from there, what is reachable right
+    # now, and which guards refused. Built strictly on the public
+    # introspection surface — the matchers add words, never new answers.
+    module StateReport
+      module_function
+
+      def current_state(record)
+        record[record.class.statecraft_mounting.column]&.to_sym
+      end
+
+      def standing(record)
+        "#{record.class.name} in state #{current_state(record).inspect}"
+      end
+
+      def machine(record)
+        record.class.statecraft_mounting.machine_class
+      end
+
+      def event_declared?(record, event_name)
+        machine(record).transitions_from(current_state(record))
+                       .any? { |descriptor| descriptor[:events].include?(event_name) }
+      end
+
+      def declared_shape(machine_class, state)
+        descriptors = machine_class.transitions_from(state)
+        return "no edges are declared from #{state.inspect}" if descriptors.empty?
+
+        rendered = descriptors.map do |descriptor|
+          if descriptor[:events].empty?
+            "to #{descriptor[:to].inspect} (direct)"
+          else
+            "to #{descriptor[:to].inspect} via #{descriptor[:events].inspect}"
+          end
+        end
+        "declared from #{state.inspect}: #{rendered.join("; ")}"
+      end
+
+      def declared_shape_of(record)
+        declared_shape(machine(record), current_state(record))
+      end
+
+      def reachable(record, metadata)
+        transitions = record.available_transitions(metadata: metadata)
+        state = current_state(record).inspect
+        return "nothing is reachable from #{state} right now" if transitions.empty?
+
+        rendered = transitions.map { |availability| "to #{availability.to.inspect} via #{availability.via.inspect}" }
+        "reachable from #{state}: #{rendered.join("; ")}"
+      end
+
+      def refusal(record, event_name, metadata)
+        refusals = record.refusals_for(event_name)
+        if refusals.empty?
+          "no record-layer guard refused — an input-reading guard: said no to metadata #{metadata.inspect}"
+        else
+          named = refusals.map { |entry| "#{entry.guard.inspect} (#{entry.layer})" }
+          "refused by record-layer guards: #{named.join(", ")}"
+        end
+      end
+    end
+  end
+end

data/lib/statecraft/rspec/transition.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Statecraft
+  module RSpec
+    # expect { order.fire!(:pay) }.to transition(order)
+    #   .from(:pending).to(:paid).via_event(:pay).with_metadata("k" => "v")
+    #
+    # The transition through the eyes of a test: the state column moved to
+    # the target AND exactly one log row was appended with the matching
+    # from/to/event/metadata. A non-bang call that returned false leaves
+    # both untouched — the matcher fails and explains why, from the same
+    # introspection the pipeline consulted. Exceptions of the bang forms
+    # fly through, like with the change matcher: refusals are asserted
+    # with refuse_event or raise_error, not here.
+    class Transition
+      def initialize(record)
+        @record = record
+        @failures = []
+      end
+
+      def from(state_name)
+        @from_state = state_name.to_sym
+        self
+      end
+
+      def to(state_name)
+        @to_state = state_name.to_sym
+        self
+      end
+
+      def via_event(event_name)
+        @event_name = event_name.to_sym
+        self
+      end
+
+      def with_metadata(metadata)
+        @metadata = metadata
+        self
+      end
+
+      def supports_block_expectations?
+        true
+      end
+
+      def matches?(block)
+        raise ArgumentError, "transition(record).to(:state) — the .to target is required" unless @to_state
+
+        @before_state = StateReport.current_state(@record)
+        appended_before = @record.history.count
+        block.call
+        @after_state = StateReport.current_state(@record)
+        @appended = @record.history.offset(appended_before).to_a
+        collect_failures
+        @failures.empty?
+      end
+
+      def failure_message
+        expected_event = " via event #{@event_name.inspect}" if @event_name
+        header = "expected the block to transition #{@record.class.name} " \
+                 "#{@before_state.inspect} -> #{@to_state.inspect}#{expected_event}"
+        ([header] + @failures).join("\n  ")
+      end
+
+      def failure_message_when_negated
+        row = @appended.last
+        written_by = " by event #{row.event.inspect}" if row.event
+        "expected the block not to transition #{@record.class.name} to #{@to_state.inspect}, " \
+          "but it did: #{row.from_state.inspect} -> #{row.to_state.inspect}#{written_by}"
+      end
+
+      def description
+        "transition #{@record.class.name} to #{@to_state.inspect}"
+      end
+
+      private
+
+      def collect_failures
+        return collect_missing_transition if @appended.empty?
+
+        if @appended.size > 1
+          @failures << "expected exactly one appended log row, but the block appended #{@appended.size}"
+        end
+        if @after_state != @to_state
+          @failures << "the record ended in #{@after_state.inspect}, not #{@to_state.inspect}"
+        end
+        collect_row_mismatches(@appended.last)
+      end
+
+      def collect_row_mismatches(row)
+        if row.to_state != @to_state.to_s
+          @failures << "the log row went to #{row.to_state.inspect}, not #{@to_state.inspect}"
+        end
+        if @from_state && row.from_state != @from_state.to_s
+          @failures << "the transition started from #{row.from_state.inspect}, not #{@from_state.inspect}"
+        end
+        if @event_name && row.event != @event_name.to_s
+          @failures << "the transition was written by event #{row.event.inspect}, not #{@event_name.inspect}"
+        end
+        collect_metadata_mismatch(row)
+      end
+
+      def collect_missing_transition
+        @failures << "no transition happened: the record stayed in #{@after_state.inspect}"
+        @failures << StateReport.reachable(@record, @metadata || {})
+        return unless @event_name && StateReport.event_declared?(@record, @event_name)
+
+        @failures << StateReport.refusal(@record, @event_name, @metadata || {})
+      end
+
+      def collect_metadata_mismatch(row)
+        return unless @metadata
+
+        expected = @metadata.deep_stringify_keys
+        return if row.metadata == expected
+
+        @failures << "the log row carries metadata #{row.metadata.inspect}, not #{expected.inspect}"
+      end
+    end
+  end
+end

data/lib/statecraft/rspec.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "statecraft"
+
+# Deliberately not required by lib/statecraft.rb: the matchers exist only
+# where RSpec does, and the gem's runtime must not know about test
+# frameworks. This file is the one opt-in door.
+unless defined?(RSpec)
+  raise Statecraft::Error,
+        "statecraft/rspec builds RSpec matchers, so RSpec must be loaded first: " \
+        "require statecraft/rspec from your spec helper, after rspec itself"
+end
+
+require_relative "rspec/state_report"
+require_relative "rspec/allow_event"
+require_relative "rspec/refuse_event"
+require_relative "rspec/allow_transition_to"
+require_relative "rspec/have_transitioned_to"
+require_relative "rspec/have_edge"
+require_relative "rspec/have_initial_state"
+require_relative "rspec/transition"
+require_relative "rspec/matchers"
+
+RSpec.configure { |config| config.include Statecraft::RSpec::Matchers }

data/lib/statecraft/version.rb

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

data/lib/statecraft.rb

@@ -10,6 +10,7 @@ require_relative "statecraft/instrumentation"
 require_relative "statecraft/machine"
 require_relative "statecraft/metadata"
 require_relative "statecraft/pipeline/edge_resolution"
+require_relative "statecraft/pipeline/versioning"
 require_relative "statecraft/pipeline"
 require_relative "statecraft/pipeline/surface"
 require_relative "statecraft/introspection"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: statecraft
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Igor Pugachev
@@ -87,6 +87,17 @@ files:
 - lib/statecraft/pipeline.rb
 - lib/statecraft/pipeline/edge_resolution.rb
 - lib/statecraft/pipeline/surface.rb
+- lib/statecraft/pipeline/versioning.rb
+- lib/statecraft/rspec.rb
+- lib/statecraft/rspec/allow_event.rb
+- lib/statecraft/rspec/allow_transition_to.rb
+- lib/statecraft/rspec/have_edge.rb
+- lib/statecraft/rspec/have_initial_state.rb
+- lib/statecraft/rspec/have_transitioned_to.rb
+- lib/statecraft/rspec/matchers.rb
+- lib/statecraft/rspec/refuse_event.rb
+- lib/statecraft/rspec/state_report.rb
+- lib/statecraft/rspec/transition.rb
 - lib/statecraft/version.rb
 - lib/statecraft/warnings.rb
 homepage: https://supostat.github.io/statecraft/