change_requests 0.3.0 → 0.4.0

data/docs/adr/0028-sweeps-are-rake-tasks.md

@@ -0,0 +1,67 @@
+# ADR-0028: Sweep with rake tasks, and keep the destructive one off the schedule
+
+- **Status:** Accepted
+- **Date:** 2026-09-12
+
+## Context
+
+Three kinds of row do not resolve themselves. A request nobody acted on sits `pending` past its
+deadline. A request claimed by a process that then died sits `executing`, which no command will move
+([ADR-0022](0022-execution-in-three-transactions.md)). A request whose operation is no longer declared
+can never run at all.
+
+Each needs sweeping. The question is what does the sweeping, and how often — which the plan asserted
+in three places without ever saying.
+
+## Decision
+
+`ChangeRequests::Maintenance` holds one method per sweep, each a query plus the command that owns its
+transition — never a write of its own. The commands hold the locks and emit the events; the sweeps
+decide which rows to hand them ([ADR-0016](0016-commands-are-the-only-writers.md)). Each returns the
+number of rows it moved.
+
+`lib/tasks/change_requests.rake` exposes one task per sweep, loaded by the engine's own `lib/tasks`
+path so a host requires nothing. Nothing rescues: rake exits non-zero when a task raises, so cron's
+mail-on-failure is the alarm, and a sweep that moved nothing is not an error.
+
+**Two are documented as cron. The third is not.**
+
+```cron
+5 * * * *  cd /app && bin/rails change_requests:expire_stale
+6 * * * *  cd /app && bin/rails change_requests:reap_stuck_executions
+```
+
+`change_requests:cancel_undeclared` is run by an operator who has looked. A missing declaration is as
+likely to be a deploy accident — an initializer that did not load, a file renamed — as a deliberate
+removal, and `canceled` is final. The gem's other responses to an undeclared operation are immediate
+**and reversible**: every guard but `Comment`, `Cancel` and `Reap` refuses it, and it leaves inboxes
+and badges at once. A scheduled sweep would turn a bad deploy into a table of permanently cancelled
+requests within the hour, when reverting the deploy would have cost nothing.
+
+Cron rather than a recurring job, because these are time-of-day work with no per-request trigger, and
+because a host running headless has no job backend to schedule into. The interval is a recommendation:
+`expires_at` and the reaper's `older_than` are the real deadlines, and a sweeper running late moves the
+same rows, just later.
+
+## Consequences
+
+### Positive
+
+- The sweeps are ordinary commands, so every row they move gets its lock, its event and its `System`
+  actor for free, and the reaper's transition is guarded like every other one.
+- A host with no job backend can still run all three.
+- The destructive one cannot fire on its own. Recovering from a failed initializer is reverting the
+  deploy, not restoring rows.
+
+### Negative
+
+- **Nothing runs by default.** A host that installs the gem and never reads `docs/05` accumulates
+  expired-but-`pending` requests and stuck `executing` rows indefinitely, and nothing warns them.
+- Three tasks to schedule is three chances to schedule none.
+- `cancel_undeclared` being manual means a stranded request is cleared by whoever notices, which in
+  practice is nobody until someone reads a list. §5.11 mitigates this by making such requests
+  cancelable by *any* actor, so clearing one does not wait on the rake task — but the bulk path is
+  still a decision somebody has to make.
+- The reaper's default threshold is a guess about the host's slowest target, and the failure mode is
+  silent: an execution written off while it is still working leaves a `failed` row and a side effect
+  that lands afterwards.

data/docs/adr/README.md

@@ -33,3 +33,10 @@ than an edit.
 | [0019](0019-separation-of-duties.md) | Refuse the requester by identity, and make only execution configurable | Accepted |
 | [0020](0020-refusal-vocabulary-and-fallback.md) | Ship refusal reasons as a closed vocabulary that degrades to the symbol | Accepted |
 | [0021](0021-serialise-commands-let-the-index-arbitrate.md) | Serialise commands with a row lock and let the unique index arbitrate | Accepted |
