fosm-rails 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 632476c001f595b1c39b2eb3a98af17ff6aeca2c54505a373c85bc442d3f07fd
-  data.tar.gz: 1d1401c44b00161288485afa4bb7228cfd88e216b1254d12233345334d437eeb
+  metadata.gz: f7d819f282973824d9dcb7c7d502193f59f3394602ff7f334eddb160eb401a10
+  data.tar.gz: 1b4ced5b691e16ffde902dd1686e8d5c05723e96eaab610a7f0f01950703e925
 SHA512:
-  metadata.gz: 343cff86bca38d2098bee6b13a577c4d9b2ec1f14dd186d12f1ea239817768a737e86542cd74eb8f6266bcc4388faf615351ed6d8677420863d7f6ca1aa3560d
-  data.tar.gz: 5f811cda70c5a7321af1599ce639da25b746f70a81e7dbbecb108acd4773259cb2b00450979ab6268a4f41436c3b6a4e8c767d393972cc025701d3a00d940e7e
+  metadata.gz: f98e77d77b443810901e802538cb1a169d9dbf0ecc63c64b19d64b14a782b181748199e5d51520c812f27f1b0f9779786a739a21f5ecfba093c2024b1bbe46c2
+  data.tar.gz: 39179d9dd4fa91b077745547ba29c667c19d74e966f2eb0a2d88ed2bd370ea03b3862080179d6be15c079710eed1a759f0f8dee4fecd3440fc1250d3fecdfe6e

data/app/controllers/fosm/admin/settings_controller.rb

@@ -13,7 +13,7 @@ module Fosm
         { name: "OpenAI",              env_key: "OPENAI_API_KEY",       model_prefix: "openai/" },
         { name: "Google (Gemini)",     env_key: "GEMINI_API_KEY",       model_prefix: "gemini/" },
         { name: "Cohere",              env_key: "COHERE_API_KEY",       model_prefix: "cohere/" },
-        { name: "Mistral",             env_key: "MISTRAL_API_KEY",      model_prefix: "mistral/" },
+        { name: "Mistral",             env_key: "MISTRAL_API_KEY",      model_prefix: "mistral/" }
       ].freeze
 
       def detect_llm_providers

data/app/controllers/fosm/admin/transitions_controller.rb

@@ -10,7 +10,7 @@ module Fosm
         @transitions = @transitions.where.not(actor_type: "symbol") if params[:actor] == "human"
 
         @per_page = 50
-        @current_page = [params[:page].to_i, 1].max
+        @current_page = [ params[:page].to_i, 1 ].max
         @total_count = @transitions.count
         @total_pages = (@total_count / @per_page.to_f).ceil
         @transitions = @transitions.limit(@per_page).offset((@current_page - 1) * @per_page)

data/app/models/fosm/transition_log.rb

@@ -1,6 +1,7 @@
 module Fosm
   # Immutable audit trail of every FOSM state transition.
   # Records are never updated or deleted — this is an append-only log.
+  # Supports optional state snapshots for efficient replay and audit.
   class TransitionLog < ApplicationRecord
     self.table_name = "fosm_transition_logs"
 
@@ -16,6 +17,11 @@ module Fosm
     scope :by_event, ->(event) { where(event_name: event.to_s) }
     scope :by_actor_type, ->(type) { where(actor_type: type) }
 
+    # Snapshot-related scopes
+    scope :with_snapshot, -> { where.not(state_snapshot: nil) }
+    scope :without_snapshot, -> { where(state_snapshot: nil) }
+    scope :by_snapshot_reason, ->(reason) { where(snapshot_reason: reason) }
+
     def by_agent?
       actor_type == "symbol" && actor_label == "agent"
     end
@@ -23,5 +29,10 @@ module Fosm
     def by_human?
       !by_agent? && actor_id.present?
     end
+
+    # Returns true if this log entry includes a state snapshot
+    def snapshot?
+      state_snapshot.present?
+    end
   end
 end

data/app/views/fosm/admin/apps/show.html.erb

@@ -12,12 +12,16 @@
       <% end %>
     </div>
     <div class="flex gap-2 shrink-0">
-      <%= link_to "View all #{@model_class.name.demodulize.humanize.pluralize}",
-                  main_app.send("fosm_#{@slug.pluralize}_path"),
-                  class: "text-sm border border-gray-200 bg-white text-gray-700 px-3 py-1.5 rounded hover:bg-gray-50" %>
-      <%= link_to "+ New #{@model_class.name.demodulize.humanize}",
-                  main_app.send("new_fosm_#{@slug}_path"),
-                  class: "text-sm bg-gray-900 text-white px-3 py-1.5 rounded hover:bg-gray-700" %>
+      <% if main_app.respond_to?("fosm_#{@slug.pluralize}_path") %>
+        <%= link_to "View all #{@model_class.name.demodulize.humanize.pluralize}",
+                    main_app.send("fosm_#{@slug.pluralize}_path"),
+                    class: "text-sm border border-gray-200 bg-white text-gray-700 px-3 py-1.5 rounded hover:bg-gray-50" %>
+      <% end %>
+      <% if main_app.respond_to?("new_fosm_#{@slug}_path") %>
+        <%= link_to "+ New #{@model_class.name.demodulize.humanize}",
+                    main_app.send("new_fosm_#{@slug}_path"),
+                    class: "text-sm bg-gray-900 text-white px-3 py-1.5 rounded hover:bg-gray-700" %>
+      <% end %>
       <%= link_to "Agent Tools",
                   fosm.agent_admin_app_path(@slug),
                   class: "text-sm border border-purple-200 bg-purple-50 text-purple-700 px-3 py-1.5 rounded hover:bg-purple-100" %>
@@ -186,9 +190,13 @@
           <% @recent_transitions.each do |t| %>
             <tr>
               <td class="py-2 text-gray-600">
