plutonium 0.60.5 → 0.61.0

data/lib/plutonium/wizard/session.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Wizard
+    # ActiveRecord model backing the +plutonium_wizard_sessions+ table.
+    #
+    # Identity is the derived {InstanceKey} digest stored in +instance_key+; the
+    # polymorphic owner/anchor/scope refs exist for listing and rebuilding context,
+    # not for identity. At-rest encryption (the wizard's +encrypt_data+ opt-in) is
+    # applied by {Store::ActiveRecord} as a self-describing envelope in the +data+
+    # column, not statically here — so this model stays a plain schema mapping.
+    class Session < ActiveRecord::Base
+      self.table_name = "plutonium_wizard_sessions"
+
+      belongs_to :owner, polymorphic: true, optional: true
+      belongs_to :anchor, polymorphic: true, optional: true
+      belongs_to :scope, polymorphic: true, optional: true
+
+      enum :status,
+        {in_progress: "in_progress", completing: "completing", completed: "completed"},
+        prefix: true
+
+      # How long a row may sit in +completing+ before the sweep treats it as a
+      # CRASHED finalize and reaps it. A healthy finalize flips to +completing+,
+      # runs +execute+, and completes/clears the row within seconds — but +execute+
+      # runs OUTSIDE the completion lock and does not bump +expires_at+, so a sweep
+      # firing mid-finalize must NOT cancel it (that would destroy the run's
+      # tracked records out from under the in-flight +execute+, §6.2). The grace
+      # window distinguishes a finalize that is still running (recent +updated_at+)
+      # from one that crashed (stale +updated_at+). Generous on purpose.
+      COMPLETING_GRACE = 15.minutes
+
+      # Idle rows eligible for the abandonment sweep, by status:
+      #
+      # - +in_progress+ — abandoned: a concrete +expires_at+ (cleanup_after) that
+      #   has passed. Rows with a null +expires_at+ (cleanup_after :never) are never
+      #   swept.
+      # - +completing+ — a finalize that CRASHED mid-flight: it has been
+      #   +completing+ longer than {COMPLETING_GRACE} (its +updated_at+, stamped
+      #   when it entered +completing+, is older than now - grace). This keeps the
+      #   sweep from racing an +execute+ that is still running (§6.2).
+      #
+      # +completed+ rows are never swept.
+      scope :sweepable, ->(now, completing_grace: COMPLETING_GRACE) {
+        in_progress =
+          status_in_progress.where.not(expires_at: nil).where(expires_at: ..now)
+        crashed_completing =
+          status_completing.where(updated_at: ..(now - completing_grace))
+        in_progress.or(crashed_completing)
+      }
+    end
+  end
+end

data/lib/plutonium/wizard/state.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Wizard
+    # In-memory snapshot of one wizard instance's stored state, exchanged between
+    # the {Store} and the runner. Independent of any persistence backend.
+    #
+    # +data+ and +persisted+ default to an empty hash, +visited+ to an empty
+    # array, so callers never have to nil-check them.
+    State = Struct.new(
+      :wizard,
+      :instance_key,
+      :current_step,
+      :status,
+      :data,
+      :persisted,
+      :visited,
+      :owner,
+      :anchor,
+      :scope,
+      :token,
+      :engine,
+      # The optimistic-merge version the row was read at (nil for a state that was
+      # never read from a row, i.e. a fresh run). The store uses it to detect a
+      # concurrent write and merge instead of clobbering (§6.2).
+      :lock_version
+    ) do
+      def data = self[:data] || {}
+
+      def persisted = self[:persisted] || {}
+
+      def visited = self[:visited] || []
+    end
+  end
+end

