approval_engine 1.0.0

data/app/models/approval_engine/template_step.rb

@@ -0,0 +1,22 @@
+module ApprovalEngine
+  # A blueprint for a layer of approval. When an approval is built, each template
+  # step is expanded into one concrete Step per resolved actor, all sharing the
+  # layer's consensus condition (`approvals_required`).
+  class TemplateStep < ApplicationRecord
+    belongs_to :track_template, class_name: "ApprovalEngine::TrackTemplate", foreign_key: "approval_engine_track_template_id"
+
+    validates :name, :assigned_group, presence: true
+    validates :layer, numericality: { greater_than: 0 }
+    validate :approvals_required_is_valid
+
+    scope :ordered, -> { order(:layer) }
+
+    private
+
+    def approvals_required_is_valid
+      return if Consensus.valid?(approvals_required)
+
+      errors.add(:approvals_required, "must be :any, :all, :majority, a percentage like \"60%\", or a positive integer")
+    end
+  end
+end

data/app/models/approval_engine/track.rb

@@ -0,0 +1,127 @@
+module ApprovalEngine
+  # One track of an approval (e.g. "Finance" or "Legal"). A track holds
+  # ordered layers of steps; a layer resolves once its consensus policy is met,
+  # which activates the next layer or completes the track.
+  #
+  # All progression happens synchronously inside the acting step's lock, so a
+  # track is never observed in a half-advanced state.
+  class Track < ApplicationRecord
+    STATUSES = %w[pending approved rejected cancelled].freeze
+    OPEN_STEP_STATUSES = %w[waiting pending].freeze
+
+    belongs_to :approval, class_name: "ApprovalEngine::Approval", foreign_key: "approval_engine_approval_id"
+    has_many :steps, class_name: "ApprovalEngine::Step", foreign_key: "approval_engine_track_id", dependent: :destroy
+
+    validates :tenant_id, :name, presence: true
+    validates :status, inclusion: { in: STATUSES }
+
+    STATUSES.each do |state|
+      define_method(:"#{state}?") { status == state }
+    end
+
+    # A step was approved or rejected: re-evaluate its layer and short-circuit.
+    # The layer resolves the moment its consensus is *met*, fails the moment its
+    # consensus is *unreachable*, and otherwise waits for more votes. Both
+    # approve! and reject! funnel through here so rejection respects the layer's
+    # consensus policy instead of being a blanket veto.
+    def advance!(step)
+      layer_steps = steps.for_iteration(step.iteration).for_layer(step.layer)
+
+      case layer_outcome(layer_steps)
+      when :met
+        cancel_steps(layer_steps.pending) # remaining votes are no longer needed
+        activate_next_layer(step) || complete!
+      when :failed
+        fail!
+      end
+    end
+
+    # An approver requested changes: cancel this iteration's open work and
+    # append a fresh iteration. The track stays pending.
+    def advance_after_changes_requested!(step)
+      cancel_open_steps!
+      IterationBuilder.build_next_iteration!(step)
+    end
+
+    # The live consensus tally for one layer (within an iteration) — the same
+    # facts `advance!` decides on, exposed as a read so a host UI can show
+    # "N of M approved" and *why* a layer is met/failed/undecided without
+    # re-deriving the consensus math (which only the engine should own).
+    #
+    #   track.layer_tally(1)
+    #   # => { required: 2, approved: 1, rejected: 0, pending: 2, waiting: 0,
+    #   #      group_size: 3, outcome: :undecided }
+    #
+    # Defaults to the track's latest iteration. A layer that hasn't opened yet
+    # (all steps still `waiting`) reads as `:undecided`, not `:failed`. Returns a
+    # zeroed `:undecided` tally for a layer that has no steps.
+    def layer_tally(layer, iteration: steps.maximum(:iteration))
+      tally_for(steps.for_iteration(iteration).for_layer(layer))
+    end
+
+    private
+
+    # :met, :failed, or :undecided for a layer — just the verdict slice of the
+    # full tally. Both approve! and reject! funnel through advance! → here, so
+    # rejection respects the layer's consensus policy instead of being a veto.
+    def layer_outcome(layer_steps)
+      tally_for(layer_steps)[:outcome]
+    end
+
+    # Met once `required` approvals are in; failed only once unreachable — even
+    # the steps still to come (pending + not-yet-opened `waiting`) couldn't reach
+    # it. advance! only sees the active layer, where waiting is 0, so it's unchanged.
+    def tally_for(layer_steps)
+      spec = layer_steps.first&.approvals_required
+      return { required: 0, approved: 0, rejected: 0, pending: 0, waiting: 0, group_size: 0, outcome: :undecided } if spec.nil?
+
+      approved = layer_steps.approved.count
+      pending  = layer_steps.pending.count
+      waiting  = layer_steps.waiting.count
+      rejected = layer_steps.where(status: "rejected").count
+      group    = layer_steps.where.not(status: "cancelled").count
+      required = Consensus.new(spec).required(group)
+
+      outcome =
+        if approved >= required then :met
+        elsif (approved + pending + waiting) < required then :failed
+        else :undecided
+        end
+
+      { required: required, approved: approved, rejected: rejected, pending: pending, waiting: waiting, group_size: group, outcome: outcome }
+    end
+
+    # This track can't reach consensus: reject it, then let the approval
+    # re-gather (one rejected track no longer forces the whole approval down).
+    def fail!
+      update!(status: "rejected")
+      cancel_open_steps!
+      approval.gather!
+    end
+
+    # Activate the next *existing* layer above this one — not blindly layer + 1 —
+    # so non-contiguous layer numbers (1, 3, 5…) don't strand a waiting layer or
+    # complete the track prematurely.
+    def activate_next_layer(step)
+      scope = steps.for_iteration(step.iteration).waiting.where("layer > ?", step.layer)
+      next_layer = scope.minimum(:layer)
+      return false unless next_layer
+
+      scope.where(layer: next_layer).find_each { |s| s.update!(status: "pending") }
+      true
+    end
+
+    def complete!
+      update!(status: "approved")
+      approval.gather!
+    end
+
+    def cancel_open_steps!
+      cancel_steps(steps.where(status: OPEN_STEP_STATUSES))
+    end
+
+    def cancel_steps(relation)
+      relation.find_each { |s| s.update!(status: "cancelled") }
+    end
+  end
+end

