change_requests 0.2.5 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7790d14f78ffa0b667712d827db6cc77d527dd9f733582b95b0a43ca4372d156
-  data.tar.gz: 21b70a37fe29a796e855571f82901d1e098328ec5b0d567335c5982b0622ccce
+  metadata.gz: 5121ac3d2657395d7e5587ab4cbed6ef9338bb17a15be4c7252ebd09a9a68202
+  data.tar.gz: 1255001fa45221fee226d66e986666e2a6b5f8fb417ffea8c89bb9069c8e7c9d
 SHA512:
-  metadata.gz: 9fe5fea5c0e07c85cbac8ca55ec947ce59d1a999ec9cfc99d3cd1beeb0615ced473e41ae89f2a2561f7edfeb20c24102a751ffe4eb4b84111df3abff8ca234fd
-  data.tar.gz: bb3d6b92463ba8c4833400c35b99f1de62fc0304e31203b2d34e8f6e3ef3aef81aba2c4c83886cf296db76f3526d473ca2cea1a01c53ccfce56613d454746a94
+  metadata.gz: 0627a54b60fe7cf7d2ad407f2f52227b28605b36a4c4b97bdb833a532155962d9d9dcde116feeb38d7b6ad13c154809be2b000de39e0d4e689950aa5ee2887b6
+  data.tar.gz: cb8d036a00b8f9cca8dab2d0ff00c9df9b0737662ea913072b93dce704d239cb39ae4bb46d203c9b93bdce729eceeefbe2da15f705980e235952e58adeec2bc0

data/CLAUDE.md

@@ -17,3 +17,21 @@ Act as a Senior Technical Lead and Subject Matter Expert.
 ## Rules
 
 Additionally read and follow: ~/.gemini/config/AGENTS.md and AGENTS.md
+
+## Plan and ADRs
+
+The Plan will stay in the branch "plan", you must not commit on branch plan or push branch plan.
+You are allowed to edit the Plan files on branch plan.
+
+Under docs/adr you will find architectural decision records. They are maintained by a human, you should not update them, unless explicitly asked.
+
+## Working on a new Ticket
+
+Ask me, if any implementation detail for this ticket is unclear or undecided.
+
+You will create a new branch for every ticket. base it off main, which has usually been updated with the prior work.
+
+When you you are done working on a ticket:
+  * push your work to a remote branch with the same name as your new local worktree branch
+  * create a PR
+  * remove your worktree access, but keep the local branch

data/README.md

@@ -28,6 +28,31 @@ gem install change_requests
 
 TODO: Write usage instructions here
 
+## The target contract
+
+The gem asks one thing of the code it executes on your behalf. A change-request target is a **public
+singleton method** that accepts **keyword arguments only**, and whose effect is **idempotent**: running it
+twice with the same payload must leave the same result as running it once.
+
+```ruby
+class Members::UpdateRoles
+  def self.call(member_id:, roles:, change_request_id: nil)
+    Member.find(member_id).update!(roles: roles)
+  end
+end
+```
+
+There is no flag to declare otherwise. A failed request keeps its approval and is retried up to
+`op.max_attempts`, so a target that cannot meet the requirement must leave that at `1` — the retry ceiling
+is what bounds a repeated effect, and it is the only bound the gem can actually enforce.
+
+A target that declares `change_request_id:` receives it, stable across every attempt, which one calling an
+external API can pass on as that API's own idempotency key.
+
+`rake change_requests:verify` checks the half of this that is checkable: that every declared service
+resolves, and that it answers the singleton method dispatch will call. Idempotence it cannot check, and
+does not try.
+
 ## Architecture
 
 The decisions behind the gem's shape — and what each one costs — are recorded as ADRs in

data/config/locales/en.yml

@@ -42,14 +42,12 @@ en:
       quorum_not_met: "This request does not have the approvals it needs."
       transition_error: "This request will not accept that."
 
