statecraft 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b9f0a6cac349045859dd7966a325ae9d0a4b27175b846e8f43bd924b298576b6
-  data.tar.gz: a148de67af8ddd2bb976ae5ed03db6a38122ebd795013f9aae6c5803e45f7120
+  metadata.gz: f809e9a1769e457d33d4b526703e4c3c7beb4ca09f8a7550cbbd31c97b07ba12
+  data.tar.gz: 8193837939f39dd0de633330b7bfc36d7adbb821221072ce1cdf30890f3488d0
 SHA512:
-  metadata.gz: a48dbba9f2e06f23bbcffc0fc632f17f6915954737c2f104c132fa8763823bb9f07a0e754dabf4eb95d14b21b97c912885d0d1efa252c7e3ce64cedeeb206a22
-  data.tar.gz: 8256c0463e14d6ddf19d2a757647f81bae4bfa73ecc37796f905adc82d397dbdcb730c45861d23b172711e75aff224482de7dbbdc94a07fbbc9c4cca95fd4c37
+  metadata.gz: a5da582f65eb60cd2f76fef2ec213ad6c09166b288f44d80f7065a943894a66c5f36134f6c094fd873e50562976a447d0183b3e0e47b5545bce707d63f965d83
+  data.tar.gz: f1247259b3bc97de6663d9545e00015e1ea443b9e9f0ac33af6a179c09ba534140b0037863ddd2fa64e4992234a5fe14ea0d43e4a9ddc30d1018927c0d3158c5

data/README.md

@@ -1,7 +1,11 @@
 # statecraft
 
