plutonium 0.68.0 → 0.69.0

data/docs/superpowers/plans/2026-10-15-async-run-pre-check.md.tasks.json

@@ -0,0 +1,49 @@
+{
+  "planPath": "docs/superpowers/plans/2026-10-15-async-run-pre-check.md",
+  "tasks": [
+    {
+      "id": 0,
+      "subject": "Task 1: Run model: reject, reject_run!, rejected outcome, max_rejections",
+      "status": "completed",
+      "description": "**Goal:** `Run` can collect rejections during a check, persist them in one write, and report `outcome == \"rejected\"`.\n\n**Files:**\n- Modify: `lib/plutonium/interaction/async/configuration.rb`\n- Modify: `lib/plutonium/interaction/async/run.rb`\n- Modify: `config/locales/en/async.yml`\n- Test: `test/plutonium/interaction/async/run_test.rb`\n\n**Acceptance Criteria:**\n- [ ] `config.async_interactions.max_rejections` defaults to 100.\n- [ ] `reject` raises outside `collect_rejections`; inside, it stores up to `max_rejections` messages and counts the rest.\n- [ ] `reject_run!(messages, overflow:)` writes entries tagged `\"stage\" => \"pre_check\"`, a truncation entry when `overflow > 0`, and `state: \"failed\"` in a single UPDATE.\n- [ ] `outcome` is `\"rejected\"` for a failed run with a tagged entry; untagged failed runs still read `\"failed\"`.\n\n**Verify:** `bundle exec appraisal rails-8.1 ruby -Itest test/plutonium/interaction/async/run_test.rb` \u2192 0 failures, 0 errors\n\nSee plan section 'Task 1: Run model: reject, reject_run!, rejected outcome, max_rejections' for steps.\n\n```json:metadata\n{\"files\": [\"lib/plutonium/interaction/async/configuration.rb\", \"lib/plutonium/interaction/async/run.rb\", \"config/locales/en/async.yml\", \"test/plutonium/interaction/async/run_test.rb\"], \"verifyCommand\": \"bundle exec appraisal rails-8.1 ruby -Itest test/plutonium/interaction/async/run_test.rb\", \"acceptanceCriteria\": [\"max_rejections defaults to 100\", \"reject raises outside collect_rejections and caps stored messages\", \"reject_run! writes tagged entries and failed in one UPDATE\", \"outcome reads rejected only for tagged failed runs\"], \"requiresUserVerification\": false}\n```"
+    },
+    {
+      "id": 1,
+      "subject": "Task 2: Executor runs the check before the work",
+      "status": "completed",
+      "description": "**Goal:** The executor calls `pre_check` with the right arguments for the run's shape and stops before any work when it rejects.\n\n**Files:**\n- Modify: `lib/plutonium/interaction/async/executor.rb` (`perform_opaque`, `perform_targets`, new private methods)\n- Modify: `config/locales/en/async.yml`\n- Test: `test/plutonium/interaction/async/executor_test.rb`\n\n**Acceptance Criteria:**\n- [ ] Opaque and targeted runs whose check rejects nothing perform as before.\n- [ ] A rejection stops `perform` / `perform_on`; `progress_done` stays 0; `outcome == \"rejected\"`.\n- [ ] Every rejection is recorded; past `max_rejections`, one \"and N more\" entry with the exact remainder.\n- [ ] An exception raised in `pre_check` reads `failed`, not `rejected`.\n- [ ] A wrong-arity `pre_check` fails the run with a message naming the class and expected signature.\n- [ ] A resumed targeted run's check receives only the unhandled records.\n- [ ] A `:transactional` run is rejected without opening a transaction.\n\n**Verify:** `bundle exec appraisal rails-8.1 ruby -Itest test/plutonium/interaction/async/executor_test.rb` \u2192 0 failures, 0 errors\n\nSee plan section 'Task 2: Executor runs the check before the work' for steps.\n\n```json:metadata\n{\"files\": [\"lib/plutonium/interaction/async/executor.rb\", \"config/locales/en/async.yml\", \"test/plutonium/interaction/async/executor_test.rb\"], \"verifyCommand\": \"bundle exec appraisal rails-8.1 ruby -Itest test/plutonium/interaction/async/executor_test.rb\", \"acceptanceCriteria\": [\"passing checks perform as before\", \"rejection stops work, progress_done 0, outcome rejected\", \"cap with exact remainder\", \"exception in check reads failed\", \"wrong arity names expected signature\", \"resumed run checks remaining records only\", \"transactional rejection opens no batch transaction\"], \"requiresUserVerification\": false}\n```",
+      "blockedBy": [
+        0
+      ]
+    },
+    {
+      "id": 2,
+      "subject": "Task 3: Show rejected runs on the progress page and index",
+      "status": "completed",
+      "description": "**Goal:** A rejected run shows a warning \"Rejected\" badge, a \"Nothing was processed\" line, and its messages.\n\n**Files:**\n- Modify: `lib/plutonium/ui/interaction/async/run_progress.rb` (`BADGE_VARIANTS`, `render_panel`, new `render_rejected`)\n- Modify: `lib/plutonium/interaction/async/run_definition.rb` (both `colors:` hashes)\n- Modify: `config/locales/en/async.yml`\n- Test: `test/integration/admin_portal/async_run_progress_test.rb`\n\n**Acceptance Criteria:**\n- [ ] The show page renders a `pu-badge-warning` badge reading \"Rejected\", the line \"Nothing was processed\", and every rejection message.\n- [ ] A plain failed run does not show \"Nothing was processed\".\n- [ ] The index renders \"Rejected\" for the run.\n\n**Verify:** `bundle exec appraisal rails-8.1 ruby -Itest test/integration/admin_portal/async_run_progress_test.rb` \u2192 0 failures, 0 errors\n\nSee plan section 'Task 3: Show rejected runs on the progress page and index' for steps.\n\n```json:metadata\n{\"files\": [\"lib/plutonium/ui/interaction/async/run_progress.rb\", \"lib/plutonium/interaction/async/run_definition.rb\", \"config/locales/en/async.yml\", \"test/integration/admin_portal/async_run_progress_test.rb\"], \"verifyCommand\": \"bundle exec appraisal rails-8.1 ruby -Itest test/integration/admin_portal/async_run_progress_test.rb\", \"acceptanceCriteria\": [\"warning Rejected badge, Nothing was processed, all messages on show page\", \"plain failed run lacks the line\", \"index shows Rejected\"], \"requiresUserVerification\": false}\n```",
+      "blockedBy": [
+        0
+      ]
+    },
+    {
+      "id": 3,
+      "subject": "Task 4: Dummy CSV import with a pre_check, end to end",
+      "status": "completed",
+      "description": "**Goal:** A real interaction in the dummy app exercises dispatch \u2192 staged file \u2192 pre_check \u2192 rejected or completed, and backs the docs example.\n\n**Files:**\n- Create: `test/dummy/app/interactions/import_tasks_interaction.rb`\n- Modify: `test/dummy/app/policies/task_policy.rb` (after `archive_all_async?`)\n- Modify: `test/dummy/app/definitions/task_definition.rb` (after `action :archive_all_async`)\n- Create: `test/integration/admin_portal/async_import_pre_check_test.rb`\n\n**Acceptance Criteria:**\n- [ ] Posting a CSV with bad rows creates a run that, once executed, reads `rejected`, lists one message per bad row, and creates no tasks.\n- [ ] Posting a valid CSV creates the tasks and the run reads `completed`.\n- [ ] The rejected run's progress page shows the badge and messages.\n\n**Verify:** `bundle exec appraisal rails-8.1 ruby -Itest test/integration/admin_portal/async_import_pre_check_test.rb` \u2192 0 failures, 0 errors\n\nSee plan section 'Task 4: Dummy CSV import with a pre_check, end to end' for steps.\n\n```json:metadata\n{\"files\": [\"test/dummy/app/interactions/import_tasks_interaction.rb\", \"test/dummy/app/models/task.rb\", \"test/dummy/app/policies/task_policy.rb\", \"test/dummy/app/definitions/task_definition.rb\", \"test/integration/admin_portal/async_import_pre_check_test.rb\"], \"verifyCommand\": \"bundle exec appraisal rails-8.1 ruby -Itest test/integration/admin_portal/async_import_pre_check_test.rb\", \"acceptanceCriteria\": [\"bad CSV rejected whole with one message per bad row and no tasks\", \"valid CSV imported and completed\", \"progress page shows Rejected and messages\"], \"requiresUserVerification\": false}\n```",
+      "blockedBy": [
+        1,
+        2
+      ]
+    },
+    {
+      "id": 4,
+      "subject": "Task 5: Docs and skill",
+      "status": "completed",
+      "description": "**Goal:** The reference doc and the shipped skill explain `pre_check`, `reject`, the `rejected` outcome, `max_rejections`, and the heartbeat requirement, with samples that match the dummy app.\n\n**Files:**\n- Modify: `docs/reference/behavior/async-interactions.md`\n- Modify: `.claude/skills/plutonium-async-interactions/SKILL.md`\n\n**Acceptance Criteria:**\n- [ ] A \"Checking input before processing\" section after \"### Files\" in the doc, and after \"## Attributes and files\" in the skill.\n- [ ] `max_rejections` in the doc's Enabling config block.\n- [ ] \"Outcome vs state\" documents `rejected`.\n- [ ] Both heartbeat warnings mention `pre_check`.\n- [ ] No em dashes; samples match `ImportTasksInteraction`.\n- [ ] `yarn docs:build` passes.\n\n**Verify:** `yarn docs:build` \u2192 completes without dead-link errors\n\nSee plan section 'Task 5: Docs and skill' for steps.\n\n```json:metadata\n{\"files\": [\"docs/reference/behavior/async-interactions.md\", \".claude/skills/plutonium-async-interactions/SKILL.md\"], \"verifyCommand\": \"yarn docs:build\", \"acceptanceCriteria\": [\"new section in doc and skill\", \"max_rejections in config block\", \"rejected in Outcome vs state\", \"heartbeat notes mention pre_check\", \"no em dashes\", \"docs build passes\"], \"requiresUserVerification\": false}\n```",
+      "blockedBy": [
+        3
+      ]
+    }
+  ],
+  "lastUpdated": "2026-10-15T04:38:35.300061+00:00"
+}

