open-loam 0.1.0

data/lib/loam/custom_field_index.rb

@@ -0,0 +1,262 @@
+module Loam
+  # The read-model index for custom fields (Loam::CustomFieldValue) — a typed-EAV
+  # projection that makes custom-field filter/sort/search index-backed.
+  #
+  #   Loam::CustomFieldIndex.filter(DamageReport, "severity", "eq", "critical")  # a relation
+  #   Loam::CustomFieldIndex.order(DamageReport, "severity", :asc)
+  #   Loam::CustomFieldIndex.reindex(DamageReport)                               # rebuild
+  #
+  # SAFETY: `field_key` must name a real Loam::FieldDefinition (no arbitrary
+  # keys); values are cast to the declared type; queries are tenant-scoped
+  # throughout (index rows carry tenant_id, the model relation is default-scoped),
+  # so a filter can't reach across tenants. Encrypted data lives in real columns,
+  # never in a custom field — nothing encrypted is projected here.
+  module CustomFieldIndex
+    OPS = %w[eq neq gt gte lt lte contains present blank].freeze
+
+    module_function
+
+    # --- maintenance (called from Loam::CustomFields) ---
+
+    # Re-project one record's custom fields (delete + insert). Soft-delete keeps
+    # the rows (the filter's base scope hides the record anyway — the same
+    # decision as the L-912 search token driver); a hard destroy removes them.
+    def project(record)
+      model = record.class
+      return unless model.respond_to?(:custom_field_definitions)
+
+      type = index_type(model)
+      Loam::CustomFieldValue.where(indexable_type: type, indexable_id: record.id).delete_all
+
+      rows = model.custom_field_definitions.filter_map { |definition| row_for(record, definition, type) }
+      Loam::CustomFieldValue.insert_all(rows) if rows.any?
+    end
+
+    def remove(record)
+      Loam::CustomFieldValue.where(indexable_type: index_type(record.class), indexable_id: record.id).delete_all
+    end
+
+    def reindex(model)
+      Loam::CustomFieldValue.where(indexable_type: index_type(model)).delete_all
+      model.find_each { |record| project(record) }
+    end
+
+    # --- query API ---
+
+    def filter(model, field_key, op, value = nil)
+      field_key = field_key.to_s
+      refuse_unknown_field!(model, field_key)
+      refuse_unreadable_field!(model, field_key)
+      raise Loam::Error, "unknown custom-field op #{op.inspect}" unless OPS.include?(op.to_s)
+
+      if covered?(model, field_key)
+        self.partial = false
+        index_filter(model, field_key, op, value)
+      else
+        # CORRECTNESS OVER SPEED: the index is known-incomplete for this field
+        # (coverage gap), so serve an authoritative JSON-scan result — never a
+        # silently-partial index set — AND enqueue a background reindex (deduped)
+        # to heal the gap so subsequent queries are fast again. `partial?` lets
+        # the caller surface an honest "results may be incomplete, reindexing…".
+        self.partial = true
+        schedule_reindex(model)
+        json_filter(model, field_key, op, value)
+      end
+    end
+
+    # The index-backed relation (used when coverage is complete).
+    def index_filter(model, field_key, op, value)
+      rows = base(model).where(field_key: field_key)
+
+      if op.to_s == "blank"
+        present_ids = rows.where.not(value_text: [ nil, "" ]).select(:indexable_id)
+        return model.where.not(id: present_ids)
+      end
+
+      model.where(id: predicate(rows, op.to_s, value).select(:indexable_id))
+    end
+
+    # Order a model's records by an indexed custom field (value_text — good for
+    # dictionary/string fields, the common case; numeric-aware ordering is a
+    # follow-up). Records with no value sort last (LEFT JOIN + NULLs).
+    def order(model, field_key, dir = :asc)
+      refuse_unknown_field!(model, field_key.to_s)
+      refuse_unreadable_field!(model, field_key.to_s)
+      # The LEFT JOIN keeps EVERY record (un-indexed ones sort as NULL), so an
+      # incomplete index mis-orders the gap but never drops a row. Flag it and
+      # heal in the background.
+      unless covered?(model, field_key.to_s)
+        self.partial = true
+        schedule_reindex(model)
+      end
+      table = Loam::CustomFieldValue.table_name
+      conn = model.connection
+      join = "LEFT JOIN #{table} ON #{table}.indexable_type = #{conn.quote(index_type(model))} " \
+             "AND #{table}.indexable_id = #{model.table_name}.id " \
+             "AND #{table}.field_key = #{conn.quote(field_key.to_s)} " \
+             "AND #{table}.tenant_id = #{Loam.tenant!.id}"
+      model.joins(join).order(Arel.sql("#{table}.value_text #{dir.to_s.casecmp('desc').zero? ? 'DESC' : 'ASC'}"))
+    end
+
+    # --- coverage + self-heal (L-919) ---
+
+    # How complete the index is for a field: how many live records HAVE a value
+    # (the authoritative JSON column) vs how many index rows exist. The trust
+    # signal — "9,980 of 10,000 indexed" tells an operator whether the index is
+    # complete or drifting (legacy data, a bulk write that bypassed the hook, a
+    # field def added before a backfill). Counting expected does a JSON pass, so
+    # it's a periodic READOUT, never a per-row query cost.
+    def coverage(model, field_key)
+      field_key = field_key.to_s
+      exp = expected(model, field_key)
+      got = indexed(model, field_key)
+      { field_key: field_key, expected: exp, indexed: got, complete: got >= exp,
+        ratio: exp.zero? ? 1.0 : (got.to_f / exp) }
+    end
+
+    def covered?(model, field_key)
+      coverage(model, field_key)[:complete]
+    end
+
+    def indexed(model, field_key)
+      base(model).where(field_key: field_key.to_s).where.not(value_text: [ nil, "" ]).count
+    end
+
+    def expected(model, field_key)
+      return 0 unless model.column_names.include?("custom_fields")
+
+      key = field_key.to_s
+      model.pluck(:custom_fields).count { |cf| cf.is_a?(Hash) && cf[key].to_s.strip != "" }
+    end
+
+    # Was the last filter/order served over an incomplete index? The admin surfaces
+    # this as an honest "results may be incomplete, reindexing…".
+    def partial?
+      Thread.current[:loam_index_partial] == true
+    end
+
+    def partial=(value)
+      Thread.current[:loam_index_partial] = value
+    end
+
+    # Enqueue a background reindex to heal a gap — DEDUPED so a hot gappy field
+    # doesn't enqueue one per request. In-process dedup here (single-process
+    # prototype); a DB/cache marker is the multi-process path.
+    def schedule_reindex(model)
+      key = [ Loam.tenant!.id, model.base_class.name ]
+      return if pending_reindex.include?(key)
+
+      pending_reindex << key
+      Loam::CustomFieldReindexJob.perform_later(Loam.tenant!.id, model.base_class.name)
+    end
+
+    def clear_pending(tenant_id, model_name)
+      pending_reindex.delete([ tenant_id, model_name ])
+    end
+
+    def reset_pending!
+      @pending_reindex = Set.new
+    end
+
+    def pending_reindex
+      @pending_reindex ||= Set.new
+    end
+
+    # Authoritative correct filter over the JSON column — DB-agnostic (reads each
+    # record's cast custom_field), used only as the fallback when the index is
+    # incomplete. Slow (a scan), which is exactly why the heal runs.
+    def json_filter(model, field_key, op, value)
+      ids = model.find_each.select { |record| json_match?(record, field_key, op, value) }.map(&:id)
+      model.where(id: ids)
+    end
+
+    def json_match?(record, field_key, op, value)
+      actual = (record.custom_field(field_key) rescue nil)
+      case op.to_s
+      when "eq"       then actual.to_s == value.to_s
+      when "neq"      then actual.to_s != value.to_s
+      when "present"  then actual.to_s.strip != ""
+      when "blank"    then actual.to_s.strip == ""
+      when "contains" then actual.to_s.include?(value.to_s)
+      when "gt"       then actual.to_f > value.to_f
+      when "gte"      then actual.to_f >= value.to_f
+      when "lt"       then actual.to_f < value.to_f
+      when "lte"      then actual.to_f <= value.to_f
+      end
+    end
+
+    # --- internals ---
+
+    def base(model)
+      Loam::CustomFieldValue.where(indexable_type: index_type(model)) # tenant-scoped by default_scope
+    end
+
+    def index_type(model_or_class)
+      klass = model_or_class.is_a?(Class) ? model_or_class : model_or_class.class
+      klass.base_class.name
+    end
+
+    def predicate(rows, op, value)
+      case op
+      when "eq"       then rows.where(value_text: value.to_s)
+      when "neq"      then rows.where.not(value_text: value.to_s)
+      when "contains" then rows.where("value_text LIKE ?", "%#{sanitize_like(value)}%")
+      when "present"  then rows.where.not(value_text: [ nil, "" ])
+      when "gt"       then numeric(rows, value, ">")
+      when "gte"      then numeric(rows, value, ">=")
+      when "lt"       then numeric(rows, value, "<")
+      when "lte"      then numeric(rows, value, "<=")
+      end
+    end
+
+    # Numeric comparisons hit the indexed value_number column.
+    def numeric(rows, value, operator)
+      rows.where("value_number #{operator} ?", value.to_f)
+    end
+
+    def row_for(record, definition, type)
+      value = (record.custom_field(definition.name) rescue nil)
+      return nil if value.nil?
+
+      # ALL value columns are present (nil when unused) so insert_all sees a
+      # uniform key set across every row.
+      row = {
+        tenant_id: record.tenant_id, indexable_type: type, indexable_id: record.id,
+        field_key: definition.name, value_text: value.to_s,
+        value_number: nil, value_boolean: nil, value_datetime: nil
+      }
+      case definition.field_type
+      when "integer", "decimal" then row[:value_number] = value.to_f
+      when "boolean"            then row[:value_boolean] = ActiveModel::Type::Boolean.new.cast(value)
+      when "date", "datetime"   then row[:value_datetime] = (Time.zone.parse(value.to_s) rescue nil)
+      end
+      row
+    end
+
+    def refuse_unknown_field!(model, field_key)
+      known = model.respond_to?(:custom_field_definitions) && model.custom_field_definitions.exists?(name: field_key)
+      raise Loam::Error, "no custom field #{field_key.inspect} on #{model.name}" unless known
+    end
+
+    # THE oracle guard: filtering or sorting on a custom field the current role
+    # may not read would let a user infer restricted values by observing which
+    # records match. Enforced against the current actor's role; a system/background
+    # context (no actor — reindex, a business rule) is trusted and not gated.
+    def refuse_unreadable_field!(model, field_key)
+      actor = Loam::Current.actor
+      return if actor.nil?
+
+      definition = model.custom_field_definitions.find_by(name: field_key.to_s)
+      return if definition.nil? # unknown field is refuse_unknown_field!'s job
+
+      role = Loam::Membership.find_by(user_id: actor.id)&.role
+      return if definition.readable_by?(role)
+
+      raise Loam::FieldAccessError, "custom field #{field_key.inspect} is not readable by #{role.inspect}"
+    end
+
+    def sanitize_like(value)
+      value.to_s.gsub(/[\\%_]/) { |c| "\\#{c}" }
+    end
+  end
+end