+| [0022](0022-execution-in-three-transactions.md) | Split execution into three transactions, and commit the claim before the side effect | Accepted |
+| [0023](0023-one-declaration-surface.md) | Declare a workflow one way | Accepted |
+| [0024](0024-idempotence-is-required-not-declared.md) | Require idempotence of every target rather than declaring it per operation | Accepted |
+| [0025](0025-verification-from-one-set-of-checks.md) | Verify declarations at boot, from the same checks the runtime reads | Accepted |
+| [0026](0026-distinct-intent-distinct-command.md) | Give a distinct intent a distinct command class, not a flag | Accepted |
+| [0027](0027-activejob-is-optional.md) | Make background execution a setting and ActiveJob an optional dependency | Accepted |
+| [0028](0028-sweeps-are-rake-tasks.md) | Sweep with rake tasks, and keep the destructive one off the schedule | Accepted |

data/lib/change_requests/commands/cancel.rb

@@ -19,7 +19,7 @@ module ChangeRequests
 
         # Emitted before the status changes, so the trail records the request as it was cancelled
         # rather than as it ended up.
-        emit(:canceled, body: reason, metadata: { status: request.status })
+        emit(event_kind, body: reason, metadata: metadata)
         request.update!(status: "canceled")
 
         request
@@ -27,6 +27,16 @@ module ChangeRequests
 
       private
 
+      # The two seams CancelUndeclared overrides, and the whole of the difference between them:
+      # who cancelled decides which fact the timeline records (Q11, §5.11).
+      def event_kind
+        :canceled
+      end
+
+      def metadata
+        { status: request.status }
+      end
+
       def reason
         options[:reason]
       end

data/lib/change_requests/commands/cancel_undeclared.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module ChangeRequests
+  module Commands
+    # The sweeper closing out a request whose declaration vanished (§5.11).
+    #
+    #   Commands::CancelUndeclared.call(request:)
+    #
+    # `Cancel` with two things changed: the event kind, and the metadata. **Who cancelled decides
+    # which event is emitted** (Q11) - a person cancelling a stranded request emits `canceled` with
+    # their own reason, because they cancelled it; this emits `operation_undeclared`, because
+    # "nobody decided this, its declaration vanished" is a different fact and a timeline should not
+    # have to infer it from the actor column.
+    #
+    # It supplies its own reason, so `Cancel`'s mandatory-reason rule holds unchanged rather than
+    # growing an exception. The text is translatable, not a hardcoded English sentence (§5.11).
+    class CancelUndeclared < Cancel
+      REASON_KEY = "change_requests.events.operation_undeclared"
+
+      def self.call(request:)
+        new(request: request, actor: nil, reason: reason).call
+      end
+
+      def self.reason
+        Translation.translate(REASON_KEY,
+                              default: "This operation is no longer declared, so the request " \
+                                       "could never run.")
+      end
+
+      private
+
+      def event_kind
+        :operation_undeclared
+      end
+
+      # Alongside Cancel's `status`: what it was cancelled out of is still worth recording. The
+      # version is the request's creation-time one - `Base#emit` falls back to it for the column
+      # too, there being no live declaration to read - and it is the version whose disappearance
+      # this event reports (§5.5, §5.11).
+      def metadata
+        super.merge(operation_key: request.operation_key,
+                    operation_version: request.operation_version)
+      end
+    end
+  end
+end

