# frozen_string_literal: true

# FOSM: Finite Object State Machine
# Based on Abhishek Parolkar's FOSM paper (https://www.parolkar.com/fosm)
#
# Objects are active lifecycle participants, not passive data bags.
# Every business object declares its lifecycle: states, events, transitions,
# guards, side-effects, and actor permissions.

module Fosm
  module Lifecycle
    extend ActiveSupport::Concern

    included do
      # Every FOSM object has many transitions (the audit log)
      has_many :fosm_transitions, -> { order(created_at: :asc) },
               as: :transitionable,
               class_name: "FosmTransition",
               foreign_key: :object_id,
               dependent: :destroy

      after_create :record_initial_transition
      after_create :sync_fosm_definition
    end

    class_methods do
      attr_reader :fosm_definition_data

      def lifecycle(&block)
        @fosm_definition_data = LifecycleBuilder.new
        @fosm_definition_data.instance_eval(&block)
        @fosm_definition_data.freeze_definition

        # Define scopes from states
        @fosm_definition_data.states.each do |state_name, _config|
          scope state_name, -> { where(status: state_name.to_s) }
        end
      end

      def fosm_states
        @fosm_definition_data&.states || {}
      end

      def fosm_events
        @fosm_definition_data&.events || {}
      end

      def fosm_guards
        @fosm_definition_data&.guards_registry || {}
      end

      def fosm_side_effects
        @fosm_definition_data&.side_effects_registry || {}
      end

      def fosm_actors
        @fosm_definition_data&.actor_types || []
      end

      def fosm_initial_state
        @fosm_definition_data&.initial_state
      end

      def fosm_terminal_states
        @fosm_definition_data&.terminal_states || []
      end

      def fosm_documentation
        @fosm_definition_data&.documentation || {}
      end

      def fosm_process_description
        @fosm_definition_data&.process_description
      end

      # Find all valid events from a given state
      def available_events_from(state)
        fosm_events.select do |_name, config|
          Array(config[:from]).map(&:to_s).include?(state.to_s)
        end
      end

      # Eagerly sync the lifecycle definition to fosm_definitions
      def sync_fosm_definition!
        defn = FosmDefinition.find_or_initialize_by(object_type: name)
        return if defn.source == "admin"

        hash = fosm_definition_hash
        defn.assign_attributes(
          states:              hash[:states],
          events:              hash[:events],
          guards:              hash[:guards],
          side_effects:        hash[:side_effects],
          actors:              hash[:actors],
          ai_config:           {},
          source:              "dsl",
          documentation:       hash[:documentation],
          process_description: hash[:process_description]
        )
        defn.save if defn.new_record? || defn.changed?
      rescue => e
        Rails.logger.warn "FOSM: Could not sync definition for #{name}: #{e.message}"
      end

      # Introspection: return full lifecycle definition as hash
      def fosm_definition_hash
        {
          object_type:         name,
          states:              fosm_states,
          events:              fosm_events.transform_values { |v| v.except(:guard_blocks, :side_effect_blocks) },
          guards:              fosm_guards.transform_values { |v| { description: v[:description] } },
          side_effects:        fosm_side_effects.transform_values { |v| { description: v[:description], on: v[:on] } },
          actors:              fosm_actors,
          initial_state:       fosm_initial_state,
          terminal_states:     fosm_terminal_states,
          documentation:       fosm_documentation,
          process_description: fosm_process_description
        }
      end
    end

    # ── Instance methods ────────────────────────────────────

    def current_state
      status&.to_sym
    end

    def available_events
      self.class.available_events_from(current_state)
    end

    def terminal?
      self.class.fosm_terminal_states.include?(current_state)
    end

    def can_transition?(event_name)
      event = self.class.fosm_events[event_name.to_sym]
      return false unless event
      Array(event[:from]).map(&:to_s).include?(status.to_s)
    end

    def transition!(event_name, actor: nil, metadata: {})
      Fosm::TransitionService.execute!(self, event_name.to_sym, actor: actor, metadata: metadata)
    end

    def lifecycle_history
      FosmTransition.where(object_type: self.class.name, object_id: id).order(created_at: :asc)
    end

    def time_in_state
      last_transition = lifecycle_history.last
      return nil unless last_transition
      Time.current - last_transition.created_at
    end

    private

    def record_initial_transition
      initial = self.class.fosm_initial_state
      return unless initial

      FosmTransition.create!(
        object_type: self.class.name,
        object_id:   id,
        from_state:  "_new",
        to_state:    initial.to_s,
        event:       "_create",
        actor_type:  "System",
        metadata:    { auto: true }
      )
    end

    def sync_fosm_definition
      defn = FosmDefinition.find_or_initialize_by(object_type: self.class.name)
      return if defn.source == "admin"  # don't overwrite admin customizations

      hash = self.class.fosm_definition_hash
      defn.assign_attributes(
        states:              hash[:states],
        events:              hash[:events],
        guards:              hash[:guards],
        side_effects:        hash[:side_effects],
        actors:              hash[:actors],
        ai_config:           {},
        source:              "dsl",
        documentation:       hash[:documentation],
        process_description: hash[:process_description]
      )
      defn.save if defn.changed?
    rescue => e
      Rails.logger.warn "FOSM: Could not sync definition for #{self.class.name}: #{e.message}"
    end
  end