data/docs/superpowers/specs/2026-10-15-async-run-pre-check-design.md

@@ -0,0 +1,208 @@
+# Async run pre_check
+
+**Status:** approved design, not yet planned
+**Date:** 2026-10-15
+**Area:** `lib/plutonium/interaction/async/`
+
+## Problem
+
+An async run has no stage for refusing its input. Cheap file checks already run
+synchronously (the uploader's `Attacher.validate` rules run during interaction
+validation, so a wrong type or size fails the form). Checks too slow or too deep
+for a request have nowhere to go: parsing a 50k-row CSV, checking its headers,
+validating every row, looking up referenced records. Today the only option is to
+raise inside `perform`, which reads as a crash partway through and gives the user
+one problem per attempt.
+
+## Decisions
+
+| Question | Decision |
+|---|---|
+| After the check passes | Processing starts in the same job. No confirmation step. |
+| Reporting problems | Collect every problem, then reject the run if any were recorded. |
+| How a rejected run reads | `state` stays `failed`; `outcome` reads `rejected`. |
+| Declaration style | A plain method in the run class, like `perform` / `perform_on`. |
+| Cap on stored problems | Configurable, `config.async_interactions.max_rejections`, default 100. |
+
+## API
+
+```ruby
+async do
+  def pre_check
+    attachment(:import_file).open do |f|
+      CSV.foreach(f, headers: true).with_index(2) do |row, line|
+        reject "line #{line}: missing email" if row["email"].blank?
+        heartbeat! if (line % 1_000).zero?
+      end
+    end
+  end
+
+  def perform
+    # only runs if pre_check rejected nothing
+  end
+end
+```
+
+A targeted run's check receives the resolved, authorized records:
+
+```ruby
+async do
+  def pre_check(invoices)
+    currencies = invoices.map(&:currency).uniq
+    reject "mixed currencies: #{currencies.join(", ")}" if currencies.size > 1
+  end
+
+  def perform_on(invoice)
+    invoice.reissue!
+  end
+end
+```
+
+### `Run#pre_check` / `Run#pre_check(records)`
+
+- Optional. The base class defines a no-op, so existing runs are unaffected.
+- Invoked through `send`, matching how `perform` / `perform_on` are invoked, so a
+  private definition works.
+- Arguments follow the run's shape: none for opaque work, the resolved records for
+  targeted work. A definition with the wrong arity fails the run with a message
+  naming the class and the expected signature.
+
+### `Run#reject(message)`
+
+- Records one problem and returns, so the check can report every bad row in one
+  pass.
+- Valid only while `pre_check` runs. Called from `perform`, `perform_on`, or
+  anywhere else it raises, since a rejection nothing reads would be lost.
+
+## Execution
+
+In `Async::Executor`, after `claim!`:
+
+- **Opaque:** `pre_check` → `perform` → `finish!`
+- **Targeted:** resolve targets → `record_unresolved` and the existing partial-batch
+  refusal for `:halt` / `:transactional` → `pre_check(resolved.records)` → the
+  per-target loop (or the transactional batch) → `finish!`
+
+`pre_check` sees only the records the loop is about to process. Missing or
+unauthorized ids are already recorded failures by then.
+
+After `pre_check` returns:
+
+- **Nothing rejected:** processing starts.
+- **Anything rejected:** the executor calls `Run#reject_run!(messages, overflow:)`. `perform` /
+  `perform_on` never run, no target is touched, and `progress_done` stays 0.
+
+An exception raised inside `pre_check` takes the existing failure path in
+`Executor#call`. That run reads `failed`, not `rejected`: "your input is wrong" and
+"the check itself broke" are different reports.
+
+## Recording
+
+No migration.
+
+Each rejection becomes an `errors_log` entry:
+
+```ruby
+{"target_id" => nil, "message" => "line 12: missing email", "stage" => "pre_check"}
+```
+
+- A nil `target_id` is already the run-level sentinel, so progress counters and
+  `handled_target_ids` are untouched.
+- `stage` is a new key. Entries written before it have none, and current readers
+  ignore unknown keys.
+
+`Run#reject_run!(messages, overflow:)` writes the entries and `state: "failed"`,
+`finished_at`, `last_activity_at` in one `update!`, so a crash cannot leave a
+failed run without its reasons or reasons on a run still marked running (the same
+reasoning as `record_target_failures!`).
+
+### Cap
+
+- Only the first `max_rejections` messages are stored.
+- When more were rejected, one extra entry (also `stage: "pre_check"`) records the
+  remainder: "and 4900 more problems were found"
+  (`plutonium.async.executor.rejections_truncated`, `one` / `other`).
+- `Async::Configuration#max_rejections`, default `100`. Not added to the install
+  generator's initializer template; documented with the other settings.
+- The cap is applied in `reject`: it stores at most `max_rejections` messages and
+  counts the rest, so memory stays bounded and the remainder is exact.
+  `reject_run!` receives the stored messages and the overflow count.
+
+## Outcome and display
+
+- `Run#outcome` returns `"rejected"` when `state == "failed"` and any `errors_log`
+  entry has `"stage" => "pre_check"`. A completed run can never carry such an
+  entry.
+- `state` stays `failed`, so `ReapJob`, `in_progress`, the running banner and the
+  poll-stop logic are unchanged.
+- **Badge:** `rejected: :warning` in the `display :outcome` and `column :outcome`
+  declarations in `RunDefinition`, and in `BADGE_VARIANTS` in
+  `lib/plutonium/ui/interaction/async/run_progress.rb`. Warning, not danger: the
+  input was refused and nothing broke.
+- **Badge text:** the existing `Plutonium::Translation.value_label` lookup
+  (`plutonium.values.*`), falling back to "Rejected".
+- **Progress panel:** a rejected run shows "Nothing was processed"
+  (`plutonium.async.progress.rejected`) above the failures list, so "0 of 50
+  targets" does not read as a run that died at its first target.
+- **Failures list:** unchanged. Entries with a nil `target_id` already render
+  without the `#id:` prefix.
+
+## Edge cases
+
+- **Resume after a reap:** A resumed opaque run re-runs `pre_check` then
+  `perform` from the start (as opaque work already does). A resumed targeted run
+  skips the check if an earlier pass applied a target (a handled id with no
+  failure entry; failed targets do not count), since targets are only performed
+  after the check passes. Otherwise it checks only the unhandled records.
+  Skipping keeps a half-applied run from being rejected as "nothing was
+  processed".
+- **`:transactional`:** `pre_check` runs before the transaction opens. A rejected
+  batch never opens one.
+- **Heartbeat:** the executor writes nothing while `pre_check` runs. A long check
+  must call `heartbeat!`, as opaque `perform` must today.
+- **Reaped mid-check:** `heartbeat!` and `reject_run!` both raise
+  `ActiveRecord::StaleObjectError` against a superseded row. `Executor#superseded?`
+  already turns that into "no longer mine".
+
+## Testing
+
+**Executor (`test/plutonium/interaction/async/executor_test.rb`)**
+- Opaque and targeted runs pass the check, then perform.
+- A rejection stops `perform` / `perform_on`; `progress_done` stays 0; outcome is
+  `rejected`.
+- Several rejections are all recorded.
+- The cap: `max_rejections` respected, plus the "and N more" entry with the exact
+  remainder.
+- An exception raised in `pre_check` reads `failed`, not `rejected`.
+- A wrong-arity `pre_check` fails with a message naming the expected signature.
+- `reject` outside `pre_check` raises.
+- A resumed targeted run's check receives only the remaining records.
+- A `:transactional` run is rejected without opening a transaction.
+
+**Run (`test/plutonium/interaction/async/run_test.rb`)**
+- `outcome` reads `rejected` from tagged entries; entries without `stage` are
+  unaffected.
+- `reject_run!` writes entries and state in one update.
+
+**Integration (`test/integration/admin_portal/`)**
+- The progress page shows the Rejected badge, the "Nothing was processed" line and
+  the messages; the index shows the badge.
+
+**Dummy app**
+- An opaque CSV import interaction in the admin portal, backing the integration
+  test and the docs example. Hand-authored: there is no interaction generator.
+
+## Docs
+
+- `docs/reference/behavior/async-interactions.md`: a "Checking input before
+  processing" section; `max_rejections` with the other settings.
+- `.claude/skills/plutonium-async-interactions/SKILL.md`: a matching section, and
+  `pre_check` added to the heartbeat warning in Critical.
+- Every sample checked against the implementation before it is published.
+
+## Out of scope
+
+- A confirmation step between check and processing.
+- Excluding individual targets from the check and processing the rest (the
+  `:continue` failure policy covers per-target failures).
+- Progress reporting for opaque work.

