plutonium 0.62.2 → 0.63.0

data/docs/blog/fractional-ordering-runs-out-of-room.md

@@ -0,0 +1,67 @@
+---
+title: "Plutonium drag-to-reorder: what happens when fractional ordering runs out of room"
+titleTemplate: "Plutonium Blog"
+date: 2026-09-21
+description: Halving the gap between two decimals works about twenty times. The interesting engineering is in the twenty-first.
+author: Stefan Froelich
+tags: [positioning, rails, database]
+draft: true
+---
+
+# Plutonium drag-to-reorder: what happens when fractional ordering runs out of room
+
+<BlogMeta />
+
+The appeal of fractional ordering is obvious once you have written the alternative. To drop a row between two others, you write the midpoint of their positions. One row changes. No `UPDATE … SET position = position + 1` sweeping the table, no lock contention, no re-sending a list to the client.
+
+```ruby
+Plutonium::Positioning.position_between(1.0, 3.0)   # => 2.0
+Plutonium::Positioning.position_between(nil, 5.0)   # => 4.0  (prepend)
+Plutonium::Positioning.position_between(5.0, nil)   # => 6.0  (append)
+```
+
+The part people skip is that midpoints are a finite resource, and running out is a correctness problem rather than a performance one.
+
+## Twenty drops into the same slot
+
+Every insert into the *same* gap halves it: `1.0`, then `0.5`, then `0.25`. After about twenty consecutive drops between the same two neighbours, the gap is below `1e-6`. Keep going and you are asking the database to distinguish decimals it cannot store, at which point two rows share a position and your ordering is whatever the query planner feels like today.
+
+Twenty sounds like a lot until you picture a user tidying a backlog, repeatedly dragging things to the same spot near the top.
+
+## The threshold and the column
+
+Two numbers hold this together, and they are related in a way that is easy to get wrong.
+
+`EPSILON` is `1e-6`. When a gap drops below it, `reposition!` rebalances **just that scope group**: it renumbers the group's rows to fresh integers (`1.0, 2.0, 3.0, …`) in current-position order, inside a transaction, reloads the two neighbours, and writes the new midpoint. Other scope groups are untouched, so rebalancing a "Doing" column does not disturb "Done".
+
+The column is `decimal(16, 8)`, which the `t.position` migration helper emits for you:
+
+```ruby
+create_table :tasks do |t|
+  t.position        # decimal :position, precision: 16, scale: 8
+end
+```
+
+The relationship: the column needs **at least two more decimal places than `EPSILON`**. Rebalancing triggers at `1e-6`, so a `scale: 8` column still has room to write that final midpoint cleanly before the rebalance happens. Give it `scale: 6` and the last subdivision before a rebalance can round into a neighbour and momentarily collide, which is a rare, data-dependent bug that will not reproduce on your machine.
+
+This is why the helper exists. `t.position` is not sugar for `decimal :position`; it is the framework refusing to let you pick a scale that appears to work.
+
+## The bit I did not expect to matter
+
+`reposition!` returns a `Plutonium::Positioning::Result`, and the useful thing on it is `rebalanced?`: did rows *other than this one* move?
+
+That single boolean decides the HTTP response. If nothing else moved, the client's optimistic update is already correct and the endpoint answers `204 No Content`. If a rebalance happened, every row in that group has a new number, the client's model of the world is stale, and the endpoint sends the whole collection back.
+
+Without it you have two bad options: always return the collection, and pay a full re-render on every drag; or never return it, and let the client drift out of sync on the one drag in twenty that renumbers everything. The flag turns a rare event into a cheap one instead of taxing the common case for it.
+
+## End moves never rebalance
+
+A drop at either end passes a `nil` neighbour, and `position_between` answers with `prev + 1` or `next - 1`. Integers, always room, no halving. So "drag to the top" and "drag to the bottom", which are the two most common gestures in any list, cannot trigger a rebalance at all.
+
+That is a nice property that falls out of the arithmetic rather than being designed in, and it means the pathological case requires deliberately dropping into the same interior gap twenty times.
+
+## The general lesson
+
+Fractional ordering is usually presented as a trick: store decimals, write midpoints, done. It is a good trick. But it comes with a resource that depletes, and a system that uses it without a rebalance path is not simpler, it is unfinished. It just fails later, on a table someone has been reordering for two years, in a way that looks like the database losing your data.
+
+The work is not the midpoint. It is knowing when you have run out of them, having somewhere to put the rows when you do, and telling the client which of those two things just happened.

