approval_engine 1.0.0

data/app/models/approval_engine/approval.rb

@@ -0,0 +1,144 @@
+module ApprovalEngine
+  # The aggregate root of one approval run: a host record + the event that
+  # spawned it, fanning out into one or more parallel tracks that gather per
+  # `approvals_required` (`:all` by default, like a layer). Progression methods
+  # run while the approval row is locked by the acting step, so they don't relock.
+  class Approval < ApplicationRecord
+    STATUSES = %w[pending approved rejected quarantined cancelled].freeze
+    TERMINAL_STATUSES = %w[approved rejected quarantined cancelled].freeze
+
+    belongs_to :target, polymorphic: true
+    # The rule that auto-routed this approval, when one did (nil for a manual
+    # run_approval!(templates:) start). Lets a host show *which* rule fired and
+    # why, and keeps that provenance stable even if the rule is later edited.
+    belongs_to :trigger_rule,
+               class_name: "ApprovalEngine::TriggerRule",
+               foreign_key: "approval_engine_trigger_rule_id",
+               optional: true
+    has_many :tracks, class_name: "ApprovalEngine::Track", foreign_key: "approval_engine_approval_id", dependent: :destroy
+    has_many :steps, through: :tracks
+
+    validates :tenant_id, presence: true
+    validates :status, inclusion: { in: STATUSES }
+    validate :approvals_required_is_valid
+
+    scope :pending, -> { where(status: "pending") }
+    scope :quarantined, -> { where(status: "quarantined") }
+    scope :terminal, -> { where(status: TERMINAL_STATUSES) }
+    scope :for_tenant, ->(tenant_id) { where(tenant_id: tenant_id) }
+
+    STATUSES.each do |state|
+      define_method(:"#{state}?") { status == state }
+    end
+
+    def terminal?
+      TERMINAL_STATUSES.include?(status)
+    end
+
+    # Convenience readers for the common single-track case. An approval always
+    # has at least one track, so when there's exactly one these read more
+    # naturally than `tracks.first`. They raise (ActiveRecord::SoleRecord
+    # exceeded) once the approval has fanned out, so a caller is never silently
+    # handed the wrong track — reach for `tracks` / `steps` then.
+    def track
+      tracks.sole
+    end
+
+    def step
+      steps.sole
+    end
+
+    # The step this approval is currently waiting on the longest — i.e. *where*
+    # it's stuck right now. The oldest still-pending step across all tracks, or
+    # nil if nothing is pending. `step.waiting_for` gives the elapsed seconds; the
+    # host decides what counts as "late" and whether to nudge or escalate.
+    def current_bottleneck
+      steps.pending.order(:activated_at).first
+    end
+
+    # Re-evaluate after any track resolves: approve once enough tracks have,
+    # fail once the count is unreachable, else wait. A layer's logic, over tracks.
+    def gather!
+      return if terminal?
+
+      case track_outcome
+      when :met
+        update!(status: "approved")
+        cancel_remaining_tracks!
+        emit_outbox("approval.approved")
+      when :failed
+        fail_gather!(reason: "required track approvals are no longer reachable")
+      end
+    end
+
+    # Withdraw an in-flight approval — the third terminal outcome beside approved
+    # and rejected, for when the thing being approved is voided or retracted.
+    # Cancels any still-open tracks/steps and fires `after_cancelled`. A no-op
+    # once terminal. Unlike the gather, this is a host entry point, so it takes
+    # its own lock.
+    def cancel!(reason: nil)
+      return self if terminal?
+
+      with_lock do
+        return self if terminal?
+
+        update!(status: "cancelled")
+        cancel_remaining_tracks!
+        emit_outbox("approval.cancelled", reason)
+      end
+      self
+    end
+
+    private
+
+    # Internal: tear the whole approval down when the gather can't be satisfied
+    # (called from gather! under the step's lock). No actor, no audit row — hosts
+    # reject through a step (Step#reject!) or withdraw via cancel!.
+    def fail_gather!(reason: nil)
+      return if terminal?
+
+      update!(status: "rejected")
+      cancel_remaining_tracks!
+      emit_outbox("approval.rejected", reason)
+    end
+
+    # :met / :failed / :undecided across tracks — layer consensus, one level up.
+    def track_outcome
+      group = tracks.where.not(status: "cancelled").count
+      return :undecided if group.zero?
+
+      approved = tracks.where(status: "approved").count
+      pending  = tracks.where(status: "pending").count
+      required = Consensus.new(approvals_required).required(group)
+
+      if approved >= required then :met
+      elsif (approved + pending) < required then :failed
+      else :undecided
+      end
+    end
+
+    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
+
+    def cancel_remaining_tracks!
+      tracks.where(status: %w[pending]).find_each do |track|
+        track.steps.where(status: Track::OPEN_STEP_STATUSES).find_each do |step|
+          step.update!(status: "cancelled")
+        end
+        track.update!(status: "cancelled")
+      end
+    end
+
+    def emit_outbox(event_name, reason = nil)
+      OutboxEvent.create!(
+        tenant_id: tenant_id,
+        event_name: event_name,
+        record: self,
+        error_payload: reason
+      )
+    end
+  end
+end

