plutonium 0.64.0 → 0.66.0

data/lib/plutonium/dashboard/dsl.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Dashboard
+    # The author-facing class macros: `metric`, `chart`, `card`, `refresh`
+    # and `width`. Mixed into {Base}.
+    module DSL
+      extend ActiveSupport::Concern
+
+      UNSET = Object.new
+      private_constant :UNSET
+
+      class_methods do
+        # The declared cards, in declaration order.
+        def cards
+          @cards ||= []
+        end
+
+        # A single number with an optional change indicator. The block returns
+        # the value, or a hash: `{value:, previous:}` / `{value:, change:, trend:}`.
+        #
+        #   metric(:orders, icon: Phlex::TablerIcons::ShoppingCart) { Order.count }
+        #   metric(:revenue, format: :currency, positive: :up) do
+        #     {value: Order.this_month.sum(:total), previous: Order.last_month.sum(:total)}
+        #   end
+        def metric(key, **options, &block)
+          add_card(key, kind: :metric, options:, block:)
+        end
+
+        # A Chartkick chart. The block returns Chartkick data: a `{label => value}`
+        # hash, an array of pairs, or an array of `{name:, data:}` series. Options
+        # other than `type:` / `height:` and the common card options are passed
+        # straight through to Chartkick (`colors:`, `stacked:`, `suffix:`, ...).
+        #
+        #   chart(:signups, type: :line, span: 8) { User.group_by_day(:created_at, last: 30).count }
+        def chart(key, **options, &block)
+          add_card(key, kind: :chart, options:, block:)
+        end
+
+        # A free-form card. The block renders Phlex markup inside the card body
+        # and can call the dashboard's own methods.
+        #
+        #   card(:recent, span: :full) do
+        #     ul { dashboard.recent_orders.each { |o| li { o.number } } }
+        #   end
+        def card(key, **options, &block)
+          add_card(key, kind: :custom, options:, block:)
+        end
+
+        # Default refresh interval (seconds) for every lazy card. A card's own
+        # `refresh:` overrides it; `refresh: false` on a card opts out.
+        def refresh(seconds = UNSET)
+          return @refresh if seconds.equal?(UNSET)
+
+          valid = seconds.nil? || (seconds.respond_to?(:to_i) && seconds.to_i.positive?)
+          raise ArgumentError, "refresh must be a positive number of seconds or nil, got #{seconds.inspect}" unless valid
+
+          @refresh = seconds&.to_i
+        end
+
+        # Page width, one of {Plutonium::UI::PageWidth::SIZES}. Defaults to
+        # `:full`: a card grid wants the room an index page gets, not the
+        # reading column detail pages are constrained to.
+        def width(value = UNSET)
+          return @width || :full if value.equal?(UNSET)
+
+          @width = Plutonium::UI::PageWidth.validate!(value)
+        end
+
+        # @return [Card, nil]
+        def find_card(key)
+          key = key.to_s
+          cards.find { |card| card.key.to_s == key }
+        end
+
+        # @return [Card]
+        # @raise [UnknownCardError] when no card has that key
+        def find_card!(key)
+          find_card(key) || raise(UnknownCardError, "#{name} declares no card #{key.inspect}")
+        end
+
+        private
+
+        def add_card(key, kind:, options:, block:)
+          key = key.to_sym
+          if find_card(key)
+            raise ArgumentError, "#{name || "dashboard"} already declares a card #{key.inspect}"
+          end
+
+          cards << Card.new(key, kind:, dashboard_class: self, block:, **options)
+          cards.last
+        end
+
+        # Class-level state must not leak into subclasses by reference.
+        def inherited(subclass)
+          super
+          subclass.instance_variable_set(:@cards, cards.dup)
+          subclass.instance_variable_set(:@refresh, @refresh)
+          subclass.instance_variable_set(:@width, @width)
+        end
+      end
+    end
+  end
+end

data/lib/plutonium/dashboard/register.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Dashboard
+    # Per-engine registry of the dashboards mounted with `register_dashboard`,
+    # so the sidebar can list them in registration order.
+    #
+    # Classes are stored by name and resolved on read, so a code reload never
+    # hands out a stale class object.
+    class Register
+      def initialize
+        @names = []
+      end
+
+      # @param dashboard_class [Class] a {Base} subclass
+      def register(dashboard_class)
+        unless dashboard_class.is_a?(Class) && dashboard_class < Plutonium::Dashboard::Base
+          raise ArgumentError, "#{dashboard_class.inspect} must subclass Plutonium::Dashboard::Base"
+        end
+
+        @names << dashboard_class.name unless @names.include?(dashboard_class.name)
+      end
+
+      # @return [Array<Class>] registered dashboards, in registration order
+      def dashboards
+        @names.map(&:constantize)
+      end
+
+      def registered?(dashboard_class)
+        @names.include?(dashboard_class.name)
+      end
+
+      def clear
+        @names.clear
+      end
+
+      def empty? = @names.empty?
+    end
+  end
+end