data/gemfiles/rails_7.gemfile.lock

@@ -9,7 +9,7 @@ GIT
 PATH
   remote: ..
   specs:
-    plutonium (0.66.0)
+    plutonium (0.68.0)
       action_policy (~> 0.7.0)
       csv
       listen (~> 3.8)
@@ -20,7 +20,7 @@ PATH
       phlex-tabler_icons
       phlexi-display (>= 0.2.0)
       phlexi-field (>= 0.2.0)
-      phlexi-form (>= 0.14.3)
+      phlexi-form (>= 0.14.4)
       phlexi-menu (>= 0.4.1)
       phlexi-table (>= 0.2.0)
       rabl (~> 0.17.0)
@@ -271,7 +271,7 @@ GEM
       fiber-local
       phlex (~> 2.0)
       zeitwerk
-    phlexi-form (0.14.3)
+    phlexi-form (0.14.4)
       activesupport
       phlex (~> 2.0)
       phlexi-field (~> 0.2.0)
@@ -608,10 +608,10 @@ CHECKSUMS
   phlex-tabler_icons (0.3.0) sha256=67d80cc09c619646cff171a620fa805cb49543625c3586a947cd752d44d2858e
   phlexi-display (0.2.0) sha256=73e22d01e7204a3b94dcb21432477982bfa5162926c11bacd7d48930114236de
   phlexi-field (0.2.0) sha256=ecb509cc2c0e0559f52651cac8d5dd2fca4bda3878cb7343ea7b298c760e7bca