data/app/models/approval_engine/approval_plan.rb

@@ -0,0 +1,60 @@
+module ApprovalEngine
+  # A read-only description of what a given event *would* trigger, produced by
+  # `RuleEvaluator.preview`. It writes nothing and resolves nothing eagerly — a
+  # UX/preview aid, not a contract (rules can change before the real run, so the
+  # authoritative routing still happens in `run_approval!`).
+  class ApprovalPlan
+    # One layer that would be created. Pure blueprint data — no DB rows.
+    PlannedStep = Struct.new(:name, :layer, :assigned_group, :approvals_required, keyword_init: true)
+
+    attr_reader :status, :template, :target, :reason
+
+    def initialize(status:, template:, target:, reason: nil)
+      @status   = status
+      @template = template
+      @target   = target
+      @reason   = reason
+    end
+
+    # An approval would be spawned.
+    def triggered?
+      status == :match
+    end
+
+    # No rule matched — taking the action needs no approval.
+    def no_approval_required?
+      status == :no_match
+    end
+
+    # A rule is malformed; the real run would quarantine. `reason` says why.
+    def error?
+      status == :error
+    end
+
+    # The layers that would be created, in order. Pure template data.
+    def steps
+      return [] unless template
+
+      template.template_steps.ordered.map do |tpl_step|
+        PlannedStep.new(
+          name: tpl_step.name,
+          layer: tpl_step.layer,
+          assigned_group: tpl_step.assigned_group,
+          approvals_required: tpl_step.approvals_required
+        )
+      end
+    end
+
+    # Best-effort, read-only resolution of who would be assigned to a planned
+    # step. Returns [] if the host resolver is unavailable or raises, so a
+    # preview never crashes on a host-side bug.
+    def actors_for(planned_step)
+      klass = ApprovalEngine.config.actor_class_constant
+      return [] unless klass.respond_to?(:resolve_approval_group)
+
+      Array(klass.resolve_approval_group(planned_step.assigned_group, target)).compact
+    rescue StandardError
+      []
+    end
+  end
+end

data/app/models/approval_engine/audit_log.rb

@@ -0,0 +1,28 @@
+module ApprovalEngine
+  # An append-only record of a single ledger event. Audit rows are write-once:
+  # they capture the *intended* actor (who the step was assigned to) alongside
+  # the *actual* actor (who acted, possibly a delegate), giving compliance teams
+  # a tamper-evident trail of every decision.
+  class AuditLog < ApplicationRecord
+    belongs_to :step, class_name: "ApprovalEngine::Step", foreign_key: "approval_engine_step_id"
+    belongs_to :intended_actor, polymorphic: true, optional: true
+    # Optional: a system event (e.g. `timed_out`/`expired`) has no human actor.
+    belongs_to :actual_actor, polymorphic: true, optional: true
+
+    validates :tenant_id, :event, presence: true
+
+    scope :for_tenant, ->(tenant_id) { where(tenant_id: tenant_id) }
+
+    # True when the acting actor differed from the assigned one — i.e. a
+    # delegate approved on someone's behalf. A system event (no actual actor) is
+    # never a proxy.
+    def by_proxy?
+      actual_actor_id.present? && intended_actor_id.present? && intended_actor != actual_actor
+    end
+
+    # The ledger never rewrites history.
+    def readonly?
+      persisted?
+    end
+  end
+end

data/app/models/approval_engine/consensus.rb