+[![Gem Version](https://img.shields.io/gem/v/statecraft.svg)](https://rubygems.org/gems/statecraft)
+[![CI](https://github.com/supostat/statecraft/actions/workflows/ci.yml/badge.svg)](https://github.com/supostat/statecraft/actions/workflows/ci.yml)
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
 
+**[Website →](https://supostat.github.io/statecraft/)** · [RubyGems](https://rubygems.org/gems/statecraft) · [Issues](https://github.com/supostat/statecraft/issues)
+
 A state machine for ActiveRecord where the current state lives in a column as
 the single source of truth, history is an append-only per-model log with
 write-once metadata, and every transition is guarded by a compare-and-swap
@@ -96,7 +100,8 @@ generator turns them on for new code).
    reload.
 5. `transaction(requires_new: true)` — a savepoint inside your transaction,
    a real transaction otherwise: optional `SELECT ... FOR UPDATE` + reload
-   (with edge re-resolution from the fresh state), guards, `before_transition`
+   (a state that changed under the lock raises
+   `Statecraft::TransitionConflict`), guards, `before_transition`
    callbacks, the CAS update (touching `updated_at` and the `changed_at`
    column in the same statement), the log INSERT, `after_transition`.
 6. `after_commit` callbacks are registered on the outermost real
@@ -108,9 +113,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
 
@@ -212,7 +218,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 })`.
@@ -309,7 +322,8 @@ The log lives next to its model, always — a cascade FK cannot cross
 databases, so this is a definition, not a restriction. The generated log
 class inherits the model's connection-owning ancestor (base, roles and
 horizontal shards follow automatically), and the generator drops the
-migration into that connection's migration path. Mounting verifies connection
+migration into the migration path configured for that connection's database
+(`db/migrate` when none is configured). Mounting verifies connection
 identity — same pool, same per-thread connection, one real transaction — and
 raises `Statecraft::ConnectionMismatch` with a fix hint otherwise. Two
 `connects_to` blocks pointing at one physical database are still two pools:
@@ -369,6 +383,12 @@ docker compose run --rm test-postgres                       # PostgreSQL 16
 AR_VERSION=7.2 RUBY_VERSION=3.3 docker compose run --rm test-postgres
 ```
 
+## Links
+
+- Landing page: <https://supostat.github.io/statecraft/>
+- RubyGems: <https://rubygems.org/gems/statecraft>
+- Issues: <https://github.com/supostat/statecraft/issues>
+
 ## License
 
 MIT. See [LICENSE.txt](LICENSE.txt).

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/machine_generator.rb

@@ -10,16 +10,16 @@ module Statecraft
     # the per-model log table with a cascade FK and a CHECK constraint for a
     # freshly created table), the machine class, the readonly log model, the
     # model mounting with helpers and scopes on, and lazily the shared
-    # ApplicationMachine parent. The migration lands in the migration path of
-    # the model's connection owner, so multi-database apps get it next to
-    # their model.
+    # ApplicationMachine parent. The migration lands in the migration path
+    # configured for the model's database, so multi-database apps get it next
+    # to their model.
     class MachineGenerator < Rails::Generators::NamedBase
       include ActiveRecord::Generators::Migration
 
       source_root File.expand_path("templates", __dir__)
 
       def detect_model_presence
-        @existing_model = File.exist?(File.join(destination_root, "app/models/#{file_name}.rb"))
+        @existing_model = File.exist?(File.join(destination_root, model_file))
       end
 
       def create_application_machine
@@ -29,26 +29,35 @@ module Statecraft
         template "application_machine.rb.tt", application_machine_path
       end
 
+      def create_namespace_module
+        return if class_path.empty? || existing_model?
+
+        module_file = "app/models/#{class_path.join("/")}.rb"
+        return if File.exist?(File.join(destination_root, module_file))
+
+        template "namespace_module.rb.tt", module_file
+      end
+
       def create_machine_class
-        template "machine.rb.tt", "app/state_machines/#{file_name}_flow.rb"
+        template "machine.rb.tt", "app/state_machines/#{file_path}_flow.rb"
       end
 
       def create_log_model
-        template "log_model.rb.tt", "app/models/#{file_name}_transition.rb"
+        template "log_model.rb.tt", "app/models/#{file_path}_transition.rb"
       end
 
       def create_or_mount_model
         if existing_model?
-          inject_into_class "app/models/#{file_name}.rb", class_name, mounting_line
+          inject_into_class model_file, mounting_target_class, mounting_line
         else
-          template "model.rb.tt", "app/models/#{file_name}.rb"
+          template "model.rb.tt", model_file
         end
       end
 
       def create_migration_file
         migration_source = existing_model? ? "add_migration.rb.tt" : "create_migration.rb.tt"
         migration_template migration_source,
-                           "#{migration_directory}/create_#{file_name}_state_machine.rb"
+                           "#{migration_directory}/create_#{migration_slug}_state_machine.rb"
       end
 
       private
@@ -57,22 +66,43 @@ module Statecraft
         @existing_model
       end
 
+      def model_file
+        "app/models/#{file_path}.rb"
+      end
+
       def mounting_line
         "  state_machine #{class_name}Flow, changed_at: true, helpers: true, scopes: true\n"
       end
 
+      # inject_into_class matches the literal `class <name>` line, so the name
+      # must follow the style the model file actually uses: the full constant
+      # for the compact `class Shop::Order` style, the demodulized one for
+      # `module Shop / class Order` nesting.
+      def mounting_target_class
+        return class_name if class_path.empty?
+
+        model_source = File.read(File.join(destination_root, model_file))
+        model_source.match?(/class #{class_name}\b/) ? class_name : class_name.demodulize
+      end
+
+      # Without a configured migrations_paths, `rails db:migrate` reads
+      # db/migrate for every database — so that is the honest fallback.
       def migration_directory
-        specification_name = model_connection_specification_name
-        return "db/migrate" if specification_name.nil? || specification_name == "ActiveRecord::Base"
+        db_config = model_class&.connection_db_config
+        configured = db_config && Array(db_config.migrations_paths).first
+        configured || "db/migrate"
+      end
 
-        "db/#{specification_name.underscore.tr("/", "_")}_migrate"
+      def model_class
+        class_name.safe_constantize
       end
 
-      def model_connection_specification_name
-        model_class = class_name.safe_constantize
-        model_class&.connection_specification_name
-      rescue StandardError
-        nil
+      # The generated model's table follows the loaded model when one exists;
+      # otherwise the Rails naming convention for the argument, namespace
+      # included (`Shop::Order` -> shop_orders, matching the generated
+      # namespace module's table_name_prefix).
+      def table_name
+        @table_name ||= model_class ? model_class.table_name : super
       end
 
       def log_table_name
@@ -80,7 +110,7 @@ module Statecraft
       end
 
       def parent_class_name
-        specification_name = model_connection_specification_name
+        specification_name = model_class&.connection_specification_name
         return "ApplicationRecord" if specification_name.nil? || specification_name == "ActiveRecord::Base"
 
         specification_name
@@ -90,8 +120,12 @@ module Statecraft
         "#{file_name}_id"
       end
 
+      def migration_slug
+        file_path.tr("/", "_")
+      end
+
       def migration_class_name
-        "Create#{class_name}StateMachine"
+        "Create#{migration_slug.camelize}StateMachine"
       end
     end
   end

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

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+<% class_path.each_with_index do |part, depth| -%>
+<%= "  " * depth %>module <%= part.camelize %>
+<% end -%>
+<%= "  " * class_path.length %>def self.table_name_prefix
+<%= "  " * class_path.length %>  "<%= class_path.join("_") %>_"
+<%= "  " * class_path.length %>end
+<% (class_path.length - 1).downto(0) do |depth| -%>
+<%= "  " * depth %>end
+<% end -%>

data/lib/statecraft/machine.rb

@@ -40,24 +40,28 @@ 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)
         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), lock: lock || current_event_lock,
           event: current_event_name
         }
       end
 
       def event(name, from: nil, to: nil, guard: nil, lock: false, &declarations)