data/lib/plutonium/wizard/step.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Wizard
+    # Metadata for one wizard step: its key, label, branching condition, captured
+    # field surface, per-step hooks, and the `using:` import marker (resolved in
+    # Task 3). A value object — holds no runtime state.
+    class Step
+      attr_reader :key, :label, :description, :condition, :fields,
+        :on_submit, :on_rollback, :using_spec
+
+      def initialize(key:, fields:, label: nil, description: nil, condition: nil,
+        on_submit: nil, on_rollback: nil, using_spec: nil)
+        @key = key
+        @label = label || key.to_s.humanize
+        @description = description
+        @condition = condition
+        @fields = fields
+        @on_submit = on_submit
+        @on_rollback = on_rollback
+        @using_spec = using_spec
+      end
+
+      def review? = false
+
+      # The step's form sections (§7.1): inline `form_layout` wins, else the layout
+      # inherited from a `using:` source (filtered to imported fields), else nil.
+      # Resolved lazily so a `using:` import is only loaded when actually needed.
+      def form_layout = fields.form_layout_sections
+
+      # The effective attribute schema ({name => type}) contributed to the union
+      # `data` schema — a `using:` import composed with inline `attribute`
+      # declarations (inline wins on conflict, §2.4).
+      def attribute_schema = fields.attribute_schema
+
+      # The per-attribute options ({name => {default:, ...}}) contributed to the
+      # typed `data` snapshot, so e.g. `default:` applies (§2.6).
+      def attribute_options = fields.attribute_options
+
+      # The effective input config ({name => {options:, block:}}) — imported inputs
+      # composed with inline `input`/`field` declarations (inline wins).
+      def inputs = fields.inputs
+
+      # Inline `validates` declarations recorded for this step (raw [args, options]).
+      def validations = fields.validations
+
+      # Form-metadata validators contributed by a `using:` import ([args, options]
+      # pairs), replayed onto the typed data class alongside inline `validations`
+      # so imported fields surface required/length/etc. — without feeding the
+      # runner (which validates imports through the transient model).
+      def imported_form_validators = fields.imported_form_validators
+
+      # The imported validation runner ({attribute => [messages]} over a data
+      # slice), or nil when there's no `using:` import or `validate: false`.
+      def imported_validate_fn = fields.imported_validate_fn
+
+      # The structured inputs declared in this step ({name => {options:, block:}}).
+      def structured_inputs = fields.defined_structured_inputs
+    end
+  end
+end

