statecraft 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f809e9a1769e457d33d4b526703e4c3c7beb4ca09f8a7550cbbd31c97b07ba12
-  data.tar.gz: 8193837939f39dd0de633330b7bfc36d7adbb821221072ce1cdf30890f3488d0
+  metadata.gz: 6000e276c5fbe7a0ba8b33724c8cf6deea30dc0e8378931166e5123f799ee2a4
+  data.tar.gz: 40ab4510c265cb13a811faac8a3c04003222f1f57644233860a6f5d6031f8b12
 SHA512:
-  metadata.gz: a5da582f65eb60cd2f76fef2ec213ad6c09166b288f44d80f7065a943894a66c5f36134f6c094fd873e50562976a447d0183b3e0e47b5545bce707d63f965d83
-  data.tar.gz: f1247259b3bc97de6663d9545e00015e1ea443b9e9f0ac33af6a179c09ba534140b0037863ddd2fa64e4992234a5fe14ea0d43e4a9ddc30d1018927c0d3158c5
+  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:
@@ -126,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
@@ -193,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
 
@@ -334,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
@@ -363,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/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,
@@ -53,14 +58,16 @@ module Statecraft
         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_sym, to: to.to_sym, 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
@@ -79,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
@@ -108,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
@@ -176,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,
@@ -228,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
 
@@ -236,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
@@ -286,12 +310,38 @@ module Statecraft
         (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/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: statecraft
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.0
 platform: ruby
 authors:
 - Igor Pugachev