data/lib/change_requests/commands/reap.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module ChangeRequests
+  module Commands
+    # The clock writing off an execution nobody finished (§8).
+    #
+    #   Commands::Reap.call(request:)
+    #
+    # T1 claimed the request and committed; then the process died, the box was replaced, or the job
+    # backend lost the work. Nothing will ever settle that attempt, so the row would sit `executing`
+    # forever - and `executing` is the one status no other command will move (Q28).
+    #
+    # No actor: `emit` stamps `SYSTEM_ACTOR`, so "who did this" is answerable for every row (§5.5).
+    # `Maintenance.reap_stuck_executions!` is the sweep around this transition.
+    class Reap < Base
+      def self.call(request:, older_than: Guards::Reap::DEFAULT_STUCK_AFTER)
+        new(request: request, actor: nil, older_than: older_than).call
+      end
+
+      def perform
+        guard = Guards::Reap.new(request: request, actor: actor, older_than: options[:older_than])
+        guard.check!
+
+        attempt = guard.stuck_attempt
+
+        # Emitted before the status changes, as Expire does: the trail records what was reaped
+        # rather than what it became, which is `failed` for every one of these rows.
+        emit(:reaped, metadata: { attempt: attempt.number, stuck_for: guard.stuck_for })
+
+        attempt.update!(outcome: "abandoned", finished_at: Time.current)
+        request.update!(status: "failed")
+
+        request
+      end
+    end
+  end
+end

data/lib/change_requests/commands/settle_execution.rb

@@ -6,13 +6,17 @@ module ChangeRequests
     # target that raises leaves no business change and still leaves a durable record of the failure.
     #
     # Internal, like ClaimExecution. `error:` nil is the success branch.
+    #
+    # It takes no actor. T1 recorded the executer's triple on the attempt, and this reads it back -
+    # so background mode can settle in a process that never saw the actor object, and the event
+    # names whoever actually claimed the run (§5.6, §8).
     class SettleExecution < Base
       # Enough to locate the failure, bounded so a deep stack cannot write a megabyte per attempt
       # into a host's database. The column is text; nothing else truncates it.
       BACKTRACE_FRAMES = 20
 
-      def self.call(request:, actor:, attempt:, error: nil)
-        new(request: request, actor: actor, attempt: attempt, error: error).call
+      def self.call(request:, attempt:, error: nil)
+        new(request: request, attempt: attempt, error: error).call
       end
 
       def perform
@@ -32,7 +36,7 @@ module ChangeRequests
       end
 
       def record_success
-        request.update!(status: "successful", executed_at: Time.current, executer: actor)
+        request.update!(status: "successful", executed_at: Time.current, **executer_columns)
         attempt.update!(outcome: "succeeded", finished_at: Time.current)
         emit(:executed, metadata: { attempt: attempt.number })
       end
@@ -47,6 +51,26 @@ module ChangeRequests
              metadata: { attempt: attempt.number, error_class: error.class.name })
       end
 
+      # Copied up from the attempt rather than resolved from an actor: §5.7's triple is already
+      # snapshotted there, and the request's executer is whoever claimed the attempt that ran.
+      def executer_columns
+        {
+          executer_type: attempt.executer_type,
+          executer_id: attempt.executer_id,
+          executer_label: attempt.executer_label,
+        }
+      end
+
+      # Base stamps the acting actor, or the System sentinel when there is none. Here there is an
+      # actor - the one on the attempt - and no object to resolve it from.
+      def event_actor
+        {
+          actor_type: attempt.executer_type,
+          actor_id: attempt.executer_id,
+          actor_label: attempt.executer_label,
+        }
+      end
+
       def bounded_backtrace
         Array(error.backtrace).first(BACKTRACE_FRAMES).join("\n").presence
       end

data/lib/change_requests/configuration.rb

@@ -6,6 +6,7 @@ module ChangeRequests
   class Configuration
     LABEL_STRATEGIES    = %i(live snapshot).freeze
     PERMISSION_MATCHES  = %i(any all).freeze
+    EXECUTION_MODES     = %i(inline background).freeze
 
     # Identity (§9.1)
     attr_reader :actor_types, :tenant_types
@@ -22,6 +23,10 @@ module ChangeRequests
     # Workflow and execution defaults (§7.1, §8)
     attr_accessor :only_record_rejections, :default_max_attempts, :default_expires_in
 
+    # Where T2 and T3 run (§8, §10). `job_class` is a string so the gem never holds a class
+    # reference across a reload, and so a headless host can name one it has not loaded.
+    attr_accessor :execution_mode, :job_class, :job_queue
+
     def initialize
       @actor_types  = {}
       @tenant_types = {}
