approval_engine 1.0.0

data/app/services/approval_engine/rule_evaluator.rb

@@ -0,0 +1,119 @@
+require "shiny_json_logic"
+
+module ApprovalEngine
+  # Resolves which track (if any) a host event should spawn by evaluating
+  # tenant-scoped JSON Logic rules against a flat payload.
+  #
+  # The payload is produced by the host model's `exposes_for_approval` DSL, so
+  # the engine never reaches into the host's domain directly — it only sees the
+  # whitelisted attributes it was handed.
+  #
+  #   ApprovalEngine::RuleEvaluator.call(
+  #     event_name: "invoice.created",
+  #     tenant_id:  account.id,
+  #     target:     invoice,
+  #     payload:    invoice.serialize_for_approval
+  #   )
+  #
+  # `call` returns the spawned Approval, the quarantine Approval on a rule
+  # failure, or nil when no rule matched. `preview` runs the identical matching
+  # logic but writes nothing — see ApprovalPlan.
+  class RuleEvaluator
+    class EvaluationError < ApprovalEngine::Error; end
+
+    def self.call(event_name:, tenant_id:, target:, payload:)
+      new(event_name: event_name, tenant_id: tenant_id, target: target, payload: payload).call
+    end
+
+    # Side-effect-free dry run: what *would* this event trigger? Writes nothing,
+    # never quarantines, never raises. Returns an ApprovalPlan.
+    def self.preview(event_name:, tenant_id:, target:, payload:)
+      new(event_name: event_name, tenant_id: tenant_id, target: target, payload: payload).preview
+    end
+
+    # Side-effect-free: *every* rule that matches, in priority order, so the host
+    # can let a user choose which to trigger instead of auto-picking the top one.
+    # Returns an array of ApprovalPlan. Broken rules are skipped, not surfaced.
+    def self.candidates(event_name:, tenant_id:, target:, payload:)
+      new(event_name: event_name, tenant_id: tenant_id, target: target, payload: payload).candidates
+    end
+
+    def initialize(event_name:, tenant_id:, target:, payload:)
+      @event_name = event_name
+      @tenant_id  = tenant_id
+      @target     = target
+      @payload    = payload
+    end
+
+    def call
+      status, rule = find_match
+      case status
+      when :match
+        ApprovalBuilder.build!(template: rule.track_template, target: target, event_name: event_name, trigger_rule: rule)
+      when :error
+        raise EvaluationError, @failure_reason if ApprovalEngine.config.raise_on_rule_errors
+
+        quarantine(rule)
+      end
+    end
+
+    def preview
+      status, rule = find_match
+      ApprovalPlan.new(status: status, template: rule&.track_template, target: target, reason: @failure_reason)
+    end
+
+    def candidates
+      candidate_rules.filter_map do |rule|
+        ApprovalPlan.new(status: :match, template: rule.track_template, target: target) if evaluate(rule) == :match
+      end
+    end
+
+    private
+
+    attr_reader :event_name, :tenant_id, :target, :payload
+
+    # Walk rules highest-priority-first; stop at the first match or the first
+    # broken rule (fail closed). Returns [status, rule] where status is one of
+    # :match, :no_match, :error. Shared by `call` and `preview` so a preview can
+    # never disagree with the real run.
+    def find_match
+      candidate_rules.each do |rule|
+        case evaluate(rule)
+        when :match then return [ :match, rule ]
+        when :error then return [ :error, rule ]
+        end
+      end
+
+      [ :no_match, nil ]
+    end
+
+    def candidate_rules
+      TriggerRule.active
+                 .for_event(event_name)
+                 .where(tenant_id: tenant_id)
+                 .order(priority: :desc)
+    end
+
+    # Evaluates one rule. A *missing* payload key is a clean non-match (JSON
+    # Logic returns false). A *malformed* rule raises, which we capture as :error
+    # — the caller (`call` vs `preview`) decides whether to quarantine, raise, or
+    # just report. This method itself never raises.
+    def evaluate(rule)
+      ShinyJsonLogic.apply(rule.condition, payload) ? :match : :no_match
+    rescue => e
+      @failure_reason = "Rule #{rule.id} evaluation failed: #{e.class}: #{e.message}"
+      :error
+    end
+
+    def quarantine(_rule)
+      # Quarantine is fail-closed and async (host hears via on_quarantined); log
+      # too, so a systematic rule bug is visible without inspecting rows.
+      Rails.logger&.warn("[ApprovalEngine] quarantined #{target.class}##{target.id} (#{tenant_id}): #{@failure_reason}")
+      ApprovalBuilder.build_quarantine_approval!(
+        target: target,
+        tenant_id: tenant_id,
+        reason: @failure_reason
+      )
+    end
+  end
+end