-  phlexi-form (0.14.3) sha256=47d69c4a49ba22279ba541b9b110e81d62acc4602513f21bb5c3d29fa9c8d5ca
+  phlexi-form (0.14.4)
   phlexi-menu (0.4.1) sha256=f6eeb1eb9597caadeee33a53f1520b3613a6ac616cf1e395e9d734a412895fb2
   phlexi-table (0.2.0) sha256=73bee135adbe73fcdb6fdd2672444373556dd9e6bba61e7b5b20ca8b7a1f822c
-  plutonium (0.66.0)
+  plutonium (0.68.0)
   pp (0.6.4) sha256=dfcb0fce700c41456265922884f9fe195d7fbb0674a3578e6c0f69588e82b570
   prettyprint (0.2.0) sha256=2bc9e15581a94742064a3cc8b0fb9d45aae3d03a1baa6ef80922627a0766f193
   prism (1.9.0) sha256=7b530c6a9f92c24300014919c9dcbc055bf4cdf51ec30aed099b06cd6674ef85

data/gemfiles/rails_8.0.gemfile.lock

@@ -9,7 +9,7 @@ GIT
 PATH
   remote: ..
   specs:
-    plutonium (0.66.0)
+    plutonium (0.68.0)
       action_policy (~> 0.7.0)
       csv
       listen (~> 3.8)