data/lib/plutonium/wizard/step_adapter.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Wizard
+    # Presents a wizard {Step} in the shape the existing resource-form pipeline
+    # (`Plutonium::UI::Form::Resource`) consumes from a definition (§7). The form
+    # renders a step exactly like a resource/interaction definition by reading:
+    #
+    #   - `defined_fields`            — empty; a step carries no separate field
+    #                                   config, only `input`s.
+    #   - `defined_inputs`            — the step's merged inline + imported inputs
+    #                                   (`{name => {options:, block:}}`).
+    #   - `defined_structured_inputs` — the step's structured inputs.
+    #   - `resolve_form_sections`     — the step's resolved form layout (inline
+    #                                   `form_layout` or one inherited from `using:`),
+    #                                   normalized to ResolvedSections; nil → single
+    #                                   grid.
+    #
+    # This is the seam that lets a wizard step ride the resource-form rendering
+    # path unchanged — seeded from the wizard's typed `data` (the form `object`),
+    # which is what makes resume/back rehydration (including repeater rows) work.
+    class StepAdapter
+      # Options on a file `input` that are consumed SERVER-SIDE by Wizard::Driving
+      # (from the raw step) to stage the upload — never form/HTML concerns. They must
+      # be stripped from what the form renders: Phlex rejects a Class-valued
+      # `uploader:` as an attribute, and `backend:` would otherwise leak as a stray
+      # attribute. Driving reads them off `step.inputs` directly, so removing them
+      # here is invisible to staging.
+      STAGING_ONLY_INPUT_OPTIONS = %i[backend uploader].freeze
+
+      def initialize(step)
+        @step = step
+      end
+
+      attr_reader :step
+
+      # The form's per-field config map. A step declares inputs, not fields, so
+      # there is no separate `field` config — return an empty map. The form merges
+      # `defined_fields[name]` (here {}) with `defined_inputs[name]`.
+      def defined_fields = {}
+
+      # `{name => {options:, block:}}` — inline + `using:`-imported inputs, with the
+      # server-side staging options stripped so they don't render as HTML attributes.
+      def defined_inputs
+        step.inputs.transform_values do |config|
+          options = config[:options]
+          next config if options.nil? || STAGING_ONLY_INPUT_OPTIONS.none? { |k| options.key?(k) }
+
+          config.merge(options: options.except(*STAGING_ONLY_INPUT_OPTIONS))
+        end
+      end
+
+      # `{name => {options:, block:}}` — structured (single/repeater) inputs.
+      def defined_structured_inputs = step.structured_inputs
+
+      # The resource form never imports nested-resource inputs from a wizard step.
+      def defined_nested_inputs = {}
+
+      # Auto-detect submit-and-continue is disabled for wizards (the wizard owns
+      # its own Back/Next/Finish navigation).
+      def submit_and_continue = false
+
+      # Resolve the step's form layout into ordered ResolvedSections (the shape the
+      # resource form's `resolve_form_layout` expects), or nil for a single grid.
+      #
+      # The step's `form_layout` is either:
+      #   - inline  → an Array<FormLayout::Section> (unresolved), or
+      #   - imported → an Array<FormLayout::ResolvedSection> (already resolved by
+      #     the FieldImporter, filtered to imported fields).
+      # Normalize both to ResolvedSections claiming only currently-permitted fields.
+      def resolve_form_sections(resource_fields)
+        layout = step.form_layout
+        return nil if layout.blank?
+
+        resource_fields = resource_fields.map(&:to_sym)
+        return resolve_resolved_sections(layout, resource_fields) if layout.first.is_a?(Plutonium::Definition::FormLayout::ResolvedSection)
+
+        resolve_raw_sections(layout, resource_fields)
+      end
+
+      private
+
+      # An imported layout is already ResolvedSections; just restrict each section's
+      # fields to the currently-permitted set (and drop emptied non-ungrouped ones).
+      def resolve_resolved_sections(layout, resource_fields)
+        known = resource_fields.to_set
+        layout.filter_map do |resolved|
+          fields = resolved.fields.map(&:to_sym).select { |f| known.include?(f) }
+          next if fields.empty? && !resolved.section.ungrouped?
+          Plutonium::Definition::FormLayout::ResolvedSection.new(resolved.section, fields)
+        end
+      end
+
+      # Raw inline Sections resolve exactly like a resource definition's layout
+      # (first-section-wins ownership; unlisted permitted fields fall into a
+      # trailing ungrouped bucket) — so delegate to the canonical resolver rather
+      # than re-implement it.
+      def resolve_raw_sections(layout, resource_fields)
+        Plutonium::Definition::FormLayout.resolve_sections(layout, resource_fields)
+      end
+    end
+  end
+end

