fosm-rails 0.1.0

data/config/routes.rb

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

data/db/migrate/20240101000001_create_fosm_transition_logs.rb

@@ -0,0 +1,23 @@
+class CreateFosmTransitionLogs < ActiveRecord::Migration[8.1]
+  def change
+    create_table :fosm_transition_logs do |t|
+      t.string  :record_type,  null: false
+      t.string  :record_id,    null: false
+      t.string  :event_name,   null: false
+      t.string  :from_state,   null: false
+      t.string  :to_state,     null: false
+      t.string  :actor_type
+      t.string  :actor_id
+      t.string  :actor_label
+      t.column  :metadata, :json, default: {}  # use json (works for SQLite + PostgreSQL; jsonb on PG only)
+
+      # Intentionally no updated_at — this is an immutable log
+      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, :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"
+  end
+end

data/db/migrate/20240101000002_create_fosm_webhook_subscriptions.rb

@@ -0,0 +1,16 @@
+class CreateFosmWebhookSubscriptions < ActiveRecord::Migration[8.1]
+  def change
+    create_table :fosm_webhook_subscriptions do |t|
+      t.string  :model_class_name, null: false
+      t.string  :event_name,       null: false
+      t.string  :url,              null: false
+      t.boolean :active,           default: true, null: false
+      t.string  :secret_token
+
+      t.timestamps
+    end
+
+    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/lib/fosm/agent.rb