data/lib/loam/custom_fields.rb

@@ -0,0 +1,114 @@
+module Loam
+  # Runtime, migration-free fields — stored in the `custom_fields` json
+  # column every generated entity table carries. Included automatically by
+  # `rails g loam:entity`. Shape is declared at runtime via a
+  # Loam::FieldDefinition (typically through the admin "Field definitions"
+  # screen), not in code — that's what makes it migration-free.
+  #
+  #   equipment.custom_field(:serial_number)                # => "SN-123" (cast)
+  #   equipment.set_custom_field(:serial_number, "SN-123")
+  #
+  # Reading/writing a name with no matching Loam::FieldDefinition for this
+  # tenant + entity raises Loam::UnknownCustomFieldError immediately — the
+  # same "fail loudly at the access site" philosophy as Loam.tenant!.
+  module CustomFields
+    extend ActiveSupport::Concern
+
+    included do
+      # Keep the read-model index (Loam::CustomFieldIndex) current so custom-field
+      # filter/sort is index-backed. Re-project only when the custom_fields column
+      # actually changed (a soft-delete touches only deleted_at, so the rows stay
+      # and the base scope hides the record — the L-912 posture). A no-op for a
+      # model with no custom_fields column. Guarded by respond_to? so Loam::
+      # CustomFields stays includable in a plain class for a DSL-only test.
+      if respond_to?(:after_save)
+        after_save    :loam_reindex_custom_fields, if: :loam_custom_fields_dirty?
+        after_destroy :loam_deindex_custom_fields
+      end
+    end
+
+    class_methods do
+      def custom_field_definitions
+        Loam::FieldDefinition.where(entity_type: name)
+      end
+    end
+
+    def custom_field(name)
+      definition = custom_field_definition!(name)
+      cast_custom_field(definition.field_type, custom_fields[definition.name])
+    end
+
+    def set_custom_field(name, value)
+      definition = custom_field_definition!(name)
+      custom_fields[definition.name] = serialize_custom_field(definition.field_type, value)
+      value
+    end
+
+    # The display label for a custom field. For a dictionary-typed field this is
+    # the matching entry's label; for every other type it is just the value. A
+    # dictionary value is stored as its plain code, so read/write is unchanged —
+    # only the human-facing rendering differs.
+    def custom_field_label(name)
+      definition = custom_field_definition!(name)
+      value = custom_field(name)
+      return value unless definition.field_type == "dictionary"
+
+      Loam::Dictionaries.label_for(definition.dictionary_key, value)
+    end
+
+    private
+
+    def loam_reindex_custom_fields = Loam::CustomFieldIndex.project(self)
+    def loam_deindex_custom_fields = Loam::CustomFieldIndex.remove(self)
+
+    def loam_custom_fields_dirty?
+      return false unless self.class.respond_to?(:custom_field_definitions)
+
+      # On create every column counts as changed; on update, only re-project when
+      # the custom_fields json actually moved.
+      respond_to?(:saved_change_to_custom_fields?) ? saved_change_to_custom_fields? : true
+    end
+
+    def custom_field_definition!(name)
+      custom_field_definitions_by_name.fetch(name.to_s) do
+        raise UnknownCustomFieldError, "No Loam::FieldDefinition named #{name.inspect} for #{self.class.name} " \
+                                       "(tenant #{Loam.tenant&.id.inspect})"
+      end
+    end
+
+    # Memoized per-instance: several fields are typically read/written per
+    # request, and definitions vary per tenant so they can't be cached on the
+    # class itself.
+    def custom_field_definitions_by_name
+      @custom_field_definitions_by_name ||= self.class.custom_field_definitions.index_by(&:name)
+    end
+
+    def cast_custom_field(type, raw)
+      return nil if raw.nil?
+
+      case type.to_s
+      when "integer" then raw.to_i
+      when "decimal" then BigDecimal(raw.to_s)
+      when "boolean" then ActiveModel::Type::Boolean.new.cast(raw)
+      when "date" then Date.parse(raw.to_s)
+      when "datetime" then Time.zone.parse(raw.to_s)
+      else raw.to_s
+      end
+    end
+
+    def serialize_custom_field(type, value)
+      return nil if value.nil? || value == ""
+
+      case type.to_s
+      when "integer" then value.to_i
+      when "decimal" then value.to_s
+      when "boolean" then ActiveModel::Type::Boolean.new.cast(value)
+      when "date" then value.is_a?(Date) ? value.iso8601 : Date.parse(value.to_s).iso8601
+      when "datetime"
+        value.is_a?(Time) || value.is_a?(DateTime) ? value.utc.iso8601 : Time.zone.parse(value.to_s).utc.iso8601
+      else
+        value.to_s
+      end
+    end
+  end
+end