data/docs/blog/half-finished-forms-are-pii.md

@@ -0,0 +1,76 @@
+---
+title: "Plutonium wizards: a half-finished form is PII sitting in your database"
+titleTemplate: "Plutonium Blog"
+date: 2026-09-24
+description: Multi-step flows have to put the partial answers somewhere. Once that somewhere is a table instead of a cookie, it is data you are responsible for.
+author: Stefan Froelich
+tags: [wizards, security, rails]
+draft: true
+---
+
+# Plutonium wizards: a half-finished form is PII sitting in your database
+
+<BlogMeta />
+
+A single-page form has a comfortable property nobody thinks about: until the user hits submit, the data is in their browser. If they wander off, it evaporates. You never held it, so you never had to protect it, retain it, or explain it in a privacy policy.
+
+Split that form across five screens and the property is gone. The answers from step two have to live somewhere while the user is on step three, and now you are storing them.
+
+Plutonium wizards store staged step values in a `data` column on a single framework table. Which raises a question the framework should not answer silently: what is in that column?
+
+## What is actually in there
+
+Whatever the flow collects, from every step the user has completed so far. For an onboarding wizard that is a company name. For a checkout, an address. For an insurance quote, a date of birth and a medical history, sitting in a row belonging to someone who abandoned the flow at step four and is never coming back.
+
+The rows are not long-lived by design; there is a sweep for abandoned sessions. But "not long-lived" is measured in your configured TTL, which is days, not the milliseconds a browser-held form would have been.
+
+## The opt-in
+
+```ruby
+class CheckoutWizard < Plutonium::Wizard::Base
+  encrypt_data
+  # ...
+end
+```
+
+That encrypts the `data` column. Deliberately *not* encrypted: `tracked_records` (record GlobalIDs only), and the `owner`, `anchor`, `scope` and `token` columns, which have to stay queryable for the wizard to find and resume a session at all.
+
+Once your app has ActiveRecord encryption keys, you can flip it on globally and opt out per wizard:
+
+```ruby
+config.wizards.encrypt_data = true
+
+class PublicSurveyWizard < Plutonium::Wizard::Base
+  encrypt_data false   # explicit opt-out even when the global default is on
+end
+```
+
+An explicit declaration on the wizard always wins. A wizard that declares neither inherits the global flag.
+
+## Why it is off by default
+
+Because it needs ActiveRecord encryption keys configured, and a framework that turns itself on and then raises on a missing key during someone's first `rails g` is a framework people uninstall. Off-by-default here is not an opinion that encryption is optional. It is an acknowledgement that the prerequisite is not in the framework's gift.
+
+That is worth being honest about rather than dressing up, because "secure by default" is the answer everyone wants to give and it would have been the wrong one.
+
+## The implementation detail that turned out to matter
+
+`data` is one shared `jsonb` column across every wizard, some encrypted and some not. A model-level `encrypts :data` does not fit: it would encrypt every row regardless of the wizard's preference, and it fights the `jsonb` type.
+
+So the store encrypts at write time with ActiveRecord's configured encryptor, the same keys `encrypts` would use, and writes a self-describing envelope:
+
+```json
+{ "_enc": "<ciphertext>" }
+```
+
+A row therefore decrypts based on **its own shape**, not on what the wizard's `encrypt_data?` currently says.
+
+That is the part worth stealing if you are building something similar. It means toggling the flag never strands existing rows. Turn encryption on and the sessions already in flight keep working, plaintext, until they finish or get swept. Turn it off and the encrypted ones still decrypt. There is no migration, no backfill, and no window where a config change breaks resumption for everyone mid-flow.
+
+The alternative, deciding how to read a row based on current configuration, works perfectly until the first time someone changes the configuration, which is precisely when you least want a surprise.
+
+## The question the feature is really asking
+
+Not "should I turn on encryption." It is "did I notice that this form now persists?"
+
+Most multi-step flows get built by someone porting a long single-page form, and the persistence arrives as an implementation detail of the step mechanism rather than a decision anybody made. The flag exists mostly to prompt the thought. If your wizard collects nothing sensitive, ignore it. If it collects a date of birth, you are storing dates of birth, and that was true before anyone thought to ask.