data/lib/plutonium/dashboard/route_resolution.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Dashboard
+    # Resolves a `register_dashboard` mount's named routes from a route set by
+    # the `dashboard_class` route default every dashboard route carries.
+    #
+    # The helper name is not derivable from the class: it comes from `at:` /
+    # `as:`, and an entity-scoped portal prefixes it with the scope segment
+    # (`organization_scoped_team_dashboard`). Looking the route up by its
+    # default tracks whatever the registration actually drew.
+    module RouteResolution
+      module_function
+
+      # @param route_set [ActionDispatch::Routing::RouteSet]
+      # @param dashboard_class [Class]
+      # @param action [String, Symbol] "show" or "card"
+      # @return [Symbol, nil] the route name (e.g. :sales_dashboard_card)
+      def route_name(route_set, dashboard_class, action:)
+        route = route_set.routes.find do |r|
+          d = r.defaults
+          r.name.present? &&
+            d[:action].to_s == action.to_s &&
+            d[:dashboard_class].to_s == dashboard_class.name
+        end
+        route&.name&.to_sym
+      end
+    end
+  end
+end

data/lib/plutonium/dashboard.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Plutonium
+  # Dashboards: a declarative page of metric, chart and free-form cards.
+  #
+  # A dashboard is a plain class (`app/dashboards/sales_dashboard.rb`) that
+  # subclasses {Plutonium::Dashboard::Base} and declares its cards with the
+  # class-level DSL. It is mounted in a portal (or the main app) with
+  # `register_dashboard` in the routes, exactly like `register_wizard`:
+  #
+  #   class SalesDashboard < Plutonium::Dashboard::Base
+  #     presents label: "Sales", icon: Phlex::TablerIcons::ChartBar
+  #
+  #     metric(:orders) { Order.count }
+  #     chart(:revenue, type: :line, span: 8) { Order.group_by_day(:created_at).sum(:total) }
+  #   end
+  #
+  #   AdminPortal::Engine.routes.draw do
+  #     register_dashboard SalesDashboard, at: "sales"
+  #   end
+  #
+  # Every card is loaded in its own lazy turbo frame, so the page renders
+  # instantly and each card's queries run in a separate request.
+  module Dashboard
+    # Raised when a route names a dashboard class that is not loaded (never a
+    # user-facing 404 in practice: the class is handed to `register_dashboard`).
+    class UnknownDashboardError < StandardError; end
+
+    # Raised by the card endpoint when the `:card` segment names no declared
+    # card, or a card whose `condition:` hides it for this request. Mapped to
+    # a 404 by the railtie so a hidden card is indistinguishable from a missing one.
+    class UnknownCardError < StandardError; end
+
+    # DOM id prefix of the per-card turbo frames, shared by the page and the
+    # card endpoint.
+    FRAME_PREFIX = "pu-dashboard-card"
+
+    # Stands in for a policy result when `authorize?` denies entry, so the
+    # standard ActionPolicy::Unauthorized rescue can render the message.
+    AuthorizationDeniedResult = Struct.new(:message)
+  end
+end

data/lib/plutonium/definition/actions.rb

@@ -26,6 +26,11 @@ module Plutonium
           @merged_defined_actions ||= begin
             customize_actions
             merged = self.class.defined_actions.merge(instance_defined_actions)
+            # The standard actions are declared on Base, so bind each action to
+            # THIS definition's model here, where it is known, for the
+            # plutonium.actions.<model>.<action> label convention.
+            model = self.class.model_class_or_nil
+            merged = merged.transform_values { |action| action.for_resource(model) } if model
             merged.sort_by { |k, v| v.position }.to_h
           end
         end
@@ -49,7 +54,7 @@ module Plutonium
         action(:destroy, route_options: {method: :delete},
           record_action: true, collection_record_action: true, category: :danger,
           icon: Phlex::TablerIcons::Trash, position: 100,
-          confirmation: "Are you sure?", turbo_frame: "_top")
+          confirmation: t("plutonium.actions.confirm_destroy"), turbo_frame: "_top")
 
         # Example of dynamic route options using custom url_resolver:
         #