@@ -0,0 +1,37 @@
+module ApprovalEngine
+  # Value object for a layer's consensus condition. It parses the declarative
+  # `approvals_required` spec and computes how many approvals a group of a given
+  # size needs:
+  #
+  #   :any       -> 1
+  #   :all       -> everyone in the group
+  #   :majority  -> more than half
+  #   "60%"      -> that proportion of the group (at least 1)
+  #   2          -> an exact count
+  #
+  # Relative specs are resolved against the *live* group, so authors never have
+  # to know team sizes — "majority of whoever is on the team" just works, and
+  # adapts as members are added or drop out.
+  class Consensus
+    FORMAT = /\A([1-9][0-9]*%?|any|all|majority)\z/
+
+    def self.valid?(spec)
+      FORMAT.match?(spec.to_s)
+    end
+
+    def initialize(spec)
+      @spec = spec.to_s
+    end
+
+    # How many approvals are needed out of a group of `group_size`.
+    def required(group_size)
+      case @spec
+      when "any"      then 1
+      when "all"      then group_size
+      when "majority" then (group_size / 2) + 1
+      when /%\z/      then [ (group_size * @spec.to_i / 100.0).ceil, 1 ].max
+      else @spec.to_i
+      end
+    end
+  end
+end

data/app/models/approval_engine/delegation.rb

@@ -0,0 +1,34 @@
+module ApprovalEngine
+  # A time-bound proxy lease: while it is active, the delegatee may act on steps
+  # assigned to the delegator (e.g. covering approvals during a vacation). The
+  # ledger still records the delegator as the *intended* actor and the delegatee
+  # as the *actual* actor, so the proxy is always visible in the audit trail.
+  class Delegation < ApplicationRecord
+    belongs_to :delegator, polymorphic: true
+    belongs_to :delegatee, polymorphic: true
+
+    validates :tenant_id, presence: true
+    validates :starts_at, :ends_at, presence: true
+    validate :ends_after_start
+
+    scope :for_tenant, ->(tenant_id) { where(tenant_id: tenant_id) }
+
+    # Currently-effective delegations as of `at` (defaults to now).
+    scope :in_effect, ->(at = Time.current) { where(active: true).where(starts_at: ..at).where(ends_at: at..) }
+
+    # Active delegations *from* a given delegator, optionally tenant-scoped.
+    def self.active_for(delegator, tenant_id: nil, at: Time.current)
+      scope = in_effect(at).where(delegator: delegator)
+      tenant_id ? scope.for_tenant(tenant_id) : scope
+    end
+
+    private
+
+    def ends_after_start
+      return if starts_at.blank? || ends_at.blank?
+      return if ends_at > starts_at
+
+      errors.add(:ends_at, "must be after starts_at")
+    end
+  end
+end

data/app/models/approval_engine/history.rb

@@ -0,0 +1,62 @@
+module ApprovalEngine
+  # A read-only view of everything a record has gone through: every approval it
+  # spawned, the track/step tree beneath each, and a flat chronological
+  # timeline of the actions taken (with actors and comments).
+  #
+  # It assembles the data; *who* may see it and *how* it's rendered is the host's
+  # call — wrap it in your own authorization and UI.
+  #
+  #   history = invoice.approval_history
+  #   history.approvals   # => newest-first, tree preloaded (no N+1)
+  #   history.events      # => chronological audit entries across everything
+  class History
+    def self.for(record)
+      new(record)
+    end
+
+    def initialize(record)
+      @record = record
+    end
+
+    # Every approval for the record, newest first, with tracks, steps and
+    # their assigned actors eager-loaded so traversal doesn't fan out into N+1
+    # queries.
+    def approvals
+      @approvals ||= Approval.where(target: @record)
+                             .includes(tracks: { steps: :assigned_actor })
+                             .order(created_at: :desc)
+                             .to_a
+    end
+
+    def latest
+      approvals.first
+    end
+
+    def empty?
+      approvals.empty?
+    end
+
+    # The "what happened" narrative: every step action (approved / rejected /
+    # changes_requested) across all of this record's approvals and iterations,
+    # oldest first. Queried (and ordered + capped) in the database rather than by
+    # walking the whole tree in Ruby, with the polymorphic actors preloaded.
+    # Each entry is an AuditLog, so the host can read its event, actors (intended
+    # vs actual), comment, timestamp and step context.
+    def events(limit: 500)
+      AuditLog.where(approval_engine_step_id: step_ids)
+              .preload(:actual_actor, :intended_actor, step: :assigned_actor)
+              .order(:created_at)
+              .limit(limit)
+    end
+
+    private
+
+    # Step ids belonging to this record's approvals, as a subquery so the events
+    # query stays a single statement (no per-row joins, no eager-load surprises).
+    def step_ids
+      Step.joins(track: :approval)
+          .where(approval_engine_approvals: { target_type: @record.class.polymorphic_name, target_id: @record.id })
+          .select(:id)
+    end
+  end
+end