+        name = name.to_sym
         declared_event_names << name
         if declarations
           if from || to
@@ -89,7 +93,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
@@ -114,8 +120,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 +145,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
@@ -268,7 +283,7 @@ 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
 
       def deep_freeze_edges(edges)

data/lib/statecraft/metadata.rb

@@ -19,7 +19,8 @@ module Statecraft
         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 Integer, true, false, nil then value
+      when Float then round_trip_float(value)
       when Time, Date, DateTime then value.iso8601
       else
         raise ArgumentError,
@@ -28,6 +29,14 @@ module Statecraft
       end
     end
 
+    def self.round_trip_float(value)
+      return value if value.finite?
+
+      raise ArgumentError,
+            "metadata value #{value.inspect} is not JSON-serializable; " \
+            "jsonb has no NaN or Infinity"
+    end
+
     def self.round_trip_key(key)
       case key
       when String then key.dup

data/lib/statecraft/mounting.rb

@@ -40,7 +40,6 @@ module Statecraft
 
       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!
@@ -64,10 +63,6 @@ module Statecraft
         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
 
@@ -87,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/surface.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Statecraft
+  class Pipeline
+    # The record-facing API mixed into the model at mounting time. Bang
+    # variants return the created log record; non-bang variants return it too,
+    # or false on GuardFailed / InvalidTransition. Programmer errors and
+    # TransitionConflict always raise.
+    module Surface
+      def transition_to!(to_state, metadata: {}, bypass_events: false)
+        Pipeline.new(self).direct(to_state, metadata: metadata, bypass_events: bypass_events)
+      end
+
+      def transition_to(to_state, metadata: {}, bypass_events: false)
+        transition_to!(to_state, metadata: metadata, bypass_events: bypass_events)
+      rescue GuardFailed, InvalidTransition
+        false
+      end
+
+      def fire!(event_name, metadata: {})
+        Pipeline.new(self).fire(event_name, metadata: metadata)
+      end
+
+      def fire(event_name, metadata: {})
+        fire!(event_name, metadata: metadata)
+      rescue GuardFailed, InvalidTransition
+        false
+      end
+    end
+  end
+end