-    # Stage and quorum names are declaration identifiers, not display text (§5.9). A host adds a key
-    # per name it declares; anything unlisted falls back to `name.humanize`, so "sign_off" reads as
-    # "Sign off" with no locale entry at all.
+    # Stage and quorum names are declaration identifiers, not display text (§5.9). The host names
+    # every stage, so the gem ships no entry here at all: a host adds a key per name it declares,
+    # and anything unlisted falls back to `name.humanize` - "sign_off" reads as "Sign off" with no
+    # locale entry.
     #
     #   stages:
     #     sign_off: "Director sign-off"
     #   quorums:
     #     owners: "Owners"
-    stages:
-      # The only name the gem itself creates - `op.approvals` builds one stage called this.
-      approval: "Approval"

data/lib/change_requests/authorization/permissions.rb

@@ -8,6 +8,15 @@ module ChangeRequests
     # `Request.awaiting_approval_from`, so "the button is enabled" and "it appears in my inbox"
     # cannot drift apart.
     class Permissions
+      # Through the actor type's own lambda, never through a method on the actor: User and Admin may
+      # derive their permissions completely differently and still be compared against one
+      # definition (§9.2). Also read by Guards::Execute's override branch, which has no quorum.
+      def self.held_by(actor, type)
+        return [] if type.nil? || type.permissions.nil?
+
+        Array(type.permissions.call(actor)).map(&:to_s)
+      end
+
       # `action` is ignored here - eligibility is the same question whichever command asks it. It
       # exists because Authorization::Callable hands it on to the host's own policy.
       def allows?(actor:, quorum:, action: :approve) # rubocop:disable Lint/UnusedMethodArgument
@@ -61,13 +70,8 @@ module ChangeRequests
           (row.actor_type.nil? || row.actor_type == actor.class.name)
       end
 
-      # Through the actor type's own lambda, never through a method on the actor: User and Admin may
-      # derive their permissions completely differently and still be compared against one stage
-      # definition (§9.2).
       def permissions_of(actor, type)
-        return [] if type.permissions.nil?
-
-        Array(type.permissions.call(actor)).map(&:to_s)
+        self.class.held_by(actor, type)
       end
     end
   end

data/lib/change_requests/commands/claim_execution.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module ChangeRequests
+  module Commands
+    # §8's **T1**: the claim. Guard, take the row, write the attempt, emit - and commit, so the
+    # claim is visible to every other process *before* the target runs.
+    #
+    # An **internal** command, like EvaluateWorkflow: hosts call `Commands::Execute`, which reaches
+    # it through `Execution::Runner`. It is a command rather than a Runner method because every
+    # event in the gem is written by one, through one `emit` (ADR 0016).
+    class ClaimExecution < Base
+      CLAIMABLE = %w(approved failed).freeze
+
+      # §8.1: an override claims a request that never reached `approved`.
+      OVERRIDE_CLAIMABLE = %w(pending).freeze
+
+      def self.call(request:, actor:, override: false, reason: nil)
+        new(request: request, actor: actor, override: override, reason: reason).call
+      end
+
+      # The attempt, which T3 finishes.
+      def perform
+        authorize!
+        refuse_without_reason
+        claim!
+        record_override if override?
+        attempt = start_attempt
+        emit(:execution_started, metadata: { attempt: attempt.number })
+
+        attempt
+      end
+
+      private
+
+      def authorize!
+        Guards::Execute.new(request: request, actor: actor, override: override?).check!
+      end
+
+      def override?
+        options[:override] ? true : false
+      end
+
+      def reason
+        options[:reason]
+      end
+
+      # After the guard, following M1b-7's shape (Q25): someone who may not override at all should
+      # not be told they merely forgot a sentence.
+      def refuse_without_reason
+        return unless override?
+        return unless operation.override_policy.require_reason?
+        return if reason.present?
+
+        fail OverrideNotPermitted.new(request: request, reason: :reason_required)
+      end
+
+      # §8.1: at claim time, inside T1, carrying the shortfall exactly as it stood. A later
+      # approval must not be able to make an override look retrospectively unnecessary.
+      def record_override
+        request.update!(overridden_at: Time.current)
+        emit(:overridden, body: reason, metadata: shortfall)
+      end
+
+      # Scoped to what is still missing rather than to the whole workflow: what an auditor asks is
+      # how far short this request was when someone went ahead anyway.
+      def shortfall
+        stages  = request.stages.reject { |stage| stage.satisfied? || stage.closed? }
+        quorums = stages.flat_map { |stage| stage.quorums.reject(&:satisfied?) }
+
+        {
+          approvals_present: quorums.sum { |quorum| quorum.approval_quorums.count },
+          approvals_required: quorums.sum(&:threshold),
+          incomplete_stages: stages.map(&:name),
+          # Omitted rather than null for a single-quorum stage, as every other event does (§5.9).
+          incomplete_quorums: quorums.filter_map(&:name),
+        }
+      end
+
+      # §8's conditional UPDATE. The guard ran under this transaction's own FOR UPDATE, so in the
+      # ordinary race the loser is already refused `:executing` and never arrives here. This is the
+      # invariant beneath that: zero rows means somebody else holds the claim, whatever route got
+      # here - a background re-entry, or a caller reaching the runner without the guard.
+      def claim!
+        claimed = Request.where(id: request.id, status: claimable)
+                         .update_all(status: "executing", updated_at: Time.current)
+
+        refuse_claimed if claimed.zero?
+
+        request.reload
+      end
+
+      def claimable
+        override? ? OVERRIDE_CLAIMABLE : CLAIMABLE
+      end
+
+      # The unique index on (change_request_id, number) is the claim's second lock: two processes
+      # cannot both create attempt 3, whatever they believe about the status column (§5.6).
+      def start_attempt
+        request.attempts.create!(number: Attempt.next_number_for(request),
+                                 executer: actor, started_at: Time.current)
+      rescue ActiveRecord::RecordNotUnique
+        refuse_claimed
+      end
+
+      def refuse_claimed
+        fail ExecutionInProgress,
+             "Change request #{request.id} is already being executed. The claim is committed " \
+             "before the target runs, so another process holds this attempt (§8)."
+      end
+    end
+  end
+end