data/lib/loam/dashboard.rb

@@ -0,0 +1,17 @@
+module Loam
+  # Resolves the admin dashboard for the current tenant/actor: the ordered,
+  # role-visible, computed widgets to show. Uses the tenant's configured
+  # Loam::DashboardWidget rows (a manager arranges them); falls back to every
+  # registered widget in registration order when the tenant has configured none,
+  # so the dashboard is useful out of the box.
+  module Dashboard
+    module_function
+
+    def for(actor:, role:)
+      configured = Loam::DashboardWidget.active.ordered.pluck(:widget_key)
+      keys = configured.presence || Loam::Widgets.keys
+
+      keys.filter_map { |key| Loam::Widgets.resolve(key, actor: actor, role: role) }
+    end
+  end
+end

data/lib/loam/dictionaries.rb

@@ -0,0 +1,55 @@
+module Loam
+  # Read API for per-tenant managed lookup lists (Loam::Dictionary /
+  # Loam::DictionaryEntry). Everything is tenant-scoped automatically and
+  # memoized per request in Loam::Current.dictionary_cache (keyed with the tenant
+  # id, so an as_tenant switch mid-request can't read another tenant's list) —
+  # the same simple prototype cache as Loam::Configs.
+  #
+  #   Loam::Dictionaries.entries("damage_severity")        # active, ordered
+  #   Loam::Dictionaries.default("damage_severity")        # the default entry
+  #   Loam::Dictionaries.label_for("damage_severity", "critical")  # => "Critical"
+  module Dictionaries
+    class << self
+      # The dictionary for the current tenant, or nil.
+      def get(key)
+        memo([:dict, key.to_s]) { Loam::Dictionary.find_by(key: key.to_s) }
+      end
+
+      # Active entries, ordered by position. Empty for an unknown key.
+      def entries(key)
+        dictionary = get(key)
+        return [] unless dictionary
+
+        memo([:entries, key.to_s]) { dictionary.entries.active.ordered.to_a }
+      end
+
+      # The default entry (the first flagged one), or nil.
+      def default(key)
+        entries(key).find(&:is_default?)
+      end
+
+      # The label for a stored value — or the raw value itself when the key or
+      # value is unknown, so an old/foreign value still renders as something.
+      def label_for(key, value)
+        return value if value.blank?
+
+        entry = entries(key).find { |e| e.value == value.to_s }
+        entry ? entry.label : value
+      end
+
+      def clear_cache
+        Loam::Current.dictionary_cache = {}
+      end
+
+      private
+
+      def memo(subkey)
+        store = (Loam::Current.dictionary_cache ||= {})
+        cache_key = subkey + [ Loam.tenant&.id ]
+        return store[cache_key] if store.key?(cache_key)
+
+        store[cache_key] = yield
+      end
+    end
+  end
+end