data/lib/plutonium/definition/base.rb

@@ -2,6 +2,9 @@
 
 module Plutonium
   module Definition
+    # Raised when a definition's model cannot be inferred from its name.
+    class ModelClassError < NameError; end
+
     # Base class for Plutonium definitions
     #
     # @abstract Subclass and override {#customize_fields}, {#customize_inputs},
@@ -25,6 +28,10 @@ module Plutonium
     # @note This class is not thread-safe. Ensure proper synchronization
     #   if used in a multi-threaded environment.
     class Base
+      # `input :email, placeholder: t("forms.email_placeholder")` — a lazy
+      # translation, resolved on every render in the request's locale.
+      extend Plutonium::Translation::Lazy
+
       include DefineableProps
       include ConfigAttr
       include InheritableConfigAttr
@@ -69,6 +76,28 @@ module Plutonium
       # fields
       defineable_props :field, :input, :display, :column
 
+      # `as: :phlexi_render, with:` is deprecated in favour of the block form.
+      # Warn here, at declaration, rather than in the component: it fires once
+      # per declaration with the definition's own file and line, instead of
+      # once per rendered cell.
+      module PhlexiRenderDeprecation
+        PHLEXI_RENDER_TAGS = %i[phlexi_render phlexi].freeze
+
+        def display(name, **options, &block)
+          if PHLEXI_RENDER_TAGS.include?(options[:as])
+            Plutonium.deprecator.warn(
+              "`display :#{name}, as: :#{options[:as]}, with:` is deprecated; use a block-form display " \
+              "instead: `display :#{name} do |f| ... end`. It renders in a Phlex context once and gives " \
+              "you `f.object`.",
+              caller_locations(1)
+            )
+          end
+          super
+        end
+      end
+      singleton_class.prepend PhlexiRenderDeprecation
+      prepend PhlexiRenderDeprecation
+
       # export
       defineable_prop :export
 
@@ -170,13 +199,22 @@ module Plutonium
         @model_class ||= infer_model_class
       end
 
+      # `model_class`, or nil for a definition that has no model to infer (an
+      # anonymous or base definition). Convention lookups keyed by the model
+      # (action / scope labels) use this so such definitions keep rendering.
+      def self.model_class_or_nil
+        model_class
+      rescue ModelClassError
+        nil
+      end
+
       def self.infer_model_class
-        raise NameError, "cannot infer a model class for an anonymous definition; define `model_class` on it" if name.nil?
+        raise ModelClassError, "cannot infer a model class for an anonymous definition; define `model_class` on it" if name.nil?
 
         segments = name.split("::")
         base = segments.pop.delete_suffix("Definition")
         if base.empty?
-          raise NameError, "#{name} does not follow the `<Model>Definition` naming convention; define `model_class` on it"
+          raise ModelClassError, "#{name} does not follow the `<Model>Definition` naming convention; define `model_class` on it"
         end
 
         # Only an ActiveRecord model can be the answer, so a namespace module, a
@@ -190,7 +228,7 @@ module Plutonium
           return klass if klass.is_a?(Class) && klass < ActiveRecord::Base
         end
 
-        raise NameError, "could not infer a model class from #{name}; define `model_class` on it"
+        raise ModelClassError, "could not infer a model class from #{name}; define `model_class` on it"
       end
       private_class_method :infer_model_class
 

data/lib/plutonium/definition/index_views.rb

@@ -118,7 +118,7 @@ module Plutonium
           #     interaction that references the definition at its own load time
           #     would deadlock the autoloader. In practice interactions depend only
           #     on their model, so this constraint is naturally satisfied.
-          board = Plutonium::Kanban::DSL.build(&block)
+          board = Plutonium::Kanban::DSL.build(resource_class: model_class_or_nil, &block)
           # Cache the compiled board so the controller can reuse it instead of
           # recompiling per request (see KanbanActions#current_kanban_board).
           self.defined_kanban_board = board

data/lib/plutonium/definition/positioning.rb

@@ -62,7 +62,7 @@ module Plutonium
           # its own `default_sort` means every resource under it renders the grip
           # in the disabled state until the user sorts by position. That is the
           # intended precedence — the app asked for that ordering — and it is
-          # documented in docs/reference/positioning.md.
+          # documented in docs/reference/resource/positioning.md.
           default_sort config.attribute, :asc if _default_sort.equal?(Sorting::DEFAULT_SORT)
 
           # Hidden: it has a POST member route (routing/mapper_extensions.rb) and