data/lib/change_requests/commands/create.rb

@@ -11,7 +11,7 @@ module ChangeRequests
     #     tenant:        current_organization      # optional
     #   )
     #
-    # M2 wraps this as `ChangeRequests.request!`.
+    # `ChangeRequests.request!` is the host-facing wrapper (§6.5); this is the command itself.
     #
     # The call is identical however elaborate the workflow is: thresholds, permissions and quorum
     # structure come from the declaration, never from the caller (§6.12 point 3).
@@ -64,20 +64,11 @@ module ChangeRequests
         declaration
       end
 
-      # Both would otherwise surface as a NOT NULL violation or as a request that can never leave
-      # `pending`. M2's `verify!` catches them at boot; this is the backstop. Reported together,
-      # like Configuration#validate!: one call should fix one round of mistakes.
+      # The same `Operation#problems` that `verify!` reads at boot and `validate!` reads at
+      # declaration, so the three cannot disagree about what a complete declaration is (§7.2 †).
+      # This is the backstop: an operation mutated after it was declared still refuses here.
       def refuse_incomplete(declaration)
-        problems = []
-
-        if declaration.service.blank?
-          problems << "it declares no service, so nothing could ever execute it - set `op.service`"
-        end
-
-        if declaration.workflow.empty?
-          problems << "it declares no approvals, so a request could never be approved - " \
-                      "declare `op.approvals`"
-        end
+        problems = declaration.problems
 
         return if problems.empty?
 

data/lib/change_requests/commands/execute.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module ChangeRequests
+  module Commands
+    # §6.6's sixth command, in the shape of the other five: the request, the acting actor, and a
+    # typed error on refusal.
+    #
+    #   Commands::Execute.call(request:, actor: current_user)
+    #
+    # The work is §8's three transactions, so this is the one command that takes **no lock of its
+    # own**: `Execution::Runner` opens one per transaction, and none of them spans the target
+    # invocation. `Guards::Execute` runs inside T1, against the row it locked - a guard call out
+    # here would read an unlocked row and could disagree with the claim that follows it.
+    #
+    # `override: true` takes §8.1's branch: a different guard question, a claim from `pending`,
+    # `overridden_at`, and an `overridden` event carrying the shortfall. `Commands::Override` is
+    # the named entry point a host calls for it (Q7).
+    class Execute < Base
+      def self.call(request:, actor:, override: false, reason: nil)
+        new(request: request, actor: actor, override: override, reason: reason).call
+      end
+
+      def perform
+        Execution::Runner.call(request: request, actor: actor,
+                               override: options[:override], reason: options[:reason])
+      end
+
+      # Base locks around `perform`; §8 forbids holding one across T2. Create overrides this too,
+      # for the opposite reason - it has no row to lock until it has written one.
+      def around_perform
+        yield
+      end
+    end
+  end
+end