data/lib/plutonium/wizard/store/active_record.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Wizard
+    module Store
+      # Shipped store, backed by the +plutonium_wizard_sessions+ table via {Session}.
+      class ActiveRecord < Base
+        # A +data+ blob encrypted at rest (§8.1, the wizard's +encrypt_data+ opt-in)
+        # is stored as a SELF-DESCRIBING envelope INSIDE the jsonb column:
+        # +{ "_enc" => "<ciphertext>" }+. The row therefore decrypts based on its own
+        # shape, independent of the wizard's CURRENT +encrypt_data?+ (which may have
+        # been toggled after the row was written). Only +data+ (the step field values)
+        # is encrypted; +tracked_records+ holds record GIDs and stays in clear.
+        ENCRYPTED_ENVELOPE_KEY = "_enc"
+
+        def read(instance_key)
+          row = Session.find_by(instance_key: instance_key)
+          row && to_state(row)
+        end
+
+        # Upsert the run's state. Concurrency-safe (§6.2): two requests can write the
+        # same run (double-submit, two tabs, the first-step create race). A blind
+        # overwrite would let the later writer clobber the earlier one's staged data
+        # (last-writer-wins). Instead:
+        #
+        # - **Create** (no row yet): insert. If a concurrent create won the unique
+        #   +instance_key+ index (RecordNotUnique), fall through to the merge path.
+        # - **Update** (row exists): take a row lock, then compare the version the
+        #   caller's +state+ was read at against the row's CURRENT version. Equal →
+        #   no concurrent writer, write +state+ verbatim (honors this request's
+        #   prunes/deletions). Differs (or the caller never read a version — it lost
+        #   a create race) → a concurrent advance committed; call the +merge+ block
+        #   with the latest committed {State} so the two sides are combined, and
+        #   write the result. The lock serializes writers; the version check keeps
+        #   the merge off the normal single-writer path.
+        #
+        # +merge+ is optional — a blockless caller keeps last-writer-wins (the
+        # store-contract callers that don't model concurrency). The runner always
+        # passes one.
+        def write(instance_key, state, cleanup_after:, &merge)
+          row = Session.find_or_initialize_by(instance_key: instance_key)
+
+          if row.new_record?
+            assign_row(row, state, cleanup_after)
+            begin
+              row.save!
+              return to_state(row)
+            rescue ::ActiveRecord::RecordNotUnique
+              # Lost the create race — the row now exists. Re-fetch and merge.
+              row = Session.find_by!(instance_key: instance_key)
+            end
+          end
+
+          write_locked(row, state, cleanup_after, merge)
+        end
+
+        def complete(instance_key)
+          row = Session.find_by!(instance_key: instance_key)
+          row.update!(status: "completed", completed_at: Time.current, data: {}, tracked_records: {}, visited: [])
+        end
+
+        def clear(instance_key)
+          Session.where(instance_key: instance_key).delete_all
+        end
+
+        def completed?(instance_key:)
+          Session.status_completed.where(instance_key: instance_key).exists?
+        end
+
+        private
+
+        # Update an existing row under a row lock, merging when a concurrent writer
+        # moved it past the version the caller read. Returns the written {State}
+        # (carrying the bumped +lock_version+ so the caller's next write is current).
+        def write_locked(row, state, cleanup_after, merge)
+          row.with_lock do
+            final = (merge && stale_for_merge?(row, state)) ? merge.call(to_state(row)) : state
+            assign_row(row, final, cleanup_after)
+            row.save!
+          end
+          to_state(row)
+        end
+
+        # Whether the row has moved since the caller read it (so a verbatim write
+        # would clobber a concurrent advance): the caller never read a version (nil
+        # — it thought it was creating, i.e. lost a create race), or its version is
+        # behind the row's current one.
+        def stale_for_merge?(row, state)
+          state.lock_version.nil? || state.lock_version != row.lock_version
+        end
+
+        # Copy a {State} onto the row's columns. Never touches +lock_version+ —
+        # ActiveRecord manages it (the WHERE-clause check + increment on save).
+        def assign_row(row, state, cleanup_after)
+          row.wizard = state.wizard
+          row.current_step = state.current_step
+          row.status ||= "in_progress"
+          row.data = encode_data(state.data, state.wizard)
+          row.tracked_records = state.persisted
+          row.visited = state.visited
+          row.owner = state.owner
+          row.anchor = state.anchor
+          row.scope = state.scope
+          row.token = state.token
+          row.engine = state.engine
+          row.expires_at = cleanup_after ? Time.current + cleanup_after : nil
+        end
+
+        def to_state(row)
+          State.new(
+            wizard: row.wizard,
+            instance_key: row.instance_key,
+            current_step: row.current_step,
+            status: row.status,
+            data: decode_data(row.data, row.wizard),
+            persisted: row.tracked_records,
+            visited: row.visited,
+            owner: row.owner,
+            anchor: row.anchor,
+            scope: row.scope,
+            token: row.token,
+            engine: row.engine,
+            lock_version: row.lock_version
+          )
+        end
+
+        # Encrypt the run's field data at rest when the wizard opts in via
+        # `encrypt_data`; a non-encrypting wizard stores the plain hash. Wrapped in
+        # a self-describing {ENCRYPTED_ENVELOPE_KEY} envelope (see the class note).
+        def encode_data(data, wizard_name)
+          return data unless encrypting?(wizard_name)
+
+          cipher = with_encryption_context(wizard_name) do
+            ::ActiveRecord::Encryption.encryptor.encrypt(JSON.generate(data))
+          end
+          {ENCRYPTED_ENVELOPE_KEY => cipher}
+        end
+
+        # Reverse of {#encode_data}: an envelope is decrypted from the row's SHAPE
+        # (not the wizard's current flag); any other value is a plain, never-
+        # encrypted blob and is returned as-is.
+        def decode_data(stored, wizard_name)
+          return stored unless stored.is_a?(Hash) && stored.key?(ENCRYPTED_ENVELOPE_KEY)
+
+          clear = with_encryption_context(wizard_name) do
+            ::ActiveRecord::Encryption.encryptor.decrypt(stored[ENCRYPTED_ENVELOPE_KEY])
+          end
+          JSON.parse(clear)
+        end
+
+        # Whether the wizard opted into at-rest encryption. A name that doesn't
+        # resolve to a loaded class (e.g. a renamed/removed wizard, or a synthetic
+        # store-test name) can carry no `encrypt_data` declaration to honour, so it
+        # is treated as clear — existing rows decode by SHAPE regardless.
+        def encrypting?(wizard_name)
+          wizard_name.to_s.safe_constantize&.encrypt_data? || false
+        end
+
+        # Run an encrypt/decrypt, translating ActiveRecord's lazy, context-free
+        # configuration error into one that names the wizard and points at the fix —
+        # `encrypt_data` is opt-in, so a missing key set is an author error, not a
+        # runtime surprise to swallow.
+        def with_encryption_context(wizard_name)
+          yield
+        rescue ::ActiveRecord::Encryption::Errors::Configuration => e
+          raise ::ActiveRecord::Encryption::Errors::Configuration,
+            "#{wizard_name} declares `encrypt_data` but ActiveRecord encryption is not " \
+            "configured (set active_record.encryption.{primary_key,deterministic_key," \
+            "key_derivation_salt}). Original error: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/plutonium/wizard/store/base.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Wizard
+    module Store
+      # Storage port for wizard sessions. Adapters exchange {State} value objects
+      # and are keyed by the derived {InstanceKey} digest.
+      class Base
+        # @param instance_key [String]
+        # @return [State, nil]
+        def read(instance_key) = raise NotImplementedError
+
+        # Upsert by +instance_key+. Stamps +expires_at = now + cleanup_after+
+        # (nil cleanup_after → null expiry).
+        #
+        # @param instance_key [String]
+        # @param state [State]
+        # @param cleanup_after [ActiveSupport::Duration, nil]
+        # @return [State]
+        def write(instance_key, state, cleanup_after:) = raise NotImplementedError
+
+        # Mark completed: status "completed", stamp completed_at, null data/persisted.
+        #
+        # @param instance_key [String]
+        def complete(instance_key) = raise NotImplementedError
+
+        # Delete the row.
+        #
+        # @param instance_key [String]
+        def clear(instance_key) = raise NotImplementedError
+
+        # One-time completion check (§4.3 / §9): does a `completed` row exist at
+        # this instance_key? Identity is the digest, so the caller recomputes the
+        # wizard's instance_key (concurrency_key + folded tenant) and asks here.
+        #
+        # @param instance_key [String]
+        # @return [Boolean]
+        def completed?(instance_key:) = raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/plutonium/wizard/store/memory.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Wizard
+    module Store
+      # In-memory store for fast, DB-free unit tests (and a template for future
+      # adapters). Mirrors {ActiveRecord}'s observable behavior.
+      class Memory < Base
+        def initialize
+          @rows = {}
+        end
+
+        def read(instance_key)
+          @rows[instance_key]&.dup
+        end
+
+        def write(instance_key, state, cleanup_after:)
+          state = state.dup
+          state.instance_key = instance_key
+          state.status ||= "in_progress"
+          @rows[instance_key] = state
+        end
+
+        def complete(instance_key)
+          state = @rows.fetch(instance_key)
+          state.status = "completed"
+          state.data = {}
+          state.persisted = {}
+          state.visited = []
+          state
+        end
+
+        def clear(instance_key)
+          @rows.delete(instance_key)
+        end
+
+        def completed?(instance_key:)
+          row = @rows[instance_key]
+          !!row && row.status == "completed"
+        end
+      end
+    end
+  end
+end