data/lib/plutonium/definition/presentable.rb

@@ -37,7 +37,7 @@ module Plutonium
         #
         # @return [String] The label defined in the presentation metadata or a default generated from the class name.
         def label
-          presentation_metadata[:label] || name.demodulize.titleize
+          Plutonium::Translation.resolve(presentation_metadata[:label]) || name.demodulize.titleize
         end
 
         # Returns the icon for the interaction.
@@ -51,7 +51,7 @@ module Plutonium
         #
         # @return [String, nil] The description defined in the presentation metadata.
         def description
-          presentation_metadata[:description]
+          Plutonium::Translation.resolve(presentation_metadata[:description])
         end
       end
 

data/lib/plutonium/helpers/assets_helper.rb

@@ -33,6 +33,19 @@ module Plutonium
         Plutonium.configuration.assets.script
       end
 
+      # URL of the on-demand charts bundle. Chart cards carry it in a data
+      # attribute and the `chart` Stimulus controller injects it once, so pages
+      # without a chart never pay for Chart.js.
+      #
+      # @return [String] the charts bundle URL
+      def resource_charts_script_url
+        if Plutonium.configuration.development?
+          resource_development_asset_url(:js, "plutonium-charts.js")
+        else
+          asset_path(Plutonium.configuration.assets.charts_script)
+        end
+      end
+
       private
 
       # Generate the appropriate asset URL based on the environment
@@ -52,9 +65,9 @@ module Plutonium
       #
       # @param type [Symbol] asset type (:css or :js)
       # @return [String] asset URL for development
-      def resource_development_asset_url(type)
+      def resource_development_asset_url(type, asset_key = nil)
         manifest_file = (type == :css) ? "css.manifest" : "js.manifest"
-        asset_key = (type == :css) ? "plutonium.css" : "plutonium.js"
+        asset_key ||= (type == :css) ? "plutonium.css" : "plutonium.js"
 
         filename = JSON.parse(File.read(Plutonium.root.join("src", "build", manifest_file)))[asset_key]
         "/build/#{filename}"

data/lib/plutonium/helpers/display_helper.rb

@@ -1,8 +1,16 @@
 module Plutonium
   module Helpers
     module DisplayHelper
+      # The model's human name, pluralised for `count`. A locale that defines
+      # `activerecord.models.<model>.one/other` supplies the plural; when it
+      # only defines a single string (or nothing), the English inflector
+      # pluralises the singular as before.
       def resource_name(resource_class, count = 1)
-        resource_class.model_name.human.pluralize(count)
+        model_name = resource_class.model_name
+        return model_name.human if count == 1
+        return model_name.human(count: count) if Plutonium::Translation.locale_plural?(resource_class)
+
+        model_name.human.pluralize(count)
       end
 
       def resource_name_plural(resource_class)
@@ -44,7 +52,7 @@ module Plutonium
         end
 
         # Maybe this is a record?
-        return "#{resource_name(obj.class)} ##{obj.id}" if obj.respond_to?(:id)
+        return t("plutonium.resource.record_label", resource: resource_name(obj.class), id: obj.id) if obj.respond_to?(:id)
 
         # Oh well. Just convert it to a string.
         obj.to_s

data/lib/plutonium/interaction/async/context.rb

@@ -351,8 +351,8 @@ module Plutonium
           # user row is gone. Refusing is the whole point: a run whose initiator
           # no longer exists has no one left to authorize as.
           if run.initiator.nil?
-            raise UnresolvableError,
-              "run #{run.id} has no initiator (#{run.initiator_type}##{run.initiator_id} no longer exists)"
+            raise UnresolvableError, I18n.t("plutonium.async.context.initiator_missing",
+              run: run.id, type: run.initiator_type, id: run.initiator_id)
           end
 
           # nil scoped_entity is LEGITIMATE — an unscoped portal has no tenant,
@@ -362,9 +362,8 @@ module Plutonium
           # drops the entity filter entirely, returning records from EVERY tenant.
           # That is precisely the fail-open case this class exists to prevent.
           if run.scoped_entity_type.present? && run.scoped_entity.nil?
-            raise UnresolvableError,
-              "run #{run.id} was scoped to #{run.scoped_entity_type}##{run.scoped_entity_id}, " \
-              "which no longer exists; refusing to resolve targets without a tenant"
+            raise UnresolvableError, I18n.t("plutonium.async.context.tenant_missing",
+              run: run.id, type: run.scoped_entity_type, id: run.scoped_entity_id)
           end
 
           # Same distinction one more time, and the same direction of failure. A
