plutonium 0.62.2 → 0.63.0

data/lib/plutonium/definition/display_layout.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Definition
+    # Declarative display sectioning — the `display_layout` counterpart to
+    # {FormLayout}, applied to the show page's field grid instead of the
+    # form. Same shape (`section`/`ungrouped`, first-section-wins ownership,
+    # `condition:`) and the same resolution semantics, so a section/field
+    # author only has to learn the DSL once.
+    #
+    # Reuses {FormLayout}'s `Section`/`ResolvedSection` structs and its
+    # ownership-resolution algorithm ({FormLayout.resolve_sections}) rather
+    # than duplicating them — the algorithm has nothing form-specific about
+    # it, only the declaring macro and the render target differ.
+    #
+    # Deliberately does NOT support `columns:`. The display side already has
+    # a per-field width pathway — `display :x, wrapper: {class: "col-span-2"}`
+    # — and every section renders into the same responsive grid, so a second,
+    # section-level column mechanism would be a redundant way to say the same
+    # thing. Grouping is what this DSL is for; widths stay on the field. A
+    # `columns:` option raises rather than being silently dropped.
+    #
+    # @example
+    #   display_layout do
+    #     section :identity, :name, :email, label: "Identification"
+    #     section :address, :street, :city, collapsible: true,
+    #       condition: -> { object.requires_address? }
+    #     ungrouped label: "Other"
+    #   end
+    module DisplayLayout
+      extend ActiveSupport::Concern
+
+      # Collects section/ungrouped calls from a display_layout block, in
+      # order. Builds the same Section struct FormLayout uses — the two
+      # layouts share a resolver, so they share a value type.
+      class Builder
+        attr_reader :sections
+
+        def initialize
+          @sections = []
+          @ungrouped_seen = false
+        end
+
+        def section(key, *fields, **options)
+          if key == FormLayout::UNGROUPED_KEY
+            raise ArgumentError,
+              "`section :#{FormLayout::UNGROUPED_KEY}` is reserved — use the `ungrouped` macro"
+          end
+          reject_columns!(options)
+          @sections << FormLayout::Section.new(key:, fields: fields.freeze, options: options.freeze)
+        end
+
+        def ungrouped(**options)
+          raise ArgumentError, "`ungrouped` may only be declared once" if @ungrouped_seen
+          @ungrouped_seen = true
+          reject_columns!(options)
+          @sections << FormLayout::Section.new(
+            key: FormLayout::UNGROUPED_KEY, fields: [].freeze, options: options.freeze
+          )
+        end
+
+        private
+
+        # `columns:` is a form_layout option only. Raising (rather than
+        # ignoring it) means an author who copies a form_layout block across
+        # finds out immediately, instead of wondering why the column count
+        # had no effect.
+        def reject_columns!(options)
+          return unless options.key?(:columns)
+          raise ArgumentError,
+            "display_layout does not support `columns:` — set a width on the field instead, " \
+            "e.g. `display :x, wrapper: {class: \"col-span-2\"}`"
+        end
+      end
+
+      class_methods do
+        # Declare the display layout. Re-declaring replaces it as a unit.
+        def display_layout(&block)
+          raise ArgumentError, "`display_layout` requires a block" unless block
+          builder = Builder.new
+          builder.instance_exec(&block)
+          @defined_display_layout = builder.sections.freeze
+        end
+
+        # Ordered Array<FormLayout::Section>, or nil when no layout was declared.
+        def defined_display_layout
+          @defined_display_layout
+        end
+
+        def inherited(subclass)
+          super
+          subclass.instance_variable_set(:@defined_display_layout, defined_display_layout&.dup)
+        end
+      end
+
+      # Instance access — the display render path holds a definition
+      # instance (mirrors the defineable_prop convention).
+      def defined_display_layout
+        self.class.defined_display_layout
+      end
+
+      # Resolve the policy-filtered field list into ordered ResolvedSections.
+      # Returns nil when no layout is declared (caller falls back to one grid).
+      def resolve_display_sections(resource_fields)
+        layout = defined_display_layout
+        return nil unless layout
+
+        FormLayout.resolve_sections(layout, resource_fields)
+      end
+    end
+  end
+end

data/lib/plutonium/definition/index_views.rb

@@ -135,17 +135,18 @@ module Plutonium
 
             # Register each column's enter_interaction as an interactive record
             # action too, so its form and params extraction exist and route the