@@ -39,6 +44,10 @@ module ChangeRequests
       @only_record_rejections = false
       @default_max_attempts   = 1
       @default_expires_in     = nil
+
+      @execution_mode = :inline
+      @job_class      = "ChangeRequests::Execution::Job"
+      @job_queue      = :default
     end
 
     # §9.2 tells hosts to assign a bare lambda; the gem needs one object answering `allows?`.
@@ -78,6 +87,9 @@ module ChangeRequests
         actor_identity_problem,
         authorization_problem,
         max_attempts_problem,
+        execution_mode_problem,
+        job_class_problem,
+        job_queue_problem,
         *actor_types.values.flat_map(&:problems),
         *tenant_types.values.flat_map(&:problems),
       ].compact
@@ -123,6 +135,29 @@ module ChangeRequests
         "Expected #{PERMISSION_MATCHES.map(&:inspect).join(" or ")} (§5.3)."
     end
 
+    def execution_mode_problem
+      return if EXECUTION_MODES.include?(execution_mode)
+
+      "config.execution_mode is #{execution_mode.inspect}. " \
+        "Expected #{EXECUTION_MODES.map(&:inspect).join(" or ")} (§8)."
+    end
+
+    # Not checked for resolvability here: a headless process may legitimately have `:background`
+    # configured and no ActiveJob at all, and refusing that would fail a boot that works. The
+    # enqueue reports it instead - see ChangeRequests.background_job! (§8).
+    def job_class_problem
+      return if job_class.respond_to?(:to_str) && !job_class.to_str.strip.empty?
+
+      "config.job_class is #{job_class.inspect}. Expected the name of an ActiveJob class, " \
+        "for example \"ChangeRequests::Execution::Job\" (§10)."
+    end
+
+    def job_queue_problem
+      return unless job_queue.nil? || job_queue.to_s.strip.empty?
+
+      "config.job_queue is #{job_queue.inspect}. Expected a queue name (§10)."
+    end
+
     def actor_identity_problem
       return if actor_identity.nil? || actor_identity.respond_to?(:call)
 

data/lib/change_requests/engine.rb

@@ -15,6 +15,13 @@ module ChangeRequests
       g.test_framework :rspec
     end
 
+    # So a host never calls `load_execution_job!` itself: ActiveJob is usually loaded before
+    # Bundler reaches this gem, but `rails/all` is not the only way to boot and `require` decides
+    # only once (§8).
+    initializer "change_requests.execution_job" do
+      ActiveSupport.on_load(:active_job) { ChangeRequests.load_execution_job! }
+    end
+
     # Fail the boot, not the first request that touches the gem.
     config.after_initialize do
       ChangeRequests.config.validate!

data/lib/change_requests/execution/job.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# §8's background mode. Zeitwerk ignores this file and `ChangeRequests.load_execution_job!`
+# requires it, because the gem has no ActiveJob dependency: `activejob` is a development
+# dependency for the dummy application, and the domain core must load in a process that has
+# never heard of it. Requiring this file without ActiveJob defines nothing at all.
+#
+# archspec:disable-next-line constants.forbid -- §8: the job exists only where the host has ActiveJob
+if defined?(ActiveJob::Base)
+  module ChangeRequests
+    module Execution
+      # T1 has already committed in the caller's process, so the request is visibly `executing`
+      # and the attempt row is claimed. This runs T2 and T3, and nothing else.
+      #
+      # archspec:disable-next-line constants.forbid -- ditto, and the class cannot exist without it
+      class Job < ::ActiveJob::Base
+        # The two ids rather than the objects: a job argument has to survive serialisation, and the
+        # attempt already carries the executer's triple, so T3 needs no actor object (§5.6).
+        def perform(change_request_id, attempt_id)
+          request = Request.find(change_request_id)
+
+          Runner.finish(request: request, attempt: request.attempts.find(attempt_id))
+        end
+      end
+    end
+  end
+end

