change_requests 0.2.0 → 0.2.2

data/lib/change_requests/configuration.rb

@@ -12,7 +12,9 @@ module ChangeRequests
     attr_accessor :actor_label_strategy, :actor_identity
 
     # Authorization (§9.2)
-    attr_accessor :authorization, :default_permission_match
+    attr_reader :authorization
+    # The default only; every quorum carries its own (§5.3).
+    attr_accessor :default_permission_match
 
     # Separation of duties (§8, §8.1)
     attr_accessor :approver_may_execute, :requester_may_execute, :requester_may_override
@@ -39,6 +41,16 @@ module ChangeRequests
       @default_expires_in     = nil
     end
 
+    # §9.2 tells hosts to assign a bare lambda; the gem needs one object answering `allows?`.
+    def authorization=(policy)
+      @authorization =
+        if policy.respond_to?(:allows?) || !policy.respond_to?(:call)
+          policy # validate! reports anything that answers neither
+        else
+          Authorization::Callable.new(policy)
+        end
+    end
+
     # Reopens an existing registration rather than replacing it: two initializers may each
     # contribute part of one.
     def actor_type(name)
@@ -64,6 +76,7 @@ module ChangeRequests
         label_strategy_problem,
         permission_match_problem,
         actor_identity_problem,
+        authorization_problem,
         max_attempts_problem,
         *actor_types.values.flat_map(&:problems),
         *tenant_types.values.flat_map(&:problems),
@@ -117,6 +130,14 @@ module ChangeRequests
         "such as `->(actor) { actor.person_id }` (§9.4)."
     end
 
+    def authorization_problem
+      return if authorization.respond_to?(:allows?)
+
+      "config.authorization is #{authorization.inspect}. Expected " \
+        "ChangeRequests::Authorization::Permissions.new, another object answering " \
+        "`allows?(actor:, quorum:)`, or a lambda taking (actor:, request:, stage:, action:) (§9.2)."
+    end
+
     def max_attempts_problem
       return if default_max_attempts.is_a?(Integer) && default_max_attempts >= 1
 

data/lib/change_requests/errors.rb

@@ -22,31 +22,17 @@ module ChangeRequests
   #   └── StaleRequest                  (optimistic lock conflict)
   class Error < StandardError; end
 
-  # Raised by config.validate! and operations.verify!. Message lists every problem found at once.
-  class ConfigurationError < Error; end
-
-  # Raised before the type string is constantized, so a typo fails at creation, not at render time.
-  class UnknownActorType < Error; end
-
-  # No live declaration for the request's operation_key. Every guard refuses except Comment (§5.11).
-  class UnknownOperation < Error; end
-
-  # Payload is not a JSON object. Matching it to the target's signature is the host's job (§6.12).
-  class InvalidPayload < Error; end
-
-  # A creation-time fact was reassigned. Raised by Concerns::ReadonlyAttributes, not attr_readonly.
-  class ReadonlyAttribute < Error; end
-
-  # The actor may never do this. "Not yet" is a TransitionError.
-  class NotAuthorized < Error; end
-
-  # A transition the request will not accept (§7.2). Carries #request and #reason:
+  # What every refusal a guard raises carries (§7). `reason` is the contract - controllers branch on
+  # it, views render it as a disabled button's tooltip. The message is for humans.
   #
   #   fail NotApprovable.new(request:, reason: :already_decided)
   #
-  # `reason` is the contract - controllers branch on it, views render it as a disabled button's
-  # tooltip. The message is for humans.
-  class TransitionError < Error
+  # A module rather than a base class, because §8 keeps NotAuthorized a *sibling* of the
+  # TransitionError family: "the actor may never do this" is a different answer from "not yet", and
+  # a host rescues them apart. Guards::Base#check! builds whichever class a guard declared with the
+  # same two keywords, so both have to accept them - without this, Ruby folds the keywords into the
+  # message and the reason is silently lost.
+  module Refusal
     # Shared with the guards, so a disabled button and a raised error cannot word :not_pending
     # differently. M1b-13 ships the translations.
     I18N_SCOPE = "change_requests.errors"
@@ -60,11 +46,19 @@ module ChangeRequests
       super(message || translated_message)
     end
 