@@ -0,0 +1,232 @@
+module Fosm
+  # Base class for FOSM AI agents powered by Gemlings.
+  #
+  # Each generated FOSM app gets an agent class that inherits from this.
+  # ::Gemlings::Tool instances are auto-generated from the lifecycle definition,
+  # giving the AI agent a bounded, machine-enforced set of actions.
+  #
+  # The AI agent can ONLY fire lifecycle events. It cannot directly update state.
+  # This is the "bounded autonomy" guarantee — the state machine is the guardrail.
+  # If a transition isn't valid, the tool returns { success: false } — the agent
+  # cannot bypass the machine.
+  #
+  # Gemlings is a required dependency of fosm-rails (declared in gemspec).
+  # See: https://github.com/khasinski/gemlings
+  #
+  # Usage:
+  #
+  #   class Fosm::InvoiceAgent < Fosm::Agent
+  #     model_class Fosm::Invoice
+  #     default_model "anthropic/claude-sonnet-4-20250514"
+  #
+  #     # Optional: add custom tools using Gemlings inline API
+  #     # fosm_tool :find_overdue,
+  #     #           description: "Find sent invoices past their due date",
+  #     #           inputs: {} do
+  #     #   Fosm::Invoice.where(state: "sent").where("due_date < ?", Date.today)
+  #     #                .map { |inv| { id: inv.id, due_date: inv.due_date } }
+  #     # end
+  #   end
+  #
+  #   # Build and run a Gemlings agent
+  #   agent = Fosm::InvoiceAgent.build_agent
+  #   agent.run("Mark all sent invoices older than 30 days as overdue")
+  #
+  class Agent
+    class << self
+      # Declares the model class this agent operates on.
+      # Resets the cached tool list so tools are regenerated on next call to .tools
+      def model_class(klass = nil)
+        if klass
+          @model_class = klass
+          @tools = nil
+        end
+        @model_class
+      end
+
+      # Sets/gets the default Gemlings model string.
+      # Format: "provider/model_name" — see Gemlings docs for supported providers.
+      def default_model(model = nil)
+        @default_model = model if model
+        @default_model || "anthropic/claude-sonnet-4-20250514"
+      end
+
+      # Declare a custom Gemlings tool using the inline ::Gemlings.tool API.
+      #
+      # @param name [Symbol] snake_case tool name
+      # @param description [String] what this tool does (shown to the LLM)
+      # @param inputs [Hash] { param_name: "description" } for each parameter
+      # @param block [Proc] the tool implementation
+      #
+      # Example:
+      #   fosm_tool :find_overdue_invoices,
+      #             description: "Find all invoices that are past their due date",
+      #             inputs: {} do
+      #     Fosm::Invoice.where(state: "sent")
+      #                  .where("due_date < ?", Date.today)
+      #                  .map { |inv| { id: inv.id, due_date: inv.due_date.to_s } }
+      #   end
+      def fosm_tool(name, description:, inputs: {}, &block)
+        @custom_tool_definitions ||= []
+        @custom_tool_definitions << { name: name, description: description, inputs: inputs, block: block }
+        @tools = nil # Reset cached tools
+      end
+
+      # Returns all Gemlings tool instances for this agent.
+      # Lazily built and cached — standard tools from lifecycle + custom tools.
+      def tools
+        @tools ||= build_all_tools
+      end
+
+      # Builds and returns a configured ::Gemlings::CodeAgent (default) or
+      # ::Gemlings::ToolCallingAgent ready to run tasks within FOSM constraints.
+      #
+      # @param model [String] override the default model, e.g. "openai/gpt-4o"
+      # @param agent_type [Symbol] :code (default) or :tool_calling
+      # @param instructions [String] extra instructions appended to system prompt
+      # @param kwargs [Hash] additional ::Gemlings::CodeAgent options
+      #   (max_steps:, planning_interval:, callbacks:, output_type:, etc.)
+      def build_agent(model: nil, agent_type: :tool_calling, instructions: nil, **kwargs)
+        agent_class = agent_type == :tool_calling ? ::Gemlings::ToolCallingAgent : ::Gemlings::CodeAgent
+
+        agent_class.new(
+          model: model || default_model,
+          tools: tools,
+          instructions: build_system_instructions(instructions),
+          **kwargs
+        )
+      end
+
+      private
+
+      def build_all_tools
+        raise ArgumentError, "#{name}.model_class is not set" unless @model_class
+
+        lifecycle = @model_class.fosm_lifecycle
+        raise ArgumentError, "#{@model_class.name} has no lifecycle defined" unless lifecycle
+
+        standard = build_standard_tools(@model_class, lifecycle)
+        custom = build_custom_tools
+
+        standard + custom
+      end
+
+      # Generates Gemlings tools from the lifecycle definition using ::Gemlings.tool inline API.
+      # Creates: list, get, available_events, transition_history, + one per event.
+      def build_standard_tools(klass, lifecycle)
+        mn = klass.name.demodulize.underscore # e.g. "invoice"
+        tools = []
+
+        # list_invoices — list all records, optionally filtered by state
+        tools << ::Gemlings.tool(
+          :"list_#{mn.pluralize}",
+          "List #{mn.pluralize} with their current state. Pass state: 'draft' to filter.",
+          state: "Optional state filter (e.g. 'draft', 'sent')"
+        ) do |state: nil|
+          records = state.present? ? klass.where(state: state) : klass.all
+          records.map { |r|
+            { id: r.id, state: r.state }
+              .merge(r.attributes.except("id", "state", "created_by_id", "created_at", "updated_at"))
+          }
+        end
+
+        # get_invoice — fetch a single record by ID
+        tools << ::Gemlings.tool(
+          :"get_#{mn}",
+          "Get a #{mn} by ID with its current state and available lifecycle events.",
+          id: "The #{mn} ID (integer)"
+        ) do |id:|
+          record = klass.find_by(id: id)
+          next({ error: "#{mn.humanize} ##{id} not found" }) unless record
+
+          { id: record.id, state: record.state, available_events: record.available_events }
+            .merge(record.attributes.except("id", "state", "created_by_id", "created_at", "updated_at"))
+        end
+
+        # available_events_for_invoice
+        tools << ::Gemlings.tool(
+          :"available_events_for_#{mn}",
+          "Returns which lifecycle events can fire on a #{mn} from its current state. Always check this before firing.",
+          id: "The #{mn} ID (integer)"
+        ) do |id:|
+          record = klass.find_by(id: id)
+          next({ error: "#{mn.humanize} ##{id} not found" }) unless record
+          { id: record.id, current_state: record.state, available_events: record.available_events }
+        end
+
+        # transition_history_for_invoice
+        tools << ::Gemlings.tool(
+          :"transition_history_for_#{mn}",
+          "Returns the full audit trail of every state transition for a #{mn}.",
+          id: "The #{mn} ID (integer)"
+        ) do |id:|
+          Fosm::TransitionLog
+            .where(record_type: klass.name, record_id: id.to_s)
+            .order(created_at: :asc)
+            .map { |l|
+              { event: l.event_name, from: l.from_state, to: l.to_state,
+                actor: l.actor_label || l.actor_type, at: l.created_at.iso8601 }
+            }
+        end
+
+        # One tool per lifecycle event — the bounded autonomy guarantee.
+        # The agent can only fire declared events. Invalid transitions return { success: false }.
+        lifecycle.events.each do |event_def|
+          from_desc = event_def.from_states.join(" or ")
+          guard_note = event_def.guards.any? ? " Requires guards: #{event_def.guards.map(&:name).join(', ')}." : ""
+
+          tools << ::Gemlings.tool(
+            :"#{event_def.name}_#{mn}",
+            "Fire the '#{event_def.name}' event on a #{mn}. " \
+            "Valid from state [#{from_desc}] → #{event_def.to_state}.#{guard_note} " \
+            "Returns { success: false } if the machine rejects the transition.",
+            id: "The #{mn} ID (integer)"
+          ) do |id:|
+            record = klass.find_by(id: id)
+            next({ success: false, error: "#{mn.humanize} ##{id} not found" }) unless record
+
+            record.fire!(event_def.name, actor: :agent)
+            { success: true, id: record.id, previous_state: event_def.from_states.first,
+              new_state: record.reload.state }
+          rescue Fosm::Error => e
+            { success: false, error: e.message, current_state: record&.state }
+          end
+        end
+
+        tools
+      end
+
+      def build_custom_tools
+        (@custom_tool_definitions || []).map do |defn|
+          ::Gemlings.tool(defn[:name], defn[:description], **defn[:inputs], &defn[:block])
+        end
+      end
+
+      # Builds a system prompt that communicates FOSM constraints to the LLM.
+      def build_system_instructions(extra = nil)
+        klass = @model_class
+        lifecycle = klass.fosm_lifecycle
+        state_names = lifecycle.state_names.join(", ")
+        terminal_states = lifecycle.states.select(&:terminal?).map(&:name).join(", ")
+        event_names = lifecycle.event_names.join(", ")
+        mn = klass.name.demodulize.underscore
+
+        base = <<~INSTRUCTIONS
+          You are a FOSM AI agent managing #{klass.name.demodulize.pluralize.humanize}.
+
+          ARCHITECTURE CONSTRAINTS — you MUST follow these at all times:
+          1. State changes happen ONLY via lifecycle event tools. Never use direct updates.
+          2. Valid states: #{state_names}
+          3. Terminal states (no further transitions allowed): #{terminal_states.presence || "none"}
+          4. Available lifecycle events: #{event_names}
+          5. ALWAYS call available_events_for_#{mn}(id:) before firing any event.
+          6. If an event tool returns { success: false }, DO NOT retry — report the error.
+          7. Records in a terminal state cannot transition further — accept this.
+          8. Think step by step. State your reasoning before any action that changes state.
+        INSTRUCTIONS
+
+        extra.present? ? "#{base.strip}\n\n#{extra}" : base.strip
+      end
+    end
+  end
+end