@@ -20,7 +20,7 @@ PATH
       phlex-tabler_icons
       phlexi-display (>= 0.2.0)
       phlexi-field (>= 0.2.0)
-      phlexi-form (>= 0.14.3)
+      phlexi-form (>= 0.14.4)
       phlexi-menu (>= 0.4.1)
       phlexi-table (>= 0.2.0)
       rabl (~> 0.17.0)
@@ -252,7 +252,7 @@ GEM
       fiber-local
       phlex (~> 2.0)
       zeitwerk
-    phlexi-form (0.14.3)
+    phlexi-form (0.14.4)
       activesupport
       phlex (~> 2.0)
       phlexi-field (~> 0.2.0)

data/gemfiles/rails_8.1.gemfile.lock

@@ -9,7 +9,7 @@ GIT
 PATH
   remote: ..
   specs:
-    plutonium (0.66.0)
+    plutonium (0.68.0)
       action_policy (~> 0.7.0)
       csv
       listen (~> 3.8)
@@ -20,7 +20,7 @@ PATH
       phlex-tabler_icons
       phlexi-display (>= 0.2.0)
       phlexi-field (>= 0.2.0)
-      phlexi-form (>= 0.14.3)
+      phlexi-form (>= 0.14.4)
       phlexi-menu (>= 0.4.1)
       phlexi-table (>= 0.2.0)
       rabl (~> 0.17.0)