-            # standard way. It is flagged `kanban_drop: true` so it is excluded
-            # from the normal show/row/index toolbars — it is reachable only by
-            # dropping a card. The key is column-scoped (enter_interaction_key →
-            # :<column>_enter_interaction), so it is unique by construction and
-            # never collides with another column's interaction. It carries NO
-            # policy method of its own — the drop is authorized by kanban_move?.
+            # standard way. It is flagged `hidden: true` so it is excluded from
+            # every render surface (toolbars, row dropdowns, cards, bulk bars) —
+            # it is reachable only by dropping a card. The key is column-scoped
+            # (enter_interaction_key → :<column>_enter_interaction), so it is
+            # unique by construction and never collides with another column's
+            # interaction. It carries NO policy method of its own — the drop is
+            # authorized by kanban_move?.
             if col.enter_interaction?
               action(
                 col.enter_interaction_key,
                 interaction: col.enter_interaction,
-                kanban_drop: true
+                hidden: true
               )
             end
           end

data/lib/plutonium/definition/input_aliases.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Definition
+    # What an `as:` on an input / display declaration MEANS, independent of any
+    # view.
+    #
+    # `as:` is a union: either an alias naming a built-in tag (`:string`,
+    # `:uppy`, a String) OR a component Class rendered directly (see
+    # {Plutonium::UI::Component::ResolvesTags}). A Class has no `#to_sym`, so
+    # every "which alias is this?" question goes through {resolve} rather than
+    # coercing `as` itself — the controller, the wizard, the generators and the
+    # views all ask here.
+    module InputAliases
+      # The `as:` values that render through the Uppy file-upload component —
+      # the single source of truth, so the form builder's tag aliases and the
+      # attachment detection in {Plutonium::Wizard::Attachments.field?} and
+      # `Plutonium::Resource::Controller#attachment_input_keys` never drift.
+      FILE_INPUT_TYPES = %i[uppy file attachment].freeze
+
+      class << self
+        # @param as [Symbol, String, Class, nil] a declared `as:`.
+        # @return [Symbol, nil] the Symbol form of a symbol/string `as:`; nil for
+        #   anything else, a component Class included, since it names no alias.
+        #   The Symbol is NOT validated against the tags that actually exist —
+        #   callers compare it against the aliases they care about.
+        def resolve(as)
+          as.to_sym if as.is_a?(Symbol) || as.is_a?(String)
+        end
+
+        # Whether an `as:` renders as an attachment/file input.
+        def file_input?(as)
+          FILE_INPUT_TYPES.include?(resolve(as))
+        end
+      end
+    end
+  end
+end

data/lib/plutonium/definition/page_widths.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Definition
+    # Per-resource width for detail-style pages. `page_width` sets both the
+    # form and the show page; `form_width` / `display_width` override one
+    # surface without disturbing the other.
+    #
+    #   Plutonium.configure { |c| c.default_page_width = :md }   # global
+    #
+    #   class PostDefinition < ResourceDefinition
+    #     page_width    :lg      # this resource's form AND show page
+    #     display_width :full    # ...except the show page, which goes full
+    #   end
+    #
+    # Resolution, most specific first: the surface-specific setting, then
+    # `page_width`, then `Plutonium.configuration.default_page_width`. All
+    # three inherit to subclasses (so a portal-specific definition keeps its
+    # parent's width unless it says otherwise), which is why these are
+    # `inheritable_config_attr` rather than plain class attributes.
+    module PageWidths
+      extend ActiveSupport::Concern
+
+      # `inheritable_config_attr` appends the `_config` suffix itself and
+      # defines the bare name as a singleton method on the class. A
+      # `class_methods` module would sit BEHIND that in the ancestor chain and
+      # never be called, so the validating versions are defined here, after
+      # generation, to replace it — the same ordering `show_in` relies on.
+      included do
+        inheritable_config_attr :page_width, :form_width, :display_width
+
+        # Reader with no argument, validated writer with one, so an unknown
+        # token raises at declaration rather than silently rendering at some
+        # other width.
+        %i[page_width form_width display_width].each do |name|
+          define_singleton_method(name) do |value = :__not_set__|
+            return public_send(:"#{name}_config") if value == :__not_set__
+
+            public_send(:"#{name}_config=", Plutonium::UI::PageWidth.validate!(value))
+          end
+        end
+      end
+
+      # The resolved token for each surface. Nil-coalescing rather than
+      # `||`-on-a-boolean, so an explicit `:full` (a legitimate choice) is
+      # honoured instead of being treated as "unset".
+      def resolved_form_width
+        self.class.form_width_config ||
+          self.class.page_width_config ||
+          Plutonium.configuration.default_page_width
+      end
+
+      def resolved_display_width
+        self.class.display_width_config ||
+          self.class.page_width_config ||
+          Plutonium.configuration.default_page_width
+      end
+
+      # The classes to put on the surface, or nil for `:full`.
+      def form_width_classes = Plutonium::UI::PageWidth.classes_for(resolved_form_width)
+
+      def display_width_classes = Plutonium::UI::PageWidth.classes_for(resolved_display_width)
+    end
+  end
+end