data/lib/change_requests/commands/override.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module ChangeRequests
+  module Commands
+    # §6.10's break-glass entry point: `Execute` with `override: true`, and a name that says so.
+    #
+    #   Commands::Override.call(request:, actor:, reason: "Provider outage, CFO approved by phone")
+    #
+    # A thin wrapper on purpose (Q7). §8.1 wants the exception to look like one, and
+    # `Execute.call(…, override: true)` buried in a controller does not. It also gives M5's
+    # presenter two distinct actions to render - `:execute` and `:execute_override`, the second
+    # `tone: :danger` and always confirmed - without branching on a boolean.
+    #
+    # A subclass rather than a delegation, so the rows and events it writes cannot drift from
+    # `Execute(override: true)`: there is nothing here to drift.
+    class Override < Execute
+      def self.call(request:, actor:, reason: nil)
+        new(request: request, actor: actor, override: true, reason: reason).call
+      end
+    end
+  end
+end

data/lib/change_requests/commands/settle_execution.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module ChangeRequests
+  module Commands
+    # §8's **T3**: what the target did. A separate transaction from T1 and from the invocation, so a
+    # 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.
+    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
+      end
+
+      def perform
+        error.nil? ? record_success : record_failure
+
+        request
+      end
+
+      private
+
+      def attempt
+        options.fetch(:attempt)
+      end
+
+      def error
+        options[:error]
+      end
+
+      def record_success
+        request.update!(status: "successful", executed_at: Time.current, executer: actor)
+        attempt.update!(outcome: "succeeded", finished_at: Time.current)
+        emit(:executed, metadata: { attempt: attempt.number })
+      end
+
+      # `failed` is not final: the request keeps its approval, and `retryable?` against max_attempts
+      # is the only thing bounding another go (§8).
+      def record_failure
+        request.update!(status: "failed")
+        attempt.update!(outcome: "failed", finished_at: Time.current, error_class: error.class.name,
+                        error_message: error.message, backtrace: bounded_backtrace)
+        emit(:execution_failed, body: error.message,
+             metadata: { attempt: attempt.number, error_class: error.class.name })
+      end
+
+      def bounded_backtrace
+        Array(error.backtrace).first(BACKTRACE_FRAMES).join("\n").presence
+      end
+    end
+  end
+end

data/lib/change_requests/engine.rb

@@ -19,5 +19,16 @@ module ChangeRequests
     config.after_initialize do
       ChangeRequests.config.validate!
     end
+
+    # §6.12 point 6, in development and test only: an operation broken by an edit fails the next
+    # request rather than the next deploy. Production runs `rake change_requests:verify` instead,
+    # because verify! constantizes every declared service and a booted app should not pay for that
+    # on every request cycle.
+    #
+    # Registered here rather than in the domain core, and it re-reads the registry on every run -
+    # a reload redefines the classes verify! resolved last time, so nothing may be held across one.
+    config.to_prepare do
+      ChangeRequests.operations.verify! if Rails.env.local?
+    end
   end
 end