data/docs/blog/index.md

@@ -0,0 +1,13 @@
+---
+layout: page
+sidebar: false
+aside: false
+title: Blog
+description: Release notes, design notes, and what's new in Plutonium.
+---
+
+<BlogIndex
+  eyebrow="Blog"
+  title="What we're building, and why."
+  lede="Release notes, design notes, and the reasoning behind the parts of Plutonium that aren't obvious from the reference."
+/>

data/docs/blog/interactions-are-presentation-objects.md

@@ -0,0 +1,152 @@
+---
+title: "Plutonium interactions are presentation objects, not service objects"
+titleTemplate: "Plutonium Blog"
+date: 2026-08-31
+description: One required keyword argument in the constructor decides where your business logic is allowed to live, and it is not in the interaction.
+author: Stefan Froelich
+tags: [architecture, interactions, rails]
+draft: true
+---
+
+# Plutonium interactions are presentation objects, not service objects
+
+<BlogMeta />
+
+Every Rails codebase eventually grows a folder for "the logic that isn't a model and isn't a controller." It gets called `app/services`, or `app/operations`, or `app/commands`. Plutonium has a folder that looks like that. It is called `app/interactions`, and putting your business logic in it is usually a mistake.
+
+Here is why, in one line of the base class:
+
+```ruby
+def initialize(view_context:, **attributes)
+```
+
+`view_context:` is required. Not optional, not defaulted. An interaction cannot be constructed without one.
+
+That single constraint decides the whole architecture, so it is worth being precise about what it means.
+
+## What the constraint rules out
+
+A `view_context` comes from a Rails view render. A background job does not have one. Neither does an API controller responding with JSON, a rake task, a seeds script, or the console.
+
+So the moment a second caller needs the operation, you have exactly two options, and both are bad:
+
+1. **Duplicate the logic** in the job, and now two implementations of "publish a post" drift apart.
+2. **Manufacture a `view_context`** so the job can build the interaction, which means a background job now owns a rendering context it has no business owning, purely to satisfy a constructor.
+
+`view_context` is the tell. If an object requires a view to exist, that object is part of the presentation layer, whatever folder you filed it in.
+
+## What an interaction is actually for
+
+An interaction is the entry point from a Plutonium page into an operation. Its job is:
+
+- declaring the inputs, which become a form
+- rendering as a button in the right place, decided by whether it declares `:resource`, `:resources`, or neither
+- validating the shape of what the user typed
+- being gated by a policy method
+- returning an outcome the controller turns into a flash message and a redirect
+
+That is a complete and useful job. It is also entirely presentational. None of it is "what publishing a post means."
+
+## So where does the logic go
+
+On the model, per ordinary Rails convention. Named in domain language, not persistence language: `publish!`, `archive!`, `register!`, never `update_published_at`.
+
+```ruby
+# app/models/post.rb
+class Post < ApplicationRecord
+  def publish!(on: Time.current)
+    update!(published: true, published_at: on)
+  end
+end
+```
+
+```ruby
+# app/interactions/publish_post_interaction.rb
+class PublishPostInteraction < ResourceInteraction
+  presents label: "Publish", icon: Phlex::TablerIcons::Send
+
+  attribute :resource
+  attribute :publish_date, :datetime, default: -> { Time.current }
+
+  input :publish_date
+  validates :publish_date, presence: true
+
+  private
+
+  def execute
+    resource.publish!(on: publish_date)
+    succeed(resource).with_message("Post published!")
+  rescue ActiveRecord::RecordInvalid => e
+    failed(e.record.errors)
+  end
+end
+```
+
+The interaction is three lines of doing and a lot of declaring. That ratio is the point.
+
+## The rule, stated properly
+
+**Logic may start in `execute`.** A one-off with a single caller is fine inline. Do not pre-extract, and do not invent a service layer for it. Plutonium deliberately ships nowhere to put one, and YAGNI applies here as much as anywhere.
+
+**The trigger to extract is the second caller.** A background job, an API controller, a rake task, the console, another interaction. Not a line count, not a sense that the method is getting long.
+
+**The destination is the model.** Fat models, the way Rails always meant it.
+
+## The chain that gives it away
+
+Here is the shape that tells you the logic ended up in the wrong layer:
+
+```ruby
+# Three interactions, three view_contexts.
+CreateUserInteraction.call(view_context:, **user_params)
+  .and_then { |user| SendWelcomeEmail.call(view_context:, user:) }
+  .and_then { |user| LogActivity.call(view_context:, user:) }
+```
+
+Now write the signup API endpoint. Or the seeds script. Or the admin rake task that backfills accounts. None of them can supply a `view_context`, so none of them can send the welcome email or write the audit row. The email and the audit trail are stranded inside the presentation layer, reachable only by someone clicking a button.
+
+The same thing, put where it belongs:
+
+```ruby
+def execute
+  user = User.register!(**attributes)   # welcome email + audit row live in here
+  succeed(user).with_message("Welcome aboard!")
+end
+```
+
+Chaining three interactions is usually one model method wearing three presentation costumes.
+
+## What genuinely does belong inline
+
+Not everything in `execute` is misplaced. This is correct:
+
+```ruby
+def execute
+  resource.update!(updated_by: current_user)
+  succeed(resource)
+end
+
+private
+
+def current_user = view_context.controller.helpers.current_user
+```
+
+"Who clicked the button" is context that only the presentation layer holds. A job has no answer for it. There is no second caller to extract for, because the fact being recorded is itself presentational.
+
+## Validations split the same way
+
+The split shows up again in validations, and it is worth getting right because the two kinds surface differently.
+
+An **interaction validation** asks "can I read this input?" Is it present, does it parse, is the format plausible. It attaches to a declared attribute, so the re-rendered form shows the error inline against that field.
+
+A **model validation** asks "is this record legal?" It holds no matter who is calling, including the job that has no form to render errors into. `failed(record.errors)` flattens `ActiveModel::Errors` into full messages on `:base`, so those land in the error summary rather than against a field.
+
+Which means it is often right to duplicate a cheap invariant: the model keeps the authoritative copy, and the interaction keeps a copy purely so the message lands on the right input. What must never happen is the reverse, where only the interaction enforces it, because the day a job calls the model directly, the rule is not in the picture at all.
+
+## Why a required keyword argument is a good design
+
+It would have been easy to make `view_context:` optional. Default it to `nil`, let the interaction work headlessly, and interactions become service objects that happen to render forms.
+
+Leaving it required is a constraint that answers an architectural question every Rails team argues about, permanently, at the point where the question is cheapest to answer: when you try to call the thing from a job and it will not build.
+
+You can still write a service layer if you want one. Plutonium is plain Rails underneath and nothing stops you. But you will not drift into one by accident, which is how most of them get started.