data/app/models/approval_engine/track_template.rb

@@ -0,0 +1,23 @@
+module ApprovalEngine
+  # The reusable blueprint an approval is stamped from. Authored by SaaS admins
+  # (often through a UI) and selected at runtime by the matching TriggerRule.
+  class TrackTemplate < ApplicationRecord
+    STATUSES = %w[draft active archived].freeze
+
+    has_many :template_steps,
+             -> { ordered },
+             class_name: "ApprovalEngine::TemplateStep",
+             foreign_key: "approval_engine_track_template_id",
+             dependent: :destroy
+    has_many :trigger_rules,
+             class_name: "ApprovalEngine::TriggerRule",
+             foreign_key: "approval_engine_track_template_id",
+             dependent: :destroy
+
+    validates :tenant_id, :name, presence: true
+    validates :status, inclusion: { in: STATUSES }
+
+    scope :active, -> { where(status: "active") }
+    scope :for_tenant, ->(tenant_id) { where(tenant_id: tenant_id) }
+  end
+end

data/app/models/approval_engine/trigger_rule.rb

@@ -0,0 +1,17 @@
+module ApprovalEngine
+  # A tenant-scoped routing rule. Its `condition` is a JSON Logic AST stored in
+  # JSONB; the RuleEvaluator applies it to a host payload and, on the
+  # highest-priority match, spawns the linked template's approval.
+  class TriggerRule < ApplicationRecord
+    belongs_to :track_template, class_name: "ApprovalEngine::TrackTemplate", foreign_key: "approval_engine_track_template_id"
+
+    validates :tenant_id, :event_name, presence: true
+    validates :condition, presence: true
+    validates :priority, numericality: { only_integer: true }
+
+    scope :active, -> { where(active: true) }
+    scope :for_event, ->(event) { where(event_name: event) }
+    scope :for_tenant, ->(tenant_id) { where(tenant_id: tenant_id) }
+    scope :by_priority, -> { order(priority: :desc) }
+  end
+end

