plutonium 0.67.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/dashboard/base.rb

@@ -32,7 +32,7 @@ module Plutonium
       delegate :current_user, :current_scoped_entity, :scoped_to_entity?,
         :params, :request, :controller, :current_engine,
         :resource_url_for, :authorized_resource_scope, :allowed_to?, :policy_for,
-        :registered_resources, :root_path,
+        :registered_resources, :root_path, :current_package,
         to: :view_context
 
       class << self
@@ -92,6 +92,75 @@ module Plutonium
         card
       end
 
+      # A filter's chosen value for this request, or its default.
+      # @raise [ArgumentError] when the dashboard declares no such filter
+      def filter_value(key)
+        filter_values.fetch(key.to_sym) { raise ArgumentError, "#{self.class.name} declares no filter #{key.inspect}" }
+      end
+
+      # Every filter's chosen value, keyed by filter: what the page carries
+      # onto each card's frame URL. Read once per request.
+      def filter_values
+        @filter_values ||= self.class.filters.to_h { |filter| [filter.key, filter.value_from(self)] }.freeze
+      end
+
+      # A filter's value => label pairs for this request, built once.
+      def filter_choices(filter)
+        (@filter_choices ||= {})[filter.key] ||= filter.choices_for(self)
+      end
+
+      # The resource's authorized scope with the scope chosen by its
+      # `filter ..., scopes:` applied by the index's own query object, so a
+      # card's number matches the index list {#filtered_url} opens. Without
+      # such a filter, or with "All" chosen, the authorized scope as is.
+      #
+      # The scope block runs against this dashboard's controller, so it has
+      # `current_user` and the portal's helpers, but not a resource
+      # controller's (`current_parent`, `current_definition`, ...).
+      def filtered(resource_class)
+        relation = authorized_resource_scope(resource_class)
+        name = chosen_scope(resource_class)
+        return relation unless name
+
+        scope_query_for(resource_class).scope_definitions.fetch(name).apply(relation, context: controller)
+      end
+
+      # The resource's index, on the scope chosen by its `filter ..., scopes:`.
+      # "All" is sent explicitly when the definition has a `default_scope`, or
+      # the index would apply that instead.
+      def filtered_url(resource_class)
+        name = chosen_scope(resource_class)
+        scope = name || ("" if resource_definition_for(resource_class).default_scope)
+        options = scope.nil? ? {} : {q: {scope:}}
+        resource_url_for(resource_class, parent: nil, **options)
+      end
+
+      # The resource's definition in this dashboard's portal, falling back to
+      # the base one, as a resource controller resolves it.
+      def resource_definition_for(resource_class)
+        (@resource_definitions ||= {})[resource_class] ||= begin
+          portal_definition = current_package && "#{current_package}::#{resource_class}Definition".safe_constantize
+          (portal_definition || "#{resource_class}Definition".constantize).new
+        end
+      end
+
+      # The index's query object for the resource, holding its definition's
+      # scopes: how each applies, whether it shows, and its label. It reads
+      # no params and builds no URLs here.
+      def scope_query_for(resource_class)
+        (@scope_queries ||= {})[resource_class] ||=
+          Plutonium::Resource::QueryObject.new(resource_class, {}, nil) do |query|
+            resource_definition_for(resource_class).defined_scopes.each do |name, scope|
+              query.define_scope name, scope[:block], **scope[:options]
+            end
+          end
+      end
+
+      # The toolbar links whose `condition:` passes for this request.
+      def visible_links
+        self.class.links.select { |link| link.visible?(self) }
+      end
+
       # The refresh interval for a card: its own, else the dashboard default.
       # A card declared `refresh: false` never refreshes.
       def refresh_for(card)
@@ -106,6 +175,16 @@ module Plutonium
 
       private
 
+      # The scope name a `filter ..., scopes: resource_class` has chosen, or
+      # nil for "All" or when the dashboard has no such filter.
+      def chosen_scope(resource_class)
+        filter = self.class.filters.find { |candidate| candidate.resource_class == resource_class }
+        return unless filter
+
+        value = filter_value(filter.key)
+        value unless value == Filter::ALL
+      end
+
       def t(key, **options)
         Plutonium::Translation.t(key, **options)
       end

data/lib/plutonium/dashboard/card.rb

@@ -9,6 +9,8 @@ module Plutonium
     # Built by {DSL} at class-load and frozen; everything request-dependent
     # (label translation, `condition:`, `href:`) is resolved per render.
     class Card
+      include Evaluation
+
       KINDS = %i[metric chart custom].freeze
 
       # The dashboard grid is 12 columns wide, so halves, thirds and quarters
@@ -21,11 +23,14 @@ module Plutonium
 
       METRIC_FORMATS = %i[number currency percentage human].freeze
       METRIC_POSITIVE = %i[up down].freeze
+      # How a metric's change reads: a percent of the previous value, or the
+      # difference in points (for a value that is itself a percentage).
+      METRIC_CHANGE_UNITS = %i[percent points].freeze
       CHART_TYPES = %i[line area column bar pie donut scatter].freeze
 
       # Options every kind accepts.
       COMMON_OPTIONS = %i[label description icon span lazy refresh condition href].freeze
-      METRIC_OPTIONS = %i[format precision unit prefix suffix positive change_label].freeze
+      METRIC_OPTIONS = %i[format precision unit prefix suffix positive change_label change_unit].freeze
       CHART_OPTIONS = %i[type height].freeze
 
       attr_reader :key, :kind, :icon, :span, :refresh, :condition, :href, :block, :options, :dashboard_class
@@ -87,14 +92,7 @@ module Plutonium
       # the page AND the card endpoint, so a hidden card cannot be fetched
       # directly.
       def visible?(dashboard)
-        return true if condition.nil?
-
-        result = case condition
-        when Symbol then dashboard.send(condition)
-        when Proc then evaluate_on(dashboard, condition)
-        else condition
-        end
-        result ? true : false
+        condition_passes?(dashboard, condition)
       end
 
       # The card's link target for this request, if any.
@@ -135,10 +133,6 @@ module Plutonium
 
       private
 
-      def evaluate_on(dashboard, callable)
-        callable.arity.zero? ? dashboard.instance_exec(&callable) : dashboard.instance_exec(dashboard, &callable)
-      end
-
       def validate_span!(span)
         return GRID_COLUMNS if span == :full
         return span if span.is_a?(Integer) && span.between?(1, GRID_COLUMNS)
@@ -178,6 +172,11 @@ module Plutonium
           raise ArgumentError, "metric #{key.inspect}: positive must be :up or :down, got #{positive.inspect}"
         end
 
+        change_unit = specific.fetch(:change_unit, :percent)
+        unless METRIC_CHANGE_UNITS.include?(change_unit)
+          raise ArgumentError, "metric #{key.inspect}: change_unit must be one of #{METRIC_CHANGE_UNITS.inspect}, got #{change_unit.inspect}"
+        end
+
         specific.merge(positive:)
       end