-                <%= link_to "##{t.record_id}",
-                            main_app.send("fosm_#{@slug}_path", t.record_id),
-                            class: "text-blue-600 hover:underline" %>
+                <% if main_app.respond_to?("fosm_#{@slug}_path") %>
+                  <%= link_to "##{t.record_id}",
+                              main_app.send("fosm_#{@slug}_path", t.record_id),
+                              class: "text-blue-600 hover:underline" %>
+                <% else %>
+                  <span class="text-gray-500">#<%= t.record_id %></span>
+                <% end %>
               </td>
               <td class="py-2 font-medium"><%= t.event_name %></td>
               <td class="py-2">

data/config/routes.rb

@@ -1,7 +1,7 @@
 Fosm::Engine.routes.draw do
   namespace :admin do
     root to: "dashboard#index"
-    resources :apps, only: [:index, :show], param: :slug do
+    resources :apps, only: [ :index, :show ], param: :slug do
       member do
         get    :agent,       to: "agents#show"
         post   :agent_invoke, to: "agents#agent_invoke"
@@ -10,13 +10,13 @@ Fosm::Engine.routes.draw do
         delete "agent/chat",  to: "agents#chat_reset", as: :agent_chat_reset
       end
     end
-    resources :transitions, only: [:index]
-    resources :webhooks,    only: [:index, :new, :create, :destroy]
-    resources :roles, only: [:index, :new, :create, :destroy] do
+    resources :transitions, only: [ :index ]
+    resources :webhooks,    only: [ :index, :new, :create, :destroy ]
+    resources :roles, only: [ :index, :new, :create, :destroy ] do
       collection do
         get :users_search
       end
     end
-    resource  :settings,    only: [:show]
+    resource :settings,    only: [ :show ]
   end
 end

data/db/migrate/20240101000001_create_fosm_transition_logs.rb

@@ -15,7 +15,7 @@ class CreateFosmTransitionLogs < ActiveRecord::Migration[8.1]
       t.datetime :created_at,  null: false, default: -> { "CURRENT_TIMESTAMP" }
     end
 
-    add_index :fosm_transition_logs, [:record_type, :record_id], name: "idx_fosm_tl_record"
+    add_index :fosm_transition_logs, [ :record_type, :record_id ], name: "idx_fosm_tl_record"
     add_index :fosm_transition_logs, :event_name, name: "idx_fosm_tl_event"
     add_index :fosm_transition_logs, :created_at, name: "idx_fosm_tl_created_at"
     add_index :fosm_transition_logs, :actor_label, name: "idx_fosm_tl_actor"

data/db/migrate/20240101000002_create_fosm_webhook_subscriptions.rb

@@ -10,7 +10,7 @@ class CreateFosmWebhookSubscriptions < ActiveRecord::Migration[8.1]
       t.timestamps
     end
 
-    add_index :fosm_webhook_subscriptions, [:model_class_name, :event_name], name: "idx_fosm_webhooks_model_event"
+    add_index :fosm_webhook_subscriptions, [ :model_class_name, :event_name ], name: "idx_fosm_webhooks_model_event"
     add_index :fosm_webhook_subscriptions, :active, name: "idx_fosm_webhooks_active"
   end
 end

data/db/migrate/20240101000005_add_state_snapshot_to_fosm_transition_logs.rb

@@ -0,0 +1,7 @@
+class AddStateSnapshotToFosmTransitionLogs < ActiveRecord::Migration[8.1]
+  def change
+    add_column :fosm_transition_logs, :state_snapshot, :json, default: nil
+    add_column :fosm_transition_logs, :snapshot_reason, :string, default: nil
+    add_index :fosm_transition_logs, :snapshot_reason, name: "idx_fosm_tl_snapshot_reason"
+  end
+end

data/lib/fosm/engine.rb

@@ -125,7 +125,7 @@ module Fosm
           klass.respond_to?(:fosm_lifecycle) &&
           klass.fosm_lifecycle.present?
       }.each do |klass|
-        slug = klass.name.demodulize.underscore.dasherize
+        slug = klass.name.demodulize.underscore
         Fosm::Registry.register(klass, slug: slug)
       end
 

data/lib/fosm/errors.rb

@@ -16,9 +16,17 @@ module Fosm
   end
 
   # Raised when a guard blocks a transition
+  # 🆕 Supports optional reason for better error messages
   class GuardFailed < Error
-    def initialize(guard_name, event_name)
-      super("Guard '#{guard_name}' prevented transition for event '#{event_name}'")
+    attr_reader :guard_name, :event_name, :reason
+
+    def initialize(guard_name, event_name, reason = nil)
+      @guard_name = guard_name
+      @event_name = event_name
+      @reason = reason
+      msg = "Guard '#{guard_name}' prevented transition for event '#{event_name}'"
+      msg += ": #{reason}" if reason
+      super(msg)
     end
   end
 

data/lib/fosm/lifecycle/definition.rb

@@ -3,6 +3,7 @@ require_relative "event_definition"
 require_relative "guard_definition"
 require_relative "side_effect_definition"
 require_relative "access_definition"
+require_relative "snapshot_configuration"
 
 module Fosm
   module Lifecycle
@@ -89,8 +90,14 @@ module Fosm
       end
 
       # DSL: declare a side effect on an event
-      def side_effect(name, on:, &block)
-        side_effect_def = SideEffectDefinition.new(name: name, &block)
+      # Options:
+      #   defer: false (default), true — run after transaction commits
+      def side_effect(name, on:, defer: false, &block)
+        side_effect_def = SideEffectDefinition.new(
+          name: name,
+          defer: defer,
+          &block
+        )
         event_def = find_event(on)
         if event_def
           event_def.add_side_effect(side_effect_def)
@@ -125,6 +132,48 @@ module Fosm
         @events.select { |e| e.valid_from?(state) }
       end
 
