approval_engine 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5d2b7c82e4d4b1fe2b40cdc8e70425049e1b08ba46544f1d220c9c85c205644b
+  data.tar.gz: 66ca2e891a150af9148a54277d7d47dee9599732e69223e10c18d63c6a665460
+SHA512:
+  metadata.gz: 7b953537aeae8f200b23ab5d92956a8aae8742c837891d66684ae901268788b2612255b3647a5695c674dd08d0a1a774574afc0df651139fd23b02a1b60f837f
+  data.tar.gz: 119a6e6869463e1a97515557882e11ead9c818d2d2e847f2ceb36ed6ae85ae772c9638ca6cc2bfb246999843f44754f988eec1ececb89f6815d79b642301ec8a

data/CHANGELOG.md

@@ -0,0 +1,138 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-06-17
+
+First public release. The API below is stable.
+
+### Added
+
+- Immutable, append-only approval ledger (`Approval` → `Track` → `Step`) with
+  forward-only state transitions and write-once `AuditLog` rows.
+- `has_approvals` model macro and the `exposes_for_approval`
+  anti-corruption DSL for whitelisting attributes to the rules engine.
+- Dynamic, tenant-scoped routing via JSON Logic (`shiny_json_logic`), with
+  fail-closed quarantine on malformed rules.
+- `preview_approval(event:)` — a side-effect-free dry run that returns
+  a `ApprovalPlan` describing what an action *would* trigger (which template,
+  steps, and assignees), so hosts can warn users before they commit.
+- `Step.actionable_by(actor)` — an approver's inbox scope: pending steps assigned
+  to them plus those they cover via an active delegation. Plus `Step#target` to
+  show what each step is approving. Powers a "my pending approvals" UI.
+- Cycle-time facts on every step: `activated_at` (became actionable) and
+  `decided_at` (human resolved it), stamped automatically — with `step.waiting_for`
+  / `step.time_to_decision` readers and `approval.current_bottleneck` (the
+  longest-pending step). The dashboard shows a time-in-step column. SLA
+  thresholds, reminders, and escalation stay the host's to define.
+- Per-step timeouts: `timeout_after` on a template step (the clock starts when the
+  step becomes actionable), swept by `ApprovalEngine::TimeoutSweepJob` /
+  `Step.sweep_timeouts!`, surfaced via the `on_step_timeout(step)` host callback. A
+  timeout fires once and never decides the step — `step.expire!` is the honest
+  terminal denial (a distinct `expired` state, recorded with no actual actor).
+  **ApprovalEngine never auto-approves: silence is not consent.**
+- `record.approval_history` — a read-only `History` view of everything a record
+  has gone through: all approvals (newest first, eager-loaded), and a
+  chronological timeline of step actions with actors and comments. The host
+  decides who may see it.
+- `Model.approval_event_name(:create)` returns the conventional auto-trigger
+  event name, so rules can reference it instead of a hand-typed literal that
+  could silently drift (raises on an unknown lifecycle).
+- Trigger approvals on any event/transition — `run_approval!(event:)`
+  accepts any event name, and `has_approvals(on: [:create, :update])`
+  auto-routes on update too (gated per-lifecycle via `trigger_approval?`).
+- `approval_candidates(event:)` lists every matching approval (not just the
+  top-priority one), and `run_approval!(templates:)` starts a chosen
+  one (or several, as parallel tracks) — so a user can decide instead of the
+  engine auto-routing by priority.
+- `approval.trigger_rule` — provenance: the `TriggerRule` that auto-routed an
+  approval (nil for a manual `run_approval!(templates:)` start), captured at
+  build time so it stays stable even if the rule is edited or retired later.
+- Consensus per layer via `approvals_required`: `:any`, `:all`, `:majority`, a
+  percentage like `"60%"`, or a fixed count — resolved against the live group
+  size, so authors express policy without hard-coding headcount.
+- `track.layer_tally(layer)` — a public read of a layer's live consensus tally
+  (`required` / `approved` / `rejected` / `pending` / `waiting` / `group_size` /
+  `outcome`), so a UI can show "N of M approved" and *why* a layer is
+  met/failed/undecided without re-deriving the consensus math the engine owns. A
+  layer that hasn't opened yet (all steps still `waiting`) reads as `:undecided`,
+  not `:failed` — `waiting` steps count as still-reachable approvals.
+- Consensus-aware rejection: a reject respects the layer's policy, failing the
+  approval as soon as the required approvals become unreachable (one no for
+  `:all`; every actor for `:any`; too few voters left to reach a count) rather
+  than vetoing on the first no. A failed layer never advances.
+- Sequential multi-layer tracks with automatic layer activation.
+- Scatter-gather parallel tracks via `ApprovalBuilder.build_parallel!` — one
+  approval gathers across several simultaneous tracks. The gather is
+  consensus-aware: `approvals_required` (on `build_parallel!` /
+  `run_approval!(templates:, approvals_required:)`) says how many tracks must
+  approve — `:all` by default (unanimity, the historical behaviour), but also
+  `:any` / `:majority` / `"60%"` / a fixed count, so "2 of 3 departments must
+  sign off" is expressible. One track rejecting no longer vetoes a still-reachable
+  gather; a count that exceeds the number of tracks raises at build time.
+- Append-only "approval changes" cycles (`request_changes!`) that send an approval
+  back for a fresh iteration while preserving history.
+- `approval.cancel!(reason:)` — withdraw an in-flight approval: the third terminal
+  outcome beside approved and rejected, for when the thing being approved is voided
+  or retracted. Cancels open tracks/steps, keeps history, fires `after_cancelled`.
+- `step.reassign!(to:, by:, comment:)` — hand a stuck step to another actor without
+  restarting the flow (the escalation partner to timeouts), recorded on the ledger
+  and firing `after_step_reassigned`.
+- `ApprovalEngine::Error` base class for every error the engine raises
+  (`BuilderError`, `EvaluationError` reparented), so a host can rescue one type.
+- Time-bound delegation with intended-vs-actual actor auditing.
+- Transactional outbox that relays host callbacks and
+  `ActiveSupport::Notifications` asynchronously via ActiveJob.
+- Pessimistic, approval-scoped locking that makes double-approvals impossible.
+- `approval_engine:install` and `approval_engine:views` generators.
+- A read-only, mountable ops dashboard.
+
+### Onboarding & hygiene
+
+- Reworked the README golden path (verified end-to-end): a "What you must
+  provide" checklist, a self-contained quickstart, a mandatory `preview ...
+  .triggered?` verification step, and loud warnings about the silent-failure
+  traps (unset tenant, `event_name` mismatch, `draft` templates, unexposed vars).
+- Added a JSON Logic "Authoring rules" cookbook section (and/or/in/equality
+  examples) and rewrote the install generator's POST_INSTALL into a warned,
+  ordered checklist.
+- Removed the redundant `ApprovalEngine::Web` alias (mount `ApprovalEngine::Engine`),
+  pruned generator dead code (unused mailer, layout, rake stub), normalized the
+  blueprint migration, and retired the stale handoff doc.
+
+### Hardened
+
+- Eliminated N+1s in the dashboard (approval list track-counts, detail-page
+  actors) and `approval_history`; `History#events` is now a single bounded,
+  DB-ordered query with preloaded actors (proven N+1-free by query-count tests).
+- Added hot-path indexes: track `(request_id, status)`, step layer-consensus
+  `(branch_id, iteration, layer, status)`, approval `(target, created_at)`,
+  audit-log `(tenant_id, created_at)`, trigger-rule resolution, a delegation
+  time-window composite, and a partial index for the outbox drain.
+- DB `CHECK` constrains `approvals_required` to the accepted vocabulary on both
+  steps and template-steps (a raw insert can't store a spec the engine can't
+  resolve).
+- `drain!` is bounded (age + limit) so a backlog can't enqueue everything at once.
+- Outbox relay now holds its row lock for the whole transaction (concurrent
+  workers can't double-deliver), retries with backoff (`retry_on`), retires
+  events whose target was purged instead of looping forever, and `drain!` skips
+  in-flight events. Host callbacks are at-least-once and unordered — make them
+  idempotent. Exhausted retries now dead-letter the row (`failed_at`) so `drain!`
+  can't resurrect a poison event forever; delivery errors are recorded in a
+  separate `delivery_error` column so a retry never clobbers the semantic reason
+  (`error_payload`) the host callback reads; and the timeout sweep isolates a
+  single step's failure so it can't starve the rest of the batch.
+- Database `CHECK` constraints enforce every status and `approvals_required`
+  value, so the ledger can't be corrupted by a raw write — not just Ruby
+  validations.
+- Consensus/layer edge cases that could silently strand an approval in `pending`
+  are now handled: non-contiguous layers activate the next existing layer, a
+  required count exceeding the resolved group raises at build time, and `:all`
+  excludes cancelled siblings from its denominator.
+- A misconfigured `actor_class` now raises an actionable `BuilderError` naming
+  the setting, instead of a raw `NameError`.
+
+[1.0.0]: https://github.com/Harry-kp/approval_engine/releases/tag/v1.0.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2026 Harry-kp
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,249 @@
+# ApprovalEngine
+
+[![CI](https://github.com/Harry-kp/approval_engine/actions/workflows/ci.yml/badge.svg)](https://github.com/Harry-kp/approval_engine/actions/workflows/ci.yml)
+![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.1-CC342D)
+![Rails](https://img.shields.io/badge/rails-%3E%3D%207.0.8-D30001)
+![License: MIT](https://img.shields.io/badge/license-MIT-blue)
+
+Multi-tenant, immutable-ledger human approval flows for Rails.
+
+Use it when a manager approves an invoice, then a CFO. Or Legal and IT
+in parallel. Or "any two of five reviewers." ApprovalEngine supplies the
+generic machinery: an append-only ledger, race-safe transitions, runtime
+routing rules, and async side-effects. You decide what gets approved, who
+approves, and what happens next.
+
+## Is this for you?
+
+Use it when you have:
+
+- Multi-step, human-in-the-loop approvals, sequential or parallel
+- Routing rules that admins change at runtime, without a deploy
+- A need to audit who approved what, when, and on whose behalf
+- Concurrency that must never double-approve
+
+Look elsewhere when:
+
+- You just need a boolean `approved` flag. A column and a method are simpler.
+- You need a state machine for non-approval domains. Try
+  [AASM](https://github.com/aasm/aasm) or
+  [state_machines](https://github.com/state-machines/state_machines).
+- You're not on PostgreSQL. The routing engine needs `jsonb` and `gin`.
+
+## Installation
+
+Add this line to your application's **Gemfile**:
+
+```ruby
+gem "approval_engine"
+```
+
+And then execute:
+
+```sh
+bundle install
+rails generate approval_engine:install
+rails db:migrate
+```
+
+The generator copies migrations and an initializer, and prints next steps.
+
+## Quickstart
+
+Teach your actor class to resolve approval groups. The engine creates one
+step per returned record. `target` is the record being approved (e.g. the
+Invoice); this example ignores it, but you can use it for record-scoped
+groups like "this invoice's department head".
+
+```ruby
+class User < ApplicationRecord
+  def self.resolve_approval_group(group_name, target)
+    where(role: group_name) # `target` available for record-scoped resolution
+  end
+end
+```
+
+Arm a model and declare the attributes the rules engine may read.
+
+```ruby
+class Invoice < ApplicationRecord
+  has_approvals
+
+  exposes_for_approval do
+    attribute :amount, type: :decimal
+  end
+
+  def after_approved
+    PaymentService.disburse_funds!(self)
+  end
+end
+```
+
+Define a template, its ordered steps, and the rule that triggers it.
+
+```ruby
+template = ApprovalEngine::TrackTemplate.create!(
+  tenant_id: "acme", name: "High-value invoice", status: "active"
+)
+template.template_steps.create!(name: "Manager", layer: 1, assigned_group: "manager")
+template.template_steps.create!(name: "CFO", layer: 2, assigned_group: "cfo")
+template.trigger_rules.create!(
+  tenant_id: "acme", event_name: "invoice.created",
+  condition: { ">" => [{ "var" => "amount" }, 10_000] }
+)
+```
+
+Trigger a run.
+
+```ruby
+invoice = Invoice.create!(amount: 20_000)
+invoice.run_approval!(event: "invoice.created", tenant_id: "acme")
+```
+
+Verify it routed before going further.
+
+```ruby
+invoice.preview_approval(event: "invoice.created", tenant_id: "acme").triggered?
+# => true
+```
+
+Act on a step. `actionable_by` is the approver's inbox, including delegations.
+
+```ruby
+ApprovalEngine::Step.actionable_by(current_user).first.approve!(by: current_user)
+```
+
+### Gotchas
+
+This gem fails closed and silent when misconfigured. If a run doesn't
+trigger, `preview_approval(...).triggered?` tells you why. Check:
+
+- The rule's `event_name` matches the event you fire.
+- The template `status` is `"active"`. Draft templates never fire.
+- Every attribute a rule reads is declared in `exposes_for_approval`.
+- `config.current_tenant_method` is set. Until then, auto-routing on
+  create is a no-op, so pass `tenant_id:` explicitly.
+
+## See it live
+
+Run the demo against a clone of this repo, not your own app. It needs
+PostgreSQL running.
+
+```sh
+bin/demo
+# seeds sample data and boots the dashboard at
+# http://localhost:3000/approval_engine
+```
+
+Or explore the API in a console preloaded with sample data.
+
+```sh
+bin/console
+>> Rails.application.load_seed
+>> ApprovalEngine::Step.pending.first.approve!(by: User.find_by(role: "manager"))
+```
+
+The mounted dashboard lists every approval, filters by status, and drills
+into tracks, steps, and the full audit trail. It is read-only, with
+bundled styling. It has no auth of its own — when you mount it in a real app,
+wrap it in a `constraints`/authenticated route ([recipe](docs/COOKBOOK.md#ui--monitoring)).
+
+## Configuration
+
+```ruby
+# config/initializers/approval_engine.rb
+ApprovalEngine.configure do |config|
+  config.actor_class           = "User"                 # who approves
+  config.current_tenant_method = -> { Current.account } # anything with #id
+  config.outbox_queue          = :default               # ActiveJob queue for side-effects
+  config.raise_on_rule_errors  = false                  # fail closed in production
+end
+```
+
+`current_tenant_method` defaults to `nil`. While it is nil, auto-routing
+on create silently no-ops, since the engine cannot scope the rules.
+Single-tenant apps can return a constant, e.g.
+`-> { Struct.new(:id).new("default") }`.
+
+No Redis or Sidekiq required. Side-effects run through ActiveJob, so
+SolidQueue, Sidekiq, or the async adapter all work.
+
+## Core concepts
+
+| Term | What it is |
+| --- | --- |
+| Template | The reusable blueprint: ordered layers of steps with consensus rules |
+| Trigger rule | A tenant-scoped JSON Logic condition that selects a template for an event |
+| Approval | One run: a host record fanned out into one or more parallel tracks |
+| Track | One parallel path of layered steps within an approval |
+| Step | One approval slot in the immutable ledger (`approve!` / `reject!` / `request_changes!`) |
+| Consensus | How many approvals a layer needs: `approvals_required` — `:any`, `:all`, `:majority`, a percentage like `"60%"`, or a count |
+
+Every run is `Approval -> Track -> Step`, even the one-approver case.
+A single-track run is an approval with one track, not a special path.
+You never build that chain by hand: start a run with
+`run_approval!` and act on a step with `step.approve!`. The
+layers surface only when you need them, such as parallel tracks or the
+dashboard. For a single-track approval, `approval.track` and
+`approval.step` read it back without `.first`.
+
+`approvals_required` is one idea used at two levels: within a layer (how many of
+its steps), and across the parallel tracks of a scatter-gather (how many tracks
+must approve — `:all` by default). Beyond the happy path, an approval can be
+withdrawn (`approval.cancel!`) and a stuck step escalated (`step.reassign!`).
+
+**Reacting to outcomes** — define any of these on your model and the engine
+calls them (via the outbox, at-least-once and unordered): `after_approved`,
+`after_rejected(reason)`, `after_cancelled(reason)`, `on_quarantined(reason)`,
+`after_step_approved/rejected/changes_requested/expired/reassigned(step)`,
+`on_step_timeout(step)`. Or subscribe to the matching `approval_engine.*`
+[notifications](docs/COOKBOOK.md#notify-another-system-without-coupling-to-my-model).
+
+## Cookbook
+
+See **[docs/COOKBOOK.md](docs/COOKBOOK.md)** for copy-paste recipes
+covering every supported case, from "any two of five reviewers" to "Legal
+and IT in parallel" to delegation and requesting changes.
+
+## How it works
+
+| Concern | Mechanism |
+| --- | --- |
+| Auditability | Append-only `Step` ledger; requesting changes appends an iteration instead of editing history |
+| Concurrency | Approval-scoped pessimistic lock around every transition, so no double-approvals |
+| Routing | JSON Logic ASTs in `jsonb`, evaluated by [`shiny_json_logic`](https://rubygems.org/gems/shiny_json_logic) |
+| Side-effects | Transactional outbox relayed by ActiveJob, so a down API never rolls back an approval |
+| Safety | A malformed rule quarantines the approval instead of raising |
+
+A missing attribute is a clean non-match, since JSON Logic treats it as
+`false`, so the approval just doesn’t start. Only a malformed rule, such
+as an unknown operator, quarantines. The approval never crashes either
+way. Set `config.raise_on_rule_errors = true` to surface errors loudly.
+
+For the full design — the model hierarchy, the consensus/rework model, and why
+the outbox exists — see **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)**.
+
+## Development
+
+ApprovalEngine needs Ruby 3.1+ and PostgreSQL.
+
+```sh
+bin/setup
+bin/rails app:test
+bundle exec rubocop
+```
+
+Point at any Postgres with `DATABASE_URL` if you're not on the default
+socket. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.
+
+## Contributing
+
+Bug reports and pull approvals are welcome on GitHub at
+https://github.com/Harry-kp/approval_engine. Please read
+[CONTRIBUTING.md](CONTRIBUTING.md) and our
+[Code of Conduct](CODE_OF_CONDUCT.md).
+
+## License
+
+Available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).

data/app/controllers/approval_engine/application_controller.rb

@@ -0,0 +1,10 @@
+module ApprovalEngine
+  # Base controller for the mounted ops dashboard. It deliberately inherits from
+  # ActionController::Base (not the host's ApplicationController) so the
+  # dashboard is self-contained; wrap the mount in your own auth constraint to
+  # protect it.
+  class ApplicationController < ActionController::Base
+    protect_from_forgery with: :exception
+    layout "approval_engine/dashboard"
+  end
+end

data/app/controllers/approval_engine/approvals_controller.rb

@@ -0,0 +1,29 @@
+module ApprovalEngine
+  # The dashboard's approval list and detail views. Read-only by design — its
+  # job is to surface stuck, quarantined and in-flight work without anyone
+  # writing SQL, not to act on it.
+  class ApprovalsController < ApplicationController
+    PAGE_LIMIT = 100
+
+    def index
+      @status = params[:status].presence
+      @counts = Approval.group(:status).count
+      scope = Approval.all.order(created_at: :desc)
+      scope = scope.where(status: @status) if @status
+      @approvals = scope.limit(PAGE_LIMIT).to_a
+      @total = scope.count
+      # One grouped query for all the row counts, instead of N `.tracks.size`.
+      @track_counts = Track.where(approval_engine_approval_id: @approvals.map(&:id))
+                             .group(:approval_engine_approval_id).count
+    end
+
+    def show
+      # Preload the whole tree *including* the polymorphic actors the view renders
+      # (assigned actor, and each audit log's actual/intended actor) so the page
+      # is a fixed handful of queries regardless of how many steps it has.
+      @approval = Approval.includes(
+        tracks: { steps: [ :assigned_actor, { audit_logs: %i[actual_actor intended_actor] } ] }
+      ).find(params[:id])
+    end
+  end
+end

data/app/helpers/approval_engine/application_helper.rb

@@ -0,0 +1,27 @@
+module ApprovalEngine
+  module ApplicationHelper
+    STATUS_TONES = {
+      "pending" => "is-pending", "waiting" => "is-waiting",
+      "approved" => "is-approved", "rejected" => "is-rejected",
+      "changes_requested" => "is-changes-requested", "cancelled" => "is-cancelled",
+      "quarantined" => "is-quarantined"
+    }.freeze
+
+    def status_badge(status)
+      tag.span(status.to_s.tr("_", " "), class: "ae-badge #{STATUS_TONES.fetch(status.to_s, "is-pending")}")
+    end
+
+    def actor_label(actor)
+      return "—" if actor.nil?
+
+      name = actor.try(:name) || actor.try(:email) || actor.try(:to_s)
+      "#{actor.class.name}##{actor.id} (#{name})"
+    end
+
+    def target_label(target)
+      return "—" if target.nil?
+
+      "#{target.class.name}##{target.id}"
+    end
+  end
+end

data/app/jobs/approval_engine/application_job.rb

@@ -0,0 +1,4 @@
+module ApprovalEngine
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/jobs/approval_engine/process_outbox_job.rb

@@ -0,0 +1,100 @@
+module ApprovalEngine
+  # Relays one outbox event to the outside world. Core ledger state is already
+  # settled by the time this runs (transitions advance synchronously), so the
+  # job only fires *side-effects*: optional host callbacks and an
+  # ActiveSupport::Notifications instrumentation hook.
+  #
+  # Delivery is *at-least-once* (host callbacks may run more than once on a
+  # redelivery, so they MUST be idempotent) and *unordered* (sibling events for
+  # one record aren't sequenced — don't assume after_step_approved precedes
+  # after_approved). The row is locked for the whole unit of work so two workers
+  # can't both deliver it. Retries are bounded; an exhausted event is dead-lettered
+  # (failed_at set) rather than retried forever.
+  class ProcessOutboxJob < ApplicationJob
+    # Read the queue lazily so the host isn't forced onto a queue name we picked.
+    queue_as { ApprovalEngine.config.outbox_queue }
+
+    # Don't depend on the host's adapter happening to retry: back off and retry
+    # here. When retries are exhausted, dead-letter the row (drain! then skips it)
+    # instead of re-raising into the host queue forever.
+    retry_on StandardError, wait: :polynomially_longer, attempts: 8 do |job, error|
+      id = job.arguments.first
+      OutboxEvent.where(id: id).update_all(failed_at: Time.current, delivery_error: job.class.format_error(error), updated_at: Time.current)
+    end
+    discard_on ActiveJob::DeserializationError
+
+    def perform(outbox_event_id)
+      # The lock is held for the whole transaction, so a concurrent worker (or a
+      # drain! pass) blocks here and then sees `processed` — never double-delivers.
+      OutboxEvent.transaction do
+        event = OutboxEvent.unprocessed.lock.find_by(id: outbox_event_id)
+        next unless event # already processed, or its record was purged
+
+        deliver(event)
+        event.mark_processed!
+      end
+    rescue => e
+      # Record the delivery failure (in its own column, so a retry never clobbers
+      # the semantic error_payload the host callback reads) and re-raise to retry.
+      OutboxEvent.where(id: outbox_event_id).update_all(delivery_error: self.class.format_error(e), updated_at: Time.current)
+      raise
+    end
+
+    private
+
+    def deliver(event)
+      run_host_callbacks(event)
+      broadcast_notification(event)
+    end
+
+    # Invoke the matching host callback if the target model chose to define one.
+    # The engine never requires these — they are pure convention-over-config.
+    def run_host_callbacks(event)
+      record = event.record
+      target = target_for(record)
+      return unless target
+
+      case event.event_name
+      when "step.approved"             then try_call(target, :after_step_approved, record)
+      when "step.rejected"             then try_call(target, :after_step_rejected, record)
+      when "step.changes_requested"    then try_call(target, :after_step_changes_requested, record)
+      when "step.timed_out"            then try_call(target, :on_step_timeout, record)
+      when "step.expired"              then try_call(target, :after_step_expired, record)
+      when "step.reassigned"           then try_call(target, :after_step_reassigned, record)
+      when "approval.approved"         then try_call(target, :after_approved)
+      when "approval.rejected"         then try_call(target, :after_rejected, event.error_payload)
+      when "approval.cancelled"        then try_call(target, :after_cancelled, event.error_payload)
+      when "approval.quarantined"      then try_call(target, :on_quarantined, event.error_payload)
+      end
+    end
+
+    # Native pub/sub for hosts who prefer subscribers over callbacks:
+    #   ActiveSupport::Notifications.subscribe("approval_engine.approval.approved") { ... }
+    def broadcast_notification(event)
+      record = event.record
+      ActiveSupport::Notifications.instrument(
+        "approval_engine.#{event.event_name}",
+        record: record,
+        target: target_for(record),
+        tenant_id: event.tenant_id
+      )
+    end
+
+    def target_for(record)
+      case record
+      when Approval then record.target
+      when Step     then record.approval&.target
+      end
+    end
+
+    def try_call(target, method_name, *args)
+      target.public_send(method_name, *args) if target.respond_to?(method_name)
+    end
+
+    # Class method so the retry-exhausted block (which runs without a job
+    # instance receiver) can reuse it.
+    def self.format_error(error)
+      "#{error.class}: #{error.message}\n#{Array(error.backtrace).first(5).join("\n")}"
+    end
+  end
+end

data/app/jobs/approval_engine/timeout_sweep_job.rb

@@ -0,0 +1,19 @@
+module ApprovalEngine
+  # Periodic safety net that fires the timeout signal for every step whose
+  # deadline has passed. Schedule it with whatever recurring mechanism you
+  # already run (solid_queue recurring tasks, sidekiq-cron, the `whenever` gem,
+  # a Kubernetes CronJob hitting a rake task, ...):
+  #
+  #   ApprovalEngine::TimeoutSweepJob.perform_later              # all tenants
+  #   ApprovalEngine::TimeoutSweepJob.perform_later(tenant_id: account.id)
+  #
+  # Idempotent: each step times out at most once, so running it more often only
+  # makes timeouts fire sooner — it never double-fires.
+  class TimeoutSweepJob < ApplicationJob
+    queue_as { ApprovalEngine.config.outbox_queue }
+
+    def perform(tenant_id: nil)
+      Step.sweep_timeouts!(tenant_id: tenant_id)
+    end
+  end
+end

data/app/models/approval_engine/application_record.rb

@@ -0,0 +1,5 @@
+module ApprovalEngine
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end