end

def lifecycle(&block)
  @fosm_definition_data = LifecycleBuilder.new
  @fosm_definition_data.instance_eval(&block)
  @fosm_definition_data.freeze_definition
  # ...auto-generate scopes...
end

nda.current_state          # → :draft
nda.available_events       # → { send_invitation: {...}, cancel: {...} }
nda.terminal?              # → false (draft is not terminal)
nda.can_transition?(:cancel)  # → true
nda.transition!(:send_invitation, actor: current_user)
nda.lifecycle_history      # → all FosmTransitions for this NDA
nda.time_in_state          # → seconds since last transition

# frozen_string_literal: true

module Fosm
  class LifecycleBuilder
    attr_reader :states, :events, :guards_registry, :side_effects_registry,
                :actor_types, :initial_state, :terminal_states,
                :documentation, :process_description

    def initialize
      @states               = {}
      @events               = {}
      @guards_registry      = {}
      @side_effects_registry = {}
      @actor_types          = []
      @initial_state        = nil
      @terminal_states      = []
      @documentation        = {}
      @process_description  = nil
    end

    def state(name, label: nil, color: "gray", initial: false, terminal: false, doc: nil)
      name = name.to_sym
      @states[name] = {
        label:    label || name.to_s.humanize,
        color:    color,
        initial:  initial,
        terminal: terminal
      }
      @initial_state = name if initial
      @terminal_states << name if terminal
      if doc
        @documentation[:states] ||= {}
        @documentation[:states][name] = doc.strip
      end
    end

    def event(name, from:, to:, label: nil, approval_required: false, doc: nil)
      name = name.to_sym
      @events[name] = {
        label:             label || name.to_s.humanize,
        from:              Array(from).map(&:to_sym),
        to:                to.to_sym,
        approval_required: approval_required,
        guards:            [],
        side_effects:      []
      }
      if doc
        @documentation[:events] ||= {}
        @documentation[:events][name] = doc.strip
      end
    end

    def actors(*types)
      @actor_types = types.map(&:to_sym)
    end

    def guard(name, on: nil, description: nil, doc: nil, &block)
      name        = name.to_sym
      events_list = on ? Array(on).map(&:to_sym) : []

      @guards_registry[name] = {
        description: description || name.to_s.humanize,
        on:          events_list,
        block:       block
      }

      # Attach guard to specific events
      events_list.each do |event_name|
        @events[event_name][:guards] << name if @events[event_name]
      end

      if doc
        @documentation[:guards] ||= {}
        @documentation[:guards][name] = doc.strip
      end
    end

    def side_effect(name, on: nil, description: nil, doc: nil, &block)
      name        = name.to_sym
      events_list = on ? Array(on).map(&:to_sym) : []

      @side_effects_registry[name] = {
        description: description || name.to_s.humanize,
        on:          events_list,
        block:       block
      }

      # Attach side_effect to specific events
      events_list.each do |event_name|
        @events[event_name][:side_effects] << name if @events[event_name]
      end

      if doc
        @documentation[:side_effects] ||= {}
        @documentation[:side_effects][name] = doc.strip
      end
    end

    # Sets the top-level prose description for the business process.
    # Write once, lives with the code, exported as llms.txt.
    def process_doc(text)
      @process_description = text.strip_heredoc.strip
    end

    # Documents a specific lifecycle element (state, event, guard, side_effect).
    def doc(element_type, name, text)
      @documentation[element_type.to_sym] ||= {}
      @documentation[element_type.to_sym][name.to_sym] = text.strip_heredoc.strip
    end

    def freeze_definition
      @states.freeze
      @events.freeze
      @guards_registry.freeze
      @side_effects_registry.freeze
      @actor_types.freeze
      @terminal_states.freeze
      @documentation.freeze
      @process_description.freeze
    end
  end