data/app/models/approval_engine/outbox_event.rb

@@ -0,0 +1,47 @@
+module ApprovalEngine
+  # A row in the transactional outbox. It is written in the *same* transaction
+  # as the state change that produced it, then relayed asynchronously — so a
+  # crashing mailer or a down payment API can never roll back an approval, and
+  # no side-effect is ever silently lost.
+  class OutboxEvent < ApplicationRecord
+    # `record` is always an engine row (Approval or Step, UUID-keyed), never a
+    # host record. The column is NOT NULL — every event is created with one — but
+    # `optional: true` relaxes the load-time check so an event whose record was
+    # destroyed before relay can be retired instead of poisoning the queue.
+    belongs_to :record, polymorphic: true, optional: true
+
+    validates :tenant_id, :event_name, presence: true
+
+    scope :unprocessed, -> { where(processed: false) }
+    # Dead letters: delivery retries were exhausted. Excluded from drain! so a
+    # permanently-failing callback isn't resurrected forever; surfaced here for
+    # ops to inspect and replay (clear failed_at to let drain! pick it up again).
+    scope :failed, -> { where.not(failed_at: nil) }
+
+    # Relay the event once the producing transaction has safely committed.
+    after_create_commit :enqueue_relay
+
+    # Safety net for events whose relay job was lost (e.g. the process died
+    # between commit and enqueue). Wire this to a periodic ActiveJob/cron.
+    # `older_than` skips freshly-created events whose relay is likely still
+    # in-flight, so draining never double-enqueues a healthy event; dead letters
+    # are skipped so exhausted poison events aren't retried in perpetuity.
+    def self.drain!(older_than: 1.minute, limit: 1000)
+      unprocessed.where(failed_at: nil)
+                 .where(created_at: ..older_than.ago)
+                 .order(:created_at).limit(limit).pluck(:id).each do |id|
+        ProcessOutboxJob.perform_later(id)
+      end
+    end
+
+    def mark_processed!
+      update!(processed: true, processed_at: Time.current, error_payload: nil, delivery_error: nil)
+    end
+
+    private
+
+    def enqueue_relay
+      ProcessOutboxJob.perform_later(id)
+    end
+  end
+end

data/app/models/approval_engine/step.rb

