statecraft 0.1.0

data/lib/statecraft/introspection.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Statecraft
+  # The record-facing questions: "would the guards pass if I fired this
+  # transition with these metadata right now". Normalization and freeze are
+  # identical to the pipeline's, so a guard that mutates metadata fails the
+  # same way in a check as in a transition, and the answer never diverges from
+  # what fire! would actually do. Every answer is a snapshot: CAS may still
+  # reject the transition later.
+  module Introspection
+    Availability = Struct.new(:to, :via, keyword_init: true)
+
+    def can_fire?(event_name, metadata: {})
+      graph = statecraft_graph
+      branches = graph.events[event_name.to_sym]
+      return false unless branches
+
+      edge = branches[statecraft_current_state]
+      return false unless edge
+
+      statecraft_guards_pass?(edge, event_name.to_sym, Metadata.normalize(metadata))
+    end
+
+    def available_events(metadata: {})
+      normalized = Metadata.normalize(metadata)
+      statecraft_graph.events.filter_map do |event_name, branches|
+        edge = branches[statecraft_current_state]
+        next unless edge
+
+        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
+
+        via = statecraft_passable_via(edge, normalized)
+        Availability.new(to: edge.to, via: via) unless via.empty?
+      end
+    end
+
+    def transitioned_to?(state_name)
+      history.where(to_state: state_name.to_s).exists?
+    end
+
+    private
+
+    def statecraft_passable_via(edge, normalized_metadata)
+      via = edge.event_names.select do |event_name|
+        statecraft_guards_pass?(edge, event_name, normalized_metadata)
+      end
+      direct = statecraft_direct_legal?(edge) && statecraft_guards_pass?(edge, nil, normalized_metadata)
+      direct ? via + [:direct] : via
+    end
+
+    def statecraft_direct_legal?(edge)
+      edge.event_guards.values.all?(&:empty?)
+    end
+
+    def statecraft_guards_pass?(edge, event_name, normalized_metadata)
+      machine_instance = self.class.statecraft_mounting.machine_class.new
+      guards = edge.edge_guards + (event_name ? edge.event_guards.fetch(event_name, []) : [])
+      guards.all? do |guard|
+        Machine::Handlers.invoke(machine_instance, guard, self, normalized_metadata)
+      end
+    end
+
+    def statecraft_graph
+      self.class.statecraft_mounting.machine_class.finalize!
+    end
+
+    def statecraft_current_state
+      self[self.class.statecraft_mounting.column].to_s.to_sym
+    end
+  end
+end

data/lib/statecraft/machine.rb