-    def i18n_key = "#{I18N_SCOPE}.#{reason || self.class.error_key}"
+    def i18n_key
+      "#{I18N_SCOPE}.#{reason || self.class.error_key}"
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
 
-    # NotApprovable => "not_approvable". Used when a caller raised without a reason.
-    def self.error_key
-      name.split("::").last.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase
+    module ClassMethods
+      # NotApprovable => "not_approvable". Used when a caller raised without a reason.
+      def error_key
+        name.split("::").last.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase
+      end
     end
 
     private
@@ -76,6 +70,31 @@ module ChangeRequests
     end
   end
 
+  # Raised by config.validate! and operations.verify!. Message lists every problem found at once.
+  class ConfigurationError < Error; end
+
+  # Raised before the type string is constantized, so a typo fails at creation, not at render time.
+  class UnknownActorType < Error; end
+
+  # No live declaration for the request's operation_key. Every guard refuses except Comment (§5.11).
+  class UnknownOperation < Error; end
+
+  # Payload is not a JSON object. Matching it to the target's signature is the host's job (§6.12).
+  class InvalidPayload < Error; end
+
+  # A creation-time fact was reassigned. Raised by Concerns::ReadonlyAttributes, not attr_readonly.
+  class ReadonlyAttribute < Error; end
+
+  # The actor may never do this. "Not yet" is a TransitionError.
+  class NotAuthorized < Error
+    include Refusal
+  end
+
+  # A transition the request will not accept (§7.2).
+  class TransitionError < Error
+    include Refusal
+  end
+
   class NotApprovable < TransitionError; end
   class NotUnapprovable < TransitionError; end
   class NotRejectable < TransitionError; end

data/lib/change_requests/guards/approve.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module ChangeRequests
+  module Guards
+    # May this actor approve this request right now (§7, §7.2)?
+    #
+    # The branch order is the contract: it decides which reason a user sees, and "not your turn yet"
+    # is a different answer from "you cannot approve this at all".
+    class Approve < Base
+      refuses_with NotApprovable
+
+      def refusal
+        return :not_pending unless request.pending?
+        # Never configurable. There is no config.requester_may_approve to read, in any form (I5).
+        return :requester if same_person?(request.requester, actor)
+        return :stage_not_current if eligible_quorums.empty? && eligible_on_another_stage?
+        return :already_decided if already_decided?
+        return :not_permitted if eligible_quorums.empty?
+
+        nil
+      end
+
+      # The subset an approval actually links to. Equal in M1; M9a makes it a strict subset under
+      # all_quorums, where an approval links to exactly one quorum - the lowest-position one the
+      # actor qualifies for - so one person cannot close two quorums that must both be met (§5.3).
+      def countable_quorums
+        eligible_quorums
+      end
+    end
+  end
+end