@@ -0,0 +1,271 @@
+module ApprovalEngine
+  # A single node in the immutable approval ledger.
+  #
+  # Steps move strictly forward through their lifecycle — they are never reset
+  # backwards. Requesting changes appends a fresh iteration instead (see
+  # IterationBuilder), preserving the historical truth of every attempt.
+  #
+  # The bang methods (#approve!, #reject!, #request_changes!) take a
+  # pessimistic lock, write an audit row, advance the surrounding track, and
+  # drop a transactional-outbox event — all in one transaction — so concurrent
+  # "Approve" clicks can never double-resolve a step.
+  class Step < ApplicationRecord
+    # Lifecycle. `waiting` steps belong to a future layer and are not yet
+    # actionable; they are activated to `pending` once the prior layer resolves.
+    STATUSES = %w[waiting pending approved rejected changes_requested expired cancelled].freeze
+    TERMINAL_STATUSES = %w[approved rejected changes_requested expired cancelled].freeze
+
+    # Allowed forward transitions. Anything else is rejected to keep the ledger
+    # append-only. `expired` is a distinct terminal state — a deadline lapse is
+    # never recorded as an approval or a human rejection.
+    TRANSITIONS = {
+      "waiting" => %w[pending cancelled],
+      "pending" => %w[approved rejected changes_requested expired cancelled]
+    }.freeze
+
+    belongs_to :track, class_name: "ApprovalEngine::Track", foreign_key: "approval_engine_track_id"
+    belongs_to :assigned_actor, polymorphic: true
+    has_many :audit_logs, class_name: "ApprovalEngine::AuditLog", foreign_key: "approval_engine_step_id", dependent: :destroy
+
+    has_one :approval, through: :track
+
+    validates :tenant_id, presence: true
+    validates :status, inclusion: { in: STATUSES }
+    validates :layer, :iteration, numericality: { greater_than: 0 }
+    validate :approvals_required_is_valid
+
+    before_update :guard_immutable_transition
+    before_save :stamp_timing
+
+    scope :waiting, -> { where(status: "waiting") }
+    scope :pending, -> { where(status: "pending") }
+    scope :approved, -> { where(status: "approved") }
+    scope :for_iteration, ->(iteration) { where(iteration: iteration) }
+    scope :for_layer, ->(layer) { where(layer: layer) }
+    scope :for_tenant, ->(tenant_id) { where(tenant_id: tenant_id) }
+    # Pending steps whose deadline has passed and that haven't fired yet — the
+    # set the timeout sweep acts on. Each step times out at most once.
+    scope :overdue, ->(as_of = Time.current) {
+      pending.where(timed_out_at: nil).where.not(timeout_at: nil).where("timeout_at <= ?", as_of)
+    }
+
+    # An approver's inbox: pending steps the actor may act on — assigned to them
+    # directly *plus* those they cover via an active delegation. The scope form
+    # of `#actionable_by?`. Chain `.count`, `.order`, pagination, etc.
+    scope :actionable_by, ->(actor, tenant: nil) {
+      type = actor.class.polymorphic_name
+      delegated_ids = Delegation.in_effect.where(delegatee: actor, delegator_type: type).pluck(:delegator_id)
+      rel = pending.where(assigned_actor_type: type, assigned_actor_id: [ actor.id, *delegated_ids ])
+      tenant ? rel.for_tenant(tenant) : rel
+    }
+
+    # True when `actor` may act on this step — either the assigned actor or one
+    # of their active delegates. Authorization itself stays with the host app;
+    # this is the helper they reason about.
+    def actionable_by?(actor)
+      return false unless pending?
+      return true if assigned_actor == actor
+
+      Delegation.active_for(assigned_actor, tenant_id: tenant_id).exists?(delegatee: actor)
+    end
+
+    STATUSES.each do |state|
+      define_method(:"#{state}?") { status == state }
+    end
+
+    def terminal?
+      TERMINAL_STATUSES.include?(status)
+    end
+
+    # The host record this step is ultimately approving (e.g. the Invoice).
+    # Preload an inbox with `.includes(track: { approval: :target })`.
+    def target
+      track&.approval&.target
+    end
+
+    # Seconds a human took to decide this step — from when it became actionable
+    # (`activated_at`) to when it was approved/rejected/changes-requested
+    # (`decided_at`). nil until decided (or for cancelled steps, never decided).
+    def time_to_decision
+      return unless activated_at && decided_at
+
+      decided_at - activated_at
+    end
+
+    # Seconds this step has been (or was) actionable: `now - activated_at` while
+    # pending, `decided_at - activated_at` once resolved. nil before activation.
+    # Useful for "how long has this been sitting in someone's queue?".
+    def waiting_for
+      return unless activated_at
+
+      (decided_at || Time.current) - activated_at
+    end
+
+    def approve!(by:, comment: nil)
+      transition!(to: "approved", event: "approved", by: by, comment: comment) do
+        track.advance!(self)
+      end
+    end
+
+    def reject!(by:, comment: nil)
+      transition!(to: "rejected", event: "rejected", by: by, comment: comment) do
+        track.advance!(self)
+      end
+    end
+
+    def request_changes!(by:, comment: nil)
+      transition!(to: "changes_requested", event: "changes_requested", by: by, comment: comment) do
+        track.advance_after_changes_requested!(self)
+      end
+    end
+
+    # The deadline passed while this step was still pending. This is a *signal*,
+    # not a verdict: it records a `timed_out` event and fires the host's
+    # `on_step_timeout` callback, but does NOT decide the step — silence is never
+    # consent. The host chooses the reaction (`expire!`, escalate, remind). Fires
+    # at most once; idempotent under concurrent sweeps.
+    def time_out!
+      track.approval.with_lock do
+        reload
+        return self unless pending? && timed_out_at.nil?
+
+        update!(timed_out_at: Time.current)
+        record_audit(event: "timed_out", by: nil, comment: nil)
+        emit_outbox("step.timed_out")
+      end
+
+      self
+    end
+
+    # Honest denial when an approver never acted in time: the step becomes
+    # `expired` (a distinct terminal state — never "approved", never a human
+    # "rejected"), with no human actor on the ledger. Resolves the surrounding
+    # layer consensus-aware, like a reject. Idempotent if already resolved.
+    def expire!(comment: nil)
+      return self if terminal?
+
+      transition!(to: "expired", event: "expired", by: nil, comment: comment) do
+        track.advance!(self)
+      end
+    rescue ActiveRecord::RecordInvalid
+      # A human decided in the window between the guard above and the lock inside
+      # transition!. Their decision stands; expire! stays the no-op it advertises.
+      raise unless reload.terminal?
+
+      self
+    end
+
+    # Hand a stuck step to another actor without restarting the flow — the
+    # escalation path for an unresponsive approver (e.g. from on_step_timeout).
+    # Records the reassignment (old assignee as intended, reassigner as actual)
+    # and keeps the step pending in its layer. Must be pending.
+    def reassign!(to:, by: nil, comment: nil)
+      track.approval.with_lock do
+        reload
+        unless pending?
+          errors.add(:status, "must be pending to reassign (was #{status})")
+          raise ActiveRecord::RecordInvalid, self
+        end
+
+        record_audit(event: "reassigned", by: by, comment: comment)
+        update!(assigned_actor: to)
+        emit_outbox("step.reassigned")
+      end
+      self
+    end
+
+    # Fire the timeout signal for every overdue step. Safe to run as often as you
+    # like (each step times out once); scope to a tenant in multi-tenant cron.
+    # Returns the number swept. One step raising (lock contention, a concurrently
+    # destroyed approval) is logged and skipped, so it can't starve the rest of
+    # the batch — the next sweep retries it (idempotent). TimeoutSweepJob wraps
+    # this for background runs.
+    def self.sweep_timeouts!(tenant_id: nil)
+      scope = tenant_id ? overdue.for_tenant(tenant_id) : overdue
+      swept = 0
+      scope.find_each do |step|
+        step.time_out!
+        swept += 1
+      rescue StandardError => e
+        Rails.logger&.warn("[ApprovalEngine] timeout sweep skipped step #{step.id}: #{e.class}: #{e.message}")
+      end
+      swept
+    end
+
+    private
+
+    # The shared transition pipeline. We lock the *approval* — the aggregate
+    # root — before touching anything, so every transition within an approval is
+    # fully serialized. That makes double-approvals impossible and lets a layer
+    # safely cancel its sibling steps without deadlocking against them.
+    #
+    # The yielded block advances the track/approval synchronously, so the
+    # ledger is always internally consistent by the time the transaction
+    # commits. External side-effects are deferred to the transactional outbox.
+    def transition!(to:, event:, by:, comment:)
+      track.approval.with_lock do
+        reload
+
+        unless pending?
+          errors.add(:status, "must be pending to be #{event} (was #{status})")
+          raise ActiveRecord::RecordInvalid, self
+        end
+
+        update!(status: to)
+        record_audit(event: event, by: by, comment: comment)
+        yield if block_given?
+        emit_outbox("step.#{event}")
+      end
+
+      self
+    end
+
+    def record_audit(event:, by:, comment:)
+      audit_logs.create!(
+        tenant_id: tenant_id,
+        event: event,
+        intended_actor: assigned_actor,
+        actual_actor: by,
+        comment: comment
+      )
+    end
+
+    def emit_outbox(event_name)
+      OutboxEvent.create!(tenant_id: tenant_id, event_name: event_name, record: self)
+    end
+
+    def guard_immutable_transition
+      return unless will_save_change_to_status?
+
+      from, to = status_change_to_be_saved
+      allowed = TRANSITIONS.fetch(from, [])
+      return if allowed.include?(to)
+
+      errors.add(:status, "cannot transition from #{from} to #{to}")
+      throw :abort
+    end
+
+    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
+
+    # Stamp the cycle-time facts wherever a step's status changes — at build, on
+    # waiting->pending activation, and on a human decision — so latency reporting
+    # never has to re-derive timing from the audit log. `||=` keeps the first
+    # value, so re-saves don't move the clock. Cancelled steps were never decided,
+    # so they stay decided_at: nil.
+    DECISION_STATUSES = %w[approved rejected changes_requested].freeze
+
+    def stamp_timing
+      if status == "pending"
+        self.activated_at ||= Time.current
+        # Deadline = actionable + the SLA window. `||=` lets the host set an
+        # absolute `timeout_at` directly (e.g. computed against business hours).
+        self.timeout_at ||= activated_at + timeout_after if timeout_after
+      end
+      self.decided_at ||= Time.current if DECISION_STATUSES.include?(status)
+    end
+  end
+end