data/lib/plutonium/wizard/sweep_job.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Wizard
+    # The abandonment sweep (§8.1). Reaps idle wizard sessions whose +expires_at+
+    # has passed (status +in_progress+ or +completing+ — the latter catches a
+    # finalize that crashed mid-flight, §6.2). For each row it builds a {Runner}
+    # and calls +cancel+, which runs the wizard's cleanup — each step's per-step
+    # +on_rollback+ (additive side-effect cleanup, if any) then the engine's
+    # always-on destroy of every tracked record, in reverse order — and then
+    # deletes the row.
+    #
+    # This is **load-bearing for save-as-you-go wizards**: for +execute+-only
+    # wizards an unscheduled sweep merely leaves stale session rows (harmless), but
+    # for +on_submit+ wizards the sweep is the only thing that cleans up abandoned
+    # partial domain records. Hosts must schedule it (a periodic job / rake task).
+    #
+    # The job is idempotent and safe to re-run: a row already cleared is skipped,
+    # and an unconstantizable wizard class is skipped while the row is still reaped.
+    # +completed+ rows are never touched (the +sweepable+ scope excludes them).
+    class SweepJob < ActiveJob::Base
+      def perform(now: Time.current)
+        store = Store::ActiveRecord.new
+
+        Session.sweepable(now).find_each do |row|
+          sweep_row(row, store, now)
+        end
+      end
+
+      private
+
+      def sweep_row(row, store, now)
+        # Re-check the row is STILL sweepable under a fresh read. The finalize we may
+        # be racing (a `completing` row within, or just past, the grace window) could
+        # have completed — and a one-time wizard RETAINS its `completed` row as the
+        # gate marker. Without this re-check, the sweep could cancel+delete a row the
+        # finalize just completed, destroying that marker (un-gating the user) or
+        # racing the cleanup of its tracked records. A still-sweepable row is safe to
+        # reap; anything else (completed, cleared, or refreshed) is skipped.
+        return unless Session.sweepable(now).exists?(id: row.id)
+
+        wizard_class = row.wizard.safe_constantize
+
+        if wizard_class
+          # `cancel` runs the wizard's cleanup (each step's on_rollback, then the
+          # engine always destroys its tracked records) and then clears the row.
+          #
+          # Reconstruct the run's context from the row the sweep already trusts:
+          #
+          # - `current_user: row.owner` — a non-`anonymous` wizard's state is
+          #   owner-scoped (§4.5), so with no owner the runner would mismatch, drop
+          #   the loaded state, and cancel an EMPTY run, orphaning every `persist`'d
+          #   record (the exact case the sweep exists for).
+          # - `current_scoped_entity: row.scope` — the wizard's `current_scoped_entity`
+          #   is set from this argument (not the loaded state), so a tenant-aware
+          #   `on_rollback` would otherwise run with a nil tenant.
+          #
+          # (The `anchor` needs no argument — the runner restores it from the loaded
+          # state.)
+          Runner.new(
+            wizard_class: wizard_class,
+            store: store,
+            instance_key: row.instance_key,
+            current_user: row.owner,
+            current_scoped_entity: row.scope
+          ).cancel
+        end
+
+        # Safety net: an unconstantizable wizard never ran `cancel` (so the row is
+        # still present), and a `cancel` failure shouldn't leave the row behind.
+        # `clear` is a no-op when the row is already gone.
+        store.clear(row.instance_key)
+      end
+    end
+  end
+end