end

def guard(name, on: nil, description: nil, doc: nil, &block)
  # ...register in guards_registry...
  events_list.each do |event_name|
    @events[event_name][:guards] << name if @events[event_name]
  end
end

# frozen_string_literal: true

module Fosm
  class TransitionService
    class InvalidTransition < StandardError; end
    class GuardFailed       < StandardError; end
    class AccessDenied      < StandardError; end

    def self.execute!(object, event_name, actor: nil, metadata: {})
      new(object, event_name, actor: actor, metadata: metadata).execute!
    end

    def initialize(object, event_name, actor: nil, metadata: {})
      @object       = object
      @event_name   = event_name.to_sym
      @actor        = actor
      @metadata     = metadata
      @event_config = object.class.fosm_events[@event_name]
    end

    def execute!
      validate_transition!
      authorize_actor!            # Last Responsible Moment
      guard_results = evaluate_guards!

      from_state = @object.status.to_s
      to_state   = @event_config[:to].to_s

      # Create the transition record FIRST (audit log)
      transition = FosmTransition.create!(
        object_type:  @object.class.name,
        object_id:    @object.id,
        from_state:   from_state,
        to_state:     to_state,
        event:        @event_name.to_s,
        actor_type:   actor_type_string,
        actor_id:     actor_id_value,
        guard_results: guard_results,
        metadata:     @metadata
      )

      # Update the object's status
      @object.update!(status: to_state)

      # Execute side effects
      executed_side_effects = execute_side_effects!(transition)
      transition.update!(side_effects_executed: executed_side_effects)

      # Publish to EventBus
      EventBus.publish(
        "fosm.transition.#{@object.class.name.underscore}.#{@event_name}",
        user: (@actor.is_a?(User) ? @actor : nil),
        payload: {
          object_type:   @object.class.name,
          object_id:     @object.id,
          from_state:    from_state,
          to_state:      to_state,
          event:         @event_name.to_s,
          transition_id: transition.id
        }
      )

      # Record analytics event
      record_analytics_event!("transition", from_state, to_state)

      transition
    rescue InvalidTransition, GuardFailed, AccessDenied => e
      record_analytics_event!("error", @object.status.to_s, nil, error: e.message, error_type: error_type_for(e))
      raise
    end

    private

    def authorize_actor!
      return unless access_control_enabled?
      return if @actor.nil?            # System transitions bypass ACL
      return if @actor.is_a?(Bot)      # Bots are system-level actors
      return unless @actor.is_a?(User)

      result = Fosm::PolicyResolver.resolve(@actor, @object.class.name, @event_name)
      unless result.permitted?
        raise AccessDenied,
          "You do not have permission to '#{@event_name}' on #{@object.class.name}. " \
          "Your roles: #{result.actor_roles.join(', ').presence || 'none'}"
      end
    end

    def access_control_enabled?
      ModuleSetting.enabled?("access_control")
    end

    def validate_transition!
      raise InvalidTransition, "Unknown event: #{@event_name}" unless @event_config

      valid_from = Array(@event_config[:from]).map(&:to_s)
      unless valid_from.include?(@object.status.to_s)
        raise InvalidTransition,
          "Cannot fire '#{@event_name}' from state '#{@object.status}'. " \
          "Valid from: #{valid_from.join(', ')}"
      end
    end

    def evaluate_guards!
      results = {}
      guards  = @event_config[:guards] || []

      guards.each do |guard_name|
        guard_def = @object.class.fosm_guards[guard_name]
        next unless guard_def && guard_def[:block]

        result = guard_def[:block].call(@object)
        results[guard_name.to_s] = result

        unless result
          raise GuardFailed, "Guard '#{guard_name}' failed for event '#{@event_name}'"
        end
      end

      results
    end

    def execute_side_effects!(transition)
      executed       = []
      side_effects   = @event_config[:side_effects] || []

      side_effects.each do |effect_name|
        effect_def = @object.class.fosm_side_effects[effect_name]
        next unless effect_def && effect_def[:block]

        begin
          effect_def[:block].call(@object, transition)
          executed << effect_name.to_s
        rescue => e
          Rails.logger.error "FOSM: Side-effect '#{effect_name}' failed: #{e.message}"
          executed << "#{effect_name}:failed"
        end
      end

      executed
    end

    def actor_type_string
      return "System" unless @actor
      @actor.class.name
    end

    def actor_id_value
      return nil unless @actor
      @actor.respond_to?(:id) ? @actor.id : nil
    end

    def error_type_for(exception)
      case exception
      when AccessDenied then "authorization_failed"
      when GuardFailed  then "guard_failed"
      else                   "transition_failed"
      end
    end

    def record_analytics_event!(event_type, from_state, to_state, extra_metadata = {})
      if @actor.is_a?(User) && @actor.respond_to?(:roles)
        extra_metadata[:actor_roles] = @actor.roles.pluck(:name) rescue []
      end

      AnalyticsEvent.create!(
        user:        (@actor.is_a?(User) ? @actor : nil),
        event_type:  event_type,
        object_type: @object.class.name,
        object_id:   @object.id,
        event_name:  @event_name.to_s,
        metadata:    { from_state: from_state, to_state: to_state }.merge(extra_metadata)
      )
    rescue => e
      Rails.logger.warn "FOSM Analytics: Could not record event: #{e.message}"
    end
  end