data/lib/change_requests/execution/dispatcher.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module ChangeRequests
+  module Execution
+    # §6.12 points 1-2: the allowlist dispatch, and §8's T2 - the one step that holds no row lock.
+    #
+    #   Dispatcher.call(operation_key: "members.update_roles", payload:, change_request_id:)
+    #
+    # It takes a **key**, never a request row. `operation_key -> (service, method_name)` resolves
+    # from the live declaration, so the `service` and `method_name` columns stay audit data and a
+    # careless endpoint that writes a row cannot choose what runs (§6.12 point 1).
+    class Dispatcher
+      def self.call(operation_key:, change_request_id:, payload: {})
+        new(operation_key: operation_key, change_request_id: change_request_id, payload: payload).call
+      end
+
+      def initialize(operation_key:, change_request_id:, payload: {})
+        @operation_key     = operation_key.to_s
+        @change_request_id = change_request_id
+        @payload           = payload
+      end
+
+      # Whatever the target returns. §8's T3 records the outcome; this step only runs it.
+      def call
+        target.public_send(operation.method_name, **arguments)
+      end
+
+      private
+
+      attr_reader :operation_key, :change_request_id, :payload
+
+      # Before anything is constantized: an undeclared key never reaches a target name at all, and
+      # §5.11 words it the same way `Commands::Create` does.
+      def operation
+        return @operation if @operation
+
+        declaration = ChangeRequests.operations[operation_key]
+
+        fail UnknownOperation, "No operation is declared for #{operation_key.inspect} (§5.11)." if declaration.nil?
+
+        @operation = declaration
+      end
+
+      def contract
+        @contract ||= TargetContract.new(service: operation.service, method_name: operation.method_name)
+      end
+
+      def target
+        @target ||= TargetContract.target!(service: operation.service, method_name: operation.method_name)
+      end
+
+      # Top-level only, because that is what round-trips through jsonb: a nested hash keeps its
+      # string keys, and a target taking one should expect them (§6.12).
+      def arguments
+        keywords = validated_payload.symbolize_keys
+
+        return keywords unless contract.accepts?(:change_request_id)
+
+        # Ours wins over a payload key of the same name: it is the identity the gem guarantees is
+        # stable across every attempt, which is the whole reason a target would want it (§8).
+        keywords.merge(change_request_id: change_request_id)
+      end
+
+      def validated_payload
+        return payload if payload.is_a?(Hash)
+
+        fail InvalidPayload,
+             "payload must be a JSON object, got #{payload.class}. It is dispatched as " \
+             "`**payload.symbolize_keys`, so its keys become the target's keyword arguments (§6.12)."
+      end
+    end
+  end
+end

data/lib/change_requests/execution/runner.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module ChangeRequests
+  module Execution
+    # §8's three transactions, which are the whole double-execution fix:
+    #
+    #   T1  claim   with_lock, conditional UPDATE, attempt, execution_started, COMMIT
+    #   T2  invoke  no lock - may take seconds, may call an external API
+    #   T3  settle  with_lock, the outcome on the request and on the attempt, and its event
+    #
+    # The claim is committed before the side effect runs, which is what makes this stronger than
+    # one lock around all three: nothing in T2 holds the row, so the request is visibly `executing`
+    # to every other process and to the UI while the target works.
+    #
+    # `Commands::Execute` is the host-facing entry point (M3a-3); this is the machinery.
+    class Runner
+      def self.call(request:, actor:, override: false, reason: nil)
+        new(request: request, actor: actor, override: override, reason: reason).call
+      end
+
+      def initialize(request:, actor:, override: false, reason: nil)
+        @request  = request
+        @actor    = actor
+        @override = override
+        @reason   = reason
+      end
+
+      def call
+        attempt = Commands::ClaimExecution.call(request: request, actor: actor,
+                                                override: override, reason: reason)
+
+        begin
+          invoke
+        rescue StandardError => e
+          # Recorded before it is re-raised, and re-raised from inside this rescue so `#cause` is
+          # the target's own error. The attempt row carries its class too, so a host that needs to
+          # tell a misconfiguration from a flaky call reads `error_class` rather than unwrapping.
+          settle(attempt, e)
+
+          raise TargetFailed, "#{target_description} raised #{e.class}: #{e.message}"
+        end
+
+        settle(attempt, nil)
+      end
+
+      private
+
+      attr_reader :request, :actor, :override, :reason
+
+      def invoke
+        Dispatcher.call(operation_key: request.operation_key, payload: request.payload,
+                        change_request_id: request.id)
+      end
+
+      # From the declaration, never from the row's columns: those are the creation-time snapshot,
+      # and naming them here would report a target that did not run (§6.12 point 1).
+      def target_description
+        operation = ChangeRequests.operations[request.operation_key]
+
+        return request.operation_key if operation.nil?
+
+        "#{operation.service}.#{operation.method_name}"
+      end
+
+      def settle(attempt, error)
+        Commands::SettleExecution.call(request: request, actor: actor, attempt: attempt, error: error)
+      end
+    end
+  end
+end