data/lib/plutonium/wizard.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "wizard/errors"
+require_relative "wizard/configuration"
+
+module Plutonium
+  # The Plutonium wizard subsystem: multi-step, DB-backed, data-capture wizards.
+  module Wizard
+    # The union `data` schema (§2.6) and the runner's inline validator both build
+    # anonymous ActiveModel classes from a step's `attribute_schema`. A `using:`
+    # import contributes the model's column types (e.g. `:text`), which
+    # ActiveModel's type registry doesn't know. Fall back to `:string` for any type
+    # the registry can't resolve so the snapshot/validator still builds — the
+    # staged value is stored/displayed as-is.
+    def self.safe_attribute_type(type)
+      ActiveModel::Type.lookup(type)
+      type
+    rescue ArgumentError
+      :string
+    end
+
+    # Compute a wizard run's identity digest (§4.1), shared by the runner/driving
+    # layer (which creates rows) and the gate (which recomputes the key) so the
+    # two are byte-identical — if they diverge, one-time gating silently breaks.
+    #
+    # A wizard with a `concurrency_key` is hashed over its resolved key value(s)
+    # (the tenant is folded in by {Base#concurrency_key_value}); otherwise it's
+    # hashed over the per-launch `wizard_token`.
+    #
+    # The wizard's `concurrency_key` resolver and tenancy fold run in a transient
+    # wizard instance seeded with the identity context. A resolver that references
+    # a missing context method raises a clear error.
+    #
+    # @return [String] the hex SHA256 instance_key
+    def self.compute_instance_key(wizard_class:, current_user:, current_scoped_entity:, anchor:, wizard_token:)
+      unless wizard_class.concurrency_key?
+        return InstanceKey.tokened(wizard_class.name, wizard_token)
+      end
+
+      probe = wizard_class.new
+      probe.current_user = current_user
+      probe.current_scoped_entity = current_scoped_entity
+      probe.wizard_token = wizard_token
+      probe.anchor = anchor if wizard_class.anchored?
+      key_value = probe.concurrency_key_value
+      InstanceKey.concurrency(wizard_class.name, key_value)
+    rescue NameError => e
+      raise ArgumentError,
+        "#{wizard_class.name}'s concurrency_key referenced a method that isn't " \
+        "available in this context (#{e.message}). Available: current_user, " \
+        "current_scoped_entity, anchor, wizard_token, or a host method."
+    end
+
+    # The "continue where you left off" listing (§4.5): in-progress wizard runs
+    # for the current user, narrowed to the current tenant scope when the portal is
+    # entity-scoped, each enriched with the wizard's label/icon, current step (+
+    # label), updated_at, and a resolved resume_url (nil with a reason when a mount
+    # can't be resolved generically).
+    #
+    # This is the public, ergonomic API: like interactions, it takes the
+    # +view_context+ and derives the run owner and tenant scope from the controller
+    # it carries — `current_user` (the run owner) and `current_scoped_entity` (the
+    # tenant, when `scoped_to_entity?`; nil for a non-scoped portal). It delegates to
+    # {Resume.entries_for}, which does that derivation and builds the resume URLs in
+    # this portal.
+    #
+    #   Plutonium::Wizard.in_progress_for(view_context)
+    #   Plutonium::Wizard.in_progress_for(view_context, wizard: ConfigureCompanyWizard)
+    #   Plutonium::Wizard.in_progress_for(view_context, anchor: company)
+    #
+    # +anchor:+ and +wizard:+ are OPTIONAL narrowing filters applied IN THE QUERY,
+    # before each row is enriched (resume-URL built, anchor loaded) — so filtering
+    # here is cheaper than `select`-ing the returned array, which enriches every row
+    # first. Use them for the per-record / per-wizard resume widgets (e.g. "does this
+    # company have an unfinished `configure` draft?"). They compose. Omit both for
+    # the full "continue where you left off" dashboard list.
+    #
+    # @param view_context [ActionView::Base] the current view context (as interactions take)
+    # @param anchor [ActiveRecord::Base, nil] narrow to runs anchored against this record
+    # @param wizard [Class, nil] narrow to runs of this wizard class
+    # @return [Array<Plutonium::Wizard::Resume::Entry>]
+    def self.in_progress_for(view_context, anchor: nil, wizard: nil)
+      Resume.entries_for(view_context, anchor: anchor, wizard: wizard)
+    end
+  end
+end