@@ -372,9 +371,8 @@ module Plutonium
           # dispatch" — and that hands the run entity scoping instead of parent
           # scoping, which is wider.
           if run.parent_type.present? && run.parent.nil?
-            raise UnresolvableError,
-              "run #{run.id} was nested under #{run.parent_type}##{run.parent_id}, " \
-              "which no longer exists; refusing to resolve targets without its parent"
+            raise UnresolvableError, I18n.t("plutonium.async.context.parent_missing",
+              run: run.id, type: run.parent_type, id: run.parent_id)
           end
         end
 

data/lib/plutonium/interaction/async/executor.rb

@@ -206,8 +206,7 @@ module Plutonium
           elsif (remaining = perform_each(resolved.records))
             # The loop stopped, so the remaining targets were never attempted.
             # A run that did not do its job must not read as completed.
-            run.fail!("stopped at the first target failure (#{run.failure_policy} policy); " \
-                      "#{remaining} target(s) were not attempted")
+            run.fail!(I18n.t("plutonium.async.executor.halted", policy: run.failure_policy, count: remaining))
           else
             # Partial failure under :continue is COMPLETED, not failed. The author
             # declared partial application acceptable, the executor ran to the
@@ -300,7 +299,7 @@ module Plutonium
         def fail_target(record, error)
           run.reload if run.changed?
 
-          raise BatchAbortedError, "target #{record.id} failed (#{error.message}); no targets were applied" if transactional?
+          raise BatchAbortedError, I18n.t("plutonium.async.executor.batch_aborted", id: record.id, error: error.message) if transactional?
 
           run.record_target_failure!(id: record.id, message: error.message)
           halt? ? :halt : nil
@@ -393,8 +392,8 @@ module Plutonium
         # part of the batch anyway would be the one outcome neither policy allows.
         def refuse_partial_batch(resolved)
           unresolved = resolved.missing_ids.size + resolved.unauthorized_ids.size
-          run.fail!("#{unresolved} of #{run.target_ids.size} targets could not be resolved; " \
-                    "a #{run.failure_policy} run does not apply a partial batch")
+          run.fail!(I18n.t("plutonium.async.executor.partial_batch_refused",
+            unresolved: unresolved, total: run.target_ids.size, policy: run.failure_policy))
         end
 
         # Advances progress and records +id+ as dispositioned, in one write —
@@ -407,9 +406,9 @@ module Plutonium
           run.save!
         end
 
-        def missing_message(id) = "Target #{id} is no longer available"
+        def missing_message(id) = I18n.t("plutonium.async.executor.target_missing", id: id)
 
-        def unauthorized_message(id) = "Target #{id} is no longer permitted by #{context.policy_action}"
+        def unauthorized_message(id) = I18n.t("plutonium.async.executor.target_unauthorized", id: id, action: context.policy_action)
 
         def continue? = run.failure_policy == :continue
 

data/lib/plutonium/interaction/async/run.rb

@@ -169,7 +169,7 @@ module Plutonium
         def to_label
           parts = self.class.name.split("::")
           name = (parts.last == "Run" && parts.size > 1) ? "#{parts[-2]}Run" : parts.last
-          "#{name.titleize} ##{to_param}"
+          I18n.t("plutonium.async.run.label", name: name.titleize, id: to_param)
         end
 
         # nil means INDETERMINATE, not zero: opaque work has no denominator, and
@@ -385,7 +385,7 @@ module Plutonium
         def enqueue_job
           Plutonium::Interaction::Async::Job.perform_later(id)
         rescue
-          fail!("could not be enqueued for execution")
+          fail!(I18n.t("plutonium.async.run.enqueue_failed"))
           raise
         end
       end

data/lib/plutonium/interaction/async/run_definition.rb

@@ -38,7 +38,7 @@ module Plutonium
         column :outcome, as: :badge,
           colors: {running: :info, completed_with_errors: :warning}
 
-        field :target_label, label: "Target type"
+        field :target_label, label: t("plutonium.async.run.target_type")
 
         # The details tab, with the live panel above the fields.
         #

data/lib/plutonium/interaction/base.rb

@@ -38,6 +38,8 @@ module Plutonium
     # @note Subclasses must implement the #execute method.
     # @see https://radioactive-labs.github.io/plutonium-core/reference/behavior/interactions
     class Base
