plutonium 0.62.2 → 0.63.0

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

@@ -0,0 +1,394 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Interaction
+    module Async
+      # A persisted interaction run.
+      #
+      # STI base: authors subclass to define execution and failure policy, and the
+      # subclass name lands in +type+. Options are JSON, so an async action costs
+      # no migration.
+      #
+      # This class deliberately holds NO execution logic — that lives in the
+      # runs executor. It is the record; the executor is the behaviour. Keeping
+      # them apart is what lets the job rebuild an authorization context around
+      # the work without the model knowing anything about policies.
+      class Run < ActiveRecord::Base
+        # Before the belongs_to declarations below: Record::Associations decorates
+        # belongs_to/has_many to generate the sgid accessors, so an association
+        # declared above the include gets none. It is also what makes a run
+        # registerable as a resource — Resource::Register refuses anything that
+        # does not include this.
+        include Plutonium::Resource::Record
+
+        self.table_name = "plutonium_async_runs"
+
+        STATES = %w[pending running completed failed].freeze
+        IN_PROGRESS_STATES = %w[pending running].freeze
+        FAILURE_POLICIES = %i[halt continue transactional].freeze
+
+        # Routes, paths and helpers are all derived from model_name, and the
+        # default would spell the gem's own namespace out in every URL
+        # (/admin/plutonium/interaction/runs) and every helper
+        # (plutonium_async_run_path). Pinned to the BASE class rather than
+        # +self+ so every STI subclass routes to the one registered resource:
+        # resource_url_for(a TestPostRun) has to find the Run's route config.
+        #
+        # "Run" rather than the shorter "Run" on purpose: a bare "Run"
+        # would squat the most generic name available and collide silently with a
+        # host app's own Run model (CI runs, ML training runs, delivery runs) on
+        # every axis that matters -- route path, controller name, param_key and
+        # i18n key are all identical, and nothing in Resource::Register detects it.
+        MODEL_NAME = ActiveModel::Name.new(self, nil, "AsyncRun")
+
+        def self.model_name = MODEL_NAME
+
+        # Failure policy, declared by subclasses via +on_failure+ and consumed by
+        # the executor. A class_attribute rather than a plain class ivar so a
+        # deep STI hierarchy (B < A < Run) inherits what A declared.
+        class_attribute :failure_policy, instance_writer: false, default: :halt
+
+        belongs_to :initiator, polymorphic: true
+        # The nested-route parent, present only for a dispatch from a nested
+        # route. Paired with +parent_association+; see the migration.
+        belongs_to :parent, polymorphic: true, optional: true
+        # Nullable by design: only entity-scoped portals have a tenant. nil means
+        # "no tenant", NOT "tenant unknown".
+        belongs_to :scoped_entity, polymorphic: true, optional: true
+
+        validates :state, inclusion: {in: STATES}
+
+        # Guarantees its own job gets enqueued once this row is durably visible
+        # (same shape as InviteToken#send_invitation_email) — not done by the
+        # caller, which would race a fast/inline job adapter against the commit.
+        after_commit :enqueue_job, on: :create
+
+        scope :in_progress, -> { where(state: IN_PROGRESS_STATES) }
+        scope :for_target, ->(klass) { where(target_type: klass.to_s) }
+
+        # In progress with no recorded activity since +before+ — see
+        # Async::ReapJob. +last_activity_at+ is nil until a job actually claims
+        # the run (see Async::Executor#claim!), so a run never picked up at all
+        # falls back to +created_at+ — otherwise it would never match and a
+        # dropped enqueue would sit "pending" forever, unreapable.
+        scope :stalled, ->(before:) {
+          in_progress.where("COALESCE(last_activity_at, created_at) < ?", before)
+        }
+
+        # Overrides the generic scope Record::AssociatedWith installs, which
+        # resolves a tenant by walking reflections. Both of this table's links to
+        # a tenant are POLYMORPHIC, and that walk skips polymorphic associations
+        # (it cannot know the class) — so the generic version raises
+        # "could not resolve the association" for every host tenant model.
+        #
+        # The tenant a run belongs to is not a fact about the object graph anyway:
+        # it is the scope the run was DISPATCHED in, recorded on the row. Reading
+        # it from the row is what makes the tenant filter mean the same thing here
+        # as it did at dispatch, for any host tenant model, with no host-side
+        # scope to define.
+        #
+        # A nil scoped_entity is therefore excluded from every tenant, which is
+        # the correct direction: nil means "dispatched outside any tenant", so it
+        # belongs to none of them.
+        scope :associated_with, ->(entity) { where(scoped_entity: entity) }
+
+        # Declares how the executor reacts to a target failure. Rejects an unknown
+        # policy at class-definition time rather than letting a typo surface as
+        # surprise behaviour deep inside a background job.
+        #
+        # @param policy [Symbol] one of {FAILURE_POLICIES}
+        # @return [void]
+        def self.on_failure(policy)
+          unless FAILURE_POLICIES.include?(policy)
+            raise ArgumentError,
+              "unknown failure policy: #{policy.inspect} (expected one of #{FAILURE_POLICIES.map(&:inspect).join(", ")})"
+          end
+
+          self.failure_policy = policy
+        end
+
+        def start! = update!(state: "running", started_at: Time.current, last_activity_at: Time.current)
+
+        def finish! = update!(state: "completed", finished_at: Time.current, last_activity_at: Time.current)
+
+        def fail!(message = nil)
+          record_target_failure!(id: nil, message: message) if message
+          update!(state: "failed", finished_at: Time.current, last_activity_at: Time.current)
+        end
+
+        def in_progress? = IN_PROGRESS_STATES.include?(state)
+
+        # What actually happened, as opposed to how the executor exited.
+        #
+        # A :continue run that could not apply some of its targets ends as
+        # +completed+ (see Async::Executor#perform_targets) — the author declared
+        # partial application acceptable and the loop ran to the end. But
+        # "completed" on its own is what a clean success looks like, so rendering
+        # it alone would make a run that under-applied indistinguishable from one
+        # that did everything asked of it. Every reader — badge, table column,
+        # progress panel — goes through this instead of through +state+.
+        #
+        # @return [String]
+        def outcome
+          (state == "completed" && errors_log.any?) ? "completed_with_errors" : state
+        end
+
+        # @return [Integer] recorded target failures, run-level entries included
+        def error_count = errors_log.size
+
+        # Human, I18n-aware name of the target resource class — "Post", not
+        # "Blogging::Post" — for display (see Async::RunDefinition). Falls back to the
+        # raw string for a target_type renamed/removed since this run was
+        # dispatched, rather than raising on an old row. nil for opaque
+        # (untargeted) work.
+        #
+        # @return [String, nil]
+        def target_label
+          return nil if target_type.nil?
+
+          target_type.constantize.model_name.human
+        rescue NameError
+          target_type
+        end
+
+        # Runs have no name or title, so Labeling would fall back to
+        # "Async run #12" — true but silent about the only thing that
+        # distinguishes one row from the next.
+        #
+        # Demodulized: a host's run class is as likely to be
+        # Billing::ReissueInvoicesRun as a top-level one, and the namespace adds
+        # nothing to a label that already sits under the run's own breadcrumb.
+        #
+        # Except when demodulizing is what throws the name away. A run declared
+        # by Dispatchable#async is Blogging::ArchivePosts::Run, and every
+        # one of them would render "Run #12" — the failure mode this method
+        # exists to avoid, reintroduced for the shape most authors will write.
+        # For those, the enclosing segment IS the name, so it is folded back in.
+        #
+        # @return [String]
+        def to_label
+          parts = self.class.name.split("::")
+          name = (parts.last == "Run" && parts.size > 1) ? "#{parts[-2]}Run" : parts.last
+          "#{name.titleize} ##{to_param}"
+        end
+
+        # nil means INDETERMINATE, not zero: opaque work has no denominator, and
+        # the progress UI renders a spinner rather than a 0% bar.
+        #
+        # @return [Float, nil]
+        def progress_fraction
+          return nil if progress_total.nil? || progress_total.zero?
+
+          progress_done.to_f / progress_total
+        end
+
+        # Appends a failure to +errors_log+ and persists immediately, preserving
+        # prior entries. It writes rather than staging because the information it
+        # carries — which targets the run could not act on — must survive an early
+        # return, a rescue that never reaches {#fail!}, or a caller that simply
+        # forgets to save. A silently-dropped entry is indistinguishable from a
+        # clean run, which is the one thing an operator must never be told.
+        #
+        # A nil +id+ is the RUN-LEVEL sentinel: the failure is the whole run's
+        # (see {#fail!}), not one target's — it advances neither progress_done
+        # nor handled_target_ids. Readers grouping the log by target must treat
+        # nil as its own bucket rather than a target id.
+        def record_target_failure!(id:, message:)
+          record_target_failures!([{id: id, message: message}])
+        end
+
+        # Appends several failures in ONE write — folding in the progress bump
+        # and handled_target_ids for every entry that names a real target, so a
+        # crash between separate writes can't leave them out of sync with each
+        # other.
+        #
+        # The singular form persists on every call, so a loop over M ids is M
+        # writes, each rewriting the whole errors_log JSON — O(M²) bytes. The
+        # executor resolves every unavailable target in one pass before it
+        # performs anything (see Async::Executor#record_unresolved), and that
+        # batch is what this exists for.
+        #
+        # @param entries [Array<Hash>] +{id:, message:}+ pairs
+        def record_target_failures!(entries)
+          return if entries.empty?
+
+          target_entries = entries.reject { |entry| entry[:id].nil? }
+          appended = entries.map { |entry| {"target_id" => entry[:id], "message" => entry[:message]} }
+          update!(
+            errors_log: errors_log + appended,
+            progress_done: progress_done + target_entries.size,
+            handled_target_ids: handled_target_ids + target_entries.map { |entry| entry[:id].to_s },
+            last_activity_at: Time.current
+          )
+        end
+
+        # Target ids not yet dispositioned — what a resumed run still has to
+        # do. See {#record_target_failures!} and Async::Executor#advance!, which
+        # are what populate handled_target_ids.
+        #
+        # @return [Array]
+        def unhandled_target_ids
+          handled = handled_target_ids.map(&:to_s).to_set
+          target_ids.reject { |id| handled.include?(id.to_s) }
+        end
+
+        # The interaction's validated inputs, with the types dispatch put in.
+        #
+        # The column is JSON, so Dispatchable#dispatch_options writes it through
+        # ActiveJob::Arguments; this is the other half. Without it a Date comes
+        # back a String and a BigDecimal comes back a String, which is the kind of
+        # bug that survives every test written against a run whose options happen
+        # to be strings anyway.
+        #
+        # Falls back to the raw hash for a row written before this existed, and
+        # for one an operator edited by hand — neither carries the envelope keys
+        # deserialize expects, and refusing to read them would take out the
+        # progress page as well as the work.
+        #
+        # @return [Hash]
+        def options
+          raw = super
+          return raw unless raw.is_a?(Hash)
+
+          ::ActiveJob::Arguments.deserialize([raw]).first
+        rescue ::ActiveJob::DeserializationError
+          raw
+        end
+
+        # An attachment attribute, revived from the token dispatch staged.
+        #
+        # A file cannot ride the options column, so dispatch uploads it to the
+        # backend's cache and stores the token (see
+        # Dispatchable#stage_dispatch_attachments). +options["file"]+ is therefore
+        # that token — a String — and this is what turns it back into something
+        # with a filename and bytes.
+        #
+        #   async do
+        #     def perform
+        #       CSV.foreach(attachment(:import_file).url) { |row| ... }
+        #     end
+        #   end
+        #
+        # Deliberately not folded into +options+. The token is what is actually
+        # stored, and reviving it reaches storage — which the progress page reads
+        # options without wanting to do.
+        #
+        # @param key [Symbol, String] the attribute name
+        # @return [Plutonium::Attachments::Resolved, nil] nil if nothing was
+        #   staged, or the token no longer resolves
+        def attachment(key) = attachments(key).first
+
+        # Every attachment staged under +key+, for a multiple-file attribute.
+        #
+        # @param key [Symbol, String]
+        # @return [Array<Plutonium::Attachments::Resolved>]
+        def attachments(key) = Plutonium::Attachments.resolve(options[key.to_s])
+
+        # Says "still working" — for work the executor cannot see inside.
+        #
+        # Async::ReapJob treats a run silent past +stall_after+ as dead and resumes
+        # it. Every write the executor makes refreshes that clock, so a targeted
+        # run whose targets are quick heartbeats once per target for free. Two
+        # shapes of work get nothing:
+        #
+        # * OPAQUE work. Between the claim and {#finish!} the executor writes
+        #   nothing at all, because there is nothing to count. An opaque +perform+
+        #   that outlives stall_after is reaped mid-flight, and — having no
+        #   handled_target_ids to resume from — is re-run FROM SCRATCH.
+        # * A single +perform_on+ that outlives stall_after on its own.
+        #
+        # So a run that does either must say so itself. This is deliberately not
+        # automatic: a background thread would have to guess how often to write,
+        # and would keep reporting a wedged worker as healthy. Only the work knows
+        # it is making progress.
+        #
+        #   def perform
+        #     invoices.each_slice(500) do |slice|
+        #       reissue(slice)
+        #       heartbeat!
+        #     end
+        #   end
+        #
+        # It also ANSWERS: the write is conditional on this instance still holding
+        # the row's lock_version, so a worker superseded while inside a long
+        # +perform+ learns at its next beat rather than at the end — see
+        # Async::Executor#superseded?, which turns that into "no longer mine"
+        # instead of a failure. That is the only place a long opaque run can find
+        # out at all.
+        #
+        # The beat must NOT bump lock_version — that is the executor's own record
+        # it would be invalidating, making its next save! raise against a row
+        # nobody else touched. Which rules out more than it looks like:
+        #
+        # * +touch+ and +update!+ both bump it (Locking::Optimistic hooks
+        #   _touch_row as well as _update_record).
+        # * so does +update_all+ GIVEN A HASH. Rails silently adds the increment
+        #   when the model locks and the hash does not mention the column — see
+        #   ActiveRecord::Relation#update_all. Only the string/array form escapes
+        #   it, going through sanitize_sql_for_assignment untouched, which is why
+        #   this and Async::Executor#claim! both spell their SQL out.
+        #
+        # The in-memory attribute is left alone for a related reason: nothing
+        # reads it, and assigning it would put a change on the record that the
+        # caller never asked to save.
+        #
+        # Call it on SELF, which is what +perform+/+perform_on+ already hand the
+        # author. The conditional reads this instance's lock_version, and the
+        # executor's own writes keep that current; a separately loaded copy
+        # (Run.find(id)) goes stale at the first advance! and would raise here
+        # having been superseded by nobody.
+        #
+        # Under the +:transactional+ policy the beat is inside the batch's
+        # transaction like everything else, so it is invisible to the reaper until
+        # the batch commits. An all-or-nothing batch longer than stall_after is
+        # reapable no matter what this does.
+        #
+        # @raise [ActiveRecord::StaleObjectError] if another executor owns the run
+        # @return [Time] the recorded activity time
+        def heartbeat!
+          now = Time.current
+          written = self.class.where(id: id, lock_version: lock_version)
+            .update_all(["last_activity_at = ?", now])
+          raise ActiveRecord::StaleObjectError.new(self, "heartbeat") if written.zero?
+
+          now
+        end
+
+        # Which shape of work this is, decided by what the subclass implements
+        # rather than a mode flag — one less thing for an author to keep in sync.
+        #
+        # Non-public methods count. `private def perform_on(record)` is a natural
+        # idiom for work only the executor is meant to invoke, and Ruby's
+        # public-only respond_to? default would read that as opaque work — routing
+        # it to #perform, which the base class raises NotImplementedError for. The
+        # author would see every dispatch fail on a run whose perform_on is right
+        # there. Async::Executor invokes both through send to match.
+        def targeted? = respond_to?(:perform_on, true)
+
+        # Opaque (untargeted) work. Subclasses override this, or +perform_on+ for
+        # per-target work.
+        #
+        # Defined here so a subclass that implements NEITHER is diagnosed by name
+        # rather than surfacing as a NoMethodError from inside the executor's loop,
+        # where nothing in the message says which class is at fault.
+        def perform
+          raise NotImplementedError,
+            "#{self.class} implements neither #perform nor #perform_on: define " \
+            "#perform_on(record) for work over targets, or #perform for opaque work"
+        end
+
+        private
+
+        # Not swallowed: after_commit runs synchronously, so re-raising here
+        # still surfaces to the dispatching request rather than leaving a
+        # permanently invisible, un-enqueued ghost.
+        def enqueue_job
+          Plutonium::Interaction::Async::Job.perform_later(id)
+        rescue
+          fail!("could not be enqueued for execution")
+          raise
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Interaction
+    module Async
+      # The UI configuration for run records.
+      #
+      # Named +RunDefinition+ rather than +Async::Definition+ because definition
+      # lookup is by convention and nothing else: both
+      # Plutonium::Resource::Controller#resource_definition and
+      # Plutonium::Resource::Controllers::Defineable#resource_definition
+      # constantize "#{resource_class}Definition", and
+      # Plutonium::Definition::Base.model_class infers the model back out of that
+      # same name. A differently-named class would simply never be found.
+      #
+      # Host apps override per portal the usual way, with
+      # +MyPortal::Plutonium::Interaction::Async::RunDefinition+.
+      class RunDefinition < Plutonium::Resource::Definition
+        # `outcome` rather than `state`: a :continue run that could not apply some
+        # of its targets ends as "completed", and a green Completed badge on a run
+        # that under-applied is exactly the report an operator must never be given.
+        # See Plutonium::Interaction::Async::Run#outcome.
+        # Only `outcome` is declared. Everything else the policy makes readable is
+        # a real column and infers its own type; `outcome` is a method, so it has
+        # neither a type to infer nor a badge to infer one from (`state` is a
+        # plain string column with an inclusion validation, not a Rails enum).
+        #
+        # `running` and `completed_with_errors` are coloured explicitly: neither
+        # is in the badge component's semantic table, and its fallback is a
+        # stable-but-meaningless colour.
+        field :outcome, as: :string
+        display :outcome, as: :badge,
+          colors: {running: :info, completed_with_errors: :warning}
+        # Declared for the table too: the index is where an operator scans for the
+        # run that did not do what it was asked, and a bare
+        # "completed_with_errors" string is the one place that reads worse than
+        # the badge.
+        column :outcome, as: :badge,
+          colors: {running: :info, completed_with_errors: :warning}
+
+        field :target_label, label: "Target type"
+
+        # The details tab, with the live panel above the fields.
+        #
+        # On the Display rather than the ShowPage: page-level
+        # render_before_content sits outside the tablist and outside the modal
+        # chrome, so a run opened in a modal would render its progress above the
+        # dialog instead of inside it.
+        class Display < Display
+          private
+
+          def render_before_fields
+            render Plutonium::UI::Interaction::Async::RunProgress.new(resource_record!)
+          end
+        end
+
+        class ShowPage < ShowPage
+          # Answers the progress frame's poll with the panel ALONE.
+          #
+          # Turbo sends +Turbo-Frame: <id>+ when the frame re-fetches its src, and
+          # DynaFrameContent wraps every response in a frame of that name. Falling
+          # through to the normal page would therefore return the whole show page
+          # wrapped in a frame carrying the progress frame's id — with the panel's
+          # own frame nested inside it, under the same id. Turbo would swap the
+          # outer one in, and the next poll would nest again.
+          def view_template(&)
+            return super unless progress_poll?
+
+            DynaFrameContent do
+              render Plutonium::UI::Interaction::Async::RunProgress.new(resource_record!)
+            end
+          end
+
+          private
+
+          def progress_poll?
+            current_turbo_frame == Plutonium::UI::Interaction::Async::RunProgress.frame_id(resource_record!)
+          end
+        end
+
+        # The index refreshes itself while any run is still working.
+        #
+        # ONE frame around the collection, not one per row. A +turbo-frame+ is
+        # not in the content model of +tr+, so a frame wrapping a row is hoisted
+        # out of the table by the HTML parser before Turbo ever sees it. A frame
+        # per CELL parses, but buys one poller per row for a single page.
+        #
+        # The Stimulus controller sits INSIDE the frame, exactly as
+        # {Plutonium::UI::Interaction::Async::RunProgress} places it: a frame
+        # navigation replaces the frame's CONTENTS, not the frame element, so a
+        # controller on the tag itself could never be removed and the timer
+        # would never stop.
+        class IndexPage < IndexPage
+          include Phlex::Rails::Helpers::TurboFrameTag
+
+          FRAME_ID = "pu_async_runs_index"
+
+          # Answers the frame's poll with the collection ALONE, for the reason
+          # spelled out on {ShowPage}: DynaFrameContent already wraps every
+          # response in a frame named by the inbound header, so emitting the
+          # page would nest the whole thing inside its own frame, and again on
+          # the next poll.
+          def view_template(&)
+            return super unless answering_own_frame?
+
+            DynaFrameContent() do
+              render_default_content
+            end
+          end
+
+          private
+
+          def answering_own_frame? = current_turbo_frame == FRAME_ID
+
+          def render_default_content
+            body = proc { div(**poll_attributes) { super() } }
+            return body.call if answering_own_frame?
+
+            # `turbo-frame` defaults to `display: inline`.
+            turbo_frame_tag(FRAME_ID, class: "block", &body)
+          end
+
+          # Absent once nothing is working: the refreshed markup no longer
+          # carries the controller, and the timer stops of its own accord. The
+          # index needs no equivalent of RunProgress's +finished+ reload — the
+          # whole collection is inside this frame, so there are no stale fields
+          # beside it to catch up.
+          #
+          # The URL is the CURRENT one, filters, sort and page included. Polling
+          # the bare index would answer page 1 unfiltered and swap that into a
+          # frame the operator had scoped to something else.
+          def poll_attributes
+            return {} unless any_run_in_progress?
+
+            {
+              data: {
+                controller: "run-progress",
+                run_progress_url_value: current_page_url,
+                run_progress_interval_value: Plutonium::UI::Interaction::Async::RunProgress::POLL_INTERVAL_MS
+              }
+            }
+          end
+
+          # Asked of the SCOPE rather than the rendered page, through the same
+          # door render_running_banner uses. It can only over-poll (an operator
+          # reading last month's finished runs while something works elsewhere),
+          # never under-poll: a run visible and in progress makes this true.
+          def any_run_in_progress?
+            authorized_resource_scope(Run, relation: Run.in_progress).exists?
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Interaction
+    module Async
+      # Authorization for run records themselves.
+      #
+      # Named +RunPolicy+ rather than +Policy+ so ActionPolicy's ordinary
+      # inference finds it: +INFER_FROM_CLASS+ looks for "#{record_class}Policy",
+      # and Plutonium's STI fallback looks for "#{base_class}Policy" — which is
+      # what routes a +TestPostRun+ (or any host subclass) to this one policy
+      # without every subclass declaring anything.
+      #
+      # == Read-only
+      #
+      # A run is the record of something that already happened. There is nothing
+      # to create through a form (a run is born from a dispatching interaction,
+      # which has its own policy), nothing to edit that would not be rewriting the
+      # audit trail, and deleting one destroys the only report of what a bulk
+      # action actually did. The four write predicates are therefore hard +false+
+      # rather than inherited defaults — subclasses can still open them, but they
+      # have to say so.
+      #
+      # == Scope
+      #
+      # Nothing is declared here. The base policy's +relation_scope+ already calls
+      # +default_relation_scope+, which applies +Run.associated_with(entity_scope)+
+      # — and that scope filters on the tenant the run RECORDED at dispatch (see
+      # Run). Re-declaring the macro to repeat that filter by hand would add a
+      # second, drifting definition of the same rule; declaring it as a
+      # +def relation_scope+ instance method would be worse still, since
+      # +apply_scope+ never calls one (Plutonium::Resource::Policy.method_added
+      # raises on that mistake at class load).
+      class RunPolicy < Plutonium::Resource::Policy
+        def read? = true
+
+        def create? = false
+
+        def update? = false
+
+        def destroy? = false
+
+        # Deliberately NOT the autodetected column list.
+        #
+        # +options+ is arbitrary JSON copied from the dispatching interaction's
+        # validated inputs — reasons, notes, recipient lists, whatever the author
+        # declared. The policy that governed who could SUBMIT those values was the
+        # interaction's; the set of people who can READ this run is different and
+        # wider (in a tenant portal, everyone in the tenant). Autodetection would
+        # quietly hand the second set the first set's input, so the readable
+        # attributes are enumerated instead, and +options+ is not among them.
+        #
+        # +target_ids+ is out for the same reason at one remove: it is a list of
+        # primary keys that were never filtered through the target resource's own
+        # policy for THIS reader.
+        # +outcome+ stands in for +state+, and +state+ is deliberately absent: the
+        # two differ only for a run that completed having failed some of its
+        # targets, and that is precisely the case where the raw column reads
+        # "completed" and tells the reader the opposite of what happened.
+        #
+        # +errors_log+ is absent because the progress panel renders it as a list —
+        # the raw JSON column beside it would be the same report twice, once
+        # unreadably.
+        def permitted_attributes_for_read
+          %i[
+            type outcome progress_done progress_total
+            target_label initiator started_at finished_at created_at
+          ]
+        end
+
+        # The show page drops the progress COUNTERS, for the reason errors_log
+        # is absent above: the panel already renders them, as "5 of 5 targets
+        # (100%)" over a bar. Two renderings of one number is the same report
+        # twice — and they disagree, because only the panel is inside the polled
+        # frame. A page that says "Completed" and "0 done" at once is worse than
+        # either alone.
+        #
+        # The INDEX keeps them. There is no progress bar in a table row, so the
+        # counters are the only progress it can show.
+        def permitted_attributes_for_show
+          permitted_attributes_for_read - %i[progress_done progress_total]
+        end
+      end
+    end
+  end
+end