data/lib/fosm/configuration.rb

@@ -0,0 +1,50 @@
+module Fosm
+  class Configuration
+    # The base controller class the engine's controllers will inherit from.
+    # Set this to match your app's ApplicationController.
+    attr_accessor :base_controller
+
+    # A callable that authorizes access to the /fosm/admin area.
+    # Called via instance_exec in the controller before_action.
+    # Example: -> { redirect_to root_path unless current_user&.superadmin? }
+    attr_accessor :admin_authorize
+
+    # A callable that authorizes access to individual FOSM apps.
+    # Receives the access_level declared in the app definition.
+    # Example: ->(level) { authenticate_user! }
+    attr_accessor :app_authorize
+
+    # A callable that returns the current user from the controller context.
+    # Used for transition log actor tracking.
+    attr_accessor :current_user_method
+
+    # Layout used for the admin section
+    attr_accessor :admin_layout
+
+    # Default layout used for generated FOSM app views
+    attr_accessor :app_layout
+
+    def initialize
+      @base_controller = "ApplicationController"
+      @admin_authorize = -> { true } # Override in initializer!
+      @app_authorize = ->(_level) { true } # Override in initializer!
+      @current_user_method = -> { defined?(current_user) ? current_user : nil }
+      @admin_layout = "fosm/application"
+      @app_layout = "application"
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+
+    def config
+      configuration
+    end
+  end
+end