data/lib/plutonium/definition/positioning.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "plutonium/positioning/config"
+
+module Plutonium
+  module Definition
+    # Declares a resource drag-orderable. The MODEL owns how positions are
+    # stored (`positioned_on :sort_order, scope: :project_id`); this only says
+    # "this UI can be reordered", and never restates the column or the scope.
+    #
+    #   position_on                      # Mode A, follows the model's column
+    #   position_on :sort_order          # Mode A, must MATCH the model's column
+    #   position_on(:rank) { |move| … }  # Mode B, another gem owns the write
+    #   position_on false                # Mode C, ordering off
+    #
+    # Mirrors kanban's `position_on` (lib/plutonium/kanban/dsl.rb) exactly, and
+    # builds the same Plutonium::Positioning::Config. Deliberately the same verb
+    # rather than a third one: the model says `positioned_on`, every UI layer
+    # says `position_on`, and a kanban board with no `position_on` of its own
+    # inherits the definition's (see Kanban::Board#position_config_for).
+    module Positioning
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :defined_position_config, instance_accessor: false, default: nil
+
+        # `attribute` defaults to nil, not :position — in Mode A the model has
+        # already named its column, and assuming :position here would silently
+        # order by one column while reposition! wrote another. Mode B has no
+        # model contract to read, so it keeps :position as its own default.
+        def self.position_on(attribute = nil, &block)
+          config =
+            if attribute == false
+              Plutonium::Positioning::Config.disabled
+            elsif block
+              Plutonium::Positioning::Config.with_block(attribute || :position, block)
+            else
+              validate_model_is_positioned!(attribute)
+              Plutonium::Positioning::Config.attribute(attribute || model_class.positioning_column)
+            end
+
+          self.defined_position_config = config
+          return config if config.disabled?
+
+          # Registering the sort is load-bearing: dragging is only permitted
+          # when the collection is ordered by this attribute, so without a
+          # permitted sort there is no way back out of the disabled state.
+          sort config.attribute
+
+          # Only claim default_sort while nobody has chosen one. A `default_sort`
+          # written ABOVE position_on must survive exactly as one written below
+          # it does — this method is otherwise the single order-dependent line in
+          # a class body that is order-independent everywhere else (see
+          # Board#position_config_for).
+          #
+          # `equal?`, not `==`: DEFAULT_SORT is a sentinel, and `default_sort
+          # :id, :desc` builds a value-equal but distinct array. Comparing by
+          # value would read that explicit choice as "untouched" and silently
+          # overwrite it.
+          #
+          # NOTE this respects an inherited choice too: a base definition with
+          # 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.
+          default_sort config.attribute, :asc if _default_sort.equal?(Sorting::DEFAULT_SORT)
+
+          # Hidden: it has a POST member route (routing/mapper_extensions.rb) and
+          # a `reposition?` policy predicate (resource/policy.rb), but is
+          # reachable only by dragging — never rendered as a button.
+          action :reposition, hidden: true
+
+          config
+        end
+
+        # Mode A calls record.reposition! AND reads `.rebalanced?` off its
+        # return, so it needs the real concern — not merely something that
+        # responds to reposition!. A model that hand-rolls reposition!
+        # (wrapping acts_as_list, say) would otherwise fail at drop time,
+        # mid-transaction, with `NoMethodError: undefined method 'rebalanced?'`.
+        #
+        # This check lives HERE rather than in Config#reposition! for two
+        # reasons: the house rule against defensive call-site guards, and
+        # config.rb's standalone-loadability invariant — naming
+        # Plutonium::Positioning::Model there would pull in the concern and
+        # break the guard test in test/plutonium/positioning/config_test.rb.
+        # The DSL is where the mode is chosen, so it is where the contract belongs.
+        def self.validate_model_is_positioned!(attribute)
+          declaration = attribute ? "position_on #{attribute.inspect}" : "position_on"
+
+          unless model_class.include?(Plutonium::Positioning::Model)
+            raise ArgumentError,
+              "#{name || "definition"}: `#{declaration}` requires #{model_class} to " \
+              "`include Plutonium::Positioning::Model` and declare `positioned_on`. " \
+              "If another gem owns positioning for this model, use the block form " \
+              "instead: position_on(#{(attribute || :position).inspect}) { |move| … }"
+          end
+
+          # Including the concern is not enough: without `positioned_on` there is
+          # no before_create hook, so every row is created with a nil position and
+          # the resulting order is arbitrary — the silent failure this class-load
+          # check exists to prevent. positioning_column has a default and so
+          # cannot answer this question; positioning_declared can.
+          unless model_class.positioning_declared
+            raise ArgumentError,
+              "#{name || "definition"}: `#{declaration}` requires #{model_class} to declare " \
+              "`positioned_on` — including Plutonium::Positioning::Model alone never " \
+              "assigns a position on create, so every row would sort arbitrarily."
+          end
+
+          return if attribute.nil? || attribute.to_sym == model_class.positioning_column.to_sym
+
+          raise ArgumentError,
+            "#{name || "definition"}: `#{declaration}` contradicts #{model_class}'s " \
+            "`positioned_on #{model_class.positioning_column.inspect}` — the collection would " \
+            "be ordered by one column while reposition! wrote another, so dragging would " \
+            "appear to do nothing. Drop the argument to follow the model, or use the block " \
+            "form if another gem owns the write."
+        end
+        private_class_method :validate_model_is_positioned!
+      end
+
+      def defined_position_config = self.class.defined_position_config
+    end
+  end
+end

