statecraft 0.7.1 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b91fc7675cab350149a2e58679893b18ccdfa779cc84e2eb5a7d28c5591c265c
-  data.tar.gz: c751611f88af3a85738877185b68de734578a353818aa130c19206d40b498b82
+  metadata.gz: c8c55553745396ae74c5ffdac6de4dfad3df8ed075e26ef06ac627084aa87216
+  data.tar.gz: 995e759e6a394619f991b1f6921065219a9259928f4797aa4a340f66c601e0b7
 SHA512:
-  metadata.gz: 42c744386532cf91f06374dc3695c4e2ee3e64602fbb428045e3b588c27dc32843959552dea944be5d98834f28036baf1d712da2c25008dba8b16766ca23310b
-  data.tar.gz: 86822e6c1fba14b00e6a8e18efc586a7f92f35280490a168e4d96d063a6d3ecd471eac6fe877c512b9972359d1d14f4d344521dc6f0fea56235075df2bae975b
+  metadata.gz: 96794cd2d550849d99ccef2d9e6d0e12d12b790e585d7b8734a04a36ba55321f98bee6db237e9199e4c8ff02875900809070bc8fd295fb22dab7f5d41e71c87b
+  data.tar.gz: 6d5400fd71f2448099d9fc5c60ac71b663bbaed19b2c2d811e25172fa75148f970b9336b21fde31c09865f525dd428e2703314234bfb3e052c4dc1c5b2708085

data/README.md

@@ -145,6 +145,16 @@ 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.
 
+The third nature is `input_guard:` — a guard declaring that its answer
+*without* the input would be a false "no". Its handler must take exactly
+`(record, metadata)` (the compiler refuses any other arity), execution runs
+it after the record and plain layers, and the question surface honors the
+declaration: a `can_fire?` / `may_*?` / `available_*` asked with metadata
+omitted entirely raises `Statecraft::MetadataRequired` naming the guard,
+instead of feeding it an empty hash and predicting a refusal that the real
+call would not hit. An explicit `metadata: {}` states "my input is empty"
+and is always a legal question.
+
 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