@@ -0,0 +1,315 @@
+# frozen_string_literal: true
+
+module Statecraft
+  # The machine DSL and its compiler. A machine is declared in a dedicated
+  # class (`include Statecraft::Machine`), collects states, edges, events and
+  # callbacks, and compiles them into a deep-frozen graph on finalization.
+  # 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)
+    Callback = Struct.new(:handler, :from, :to, :event, keyword_init: true)
+    CompiledGraph = Struct.new(
+      :states, :initial_state, :edges, :events, :callbacks,
+      keyword_init: true
+    )
+
+    CALLBACK_PHASES = %i[before_transition after_transition after_commit].freeze
+
+    def self.included(machine_class)
+      machine_class.extend(ClassMethods)
+    end
+
+    # Invokes a guard or callback handler with the honest-call convention:
+    # a Symbol resolves to a (possibly private) instance method of the machine,
+    # a callable is called as-is with `self` untouched. Arity 1 receives the
+    # record alone, everything else receives (record, payload) — the same
+    # dispatch Active Record validators use.
+    module Handlers
+      def self.invoke(machine_instance, handler, record, payload)
+        callable = resolve(machine_instance, handler)
+        if unary?(callable)
+          callable.call(record)
+        else
+          callable.call(record, payload)
+        end
+      end
+
+      def self.resolve(machine_instance, handler)
+        handler.is_a?(Symbol) ? machine_instance.method(handler) : handler
+      end
+
+      def self.unary?(callable)
+        callable.arity == 1
+      end
+    end
+
+    # Class-level DSL collected declaratively and compiled by finalize!.
+    module ClassMethods
+      def state(name, initial: false)
+        declared_states << { name: name, initial: initial }
+      end
+
+      def transition(from:, to:, guard: nil, lock: false)
+        declared_edges << {
+          from: from, to: to, guards: Array(guard), lock: lock || current_event_lock,
+          event: current_event_name
+        }
+      end
+
+      def event(name, from: nil, to: nil, guard: nil, lock: false, &declarations)
+        declared_event_names << name
+        if declarations
+          if from || to
+            raise CompilationError, "event #{name.inspect} takes either inline from:/to: or a block, not both"
+          end
+
+          begin
+            @statecraft_current_event = { name: name, lock: lock }
+            yield
+          ensure
+            @statecraft_current_event = nil
+          end
+        else
+          raise CompilationError, "event #{name.inspect} needs from:/to: or a block" if from.nil? || to.nil?
+
+          @statecraft_current_event = { name: name, lock: false }
+          begin
+            transition(from: from, to: to, guard: guard, lock: lock)
+          ensure
+            @statecraft_current_event = nil
+          end
+        end
+      end
+
+      CALLBACK_PHASES.each do |phase|
+        define_method(phase) do |handler = nil, from: nil, to: nil, event: nil, &block|
+          callback_handler = handler || block
+          raise CompilationError, "#{phase} needs a method name or a callable" if callback_handler.nil?
+
+          declared_callbacks[phase] << Callback.new(
+            handler: callback_handler,
+            from: from && Array(from), to: to && Array(to), event: event && Array(event)
+          )
+        end
+      end
+
+      def states
+        compiled_graph.states
+      end
+
+      def events
+        compiled_graph.events.keys
+      end
+
+      def initial_state
+        compiled_graph.initial_state
+      end
+
+      def compiled_graph
+        finalize!
+      end
+
+      def finalized?
+        !@statecraft_compiled_graph.nil?
+      end
+
+      def finalize!
+        @statecraft_compiled_graph ||= Compiler.new(self).compile
+      end
+
+      def declared_states
+        @statecraft_declared_states ||= []
+      end
+
+      def declared_edges
+        @statecraft_declared_edges ||= []
+      end
+
+      def declared_event_names
+        @statecraft_declared_event_names ||= []
+      end
+
+      def declared_callbacks
+        @statecraft_declared_callbacks ||= CALLBACK_PHASES.to_h { |phase| [phase, []] }
+      end
+
+      private
+
+      def current_event_name
+        @statecraft_current_event && @statecraft_current_event[:name]
+      end
+
+      def current_event_lock
+        @statecraft_current_event ? @statecraft_current_event[:lock] : false
+      end
+    end
+
+    # Validates the declarations and produces the deep-frozen graph. All five
+    # compilation errors live here, plus symbol resolution: every Symbol guard
+    # or callback must exist as an instance method of the machine class at
+    # finalization time (never checked at the declaration line, so a guard may
+    # be declared above its def).
+    class Compiler
+      def initialize(machine_class)
+        @machine_class = machine_class
+      end
+
+      def compile
+        states = compile_states
+        initial = compile_initial(states)
+        edges = compile_edges(states)
+        events = compile_events(edges)
+        resolve_symbols(edges)
+        CompiledGraph.new(
+          states: states.freeze,
+          initial_state: initial,
+          edges: deep_freeze_edges(edges),
+          events: freeze_events(events),
+          callbacks: freeze_callbacks
+        ).freeze
+      end
+
+      private
+
+      attr_reader :machine_class
+
+      def compile_states
+        names = machine_class.declared_states.map { |declaration| declaration[:name] }
+        duplicate = names.tally.find { |_name, count| count > 1 }
+        raise CompilationError, "state #{duplicate.first.inspect} is declared twice" if duplicate
+
+        names
+      end
+
+      def compile_initial(states)
+        initials = machine_class.declared_states.select { |declaration| declaration[:initial] }.map { |d| d[:name] }
+        raise CompilationError, "exactly one initial state is required, got none" if initials.empty?
+        if initials.length > 1
+          raise CompilationError, "exactly one initial state is required, got #{initials.join(", ")}"
+        end
+
+        initials.first.tap { |initial| assert_known_state(initial, states) }
+      end
+
+      def compile_edges(states)
+        edges = {}
+        machine_class.declared_edges.each do |declaration|
+          assert_known_state(declaration[:from], states)
+          assert_known_state(declaration[:to], states)
+          pair = [declaration[:from], declaration[:to]]
+          edge = edges[pair]
+          if declaration[:event].nil?
+            raise CompilationError, "duplicate edge #{pair_name(pair)}" if edge
+
+            edges[pair] = build_edge(declaration)
+          else
+            edges[pair] = attach_event(edge, declaration, pair)
+          end
+        end
+        edges
+      end
+
+      def build_edge(declaration)
+        Edge.new(
+          from: declaration[:from], to: declaration[:to], lock: declaration[:lock],
+          edge_guards: declaration[:guards], event_names: [], event_guards: {}
+        )
+      end
+
+      def attach_event(edge, declaration, pair)
+        event_name = declaration[:event]
+        edge ||= Edge.new(
+          from: declaration[:from], to: declaration[:to], lock: false,
+          edge_guards: [], event_names: [], event_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.lock ||= declaration[:lock]
+        edge
+      end
+
+      def compile_events(edges)
+        events = machine_class.declared_event_names.to_h { |name| [name, {}] }
+        edges.each_value do |edge|
+          edge.event_names.each do |event_name|
+            branches = events[event_name]
+            if branches.key?(edge.from)
+              raise CompilationError,
+                    "event #{event_name.inspect} has two edges from #{edge.from.inspect}: " \
+                    "within one event, from must be unique"
+            end
+            branches[edge.from] = edge
+          end
+        end
+        events.each do |name, branches|
+          raise CompilationError, "event #{name.inspect} has no edges" if branches.empty?
+        end
+        events
+      end
+
+      def resolve_symbols(edges)
+        symbol_handlers(edges).each do |symbol|
+          next if machine_class.method_defined?(symbol) || machine_class.private_method_defined?(symbol)
+
+          raise CompilationError,
+                "guard or callback #{symbol.inspect} is not defined on #{machine_class.name || "the machine class"}"
+        end
+      end
+
+      def symbol_handlers(edges)
+        from_edges = edges.each_value.flat_map do |edge|
+          edge.edge_guards + edge.event_guards.values.flatten
+        end
+        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) }
+      end
+
+      def deep_freeze_edges(edges)
+        edges.each_value do |edge|
+          edge.edge_guards.freeze
+          edge.event_names.freeze
+          edge.event_guards.each_value(&:freeze)
+          edge.event_guards.freeze
+          edge.freeze
+        end
+        edges.freeze
+      end
+
+      def freeze_events(events)
+        events.each_value(&:freeze)
+        events.freeze
+      end
+
+      def freeze_callbacks
+        callbacks = machine_class.declared_callbacks
+        callbacks.each_value do |list|
+          list.each do |callback|
+            callback.from&.freeze
+            callback.to&.freeze
+            callback.event&.freeze
+            callback.freeze
+          end
+          list.freeze
+        end
+        callbacks.freeze
+      end
+
+      def assert_known_state(name, states)
+        return if states.include?(name)
+
+        raise CompilationError, "unknown state #{name.inspect}: declare it with state #{name.inspect}"
+      end
+
+      def pair_name(pair)
+        "#{pair.first} -> #{pair.last}"
+      end
+    end
+  end
+end