data/docs/blog/introducing-plutonium.md

@@ -0,0 +1,253 @@
+---
+title: "Introducing Plutonium: Rails conventions, past CRUD"
+titleTemplate: "Plutonium Blog"
+date: 2026-08-24
+description: Rails made a bargain. Follow the conventions and the framework carries you. Plutonium makes the same bargain about the layer Rails deliberately left alone.
+author: Stefan Froelich
+tags: [announcement, rails, architecture]
+draft: true
+---
+
+# Introducing Plutonium: Rails conventions, past CRUD
+
+<BlogMeta />
+
+Rails made a bargain with you, and the bargain is the whole reason it works.
+
+Name the column `user_id` and the association resolves itself. Name the file `posts_controller.rb` and the routing finds it. Put the partial where Rails expects it and it renders. You give up the freedom to arrange things however you like, and in exchange the framework stops asking you questions. Follow the conventions and the code nearly writes itself. Fight them and every line becomes a negotiation.
+
+The second half of the bargain matters just as much. Rails never locks the door. Every convention has a configuration point behind it: `foreign_key:`, `class_name:`, `to_prepare`, a custom inflection, a controller that renders whatever you want. You get to ninety percent without making a decision, and the rest stays possible.
+
+That bargain stops at the framework layer, on purpose. Rails gives you models, controllers, views, routing, migrations. It does not give you an opinion about authentication flows, authorization rules, admin interfaces, multi-tenancy, or the difference between "a record" and "a thing a user is allowed to act on." Those are application concerns. Rails leaves them to you, which is the right call for a general-purpose framework and also the reason you have written them four times.
+
+Plutonium makes the same bargain about that layer: follow the convention and it carries you, reach for an escape hatch when you need one.
+
+## Design the model correctly and multi-tenancy stops being work
+
+Multi-tenancy is the clearest example, because it's the feature most often implemented as a discipline problem. The usual approach: add a tenant filter to every query, scope every controller action, then review every pull request for the one place someone forgot. The failure mode is a data leak.
+
+In Plutonium you don't write filters. You declare where the tenant lives, once, on the portal:
+
+```ruby
+# packages/admin_portal/lib/engine.rb
+module AdminPortal
+  class Engine < ::Rails::Engine
+    include Plutonium::Portal::Engine
+
+    scope_to_entity Organization, strategy: :path
+  end
+end
+```
+
+Then you design your models the way you would have anyway:
+
+```ruby
+class Post < ApplicationRecord
+  belongs_to :organization              # a direct child of the tenant
+end
+
+class Comment < ApplicationRecord
+  belongs_to :post
+  has_one :organization, through: :post # reachable through an association
+end
+```
+
+That's the entire setup. Every query in that portal is scoped, every create is associated, every nested route is constrained, because Plutonium can read the path from a record to its tenant out of your associations. Resolution happens in a defined order: a direct `belongs_to` first, then `has_one` or `has_one :through`, then a reverse `has_many` from the entity if it has to.
+
+What matters more is the case where your schema is complicated, because real ones are. When no association expresses the relationship, you don't abandon the convention and start hand-scoping controllers. You write the resolution yourself, on the model:
+
+```ruby
+class Invoice < ApplicationRecord
+  scope :associated_with_organization, ->(org) {
+    joins(:contract).where(contracts: {organization_id: org.id})
+  }
+end
+```
+
+Now `Invoice` scopes exactly the way `Post` does. The index, the show page, nested routes, the authorization scope: all of it behaves identically. You replaced one lookup, not the mechanism.
+
+The convention covers the common shapes, and the exception gets a named place to live. It lives on the *model* rather than in a policy or a controller, so it applies everywhere the record is read.
+
+## Nothing gets declared twice
+
+A definition can be empty:
+
+```ruby
+class PostDefinition < ResourceDefinition
+end
+```
+
+That already renders an index table, a form and a show page. Plutonium reads the model for the rest: column types become field types, `belongs_to` and `has_many` become pickers and nested tables, an attached file becomes an upload. Validations carry through too, so `validates :title, presence: true` marks the field required and `validates :status, inclusion: {in: %w[draft published archived]}` supplies the select's choices.
+
+That move is not a definition feature. It's how the whole framework is built:
+
+- The tenant scope is read off your associations, which is why the multi-tenancy above needed no filters.
+- A collection's preloads are read off the policy's permitted fields, so there is no `includes` list to maintain.
+- An association picker's typeahead is read off the target resource's own `search` block.
+- Whether an interaction is a record, bulk or resource action is read off whether it declares `:resource`, `:resources`, or neither.
+- CRUD routes, nested routes and action routes are read off the resource registration.
+
+None of these is a default someone picked for you. Each is computed from a declaration you already made for another reason, which is the part that matters: there is one place to change it, and nothing downstream to keep in step. Add a column, and the form, the table, the export and the preloads all move together.
+
+So you declare only what differs. A `field :title` matching what was detected is dead code.
+
+That leaves the differences, and two portals rarely want the same ones.
+
+## Overrides follow the inheritance you already understand
+
+Rails view lookup walks an inheritance chain. A template in your controller's own directory wins, otherwise it falls back to the parent's.
+
+Plutonium customization works the same way, because it is the same thing: plain Ruby inheritance, across three levels.
+
+Your resource has an app-wide definition:
+
+```ruby
+# app/definitions/post_definition.rb
+class PostDefinition < ResourceDefinition
+  input :content, as: :markdown
+
+  display :status, as: :badge, colors: {published: :accent, draft: :neutral}
+end
+```
+
+A portal that needs something different inherits from it:
+
+```ruby
+# packages/admin_portal/app/definitions/admin_portal/post_definition.rb
+class AdminPortal::PostDefinition < ::PostDefinition
+  scope :pending_review
+  input :internal_notes, hint: "Not shown to the author"
+end
+```
+
+The policy for that portal inherits the same way, and decides a different question:
+
+```ruby
+# packages/admin_portal/app/policies/admin_portal/post_policy.rb
+class AdminPortal::PostPolicy < ::PostPolicy
+  include AdminPortal::ResourcePolicy
+
+  def permitted_attributes_for_create = %i[title content internal_notes]
+end
+```
+
+That split is worth being precise about. The definition says *how* a field renders. The policy says *whether it appears at all*. `internal_notes` shows up in the admin portal because the admin policy permits it, not because the admin definition mentions it, and a customer-facing portal that inherits from the same two base classes makes both decisions independently.
+
+Neither portal knows about the other. There's no registry of overrides, no configuration DSL for precedence, no merge semantics to learn. It's a superclass and a subclass, so the answer to "why is this field showing up here but not there" is readable as a class hierarchy.
+
+## Escape hatches, sized to the problem
+
+Plutonium's exits are graduated. You climb only as far as the problem requires.
+
+**Change an option.** Most customization is a keyword:
+
+```ruby
+input :content, as: :markdown
+display :status, as: :badge, colors: {published: :accent, draft: :neutral}
+```
+
+**Render it inline.** A display takes a block, or a proc that runs inside a Phlex context, so tag methods and Tailwind classes are available without defining a class:
+
+```ruby
+display :priority, as: :phlexi_render, with: ->(value, attrs) do
+  span(class: "pu-badge") { value.humanize }
+end
+```
+
+**Write a component.** It's Phlex. A field component reads everything off `field` and plugs straight into `as:`:
+
+```ruby
+class ChartComponent < Phlexi::Display::Components::Base
+  def view_template
+    div(**attributes, data: {controller: "chart", chart_value: field.value.to_json})
+  end
+end
+
+# in the definition
+display :revenue, as: ChartComponent
+```
+
+A component with its own constructor renders from a block instead:
+
+```ruby
+display :card do |field|
+  PostCardComponent.new(post: field.object)
+end
+```
+
+**Implement a hook.** Once the change is about a page or a request rather than a field, there is usually a named seam waiting. Controllers expose hooks rather than asking you to reopen the CRUD actions:
+
+```ruby
+class PostsController < ::ResourceController
+  private
+
+  def redirect_url_after_submit = posts_path
+
+  def resource_params
+    params = super
+    params[:tags] = params[:tags].split(",") if params[:tags].is_a?(String)
+    params
+  end
+end
+```
+
+Pages expose a matching set for markup: `render_before_content` and `render_after_content`, plus the same pairs around the header, breadcrumbs, toolbar and footer.
+
+```ruby
+class PostDefinition < ResourceDefinition
+  class ShowPage < ShowPage
+    private
+
+    def page_title = "Post: #{object.title}"
+
+    def render_after_content
+      render RelatedPostsComponent.new(post: object)
+    end
+  end
+end
+```
+
+Both families exist for the reason Rails gives you `before_action` instead of asking you to rewrite dispatch. Overriding a whole method means inheriting responsibility for everything else it did: a page's `view_template` also renders breadcrumbs, the header, and the frame wiring that makes turbo navigation work. Implement `render_after_content` and all of that keeps working.
+
+**Replace the page.** When no hook sits where you need it, override `view_template` on the nested class and take over the whole body. When Phlex is the wrong tool entirely, a designer's HTML or an existing layout you're keeping, drop an ERB view at the controller path instead. ERB wins over the page class when both exist for the same action:
+
+```erb
+<%-# app/views/posts/show.html.erb %>
+<div class="announcement-banner">Special announcement</div>
+<%= render current_definition.show_page_class.new %>
+<%= render partial: "related" %>
+```
+
+That middle line is the generated page. Keep it and wrap it, or delete it and write the whole thing yourself.
+
+Underneath all five rungs it stays Rails. Your models are plain ActiveRecord. Your controllers inherit from Rails controllers. Your views resolve through Rails view paths. Hotwire works as it does in any Rails app. A Plutonium resource and a hand-written controller can sit in the same app.
+
+## What comes in the box
+
+- **Resources.** One line of registration generates CRUD routes, nested routes and action routes.
+- **Authentication.** Rodauth integration, or bring your own.
+- **Authorization.** ActionPolicy-backed, with per-field read and write permissions.
+- **Multi-tenancy.** Entity scoping declared per portal, resolved through your associations.
+- **Queries.** Search, filters, scopes and sorting declared on the definition.
+- **Exports.** Streamed CSV on every resource, opt-in through the policy, with columns drawn from the same permitted-attributes list.
+- **Eager loading.** Index pages, kanban boards and exports preload the associations and attachments they are about to render. The field set comes from the policy, so there is no `includes` list to declare or keep in step.
+- **Positioning.** `positioned_on` on the model and `position_on` in the definition put drag handles on index tables, card grids and nested association tables. A drop writes one decimal, so there is no renumbering sweep.
+- **Generators.** Scaffolding for resources, packages, portals, auth and tests, so the conventional files start out conventional.
+- **Testing.** Concerns for CRUD, policy, definition, interaction and portal-access tests.
+- **Forms.** Nested attributes, markdown editors, date pickers and drag-and-drop uploads.
+- **Association inputs.** Server-side typeahead by default, searching through the target resource's own `search` block, with the options filtered by its policy and the values protected by signed global IDs.
+- **Interactions.** A business operation gets a button, a form, a policy gate and a typed outcome instead of a bespoke controller action.
+
+Newer, and still experimental:
+
+- **Kanban boards.** Drag between columns, WIP limits, opt-in realtime.
+- **Wizards.** Multi-step flows with branching and a built-in review step.
+- **Async interactions.** Persisted, resumable runs for work that outlives a request.
+
+## Where it actually is
+
+Plutonium is pre-1.0 and MIT licensed. The core (resources, definitions, policies, portals, packages, entity scoping) is stable and running in production. The newer surfaces are marked experimental in the docs, individually, because their DSLs are young enough that I'd rather rename a method in response to real use than freeze a first guess into a compatibility promise. Pin your version if that makes you nervous.
+
+None of this does something Rails can't. You can build all of it by hand, and you probably have. The argument is that you shouldn't have to build it a fifth time.
+
+Start with the [tutorial](/getting-started/tutorial/), or read [Core Concepts](/getting-started/) to see whether the shape fits how you already think. If it fights you somewhere, I'd like to hear where. That feedback still changes things.