+      # DSL: configure automatic state snapshots on transitions
+      # Supports multiple strategies for how often to snapshot:
+      #
+      #   snapshot :every        # snapshot on every transition
+      #   snapshot every: 10      # snapshot every 10 transitions
+      #   snapshot time: 300      # snapshot if >5 min since last snapshot
+      #   snapshot :terminal      # snapshot only when reaching terminal states
+      #   snapshot :manual        # only snapshot when explicitly requested (default)
+      #
+      #   snapshot_attributes :amount, :due_date, :line_items_count
+      #
+      def snapshot(strategy = nil, **options)
+        @snapshot_configuration ||= SnapshotConfiguration.new
+
+        if strategy.is_a?(Symbol) || strategy.is_a?(String)
+          @snapshot_configuration.send(strategy)
+        elsif options[:every]
+          @snapshot_configuration.count(options[:every])
+        elsif options[:time]
+          @snapshot_configuration.time(options[:time])
+        end
+
+        @snapshot_configuration
+      end
+
+      # DSL: specify which attributes to include in snapshots
+      # Usage: snapshot_attributes :amount, :status, :line_items_count
+      def snapshot_attributes(*attrs)
+        @snapshot_configuration ||= SnapshotConfiguration.new
+        @snapshot_configuration.set_attributes(*attrs)
+      end
+
+      # Returns true if snapshot configuration has been set
+      def snapshot_configured?
+        @snapshot_configuration.present?
+      end
+
+      # Returns the snapshot configuration (nil if not configured)
+      def snapshot_configuration
+        @snapshot_configuration
+      end
+
       # Returns a hash suitable for rendering a state diagram
       def to_diagram_data
         {

data/lib/fosm/lifecycle/guard_definition.rb

@@ -11,6 +11,28 @@ module Fosm
       def call(record)
         @block.call(record)
       end
+
+      # 🆕 Evaluate guard and return [allowed, reason] tuple
+      # Supports: true/false (legacy), String (failure reason), [:fail, reason]
+      def evaluate(record)
+        result = call(record)
+
+        case result
+        when true
+          [ true, nil ]
+        when false
+          [ false, nil ]
+        when String
+          # String is treated as failure reason
+          [ false, result ]
+        when Array
+          result[0] == :fail ? [ false, result[1] ] : [ true, nil ]
+        else
+          # 🆕 Any other truthy value is treated as passing
+          # Only false/nil fails; everything else passes
+          result ? [ true, nil ] : [ false, nil ]
+        end
+      end
     end
   end
 end

data/lib/fosm/lifecycle/side_effect_definition.rb

@@ -1,16 +1,21 @@
 module Fosm
   module Lifecycle
     class SideEffectDefinition
-      attr_reader :name
+      attr_reader :name, :deferred
 
-      def initialize(name:, &block)
+      def initialize(name:, defer: false, &block)
         @name = name
+        @deferred = defer
         @block = block
       end
 
       def call(record, transition)
         @block.call(record, transition)
       end
+
+      def deferred?
+        @deferred
+      end
     end
   end
 end

data/lib/fosm/lifecycle/snapshot_configuration.rb

@@ -0,0 +1,148 @@
+module Fosm
+  module Lifecycle
+    # Configuration for when and what to snapshot during transitions.
+    # Supports multiple strategies: every, count, time, terminal, manual
+    class SnapshotConfiguration
+      # Strategy types
+      STRATEGIES = %i[every count time terminal manual].freeze
+
+      attr_reader :strategy, :interval, :conditions
+
+      def initialize
+        @strategy = :manual  # default: no automatic snapshots
+        @attributes = []     # empty = snapshot all readable attributes
+        @interval = nil      # for :count (transitions) or :time (seconds)
+        @conditions = []     # additional conditions that must be met
+      end
+
+      # Returns the configured attributes
+      def attributes
+        @attributes
+      end
+
+      # DSL: snapshot on every transition
+      # Usage: snapshot :every
+      def every
+        @strategy = :every
+      end
+
+      # DSL: snapshot every N transitions
+      # Usage: snapshot every: 10
+      def count(n)
+        @strategy = :count
+        @interval = n
+      end
+
+      # DSL: snapshot if last snapshot was more than N seconds ago
+      # Usage: snapshot time: 300 (5 minutes)
+      def time(seconds)
+        @strategy = :time
+        @interval = seconds
+      end
+
+      # DSL: snapshot only on terminal states
+      # Usage: snapshot :terminal
+      def terminal
+        @strategy = :terminal
+      end
+
+      # DSL: manual snapshots only (default)
+      # Usage: snapshot :manual
+      def manual
+        @strategy = :manual
+      end
+
+      # DSL: specify which attributes to snapshot
+      # Usage: snapshot_attributes :amount, :status, :line_items_count
+      #        snapshot_attributes %i[amount status]  # array also works
+      def set_attributes(*attrs)
+        @attributes = attrs.flatten.map(&:to_s)
+      end
+
+      # Check if a snapshot should be taken for this transition
+      # @param transition_count [Integer] transitions since last snapshot
+      # @param seconds_since_last [Float] seconds since last snapshot
+      # @param to_state [String] the state we're transitioning to
+      # @param to_state_terminal [Boolean] whether the destination state is terminal
+      # @param force [Boolean] manual override to force snapshot
+      def should_snapshot?(transition_count:, seconds_since_last:, to_state:, to_state_terminal:, force: false)
+        return true if force
+        return false if @strategy == :manual
+        return true if @strategy == :every
+        return true if @strategy == :terminal && to_state_terminal
+        return true if @strategy == :count && transition_count >= @interval
+        return true if @strategy == :time && seconds_since_last >= @interval
+
+        false
+      end
+
+      # Build the snapshot data from a record
+      # @param record [ActiveRecord::Base] the record to snapshot
+      # @return [Hash] the snapshot data
+      def build_snapshot(record)
+        attrs = @attributes.any? ? @attributes : default_attributes(record)
+
+        snapshot = {}
+        attrs.each do |attr|
+          value = read_attribute(record, attr)
+          snapshot[attr] = serialize_value(value)
+        end
+
+        # Always include core FOSM metadata
+        snapshot["_fosm_snapshot_meta"] = {
+          "snapshot_at" => Time.current.iso8601,
+          "record_class" => record.class.name,
+          "record_id" => record.id.to_s
+        }
+
+        snapshot
+      end
+
+      private
+
+      # Default attributes to snapshot when none specified
+      # Excludes internal AR columns and associations
+      def default_attributes(record)
+        record.attributes.keys.reject do |attr|
+          attr.start_with?("_") ||
+            %w[id created_at updated_at].include?(attr) ||
+            attr.end_with?("_id") && record.class.reflect_on_association(attr.sub(/_id$/, ""))
+        end
+      end
+
+      def read_attribute(record, attr)
+        # Handle associations (e.g., :line_items -> count)
+        if attr.to_s.end_with?("_count") || attr.to_s.start_with?("count_")
+          association_name = attr.to_s.gsub(/^_count|count_/, "").pluralize
+          if record.respond_to?(association_name)
+            record.send(association_name).count
+          else
+            record.send(attr)
+          end
+        else
+          record.send(attr)
+        end
+      rescue => e
+        # Graceful degradation: log error, return nil for this attribute
+        nil
+      end
+
+      def serialize_value(value)
+        case value
+        when ActiveRecord::Base
+          { "_type" => "record", "class" => value.class.name, "id" => value.id }
+        when ActiveRecord::Relation, Array
+          value.map { |v| serialize_value(v) }
+        when Time, DateTime, Date
+          { "_type" => "datetime", "value" => value.iso8601 }
+        when BigDecimal
+          { "_type" => "decimal", "value" => value.to_s }
+        when Symbol
+          value.to_s
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/fosm/lifecycle.rb

@@ -34,8 +34,8 @@ module Fosm
 
         # Generate dynamic bang methods per event: invoice.send_invoice!(actor: user)
         fosm_lifecycle.events.each do |event_def|
-          define_method(:"#{event_def.name}!") do |actor: nil, metadata: {}|
-            fire!(event_def.name, actor: actor, metadata: metadata)
+          define_method(:"#{event_def.name}!") do |actor: nil, metadata: {}, snapshot_data: nil|
+            fire!(event_def.name, actor: actor, metadata: metadata, snapshot_data: snapshot_data)
           end
 
           define_method(:"can_#{event_def.name}?") do
@@ -53,21 +53,31 @@ module Fosm
     #   3. Check event is valid from current state
     #   4. Run guards (pure in-memory functions)
     #   5. RBAC check (O(1) cache lookup after first request hit)
-    #   6. BEGIN TRANSACTION: UPDATE state, run side effects
+    #   6. Acquire row lock (SELECT FOR UPDATE) and re-validate
+    #   7. BEGIN TRANSACTION: UPDATE state, run side effects
     #                         [optionally INSERT log if strategy == :sync]
     #      COMMIT
-    #   7. Emit transition log (:async or :buffered, non-blocking)
-    #   8. Enqueue webhook delivery (always async)
+    #   8. Emit transition log (:async or :buffered, non-blocking)
+    #   9. Enqueue webhook delivery (always async)
+    #
+    # RACE CONDITION PROTECTION:
+    #   - Uses SELECT FOR UPDATE to lock the row, preventing concurrent transitions
+    #   - Re-validates state, guards, and RBAC after acquiring lock
+    #   - Guarantees only one transition succeeds when concurrent requests fire
+    #     the same event on the same record
     #
     # @param event_name [Symbol, String] the event to fire
     # @param actor [Object] who/what is firing the event (User, or :system/:agent symbol)
     # @param metadata [Hash] optional metadata stored in the transition log
+    # @param snapshot_data [Hash] arbitrary observations/data to include in state snapshot
+    #   This allows capturing adhoc observations alongside schema attributes.
+    #   Merged with schema data under the `_observations` key in the snapshot.
     # @raise [Fosm::UnknownEvent]    if event doesn't exist
     # @raise [Fosm::TerminalState]   if current state is terminal
     # @raise [Fosm::InvalidTransition] if current state doesn't allow this event
     # @raise [Fosm::GuardFailed]     if a guard blocks the transition
     # @raise [Fosm::AccessDenied]    if actor lacks a role that permits this event
-    def fire!(event_name, actor: nil, metadata: {})
+    def fire!(event_name, actor: nil, metadata: {}, snapshot_data: nil)
       lifecycle = self.class.fosm_lifecycle
       raise Fosm::Error, "No lifecycle defined on #{self.class.name}" unless lifecycle
 
@@ -88,9 +98,11 @@ module Fosm
       end
 
       # Run guards (pure functions — no side effects, evaluated before any writes)
+      # 🆕 Use evaluate for rich error messages
       event_def.guards.each do |guard_def|
-        unless guard_def.call(self)
-          raise Fosm::GuardFailed.new(guard_def.name, event_name)
+        allowed, reason = guard_def.evaluate(self)
+        unless allowed
+          raise Fosm::GuardFailed.new(guard_def.name, event_name, reason)
         end
       end
 
@@ -103,6 +115,9 @@ module Fosm
       to_state        = event_def.to_state.to_s
       transition_data = { from: from_state, to: to_state, event: event_name.to_s, actor: actor }
 
+      # Auto-capture triggered_by when called from within a side effect
+      triggered_by = Thread.current[:fosm_trigger_context]
+
       log_data = {
         "record_type" => self.class.name,
         "record_id"   => self.id.to_s,
@@ -112,20 +127,152 @@ module Fosm
         "actor_type"  => actor_type_for(actor),
         "actor_id"    => actor_id_for(actor),
         "actor_label" => actor_label_for(actor),
-        "metadata"    => metadata
+        "metadata"    => metadata.merge(
+          triggered_by ? { triggered_by: triggered_by } : {}
+        ).compact
       }
 
+      # ==========================================================================
+      # SNAPSHOT CONFIGURATION
+      # ==========================================================================
+      # If snapshots are configured, determine if we should capture one for this
+      # transition based on the strategy (every, count, time, terminal, manual).
+      # ==========================================================================
+      snapshot_config = lifecycle.snapshot_configuration
+      if snapshot_config && metadata[:snapshot] != false  # allow manual opt-out
+        # Calculate metrics for snapshot decision
+        last_snapshot = Fosm::TransitionLog
+          .where(record_type: self.class.name, record_id: self.id.to_s)
+          .where.not(state_snapshot: nil)
+          .order(created_at: :desc)
+          .first
+
+        transitions_since = last_snapshot ?
+          Fosm::TransitionLog.where(record_type: self.class.name, record_id: self.id.to_s)
+            .where("created_at > ?", last_snapshot.created_at).count :
+          Fosm::TransitionLog.where(record_type: self.class.name, record_id: self.id.to_s).count
+
+        seconds_since = last_snapshot ?
+          (Time.current - last_snapshot.created_at).to_f :
+          Float::INFINITY
+
+        to_state_def = lifecycle.find_state(to_state)
+
+        # Check if we should snapshot (respecting manual: false unless forced)
+        force_snapshot = metadata[:snapshot] == true
+        should_snapshot = snapshot_config.should_snapshot?(
+          transition_count: transitions_since,
+          seconds_since_last: seconds_since,
+          to_state: to_state,
+          to_state_terminal: to_state_def&.terminal? || false,
+          force: force_snapshot
+        )
+
+        if should_snapshot
+          # Build snapshot: schema attributes + arbitrary observations
+          schema_snapshot = snapshot_config.build_snapshot(self)
+
+          # Merge arbitrary observations if provided (stored under _observations key)
+          if snapshot_data.present?
+            schema_snapshot["_observations"] = snapshot_data.as_json
+          end
+
+          log_data["state_snapshot"] = schema_snapshot
+          log_data["snapshot_reason"] = determine_snapshot_reason(
+            snapshot_config.strategy, force_snapshot, to_state_def
+          )
+        end
+      end
+
+      # ==========================================================================
+      # RACE CONDITION FIX: SELECT FOR UPDATE
+      # ==========================================================================
+      # Acquire a row-level lock before proceeding. This prevents concurrent
+      # transactions from reading stale state and attempting concurrent transitions.
+      #
+      # Behavior:
+      # - PostgreSQL/MySQL: SELECT ... FOR UPDATE blocks until lock acquired
+      # - SQLite: No-op (database-level locking makes it already serializable)
+      #
+      # We re-read state after locking to ensure we have the latest value.
+      # If another transaction committed while we waited for the lock, we get
+      # the fresh state and must re-validate our checks.
+      # ==========================================================================
+
+      # Acquire lock - this blocks if another transaction holds the lock
+      locked_record = self.class.lock.find(self.id)
+
+      # Re-validate with locked state - the world may have changed while waiting
+      locked_current = locked_record.state.to_s
+      locked_current_state_def = lifecycle.find_state(locked_current)
+
+      # If state changed while waiting for lock, transition may no longer be valid
+      if locked_current_state_def&.terminal?
+        raise Fosm::TerminalState.new(locked_current, self.class)
+      end
+
+      unless event_def.valid_from?(locked_current)
+        raise Fosm::InvalidTransition.new(event_name, locked_current, self.class)
+      end
+
+      # Re-check guards with locked record (guards may depend on fresh state)
+      event_def.guards.each do |guard_def|
+        allowed, reason = guard_def.evaluate(locked_record)
+        unless allowed
+          raise Fosm::GuardFailed.new(guard_def.name, event_name, reason)
+        end
+      end
+
+      # Re-check RBAC with locked record (for consistency, though RBAC uses cache)
+      if lifecycle.access_defined?
+        unless fosm_rbac_bypass?(actor)
+          unless fosm_actor_has_event_permission_for_record?(event_name, actor, locked_record)
+            raise Fosm::AccessDenied.new(event_name, actor)
+          end
+        end
+      end
+
+      # Update from_state to reflect the locked state's current value
+      from_state = locked_current
+      log_data["from_state"] = from_state
+
       ActiveRecord::Base.transaction do
-        update!(state: to_state)
+        # Use the locked record for the update to ensure we hold the lock
+        locked_record.update!(state: to_state)
+
+        # Sync our instance state with what was written
+        self.state = to_state
 
         # :sync strategy — INSERT inside transaction for strict consistency
         if Fosm.config.transition_log_strategy == :sync
           Fosm::TransitionLog.create!(log_data)
         end
 
-        # Run side effects inside transaction so they roll back on error
-        event_def.side_effects.each do |side_effect_def|
-          side_effect_def.call(self, transition_data)
+        # Run immediate side effects inside transaction so they roll back on error
+        # Set context for auto-capturing triggered_by in nested transitions
+        begin
+          Thread.current[:fosm_trigger_context] = {
+            record_type: self.class.name,
+            record_id: self.id.to_s,
+            event_name: event_name.to_s
+          }
+          # Call side effects on self (not locked_record) so instance state is preserved
+          event_def.side_effects.reject(&:deferred?).each do |side_effect_def|
+            side_effect_def.call(self, transition_data)
+          end
+        ensure
+          Thread.current[:fosm_trigger_context] = nil
+        end
+
+        # 🆕 Queue deferred side effects to run after commit
+        deferred_effects = event_def.side_effects.select(&:deferred?)
+        if deferred_effects.any?
+          # Set instance variables on locked_record (the instance that gets saved)
+          # so after_commit callback can access them
+          locked_record.instance_variable_set(:@_fosm_deferred_side_effects, deferred_effects)
+          locked_record.instance_variable_set(:@_fosm_transition_data, transition_data)
+          # Use after_commit to run after transaction completes
+          locked_record.class.after_commit :_fosm_run_deferred_side_effects, on: :update
         end
       end
 
@@ -160,10 +307,12 @@ module Fosm
 
       event_def = lifecycle.find_event(event_name)
       return false unless event_def
+      # Terminal states block transitions
       return false if lifecycle.find_state(self.state)&.terminal?
       return false unless event_def.valid_from?(self.state)
 
-      event_def.guards.all? { |guard_def| guard_def.call(self) }
+      # Use evaluate to properly check guards (handles rich return values)
+      event_def.guards.all? { |guard_def| guard_def.evaluate(self).first }
     end
 
     # Returns true if the actor has a role permitting this event AND the transition is valid.
@@ -180,15 +329,163 @@ module Fosm
       return [] unless lifecycle
 
       lifecycle.available_events_from(self.state).select { |event_def|
-        event_def.guards.all? { |g| g.call(self) }
+        # 🆕 Use evaluate to properly check guards
+        event_def.guards.all? { |g| g.evaluate(self).first }
       }.map(&:name)
     end
 
+    # 🆕 Detailed introspection: why can this event (not) be fired?
+    # Returns a hash with diagnostic information for debugging and UI messages.
+    def why_cannot_fire?(event_name)
+      lifecycle = self.class.fosm_lifecycle
+      return { can_fire: false, reason: "No lifecycle defined" } unless lifecycle
+
+      event_def = lifecycle.find_event(event_name)
+      return { can_fire: false, reason: "Unknown event '#{event_name}'" } unless event_def
+
+      current = self.state.to_s
+      current_state_def = lifecycle.find_state(current)
+      result = {
+        can_fire: true,
+        event: event_name.to_s,
+        current_state: current
+      }
+
+      # Check terminal state
+      if current_state_def&.terminal?
+        result[:can_fire] = false
+        result[:reason] = "State '#{current}' is terminal and cannot transition further"
+        result[:is_terminal] = true
+        return result
+      end
+
+      # Check valid from state
+      unless event_def.valid_from?(current)
+        result[:can_fire] = false
+        result[:reason] = "Cannot fire '#{event_name}' from '#{current}' (valid from: #{event_def.from_states.join(', ')})"
+        result[:valid_from_states] = event_def.from_states
+        return result
+      end
+
+      # Evaluate guards
+      failed_guards = []
+      passed_guards = []
+
+      event_def.guards.each do |guard_def|
+        allowed, reason = guard_def.evaluate(self)
+        if allowed
+          passed_guards << guard_def.name
+        else
+          failed_guards << { name: guard_def.name, reason: reason }
+        end
+      end
+
+      if failed_guards.any?
+        result[:can_fire] = false
+        result[:failed_guards] = failed_guards
+        result[:passed_guards] = passed_guards
+        first_failure = failed_guards.first
+        result[:reason] = "Guard '#{first_failure[:name]}' failed"
+        result[:reason] += ": #{first_failure[:reason]}" if first_failure[:reason]
+      end
+
+      result
+    end
+
     # Returns the current state as a symbol
     def current_state
       self.state.to_sym
     end
 
+    # ==========================================================================
+    # SNAPSHOT REPLAY AND TIME-TRAVEL METHODS
+    # ==========================================================================
+
+    # Returns the most recent snapshot for this record, or nil if none exists.
+    # @return [Fosm::TransitionLog, nil] the transition log entry with snapshot
+    def last_snapshot
+      Fosm::TransitionLog
+        .where(record_type: self.class.name, record_id: self.id.to_s)
+        .where.not(state_snapshot: nil)
+        .order(created_at: :desc)
+        .first
+    end
+
+    # Returns the snapshot data from the most recent snapshot, or nil.
+    # @return [Hash, nil] the snapshot data
+    def last_snapshot_data
+      last_snapshot&.state_snapshot
+    end
+
+    # Returns the state of the record at a specific transition log ID.
+    # This is a "time-travel" query that reconstructs state from snapshot + replay.
+    #
+    # @param transition_log_id [Integer] the ID of the transition log entry
+    # @return [Hash] the reconstructed state at that point in time
+    def state_at_transition(transition_log_id)
+      log = Fosm::TransitionLog.find_by(id: transition_log_id)
+      return nil unless log
+      return nil unless log.record_type == self.class.name && log.record_id == self.id.to_s
+
+      # If this log entry has a snapshot, use it directly
+      return log.state_snapshot if log.state_snapshot.present?
+
+      # Otherwise, find the most recent snapshot before this log entry
+      prior_snapshot = Fosm::TransitionLog
+        .where(record_type: self.class.name, record_id: self.id.to_s)
+        .where.not(state_snapshot: nil)
+        .where("created_at <= ?", log.created_at)
+        .order(created_at: :desc)
+        .first
+
+      # Return the prior snapshot data, or nil if no snapshot exists
+      prior_snapshot&.state_snapshot
+    end
+
+    # Replays events from a specific snapshot forward to the current state.
+    # Yields each transition to a block for custom processing.
+    #
+    # @param from_snapshot [Fosm::TransitionLog, Integer] snapshot log entry or ID
+    # @yield [transition_log] optional block to process each transition
+    # @return [Array<Fosm::TransitionLog>] the transitions replayed
+    def replay_from(from_snapshot)
+      snapshot_id = from_snapshot.is_a?(Fosm::TransitionLog) ? from_snapshot.id : from_snapshot
+
+      transitions = Fosm::TransitionLog
+        .where(record_type: self.class.name, record_id: self.id.to_s)
+        .where("id > ?", snapshot_id)
+        .order(:created_at)
+
+      if block_given?
+        transitions.each { |log| yield log }
+      end
+
+      transitions.to_a
+    end
+
+    # Returns all snapshots for this record in chronological order.
+    # Useful for audit trails and debugging.
+    # @return [ActiveRecord::Relation] snapshot transition logs
+    def snapshots
+      Fosm::TransitionLog
+        .where(record_type: self.class.name, record_id: self.id.to_s)
+        .where.not(state_snapshot: nil)
+        .order(:created_at)
+    end
+
+    # Returns the number of transitions since the last snapshot.
+    # Useful for monitoring snapshot coverage.
+    # @return [Integer] transitions since last snapshot
+    def transitions_since_snapshot
+      last_snap = last_snapshot
+      return Fosm::TransitionLog.where(record_type: self.class.name, record_id: self.id.to_s).count unless last_snap
+
+      Fosm::TransitionLog
+        .where(record_type: self.class.name, record_id: self.id.to_s)
+        .where("created_at > ?", last_snap.created_at)
+        .count
+    end
+
     private
 
     def fosm_set_initial_state
@@ -259,6 +556,15 @@ module Fosm
       (actor_roles & permitted_roles).any?
     end
 
+    # Variant for checking permissions with a locked record (after SELECT FOR UPDATE)
+    def fosm_actor_has_event_permission_for_record?(event_name, actor, record)
+      return true if fosm_rbac_bypass?(actor)
+
+      permitted_roles = record.class.fosm_lifecycle.access_definition.roles_for_event(event_name)
+      actor_roles     = fosm_roles_for_actor(actor)
+      (actor_roles & permitted_roles).any?
+    end
+
     # Returns the actor's roles for this specific record (type-level + record-level combined)
     def fosm_roles_for_actor(actor)
       return [] unless actor.respond_to?(:id) && actor.respond_to?(:class)
@@ -292,5 +598,49 @@ module Fosm
       return nil unless actor
       actor.respond_to?(:email) ? actor.email : actor.to_s
     end
+
+    # Run deferred side effects after transaction commits
+    # This prevents SQLite locking when cross-machine triggers occur
+    def _fosm_run_deferred_side_effects
+      return unless defined?(@_fosm_deferred_side_effects) && @_fosm_deferred_side_effects
+
+      transition_data = @_fosm_transition_data
+
+      begin
+        # Set context for auto-capturing triggered_by in nested transitions
+        Thread.current[:fosm_trigger_context] = {
+          record_type: self.class.name,
+          record_id: self.id.to_s,
+          event_name: transition_data[:event]
+        }
+
+        @_fosm_deferred_side_effects.each do |side_effect_def|
+          side_effect_def.call(self, transition_data)
+        end
+      rescue => e
+        # Log error but don't fail - transaction is already committed
+        logger = defined?(Rails) && Rails.respond_to?(:logger) ? Rails.logger : nil
+        logger ||= Logger.new(STDOUT)
+        logger.error("[Fosm] Deferred side effect failed: #{e.message}")
+      ensure
+        Thread.current[:fosm_trigger_context] = nil
+        # Clean up instance variables
+        @_fosm_deferred_side_effects = nil
+        @_fosm_transition_data = nil
+      end
+
+      # Remove the after_commit callback to avoid running on subsequent updates
+      self.class.skip_callback(:commit, :after, :_fosm_run_deferred_side_effects, on: :update, raise: false)
+    end
+
+    # Determine the reason string for a snapshot based on strategy and context
+    def determine_snapshot_reason(strategy, forced, to_state_def)
+      return "manual" if forced
+      return "every" if strategy == :every
+      return "terminal" if strategy == :terminal && to_state_def&.terminal?
+      return "count_interval" if strategy == :count
+      return "time_interval" if strategy == :time
+      "auto"
+    end
   end
 end

data/lib/fosm/registry.rb

@@ -6,6 +6,11 @@ module Fosm
 
     class << self
       def register(model_class, slug:)
+        unless slug.match?(/\A[a-z0-9_]+\z/)
+          raise ArgumentError, "FOSM slug must contain only lowercase letters, digits, and underscores " \
+                               "(got: #{slug.inspect} for #{model_class.name}). " \
+                               "Hyphens are not allowed because slugs are used to construct Ruby route helper names."
+        end
         @registered[slug] = model_class
       end
 
@@ -24,6 +29,10 @@ module Fosm
       def slugs
         @registered.keys
       end
+
+      def each(&block)
+        @registered.each(&block)
+      end
     end
   end
 end

data/lib/fosm/version.rb

@@ -1,3 +1,3 @@
 module Fosm
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end

data/lib/generators/fosm/app/app_generator.rb

@@ -41,6 +41,38 @@ module Fosm
         migration_template "migration.rb.tt", "db/migrate/create_fosm_#{table_name}.rb"
       end
 
+      def inject_agent_instructions
+        claude_md = ::Rails.root.join("CLAUDE.md")
+        sentinel  = "<!-- fosm:agent-instructions -->"
+
+        if File.exist?(claude_md) && File.read(claude_md).include?(sentinel)
+          say_status :skip, "CLAUDE.md already has FOSM agent instructions", :yellow
+          return
+        end
+
+        gem_root = Fosm::Engine.root.to_s
+        agents_md_path = File.join(gem_root, "AGENTS.md")
+
+        section = <<~MARKDOWN
+
+          #{sentinel}
+          ## FOSM (fosm-rails)
+
+          This project uses `fosm-rails` — a Finite Object State Machine engine.
+          When the user asks to build, extend, or modify features involving state machines,
+          lifecycles, FOSM, or any code under `app/models/fosm/`, `app/controllers/fosm/`,
+          or `app/agents/fosm/`, you **must** read and follow the instructions in:
+
+          `#{agents_md_path}`
+        MARKDOWN
+
+        if File.exist?(claude_md)
+          append_to_file claude_md, section
+        else
+          create_file claude_md, section.lstrip
+        end
+      end
+
       def update_routes
         routes_file = ::Rails.root.join("config/routes/fosm.rb")
 

data/lib/tasks/fosm_graph.rake

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "rake"
+
+namespace :fosm do
+  namespace :graph do
+    desc "Generate state machine graph for a FOSM model (e.g., rake fosm:graph:generate MODEL=Invoice)"
+    task generate: :environment do
+      model_name = ENV["MODEL"]
+      raise "Usage: rake fosm:graph:generate MODEL=Invoice" unless model_name
+
+      model_class = "Fosm::#{model_name}".constantize rescue model_name.constantize
+      raise "#{model_name} does not include Fosm::Lifecycle" unless model_class.respond_to?(:fosm_lifecycle)
+
+      lifecycle = model_class.fosm_lifecycle
+      output_dir = ENV["OUTPUT"] || Rails.root.join("app", "assets", "graphs")
+      FileUtils.mkdir_p(output_dir)
+
+      # Generate machine-level graph
+      machine_data = {
+        machine: model_class.name,
+        states: lifecycle.states.map { |s|
+          {
+            name: s.name,
+            initial: s.initial?,
+            terminal: s.terminal?
+          }
+        },
+        events: lifecycle.events.map { |e|
+          {
+            name: e.name,
+            from: e.from_states,
+            to: e.to_state,
+            guards: e.guards.map(&:name),
+            side_effects: e.side_effects.map(&:name)
+          }
+        }
+      }
+
+      # Detect cross-machine connections by analyzing side effect names
+      cross_connections = []
+      lifecycle.events.each do |event|
+        event.side_effects.each do |side_effect|
+          name = side_effect.name.to_s
+          # Convention: trigger_other_machine or activate_contract patterns
+          if name.include?("_")
+            parts = name.split("_")
+            potential_targets = parts.select { |p|
+              # Look for capitalized words that match model names
+              p.capitalize == p && Object.const_defined?("Fosm::#{p.capitalize}") rescue false
+            }
+            potential_targets.each do |target|
+              cross_connections << {
+                source: { machine: model_class.name, event: event.name },
+                via: side_effect.name,
+                target_machine: "Fosm::#{target.capitalize}"
+              }
+            end
+          end
+        end
+      end
+
+      machine_data[:cross_machine_connections] = cross_connections
+
+      # Write machine graph
+      machine_file = File.join(output_dir, "#{model_name.underscore}_graph.json")
+      File.write(machine_file, JSON.pretty_generate(machine_data))
+      puts "Generated: #{machine_file}"
+
+      # Generate system-wide graph if requested
+      if ENV["SYSTEM"]
+        system_data = Fosm::Graph.system_graph
+        system_file = File.join(output_dir, "fosm_system_graph.json")
+        File.write(system_file, JSON.pretty_generate(system_data))
+        puts "Generated: #{system_file}"
+      end
+    end
+
+    desc "Generate graphs for all FOSM models"
+    task all: :environment do
+      Fosm::Registry.each do |slug, model_class|
+        ENV["MODEL"] = model_class.name.demodulize
+        Rake::Task["fosm:graph:generate"].invoke
+        Rake::Task["fosm:graph:generate"].reenable
+      end
+    end
+  end
+end
+
+module Fosm
+  class Graph
+    # Generate system-wide dependency graph
+    def self.system_graph
+      machines = {}
+      connections = []
+
+      Fosm::Registry.each do |slug, model_class|
+        next unless model_class.respond_to?(:fosm_lifecycle)
+        lifecycle = model_class.fosm_lifecycle
+
+        machines[model_class.name] = {
+          states: lifecycle.states.count,
+          events: lifecycle.events.count,
+          terminal_states: lifecycle.states.select(&:terminal?).map(&:name)
+        }
+
+        lifecycle.events.each do |event|
+          event.side_effects.each do |side_effect|
+            connections << {
+              from: model_class.name,
+              to: infer_target_from_side_effect(side_effect),
+              via: side_effect.name,
+              event: event.name
+            } if infer_target_from_side_effect(side_effect)
+          end
+        end
+      end
+
+      {
+        machines: machines,
+        connections: connections.compact,
+        generated_at: Time.current.iso8601
+      }
+    end
+
+    def self.infer_target_from_side_effect(side_effect)
+      name = side_effect.name.to_s
+      # Common patterns: activate_contract, notify_user, create_payment
+      targets = %w[Contract Invoice User Payment Order Shipment].select do |model|
+        name.downcase.include?(model.downcase)
+      end
+      targets.first ? "Fosm::#{targets.first}" : nil
+    end
+  end
+end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fosm-rails
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Abhishek Parolkar
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-03-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -91,6 +92,7 @@ files:
 - db/migrate/20240101000002_create_fosm_webhook_subscriptions.rb
 - db/migrate/20240101000003_create_fosm_role_assignments.rb
 - db/migrate/20240101000004_create_fosm_access_events.rb
+- db/migrate/20240101000005_add_state_snapshot_to_fosm_transition_logs.rb
 - lib/fosm-rails.rb
 - lib/fosm/agent.rb
 - lib/fosm/configuration.rb
@@ -104,6 +106,7 @@ files:
 - lib/fosm/lifecycle/guard_definition.rb
 - lib/fosm/lifecycle/role_definition.rb
 - lib/fosm/lifecycle/side_effect_definition.rb
+- lib/fosm/lifecycle/snapshot_configuration.rb
 - lib/fosm/lifecycle/state_definition.rb
 - lib/fosm/rails.rb
 - lib/fosm/rails/engine.rb
@@ -121,6 +124,7 @@ files:
 - lib/generators/fosm/app/templates/views/new.html.erb.tt
 - lib/generators/fosm/app/templates/views/show.html.erb.tt
 - lib/tasks/fosm/rails_tasks.rake
+- lib/tasks/fosm_graph.rake
 homepage: https://github.com/inloopstudio/fosm-rails
 licenses:
 - FSL-1.1-Apache-2.0
@@ -128,6 +132,7 @@ metadata:
   homepage_uri: https://github.com/inloopstudio/fosm-rails
   source_code_uri: https://github.com/inloopstudio/fosm-rails
   changelog_uri: https://github.com/inloopstudio/fosm-rails/blob/main/CHANGELOG.md
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -142,7 +147,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: Finite Object State Machine for Rails — declarative lifecycles for business
   objects