@@ -254,7 +254,7 @@ GEM
       fiber-local
       phlex (~> 2.0)
       zeitwerk
-    phlexi-form (0.14.3)
+    phlexi-form (0.14.4)
       activesupport
       phlex (~> 2.0)
       phlexi-field (~> 0.2.0)

data/lib/generators/pu/lite/maintenance/maintenance_generator.rb

@@ -10,10 +10,12 @@ module Pu
 
       source_root File.expand_path("templates", __dir__)
 
-      desc "Install a nightly SqliteMaintenanceJob (PRAGMA optimize + VACUUM)"
+      desc "Install a nightly SqliteMaintenanceJob (PRAGMA optimize + VACUUM) and schedule SolidQueue finished-job cleanup"
 
       class_option :schedule, type: :string, default: "every day at 3:30am",
         desc: "Cron-style schedule for the maintenance job"
+      class_option :clear_finished_schedule, type: :string, default: "every hour at minute 12",
+        desc: "Schedule for clearing finished SolidQueue jobs"
 
       def start
         template "app/jobs/sqlite_maintenance_job.rb"
@@ -22,6 +24,11 @@ module Pu
           unless add_recurring_tasks(maintenance_task_yaml, marker: "sqlite_maintenance")
             log :skip, "could not schedule (config/recurring.yml missing or already scheduled)"
           end
+          # Rails 8 apps ship this task already; the marker matches its command
+          # so we never schedule it twice under a different key.
+          unless add_recurring_tasks(clear_finished_jobs_task_yaml, marker: "clear_finished_in_batches")
+            log :skip, "finished-job cleanup not scheduled (config/recurring.yml missing or already scheduled)"
+          end
         else
           log :info, "solid_queue not found — job installed but not scheduled. Add a 'sqlite_maintenance' entry to your scheduler."
         end
@@ -40,6 +47,18 @@ module Pu
             description: "VACUUM + PRAGMA optimize across SQLite databases"
         YAML
       end