data/app/views/approval_engine/approvals/index.html.erb

@@ -0,0 +1,38 @@
+<% content_for :title, "Approvals" %>
+<h1>Approvals</h1>
+
+<div class="ae-filters">
+  <%= link_to approvals_path, class: ("is-active" unless @status) do %>
+    All <span class="ae-count"><%= @counts.values.sum %></span>
+  <% end %>
+  <% ApprovalEngine::Approval::STATUSES.each do |status| %>
+    <%= link_to approvals_path(status: status), class: ("is-active" if @status == status) do %>
+      <%= status.tr("_", " ") %> <span class="ae-count"><%= @counts.fetch(status, 0) %></span>
+    <% end %>
+  <% end %>
+</div>
+
+<% if @approvals.empty? %>
+  <div class="ae-empty">No approvals<%= " with status #{@status}" if @status %>.</div>
+<% else %>
+  <table>
+    <thead>
+      <tr><th>Target</th><th>Event</th><th>Status</th><th>Tracks</th><th>Created</th><th></th></tr>
+    </thead>
+    <tbody>
+      <% @approvals.each do |approval| %>
+        <tr>
+          <td class="ae-mono"><%= target_label(approval.target) %></td>
+          <td><%= approval.event_name || "—" %></td>
+          <td><%= status_badge(approval.status) %></td>
+          <td><%= @track_counts.fetch(approval.id, 0) %></td>
+          <td class="ae-meta"><%= approval.created_at.to_fs(:short) %></td>
+          <td><%= link_to "View", approval_path(approval) %></td>
+        </tr>
+      <% end %>
+    </tbody>
+  </table>
+  <% if @total > @approvals.size %>
+    <p class="ae-meta">Showing the most recent <%= @approvals.size %> of <%= @total %>.</p>
+  <% end %>
+<% end %>

data/app/views/approval_engine/approvals/show.html.erb

@@ -0,0 +1,55 @@
+<% content_for :title, "Approval" %>
+<%= link_to "← All approvals", approvals_path, class: "ae-back" %>
+<h1>Approval <%= status_badge(@approval.status) %></h1>
+
+<div class="ae-card">
+  <div><strong>Target:</strong> <span class="ae-mono"><%= target_label(@approval.target) %></span></div>
+  <div><strong>Event:</strong> <%= @approval.event_name || "—" %></div>
+  <div><strong>Tenant:</strong> <span class="ae-mono"><%= @approval.tenant_id %></span></div>
+  <div class="ae-meta">Created <%= @approval.created_at.to_fs(:short) %></div>
+</div>
+
+<% @approval.tracks.each do |track| %>
+  <h2><%= track.name %> <%= status_badge(track.status) %></h2>
+  <table>
+    <thead>
+      <tr><th>Iter</th><th>Layer</th><th>Step</th><th>Assigned</th><th>Consensus</th><th>Status</th><th>Time in step</th></tr>
+    </thead>
+    <tbody>
+      <% track.steps.sort_by { |s| [s.iteration, s.layer] }.each do |step| %>
+        <tr>
+          <td><%= step.iteration %></td>
+          <td><%= step.layer %></td>
+          <td><%= step.name || "—" %></td>
+          <td class="ae-mono"><%= actor_label(step.assigned_actor) %></td>
+          <td><%= step.approvals_required %></td>
+          <td><%= status_badge(step.status) %></td>
+          <td class="ae-meta"><%= step.activated_at ? distance_of_time_in_words(step.activated_at, step.decided_at || Time.current) : "—" %></td>
+        </tr>
+      <% end %>
+    </tbody>
+  </table>
+<% end %>
+
+<h2>Audit trail</h2>
+<% logs = @approval.steps.flat_map(&:audit_logs).sort_by(&:created_at) %>
+<% if logs.empty? %>
+  <div class="ae-empty">No audit events yet.</div>
+<% else %>
+  <table>
+    <thead>
+      <tr><th>When</th><th>Event</th><th>Actual actor</th><th>Intended</th><th>Comment</th></tr>
+    </thead>
+    <tbody>
+      <% logs.each do |log| %>
+        <tr>
+          <td class="ae-meta"><%= log.created_at.to_fs(:short) %></td>
+          <td><%= status_badge(log.event) %></td>
+          <td class="ae-mono"><%= actor_label(log.actual_actor) %></td>
+          <td class="ae-mono"><%= log.by_proxy? ? actor_label(log.intended_actor) : "—" %></td>
+          <td><%= log.comment %></td>
+        </tr>
+      <% end %>
+    </tbody>
+  </table>
+<% end %>