data/lib/fosm/engine.rb

@@ -0,0 +1,133 @@
+require "rails/engine"
+
+module Fosm
+  class Engine < ::Rails::Engine
+    isolate_namespace Fosm
+
+    config.generators do |g|
+      g.test_framework :minitest
+    end
+
+    # Expose configuration
+    initializer "fosm.configuration" do
+      # Host app can configure via config/initializers/fosm.rb
+      # Run: rails fosm:install:migrations && rails db:migrate
+
+      # ── Gemlings compatibility patches ────────────────────────────────────────
+      # These patches fix Anthropic API incompatibilities in Gemlings' ToolCallingAgent.
+      # Each patch is guarded: it reads the upstream source file and checks whether the
+      # fix is already present. If Gemlings merges the fix, the patch becomes a no-op.
+      #
+      # Upstream PR: https://github.com/khasinski/gemlings (submitted from fork)
+      #
+      # TODO: remove these patches once the upstream PR is merged and a fixed version
+      # of gemlings is released. Steps to clean up:
+      #   1. Check if gemlings >= X.Y (the version that includes the fix) is the minimum
+      #      required version in fosm-rails.gemspec.
+      #   2. Delete the two `unless` blocks below (lines ~37-104).
+      #   3. Remove the `_gemlings_dir`, `_memory_text`, `_adapter_text` variables.
+      #   4. Update AGENTS.md "Compatibility note" section to remove the patch description.
+      #   5. Bump fosm-rails version with a note in CHANGELOG.
+      # Track: https://github.com/khasinski/gemlings/pull/[PR_NUMBER]
+
+      # Read upstream source files directly from the gem installation path.
+      # We avoid using source_location on the methods themselves because prepend
+      # would redirect source_location to this engine file after patching.
+      _gemlings_dir = Gem.loaded_specs["gemlings"]&.gem_dir || ""
+      _memory_text  = File.read(File.join(_gemlings_dir, "lib/gemlings/memory.rb"))              rescue ""
+      _adapter_text = File.read(File.join(_gemlings_dir, "lib/gemlings/models/ruby_llm_adapter.rb")) rescue ""
+
+      # Patch 1 — Memory#to_messages (needed if upstream hasn't added tool_result + rstrip)
+      #
+      # Fixes:
+      #   a) Trailing whitespace — Anthropic rejects assistant content ending with whitespace.
+      #   b) Tool result format  — Observation: plain text must become a tool_result block.
+      #
+      # Detection: upstream fix will contain both "tool_result" and "rstrip" in to_messages.
+      unless _memory_text.include?("tool_result") && _memory_text.include?("rstrip")
+        ::Gemlings::Memory.prepend(Module.new do
+          def to_messages
+            messages = super
+
+            # Strip trailing whitespace — some LLM APIs (e.g. Anthropic) reject messages
+            # whose string content ends with whitespace.
+            messages = messages.map do |msg|
+              msg[:content].is_a?(String) ? msg.merge(content: msg[:content].rstrip) : msg
+            end
+
+            # Rewrite "Observation: ..." user messages that follow a tool_calls step into
+            # structured tool_result blocks. Anthropic requires that every tool_use in an
+            # assistant message is immediately followed by a tool_result block.
+            result = []
+            messages.each do |msg|
+              prev = result.last
+              if prev && prev[:role] == "assistant" && prev[:tool_calls].present? &&
+                 msg[:role] == "user" && msg[:content].is_a?(String) && msg[:content].start_with?("Observation:")
+                observation = msg[:content].sub(/\AObservation:\s*/, "").strip
+                tool_results = prev[:tool_calls].map { |tc| { type: "tool_result", tool_use_id: tc.id, content: observation } }
+                result << msg.merge(content: tool_results)
+              else
+                result << msg
+              end
+            end
+
+            result
+          end
+        end)
+      end
+
+      # Patch 2 — RubyLLMAdapter#load_messages (needed if upstream hasn't added tool_result handling)
+      #
+      # Fixes: tool_result content arrays must be passed to ruby_llm as role: :tool messages
+      # with a tool_call_id, not as plain user text. Without this, ruby_llm sends a malformed
+      # payload that Anthropic rejects with "tool_use without tool_result" errors.
+      #
+      # Detection: upstream fix will contain "tool_result" in load_messages.
+      unless _adapter_text.include?("tool_result")
+        ::Gemlings::Models::RubyLLMAdapter.prepend(Module.new do
+          private
+
+          def load_messages(chat, messages)
+            messages.each do |msg|
+              role    = msg[:role]
+              content = msg[:content]
+
+              case role
+              when "system"
+                chat.with_instructions(content)
+              when "assistant"
+                attrs = { role: :assistant, content: content }
+                attrs[:tool_calls] = send(:convert_tool_calls_to_ruby_llm, msg[:tool_calls]) if msg[:tool_calls]
+                chat.add_message(attrs)
+              else
+                if content.is_a?(Array) && content.all? { |c| c.is_a?(Hash) && (c[:type] == "tool_result" || c["type"] == "tool_result") }
+                  content.each do |tr|
+                    chat.add_message(role: :tool, content: (tr[:content] || tr["content"]).to_s, tool_call_id: tr[:tool_use_id] || tr["tool_use_id"])
+                  end
+                else
+                  chat.add_message(role: role.to_sym, content: content || "")
+                end
+              end
+            end
+          end
+        end)
+      end
+    end
+
+    # Auto-register all Fosm models with the registry after app loads.
+    # Use ::Rails to avoid ambiguity with Fosm::Rails module.
+    config.after_initialize do
+      ::Rails.application.eager_load! if ::Rails.env.development? && !::Rails.application.config.eager_load
+
+      ObjectSpace.each_object(Class).select { |klass|
+        klass < ActiveRecord::Base &&
+          klass.name&.start_with?("Fosm::") &&
+          klass.respond_to?(:fosm_lifecycle) &&
+          klass.fosm_lifecycle.present?
+      }.each do |klass|
+        slug = klass.name.demodulize.underscore.dasherize
+        Fosm::Registry.register(klass, slug: slug)
+      end
+    end
+  end
+end