data/lib/change_requests/execution/runner.rb

@@ -18,7 +18,12 @@ module ChangeRequests
         new(request: request, actor: actor, override: override, reason: reason).call
       end
 
-      def initialize(request:, actor:, override: false, reason: nil)
+      # T2 and T3 alone: T1 committed in another process, which is what Execution::Job resumes.
+      def self.finish(request:, attempt:)
+        new(request: request).finish(attempt)
+      end
+
+      def initialize(request:, actor: nil, override: false, reason: nil)
         @request  = request
         @actor    = actor
         @override = override
@@ -29,6 +34,14 @@ module ChangeRequests
         attempt = Commands::ClaimExecution.call(request: request, actor: actor,
                                                 override: override, reason: reason)
 
+        # T1 commits either way, so the request is visibly `executing` the moment this returns -
+        # which is the whole reason background mode does not enqueue the claim as well (§8).
+        return enqueue(attempt) if background?
+
+        finish(attempt)
+      end
+
+      def finish(attempt)
         begin
           invoke
         rescue StandardError => e
@@ -47,6 +60,20 @@ module ChangeRequests
 
       attr_reader :request, :actor, :override, :reason
 
+      def background?
+        ChangeRequests.config.execution_mode == :background
+      end
+
+      # The ids, not the objects: §8's job takes what survives serialisation. Returns the claimed
+      # request, so a caller sees what inline mode gives it - a row, already `executing`.
+      def enqueue(attempt)
+        ChangeRequests.background_job!
+                      .set(queue: ChangeRequests.config.job_queue)
+                      .perform_later(request.id, attempt.id)
+
+        request.reload
+      end
+
       def invoke
         Dispatcher.call(operation_key: request.operation_key, payload: request.payload,
                         change_request_id: request.id)
@@ -62,8 +89,10 @@ module ChangeRequests
         "#{operation.service}.#{operation.method_name}"
       end
 
+      # No actor: the attempt carries the executer's triple from T1, which is what T3 records.
+      # That is what lets the job settle a claim it did not make (§5.6).
       def settle(attempt, error)
-        Commands::SettleExecution.call(request: request, actor: actor, attempt: attempt, error: error)
+        Commands::SettleExecution.call(request: request, attempt: attempt, error: error)
       end
     end
   end

data/lib/change_requests/guards/base.rb

@@ -36,6 +36,8 @@ module ChangeRequests
         may_not_request
         not_approved
         attempts_exhausted
+        not_executing
+        not_stuck
         not_expired
         not_expirable
         not_system

data/lib/change_requests/guards/cancel.rb

@@ -9,14 +9,22 @@ module ChangeRequests
     # about the step it happens to be sitting on.
     #
     # The reason is mandatory and `Commands::Cancel` enforces it, for the reason Reject does (Q25).
+    #
+    # Once the operation is undeclared, **anyone** may cancel (§5.11, Q9). A request that can never
+    # run is not worth adjudicating who may tidy it away, and leaving it clearable only by a rake
+    # task means a stranded row sits in the table until an operator notices.
     class Cancel < Base
       refuses_with NotCancelable
+      exempt_from_undeclared_operation!
 
       def refusal
         return :already_finalized if request.final?
         # The target is mid-flight. A status change cannot recall it, and setting a terminal status
-        # would leave the execution unable to record its own outcome (Q28, §8).
+        # would leave the execution unable to record its own outcome (Q28, §8). Ahead of the
+        # undeclared branch: being undeclared does not make a running request recallable.
         return :executing if request.executing?
+        # §5.11: the requester-or-approver rule is dropped along with the refusal, not before it.
+        return nil if operation.nil?
         return :not_permitted unless requester? || eligible_approver?
 
         nil