data/app/views/layouts/approval_engine/dashboard.html.erb

@@ -0,0 +1,49 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>ApprovalEngine — <%= content_for?(:title) ? yield(:title) : "Dashboard" %></title>
+  <%= csrf_meta_tags %>
+  <style>
+    :root { --bg:#0f172a; --panel:#fff; --ink:#1e293b; --muted:#64748b; --line:#e2e8f0; --accent:#4f46e5; }
+    * { box-sizing: border-box; }
+    body { margin:0; font:14px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif; color:var(--ink); background:#f1f5f9; }
+    header.ae-top { background:var(--bg); color:#fff; padding:14px 24px; display:flex; align-items:center; gap:12px; }
+    header.ae-top a { color:#fff; text-decoration:none; font-weight:600; }
+    header.ae-top .ae-tag { font-size:11px; color:#94a3b8; border:1px solid #334155; padding:1px 8px; border-radius:999px; }
+    main { max-width:1100px; margin:24px auto; padding:0 24px; }
+    h1 { font-size:20px; margin:0 0 16px; }
+    h2 { font-size:15px; margin:24px 0 8px; color:var(--muted); text-transform:uppercase; letter-spacing:.04em; }
+    a { color:var(--accent); }
+    .ae-filters { display:flex; flex-wrap:wrap; gap:8px; margin-bottom:16px; }
+    .ae-filters a { text-decoration:none; background:#fff; border:1px solid var(--line); border-radius:999px; padding:4px 12px; color:var(--ink); }
+    .ae-filters a.is-active { background:var(--accent); color:#fff; border-color:var(--accent); }
+    .ae-filters .ae-count { color:var(--muted); font-variant-numeric:tabular-nums; }
+    .ae-filters a.is-active .ae-count { color:#e0e7ff; }
+    table { width:100%; border-collapse:collapse; background:var(--panel); border:1px solid var(--line); border-radius:10px; overflow:hidden; }
+    th, td { text-align:left; padding:10px 14px; border-bottom:1px solid var(--line); vertical-align:top; }
+    th { background:#f8fafc; font-size:12px; color:var(--muted); text-transform:uppercase; letter-spacing:.03em; }
+    tr:last-child td { border-bottom:0; }
+    .ae-badge { display:inline-block; font-size:11px; font-weight:600; padding:2px 9px; border-radius:999px; text-transform:capitalize; }
+    .is-pending{background:#fef9c3;color:#854d0e;} .is-waiting{background:#e2e8f0;color:#475569;}
+    .is-approved{background:#dcfce7;color:#166534;} .is-rejected{background:#fee2e2;color:#991b1b;}
+    .is-changes-requested{background:#ffedd5;color:#9a3412;} .is-cancelled{background:#f1f5f9;color:#94a3b8;}
+    .is-quarantined{background:#fae8ff;color:#86198f;}
+    .ae-empty { background:#fff; border:1px dashed var(--line); border-radius:10px; padding:40px; text-align:center; color:var(--muted); }
+    .ae-meta { color:var(--muted); font-size:13px; }
+    .ae-mono { font-family:ui-monospace,SFMono-Regular,Menlo,monospace; font-size:12px; }
+    .ae-card { background:var(--panel); border:1px solid var(--line); border-radius:10px; padding:16px 20px; margin-bottom:16px; }
+    .ae-back { display:inline-block; margin-bottom:12px; }
+  </style>
+</head>
+<body>
+  <header class="ae-top">
+    <%= link_to "ApprovalEngine", root_path %>
+    <span class="ae-tag">ops dashboard</span>
+  </header>
+  <main>
+    <%= yield %>
+  </main>
+</body>
+</html>

data/config/routes.rb

@@ -0,0 +1,8 @@
+ApprovalEngine::Engine.routes.draw do
+  # Read-only ops dashboard. Mount behind your own auth, e.g.:
+  #   authenticate :admin_user, ->(u) { u.super_admin? } do
+  #     mount ApprovalEngine::Engine => "/approval_engine"
+  #   end
+  root to: "approvals#index"
+  resources :approvals, only: %i[index show]
+end

data/db/migrate/20260614103434_create_approval_engine_core_tables.rb

@@ -0,0 +1,107 @@
+class CreateApprovalEngineCoreTables < ActiveRecord::Migration[7.0]
+  def change
+    # The orchestrator. One per host record + event. Holds the parallel
+    # track tracks and the overall outcome.
+    create_table :approval_engine_approvals, id: :uuid do |t|
+      t.string :tenant_id, null: false, index: true
+      t.references :target, polymorphic: true, null: false, index: true
+      t.string :status, null: false, default: "pending", index: true
+      t.string :event_name
+
+      t.timestamps
+    end
+
+    # A single track within an approval (e.g. "Finance", "Legal"). Approvals with
+    # more than one track model scatter-gather parallelism.
+    create_table :approval_engine_tracks, id: :uuid do |t|
+      t.string :tenant_id, null: false
+      t.references :approval_engine_approval, null: false, foreign_key: true, type: :uuid
+      t.string :name, null: false
+      t.string :status, null: false, default: "pending"
+
+      t.timestamps
+    end
+
+    # The immutable ledger row. Steps are never updated backwards: a rework
+    # rejection appends a fresh iteration rather than resetting history.
+    create_table :approval_engine_steps, id: :uuid do |t|
+      t.string :tenant_id, null: false
+      t.references :approval_engine_track, null: false, foreign_key: true, type: :uuid
+      t.string :name
+      t.integer :layer, null: false, default: 1
+      t.integer :iteration, null: false, default: 1
+      t.string :status, null: false, default: "pending", index: true
+      # How many approvals this step's layer needs: any | all | majority | "60%" | "2".
+      t.string :approvals_required, null: false, default: "any"
+      t.references :assigned_actor, polymorphic: true, null: false
+
+      # Cycle-time facts for latency/bottleneck reporting: when the step became
+      # actionable (pending), and when a human resolved it. Both stay null while
+      # waiting; decided_at also stays null for cancelled/expired steps (never decided).
+      t.datetime :activated_at
+      t.datetime :decided_at
+
+      # Timeout — three distinct facts:
+      #   timeout_after : the SLA window in seconds, copied from the template like
+      #                   the step's other facts (the ledger stays self-contained).
+      #   timeout_at    : the deadline itself, fixed when the step is activated.
+      #                   Stored (not recomputed) and indexed so the sweep stays a
+      #                   plain `timeout_at <= now`, not interval arithmetic.
+      #   timed_out_at  : when the timeout fired — so it fires exactly once.
+      t.integer :timeout_after
+      t.datetime :timeout_at
+      t.datetime :timed_out_at
+
+      t.timestamps
+    end
+
+    # Append-only audit trail. Records the intended actor (who was assigned) vs.
+    # the actual actor (who acted, possibly a delegate) for strict compliance.
+    create_table :approval_engine_audit_logs, id: :uuid do |t|
+      t.string :tenant_id, null: false
+      t.references :approval_engine_step, null: false, foreign_key: true, type: :uuid
+      t.string :event, null: false
+      t.references :intended_actor, polymorphic: true, null: true
+      # Nullable: system events (e.g. a step timing out) have no human actor —
+      # the ledger records that honestly rather than fabricating one.
+      t.references :actual_actor, polymorphic: true, null: true
+      t.text :comment
+
+      t.timestamps
+    end
+
+    # Fast lookup for "my pending approvals" dashboards.
+    add_index :approval_engine_steps,
+              %i[tenant_id assigned_actor_type assigned_actor_id status],
+              name: "idx_approval_engine_pending_tasks"
+
+    # Enforce the enumerated values at the database level, not just in Ruby —
+    # the ledger is the source of truth, so a raw write can't corrupt it.
+    add_check_constraint :approval_engine_approvals,
+                         "status IN ('pending','approved','rejected','quarantined','cancelled')",
+                         name: "chk_approval_engine_approval_status"
+    add_check_constraint :approval_engine_tracks,
+                         "status IN ('pending','approved','rejected','cancelled')",
+                         name: "chk_approval_engine_track_status"
+    add_check_constraint :approval_engine_steps,
+                         "status IN ('waiting','pending','approved','rejected','changes_requested','expired','cancelled')",
+                         name: "chk_approval_engine_step_status"
+    add_check_constraint :approval_engine_steps,
+                         "approvals_required ~ '^([1-9][0-9]*%?|any|all|majority)$'",
+                         name: "chk_approval_engine_step_approvals_required"
+
+    # Hot-path indexes the read/write queries actually use.
+    add_index :approval_engine_tracks, %i[approval_engine_approval_id status],
+              name: "idx_ae_tracks_approval_status"
+    add_index :approval_engine_steps, %i[approval_engine_track_id iteration layer status],
+              name: "idx_ae_steps_layer_consensus"
+    add_index :approval_engine_approvals, %i[target_type target_id created_at],
+              name: "idx_ae_approvals_target_recency"
+    add_index :approval_engine_audit_logs, %i[tenant_id created_at]
+
+    # The timeout sweep only cares about steps with a live, unfired deadline.
+    add_index :approval_engine_steps, :timeout_at,
+              where: "timeout_at IS NOT NULL AND timed_out_at IS NULL",
+              name: "idx_ae_steps_overdue"
+  end
+end

data/db/migrate/20260614103435_create_approval_engine_infrastructure_tables.rb

@@ -0,0 +1,35 @@
+class CreateApprovalEngineInfrastructureTables < ActiveRecord::Migration[7.0]
+  def change
+    create_table :approval_engine_outbox_events, id: :uuid do |t|
+      t.string :tenant_id, null: false
+      t.string :event_name, null: false
+      t.references :record, polymorphic: true, null: false, type: :uuid
+      t.boolean :processed, null: false, default: false, index: true
+      t.datetime :processed_at
+      t.text :error_payload
+
+      t.timestamps
+    end
+
+    create_table :approval_engine_delegations, id: :uuid do |t|
+      t.string :tenant_id, null: false
+      t.references :delegator, polymorphic: true, null: false
+      t.references :delegatee, polymorphic: true, null: false
+      t.datetime :starts_at, null: false
+      t.datetime :ends_at, null: false
+      t.boolean :active, null: false, default: true
+
+      t.timestamps
+    end
+
+    # Serves the inbox's `in_effect.where(delegatee:)` time-window lookup.
+    add_index :approval_engine_delegations,
+              %i[delegatee_type delegatee_id active starts_at ends_at],
+              name: "idx_ae_delegations_lookup"
+
+    # Partial index keeps the outbox `drain!` backlog scan tiny.
+    add_index :approval_engine_outbox_events, :created_at,
+              where: "processed = false",
+              name: "idx_ae_outbox_unprocessed"
+  end
+end

data/db/migrate/20260614104809_create_approval_engine_blueprint_tables.rb

@@ -0,0 +1,60 @@
+class CreateApprovalEngineBlueprintTables < ActiveRecord::Migration[7.0]
+  def change
+    # The reusable blueprint an approval is stamped from. Event-agnostic: which
+    # event triggers it is a routing concern owned by TriggerRule, not the template.
+    create_table :approval_engine_track_templates, id: :uuid do |t|
+      t.string :tenant_id, null: false, index: true
+      t.string :name, null: false
+      t.string :status, null: false, default: "draft"
+
+      t.timestamps
+    end
+
+    # The ordered layers of a template (custom index name keeps it under 63 chars).
+    create_table :approval_engine_template_steps, id: :uuid do |t|
+      t.references :approval_engine_track_template,
+                   null: false,
+                   foreign_key: true,
+                   type: :uuid,
+                   index: { name: "idx_ae_tpl_steps_on_tpl_id" }
+      t.string :name, null: false
+      t.integer :layer, null: false, default: 1
+      t.string :approvals_required, null: false, default: "any"
+      t.string :assigned_group, null: false
+      # Optional SLA: seconds the step gets once it becomes actionable. nil = no
+      # deadline. Stamped onto each concrete Step; the host sweeps for breaches.
+      t.integer :timeout_after
+
+      t.timestamps
+    end
+
+    # The JSON Logic routing rules.
+    create_table :approval_engine_trigger_rules, id: :uuid do |t|
+      t.string :tenant_id, null: false, index: true
+      t.string :event_name, null: false
+      t.jsonb :condition, null: false, default: {}
+      t.integer :priority, null: false, default: 0
+      t.references :approval_engine_track_template,
+                   null: false,
+                   foreign_key: true,
+                   type: :uuid,
+                   index: { name: "idx_ae_trigger_rules_on_tpl_id" }
+      t.boolean :active, null: false, default: true
+
+      t.timestamps
+    end
+
+    add_index :approval_engine_trigger_rules, :condition, using: :gin
+
+    add_check_constraint :approval_engine_track_templates,
+                         "status IN ('draft','active','archived')",
+                         name: "chk_approval_engine_template_status"
+    add_check_constraint :approval_engine_template_steps,
+                         "approvals_required ~ '^([1-9][0-9]*%?|any|all|majority)$'",
+                         name: "chk_approval_engine_template_step_approvals_required"
+
+    # Rule resolution runs on every triggering event — make it one index scan.
+    add_index :approval_engine_trigger_rules, %i[tenant_id event_name active priority],
+              name: "idx_ae_trigger_rules_resolution"
+  end
+end

data/db/migrate/20260616000001_add_trigger_rule_to_approvals.rb

@@ -0,0 +1,14 @@
+class AddTriggerRuleToApprovals < ActiveRecord::Migration[7.0]
+  # Provenance: which TriggerRule auto-routed this approval. Nullable — an
+  # approval started manually via run_approval!(templates:) has no matching
+  # rule. on_delete: :nullify so retiring a rule never blocks or rewrites the
+  # historical approvals it once spawned (the ledger stays append-only).
+  def change
+    add_reference :approval_engine_approvals,
+                  :approval_engine_trigger_rule,
+                  type: :uuid,
+                  null: true,
+                  foreign_key: { to_table: :approval_engine_trigger_rules, on_delete: :nullify },
+                  index: { name: "idx_ae_approvals_on_trigger_rule" }
+  end
+end

data/db/migrate/20260617000001_add_approvals_required_to_approvals.rb

@@ -0,0 +1,11 @@
+class AddApprovalsRequiredToApprovals < ActiveRecord::Migration[7.0]
+  # The gather consensus: how many of an approval's parallel tracks must approve.
+  # Defaults to "all" so existing approvals keep their unanimity behaviour.
+  def change
+    add_column :approval_engine_approvals, :approvals_required, :string, null: false, default: "all"
+
+    add_check_constraint :approval_engine_approvals,
+                         "approvals_required ~ '^([1-9][0-9]*%?|any|all|majority)$'",
+                         name: "chk_approval_engine_approval_approvals_required"
+  end
+end

data/db/migrate/20260617000002_add_delivery_tracking_to_outbox_events.rb

@@ -0,0 +1,11 @@
+class AddDeliveryTrackingToOutboxEvents < ActiveRecord::Migration[7.0]
+  # `error_payload` carries the *semantic* reason (why an approval was rejected,
+  # quarantined, or cancelled) that the host callback consumes. Delivery failures
+  # now record their backtrace in `delivery_error` so a retry can't clobber that
+  # reason. `failed_at` is the dead-letter mark: a row whose retries are exhausted,
+  # so `drain!` stops resurrecting it forever.
+  def change
+    add_column :approval_engine_outbox_events, :delivery_error, :text
+    add_column :approval_engine_outbox_events, :failed_at, :datetime
+  end
+end

data/lib/approval_engine/approval_exposure.rb

@@ -0,0 +1,66 @@
+module ApprovalEngine
+  # The anti-corruption layer. Collects the explicitly whitelisted attributes a
+  # host model is willing to expose to the dynamic rules engine, and produces a
+  # flat, string-keyed payload from them.
+  #
+  # The rules engine only ever sees what was declared here — never the raw
+  # model — so a SaaS admin's JSON Logic can never reach into unsafe internals.
+  #
+  #   exposes_for_approval do
+  #     attribute :amount, type: :decimal
+  #     attribute :department, type: :string, source: ->(invoice) { invoice.department.name }
+  #     attribute :is_high_risk, type: :boolean, source: :requires_manual_audit?
+  #   end
+  class ApprovalExposure
+    # A single whitelisted attribute. `source` decides how the value is read:
+    #   nil    -> read the attribute/method named `name`
+    #   Symbol -> call that method on the record
+    #   Proc   -> call it with the record
+    Attribute = Struct.new(:name, :type, :source, keyword_init: true) do
+      def value_for(record)
+        case source
+        when nil    then record.public_send(name)
+        when Symbol then record.public_send(source)
+        when Proc   then source.call(record)
+        else source
+        end
+      end
+    end
+
+    attr_reader :attributes
+
+    def initialize
+      @attributes = {}
+    end
+
+    # Keep dup'd exposures independent so per-class definitions never leak into
+    # one another (class_attribute inheritance relies on this).
+    def initialize_dup(other)
+      super
+      @attributes = other.attributes.dup
+    end
+
+    def attribute(name, type: :string, source: nil)
+      @attributes[name.to_s] = Attribute.new(name: name, type: type, source: source)
+    end
+
+    # The flat payload handed to the JSON Logic evaluator.
+    def serialize(record)
+      @attributes.transform_values { |attr| coerce(attr.value_for(record), attr.type) }
+    end
+
+    private
+
+    def coerce(value, type)
+      return nil if value.nil?
+
+      case type
+      when :integer         then value.to_i
+      when :decimal, :float then value.to_f
+      when :boolean         then ActiveModel::Type::Boolean.new.cast(value)
+      when :string          then value.to_s
+      else value
+      end
+    end
+  end
+end

data/lib/approval_engine/configuration.rb

@@ -0,0 +1,67 @@
+module ApprovalEngine
+  # Host-tunable configuration. Every knob here is a *seam*: the engine ships a
+  # sensible default and lets the host application override behaviour without
+  # the engine having to know anything about the host's domain.
+  #
+  #   ApprovalEngine.configure do |config|
+  #     config.outbox_queue          = :high_priority
+  #     config.actor_class           = "User"
+  #     config.current_tenant_method = -> { Current.account }
+  #   end
+  class Configuration
+    # A callable (lambda/proc) that returns the current tenant, e.g.
+    # `-> { Current.account }`. The engine only ever reads `#id` off the result.
+    attr_accessor :current_tenant_method
+
+    # The ActiveJob queue the transactional outbox is processed on.
+    attr_accessor :outbox_queue
+
+    # Name of the host's actor class (the thing that approves). It must respond
+    # to `resolve_approval_group(group_name, target)`. Kept as a String so the
+    # engine never holds a reference to an un-reloadable constant in development.
+    attr_accessor :actor_class
+
+    # When a dynamic rule blows up (e.g. a typo'd payload key), the engine fails
+    # *closed* by quarantining the approval rather than raising into your app.
+    # Flip this to `true` in development/test to surface the error loudly instead.
+    attr_accessor :raise_on_rule_errors
+
+    def initialize
+      @outbox_queue          = :default
+      @current_tenant_method = nil
+      @actor_class           = "User"
+      @raise_on_rule_errors  = false
+    end
+
+    # The host's actor class, resolved lazily so reloading works in development.
+    def actor_class_constant
+      actor_class.to_s.constantize
+    end
+
+    # Resolves the current tenant via the configured callable. Returns nil when
+    # the host has not configured tenancy (single-tenant apps are welcome too).
+    def current_tenant
+      current_tenant_method&.call
+    end
+  end
+
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield(config)
+    end
+
+    # Resets configuration to defaults. Primarily a test-suite affordance.
+    def reset_configuration!
+      @config = Configuration.new
+    end
+
+    # Convenience reader used across the engine to scope queries by tenant.
+    def current_tenant
+      config.current_tenant
+    end
+  end
+end

data/lib/approval_engine/engine.rb

@@ -0,0 +1,17 @@
+module ApprovalEngine
+  class Engine < ::Rails::Engine
+    isolate_namespace ApprovalEngine
+
+    # Make `has_approvals` available on every ActiveRecord model.
+    initializer "approval_engine.model_extensions" do
+      ActiveSupport.on_load(:active_record) do
+        extend ApprovalEngine::ModelExtensions
+      end
+    end
+
+    # Keep the engine's own tests/factories from bleeding into a host app.
+    config.generators do |g|
+      g.test_framework :test_unit, fixture: false
+    end
+  end
+end