data/lib/change_requests/guards/base.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+module ChangeRequests
+  module Guards
+    # One guard object, consulted by both the command and the presenter, so a disabled button and a
+    # raised error cannot disagree about why something is refused (§7).
+    #
+    #   class Approve < Base
+    #     refuses_with NotApprovable
+    #
+    #     def refusal
+    #       return :not_pending unless request.pending?
+    #       ...
+    #     end
+    #   end
+    #
+    # Subclasses implement `refusal` and return nil when they permit the transition. The
+    # undeclared-operation check runs first, here, so no guard has to repeat it (§5.11).
+    class Base
+      # The shared vocabulary. `reason` is the contract - controllers branch on these symbols and
+      # views render them as a disabled button's tooltip - so a guard picks one from this list
+      # rather than inventing wording. M1b-13 translates every entry.
+      REASONS = %i(
+        operation_undeclared
+        not_pending
+        requester
+        stage_not_current
+        stage_not_open
+        already_decided
+        not_the_approver
+        not_permitted
+        already_finalized
+        executing
+        reason_required
+        body_required
+        may_not_request
+        not_approved
+        attempts_exhausted
+        not_expired
+        not_expirable
+        not_system
+      ).freeze
+
+      attr_reader :request, :actor, :options
+
+      class_attribute :declared_error_class, instance_accessor: false
+      class_attribute :exempt_from_undeclared_operation, instance_accessor: false, default: false
+
+      class << self
+        # Declared, never derived from the guard's name: Create, Comment and Expire refuse with
+        # NotAuthorized, the rest with their own TransitionError.
+        def refuses_with(error_class)
+          self.declared_error_class = error_class
+        end
+
+        def error_class
+          declared_error_class ||
+            fail(ConfigurationError, "#{name} must declare `refuses_with <error class>` (§7)")
+        end
+
+        # Comment only. A request stranded by a removed declaration is exactly the one someone needs
+        # to leave a note on, and a comment writes no lifecycle state (§5.11, I8).
+        def exempt_from_undeclared_operation!
+          self.exempt_from_undeclared_operation = true
+        end
+      end
+
+      def initialize(request:, actor:, **options)
+        @request = request
+        @actor   = actor
+        @options = options
+      end
+
+      def allowed?
+        reason.nil?
+      end
+
+      def reason
+        return :operation_undeclared if operation.nil? && !self.class.exempt_from_undeclared_operation
+
+        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
+
+      def check!
+        return request if allowed?
+
+        fail error_for(reason).new(request: request, reason: reason)
+      end
+
+      # Subclasses override. nil permits.
+      def refusal
+        nil
+      end
+
+      def config
+        ChangeRequests.config
+      end
+
+      # Resolved live, never from the columns on the row: those are audit data, and a request whose
+      # operation is no longer declared can never run (§6.12).
+      def operation
+        ChangeRequests.operations[request.operation_key]
+      end
+
+      def stage
+        request.current_stage
+      end
+
+      # Pluggable: the permission rows by default, or the host's own policy (§9.2).
+      def authorization
+        config.authorization
+      end
+
+      # The quorums of the current stage this actor qualifies for - the same predicate
+      # Request.awaiting_approval_from runs in SQL (§5.3). Shared by every guard that asks whether
+      # someone is an eligible approver: Approve, Reject, Cancel and Comment.
+      def eligible_quorums
+        @eligible_quorums ||= qualifying(stage&.quorums&.pending)
+      end
+
+      # §7.2's preamble: "eligible approver" means eligible for at least one quorum on *any* stage of
+      # this request, by permission or by name. A stage-three director may cancel or comment on a
+      # request sitting in stage one. Approve and Reject are the narrower, current-stage question.
+      def eligible_approver?
+        eligible_quorums.any? || eligible_on_another_stage?
+      end
+
+      # §6.9: a stage-three director sitting on a stage-one request is told to wait, not refused.
+      def eligible_on_another_stage?
+        request.stages.where.not(id: stage&.id).any? { |other| qualifying(other.quorums).any? }
+      end
+
+      # One decision per stage per person. When the host declares a shared identity it is used in
+      # place of (type, id), so one human cannot decide twice through two actor classes (§9.4).
+      def already_decided?
+        return false if stage.nil?
+
+        decided_by_reference? || decided_by_identity?
+      end
+
+      # The acting actor as the columns store them. Raises UnknownActorType for an unregistered
+      # class, which is the allowlist doing its job (§9.1).
+      def actor_ref
+        @actor_ref ||= ChangeRequests.actor_attributes(actor)
+      end
+
+      # Is this the same human twice? `(type, id)` is airtight within one actor class and blind
+      # across them, which `config.actor_identity` is the opt-in fix for (§9.4). Either side may be
+      # a live actor object or a stored reference triple.
+      def same_person?(one, other)
+        return false if one.nil? || other.nil?
+
+        left  = identity_of(one)
+        right = identity_of(other)
+
+        return left == right if left && right
+
+        reference_of(one) == reference_of(other)
+      end
+
+      private
+
+      def error_for(reason)
+        REASON_ERRORS.fetch(reason) { self.class.error_class }
+      end
+
+      def qualifying(quorums)
+        return [] if quorums.nil?
+
+        quorums.select { |quorum| authorization.allows?(actor: actor, quorum: quorum) }
+      end
+
+      def decided_by_reference?
+        stage.approvals.exists?(approver_type: actor_ref[:type], approver_id: actor_ref[:id])
+      end
+
+      def decided_by_identity?
+        identity = identity_of(actor)
+
+        identity.present? && stage.approvals.exists?(approver_identity: identity)
+      end
+
+      def identity_of(subject)
+        return subject[:identity] if subject.is_a?(Hash)
+
+        config.actor_identity&.call(subject)
+      end
+
+      def reference_of(subject)
+        return subject.slice(:type, :id) if subject.is_a?(Hash)
+
+        ChangeRequests.actor_attributes(subject).slice(:type, :id)
+      end
+    end
+  end
+end