@@ -326,7 +336,36 @@ 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!`.
+pass the same metadata to `may_*?` that you will collect for `fire!`. Mark
+such a guard `input_guard:` and the machine holds you to it: a question
+asked without any `metadata:` raises `Statecraft::MetadataRequired` with
+the guard's name instead of answering a false "no" (an explicit
+`metadata: {}` stays legal — it states the input is genuinely empty). A
+plain `guard:` keeps the old behavior: a bare question consults it with an
+empty hash.
+
+## Strict mode
+
+By default an unreachable state compiles silently — the column is written
+by more than the gem (legacy rows, the console, external systems), so a
+state without inbound edges is not necessarily a mistake. A machine that
+claims its graph is closed opts in:
+
+<!-- illustrative -->
+```ruby
+class OrderFlow < ApplicationMachine
+  strict!
+
+  state :pending, initial: true
+  # every state below must now be reachable from :pending through edges
+end
+```
+
+With `strict!` compilation additionally requires every declared state to be
+reachable from the initial one, walking edges only — guards are not
+consulted, exactly like `transitions_from`. Dead ends stay legal in strict
+mode too: terminal states are the norm, and an accidental one is surfaced
+by the first test as `InvalidTransition` with the list of allowed targets.
 
 ## RSpec matchers
 
@@ -373,6 +412,20 @@ not with the block matcher.
 it names record-layer guards only. An input-reading `guard:` has no name
 there, and the failure message says so instead of guessing.
 
+Under [`versioning:`](#stale-transitions-versioning-against-aba) the block
+matcher folds the version into the same assertion — a matching transition
+must also have incremented the version column — and every failure message
+prints the record's standing with its version
+(`Order in state :pending (state_version 3)`). Staleness stays an
+exception, exactly as in production: assert the refusal of a stale token
+with `raise_error`, not with a prediction matcher —
+
+<!-- illustrative -->
+```ruby
+expect { order.cancel!(seen: stale_token) }
+  .to raise_error(Statecraft::StaleTransition)
+```
+
 ## Metadata
 
 Metadata is normalized on pipeline entry with a full JSON round-trip —
@@ -621,9 +674,10 @@ class OrderFlow
   # 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).
+  # layer judges what the operator typed — and is marked input_guard:, so a
+  # question asked without metadata raises instead of predicting a false no.
   event :cancel, from: :pending, to: :cancelled,
-        record_guard: :customer_cancellable?, guard: :reason_present?
+        record_guard: :customer_cancellable?, input_guard: :reason_present?
   event :admin_override, from: :pending, to: :cancelled
 
   private

data/lib/statecraft/errors.rb

@@ -139,4 +139,21 @@ module Statecraft
             "make the log model inherit from the model's connection-owning ancestor")
     end
   end
+
+  # A question (can_fire?, may_*?, available_*) was asked without metadata
+  # while an input_guard stands on the consulted path — its answer without
+  # the input would be a false "no", so the question refuses loudly instead.
+  # An explicit `metadata: {}` states "my input is empty" and is legal.
+  class MetadataRequired < Error
+    attr_reader :record, :question, :guards
+
+    def initialize(record:, question:, guards:)
+      @record = record
+      @question = question
+      @guards = guards
+      super("#{question} on #{record.class.name} consults input guards " \
+            "#{guards.map(&:inspect).join(", ")} — pass metadata: to answer with input " \
+            "(an explicit metadata: {} means the input is empty)")
+    end
+  end
 end

data/lib/statecraft/introspection.rb

@@ -11,7 +11,7 @@ module Statecraft
     Availability = Struct.new(:to, :via, keyword_init: true)
     Refusal = Struct.new(:event, :guard, :layer, keyword_init: true)
 
-    def can_fire?(event_name, metadata: {})
+    def can_fire?(event_name, metadata: Metadata::OMITTED)
       graph = statecraft_graph
       branches = graph.events[event_name.to_sym]
       return false unless branches
@@ -19,24 +19,32 @@ module Statecraft
       edge = branches[statecraft_current_state]
       return false unless edge
 
-      statecraft_guards_pass?(edge, event_name.to_sym, Metadata.normalize(metadata))
+      normalized = statecraft_question_metadata(metadata, [[edge, event_name.to_sym]],
+                                                question: "can_fire?(#{event_name.inspect})")
+      statecraft_guards_pass?(edge, event_name.to_sym, normalized)
     end
 
-    def available_events(metadata: {})
-      normalized = Metadata.normalize(metadata)
-      statecraft_graph.events.filter_map do |event_name, branches|
+    def available_events(metadata: Metadata::OMITTED)
+      consulted = statecraft_graph.events.filter_map do |event_name, branches|
         edge = branches[statecraft_current_state]
-        next unless edge
-
+        [edge, event_name] if edge
+      end
+      normalized = statecraft_question_metadata(metadata, consulted, question: "available_events")
+      consulted.filter_map do |edge, event_name|
         event_name if statecraft_guards_pass?(edge, event_name, normalized)
       end
     end
 
-    def available_transitions(metadata: {})
-      normalized = Metadata.normalize(metadata)
-      statecraft_graph.edges.filter_map do |(from, _to), edge|
-        next unless from == statecraft_current_state
-
+    def available_transitions(metadata: Metadata::OMITTED)
+      outgoing = statecraft_graph.edges.filter_map do |(from, _to), edge|
+        edge if from == statecraft_current_state
+      end
+      consulted = outgoing.flat_map do |edge|
+        pairs = edge.event_names.map { |event_name| [edge, event_name] }
+        statecraft_direct_legal?(edge) ? pairs + [[edge, nil]] : pairs
+      end
+      normalized = statecraft_question_metadata(metadata, consulted, question: "available_transitions")
+      outgoing.filter_map do |edge|
         via = statecraft_passable_via(edge, normalized)
         Availability.new(to: edge.to, via: via) unless via.empty?
       end
@@ -73,6 +81,23 @@ module Statecraft
 
     private
 
+    # The single funnel for a question's metadata. Omitted with no input
+    # guard on the consulted path degrades to an empty hash; omitted with
+    # one raises MetadataRequired — the guard declared that its answer
+    # without input would be a false "no". An explicit hash always passes.
+    def statecraft_question_metadata(metadata, consulted_pairs, question:)
+      return Metadata.normalize(metadata) unless metadata.equal?(Metadata::OMITTED)
+
+      input_guards = consulted_pairs.flat_map { |edge, event_name| statecraft_input_guards(edge, event_name) }
+      return Metadata.normalize({}) if input_guards.empty?
+
+      raise MetadataRequired.new(record: self, question: question, guards: input_guards.uniq)
+    end
+
+    def statecraft_input_guards(edge, event_name)
+      edge.edge_input_guards + (event_name ? edge.event_input_guards.fetch(event_name, []) : [])
+    end
+
     def statecraft_record_refusals(edge, event_name)
       machine_instance = self.class.statecraft_mounting.machine_class.new
       layers = {

data/lib/statecraft/machine.rb

@@ -7,12 +7,15 @@ 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_guards / event_guards carry the FULL lists of both layers in
-    # record-then-input order — execution and the prediction run them as one
+    # edge_guards / event_guards carry the FULL lists of all layers in
+    # record-plain-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)
+    # layer (read by the offering introspection); the *_input_guards fields
+    # hold only the marked input layer (read by the question surface to
+    # refuse a question asked without metadata).
+    Edge = Struct.new(:from, :to, :lock, :edge_guards, :edge_record_guards, :edge_input_guards,
+                      :event_names, :event_guards, :event_record_guards, :event_input_guards,
+                      keyword_init: true)
     Callback = Struct.new(:handler, :from, :to, :event, keyword_init: true)
     CompiledGraph = Struct.new(
       :states, :initial_state, :edges, :events, :callbacks,
@@ -59,16 +62,17 @@ module Statecraft
         declared_states << { name: name.to_sym, initial: initial }
       end
 
-      def transition(from:, to:, guard: nil, record_guard: nil, lock: false)
+      def transition(from:, to:, guard: nil, record_guard: nil, input_guard: nil, lock: false)
         declared_edges << {
           from: from.to_sym, to: to.to_sym,
           guards: Array(guard), record_guards: Array(record_guard),
+          input_guards: Array(input_guard),
           lock: lock || current_event_lock,
           event: current_event_name
         }
       end
 
-      def event(name, from: nil, to: nil, guard: nil, record_guard: nil, lock: false, &declarations)
+      def event(name, from: nil, to: nil, guard: nil, record_guard: nil, input_guard: nil, lock: false, &declarations)
         name = name.to_sym
         declared_event_names << name
         if declarations
@@ -87,7 +91,8 @@ module Statecraft
 
           @statecraft_current_event = { name: name, lock: false }
           begin
-            transition(from: from, to: to, guard: guard, record_guard: record_guard, lock: lock)
+            transition(from: from, to: to, guard: guard, record_guard: record_guard,
+                       input_guard: input_guard, lock: lock)
           ensure
             @statecraft_current_event = nil
           end
@@ -108,6 +113,16 @@ module Statecraft
         end
       end
 
+      # Opt-in shape strictness: with strict! the compiler additionally
+      # requires every declared state to be reachable from the initial one.
+      # Off by default — the column is written by more than the gem, so an
+      # unconnected state is legal unless the machine claims a closed graph.
+      def strict!
+        @statecraft_strict = true
+      end
+
+      def strict? = @statecraft_strict == true
+
       def states
         compiled_graph.states
       end
@@ -197,6 +212,8 @@ module Statecraft
         events = compile_events(edges)
         resolve_symbols(edges)
         assert_record_guards_unary(edges)
+        assert_input_guards_binary(edges)
+        assert_states_reachable(states, initial, edges) if machine_class.strict?
         CompiledGraph.new(
           states: states.freeze,
           initial_state: initial,
@@ -249,9 +266,10 @@ module Statecraft
       def build_edge(declaration)
         Edge.new(
           from: declaration[:from], to: declaration[:to], lock: declaration[:lock],
-          edge_guards: declaration[:record_guards] + declaration[:guards],
+          edge_guards: declaration[:record_guards] + declaration[:guards] + declaration[:input_guards],
           edge_record_guards: declaration[:record_guards],
-          event_names: [], event_guards: {}, event_record_guards: {}
+          edge_input_guards: declaration[:input_guards],
+          event_names: [], event_guards: {}, event_record_guards: {}, event_input_guards: {}
         )
       end
 
@@ -259,16 +277,18 @@ module Statecraft
         event_name = declaration[:event]
         edge ||= Edge.new(
           from: declaration[:from], to: declaration[:to], lock: false,
-          edge_guards: [], edge_record_guards: [],
-          event_names: [], event_guards: {}, event_record_guards: {}
+          edge_guards: [], edge_record_guards: [], edge_input_guards: [],
+          event_names: [], event_guards: {}, event_record_guards: {}, event_input_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[:record_guards] + declaration[:guards]
+        edge.event_guards[event_name] = declaration[:record_guards] + declaration[:guards] +
+                                        declaration[:input_guards]
         edge.event_record_guards[event_name] = declaration[:record_guards]
+        edge.event_input_guards[event_name] = declaration[:input_guards]
         edge.lock ||= declaration[:lock]
         edge
       end
@@ -334,15 +354,62 @@ module Statecraft
         guard.respond_to?(:arity) ? guard.arity : guard.method(:call).arity
       end
 
+      # An input guard promises that its answer is meaningless without the
+      # input, and the promise is held by shape: it must accept exactly the
+      # record and the metadata, so a question asked without metadata can be
+      # refused instead of answered falsely.
+      def assert_input_guards_binary(edges)
+        edges.each_value do |edge|
+          input_guards = edge.edge_input_guards + edge.event_input_guards.values.flatten
+          input_guards.each do |guard|
+            arity = record_guard_arity(guard)
+            next if arity == 2
+
+            label = guard.is_a?(Symbol) ? guard.inspect : "the callable"
+            raise CompilationError,
+                  "input_guard #{label} must take the record and the metadata (arity 2), got arity #{arity}"
+          end
+        end
+      end
+
+      # Strict reachability is a shape check, like transitions_from: edges
+      # only, no guards. Dead ends stay legal — terminal states are the norm.
+      def assert_states_reachable(states, initial, edges)
+        unreachable = states - reachable_states(initial, edges)
+        return if unreachable.empty?
+
+        raise CompilationError,
+              "strict!: unreachable from the initial #{initial.inspect}: " \
+              "#{unreachable.map(&:inspect).join(", ")} — connect with edges or drop strict!"
+      end
+
+      def reachable_states(initial, edges)
+        reached = [initial]
+        queue = [initial]
+        until queue.empty?
+          from = queue.shift
+          edges.each_key do |(edge_from, edge_to)|
+            next if edge_from != from || reached.include?(edge_to)
+
+            reached << edge_to
+            queue << edge_to
+          end
+        end
+        reached
+      end
+
       def deep_freeze_edges(edges)
         edges.each_value do |edge|
           edge.edge_guards.freeze
           edge.edge_record_guards.freeze
+          edge.edge_input_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.event_input_guards.each_value(&:freeze)
+          edge.event_input_guards.freeze
           edge.freeze
         end
         edges.freeze

data/lib/statecraft/metadata.rb

@@ -7,6 +7,11 @@ module Statecraft
   # strings, and anything that JSON cannot represent fails instantly at the
   # pipeline entrance instead of inside the transaction.
   module Metadata
+    # The question surface's default: distinguishes "asked without metadata"
+    # from an explicit empty hash, so a question that would consult an
+    # input_guard can refuse loudly instead of answering from a void.
+    OMITTED = Object.new.freeze
+
     def self.normalize(raw_metadata)
       deep_freeze(round_trip(raw_metadata))
     end

data/lib/statecraft/mounting.rb

@@ -183,7 +183,9 @@ module Statecraft
             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) }
+            define_method("may_#{event_name}?") do |metadata: Metadata::OMITTED|
+              can_fire?(event_name, metadata: metadata)
+            end
           end
         end
         model.include(verbs)

data/lib/statecraft/rspec/state_report.rb

@@ -14,7 +14,12 @@ module Statecraft
       end
 
       def standing(record)
-        "#{record.class.name} in state #{current_state(record).inspect}"
+        "#{record.class.name} in state #{current_state(record).inspect}#{version_standing(record)}"
+      end
+
+      def version_standing(record)
+        column = record.class.statecraft_mounting.version_column
+        column ? " (#{column} #{record[column]})" : ""
       end
 
       def machine(record)

data/lib/statecraft/rspec/transition.rb

@@ -7,7 +7,8 @@ module Statecraft
     #
     # 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
+    # from/to/event/metadata — and under versioning: the version column
+    # incremented together with the state. 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
@@ -45,10 +46,13 @@ module Statecraft
       def matches?(block)
         raise ArgumentError, "transition(record).to(:state) — the .to target is required" unless @to_state
 
+        @version_column = @record.class.statecraft_mounting.version_column
         @before_state = StateReport.current_state(@record)
+        @before_version = @record[@version_column] if @version_column
         appended_before = @record.history.count
         block.call
         @after_state = StateReport.current_state(@record)
+        @after_version = @record[@version_column] if @version_column
         @appended = @record.history.offset(appended_before).to_a
         collect_failures
         @failures.empty?
@@ -84,6 +88,15 @@ module Statecraft
           @failures << "the record ended in #{@after_state.inspect}, not #{@to_state.inspect}"
         end
         collect_row_mismatches(@appended.last)
+        collect_version_mismatch
+      end
+
+      def collect_version_mismatch
+        return unless @version_column
+        return if @after_version == @before_version + 1
+
+        @failures << "the #{@version_column} column went from #{@before_version} to #{@after_version}, " \
+                     "expected #{@before_version + 1}: a versioned transition increments the version with the state"
       end
 
       def collect_row_mismatches(row)

data/lib/statecraft/version.rb

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

metadata

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