data/app/models/concerns/approval_engine/approvable.rb

@@ -0,0 +1,183 @@
+module ApprovalEngine
+  # Mixed into a host model by the `has_approvals` macro. Gives the
+  # model its approval association, the `exposes_for_approval` anti-corruption
+  # DSL, and the trigger that spawns an approval for a domain event.
+  #
+  #   class Invoice < ApplicationRecord
+  #     has_approvals
+  #
+  #     exposes_for_approval do
+  #       attribute :amount, type: :decimal
+  #       attribute :department, type: :string, source: ->(i) { i.department.name }
+  #     end
+  #
+  #     def after_approved
+  #       PaymentService.disburse_funds!(self)
+  #     end
+  #   end
+  #
+  # By default, creating the record evaluates the tenant's rules and spawns the
+  # matching approval. Override `trigger_approval?` to gate that, or
+  # pass `has_approvals(on: [])` to opt out and trigger manually with
+  # `record.run_approval!(event:)`.
+  module Approvable
+    extend ActiveSupport::Concern
+
+    # The ActiveRecord lifecycle events the `on:` option understands, mapped to
+    # the conventional suffix of the event they route (create -> "<model>.created").
+    # Add a lifecycle here and it's wired automatically — no new methods.
+    LIFECYCLE_EVENTS = { create: "created", update: "updated", destroy: "destroyed" }.freeze
+
+    included do
+      has_many :approvals,
+               class_name: "ApprovalEngine::Approval",
+               as: :target,
+               dependent: :destroy
+
+      # Per-class exposure, inherited and dup-on-write so subclasses can extend
+      # a parent's declaration without mutating it.
+      class_attribute :approval_exposure,
+                      instance_writer: false,
+                      default: ApprovalEngine::ApprovalExposure.new
+
+      # Which lifecycle events auto-trigger routing. Set by the macro.
+      class_attribute :approval_trigger_events, instance_writer: false, default: [].freeze
+
+      # One generic registration for every lifecycle — no method-per-event.
+      LIFECYCLE_EVENTS.each_key do |lifecycle|
+        after_commit(on: lifecycle, if: -> { auto_trigger_approval?(lifecycle) }) do
+          run_approval!(event: self.class.approval_event_name(lifecycle))
+        end
+      end
+    end
+
+    class_methods do
+      # Declare the whitelisted surface the rules engine may read. Additive: can
+      # be called more than once, and subclasses extend rather than replace.
+      def exposes_for_approval(&block)
+        exposure = approval_exposure.dup
+        exposure.instance_eval(&block) if block
+        self.approval_exposure = exposure
+      end
+
+      # The conventional event name an auto-trigger emits for a lifecycle
+      # (:create, :update, :destroy). Use it when defining rules so the rule's
+      # event_name can never drift from what the engine actually fires:
+      #
+      #   trigger_rules.create!(event_name: Invoice.approval_event_name(:create), ...)
+      #
+      # Raises for an unknown lifecycle rather than producing a silent typo.
+      def approval_event_name(lifecycle)
+        "#{model_name.element}.#{LIFECYCLE_EVENTS.fetch(lifecycle)}"
+      end
+    end
+
+    # The flat, string-keyed payload derived from `exposes_for_approval`.
+    def serialize_for_approval
+      approval_exposure.serialize(self)
+    end
+
+    # Start an approval, two ways (pass exactly one):
+    #
+    #   run_approval!(event: "invoice.created")     # engine routes by rules
+    #   run_approval!(templates: [finance, legal])  # you choose explicitly
+    #
+    # With `event:`, the tenant's rules are evaluated and the highest-priority
+    # match is spawned — returns the approval, a quarantine approval on a rule
+    # failure, or nil when nothing matched (or the tenant can't be resolved).
+    #
+    # With `templates:`, rule evaluation is skipped and exactly those templates
+    # are started (several become parallel tracks of one approval); always
+    # returns the spawned approval. Pair with `approval_candidates` to let a user
+    # choose instead of the engine. `approvals_required` is the gather consensus
+    # across those tracks (default `:all`).
+    def run_approval!(event: nil, templates: nil, approvals_required: "all", tenant_id: approval_tenant_id)
+      raise ArgumentError, "pass either event: or templates:, not both" if event && templates
+
+      if templates
+        ApprovalEngine::ApprovalBuilder.build_parallel!(templates: Array(templates), target: self, approvals_required: approvals_required)
+      elsif event
+        return if tenant_id.nil?
+
+        ApprovalEngine::RuleEvaluator.call(
+          event_name: event,
+          tenant_id: tenant_id,
+          target: self,
+          payload: serialize_for_approval
+        )
+      else
+        raise ArgumentError, "pass either event: or templates:"
+      end
+    end
+
+    # Host override hook: return false to skip an automatic trigger. Receives
+    # the lifecycle (:create or :update), so you can gate per-event — e.g. only
+    # auto-route an update when a specific transition happened:
+    #
+    #   def trigger_approval?(lifecycle)
+    #     lifecycle == :update ? saved_change_to_status? : true
+    #   end
+    def trigger_approval?(_lifecycle = nil)
+      true
+    end
+
+    # Preview what `event` *would* trigger for this record, without writing
+    # anything — handy for showing a user "this will go to Manager, then CFO"
+    # before they commit an action. Works against the in-memory record, so you
+    # can preview an unsaved change (`invoice.amount = 20_000; invoice.preview_...`).
+    # Returns an ApprovalEngine::ApprovalPlan.
+    def preview_approval(event:, tenant_id: approval_tenant_id)
+      ApprovalEngine::RuleEvaluator.preview(
+        event_name: event,
+        tenant_id: tenant_id,
+        target: self,
+        payload: serialize_for_approval
+      )
+    end
+
+    # Every approval that *would* match `event` for this record, in priority
+    # order — so you can let a user choose which to trigger rather than letting
+    # the engine auto-pick the top one. Returns an array of ApprovalPlan; writes
+    # nothing.
+    def approval_candidates(event:, tenant_id: approval_tenant_id)
+      ApprovalEngine::RuleEvaluator.candidates(
+        event_name: event,
+        tenant_id: tenant_id,
+        target: self,
+        payload: serialize_for_approval
+      )
+    end
+
+    # A read-only view of everything this record has gone through — approvals,
+    # the step tree, and a chronological timeline of actions + comments. The
+    # gem assembles it; you decide who may see it and how to render it.
+    def approval_history
+      ApprovalEngine::History.for(self)
+    end
+
+    def latest_approval
+      approvals.order(created_at: :desc).first
+    end
+
+    def approval_in_flight?
+      approvals.pending.exists?
+    end
+
+    def approval_status
+      latest_approval&.status
+    end
+
+    private
+
+    def auto_trigger_approval?(lifecycle)
+      approval_trigger_events.include?(lifecycle) && trigger_approval?(lifecycle)
+    end
+
+    # Tenant id derived from the configured `current_tenant_method`. Override in
+    # the host model if the tenant lives somewhere model-specific.
+    def approval_tenant_id
+      tenant = ApprovalEngine.current_tenant
+      tenant.respond_to?(:id) ? tenant.id : tenant
+    end
+  end
+end