end

# frozen_string_literal: true

# Every state change is recorded here — the single source of truth audit log.
# Based on Plattner's principle: eliminate aggregates, query the transitions directly.
class FosmTransition < ApplicationRecord
  belongs_to :actor, polymorphic: true, optional: true

  scope :for_object,  ->(type, id) { where(object_type: type, object_id: id) }
  scope :for_type,    ->(type)     { where(object_type: type) }
  scope :by_event,    ->(event)    { where(event: event) }
  scope :by_actor,    ->(actor_type) { where(actor_type: actor_type) }
  scope :recent,      -> { order(created_at: :desc) }
  scope :today,       -> { where("created_at >= ?", Time.current.beginning_of_day) }
  scope :this_week,   -> { where("created_at >= ?", 1.week.ago) }

  # Analytics: time spent in each state, computed from raw transitions
  def self.avg_time_in_state(object_type, state)
    transitions = where(object_type: object_type, from_state: state.to_s).order(:created_at)
    return nil if transitions.empty?

    durations = transitions.map do |t|
      entry = where(object_type: t.object_type, object_id: t.object_id, to_state: state.to_s)
                .where("created_at < ?", t.created_at)
                .order(created_at: :desc).first
      next unless entry
      t.created_at - entry.created_at
    end.compact

    return nil if durations.empty?
    durations.sum / durations.size
  end

  def self.transition_counts_by_event(object_type, since: 30.days.ago)
    where(object_type: object_type)
      .where("created_at >= ?", since)
      .where.not(event: "_create")
      .group(:event)
      .count
  end

  def self.state_distribution(object_type)
    subquery = where(object_type: object_type)
                 .select("object_id, MAX(created_at) as max_created")
                 .group(:object_id)

    latest_transitions = joins(
      "INNER JOIN (#{subquery.to_sql}) latest " \
      "ON fosm_transitions.object_id = latest.object_id " \
      "AND fosm_transitions.created_at = latest.max_created"
    ).where(object_type: object_type)

    latest_transitions.group(:to_state).count
  end

  def human_actor?  = actor_type == "User"
  def ai_actor?     = actor_type == "AiService" || actor_type == "Ai"
  def system_actor? = actor_type == "System"

  def duration_from_previous
    prev = FosmTransition
             .where(object_type: object_type, object_id: object_id)
             .where("created_at < ?", created_at)
             .order(created_at: :desc).first
    return nil unless prev
    created_at - prev.created_at
  end
end

create_table :fosm_transitions do |t|
  t.string  :object_type,         null: false
  t.integer :object_id,           null: false
  t.string  :from_state,          null: false
  t.string  :to_state,            null: false
  t.string  :event,               null: false
  t.string  :actor_type                      # "User", "AiService", "System"
  t.integer :actor_id                        # polymorphic
  t.json    :guard_results,       default: {} # { guard_name: true/false }
  t.json    :side_effects_executed, default: [] # ["send_email", "notify:failed"]
  t.json    :metadata,            default: {}  # arbitrary context
  t.string  :approval_status                  # nil, "pending", "approved", "rejected"
  t.integer :approved_by_id
  t.datetime :approved_at
  t.timestamps