data/lib/statecraft/metadata.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Statecraft
+  # Normalizes transition metadata to exactly what will survive the jsonb
+  # round-trip, then deep-freezes it: what the guards checked is what the log
+  # stored. Symbols become strings (keys and values), times become ISO-8601
+  # strings, and anything that JSON cannot represent fails instantly at the
+  # pipeline entrance instead of inside the transaction.
+  module Metadata
+    def self.normalize(raw_metadata)
+      deep_freeze(round_trip(raw_metadata))
+    end
+
+    def self.round_trip(value)
+      case value
+      when Hash
+        value.to_h { |key, nested| [round_trip_key(key), round_trip(nested)] }
+      when Array
+        value.map { |element| round_trip(element) }
+      when String then value.dup
+      when Symbol then value.to_s
+      when Integer, Float, true, false, nil then value
+      when Time, Date, DateTime then value.iso8601
+      else
+        raise ArgumentError,
+              "metadata value #{value.inspect} (#{value.class}) is not JSON-serializable; " \
+              "metadata must round-trip through jsonb"
+      end
+    end
+
+    def self.round_trip_key(key)
+      case key
+      when String then key.dup
+      when Symbol, Integer then key.to_s
+      else
+        raise ArgumentError,
+              "metadata key #{key.inspect} (#{key.class}) is not a JSON object key"
+      end
+    end
+
+    def self.deep_freeze(value)
+      case value
+      when Hash
+        value.each { |key, nested| key.freeze && deep_freeze(nested) }
+      when Array
+        value.each { |element| deep_freeze(element) }
+      end
+      value.freeze
+    end
+  end
+end