data/app/services/approval_engine/approval_builder.rb

@@ -0,0 +1,172 @@
+module ApprovalEngine
+  # Stamps a concrete, actionable ledger (Approval → Track → Steps) out of one
+  # or more abstract TrackTemplates.
+  #
+  # A single template builds a single-track approval. Several templates build a
+  # scatter-gather approval: one parallel track per template, all active at once,
+  # gathering per the approval's `approvals_required` (`:all` by default).
+  #
+  # Each template step is expanded into one Step per resolved actor — so "any
+  # one of five senior devs" becomes five sibling steps sharing one consensus
+  # policy. Only each track's first layer starts `pending`; later layers wait
+  # until the layer before them resolves.
+  class ApprovalBuilder
+    class BuilderError < ApprovalEngine::Error; end
+
+    # Build a single-track approval from one template. `event_name` is the event
+    # that triggered this run (nil when started manually) — recorded on the
+    # Approval for audit/display. `trigger_rule` is the rule that matched, when
+    # auto-routed, so the approval remembers its provenance.
+    def self.build!(template:, target:, event_name: nil, trigger_rule: nil)
+      new(templates: [ template ], target: target, event_name: event_name, trigger_rule: trigger_rule).build!
+    end
+
+    # Build a scatter-gather approval, one parallel track per template.
+    # `approvals_required` is the gather consensus (default `:all`).
+    def self.build_parallel!(templates:, target:, event_name: nil, approvals_required: "all")
+      raise BuilderError, "build_parallel! needs at least one template" if templates.blank?
+
+      new(templates: templates, target: target, event_name: event_name, approvals_required: approvals_required).build!
+    end
+
+    def initialize(templates:, target:, event_name: nil, trigger_rule: nil, approvals_required: "all")
+      @templates           = templates
+      @target              = target
+      @event_name          = event_name
+      @trigger_rule        = trigger_rule
+      @approvals_required  = approvals_required.to_s
+    end
+
+    def build!
+      guard_single_tenant!
+      guard_gather_consensus!
+      ActiveRecord::Base.transaction do
+        approval = build_approval
+        templates.each { |template| build_track!(approval, template) }
+        approval
+      end
+    end
+
+    # The fail-closed quarantine state. Built when a dynamic rule blows up, so
+    # ops can see exactly why a track never started instead of hitting a 500.
+    def self.build_quarantine_approval!(target:, tenant_id:, reason:)
+      Approval.create!(tenant_id: tenant_id, target: target, status: "quarantined").tap do |approval|
+        OutboxEvent.create!(
+          tenant_id: approval.tenant_id,
+          event_name: "approval.quarantined",
+          record: approval,
+          error_payload: reason
+        )
+      end
+    end
+
+    private
+
+    attr_reader :templates, :target, :event_name, :trigger_rule, :approvals_required
+
+    def build_approval
+      Approval.create!(
+        tenant_id: templates.first.tenant_id,
+        target: target,
+        status: "pending",
+        event_name: event_name,
+        trigger_rule: trigger_rule,
+        approvals_required: approvals_required
+      )
+    end
+
+    def build_track!(approval, template)
+      track = Track.create!(
+        tenant_id: template.tenant_id,
+        approval: approval,
+        name: template.name,
+        status: "pending"
+      )
+      build_steps(track, template)
+    end
+
+    def build_steps(track, template)
+      first_layer = template.template_steps.minimum(:layer)
+
+      template.template_steps.ordered.each do |tpl_step|
+        actors = resolve_actors(tpl_step)
+        guard_consensus!(tpl_step, actors)
+
+        actors.each do |actor|
+          track.steps.create!(
+            tenant_id: template.tenant_id,
+            name: tpl_step.name,
+            layer: tpl_step.layer,
+            iteration: 1,
+            status: tpl_step.layer == first_layer ? "pending" : "waiting",
+            approvals_required: tpl_step.approvals_required,
+            timeout_after: tpl_step.timeout_after,
+            assigned_actor: actor
+          )
+        end
+      end
+    end
+
+    def resolve_actors(tpl_step)
+      actors = Array(host_actor_resolver.resolve_approval_group(tpl_step.assigned_group, target)).compact
+
+      if actors.empty?
+        raise BuilderError, "No actors resolved for group '#{tpl_step.assigned_group}'. " \
+                            "Check #{host_actor_resolver}.resolve_approval_group."
+      end
+
+      actors
+    end
+
+    # A layer needing more approvals than it has actors could never resolve —
+    # fail loudly at build time instead of silently stranding the approval in
+    # `pending` forever. (Only an absolute count can exceed the group; relative
+    # specs like :majority / "60%" are always satisfiable.)
+    def guard_consensus!(tpl_step, actors)
+      required = Consensus.new(tpl_step.approvals_required).required(actors.size)
+      return if required <= actors.size
+
+      raise BuilderError, "Step '#{tpl_step.name}' needs #{required} approval(s) but only " \
+                          "#{actors.size} actor(s) resolved for group '#{tpl_step.assigned_group}' " \
+                          "— it could never resolve."
+    end
+
+    # The approval and all its rows are stamped from one tenant; mixed-tenant
+    # templates would scatter a single ledger across tenants. Fail at the boundary.
+    def guard_single_tenant!
+      tenants = templates.map(&:tenant_id).uniq
+      return if tenants.size == 1
+
+      raise BuilderError, "all templates must belong to one tenant (got #{tenants.inspect})."
+    end
+
+    # The gather twin of guard_consensus!: a fixed count exceeding the track
+    # count could never resolve.
+    def guard_gather_consensus!
+      raise BuilderError, "approvals_required #{approvals_required.inspect} is not a valid consensus spec." unless Consensus.valid?(approvals_required)
+
+      required = Consensus.new(approvals_required).required(templates.size)
+      return if required <= templates.size
+
+      raise BuilderError, "approval needs #{required} track approval(s) but only #{templates.size} " \
+                          "track(s) were given — it could never resolve."
+    end
+
+    def host_actor_resolver
+      klass = actor_class
+
+      unless klass.respond_to?(:resolve_approval_group)
+        raise BuilderError, "#{klass} must define `self.resolve_approval_group(group_name, target)`."
+      end
+
+      klass
+    end
+
+    def actor_class
+      ApprovalEngine.config.actor_class_constant
+    rescue NameError => e
+      raise BuilderError, "ApprovalEngine.config.actor_class is #{ApprovalEngine.config.actor_class.inspect}, " \
+                          "which doesn't resolve to a loaded class (#{e.message})."
+    end
+  end
+end