data/lib/fosm/errors.rb

@@ -0,0 +1,31 @@
+module Fosm
+  class Error < StandardError; end
+
+  # Raised when fire! is called with an unknown event name
+  class UnknownEvent < Error
+    def initialize(event_name, model_class)
+      super("Unknown event '#{event_name}' on #{model_class.name}. Available events: #{model_class.fosm_lifecycle.events.map(&:name).join(', ')}")
+    end
+  end
+
+  # Raised when fire! is called but current state doesn't allow the event
+  class InvalidTransition < Error
+    def initialize(event_name, current_state, record_class)
+      super("Cannot fire '#{event_name}' from state '#{current_state}' on #{record_class.name}")
+    end
+  end
+
+  # Raised when a guard blocks a transition
+  class GuardFailed < Error
+    def initialize(guard_name, event_name)
+      super("Guard '#{guard_name}' prevented transition for event '#{event_name}'")
+    end
+  end
+
+  # Raised when trying to transition a record in a terminal state
+  class TerminalState < Error
+    def initialize(state_name, record_class)
+      super("#{record_class.name} is in terminal state '#{state_name}' and cannot transition further")
+    end
+  end
+end

data/lib/fosm/lifecycle/definition.rb

@@ -0,0 +1,103 @@
+require_relative "state_definition"
+require_relative "event_definition"
+require_relative "guard_definition"
+require_relative "side_effect_definition"
+
+module Fosm
+  module Lifecycle
+    # Holds the entire lifecycle definition for a FOSM model.
+    # Instantiated once per model class at class load time.
+    class Definition
+      attr_reader :states, :events
+
+      def initialize
+        @states = []
+        @events = []
+        @pending_guards = {}       # event_name => [GuardDefinition, ...]
+        @pending_side_effects = {} # event_name => [SideEffectDefinition, ...]
+      end
+
+      # DSL: declare a state
+      def state(name, initial: false, terminal: false)
+        if initial && @states.any?(&:initial?)
+          raise ArgumentError, "Only one initial state is allowed"
+        end
+        @states << StateDefinition.new(name: name, initial: initial, terminal: terminal)
+      end
+
+      # DSL: declare an event
+      def event(name, from:, to:)
+        event_def = EventDefinition.new(name: name, from: from, to: to)
+
+        # Apply any guards/side_effects declared before this event (unusual but handle it)
+        (@pending_guards[name.to_sym] || []).each { |g| event_def.add_guard(g) }
+        (@pending_side_effects[name.to_sym] || []).each { |se| event_def.add_side_effect(se) }
+
+        @events << event_def
+        event_def
+      end
+
+      # DSL: declare a guard on an event
+      def guard(name, on:, &block)
+        guard_def = GuardDefinition.new(name: name, &block)
+        event_def = find_event(on)
+        if event_def
+          event_def.add_guard(guard_def)
+        else
+          # Event may be declared after guard — store for later
+          @pending_guards[on.to_sym] ||= []
+          @pending_guards[on.to_sym] << guard_def
+        end
+      end
+
+      # DSL: declare a side effect on an event
+      def side_effect(name, on:, &block)
+        side_effect_def = SideEffectDefinition.new(name: name, &block)
+        event_def = find_event(on)
+        if event_def
+          event_def.add_side_effect(side_effect_def)
+        else
+          @pending_side_effects[on.to_sym] ||= []
+          @pending_side_effects[on.to_sym] << side_effect_def
+        end
+      end
+
+      def initial_state
+        @states.find(&:initial?)
+      end
+
+      def find_event(name)
+        @events.find { |e| e.name == name.to_sym }
+      end
+
+      def find_state(name)
+        @states.find { |s| s.name == name.to_sym }
+      end
+
+      def state_names
+        @states.map(&:name).map(&:to_s)
+      end
+
+      def event_names
+        @events.map(&:name)
+      end
+
+      # Returns events valid from the given state
+      def available_events_from(state)
+        @events.select { |e| e.valid_from?(state) }
+      end
+
+      # Returns a hash suitable for rendering a state diagram
+      def to_diagram_data
+        {
+          states: @states.map { |s| { name: s.name, initial: s.initial?, terminal: s.terminal? } },
+          transitions: @events.map { |e|
+            e.from_states.map { |from|
+              { event: e.name, from: from, to: e.to_state, guards: e.guards.map(&:name) }
+            }
+          }.flatten
+        }
+      end
+    end
+  end
+end

data/lib/fosm/lifecycle/event_definition.rb

@@ -0,0 +1,27 @@
+module Fosm
+  module Lifecycle
+    class EventDefinition
+      attr_reader :name, :from_states, :to_state, :guards, :side_effects
+
+      def initialize(name:, from:, to:)
+        @name = name.to_sym
+        @from_states = Array(from).map(&:to_sym)
+        @to_state = to.to_sym
+        @guards = []
+        @side_effects = []
+      end
+
+      def add_guard(guard_def)
+        @guards << guard_def
+      end
+
+      def add_side_effect(side_effect_def)
+        @side_effects << side_effect_def
+      end
+
+      def valid_from?(state)
+        @from_states.include?(state.to_sym)
+      end
+    end
+  end
+end

data/lib/fosm/lifecycle/guard_definition.rb

@@ -0,0 +1,16 @@
+module Fosm
+  module Lifecycle
+    class GuardDefinition
+      attr_reader :name
+
+      def initialize(name:, &block)
+        @name = name
+        @block = block
+      end
+
+      def call(record)
+        @block.call(record)
+      end
+    end
+  end
+end

data/lib/fosm/lifecycle/side_effect_definition.rb

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