data/docs/blog/jobs-are-not-permission-snapshots.md

@@ -0,0 +1,100 @@
+---
+title: "Plutonium async runs: a queued job is not a permission snapshot"
+titleTemplate: "Plutonium Blog"
+date: 2026-09-03
+description: The usual bulk-job pattern decides who is allowed at enqueue time and then trusts that decision minutes later. Plutonium re-derives it, per target, right before doing the work.
+author: Stefan Froelich
+tags: [async, authorization, rails]
+draft: true
+---
+
+# Plutonium async runs: a queued job is not a permission snapshot
+
+<BlogMeta />
+
+Here is the bulk operation everyone writes at least once:
+
+```ruby
+def archive_all
+  ids = params[:ids]
+  authorize_all!(ids)
+  ArchivePostsJob.perform_later(current_user.id, ids)
+  redirect_to posts_path, notice: "Archiving in the background"
+end
+```
+
+It is a reasonable piece of code and it contains a bug that is easy to miss, because the bug is not in any line. It is in the gap between two of them.
+
+Authority is decided in the controller, at enqueue time. The work happens somewhere else, minutes or hours later. In between, the queue is holding a list of record IDs and a user ID, and nothing in that payload is a permission. It is a claim that a permission existed once.
+
+## What can change in the gap
+
+Quite a lot, and none of it is exotic:
+
+- The initiator loses access. They are removed from the team, their role is downgraded, their account is suspended. The job proceeds anyway, applying an authority that was revoked before it ran.
+- A record moves to another tenant, or gets reparented, or is deleted. The job loads it by ID and acts on it, because an ID does not carry a tenant.
+- Someone renames or re-namespaces the model class between deploy and drain. The job deserializes into a class whose policy the initiator was never subject to.
+- The initiator, the tenant, or the parent record is deleted outright. Now the job is holding a foreign key to nothing.
+
+Each of these is individually unlikely on any given day. Collectively, across a queue that runs every day for years, they are certainties. And every one of them fails in the same direction: the job does the work.
+
+## What Plutonium persists instead
+
+An `async` interaction does not serialize a decision. It persists a run, and the run records the *inputs to* a decision: who initiated it, which tenant they were in, which parent record scoped the dispatch if it was nested, and the validated attributes.
+
+When the job picks it up, `Async::Context` rebuilds the authorization triple from that row and re-asks every question from scratch. It trusts nothing the dispatching request already concluded.
+
+There are four separate checks, and the interesting part is that they are separate.
+
+**The scope check** re-runs the same `associated_with` filtering the index would use. A target that left the tenant, left the parent, or was deleted between dispatch and perform is reported as `missing` or `unauthorized`. It is not silently skipped, which matters: a run that quietly processes 47 of 50 records and reports success is worse than one that tells you which three it refused.
+
+**The predicate check** re-asks the policy the same question dispatch asked, per target, immediately before each `perform_on`. Not once up front for the batch. That distinction is the whole feature: an initiator whose permission is revoked halfway through a run stops applying to the remaining targets, mid-run.
+
+**The policy mismatch check** refuses to run at all if the class has been renamed, reparented, or re-namespaced since dispatch. The alternative is authorizing under a policy the initiator was never subject to, which is the kind of thing that is invisible until it is an incident.
+
+**The deleted subject check** refuses the run if the initiator, tenant, or parent is gone. This one has a subtlety worth spelling out, because it is where a naive implementation quietly breaks. When the association nils out, `nil` reads as "there was never one here": no tenant, or not a nested dispatch. Both of those interpretations *drop a filter* rather than narrowing one. So a deleted tenant would widen the run's reach rather than stopping it. The `*_type` column is what distinguishes "this run carries no tenant" from "this run carries a tenant that is gone."
+
+## Failing closed
+
+The rule underneath all four is that resolution failure always fails **closed**. Refuse, or report missing. Never "assume permitted."
+
+That sounds obvious written down. It is not what most hand-rolled jobs do, because most hand-rolled jobs do not re-resolve anything at all, and code that never asks a question cannot fail its answer closed. The default behaviour of `find(id)` plus a serialized `user_id` is to fail open, silently, in exactly the cases you would most want to know about.
+
+## What you write
+
+None of the above appears in your code. The interaction declares the work:
+
+```ruby
+class Blogging::ArchivePosts < ResourceInteraction
+  presents label: "Archive", icon: Phlex::TablerIcons::Archive
+
+  attribute :resources          # bulk, so perform_on runs once per record
+  attribute :reason, :string
+
+  async do
+    on_failure :continue        # :halt (default) | :continue | :transactional
+
+    def perform_on(post)
+      post.archive!(reason: options["reason"])
+    end
+  end
+end
+```
+
+`async` replaces `execute`. Everything in front of it is unchanged: same form, same validations, same policy gate. Only what happens on submit changes. Instead of doing the work in the request, it persists a run, enqueues it, and redirects to a progress page you did not write.
+
+The block is a class body rather than a closure, and that is deliberate for the same reason the row stores an initiator instead of a serialized user object. The work happens in a process with no controller, no request, and no `view_context` to capture. `def` opens a fresh scope, so those method bodies cannot accidentally close over the interaction's locals, which is the one thing that would make writing them there misleading.
+
+## The part that is genuinely hard
+
+Re-deriving permissions is the easy half. The hard half is that a worker crash mid-batch leaves a run marked `running` forever, and nothing revisits it on its own.
+
+Plutonium ships `Async::ReapJob` for that: it finds runs with no recorded activity past `config.async_interactions.stall_after`, resets them to `pending`, and re-enqueues. The install generator schedules it automatically when Solid Queue is in the bundle. On any other scheduler **you have to schedule it yourself**, and if you do not, a crash mid-batch is a row that says `running` until someone goes looking.
+
+That is worth stating plainly rather than burying, because it is the failure mode the feature cannot solve for you.
+
+## Why bother
+
+Because the alternative is a permission model where the answer to "can this user do this?" is computed once, in a controller, and then trusted by a different process at an unbounded later time. That is a snapshot, and a snapshot of an authorization decision is not an authorization decision. It is a cached one, with no invalidation.
+
+Async interactions are marked experimental, so the DSL may still move. The property described here is not the part I expect to change.