data/app/services/approval_engine/iteration_builder.rb

@@ -0,0 +1,44 @@
+module ApprovalEngine
+  # Implements the append-only iteration cycle. Rather than resetting an approved
+  # step back to pending (which would destroy the audit trail), requesting
+  # changes clones the track's current iteration into a fresh one, so every
+  # past attempt remains permanently on the ledger.
+  #
+  # Always invoked while the approval is locked, so it does not lock again.
+  class IterationBuilder
+    def self.build_next_iteration!(from_step)
+      new(from_step).build!
+    end
+
+    def initialize(from_step)
+      @from_step = from_step
+      @track  = from_step.track
+    end
+
+    def build!
+      blueprint = track.steps.for_iteration(from_step.iteration).order(:layer, :created_at).to_a
+      first_layer = blueprint.map(&:layer).min
+
+      blueprint.each do |old_step|
+        track.steps.create!(
+          tenant_id: old_step.tenant_id,
+          name: old_step.name,
+          layer: old_step.layer,
+          iteration: next_iteration,
+          status: old_step.layer == first_layer ? "pending" : "waiting",
+          approvals_required: old_step.approvals_required,
+          timeout_after: old_step.timeout_after,
+          assigned_actor: old_step.assigned_actor
+        )
+      end
+    end
+
+    private
+
+    attr_reader :from_step, :track
+
+    def next_iteration
+      @next_iteration ||= from_step.iteration + 1
+    end
+  end
+end