data/lib/change_requests/guards/cancel.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module ChangeRequests
+  module Guards
+    # May this actor call the whole thing off (§7.2)?
+    #
+    # The requester, or any eligible approver - eligible for a quorum on *any* stage, not just the
+    # current one, per §7.2's preamble. Cancelling is a judgement about the request as a whole, not
+    # about the step it happens to be sitting on.
+    #
+    # The reason is mandatory and `Commands::Cancel` enforces it, for the reason Reject does (Q25).
+    class Cancel < Base
+      refuses_with NotCancelable
+
+      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).
+        return :executing if request.executing?
+        return :not_permitted unless requester? || eligible_approver?
+
+        nil
+      end
+
+      private
+
+      def requester?
+        same_person?(request.requester, actor)
+      end
+    end
+  end
+end

data/lib/change_requests/guards/comment.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module ChangeRequests
+  module Guards
+    # May this actor leave a note (§7.2)?
+    #
+    # The requester, or any eligible approver - eligible for a quorum on *any* stage, like Cancel.
+    # Beyond that it refuses nothing: every final status, and a request whose operation is no longer
+    # declared, both stay open to comment. A comment writes no request column, so the terminal-state
+    # guard is never in its way, and post-mortem notes on a finished request are the point of an
+    # audit trail (§5.5).
+    #
+    # This is the one guard exempt from the undeclared-operation refusal (§5.11, I8): a request
+    # stranded by a removed declaration is exactly the one somebody needs to leave a note on.
+    class Comment < Base
+      refuses_with NotAuthorized
+      exempt_from_undeclared_operation!
+
+      def refusal
+        return :not_permitted unless requester? || eligible_approver?
+
+        nil
+      end
+
+      private
+
+      def requester?
+        same_person?(request.requester, actor)
+      end
+    end
+  end
+end

data/lib/change_requests/guards/execute.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module ChangeRequests
+  module Guards
+    # May this actor execute this request (§7.2, §8)?
+    #
+    # **Guard only.** `Commands::Execute`, the claim-then-invoke machinery and the §8.1 override
+    # branch are M3a (decision D2). The guard's inputs are all M1 state; the claim is not.
+    #
+    # Separation of duties is the one rule here with no counterpart in the other guards. `Approve`
+    # refuses the requester by identity and consults nothing (I5); `Execute` refuses them *unless*
+    # `config.requester_may_execute`, which defaults to false. Both use `same_person?`, so "is this
+    # the same human" is answered identically - including through `config.actor_identity` (§9.4).
+    class Execute < Base
+      EXECUTABLE_STATUSES = %w(approved failed).freeze
+
+      refuses_with NotExecutable
+
+      def refusal
+        # `successful` is final, and "already done" is a better answer than "not approved".
+        return :already_finalized if request.final?
+        return :not_approved unless EXECUTABLE_STATUSES.include?(request.status)
+        return :attempts_exhausted if request.failed? && !request.retryable?
+        return :not_permitted unless actor_type.may_execute
+        return :requester if requester? && !config.requester_may_execute
+        return :not_permitted if approver? && !config.approver_may_execute
+
+        nil
+      end
+
+      private
+
+      def actor_type
+        config.actor_types.fetch(actor_ref[:type])
+      end
+
+      def requester?
+        same_person?(request.requester, actor)
+      end
+
+      # Who actually decided, not who was merely eligible to: `approver_may_execute` is about
+      # having spent a decision on this request, and it defaults to true.
+      def approver?
+        request.approvals.exists?(approver_type: actor_ref[:type], approver_id: actor_ref[:id])
+      end
+    end
+  end
+end