data/lib/plutonium/definition/sorting.rb

@@ -3,6 +3,17 @@ module Plutonium
     module Sorting
       extend ActiveSupport::Concern
 
+      # The framework-wide default sort: newest first.
+      #
+      # A SENTINEL, compared with `equal?` — see Definition::Positioning, which
+      # only claims default_sort while nobody has chosen one. `==` cannot answer
+      # that question: `default_sort :id, :desc` builds a fresh `[field,
+      # direction]` array that is value-equal to this one, so an app that
+      # explicitly asked for newest-first would have its choice silently
+      # overwritten. Identity distinguishes them, which is why the installation
+      # below assigns this exact object rather than going through `default_sort`.
+      DEFAULT_SORT = [:id, :desc].freeze
+
       included do
         defineable_props :sort
 
@@ -21,8 +32,12 @@ module Plutonium
           _default_sort
         end
 
-        # Set a sensible default: newest items first
-        default_sort :id, :desc
+        # Set a sensible default: newest items first. Assigned directly rather
+        # than through `default_sort` so `_default_sort` holds the SENTINEL
+        # object itself — that identity is what tells a later `position_on` the
+        # sort is still untouched. Equivalent otherwise: `default_sort :id,
+        # :desc` would store a value-equal `[:id, :desc]`.
+        self._default_sort = DEFAULT_SORT
       end
 
       def default_sort

data/lib/plutonium/helpers/turbo_helper.rb

@@ -16,6 +16,13 @@ module Plutonium
       # modal frame specifically.
       def in_secondary_modal? = current_turbo_frame == Plutonium::REMOTE_MODAL_SECONDARY_FRAME
 
+      # True when this show request was opened from a kanban card in the modal
+      # frame — the card tags its show URL with KANBAN_MODAL_PARAM. Gated on
+      # in_modal? so a stray param on a full-page show never hides metadata.
+      # Lets the show page drop the metadata rail for kanban cards specifically,
+      # leaving regular show modals (and full-page shows) untouched.
+      def in_kanban_modal? = in_modal? && params[Plutonium::KANBAN_MODAL_PARAM].present?
+
       # Returns a turbo-frame-scoped element id. Two identically-named forms
       # can be on the page simultaneously (e.g. a primary modal opens a
       # secondary modal, each rendering an `id="resource-form"`). When the