end

add_index :fosm_transitions, [:object_type, :object_id]
add_index :fosm_transitions, :event
add_index :fosm_transitions, :actor_type
add_index :fosm_transitions, :created_at
add_index :fosm_transitions, :from_state
add_index :fosm_transitions, :to_state

# frozen_string_literal: true

# Stores the lifecycle definition for each FOSM object type.
# The Ruby DSL and Admin UI both read/write this.
class FosmDefinition < ApplicationRecord
  validates :object_type, presence: true, uniqueness: true

  def state_names  = (states  || {}).keys
  def event_names  = (events  || {}).keys

  def state_config(state_name) = (states || {})[state_name.to_s]
  def event_config(event_name) = (events || {})[event_name.to_s]

  def initial_state
    (states || {}).find { |_k, v| v["initial"] }&.first
  end

  def terminal_states
    (states || {}).select { |_k, v| v["terminal"] }.keys
  end

  def state_doc(state_name)    = (documentation || {}).dig("states", state_name.to_s)
  def event_doc(event_name)    = (documentation || {}).dig("events", event_name.to_s)
  def guard_doc(guard_name)    = (documentation || {}).dig("guards", guard_name.to_s)
  def side_effect_doc(name)    = (documentation || {}).dig("side_effects", name.to_s)

  def mermaid_diagram
    lines = ["stateDiagram-v2"]
    init  = initial_state
    lines << "  [*] --> #{init}" if init

    (events || {}).each do |event_name, config|
      froms = Array(config["from"] || config[:from])
      to    = config["to"] || config[:to]
      froms.each { |from| lines << "  #{from} --> #{to}: #{event_name}" }
    end

    terminal_states.each { |ts| lines << "  #{ts} --> [*]" }
    lines.join("\n")
  end

  def to_prose
    lines = []
    lines << "# #{object_type}"
    lines << ""
    lines << process_description if process_description.present?
    lines << ""

    lines << "## States"
    lines << ""
    (states || {}).each do |name, config|
      label    = config["label"] || name.to_s.humanize
      flags    = []
      flags << "INITIAL"   if config["initial"]
      flags << "TERMINAL"  if config["terminal"]
      flag_str = flags.any? ? " (#{flags.join(', ')})" : ""
      lines << "### #{label}#{flag_str}"
      doc = state_doc(name)
      lines << doc if doc.present?
      lines << ""
    end

    lines << "## Events"
    lines << ""
    (events || {}).each do |name, config|
      label = config["label"] || name.to_s.humanize
      from  = Array(config["from"]).join(", ")
      to    = config["to"]
      lines << "### #{label}"
      lines << "Transition: #{from} → #{to}"
      lines << "⚠ Requires approval" if config["approval_required"]
      doc = event_doc(name)
      lines << doc if doc.present?
      lines << ""
    end

    # ... guards and side effects sections
    lines.join("\n")
  end
end

create_table :fosm_definitions do |t|
  t.string  :object_type, null: false        # "Nda", "Invoice", "LeaveRequest"
  t.json    :states,      null: false, default: {}
  t.json    :events,      null: false, default: {}
  t.json    :guards,      null: false, default: {}
  t.json    :side_effects, null: false, default: {}
  t.json    :actors,      null: false, default: {}
  t.json    :ai_config,   null: false, default: {}
  t.string  :source, default: "dsl"          # "dsl" or "admin"
  t.integer :version, default: 1
  t.timestamps
end

add_index :fosm_definitions, :object_type, unique: true

# frozen_string_literal: true

class EventBus
  class << self
    def publish(name, user: nil, conversation: nil, payload: {})
      EventLog.create!(name:, user:, conversation:, payload: payload || {})
    end

    def message_created(message)
      conv = message.conversation
      publish('message.created', user: conv.user, conversation: conv,
              payload: { message_id: message.id })
    end

    def assistant_typing(conversation)
      publish('assistant.typing', user: conversation.user,
              conversation:, payload: {})
    end

    def conversation_title_updated(conversation)
      publish('conversation.title_updated', user: conversation.user,
              conversation:, payload: { title: conversation.title })
    end
  end
end

EventBus.publish(
  "fosm.transition.nda.send_invitation",
  user:    current_user,
  payload: { object_type: "Nda", object_id: 42, from_state: "draft", to_state: "sent", transition_id: 7 }
)

@nda.transition!(:send_invitation, actor: current_user)