statecraft 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 207eda16ee51c42a787b0e3ba1a37c297242316edfe742c6be75b5dbca1166c0
-  data.tar.gz: efe7505f2499fdcd1175b35be3c454a9143b7afb2824dc3a6f0e2f98a8429a5f
+  metadata.gz: 6000e276c5fbe7a0ba8b33724c8cf6deea30dc0e8378931166e5123f799ee2a4
+  data.tar.gz: 40ab4510c265cb13a811faac8a3c04003222f1f57644233860a6f5d6031f8b12
 SHA512:
-  metadata.gz: 29d2cd130932273c9469dcbecf03f2a0fb20d33fc8b776efba5f850cd21bb447c5032de1dc10375e5dc9718d993001f6e0b279a5aa2e72c7be0cd1b890408710
-  data.tar.gz: c0856de0dde4ff10884ac2f567848b01b8949b514a2a171971957161d88348994d8f207e0f1e2f5d10fb1137a2b750b7f9f08e183537759dd2947be8c57911f4
+  metadata.gz: 7067033a04b74f602366186bbf5536070d21ab8f2151cc955529db3a4d522cfbbd07d1586f7ed50c2ab766081ead669a490d0f76a4e20c61bc939d9d6a1669b6
+  data.tar.gz: 808b7b6a2c2d790636954a2da78a884355568487e43470885db340f75459cea23bc98e72839e3aa072fa29e45dbccc3b6c44e4efddfea27445405b8a71125b96

data/README.md

@@ -29,6 +29,7 @@ the generator as a progressive enhancement.
 
 ## Installation
 
+<!-- illustrative -->
 ```ruby
 gem "statecraft"
 ```
@@ -48,6 +49,7 @@ log table with a cascade FK — and a CHECK constraint when the table is
 freshly created), the machine class, the readonly log model, and mounts the
 machine into the model. By hand it looks like this:
 
+<!-- illustrative -->
 ```ruby
 class OrderFlow < ApplicationMachine
   state :pending, initial: true
@@ -86,6 +88,13 @@ Mounting options: `log:` (defaults to the `<Model>Transition` convention),
 the same CAS update), `helpers:` and `scopes:` (both off by default; the
 generator turns them on for new code).
 
+## Example app
+
+A complete, working web store lives in [`example/`](example/): a storefront
+in human words over a two-zone Rails app, with the gem's full mechanics on
+the operator side and an e2e suite on top. Inside it:
+`bundle install && bin/rails db:setup && bin/rails s` — PostgreSQL only.
+
 ## The transition pipeline
 
 `transition_to!` / `fire!` run one strict order:
@@ -113,9 +122,10 @@ do not run, and unsaved changes on other attributes are neither saved nor
 callbacks are the transition's callbacks.
 
 Bang variants return the created log record. Non-bang variants return it too,
-or `false` — and `false` means exactly "a guard said no or the edge is not
-declared" (`GuardFailed` / `InvalidTransition`). Everything else — including
-`TransitionConflict` — always raises, in both variants.
+or `false` — and `false` covers exactly three refusals: a guard said no, the
+edge is not declared, or the bypass policy refused a direct transition over
+an event-guarded edge (`GuardFailed` / `InvalidTransition`). Everything
+else — including `TransitionConflict` — always raises, in both variants.
 
 ## Guards, events and the bypass policy
 
@@ -125,6 +135,16 @@ one event, `from` is unique — an event is a partial function from state to
 edge, so `fire!` is structurally deterministic. Branching by outcome means
 two events (`pay` and `fail_payment`), not one event with two branches.
 
+A guard also declares its nature. `guard:` judges the input: it receives
+`(record, metadata)` and belongs to execution and prediction. `record_guard:`
+judges the record alone: its handler must take exactly one argument — the
+compiler refuses any other arity — so it physically cannot read the input.
+Execution runs both layers, record first; the split exists for the offering
+introspection below, which may ask the record layer before any input exists.
+A good `record_guard:` is a one-line delegation to a domain predicate on the
+model (`def customer_cancellable?(record) = record.customer_cancellable?`):
+the machine keeps the registry "event → predicate", the model keeps the fact.
+
 Calling `transition_to!` directly over an edge that carries event guards is
 refused — the guards would be silently skipped. The escape hatch is explicit:
 `transition_to!(:paid, bypass_events: true)` skips event guards (edge guards
@@ -192,23 +212,39 @@ retry policy belongs to whoever chose the isolation level.
 
 ## Introspection
 
+<!-- illustrative -->
 ```ruby
 order.can_fire?(:pay, metadata: { amount: 100 })  # would the guards pass right now?
 order.may_pay?(metadata: { amount: 100 })          # alias, with helpers: true
 order.available_events(metadata: { amount: 100 })  # => [:pay]
 order.available_transitions(metadata: {})          # => [#<to: :cancelled, via: [:direct]>]