data/lib/plutonium/interaction/README.md

@@ -14,24 +14,29 @@
 
 ## Introduction
 
-Interactions allows us to leverage an architectural approach that focuses on organizing code around business actions or user interactions.
-It builds upon the traditional MVC pattern by introducing additional layers that encapsulate business logic and improve separation of concerns.
+Interactions organize code around the actions a user can take. Each one is the entry point from a page into a single, well-defined operation: it declares the inputs, renders as a button and a form, is gated by a policy, and hands back an outcome the controller turns into a message and a redirect.
 
 ### Key Benefits
 
-- Clear separation of business logic from controllers
-- Improved testability of business operations
+- A uniform surface for custom operations: button, form, authorization, messaging, redirect
+- Clear separation of the *request* from the controller
 - Consistent handling of success and failure cases
-- Flexible and expressive way to chain operations
-- Enhanced maintainability and readability of complex business processes
-- Improved code organization and discoverability of business logic
+- Input validation that renders as form errors
+- Improved discoverability — every custom operation is a named class in `app/interactions/`
 
 ## Key Concepts
 
 ### Interactions
 
-Interactions are the core of this pattern. They represent specific use cases or business operations in your application. Each interaction is responsible for a single, well-defined task.
-Interactions encapsulate the business logic, input validation, and outcome handling, providing a clean interface between the controller and the application's core functionality.
+An interaction is a **presentation object**. It owns the button, the form, the input-shape validation, and the user-facing outcome.
+
+It is *not* where a domain operation should end up living. An interaction cannot be constructed without a `view_context:`, so anything reachable only through one is reachable only from a page. Logic may **start** in `execute` — a one-off with a single caller is fine there, and pre-extracting is YAGNI. The trigger to extract is the **second caller**: a background job, an API controller, a rake task, the console, or another interaction. At that point the behaviour moves onto the **model** (fat models, per Rails convention — not a new service layer), and the interaction shrinks to a call to a well-named method.
+
+`view_context` is the tell: if a caller would need one purely to reach some behaviour, that behaviour is on the wrong side of the boundary.
+
+Validations split along the same line. **Interaction validations check input shape** — is it present, does it parse, is it the right type — and exist to render form errors. **Model validations are business invariants** and must hold regardless of who is calling.
+
+Full explanation: [Reference › Behavior › Interactions](https://radioactive-labs.github.io/plutonium-core/reference/behavior/interactions).
 
 ### Outcomes
 
@@ -99,7 +104,7 @@ We ship with these out of the box:
              .with_response(Response::Redirect.new(user_path(user)))
              .with_message("User was successfully created.")
          else
-           failure(user.errors)
+           failed(user.errors)
          end
        end
      end
@@ -159,26 +164,55 @@ else
 end
 ```
 
-Or within another interaction:
+### Composing outcomes — `and_then`
+
+`and_then` composes `Outcome`s. On a `Success` it yields **the value** (not the outcome) and returns whatever the block returns; on a `Failure` it short-circuits, returning the failure untouched. It's useful for expressing a guard as an outcome inside one `execute`:
 
 ```ruby
 def execute
-  MyInteraction.call(some_input: "value")
-    .and_then { |result| do_something_with(result) }
-    .with_response(Response::Redirect.new(some_path(final_result)))
-    .with_message("Operation completed successfully")
+  unlocked_resource.and_then do |post|
+    post.publish!
+    succeed(post).with_message("Published")
+  end
+end
+
+private
+
+def unlocked_resource
+  resource.locked? ? failed("This post is locked") : succeed(resource)
 end
 ```
 
+> **Don't use `and_then` to sequence business operations.** A chain of three interactions is a chain of three things that each demand a `view_context` — none of which a job or an API controller can supply. That's one model method wearing three costumes; see [Best Practices](#best-practices) below.
+
 ## Best Practices
 
 1. Keep interactions focused on a single responsibility
 2. Use meaningful names for interactions that describe the action being performed
-3. Leverage the `and_then` method for clean and expressive operation chaining
-4. Prefer small, composable interactions over large, monolithic ones
+3. **Put the operation on the model as soon as a second caller needs it.** Logic may start in `execute`; a job, API controller, rake task, or console session wanting the same behaviour is the trigger to extract. Name the model method in domain language (`publish!`, `archive!`, `register!`), not persistence terms (`update_published_at`)
+4. **Interaction validations check input shape; model validations enforce invariants.** The interaction's exist to render form errors — they don't run for any other caller
 5. Use `with_response` to explicitly set the desired response type
 6. Keep the interaction's core logic separate from response handling
 
+### The chaining anti-pattern
+
+```ruby
+# 🚫 Each link demands a view_context that has nothing to do with the work
+CreateUserInteraction.call(view_context:, **user_params)
+  .and_then { |user| SendWelcomeEmail.call(view_context:, user:) }
+  .and_then { |user| LogActivity.call(view_context:, user:) }
+```
+
+Sending a welcome email and writing an audit row are exactly what a signup API endpoint or a seeds script also has to do — and neither has a view context. Give the model the operation instead:
+
+```ruby
+# ✅
+def execute
+  user = User.register!(**attributes)   # welcome email + audit row live in here
+  succeed(user).with_message("Welcome aboard!")
+end
+```
+
 ## Testing
 
 Interactions are easy to test in isolation. Here's an example using RSpec:
@@ -314,7 +348,7 @@ module Users
         if user.save
           success(user).with_message("User created successfully")
         else
-          failure(user.errors)
+          failed(user.errors)
         end
       end
     end
@@ -345,25 +379,28 @@ module Orders
 
     def find_user(user_id)
       user = User.find_by(id: user_id)
-      user ? success(user) : failure(["User not found"])
+      user ? success(user) : failed(["User not found"])
     end
 
     def find_products(user, product_ids)
       products = Product.where(id: product_ids.split(','))
-      products.empty? ? failure(["No valid products found"]) : success([user, products])
+      products.empty? ? failed(["No valid products found"]) : success([user, products])
     end
 
     def create_order(user, products)
-      order = Order.create(user: user, products: products)
-      order.persisted? ? success(order) : failure(order.errors.full_messages)
+      # Order.place! owns the domain work — inventory, totals, confirmation mail.
+      # The interaction only resolves the inputs and shapes the outcome.
+      success(Order.place!(user: user, products: products))
+    rescue ActiveRecord::RecordInvalid => e
+      failed(e.record.errors)
     end
   end
 end
 ```
 
-This example demonstrates how to chain multiple operations, handle potential failures at each step, and return an appropriate outcome with a specific response type. Note how the `with_response` and `with_message` methods are used to set the response and add a message to the outcome.
+Every link here is a **private method of this one interaction** resolving an input, not a separate interaction — so nothing in the chain needs a `view_context` of its own, and `Order.place!` stays callable from a job or an API. That's the shape `and_then` is for: composing outcomes inside a single `execute`, not sequencing business operations across interactions.
 
-By following these guidelines and examples, you can effectively implement and use the Interaction pattern in your Rails applications, leading to more maintainable and testable code.
+Note also how `with_response` and `with_message` set the response and attach a message to the outcome.
 
 <!--
 

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Interaction
+    module Async
+      # Configuration for async interactions. Mirrors
+      # Plutonium::Wizard::Configuration: `enabled` gates both the subsystem and
+      # its migrations (see Plutonium::Migrations).
+      class Configuration
+        # @return [Boolean] whether runs (and their migrations) are enabled
+        attr_accessor :enabled
+
+        # @return [Symbol] ActiveJob queue for run jobs
+        attr_accessor :queue
+
+        # @return [ActiveSupport::Duration] how long a run may sit with no
+        #   progress write before ReapJob considers it stalled
+        attr_accessor :stall_after
+
+        # @return [Symbol, nil] the storage backend used to stage an attachment
+        #   attribute into the run's options — `:active_storage` or `:shrine`.
+        #   `nil` falls back to `config.attachment_backend`, then to auto-detection.
+        #
+        #   A file cannot ride the options column: it is JSON, and the request's
+        #   tempfile is gone by the time the job runs. So an attachment attribute is
+        #   uploaded to the backend's cache at dispatch and carried as its token.
+        #   This is the knob for which backend does that, for runs alone.
+        attr_accessor :attachment_backend
+
+        def initialize
+          @enabled = false
+          @queue = :default
+          @stall_after = 1.hour
+        end
+      end
+    end
+  end
+end