data/lib/statecraft/pipeline.rb

@@ -5,7 +5,7 @@ module Statecraft
   #
   #   persisted? -> metadata normalize+freeze -> edge resolution ->
   #   dirty check (lock only) -> transaction(requires_new: true) [
-  #     lock+reload -> re-resolve edge from fresh state -> guards ->
+  #     lock+reload -> conflict check against the resolved edge -> guards ->
   #     before_transition -> CAS UPDATE -> log INSERT (insert path) ->
   #     after_transition
   #   ] -> after_commit registration on the outermost real commit
@@ -28,36 +28,12 @@ module Statecraft
     STACK_KEY = :statecraft_transition_stack
     MAX_CHAIN_DEPTH = 16
 
+    include EdgeResolution
+
     def self.transition_stack
       ActiveSupport::IsolatedExecutionState[STACK_KEY] ||= []
     end
 
-    # The record-facing API mixed into the model at mounting time. Bang
-    # variants return the created log record; non-bang variants return it too,
-    # or false on GuardFailed / InvalidTransition. Programmer errors and
-    # TransitionConflict always raise.
-    module Surface
-      def transition_to!(to_state, metadata: {}, bypass_events: false)
-        Pipeline.new(self).direct(to_state, metadata: metadata, bypass_events: bypass_events)
-      end
-
-      def transition_to(to_state, metadata: {}, bypass_events: false)
-        transition_to!(to_state, metadata: metadata, bypass_events: bypass_events)
-      rescue GuardFailed, InvalidTransition
-        false
-      end
-
-      def fire!(event_name, metadata: {})
-        Pipeline.new(self).fire(event_name, metadata: metadata)
-      end
-
-      def fire(event_name, metadata: {})
-        fire!(event_name, metadata: metadata)
-      rescue GuardFailed, InvalidTransition
-        false
-      end
-    end
-
     def initialize(record)
       @record = record
       @configuration = record.class.statecraft_mounting
@@ -86,6 +62,7 @@ module Statecraft
     def run(raw_metadata, &edge_resolver)
       raise UnsavedRecordError.new(record: record) unless record.persisted?
 
+      assert_single_column_primary_key
       metadata = Metadata.normalize(raw_metadata)
       started_at = Time.current
       begin
@@ -93,18 +70,12 @@ module Statecraft
         assert_clean_when_locked(edge)
         frame = open_frame(edge, event)
         begin