data/lib/statecraft/mounting.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+module Statecraft
+  # The model-side macro. `state_machine OrderFlow, ...` mounts a compiled
+  # machine onto an ActiveRecord model: resolves the log class (convention
+  # `<base_class>Transition`, overridable via log:), runs the mounting-time
+  # checks (AlreadyMounted, composite primary keys, connection-class identity),
+  # finalizes the machine, verifies helper and scope name conflicts, generates
+  # scopes, and defines the reading surface (history, last_transition,
+  # 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,
+      keyword_init: true
+    )
+
+    def state_machine(machine_class, log: nil, column: :state, changed_at: 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
+      ).mount
+    end
+
+    # Performs the mounting steps in threshold order. Every check here works on
+    # 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:)
+        @model = model
+        @machine_class = machine_class
+        @log_option = log
+        @column = column
+        @changed_at = changed_at
+        @touch = touch
+        @helpers = helpers
+        @scopes = scopes
+      end
+
+      def mount
+        assert_not_mounted
+        assert_single_column_primary_key
+        log_class = resolve_log_class
+        assert_shared_connection_class(log_class)
+        graph = machine_class.finalize!
+        assert_no_verb_conflicts(graph)
+        assert_no_scope_conflicts(graph)
+        configuration = build_configuration(log_class)
+        store_configuration(configuration)
+        define_scopes(graph, configuration)
+        define_reading_surface
+        model.include(Pipeline::Surface)
+        model.include(Introspection)
+        define_verbs(graph) if @helpers
+        configuration
+      end
+
+      private
+
+      attr_reader :model, :machine_class
+
+      def assert_not_mounted
+        raise AlreadyMounted.new(model: model) if model.respond_to?(:statecraft_mounting)
+      end
+
+      def assert_single_column_primary_key
+        raise CompositePrimaryKeyUnsupported.new(model: model) if model.primary_key.is_a?(Array)
+      end
+
+      def resolve_log_class
+        return @log_option if @log_option
+
+        conventional_name = "#{model.base_class.name}Transition"
+        begin
+          Object.const_get(conventional_name)
+        rescue NameError
+          raise CompilationError,
+                "log class #{conventional_name} not found for #{model.name}: " \
+                "create it or pass log: explicitly"
+        end
+      end
+
+      def assert_shared_connection_class(log_class)
+        return if model.connection_specification_name == log_class.connection_specification_name
+
+        raise ConnectionMismatch.new(model: model, log_class: log_class)
+      end
+
+      def assert_no_verb_conflicts(graph)
+        return unless @helpers
+
+        graph.events.each_key do |event_name|
+          verb_names(event_name).each do |verb|
+            next unless model.method_defined?(verb) || model.private_method_defined?(verb)
+
+            raise CompilationError,
+                  "helper #{verb} for event #{event_name.inspect} conflicts with an existing " \
+                  "instance method on #{model.name}"
+          end
+        end
+      end
+
+      def assert_no_scope_conflicts(graph)
+        return unless @scopes
+
+        graph.states.each do |state_name|
+          next unless model.respond_to?(state_name, true)
+
+          raise CompilationError,
+                "scope #{state_name} conflicts with an existing class method on #{model.name}"
+        end
+      end
+
+      def verb_names(event_name)
+        ["#{event_name}!", event_name.to_s, "may_#{event_name}?"]
+      end
+
+      def build_configuration(log_class)
+        Configuration.new(
+          machine_class: machine_class,
+          log_class: log_class,
+          column: @column.to_sym,
+          changed_at_column: resolve_changed_at_column,
+          touch: @touch,
+          helpers: @helpers,
+          scopes: @scopes,
+          log_foreign_key: model.base_class.name.foreign_key.to_sym
+        ).freeze
+      end
+
+      def resolve_changed_at_column
+        case @changed_at
+        when false then nil
+        when true then :"#{@column}_changed_at"
+        else @changed_at.to_sym
+        end
+      end
+
+      def store_configuration(configuration)
+        model.define_singleton_method(:statecraft_mounting) { configuration }
+      end
+
+      def define_scopes(graph, configuration)
+        return unless configuration.scopes
+
+        column = configuration.column
+        graph.states.each do |state_name|
+          model.scope state_name, -> { where(column => state_name.to_s) }
+        end
+      end
+
+      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("may_#{event_name}?") { |metadata: {}| can_fire?(event_name, metadata: metadata) }
+          end
+        end
+        model.include(verbs)
+      end
+
+      def define_reading_surface
+        reading_surface = Module.new do
+          define_method(:history) do
+            config = self.class.statecraft_mounting
+            config.log_class.where(config.log_foreign_key => id).order(:id)
+          end
+
+          define_method(:last_transition) do
+            history.last
+          end
+
+          define_method(:in_state?) do |state_name|
+            config = self.class.statecraft_mounting
+            self[config.column].to_s == state_name.to_s
+          end
+        end
+        model.include(reading_surface)
+      end
+    end
+  end
+end