+      extend Plutonium::Translation::Lazy
+
       include ActiveModel::Model
       include ActiveModel::Attributes
       include Plutonium::Definition::DefineableProps

data/lib/plutonium/interaction/concerns/dispatchable.rb

@@ -336,13 +336,25 @@ module Plutonium
         # equivalent of that.
         #
         # No-op for ActiveStorage fields, and for uploaders declaring no rules.
+        #
+        # Which attributes are files is decided by their INPUT DECLARATION (an
+        # `as:` file alias), not by the shape of the value they currently hold.
+        # A direct upload arrives already staged, as a token String, so keying
+        # off IO-shape (respond_to?(:read)) skipped exactly those — an oversized
+        # cached token validated clean and dispatched, the rule surfacing as a
+        # run failure the submitter never sees. This is how a wizard decides the
+        # same question (Plutonium::Wizard::Attachments.field?).
         def validate_dispatch_attachments
-          staged = attributes.except("resource", "resources").select { |_, v| dispatch_attachment?(v) }.keys
           stage_dispatch_attachments!
 
-          staged.each do |name|
+          self.class.defined_inputs.each do |name, config|
+            next unless Plutonium::Definition::InputAliases.file_input?(config.dig(:options, :as))
+
+            value = public_send(name)
+            next if value.blank?
+
             messages = Plutonium::Attachments.validation_errors(
-              public_send(name), **dispatch_attachment_options(name)
+              value, **dispatch_attachment_options(name)
             )
             messages.each { |message| errors.add(name, message) }
           end

data/lib/plutonium/invites/concerns/cancel_invite.rb

@@ -17,7 +17,7 @@ module Plutonium
         extend ActiveSupport::Concern
 
         included do
-          presents label: "Cancel Invitation", icon: Phlex::TablerIcons::CircleX
+          presents label: t("plutonium.invites.cancel_invite.label"), icon: Phlex::TablerIcons::CircleX
 
           attribute :resource
         end
@@ -34,11 +34,11 @@ module Plutonium
         private
 
         def success_message
-          "Invitation cancelled"
+          I18n.t("plutonium.invites.cancel_invite.cancelled")
         end
 
         def not_pending_message
-          "Can only cancel pending invitations"
+          I18n.t("plutonium.invites.cancel_invite.not_pending")
         end
       end
     end

data/lib/plutonium/invites/concerns/invite_token.rb

@@ -97,7 +97,7 @@ module Plutonium
         # @raise [ActiveRecord::RecordInvalid] if constraints are violated
         def validate_email_constraints!(user_email)
           if enforce_email? && user_email.downcase != email.downcase
-            errors.add(:base, "This invitation is for #{email}. You must use an account with that email address.")
+            errors.add(:base, :invite_email_mismatch, email: email)
             raise ActiveRecord::RecordInvalid.new(self)
           end
 
@@ -105,7 +105,7 @@ module Plutonium
             user_domain = extract_domain(user_email)
 
             if user_domain != required_domain
-              errors.add(:base, "This invitation requires an email from the #{required_domain} domain.")
+              errors.add(:base, :invite_domain_mismatch, domain: required_domain)
               raise ActiveRecord::RecordInvalid.new(self)
             end
           end
@@ -115,16 +115,34 @@ module Plutonium
         #
         # This method:
         # 1. Validates email constraints
-        # 2. Marks the invite as accepted
-        # 3. Creates the entity membership
-        # 4. Notifies the invitable (if present)
+        # 2. Acquires a row lock and re-checks the pending state to serialize
+        #    concurrent acceptances (prevents a TOCTOU race from creating
+        #    memberships for multiple users from a single invite when
+        #    `enforce_email?` is false)
+        # 3. Marks the invite as accepted
+        # 4. Creates the entity membership
+        # 5. Notifies the invitable (if present)
         #
         # @param user [Object] the user accepting the invitation
-        # @raise [ActiveRecord::RecordInvalid] if acceptance fails
+        # @raise [ActiveRecord::RecordInvalid] if acceptance fails (e.g. the
+        #   invite was already accepted by a concurrent request)
         def accept_for_user!(user)
           validate_email_constraints!(user.email)
 
-          transaction do
+          with_lock do
+            unless pending?
+              error =
+                if accepted?
+                  :invite_already_accepted
+                elsif cancelled?
+                  :invite_cancelled
+                else
+                  :invite_expired
+                end
+              errors.add(:base, error)
+              raise ActiveRecord::RecordInvalid.new(self)
+            end
+
             update!(
               :state => :accepted,
               :accepted_at => Time.current,