-          log_record = execute_transaction(edge, event, bypass, metadata, edge_resolver, frame)
+          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 => guard_error
-        publish_failure(started_at, :guard_failed, guard: guard_error.guard)
-        raise
-      rescue InvalidTransition => invalid_error
-        publish_failure(started_at, :invalid_transition, requested: invalid_error.requested)
-        raise
-      rescue TransitionConflict => conflict_error
-        publish_failure(started_at, :conflict, expected_from: conflict_error.expected_from)
+      rescue GuardFailed, InvalidTransition, TransitionConflict => transition_error
+        publish_failure(started_at, transition_error)
         raise
       end
       Instrumentation.publish_transition(
@@ -115,19 +86,25 @@ module Statecraft
       log_record
     end
 
-    def publish_failure(started_at, reason, details)
+    def publish_failure(started_at, error)
+      reason, details =
+        case error
+        when GuardFailed then [:guard_failed, { guard: error.guard }]
+        when InvalidTransition then [:invalid_transition, { requested: error.requested }]
+        when TransitionConflict then [:conflict, { expected_from: error.expected_from }]
+        end
       Instrumentation.publish_failure(
         started_at: started_at, record: record,
         machine_class: configuration.machine_class, reason: reason, details: details
       )
     end
 
-    def execute_transaction(edge, event, bypass, metadata, edge_resolver, frame)
+    def execute_transaction(edge, event, bypass, metadata, frame)
       base_class.transaction(requires_new: true) do
         if edge.lock
           warn_when_row_locking_unavailable
           record.reload(lock: true)
-          edge, event, bypass = edge_resolver.call(current_state)
+          assert_lock_saw_expected_state(edge)
         end
         transition_time = Time.current
         run_guards(edge, event, bypass, metadata)
@@ -138,8 +115,13 @@ module Statecraft
         cas_update!(edge, transition_time)
         frame.cas_done = true
         context.log_record = insert_log_row(edge, event, metadata, transition_time)
-        sync_record(edge, transition_time)
-        run_callbacks(:after_transition, context)
+        synced_snapshot = sync_record(edge, transition_time)
+        begin
+          run_callbacks(:after_transition, context)
+        rescue Exception # rubocop:disable Lint/RescueException -- the savepoint rolls the database back on ANY exception, so the in-memory sync must roll back with it
+          restore_synced_attributes(synced_snapshot)
+          raise
+        end
         context.log_record
       end
     end
@@ -169,39 +151,13 @@ 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
+    # 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.
+    def assert_single_column_primary_key
+      return unless base_class.primary_key.is_a?(Array)
 
-    def allowed_targets(current)
-      graph.edges.keys.select { |from, _to| from == current }.map(&:last)
+      raise CompositePrimaryKeyUnsupported.new(model: base_class)
     end
 
     def assert_clean_when_locked(edge)
@@ -210,6 +166,16 @@ module Statecraft
       raise DirtyRecordError.new(record: record, changed_attributes: record.changed)
     end
 
+    # The lock reload can reveal a state that no longer matches the edge the
+    # caller validated. That is a concurrent write observed early: the same
+    # conflict CAS would report, so it raises the same error instead of
+    # silently resolving a different edge from the fresh state.
+    def assert_lock_saw_expected_state(edge)
+      return if current_state == edge.from
+
+      raise TransitionConflict.new(record: record, expected_from: edge.from)
+    end
+
     def run_guards(edge, event, bypass, metadata)
       guards = edge.edge_guards.dup
       guards.concat(edge.event_guards.fetch(event, [])) if event && !bypass
@@ -267,18 +233,20 @@ module Statecraft
       log_class.find(log_id)
     end
 
+    # Mirrors exactly what the CAS statement wrote into the row, without a
+    # dirty mark, and returns the prior values so a failing after_transition
+    # can roll the memory back alongside the savepoint.
     def sync_record(edge, transition_time)
-      synced_columns = [configuration.column]
-      record[configuration.column] = edge.to.to_s
-      if touch_updated_at?
-        record[:updated_at] = transition_time
-        synced_columns << :updated_at
-      end
-      if changed_at_column
-        record[changed_at_column] = transition_time
-        synced_columns << changed_at_column
-      end
-      record.clear_attribute_changes(synced_columns)
+      updates = cas_updates(edge, transition_time)
+      snapshot = updates.to_h { |column, _value| [column, record[column]] }
+      updates.each { |column, value| record[column] = value }
+      record.clear_attribute_changes(updates.keys)
+      snapshot
+    end
+
+    def restore_synced_attributes(snapshot)
+      snapshot.each { |column, value| record[column] = value }
+      record.clear_attribute_changes(snapshot.keys)
     end
 
     def register_after_commit_callbacks(log_record, metadata)
@@ -310,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.1"
+  VERSION = "0.1.3"
 end

data/lib/statecraft.rb

@@ -9,7 +9,9 @@ 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"
 require_relative "statecraft/mounting"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: statecraft
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.3
 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
@@ -67,6 +68,7 @@ files:
 - lib/generators/statecraft/machine/templates/log_model.rb.tt
 - lib/generators/statecraft/machine/templates/machine.rb.tt
 - lib/generators/statecraft/machine/templates/model.rb.tt
+- lib/generators/statecraft/machine/templates/namespace_module.rb.tt
 - lib/statecraft.rb
 - lib/statecraft/errors.rb
 - lib/statecraft/instrumentation.rb
@@ -75,6 +77,8 @@ 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
 homepage: https://supostat.github.io/statecraft/