+order.offerable_events                             # => [:pay, :cancel] — graph × record layer
+order.refusals_for(:cancel)                        # => [#<event: :cancel, guard: :customer_cancellable?, layer: :event_record>]
 order.transitioned_to?(:paid)                      # strictly log-based
+OrderFlow.transitions_from(:pending)               # => [{ to: :paid, events: [:pay] }, ...]
 ```
 
+`transitions_from` is class-level and answers the graph's shape, not a
+prediction: no guards are consulted, a bare edge carries an empty `events`
+list, and a state outside the graph owns no edges. Pair it with
+`available_transitions` for the prediction.
+
 `available_transitions` tells you not only *where* you can go but *how*:
 `via` lists the events whose guards pass, plus `:direct` when the edge is
 free of event guards and its edge guards pass. Every answer is a snapshot —
 CAS may still reject the transition a moment later.
 
-A guard that reads metadata makes `may_*?` depend on the metadata you pass.
-For a UI "is this button available" question, either do not hang input
-validation on a guard, or pass the same metadata to `may_*?` that you will
-collect for `fire!`.
+For a UI "is this button available" question, ask `offerable_events`: the
+graph filtered by the record layer only. An input-reading `guard:` never
+hides a button — hiding it would hide the form its input arrives through —
+while a `record_guard:` honestly strips an event this record is not offered.
+`refusals_for(:event)` returns the refusing record-layer guards as frozen
+structures (event, guard name, layer) and answers `[]` for an unknown event
+or a missing branch. It carries names, never words: human-readable reasons
+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!`.
 
 ## Metadata
 
@@ -217,7 +253,14 @@ symbol keys and values become strings, times become ISO-8601 strings — and
 then deep-frozen: **the guards see exactly what the log will store**, and a
 guard that mutates metadata dies with `FrozenError` in a transition and in a
 check alike. Unserializable values (a `Proc`, a model instance) fail
-instantly at the entrance, not inside the transaction.
+instantly at the entrance, not inside the transaction — and so do `NaN` and
+`Infinity`, which JSON cannot represent.
+
+`BigDecimal` is rejected deliberately, not by omission: jsonb would hand it
+back as a string or a float depending on the reader, silently breaking the
+"what the guards checked is what the log stored" promise. Pass money and
+other exact decimals as strings (`metadata: { price: order.total.to_s }`)
+and parse them in the guard.
 
 Facts of the transition moment (a price snapshot, a rules version) are
 collected by the caller: `order.pay!(metadata: { price: order.total })`.
@@ -326,6 +369,7 @@ that also fails the check, correctly.
 No railties at runtime — the hygiene is enforced by a test, not a promise.
 Without the generator, create the schema by hand; the reference shape:
 