data/lib/change_requests/guards/reap.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module ChangeRequests
+  module Guards
+    # May this request's abandoned execution be written off (§8)?
+    #
+    # System only, for the reason `Expire` is: nobody reaps a request on purpose, the clock does,
+    # so an actor being supplied at all is the refusal. Every refusal is `NotAuthorized` rather
+    # than a TransitionError apart from the shared `:already_finalized` mapping - the only caller
+    # is `Maintenance.reap_stuck_executions!`, whose query already filters on status and age, so
+    # these branches are a floor beneath it and never a user-facing flash (Q32).
+    # Exempt from the undeclared-operation refusal, joining Comment and Cancel (§5.11). Whether
+    # the declaration still exists has no bearing on "this attempt died and nobody will settle it" -
+    # and Cancel refuses an `executing` request (Q28), so without this a row claimed just as its
+    # declaration vanished could be cleared by nothing at all.
+    class Reap < Base
+      # §8's documented default, in seconds rather than `1.hour`: the domain core loads against a
+      # bare ActiveRecord, which does not bring active_support/core_ext/numeric/time with it. A
+      # host passing `1.hour` still works - a Duration subtracts from a Time exactly the same.
+      DEFAULT_STUCK_AFTER = 3600
+
+      refuses_with NotAuthorized
+      exempt_from_undeclared_operation!
+
+      def refusal
+        return :not_system unless actor.nil?
+        return :already_finalized if request.final?
+        return :not_executing unless request.executing?
+        return :not_stuck if stuck_attempt.nil?
+
+        nil
+      end
+
+      # The attempt the reaper writes off, exposed so the command writes the same row the guard
+      # judged - one guard object, built once (I7).
+      def stuck_attempt
+        return @stuck_attempt if defined?(@stuck_attempt)
+
+        @stuck_attempt = request.attempts.in_flight.where(started_at: ..cutoff).order(:number).last
+      end
+
+      def stuck_for(now = Time.current)
+        return nil if stuck_attempt&.started_at.nil?
+
+        (now - stuck_attempt.started_at).round
+      end
+
+      private
+
+      def cutoff
+        Time.current - older_than
+      end
+
+      def older_than
+        options.fetch(:older_than, DEFAULT_STUCK_AFTER)
+      end
+    end
+  end
+end

data/lib/change_requests/maintenance.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module ChangeRequests
+  # The scheduled sweeps (§8, §5.11). Each one is a query plus the command that owns its
+  # transition, never a write of its own: the commands hold the locks and emit the events, and
+  # these decide which rows to hand them (ADR 0016).
+  #
+  # Every event they cause carries the `System` sentinel, because `Commands::Base#emit` stamps it
+  # when `actor` is nil - closing these rows out is the gem's own act, not anyone's decision.
+  #
+  # Each returns the number of rows it moved, which is what M3b-3's rake tasks report. Rows are
+  # read into an array first: a sweep whose scope stops matching as it works should still visit
+  # everything it set out to.
+  #
+  # `close_due_stages!` is **M9b** - a cooldown window has to exist before a stage can be due.
+  module Maintenance
+    module_function
+
+    # `pending` / `approved` past `expires_at` become `expired`. The query is the same
+    # `Request.expired_candidates` that `Guards::Expire` agrees with status for status (§8).
+    def expire_stale!(now: Time.current)
+      sweep(Request.expired_candidates(now)) { |request| Commands::Expire.call(request: request) }
+    end
+
+    # `executing` rows whose attempt nobody ever settled. T1 committed the claim and then the
+    # process died; `executing` is the one status no other command will move, so without this the
+    # row sits there forever (§8).
+    def reap_stuck_executions!(older_than: Guards::Reap::DEFAULT_STUCK_AFTER)
+      sweep(Request.stuck_executions(older_than)) do |request|
+        Commands::Reap.call(request: request, older_than: older_than)
+      end
+    end
+
+    # Non-final requests whose `operation_key` is no longer declared (§5.11). Deliberately not
+    # automatic: a missing declaration is as likely to be a deploy accident as a deliberate
+    # removal, and `canceled` is final - so this runs when an operator asks for it.
+    def cancel_undeclared!
+      sweep(Request.undeclared) { |request| Commands::CancelUndeclared.call(request: request) }
+    end
+
+    def sweep(scope, &)
+      rows = scope.to_a
+      rows.each(&)
+
+      rows.size
+    end
+  end
+end

