Add bang method variants for flow actions

[saturnflyer]

Summary

• Add Circulator::InvalidTransition base exception and auto-define HostClass::InvalidTransition subclass when a flow is declared, so host apps can rescue their own namespaced exception without coupling to Circulator
• Generate bang methods (e.g. status_approve!) that raise InvalidTransition with distinct messages for missing transitions vs guard rejections
• Add flow! instance method and variant: keyword to flow for extensible dispatch (e.g. future flow? / variant: :check)
• Unknown variant: values raise ArgumentError

Examples

class Widget
  extend Circulator

  flow :status do
    state :pending do
      action :approve, to: :approved, allow_if: :admin?
    end
  end
end

widget.status_approve   # => nil (guard rejected, no raise)
widget.status_approve!  # => raises Widget::InvalidTransition

# Rescue by host namespace or gem namespace
rescue Widget::InvalidTransition    # works
rescue Circulator::InvalidTransition # also works

# Via flow instance method
widget.flow!(:approve, :status)
widget.flow(:approve, :status, variant: :bang)

Test plan

• Successful transitions with bang methods
• Raises on missing transition with descriptive message
• Raises on guard rejection with distinct message
• Exception hierarchy (host < Circulator < StandardError)
• Self-transitions do not raise
• Around blocks (success, failure, intentional skip)
• Callable to: lambdas
• Arguments passthrough
• Model-based flow_target: flows
• flow! and variant: :bang
• Invalid variant: raises ArgumentError
• Non-bang methods unchanged
• Extension system generates bang methods
• Full suite: 358 runs, 1055 assertions, 0 failures
• Standardrb clean

[jeffdlange]

Really good explanation and example in the main description. Thank you!