+<!-- illustrative -->
 ```ruby
 create_table :orders do |t|
   t.string :state, null: false, default: "pending", index: true
@@ -355,6 +399,219 @@ degrades — the locking clause is dropped, the reload still runs, and
 statecraft warns once per machine per process that row-locking guarantees
 require PostgreSQL.
 
+## Example app patterns
+
+These blocks are copied verbatim from the example store and locked by
+`example/script/readme_drift_check.rb` — the code is right, the README
+catches up by hand. The machine behind an order:
+
+<!-- readme: machine-skeleton -->
+```ruby
+class OrderFlow
+  include Statecraft::Machine
+
+  state :pending, initial: true
+  state :paid
+  state :refunded
+  state :cancelled
+
+  event :pay, from: :pending, to: :paid
+  event :refund, from: :paid, to: :refunded, record_guard: :refundable?
+
+  # One edge, the whole event layer: a guarded event, an unguarded privileged
+  # event and the bypass path all share pending -> cancelled — the log
+  # records HOW, not only WHAT. The cancel guards split by nature: the
+  # record layer judges the order (and the offering may ask it), the input
+  # layer judges what the operator typed (only fire! and the panel see it).
+  event :cancel, from: :pending, to: :cancelled,
+        record_guard: :customer_cancellable?, guard: :reason_present?
+  event :admin_override, from: :pending, to: :cancelled
+
+  private
+
+  # The machine keeps the registry "event -> predicate" and delegates the
+  # domain facts to the record.
+  def refundable?(record) = record.refundable?
+
+  def customer_cancellable?(record) = record.customer_cancellable?
+
+  def reason_present?(_record, metadata)
+    metadata["reason"].to_s.strip.present?
+  end
+end
+```
+
+The operator order desk, whole: authorize! on entry and per event, thin
+actions over services, guard refusals local to their form:
+
+<!-- readme: order-controller -->
+```ruby
+  # The operator's order desk — bang everywhere: an operator wants the gem's
+  # message for the flash, and a non-bang false carries no text. Staleness
+  # heals in ApplicationController; a guard refusal is local to this form.
+  class OrdersController < BaseController
+    def index
+      @orders = OrdersQuery.call(state: params[:state])
+      @active_state = params[:state].to_s
+    end
+
+    def show
+      @order = Order.find(params[:id])
+      @metadata = {}
+    end
+
+    def pay
+      fire(:pay)
+    end
+
+    def cancel
+      fire(:cancel)
+    end
+
+    def refund
+      fire(:refund)
+    end
+
+    # The non-mutating submit of the SAME fields: the panel recomputes from
+    # exactly the metadata a real fire would carry. Nothing is written.
+    def preview
+      @order = Order.find(params[:id])
+      @metadata = submitted_metadata
+      flash.now[:notice] = "Preview only — nothing was written."
+      render :show
+    end
+
+    # The privileged event: a SECOND event on the same edge, without a
+    # guard — the log will name it admin_override.
+    def admin_override
+      order = Order.find(params[:id])
+      authorize! :admin_override, order
+      order.admin_override!(metadata: { "reason" => "admin override" })
+      redirect_to admin_order_path(order),
+                  notice: "admin_override fired: the order is now #{order[:state]}."
+    end
+
+    # The bypass: the same edge with the event layer skipped — the log
+    # writes event: nil and the history renders the muted
+    # "direct (bypassed events)".
+    def bypass_cancel
+      order = Order.find(params[:id])
+      authorize! :bypass_cancel, order
+      order.transition_to!(:cancelled, bypass_events: true,
+                                       metadata: { "reason" => "bypassed by admin" })
+      redirect_to admin_order_path(order),
+                  notice: "bypassed: the order is now #{order[:state]}."
+    end
+
+    def create_shipment
+      order = Order.find(params[:id])
+      authorize! :create_shipment, order
+      shipment = CreateShipment.call(order: order)
+      redirect_to admin_shipment_path(shipment), notice: "Shipment created."
+    rescue ArgumentError => error
+      redirect_to admin_order_path(order), alert: error.message.capitalize + "."
+    end
+
+    private
+
+    def fire(event_name)
+      @order = Order.find(params[:id])
+      authorize! event_name, @order
+      @metadata = submitted_metadata
+      @order.fire!(event_name, metadata: @metadata)
+      redirect_to admin_order_path(@order),
+                  notice: "#{event_name} fired: the order is now #{@order[:state]}."
+    rescue Statecraft::GuardFailed => error
+      # Local to the form: re-render THIS card with the panel computed from
+      # the metadata that were actually submitted — a guard refusal belongs
+      # to the scene, not to a global handler.
+      flash.now[:alert] = "Refused: #{error.message}"
+      render :show, status: :unprocessable_entity
+    end
+
+    def submitted_metadata
+      params.fetch(:metadata, {}).permit(:reason).to_h
+    end
+  end
+```
+
+The preview button — a non-mutating submit of the same fields the
+guard-aware panel predicts with, next to buttons that render only in the
+possibility-times-permission intersection:
+
+<!-- readme: preview-pattern -->
+```erb
+<%= form_with url: preview_admin_order_path(@order), method: :post, local: true do %>
+  <fieldset>
+    <legend>Metadata for the next action</legend>
+    <label>
+      reason
+      <input type="text" name="metadata[reason]" value="<%= @metadata["reason"] %>">
+    </label>
+  </fieldset>
+
+  <%= render "shared/transition_buttons",
+             record: @order,
+             fire_url: ->(event_name) { public_send("#{event_name}_admin_order_path", @order) } %>
+
+  <button type="submit" class="preview-button">preview</button>
+<% end %>
+```
+
+Subscribing to the telemetry — the five-argument form is the one that
+publish-style events actually deliver to:
+
+<!-- readme: telemetry-subscriber -->
+```ruby
+# The one executable example of subscribing to statecraft's telemetry: the
+# Operations log feed is written here, with create!, into an ordinary table.
+# The gem publishes with explicit start/finish, so subscribers take the
+# five-argument block form. Payloads never carry metadata (the gem's PII
+# decision) — whoever needs it reads the transition log record instead.
+ActiveSupport::Notifications.subscribe("transition.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: "transition"
+  )
+end
+
+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
+  )
+end
+```
+
+Seeding through the honest pipeline, refusal narrative included:
+
+<!-- readme: seed-pattern -->
+```ruby
+  # The refusal scenario WITH its narrative: the rescue is part of the plot —
+  # a cancellation attempt without a reason lands in the operations feed as a
+  # refusal, then the reasoned retry succeeds.
+  def seed_disputed_order
+    order = place_order(number: "ORD-1009", customer: "Ivy Chen",
+                        items: { "Ceramic vase" => 2 })
+    begin
+      order.cancel!(metadata: {})
+    rescue Statecraft::GuardFailed
+      # the refusal is the point: the feed keeps it
+    end
+    order.cancel!(metadata: { "reason" => "dispute resolved in the customer's favor" })
+    order
+  end
+```
+
 ## Running the tests
 
 Natively, against SQLite:

data/lib/generators/statecraft/machine/USAGE

@@ -0,0 +1,26 @@
+Description:
+    Creates everything one model needs for a statecraft state machine: the
+    migration (state column with a CHECK constraint for a fresh table, the
+    state_changed_at column, and the append-only per-model log table with a
+    cascade FK), the machine class, the readonly log model, the model itself
+    when it does not exist yet (an existing model gets the state_machine
+    mounting injected instead), and — once per application — the shared
+    ApplicationMachine parent.
+
+    Namespaced models are fully supported: every file lands by the full
+    path, and a table_name_prefix module is generated the way the Rails
+    model generator does it. For a model on a non-primary database the
+    migration lands in the migrations_paths configured for that database
+    (db/migrate when none is configured).
+
+Example:
+    bin/rails generate statecraft:machine Order
+    bin/rails generate statecraft:machine Shop::Order
+
+    This will create:
+        app/state_machines/application_machine.rb  (first run only)
+        app/state_machines/shop/order_flow.rb
+        app/models/shop.rb                         (namespace prefix module)
+        app/models/shop/order_transition.rb
+        app/models/shop/order.rb                   (or mounting injection)
+        db/migrate/XXXXXXXXXXXXXX_create_shop_order_state_machine.rb

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

@@ -3,14 +3,21 @@
 class <%= class_name %>Flow < ApplicationMachine
   state :pending, initial: true
   # state :paid
+  # state :refunded
   #
   # event :pay, from: :pending, to: :paid, guard: :payable?
+  # event :refund, from: :paid, to: :refunded, record_guard: :refundable?
   #
-  # Guards and callbacks resolve to instance methods of this class:
+  # Guards and callbacks resolve to instance methods of this class, and a
+  # guard declares its nature: guard: judges the input and receives
+  # (record, metadata); record_guard: judges the record alone (arity 1,
+  # compiler-enforced) — delegate it to a domain predicate on the model:
   #
   # private
   #
   # def payable?(record, metadata)
   #   metadata["amount"].to_i.positive?
   # end
+  #
+  # def refundable?(record) = record.refundable?
 end

data/lib/statecraft/introspection.rb

@@ -9,6 +9,7 @@ module Statecraft
   # reject the transition later.
   module Introspection
     Availability = Struct.new(:to, :via, keyword_init: true)
+    Refusal = Struct.new(:event, :guard, :layer, keyword_init: true)
 
     def can_fire?(event_name, metadata: {})
       graph = statecraft_graph
@@ -45,8 +46,48 @@ module Statecraft
       history.where(to_state: state_name.to_s).exists?
     end
 
+    # The offering: which events the graph AND this record allow from here —
+    # the record layer alone, so an input-reading guard never hides the form
+    # its input arrives through. A snapshot, like every question here.
+    def offerable_events
+      statecraft_graph.events.filter_map do |event_name, branches|
+        edge = branches[statecraft_current_state]
+        next unless edge
+
+        event_name if statecraft_record_refusals(edge, event_name).empty?
+      end
+    end
+
+    # The structured "why not": every record-layer guard refusing the event
+    # right now. Guard handlers by name, no words — the words belong to the
+    # presentation. An unknown event or a missing branch answers [].
+    def refusals_for(event_name)
+      branches = statecraft_graph.events[event_name.to_sym]
+      return [].freeze unless branches
+
+      edge = branches[statecraft_current_state]
+      return [].freeze unless edge
+
+      statecraft_record_refusals(edge, event_name.to_sym)
+    end
+
     private
 
+    def statecraft_record_refusals(edge, event_name)
+      machine_instance = self.class.statecraft_mounting.machine_class.new
+      layers = {
+        edge_record: edge.edge_record_guards,
+        event_record: edge.event_record_guards.fetch(event_name, [])
+      }
+      layers.flat_map do |layer, guards|
+        guards.filter_map do |guard|
+          next if Machine::Handlers.invoke(machine_instance, guard, self, nil)
+
+          Refusal.new(event: event_name, guard: guard, layer: layer).freeze
+        end
+      end.freeze
+    end
+
     def statecraft_passable_via(edge, normalized_metadata)
       via = edge.event_names.select do |event_name|
         statecraft_guards_pass?(edge, event_name, normalized_metadata)

data/lib/statecraft/machine.rb

@@ -7,7 +7,12 @@ module Statecraft
   # Guard and callback symbols resolve to instance methods of the machine
   # class; callables are honored with a plain `call` and arity dispatch.
   module Machine
-    Edge = Struct.new(:from, :to, :lock, :edge_guards, :event_names, :event_guards, keyword_init: true)
+    # edge_guards / event_guards carry the FULL lists of both layers in
+    # record-then-input order — execution and the prediction run them as one
+    # sequence. The parallel *_record_guards fields hold only the record
+    # layer; nothing but the offering introspection reads them.
+    Edge = Struct.new(:from, :to, :lock, :edge_guards, :edge_record_guards,
+                      :event_names, :event_guards, :event_record_guards, keyword_init: true)
     Callback = Struct.new(:handler, :from, :to, :event, keyword_init: true)
     CompiledGraph = Struct.new(
       :states, :initial_state, :edges, :events, :callbacks,
@@ -40,24 +45,30 @@ module Statecraft
       end
 
       def self.unary?(callable)
-        callable.arity == 1
+        arity = callable.respond_to?(:arity) ? callable.arity : callable.method(:call).arity
+        arity == 1
       end
     end
 
     # Class-level DSL collected declaratively and compiled by finalize!.
+    # Names arrive as symbols or strings interchangeably (the ActiveRecord
+    # idiom) and are normalized to symbols at the declaration line.
     module ClassMethods
       def state(name, initial: false)
-        declared_states << { name: name, initial: initial }
+        declared_states << { name: name.to_sym, initial: initial }
       end
 
-      def transition(from:, to:, guard: nil, lock: false)
+      def transition(from:, to:, guard: nil, record_guard: nil, lock: false)
         declared_edges << {
-          from: from, to: to, guards: Array(guard), lock: lock || current_event_lock,
+          from: from.to_sym, to: to.to_sym,
+          guards: Array(guard), record_guards: Array(record_guard),
+          lock: lock || current_event_lock,
           event: current_event_name
         }
       end
 
-      def event(name, from: nil, to: nil, guard: nil, lock: false, &declarations)
+      def event(name, from: nil, to: nil, guard: nil, record_guard: nil, lock: false, &declarations)
+        name = name.to_sym
         declared_event_names << name
         if declarations
           if from || to
@@ -75,7 +86,7 @@ module Statecraft
 
           @statecraft_current_event = { name: name, lock: false }
           begin
-            transition(from: from, to: to, guard: guard, lock: lock)
+            transition(from: from, to: to, guard: guard, record_guard: record_guard, lock: lock)
           ensure
             @statecraft_current_event = nil
           end
@@ -89,7 +100,9 @@ module Statecraft
 
           declared_callbacks[phase] << Callback.new(
             handler: callback_handler,
-            from: from && Array(from), to: to && Array(to), event: event && Array(event)
+            from: from && Array(from).map(&:to_sym),
+            to: to && Array(to).map(&:to_sym),
+            event: event && Array(event).map(&:to_sym)
           )
         end
       end
@@ -102,6 +115,18 @@ module Statecraft
         compiled_graph.events.keys
       end
 
+      # The graph's shape from one state: a frozen descriptor per outgoing
+      # edge, `events` empty for a bare edge. Shape, not a prediction — no
+      # guards are consulted, and a state outside the graph honestly owns no
+      # edges. Class-level on purpose: the answer is a property of the graph,
+      # never of a record.
+      def transitions_from(state)
+        normalized = state.to_sym
+        compiled_graph.edges.filter_map do |(from, _to), edge|
+          { to: edge.to, events: edge.event_names }.freeze if from == normalized
+        end.freeze
+      end
+
       def initial_state
         compiled_graph.initial_state
       end
@@ -114,8 +139,11 @@ module Statecraft
         !@statecraft_compiled_graph.nil?
       end
 
+      # Compilation memoizes the graph and freezes the declaration lists, so a
+      # reopened machine class fails loudly on any late state/transition/event
+      # instead of silently ignoring it (callbacks already freeze in compile).
       def finalize!
-        @statecraft_compiled_graph ||= Compiler.new(self).compile
+        @statecraft_compiled_graph ||= Compiler.new(self).compile.tap { freeze_declarations }
       end
 
       def declared_states
@@ -136,6 +164,12 @@ module Statecraft
 
       private
 
+      def freeze_declarations
+        declared_states.freeze
+        declared_edges.freeze
+        declared_event_names.freeze
+      end
+
       def current_event_name
         @statecraft_current_event && @statecraft_current_event[:name]
       end
@@ -161,6 +195,7 @@ module Statecraft
         edges = compile_edges(states)
         events = compile_events(edges)
         resolve_symbols(edges)
+        assert_record_guards_unary(edges)
         CompiledGraph.new(
           states: states.freeze,
           initial_state: initial,
@@ -213,7 +248,9 @@ module Statecraft
       def build_edge(declaration)
         Edge.new(
           from: declaration[:from], to: declaration[:to], lock: declaration[:lock],
-          edge_guards: declaration[:guards], event_names: [], event_guards: {}
+          edge_guards: declaration[:record_guards] + declaration[:guards],
+          edge_record_guards: declaration[:record_guards],
+          event_names: [], event_guards: {}, event_record_guards: {}
         )
       end
 
@@ -221,14 +258,16 @@ module Statecraft
         event_name = declaration[:event]
         edge ||= Edge.new(
           from: declaration[:from], to: declaration[:to], lock: false,
-          edge_guards: [], event_names: [], event_guards: {}
+          edge_guards: [], edge_record_guards: [],
+          event_names: [], event_guards: {}, event_record_guards: {}
         )
         if edge.event_names.include?(event_name)
           raise CompilationError, "event #{event_name.inspect} declares edge #{pair_name(pair)} twice"
         end
 
         edge.event_names << event_name
-        edge.event_guards[event_name] = declaration[:guards]
+        edge.event_guards[event_name] = declaration[:record_guards] + declaration[:guards]
+        edge.event_record_guards[event_name] = declaration[:record_guards]
         edge.lock ||= declaration[:lock]
         edge
       end
@@ -268,15 +307,41 @@ module Statecraft
         from_callbacks = machine_class.declared_callbacks.each_value.flat_map do |callbacks|
           callbacks.map(&:handler)
         end
-        (from_edges + from_callbacks).select { |handler| handler.is_a?(Symbol) }
+        (from_edges + from_callbacks).grep(Symbol)
+      end
+
+      # A record guard promises to judge the record alone, and the promise is
+      # held by shape: it must accept exactly one argument, so it physically
+      # cannot read the input it claims not to need.
+      def assert_record_guards_unary(edges)
+        edges.each_value do |edge|
+          record_guards = edge.edge_record_guards + edge.event_record_guards.values.flatten
+          record_guards.each do |guard|
+            arity = record_guard_arity(guard)
+            next if arity == 1
+
+            label = guard.is_a?(Symbol) ? guard.inspect : "the callable"
+            raise CompilationError,
+                  "record_guard #{label} must take exactly the record (arity 1), got arity #{arity}"
+          end
+        end
+      end
+
+      def record_guard_arity(guard)
+        return machine_class.instance_method(guard).arity if guard.is_a?(Symbol)
+
+        guard.respond_to?(:arity) ? guard.arity : guard.method(:call).arity
       end
 
       def deep_freeze_edges(edges)
         edges.each_value do |edge|
           edge.edge_guards.freeze
+          edge.edge_record_guards.freeze
           edge.event_names.freeze
           edge.event_guards.each_value(&:freeze)
           edge.event_guards.freeze
+          edge.event_record_guards.each_value(&:freeze)
+          edge.event_record_guards.freeze
           edge.freeze
         end
         edges.freeze

data/lib/statecraft/mounting.rb

@@ -82,11 +82,26 @@ module Statecraft
         raise ConnectionMismatch.new(model: model, log_class: log_class)
       end
 
+      # Methods this mounting itself defines, so a verb check runs BEFORE the
+      # includes and still sees them: an event named fire or history would
+      # otherwise silently shadow the gem's own surface.
+      def mounted_surface_methods
+        Pipeline::Surface.instance_methods +
+          Introspection.instance_methods +
+          %i[history last_transition in_state?]
+      end
+
       def assert_no_verb_conflicts(graph)
         return unless @helpers
 
+        surface_methods = mounted_surface_methods
         graph.events.each_key do |event_name|
           verb_names(event_name).each do |verb|
+            if surface_methods.include?(verb.to_sym)
+              raise CompilationError,
+                    "helper #{verb} for event #{event_name.inspect} conflicts with the " \
+                    "#{verb} method statecraft itself mounts; rename the event"
+            end
             next unless model.method_defined?(verb) || model.private_method_defined?(verb)
 
             raise CompilationError,

data/lib/statecraft/pipeline/edge_resolution.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Statecraft
+  class Pipeline
+    # Resolves the requested edge from the compiled graph and raises
+    # InvalidTransition with a diagnosis that names what actually failed:
+    # an undeclared edge, a bypass-policy refusal, an unknown event, or an
+    # event with no branch from the current state.
+    module EdgeResolution
+      private
+
+      def resolve_direct_edge(current, to_state, bypass_events)
+        edge = graph.edges[[current, to_state]]
+        raise_invalid_transition(current, to_state) if edge.nil?
+        guarding_events = edge.event_names.select { |name| edge.event_guards[name].any? }
+        if guarding_events.any? && !bypass_events
+          raise InvalidTransition.new(
+            record: record, from: current, requested: to_state,
+            allowed: allowed_targets(current),
+            message: "direct transition #{current} -> #{to_state} is guarded by " \
+                     "event#{"s" if guarding_events.length > 1} #{guarding_events.join(", ")}; " \
+                     "call fire!(:#{guarding_events.first}) or pass bypass_events: true"
+          )
+        end
+        edge
+      end
+
+      def resolve_event_edge(current, event_name)
+        branches = graph.events[event_name]
+        raise_unknown_event(current, event_name) if branches.nil?
+        edge = branches[current]
+        raise_event_without_branch(current, event_name, branches) if edge.nil?
+        edge
+      end
+
+      def raise_unknown_event(current, event_name)
+        known_events = graph.events.keys
+        raise InvalidTransition.new(
+          record: record, from: current, requested: event_name,
+          allowed: allowed_targets(current),
+          message: "unknown event #{event_name.inspect} for #{configuration.machine_class.name}; " \
+                   "events: #{known_events.empty? ? "none" : known_events.map(&:inspect).join(", ")}"
+        )
+      end
+
+      def raise_event_without_branch(current, event_name, branches)
+        declared_branches = branches.map { |from, edge| "#{from} -> #{edge.to}" }.join(", ")
+        raise InvalidTransition.new(
+          record: record, from: current, requested: event_name,
+          allowed: allowed_targets(current),
+          message: "event #{event_name.inspect} has no branch from #{current} for " \
+                   "#{record.class.name}; branches: #{declared_branches}"
+        )
+      end
+
+      def raise_invalid_transition(current, requested)
+        raise InvalidTransition.new(
+          record: record, from: current, requested: requested,
+          allowed: allowed_targets(current)
+        )
+      end
+
+      def allowed_targets(current)
+        graph.edges.keys.select { |from, _to| from == current }.map(&:last)
+      end
+    end
+  end
+end

data/lib/statecraft/pipeline.rb

@@ -28,6 +28,8 @@ module Statecraft
     STACK_KEY = :statecraft_transition_stack
     MAX_CHAIN_DEPTH = 16
 
+    include EdgeResolution
+
     def self.transition_stack
       ActiveSupport::IsolatedExecutionState[STACK_KEY] ||= []
     end
@@ -70,7 +72,7 @@ module Statecraft
         begin
           log_record = execute_transaction(edge, event, bypass, metadata, frame)
         ensure
-          Pipeline.transition_stack.delete(frame)
+          Pipeline.transition_stack.delete_if { |open| open.equal?(frame) }
         end
       rescue GuardFailed, InvalidTransition, TransitionConflict => transition_error
         publish_failure(started_at, transition_error)
@@ -149,41 +151,6 @@ module Statecraft
       record[configuration.column].to_s.to_sym
     end
 
-    def resolve_direct_edge(current, to_state, bypass_events)
-      edge = graph.edges[[current, to_state]]
-      raise_invalid_transition(current, to_state) if edge.nil?
-      guarding_events = edge.event_names.select { |name| edge.event_guards[name].any? }
-      if guarding_events.any? && !bypass_events
-        raise InvalidTransition.new(
-          record: record, from: current, requested: to_state,
-          allowed: allowed_targets(current),
-          message: "direct transition #{current} -> #{to_state} is guarded by " \
-                   "event#{"s" if guarding_events.length > 1} #{guarding_events.join(", ")}; " \
-                   "call fire!(:#{guarding_events.first}) or pass bypass_events: true"
-        )
-      end
-      edge
-    end
-
-    def resolve_event_edge(current, event_name)
-      branches = graph.events[event_name]
-      raise_invalid_transition(current, event_name) if branches.nil?
-      edge = branches[current]
-      raise_invalid_transition(current, event_name) if edge.nil?
-      edge
-    end
-
-    def raise_invalid_transition(current, requested)
-      raise InvalidTransition.new(
-        record: record, from: current, requested: requested,
-        allowed: allowed_targets(current)
-      )
-    end
-
-    def allowed_targets(current)
-      graph.edges.keys.select { |from, _to| from == current }.map(&:last)
-    end
-
     # Checked at the first transition, not at mounting time: resolving an
     # implicit primary key goes through the schema cache, and mounting must
     # stay safe without a database connection.
@@ -311,7 +278,7 @@ module Statecraft
     end
 
     def warn_when_row_locking_unavailable
-      return unless base_class.connection.adapter_name.match?(/sqlite/i)
+      return unless base_class.connection_db_config.adapter.match?(/sqlite/i)
 
       Statecraft.warn(
         [configuration.machine_class.name, :sqlite_row_lock],

data/lib/statecraft/version.rb

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

data/lib/statecraft.rb

@@ -9,6 +9,7 @@ require_relative "statecraft/warnings"
 require_relative "statecraft/instrumentation"
 require_relative "statecraft/machine"
 require_relative "statecraft/metadata"
+require_relative "statecraft/pipeline/edge_resolution"
 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.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Igor Pugachev
@@ -60,6 +60,7 @@ extra_rdoc_files: []
 files:
 - LICENSE.txt
 - README.md
+- lib/generators/statecraft/machine/USAGE
 - lib/generators/statecraft/machine/machine_generator.rb
 - lib/generators/statecraft/machine/templates/add_migration.rb.tt
 - lib/generators/statecraft/machine/templates/application_machine.rb.tt
@@ -76,6 +77,7 @@ files:
 - lib/statecraft/metadata.rb
 - lib/statecraft/mounting.rb
 - lib/statecraft/pipeline.rb
+- lib/statecraft/pipeline/edge_resolution.rb
 - lib/statecraft/pipeline/surface.rb
 - lib/statecraft/version.rb
 - lib/statecraft/warnings.rb