data/lib/change_requests/execution/target_contract.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module ChangeRequests
+  module Execution
+    # §6.12's target contract, in one place: a **public singleton method** taking **keyword
+    # arguments only**. `Operation#target_problems` reads it at boot and `Dispatcher` at dispatch,
+    # so `verify!` and execution cannot word the same defect differently.
+    #
+    # Idempotence is the third half of the contract and is not here, because nothing can check it.
+    class TargetContract
+      # `:block` is not positional in the sense that matters - a target may take one and ignore it.
+      POSITIONAL = %i(req opt rest).freeze
+      KEYWORDS   = %i(key keyreq).freeze
+
+      def self.problem(service:, method_name:)
+        new(service: service, method_name: method_name).problem
+      end
+
+      # The constant, or a ConfigurationError carrying the same words `problem` would have returned.
+      # A target that cannot be dispatched is a declaration error, not a target failure: retrying it
+      # could never succeed, and M3a's retry ceiling exists for failures that might (§8).
+      def self.target!(service:, method_name:)
+        contract = new(service: service, method_name: method_name)
+        problem  = contract.problem
+
+        fail ConfigurationError, problem if problem
+
+        contract.target
+      end
+
+      def initialize(service:, method_name:)
+        @service     = service
+        @method_name = method_name
+      end
+
+      def target
+        @target ||= service.to_s.safe_constantize
+      end
+
+      def problem
+        return unresolved_service if target.nil?
+        return unanswered_method unless target.respond_to?(method_name)
+        return positional_arguments if positional_parameters.any?
+
+        nil
+      end
+
+      # Whether the target would accept this keyword: it declares it, or it forwards everything.
+      def accepts?(keyword)
+        parameters.any? do |kind, name|
+          kind == :keyrest || (KEYWORDS.include?(kind) && name == keyword)
+        end
+      end
+
+      private
+
+      attr_reader :service, :method_name
+
+      # A target answering through method_missing has no Method to inspect. Nothing can be proven
+      # about its parameters, so nothing is claimed: an empty list refuses nothing.
+      def parameters
+        @parameters ||= target.method(method_name).parameters
+      rescue NameError
+        @parameters = []
+      end
+
+      def positional_parameters
+        parameters.filter_map { |kind, name| name || kind if POSITIONAL.include?(kind) }
+      end
+
+      def unresolved_service
+        "op.service is #{service.inspect}, which does not resolve to a constant. Execution " \
+          "dispatches through the declaration, never through the strings on the row (§6.12 point 1)."
+      end
+
+      def unanswered_method
+        "#{service} does not answer .#{method_name}. Dispatch calls the public singleton method, so " \
+          "an instance method of the same name is not the one it will reach (§6.12)."
+      end
+
+      def positional_arguments
+        "#{service}.#{method_name} takes positional arguments " \
+          "(#{positional_parameters.join(", ")}). A change-request target accepts keyword arguments " \
+          "only - the payload is dispatched as `**payload.symbolize_keys` (§6.12)."
+      end
+    end
+  end
+end

data/lib/change_requests/guards/base.rb

@@ -81,10 +81,16 @@ module ChangeRequests
         refusal
       end
 
-      # One shared rule beside the declared class: a request that is already over is the same
-      # refusal whichever command met it, and the model's TerminalStateGuard raises exactly this
-      # with exactly this reason (§5.8). A host rescuing AlreadyFinalized catches both.
-      REASON_ERRORS = { already_finalized: AlreadyFinalized }.freeze
+      # Reasons the taxonomy gives a class of their own, raised in place of the guard's declared
+      # one. `already_finalized`: a request that is already over is the same refusal whichever
+      # command met it, and the model's TerminalStateGuard raises exactly this with exactly this
+      # reason (§5.8), so a host rescuing AlreadyFinalized catches both. `override_not_permitted`:
+      # §8.1's break-glass refusal is not an ordinary NotExecutable, and a host alerting on
+      # attempted overrides rescues it by name.
+      REASON_ERRORS = {
+        already_finalized: AlreadyFinalized,
+        override_not_permitted: OverrideNotPermitted,
+      }.freeze
 
       def check!
         return request if allowed?