+
+      # SolidQueue keeps finished jobs (preserve_finished_jobs defaults to true)
+      # and only deletes them when asked. Without this the queue database grows
+      # without bound.
+      def clear_finished_jobs_task_yaml
+        <<~YAML
+          clear_solid_queue_finished_jobs:
+            command: "SolidQueue::Job.clear_finished_in_batches(sleep_between_batches: 0.3)"
+            schedule: "#{options[:clear_finished_schedule]}"
+            description: "Delete SolidQueue jobs finished longer ago than clear_finished_jobs_after"
+        YAML
+      end
     end
   end
 end

data/lib/generators/pu/lite/maintenance/templates/app/jobs/sqlite_maintenance_job.rb.tt

@@ -26,6 +26,12 @@ class SqliteMaintenanceJob < ApplicationJob
   # churning DB sits at a steady-state size without nightly reclamation.
   VACUUM_DBS = %w[primary errors rails_pulse].freeze
 
+  # VACUUM holds that exclusive lock for as long as the rewrite takes, which on
+  # a large primary is long enough for inbound requests to time out waiting.
+  # WAL reuses freelist pages anyway, so the rewrite only pays off once a real
+  # share of the file is free, usually after a bulk delete.
+  VACUUM_MIN_FREE_RATIO = 0.1
+
   def perform
     OPTIMIZE_DBS.each { |db_name| run_maintenance(db_name) }
   end
@@ -46,6 +52,7 @@ class SqliteMaintenanceJob < ApplicationJob
       conn.execute("PRAGMA optimize")
 
       next unless VACUUM_DBS.include?(db_name)
+      next unless vacuum_worthwhile?(conn, db_name)
 
       Rails.logger.info { "[SqliteMaintenance] VACUUM on #{db_name}" }
       started = Time.current
@@ -53,8 +60,18 @@ class SqliteMaintenanceJob < ApplicationJob
       Rails.logger.info { "[SqliteMaintenance] VACUUM on #{db_name} done in #{(Time.current - started).round(2)}s" }
     end
   rescue => e
-    Rails.error.report(e, context: {db: db_name, action: "sqlite_maintenance"})
+    Rails.error.report(e, context: {db: db_name, action: "sqlite_maintenance"}, source: "sqlite_maintenance")
   ensure
     MaintenanceConnection.remove_connection
   end
+
+  def vacuum_worthwhile?(conn, db_name)
+    free = conn.select_value("PRAGMA freelist_count").to_i
+    total = conn.select_value("PRAGMA page_count").to_i
+    ratio = total.zero? ? 0 : free.fdiv(total)
+    return true if ratio >= VACUUM_MIN_FREE_RATIO
+
+    Rails.logger.info { "[SqliteMaintenance] VACUUM on #{db_name} skipped, #{(ratio * 100).round(1)}% free" }
+    false
+  end
 end

data/lib/plutonium/definition/presentable.rb

@@ -36,8 +36,11 @@ module Plutonium
         # Returns the label for the interaction.
         #
         # @return [String] The label defined in the presentation metadata or a default generated from the class name.
+        #   The conventional "Interaction" suffix is dropped: ImportPostsInteraction reads "Import Posts".
+        #   Only a suffix: a class named just Interaction keeps its name rather than going blank.
         def label
-          Plutonium::Translation.resolve(presentation_metadata[:label]) || name.demodulize.titleize
+          Plutonium::Translation.resolve(presentation_metadata[:label]) ||
+            name.demodulize.sub(/(?<=.)Interaction\z/, "").titleize
         end
 
         # Returns the icon for the interaction.

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

@@ -27,10 +27,25 @@ module Plutonium
         #   This is the knob for which backend does that, for runs alone.
         attr_accessor :attachment_backend
 
+        # @return [Integer] how many pre_check rejections a run stores. The rest
+        #   are counted and reported as one "and N more" entry, so a file that is
+        #   bad on every row cannot write tens of thousands of entries into the
+        #   errors_log column (and onto the progress page). Must be a positive Integer.
+        attr_accessor :max_rejections
+
+        # @return [ActiveSupport::Duration] how long a run stays in the running
+        #   banner after it finishes, for the user who started it. A dispatch
+        #   sends that user back to the index, and a short run (or one its
+        #   pre_check rejected) settles before the page loads; without this it
+        #   would never show there at all.
+        attr_accessor :recent_runs_window
+
         def initialize
           @enabled = false
           @queue = :default
           @stall_after = 1.hour