data/lib/loam/durable_events.rb

@@ -0,0 +1,174 @@
+module Loam
+  # Durable (persistent) event subscribers — the twin of Loam::Events.subscribe,
+  # and the formal contract L-706 pins down.
+  #
+  # THE CONTRACT
+  #   * Ephemeral — Loam::Events.subscribe(&block): runs INLINE in the publisher's
+  #     thread, synchronously, best-effort. An exception in the block PROPAGATES
+  #     into whatever published the event. No persistence, no retry. Right for
+  #     cheap in-process fan-out (the webhook dispatcher enqueues its own jobs
+  #     this way).
+  #   * Persistent — Loam::DurableEvents.register(...): publishing commits a
+  #     Loam::EventDelivery row in the event's tenant, then hands the handler to a
+  #     background job. The handler's exception is CONTAINED in the job; delivery
+  #     is retried with backoff and, past MAX_ATTEMPTS, parked as `dead` for an
+  #     operator (Admin::EventDeliveriesController).
+  #
+  # GUARANTEE: at-least-once, UNORDERED. Handlers MUST be idempotent — a retry or
+  # the sweep may deliver the same event twice. Durability is of DELIVERY, not
+  # CAPTURE: an event whose process dies between the after_commit and the publish
+  # leaves no row and is lost, exactly as today. This feature makes what WAS
+  # published arrive; it does not resurrect what was never published.
+  #
+  # SECURITY: a handler is resolved from THIS in-memory registry by key, populated
+  # at boot from trusted code — never constantized from the stored row. If the key
+  # is unknown at delivery time (handler removed since enqueue) the row is parked
+  # `dead`; an arbitrary class is never executed off a DB value. (Same posture as
+  # the scheduler's job_class allowlist.)
+  module DurableEvents
+    MAX_ATTEMPTS = 5
+    # Backoff (seconds) indexed by attempt number; the last value is the cap.
+    BACKOFF = [ 0, 60, 300, 1800, 7200 ].freeze
+    SWEEP_KEY = "loam_event_redelivery_sweep".freeze
+
+    class << self
+      # --- declarative registry (mirrors Loam::Scheduler.register) ---
+
+      # key:  a stable identifier stored on every delivery row it produces.
+      # to:   an event name ("billing.invoice.paid") or a domain prefix
+      #       ("billing.") — same matching rule as Events/webhooks.
+      # call: a class (or anything) responding to .call(event_name, payload),
+      #       or its name as a String. Resolved from this registry, never the row.
+      def register(key:, to:, call:)
+        registry[key.to_s] = { key: key.to_s, pattern: to.to_s, handler: call }
+        key.to_s
+      end
+
+      def registered = registry.values
+
+      def reset_registry!
+        @registry = {}
+      end
+
+      def subscribers_for(event_name)
+        registered.select { |entry| Loam::Events.pattern_matches?(entry[:pattern], event_name) }
+      end
+
+      def handler_for(key)
+        entry = registry[key.to_s]
+        entry && resolve(entry[:handler])
+      end
+
+      # --- wiring (mirrors Loam::Webhooks.subscribe!) ---
+
+      # Wired once from Loam::Engine. Idempotent: subscribing twice would persist
+      # every event twice.
+      def subscribe!
+        @subscription ||= Loam::Events.subscribe_all { |event_name, payload| capture(event_name, payload) }
+      end
+
+      # Persist a delivery row per matching durable subscriber, in the event's
+      # tenant, then nudge a job per row. The ROW is the durable record; the job
+      # is only the accelerator (the sweep redelivers rows whose job was lost).
+      def capture(event_name, payload)
+        tenant = Loam::Tenant.find_by(id: payload[:tenant_id])
+        return if tenant.nil? # nil-tenant events are not durably delivered (as Webhooks.dispatch)
+
+        matches = subscribers_for(event_name)
+        return if matches.empty?
+
+        # Only JSON-safe primitives cross into the row/job — payloads are ids and
+        # scalars by convention, never records (same rule as the webhook path).
+        deliverable = payload.transform_keys(&:to_s)
+
+        Loam.as_tenant(tenant) do
+          matches.each do |sub|
+            delivery = Loam::EventDelivery.create!(
+              subscriber_key: sub[:key], event_name: event_name.to_s,
+              payload: deliverable, status: "pending", attempts: 0
+            )
+            Loam::EventDeliveryJob.perform_later(tenant.id, delivery.id)
+          end
+        end
+      end
+
+      # --- delivery (called by Loam::EventDeliveryJob) ---
+
+      # Run one delivery and advance the row's state. Manual, ROW-STATE retries —
+      # deliberately NOT ActiveJob retry_on, which keeps retry state in the queue
+      # (the very thing this feature stops trusting). Safe to call twice on one
+      # row (at-least-once): a delivered/dead/not-yet-due row is a no-op.
+      def deliver(delivery, now: Time.current)
+        return unless delivery.status == "pending"
+        return if delivery.next_attempt_at && delivery.next_attempt_at > now # duplicate nudge, backoff not elapsed
+
+        Loam::Telemetry.span("durable_event_delivery",
+                             subscriber_key: delivery.subscriber_key, event_name: delivery.event_name) do
+          run_delivery(delivery, now)
+        end
+      end
+
+      def run_delivery(delivery, now)
+        handler = handler_for(delivery.subscriber_key)
+        if handler.nil?
+          delivery.update!(status: "dead",
+                           last_error: "no registered subscriber #{delivery.subscriber_key.inspect}")
+          return
+        end
+
+        begin
+          handler.call(delivery.event_name, delivery.payload_hash)
+          delivery.update!(status: "delivered", delivered_at: now, last_error: nil)
+        rescue StandardError => error
+          attempts = delivery.attempts + 1
+          if attempts >= MAX_ATTEMPTS
+            delivery.update!(status: "dead", attempts: attempts, last_error: format_error(error))
+          else
+            delivery.update!(attempts: attempts, next_attempt_at: now + backoff_for(attempts),
+                             last_error: format_error(error))
+          end
+        end
+      end
+
+      # THE durability guarantee: re-enqueue due-but-undelivered rows whose job
+      # was lost (worker crash, dropped message, async adapter racing the txn).
+      # Tenant-scoped — called from the per-tenant sweep the engine registers, so
+      # no cross-tenant scan is needed.
+      def redeliver_stuck(now: Time.current, limit: 500)
+        count = 0
+        Loam::EventDelivery.due(now).limit(limit).find_each do |delivery|
+          Loam::EventDeliveryJob.perform_later(delivery.tenant_id, delivery.id)
+          count += 1
+        end
+        count
+      end
+
+      private
+
+      def registry
+        @registry ||= {}
+      end
+
+      # A callable passed directly (class with .call, Proc) is used as-is; a
+      # String/Symbol is constantized HERE, from the trusted registry value.
+      def resolve(handler)
+        if handler.is_a?(String) || handler.is_a?(Symbol)
+          klass = handler.to_s.safe_constantize
+          return klass if klass.respond_to?(:call)
+
+          nil
+        elsif handler.respond_to?(:call)
+          handler
+        end
+      end
+
+      def backoff_for(attempts)
+        BACKOFF[attempts] || BACKOFF.last
+      end
+
+      def format_error(error)
+        "#{error.class}: #{error.message}"
+      end
+    end
+  end
+end