data/lib/change_requests/guards/expire.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module ChangeRequests
+  module Guards
+    # May this request be expired right now (§7.2, §8)?
+    #
+    # System only. Expiry has no human behind it, so an actor being supplied at all is the refusal -
+    # nobody expires a request on purpose, the clock does.
+    #
+    # Every refusal here is NotAuthorized rather than a TransitionError, apart from the shared
+    # :already_finalized mapping. The only caller is M3b's `Maintenance.expire_stale!`, whose query
+    # already filters on status and `expires_at`, so these branches are a floor beneath it and never
+    # a user-facing flash (Q32).
+    class Expire < Base
+      EXPIRABLE_STATUSES = %w(pending approved).freeze
+
+      refuses_with NotAuthorized
+
+      def refusal
+        return :not_system unless actor.nil?
+        return :already_finalized if request.final?
+        return :not_expirable unless EXPIRABLE_STATUSES.include?(request.status)
+        return :not_expired unless expired?
+
+        nil
+      end
+
+      private
+
+      # A null `expires_at` never expires (§5.1), which is the default: `config.default_expires_in`
+      # and `op.expires_in` are both nil until a host says otherwise.
+      def expired?
+        request.expires_at.present? && request.expires_at <= Time.current
+      end
+    end
+  end
+end

data/lib/change_requests/guards/reject.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module ChangeRequests
+  module Guards
+    # May this actor reject this request (§7.1, §7.2)?
+    #
+    # An eligible approver of the current open stage, or the requester - who may always stop their
+    # own request.
+    #
+    # It says nothing about the reason. The reason is mandatory, but a Reject button is what *opens*
+    # the form that collects it, so a guard refusing without one could never let the button appear.
+    # `Commands::Reject` enforces it (Q25).
+    class Reject < Base
+      refuses_with NotRejectable
+
+      def refusal
+        return :not_pending unless request.pending?
+        return :stage_not_current if !permitted_here? && eligible_on_another_stage?
+        return :already_decided if already_decided?
+        return :not_permitted unless permitted_here?
+
+        nil
+      end
+
+      private
+
+      def permitted_here?
+        requester? || eligible_quorums.any?
+      end
+
+      # Rejection is the one decision the requester may take on their own request: stopping
+      # something you asked for needs no four-eyes (§7.2).
+      def requester?
+        same_person?(request.requester, actor)
+      end
+    end
+  end
+end

data/lib/change_requests/guards/unapprove.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module ChangeRequests
+  module Guards
+    # May this actor take their own decision back (§7.1, §7.2)?
+    #
+    # Only the actor who gave it, and only while the stage they gave it on is still open. Cooldown
+    # is M9b, so "open" means `pending` here.
+    class Unapprove < Base
+      refuses_with NotUnapprovable
+
+      def refusal
+        return :not_pending unless request.pending?
+        return :not_the_approver if decision.nil?
+        return :stage_not_open unless decision.stage.pending?
+
+        nil
+      end
+
+      # The row this actor is retracting - an approval, or a rejection recorded without
+      # short-circuiting (§7.1). The command needs it, so it is resolved once, here.
+      #
+      # Matched on (type, id) alone. config.actor_identity says who *counts* as one person when
+      # tallying approvers (§9.4); retracting is about which row this actor wrote, and one actor
+      # undoing another's row would make the trail say something untrue.
+      def decision
+        return @decision if defined?(@decision)
+
+        @decision = mine.find_by(change_request_stage_id: stage&.id) || mine.first
+      end
+
+      private
+
+      def mine
+        request.approvals
+               .where(approver_type: actor_ref[:type], approver_id: actor_ref[:id])
+               .order(decided_at: :desc)
+      end
+    end
+  end
+end

data/lib/change_requests/models/approval.rb

@@ -26,7 +26,7 @@ module ChangeRequests
                                 inverse_of: :approval
     has_many :quorums, through: :approval_quorums, source: :quorum
 
-    actor_reference :approver
+    actor_reference :approver, identity: true
 
     validates :decided_at, presence: true
 

data/lib/change_requests/models/attempt.rb

@@ -34,7 +34,9 @@ module ChangeRequests
       define_method(:"#{value}?") { outcome == value }
     end
 
-    def finished? = outcome.present?
+    def finished?
+      outcome.present?
+    end
 
     # What the retry ceiling counts against `max_attempts` (§8).
     def self.next_number_for(change_request)