+          @max_rejections = 100
+          @recent_runs_window = 10.minutes
         end
       end
     end

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

@@ -225,9 +225,14 @@ module Plutonium
         #
         # @return [Targets]
         def targets
+          unless run.targeted?
+            raise UnresolvableError,
+              "run #{run.id} (#{run.class}) is not a targeted run; it has no targets to resolve"
+          end
+
           unless run.target_type
             raise UnresolvableError,
-              "run #{run.id} (#{run.class}) has no target_type; it is not a targeted run"
+              "run #{run.id} (#{run.class}) has no target_type; it cannot resolve its targets"
           end
 
           key = target_class.primary_key
@@ -380,8 +385,13 @@ module Plutonium
         #
         # Only meaningful for a targeted run — untargeted work has no target
         # resource and therefore no policy to pin.
+        #
+        # Keyed on Run#targeted?, not on target_type: an opaque run dispatched
+        # from a resource still records target_type (it is what puts the run in
+        # that resource's banner), but it resolves no targets, so it pins no
+        # policy and there is nothing here to verify.
         def verify_policy!
-          return if run.target_type.nil?
+          return unless run.targeted? && run.target_type
 
           # A targeted run with no recorded policy is not "unasserted", it is
           # unverifiable: there is nothing to compare today's lookup against, and

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

@@ -190,6 +190,8 @@ module Plutonium
         # the framework is meant to call, and it must not change what the
         # executor does with it.
         def perform_opaque
+          return unless pre_check_passed?
+
           run.send(:perform)
           run.finish!
         end
@@ -200,6 +202,17 @@ module Plutonium
 
           return refuse_partial_batch(resolved) if unresolved?(resolved) && !continue?
 
+          # A resumed run whose earlier pass already applied a target was
+          # approved by that pass's check: targets are only performed after it
+          # passes. Re-checking the remainder could reject a run that is
+          # half-applied and report "nothing was processed". Opaque runs restart
+          # from scratch, so they re-check.
+          #
+          # After record_unresolved, so a rejected :continue run still reports
+          # the targets that had gone; those count toward progress_done, though
+          # nothing was performed.
+          return unless run.any_target_applied? || pre_check_passed?(resolved.records)
+
           if transactional?
             perform_all_or_nothing(resolved.records)
             run.finish!
@@ -217,6 +230,47 @@ module Plutonium
           end
         end
 
+        # Runs the run's pre_check with #reject live, and fails the run with
+        # whatever it rejected. Before any work: a rejected run touches no
+        # target. Outside the :transactional batch, which never opens for a
+        # rejected run.
+        #
+        # An exception from the check is NOT a rejection. It propagates to #call
+        # and fails the run the ordinary way, so "your input is wrong" and "the
+        # check itself broke" stay distinguishable (Run#outcome).
+        #
+        # send, for the reason #perform_opaque gives.
+        #
+        # @return [Boolean] whether the work may go ahead
+        def pre_check_passed?(*args)
+          verify_pre_check_arity!(args.size)
+
+          messages, overflow = run.collect_rejections { run.send(:pre_check, *args) }
+          return true if messages.empty? && overflow.zero?
+
+          run.reject_run!(messages, overflow: overflow)
+          false
+        end
+
+        # A targeted check declared opaque-style (or the reverse) would raise a
+        # bare "wrong number of arguments" from inside the executor, naming
+        # neither the class nor the fix.
+        #
+        # Raised as NotImplementedError ("the run class is written wrong"), which
+        # #call records like any other failure.
+        def verify_pre_check_arity!(given)
+          params = run.method(:pre_check).parameters.group_by(&:first)
+          required = params.fetch(:req, []).size
+          positional = required + params.fetch(:opt, []).size
+          fits = params[:keyreq].nil? && required <= given && (params.key?(:rest) || positional >= given)
+          return if fits
+
+          raise NotImplementedError, I18n.t(
+            "plutonium.async.executor.pre_check_arity.#{run.targeted? ? "targeted" : "opaque"}",
+            run_class: run.class
+          )
+        end
+
         # @return [Integer, nil] how many records were never attempted, if the
         #   failure policy stopped the loop early — nil if it ran to the end
         def perform_each(records)