data/lib/change_requests/models/request.rb

@@ -53,6 +53,24 @@ module ChangeRequests
       where(status: %w(pending approved)).where(expires_at: ...now)
     }
 
+    # What Maintenance.reap_stuck_executions! sweeps (§8): claimed, and nothing ever settled the
+    # attempt. Inclusive at the cutoff, as Guards::Reap is - a spec asserts the two agree.
+    scope :stuck_executions, lambda { |older_than = Guards::Reap::DEFAULT_STUCK_AFTER|
+      claimed = Attempt.in_flight.where(started_at: ..(Time.current - older_than))
+
+      where(status: "executing").where(id: claimed.select(:change_request_id))
+    }
+
+    # What Maintenance.cancel_undeclared! sweeps (§5.11). `executing` is excluded deliberately:
+    # Guards::Cancel refuses a request mid-flight, and being undeclared does not make it
+    # recallable - the reaper is what clears those.
+    scope :undeclared, lambda {
+      declared = ChangeRequests.operations.keys
+      candidates = where(status: OPEN_STATUSES - %w(executing))
+
+      declared.empty? ? candidates : candidates.where.not(operation_key: declared)
+    }
+
     def current_stage
       stages.find_by(position: current_stage_position)
     end

data/lib/change_requests/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ChangeRequests
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/change_requests.rb

@@ -57,6 +57,39 @@ module ChangeRequests
                             payload: payload, tenant: tenant)
     end
 
+    # §8's background mode, on the same terms as the engine: idempotent, public, and guarded so
+    # requiring the gem in a process without ActiveJob defines no job at all. A host that loads
+    # ActiveJob after this gem calls it again - the engine does that automatically on_load.
+    def load_execution_job!
+      # archspec:disable-next-line dependencies.forbid -- the loader must name what it loads (§1)
+      return false if defined?(ChangeRequests::Execution::Job)
+      # archspec:disable-next-line constants.forbid -- the guard that keeps ActiveJob optional (§8)
+      return false unless defined?(::ActiveJob::Base)
+
+      require_relative "change_requests/execution/job"
+
+      true
+    end
+
+    # What a headless process asks before trusting `execution_mode = :background`.
+    def background_available?
+      # archspec:disable-next-line dependencies.forbid -- the same reference, as a question (§8)
+      defined?(ChangeRequests::Execution::Job) ? true : false
+    end
+
+    # The configured job class, resolved at enqueue time and never held: a reloading application
+    # redefines it, and §10 makes the setting a string for that reason.
+    def background_job!
+      job = config.job_class.to_s.safe_constantize
+
+      return job unless job.nil?
+
+      fail ConfigurationError,
+           "config.execution_mode is :background but config.job_class " \
+           "(#{config.job_class.inspect}) does not resolve. ChangeRequests::Execution::Job is " \
+           "defined only where ActiveJob is loaded, which this process has not done (§8)."
+    end
+
     def configure
       yield(config)
 
@@ -97,8 +130,10 @@ module ChangeRequests
         loader.ignore("#{__dir__}/change_requests/version.rb")
         loader.ignore("#{__dir__}/change_requests/errors.rb")
 
-        # Autoloading it would let an eager load in a headless process require Rails.
+        # Autoloading either would let an eager load pull in something optional: Rails for the
+        # engine, ActiveJob for the job - which defines nothing at all when ActiveJob is absent.
         loader.ignore("#{__dir__}/change_requests/engine.rb")
+        loader.ignore("#{__dir__}/change_requests/execution/job.rb")
 
         loader.setup
       end
@@ -108,3 +143,4 @@ end
 
 ChangeRequests.setup_loader
 ChangeRequests.load_engine!
+ChangeRequests.load_execution_job!